token-pilot 0.29.0 → 0.30.1

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

@@ -1,6 +1,26 @@
 /**
  * MCP tool definitions and system instructions.
  * Pure static data — no runtime dependencies.
+ *
+ * v0.30.0 — Profile-specific instructions. Each profile advertises only
+ * the tools it includes; instructions are trimmed to match so the agent
+ * doesn't hallucinate tools that aren't in tools/list.
+ *
+ *   minimal — 5 core tools, minimal context overhead
+ *   nav     — 10 exploration tools, no editing
+ *   edit    — nav + 6 edit-prep tools (DEFAULT)
+ *   full    — everything including audit tools
+ */
+import type { ToolProfile } from "./tool-profiles.js";
+/**
+ * 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 declare function getMcpInstructions(profile: ToolProfile): string;
+/**
+ * @deprecated Use getMcpInstructions(profile) instead.
+ * Kept for backward-compat — resolves to the full profile instructions.
  */
 export declare const MCP_INSTRUCTIONS: string;
 export declare const TOOL_DEFINITIONS: ({

package/dist/server/tool-definitions.js

@@ -1,10 +1,58 @@
-/**
- * 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.",
     "",
+    "MANDATORY EDIT SAFETY — before ANY Edit/Write tool call on an existing code file:",
+    "  → FIRST call read_for_edit(path, symbol=<target>) to obtain the exact old_string.",
+    "  → NEVER build Edit's old_string from a smart_read / Read snippet — whitespace and",
+    "    line-number prefixes diverge from disk and Edit silently mismatches.",
+    "  → For a brand-new file, Write is fine; read_for_edit is only required for edits.",
+    "",
     "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)",
@@ -14,7 +62,52 @@ export const MCP_INSTRUCTIONS = [
     "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)",
+    "6. Preparing an Edit → read_for_edit — MANDATORY, not optional. Returns exact 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 (mandatory): smart_read (to pick target) → read_for_edit → 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.",
+    "",
+    "MANDATORY EDIT SAFETY — before ANY Edit/Write tool call on an existing code file:",
+    "  → FIRST call read_for_edit(path, symbol=<target>) to obtain the exact old_string.",
+    "  → NEVER build Edit's old_string from a smart_read / Read snippet — whitespace and",
+    "    line-number prefixes diverge from disk and Edit silently mismatches.",
+    "  → For a brand-new file, Write is fine; read_for_edit is only required for edits.",
+    "",
+    "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 — MANDATORY, not optional. Returns exact 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)",
@@ -28,20 +121,42 @@ 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",
-    "• Edit: smart_read → read_symbol(include_edit_context=true) → Edit → read_diff",
+    "• Edit (mandatory): smart_read (to pick target) → read_for_edit → 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 → test_summary",
     "• 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 ---
     {
@@ -477,7 +592,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "explore_area",
-        description: "One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls.",
+        description: "One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls. Default since v0.30.0 returns only outline+changes — telemetry showed the all-4 default producing negative token reduction for small areas. Opt into imports/tests explicitly via `include` when you need them.",
         inputSchema: {
             type: "object",
             properties: {
@@ -491,7 +606,7 @@ export const TOOL_DEFINITIONS = [
                         type: "string",
                         enum: ["outline", "imports", "tests", "changes"],
                     },
-                    description: "Sections to include (default: all)",
+                    description: 'Sections to include. Default: ["outline","changes"]. Add "imports" for dep graph, "tests" to map test files — both can be heavy on large areas.',
                 },
             },
             required: ["path"],

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,
@@ -67,6 +69,10 @@ export async function createServer(projectRoot, options) {
     // entirely; callers that care about durability should not use it.
     const shutdownFlush = () => {
         void sessionRegistries.flushAll();
+        // Stop the 5-minute ast-index tick so we don't block exit on SIGINT/SIGTERM.
+        // .unref() already makes it non-keeping, but clearing is defensive and
+        // avoids a stray `update` firing during shutdown.
+        astIndex.stopPeriodicUpdate();
     };
     process.once("beforeExit", shutdownFlush);
     process.once("SIGINT", shutdownFlush);
@@ -193,7 +199,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);
@@ -221,13 +226,25 @@ export async function createServer(projectRoot, options) {
             fileWatcher.onAstUpdate(() => sessionCache.invalidateByAst());
         }
     }
-    // Wire session cache to git watcher
-    if (sessionCache) {
-        gitWatcher.onBranchSwitchEvent((changedFiles) => {
+    // Wire git-watcher → session cache + AST index.
+    // Always registers — even without sessionCache — so branch-switch still
+    // triggers the index update. Without this the index went stale on every
+    // `git checkout` until the next file-touch (or never, for branches that
+    // only moved files the agent hadn't read yet).
+    gitWatcher.onBranchSwitchEvent((changedFiles) => {
+        if (sessionCache) {
             sessionCache.invalidateByFiles(changedFiles);
             sessionCache.invalidateByGit();
-        });
-    }
+        }
+        // Fire-and-forget. incrementalUpdate self-guards against
+        // disabled / oversized / uninitialised index states.
+        void astIndex.incrementalUpdate();
+    });
+    // 5-minute safety-net for long sessions where FileWatcher may miss events
+    // (Docker bind mounts, NFS, files mutated by sibling processes). Cheap —
+    // each tick is a single `ast-index update` call that bails early if the
+    // index isn't ready or the previous tick is still running.
+    astIndex.startPeriodicUpdate();
     // Read version from package.json
     let pkgVersion = "0.1.1";
     try {
@@ -238,18 +255,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 +308,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 +346,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 +396,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 +551,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 +591,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 +840,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 +881,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 +911,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.