token-pilot 0.22.2 → 0.23.1

package/.claude-plugin/hooks/hooks.json

@@ -39,6 +39,15 @@
             "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-bash"
           }
         ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-post-task"
+          }
+        ]
       }
     ]
   }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "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",
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.23.1] - 2026-04-18
+
+### Changed — agent toolset coverage
+
+Audit of all 14 agents vs 22 MCP tools surfaced 6 unused tools — 3 of those were genuine efficiency leaks (agents used scalar calls where batch was available). Fixed:
+
+- **`read_symbols`** (batch read of N symbols in one file) — now in `tp-pr-reviewer` + `tp-impact-analyzer`. Previously both ran `read_symbol` in a loop for changed diffs.
+- **`read_section`** (headed-section read for MD/YAML/JSON) — now in `tp-onboard` + `tp-audit-scanner` + `tp-session-restorer`. Previously `smart_read` pulled whole README / policy files when only one section was needed.
+- **`smart_read_many`** (batch read of N files) — now in `tp-pr-reviewer` + `tp-migration-scout` + `tp-impact-analyzer` + `tp-onboard`. Previously loops of `smart_read` across the touched file set.
+- **`session_budget`** — now in `tp-session-restorer`, included in the restored briefing so a resumed session knows its burn fraction + time-to-compact projection immediately.
+
+Each agent's numbered steps were updated with an explicit instruction to prefer the batch tool over a loop. Preambles unchanged.
+
+**Remaining "unused by tp-*" tools (by design):**
+- `session_snapshot` — called by the main Claude Code agent at turn boundaries, not by subagents.
+- `session_analytics` — user-facing summary tool invoked via `/ask token-pilot:session_analytics`, not subagent surface.
+
+### Numbers
+- 904 tests green (+0 new — existing parity tests catch frontmatter changes automatically), `tsc --noEmit` clean.
+
+## [0.23.0] - 2026-04-18
+
+### Added — three more specialist agents (TP-02l follow-up)
+
+Closes the gap between the shipped TP-02l set and the originally-scoped one. Total roster now: **14 agents** (6 Tier 1 + 8 Tier 2).
+
+- **`tp-history-explorer`** — answers "why is this like this?" by tracing git for a symbol. Returns the minimum commit chain that explains current state, not the full log. Refuses to theorise beyond what commit messages say (no "author likely wanted X" hallucinations).
+- **`tp-audit-scanner`** — read-only security + quality scan. Grep patterns for hardcoded secrets, injection shapes, unsafe casts; cross-checked by reading the enclosing symbol before classifying. Outputs Critical / Important / Minor; never edits; never quotes secrets in findings.
+- **`tp-session-restorer`** — rehydrates state after `/clear` / compaction. Reads `.token-pilot/snapshots/latest.md`, git status, saved docs list; returns a ≤200-token briefing in a fixed shape. Refuses to infer next steps the snapshot didn't record.
+
+### Added — subagent budget enforcement (TP-q33 part a)
+
+Every `tp-*` agent declares `Response budget: ~N tokens` in its preamble. Until now, nothing enforced it.
+
+- **`PostToolUse:Task` hook** — after a subagent returns, reads its frontmatter budget, counts tokens in the response (chars/4 heuristic), logs any over-run beyond 10 % tolerance to `.token-pilot/over-budget.log` as JSONL. Silent on every failure; telemetry must never break the agent loop.
+- **Log schema:** `{ ts, agent, budget, actualTokens, overByRatio }`.
+- **Scope:** only `tp-*` subagents — third-party `acc-*`, `feature-dev:*`, etc. are ignored (we only enforce contracts we own).
+- **Zero API cost** — pure post-response analysis. Live-test-harness half (TP-q33 part b) still deferred; requires `ANTHROPIC_API_KEY`.
+
+### Changed
+
+- `.claude-plugin/hooks/hooks.json` and the installer now register a `PostToolUse:Task` matcher alongside the existing `Bash` matcher. Idempotent install; uninstall removes both.
+- `typo-guard` KNOWN_COMMANDS expanded to include `hook-post-task`.
+
+### Numbers
+- 904 tests green (+14 post-task budget tests), `tsc --noEmit` clean.
+
+## [0.22.3] - 2026-04-18
+
+### Fixed
+
+- **CLI typo guard** — mis-typed commands like `npx token-pilot install-aents` (missing `g`) used to silently become a `projectRoot=install-aents` MCP server launch and create stray `install-aents/.claude/settings.json` directories. Now the CLI detects command-shaped first args that aren't in the allow-list and aren't valid paths, prints `[token-pilot] Unknown command "install-aents". Did you mean "install-agents"?` on stderr, and exits non-zero. Levenshtein-based suggestion with a distance cap of 3.
+
+### Numbers
+- 890 tests green (+9 typo-guard regression tests), `tsc --noEmit` clean.
+
 ## [0.22.2] - 2026-04-18
 
 ### Fixed

package/README.md

@@ -121,6 +121,11 @@ Claude Code subagents guarantee MCP-first behaviour with tight response budgets
 | `tp-test-writer` | Write tests for ONE symbol, mirrors project style, runs tests | 900 |
 | `tp-dead-code-finder` | Cross-checked dead-code detection, output-only (never deletes) | 600 |
 | `tp-commit-writer` | Draft Conventional-Commit from staged diff; refuses failing tests | 400 |
+| `tp-history-explorer` | "Why is this like this?" — minimum commit chain explaining current state | 600 |
+| `tp-audit-scanner` | Read-only security / quality audit; Critical / Important / Minor findings | 800 |
+| `tp-session-restorer` | Rehydrate state after /clear or compaction from latest snapshot | 400 |
+
+Every agent's budget is enforced post-response — overshoots beyond 10 % land in `.token-pilot/over-budget.log`.
 
 `init` offers to install these; to do it later or add them to another project, run `npx token-pilot install-agents`. Remove with `npx token-pilot uninstall-agents --scope=user|project`.
 
@@ -220,14 +225,33 @@ Drop `.token-pilot.json` in your project root. All fields optional.
 | `cache.maxSizeMB` | `100` | File cache ceiling (LRU eviction) |
 | `policies.maxFullFileReads` | `10` | Warn after N full-file reads in session |
 
-## Integration with context-mode
+## Ecosystem
+
+Token Pilot sits in a small toolkit of three orthogonal pieces. Each has a single job; none overlaps with another.
+
+```
+Agent
+  ├─ Read code file          → smart_read / read_symbol    (Token Pilot MCP)
+  │                               └→ ast-index              (structural backend)
+  ├─ Need a fresh Read?      → force: true                  (Token Pilot MCP)
+  ├─ Run code / inspect logs → execute                      (context-mode MCP)
+  └─ Bash agent, no MCP?     → ast-index <subcmd>           (CLI binary)
+```
+
+| Tool | Role | When it fires |
+|------|------|---------------|
+| **[Token Pilot](.)** | Enforcement layer — Read hook, MCP structural reads, dedup, snapshots, subagents | Every code Read / Edit / session |
+| **[ast-index](https://github.com/defendend/Claude-ast-index-search)** | Structural indexer. Symbols, usages, hierarchy. Used by Token Pilot under the hood; also a standalone CLI for bash-only agents. | Auto-installed by Token Pilot; CLI available as `ast-index` |
+| **[context-mode](https://github.com/mksglu/claude-context-mode)** | Sandbox executor — runs shell / python / js, only stdout enters the window. Orthogonal: not for reading source. | Large `Bash` outputs, `execute(language, code)` calls |
 
-Token Pilot is complementary to [claude-context-mode](https://github.com/mksglu/claude-context-mode):
+**Rules of thumb:**
 
-- **Token Pilot** — code files (AST structure, symbols, imports)
-- **context-mode** — non-code data (shell output, logs, JSON dumps) via sandbox + BM25
+- Read code → Token Pilot `smart_read` / `read_symbol` (automatic via hook or MCP).
+- Execute code that produces big output → context-mode `execute`.
+- Bash agent or pre-flight shell command → `ast-index` CLI directly.
+- Never all three in `CLAUDE.md` — Token Pilot's `doctor` warns when `CLAUDE.md` exceeds 60 lines for this reason.
 
-`init` sets up both; they don't overlap. If context-mode is unavailable, Token Pilot works standalone.
+`npx token-pilot init` wires Token Pilot + context-mode into `.mcp.json`; ast-index installs on first run. If any single tool is missing, the other two still work standalone.
 
 ## Supported Languages
 

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

@@ -0,0 +1,50 @@
+---
+name: tp-audit-scanner
+description: Read-only security + quality scan — hardcoded secrets, SQL/command injection shapes, unsafe-cast patterns, deprecated APIs, stale TODOs with missing owners. Reports by severity, never edits. Use for audits / pre-release sweeps, not for writing the fix.
+tools:
+  - mcp__token-pilot__code_audit
+  - mcp__token-pilot__find_usages
+  - mcp__token-pilot__smart_read
+  - mcp__token-pilot__read_for_edit
+  - mcp__token-pilot__outline
+  - mcp__token-pilot__read_section
+  - Grep
+  - Read
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
+---
+
+You are a token-pilot agent (`tp-<name>`). Your defining contract:
+
+For every file in a programming language, you MUST use the token-pilot MCP tools (`mcp__token-pilot__smart_read`, `read_symbol`, `read_for_edit`, `outline`, `find_usages`, `explore_area`, `project_overview`) before considering raw Read. Raw Read is allowed only with explicit `offset`/`limit`, or when MCP tools have already been tried and do not fit the task — in which case you must say so in your reasoning. Never dump a file's full contents unless absolutely necessary.
+
+If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
+
+Your specific role is defined below.
+
+Role: audit scanner — surfaces risks, never fixes.
+
+Response budget: ~800 tokens.
+
+When asked to audit a file / module / whole repo:
+
+1. Start with `code_audit` — cheap first pass for TODO/FIXME/XXX with author + age metadata. Flag items older than 90 days or missing an owner. For config / policy files (`.env.example`, YAML, JSON), `read_section` by key — NOT whole-file `smart_read`.
+2. For each high-risk concern, Grep the precise pattern across scope:
+   - Secrets: `(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{8,}` + `AKIA[0-9A-Z]{16}` + `-----BEGIN.*PRIVATE KEY-----`
+   - Injection shapes: raw string concat into `exec`/`query`/`eval`/`Function(`, shell metachars in `spawn`/`system`
+   - Unsafe casts: `as any`, `# type: ignore`, `@ts-ignore`, `unchecked Cast`
+3. For each hit, `read_for_edit` the enclosing symbol to confirm it's a real vulnerability vs a test fixture / documented exception. False positives are worse than silence here.
+4. Classify every finding:
+   - **Critical:** live credentials, active injection vector, RCE-shape code on user input
+   - **Important:** deprecated API with migration path known, unsafe cast in critical path, stale TODO > 180 days
+   - **Minor:** style, consistency, obsolete comment
+5. Deliver: per severity, `path:line — one-line risk description → one-line remediation hint`. End with a summary count per severity. Do NOT include findings you couldn't confirm by reading the enclosing symbol.
+
+Do NOT edit code. Do NOT quote secrets you find in the output (say `redacted`). Do NOT report low-confidence pattern matches as Critical — when unsure, Important. Confidence threshold: Critical requires a reading of the enclosing function confirming the data flow.
+
+RESPONSE CONTRACT:
+- Lead with a one-line verdict.
+- Use bold section headers; one finding per bullet.
+- Reference code as `path:line`; paste source only if your role requires a patch.
+- Do NOT narrate tool calls. Do NOT preamble with "what was done well".
+- If findings exceed your budget, write overflow to `.token-pilot/<agent>-<timestamp>.md` and reference it; keep the visible response within budget.

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

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.1"
 token_pilot_body_hash: 559a0b61d20974bf33e35bc4c80dcf1b41d10d4df46cf9d05d3d5620713cd46f
 ---
 

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

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__related_files
   - Grep
   - Read
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.1"
 token_pilot_body_hash: 482e33ba566dc75d87753d980267fb2e01763e5924612efd54ec89993b5e12fd
 ---
 

package/dist/agents/tp-debugger.md

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

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

@@ -0,0 +1,43 @@
+---
+name: tp-history-explorer
+description: Answers "why is this like this?" by tracing git history for a file / symbol / regression. Returns the minimum commit chain that explains the current state, not the full log. Use when the question is about origin or intent, not about current behaviour.
+tools:
+  - mcp__token-pilot__smart_log
+  - mcp__token-pilot__smart_diff
+  - mcp__token-pilot__read_symbol
+  - mcp__token-pilot__find_usages
+  - mcp__token-pilot__outline
+  - Bash
+  - Read
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: b2daca007e959eaf26bf9a4d92ba36c3aa277a51de4ca4db674833d36acbe11b
+---
+
+You are a token-pilot agent (`tp-<name>`). Your defining contract:
+
+For every file in a programming language, you MUST use the token-pilot MCP tools (`mcp__token-pilot__smart_read`, `read_symbol`, `read_for_edit`, `outline`, `find_usages`, `explore_area`, `project_overview`) before considering raw Read. Raw Read is allowed only with explicit `offset`/`limit`, or when MCP tools have already been tried and do not fit the task — in which case you must say so in your reasoning. Never dump a file's full contents unless absolutely necessary.
+
+If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
+
+Your specific role is defined below.
+
+Role: git-history archaeology — why, when, by whom.
+
+Response budget: ~600 tokens.
+
+When asked about history (who added X, when did Y break, why is Z written this way):
+
+1. Pin the symbol — `outline` + `read_symbol` to get exact file + line range. History queries need a target.
+2. Walk commits via `smart_log` on the file (filter path-scoped; the full repo log is useless). For a specific symbol, narrow further with `git log -L :<symbol>:<file>` via Bash.
+3. For each commit of interest: `smart_diff` to see *what that commit actually changed* for our symbol (not the whole commit) — use `--range=<sha>^..<sha>`.
+4. Walk outward with `find_usages` at each historical revision only if the question is "why did callers stop using X" — otherwise stay on the symbol.
+5. Deliver: one-line origin answer → 2–4 commit-entry bullets formatted `sha · YYYY-MM-DD · author · one-line reason` → link to the single commit that most explains current state.
+
+Do NOT dump `git log` output. Do NOT theorise about intent beyond what commit messages actually say ("author likely wanted X" is a hallucination; quote the message or admit absence). Do NOT walk history older than the last 50 commits unless explicitly asked. Confidence threshold: if the commit message is empty or `wip`, say so — don't invent.
+
+RESPONSE CONTRACT:
+- Lead with a one-line verdict.
+- Use bold section headers; one finding per bullet.
+- Reference code as `path:line`; paste source only if your role requires a patch.
+- Do NOT narrate tool calls. Do NOT preamble with "what was done well".
+- If findings exceed your budget, write overflow to `.token-pilot/<agent>-<timestamp>.md` and reference it; keep the visible response within budget.

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

@@ -8,9 +8,11 @@ tools:
   - mcp__token-pilot__module_info
   - mcp__token-pilot__related_files
   - mcp__token-pilot__smart_read
+  - mcp__token-pilot__smart_read_many
+  - mcp__token-pilot__read_symbols
   - Read
-token_pilot_version: "0.22.2"
-token_pilot_body_hash: 3c09b7db1ae7224f5d72e88abfbfdbf1dd690c0fded261f4b6a805f8855ff877
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: 0be2620ce0303f912f6b3334f261d169f064970c0d16602fa1e76db4cb2ea441
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -29,7 +31,7 @@ When given a symbol, file, or change description:
 
 1. Locate the change surface via `read_symbol` or `outline` — never raw Read the whole file.
 2. Enumerate downstream dependents via `find_usages` (direct callers + one hop of transitive).
-3. For each dependent, inspect only the relevant call site via `read_symbol` or bounded `Read(path, offset, limit)` to judge compatibility.
+3. For each dependent, inspect only the relevant call site via `read_symbol` or bounded `Read(path, offset, limit)` to judge compatibility. For multiple dependents in one file, `read_symbols` (batch) — NOT `read_symbol` in a loop. For structural view across many files at once, `smart_read_many`.
 4. Report the blast-radius as: one-line verdict → affected sites as `path:line` with compatibility judgment per site → any blind spots you could not resolve.
 
 Do NOT propose fixes. Do NOT paste source. Do NOT cross module boundaries beyond the second hop unless asked. Your only deliverable is the honest impact map.

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

@@ -7,10 +7,11 @@ tools:
   - mcp__token-pilot__related_files
   - mcp__token-pilot__outline
   - mcp__token-pilot__smart_read
+  - mcp__token-pilot__smart_read_many
   - Grep
   - Glob
-token_pilot_version: "0.22.2"
-token_pilot_body_hash: e687ecf7e2251c63c7a1da48316e7dc0e0acf84cc234afede2a98cef30e7e3d6
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: cf32cdee777430ecc6732db32b3f883a685c8a02b6dc93379d71b15555e79b3e
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -28,7 +29,7 @@ Response budget: ~800 tokens.
 When given a migration target (a symbol, API endpoint, pattern, or dependency to replace):
 
 1. Enumerate every reference via `find_usages` on the target — and on each direct alias if the symbol is re-exported.
-2. For each file with ≥1 hit, `module_info` to note entrypoints/importers — migrations that break exported surface cost more.
+2. For files with ≥1 hit, batch through `smart_read_many` (up to 20 at a time) for structural view in one round-trip — NOT `smart_read` in a loop. Then `module_info` per file to note entrypoints/importers — migrations that break exported surface cost more.
 3. Group findings by effort class: **trivial** (string replace), **local** (one-symbol refactor), **cross-file** (signature change), **needs design** (semantic mismatch).
 4. Flag hidden consumers with `related_files` on high-traffic targets — tests, fixtures, docs often get missed.
 5. Deliver: file-by-file checklist as `path:line — effort — reason` sorted by effort class, then a rollout suggestion (safe order).

package/dist/agents/tp-onboard.md

@@ -7,8 +7,10 @@ tools:
   - mcp__token-pilot__related_files
   - mcp__token-pilot__outline
   - mcp__token-pilot__smart_read
-token_pilot_version: "0.22.2"
-token_pilot_body_hash: 2a4747a72609cbbca9d2060e7cd892a2533eee1e3b909f7e6742c080621ded50
+  - mcp__token-pilot__smart_read_many
+  - mcp__token-pilot__read_section
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -25,8 +27,8 @@ Response budget: ~600 tokens.
 
 When asked to orient a caller to an unfamiliar codebase:
 
-1. Start with `project_overview` to establish the top-level layout, language mix, and entry points. Do not Read individual files first.
-2. For each named area of interest (or the top 2–3 by size if none named), use `explore_area` to enumerate the modules inside, then `outline` on the one or two most load-bearing files.
+1. Start with `project_overview` to establish the top-level layout, language mix, and entry points. Do not Read individual files first. For `README.md` / `CONTRIBUTING.md` / `ARCHITECTURE.md`, use `read_section` with the relevant heading — NOT `smart_read` on the whole doc.
+2. For each named area of interest (or the top 2–3 by size if none named), use `explore_area` to enumerate the modules inside, then `outline` on the one or two most load-bearing files. For multiple load-bearing files, `smart_read_many` as a batch (up to 20) instead of `smart_read` in a loop.
 3. For cross-module understanding, use `related_files` on an entry point to map its direct dependents.
 4. Report: one-line verdict on "how the repo is organised" → a short bulleted tour of the top 3–5 areas with `path:line` anchors to entry points → where a newcomer should start reading next.
 

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

@@ -6,10 +6,12 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
+  - mcp__token-pilot__read_symbols
+  - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_for_edit
   - Read
-token_pilot_version: "0.22.2"
-token_pilot_body_hash: 85f8212852dba3f6b34872f1694633ff6522543b2e01318f8dab36dda59e8ac6
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: eb9fb7f87d9ab61c5b18248a40b283008b5d73414ddb2e3094ff0826e7e463d0
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -27,7 +29,7 @@ Response budget: ~600 tokens.
 When reviewing a changeset (diff, commit range, or PR):
 
 1. Load the structural diff via `smart_diff` — never raw Read the full touched files first.
-2. For each changed symbol of substance, `outline` its containing file and, if needed, `read_symbol` to inspect only the changed block.
+2. For each changed symbol of substance, `outline` its containing file. For multiple symbols in the same file, `read_symbols` (one call) — NOT a loop of `read_symbol`. For multiple touched files at once, `smart_read_many` before drilling in.
 3. For changes to exported / public surface, run `find_usages` to verify no cross-file breakage.
 4. Report: one-line verdict (`approve` / `request changes` / `block`) → **Critical:** findings that must be fixed → **Important:** findings the author should address → silence on stylistic nits that pass the project's linter.
 

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.22.2"
+token_pilot_version: "0.23.1"
 token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
 ---
 

package/dist/agents/tp-run.md

@@ -15,7 +15,7 @@ tools:
   - Grep
   - Glob
   - Bash
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.1"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

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

@@ -0,0 +1,51 @@
+---
+name: tp-session-restorer
+description: Rehydrates session state after /clear, compaction, or a fresh window. Reads the latest session_snapshot + saved docs + git status, returns a ≤200-token "where we were" briefing. Use at the start of a continuation session, not mid-task.
+tools:
+  - mcp__token-pilot__smart_read
+  - mcp__token-pilot__read_range
+  - mcp__token-pilot__read_section
+  - mcp__token-pilot__session_budget
+  - Bash
+  - Read
+token_pilot_version: "0.23.1"
+token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
+---
+
+You are a token-pilot agent (`tp-<name>`). Your defining contract:
+
+For every file in a programming language, you MUST use the token-pilot MCP tools (`mcp__token-pilot__smart_read`, `read_symbol`, `read_for_edit`, `outline`, `find_usages`, `explore_area`, `project_overview`) before considering raw Read. Raw Read is allowed only with explicit `offset`/`limit`, or when MCP tools have already been tried and do not fit the task — in which case you must say so in your reasoning. Never dump a file's full contents unless absolutely necessary.
+
+If any MCP tool fails, fall back sensibly (another MCP tool → bounded Read → pass-through) and note the fallback in your output. Never silently abandon the contract.
+
+Your specific role is defined below.
+
+Role: session-state rehydration.
+
+Response budget: ~400 tokens.
+
+When invoked at the start of a continuation (post-/clear, post-compaction, fresh window on a mid-flight task):
+
+1. Read `.token-pilot/snapshots/latest.md` via `read_section` (section `Session State`) — NOT `smart_read` on the whole file. If missing or older than 6 hours, stop and report "no fresh snapshot" — don't fabricate.
+2. Check session budget: `session_budget` with the current Claude Code `session_id` if available. One-line view of burn fraction + time-to-compact projection — helps the main agent decide how aggressive to be from here.
+3. Check git context: `git status --short` + `git log -1 --oneline` + current branch. One-line view.
+4. List saved research: `ls .token-pilot/docs/*.md` — count + newest 3 names only, do NOT read their bodies.
+5. Parse the snapshot's `**Goal:**` / `**Decisions:**` / `**Next:**` sections. Cap Decisions at top 3; keep Next verbatim.
+6. Deliver a compact briefing in this shape exactly:
+   ```
+   Resuming: <goal>
+   Budget: <burnFraction*100>% burned, ~<eventsUntilExhaustion> events left (or "unknown" if no session_id)
+   Branch: <branch> (<dirty|clean>) · last commit: <sha> <msg>
+   Decisions so far: <top 3 bullets>
+   Next step: <verbatim from snapshot>
+   Saved docs: <N> (latest: <name1>, <name2>, <name3>)
+   ```
+
+Do NOT re-read every saved doc — the user loads them on demand via `smart_read`. Do NOT summarise the full snapshot body — the user already sees the pointer at SessionStart. Do NOT infer next steps; if the snapshot has no Next, say "snapshot has no explicit next step". Confidence threshold: this agent refuses to guess — it's a parser, not an advisor.
+
+RESPONSE CONTRACT:
+- Lead with a one-line verdict.
+- Use bold section headers; one finding per bullet.
+- Reference code as `path:line`; paste source only if your role requires a patch.
+- Do NOT narrate tool calls. Do NOT preamble with "what was done well".
+- If findings exceed your budget, write overflow to `.token-pilot/<agent>-<timestamp>.md` and reference it; keep the visible response within budget.

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.22.2"
+token_pilot_version: "0.23.1"
 token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
 ---
 

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

@@ -12,7 +12,7 @@ tools:
   - Write
   - Edit
   - Bash
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.1"
 token_pilot_body_hash: 533b3d2387e631a24291314b2b8ad8c3e01c19e0b9ec1d3fe08ae0011f0c73f9
 ---
 

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

@@ -0,0 +1,27 @@
+/**
+ * CLI typo guard — catches obvious mis-typed commands before they fall
+ * through to the default `startServer(cliArgs)` branch where the arg is
+ * treated as a project root.
+ *
+ * The bug it prevents: `npx token-pilot install-aents` (missing 'g')
+ * silently became a projectRoot=install-aents MCP server launch, which
+ * then created stray `install-aents/.claude/settings.json` directories.
+ *
+ * Heuristic:
+ *   - If the first arg looks command-like (all-lowercase kebab, no path
+ *     separators, no absolute/relative path markers)
+ *   - AND it's not in the known-commands allow-list
+ *   - AND it doesn't resolve to an existing directory
+ *   - → treat as typo: print an error + suggest the closest command.
+ *
+ * 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-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", "save-doc", "list-docs", "init", "--version", "-v", "--help", "-h"];
+export interface TypoGuardResult {
+    kind: "pass-through" | "typo";
+    suggestion?: string;
+    message?: string;
+}
+export declare function checkForTypo(firstArg: string | undefined): TypoGuardResult;
+//# sourceMappingURL=typo-guard.d.ts.map

package/dist/cli/typo-guard.js

@@ -0,0 +1,119 @@
+/**
+ * CLI typo guard — catches obvious mis-typed commands before they fall
+ * through to the default `startServer(cliArgs)` branch where the arg is
+ * treated as a project root.
+ *
+ * The bug it prevents: `npx token-pilot install-aents` (missing 'g')
+ * silently became a projectRoot=install-aents MCP server launch, which
+ * then created stray `install-aents/.claude/settings.json` directories.
+ *
+ * Heuristic:
+ *   - If the first arg looks command-like (all-lowercase kebab, no path
+ *     separators, no absolute/relative path markers)
+ *   - AND it's not in the known-commands allow-list
+ *   - AND it doesn't resolve to an existing directory
+ *   - → treat as typo: print an error + suggest the closest command.
+ *
+ * Everything else passes through untouched — a real project root like
+ * `/home/user/my-project` or `./subdir` goes to startServer as before.
+ */
+import { existsSync, statSync } from "node:fs";
+export const KNOWN_COMMANDS = [
+    "hook-read",
+    "hook-edit",
+    "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",
+    "save-doc",
+    "list-docs",
+    "init",
+    "--version",
+    "-v",
+    "--help",
+    "-h",
+];
+const COMMAND_LIKE_RE = /^[a-z]+(-[a-z]+)+$/;
+function looksLikeCommand(arg) {
+    if (!arg)
+        return false;
+    if (arg.startsWith("-") && !arg.startsWith("--"))
+        return false;
+    if (arg.includes("/") || arg.includes("\\"))
+        return false;
+    if (arg === "." || arg === "..")
+        return false;
+    return COMMAND_LIKE_RE.test(arg);
+}
+function existsAsDir(arg) {
+    try {
+        return existsSync(arg) && statSync(arg).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Levenshtein distance — cheap enough on 20-item allow-list.
+ */
+function distance(a, b) {
+    if (a === b)
+        return 0;
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const prev = new Array(n + 1);
+    const curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = curr[j];
+    }
+    return prev[n];
+}
+export function checkForTypo(firstArg) {
+    if (!firstArg)
+        return { kind: "pass-through" };
+    if (KNOWN_COMMANDS.includes(firstArg)) {
+        return { kind: "pass-through" };
+    }
+    if (!looksLikeCommand(firstArg))
+        return { kind: "pass-through" };
+    if (existsAsDir(firstArg))
+        return { kind: "pass-through" };
+    // Find closest match among command-like known commands.
+    let best = "";
+    let bestDistance = Infinity;
+    for (const cmd of KNOWN_COMMANDS) {
+        if (cmd.startsWith("-"))
+            continue; // skip flags for suggestion
+        const d = distance(firstArg, cmd);
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = cmd;
+        }
+    }
+    const suggestion = bestDistance <= 3 ? best : undefined;
+    const message = suggestion
+        ? `Unknown command "${firstArg}". Did you mean "${suggestion}"?`
+        : `Unknown command "${firstArg}". Run "token-pilot --help" for the full list.`;
+    return { kind: "typo", suggestion, message };
+}
+//# sourceMappingURL=typo-guard.js.map

package/dist/hooks/installer.js

@@ -55,6 +55,15 @@ function createHookConfig(options) {
                         },
                     ],
                 },
+                {
+                    matcher: "Task",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("hook-post-task", options),
+                        },
+                    ],
+                },
             ],
         },
     };

package/dist/hooks/post-task.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TP-q33(a) — PostToolUse:Task budget enforcement.
+ *
+ * Claude Code's `Task` tool is how subagents are dispatched. When one
+ * returns, this hook:
+ *   1. Identifies the subagent by `tool_input.subagent_type`.
+ *   2. Loads its agent markdown (project first, then ~/.claude/agents).
+ *   3. Reads the `Response budget: ~N tokens` line from the body.
+ *   4. Counts tokens in the `tool_response` body (chars/4 heuristic).
+ *   5. If actual > budget × (1 + OVER_BUDGET_TOLERANCE), append a JSONL
+ *      entry to `.token-pilot/over-budget.log`.
+ *
+ * Silent on every failure — telemetry must never break the agent loop.
+ * Non-tp-* subagents are ignored (we only enforce our own contracts).
+ */
+export declare const OVER_BUDGET_LOG = "over-budget.log";
+/** Ratio above which we flag — 0.1 = 10 % grace. */
+export declare const OVER_BUDGET_TOLERANCE = 0.1;
+export declare function parseAgentBudget(body: string): number | null;
+/**
+ * Count approx tokens in the `tool_response.content[*].text` blocks of a
+ * PostToolUse hook input for the Task tool. Returns null for anything
+ * other than a well-formed Task response.
+ */
+export declare function extractSubagentTokens(input: {
+    tool_name?: string;
+    tool_response?: unknown;
+}): number | null;
+export interface BudgetDecisionInput {
+    agentName: string;
+    budget: number | null;
+    actualTokens: number;
+}
+export interface BudgetDecisionResult {
+    overBudget: boolean;
+    overByRatio: number;
+    message: string | null;
+}
+export declare function decideBudgetAdvice(input: BudgetDecisionInput): BudgetDecisionResult;
+export interface OverBudgetEntry {
+    ts: number;
+    agent: string;
+    budget: number;
+    actualTokens: number;
+    overByRatio: number;
+}
+export declare function appendOverBudgetLog(projectRoot: string, entry: OverBudgetEntry): Promise<void>;
+/**
+ * Locate the markdown body for a `tp-*` subagent — project-level first,
+ * then user-level. Returns null when neither exists. Non-tp-* subagents
+ * are rejected up front so we never peek outside our namespace.
+ */
+export declare function loadAgentBody(projectRoot: string, homeDir: string, agentName: string): Promise<string | null>;
+export interface PostTaskHookInput {
+    tool_name?: string;
+    tool_input?: {
+        subagent_type?: string;
+    };
+    tool_response?: unknown;
+}
+/**
+ * Full post-Task processing: read frontmatter, count tokens, log over-budget.
+ * Returns the advice message (or null) so the caller can optionally emit
+ * `additionalContext` — though the primary output channel is the log file.
+ */
+export declare function processPostTask(projectRoot: string, homeDir: string, input: PostTaskHookInput): Promise<string | null>;
+//# sourceMappingURL=post-task.d.ts.map

package/dist/hooks/post-task.js

@@ -0,0 +1,136 @@
+/**
+ * TP-q33(a) — PostToolUse:Task budget enforcement.
+ *
+ * Claude Code's `Task` tool is how subagents are dispatched. When one
+ * returns, this hook:
+ *   1. Identifies the subagent by `tool_input.subagent_type`.
+ *   2. Loads its agent markdown (project first, then ~/.claude/agents).
+ *   3. Reads the `Response budget: ~N tokens` line from the body.
+ *   4. Counts tokens in the `tool_response` body (chars/4 heuristic).
+ *   5. If actual > budget × (1 + OVER_BUDGET_TOLERANCE), append a JSONL
+ *      entry to `.token-pilot/over-budget.log`.
+ *
+ * Silent on every failure — telemetry must never break the agent loop.
+ * Non-tp-* subagents are ignored (we only enforce our own contracts).
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+export const OVER_BUDGET_LOG = "over-budget.log";
+/** Ratio above which we flag — 0.1 = 10 % grace. */
+export const OVER_BUDGET_TOLERANCE = 0.1;
+const BUDGET_RE = /Response budget:\s*~?\s*(\d{2,6})\s*tokens?/i;
+export function parseAgentBudget(body) {
+    const m = body.match(BUDGET_RE);
+    if (!m)
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/**
+ * Count approx tokens in the `tool_response.content[*].text` blocks of a
+ * PostToolUse hook input for the Task tool. Returns null for anything
+ * other than a well-formed Task response.
+ */
+export function extractSubagentTokens(input) {
+    if (input.tool_name !== "Task")
+        return null;
+    const resp = input.tool_response;
+    if (!resp || typeof resp !== "object")
+        return null;
+    const parts = Array.isArray(resp.content) ? resp.content : [];
+    let chars = 0;
+    for (const p of parts) {
+        if (typeof p?.text === "string")
+            chars += p.text.length;
+    }
+    if (chars === 0)
+        return null;
+    return Math.ceil(chars / 4);
+}
+export function decideBudgetAdvice(input) {
+    if (input.budget == null || input.budget <= 0) {
+        return { overBudget: false, overByRatio: 0, message: null };
+    }
+    const allowed = input.budget * (1 + OVER_BUDGET_TOLERANCE);
+    if (input.actualTokens <= allowed) {
+        return {
+            overBudget: false,
+            overByRatio: input.actualTokens / input.budget - 1,
+            message: null,
+        };
+    }
+    const ratio = input.actualTokens / input.budget - 1;
+    const pct = Math.round(ratio * 100);
+    return {
+        overBudget: true,
+        overByRatio: ratio,
+        message: `${input.agentName} exceeded budget (~${input.actualTokens} tokens vs budget ${input.budget}, +${pct}%). See .token-pilot/over-budget.log.`,
+    };
+}
+export async function appendOverBudgetLog(projectRoot, entry) {
+    try {
+        const dir = join(projectRoot, ".token-pilot");
+        await fs.mkdir(dir, { recursive: true });
+        const line = JSON.stringify(entry) + "\n";
+        await fs.appendFile(join(dir, OVER_BUDGET_LOG), line);
+    }
+    catch {
+        /* silent — logging must never break the hook */
+    }
+}
+/**
+ * Locate the markdown body for a `tp-*` subagent — project-level first,
+ * then user-level. Returns null when neither exists. Non-tp-* subagents
+ * are rejected up front so we never peek outside our namespace.
+ */
+export async function loadAgentBody(projectRoot, homeDir, agentName) {
+    if (!agentName.startsWith("tp-"))
+        return null;
+    const candidates = [
+        join(projectRoot, ".claude", "agents", `${agentName}.md`),
+        join(homeDir, ".claude", "agents", `${agentName}.md`),
+    ];
+    for (const p of candidates) {
+        try {
+            return await fs.readFile(p, "utf-8");
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+/**
+ * Full post-Task processing: read frontmatter, count tokens, log over-budget.
+ * Returns the advice message (or null) so the caller can optionally emit
+ * `additionalContext` — though the primary output channel is the log file.
+ */
+export async function processPostTask(projectRoot, homeDir, input) {
+    if (input.tool_name !== "Task")
+        return null;
+    const agentName = input.tool_input?.subagent_type;
+    if (typeof agentName !== "string" || !agentName.startsWith("tp-")) {
+        return null;
+    }
+    const actualTokens = extractSubagentTokens(input);
+    if (actualTokens == null)
+        return null;
+    const body = await loadAgentBody(projectRoot, homeDir, agentName);
+    const budget = body ? parseAgentBudget(body) : null;
+    const decision = decideBudgetAdvice({
+        agentName,
+        budget,
+        actualTokens,
+    });
+    if (decision.overBudget && budget != null) {
+        await appendOverBudgetLog(projectRoot, {
+            ts: Date.now(),
+            agent: agentName,
+            budget,
+            actualTokens,
+            overByRatio: decision.overByRatio,
+        });
+    }
+    return decision.message;
+}
+//# sourceMappingURL=post-task.js.map

package/dist/index.js

@@ -18,6 +18,8 @@ import { handleSessionStart } from "./hooks/session-start.js";
 import { computeEffectiveThreshold } from "./hooks/adaptive-threshold.js";
 import { loadSessionSavedTokens } from "./core/session-savings.js";
 import { handleSaveDocCli, handleListDocsCli } from "./cli/save-doc.js";
+import { checkForTypo } from "./cli/typo-guard.js";
+import { processPostTask } from "./hooks/post-task.js";
 import { isContextModeInstalledSync } from "./integration/context-mode-detector.js";
 import { handleBlessAgents } from "./cli/bless-agents.js";
 import { unblessAgents } from "./cli/unbless-agents.js";
@@ -87,6 +89,13 @@ export function getVersion() {
     }
 }
 export async function main(cliArgs = process.argv.slice(2)) {
+    // Guard against mis-typed commands like `install-aents` silently
+    // becoming a projectRoot=install-aents server launch. See TP-v0.22.3.
+    const typo = checkForTypo(cliArgs[0]);
+    if (typo.kind === "typo") {
+        process.stderr.write(`[token-pilot] ${typo.message}\n`);
+        process.exit(1);
+    }
     switch (cliArgs[0]) {
         case "hook-read": {
             const cfg = await loadConfig(process.cwd());
@@ -116,6 +125,26 @@ export async function main(cliArgs = process.argv.slice(2)) {
             process.exit(0);
             return;
         }
+        case "hook-post-task": {
+            try {
+                const stdin = readFileSync(0, "utf-8");
+                const input = JSON.parse(stdin);
+                const message = await processPostTask(process.cwd(), homedir(), input);
+                if (message) {
+                    process.stdout.write(JSON.stringify({
+                        hookSpecificOutput: {
+                            hookEventName: "PostToolUse",
+                            additionalContext: `[token-pilot] ${message}`,
+                        },
+                    }));
+                }
+            }
+            catch {
+                /* silent — hook must not break */
+            }
+            process.exit(0);
+            return;
+        }
         case "hook-session-start": {
             const cfg = await loadConfig(process.cwd());
             // `sessionStart.enabled` is independent of `hooks.mode` by design —

package/package.json

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