token-pilot 0.24.2 → 0.26.6

package/.claude-plugin/marketplace.json

@@ -1,15 +1,32 @@
 {
   "name": "token-pilot",
-  "displayName": "Token Pilot",
-  "description": "Reduces token consumption by 60-80% via AST-aware lazy file reading. 18 MCP tools for structural code reading, symbol navigation, and cross-file search.",
-  "version": "0.13.0",
-  "author": "Digital-Threads",
-  "repository": "https://github.com/Digital-Threads/token-pilot",
-  "license": "MIT",
-  "keywords": ["mcp", "token", "ast", "code-reading", "optimization"],
-  "categories": ["developer-tools", "code-analysis"],
-  "installMethod": "plugin",
-  "requirements": {
-    "node": ">=18.0.0"
-  }
+  "owner": {
+    "name": "Digital-Threads",
+    "email": "shahinyanm@gmail.com"
+  },
+  "metadata": {
+    "description": "Token Pilot — save 60-90% tokens when AI reads code",
+    "version": "0.26.6"
+  },
+  "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.26.6",
+      "author": {
+        "name": "Digital-Threads"
+      },
+      "category": "development",
+      "keywords": [
+        "mcp",
+        "token",
+        "ast",
+        "code-reading",
+        "optimization",
+        "context-window",
+        "subagents"
+      ]
+    }
+  ]
 }

package/.claude-plugin/plugin.json

@@ -1,9 +1,27 @@
 {
   "name": "token-pilot",
-  "version": "0.24.2",
-  "description": "Enforcement layer for token-efficient AI coding: MCP-first hook with structural denial summaries, SessionStart reminder, bless-agents CLI, and six tp-* subagents — works for every agent including those without MCP access.",
-  "author": "token-pilot",
+  "version": "0.26.6",
+  "description": "Saves 60-90% tokens when AI reads code. AST-aware lazy reading, symbol navigation, cross-session tool-usage analytics, 19 subagents with budget watchdog.",
+  "author": {
+    "name": "Digital-Threads",
+    "url": "https://github.com/Digital-Threads"
+  },
+  "homepage": "https://github.com/Digital-Threads/token-pilot#readme",
+  "repository": "https://github.com/Digital-Threads/token-pilot",
   "license": "MIT",
-  "skills": "../skills",
-  "hooks": "./hooks"
+  "keywords": [
+    "mcp",
+    "token",
+    "ast",
+    "code-reading",
+    "context-window",
+    "subagents",
+    "optimization"
+  ],
+  "mcpServers": {
+    "token-pilot": {
+      "command": "sh",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/start.sh"]
+    }
+  }
 }

package/CHANGELOG.md

@@ -5,6 +5,185 @@ All notable changes to Token Pilot will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.6] - 2026-04-18
+
+### Fixed — EPIPE stacktrace when piping CLI to `head`/`less`/`grep`
+
+First field report after the plugin install worked: user ran
+`npx token-pilot doctor | head -5` and got a red "Unhandled 'error' event"
+stacktrace from node:events. Classic Node.js CLI wart — `console.log`
+tries to write after `head` closed stdin, EPIPE propagates, no handler,
+crash.
+
+Fixed by swallowing `EPIPE` on stdout and stderr at process start
+(`process.stdout.on('error', ...)`). Any CLI piped to `head | less | grep`
+should behave this way; ours now does.
+
+Confirmed: `node dist/index.js doctor | head -5` returns exit 0 with a
+clean truncated output, no stacktrace.
+
+## [0.26.5] - 2026-04-18
+
+### Fixed — plugin installation path was broken since 2026-03-01
+
+Surface: a user asked "can token-pilot be installed as a Claude Code plugin?". The `.claude-plugin/` manifest said yes, but attempting `claude plugin install token-pilot@token-pilot` against our repo failed on schema errors. Root cause: `marketplace.json` and `plugin.json` were written 2026-03-01 for the Claude Code schema as-of-then. The schema has since moved to a `owner`/`plugins`-array shape in `marketplace.json` and `author`-as-object in `plugin.json`, with `mcpServers` declared inside `plugin.json` itself. Our files never caught up. Every user who tried the plugin path for 48 days saw a validation error.
+
+Fixed: both manifests rewritten to current shape. Verified end-to-end — `claude plugin marketplace add <path> && claude plugin install token-pilot@token-pilot` now reports ✔ Successfully installed and the MCP server connects green.
+
+### Added — README documents both install paths
+
+Until now the README only described npm/npx. With plugin install fixed, the Claude Code section now lays out three paths side-by-side:
+- **A.** `claude plugin install` — hooks + MCP + (optional) tp-* agents in one step.
+- **B.** `claude mcp add -- npx -y token-pilot` — for npm-based setups.
+- **C.** `npx -y token-pilot init` — the one-liner that writes path B for you.
+
+### Changed — plugin-aware CLI behaviour
+
+- **`install-hook`** now early-returns with an explanation when `CLAUDE_PLUGIN_ROOT` is set. Plugin installation already wires hooks via `.claude-plugin/hooks/hooks.json`; calling `install-hook` on top would double-register every PreToolUse/PostToolUse matcher. This prevents the silent duplication.
+- **`install-agents`** keeps working under plugin mode (tp-* subagents are independent of plugin hooks — they live in `~/.claude/agents/` regardless) but now prints a one-line note so the user doesn't wonder why a plugin install needs a manual step. New regression test covers the plugin-mode path.
+- **`doctor`** prints a new `Install mode:` line — one of `plugin (<root>)` / `dev / worktree (contributor)` / `npm / npx`. Helps diagnose support issues: "why do I have two hook entries?" → doctor says `plugin` → answer is "remove the manual install-hook run".
+
+### Removed — repo-level `.mcp.json`
+
+The file at the repo root was a 2026-03 plugin-compat artifact using `${CLAUDE_PLUGIN_ROOT}/start.sh`. It only resolved correctly when token-pilot ran as a registered plugin — for anyone developing the repo locally (or running the MCP server from a worktree) it just produced `✗ Failed to connect` in `claude mcp list`. With plugin install fixed and the `mcpServers` block moved inside `plugin.json`, the file is no longer needed from either path. Removed.
+
+**Note for users migrating npm → plugin:** if you ran `npx token-pilot install-hook` on your old npm setup and then install as a plugin, both will register hooks — every PreToolUse matcher fires twice. Clean the manual entry out of `~/.claude/settings.json` (the one whose `command` starts with `token-pilot hook-read`). The v0.26.5 early-return only prevents *new* duplicates; it doesn't clean old ones.
+
+975 tests still passing (+1 new: plugin-mode regression).
+
+## [0.26.4] - 2026-04-18
+
+### Added — automatic profile recommendation in `doctor`
+
+v0.26.3 shipped profiles, but the default stayed `full` — a breaking default change would silently hide tools from anyone who actually uses `code_audit` / `test_summary` / `find_unused`. The correct path: **data-driven advisory, not default flip**.
+
+`npx token-pilot doctor` now reads the cumulative `.token-pilot/tool-calls.jsonl` (introduced v0.26.2) and prints a profile recommendation:
+
+```
+── profile recommendation ──
+  data:         30 calls, 1 distinct tools
+  recommend:    TOKEN_PILOT_PROFILE=nav
+  why:          Every tool you've used (1 distinct) is part of the nav subset. You're a read-only explorer.
+  savings:      ~2200 tokens (−54%) on every tools/list response
+  apply:        add "env": { "TOKEN_PILOT_PROFILE": "nav" } to your token-pilot entry in .mcp.json
+```
+
+Decision matrix (pure, unit-tested):
+- Every call ∈ nav-set → recommend `nav`.
+- Uses edit-prep tools (read_for_edit, batch reads) but never full-only → recommend `edit`.
+- Touches any full-only tool (test_summary, code_audit, find_unused, session_*) → stay on `full`.
+- <20 calls total → insufficient data, say so honestly, tell user to re-run doctor after a few sessions.
+
+**Never auto-applies.** Recommendation is printed, not written. Users who haven't read the CHANGELOG learn the lever exists next time they run `doctor`. Gives the narrowest profile that *doesn't silently break their workflow*, because the recommendation is based on their actual usage — not ours.
+
+11 unit tests on the decision matrix + formatter (min-samples boundary, all branches of the matrix, empty-input safety, env-snippet rendering).
+
+## [0.26.3] - 2026-04-18
+
+### Added — tool profiles (lifted honestly from Token Savior's idea)
+
+When an MCP server advertises 22 tools, every `tools/list` response costs the agent ~4 k tokens *before it does anything*. Most sessions don't need every tool — a code-review subagent uses `smart_read` + `find_usages` + `outline` and nothing else. A profile lets the operator ship a narrower `tools/list` while keeping every handler live (so a subagent that explicitly names a filtered-out tool still gets served — we just don't brag about every tool upfront).
+
+**Three profiles:**
+
+| Profile | Tools | ~Tokens in `tools/list` | When to use |
+|---------|------:|------------------------:|-------------|
+| `full` *(default)* | 22 | ~4 150 | All capabilities, same as pre-v0.26.3 |
+| `edit` | 16 | ~3 120 | Code-change workflows (nav + batch reads + read_for_edit) |
+| `nav` | 10 | ~1 910 | Read-only exploration (smart_read, outline, find_usages, project_overview, module_info, related_files, explore_area, smart_log, smart_diff, read_symbol) |
+
+**Savings:** `nav` saves ~2.2 k tokens (54 %) at session start; `edit` saves ~1 k (25 %). Every session pays this tax, so it compounds fast across a working day.
+
+**Selection:** set `TOKEN_PILOT_PROFILE=nav|edit|full` in the MCP server env block. Unknown values fall back to `full` with a stderr warning.
+
+**Containment invariant** (guarded by a unit test): `nav ⊂ edit ⊂ full`. A future tool added to `tool-definitions.ts` without updating a profile set ends up in `full` only — conservative by default, so we never accidentally hide a tool from everyone.
+
+11 unit tests (filter math, containment, unknown-value fallback, case-insensitivity, whitespace).
+
+### Noted for later — context-mode stewardship
+
+We currently integrate with [context-mode](https://github.com/mksglu/context-mode) only as a detector + advisor (suggest its `execute` tool when Bash stdout is large). If in a future release we don't deepen that integration, the dependency should be dropped — carrying a soft integration we don't leverage is exactly the kind of "not saving tokens, therefore a problem" the user mandate calls out. Tracked, not actioned this release.
+
+## [0.26.2] - 2026-04-18
+
+### Added — persistent per-tool savings data
+
+The user's mandate for Token Pilot is one thing: **"save the maximum number of tokens, all possible ways, no hacks, clean architecture"** — and the corollary, "if a tool doesn't save tokens, or saves poorly, drop it". Executing that mandate responsibly needs **data across many sessions**, not one Opus field report on a Go monorepo.
+
+Until v0.26.1 the MCP tool-call analytics lived entirely in memory (`SessionAnalytics`). The moment the MCP server restarted — every session end, every `/clear`, every laptop reboot — the per-tool distribution reset. Decisions about which tools pay off had no real baseline.
+
+**1. `src/core/tool-call-log.ts` — append-only JSONL log of every MCP tool call.** Schema matches the in-memory `ToolCall` minus runtime-only fields (intent, decisionTrace). Written from `recordWithTrace` fire-and-forget. Same rotation + retention contract as the existing `hook-events.jsonl` (10 MB rotation, 30-day age cap, 100 MB total size cap). Silent on disk errors — telemetry never blocks the tool-response path. 9 regression tests (roundtrip, JSONL tolerance, cross-session persistence, retention by age, retention by size).
+
+**2. `npx token-pilot tool-audit` — CLI that reads every log file + archive and emits a per-tool savings table.** Default human-readable output, `--json` for scripts. Flags a tool as "low-value" when reduction <20% *across ≥5 calls* — the min-samples gate exists so one bad session doesn't get a tool removed. Output is sorted by total tokens saved so your biggest contributor sits on top. 10 unit tests covering aggregation math, sorting, flagging threshold, JSON shape, empty-dataset message.
+
+What this unlocks (not in this release, but the foundation is now in place):
+- Real prune decisions: "after 50 sessions, `X` saves <5% on average → remove or restrict".
+- CI savings-regression gate: `tool-audit --fail-below=20` on a baseline.
+- Tool description tuning: compare `smart_read`'s cumulative reduction to `read_symbol` — whichever consistently wins, describe more aggressively.
+
+No behavioural change to existing tools — this is strictly observation infrastructure.
+
+## [0.26.1] - 2026-04-18
+
+### Fixed — savings accounting regressions from Opus 4.7 field report
+
+The single mandate from the user: **"if a tool doesn't save tokens, or saves poorly, it's a real problem"**. Two tools on Opus 4.7's 19/19 verification reported poor savings that turned out to be accounting/dedupe bugs, not tool failures. Fixing them instead of removing them.
+
+**1. `read_symbols` overlap dedupe (15% → 40-60% savings).** The ast-index parser resolves two distinct requested symbols to the same line range on arrow-function exports, Vue SFCs, and type-vs-function ambiguity. Before this fix the handler emitted the body N× — a 4× token blow-up on the field-report file (`nuxt/composables/useCart.ts`). Now the handler keys sections by `startLine:endLine` and emits a short dedupe note instead of repeating the source. Caller still sees which names they asked for; the header advertises the savings (`DEDUPED: N (parser overlap — saved ~N× body tokens)`). Two regression tests.
+
+**2. `smart_read` small-file pass-through no longer reports -2% "negative savings".** When `smart_read` returns a file ≤`smallFileThreshold` (200 lines) verbatim with a tiny header, it's not compressing anything — but the recorder was still setting `wouldBe = fullFile`, making the header's 1-2% overhead show up as *negative* savings on `session_analytics`'s Needs-improvement line. New `detectSavingsCategoryPure('none')` branch classifies these calls honestly; server zeroes `wouldBe = returned` → 0% savings claimed, no ghost overhead. Six unit tests on the classifier.
+
+### Not shipped (on purpose)
+
+Per advisor guidance, we held off on three things that looked tempting but lack data:
+- **Server-side `find_usages` short-symbol fallback.** We just shipped a description hint in v0.26.0. Measure whether agents follow the hint before writing speculative server code.
+- **Removing any tool based on one session of data.** Opus on a Go monorepo ≠ average usage. Needs persistent per-tool stats across sessions first.
+- **CI savings-regression gate.** Premature without a cumulative baseline.
+
+The next iteration will build the persistent `.token-pilot/tool-calls.jsonl` + `npx token-pilot tool-audit` CLI so future prune/fix decisions are data-backed, not anecdotal.
+
+## [0.26.0] - 2026-04-18
+
+### Added — cross-client honesty
+
+**1. `install-agents` detects non-Claude clients and skips silently.** Until this release, running `npx token-pilot install-agents` in Cursor / Codex CLI / Gemini CLI / Cline silently created a `~/.claude/agents/` directory that nothing in those clients would ever read. `tp-*` subagents are a Claude Code concept — other clients still benefit from MCP tools + Read hook, but the 19 delegates sit idle. New detector (`src/cli/detect-client.ts`) checks env vars (`CURSOR_TRACE_ID`, `GEMINI_CLI`, `OPENAI_CODEX`, `CLAUDE_PLUGIN_ROOT`) and on-disk markers (`~/.claude/`, `~/.cursor/`, `~/.codex/`, `~/.gemini/`). When a non-Claude client is detected and `--scope` is not passed, install-agents prints a clear warning and exits 0 without touching disk. Explicit `--scope=user|project` overrides (multi-client setups). 10 detector unit tests + 3 integration tests.
+
+**2. README: client support matrix.** Honest table showing what works where — MCP tools ✅ everywhere, subagents + `model:` frontmatter + budget watchdog Claude Code only. Non-Claude users get ~60% of the package. Fixes the implicit "works with all clients" promise that was hiding a real gap.
+
+### Improved
+
+**3. `tp-dead-code-finder` project-type detection.** Field report showed this agent running 128 `find_usages` iterations over 145s on a Go project — because it defaulted to MCP-based scanning even when native tools (`go vet + deadcode`, `phpstan --level=max`, `vulture`, `ts-prune`) would do the same job in one Bash call. Agent body now instructs the first pass through the right native analyzer based on project markers (`go.mod`, `composer.json`, `pyproject.toml`, `package.json`). `find_unused` is the fallback, not the default. Budget discipline: ≥40 candidates → report top-20 with confidence, not iterate.
+
+**4. `find_usages` tool description: Grep hint for short symbols.** Semantic find is great for specific symbol names, but wastes tokens when the symbol is ≤4 chars and generic (`id`, `err`, `Cmd`, `db`) — resolves ambiguously across thousands of files, Grep is cheaper. Description now says so explicitly.
+
+### Deferred to a later epic
+
+- **Auto session-snapshot writer on `PreCompact` / `Stop` hook events.** Claude Code does not expose these events to external hooks today — needs either an upstream feature request or a polling alternative. Tracked as research, not shipped.
+- **Cross-client equivalents of `tp-*` subagents.** Cursor Custom Rules (`.cursor/rules/*.mdc`), Gemini `GEMINI.md`, Codex system prompts — can we generate equivalent guidance from our templates? Separate design doc, not v0.26.
+
+## [0.25.0] - 2026-04-18
+
+### Fixed — findings from Opus 4.7 19/19 verification
+
+A live verification of all 19 agents on a real Go monorepo surfaced three issues. Fixed together.
+
+**1. `install-agents` / installer: PostToolUse idempotence was broken for upgrades.** The check treated the whole PostToolUse section as one unit — *"any token-pilot hook present → skip"*. Users who installed when only the Bash matcher existed (v0.21.x) kept that, never received the Task matcher added in v0.23.0, and their budget watchdog was **silently disabled forever**. 6 out of 19 agents in the field test went over-budget without a single entry in `.token-pilot/over-budget.log` — because the hook wasn't registered at all. Now installer checks each PostToolUse matcher individually (same contract as PreToolUse). Regression test reproduces the v0.21-style settings file and asserts that re-install picks up the Task matcher.
+
+**2. `tp-api-surface-tracker` false REMOVED classification.** Field test: `smart_diff` labelled a symbol as REMOVED; `read_symbol` confirmed it was still there (context around it had changed). Agent body now **requires `read_symbol` verification before reporting REMOVED**. Symbols that still exist are reclassified PATCH (body-only change). Prevents false breaking-change alarms in the MAJOR/MINOR/PATCH verdict.
+
+**3. `tp-dep-health` over-scans monorepo orchestration roots.** When the root `package.json` has only dev-deps and real services live in gitignored sub-repos or under `services/`/`packages/`/`apps/`, the agent used to scan the whole repo for nothing. Agent now detects this shape and returns a one-line instruction to re-run against a specific sub-repo, instead of iterating find_usages on zero-dep input.
+
+### Deferred to v0.26
+
+From the same report, larger changes that need design:
+
+- **`tp-dead-code-finder` project-type detection.** 128 `find_usages` iterations in 145 s when `find_unused` is permission-denied in sandbox. Needs Go → `go vet` + `deadcode`, PHP → phpstan, etc. integration.
+- **Auto-invoke `session_snapshot` on Stop / Pre-Compact hook.** `tp-session-restorer` is dead without a paired writer — right now the snapshot file is only created on explicit user call. Needs a hook-type evaluation (Stop hook doesn't exist in Claude Code's current hook set; may need a Pre-Compact substitute).
+- **`find_usages` → Grep fallback for single-word symbols.** 0 % savings observed when symbols are short (structural overview is already longer than the hit list).
+
+### Numbers
+- 912 tests green (+1 regression for installer's per-matcher idempotence), `tsc --noEmit` clean.
+
 ## [0.24.2] - 2026-04-18
 
 ### Changed — README manual-install section restored and expanded

package/README.md

@@ -44,7 +44,31 @@ This does two things:
 1. Creates (or merges into) `.mcp.json` with `token-pilot` + [`context-mode`](https://github.com/mksglu/claude-context-mode).
 2. If you're on a TTY, asks whether to install the `tp-*` subagents now — pick `user` (available in every project) or `project` scope.
 
-Restart your AI assistant to activate. The Read hook auto-installs the first time `token-pilot` starts inside Claude Code. Works with **Claude Code, Cursor, Codex, Antigravity, Cline**, and any MCP-compatible client.
+Restart your AI assistant to activate. The Read hook auto-installs the first time `token-pilot` starts inside Claude Code. Works with **Claude Code, Cursor, Codex, Antigravity, Cline**, and any MCP-compatible client — though support varies (see matrix below).
+
+## Client support matrix
+
+Not every capability works in every client. Subagents are a Claude Code concept; other clients still get the MCP tools + Read hook but won't auto-invoke `tp-*` agents.
+
+| Client          | MCP tools | Read hook (context-mode) | `tp-*` subagents (19) | `model:` frontmatter (haiku) | Budget watchdog |
+|-----------------|:---------:|:------------------------:|:---------------------:|:----------------------------:|:---------------:|
+| Claude Code     | ✅        | ✅                       | ✅                    | ✅                           | ✅              |
+| Cursor          | ✅        | ✅                       | ❌                    | ❌ (ignored)                 | ❌              |
+| Codex CLI       | ✅        | ✅                       | ❌                    | ❌                           | ❌              |
+| Gemini CLI      | ✅        | ✅                       | ❌                    | ❌                           | ❌              |
+| Cline (VS Code) | ✅        | ✅                       | ❌                    | ❌                           | ❌              |
+| Antigravity     | ✅        | ✅                       | ❌                    | ❌                           | ❌              |
+
+**What non-Claude users get (~60% of the package):**
+- All 22 MCP tools: `smart_read`, `read_symbol`, `find_usages`, `smart_diff`, `code_audit`, `session_analytics`, etc.
+- The Read hook that blocks oversized reads and suggests token-saving alternatives.
+
+**What needs Claude Code to work:**
+- 19 `tp-*` subagents invoked via the `Task` tool.
+- `model: claude-haiku-4-5` frontmatter on format-bound agents (commit-writer, session-restorer, onboard) — cheaper runs.
+- `PostToolUse:Task` budget watchdog — logs agent runs exceeding their declared budget to `.token-pilot/over-budget.log`.
+
+`install-agents` detects non-Claude clients via env vars + filesystem markers (`CURSOR_TRACE_ID`, `~/.codex/`, `~/.gemini/`, etc.) and **skips installing** unless you pass `--scope=user|project` explicitly.
 
 ## Manual MCP install (per-client examples)
 
@@ -52,10 +76,20 @@ If `init` isn't right for your setup — CI, non-TTY environments, editing a sha
 
 ### Claude Code
 
-Two equivalent paths:
+Three paths — pick one, they're mutually exclusive.
+
+**A. As a Claude Code plugin (one-step install — hooks + MCP registered together):**
+
+```bash
+claude plugin marketplace add https://github.com/Digital-Threads/token-pilot
+claude plugin install token-pilot@token-pilot
+```
+
+Claude Code clones the repo into `~/.claude/plugins/cache/token-pilot/`, sets `CLAUDE_PLUGIN_ROOT`, and registers the MCP server + all hooks declared in `.claude-plugin/hooks/hooks.json`. No `install-hook` call needed. `install-agents` still applies for the tp-* subagents (they're separate from plugin hooks).
+
+**B. Via MCP config (npm-based, no plugin system):**
 
 ```bash
-# Via CLI (recommended — handles scope + scoping)
 claude mcp add token-pilot -- npx -y token-pilot
 claude mcp add --scope user token-pilot -- npx -y token-pilot
 claude mcp add --scope project token-pilot -- npx -y token-pilot
@@ -72,6 +106,10 @@ claude mcp add --scope project token-pilot -- npx -y token-pilot
 }
 ```
 
+Then `npx token-pilot install-hook` to register the PreToolUse Read/Edit hooks and `npx token-pilot install-agents --scope=user` to install the 19 tp-* subagents.
+
+**C. One-liner `init`:** `npx -y token-pilot init` — writes path B config for you, then prompts about subagents.
+
 ### Cursor
 
 Cursor reads `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
@@ -119,11 +157,22 @@ No env vars required. Optional overrides:
 
 | Env var | Default | Purpose |
 |---|---|---|
+| `TOKEN_PILOT_PROFILE` | `full` | `nav`/`edit`/`full` — trims the advertised `tools/list` payload to save ~2 k tokens per session (see "Tool profiles" below) |
 | `TOKEN_PILOT_DENY_THRESHOLD` | `300` | Line count above which the Read hook intervenes |
 | `TOKEN_PILOT_ADAPTIVE_THRESHOLD` | `false` | Enable the adaptive curve as the session burns |
 | `TOKEN_PILOT_BYPASS` | unset | Set to `1` to disable the Read hook for one session |
 | `TOKEN_PILOT_SKIP_POSTINSTALL` | unset | Skip the `ast-index` safety-net install at `npm install` time |
 
+### Tool profiles
+
+| Profile | Tools | ~Tokens | Use when |
+|---------|------:|--------:|----------|
+| `full` *(default)* | 22 | ~4 150 | All capabilities |
+| `edit` | 16 | ~3 120 | Code-change workflows (nav + batch reads + `read_for_edit`) |
+| `nav` | 10 | ~1 910 | Read-only exploration / subagents that only navigate |
+
+Set via `TOKEN_PILOT_PROFILE` in your MCP server env block. Handlers stay live regardless — a subagent that explicitly names a filtered-out tool still gets served. The profile only trims what we advertise in `tools/list` at session start.
+
 ### Subagents (Claude Code only)
 
 `tp-*` subagents are a Claude Code feature. Other clients use only the MCP tools + Read hook. To install on a target scope explicitly:
@@ -255,6 +304,8 @@ token-pilot install-hook           # Install PreToolUse hook
 token-pilot uninstall-hook
 token-pilot stats                  # Totals + top files from hook-events.jsonl
 token-pilot stats --session[=<id>] | --by-agent
+token-pilot tool-audit             # Per-tool savings distribution (cumulative across sessions)
+token-pilot tool-audit --json      # Same, machine-readable
 token-pilot doctor                 # Diagnostics (ast-index, config, upstream drift)
 token-pilot install-ast-index      # Download ast-index binary (auto on first run)
 ```

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

@@ -8,8 +8,8 @@ tools:
   - mcp__token-pilot__smart_diff
   - mcp__token-pilot__read_symbol
   - Bash
-token_pilot_version: "0.24.2"
-token_pilot_body_hash: 1ab0a379cfa6cf59c908be61c573ba208c0a8c47d7712bc5341c3600dd49ac3c
+token_pilot_version: "0.26.6"
+token_pilot_body_hash: f30fb3378463d6518041650487f1074b5411c6c3d6d7df315d21267f25f812d6
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -29,7 +29,8 @@ When asked to audit API surface change:
 1. Find public surface HEAD: `outline` each file named by the project's exports entry (main/module/exports in package.json, or `index.*` / `mod.*`). Collect { name, signature, visibility=public } for every symbol.
 2. Walk git back to the comparison point (argued by user, else last release tag found via `git describe --tags --abbrev=0`). Use `smart_log --since=<tag>` to scope; `git worktree` or `git show <tag>:<file>` via Bash to reconstruct past outline.
 3. For each symbol present in only one side:
-   - Removed → **MAJOR** (breaking)
+   - **Always verify REMOVED with `read_symbol` on HEAD before reporting.** `smart_diff` can mis-label a symbol as REMOVED when only its surrounding context changed — a short confirmation read prevents false breaking-change alarms. If the symbol is still there, reclassify as PATCH (body-only change).
+   - Removed (verified) → **MAJOR** (breaking)
    - Added → **MINOR** (backward-compatible)
 4. For symbols present on both sides, `read_symbol` current + `git show <tag>:<file>` past. Compare signatures:
    - Parameter added without default → **MAJOR**

package/dist/agents/tp-audit-scanner.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__read_section
   - Grep
   - Read
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
 ---
 

package/dist/agents/tp-commit-writer.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 559a0b61d20974bf33e35bc4c80dcf1b41d10d4df46cf9d05d3d5620713cd46f
 ---
 

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

@@ -1,16 +1,17 @@
 ---
 name: tp-dead-code-finder
-description: Use this when the user asks to find or remove dead / unused code ("clean up this file", "find unused exports", "pre-release cleanup"). Cross-checks find_unused with Grep, git history, and dynamic-lookup patterns before classifying. Output-only — NEVER deletes code itself.
+description: Use this when the user asks to find or remove dead / unused code ("clean up this file", "find unused exports", "pre-release cleanup"). Picks the fastest per-language analyzer first (go vet/deadcode, phpstan, vulture, ts-prune), falls back to find_unused + find_usages cross-check. Output-only — NEVER deletes code itself.
 tools:
   - mcp__token-pilot__find_unused
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__smart_log
   - mcp__token-pilot__outline
   - mcp__token-pilot__related_files
+  - Bash
   - Grep
   - Read
-token_pilot_version: "0.24.2"
-token_pilot_body_hash: 482e33ba566dc75d87753d980267fb2e01763e5924612efd54ec89993b5e12fd
+token_pilot_version: "0.26.6"
+token_pilot_body_hash: 33798b70002a206c4547d08ff46caefe6dbe5a9300f94ab5dad4a57ab5fb4478
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -25,15 +26,29 @@ Role: safe dead-code detection.
 
 Response budget: ~600 tokens.
 
-When asked to find unused code:
+## Project-type detection (DO THIS FIRST)
 
-1. Start with `find_unused` — treat its output as a candidate list, not a verdict.
-2. For each candidate, re-verify with `find_usages` across the whole repo (including tests/fixtures/docs). Reflection, dynamic imports, string-based routing, DI containers — `find_unused` misses these; Grep the symbol name as a string as a backstop.
+Before touching `find_unused` (which does per-symbol scans and can balloon to 100+ tool calls on large repos), pick the cheapest **native** analyzer for the project. Run ONE detection Bash call:
+
+- `go.mod` present → Go. Use `go vet ./...` + `deadcode ./...` (install: `go install golang.org/x/tools/cmd/deadcode@latest`). 1 Bash call instead of N.
+- `composer.json` with `phpstan` dep → PHP. Use `vendor/bin/phpstan analyse --level=max` with `unusedElements: true`.
+- `pyproject.toml` / `requirements.txt` → Python. Try `vulture .` (install: `pip install vulture --user`). Reports unused code with confidence %.
+- `package.json` with TypeScript → TS. Try `npx -y ts-prune` (exports-only) or `knip` if configured (broader).
+- None of the above, or analyzer unavailable → fall back to `find_unused`.
+
+If the native analyzer works, use its output as the **candidate list** and still cross-check with `find_usages` / Grep (see below) before promoting to "safe to remove". Native tools have false-positives too (reflection, DI, string-based routing).
+
+## Verification pipeline (always runs)
+
+1. Build candidate list (native analyzer or `find_unused`).
+2. For each candidate, re-verify with `find_usages` across the whole repo (including tests/fixtures/docs). Reflection, dynamic imports, string-based routing, DI containers — analyzers miss these; Grep the symbol name as a string as a backstop.
 3. `smart_log` each candidate's file — symbols added within the last 2 weeks are often mid-feature, not dead. Flag, don't delete.
 4. Group by confidence: **safe to remove** (zero refs, old, no dynamic-lookup risk), **probably safe** (needs human glance), **unsafe** (dynamic-lookup / recent / test-only survivor).
 5. Deliver: checklist grouped by confidence, each entry as `path:line — symbol — reason for classification`. Do NOT delete anything.
 
-Do NOT delete code in this agent — output the list, let the user act. Do NOT rely on `find_unused` alone for the safe bucket. Confidence threshold: "safe to remove" bucket requires BOTH empty `find_usages` AND empty Grep of the name as a string.
+Do NOT delete code in this agent — output the list, let the user act. Do NOT rely on analyzer output alone for the "safe" bucket. Confidence threshold: "safe to remove" requires ALL of: empty `find_usages`, empty Grep-as-string, file older than 2 weeks.
+
+Budget discipline: if the candidate list exceeds 40 items, report the top-20 with highest confidence + one-line summary of the rest. Do not iterate `find_usages` 100+ times.
 
 RESPONSE CONTRACT:
 - Lead with a one-line verdict.

package/dist/agents/tp-debugger.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
   - Bash
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 04864ae0bf0689863d7de9f4c0b44b293087b34098ad2771837e491d37dab953
 ---
 

package/dist/agents/tp-dep-health.md

@@ -8,8 +8,8 @@ tools:
   - mcp__token-pilot__find_unused
   - Bash
   - Read
-token_pilot_version: "0.24.2"
-token_pilot_body_hash: abf5f78b2d55e4611eb1cdde75d604993071f14ac7b5cd6b51ecd5cc1beddc38
+token_pilot_version: "0.26.6"
+token_pilot_body_hash: 6224d989835ea284985b474005b8b46052b7007c4610e661b10658286b5c6624
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -27,6 +27,7 @@ Response budget: ~600 tokens.
 When asked to audit dependencies:
 
 1. Enumerate deps: `Read package.json` / `pnpm-lock.yaml` / `requirements.txt` / `Gemfile` / `Cargo.toml` — whichever the project uses. One-line summary of counts (prod / dev).
+   - **Monorepo orchestration root detection:** if the root manifest has only dev dependencies (or only workspace pointers) AND the real source lives in sub-repos (gitignored or under `services/`, `packages/`, `apps/`), STOP. Return: "This is a monorepo root with no production deps of its own — re-run this agent pointing at `<sub-repo>` via Task(subagent_type=tp-dep-health) per service". Do not scan further.
 2. Run the native outdated check: `npm outdated --json` (or pip list --outdated, etc.) via Bash. Parse into `{pkg, current, latest, major|minor|patch}`.
 3. For each outdated package, count actual IMPORTS across source: `find_usages` on the package name (or Grep `from "pkg"` / `require("pkg")` for non-JS). Zero = candidate for removal; many = priority upgrade.
 4. For high-usage stale deps, `smart_log -- <sample source file>` touching the import to see when the usage last moved — stale dep + stale integration = low risk; stale dep + active integration = urgent.

package/dist/agents/tp-history-explorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__outline
   - Bash
   - Read
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: b2daca007e959eaf26bf9a4d92ba36c3aa277a51de4ca4db674833d36acbe11b
 ---
 

package/dist/agents/tp-impact-analyzer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_symbols
   - Read
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 0be2620ce0303f912f6b3334f261d169f064970c0d16602fa1e76db4cb2ea441
 ---
 

package/dist/agents/tp-incident-timeline.md

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
   - Bash
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 420ffc423c7479a8d4e1b226cf73eb98d6d41388317c74a950d7f3b6240b6786
 ---
 

package/dist/agents/tp-migration-scout.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - Grep
   - Glob
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: cf32cdee777430ecc6732db32b3f883a685c8a02b6dc93379d71b15555e79b3e
 ---
 

package/dist/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.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
 ---
 

package/dist/agents/tp-pr-reviewer.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_for_edit
   - Read
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: eb9fb7f87d9ab61c5b18248a40b283008b5d73414ddb2e3094ff0826e7e463d0
 ---
 

package/dist/agents/tp-refactor-planner.md

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__read_diff
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
 ---
 

package/dist/agents/tp-review-impact.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__module_info
   - Bash
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 72b635f511492188587d6cb6fd70f936ae34cf5df1f9cd9eff7849cf1231e185
 ---
 

package/dist/agents/tp-run.md

@@ -15,7 +15,7 @@ tools:
   - Grep
   - Glob
   - Bash
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

package/dist/agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
 ---
 

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

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: cc3d1f46fdb95ac3caf9344f69f1ddcd5ce5a175ee70aa150b7f9fda93edb152
 ---
 

package/dist/agents/tp-test-triage.md

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__read_range
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
-token_pilot_version: "0.24.2"
+token_pilot_version: "0.26.6"
 token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
 ---