Gateway Module — `tools/`

1. Purpose

The tools module exposes the source-of-truth advertisement of the live gateway-side write-path Zod schemas (Dispatch 42). It exists to close the residual gap left by the Raw Twin pattern: the Claude Code MCP client caches every tool's inputSchema at session startup, so any post-startup server-side schema evolution is invisible to a running session. GET /api/tools/list returns a hand-curated SCHEMA_VERSION string plus every mutation tool's per-branch required/optional field contract, so the konnichiwagwan Phase F freshness probe can diff a session's cached view against live server state and warn the operator to restart before silent-strip bugs bite. The advertisement is deliberately hand-curated, not reflected from Zod internals — it IS a contract, and the manual duplication is the governance surface.

2. File Inventory

No index.ts/types.ts — router wired directly (createToolsRouter(), mount index.ts:744); types are inline exports in schema-introspection.ts.

3. Public API Surface

REST Endpoints (mount: index.ts:744 → /api/tools)

MCP Tools

None registered here. This module describes the MCP mutation tools (defined in mcp/index.ts); it does not register any.

4. Internal API

• SCHEMA_VERSION (const, current value '2026-06-13a') — ISO-dated; MUST bump on any field/context_type add-remove (freshness probe diffs on this string).
• buildToolsList(): ToolsListResponse — assembles 11 tool specs: write_psychic_cache (9-branch discriminated union), 6 flat mutation tools (report_dispatch, report_progress, report_complete, commit_agent_memory, commit_memory, context_feedback), 4 KG tools (kg_add_triple, kg_query_entity, kg_timeline, kg_invalidate). Each carries raw_tool sibling name + base_required/base_optional + per-branch required/optional.
• Exported interfaces: ToolFieldSpec, WriteCacheTypeBranch, ToolSpec, ToolsListResponse.

5. Background Services

None.

6. Data Contracts

The advertised write-cache branches (mirror of psychic-cache/types.ts WriteCacheInputSchema):

• Base required: mission_id, content, context_type. Base optional: agent_name, ttl_hours, tags, source_turn, dispatch_id.
• Branches: decision→decision_rationale; directive→directive_target; intel→intel_source; state_change→state_from+state_to; output→agent_name+output_url+dispatch_id (D1929/AK-439 added dispatch_id required on the output branch ONLY — closes the D52 probe asymmetry); report→report_dispatch_id+report_outcome; escalation→escalation_target+escalation_reason; shadow_clone→subtasks; thread_checkpoint→7 required fields.
• Flat tools emit a single synthetic context_type='_flat' branch. KG branches carry D4 admission fields.

This introspection surface is the observable half of the Raw Twin Discipline: mcp/index.ts holds the client-facing tools (no schemas), psychic-cache/dispatch/etc. hold the Zod source of truth, and tools/ publishes the diffable contract between them.

7. Dependencies

• Gateway modules: none imported at runtime — the branch specs are hand-transcribed from the sibling modules' Zod schemas (governance-enforced parity, no code import).
• External: express.
• Environment variables: none.

8. Test Coverage

9. Known Limitations

• The advertisement is manually curated. A new field added to a Zod branch but not to schema-introspection.ts (or vice versa) drifts silently until SCHEMA_VERSION is bumped — there is no mechanical Zod↔advertisement parity test, only the "every tool has a raw twin" invariant and the CLAUDE.md Dependency Propagation Protocol. This is deliberate (the duplication IS the governance surface) but is a live drift risk (see the AK-439 comment: "no automated parity test enforces this pair").
• SCHEMA_VERSION must be bumped by hand on every schema edit; a forgotten bump means stale sessions never receive a drift warning.
• Read-only tools (assemble_context) are excluded from the advertisement by design — drift impact there is graceful degradation, not data loss.

10. Change History