@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/hooks/run.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Run one hook command — the evaluator's one impure seam.
+ *
+ * As Claude Code runs a command hook: exec form (`args` set) spawns the
+ * command with its arguments and no shell; shell form runs the command in
+ * `bash -c`. The call's JSON is written to stdin and stdin is closed; each
+ * output stream is kept up to {@link OUTPUT_CAP_BYTES}. The working
+ * directory is the workspace root and the environment is the caller's (the
+ * agent shell's, plus the hook's own variables, `evaluate.ts`).
+ *
+ * The command gets its own process group, and the whole group is killed when
+ * its timeout passes or the turn is stopped, so a hook that forks cannot
+ * keep its call waiting. A child it leaves running after it exits by itself
+ * is left alone (a hook may start a helper on purpose), and its answer is
+ * the command's: the runner settles {@link EXIT_DRAIN_MS} after the command
+ * exits even when a helper still holds the output pipes. A timed-out or failed command answers no decision; what it
+ * printed is kept for the log.
+ *
+ * While the command lives, `onPulse` is called every `pulseMs` (at most
+ * {@link ACTIVITY_PULSE_MS}): a PreToolUse hook runs before its tool
+ * starts, so nothing else reports activity, and the turn's stall watchdog
+ * would stop a turn whose hook legitimately runs for minutes (Claude's
+ * default timeout is ten). The hook's own timeout bounds the wait instead.
+ */
+/** Claude Code's default command-hook timeout. */
+export declare const DEFAULT_HOOK_TIMEOUT_SECONDS = 600;
+/** The most of each output stream kept; the rest is dropped. */
+export declare const OUTPUT_CAP_BYTES: number;
+/**
+ * How long the runner keeps reading a command's output after the command
+ * exits. A helper it started in the background may hold the pipes open for
+ * as long as it lives; the command's own answer is written by then.
+ */
+export declare const EXIT_DRAIN_MS = 250;
+/** How often, at most, a running hook reports that the turn is alive. */
+export declare const ACTIVITY_PULSE_MS = 30000;
+/**
+ * The pulse for a turn whose stall watchdog fires after `stallTimeoutMs`:
+ * a third of it, so a lowered timeout still sees every running hook alive,
+ * and never more than {@link ACTIVITY_PULSE_MS}.
+ */
+export declare function activityPulseFor(stallTimeoutMs: number): number;
+/**
+ * A handler's timeout as a timer delay. The contract bounds it only from
+ * below, and a delay past the timer's limit would fire at once and kill
+ * every run, so a longer one waits as long as a timer can (about 24 days);
+ * the turn's stop still ends it.
+ */
+export declare function hookTimeoutMs(timeoutSeconds: number): number;
+/** The shell a shell-form handler runs in. */
+export declare const HOOK_SHELL = "bash";
+/** One command to run. */
+export interface HookProcessSpec {
+    readonly command: string;
+    /** Exec form's arguments; `null` runs `command` in {@link HOOK_SHELL}. */
+    readonly args: readonly string[] | null;
+    readonly timeoutSeconds: number;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly stdin: string;
+}
+/** What a run produced. */
+export interface HookRunResult {
+    /** The exit code; `null` when the command did not exit by itself (killed, or never started). */
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    /** Set when the command could not be started. */
+    readonly spawnError?: string;
+}
+export interface HookRunOptions {
+    /** The turn's stop: aborting it kills the command. */
+    readonly signal?: AbortSignal;
+    /** Called every `pulseMs` while the command lives. */
+    readonly onPulse?: () => void;
+    /** How often `onPulse` is called; {@link ACTIVITY_PULSE_MS} when absent. */
+    readonly pulseMs?: number;
+}
+/** The function the evaluator runs commands through; a test substitutes its own. */
+export type HookProcessRunner = (spec: HookProcessSpec, options: HookRunOptions) => Promise<HookRunResult>;
+export declare const runHookProcess: HookProcessRunner;
+/** A stream's text, kept up to {@link OUTPUT_CAP_BYTES}; exported for its test. */
+export declare class CappedText {
+    private readonly chunks;
+    private size;
+    add(chunk: Buffer): void;
+    text(): string;
+}

package/dist/shared/hooks/run.js

@@ -0,0 +1,146 @@
+/**
+ * Run one hook command — the evaluator's one impure seam.
+ *
+ * As Claude Code runs a command hook: exec form (`args` set) spawns the
+ * command with its arguments and no shell; shell form runs the command in
+ * `bash -c`. The call's JSON is written to stdin and stdin is closed; each
+ * output stream is kept up to {@link OUTPUT_CAP_BYTES}. The working
+ * directory is the workspace root and the environment is the caller's (the
+ * agent shell's, plus the hook's own variables, `evaluate.ts`).
+ *
+ * The command gets its own process group, and the whole group is killed when
+ * its timeout passes or the turn is stopped, so a hook that forks cannot
+ * keep its call waiting. A child it leaves running after it exits by itself
+ * is left alone (a hook may start a helper on purpose), and its answer is
+ * the command's: the runner settles {@link EXIT_DRAIN_MS} after the command
+ * exits even when a helper still holds the output pipes. A timed-out or failed command answers no decision; what it
+ * printed is kept for the log.
+ *
+ * While the command lives, `onPulse` is called every `pulseMs` (at most
+ * {@link ACTIVITY_PULSE_MS}): a PreToolUse hook runs before its tool
+ * starts, so nothing else reports activity, and the turn's stall watchdog
+ * would stop a turn whose hook legitimately runs for minutes (Claude's
+ * default timeout is ten). The hook's own timeout bounds the wait instead.
+ */
+import { spawn } from "node:child_process";
+/** Claude Code's default command-hook timeout. */
+export const DEFAULT_HOOK_TIMEOUT_SECONDS = 600;
+/** The most of each output stream kept; the rest is dropped. */
+export const OUTPUT_CAP_BYTES = 1024 * 1024;
+/**
+ * How long the runner keeps reading a command's output after the command
+ * exits. A helper it started in the background may hold the pipes open for
+ * as long as it lives; the command's own answer is written by then.
+ */
+export const EXIT_DRAIN_MS = 250;
+/** How often, at most, a running hook reports that the turn is alive. */
+export const ACTIVITY_PULSE_MS = 30_000;
+/**
+ * The pulse for a turn whose stall watchdog fires after `stallTimeoutMs`:
+ * a third of it, so a lowered timeout still sees every running hook alive,
+ * and never more than {@link ACTIVITY_PULSE_MS}.
+ */
+export function activityPulseFor(stallTimeoutMs) {
+    return Math.max(1, Math.min(ACTIVITY_PULSE_MS, Math.floor(stallTimeoutMs / 3)));
+}
+/** The longest delay a timer keeps; a longer one fires at once. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * A handler's timeout as a timer delay. The contract bounds it only from
+ * below, and a delay past the timer's limit would fire at once and kill
+ * every run, so a longer one waits as long as a timer can (about 24 days);
+ * the turn's stop still ends it.
+ */
+export function hookTimeoutMs(timeoutSeconds) {
+    return Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
+}
+/** The shell a shell-form handler runs in. */
+export const HOOK_SHELL = "bash";
+export const runHookProcess = (spec, options) => new Promise((resolve) => {
+    let child;
+    try {
+        child = spec.args === null
+            ? spawn(HOOK_SHELL, ["-c", spec.command], { cwd: spec.cwd, env: spec.env, detached: true, stdio: "pipe" })
+            : spawn(spec.command, [...spec.args], { cwd: spec.cwd, env: spec.env, detached: true, stdio: "pipe" });
+    }
+    catch (err) {
+        // A command Node refuses outright (a NUL byte in it) never starts.
+        resolve({ exitCode: null, stdout: "", stderr: "", timedOut: false, spawnError: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    const stdout = new CappedText();
+    const stderr = new CappedText();
+    let timedOut = false;
+    let settled = false;
+    const killGroup = () => {
+        if (child.pid === undefined)
+            return;
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch {
+            // Already gone.
+        }
+    };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        killGroup();
+    }, hookTimeoutMs(spec.timeoutSeconds));
+    const pulse = options.onPulse ? setInterval(options.onPulse, options.pulseMs ?? ACTIVITY_PULSE_MS) : undefined;
+    const onAbort = () => killGroup();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (pulse)
+            clearInterval(pulse);
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve(result);
+    };
+    child.stdout.on("data", (chunk) => stdout.add(chunk));
+    child.stderr.on("data", (chunk) => stderr.add(chunk));
+    child.on("error", (err) => {
+        finish({ exitCode: null, stdout: stdout.text(), stderr: stderr.text(), timedOut, spawnError: err.message });
+    });
+    let exitCode = null;
+    let drain;
+    const settle = () => {
+        if (drain)
+            clearTimeout(drain);
+        finish({ exitCode: timedOut ? null : exitCode, stdout: stdout.text(), stderr: stderr.text(), timedOut });
+    };
+    child.on("exit", (code) => {
+        exitCode = code;
+        // A background helper may keep the pipes open; stop reading soon after.
+        drain = setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+            settle();
+        }, EXIT_DRAIN_MS);
+    });
+    child.on("close", settle);
+    // A command that never reads its input closes the pipe first; that is not a failure.
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(spec.stdin);
+    if (options.signal?.aborted)
+        killGroup();
+});
+/** A stream's text, kept up to {@link OUTPUT_CAP_BYTES}; exported for its test. */
+export class CappedText {
+    chunks = [];
+    size = 0;
+    add(chunk) {
+        const room = OUTPUT_CAP_BYTES - this.size;
+        if (room <= 0)
+            return;
+        const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+        this.chunks.push(kept);
+        this.size += kept.length;
+    }
+    text() {
+        return Buffer.concat(this.chunks).toString("utf-8");
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/shared/hooks/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/shared/hooks/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAuC,MAAM,oBAAoB,CAAC;AAEhF,kDAAkD;AAClD,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAsB;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,mEAAmE;AACnE,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,cAAsB;IAClD,OAAO,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC;AACvD,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AAoCjC,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CACjE,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,IAAI,KAAqC,CAAC;IAC1C,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI;YACxB,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAC1G,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3G,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mEAAmE;QACnE,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnI,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;IAChC,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;IAChC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,SAAS,GAAG,GAAS,EAAE;QAC3B,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO;QACpC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,gBAAgB;QAClB,CAAC;IACH,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,EAAE,CAAC;IACd,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/G,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,SAAS,EAAE,CAAC;IACxC,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAEnE,MAAM,MAAM,GAAG,CAAC,MAAqB,EAAQ,EAAE;QAC7C,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,aAAa,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACxB,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9G,CAAC,CAAC,CAAC;IACH,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,KAAiC,CAAC;IACtC,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3G,CAAC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,QAAQ,GAAG,IAAI,CAAC;QAChB,wEAAwE;QACxE,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,EAAE,CAAC;QACX,CAAC,EAAE,aAAa,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE1B,qFAAqF;IACrF,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;QAAE,SAAS,EAAE,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,mFAAmF;AACnF,MAAM,OAAO,UAAU;IACJ,MAAM,GAAa,EAAE,CAAC;IAC/B,IAAI,GAAG,CAAC,CAAC;IAEjB,GAAG,CAAC,KAAa;QACf,MAAM,IAAI,GAAG,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1C,IAAI,IAAI,IAAI,CAAC;YAAE,OAAO;QACtB,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,IAAI;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/shared/hooks/setup.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A turn's hooks, turned into the evaluator (`evaluate.ts`): the half of the
+ * setup no engine owns. Each engine's adapter passes the runtime's resolved
+ * sources (every plugin mounted and verified) with its own views of its
+ * calls (`tool-view.ts` for the native engine, `execute-cursor/
+ * hook-views.ts` for Cursor), and gets the evaluator back, or `null` when
+ * the agent has no hook either engine runs.
+ *
+ * What a hook runs WITH is the agent shell's, on both engines: the runner's
+ * process environment less its credentials, plus the agent's own run values
+ * (`../shell-env.ts`), never a tool's. They are
+ * built even in plan mode, where the agent has no shell, because hooks
+ * still run there. A plugin's `${user_config.KEY}` resolves from that
+ * plugin's own values (`RunValues.plugins`), never another plugin's or the
+ * agent's; the agent's own block resolves from the agent's.
+ *
+ * A subagent's calls run the conversation's hooks, then the subagent's
+ * own. A source of the subagent's carries its values (`shellValues`): its
+ * own block resolves from them, and every command of the source runs in
+ * the subagent's shell environment instead of the agent's, so a
+ * subagent's hook never holds the agent's keys and the agent's never holds
+ * the subagent's. One the run
+ * does not have refuses the turn, naming the variable and the plugin, and
+ * so does a shell-form handler (every Cursor handler is one) when no `bash`
+ * is on the hook's `PATH`. A hook that cannot run as
+ * written is a policy that vanished, and Stigmer has no enable-time prompt
+ * to ask for the value instead; what a single run does with a missing
+ * script or a failing exit stays its format's rule.
+ */
+import type { HookGroup } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/hooks_pb";
+import type { ResolvedMcpServer } from "../mcp-resolver.js";
+import type { MountedPlugin } from "../plugin-mount.js";
+import { type RunValues } from "../run-values.js";
+import { HookEvaluator, type HookPermissionMode } from "./evaluate.js";
+import { type HookFormatName } from "./hook-set.js";
+import type { HookToolViews } from "./tool-view.js";
+/** The agent's hooks cannot run as written this turn; the message names what and why. */
+export declare class HookSetupError extends Error {
+    constructor(message: string);
+}
+/** What the setup reads from the turn, as each adapter hands it over. */
+export interface HookSetupInput {
+    /** The runtime's resolved sources, in the agent's order. */
+    readonly sources: readonly {
+        readonly plugin: MountedPlugin | null;
+        readonly format: HookFormatName;
+        readonly groups: readonly HookGroup[];
+        /** A subagent's source: that subagent's values, which its own block reads and its commands run with (the module header). */
+        readonly shellValues?: Readonly<Record<string, string>>;
+        /** A subagent's source: that subagent's name, which a refusal names. */
+        readonly subagent?: string;
+    }[];
+    /** The run's values, per declarer (`TurnInput.values`). */
+    readonly runValues: Pick<RunValues, "agent" | "tools" | "plugins">;
+    readonly mcpServers: readonly ResolvedMcpServer[];
+    /** The engine's views of its calls. */
+    readonly views: HookToolViews;
+    readonly sessionId: string;
+    readonly executionId: string;
+    readonly model: string;
+    readonly workspaceRoot: string;
+    readonly permissionMode: HookPermissionMode;
+    /** The hook leases this run holds (`ActiveLeases.hooks`). */
+    readonly leases: ReadonlySet<string>;
+    readonly signal: AbortSignal;
+    readonly onActivity: (detail: string) => void;
+    /** The turn's stall timeout; a running hook pulses often enough to stay inside it. */
+    readonly stallTimeoutMs: number;
+}
+/** The turn's hook evaluator, or `null` when the agent has no hook this runner runs. Throws {@link HookSetupError}. */
+export declare function buildHookEvaluator(input: HookSetupInput): Promise<HookEvaluator | null>;
+/** Claude Code's `permission_mode` for a turn: `plan` in plan mode, `bypassPermissions` under the pre-armed bypass. */
+export declare function hookPermissionMode(planMode: boolean, globalBypass: boolean): HookPermissionMode;

package/dist/shared/hooks/setup.js

@@ -0,0 +1,166 @@
+/**
+ * A turn's hooks, turned into the evaluator (`evaluate.ts`): the half of the
+ * setup no engine owns. Each engine's adapter passes the runtime's resolved
+ * sources (every plugin mounted and verified) with its own views of its
+ * calls (`tool-view.ts` for the native engine, `execute-cursor/
+ * hook-views.ts` for Cursor), and gets the evaluator back, or `null` when
+ * the agent has no hook either engine runs.
+ *
+ * What a hook runs WITH is the agent shell's, on both engines: the runner's
+ * process environment less its credentials, plus the agent's own run values
+ * (`../shell-env.ts`), never a tool's. They are
+ * built even in plan mode, where the agent has no shell, because hooks
+ * still run there. A plugin's `${user_config.KEY}` resolves from that
+ * plugin's own values (`RunValues.plugins`), never another plugin's or the
+ * agent's; the agent's own block resolves from the agent's.
+ *
+ * A subagent's calls run the conversation's hooks, then the subagent's
+ * own. A source of the subagent's carries its values (`shellValues`): its
+ * own block resolves from them, and every command of the source runs in
+ * the subagent's shell environment instead of the agent's, so a
+ * subagent's hook never holds the agent's keys and the agent's never holds
+ * the subagent's. One the run
+ * does not have refuses the turn, naming the variable and the plugin, and
+ * so does a shell-form handler (every Cursor handler is one) when no `bash`
+ * is on the hook's `PATH`. A hook that cannot run as
+ * written is a policy that vanished, and Stigmer has no enable-time prompt
+ * to ask for the value instead; what a single run does with a missing
+ * script or a failing exit stays its format's rule.
+ */
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { buildShellEnv, shellRunValues } from "../shell-env.js";
+import { toolValuesKey } from "../run-values.js";
+import { HookEvaluator } from "./evaluate.js";
+import { HookSet, isRunEvent, userConfigKeys } from "./hook-set.js";
+import { activityPulseFor, HOOK_SHELL } from "./run.js";
+/** The agent's hooks cannot run as written this turn; the message names what and why. */
+export class HookSetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HookSetupError";
+    }
+}
+/** The turn's hook evaluator, or `null` when the agent has no hook this runner runs. Throws {@link HookSetupError}. */
+export async function buildHookEvaluator(input) {
+    if (input.sources.length === 0)
+        return null;
+    const values = shellRunValues(input.runValues);
+    const sources = input.sources.map(({ plugin, format, groups, shellValues, subagent }) => {
+        const owner = subagent === undefined ? "the agent" : `the subagent '${subagent}'`;
+        const who = plugin === null
+            ? subagent === undefined ? "A hook in the agent's own hooks block" : `A hook in ${owner}'s own hooks block`
+            : `A hook of the plugin '${plugin.slug}'`;
+        const handlers = groups.filter((group) => isRunEvent(group.event, format)).flatMap((group) => group.handlers);
+        if (format === "claude-code" && handlers.some((handler) => handler.args.length === 0 && handler.command.includes("${user_config."))) {
+            throw new HookSetupError(`${who} reads \${user_config.*} in a command that runs in ${HOOK_SHELL}, where the value is not substituted. ` +
+                "Pass it in args (exec form), then run again.");
+        }
+        const options = new Map();
+        const own = plugin === null ? (shellValues ?? values) : (input.runValues.plugins.get(plugin.id) ?? {});
+        for (const key of format === "claude-code" ? handlers.flatMap(userConfigKeys) : []) {
+            const value = own[key];
+            if (value === undefined) {
+                const claimant = toolHolding(input, key);
+                throw new HookSetupError(claimant === undefined
+                    ? plugin === null
+                        ? `${who} reads the variable ${key}, which this run does not give ${owner}. ` +
+                            `Declare ${key} in ${owner}'s env and set its value, then run again.`
+                        : `${who} reads the variable ${key}, which none of this conversation's vaults holds. ` +
+                            `Save ${key} in one of them, then run again.`
+                    : `${who} reads the variable ${key}, which this run keeps for its MCP server '${claimant}' ` +
+                        "and gives neither the agent's shell nor its hooks. Give the hook a variable of its own, then run again.");
+            }
+            options.set(key, value);
+        }
+        const env = shellValues === undefined ? {} : { env: buildShellEnv(shellValues) };
+        return {
+            source: plugin === null
+                ? { plugin: "", root: "", data: "", options, ...env }
+                : { plugin: plugin.slug, root: plugin.root, data: plugin.data, options, beforeRun: plugin.verify, ...env },
+            format,
+            groups,
+        };
+    });
+    const set = HookSet.of(sources);
+    if (set.isEmpty)
+        return null;
+    const baseEnv = buildShellEnv(values);
+    if (set.needsShell && !(await onPath(HOOK_SHELL, baseEnv["PATH"] ?? ""))) {
+        throw new HookSetupError(`The agent's hooks include a command that runs in ${HOOK_SHELL}, and no ${HOOK_SHELL} is on this runner's PATH. ` +
+            `Install ${HOOK_SHELL}, or write the hook in exec form (with args).`);
+    }
+    return new HookEvaluator({
+        set,
+        views: input.views,
+        sessionId: input.sessionId,
+        executionId: input.executionId,
+        model: input.model,
+        workspaceRoot: input.workspaceRoot,
+        permissionMode: input.permissionMode,
+        baseEnv,
+        homeDir: homedir(),
+        leases: input.leases,
+        signal: input.signal,
+        onActivity: input.onActivity,
+        activityPulseMs: activityPulseFor(input.stallTimeoutMs),
+    });
+}
+/** The key a resolved server's values are grouped by; none for the platform's, which the fetch never answers. */
+function valuesKeyOf(server) {
+    switch (server.home.kind) {
+        case "plugin":
+            return toolValuesKey("plugin", server.home.pluginId, server.home.server);
+        case "agent":
+            return toolValuesKey("agent", server.home.agentId, server.home.server);
+        case "platform":
+            return undefined;
+        /* v8 ignore next -- @preserve: the exhaustiveness guard over a closed union; no value reaches it */
+        default: {
+            const exhaustive = server.home;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * The MCP server a run value belongs to, by its group in the run's values:
+ * the name of the resolved server of that home and key, or the server's own
+ * name in its home for a server that did not resolve this turn (the last
+ * part of the group key; the parts before it name the home's kind and id,
+ * never shown). `undefined` when no tool holds it.
+ */
+function toolHolding(input, key) {
+    for (const [groupKey, group] of input.runValues.tools) {
+        if (!(key in group.values))
+            continue;
+        const server = input.mcpServers.find((candidate) => valuesKeyOf(candidate) === groupKey);
+        return server?.slug ?? groupKey.slice(groupKey.lastIndexOf("\u0000") + 1);
+    }
+    return undefined;
+}
+/** Claude Code's `permission_mode` for a turn: `plan` in plan mode, `bypassPermissions` under the pre-armed bypass. */
+export function hookPermissionMode(planMode, globalBypass) {
+    if (planMode)
+        return "plan";
+    if (globalBypass)
+        return "bypassPermissions";
+    return "default";
+}
+/** Whether an executable named `name` is on `path`. */
+async function onPath(name, path) {
+    for (const dir of path.split(delimiter)) {
+        if (dir === "")
+            continue;
+        try {
+            await access(join(dir, name), constants.X_OK);
+            return true;
+        }
+        catch {
+            // Not here.
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=setup.js.map

package/dist/shared/hooks/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/shared/hooks/setup.ts"],"names":[],"mappings":"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"}

package/dist/shared/hooks/shell-commands.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Split a shell command line into the simple commands it runs, for matching
+ * a `Bash(...)` permission rule against each (`condition.ts`).
+ *
+ * Claude Code matches a Bash rule against every subcommand: it splits on
+ * `&&`, `||`, `;`, `|`, `|&`, `&` and newlines, and reaches into subshells
+ * and command substitutions. This is a small scanner for exactly that, not
+ * a shell: it understands quotes and escapes, collects `$( )`, backticks
+ * and a leading `( )` as nested command lines, and returns each simple
+ * command as its words with the quotes removed. The shell's own words that
+ * open or close a compound command (`if`, `then`, `do`, `{`, `!`, `fi`,
+ * `done`, `}` and the rest) are not commands: they are dropped, so
+ * `if true; then rm -rf build; fi` runs `true` and `rm -rf build`. An
+ * interpreter's `-c` script (`bash -c`, `bash -lc`, `/bin/sh -ec`, behind a
+ * wrapper or not) is scanned as one more command line.
+ *
+ * A word is literal only when the shell would run it as written. An
+ * unquoted `$`, glob character (`*`, `?`, `[`), `~`, brace (`{a,b}`
+ * expands) or redirection (`>out` before a command) makes it not literal,
+ * and the caller treats such a word as possibly anything.
+ *
+ * Its one safety rule: what it cannot be sure it understood answers `null`,
+ * and the caller then runs the hook. An unbalanced quote or bracket, a
+ * heredoc, `eval`, a `function` definition, arithmetic that runs a command
+ * (`$(( $(…) ))`), and `sh -c` or `bash -c` over anything but a literal
+ * string are all `null`. Matching too widely runs a hook more often and the
+ * hook still decides; matching too narrowly would skip a policy.
+ */
+/** One word of a simple command. */
+export interface ShellWord {
+    /** The word with its quotes and escapes removed. */
+    readonly text: string;
+    /** False when the shell would expand something in it (`$`, a substitution, unquoted `*`). */
+    readonly literal: boolean;
+}
+/** A simple command: its words, in order. */
+export type ShellCommand = readonly ShellWord[];
+/** Every simple command `line` runs, nested ones included; `null` when it cannot be sure. */
+export declare function splitShellCommands(line: string): readonly ShellCommand[] | null;