token-pilot 0.40.0 → 0.42.0

package/.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.42.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.42.0",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

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

package/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

package/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.42.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-audit-scanner.md

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

package/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.42.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-context-engineer.md

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

package/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.42.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-debugger.md

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

package/agents/tp-dep-health.md

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

package/agents/tp-doc-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-history-explorer.md

@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-impact-analyzer.md

@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-incident-timeline.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-incremental-builder.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-migration-scout.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
 requiredMcpServers:
   - "token-pilot"

package/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.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-performance-profiler.md

@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-pr-reviewer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
 requiredMcpServers:
   - "token-pilot"

package/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.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-review-impact.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-run.md

@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-ship-coordinator.md

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

package/agents/tp-spec-writer.md

@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-test-coverage-gapper.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
 requiredMcpServers:
   - "token-pilot"

package/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.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-test-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.40.0"
+token_pilot_version: "0.42.0"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
 requiredMcpServers:
   - "token-pilot"

package/dist/cli/ecosystem-check.js

@@ -225,18 +225,10 @@ export function formatStatuslineHint(result, ecosystemStatuses) {
         case "unknown":
             return null;
         case "not-configured": {
-            lines.push(`  ○ no statusline badge configured — add one to see token-pilot`);
-            lines.push(`    state (enforcement mode + cumulative saved tokens) in`);
-            lines.push(`    Claude Code's status bar.`);
-            lines.push("");
-            const command = pluginRoot
-                ? `bash "${pluginRoot}/hooks/statusline-chain.sh"`
-                : `bash "$(ls -t ~/.claude/plugins/cache/token-pilot/token-pilot/*/hooks/statusline-chain.sh 2>/dev/null | head -1)"`;
-            lines.push(`    Add to ${result.configPath}:`);
-            lines.push(`      "statusLine": {`);
-            lines.push(`        "type": "command",`);
-            lines.push(`        "command": "${command.replace(/"/g, '\\"')}"`);
-            lines.push(`      }`);
+            lines.push(`  ○ no statusline badge configured — see token-pilot's live`);
+            lines.push(`    saved-token count + enforcement mode in your status bar.`);
+            lines.push(`    one command (non-destructive — never clobbers an existing one):`);
+            lines.push(`      token-pilot install-statusline`);
             return lines.join("\n");
         }
     }

package/dist/cli/install-statusline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * v0.42.0 — `token-pilot install-statusline`.
+ *
+ * Convenience installer for the statusline badge. v0.41.1 removed the
+ * intrusive sessionTitle overwrite and pointed users at the additive
+ * statusline (hooks/statusline-chain.sh) — the caveman-style channel
+ * that sits ALONGSIDE the session name and live-updates on every render.
+ * This command wires it into `~/.claude/settings.json` without making
+ * the user hand-edit JSON.
+ *
+ * Non-destructive by design (the sessionTitle lesson): we NEVER clobber
+ * a third-party statusLine. Decision per current state:
+ *
+ *   not-configured        → write our chain command
+ *   configured-caveman-only → upgrade to chain (shows BOTH badges)
+ *   configured-tp-only    → upgrade to chain (so caveman shows too if present)
+ *   configured-chain      → already ideal, no-op
+ *   configured-other      → leave alone; print how to switch manually
+ *   unknown               → settings.json unreadable; print guidance
+ *
+ * `--force` overrides the configured-other guard for users who really
+ * want to replace a custom statusLine.
+ */
+import type { StatuslineStatus } from "./ecosystem-check.js";
+/** The version-agnostic chain command (auto-picks the newest plugin dir). */
+export declare const CHAIN_COMMAND = "bash \"$(ls -t ~/.claude/plugins/cache/token-pilot/token-pilot/*/hooks/statusline-chain.sh 2>/dev/null | head -1)\"";
+export interface InstallStatuslineResult {
+    action: "installed" | "upgraded" | "noop" | "skipped";
+    message: string;
+}
+/**
+ * Pure decision: given the current statusline status, what should the
+ * installer do? Separated from I/O for unit tests.
+ */
+export declare function decideStatuslineAction(status: StatuslineStatus, force: boolean): {
+    write: boolean;
+    result: InstallStatuslineResult;
+};
+/**
+ * Classify the statusLine state of a settings.json at `settingsPath`.
+ * Async, path-injectable (so tests point at a tmp file). Mirrors
+ * ecosystem-check.checkStatusline but works on any path. Never throws.
+ */
+export declare function classifyStatuslineAt(settingsPath: string): Promise<StatuslineStatus>;
+/**
+ * CLI entry. Returns an exit code.
+ */
+export declare function handleInstallStatusline(argv: string[], opts?: {
+    settingsPath?: string;
+}): Promise<number>;
+//# sourceMappingURL=install-statusline.d.ts.map

package/dist/cli/install-statusline.js

@@ -0,0 +1,160 @@
+/**
+ * v0.42.0 — `token-pilot install-statusline`.
+ *
+ * Convenience installer for the statusline badge. v0.41.1 removed the
+ * intrusive sessionTitle overwrite and pointed users at the additive
+ * statusline (hooks/statusline-chain.sh) — the caveman-style channel
+ * that sits ALONGSIDE the session name and live-updates on every render.
+ * This command wires it into `~/.claude/settings.json` without making
+ * the user hand-edit JSON.
+ *
+ * Non-destructive by design (the sessionTitle lesson): we NEVER clobber
+ * a third-party statusLine. Decision per current state:
+ *
+ *   not-configured        → write our chain command
+ *   configured-caveman-only → upgrade to chain (shows BOTH badges)
+ *   configured-tp-only    → upgrade to chain (so caveman shows too if present)
+ *   configured-chain      → already ideal, no-op
+ *   configured-other      → leave alone; print how to switch manually
+ *   unknown               → settings.json unreadable; print guidance
+ *
+ * `--force` overrides the configured-other guard for users who really
+ * want to replace a custom statusLine.
+ */
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** The version-agnostic chain command (auto-picks the newest plugin dir). */
+export const CHAIN_COMMAND = 'bash "$(ls -t ~/.claude/plugins/cache/token-pilot/token-pilot/*/hooks/statusline-chain.sh 2>/dev/null | head -1)"';
+/**
+ * Pure decision: given the current statusline status, what should the
+ * installer do? Separated from I/O for unit tests.
+ */
+export function decideStatuslineAction(status, force) {
+    switch (status) {
+        case "not-configured":
+            return {
+                write: true,
+                result: {
+                    action: "installed",
+                    message: "statusLine configured — the [TP] badge will show in your status bar (restart Claude Code).",
+                },
+            };
+        case "configured-caveman-only":
+        case "configured-tp-only":
+            return {
+                write: true,
+                result: {
+                    action: "upgraded",
+                    message: "statusLine upgraded to the chain wrapper — both caveman and [TP] badges now render side by side.",
+                },
+            };
+        case "configured-chain":
+            return {
+                write: false,
+                result: {
+                    action: "noop",
+                    message: "statusLine already uses the token-pilot chain wrapper. Nothing to do.",
+                },
+            };
+        case "configured-other":
+            if (force) {
+                return {
+                    write: true,
+                    result: {
+                        action: "installed",
+                        message: "Replaced your custom statusLine with the token-pilot chain wrapper (--force).",
+                    },
+                };
+            }
+            return {
+                write: false,
+                result: {
+                    action: "skipped",
+                    message: "You already have a custom statusLine — left untouched. " +
+                        "To show the [TP] badge too, set statusLine.command to:\n  " +
+                        CHAIN_COMMAND +
+                        "\nor re-run with --force to replace it.",
+                },
+            };
+        case "unknown":
+        default:
+            return {
+                write: false,
+                result: {
+                    action: "skipped",
+                    message: "Could not read ~/.claude/settings.json as JSON — not modifying it. " +
+                        "Add this manually under \"statusLine\":\n  " +
+                        CHAIN_COMMAND,
+                },
+            };
+    }
+}
+/**
+ * Classify the statusLine state of a settings.json at `settingsPath`.
+ * Async, path-injectable (so tests point at a tmp file). Mirrors
+ * ecosystem-check.checkStatusline but works on any path. Never throws.
+ */
+export async function classifyStatuslineAt(settingsPath) {
+    try {
+        await access(settingsPath);
+    }
+    catch {
+        return "not-configured";
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(settingsPath, "utf-8"));
+    }
+    catch {
+        return "unknown";
+    }
+    const cmd = parsed
+        ?.statusLine?.command;
+    if (typeof cmd !== "string")
+        return "not-configured";
+    if (cmd.includes("statusline-chain.sh"))
+        return "configured-chain";
+    if (cmd.includes("tp-statusline.sh"))
+        return "configured-tp-only";
+    if (cmd.includes("caveman-statusline.sh"))
+        return "configured-caveman-only";
+    return "configured-other";
+}
+/**
+ * CLI entry. Returns an exit code.
+ */
+export async function handleInstallStatusline(argv, opts) {
+    const force = argv.includes("--force");
+    const settingsPath = opts?.settingsPath ?? join(homedir(), ".claude", "settings.json");
+    const status = await classifyStatuslineAt(settingsPath);
+    const { write, result } = decideStatuslineAction(status, force);
+    if (!write) {
+        process.stdout.write(`[token-pilot] ${result.message}\n`);
+        return 0;
+    }
+    // Merge the statusLine field into existing settings (preserve the rest).
+    let settings = {};
+    try {
+        const raw = await readFile(settingsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            settings = parsed;
+        }
+    }
+    catch {
+        /* fresh file — start clean (only reached when status was safe) */
+    }
+    settings.statusLine = { type: "command", command: CHAIN_COMMAND };
+    try {
+        await mkdir(dirname(settingsPath), { recursive: true });
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    catch (err) {
+        process.stderr.write(`[token-pilot] failed to write ${settingsPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    process.stdout.write(`[token-pilot] ${result.message}\n`);
+    return 0;
+}
+//# sourceMappingURL=install-statusline.js.map

package/dist/cli/typo-guard.d.ts

@@ -17,7 +17,7 @@
  * Everything else passes through untouched — a real project root like
  * `/home/user/my-project` or `./subdir` goes to startServer as before.
  */
-export declare const KNOWN_COMMANDS: readonly ["hook-read", "hook-edit", "hook-pre-bash", "hook-pre-grep", "hook-pre-task", "hook-post-bash", "hook-post-task", "hook-session-start", "hook-bootstrap", "hook-subagent-stop", "install-hook", "uninstall-hook", "install-ast-index", "doctor", "bless-agents", "unbless-agents", "install-agents", "uninstall-agents", "stats", "tool-audit", "save-doc", "list-docs", "init", "migrate-hooks", "errors", "workflow", "--version", "-v", "--help", "-h"];
+export declare const KNOWN_COMMANDS: readonly ["hook-read", "hook-edit", "hook-pre-bash", "hook-pre-grep", "hook-pre-task", "hook-post-bash", "hook-post-task", "hook-session-start", "hook-bootstrap", "hook-subagent-stop", "install-statusline", "install-hook", "uninstall-hook", "install-ast-index", "doctor", "bless-agents", "unbless-agents", "install-agents", "uninstall-agents", "stats", "tool-audit", "save-doc", "list-docs", "init", "migrate-hooks", "errors", "workflow", "--version", "-v", "--help", "-h"];
 export interface TypoGuardResult {
     kind: "pass-through" | "typo";
     suggestion?: string;

package/dist/cli/typo-guard.js

@@ -37,6 +37,8 @@ export const KNOWN_COMMANDS = [
     "hook-bootstrap",
     // v0.40.0 — canonical subagent-completion capture
     "hook-subagent-stop",
+    // v0.42.0 — one-command statusline badge installer
+    "install-statusline",
     "install-hook",
     "uninstall-hook",
     "install-ast-index",

package/dist/hooks/session-start.js

@@ -274,72 +274,20 @@ export async function handleSessionStart(opts) {
             ".token-pilot/snapshots/latest.md",
             ".token-pilot/hook-events.jsonl",
         ];
-        // v0.36.0 — sessionTitle was added in Claude Code 2.1.152. We surface
-        // the cumulative saved-token count for this project so users see the
-        // payoff at a glance in their window/tab title. Best-effort — if the
-        // savings file is unreadable we fall back to a neutral title.
-        let sessionTitle;
-        try {
-            const { loadSessionStats } = await import("../core/session-savings.js");
-            // Sum savings across all sessions in this project, not just one.
-            const stats = loadSessionStats(opts.projectRoot, "");
-            // sessionId="" makes loadSessionStats short-circuit; use a tiny
-            // dedicated reader instead.
-            const { readFileSync } = await import("node:fs");
-            const { join } = await import("node:path");
-            let total = 0;
-            try {
-                const raw = readFileSync(join(opts.projectRoot, ".token-pilot", "hook-events.jsonl"), "utf-8");
-                for (const line of raw.split("\n")) {
-                    if (!line)
-                        continue;
-                    try {
-                        const ev = JSON.parse(line);
-                        if (typeof ev.savedTokens === "number")
-                            total += ev.savedTokens;
-                    }
-                    catch {
-                        /* skip malformed line */
-                    }
-                }
-            }
-            catch {
-                /* no log file yet */
-            }
-            // Use the larger of "single-session" (loadSessionStats fallback)
-            // and the all-sessions sum so an empty single-session number
-            // doesn't override the meaningful project-wide total.
-            const surfaced = Math.max(total, stats.savedTokens);
-            if (surfaced > 0) {
-                const human = surfaced >= 1_000_000
-                    ? `${(surfaced / 1_000_000).toFixed(1)}M`
-                    : surfaced >= 1000
-                        ? `${Math.round(surfaced / 1000)}k`
-                        : `${surfaced}`;
-                sessionTitle = `[TP] ${human} saved`;
-            }
-            // v0.38.0 — when a fleet workflow is active, prefer a
-            // workflow-progress title so a long fan-out run shows live
-            // task count + budget in the window title.
-            const { activeWorkflowId, workflowStatus } = await import("../core/workflow.js");
-            const wfId = activeWorkflowId();
-            if (wfId) {
-                const st = await workflowStatus(opts.projectRoot, wfId);
-                if (st) {
-                    const pct = st.pct != null ? ` · ${st.pct}%` : "";
-                    sessionTitle = `[TP] wf · ${st.task_count} tasks${pct}`;
-                }
-            }
-        }
-        catch {
-            /* sessionTitle is best-effort decoration; never block startup */
-        }
+        // v0.41.1 — sessionTitle removed. v0.36.0 set the window/tab title
+        // to `[TP] Nk saved`, but `sessionTitle` OVERWRITES Claude Code's
+        // own session name — an intrusive clobber users (rightly) disliked.
+        // The cumulative-savings display belongs in the additive statusline
+        // badge (hooks/tp-statusline.sh), the same non-intrusive channel
+        // caveman uses — it sits alongside the session name instead of
+        // replacing it. Workflow progress, likewise, can ride the
+        // statusline (tp-statusline.sh reads the active workflow) rather
+        // than hijacking the title.
         const output = {
             hookSpecificOutput: {
                 hookEventName: "SessionStart",
                 additionalContext: message,
                 watchPaths,
-                ...(sessionTitle ? { sessionTitle } : {}),
             },
         };
         return JSON.stringify(output);

package/dist/hooks/subagent-stop.d.ts

@@ -52,4 +52,32 @@ export declare function tokensFromTranscript(path: string | undefined): number;
  * can pre-resolve for tests via `tokensOverride`.
  */
 export declare function buildSubagentTaskEvent(input: SubagentStopInput, now: number, tokensOverride?: number): HookEvent | null;
+export interface SubagentFeedbackContext {
+    /** Active workflow budget status, when a fleet workflow is running. */
+    workflow?: {
+        workflow_id: string;
+        budget_tokens: number | null;
+        used_tokens: number;
+        pct: number | null;
+    } | null;
+}
+/**
+ * Decide the `additionalContext` feedback to hand back from a
+ * SubagentStop hook. Pure — caller resolves the workflow status.
+ *
+ * Returns a short wind-down note when an active fleet workflow is at or
+ * past 90 % of its token ceiling, so a `/workflow`-style fan-out winds
+ * down before the budget is blown. Returns null otherwise — we do NOT
+ * nag on every completion; broad adoption nudges stay in SessionStart.
+ *
+ * Emission is the caller's responsibility and is gated behind
+ * TOKEN_PILOT_SUBAGENT_FEEDBACK=1 + Claude Code 2.1.163+ (older Claude
+ * Code labels a SubagentStop hookSpecificOutput return as a hook error).
+ */
+export declare function decideSubagentFeedback(_input: SubagentStopInput, ctx: SubagentFeedbackContext): string | null;
+/**
+ * Render the SubagentStop hook JSON response carrying feedback. Returns
+ * null when there is nothing to say (caller writes no stdout).
+ */
+export declare function renderSubagentFeedback(message: string | null): string | null;
 //# sourceMappingURL=subagent-stop.d.ts.map

package/dist/hooks/subagent-stop.js

@@ -105,4 +105,45 @@ export function buildSubagentTaskEvent(input, now, tokensOverride) {
         code: "subagent_stop",
     };
 }
+/**
+ * Decide the `additionalContext` feedback to hand back from a
+ * SubagentStop hook. Pure — caller resolves the workflow status.
+ *
+ * Returns a short wind-down note when an active fleet workflow is at or
+ * past 90 % of its token ceiling, so a `/workflow`-style fan-out winds
+ * down before the budget is blown. Returns null otherwise — we do NOT
+ * nag on every completion; broad adoption nudges stay in SessionStart.
+ *
+ * Emission is the caller's responsibility and is gated behind
+ * TOKEN_PILOT_SUBAGENT_FEEDBACK=1 + Claude Code 2.1.163+ (older Claude
+ * Code labels a SubagentStop hookSpecificOutput return as a hook error).
+ */
+export function decideSubagentFeedback(_input, ctx) {
+    const wf = ctx.workflow;
+    if (wf &&
+        wf.budget_tokens != null &&
+        wf.budget_tokens > 0 &&
+        wf.used_tokens >= wf.budget_tokens * 0.9) {
+        const pct = wf.pct != null ? `${wf.pct}%` : "~90%";
+        return (`[token-pilot] workflow ${wf.workflow_id} is at ${pct} of its ` +
+            `${wf.budget_tokens} token ceiling (${wf.used_tokens} used). ` +
+            `Wind down the fan-out: finish in-flight branches and report ` +
+            `rather than dispatching new agents.`);
+    }
+    return null;
+}
+/**
+ * Render the SubagentStop hook JSON response carrying feedback. Returns
+ * null when there is nothing to say (caller writes no stdout).
+ */
+export function renderSubagentFeedback(message) {
+    if (!message)
+        return null;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "SubagentStop",
+            additionalContext: message,
+        },
+    });
+}
 //# sourceMappingURL=subagent-stop.js.map

package/dist/index.js

@@ -336,12 +336,37 @@ export async function main(cliArgs = process.argv.slice(2)) {
             await runHookEntryPoint({ hook: "hook-subagent-stop" }, async () => {
                 const stdin = readFileSync(0, "utf-8");
                 const input = JSON.parse(stdin);
-                const { buildSubagentTaskEvent } = await import("./hooks/subagent-stop.js");
+                const { buildSubagentTaskEvent, decideSubagentFeedback, renderSubagentFeedback, } = await import("./hooks/subagent-stop.js");
                 const ev = buildSubagentTaskEvent(input, Date.now());
                 if (ev) {
                     const { appendEvent } = await import("./core/event-log.js");
                     await appendEvent(process.cwd(), ev);
                 }
+                // v0.41.0 — optional SubagentStop feedback. Returning
+                // hookSpecificOutput.additionalContext from SubagentStop is a
+                // Claude Code 2.1.163+ feature; on older Claude Code it is
+                // labelled a hook error (noise). Gate strictly behind
+                // TOKEN_PILOT_SUBAGENT_FEEDBACK=1 so the default path (telemetry
+                // only) stays safe on every version.
+                if (process.env.TOKEN_PILOT_SUBAGENT_FEEDBACK === "1") {
+                    const { activeWorkflowId, workflowStatus } = await import("./core/workflow.js");
+                    let wf = null;
+                    const wfId = activeWorkflowId();
+                    if (wfId) {
+                        const st = await workflowStatus(process.cwd(), wfId);
+                        if (st) {
+                            wf = {
+                                workflow_id: st.workflow_id,
+                                budget_tokens: st.budget_tokens,
+                                used_tokens: st.used_tokens,
+                                pct: st.pct,
+                            };
+                        }
+                    }
+                    const rendered = renderSubagentFeedback(decideSubagentFeedback(input, { workflow: wf }));
+                    if (rendered)
+                        process.stdout.write(rendered);
+                }
             });
             return;
         }
@@ -400,6 +425,16 @@ export async function main(cliArgs = process.argv.slice(2)) {
             process.exit(code);
             return;
         }
+        case "install-statusline": {
+            // v0.42.0 — wire the additive statusline badge into
+            // ~/.claude/settings.json so users don't hand-edit JSON. Never
+            // clobbers a third-party statusLine (the sessionTitle lesson);
+            // upgrades caveman-only / tp-only to the chain wrapper.
+            const { handleInstallStatusline } = await import("./cli/install-statusline.js");
+            const code = await handleInstallStatusline(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
         case "migrate-hooks": {
             // v0.33.0 — clean stale npx-cache / pinned-version token-pilot
             // hook entries from user-level + project-level settings.json so

package/package.json

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