vexp-cli 3.3.6 → 3.3.8

package/dist/doctor.js

@@ -605,6 +605,42 @@ function withoutVexpCommands(line) {
         .filter((sentence) => !/[`']vexp /.test(sentence))
         .join(" ");
 }
+/** ~/.vexp/config.toml, under VEXP_HOME when that is set: where the engine reads it. */
+function configTomlPath() {
+    return path.join(vexpHome(), ".vexp", "config.toml");
+}
+/** Minutes as the setting gives them: whole, else seconds. */
+function spokenMinutes(minutes) {
+    return Number.isInteger(minutes) ? `${minutes} min` : `${Math.round(minutes * 60)} s`;
+}
+/**
+ * The idle stop, as the daemon that answered sees it (index_status
+ * `idle_stop`, 3.3.6 and later). The setting was only to be found by reading
+ * the binary (field report, 2026-10-17): doctor names it, on, off, or passed
+ * over for a window's daemon. Null for a daemon from before it.
+ */
+export function idleStopFinding(idle) {
+    if (!idle || typeof idle !== "object")
+        return null;
+    const st = idle;
+    const after = typeof st.after_minutes === "number" && st.after_minutes > 0 ? st.after_minutes : null;
+    if (after === null) {
+        return {
+            level: INFO,
+            message: `idle stop: off, so this daemon runs until it is stopped. To stop the daemons nobody uses, set [daemon] idle_timeout_minutes = 30 in ${configTomlPath()} ` +
+                `(or VEXP_IDLE_TIMEOUT_MINUTES for one daemon); the next tool call or prompt starts one again. A daemon an editor window started stops with that window instead.`,
+        };
+    }
+    if (st.editor_owned === true) {
+        return {
+            level: OK,
+            message: `idle stop: after ${spokenMinutes(after)} without use, but not this daemon: an editor window started it, and it stops when that window closes`,
+        };
+    }
+    const idleS = typeof st.idle_s === "number" ? st.idle_s : null;
+    const unused = idleS === null ? "" : idleS >= 60 ? ` (unused for ${Math.floor(idleS / 60)} min now)` : " (used in the last minute)";
+    return { level: OK, message: `idle stop: after ${spokenMinutes(after)} without use${unused}; the next tool call or prompt starts it again` };
+}
 /**
  * What doctor says when no daemon answers for this workspace.
  *
@@ -654,6 +690,18 @@ export function daemonDownFindings(o) {
             },
         ];
     }
+    // Stopped on purpose: idle_timeout_minutes. Nothing to restart by hand,
+    // and the marker goes as soon as a daemon starts here again.
+    const idle = (o.idleExit ?? "").split(/\r?\n/)[0].trim();
+    if (idle) {
+        return [
+            {
+                level: INFO,
+                message: `no daemon is running for this project (${o.sock}): it ${idle}.\n` +
+                    `        nothing to do: the next tool call or prompt starts it again. The setting is [daemon] idle_timeout_minutes in ${configTomlPath()}.`,
+            },
+        ];
+    }
     if (ext && !o.hasIndex) {
         return [
             {
@@ -1009,7 +1057,11 @@ export function partialParseVerdict(cov, coveragePath = ".vexp/coverage.json") {
     const files = list;
     const examples = files
         .slice(0, 5)
-        .map((f) => `${f.path} (${Number(f.lines) || 0} line(s) from line ${Number(f.first_line) || 0})`);
+        .map((f) => {
+        const broke = Number(f.broke_line) || 0;
+        const at = broke > 0 ? `, the reading broke at line ${broke}` : "";
+        return `${f.path} (${Number(f.lines) || 0} line(s) from line ${Number(f.first_line) || 0}${at})`;
+    });
     const more = files.length - examples.length;
     return {
         level: WARN,
@@ -1256,7 +1308,8 @@ export function claudeHookSpawnSpec(command, root, platform, gitBash, baseEnv =
     if (!gitBash)
         return null;
     const env = { ...baseEnv, CLAUDE_PROJECT_DIR: root.replace(/\\/g, "/") };
-    // The `bash` inside the command must resolve to Git Bash too, not WSL's.
+    // The `sh` inside the command (`bash` in an older entry) must resolve
+    // beside Git Bash too, as in Claude Code, never to WSL's launcher.
     if (path.win32.isAbsolute(gitBash)) {
         const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
         const dir = path.win32.dirname(gitBash);
@@ -1278,10 +1331,108 @@ export function claudeShellMissing(what, lookup) {
     }
     return (`${what} cannot run on this PC: on Windows Claude Code runs hooks with Git Bash, and there is none where it looks ` +
         `(CLAUDE_CODE_GIT_BASH_PATH, C:\\Program Files\\Git\\bin\\bash.exe, bin\\bash.exe beside the git.exe on PATH). ` +
-        `It then runs them with PowerShell, which cannot run vexp's bash hooks. A 'bash' on PATH does not count: with WSL installed it is WSL's, which cannot see this project.\n` +
+        `It then runs them with PowerShell, which cannot run vexp's sh hooks. A 'bash' on PATH does not count: with WSL installed it is WSL's, which cannot see this project.\n` +
         `        install Git for Windows (https://git-scm.com/downloads/win) or set CLAUDE_CODE_GIT_BASH_PATH to your bash.exe ` +
         `(in the environment or the "env" block of ~/.claude/settings.json; a project's settings do not count), then restart Claude Code.`);
 }
+/**
+ * Does this Claude Code entry start vexp's script with `bash`? Setup wrote
+ * that form until the hooks became POSIX sh; both installers now replace it,
+ * matched by script name, with `sh "..."`. Off Windows Claude Code runs
+ * either as `/bin/sh -c '<command>'`, so the old one keeps working wherever
+ * a bash is on PATH, and doctor says nothing of it there.
+ */
+export function isBashHookEntry(command) {
+    return /^\s*bash\s/.test(command);
+}
+/** Is `name` an executable file in a folder of PATH? POSIX lookup. */
+export function onPosixPath(name, env = process.env, canExec = (p) => {
+    try {
+        fs.accessSync(p, fs.constants.X_OK);
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}) {
+    return (env.PATH ?? "").split(path.posix.delimiter).some((dir) => dir !== "" && canExec(path.posix.join(dir, name)));
+}
+/**
+ * What a Claude Code hook that fails at its event costs. "Fails on every
+ * prompt" was the line for the subagent hook too, which never sees a prompt:
+ * on Agent the subagent still starts, only blind (review, 2026-10-24).
+ */
+export function claudeHookFailureCost(event) {
+    if (event === "PreToolUse")
+        return "Claude Code reports a hook error on every Agent call and each subagent starts without orientation";
+    if (event === "SessionStart")
+        return "the hook fails at every session start";
+    if (event === "Stop")
+        return "the hook fails at the end of every reply";
+    return "the hook fails on every prompt";
+}
+/**
+ * Which opt-ins this settings.json shows on. Setup keeps no record of its
+ * flags, so the entries are the only answer, and a rewrite has to carry
+ * them: `vexp setup` without --guard-strict or --interventions REMOVES those
+ * hooks, script and entry (review, 2026-10-24).
+ */
+export function claudeOptInsOn(settings) {
+    const hooks = settings?.hooks ?? {};
+    const commands = Object.values(hooks)
+        .flatMap((groups) => (Array.isArray(groups) ? groups : []))
+        .flatMap((g) => (Array.isArray(g?.hooks) ? g.hooks : []))
+        .map((h) => (typeof h?.command === "string" ? h.command : ""));
+    return {
+        guard: commands.some((c) => c.includes("vexp-guard")),
+        interventions: commands.some((c) => /vexp-(verify|edit-hint|read-hint|bash-cap)\b/.test(c)),
+    };
+}
+/**
+ * How vexp's Claude Code entries get rewritten, with the install at hand:
+ * the setup that writes them, and for someone with the extension a restart
+ * of the window, since the extension rewrites them at every start in a
+ * project where it sets Claude Code up (and the guard when vexp.guardStrict
+ * is on).
+ *
+ * The project's opt-ins ride along (claudeOptInsOn). The plain command,
+ * offered for an old `bash` stop gate, rewrote nothing: a setup without
+ * --interventions takes the gate out, so a user who had chosen it and
+ * followed doctor lost it without a word (review, 2026-10-24). The extension
+ * writes none of the --interventions hooks and takes them out at every
+ * start, which a reopen does too; the line says so rather than call that a
+ * rewrite.
+ */
+export function claudeHooksRewriteRemedy(install, root, on = { guard: false, interventions: false }) {
+    const ide = ideName(install.extensions);
+    const reopen = on.guard
+        ? `reopen this project in ${ide} with the vexp.guardStrict setting on`
+        : `reopen this project in ${ide} (the vexp extension rewrites them at every start where it sets Claude Code up)`;
+    const takesOut = on.interventions
+        ? "; the extension takes out the stop gate and the other opt-in hooks of 'vexp setup --interventions' as it does so, since only the vexp CLI writes them"
+        : "";
+    if (extensionOnly(install)) {
+        return (on.guard ? reopen : `${reopen}, or run "vexp: Setup Agents" from the Command Palette and tick Claude Code`) + takesOut;
+    }
+    const flags = `${on.guard ? " --guard-strict" : ""}${on.interventions ? " --interventions" : ""}`;
+    const setup = `run '${setupAgentsCommand(["Claude Code"], root)}${flags}'`;
+    return install.extensions.length > 0 ? `${setup}, or ${reopen}${takesOut}` : setup;
+}
+/**
+ * The line for a `bash` entry on a machine with no bash. Alpine and the
+ * other BusyBox systems ship sh alone, and the alpine-x64/arm64 builds put
+ * vexp there: `bash "..."` exits 127 at every event, a hook error each time
+ * and no orientation. Off Windows only: there Claude Code runs hooks with
+ * Git Bash, which brings its own bash (claudeShellMissing covers its
+ * absence). Null when the entry is not the old form or a bash is on PATH;
+ * the probe that follows judges it then.
+ */
+export function claudeBashEntryLine(what, command, cost, remedy, platform = process.platform, bashOnPath = () => onPosixPath("bash")) {
+    if (platform === "win32" || !isBashHookEntry(command) || bashOnPath())
+        return null;
+    return (`${what} starts vexp's script with bash, and this machine has no bash on PATH (Alpine and other BusyBox systems ship only sh): ${cost}.\n` +
+        `        vexp writes this entry with sh now; to fix it: ${remedy}.`);
+}
 /**
  * What the ledger adds to a failed hook probe. Its prompts arrive only
  * through an agent's hook — doctor's own probe is tagged manual and never
@@ -1291,14 +1442,36 @@ export function claudeShellMissing(what, lookup) {
  * probes' own failures: the prompts it counts come from UserPromptSubmit
  * hooks, and next to a failure that is real (no Git Bash for Claude Code, an
  * exec-form guard Windows cannot spawn) "may be the probe's alone" talked the
- * reader out of the one line he had to act on (review, 2026-09-24).
+ * reader out of the one line he had to act on (review, 2026-09-24). And only
+ * on the UserPromptSubmit probe's: a count of prompts says nothing of
+ * vexp-subagent.sh, and an exit 2 line read "Claude Code REFUSES the Agent
+ * call" and "may be the probe's alone" at once (review, 2026-10-24).
  */
-export function hookLedgerNote(hookPrompts7d) {
-    if (!(hookPrompts7d > 0))
+export function hookLedgerNote(hookPrompts7d, event) {
+    if (event !== "UserPromptSubmit" || !(hookPrompts7d > 0))
         return "";
     return (`\n        note: the savings ledger counted ${hookPrompts7d} prompt(s) in the last 7 days that reached vexp through an agent's hook ` +
         `(doctor's own probe is never counted), so an agent's hooks do reach vexp in this project — this failure may be the probe's alone.`);
 }
+/**
+ * The keys of the Agent call the subagent hook's answer leaves out. Claude
+ * Code replaces tool_input with updatedInput instead of merging the two, so
+ * a key missing there is missing from the call itself: the agent type, the
+ * background flag. No output, or output without updatedInput, leaves the
+ * call as the model wrote it and drops nothing.
+ */
+export function droppedAgentKeys(stdout, toolInput) {
+    let updated;
+    try {
+        updated = JSON.parse(String(stdout ?? "").trim() || "null")?.hookSpecificOutput?.updatedInput;
+    }
+    catch {
+        return [];
+    }
+    if (!updated || typeof updated !== "object")
+        return [];
+    return Object.keys(toolInput).filter((k) => !(k in updated));
+}
 /** The answers file when it exists but does not read as answers. */
 function unreadableAnswers(file) {
     // The same loader the CLI and the extension read the answers with: it
@@ -3257,6 +3430,11 @@ async function doctorChecks(onWorkspace) {
             startBlocked = fs.readFileSync(path.join(ws.root, ".vexp", "start-blocked"), "utf-8");
         }
         catch { /* the last start was not refused */ }
+        let idleExit;
+        try {
+            idleExit = fs.readFileSync(path.join(ws.root, ".vexp", "idle-exit"), "utf-8");
+        }
+        catch { /* the last daemon did not stop for idleness */ }
         const what = notAProject(ws.root);
         const down = daemonDownFindings({
             sock,
@@ -3264,6 +3442,7 @@ async function doctorChecks(onWorkspace) {
             hasIndex: fs.existsSync(path.join(ws.root, ".vexp", "index.db")),
             startBlocked,
             outside: what ? { root: ws.root, what } : undefined,
+            idleExit,
         });
         closedInIde = down.every((f) => f.level === INFO);
         for (const f of down)
@@ -3303,6 +3482,9 @@ async function doctorChecks(onWorkspace) {
                     ? "loading (the model is still starting — this is not the rule compressor settling in)"
                     : st.compressor ?? "unknown (older daemon)";
             line(OK, `index: ${st.total_files ?? "?"} files · ${st.total_nodes ?? "?"} nodes · state ${st.status ?? "?"} · compressor ${comp}`);
+            const idleStop = idleStopFinding(st.idle_stop);
+            if (idleStop)
+                emit(idleStop);
             if (st.llm_configured_but_inactive === true) {
                 // The daemon knows WHY, and doctor was throwing it away: it printed
                 // the same "restart to load the model" the sidebar prints, to a user
@@ -3759,9 +3941,11 @@ async function doctorChecks(onWorkspace) {
         const sPath = path.join(ws.root, ".claude", "settings.json");
         let guardHooks = [];
         let settingsReadable = false;
+        let optIns = { guard: true, interventions: false };
         try {
             const settings = JSON.parse(fs.readFileSync(sPath, "utf-8"));
             settingsReadable = true;
+            optIns = { ...claudeOptInsOn(settings), guard: true };
             const pre = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
             for (const m of pre) {
                 const hks = Array.isArray(m?.hooks) ? m.hooks : [];
@@ -3791,7 +3975,7 @@ async function doctorChecks(onWorkspace) {
                     // all — the entry LOOKS installed and enforces nothing. This was
                     // invisible for days because doctor used to skip the live check
                     // on Windows entirely.
-                    line(BAD, `exec-form hook entry ('args' present) cannot run a .sh on Windows — the guard fails open. Re-run 'vexp setup --guard-strict' to rewrite it (bash-prefixed shell form).`);
+                    line(BAD, `exec-form hook entry ('args' present) cannot run a .sh on Windows — the guard fails open. Re-run 'vexp setup --guard-strict' to rewrite it (sh-prefixed shell form).`);
                 }
                 if (timeoutS > 600) {
                     line(WARN, `hook timeout ${timeoutS} is in SECONDS (${Math.round(timeoutS / 60)} minutes) — likely meant milliseconds. Re-run 'vexp setup --guard-strict' to fix.`);
@@ -3800,6 +3984,15 @@ async function doctorChecks(onWorkspace) {
                     line(INFO, `guard hook declares "shell": "powershell" — not tested here; Claude Code runs it with PowerShell`);
                     continue;
                 }
+                // An entry from before the hooks became POSIX sh, on a machine with
+                // no bash (Alpine): the probe would only print sh's exit 127.
+                const noBash = execForm
+                    ? null
+                    : claudeBashEntryLine("the guard hook", cmd, "Claude Code reports a hook error on every search and the guard enforces nothing", claudeHooksRewriteRemedy(install, ws.root, optIns));
+                if (noBash) {
+                    line(BAD, noBash);
+                    continue;
+                }
                 // Run it exactly as Claude Code would: exec form = direct spawn with
                 // the placeholder substituted by the host; shell form = the shell
                 // Claude Code uses (claudeHookSpawnSpec: Git Bash on Windows, never
@@ -3887,6 +4080,7 @@ async function doctorChecks(onWorkspace) {
         // --interventions` installs it for anyone who wants that trade.
         const wanted = [
             { event: "UserPromptSubmit", marker: "vexp-hint", label: "orientation" },
+            { event: "PreToolUse", marker: "vexp-subagent", label: "subagent orientation" },
             { event: "SessionStart", marker: "vexp-restore", label: "context restore" },
             { event: "Stop", marker: "vexp-verify", label: "verification gate", optIn: true },
         ];
@@ -3935,15 +4129,31 @@ async function doctorChecks(onWorkspace) {
                 }
                 const scriptPath = path.join(ws.root, ".claude", "hooks", `${w.marker}.sh`);
                 if (!fs.existsSync(scriptPath)) {
-                    line(BAD, `${w.event} points at ${w.marker}.sh but the script is missing — the hook fails on every prompt.`);
+                    // sh exits 127, an error Claude Code reports and steps over each
+                    // time the event fires (claudeHookFailureCost says what that costs).
+                    line(BAD, `${w.event} points at ${w.marker}.sh but the script is missing — ${claudeHookFailureCost(w.event)}.`);
+                    continue;
+                }
+                // A `bash` entry from before the hooks became POSIX sh, where there
+                // is no bash: the same 127 at every event, and a rewrite fixes it.
+                const noBash = claudeBashEntryLine(`${w.event} hook`, hook.command, claudeHookFailureCost(w.event), claudeHooksRewriteRemedy(install, ws.root, claudeOptInsOn(settings)));
+                if (noBash) {
+                    line(BAD, noBash);
                     continue;
                 }
                 // Feed it a payload shaped like the real event and see it survive.
+                // Like every probe here it carries no hook_event_name and no
+                // transcript_path: those are what tell the engine a call came from an
+                // agent (payload_is_from_hook, main.rs), and a probe with them would
+                // be counted in the activity ledger as an agent's.
+                const agentInput = { description: "vexp doctor probe", prompt: "vexp doctor probe", subagent_type: "general-purpose" };
                 const payload = JSON.stringify(w.event === "SessionStart"
                     ? { session_id: "vexp-doctor", source: "compact", cwd: ws.root }
                     : w.event === "Stop"
                         ? { session_id: "vexp-doctor", stop_hook_active: true, cwd: ws.root }
-                        : { session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root });
+                        : w.event === "PreToolUse"
+                            ? { session_id: "vexp-doctor", tool_name: "Agent", tool_input: agentInput, cwd: ws.root }
+                            : { session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root });
                 // In Claude Code's own shell (claudeHookSpawnSpec), from the project.
                 const bash = process.platform === "win32" ? claudeGitBash() : null;
                 const spec = claudeHookSpawnSpec(hook.command, ws.root, process.platform, bash?.path ?? null);
@@ -3959,15 +4169,27 @@ async function doctorChecks(onWorkspace) {
                     encoding: "utf-8",
                     windowsHide: true,
                 });
+                const lost = w.event === "PreToolUse" && !r.error && r.status === 0 ? droppedAgentKeys(r.stdout, agentInput) : [];
                 if (r.error) {
-                    line(BAD, `${w.event} hook DID NOT RUN: ${r.error.code ?? r.error.message} — the ${w.label} is inert.` + hookLedgerNote(hookPrompts7d));
+                    line(BAD, `${w.event} hook DID NOT RUN: ${r.error.code ?? r.error.message} — the ${w.label} is inert.` + hookLedgerNote(hookPrompts7d, w.event));
                 }
                 else if (r.status !== 0) {
-                    line(BAD, `${w.event} hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Claude Code treats this as a failure and continues without vexp.` + hookLedgerNote(hookPrompts7d));
+                    // Exit 2 from a PreToolUse hook is not a failure Claude Code steps
+                    // over: it refuses the tool call. The script setup writes ends on
+                    // `exit 0` for exactly this reason, so one that exits 2 is not it.
+                    const consequence = w.event === "PreToolUse" && r.status === 2
+                        ? "on exit 2 Claude Code REFUSES the Agent call, so no subagent can start"
+                        : "Claude Code treats this as a failure and continues without vexp";
+                    line(BAD, `${w.event} hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — ${consequence}.` + hookLedgerNote(hookPrompts7d, w.event));
+                }
+                else if (lost.length > 0) {
+                    line(BAD, `${w.event} hook rewrites the Agent call without ${lost.join(", ")} — Claude Code replaces the call's input with the hook's, so every subagent loses them; update the vexp engine.`);
                 }
                 else {
                     // Silence is a legitimate outcome for the hint hook (the classifier
-                    // decides), so report the daemon's reason instead of guessing.
+                    // decides), so report the daemon's reason instead of guessing. The
+                    // same for the subagent hook: no seed is no output, and the call
+                    // goes ahead as the model wrote it.
                     const why = String(r.stderr ?? "").trim().replace(/^vexp [\w-]+: /, "");
                     line(OK, `${w.event} hook runs${why ? ` (this probe: ${why.slice(0, 120)})` : ""}`);
                 }
@@ -4053,7 +4275,7 @@ async function doctorChecks(onWorkspace) {
                 : [{ shell: "sh", spec: codexHookSpawnSpec(cmdLine) }];
             const baked = (() => {
                 try {
-                    // One pattern covers both twins: VEXP_BIN="path" (bash) and
+                    // One pattern covers both twins: VEXP_BIN="path" (sh) and
                     // set "VEXP_BIN=path" (cmd).
                     const probed = isWin ? path.join(ws.root, ".codex", "vexp-hint.cmd") : scriptPath;
                     return fs.readFileSync(probed, "utf-8").match(/VEXP_BIN="?([^"\r\n]+)"?/)?.[1];

package/dist/hook-template.js

@@ -11,7 +11,7 @@
  * platform uses the right "daemon is listening" signal. The healthy marker
  * (removed by the daemon on graceful shutdown) gates both branches.
  */
-export const VEXP_GUARD_HOOK = `#!/bin/bash
+export const VEXP_GUARD_HOOK = `#!/bin/sh
 # vexp-guard: block Grep/Glob/Read when the vexp daemon is running AND healthy.
 # Cross-platform: Unix/macOS use the domain socket file (.vexp/daemon.sock);
 # Windows (Git Bash) has no socket file, so the daemon writes .vexp/daemon.pipe.
@@ -31,7 +31,7 @@ vexp_allow() {
 }
 
 # Healthy marker is the portable "daemon is up" signal; the daemon removes it on
-# graceful shutdown. Required on every platform — if it's missing, fail open.
+# graceful shutdown. Required on every platform - if it's missing, fail open.
 [ -f "$HEALTHY" ] || vexp_allow
 
 case "$(uname -s 2>/dev/null)" in
@@ -207,8 +207,8 @@ export const VexpGuard = async ({ directory, worktree }) => {
  * never touch the shell, never block a target vexp did not index — expressed in
  * the third dialect we now have to speak.
  *
- * Written in NODE, not bash, and that is deliberate. The Claude Code guard is a
- * bash script and it silently enforced NOTHING on Windows for several releases
+ * Written in NODE, not shell, and that is deliberate. The Claude Code guard is a
+ * shell script and it silently enforced NOTHING on Windows for several releases
  * (`[ -S "$SOCK" ]` can never match a named pipe), which is the single most
  * expensive bug this file has produced. Cursor documents no PowerShell variant
  * of `command` and does not say which shell runs it on Windows, so a bash guard
@@ -381,6 +381,15 @@ process.stdin.on("end", () => {
  * hint suggesting run_pipeline. All logic (stdin parsing, classification,
  * hook-JSON output) lives in the Rust binary so the script is OS-neutral;
  * Claude Code runs shell-form hooks through Git Bash on Windows.
+ *
+ * POSIX sh, like every Claude Code hook script in this file, and registered
+ * as `sh "$CLAUDE_PROJECT_DIR/..."`. They were bash scripts run by `bash`,
+ * and Alpine (BusyBox) has no bash: on an Alpine remote, the platform of the
+ * alpine-x64/arm64 builds, every prompt, session start and Agent call
+ * reported a hook error and got no orientation. Nothing here needed bash.
+ * Keep it that way: test/hook-posix.test.ts rejects the usual bashisms and
+ * runs every baked script under dash.
+ *
  * FAIL-OPEN CONTRACT: every failure path (binary missing, daemon down,
  * timeout) exits 0 with no output = vanilla behavior, never a broken
  * prompt. Keep in lockstep with the VS Code extension copy.
@@ -392,13 +401,45 @@ process.stdin.on("end", () => {
  * line: Codex hashes that line for its trust record, and a change there would
  * make every user approve the hook again. Binaries that predate it ignore it.
  */
-export const VEXP_HINT_HOOK = `#!/bin/bash
+export const VEXP_HINT_HOOK = `#!/bin/sh
 # vexp-hint: event-driven orientation hint (UserPromptSubmit). Fails open.
 VEXP_BIN="__VEXP_BIN__"
 [ -x "$VEXP_BIN" ] || exit 0
 VEXP_HOOK_AGENT="__VEXP_AGENT__" "$VEXP_BIN" prompt-hint 2>/dev/null
 exit 0
 `;
+/**
+ * Orientation for a delegated task: PreToolUse on Claude Code's Agent tool.
+ *
+ * A subagent started blind (field report, 2026-10-24). UserPromptSubmit fires
+ * for what the user types and never for the prompt the model writes for a
+ * subagent; the built-in Explore and Plan agents run without CLAUDE.md; and
+ * vexp's tools reach a subagent only as bare deferred names. SubagentStart is
+ * no way in either: it is handed the agent's id and type, not its task.
+ *
+ * PreToolUse on Agent is handed the task, as tool_input.prompt, and Claude
+ * Code starts the subagent on `updatedInput` when the hook returns one. It
+ * REPLACES the input, it does not merge it, so `subagent-hint` echoes every
+ * key with the seed appended to the prompt. It sets no permissionDecision:
+ * without one the rewrite is applied silently in default, acceptEdits, auto,
+ * plan and bypassPermissions mode (verified on Claude Code 2.1.217 and
+ * 2.1.309), and an "allow" would skip the auto-mode classifier. The parent's
+ * transcript keeps the prompt the model wrote; only the subagent's first
+ * message carries the seed, so only the subagent pays for it.
+ *
+ * The last `exit 0` matters more here than in any other hook: a PreToolUse
+ * hook that exits 2 BLOCKS the tool call, and an engine older than
+ * `subagent-hint` exits 2 from its argument parser. Without it, every
+ * delegation would be refused until the engine was updated. Claude Code is
+ * the only agent that runs this script, hence the agent name written in.
+ */
+export const VEXP_SUBAGENT_HOOK = `#!/bin/sh
+# vexp-subagent: orientation for a delegated task (PreToolUse on Agent). Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+VEXP_HOOK_AGENT="claude-code" "$VEXP_BIN" subagent-hint 2>/dev/null
+exit 0
+`;
 /**
  * v5: the coupling, delivered on the edit that needs it (PostToolUse).
  *
@@ -417,14 +458,14 @@ exit 0
  * FAIL-OPEN like every other hook: no binary, no daemon, nothing to say —
  * exit 0 silent.
  */
-export const VEXP_EDIT_HINT_HOOK = `#!/bin/bash
+export const VEXP_EDIT_HINT_HOOK = `#!/bin/sh
 # vexp-edit-hint: what else references the file you just changed. Fails open.
 VEXP_BIN="__VEXP_BIN__"
 [ -x "$VEXP_BIN" ] || exit 0
 "$VEXP_BIN" edit-hint 2>/dev/null
 exit 0
 `;
-export const VEXP_READ_HINT_HOOK = `#!/bin/bash
+export const VEXP_READ_HINT_HOOK = `#!/bin/sh
 # vexp-read-hint: answer a whole-file read of a large file with its skeleton.
 # The only mechanism vexp has that SUBTRACTS tokens. Fails open.
 VEXP_BIN="__VEXP_BIN__"
@@ -432,7 +473,7 @@ VEXP_BIN="__VEXP_BIN__"
 "$VEXP_BIN" read-hint 2>/dev/null
 exit 0
 `;
-export const VEXP_BASH_CAP_HOOK = `#!/bin/bash
+export const VEXP_BASH_CAP_HOOK = `#!/bin/sh
 # vexp-bash-cap: bound the output of a shell command that has no bound of its
 # own. The other door: narrowing reads alone just moved the work here. Fails
 # open, and never touches a build or a test.
@@ -548,6 +589,10 @@ export function bakeEditHintHook(binaryPath) {
 export function vexpHintHookScript(binaryPath, agent = "claude-code") {
     return VEXP_HINT_HOOK.replace("__VEXP_BIN__", upperDriveLetter(binaryPath).replace(/\\/g, "/")).replace("__VEXP_AGENT__", agent);
 }
+/** Bake the binary path into the subagent hook script. */
+export function vexpSubagentHookScript(binaryPath) {
+    return VEXP_SUBAGENT_HOOK.replace("__VEXP_BIN__", upperDriveLetter(binaryPath).replace(/\\/g, "/"));
+}
 /**
  * Windows twin of the hint hook, for Codex. A Windows user with neither Git
  * Bash nor WSL has no `bash`, so `bash "..."` failed on every prompt and
@@ -611,7 +656,7 @@ export function codexWindowsHookCommand(cmdPath) {
  * the script is a cross-OS wrapper that exits silently when anything is
  * missing.
  */
-export const VEXP_SEARCH_HOOK = `#!/bin/bash
+export const VEXP_SEARCH_HOOK = `#!/bin/sh
 # vexp-search: answer a grep with structure instead of lines. Fails open.
 VEXP_BIN="__VEXP_BIN__"
 [ -x "$VEXP_BIN" ] || exit 0
@@ -629,7 +674,7 @@ export function vexpSearchHookScript(binaryPath) {
  * imports. FAIL-OPEN by construction: no binary / no daemon / timeout =
  * silent exit 0 = normal stop.
  */
-export const VEXP_STOP_GATE_HOOK = `#!/bin/bash
+export const VEXP_STOP_GATE_HOOK = `#!/bin/sh
 # vexp-verify: mechanical completion gate on Stop (Horizon). Fails open.
 VEXP_BIN="__VEXP_BIN__"
 [ -x "$VEXP_BIN" ] || exit 0
@@ -647,7 +692,7 @@ export function vexpStopGateHookScript(binaryPath) {
  * orientation) and re-injects one compact context paragraph. FAIL-OPEN:
  * no binary / no daemon / fresh start = silent exit 0.
  */
-export const VEXP_SESSION_CONTEXT_HOOK = `#!/bin/bash
+export const VEXP_SESSION_CONTEXT_HOOK = `#!/bin/sh
 # vexp-restore: context lifecycle restore on SessionStart (compact/resume). Fails open.
 VEXP_BIN="__VEXP_BIN__"
 [ -x "$VEXP_BIN" ] || exit 0