token-pilot 0.30.0 → 0.30.1

package/dist/hooks/pre-bash.js

@@ -141,8 +141,47 @@ 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" };
 }
+/**
+ * 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" };
@@ -156,6 +195,15 @@ export function decidePreBash(input, mode = "deny") {
 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

@@ -32,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?

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?
@@ -65,14 +77,29 @@ export function isSymbolLikePattern(pattern) {
  * return whether to allow or deny (with a suggestion).
  */
 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;
     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. ` +
@@ -89,6 +116,15 @@ export function decidePreGrep(input, mode = "deny") {
 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,8 @@ 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([
@@ -293,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)
@@ -558,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/tool-definitions.js

@@ -47,6 +47,12 @@ const MCP_INSTRUCTIONS_NAV = [
 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)",
@@ -56,7 +62,7 @@ const MCP_INSTRUCTIONS_EDIT = [
     "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)",
@@ -75,7 +81,7 @@ const MCP_INSTRUCTIONS_EDIT = [
     "",
     "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",
     "• Long session: session_snapshot → compact context → continue with minimal state",
@@ -86,6 +92,12 @@ const MCP_INSTRUCTIONS_EDIT = [
 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)",
@@ -95,7 +107,7 @@ const MCP_INSTRUCTIONS_FULL = [
     "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)",
@@ -117,7 +129,7 @@ const MCP_INSTRUCTIONS_FULL = [
     "",
     "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)",
@@ -580,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: {
@@ -594,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.js

@@ -69,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);
@@ -222,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 {