v0.41.0: SubagentStop budget feedback (env-gated, CC 2.1.163+) (#39)

CC 2.1.163 added: "Stop and SubagentStop hooks can now return
hookSpecificOutput.additionalContext to give Claude feedback and keep
the turn going without being labeled a hook error." That unlocks
in-the-moment feedback from our v0.40.0 SubagentStop capture, useful
for the new dynamic-workflows era (a /workflow run fans out to tens-
hundreds of agents).

Verified against the user's installed bundle FIRST (the doctrine):
the active CC is 2.1.161, which does NOT support additionalContext
from SubagentStop — returning it there is labelled a hook error
(noise, the v0.34.0-args failure class). So this is strictly
env-gated, default OFF, and documented as 2.1.163+ only.

What it does (when TOKEN_PILOT_SUBAGENT_FEEDBACK=1 AND CC >= 2.1.163):
  - decideSubagentFeedback(): when an active `token-pilot workflow`
    is at >=90% of its token ceiling, returns a wind-down note so a
    large fan-out stops dispatching new agents before the budget
    blows. Silent otherwise — no nagging on every completion; broad
    adoption nudges stay in SessionStart.
  - renderSubagentFeedback(): wraps it in the SubagentStop
    hookSpecificOutput shape.
  - hook-subagent-stop emits it ONLY behind the env flag; the
    default path (telemetry write only, v0.40.0) is unchanged and
    safe on every CC version.

Pure logic is fully unit-tested; the CC-side emission can only be
verified once on 2.1.163 (the user is not there yet) — hence the flag.

Tests: 1333/1333 pass (+5).
Build: clean (25 agents under 0.41.0).

Author: Shahinyanm

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot \u2014 save 60-90% tokens when AI reads code",
-    "version": "0.40.0"
+    "version": "0.41.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.40.0",
+      "version": "0.41.0",
       "author": {
         "name": "Digital-Threads"
       },

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.40.0",
+  "version": "0.41.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",

README.md

@@ -232,6 +232,21 @@ lines instead of bouncing the call. The structural summary still
 rides along in `additionalContext`. Default OFF because the field
 is undocumented and may change.
 
+### Experimental: SubagentStop budget feedback (CC 2.1.163+)
+
+Every subagent completion already lands a task-telemetry row via the
+`SubagentStop` hook (that's how `stats --tasks` knows what you
+dispatched). With `TOKEN_PILOT_SUBAGENT_FEEDBACK=1` the same hook also
+returns `additionalContext` — when a `token-pilot workflow` fan-out is
+at ≥90 % of its token ceiling, each completing agent gets a wind-down
+note so a hundred-agent `/workflow` run stops before blowing the
+budget.
+
+**Requires Claude Code 2.1.163+.** Returning `additionalContext` from
+`SubagentStop` is only honoured there; older Claude Code labels it a
+hook error. Default OFF for that reason — enable only once
+`claude --version` reports 2.1.163 or later.
+
 ## What's new for Claude Code 2.1.151+
 
 These notes are about behaviour you'll see automatically once you

agents/tp-api-surface-tracker.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 requiredMcpServers:
   - "token-pilot"

agents/tp-audit-scanner.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
 requiredMcpServers:
   - "token-pilot"

agents/tp-commit-writer.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 requiredMcpServers:
   - "token-pilot"

agents/tp-context-engineer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
 requiredMcpServers:
   - "token-pilot"

agents/tp-dead-code-finder.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 requiredMcpServers:
   - "token-pilot"

agents/tp-debugger.md

@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
 requiredMcpServers:
   - "token-pilot"

agents/tp-dep-health.md

@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.41.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 requiredMcpServers:
   - "token-pilot"