token-pilot 0.23.2 → 0.23.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.23.2",
+  "version": "0.23.4",
   "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,36 @@ 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.4] - 2026-04-18
+
+### Fixed
+
+- **`install-agents --force` now actually forces a refresh when body-hash matches.** Before this fix, `--force` was a no-op for unchanged-installed agents because the body hash (used to detect template drift) ignores the YAML frontmatter. Any frontmatter-only update (description, tools list, etc.) left `storedHash === templateHash`, so `--force` reported `unchanged` and skipped. This silently blocked v0.23.3's PROACTIVELY triggers from reaching existing installations — users had to `rm ~/.claude/agents/tp-*.md` first. Now `--force` rewrites the file regardless of body-hash match, while still refusing to touch user-owned files that carry no `token_pilot_body_hash` stamp.
+
+### Numbers
+- 907 tests green (+1 regression test for `--force` on unchanged files), `tsc --noEmit` clean.
+
+## [0.23.3] - 2026-04-18
+
+### Changed — PROACTIVELY triggers in every agent description + wider MANDATORY block
+
+Live-testing on a real machine surfaced a concrete gap: Claude Code's main agent read the reminder, saw tool descriptions, but **systematically skipped tp-\* subagents** — no explicit `PROACTIVELY` trigger meant they sat unused even when the task fit. Also reported: "I see only 4 token-pilot tools in MANDATORY, not 14" — the agent didn't scan tool descriptions to discover the rest unless prompted.
+
+Both fixes:
+
+1. **Every `tp-*` description now carries `PROACTIVELY use this when …` or `Use this when …` plus concrete user-intent signals** ("when the user reports a bug", "when the user asks to review a diff"). Claude Code's auto-invocation heuristic looks for exactly these phrases. 14 agents rewritten.
+
+2. **MANDATORY block expanded from 4 tools → 9 core tools** (smart_read, read_symbol, read_for_edit, outline, find_usages, smart_diff, smart_log, test_summary, project_overview) with `INSTEAD of` hints against raw Read/Grep/git. Still lists batch variants (read_symbols, smart_read_many, read_section) and names the remaining 10 under "Also available:" so the main agent sees the full surface even if it doesn't crawl descriptions.
+
+3. **Default `sessionStart.maxReminderTokens` raised 250 → 500** to fit the expanded block without aggressive trimming. Token-wise: ~500 tokens is 0.3% of a 160K context window — the round-trip savings from one prevented raw Read pay it back ~5×.
+
+### Updated
+
+- `prompt-contract.test.ts` relaxed: descriptions may now be up to 350 chars and every agent is **required** to carry a trigger phrase (`PROACTIVELY …` or `Use this when …`). Old contract required "only tp-run uses PROACTIVELY" and ≤160 chars — removed.
+
+### Numbers
+- 906 tests green (+6 rewrites of contract + reminder tests; none removed), `tsc --noEmit` clean.
+
 ## [0.23.2] - 2026-04-18
 
 ### Changed — SessionStart reminder now carries a task→agent decision guide

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use this when the user asks for a security / quality audit, pre-release sweep, or "scan this for issues". Finds hardcoded secrets, injection shapes, unsafe casts, stale TODOs — classified Critical / Important / Minor. Read-only, NEVER edits, never quotes secrets in output.
 tools:
   - mcp__token-pilot__code_audit
   - mcp__token-pilot__find_usages
@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__read_section
   - Grep
   - Read
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
 ---
 

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

@@ -1,13 +1,13 @@
 ---
 name: tp-commit-writer
-description: Drafts one Conventional-Commit message from current staged changes. Verifies tests/lint pass first; blocks when they don't. Use BEFORE `git commit`, not to explain already-made commits.
+description: PROACTIVELY use this when the user is about to commit, asks "write a commit message", or says "commit this". Reads staged diff, verifies tests pass, drafts Conventional Commit. Refuses mixed diffs (asks to split), failing tests, or empty stage. Do NOT use to explain already-made commits.
 tools:
   - mcp__token-pilot__smart_diff
   - mcp__token-pilot__smart_log
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 559a0b61d20974bf33e35bc4c80dcf1b41d10d4df46cf9d05d3d5620713cd46f
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: tp-dead-code-finder
-description: Finds truly unused symbols safe to delete. Cross-checks with git history, reflection / dynamic-import patterns, and test-only references before recommending removal. Use for codebase cleanup, NOT mid-feature.
+description: Use this when the user asks to find or remove dead / unused code ("clean up this file", "find unused exports", "pre-release cleanup"). Cross-checks find_unused with Grep, git history, and dynamic-lookup patterns before classifying. Output-only — NEVER deletes code itself.
 tools:
   - mcp__token-pilot__find_unused
   - mcp__token-pilot__find_usages
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__related_files
   - Grep
   - Read
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 482e33ba566dc75d87753d980267fb2e01763e5924612efd54ec89993b5e12fd
 ---
 

package/dist/agents/tp-debugger.md

@@ -1,6 +1,6 @@
 ---
 name: tp-debugger
-description: Bug diagnosis via call-tree traversal. Given a stack trace, error, or reproduction, finds the root cause path structurally before touching source. Use when debugging, not when writing new features.
+description: PROACTIVELY use this when the user reports a bug, stack trace, error message, failing behaviour, or asks "why does X break / fail / throw". Traces root cause via call-tree without reading whole files first. Do NOT use for writing new features or planning changes.
 tools:
   - mcp__token-pilot__read_symbol
   - mcp__token-pilot__find_usages
@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
   - Bash
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 04864ae0bf0689863d7de9f4c0b44b293087b34098ad2771837e491d37dab953
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: PROACTIVELY use this when the user asks "why is this like this", "when was X added / changed", "who added Y", "what was the reason for this code". Returns the minimum commit chain that explains current state — no theorising beyond what commit messages say.
 tools:
   - mcp__token-pilot__smart_log
   - mcp__token-pilot__smart_diff
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__outline
   - Bash
   - Read
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: b2daca007e959eaf26bf9a4d92ba36c3aa277a51de4ca4db674833d36acbe11b
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: tp-impact-analyzer
-description: Impact analyst. Given a symbol, file, or change description, produces a blast-radius map of affected call sites. Use when tracing what a change will break.
+description: PROACTIVELY use this when the user asks "what will break if I change X", "who depends on this", or is about to modify a shared symbol / public API / widely-used function. Produces a blast-radius map of affected call sites. Does NOT propose fixes.
 tools:
   - mcp__token-pilot__read_symbol
   - mcp__token-pilot__outline
@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_symbols
   - Read
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 0be2620ce0303f912f6b3334f261d169f064970c0d16602fa1e76db4cb2ea441
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: tp-migration-scout
-description: Pre-migration impact scout. Given a target (API, framework version, deprecated symbol), enumerates every touch-point in the repo as an actionable checklist. Use BEFORE starting a migration, not during.
+description: PROACTIVELY use this BEFORE the user starts any migration — replacing an API, upgrading a framework version, removing a deprecated symbol, switching libraries. Enumerates touch-points as an effort-classified checklist. Do NOT use during the migration itself (file-by-file edits).
 tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__module_info
@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - Grep
   - Glob
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: cf32cdee777430ecc6732db32b3f883a685c8a02b6dc93379d71b15555e79b3e
 ---
 

package/dist/agents/tp-onboard.md

@@ -1,6 +1,6 @@
 ---
 name: tp-onboard
-description: Repo onboarding guide. Orients a caller to an unfamiliar codebase structurally — layout, entry points, core modules. Use when first exploring a new repo.
+description: PROACTIVELY use this when the user is exploring an unfamiliar codebase — asks "how is this organised", "what does this project do", "where do I start reading", or starts any conversation in a repo the main agent doesn't know. Orientation map only (layout, entry points, modules); does NOT drill into implementation.
 tools:
   - mcp__token-pilot__project_overview
   - mcp__token-pilot__explore_area
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: tp-pr-reviewer
-description: PR diff reviewer. Reviews a changeset structurally — verdict first, then Critical/Important findings as path:line. Use when reviewing a diff or pending PR.
+description: PROACTIVELY use this when the user asks to review a diff, PR, commit range, or changeset ("review these changes", "look at my PR", "is this safe to merge"). Verdict-first output with Critical / Important findings. Do NOT use for writing code or planning.
 tools:
   - mcp__token-pilot__smart_diff
   - mcp__token-pilot__outline
@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_for_edit
   - Read
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: eb9fb7f87d9ab61c5b18248a40b283008b5d73414ddb2e3094ff0826e7e463d0
 ---
 

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

@@ -1,13 +1,13 @@
 ---
 name: tp-refactor-planner
-description: Refactor planner. Produces a step-by-step plan with exact edit context per step — plan only, no edits applied. Use for planning a refactor before coding.
+description: PROACTIVELY use this when the user asks to "plan", "design", or "scope" a refactor, or says "I want to refactor X but need a plan first". Produces step-by-step plan with exact edit context; never applies changes itself.
 tools:
   - mcp__token-pilot__read_for_edit
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_diff
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
 ---
 

package/dist/agents/tp-run.md

@@ -1,6 +1,6 @@
 ---
 name: tp-run
-description: MCP-first workhorse for general coding work — reading, editing, searching, exploring. Use PROACTIVELY when no specialised tp-* agent fits the task.
+description: PROACTIVELY use this general-purpose token-pilot workhorse for ANY coding task (read / edit / search / explore) when no other tp-* specialist matches. Prefer token-pilot MCP tools over raw Read / Grep / git. Invoke when the user asks to touch code and no more specific specialist fits.
 tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__read_symbol
@@ -15,7 +15,7 @@ tools:
   - Grep
   - Glob
   - Bash
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: PROACTIVELY use this as the FIRST step after /clear, compaction, or a fresh window when a recent session_snapshot exists on disk. Reads snapshot + git status + saved docs, returns a ≤200-token briefing. Do NOT use mid-task.
 tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__read_range
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
 ---
 

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

@@ -1,13 +1,13 @@
 ---
 name: tp-test-triage
-description: Test-failure triage. Given failing tests, identifies root cause and suggests the minimal fix — no speculation. Use when investigating why tests fail.
+description: PROACTIVELY use this when the user reports failing tests, asks to investigate a red CI, or says "these tests are broken / flaky". Identifies root cause and suggests minimal fix — no speculation. Do NOT use to write new tests (that's tp-test-writer).
 tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__read_range
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: tp-test-writer
-description: Writes tests for a specific symbol — not for whole files, not for untested suites. Mirrors project's existing test style. Use when extending coverage, not when diagnosing a failing test (use tp-test-triage for that).
+description: PROACTIVELY use this when the user asks to write, add, or cover a SPECIFIC function / method / class with tests ("add test for X", "cover Y"). Mirrors project's existing test style; runs the tests before declaring done. Do NOT use for diagnosing failures (that's tp-test-triage).
 tools:
   - mcp__token-pilot__read_symbol
   - mcp__token-pilot__read_for_edit
@@ -12,7 +12,7 @@ tools:
   - Write
   - Edit
   - Bash
-token_pilot_version: "0.23.2"
+token_pilot_version: "0.23.4"
 token_pilot_body_hash: 533b3d2387e631a24291314b2b8ad8c3e01c19e0b9ec1d3fe08ae0011f0c73f9
 ---
 

package/dist/cli/install-agents.js

@@ -144,8 +144,22 @@ export async function installAgents(opts) {
             continue;
         }
         if (storedHash === templateHash) {
-            // unchanged-installed: silent skip (re-write would be a no-op).
-            result.skipped.push({ name, reason: "unchanged" });
+            // unchanged-installed: body matches template. But body hash ignores
+            // frontmatter, so a description / tools update leaves the hash
+            // equal while the file genuinely needs refreshing. Respect --force
+            // by always rewriting in that case; keep silent skip otherwise.
+            if (opts.force) {
+                try {
+                    await writeFile(targetPath, templateMd);
+                    result.installed.push(name);
+                }
+                catch {
+                    result.skipped.push({ name, reason: "write failed" });
+                }
+            }
+            else {
+                result.skipped.push({ name, reason: "unchanged" });
+            }
             continue;
         }
         // template-upgraded: user did not edit (currentBodyHash === storedHash)

package/dist/config/defaults.js

@@ -68,7 +68,7 @@ export const DEFAULT_CONFIG = {
     sessionStart: {
         enabled: true,
         showStats: false,
-        maxReminderTokens: 250,
+        maxReminderTokens: 500,
     },
     agents: {
         scope: null,

package/dist/hooks/session-start.js

@@ -92,13 +92,21 @@ export async function scanAgents(projectRoot, homeDir) {
 // ─── Message builder (subtask 2.3) ───────────────────────────────────────────
 const MANDATORY_BLOCK = `[token-pilot active]
 
-MANDATORY — for code files, use these before raw Read:
-  mcp__token-pilot__smart_read(path)        — structural overview
-  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
+MANDATORY — use these BEFORE raw Read / Grep / git:
+  smart_read(path)             — structural overview of a code file
+  read_symbol(path, sym)       — one function / class body
+  read_for_edit(path, sym)     — exact text for Edit's old_string
+  outline(path)                — symbol list
+  find_usages(symbol)          — who calls / uses a symbol (INSTEAD of Grep)
+  smart_diff                   — git diff structurally (INSTEAD of raw git diff)
+  smart_log(path?)             — git log with symbol context (INSTEAD of raw git log)
+  test_summary(command)        — test runs without dumping full output
+  project_overview             — unfamiliar repo top-level map (first step)
 Batch variants (prefer over loops): read_symbols, smart_read_many, read_section.
-Raw Read allowed only with offset/limit or TOKEN_PILOT_BYPASS=1.`;
+Also available: read_range, read_diff, module_info, related_files, explore_area,
+code_audit, find_unused, session_snapshot, session_budget, session_analytics.
+Raw Read/Grep allowed only with offset/limit / narrow regex / non-code files,
+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

package/package.json

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