token-pilot 0.29.0 → 0.30.0

package/dist/server/tool-definitions.js

@@ -1,8 +1,89 @@
-/**
- * MCP tool definitions and system instructions.
- * Pure static data — no runtime dependencies.
- */
-export const MCP_INSTRUCTIONS = [
+// ---------------------------------------------------------------------------
+// Minimal profile — 5 essential tools, near-zero instructions overhead
+// ---------------------------------------------------------------------------
+const MCP_INSTRUCTIONS_MINIMAL = [
+    "Token Pilot — token-efficient code reading. ALWAYS prefer these tools over Read/cat/grep.",
+    "",
+    "TOOLS:",
+    "• smart_read(path) — read a code file (NOT cat/Read — returns structure, 60-80% fewer tokens)",
+    "• read_symbol(path, symbol) — read ONE function/class body (NOT the whole file)",
+    "• find_usages(symbol) — find where a symbol is defined, imported, or used",
+    "• smart_diff — review git changes mapped to functions/classes (NOT git diff)",
+    "• smart_log — structured commit history (NOT git log)",
+    "",
+    "USE Read/Grep ONLY for: non-code configs (JSON, YAML, markdown), regex patterns.",
+].join("\n");
+// ---------------------------------------------------------------------------
+// Nav profile — exploration only, no edit-prep tools
+// ---------------------------------------------------------------------------
+const MCP_INSTRUCTIONS_NAV = [
+    "Token Pilot — token-efficient code reading (saves 60-80% tokens). ALWAYS prefer these tools over Read/cat/grep.",
+    "",
+    "DECISION RULES — pick the first match:",
+    "1. New codebase / unfamiliar project → project_overview",
+    "2. Starting work on a directory → explore_area (outline + imports + tests + git log in one call)",
+    "3. Need to read a code file → smart_read (NOT Read/cat — returns structure, 60-80% fewer tokens)",
+    '   - For navigation/browsing: smart_read(scope="nav") — names + lines only, 2-3x smaller',
+    '   - For public API overview: smart_read(scope="exports")',
+    "4. Need one function/class body → read_symbol (loads only that symbol, NOT the whole file)",
+    "5. Find where a symbol is used → find_usages (semantic: definitions + imports + usages)",
+    '   - For initial discovery: find_usages(mode="list") — file:line only, 5-10x smaller',
+    "6. Understand file dependencies → related_files (imports, importers, tests — ranked by relevance)",
+    "7. List all symbols in a directory → outline (classes, functions, methods in one call)",
+    "8. Review git changes → smart_diff (NOT git diff — maps changes to functions/classes)",
+    "9. Commit history → smart_log (NOT git log — structured with categories)",
+    "10. Module architecture → module_info (deps, dependents, public API)",
+    "11. Read markdown/yaml/json/csv section → read_section (loads one heading/key/row-range, NOT the whole file)",
+    "12. Long session / before compaction → session_snapshot (<200 token state capture)",
+    "",
+    "USE Read/Grep ONLY for: regex text search → Grep | exact raw content → Read",
+    "",
+    "WORKFLOW:",
+    "• Explore: project_overview → explore_area → smart_read → read_symbol",
+].join("\n");
+// ---------------------------------------------------------------------------
+// Edit profile — nav + batch reads + edit-prep (DEFAULT)
+// ---------------------------------------------------------------------------
+const MCP_INSTRUCTIONS_EDIT = [
+    "Token Pilot — token-efficient code reading (saves 60-80% tokens). ALWAYS prefer these tools over Read/cat/grep.",
+    "",
+    "DECISION RULES — pick the first match:",
+    "1. New codebase / unfamiliar project → project_overview",
+    "2. Starting work on a directory → explore_area (outline + imports + tests + git log in one call)",
+    "3. Need to read a code file → smart_read (NOT Read/cat — returns structure, 60-80% fewer tokens)",
+    '   - For navigation/browsing: smart_read(scope="nav") — names + lines only, 2-3x smaller',
+    '   - For public API overview: smart_read(scope="exports")',
+    "4. Need one function/class body → read_symbol (loads only that symbol, NOT the whole file)",
+    "   - Preparing edit? Add include_edit_context=true to skip separate read_for_edit call",
+    "5. Need MULTIPLE function/class bodies from same file → read_symbols (batch — one call instead of N)",
+    "6. Preparing an edit → read_for_edit (returns exact text for Edit old_string)",
+    "7. Verify edits after editing → read_diff (only changed hunks — REQUIRES smart_read BEFORE editing)",
+    "8. Multiple files at once → smart_read_many (batch up to 20 files)",
+    "9. Find where a symbol is used → find_usages (semantic: definitions + imports + usages)",
+    '   - For initial discovery: find_usages(mode="list") — file:line only, 5-10x smaller',
+    "10. Understand file dependencies → related_files (imports, importers, tests — ranked by relevance)",
+    "11. List all symbols in a directory → outline (classes, functions, methods in one call)",
+    "12. Review git changes → smart_diff (NOT git diff — maps changes to functions/classes)",
+    "13. Commit history → smart_log (NOT git log — structured with categories)",
+    "14. Module architecture → module_info (deps, dependents, public API)",
+    "15. Read markdown/yaml/json/csv section → read_section (loads one heading/key/row-range, NOT the whole file)",
+    '    - For editing sections: read_for_edit(path, section="Section Name")',
+    "16. Long session / before compaction → session_snapshot (capture goal, decisions, confirmed facts, files, next step as <200 token block)",
+    "    - Budget-constrained? Use smart_read(max_tokens=N) to auto-downgrade output size",
+    "",
+    "USE Read/Grep ONLY for: regex text search → Grep | exact raw content → Read",
+    "",
+    "WORKFLOWS:",
+    "• Explore: project_overview → explore_area → smart_read → read_symbol",
+    "• Edit: smart_read → read_symbol(include_edit_context=true) → Edit → read_diff",
+    "• Docs: smart_read (outline) → read_section → read_for_edit(section=) → Edit → read_diff",
+    "• Refactor: find_usages → read_symbols → read_for_edit → Edit",
+    "• Long session: session_snapshot → compact context → continue with minimal state",
+].join("\n");
+// ---------------------------------------------------------------------------
+// Full profile — all tools including audit (code_audit, find_unused, test_summary)
+// ---------------------------------------------------------------------------
+const MCP_INSTRUCTIONS_FULL = [
     "Token Pilot — token-efficient code reading (saves 60-80% tokens). ALWAYS prefer these tools over Read/cat/grep.",
     "",
     "DECISION RULES — pick the first match:",
@@ -28,11 +109,11 @@ export const MCP_INSTRUCTIONS = [
     "16. Dead code → find_unused (unreferenced symbols across project)",
     "17. Module architecture → module_info (deps, dependents, public API)",
     "18. Read markdown/yaml/json/csv section → read_section (loads one heading/key/row-range, NOT the whole file)",
-    '   - For editing sections: read_for_edit(path, section="Section Name")',
+    '    - For editing sections: read_for_edit(path, section="Section Name")',
     "19. Long session / before compaction → session_snapshot (capture goal, decisions, confirmed facts, files, next step as <200 token block)",
-    "   - Budget-constrained? Use smart_read(max_tokens=N) to auto-downgrade output size",
+    "    - Budget-constrained? Use smart_read(max_tokens=N) to auto-downgrade output size",
     "",
-    "USE DEFAULT TOOLS ONLY FOR: regex text search → Grep | exact raw content → Read | non-code configs → Read",
+    "USE Read/Grep ONLY for: regex text search → Grep | exact raw content → Read | non-code configs → Read",
     "",
     "WORKFLOWS:",
     "• Explore: project_overview → explore_area → smart_read → read_symbol",
@@ -42,6 +123,28 @@ export const MCP_INSTRUCTIONS = [
     "• Audit: code_audit + find_unused + Grep (for regex patterns)",
     "• Long session: session_snapshot → compact context → continue with minimal state",
 ].join("\n");
+/**
+ * Select MCP instructions for the given tool profile.
+ * Each profile only mentions tools that are actually advertised in its
+ * tools/list — prevents the agent from calling tools it can't see.
+ */
+export function getMcpInstructions(profile) {
+    switch (profile) {
+        case "minimal":
+            return MCP_INSTRUCTIONS_MINIMAL;
+        case "nav":
+            return MCP_INSTRUCTIONS_NAV;
+        case "edit":
+            return MCP_INSTRUCTIONS_EDIT;
+        case "full":
+            return MCP_INSTRUCTIONS_FULL;
+    }
+}
+/**
+ * @deprecated Use getMcpInstructions(profile) instead.
+ * Kept for backward-compat — resolves to the full profile instructions.
+ */
+export const MCP_INSTRUCTIONS = MCP_INSTRUCTIONS_FULL;
 export const TOOL_DEFINITIONS = [
     // --- Core reading tools ---
     {

package/dist/server/tool-profiles.d.ts

@@ -21,7 +21,7 @@
  * Selection: TOKEN_PILOT_PROFILE=nav|edit|full env var. Unknown values
  * fall back to full with a stderr warning. Silent on missing env.
  */
-export type ToolProfile = "full" | "nav" | "edit";
+export type ToolProfile = "full" | "nav" | "edit" | "minimal";
 export declare const PROFILE_NAMES: readonly ToolProfile[];
 /**
  * Meta-tools — diagnostic / self-observation tools that must be visible
@@ -30,6 +30,12 @@ export declare const PROFILE_NAMES: readonly ToolProfile[];
  * would you trust the savings number?
  */
 export declare const META_TOOLS: ReadonlySet<string>;
+/**
+ * Minimal profile — 5 core tools for emergency / context-constrained sessions.
+ * Token overhead: tools/list is tiny; instructions are ~80 tokens vs ~350 for full.
+ * Use TOKEN_PILOT_PROFILE=minimal when the agent's context budget is nearly full.
+ */
+export declare const MINIMAL_TOOLS: ReadonlySet<string>;
 /** Minimum nav profile — exploration only, no editing support. */
 export declare const NAV_TOOLS: ReadonlySet<string>;
 /** Edit profile adds batch reads + edit-preparation tools. */
@@ -48,5 +54,17 @@ export declare function filterToolsByProfile<T extends {
  * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning
  * and fall back to full — we never silently apply a guess.
  */
+/**
+ * Parse the TOKEN_PILOT_PROFILE env value.
+ *
+ * Default changed in v0.30.0: full → edit.
+ * Rationale: 'full' was exposing 22 tools + full instruction set on every
+ * session, burning ~3 k tokens before any work. 'edit' covers 99% of
+ * development workflows (reading + writing code). Switch to 'full' only
+ * when you need audit tools (code_audit, find_unused, test_summary).
+ *
+ * Unknown values fall back to 'edit' with a stderr warning — we never
+ * silently apply a guess.
+ */
 export declare function parseProfileEnv(envValue: string | undefined, warn?: (msg: string) => void): ToolProfile;
 //# sourceMappingURL=tool-profiles.d.ts.map

package/dist/server/tool-profiles.js

@@ -25,6 +25,7 @@ export const PROFILE_NAMES = [
     "full",
     "nav",
     "edit",
+    "minimal",
 ];
 /**
  * Meta-tools — diagnostic / self-observation tools that must be visible
@@ -37,6 +38,18 @@ export const META_TOOLS = new Set([
     "session_budget",
     "session_snapshot",
 ]);
+/**
+ * Minimal profile — 5 core tools for emergency / context-constrained sessions.
+ * Token overhead: tools/list is tiny; instructions are ~80 tokens vs ~350 for full.
+ * Use TOKEN_PILOT_PROFILE=minimal when the agent's context budget is nearly full.
+ */
+export const MINIMAL_TOOLS = new Set([
+    "smart_read",
+    "read_symbol",
+    "find_usages",
+    "smart_diff",
+    "smart_log",
+]);
 /** Minimum nav profile — exploration only, no editing support. */
 export const NAV_TOOLS = new Set([
     "smart_read",
@@ -49,6 +62,7 @@ export const NAV_TOOLS = new Set([
     "explore_area",
     "smart_log",
     "smart_diff",
+    "read_section", // v0.30.0: section reading is nav-class (read-only, no edit prep)
 ]);
 /** Edit profile adds batch reads + edit-preparation tools. */
 export const EDIT_EXTRAS = new Set([
@@ -73,6 +87,11 @@ export function filterToolsByProfile(tools, profile) {
     // session_snapshot are the instruments for verifying the profile is
     // doing its job. Hiding them would turn "did this save tokens?" into
     // a guess.
+    if (profile === "minimal") {
+        // Minimal: 5 core tools only. META excluded — keep the footprint tiny.
+        // The agent can still call session_analytics by name if it knows it.
+        return tools.filter((t) => MINIMAL_TOOLS.has(t.name));
+    }
     if (profile === "nav") {
         return tools.filter((t) => NAV_TOOLS.has(t.name) || META_TOOLS.has(t.name));
     }
@@ -85,14 +104,29 @@ export function filterToolsByProfile(tools, profile) {
  * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning
  * and fall back to full — we never silently apply a guess.
  */
+/**
+ * Parse the TOKEN_PILOT_PROFILE env value.
+ *
+ * Default changed in v0.30.0: full → edit.
+ * Rationale: 'full' was exposing 22 tools + full instruction set on every
+ * session, burning ~3 k tokens before any work. 'edit' covers 99% of
+ * development workflows (reading + writing code). Switch to 'full' only
+ * when you need audit tools (code_audit, find_unused, test_summary).
+ *
+ * Unknown values fall back to 'edit' with a stderr warning — we never
+ * silently apply a guess.
+ */
 export function parseProfileEnv(envValue, warn = () => { }) {
     if (!envValue)
-        return "full";
+        return "edit";
     const lower = envValue.trim().toLowerCase();
-    if (lower === "full" || lower === "nav" || lower === "edit") {
+    if (lower === "full" ||
+        lower === "nav" ||
+        lower === "edit" ||
+        lower === "minimal") {
         return lower;
     }
-    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit. Falling back to full.`);
-    return "full";
+    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit|minimal. Falling back to edit.`);
+    return "edit";
 }
 //# sourceMappingURL=tool-profiles.js.map

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type EnforcementMode } from "./server/enforcement-mode.js";
 export declare function createServer(projectRoot: string, options?: {
     skipAstIndex?: boolean;
+    enforcementMode?: EnforcementMode;
 }): Promise<Server<{
     method: string;
     params?: {

package/dist/server.js

@@ -45,11 +45,13 @@ import { detectContextMode } from "./integration/context-mode-detector.js";
 import { estimateTokens } from "./core/token-estimator.js";
 import { checkPolicy, isFullReadTool } from "./core/policy-engine.js";
 import { appendToolCall } from "./core/tool-call-log.js";
-import { MCP_INSTRUCTIONS, TOOL_DEFINITIONS, } from "./server/tool-definitions.js";
+import { getMcpInstructions, TOOL_DEFINITIONS, } from "./server/tool-definitions.js";
 import { filterToolsByProfile, parseProfileEnv, } from "./server/tool-profiles.js";
+import { STRICT_SMART_READ_MAX_TOKENS, STRICT_EXPLORE_AREA_INCLUDE, } from "./server/enforcement-mode.js";
 import { createTokenEstimates } from "./server/token-estimates.js";
 import { validateSmartReadArgs, validateReadSymbolArgs, validateReadSymbolsArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, validateReadSectionArgs, } from "./core/validation.js";
 export async function createServer(projectRoot, options) {
+    const mode = options?.enforcementMode ?? "deny";
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
         binaryPath: config.astIndex.binaryPath,
@@ -193,7 +195,6 @@ export async function createServer(projectRoot, options) {
     let fullFileReadsCount = 0;
     let totalCallCount = 0;
     let totalTokensReturned = 0;
-    const readForEditCalled = new Set();
     // Detect context-mode companion
     const cmEnabled = config.contextMode.enabled;
     const contextModeStatus = await detectContextMode(projectRoot, cmEnabled === "auto" ? undefined : cmEnabled);
@@ -238,18 +239,20 @@ export async function createServer(projectRoot, options) {
     catch {
         /* fallback to hardcoded */
     }
+    // v0.26.3 — tool profiles. TOKEN_PILOT_PROFILE=nav|edit|full|minimal
+    // (default: edit since v0.30.0) trims the advertised tools/list payload.
+    // Handlers stay live, so a subagent that explicitly names a filtered-out
+    // tool still gets a response — we just don't brag about every tool upfront.
+    // v0.30.0 — profile also selects matching MCP instructions so the agent
+    // doesn't see rules for tools that aren't in its tools/list.
+    const activeProfile = parseProfileEnv(process.env.TOKEN_PILOT_PROFILE, (m) => process.stderr.write(m + "\n"));
     const server = new Server({ name: "token-pilot", version: pkgVersion }, {
         capabilities: { tools: {} },
-        instructions: MCP_INSTRUCTIONS,
+        instructions: getMcpInstructions(activeProfile),
     });
-    // v0.26.3 — tool profiles. TOKEN_PILOT_PROFILE=nav|edit|full (default
-    // full) trims the advertised tools/list payload. Handlers stay live,
-    // so a subagent that explicitly names a filtered-out tool still gets
-    // a response — we just don't brag about every tool upfront.
-    const activeProfile = parseProfileEnv(process.env.TOKEN_PILOT_PROFILE, (m) => process.stderr.write(m + "\n"));
     const advertisedTools = filterToolsByProfile(TOOL_DEFINITIONS, activeProfile);
-    if (activeProfile !== "full") {
-        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools. Unset TOKEN_PILOT_PROFILE for the full set.\n`);
+    if (activeProfile !== "edit") {
+        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools. Set TOKEN_PILOT_PROFILE=edit for the default set.\n`);
     }
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: advertisedTools,
@@ -289,14 +292,10 @@ export async function createServer(projectRoot, options) {
         if (isFullReadTool(rest.tool)) {
             fullFileReadsCount++;
         }
-        if (rest.tool === "read_for_edit" && call.path) {
-            readForEditCalled.add(call.path);
-        }
         // Policy check
         const advisory = checkPolicy(config.policies, rest.tool, {
             fullFileReadsCount,
             tokensReturned: rest.tokensReturned,
-            readForEditCalled,
             totalCallCount,
             totalTokensReturned,
         });
@@ -331,6 +330,14 @@ export async function createServer(projectRoot, options) {
             switch (name) {
                 case "smart_read": {
                     const validArgs = validateSmartReadArgs(args);
+                    // v0.30.0 strict mode: cap max_tokens when caller didn't set it.
+                    let strictReadCapNote;
+                    if (mode === "strict" && validArgs.max_tokens === undefined) {
+                        validArgs.max_tokens = STRICT_SMART_READ_MAX_TOKENS;
+                        strictReadCapNote =
+                            `\n\n[token-pilot strict] Output capped at ${STRICT_SMART_READ_MAX_TOKENS} tokens ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass max_tokens explicitly to override.`;
+                    }
                     const picked = pickRegistry(args);
                     // Try non-code handler for JSON/YAML/MD etc.
                     if (isNonCodeStructured(validArgs.path)) {
@@ -373,8 +380,9 @@ export async function createServer(projectRoot, options) {
                         absPath: resolve(projectRoot, validArgs.path),
                         args: validArgs,
                     });
-                    if (policyAdv)
-                        result.content[0] = { type: "text", text: text + policyAdv };
+                    const srSuffix = (policyAdv ?? "") + (strictReadCapNote ?? "");
+                    if (srSuffix)
+                        result.content[0] = { type: "text", text: text + srSuffix };
                     return result;
                 }
                 case "read_symbol": {
@@ -527,6 +535,15 @@ export async function createServer(projectRoot, options) {
                 }
                 case "find_usages": {
                     const usagesArgs = validateFindUsagesArgs(args);
+                    // v0.30.0 strict mode: default mode to "list" when caller didn't set it.
+                    // Injected before cache lookup so the key matches strict-mode cached results.
+                    let strictFuNote;
+                    if (mode === "strict" && usagesArgs.mode === undefined) {
+                        usagesArgs.mode = "list";
+                        strictFuNote =
+                            `\n\n[token-pilot strict] find_usages mode defaulted to "list" ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass mode explicitly to override.`;
+                    }
                     const cachedUsages = sessionCache?.get("find_usages", usagesArgs);
                     if (cachedUsages) {
                         recordWithTrace({
@@ -558,6 +575,12 @@ export async function createServer(projectRoot, options) {
                         savingsCategory: "compression",
                         args: usagesArgs,
                     });
+                    if (strictFuNote && usagesResult.content[0]) {
+                        usagesResult.content[0] = {
+                            type: "text",
+                            text: usagesText + strictFuNote,
+                        };
+                    }
                     return usagesResult;
                 }
                 case "project_overview": {
@@ -801,6 +824,15 @@ export async function createServer(projectRoot, options) {
                 }
                 case "explore_area": {
                     const eaArgs = validateExploreAreaArgs(args);
+                    // v0.30.0 strict mode: default include to outline-only when caller didn't set it.
+                    // Injected before cache lookup so the key matches strict-mode cached results.
+                    let strictEaCapNote;
+                    if (mode === "strict" && eaArgs.include === undefined) {
+                        eaArgs.include = STRICT_EXPLORE_AREA_INCLUDE;
+                        strictEaCapNote =
+                            `\n\n[token-pilot strict] include defaulted to ["outline"] ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass include explicitly to override.`;
+                    }
                     const cachedEa = sessionCache?.get("explore_area", eaArgs);
                     if (cachedEa) {
                         recordWithTrace({
@@ -833,10 +865,24 @@ export async function createServer(projectRoot, options) {
                         savingsCategory: "compression",
                         args: eaArgs,
                     });
+                    if (strictEaCapNote && eaResult.content[0]) {
+                        eaResult.content[0] = {
+                            type: "text",
+                            text: eaText + strictEaCapNote,
+                        };
+                    }
                     return eaResult;
                 }
                 case "smart_log": {
                     const slArgs = validateSmartLogArgs(args);
+                    // v0.30.0 strict mode: bound count to 20 when caller didn't set it.
+                    let strictSlNote;
+                    if (mode === "strict" && slArgs.count === undefined) {
+                        slArgs.count = 20;
+                        strictSlNote =
+                            `\n\n[token-pilot strict] smart_log count defaulted to 20 ` +
+                                `(TOKEN_PILOT_MODE=strict). Pass count explicitly to override.`;
+                    }
                     const slResult = await handleSmartLog(slArgs, projectRoot);
                     const slText = slResult.content[0]?.text ?? "";
                     const slTokens = estimateTokens(slText);
@@ -849,6 +895,12 @@ export async function createServer(projectRoot, options) {
                         savingsCategory: "compression",
                         args: slArgs,
                     });
+                    if (strictSlNote && slResult.content[0]) {
+                        slResult.content[0] = {
+                            type: "text",
+                            text: slText + strictSlNote,
+                        };
+                    }
                     return { content: slResult.content };
                 }
                 case "test_summary": {

package/docs/agents.md

@@ -0,0 +1,82 @@
+# tp-* Subagents (Claude Code only)
+
+`tp-*` subagents are a Claude Code feature. Other clients get the MCP tools + hooks but cannot invoke subagents. Each agent carries an explicit `model:` field in its frontmatter; the budget is enforced post-response — overshoots beyond 10% land in `.token-pilot/over-budget.log`.
+
+## Installation
+
+```bash
+npx token-pilot install-agents --scope=user            # all projects
+npx token-pilot install-agents --scope=project         # this repo only
+npx token-pilot install-agents --scope=user --force    # re-apply after an update
+npx token-pilot uninstall-agents --scope=user|project
+```
+
+`init` offers to install these; to add them to another project run `npx token-pilot install-agents`.
+
+## Tier 1 — Workhorses (invoke proactively)
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-run` | General MCP-first workhorse; use when no specialised agent fits | 800 |
+| `tp-onboard` | Orient to an unfamiliar repo (layout, entry points, modules) | 600 |
+| `tp-pr-reviewer` | Review a diff / PR / changeset; verdict-first, Critical/Important tiers | 600 |
+| `tp-impact-analyzer` | Trace blast-radius of a change (callers, transitive deps) | 400 |
+| `tp-refactor-planner` | Plan a refactor with exact edit context per step | 500 |
+| `tp-test-triage` | Investigate test failures → root cause → minimal fix | 500 |
+
+## Tier 2 — Specialists
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-debugger` | Stack trace / error → root-cause line via call-tree traversal | 700 |
+| `tp-migration-scout` | Pre-migration impact map grouped by effort class | 800 |
+| `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 |
+
+## Tier 3 — Combo / Workflow
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-review-impact` | Pre-merge blast-radius review (diff × dependents × API surface) | 700 |
+| `tp-test-coverage-gapper` | Find symbols with zero test references, prioritised | 500 |
+| `tp-api-surface-tracker` | Public API diff vs last release → MAJOR / MINOR / PATCH verdict | 600 |
+| `tp-dep-health` | Dep audit: stale × heavily-used × removable | 600 |
+| `tp-incident-timeline` | Correlate an incident window with commits, rank likely culprits | 700 |
+
+## Tier 4 — Methodology
+
+| Agent | When to invoke | Budget |
+|-------|---------------|-------:|
+| `tp-context-engineer` | Audit / write CLAUDE.md / AGENTS.md rules files per project | 800 |
+| `tp-spec-writer` | Pre-code spec with gated workflow; surfaces assumptions before code | 900 |
+| `tp-performance-profiler` | Measure → identify → fix → verify → guard; refuses to optimise without data | 800 |
+| `tp-incremental-builder` | Multi-file feature work in thin vertical slices, test between each | 900 |
+| `tp-doc-writer` | ADRs + READMEs + API docs; documents *why* not *what* | 700 |
+| `tp-ship-coordinator` | 5-pillar pre-launch checklist (quality / security / observability / rollback / rollout) | 800 |
+
+## Model Tiers
+
+Every agent carries an explicit `model:` field:
+
+| Model | Count | Used for |
+|-------|------:|---------|
+| `haiku` | 9 | Structured / format-bound output (commit messages, onboarding maps, ADRs, session briefings) |
+| `sonnet` | 15 | Reasoning tasks (review, debug, test, plan, audit, spec, profile, ship) |
+| `inherit` | 1 | Deep correlation needing the main thread's model (`tp-incident-timeline`) |
+
+Under Opus 4.7's +35% tokenizer tax, keeping the majority of agent spawns on haiku/sonnet saves 5–10× model cost vs an all-Opus baseline.
+
+## Third-party Agent Integration (bless-agents)
+
+For third-party agents (e.g. `acc-*` plugins) whose tool allowlist excludes token-pilot MCP:
+
+```bash
+npx token-pilot bless-agents       # add token-pilot MCP to project-level overrides
+npx token-pilot unbless-agents <name>... | --all
+```
+
+`doctor` warns when the original agent has changed since blessing.

package/docs/configuration.md

@@ -0,0 +1,117 @@
+# Configuration & Tool Profiles
+
+## .token-pilot.json
+
+Drop `.token-pilot.json` in your project root. All fields are optional.
+
+```json
+{
+  "hooks": { "mode": "deny-enhanced", "denyThreshold": 300 },
+  "sessionStart": { "enabled": true, "showStats": false, "maxReminderTokens": 250 },
+  "agents": { "scope": null, "reminder": true },
+  "smartRead": { "smallFileThreshold": 200 },
+  "cache": { "maxSizeMB": 100, "watchFiles": true },
+  "policies": { "maxFullFileReads": 10, "largeReadThreshold": 2000 },
+  "astIndex": { "binaryPath": null },
+  "updates": { "checkOnStartup": true, "autoUpdate": false },
+  "ignore": ["node_modules/**", "dist/**", ".git/**"]
+}
+```
+
+| Option | Default | What it does |
+|--------|---------|--------------|
+| `hooks.mode` | `"deny-enhanced"` | Read hook mode: `off` / `advisory` / `deny-enhanced` |
+| `hooks.denyThreshold` | `300` | Line count above which the hook intervenes on unbounded `Read` |
+| `sessionStart.enabled` | `true` | Re-inject MCP-rules reminder at every new session / `/clear` / `/compact` |
+| `agents.scope` | `null` | Persisted scope of last `install-agents` run; reused silently |
+| `agents.reminder` | `true` | Show the "agents not installed" startup nudge |
+| `smartRead.smallFileThreshold` | `200` | Files with fewer lines bypass AST overhead and are returned in full |
+| `cache.maxSizeMB` | `100` | File cache ceiling (LRU eviction) |
+| `policies.maxFullFileReads` | `10` | Warn after N full-file reads in session |
+| `policies.largeReadThreshold` | `2000` | Token threshold above which a read is flagged as "large" in analytics |
+
+## Tool Profiles
+
+Trim the advertised `tools/list` to save ~2 k tokens per session. Set via `TOKEN_PILOT_PROFILE` in your MCP server env block.
+
+| Profile | Tools | ~Tokens | Use when |
+|---------|------:|--------:|----------|
+| `full` *(default)* | 22 | ~4 150 | All capabilities |
+| `edit` | 16 | ~3 120 | Code-change workflows (nav + batch reads + `read_for_edit`) |
+| `nav` | 10 | ~1 910 | Read-only exploration / subagents that only navigate |
+
+Handlers remain active regardless of profile — a subagent that explicitly names a filtered-out tool still gets served. The profile only controls what appears in `tools/list` at session start.
+
+### Setting a profile
+
+**In `.mcp.json`:**
+```json
+{
+  "mcpServers": {
+    "token-pilot": {
+      "command": "npx",
+      "args": ["-y", "token-pilot"],
+      "env": { "TOKEN_PILOT_PROFILE": "nav" }
+    }
+  }
+}
+```
+
+**Via shell:**
+```bash
+TOKEN_PILOT_PROFILE=edit npx token-pilot
+```
+
+## CLI Reference
+
+```bash
+token-pilot                              # start MCP server
+token-pilot init                         # create/merge .mcp.json; prompt about subagents
+token-pilot install-agents [--scope=user|project] [--force]
+token-pilot uninstall-agents --scope=user|project
+token-pilot bless-agents                 # extend third-party agents with token-pilot MCP
+token-pilot unbless-agents <name>... | --all
+token-pilot install-hook                 # install PreToolUse hooks
+token-pilot uninstall-hook
+token-pilot stats                        # totals + top files from hook-events.jsonl
+token-pilot stats --session[=<id>] | --by-agent
+token-pilot tool-audit                   # per-tool savings distribution
+token-pilot tool-audit --json
+token-pilot doctor                       # diagnostics (ast-index, config, upstream drift)
+token-pilot doctor --check=env           # env var check only
+token-pilot install-ast-index            # download ast-index binary (auto on first run)
+```
+
+## Architecture
+
+```
+src/
+  index.ts              — CLI entry + MCP server bootstrap
+  server.ts             — MCP server: 22 tool definitions + enforcement mode
+  server/
+    enforcement-mode.ts — TOKEN_PILOT_MODE parsing (advisory / deny / strict)
+  ast-index/            — ast-index binary client + auto-install
+  core/
+    event-log.ts        — hook-events.jsonl + rotation + retention
+    session-analytics.ts, policy-engine.ts, intent-classifier.ts
+  hooks/
+    installer.ts        — hook install/uninstall for Claude Code
+    pre-bash.ts         — PreToolUse:Bash advisor (Bash/sh/eval/loop patterns)
+    pre-grep.ts         — PreToolUse:Grep advisor (symbol-like pattern detection)
+    session-start.ts    — SessionStart reminder handler
+    summary-pipeline.ts — ast-index → regex → head+tail → pass-through
+  cli/
+    install-agents.ts, uninstall-agents.ts
+    bless-agents.ts, unbless-agents.ts, doctor-drift.ts
+    stats.ts, tool-audit.ts
+  templates/agent-builder.ts
+  config/loader.ts, defaults.ts
+  handlers/             — 22 MCP tool handlers
+  git/                  — HEAD + file watchers (cache invalidation)
+
+scripts/
+  build-agents.mjs      — render templates/ → dist/agents/
+  bench-hook.mjs        — hook latency benchmark
+
+templates/agents/       — source for tp-* family + shared preamble + contract
+```