token-pilot 0.28.3 → 0.30.0

package/dist/core/policy-engine.js

@@ -5,7 +5,6 @@
  */
 export const DEFAULT_POLICIES = {
     preferCheapReads: true,
-    requireReadForEditBeforeEdit: true,
     cacheProjectOverview: true,
     maxFullFileReads: 10,
     warnOnLargeReads: true,
@@ -14,14 +13,11 @@ export const DEFAULT_POLICIES = {
     compactionTokenThreshold: 8000,
 };
 /** Full-file read tools that count toward maxFullFileReads */
-const FULL_READ_TOOLS = new Set([
-    'smart_read',
-    'smart_read_many',
-]);
+const FULL_READ_TOOLS = new Set(["smart_read", "smart_read_many"]);
 /** Tools that indicate a cheaper alternative may exist */
 const EXPENSIVE_TOOLS = {
-    smart_read: 'Consider read_symbol() or read_range() for targeted reads',
-    smart_read_many: 'Consider reading files individually with read_symbol()',
+    smart_read: "Consider read_symbol() or read_range() for targeted reads",
+    smart_read_many: "Consider reading files individually with read_symbol()",
 };
 /**
  * Check policy rules and return advisory messages.
@@ -33,7 +29,7 @@ export function checkPolicy(policy, tool, context) {
         FULL_READ_TOOLS.has(tool) &&
         context.fullFileReadsCount >= policy.maxFullFileReads) {
         return {
-            level: 'warn',
+            level: "warn",
             message: `POLICY: ${context.fullFileReadsCount} full-file reads this session (limit: ${policy.maxFullFileReads}). Consider read_symbol() or read_range() for targeted access.`,
         };
     }
@@ -41,7 +37,7 @@ export function checkPolicy(policy, tool, context) {
     if (policy.warnOnLargeReads &&
         context.tokensReturned > policy.largeReadThreshold) {
         return {
-            level: 'info',
+            level: "info",
             message: `POLICY: Large response (~${context.tokensReturned} tokens). Future reads on this file: use read_symbol() or read_range() for targeted access.`,
         };
     }
@@ -50,29 +46,18 @@ export function checkPolicy(policy, tool, context) {
         // Only advise when token count is high enough to matter
         if (context.tokensReturned > 500) {
             return {
-                level: 'info',
+                level: "info",
                 message: `POLICY: ${EXPENSIVE_TOOLS[tool]}`,
             };
         }
     }
-    // 4. Require read_for_edit before edit
-    if (policy.requireReadForEditBeforeEdit &&
-        tool === 'edit' &&
-        context.editTargetPath &&
-        context.readForEditCalled &&
-        !context.readForEditCalled.has(context.editTargetPath)) {
-        return {
-            level: 'info',
-            message: `POLICY: Consider using read_for_edit("${context.editTargetPath}") before editing to get precise edit context.`,
-        };
-    }
-    // 5. Session compaction advisory — by call count
+    // 4. Session compaction advisory — by call count
     if (policy.compactionCallThreshold > 0 &&
         context.totalCallCount !== undefined &&
         context.totalCallCount > 0 &&
         context.totalCallCount % policy.compactionCallThreshold === 0) {
         return {
-            level: 'info',
+            level: "info",
             message: `COMPACTION: ${context.totalCallCount} tool calls this session. Consider calling session_snapshot() to capture state, then compact context.`,
         };
     }
@@ -84,7 +69,7 @@ export function checkPolicy(policy, tool, context) {
         context.totalCallCount % 5 === 0 // don't spam every call, check every 5th
     ) {
         return {
-            level: 'info',
+            level: "info",
             message: `COMPACTION: ~${context.totalTokensReturned} tokens returned this session. Consider calling session_snapshot() to capture state, then compact context.`,
         };
     }

package/dist/hooks/pre-bash.d.ts

@@ -24,6 +24,7 @@
  * `bash -c`, heredocs, or eval'd strings slip through. Acceptable for
  * v0.28.0; tighten only if tool-audit shows repeated escapes.
  */
+import type { EnforcementMode } from "../server/enforcement-mode.js";
 export interface PreBashInput {
     tool_name?: string;
     tool_input?: {
@@ -37,7 +38,18 @@ export type PreBashDecision = {
     kind: "deny";
     reason: string;
 };
+/**
+ * v0.29.0 — expose wrapped commands. Opus 4.7's v0.28.2 verification
+ * report showed escape patterns: `bash -c "cat src/foo.ts"`,
+ * `eval "..."`, `for f in *.ts; do cat $f; done` all slipped through
+ * our heuristics because the dangerous call sat inside quotes / a loop
+ * body. Unwrap those before matching.
+ *
+ * Returns the original command PLUS the extracted inner body for each
+ * wrapper found. Duplication is fine — detectHeavyPattern is pure.
+ */
+export declare function extractWrappedCommands(command: string): string[];
 export declare function detectHeavyPattern(command: string): PreBashDecision;
-export declare function decidePreBash(input: PreBashInput): PreBashDecision;
+export declare function decidePreBash(input: PreBashInput, mode?: EnforcementMode): PreBashDecision;
 export declare function renderPreBashOutput(decision: PreBashDecision): string | null;
 //# sourceMappingURL=pre-bash.d.ts.map

package/dist/hooks/pre-bash.js

@@ -32,7 +32,60 @@ function invokes(command, utility) {
     const re = new RegExp(`(^|[;&|\\n]\\s*)${utility}(\\s|$)`, "m");
     return re.test(command);
 }
+/**
+ * v0.29.0 — expose wrapped commands. Opus 4.7's v0.28.2 verification
+ * report showed escape patterns: `bash -c "cat src/foo.ts"`,
+ * `eval "..."`, `for f in *.ts; do cat $f; done` all slipped through
+ * our heuristics because the dangerous call sat inside quotes / a loop
+ * body. Unwrap those before matching.
+ *
+ * Returns the original command PLUS the extracted inner body for each
+ * wrapper found. Duplication is fine — detectHeavyPattern is pure.
+ */
+export function extractWrappedCommands(command) {
+    const out = [command];
+    // bash -c "..." / sh -c "..." / zsh -c "..."
+    for (const shell of ["bash", "sh", "zsh"]) {
+        const re = new RegExp(`\\b${shell}\\s+-c\\s+(?:"([^"]+)"|'([^']+)')`, "g");
+        for (const m of command.matchAll(re)) {
+            const inner = m[1] ?? m[2];
+            if (inner)
+                out.push(inner);
+        }
+    }
+    // eval "..." / eval '...'
+    for (const m of command.matchAll(/\beval\s+(?:"([^"]+)"|'([^']+)')/g)) {
+        const inner = m[1] ?? m[2];
+        if (inner)
+            out.push(inner);
+    }
+    // for LOOP with body: `for X in Y; do BODY; done` — extract BODY
+    // Also covers `while COND; do BODY; done` and `until COND; do BODY; done`
+    for (const m of command.matchAll(/\b(?:for|while|until)\b[^;]*;\s*do\s+(.+?)\s*;?\s*done\b/gs)) {
+        const body = m[1];
+        if (body)
+            out.push(body);
+    }
+    return out;
+}
 export function detectHeavyPattern(command) {
+    const cmd = command.trim();
+    if (!cmd)
+        return { kind: "allow" };
+    // v0.29.0: check each of the original + any unwrapped inner commands.
+    // First deny wins.
+    const candidates = extractWrappedCommands(cmd);
+    if (candidates.length > 1) {
+        // Check only the unwrapped inners; the original is handled below.
+        for (let i = 1; i < candidates.length; i++) {
+            const inner = detectHeavyPatternSingle(candidates[i]);
+            if (inner.kind === "deny")
+                return inner;
+        }
+    }
+    return detectHeavyPatternSingle(cmd);
+}
+function detectHeavyPatternSingle(command) {
     const cmd = command.trim();
     if (!cmd)
         return { kind: "allow" };
@@ -90,7 +143,9 @@ export function detectHeavyPattern(command) {
     }
     return { kind: "allow" };
 }
-export function decidePreBash(input) {
+export function decidePreBash(input, mode = "deny") {
+    if (mode === "advisory")
+        return { kind: "allow" };
     if (input.tool_name !== "Bash")
         return { kind: "allow" };
     const cmd = input.tool_input?.command;

package/dist/hooks/pre-grep.d.ts

@@ -20,6 +20,7 @@
  * find_usages after the block, we keep it. If they bypass via `-E` or
  * raw shell, we soften to advisory.
  */
+import type { EnforcementMode } from "../server/enforcement-mode.js";
 export interface PreGrepInput {
     tool_name?: string;
     tool_input?: {
@@ -51,7 +52,7 @@ export declare function isSymbolLikePattern(pattern: string): boolean;
  * Pure decision function. Given a PreToolUse hook input for Grep,
  * return whether to allow or deny (with a suggestion).
  */
-export declare function decidePreGrep(input: PreGrepInput): PreGrepDecision;
+export declare function decidePreGrep(input: PreGrepInput, mode?: EnforcementMode): PreGrepDecision;
 /**
  * Render the Claude Code hook JSON response.
  */

package/dist/hooks/pre-grep.js

@@ -64,7 +64,9 @@ export function isSymbolLikePattern(pattern) {
  * Pure decision function. Given a PreToolUse hook input for Grep,
  * return whether to allow or deny (with a suggestion).
  */
-export function decidePreGrep(input) {
+export function decidePreGrep(input, mode = "deny") {
+    if (mode === "advisory")
+        return { kind: "allow" };
     if (input.tool_name !== "Grep")
         return { kind: "allow" };
     const pattern = input.tool_input?.pattern;

package/dist/index.js

@@ -52,6 +52,7 @@ import { assessClaudeMd } from "./cli/claudemd-hygiene.js";
 import { decidePostBashAdvice, renderPostBashHookOutput, } from "./hooks/post-bash.js";
 import { decidePreBash, renderPreBashOutput } from "./hooks/pre-bash.js";
 import { decidePreGrep, renderPreGrepOutput } from "./hooks/pre-grep.js";
+import { parseEnforcementMode } from "./server/enforcement-mode.js";
 const execFileAsync = promisify(execFile);
 export const CODE_EXTENSIONS = new Set([
     "ts",
@@ -152,7 +153,7 @@ export async function main(cliArgs = process.argv.slice(2)) {
             try {
                 const stdin = readFileSync(0, "utf-8");
                 const input = JSON.parse(stdin);
-                const decision = decidePreBash(input);
+                const decision = decidePreBash(input, parseEnforcementMode(process.env.TOKEN_PILOT_MODE));
                 const rendered = renderPreBashOutput(decision);
                 if (rendered)
                     process.stdout.write(rendered);
@@ -169,7 +170,7 @@ export async function main(cliArgs = process.argv.slice(2)) {
             try {
                 const stdin = readFileSync(0, "utf-8");
                 const input = JSON.parse(stdin);
-                const decision = decidePreGrep(input);
+                const decision = decidePreGrep(input, parseEnforcementMode(process.env.TOKEN_PILOT_MODE));
                 const rendered = renderPreGrepOutput(decision);
                 if (rendered)
                     process.stdout.write(rendered);
@@ -386,6 +387,7 @@ export async function startServer(cliArgs = process.argv.slice(2)) {
     });
     const server = await createServer(projectRoot, {
         skipAstIndex: isDangerousRoot(projectRoot),
+        enforcementMode: parseEnforcementMode(process.env.TOKEN_PILOT_MODE),
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/server/enforcement-mode.d.ts

@@ -0,0 +1,47 @@
+/**
+ * v0.30.0 — TOKEN_PILOT_MODE enforcement modes.
+ *
+ * Controls how aggressively token-pilot blocks heavy native tools and
+ * caps MCP tool output sizes. Three modes:
+ *
+ *   advisory  — hooks always allow, no MCP output caps. Observation-only.
+ *               Use when measuring baseline token usage or debugging.
+ *
+ *   deny      — DEFAULT. Hooks deny heavy Bash/Grep patterns and suggest
+ *               cheaper MCP alternatives. No auto-caps on MCP output.
+ *               This is the "smart redirect" mode — the agent learns the
+ *               right tool but can still produce large MCP responses.
+ *
+ *   strict    — deny + MCP output auto-caps. smart_read is capped at
+ *               max_tokens=2000 when the caller doesn't set it; explore_area
+ *               defaults include=['outline'] when the caller doesn't set it.
+ *               Cap values are v0.30.0 initial estimates — tune from real
+ *               tool-audit data in a follow-up PR (#8).
+ *
+ * Set via TOKEN_PILOT_MODE environment variable (case-insensitive, trimmed).
+ * Unknown values fall back to "deny" with a warning.
+ *
+ * Separate from `hooks.mode` (HookMode) which controls only the PreToolUse:Read
+ * hook (deny-enhanced vs advisory for large file reads). TOKEN_PILOT_MODE
+ * covers Bash and Grep hooks plus MCP output caps.
+ */
+export type EnforcementMode = "advisory" | "deny" | "strict";
+export declare const ENFORCEMENT_MODE_NAMES: readonly ["advisory", "deny", "strict"];
+/**
+ * Parse TOKEN_PILOT_MODE from an env-var string. Returns "deny" for
+ * missing or empty values. Emits a warning for unrecognised values.
+ */
+export declare function parseEnforcementMode(raw: string | undefined, warn?: (msg: string) => void): EnforcementMode;
+/**
+ * The cap applied to smart_read max_tokens in strict mode when the
+ * caller has not supplied an explicit max_tokens.
+ * v0.30.0 initial estimate — tune from tool-audit data.
+ */
+export declare const STRICT_SMART_READ_MAX_TOKENS = 2000;
+/**
+ * The include sections applied to explore_area in strict mode when the
+ * caller has not supplied an explicit include array.
+ * v0.30.0 initial estimate — outline-only keeps footprint minimal.
+ */
+export declare const STRICT_EXPLORE_AREA_INCLUDE: Array<"outline" | "imports" | "tests" | "changes">;
+//# sourceMappingURL=enforcement-mode.d.ts.map

package/dist/server/enforcement-mode.js

@@ -0,0 +1,59 @@
+/**
+ * v0.30.0 — TOKEN_PILOT_MODE enforcement modes.
+ *
+ * Controls how aggressively token-pilot blocks heavy native tools and
+ * caps MCP tool output sizes. Three modes:
+ *
+ *   advisory  — hooks always allow, no MCP output caps. Observation-only.
+ *               Use when measuring baseline token usage or debugging.
+ *
+ *   deny      — DEFAULT. Hooks deny heavy Bash/Grep patterns and suggest
+ *               cheaper MCP alternatives. No auto-caps on MCP output.
+ *               This is the "smart redirect" mode — the agent learns the
+ *               right tool but can still produce large MCP responses.
+ *
+ *   strict    — deny + MCP output auto-caps. smart_read is capped at
+ *               max_tokens=2000 when the caller doesn't set it; explore_area
+ *               defaults include=['outline'] when the caller doesn't set it.
+ *               Cap values are v0.30.0 initial estimates — tune from real
+ *               tool-audit data in a follow-up PR (#8).
+ *
+ * Set via TOKEN_PILOT_MODE environment variable (case-insensitive, trimmed).
+ * Unknown values fall back to "deny" with a warning.
+ *
+ * Separate from `hooks.mode` (HookMode) which controls only the PreToolUse:Read
+ * hook (deny-enhanced vs advisory for large file reads). TOKEN_PILOT_MODE
+ * covers Bash and Grep hooks plus MCP output caps.
+ */
+export const ENFORCEMENT_MODE_NAMES = [
+    "advisory",
+    "deny",
+    "strict",
+];
+/**
+ * Parse TOKEN_PILOT_MODE from an env-var string. Returns "deny" for
+ * missing or empty values. Emits a warning for unrecognised values.
+ */
+export function parseEnforcementMode(raw, warn = (m) => process.stderr.write(m + "\n")) {
+    if (!raw || raw.trim() === "")
+        return "deny";
+    const v = raw.trim().toLowerCase();
+    if (v === "advisory" || v === "deny" || v === "strict")
+        return v;
+    warn(`[token-pilot] Unknown TOKEN_PILOT_MODE="${raw}", falling back to "deny". ` +
+        `Valid values: advisory | deny | strict.`);
+    return "deny";
+}
+/**
+ * The cap applied to smart_read max_tokens in strict mode when the
+ * caller has not supplied an explicit max_tokens.
+ * v0.30.0 initial estimate — tune from tool-audit data.
+ */
+export const STRICT_SMART_READ_MAX_TOKENS = 2000;
+/**
+ * The include sections applied to explore_area in strict mode when the
+ * caller has not supplied an explicit include array.
+ * v0.30.0 initial estimate — outline-only keeps footprint minimal.
+ */
+export const STRICT_EXPLORE_AREA_INCLUDE = ["outline"];
+//# sourceMappingURL=enforcement-mode.js.map

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,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 ---
     {
@@ -499,7 +602,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "smart_log",
-        description: "Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref.",
+        description: "Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref. HEADS UP: two verification runs measured this tool at ~39% token reduction (borderline — vs 95-99% for outline/smart_diff). Cumulative data being gathered — tool may be dropped or redesigned in v0.30.0 if numbers don't improve. Prefer scoping with `path` or `count` to tighten savings.",
         inputSchema: {
             type: "object",
             properties: {
@@ -581,7 +684,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "session_budget",
-        description: "Report Read-hook pressure for this session: suppressed tokens so far, reference budget, burn fraction (0..1), and the effective denyThreshold the adaptive curve would apply right now. NOTE: burnFraction measures hook activity, not actual context-window occupancy. Useful to decide when to tighten further before a big read.",
+        description: "META / info-only: reports Read-hook pressure for this session (suppressed tokens, reference budget, burn fraction, effective denyThreshold). Does NOT save tokens itself — this is diagnostic, use to decide when to tighten before a big read. NOTE: burnFraction measures hook activity, not actual context-window occupancy.",
         inputSchema: {
             type: "object",
             properties: {

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