token-pilot 0.22.2 → 0.23.0

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.0",
   "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,42 @@ 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.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,49 @@
+---
+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
+  - Grep
+  - Read
+token_pilot_version: "0.23.0"
+token_pilot_body_hash: 1850e394b726f6975177a1f4cbb9153fa49cb263355c068f1924a2f625bea4b4
+---
+
+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.
+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.0"
 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.0"
 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.0"
 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.0"
+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

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__related_files
   - mcp__token-pilot__smart_read
   - Read
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.0"
 token_pilot_body_hash: 3c09b7db1ae7224f5d72e88abfbfdbf1dd690c0fded261f4b6a805f8855ff877
 ---
 

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

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__smart_read
   - Grep
   - Glob
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.0"
 token_pilot_body_hash: e687ecf7e2251c63c7a1da48316e7dc0e0acf84cc234afede2a98cef30e7e3d6
 ---
 

package/dist/agents/tp-onboard.md

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__related_files
   - mcp__token-pilot__outline
   - mcp__token-pilot__smart_read
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.0"
 token_pilot_body_hash: 2a4747a72609cbbca9d2060e7cd892a2533eee1e3b909f7e6742c080621ded50
 ---
 

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

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - mcp__token-pilot__read_for_edit
   - Read
-token_pilot_version: "0.22.2"
+token_pilot_version: "0.23.0"
 token_pilot_body_hash: 85f8212852dba3f6b34872f1694633ff6522543b2e01318f8dab36dda59e8ac6
 ---
 

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.0"
 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.0"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

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

@@ -0,0 +1,47 @@
+---
+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
+  - Bash
+  - Read
+token_pilot_version: "0.23.0"
+token_pilot_body_hash: 88ccd78695eacf1216021d450be00873f2b7546d1603a3b03d55720ca1c7e83a
+---
+
+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 `smart_read`. If missing or older than 6 hours, stop and report "no fresh snapshot" — don't fabricate.
+2. Check git context: `git status --short` + `git log -1 --oneline` + current branch. One-line view.
+3. List saved research: `ls .token-pilot/docs/*.md` — count + newest 3 names only, do NOT read their bodies.
+4. Parse the snapshot's `**Goal:**` / `**Decisions:**` / `**Next:**` sections. Cap Decisions at top 3; keep Next verbatim.
+5. Deliver a compact briefing in this shape exactly:
+   ```
+   Resuming: <goal>
+   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.0"
 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.0"
 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.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",