token-pilot 0.29.0 → 0.30.0

package/agents/tp-onboard.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 4e82f7b3c6446663e958fb6bf5eb5348bbdf33389269c888ce0dab766e50561f
 ---
 

package/agents/tp-performance-profiler.md

@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 8b9f454a47e57e3761668de788850ef97d5d6f127b059cf8e0cef03deaca3f98
 ---
 

package/agents/tp-pr-reviewer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 91003b244472c4e65d840b55474a86ce04fba379859d588cc0fa54850b0e1e4f
 ---
 

package/agents/tp-refactor-planner.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 45f972c6b36929491a529322bac3c34fd44872f7be4a974d25c7e27cb12e9dc3
 ---
 

package/agents/tp-review-impact.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 3c1c66f952ac63a5936bec86fefda8c842fb9713bca81e48ca5bb568ccb5f367
 ---
 

package/agents/tp-run.md

@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: de342efe1e3ee265df1773ebde1241555750ab17de249190a5c1c200f1f8f51a
 ---
 

package/agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: d031f30e9cc4ea454aa256427659ed27249d820b75dc8b9b99c81ba7635230a7
 ---
 

package/agents/tp-ship-coordinator.md

@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 6b1c27b3dc4fad622cebff7c49e079fc764ca0ae57ef5bc4e61b563d8321092d
 ---
 

package/agents/tp-spec-writer.md

@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 4ae44482db80a8a3a43794c6ecb665ec0b5385a274e1e5b2e3a404956075be88
 ---
 

package/agents/tp-test-coverage-gapper.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 6d862d1bcaeda3fb13099f51e40faaaf45d16d7d41d1b938609500192aa606f2
 ---
 

package/agents/tp-test-triage.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: f4e0dcbd2b4e8648efcafc9d53101a66bf394d7c90e97df7581ac47fcfbff5cb
 ---
 

package/agents/tp-test-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.29.0"
+token_pilot_version: "0.30.0"
 token_pilot_body_hash: 960fe9e907e9c7d13b14dcc22af99e8cc7e7335f99791fa808df76ac21e1f5e9
 ---
 

package/dist/cli/tool-audit.d.ts

@@ -22,6 +22,11 @@ export interface ToolAuditRow {
     /** Calls where the recorder claimed NO savings (pass-through) — separate so
      *  they don't poison the reduction average. */
     noneCalls: number;
+    /** Calls where the MCP response was served from the session cache (the model
+     *  replayed cached tokens).  These contribute to `saved` but the mechanism
+     *  is token re-use, not structural compression — useful to split out so the
+     *  "Est.Saved*" column is understood correctly. */
+    cacheHitCalls: number;
     /** True when reduction is below the low-value threshold AND we have enough
      *  samples (≥5) to make a claim — avoids flagging tools after 1 bad run. */
     lowValue: boolean;

package/dist/cli/tool-audit.js

@@ -24,12 +24,15 @@ export function aggregateToolCalls(events, lowValueThreshold = 20, minSamples =
             tokensReturned: 0,
             tokensWouldBe: 0,
             noneCalls: 0,
+            cacheHitCalls: 0,
         };
         row.count++;
         row.tokensReturned += e.tokensReturned;
         row.tokensWouldBe += e.tokensWouldBe;
         if (e.savingsCategory === "none")
             row.noneCalls++;
+        if (e.sessionCacheHit)
+            row.cacheHitCalls++;
         byTool.set(e.tool, row);
     }
     const rows = [];
@@ -47,6 +50,7 @@ export function aggregateToolCalls(events, lowValueThreshold = 20, minSamples =
             saved,
             reductionPct,
             noneCalls: r.noneCalls,
+            cacheHitCalls: r.cacheHitCalls,
             lowValue,
         });
     }
@@ -74,7 +78,7 @@ Run a few MCP tool calls from your AI client, then re-run \`npx token-pilot tool
     lines.push(`Token Pilot — tool audit`);
     lines.push(`  ${opts.totalEvents} calls across ${rows.length} tools (cumulative across sessions)`);
     lines.push("");
-    lines.push("  Tool                     Calls      Saved   Returned  Reduction");
+    lines.push("  Tool                     Calls  Est.Saved*   Returned  Reduction");
     lines.push("  ─────────────────────────────────────────────────────────────────");
     for (const r of rows) {
         const tool = r.tool.padEnd(24);
@@ -91,6 +95,10 @@ Run a few MCP tool calls from your AI client, then re-run \`npx token-pilot tool
         lines.push("Low-value tools flagged above have <20% token reduction across ≥5 calls.");
         lines.push("Consider: check their `none` passthrough count, or whether a cheaper alternative (Grep, Read) would do the job.");
     }
+    lines.push("");
+    lines.push("* Est.Saved is estimated against a full-file read baseline. Actual prompt");
+    lines.push("  savings depend on client caching — use `cacheHitCalls` in --json output");
+    lines.push("  to distinguish structural compression from cache re-use.");
     return lines.join("\n");
 }
 export async function runToolAudit(opts) {

package/dist/core/policy-engine.d.ts

@@ -6,8 +6,6 @@
 export interface PolicyConfig {
     /** Advisory hints when an expensive tool is used where a cheaper alternative exists */
     preferCheapReads: boolean;
-    /** Track if read_for_edit was called before edit (advisory) */
-    requireReadForEditBeforeEdit: boolean;
     /** Always cache project overview in session cache */
     cacheProjectOverview: boolean;
     /** Warn after N full-file reads in a session */
@@ -25,13 +23,11 @@ export declare const DEFAULT_POLICIES: PolicyConfig;
 export interface PolicyCheckContext {
     fullFileReadsCount: number;
     tokensReturned: number;
-    readForEditCalled?: Set<string>;
-    editTargetPath?: string;
     totalCallCount?: number;
     totalTokensReturned?: number;
 }
 export interface PolicyAdvisory {
-    level: 'info' | 'warn';
+    level: "info" | "warn";
     message: string;
 }
 /**

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?: {
@@ -49,6 +50,6 @@ export type PreBashDecision = {
  */
 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

@@ -143,7 +143,9 @@ function detectHeavyPatternSingle(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: ({