v0.40.0: capture task telemetry via SubagentStop (confirmed root cause) (#38)

Shahinyanm · web-flow · commit 6c0227255fd8 · 2026-06-04T11:25:54.000+04:00
Resolves the multi-release "0 task events" mystery with a clean,
in-session empirical proof — not another guess.

The proof (run this session, fresh 0.39.3, async already reverted):
  1. Captured a cutoff timestamp.
  2. Dispatched a real subagent via the Agent tool (32947 tokens,
     returned). Result: ZERO events after cutoff.
  3. In the SAME session, triggered a Read-deny on a large file.
     Result: exactly 1 `denied` event written after its cutoff.
  4. An unbounded recursive search was blocked by hook-pre-bash
     (hooks demonstrably live this session).

So: appendEvent + the hook runtime are healthy (Read-deny wrote),
but PostToolUse:Task produces nothing on a real dispatch. That is
the entire "0 task events" history explained — the parent-side
PostToolUse hook simply does not fire for the dispatch tool on this
Claude Code. async (v0.35.0) was never the cause; the April zeros
predate it. Releases v0.33.1 / v0.39.2 chased the wrong layer.

The fix — SubagentStop:
  Claude Code's SubagentStop is the canonical subagent-completion
  event (bundle schema: agent_id, agent_type, agent_transcript_path,
  last_assistant_message). It fires once per subagent by definition.
  New hook-subagent-stop writes the `event:"task"` record from it:
    - subagent_type = agent_type (the adoption signal v0.30 needs:
      was a subagent used, tp-* or not)
    - estTokens = best-effort sum from the transcript usage
      (agent_transcript_path), 0 on any failure
    - code:"subagent_stop" marks the source so a future revival of
      PostToolUse:Task can be deduped, not double-counted
  Routing-miss detection (general-purpose where tp-* fit) stays in
  the PreToolUse:Task diagnostic, which has the task description
  SubagentStop lacks.

Wiring:
  - src/hooks/subagent-stop.ts — buildSubagentTaskEvent +
    tokensFromTranscript (both pure / injectable, fully tested).
  - index.ts case hook-subagent-stop (synchronous — writes telemetry).
  - hooks/hooks.json + installer.ts: SubagentStop section, installed
    + uninstalled idempotently alongside the others.
  - typo-guard registers hook-subagent-stop.

Verified end-to-end against the built dist: a SubagentStop payload
for tp-pr-reviewer writes event:"task" subagent_type=tp-pr-reviewer
code=subagent_stop.

PostToolUse:Task is KEPT (harmless; carries tokens if CC ever fixes
it; code-marked events let stats dedup).

Tests: 1328/1328 pass (+9 subagent-stop + typo-guard).
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot \u2014 save 60-90% tokens when AI reads code",
-    "version": "0.39.3"
+    "version": "0.40.0"
   },
   "plugins": [
     {
       "name": "token-pilot",
       "source": "./",
       "description": "Reduces token consumption by 60-90% via AST-aware lazy file reading, structural symbol navigation, and cross-session tool-usage analytics. 22 MCP tools + 19 subagents + budget watchdog hooks.",
-      "version": "0.39.3",
+      "version": "0.40.0",
       "author": {
         "name": "Digital-Threads"
       },
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.39.3",
+  "version": "0.40.0",
   "description": "Saves 60-90% tokens on AI code reading. AST-aware lazy reads, symbol navigation, find_usages, structural git diff/log, edit-safety guard, Task-routing matcher, cross-session telemetry (errors + diagnostics), 25 tp-* subagents tiered to haiku/sonnet/opus with budget watchdog.",
   "author": {
     "name": "Digital-Threads",
diff --git a/agents/tp-api-surface-tracker.md b/agents/tp-api-surface-tracker.md
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-audit-scanner.md b/agents/tp-audit-scanner.md
@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-commit-writer.md b/agents/tp-commit-writer.md
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-context-engineer.md b/agents/tp-context-engineer.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-dead-code-finder.md b/agents/tp-dead-code-finder.md
@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-debugger.md b/agents/tp-debugger.md
@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-dep-health.md b/agents/tp-dep-health.md
@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-doc-writer.md b/agents/tp-doc-writer.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-history-explorer.md b/agents/tp-history-explorer.md
@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-impact-analyzer.md b/agents/tp-impact-analyzer.md
@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-incident-timeline.md b/agents/tp-incident-timeline.md
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-incremental-builder.md b/agents/tp-incremental-builder.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-migration-scout.md b/agents/tp-migration-scout.md
@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-onboard.md b/agents/tp-onboard.md
@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-performance-profiler.md b/agents/tp-performance-profiler.md
@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-pr-reviewer.md b/agents/tp-pr-reviewer.md
@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-refactor-planner.md b/agents/tp-refactor-planner.md
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-review-impact.md b/agents/tp-review-impact.md
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-run.md b/agents/tp-run.md
@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-session-restorer.md b/agents/tp-session-restorer.md
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-ship-coordinator.md b/agents/tp-ship-coordinator.md
@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-spec-writer.md b/agents/tp-spec-writer.md
@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-test-coverage-gapper.md b/agents/tp-test-coverage-gapper.md
@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-test-triage.md b/agents/tp-test-triage.md
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 requiredMcpServers:
   - "token-pilot"
diff --git a/agents/tp-test-writer.md b/agents/tp-test-writer.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.39.3"
+token_pilot_version: "0.40.0"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
 requiredMcpServers:
   - "token-pilot"
diff --git a/hooks/hooks.json b/hooks/hooks.json
@@ -96,6 +96,16 @@
           }
         ]
       }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-subagent-stop"
+          }
+        ]
+      }
     ]
   }
 }
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.39.3",
+  "version": "0.40.0",
   "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",
diff --git a/src/cli/typo-guard.ts b/src/cli/typo-guard.ts
@@ -37,6 +37,8 @@ export const KNOWN_COMMANDS = [
   // v0.35.0 — one-shot project setup hook (uses Claude Code's
   // undocumented `once: true` SessionStart flag).
   "hook-bootstrap",
+  // v0.40.0 — canonical subagent-completion capture
+  "hook-subagent-stop",
   "install-hook",
   "uninstall-hook",
   "install-ast-index",
diff --git a/src/hooks/installer.ts b/src/hooks/installer.ts
@@ -170,13 +170,21 @@ function createHookConfig(options?: HookInstallOptions) {
           // v0.39.2 — post-task MUST run synchronously. It writes the
           // `event:"task"` record via appendEvent (mkdir + stat +
           // appendFile). Under `async: true` Claude Code fires the hook
-          // detached and may reap the process before those writes flush
-          // — the suspected cause of persistently zero task events in
-          // hook-events.jsonl despite subagents being dispatched.
-          // Telemetry integrity > the ~5ms saved on a non-hot-path hook.
+          // detached and may reap the process before those writes flush.
+          // Kept as a secondary path; v0.39.3 probe showed it does not
+          // fire on current Claude Code (see SubagentStop below).
           hooks: [hookEntry("hook-post-task", options)],
         },
       ],
+      // v0.40.0 — SubagentStop is the canonical, reliably-firing
+      // subagent-completion event. PostToolUse:Task proved non-firing
+      // for the dispatch tool; SubagentStop is where the task adoption
+      // signal is actually captured. Synchronous (writes telemetry).
+      SubagentStop: [
+        {
+          hooks: [hookEntry("hook-subagent-stop", options)],
+        },
+      ],
     },
   };
 }
@@ -342,6 +350,21 @@ export async function installHook(
       }
     }
 
+    // v0.40.0 — SubagentStop (canonical subagent-completion capture).
+    // Installed idempotently, same pattern as SessionStart.
+    if (Array.isArray((hookConfig.hooks as any).SubagentStop)) {
+      if (!Array.isArray(settings.hooks.SubagentStop)) {
+        settings.hooks.SubagentStop = [];
+      }
+      const hasSubagentStop =
+        settings.hooks.SubagentStop.some(isTokenPilotHook);
+      if (!hasSubagentStop) {
+        settings.hooks.SubagentStop.push(
+          ...(hookConfig.hooks as any).SubagentStop,
+        );
+      }
+    }
+
     await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 
     return {
@@ -374,7 +397,13 @@ export async function uninstallHook(
     const hasPreToolUse = !!settings.hooks?.PreToolUse;
     const hasSessionStart = !!settings.hooks?.SessionStart;
     const hasPostToolUse = !!settings.hooks?.PostToolUse;
-    if (!hasPreToolUse && !hasSessionStart && !hasPostToolUse) {
+    const hasSubagentStop = !!settings.hooks?.SubagentStop;
+    if (
+      !hasPreToolUse &&
+      !hasSessionStart &&
+      !hasPostToolUse &&
+      !hasSubagentStop
+    ) {
       return { removed: false, fatal: false, message: "No hooks to remove." };
     }
 
@@ -408,6 +437,15 @@ export async function uninstallHook(
       }
     }
 
+    if (Array.isArray(settings.hooks?.SubagentStop)) {
+      settings.hooks.SubagentStop = settings.hooks.SubagentStop.filter(
+        (h: any) => !isTokenPilotHook(h),
+      );
+      if (settings.hooks.SubagentStop.length === 0) {
+        delete settings.hooks.SubagentStop;
+      }
+    }
+
     if (settings.hooks && Object.keys(settings.hooks).length === 0) {
       delete settings.hooks;
     }
diff --git a/src/hooks/subagent-stop.ts b/src/hooks/subagent-stop.ts
diff --git a/src/index.ts b/src/index.ts
diff --git a/tests/cli/typo-guard.test.ts b/tests/cli/typo-guard.test.ts
diff --git a/tests/hooks/subagent-stop.test.ts b/tests/hooks/subagent-stop.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "token-pilot",`
`3`		`- "version": "0.39.3",`
	`3`	`+ "version": "0.40.0",`
`4`	`4`	`"description": "Saves 60-90% tokens on AI code reading. AST-aware lazy reads, symbol navigation, find_usages, structural git diff/log, edit-safety guard, Task-routing matcher, cross-session telemetry (errors + diagnostics), 25 tp-* subagents tiered to haiku/sonnet/opus with budget watchdog.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Digital-Threads",`