token-pilot 0.34.3 → 0.36.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.34.3"
+    "version": "0.36.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.34.3",
+      "version": "0.36.0",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

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

@@ -154,6 +154,121 @@ quality-of-life notes for the newer ones.
   the MCP server entry. The skill list, the agent list, and the LSP
   list are all auto-discovered from the canonical sub-folders.
 
+## Power-user — undocumented Claude Code features that pair with token-pilot
+
+These fields come from reverse-engineering `@anthropic-ai/claude-code@2.1.87`
+source (see the May 2026 Habr write-up). They work today but are
+not in the official Claude Code docs, so use at your own risk.
+
+### Persistent agent memory (`memory: project`)
+
+Every relevant tp-\* agent (onboard, debugger, pr-reviewer,
+history-explorer, audit-scanner) now ships with `memory: project`
+in its frontmatter. Claude Code persists the agent's working notes
+in the project so the agent gets faster on repeat invocations —
+`tp-onboard` remembers your layout, `tp-pr-reviewer` remembers your
+flagged patterns, etc. v0.35.0+.
+
+### Required MCP gating (`requiredMcpServers`)
+
+Every tp-\* agent declares `requiredMcpServers: ["token-pilot"]`.
+Claude Code refuses to load the agent when the MCP server isn't
+configured, so a stale install never produces a "tools not found"
+loop. v0.35.0+.
+
+### Bootstrap-once hook (`once: true`)
+
+The plugin ships a SessionStart hook flagged `once: true` —
+Claude Code runs it once per project then auto-removes the entry.
+It surfaces friendly hints when `install-agents` or
+`install-ast-index` hasn't been run yet. v0.35.0+.
+
+### Async telemetry (`async: true`)
+
+PostToolUse hooks (Bash, Task) are marked `async: true` so they
+no longer add wall-clock to the hot path — telemetry writes fire
+in the background.
+
+### Auto-mode permissions (user-side)
+
+If you want full auto-approval for safe commands, the YOLO
+classifier reads natural-language environment descriptions:
+
+```json
+{
+  "autoMode": {
+    "allow": ["Bash(git status)", "Bash(npm test)", "Read", "Grep"],
+    "soft_deny": ["Bash(git push *)", "Bash(rm *)", "Write(.env)"],
+    "environmentDescription":
+      "This is a development laptop. Read-only ops are safe; deny anything touching credentials or production."
+  }
+}
+```
+
+token-pilot's enforcement still runs on top (raw Read on large files
+is denied first, regardless of autoMode).
+
+### Permission rule syntax cheat-sheet
+
+```
+Bash(npm *)                       # wildcard after "npm "
+Bash(git commit *)                # specific subcommand
+Read(*.ts)                        # extension
+Read(src/**/*.ts)                 # recursive + extension
+Write(src/**)                     # recursive all files
+mcp__token-pilot                  # all token-pilot MCP tools
+mcp__token-pilot__smart_read      # one specific MCP tool
+```
+
+`*` matches inside word boundaries (shell-glob); `**` is recursive.
+The `if` field on hooks uses the same syntax.
+
+### Experimental: transparent Read rewrite
+
+Set `TOKEN_PILOT_HOOK_REWRITE=1` to swap the "deny + suggest" Read
+hook behaviour for an `updatedInput` rewrite — Claude Code's
+undocumented field that silently bounds the Read to its first 200
+lines instead of bouncing the call. The structural summary still
+rides along in `additionalContext`. Default OFF because the field
+is undocumented and may change.
+
+## What's new for Claude Code 2.1.151+
+
+These notes are about behaviour you'll see automatically once you
+update both Claude Code and `token-pilot@latest`. No extra
+configuration required.
+
+### Session title badge (`[TP] Nk saved`)
+
+The SessionStart hook now sets the window/tab title to the cumulative
+token savings for the current project, using Claude Code 2.1.152's
+`hookSpecificOutput.sessionTitle` field. You'll see a badge like
+`[TP] 1.2M saved` in the title bar so you can confirm at a glance
+that the plugin is doing its job.
+
+### Hardened skills (`disallowed-tools`)
+
+The three bundled skills (`guide`, `install`, `stats`) declare
+`disallowed-tools` (Claude Code 2.1.152+) so a runaway model can't
+issue `Write` / `Edit` / `Task` while the skill is on display. The
+install skill keeps `Bash` because it has to run
+`npx token-pilot install-ast-index`; the other two have Bash
+disallowed too.
+
+### Auto mode on third-party providers
+
+Claude Code 2.1.158 opened auto mode to Bedrock / Vertex / Foundry
+on Opus 4.7 + 4.8. If you're on one of those, opt in with
+`CLAUDE_CODE_ENABLE_AUTO_MODE=1`. token-pilot's deny-Read /
+deny-Bash gates still run on top — auto mode never bypasses them.
+
+### Opus 4.8 as fast-mode default
+
+Claude Code 2.1.154 made Opus 4.8 the default for high effort. The
+tp-* agents that already declared `model: haiku` keep their cheaper
+tier (90 %+ of the agent roster); the few sonnet/opus-tier ones
+ride the upgrade automatically.
+
 ## Troubleshooting
 
 ```bash

package/agents/tp-api-surface-tracker.md

@@ -9,8 +9,11 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
+requiredMcpServers:
+  - "token-pilot"
+color: blue
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-audit-scanner.md

@@ -11,8 +11,13 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
+requiredMcpServers:
+  - "token-pilot"
+memory: project
+color: red
+omitClaudeMd: true
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-commit-writer.md

@@ -8,8 +8,11 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
+requiredMcpServers:
+  - "token-pilot"
+color: purple
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-context-engineer.md

@@ -13,8 +13,11 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
+requiredMcpServers:
+  - "token-pilot"
+color: green
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-dead-code-finder.md

@@ -11,8 +11,11 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
+requiredMcpServers:
+  - "token-pilot"
+color: red
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-debugger.md

@@ -12,8 +12,12 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
+requiredMcpServers:
+  - "token-pilot"
+memory: project
+color: yellow
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-dep-health.md

@@ -9,8 +9,11 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
+requiredMcpServers:
+  - "token-pilot"
+color: purple
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-doc-writer.md

@@ -13,8 +13,11 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
+requiredMcpServers:
+  - "token-pilot"
+color: green
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-history-explorer.md

@@ -10,8 +10,12 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
+requiredMcpServers:
+  - "token-pilot"
+memory: project
+color: blue
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-impact-analyzer.md

@@ -12,8 +12,11 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
+requiredMcpServers:
+  - "token-pilot"
+color: blue
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-incident-timeline.md

@@ -8,8 +8,11 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
+requiredMcpServers:
+  - "token-pilot"
+color: yellow
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-incremental-builder.md

@@ -13,8 +13,11 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
+requiredMcpServers:
+  - "token-pilot"
+color: orange
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-migration-scout.md

@@ -11,8 +11,11 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
+requiredMcpServers:
+  - "token-pilot"
+color: orange
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-onboard.md

@@ -10,8 +10,12 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
+requiredMcpServers:
+  - "token-pilot"
+memory: project
+color: blue
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-performance-profiler.md

@@ -11,8 +11,11 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
+requiredMcpServers:
+  - "token-pilot"
+color: yellow
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-pr-reviewer.md

@@ -11,8 +11,12 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
+requiredMcpServers:
+  - "token-pilot"
+memory: project
+color: red
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-refactor-planner.md

@@ -8,8 +8,11 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
+requiredMcpServers:
+  - "token-pilot"
+color: orange
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-review-impact.md

@@ -9,8 +9,11 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
+requiredMcpServers:
+  - "token-pilot"
+color: red
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-run.md

@@ -16,8 +16,11 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
+requiredMcpServers:
+  - "token-pilot"
+color: gray
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-session-restorer.md

@@ -9,8 +9,11 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
+requiredMcpServers:
+  - "token-pilot"
+color: blue
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-ship-coordinator.md

@@ -11,8 +11,11 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b
+requiredMcpServers:
+  - "token-pilot"
+color: purple
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-spec-writer.md

@@ -9,8 +9,11 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
+requiredMcpServers:
+  - "token-pilot"
+color: orange
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

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

@@ -10,8 +10,11 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
+requiredMcpServers:
+  - "token-pilot"
+color: red
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-test-triage.md

@@ -8,8 +8,11 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
+requiredMcpServers:
+  - "token-pilot"
+color: red
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

package/agents/tp-test-writer.md

@@ -13,8 +13,11 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.34.3"
+token_pilot_version: "0.36.0"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
+requiredMcpServers:
+  - "token-pilot"
+color: yellow
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:

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", "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", "--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", "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", "--version", "-v", "--help", "-h"];
 export interface TypoGuardResult {
     kind: "pass-through" | "typo";
     suggestion?: string;

package/dist/cli/typo-guard.js

@@ -32,6 +32,9 @@ export const KNOWN_COMMANDS = [
     "hook-post-bash",
     "hook-post-task",
     "hook-session-start",
+    // v0.35.0 — one-shot project setup hook (uses Claude Code's
+    // undocumented `once: true` SessionStart flag).
+    "hook-bootstrap",
     "install-hook",
     "uninstall-hook",
     "install-ast-index",

package/dist/hooks/installer.js

@@ -67,11 +67,21 @@ export function isStaleTokenPilotHookCommand(cmd) {
  * reverts: shell-expanded `command` remains the safe, portable form
  * for every Claude Code version we know of. When Claude Code docs
  * confirm the env-expansion rules for `args`, we can revisit.
+ *
+ * v0.35.0 — `extras` lets callers attach undocumented Claude Code
+ * fields surfaced by reverse-engineering the 2.1.87 source:
+ *   - `async: true`     — non-blocking; ideal for telemetry-only
+ *                         PostToolUse hooks that just log events
+ *   - `once: true`      — runs exactly once per project, auto-removes
+ *                         on success; for first-session bootstrap
+ *   - `statusMessage`   — UI hint while the hook runs
+ * All are additive and ignored by older Claude Code versions.
  */
-function hookEntry(action, options) {
+function hookEntry(action, options, extras = {}) {
     return {
         type: "command",
         command: buildHookCommand(action, options),
+        ...extras,
     };
 }
 function createHookConfig(options) {
@@ -104,6 +114,15 @@ function createHookConfig(options) {
                 },
             ],
             SessionStart: [
+                {
+                    hooks: [
+                        // v0.35.0 — once-only bootstrap (project setup hints)
+                        hookEntry("hook-bootstrap", options, {
+                            once: true,
+                            statusMessage: "Bootstrapping token-pilot...",
+                        }),
+                    ],
+                },
                 {
                     hooks: [hookEntry("hook-session-start", options)],
                 },
@@ -111,11 +130,12 @@ function createHookConfig(options) {
             PostToolUse: [
                 {
                     matcher: "Bash",
-                    hooks: [hookEntry("hook-post-bash", options)],
+                    // v0.35.0 — async: true keeps telemetry off the hot path
+                    hooks: [hookEntry("hook-post-bash", options, { async: true })],
                 },
                 {
                     matcher: "Task",
-                    hooks: [hookEntry("hook-post-task", options)],
+                    hooks: [hookEntry("hook-post-task", options, { async: true })],
                 },
             ],
         },

package/dist/hooks/session-start.js

@@ -264,10 +264,70 @@ export async function handleSessionStart(opts) {
         catch {
             /* silent — telemetry nudge is strictly opt-in */
         }
+        // v0.35.0 — watchPaths is an undocumented SessionStart return key
+        // (surfaced by reverse-engineering @anthropic-ai/claude-code@2.1.87).
+        // Claude Code watches these paths and re-fires FileChanged so a
+        // second active session picks up new snapshots / errors emitted by
+        // another worker without manual polling. Additive — older Claude
+        // Code versions ignore the key.
+        const watchPaths = [
+            ".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`;
+            }
+        }
+        catch {
+            /* sessionTitle is best-effort decoration; never block startup */
+        }
         const output = {
             hookSpecificOutput: {
                 hookEventName: "SessionStart",
                 additionalContext: message,
+                watchPaths,
+                ...(sessionTitle ? { sessionTitle } : {}),
             },
         };
         return JSON.stringify(output);

package/dist/index.js

@@ -251,6 +251,57 @@ export async function main(cliArgs = process.argv.slice(2)) {
             });
             return;
         }
+        case "hook-bootstrap": {
+            // v0.35.0 — fires ONCE per project via Claude Code's undocumented
+            // `once: true` SessionStart flag. Self-removes after the first
+            // run, so steps must be idempotent (re-running cannot hurt).
+            // Stays silent on success; only emits hints when something is
+            // missing. Always exits 0 — the very first session must never
+            // be blocked by a bootstrap hint.
+            await runHookEntryPoint({ hook: "hook-bootstrap" }, async () => {
+                const cwd = process.cwd();
+                const hints = [];
+                // Detect installed tp-* agents (project-level OR user-level).
+                try {
+                    const { readdirSync, existsSync } = await import("node:fs");
+                    const projAgents = resolve(cwd, ".claude", "agents");
+                    const userAgents = resolve(homedir(), ".claude", "agents");
+                    let total = 0;
+                    for (const dir of [projAgents, userAgents]) {
+                        if (existsSync(dir)) {
+                            total += readdirSync(dir).filter((f) => f.startsWith("tp-") && f.endsWith(".md")).length;
+                        }
+                    }
+                    if (total === 0) {
+                        hints.push("no tp-* agents installed — run `npx token-pilot install-agents --scope=project` to enable the 25-agent toolkit");
+                    }
+                }
+                catch {
+                    /* skip silently */
+                }
+                // Detect ast-index binary availability.
+                try {
+                    const { findBinary } = await import("./ast-index/binary-manager.js");
+                    const status = await findBinary();
+                    if (!status.available) {
+                        hints.push("ast-index binary missing — run `npx token-pilot install-ast-index` to unlock find_usages / outline / read_symbol");
+                    }
+                }
+                catch {
+                    /* skip silently */
+                }
+                if (hints.length > 0) {
+                    const message = `[token-pilot] bootstrap notes:\n  - ${hints.join("\n  - ")}`;
+                    process.stdout.write(JSON.stringify({
+                        hookSpecificOutput: {
+                            hookEventName: "SessionStart",
+                            additionalContext: message,
+                        },
+                    }));
+                }
+            });
+            return;
+        }
         case "hook-session-start": {
             await runHookEntryPoint({ hook: "hook-session-start" }, async () => {
                 const cfg = await loadConfig(process.cwd());
@@ -757,6 +808,32 @@ async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, project
         tier: pipelineResult.tier,
     });
     await writeEvent("denied", Math.ceil(message.length / 4));
+    // v0.35.0 — `updatedInput` rewrite. Claude Code's undocumented
+    // PreToolUse return key (surfaced from @anthropic-ai/claude-code@2.1.87
+    // source) lets a hook silently transform the tool_input instead of
+    // blocking. When TOKEN_PILOT_HOOK_REWRITE=1 is set we bound the Read
+    // to its first ~200 lines so the model sees a truncated file rather
+    // than a deny + suggestion. The structural summary still rides in
+    // `additionalContext`, so the model gets both views in one round.
+    //
+    // Default OFF — the field is undocumented and changes user-visible
+    // behaviour. Opt-in only.
+    if (process.env.TOKEN_PILOT_HOOK_REWRITE === "1") {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                updatedInput: {
+                    file_path: filePath,
+                    offset: 1,
+                    limit: 200,
+                },
+                additionalContext: `[token-pilot] Read on ${filePath} was rewritten to lines 1-200 ` +
+                    `(file has ${lineCount} lines). For full structure use mcp__token-pilot__smart_read(${filePath}).\n\n` +
+                    message,
+            },
+        });
+    }
     return JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "PreToolUse",

package/hooks/hooks.json

@@ -57,6 +57,16 @@
       }
     ],
     "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-bootstrap",
+            "once": true,
+            "statusMessage": "Bootstrapping token-pilot..."
+          }
+        ]
+      },
       {
         "hooks": [
           {
@@ -72,7 +82,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-bash"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-bash",
+            "async": true
           }
         ]
       },
@@ -81,7 +92,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-task"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-task",
+            "async": true
           }
         ]
       }

package/package.json

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

package/skills/guide/SKILL.md

@@ -3,6 +3,17 @@ name: guide
 description: Show a quick-reference guide for all Token Pilot tools — when to use each one
 command: guide
 user_invocable: true
+# v0.36.0 — disallowed-tools is a Claude Code 2.1.152+ field that
+# strips the listed tools from the model's surface while this skill
+# is active. The guide just renders Markdown; it never needs Edit /
+# Write / Bash / Task. Defense-in-depth so a runaway model can't
+# mutate the workspace while a help screen is on display.
+disallowed-tools:
+  - Bash
+  - Edit
+  - MultiEdit
+  - Write
+  - Task
 ---
 
 Display the following Token Pilot tool reference to the user. Show it exactly as formatted below.

package/skills/install/SKILL.md

@@ -3,6 +3,16 @@ name: install
 description: Install or check ast-index binary (auto-downloads if missing)
 command: install
 user_invocable: true
+# v0.36.0 — disallowed-tools (Claude Code 2.1.152+). The install
+# skill drives one `npx token-pilot install-ast-index` Bash command;
+# nothing else. Keep Bash, block all write/edit/delegation tools so
+# a rogue interpretation can't extend the install into arbitrary
+# workspace mutation.
+disallowed-tools:
+  - Edit
+  - MultiEdit
+  - Write
+  - Task
 ---
 
 Run the following command to install or verify the ast-index binary:

package/skills/stats/SKILL.md

@@ -3,6 +3,14 @@ name: stats
 description: Show Token Pilot session analytics — token savings, per-tool breakdown, top files, per-agent grouping
 command: stats
 user_invocable: true
+# v0.36.0 — disallowed-tools (Claude Code 2.1.152+). stats only reads
+# the events log and runs `token-pilot stats` variants. No
+# Edit/Write/Task ever — block them defensively.
+disallowed-tools:
+  - Edit
+  - MultiEdit
+  - Write
+  - Task
 ---
 
 Two entry points: