@adhd/agent-mcp 2.0.1 → 2.1.0

package/docs/marketing/.catalog/required-tooling.md

@@ -0,0 +1,224 @@
+# @adhd/agent-mcp — Required Tooling & Unverified Capabilities
+
+**Catalog date:** 2026-07-12  
+**Total shipped capabilities:** 33  
+**Capabilities marked 🔴 UNVERIFIED:** 7  
+
+---
+
+## Summary
+
+Seven shipped capabilities cannot be proven with the current tooling setup. Each is marked as shipped in code but lacks a default-running test (either because the test is gated behind an env flag, or the test infrastructure doesn't exist).
+
+---
+
+## Unverified Capabilities & Root Causes
+
+### 1. HTTP OpenAI-Compatible Chat Gateway (`/v1/chat/completions`)
+
+**Status:** ✅ Shipped (implemented in src/streaming/chat-gateway.ts + src/streaming/sse-server.ts)  
+**Tested:** ❌ No test  
+**Reason:** No HTTP client smoke test exists; SSE server is started but never exercised in CI
+
+**Needed to verify:**
+- **Tool:** HTTP client (curl, node-fetch, or similar) to POST to /v1/chat/completions
+- **Setup:** Start agent-mcp server with running SQLite DB, create agent, POST request
+- **Assertion:** Parse JSON response, verify status + content + streaming format
+
+**Effort:** ~2 hours (write integration test using vitest + node http or got library)
+
+**File locations:**
+- Capability: `src/streaming/chat-gateway.ts:handleChatCompletions` (comprehensive implementation)
+- Server wiring: `src/streaming/sse-server.ts:45-50` (route registration)
+- Entry point: `src/index.ts:188` (SSE server startup)
+
+---
+
+### 2. HTTP Models Endpoint (`GET /v1/models`)
+
+**Status:** ✅ Shipped (implemented in src/streaming/chat-gateway.ts)  
+**Tested:** ❌ No test  
+**Reason:** Part of SSE server, not exercised in tests
+
+**Needed to verify:**
+- **Tool:** HTTP GET client (curl -s localhost:ADHD_AGENT_SSE_PORT/v1/models | jq)
+- **Setup:** Start agent-mcp, create agent
+- **Assertion:** Parse JSON response, verify models array
+
+**Effort:** ~1 hour (trivial HTTP GET test)
+
+**File locations:**
+- Capability: `src/streaming/chat-gateway.ts:handleGetModels`
+- Server wiring: `src/streaming/sse-server.ts:44-45`
+
+---
+
+### 3. Claude CLI Provider (`claudecli` type)
+
+**Status:** ✅ Shipped (configured in src/config.ts, documented in USAGE_GUIDE)  
+**Tested:** ❌ No test  
+**Reason:** Requires `claude` binary on PATH; not available in CI environment
+
+**Needed to verify:**
+- **Tool:** Claude CLI binary (`claude --version` must succeed)
+- **Setup:** Install Claude CLI locally, create agent with type:'claudecli', run task
+- **Assertion:** Task completes, output matches claudecli format
+
+**Effort:** ~3 hours (integration test + conditional skip if claude unavailable)
+
+**File locations:**
+- Config: `src/config.ts` (no explicit claudecli block; handled separately)
+- Documentation: `src/server.ts:259` (USAGE_GUIDE provider table)
+
+---
+
+### 4. MCP Server Bindings & Tool Registration
+
+**Status:** ✅ Shipped (core feature, wired in orchestrator)  
+**Tested:** ❌ Live e2e test exists but skipped (AGENT_MCP_LIVE=1 only)  
+**Reason:** Requires real model (LM Studio or Anthropic) to exercise multi-agent recursion
+
+**Needed to verify:**
+- **Tool:** LM Studio (`http://localhost:1234/v1`) OR Anthropic API key
+- **Setup:** Start calc-server.mjs (stdio MCP), create agent with mcpServers binding, run task using calc tool
+- **Assertion:** Tool call reaches MCP server, result comes back, persisted in DB
+
+**Effort:** ~2 hours (make live-dag.e2e.test.ts run by default with fallback provider detection)
+
+**File locations:**
+- Live test: `src/__tests__/integration/live-dag.e2e.test.ts:75-76` (skipIf(!isLive) guard)
+- Calc server fixture: `src/__tests__/integration/fixtures/calc-server.mjs`
+
+---
+
+### 5. Agent Delegation (Recursive Multi-Agent DAG)
+
+**Status:** ✅ Shipped (core feature, tested live)  
+**Tested:** ❌ Live e2e test exists but skipped (AGENT_MCP_LIVE=1 only)  
+**Reason:** Same as #4 — requires real model to exercise delegation logic
+
+**Needed to verify:**
+- **Tool:** Real LLM (LM Studio or Anthropic)
+- **Setup:** Same as #4; test wiring in src/__tests__/integration/live-dag.e2e.test.ts already exists
+- **Assertion:** 3-level recursion happens (coordinator→fanout→workers); every worker invokes calc tool; all tasks persisted
+
+**Effort:** ~1 hour (remove skipIf guard + add provider auto-detection fallback)
+
+**File locations:**
+- Test: `src/__tests__/integration/live-dag.e2e.test.ts` (complete test, just gated)
+
+---
+
+### 6. Human-in-the-Loop (HITL) Task Suspension
+
+**Status:** ✅ Shipped (awaiting_input status, task_resume tool, documented in USAGE_GUIDE)  
+**Tested:** ❌ No test  
+**Reason:** No integration test exercises the HITL flow (create task, wait for suspension, resume with input)
+
+**Needed to verify:**
+- **Tool:** Real model that calls `request_human_input` tool; test harness to simulate human response
+- **Setup:** Create agent with allowHumanInput:true, run task with model that triggers HITL
+- **Assertion:** Task suspends with awaiting_input status, resumeToken issued, task_resume moves task to running, final result produced
+
+**Effort:** ~4 hours (write integration test with mock model or real LM Studio)
+
+**File locations:**
+- Tool: `src/server.ts:513-517` (task_resume definition)
+- USAGE_GUIDE: `src/server.ts:269-276` (error codes reference)
+- Config: allowHumanInput field in agent definition
+
+---
+
+### 7. Server-Sent Events (SSE) Task Streaming
+
+**Status:** ✅ Shipped (SSE server on separate port, task/completed notifications)  
+**Tested:** ❌ No test  
+**Reason:** No SSE client test; SSE server starts but is never polled in CI
+
+**Needed to verify:**
+- **Tool:** SSE client (node EventSource or similar) to subscribe to task stream
+- **Setup:** Start agent-mcp, create agent, run background task, subscribe to SSE /tasks endpoint
+- **Assertion:** Receive task/completed event with correct task_id + status
+
+**Effort:** ~2 hours (write integration test using EventSource or fetch EventStream)
+
+**File locations:**
+- SSE server: `src/streaming/sse-server.ts`
+- Event bus: `src/streaming/event-bus.ts:subscribeToTaskDone`
+- Wiring: `src/index.ts:188` (SSE server startup)
+
+---
+
+## Tooling Gap Summary
+
+| Need | Tool | Status | Impact | Priority |
+|------|------|--------|--------|----------|
+| HTTP client | curl, node-fetch, got | ✅ available | 2 HTTP endpoints unproven | HIGH |
+| Real LLM | LM Studio (localhost) or Anthropic API | ⚠ optional | 2 features unproven (delegation, DAG) | HIGH |
+| Claude CLI binary | claude (system PATH) | ❌ not in CI | 1 provider unproven | MEDIUM |
+| EventSource client | node EventSource | ✅ available | SSE streaming unproven | MEDIUM |
+
+---
+
+## Capability Impact
+
+**If these 7 capabilities are not proven by catalog v2.0.2:**
+
+- 🟢 Agent/session/task management: ✅ Proven (19 unit tests pass)
+- 🟢 Provider (OpenAI, Anthropic, DeepSeek): ✅ Proven (config tests pass)
+- 🟢 Tool advertisement (names-only vs full): ✅ Proven (14 tool-advertisement tests pass)
+- 🔴 HTTP API (OpenAI compat): ❌ Unproven — consumers cannot verify it works before deploying
+- 🔴 Agent delegation: ❌ Unproven in CI — works live but no regression guard
+- 🔴 HITL suspension: ❌ Unproven — no evidence it works beyond code review
+- 🔴 SSE streaming: ❌ Unproven — no evidence real-time events flow
+
+**Risk:** Publishing 2.0.2 with these 7 gaps means consumers reporting "chat gateway doesn't work" or "delegation failed" after install, with no CI gates to catch regression.
+
+---
+
+## Action Items for Next Catalog Run
+
+### Must-Have (blocker for 2.0.2 publish):
+
+1. **Add HTTP smoke test** (curl or node-fetch client) for /v1/chat/completions and /v1/models
+   - File: src/__tests__/integration/http-gateway.test.ts (new)
+   - Time: ~2 hours
+   - Dependency: HTTP client library (already in Nx workspace)
+
+2. **Add HITL integration test** (with mock model or real LM Studio)
+   - File: src/__tests__/integration/hitl.test.ts (new)
+   - Time: ~4 hours
+   - Dependency: LM Studio running on localhost:1234
+
+### Nice-to-Have (gated by env, runs in CI with fallback):
+
+3. **Ungat live-dag.e2e.test.ts** — remove AGENT_MCP_LIVE=1 guard, add provider auto-detection
+   - File: src/__tests__/integration/live-dag.e2e.test.ts (modify)
+   - Time: ~1 hour
+   - Dependency: LM Studio OR Anthropic API key (env var)
+   - Fallback: Skip if neither available, warn in logs
+
+4. **Add SSE integration test**
+   - File: src/__tests__/integration/sse-stream.test.ts (new)
+   - Time: ~2 hours
+   - Dependency: EventSource client (available)
+
+5. **Add Claude CLI test**
+   - File: src/__tests__/integration/claudecli.test.ts (new)
+   - Time: ~3 hours
+   - Dependency: claude CLI binary on PATH
+   - Fallback: Skip if not available
+
+---
+
+## Recommendation
+
+**For 2.0.2:**
+- ✅ **Mandatory:** HTTP smoke test (2 hrs) — blocks OpenAI compat consumer trust
+- ✅ **Strongly recommended:** HITL test (4 hrs) — blocks HITL feature launch
+- ⚠ **Nice-to-have:** Ungat live-dag.e2e, add SSE test (3 hrs total) — regression guards
+- ⚠ **Optional:** Claude CLI test (3 hrs) — lower priority (fewer users)
+
+**Total effort to verify all 7 capabilities:** ~12 hours across 5 new test files.
+
+→ Cartographer recommends 2.0.2 proceed without all 7 verified, but with HTTP + HITL tests added. Delegation + SSE + Claude CLI can be deferred to 2.0.3 with async CI integration.

package/docs/marketing/.catalog/review.md

@@ -0,0 +1,164 @@
+# Doc Review — @adhd/agent-mcp 2.0.2 — 7c400a7
+
+**Final Review Gate Run**  
+**Timestamp:** 2026-07-12T02:50:00Z  
+**Reviewer:** Documentation Assessment Gate (Final)
+
+---
+
+## VERDICT: FAIL
+
+**Reason:** Lens 2 failure — AGENTS.md contains 2 critical inaccuracies referencing removed/renamed tools incompatible with current capabilities.json.
+
+---
+
+## Lens 1 — Closed-Loop Metrics
+
+**STATUS: PASS**
+
+### Evidence
+
+The steward re-ran the cartographer after fixes; metrics.md now contains a post-fix block (lines 74-119).
+
+**Post-fix results (lines 75-89):**
+- **metric_1_eliminated_reader_searches:** 23 → 5 (78% improvement; goal was < 10) ✓ PASS
+- **metric_3_undocumented%:** 76% → 3% (97% improvement; goal was < 50%) ✓ PASS
+- **junk%:** 0% → 0% ✓ PASS
+
+**Contradictions with capabilities.json:**
+- All 33 shipped capabilities (per capabilities.json) are status:shipped
+- No deprecated items claimed as current
+- Roadmap items (AGENTS.md lines 134-145) explicitly marked "Do not document these as shipped features"
+- Architecture schema field names verified: snake_case correct (`cache_read_input_tokens`, `cache_creation_input_tokens`, `uncached_input_tokens`, `peak_context_tokens`)
+- `peak_context_at` correctly defined as INTEGER (line 157), not TIMESTAMP
+
+✓ **Lens 1 Result: PASS**
+
+---
+
+## Lens 2 — Template Conformance & Accuracy
+
+**STATUS: FAIL**
+
+### Per-Document Scores
+
+| Doc | Score | Status | Finding |
+|---|---|---|---|
+| README.md | 98/100 | PASS | Quickstart, release notes, env vars all correct; LICENSE file exists |
+| CHANGELOG.md | 100/100 | PASS | Keep-a-Changelog compliant; 6 regression fixes documented |
+| AGENTS.md | 92/100 | **FAIL** | 16 tools in table correct; but example section uses removed tools |
+| llms.txt | 98/100 | PASS | Quick reference accurate; correct 2.0.2 highlights |
+| architecture-and-security.md | 98/100 | PASS | Token field names correct (post-fix); schema accurate |
+
+### Critical Failures
+
+**FAIL #1: AGENTS.md Example Uses Removed Tool "agent_message"**
+
+- **Location:** AGENTS.md, lines 208-213
+- **Issue:** JSON-RPC example calls `"method": "agent_message"` which does NOT exist in capabilities.json or shipped 2.0.2
+- **Evidence:**
+  - capabilities.json lists 16 MCP tools; `agent_message` is absent
+  - README.md quickstart (lines 82-89) correctly uses `"method": "task"`
+  - Consumer test confirms `task` is the correct tool
+- **Impact:** LLM reading AGENTS.md will attempt to use a non-existent tool, breaking playbook integration
+- **Fix:** Replace lines 208-213 example with correct `task` method call (template: README.md lines 82-89)
+
+**FAIL #2: AGENTS.md References Renamed Tools in Explanation**
+
+- **Location:** AGENTS.md, line 225
+- **Issue:** States "client can later call `task_status(taskId)` or `task_usage(taskId)`" but these tools don't exist; correct names are `result` and `usage_query`
+- **Evidence:**
+  - AGENTS.md's own tool table (lines 24-41) correctly lists `result` (line 33) and `usage_query` (line 40)
+  - Line 225 contradicts the same document's tool inventory
+- **Impact:** LLM reading explanation section will use wrong tool names, causing failures
+- **Fix:** Replace `task_status(taskId)` → `result(taskId)` and `task_usage(taskId)` → `usage_query({task_id: taskId})`
+
+### Conformance Summary
+
+✓ **Token field naming:** Correct and consistent across README, AGENTS, CHANGELOG, llms.txt, architecture-and-security.md (cacheReadTokens, uncachedInputTokens, cacheCreationTokens, peakContextTokens)  
+✓ **Plugin config chain:** Documented correctly (3 paths in order)  
+✓ **All 16 tools:** Listed in AGENTS.md table with correct signatures  
+✓ **Link integrity:** All links resolve (LICENSE file verified to exist)  
+✓ **Architecture schema:** Snake_case DB names correct; peakContextAt is INTEGER  
+✗ **Example consistency:** 2 instances of removed/renamed tools in narrative sections
+
+✗ **Lens 2 Result: FAIL** (2 critical inaccuracies prevent PASS)
+
+---
+
+## Lens 3 — Consumer Usability Test
+
+**STATUS: PASS**
+
+### Evidence
+
+File `/docs/marketing/.catalog/consumer.md` exists and shows completion of all canonical tasks.
+
+**Task Results:**
+1. **Quick-Start Installation & First Agent:** ✓ PASS
+   - Docs sufficient for install, config, agent creation, task execution, result retrieval
+   - No source code required; correct tool names and JSON-RPC format documented
+
+2. **Provider Migration (Anthropic → DeepSeek):** ✓ PASS
+   - Env vars and token accounting differences clearly explained
+   - README, AGENTS.md, CHANGELOG all provide needed information
+
+3. **Debugging Token Usage:** ✓ PASS
+   - Token field meanings documented; cumulative vs. peak distinction clear
+   - AGENTS.md token accounting section and CHANGELOG break down each field
+
+**Consumer Verdict:** Documentation is sufficient for independent use; no source-code reading required.
+
+✓ **Lens 3 Result: PASS**
+
+---
+
+## Summary by Lens
+
+| Lens | Status | Gate Impact |
+|------|--------|-------------|
+| **Lens 1: Metrics** | PASS | Improvement verified (23→5 searches, 76→3% undoc) |
+| **Lens 2: Conformance** | FAIL | 2 critical tool-name inaccuracies in AGENTS.md |
+| **Lens 3: Consumer** | PASS | All 3 canonical tasks pass; docs are self-sufficient |
+
+**Gate Rule:** ALL THREE LENSES must PASS for overall PASS.  
+**Result:** 2/3 PASS → **OVERALL FAIL**
+
+---
+
+## Required Fixes (Before Resubmission)
+
+**Fix #1 (CRITICAL):** AGENTS.md lines 208-213 — Remove incorrect tool reference
+- Delete the `agent_message` example block (lines 208-213)
+- Replace with correct `task` method call using README.md lines 82-89 as template:
+  ```json
+  {
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "task",
+    "params": {
+      "agentName": "research-agent",
+      "prompt": "Find all TypeScript files in /Users/me/code"
+    }
+  }
+  ```
+
+**Fix #2 (CRITICAL):** AGENTS.md line 225 — Fix tool name references
+- Current: `"client can later call task_status(taskId) or task_usage(taskId)"`
+- Corrected: `"client can later call result(taskId) to retrieve results, or usage_query(filter, groupBy) to query usage across tasks"`
+- Reason: Aligns with correct tool names from the MCP tool table (lines 33, 40)
+
+---
+
+## Resubmission Process
+
+1. **Apply both fixes to AGENTS.md** (2 surgical edits, ~3 minutes)
+2. **Re-run cartographer** to verify no new broken links: `npx nx run agent-mcp:cartographer`
+3. **Verify consumer test still passes** (it will; consumer uses README examples, not AGENTS.md)
+4. **Re-submit for final gate review**
+
+---
+
+**Gate Decision:** FAIL — 2 critical inaccuracies in tool naming blocks publication.  
+**Resubmit After:** Fixes applied and cartographer re-run (est. 10 minutes).  
+**This is the final gate run.** No further iterations after this.

package/docs/provider-call-audit.md

@@ -0,0 +1,254 @@
+# agent-mcp: Provider Call & Event Storage Audit
+
+Audit of what agent-mcp sends to the provider API each turn and what it stores in
+the DB. Compared against the standard ReAct loop pattern used by OpenCode and Claude
+Code.
+
+**Date:** 2026-07-02
+**Trigger:** investigating 262k input tokens for a 15-turn, 775-line implementation task.
+
+---
+
+## 1. What Goes to the Provider Every Turn
+
+### Orchestrator Loop (`packages/ai/agent-mcp/src/engine/orchestrator.ts`)
+
+Every iteration of the while-loop (lines ~130–850):
+
+1. **`registry.listAllTools()` (line 176)** — fetches the full tool list from every
+   connected MCP server. For each server, this:
+   - Calls `getOrCreateClient(serverName)` (stdio clients are cached; the stdio
+     subprocess persists across calls)
+   - Calls `client.listTools()` which sends an MCP `tools/list` JSON-RPC request
+     over stdio and waits for the response
+   - Prefixes each tool name as `<server>__<tool>`
+   - Returns the complete array of `ToolDefinition[]`
+
+2. **HITL append (lines 180-185)** — if the agent has `allowHumanInput: true` and
+   the task is durable, appends the built-in `request_human_input` tool.
+
+3. **Hook emission (lines 208-226)** — fires `pre:model_request` for observation
+   and enforcement, with the full `{messages, tools}` payload.
+
+4. **Provider call (lines 235-237)** — passes `tools: tools.length > 0 ? tools : undefined`
+   to `provider.chat()`.
+
+### OpenAI Provider (`packages/ai/agent-mcp/src/providers/openai.ts`)
+
+`toOpenAITools()` (lines 62-76) serializes every `ToolDefinition` as:
+
+```typescript
+{
+  type: "function",
+  function: {
+    name: "filesystem__read_text_file",
+    description: "Read the complete contents of a file...",
+    parameters: {           // full JSON Schema — type, properties, required, descriptions
+      type: "object",
+      properties: {
+        path: { type: "string", description: "..." },
+        head: { type: "number", description: "..." },
+        tail: { type: "number", description: "..." },
+        ...
+      },
+      required: ["path"],
+      additionalProperties: false
+    }
+  }
+}
+```
+
+The OpenAI client then sends this `tools` array in EVERY `chat.completions.create()`
+call (line 121). The API is stateless — tool definitions must be present in every
+request for the model to emit tool calls.
+
+### Measured Overhead (from the 2-tool-call experiment)
+
+| Agent | Tools sent per turn | Input tokens (2 turns) | Cache hit | Net paid | Overhead vs shell |
+|---|---|---|---|---|---|
+| Both (fs + shell) | ~10 tools | 5,645 | — | — | 3.0× |
+| Filesystem-only | ~8 tools | 5,126 | 2,560 (50%) | 2,566 | 2.7× |
+| Shell-only | ~1 tool | 1,877 | 768 (41%) | 1,109 | 1.0× baseline |
+
+Tool schemas are the dominant per-turn cost. On a 15-turn task:
+- Filesystem-only: ~48k tokens (tool schemas re-sent 15×)
+- Shell-only: ~10k tokens
+- Delta: ~38k tokens (17% of the 262k total on the spec-types task)
+
+### Cache Behavior
+
+DeepSeek caches repeated prefixes automatically. The 50% cache-hit rate on the
+filesystem agent means:
+- Turn 1: 2,560 tokens paid at full price (system prompt + tool schemas + work order)
+- Turn 2: 2,560 tokens read from cache at ~10% cost (256 billed), 2,566 new tokens
+  (tool results from turn 1 + assistant response + next turn's request)
+- The 50% that changes is the growing conversation history — this is inherent and
+  cannot be eliminated by any agent-mcp change.
+
+---
+
+## 2. What Gets Stored in the DB
+
+### `task_events` Table
+
+Schema: `(id TEXT PK, task_id TEXT, type TEXT, payload TEXT, created_at TEXT)`
+
+Event types written per turn:
+- `MODEL_REQUEST` — `{messageCount, toolCount}` (thin summary, no token data)
+- `MODEL_RESPONSE` — `{stopReason, hasContent, toolCallCount}` (thin summary, no token data)
+- `TOOL_CALL` — empty payload
+- `TOOL_RESULT` — empty payload
+
+**The payload column is arbitrary JSON but carries no usage data.** Per-turn token
+counts from `providerResponse.usage` are available at the event emission site
+(`orchestrator.ts:303`) but were never written to the payload.
+
+### `task_usage` Table
+
+Schema includes: `task_id PK, input_tokens, output_tokens, tool_call_count,
+model_calls, cache_read_input_tokens, cache_creation_input_tokens, ...`
+
+Updated per turn via UPSERT (accumulate in-place):
+```sql
+INSERT ... ON CONFLICT(task_id) DO UPDATE SET
+  input_tokens = input_tokens + <new>,
+  output_tokens = output_tokens + <new>,
+  model_calls = model_calls + 1,
+  cache_read_input_tokens = COALESCE(cache_read_input_tokens, 0) + <new>
+```
+
+Single row per task. Per-turn deltas are lost — only the aggregate survives.
+
+### `cache_read_input_tokens` Gap (FIXED 2026-07-02)
+
+Prior to the fix in `openai.ts:169-170`, `cacheReadTokens` was never extracted from
+the OpenAI SDK response (`sdkUsage.prompt_tokens_details.cached_tokens` existed but
+was ignored). The Anthropic provider had equivalent extraction since inception.
+The fix (3 lines) now captures cache reads for all OpenAI-compatible providers
+(OpenAI, DeepSeek, LM Studio, Ollama).
+
+### Per-turn token tracking (PENDING)
+
+The MODEL_RESPONSE event payload at `orchestrator.ts:311-315` still writes only
+`{stopReason, hasContent, toolCallCount}`. The fix to add `{inputTokens,
+outputTokens, cacheReadTokens, cacheCreationTokens}` from `providerResponse.usage`
+was applied to source but not yet built/reloaded. Once live, every MODEL_RESPONSE
+row will carry per-turn token counts, enabling reconstruction of exactly where
+tokens went in a multi-turn task.
+
+---
+
+## 3. Comparison: OpenCode / Claude Code Standard Pattern
+
+The standard ReAct (Reasoning + Acting) agent loop sends tools on every request.
+This is not an agent-mcp design flaw — it's how the OpenAI/Anthropic APIs work
+(stateless chat completions).
+
+| Aspect | agent-mcp | OpenCode (anomalyco) | Claude Code (Anthropic) |
+|---|---|---|---|
+| Tools fetched per turn | Yes — `listAllTools()` calls MCP `tools/list` every loop iteration | Yes — tool registry queried per turn | Yes — tool schemas sent every request |
+| Full tools sent every turn | Yes — all servers, all tools | Yes — all registered tools | Yes — all tools the model can call |
+| Tool pruning | No — all tools always sent | Partial — tools gated by permission mode | Yes — per-task tool filtering |
+| Tool schema size | Filesystem: ~8 tools, ~3,200 tokens of JSON Schema | ~45 tools, variable | Model-dependent; auto-compacted |
+| Caching behavior | Provider-dependent (DeepSeek: auto-prefix, ~50% hit) | Provider-dependent | Anthropic: explicit breakpoints, 90%+ hit with Sentinel-Fanout |
+
+The critical difference: **agent-mcp has no tool pruning.** Claude Code sends only
+the tools relevant to the current task. OpenCode gates tools by permission mode.
+agent-mcp sends every tool from every connected MCP server on every turn.
+
+---
+
+## 4. Opportunities
+
+> **Status update (2026-07-02):** #1, #2, and #3 are SHIPPED. `listAllTools()` is
+> hoisted out of the loop; MODEL_RESPONSE events carry the normalized per-turn
+> token fields plus `rawUsage` (the provider usage object verbatim); and tool
+> advertisement defaults to `"names"` — slim name-only definitions on the wire
+> with full documentation prepended to the system message as a cacheable prefix
+> (per-agent override: `toolAdvertisement: "full"`; claudecli always full). See
+> `engine/tool-advertisement.ts` and `__tests__/tool-advertisement.test.ts`
+> (includes negative control). Remaining: registry-backed tool docs (Plan 8).
+
+### Immediate (low effort, high impact)
+
+1. **Pull `listAllTools()` out of the loop** — tools don't change mid-task. Call it
+   once before the while-loop and reuse the array. Eliminates MCP `tools/list`
+   round-trips on every turn. **DONE.**
+
+2. **Add `inputTokens/outputTokens/cacheReadTokens/cacheCreationTokens` to
+   MODEL_RESPONSE payloads** — fix applied to source, pending build. **DONE, plus
+   `rawUsage` verbatim.**
+
+### Medium (requires design)
+
+3. **Tool pruning** — the agent definition or system prompt should declare which
+   tools the work order needs. The `DispatchUnit` from the dispatch-optimizer
+   already carries `context_files` and operation shapes — the orchestrator could
+   pass a `tools` allowlist. GitHub Engineering cut costs 62% with this approach.
+   Per-turn savings for filesystem-only: ~1,600 tokens/turn after caching.
+
+4. **Cache-optimized system prompt** — place the largest stable prefix (system
+   prompt + tool schemas) first in the messages array to maximize cache-hit
+   surface area.
+
+### Speculative (would require provider API changes)
+
+5. **Omit `tools` on follow-up turns** — some providers tolerate this (model
+   already emitted valid tool calls, doesn't need schemas re-validated). Would
+   save ~1,600-3,200 tokens/turn. Not standard OpenAI behavior; needs testing
+   per provider.
+
+---
+
+## 5. Verbatim: What the Provider Sees Each Turn
+
+A synthesized, token-annotated view of a single turn in the spec-types task:
+
+```
+SYSTEM (3,500 tokens — CACHED after turn 1)
+  "You are an implementation agent for the ADHD Nx monorepo..."
+  + repo conventions, tool discipline, fail-fast rules
+
+TOOLS (3,200 tokens — CACHED after turn 1)
+  filesystem__read_text_file  { path: string, head?: number, tail?: number }
+  filesystem__write_file      { path: string, content: string }
+  filesystem__edit_file       { path: string, old_string: string, new_string: string }
+  filesystem__search_files    { path: string, pattern: string }
+  filesystem__list_directory  { path: string }
+  shell__shell_exec           { command: string }
+  ... (8 tools * ~400 tokens avg JSON Schema each)
+
+USER MESSAGE (1,500 tokens — CACHED after turn 1)
+  "SANDBOX MODE — compiler smoke test. Work order compiled from..."
+  + spec-types operations list
+
+ASSISTANT (turn 1 — 120 tokens — NOT CACHED)
+  Tool call: filesystem__read_text_file(path="packages/dispatch/...")
+
+TOOL RESULT (turn 1 — 22,000 tokens — NOT CACHED)
+  Full content of types.ts (660 lines)
+
+ASSISTANT (turn 2 — 80 tokens — NOT CACHED)
+  Tool call: filesystem__create_directory(path="...")
+
+TOOL RESULT (turn 2 — 15 tokens — NOT CACHED)
+  "Directory created"
+
+... (grows each turn — everything below the USER MESSAGE changes)
+
+ASSISTANT (turn N — this request)
+  "I will now write types.ts..."
+```
+
+Every turn after turn 1: ~3,500 system + 3,200 tools + 1,500 work order =
+~8,200 tokens READ FROM CACHE (820 billed), plus the entire growing conversation
+history PAID AT FULL PRICE.
+
+For turn 15 with ~30 messages in history (~180k tokens of conversation +
+tool results): 820 (cached) + 180,000 (uncached) = ~180,820 input tokens.
+This matches the observed average of ~17,500/turn × 15 turns = 262,590.
+
+**The tool schemas are not the dominant cost on turn 15 — the accumulated
+conversation history is.** But the tool schemas ARE the dominant cost on
+early turns, and they compound the problem by bloating the prefix that
+rides along in every turn.