token-pilot 0.23.0 → 0.23.2

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.2] - 2026-04-18
+
+### Changed — SessionStart reminder now carries a task→agent decision guide
+
+The reminder used to list the installed `tp-*` agents with their descriptions. Useful, but the main agent still had to decide **when** to delegate. Now the reminder carries a compact task→agent cheat-sheet inline:
+
+```
+WHEN DELEGATING — if the task fits a specialist, use the Task tool:
+  bug / stack trace       → tp-debugger
+  PR / diff review        → tp-pr-reviewer
+  impact before change    → tp-impact-analyzer
+  plan refactor           → tp-refactor-planner
+  failing tests           → tp-test-triage
+  write new tests         → tp-test-writer
+  migrate API / version   → tp-migration-scout
+  "why is this like this?" → tp-history-explorer
+  security / quality audit → tp-audit-scanner
+  resume after /clear     → tp-session-restorer
+  dead code cleanup       → tp-dead-code-finder
+  commit message          → tp-commit-writer
+  repo onboarding         → tp-onboard
+  general workhorse       → tp-run
+```
+
+Lines for agents the user hasn't installed are filtered out automatically. Custom / third-party `tp-*` agents not in the core map get a fallback line with their own description. Over-budget trimming still lands `… and N more` with a total count, so nothing silently disappears.
+
+Also added to the MANDATORY block: `Batch variants (prefer over loops): read_symbols, smart_read_many, read_section.` — the three batch tools that v0.23.1 wired into specialist agents but that the main agent also benefits from.
+
+### Numbers
+- 906 tests green (+6 new buildReminderMessage regression tests), `tsc --noEmit` clean.
+
+## [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)

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

@@ -7,10 +7,11 @@ tools:
   - 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.0"
-token_pilot_body_hash: 1850e394b726f6975177a1f4cbb9153fa49cb263355c068f1924a2f625bea4b4
+token_pilot_version: "0.23.2"
+token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -27,7 +28,7 @@ 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.
+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`

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.23.0"
+token_pilot_version: "0.23.2"
 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.23.0"
+token_pilot_version: "0.23.2"
 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.23.0"
+token_pilot_version: "0.23.2"
 token_pilot_body_hash: 04864ae0bf0689863d7de9f4c0b44b293087b34098ad2771837e491d37dab953
 ---
 

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

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

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.23.0"
-token_pilot_body_hash: 3c09b7db1ae7224f5d72e88abfbfdbf1dd690c0fded261f4b6a805f8855ff877
+token_pilot_version: "0.23.2"
+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.23.0"
-token_pilot_body_hash: e687ecf7e2251c63c7a1da48316e7dc0e0acf84cc234afede2a98cef30e7e3d6
+token_pilot_version: "0.23.2"
+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.23.0"
-token_pilot_body_hash: 2a4747a72609cbbca9d2060e7cd892a2533eee1e3b909f7e6742c080621ded50
+  - mcp__token-pilot__smart_read_many
+  - mcp__token-pilot__read_section
+token_pilot_version: "0.23.2"
+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.23.0"
-token_pilot_body_hash: 85f8212852dba3f6b34872f1694633ff6522543b2e01318f8dab36dda59e8ac6
+token_pilot_version: "0.23.2"
+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.23.0"
+token_pilot_version: "0.23.2"
 token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
 ---
 

package/dist/agents/tp-run.md

@@ -15,7 +15,7 @@ tools:
   - Grep
   - Glob
   - Bash
-token_pilot_version: "0.23.0"
+token_pilot_version: "0.23.2"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

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

@@ -4,10 +4,12 @@ description: Rehydrates session state after /clear, compaction, or a fresh windo
 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.0"
-token_pilot_body_hash: 88ccd78695eacf1216021d450be00873f2b7546d1603a3b03d55720ca1c7e83a
+token_pilot_version: "0.23.2"
+token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
 ---
 
 You are a token-pilot agent (`tp-<name>`). Your defining contract:
@@ -24,13 +26,15 @@ 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:
+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>

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

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

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

package/dist/hooks/session-start.js

@@ -97,7 +97,24 @@ MANDATORY — for code files, use these before raw Read:
   mcp__token-pilot__read_symbol(path, sym)  — one function / class
   mcp__token-pilot__read_for_edit(path, sym)— exact text for editing
   mcp__token-pilot__outline(path)           — symbol list
+Batch variants (prefer over loops): read_symbols, smart_read_many, read_section.
 Raw Read allowed only with offset/limit or TOKEN_PILOT_BYPASS=1.`;
+const DECISION_GUIDE = `WHEN DELEGATING — if the task fits a specialist, use the Task tool:
+  bug / stack trace      → tp-debugger
+  PR / diff review       → tp-pr-reviewer
+  impact before change   → tp-impact-analyzer
+  plan refactor          → tp-refactor-planner
+  failing tests          → tp-test-triage
+  write new tests        → tp-test-writer
+  migrate API / version  → tp-migration-scout
+  "why is this like this?"→ tp-history-explorer
+  security / quality audit→ tp-audit-scanner
+  resume after /clear    → tp-session-restorer
+  dead code cleanup      → tp-dead-code-finder
+  commit message         → tp-commit-writer
+  repo onboarding        → tp-onboard
+  general workhorse      → tp-run
+Delegating keeps main-context lean; each specialist has a narrow toolset + budget.`;
 function estimateTokens(text) {
     // Fast approximation: chars / 4, adjusted for whitespace
     if (text.length === 0)
@@ -110,29 +127,51 @@ function estimateTokens(text) {
  * delegating list with "… and N more" if needed.
  */
 export function buildReminderMessage(agents, maxReminderTokens) {
-    const agentLines = agents.length === 0
-        ? "  none installed — run: npx token-pilot install-agents"
-        : agents.map((a) => `  ${a.name}  — ${a.description}`).join("\n");
-    const delegatingSection = `WHEN DELEGATING — use the right token-pilot-native subagent:\n${agentLines}`;
-    const full = `${MANDATORY_BLOCK}\n\n${delegatingSection}`;
+    // If no agents installed, give the user a clear nudge; skip the
+    // delegation guide since there's nothing to delegate to.
+    if (agents.length === 0) {
+        return `${MANDATORY_BLOCK}\n\nWHEN DELEGATING — none installed; run: npx token-pilot install-agents`;
+    }
+    // Filter the decision guide to the agents this user actually has
+    // installed. Dropping lines for missing agents keeps the reminder
+    // honest when the template ships an agent the user hasn't installed.
+    const installedNames = new Set(agents.map((a) => a.name));
+    const guideKnownNames = new Set();
+    const decisionGuideLines = DECISION_GUIDE.split("\n").filter((line) => {
+        const m = line.match(/→\s+(tp-[a-z-]+)/);
+        if (!m)
+            return true; // header / footer
+        guideKnownNames.add(m[1]);
+        return installedNames.has(m[1]);
+    });
+    // Fallback: custom / third-party tp-* agents we don't hard-code in the
+    // guide still deserve a mention so the main agent can delegate to them.
+    const extras = agents.filter((a) => !guideKnownNames.has(a.name));
+    if (extras.length > 0) {
+        const extraLines = extras.map((a) => `  custom: ${a.name}  — ${a.description}`);
+        // Insert before the "Delegating keeps..." footer.
+        const footer = decisionGuideLines.pop() ?? "";
+        decisionGuideLines.push(...extraLines, footer);
+    }
+    const decisionGuide = decisionGuideLines.join("\n");
+    const full = `${MANDATORY_BLOCK}\n\n${decisionGuide}`;
     if (estimateTokens(full) <= maxReminderTokens) {
         return full;
     }
-    // Trim agent list until we fit. Distinguish "all agents trimmed due to
-    // budget" (count remained >0 in the original list) from "no agents at
-    // all" — they look the same to `trimmedAgents.length === 0` but mean
-    // very different things to the caller (one requires install-agents; the
-    // other just reports "N more hidden").
-    let trimmedAgents = [...agents];
-    while (trimmedAgents.length > 0) {
-        trimmedAgents = trimmedAgents.slice(0, trimmedAgents.length - 1);
-        const dropped = agents.length - trimmedAgents.length;
-        const trimmedLines = trimmedAgents.length === 0
-            ? `  … and ${dropped} more (reminder budget exhausted)`
-            : trimmedAgents
-                .map((a) => `  ${a.name}  — ${a.description}`)
-                .join("\n") + `\n  … and ${dropped} more`;
-        const candidate = `${MANDATORY_BLOCK}\n\nWHEN DELEGATING — use the right token-pilot-native subagent:\n${trimmedLines}`;
+    // Budget overflow: trim decision-guide body lines from the end (keep
+    // header, footer, and as many mappings as fit). Preserves the first
+    // line so the agent still knows the section exists.
+    const header = decisionGuideLines[0];
+    const footer = decisionGuideLines[decisionGuideLines.length - 1];
+    const body = decisionGuideLines.slice(1, -1);
+    let kept = body.length;
+    while (kept > 0) {
+        kept--;
+        const dropped = body.length - kept;
+        const trimmedBody = kept === 0
+            ? [`  … and ${dropped} more (reminder budget exhausted)`]
+            : body.slice(0, kept).concat(`  … and ${dropped} more`);
+        const candidate = `${MANDATORY_BLOCK}\n\n${[header, ...trimmedBody, footer].join("\n")}`;
         if (estimateTokens(candidate) <= maxReminderTokens) {
             return candidate;
         }

package/package.json

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