vexp-cli 2.3.1 → 2.5.0

package/dist/agent-config.js

@@ -10,7 +10,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import * as crypto from "crypto";
-import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpStopGateHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -320,6 +320,19 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
+            // Event-driven hint hook: default-on (non-blocking, fail-open — the
+            // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
+            const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeStopGate(workspaceRoot, binaryPath);
+            if (hintResult) {
+                results.push({
+                    agent: "Claude Code Hint",
+                    configFile: ".claude/hooks/vexp-hint.sh",
+                    content: vexpHintHookScript(binaryPath),
+                    alreadyExists: false,
+                    action: hintResult,
+                });
+            }
             // Guard is OPT-IN from 2.3 (see GuardMode): strict installs the
             // PreToolUse deny hook; default removes any previously installed one.
             if (guardMode() === "strict") {
@@ -349,6 +362,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.codex/config.toml");
+            installCodexHintHook(workspaceRoot, binaryPath);
         }
         // Antigravity: machine-global MCP config (~/.gemini/antigravity/mcp_config.json)
         if (detector.agent === "Antigravity") {
@@ -376,6 +390,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             // Kilo v7 vendors opencode, so it takes the same guard plugin — the rules
             // markdown alone was demonstrably not enough (a reported session loaded
             // vexp.md, quoted it back, and still read five files by hand).
@@ -437,6 +452,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         // Claude Code PreToolUse hook) — which is only safe once MCP is registered.
         if (detector.agent === "Opencode") {
             const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (wroteMcp)
                 mcpConfigs.push(wroteMcp);
             if (guardMode() === "strict") {
@@ -607,6 +623,8 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
+            installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeStopGate(workspaceRoot, binaryPath);
             if (guardMode() === "strict")
                 installClaudeCodeHook(workspaceRoot);
             else
@@ -616,6 +634,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.codex/config.toml");
+            installCodexHintHook(workspaceRoot, binaryPath);
         }
         if (detector.agent === "Antigravity") {
             const wrote = configureAntigravityGlobal(binaryPath, mcpServerPath);
@@ -636,6 +655,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (guardMode() === "strict")
                 installOpencodePlugin(workspaceRoot);
             else
@@ -655,6 +675,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             if (guardMode() === "strict")
                 installKiloPlugin(workspaceRoot);
             else
@@ -1634,20 +1655,23 @@ export function installClaudeCodeHook(workspaceRoot) {
     const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
     // Aggressively remove ALL vexp-related hook entries (old format, stale matchers, malformed)
     const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
-    // Exec form (`args` present → direct spawn, no `sh -c`): the old shell-form
-    // `$CLAUDE_PROJECT_DIR/...` word-split on project paths containing spaces,
-    // so sh tried to exec the path's first fragment and the guard NEVER ran —
-    // non-blocking failure, every search went through unguarded. In exec form
-    // Claude Code substitutes `${CLAUDE_PROJECT_DIR}` itself (brace form
-    // required) before spawning. `timeout` is SECONDS (default 600), not ms:
-    // 3000 configured a 50-minute hook timeout.
+    // Shell form with an explicit `bash` prefix and a QUOTED path — the one
+    // shape that works on every OS Claude Code supports:
+    //  - the quotes fix the historical spaces bug (unquoted
+    //    `$CLAUDE_PROJECT_DIR/...` word-split and the guard never ran);
+    //  - exec form (`args` present → direct spawn) fixed spaces but broke
+    //    Windows entirely: the OS cannot spawn a `.sh` without a shell, the
+    //    hook errored, failed open, and enforced nothing (field report) —
+    //    Claude Code on Windows runs shell-form hooks through Git Bash, so
+    //    `bash "$VAR"` works there and on unix alike.
+    // `timeout` is SECONDS (default 600), not ms: 3000 once configured a
+    // 50-minute hook timeout.
     filtered.push({
         matcher: "Grep|Glob|Regex",
         hooks: [
             {
                 type: "command",
-                command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/vexp-guard.sh",
-                args: [],
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh"',
                 timeout: 5,
             },
         ],
@@ -1667,6 +1691,206 @@ export function installClaudeCodeHook(workspaceRoot) {
     }
     return existed ? "updated" : "created";
 }
+function isVexpHookEntry(h, needle) {
+    if (!h || typeof h !== "object")
+        return false;
+    const entry = h;
+    if (entry.command?.includes(needle))
+        return true;
+    const hks = entry.hooks;
+    return Array.isArray(hks) && hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        return hook.command?.includes(needle) ?? false;
+    });
+}
+/**
+ * Horizon F2a: install the Stop-hook verification gate for Claude Code.
+ * Same fail-open family as the hint hook: the Rust `stop-gate` command
+ * blocks a stop at most once per session and only on mechanically broken
+ * references (parse errors, imports of removed names). No daemon = no
+ * gate = vanilla stop. Additive like the hint hook, so not guardMode-gated.
+ */
+export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-verify.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    fs.mkdirSync(hookDir, { recursive: true });
+    const script = vexpStopGateHookScript(binaryPath);
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf8") === script;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    }
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok) {
+        warnUnparseable(settingsPath);
+        return scriptIdentical ? null : existed ? "updated" : "created";
+    }
+    const settings = read.data;
+    const hooks = (settings.hooks ?? {});
+    const existing = Array.isArray(hooks.Stop) ? hooks.Stop : [];
+    const filtered = existing.filter((h) => !isVexpHookEntry(h, "vexp-verify"));
+    // Cross-OS shape as everywhere: bash + QUOTED path; timeout in SECONDS.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-verify.sh"',
+                timeout: 15,
+            },
+        ],
+    });
+    const merged = { ...hooks, Stop: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
+function isVexpHintHookEntry(h) {
+    if (!h || typeof h !== "object")
+        return false;
+    const entry = h;
+    const own = entry.command?.includes("vexp-hint");
+    if (own)
+        return true;
+    const hks = entry.hooks;
+    return Array.isArray(hks) && hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        return hook.command?.includes("vexp-hint") ?? false;
+    });
+}
+/**
+ * Install the event-driven hint hook for Claude Code (2.3.3 default).
+ * Replaces the resident CLAUDE.md strategy text: a UserPromptSubmit hook
+ * asks the daemon to classify each prompt against the index and injects a
+ * one-line run_pipeline suggestion ONLY for unfamiliar-area prompts. On
+ * oriented prompts the injection is empty — zero context cost. Fail-open by
+ * construction (see VEXP_HINT_HOOK): any failure = vanilla behavior.
+ * Non-blocking and additive, so it is NOT gated by guardMode (the 2.3 A2
+ * opt-in applies to DENY hooks, which add a failure mode; this one cannot
+ * block anything).
+ */
+export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-hint.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const script = vexpHintHookScript(binaryPath);
+    fs.mkdirSync(hookDir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    }
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok) {
+        warnUnparseable(settingsPath);
+        return scriptIdentical ? null : existed ? "updated" : "created";
+    }
+    const settings = read.data;
+    const hooks = (settings.hooks ?? {});
+    const existing = Array.isArray(hooks.UserPromptSubmit)
+        ? hooks.UserPromptSubmit
+        : [];
+    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
+    // Same cross-OS shape as the guard entry: bash prefix + QUOTED path
+    // (spaces-safe on unix, Git Bash on Windows). timeout is SECONDS.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-hint.sh"',
+                timeout: 5,
+            },
+        ],
+    });
+    const merged = { ...hooks, UserPromptSubmit: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
+/**
+ * opencode/Kilo hint plugin (2.4.0): default-ON, non-blocking, fail-open —
+ * unlike the deny guard (strict-only), this cannot break a session; it only
+ * ever appends an orientation line the daemon judged useful.
+ */
+export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir) {
+    const pluginPath = path.join(workspaceRoot, pluginDir, "vexp-hint.js");
+    const content = vexpOpencodeHintPlugin(binaryPath);
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+    const existed = fs.existsSync(pluginPath);
+    if (existed && fs.readFileSync(pluginPath, "utf-8") === content)
+        return null;
+    fs.writeFileSync(pluginPath, content);
+    return existed ? "updated" : "created";
+}
+/**
+ * Codex hint hook (2.4.0). Codex >=0.129 discovers `<repo>/.codex/hooks.json`
+ * and its UserPromptSubmit stdout envelope is byte-identical to Claude
+ * Code's (hookSpecificOutput.additionalContext), so the same prompt-hint
+ * backend serves both: PROJECT-scope file, no global config touched.
+ * Fail-open: missing bash/binary/daemon => no output => vanilla.
+ */
+export function installCodexHintHook(workspaceRoot, binaryPath) {
+    const dir = path.join(workspaceRoot, ".codex");
+    const hookPath = path.join(dir, "vexp-hint.sh");
+    const hooksJsonPath = path.join(dir, "hooks.json");
+    const script = vexpHintHookScript(binaryPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    }
+    let root = {};
+    if (fs.existsSync(hooksJsonPath)) {
+        try {
+            root = JSON.parse(fs.readFileSync(hooksJsonPath, "utf-8"));
+        }
+        catch {
+            warnUnparseable(hooksJsonPath);
+            return scriptIdentical ? null : existed ? "updated" : "created";
+        }
+    }
+    // Codex hooks.json shape: EVENT NAME at top level (no "hooks" wrapper).
+    const existing = Array.isArray(root.UserPromptSubmit)
+        ? root.UserPromptSubmit
+        : [];
+    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
+    // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: `bash "${hookPath.replace(/\\/g, "/")}"`,
+                timeout: 5,
+            },
+        ],
+    });
+    const before = JSON.stringify(root.UserPromptSubmit ?? null);
+    root.UserPromptSubmit = filtered;
+    const identical = before === JSON.stringify(filtered);
+    if (scriptIdentical && identical)
+        return null;
+    if (!identical) {
+        fs.writeFileSync(hooksJsonPath, JSON.stringify(root, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
 // ---------------------------------------------------------------------------
 // opencode plugin - blocks grep/glob (and shelled-out search) when the daemon
 // is healthy. opencode has no PreToolUse hook, but auto-loads plugins from
@@ -1929,90 +2153,33 @@ function generateAgentConfig(template, vars) {
 // ---------------------------------------------------------------------------
 function claudeCodeTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
-
-### Context strategy: one pipeline call up front, then your normal tools
-For every multi-file task - bug fixes, features, refactors, debugging:
-**call \`run_pipeline\` ONCE at the start**. It executes context search + impact
-analysis + memory recall in a single call: which files matter, what breaks,
-what was learned before. Then implement with your normal tools.
-
-Division of labor (each tool where it wins):
-- **Architecture, impact, "where is X wired"**: \`run_pipeline\` - the graph
-  answers these better and cheaper than exploratory reading.
-- **Literal text sweeps** (string constants, log messages, config keys, e.g.
-  \`localStorage\`, API paths): Grep/Glob directly - text search is what they
-  are best at, do NOT route text sweeps through vexp.
-- **Editing**: Read the files you are about to modify; use \`get_skeleton\`
-  (detail: minimal/standard/detailed, 70-90% token savings) for files you only
+vexp runs entirely on this machine: local daemon, index in \`.vexp/\`.
+\`run_pipeline\` transmits nothing to any external service.
+- \`run_pipeline({ "task": "..." })\` - orientation in one call (ranked pivot
+  files with line ranges + blast radius + session notes) when a task does NOT
+  name the files/symbols to touch. If it does, SKIP vexp - use your normal tools.
+- \`get_skeleton\` - file structure at 70-90% token savings for files you only
   need to understand, not edit.
-
-Every extra tool call costs a turn: one good \`run_pipeline\` call beats five
-small ones. Each result opens with a coverage header (index: N files, M nodes) -
-if it does not match this repo, run \`vexp index\`.
-vexp only covers indexed source inside the workspace: for runtime logs, build
-output (dist/, .vite/, node_modules/) or files outside the repo use Bash/Read.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Primary Tool
-- \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Single call that runs
-  capsule + impact + memory server-side. Returns compressed results.
-  Auto-detects intent (debug/modify/refactor/explore) from your task.
-  Includes full file content for pivots.
-  Examples:
-  - \`run_pipeline({ "task": "fix JWT validation bug" })\` - auto-detect
-  - \`run_pipeline({ "task": "refactor db layer", "preset": "refactor" })\` - explicit
-  - \`run_pipeline({ "task": "add auth", "observation": "using JWT" })\` - save insight in same call
-
-### Other MCP tools (use only when run_pipeline is insufficient)
-- \`get_skeleton\` - **preferred over Read** for inspecting files (minimal/standard/detailed detail levels, 70-90% token savings)
-- \`index_status\` - indexing status and health check
-- \`expand_vexp_ref\` - expand V-REF hash placeholders in v2 compact output
-
-${QUERY_SHAPE}
-
-### Workflow
-1. \`run_pipeline("your task")\` - ONCE at task start. Returns pivots + impact + memories in 1 call
-2. Literal string sweeps? Grep/Glob directly. Editing a file? Read it directly.
-3. Structural overview of a non-edit file? \`get_skeleton({ files: [...], detail: "detailed" })\`
-4. Make targeted changes based on the context returned
-5. \`run_pipeline\` again ONLY when the task moves to a new area - do NOT chain vexp calls per turn
-
-### Subagent / Explore / Plan mode
-- Subagents CAN call \`run_pipeline\` - always include the task description
-- Before spawning Agent(Explore) for architecture questions, call \`run_pipeline\`
-  and pass the returned context into the agent prompt - it usually replaces the
-  exploration entirely
-
-### Smart Features (automatic - no action needed)
-- **Intent Detection**: auto-detects from your task keywords. "fix bug" -> Debug, "refactor" -> blast-radius, "add" -> Modify
-- **Hybrid Search**: keyword + semantic + graph centrality ranking
-- **Session Memory**: auto-captures observations; memories auto-surfaced in results
-- **LSP Bridge**: VS Code captures type-resolved call edges
-- **Change Coupling**: co-changed files included as related context
-
-### Advanced Parameters
-- \`preset: "debug"\` - forces debug mode (capsule+tests+impact+memory)
-- \`preset: "refactor"\` - deep impact analysis (depth 5)
-- \`max_tokens: 12000\` - increase total budget for complex tasks
-- \`include_tests: true\` - include test files in results
-- \`include_file_content: false\` - omit full file content (lighter response)
-
-### Fallback
-If \`run_pipeline\` returns \`status: "degraded"\` or 0 pivots with an INDEX EMPTY warning,
-the index is empty or rebuilding. Use Grep, Glob, and Read directly until the index is ready.
-
-### Multi-Repo Workspaces
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope.
-Use \`index_status\` to discover available repo aliases.
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  returns mechanically broken references (imports of removed names, parse
+  errors) and untouched dependents of the files you changed, with file:line.
+- vexp may append a one-line hint to a prompt when orientation would help;
+  otherwise it stays silent.
+
+### Query shape (do this)
+Anchor the task on real identifiers (ClassName, functionName) or file paths:
+\`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 <!-- /vexp -->`;
 }
 function cursorTemplate(vars) {
     return `## vexp rules for Cursor <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2029,9 +2196,15 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2059,7 +2232,11 @@ function windsurfTemplate(vars) {
     return `## vexp for Windsurf <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2076,9 +2253,15 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2117,7 +2300,11 @@ function augmentTemplate(vars) {
     return `## vexp for Augment <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2134,9 +2321,15 @@ When working on this codebase:
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - token-efficient file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2156,7 +2349,11 @@ function copilotTemplate(vars) {
     return `## vexp context tools <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2173,9 +2370,15 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2195,7 +2398,11 @@ function zedTemplate(vars) {
     return `## vexp for Zed <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2212,9 +2419,15 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2234,7 +2447,11 @@ function agentsMdTemplate(vars) {
     return `## vexp <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2251,6 +2468,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2276,7 +2495,11 @@ function kiroTemplate(vars) {
     return `# vexp steering <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2293,9 +2516,15 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ## Agentic search
@@ -2315,6 +2544,8 @@ function genericTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
 ### Context strategy: call run_pipeline ONCE at task start
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 For every multi-file task - bug fixes, features, refactors, questions about the code:
 **start with one \`run_pipeline\` call**. It runs context search + impact analysis +
 memory recall in a single call and returns compressed, graph-ranked results: the
@@ -2328,6 +2559,9 @@ Then implement with your normal tools:
   need to understand, not edit.
 - Do NOT open files one by one to find your way around - one good pipeline call
   beats five exploratory reads; every extra tool call costs a turn.
+- Before declaring a multi-file task complete, call \`verify_done\` once:
+  it returns mechanically broken references (imports of removed names,
+  parse errors) and untouched dependents of your changes, with file:line.
 
 vexp runs entirely on this machine: local daemon, local index stored inside the
 workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -

package/dist/cli.js

@@ -434,6 +434,21 @@ program
         args.push("--export");
     runBinary(binaryPath, args);
 });
+program
+    .command("shield <action>")
+    .description("PII/secret shield: 'scan' reports what comments and string literals would hand to any AI agent (free, read-only, local)")
+    .option("--json", "Emit machine-readable JSON")
+    .action(async (action, opts) => {
+    if (action !== "scan") {
+        console.error(`Unknown shield action '${action}'. Available: scan`);
+        process.exit(1);
+    }
+    const binaryPath = ensureBinary();
+    const args = ["shield", "scan"];
+    if (opts.json)
+        args.push("--json");
+    runBinary(binaryPath, args);
+});
 program
     .command("compress <file>")
     .description("Compress a markdown/text file using prose compression (backup to <name>.original.md)")