token-pilot 0.29.0 → 0.30.1

package/dist/hooks/pre-bash.js

@@ -141,9 +141,50 @@ function detectHeavyPatternSingle(command) {
                 "or `git diff --stat` / `git diff <path>` to scope. Re-run scoped to bypass.",
         };
     }
+    // 6. Test runners — suggest test_summary. Advisory only (allow + hint):
+    //    tests are legitimate to run; we just want the token-lean summary by
+    //    default. Tool-audit 2026-04-24 showed test_summary = 0 calls across
+    //    three real projects — agents always go straight to the raw runner.
+    if (isTestRunnerCommand(cmd)) {
+        return {
+            kind: "advise",
+            reason: "Running tests via raw command dumps stdout into context. " +
+                'Prefer mcp__token-pilot__test_summary(command="<your runner>") — ' +
+                "returns structured pass/fail/flaky counts and only the failing output, " +
+                "typically 70-90% fewer tokens than raw runner output.",
+        };
+    }
     return { kind: "allow" };
 }
-export function decidePreBash(input) {
+/**
+ * Detect common test-runner invocations. Returns true for anything we'd
+ * route through `test_summary`. Kept as a pure string test so it's unit-
+ * testable without spinning up child processes.
+ */
+export function isTestRunnerCommand(cmd) {
+    const trimmed = cmd.trim();
+    if (!trimmed)
+        return false;
+    // npm/yarn/pnpm run test[:suite], yarn workspace <x> test, etc.
+    if (/\b(?:npm|yarn|pnpm)\s+(?:run\s+)?test(?:[:\s]|$)/.test(trimmed)) {
+        return true;
+    }
+    if (/\byarn\s+workspace\s+\S+\s+test\b/.test(trimmed))
+        return true;
+    // Direct runner invocations (bare or via npx / pnpx / dlx wrappers)
+    if (/\b(?:npx|pnpx|pnpm dlx|yarn dlx)?\s*(?:vitest|jest|mocha|phpunit|rspec|pytest)\b/.test(trimmed)) {
+        return true;
+    }
+    // Go / Cargo native test drivers
+    if (/\bgo\s+test\b/.test(trimmed))
+        return true;
+    if (/\bcargo\s+test\b/.test(trimmed))
+        return true;
+    return false;
+}
+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;
@@ -154,6 +195,15 @@ export function decidePreBash(input) {
 export function renderPreBashOutput(decision) {
     if (decision.kind === "allow")
         return null;
+    if (decision.kind === "advise") {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                additionalContext: decision.reason,
+            },
+        });
+    }
     return JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "PreToolUse",

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

@@ -0,0 +1,69 @@
+/**
+ * v0.30.0 — PreToolUse:Edit/MultiEdit/Write enforcement.
+ *
+ * Background: tool-audit data across three real projects (2026-04-24)
+ * showed Codex calling `read_for_edit` at 33% of its MCP volume while
+ * Claude sat at 0-1% despite our MCP instructions marking it MANDATORY.
+ * Text rules alone don't flip trained agent instincts. The pattern that
+ * did move Claude — pre-grep → find_usages — is hook-based deny.
+ *
+ * This hook closes the gap: before Claude executes Edit/MultiEdit/Write
+ * on an existing code file, we check a shared prep-state file that
+ * read_for_edit updates on every call. If the file isn't prepared we
+ * block (deny) or warn (advisory), depending on TOKEN_PILOT_MODE.
+ *
+ * Scope rules, in order:
+ *   1. Non-code files            → allow (config, markdown, etc.)
+ *   2. Write on non-existent file → allow (new-file creation is fine)
+ *   3. TOKEN_PILOT_BYPASS=1      → allow (escape hatch)
+ *   4. advisory mode             → allow + additionalContext hint
+ *   5. File already prepared     → allow
+ *   6. Otherwise                 → deny with actionable message
+ *
+ * The decide function is pure — no I/O, no process.env reads — so it is
+ * trivially unit-testable. All side effects (existsSync, state read,
+ * enforcement-mode env) are resolved in the thin wrapper before the call.
+ */
+import type { EnforcementMode } from "../server/enforcement-mode.js";
+export interface PreEditInput {
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        [k: string]: unknown;
+    };
+}
+export type PreEditDecision = {
+    kind: "allow";
+} | {
+    kind: "advise";
+    message: string;
+} | {
+    kind: "deny";
+    reason: string;
+};
+export interface PreEditContext {
+    /** Enforcement mode from TOKEN_PILOT_MODE */
+    mode: EnforcementMode;
+    /** File extension is a code file we care about */
+    isCodeFile: boolean;
+    /** The target file already exists on disk */
+    fileExists: boolean;
+    /** read_for_edit was called for this file recently */
+    isPrepared: boolean;
+    /** TOKEN_PILOT_BYPASS=1 set in env */
+    bypassed: boolean;
+}
+/**
+ * Pure decision function. Caller resolves all context (FS, env, state)
+ * beforehand so this stays a deterministic mapping input → decision.
+ */
+export declare function decidePreEdit(input: PreEditInput, ctx: PreEditContext): PreEditDecision;
+/**
+ * Render the Claude Code hook JSON response.
+ *
+ * - allow   → no output (hook passes through with no side-effect)
+ * - advise  → permissionDecision=allow + additionalContext hint
+ * - deny    → permissionDecision=deny + reason
+ */
+export declare function renderPreEditOutput(decision: PreEditDecision): string | null;
+//# sourceMappingURL=pre-edit.d.ts.map

package/dist/hooks/pre-edit.js

@@ -0,0 +1,104 @@
+/**
+ * v0.30.0 — PreToolUse:Edit/MultiEdit/Write enforcement.
+ *
+ * Background: tool-audit data across three real projects (2026-04-24)
+ * showed Codex calling `read_for_edit` at 33% of its MCP volume while
+ * Claude sat at 0-1% despite our MCP instructions marking it MANDATORY.
+ * Text rules alone don't flip trained agent instincts. The pattern that
+ * did move Claude — pre-grep → find_usages — is hook-based deny.
+ *
+ * This hook closes the gap: before Claude executes Edit/MultiEdit/Write
+ * on an existing code file, we check a shared prep-state file that
+ * read_for_edit updates on every call. If the file isn't prepared we
+ * block (deny) or warn (advisory), depending on TOKEN_PILOT_MODE.
+ *
+ * Scope rules, in order:
+ *   1. Non-code files            → allow (config, markdown, etc.)
+ *   2. Write on non-existent file → allow (new-file creation is fine)
+ *   3. TOKEN_PILOT_BYPASS=1      → allow (escape hatch)
+ *   4. advisory mode             → allow + additionalContext hint
+ *   5. File already prepared     → allow
+ *   6. Otherwise                 → deny with actionable message
+ *
+ * The decide function is pure — no I/O, no process.env reads — so it is
+ * trivially unit-testable. All side effects (existsSync, state read,
+ * enforcement-mode env) are resolved in the thin wrapper before the call.
+ */
+/**
+ * Pure decision function. Caller resolves all context (FS, env, state)
+ * beforehand so this stays a deterministic mapping input → decision.
+ */
+export function decidePreEdit(input, ctx) {
+    const toolName = input.tool_name ?? "";
+    if (toolName !== "Edit" && toolName !== "MultiEdit" && toolName !== "Write") {
+        return { kind: "allow" };
+    }
+    const filePath = input.tool_input?.file_path;
+    if (typeof filePath !== "string" || filePath.length === 0) {
+        return { kind: "allow" };
+    }
+    // Non-code files: config, markdown, JSON — Read-based edit-prep doesn't
+    // carry the same value, skip enforcement.
+    if (!ctx.isCodeFile)
+        return { kind: "allow" };
+    // Non-existent files are out of scope for the enforcement:
+    //  - Write on a new file is legitimate new-file creation
+    //  - Edit / MultiEdit on a missing path will error downstream in
+    //    Claude Code itself — nothing for us to add there
+    if (!ctx.fileExists)
+        return { kind: "allow" };
+    // Explicit escape hatch. Documented as TOKEN_PILOT_BYPASS=1.
+    if (ctx.bypassed)
+        return { kind: "allow" };
+    // Already prepared → allow.
+    if (ctx.isPrepared)
+        return { kind: "allow" };
+    const suggestion = `mcp__token-pilot__read_for_edit(path="${filePath}", symbol="<target>")`;
+    // advisory mode: inject a non-blocking hint. The agent still runs the
+    // Edit, but next time should see the pattern.
+    if (ctx.mode === "advisory") {
+        return {
+            kind: "advise",
+            message: `File "${filePath}" was not prepared with read_for_edit. ` +
+                `Consider calling ${suggestion} first — the exact old_string it returns is what Edit actually needs. ` +
+                `Edit built from smart_read / Read snippets frequently mismatches on whitespace.`,
+        };
+    }
+    // deny / strict: hard block with an actionable message.
+    const reason = `File "${filePath}" was not prepared with read_for_edit. ` +
+        `Call ${suggestion} FIRST to obtain the exact old_string for Edit — ` +
+        `this is the canonical flow. Building old_string from smart_read or Read ` +
+        `snippets diverges from disk (whitespace, line-number prefixes) and Edit ` +
+        `silently mismatches. ` +
+        `Escape hatch: set TOKEN_PILOT_BYPASS=1 in the environment, or switch to ` +
+        `TOKEN_PILOT_MODE=advisory for warn-only behaviour.`;
+    return { kind: "deny", reason };
+}
+/**
+ * Render the Claude Code hook JSON response.
+ *
+ * - allow   → no output (hook passes through with no side-effect)
+ * - advise  → permissionDecision=allow + additionalContext hint
+ * - deny    → permissionDecision=deny + reason
+ */
+export function renderPreEditOutput(decision) {
+    if (decision.kind === "allow")
+        return null;
+    if (decision.kind === "advise") {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                additionalContext: decision.message,
+            },
+        });
+    }
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: decision.reason,
+        },
+    });
+}
+//# sourceMappingURL=pre-edit.js.map

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?: {
@@ -31,10 +32,20 @@ export interface PreGrepInput {
 }
 export type PreGrepDecision = {
     kind: "allow";
+} | {
+    kind: "advise";
+    reason: string;
 } | {
     kind: "deny";
     reason: string;
 };
+/**
+ * Shapes that look like TODO / FIXME / HACK / XXX / BUG tag scans —
+ * route these to `code_audit` which returns deduplicated, categorised
+ * results instead of N raw grep hits. Zero code_audit calls across three
+ * projects (tool-audit 2026-04-24) = agents reach for Grep every time.
+ */
+export declare function isTodoScanPattern(pattern: string): boolean;
 /**
  * Heuristic: does `pattern` look like a code identifier worth sending
  * through find_usages?
@@ -51,7 +62,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

@@ -20,6 +20,18 @@
  * find_usages after the block, we keep it. If they bypass via `-E` or
  * raw shell, we soften to advisory.
  */
+/**
+ * Shapes that look like TODO / FIXME / HACK / XXX / BUG tag scans —
+ * route these to `code_audit` which returns deduplicated, categorised
+ * results instead of N raw grep hits. Zero code_audit calls across three
+ * projects (tool-audit 2026-04-24) = agents reach for Grep every time.
+ */
+export function isTodoScanPattern(pattern) {
+    // Strip common grep-alternation syntax to compare the symbol cores
+    const normalised = pattern.replace(/[()\s]/g, "").toUpperCase();
+    const tagRe = /^(TODO|FIXME|HACK|XXX|BUG|NOTE|OPTIMIZE|REFACTOR)(\|(TODO|FIXME|HACK|XXX|BUG|NOTE|OPTIMIZE|REFACTOR))*$/;
+    return tagRe.test(normalised);
+}
 /**
  * Heuristic: does `pattern` look like a code identifier worth sending
  * through find_usages?
@@ -64,13 +76,30 @@ 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 (input.tool_name !== "Grep")
         return { kind: "allow" };
     const pattern = input.tool_input?.pattern;
     if (typeof pattern !== "string" || pattern.length === 0) {
         return { kind: "allow" };
     }
+    // TODO / FIXME / HACK tag scan → route to code_audit. Emitted as an
+    // advisory ("allow" + hint) regardless of enforcement mode: blocking
+    // would frustrate a legitimate one-off scan, but nudging the agent
+    // toward code_audit compounds the benefit across a session.
+    if (isTodoScanPattern(pattern)) {
+        return {
+            kind: "advise",
+            reason: `Grep pattern "${pattern}" is a TODO / FIXME / HACK scan. ` +
+                `Prefer mcp__token-pilot__code_audit — it returns deduplicated, ` +
+                `categorised tags across the project with file/line references, ` +
+                `typically 3-5× fewer tokens than raw Grep and ignores generated/` +
+                `vendored code automatically.`,
+        };
+    }
+    // Advisory mode disables the symbol-like deny (legacy behaviour).
+    if (mode === "advisory")
+        return { kind: "allow" };
     if (!isSymbolLikePattern(pattern))
         return { kind: "allow" };
     const reason = `Grep pattern "${pattern}" looks like a code identifier. ` +
@@ -87,6 +116,15 @@ export function decidePreGrep(input) {
 export function renderPreGrepOutput(decision) {
     if (decision.kind === "allow")
         return null;
+    if (decision.kind === "advise") {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                additionalContext: decision.reason,
+            },
+        });
+    }
     return JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "PreToolUse",

package/dist/index.d.ts

@@ -3,6 +3,18 @@ import type { HookMode } from "./types.js";
 export declare const CODE_EXTENSIONS: Set<string>;
 export declare function getVersion(): string;
 export declare function main(cliArgs?: string[]): Promise<void>;
+/**
+ * Defensive check for the Claude Code plugin `start.sh` bug (fixed 2026-04-24,
+ * but older installs still in the wild). If the caller passed the plugin's own
+ * cache dir as projectRoot, every relative path like `front/src/File.php` gets
+ * resolved inside the plugin install instead of the user's repo (ENOENT).
+ *
+ * Matches the canonical Claude Code plugin cache pattern
+ *   ~/.claude/plugins/cache/token-pilot/token-pilot/<version>/
+ * on both POSIX and Windows separators. Intentionally narrow — does NOT match
+ * dev installs (cloning the repo and running against itself stays legal).
+ */
+export declare function looksLikePluginCacheDir(candidate: string): boolean;
 export declare function startServer(cliArgs?: string[]): Promise<void>;
 export interface HookReadAdaptiveOptions {
     adaptiveThreshold?: boolean;
@@ -16,6 +28,24 @@ export declare function handleHookRead(filePathArg?: string, mode?: HookMode, de
  * wrapping.
  */
 export declare function runHookReadDispatch(filePathArg: string | undefined, mode: HookMode, denyThresholdArg?: number, projectRootArg?: string, adaptive?: HookReadAdaptiveOptions): Promise<string | null>;
+/**
+ * PreToolUse:Edit / MultiEdit / Write enforcement.
+ *
+ * v0.30.0 upgraded this from a passive advisory hint into a real gate.
+ * The previous implementation always returned `allow` + a TIP; Claude
+ * ignored the TIP and kept building Edit's old_string from smart_read
+ * snippets (tool-audit 2026-04-24: read_for_edit = 0-1% of Claude calls
+ * vs 33% for Codex, which gets explicit prompt-level enforcement).
+ *
+ * New behaviour driven by TOKEN_PILOT_MODE:
+ *   - advisory → allow + non-blocking hint when the file wasn't prepped
+ *   - deny     → block when the file wasn't prepped (the default)
+ *   - strict   → same as deny, plus event log for telemetry
+ *
+ * Pure decision logic lives in src/hooks/pre-edit.ts — this wrapper is
+ * responsible only for stdin parsing and I/O-bound context resolution
+ * (file existence, prep-state lookup, env vars).
+ */
 export declare function handleHookEdit(): void;
 export declare function handleInstallHook(projectRoot: string): Promise<void>;
 export declare function handleUninstallHook(projectRoot: string): Promise<void>;

package/dist/index.js

@@ -16,8 +16,8 @@ process.stderr.on("error", (err) => {
     throw err;
 });
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { readFileSync, realpathSync, appendFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, realpathSync, appendFileSync, mkdirSync, } from "node:fs";
+import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -52,6 +52,9 @@ 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 { decidePreEdit, renderPreEditOutput, } from "./hooks/pre-edit.js";
+import { isEditPrepared as isEditPreparedFn } from "./core/edit-prep-state.js";
+import { parseEnforcementMode } from "./server/enforcement-mode.js";
 const execFileAsync = promisify(execFile);
 export const CODE_EXTENSIONS = new Set([
     "ts",
@@ -152,7 +155,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 +172,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);
@@ -292,11 +295,41 @@ export async function main(cliArgs = process.argv.slice(2)) {
             return;
     }
 }
+/**
+ * Defensive check for the Claude Code plugin `start.sh` bug (fixed 2026-04-24,
+ * but older installs still in the wild). If the caller passed the plugin's own
+ * cache dir as projectRoot, every relative path like `front/src/File.php` gets
+ * resolved inside the plugin install instead of the user's repo (ENOENT).
+ *
+ * Matches the canonical Claude Code plugin cache pattern
+ *   ~/.claude/plugins/cache/token-pilot/token-pilot/<version>/
+ * on both POSIX and Windows separators. Intentionally narrow — does NOT match
+ * dev installs (cloning the repo and running against itself stays legal).
+ */
+export function looksLikePluginCacheDir(candidate) {
+    if (!candidate)
+        return false;
+    try {
+        const resolved = resolve(candidate);
+        return /[\\/]plugins[\\/]cache[\\/]token-pilot[\\/]/.test(resolved);
+    }
+    catch {
+        return false;
+    }
+}
 export async function startServer(cliArgs = process.argv.slice(2)) {
-    let projectRoot = cliArgs[0] || process.cwd();
+    // Defensive: ignore a poisoned cliArgs[0] pointing into the plugin install
+    // dir. Fall through to the INIT_CWD / PWD / cwd detection below — same
+    // behaviour as if the argument had never been passed.
+    let explicitRoot = cliArgs[0];
+    if (explicitRoot && looksLikePluginCacheDir(explicitRoot)) {
+        console.error(`[token-pilot] ignoring "${explicitRoot}" — looks like the plugin cache dir (start.sh bug). Auto-detecting project root instead.`);
+        explicitRoot = "";
+    }
+    let projectRoot = explicitRoot || process.cwd();
     // Detect git root for reliable project root
     // Try multiple sources: args[0] → INIT_CWD (npm/npx invoking dir) → PWD → cwd
-    if (!cliArgs[0]) {
+    if (!explicitRoot) {
         const candidates = [
             process.env.INIT_CWD, // npm/npx sets this to invoking directory
             process.env.PWD, // shell working directory (may differ from cwd)
@@ -386,6 +419,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);
@@ -556,34 +590,65 @@ async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, project
         },
     });
 }
+/**
+ * PreToolUse:Edit / MultiEdit / Write enforcement.
+ *
+ * v0.30.0 upgraded this from a passive advisory hint into a real gate.
+ * The previous implementation always returned `allow` + a TIP; Claude
+ * ignored the TIP and kept building Edit's old_string from smart_read
+ * snippets (tool-audit 2026-04-24: read_for_edit = 0-1% of Claude calls
+ * vs 33% for Codex, which gets explicit prompt-level enforcement).
+ *
+ * New behaviour driven by TOKEN_PILOT_MODE:
+ *   - advisory → allow + non-blocking hint when the file wasn't prepped
+ *   - deny     → block when the file wasn't prepped (the default)
+ *   - strict   → same as deny, plus event log for telemetry
+ *
+ * Pure decision logic lives in src/hooks/pre-edit.ts — this wrapper is
+ * responsible only for stdin parsing and I/O-bound context resolution
+ * (file existence, prep-state lookup, env vars).
+ */
 export function handleHookEdit() {
-    // Parse stdin for Edit tool_input
-    let filePath;
+    let input;
     try {
         const stdin = readFileSync(0, "utf-8");
-        const input = JSON.parse(stdin);
-        filePath = input?.tool_input?.file_path;
+        input = JSON.parse(stdin);
     }
     catch {
         process.exit(0);
     }
-    if (!filePath) {
+    const filePath = input.tool_input?.file_path;
+    if (typeof filePath !== "string" || filePath.length === 0) {
         process.exit(0);
     }
+    const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
     const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
-    // Only add context for code files
-    if (!CODE_EXTENSIONS.has(ext)) {
-        process.exit(0);
+    const isCodeFile = CODE_EXTENSIONS.has(ext);
+    const mode = parseEnforcementMode(process.env.TOKEN_PILOT_MODE);
+    const bypassed = process.env.TOKEN_PILOT_BYPASS === "1";
+    // Existence check must be sync + cheap — the hook is on the request hot path.
+    let fileExists = false;
+    try {
+        fileExists = existsSync(filePath);
     }
-    // Add additionalContext suggesting read_for_edit — doesn't block Edit
-    const context = JSON.stringify({
-        hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            permissionDecision: "allow",
-            additionalContext: `TIP: Use read_for_edit("${filePath}", symbol="<name>") to get minimal raw code for Edit's old_string — 97% fewer tokens than Read.`,
-        },
+    catch {
+        // If we can't even stat it, fall back to "does not exist" so Write-on-new
+        // still flows through; Edit on a missing file would error anyway.
+        fileExists = false;
+    }
+    const isPrepared = isCodeFile
+        ? isEditPreparedFn(projectRoot, filePath)
+        : false;
+    const decision = decidePreEdit(input, {
+        mode,
+        isCodeFile,
+        fileExists,
+        isPrepared,
+        bypassed,
     });
-    process.stdout.write(context);
+    const rendered = renderPreEditOutput(decision);
+    if (rendered)
+        process.stdout.write(rendered);
     process.exit(0);
 }
 export async function handleInstallHook(projectRoot) {

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