howtofixcli 0.7.24 → 0.7.26

package/dist/hooks-extension.js

@@ -0,0 +1,176 @@
+import { readMessageText, writeMessageText } from "./prompt-text.js";
+import { HOOKS_FILE, checkToolInput, loadHooks, resetOnceHooks, runHooksFor } from "./hooks.js";
+/** Read once per session; see the note above. */
+let config = { hooks: {} };
+/** Context a `SessionStart` hook contributed, kept for the session's prompts. */
+let sessionContext;
+export function createHooksExtension() {
+    return (hxf) => {
+        // Read the config HERE, in the factory, not in `session_start`.
+        //
+        // Measured: `session_start` does not fire in `-p` print mode — one-shot runs
+        // are exactly where a `PreToolUse` hook matters most (an unattended agent is
+        // the one you want policed), and loading in the lifecycle event left `config`
+        // empty there, so every hook silently did nothing. The factory runs in every
+        // mode. The read is one small synchronous file; it happens once per process.
+        const loaded = loadHooks(HOOKS_FILE);
+        config = loaded.config;
+        sessionContext = undefined;
+        // A resumed session re-arms its `once` hooks: the ledger is per process, and
+        // the session that just opened is a new one from the hook's point of view.
+        resetOnceHooks();
+        hxf.on("session_start", async (_event, ctx) => {
+            for (const diagnostic of loaded.diagnostics) {
+                ctx.ui.notify(`hooks.json: ${diagnostic.message}`, "warning");
+            }
+            const { outcome, ran } = await runHooksFor(config, "SessionStart", { hook_event_name: "SessionStart", cwd: ctx.cwd }, { cwd: ctx.cwd });
+            if (outcome.context)
+                sessionContext = outcome.context;
+            if (outcome.error)
+                ctx.ui.notify(`SessionStart hook: ${outcome.error}`, "warning");
+            if (ran && sessionContext) {
+                ctx.ui.notify(`SessionStart hooks added ${sessionContext.length} characters of context`, "info");
+            }
+        });
+        // `UserPromptSubmit` may block a prompt or add to it. The SDK's `input` event
+        // is the only place a prompt can be replaced before the run starts.
+        hxf.on("input", async (event, ctx) => {
+            if (!config.hooks.UserPromptSubmit)
+                return undefined;
+            const payload = {
+                hook_event_name: "UserPromptSubmit",
+                cwd: ctx.cwd,
+                prompt: event.text,
+            };
+            const { outcome } = await runHooksFor(config, "UserPromptSubmit", payload, { cwd: ctx.cwd });
+            if (outcome.error)
+                ctx.ui.notify(`UserPromptSubmit hook: ${outcome.error}`, "warning");
+            if (outcome.block) {
+                ctx.ui.notify(outcome.reason ?? "blocked by a hook", "warning");
+                return { action: "handled" };
+            }
+            if (!outcome.context)
+                return undefined;
+            return { action: "transform", text: `${event.text}\n\n${outcome.context}` };
+        });
+        // `PreToolUse` is the one that can refuse — or rewrite. It runs before the
+        // approval gate because a hook is the user's own policy and must not be
+        // overridable by an approval mode.
+        hxf.on("tool_call", async (event, ctx) => {
+            if (!config.hooks.PreToolUse)
+                return undefined;
+            const payload = {
+                hook_event_name: "PreToolUse",
+                cwd: ctx.cwd,
+                tool_name: event.toolName,
+                tool_input: event.input,
+            };
+            const { outcome } = await runHooksFor(config, "PreToolUse", payload, { cwd: ctx.cwd });
+            if (outcome.error)
+                ctx.ui.notify(`PreToolUse hook: ${outcome.error}`, "warning");
+            if (outcome.block) {
+                return { block: true, reason: outcome.reason ?? "blocked by a hook" };
+            }
+            // A rewrite replaces what the tool will actually do, so it is validated
+            // against the tool's own schema before it is used — the same schema the
+            // provider was given, read from the SDK's own registry. A rewrite that
+            // fails is dropped and the original arguments run: a guard must not be able
+            // to turn itself into a way to run something the model never asked for.
+            if (outcome.updatedInput) {
+                const tools = hxf.getAllTools();
+                const schema = tools.find((tool) => tool.name === event.toolName)?.parameters;
+                if (!schema) {
+                    ctx.ui.notify(`PreToolUse hook rewrote \`${event.toolName}\`, but no schema is known for that tool — the rewrite was ignored`, "warning");
+                }
+                else {
+                    const problem = checkToolInput(schema, outcome.updatedInput);
+                    if (problem) {
+                        ctx.ui.notify(`PreToolUse hook rewrite ignored — ${problem}`, "warning");
+                    }
+                    else {
+                        // The SDK's documented way to change arguments: mutate in place.
+                        Object.assign(event.input, outcome.updatedInput);
+                    }
+                }
+            }
+            return undefined;
+        });
+        // `PostToolUse` adds context to what the tool returned. The event is
+        // `tool_result`, and the result's `content` is replaced with the hook's text
+        // appended — `structuredContent` is returned alongside it so it is not
+        // dropped (the SDK drops it otherwise).
+        hxf.on("tool_result", async (event, ctx) => {
+            if (!config.hooks.PostToolUse)
+                return undefined;
+            const text = event.content.map((block) => (block.type === "text" ? block.text : "")).join("\n");
+            const payload = {
+                hook_event_name: "PostToolUse",
+                cwd: ctx.cwd,
+                tool_name: event.toolName,
+                tool_input: event.input,
+                tool_result: text,
+                tool_is_error: event.isError,
+            };
+            const { outcome } = await runHooksFor(config, "PostToolUse", payload, { cwd: ctx.cwd });
+            if (outcome.error)
+                ctx.ui.notify(`PostToolUse hook: ${outcome.error}`, "warning");
+            if (!outcome.context)
+                return undefined;
+            return {
+                content: [...event.content, { type: "text", text: `\n[hook] ${outcome.context}` }],
+                structuredContent: event.structuredContent,
+            };
+        });
+        // `SessionStart` context reaches the model through the same path the shared
+        // notes use: appended to the leading system message, which must stay at index
+        // 0 because that is where the provider reads the prompt from.
+        hxf.on("context_with_system", async (event) => {
+            if (!sessionContext)
+                return undefined;
+            const head = event.messages[0];
+            if (!head || head.role !== "system")
+                return undefined;
+            const combined = `${readMessageText(head.content)}\n\n${sessionContext}`;
+            const messages = event.messages.map((message) => (message === head ? { ...head, content: writeMessageText(head.content, combined) } : message));
+            return { messages };
+        });
+        // `PreCompact` observes a compaction before it happens — the moment context
+        // is about to be thrown away. Notification only: the SDK's compaction result
+        // is not something a shell command should be able to veto, and a hook that
+        // could would be a way to wedge a session at its most fragile point.
+        hxf.on("session_before_compact", async (event, ctx) => {
+            if (!config.hooks.PreCompact)
+                return;
+            const { outcome } = await runHooksFor(config, "PreCompact", {
+                hook_event_name: "PreCompact",
+                cwd: ctx.cwd,
+                compact_reason: event.reason,
+            }, { cwd: ctx.cwd });
+            if (outcome.error)
+                ctx.ui.notify(`PreCompact hook: ${outcome.error}`, "warning");
+        });
+        // `SessionEnd` for a session that is **replaced** (`/new`, `/resume`, a fork).
+        //
+        // Measured: this event does NOT fire when the process exits — `/quit` and
+        // double Ctrl+C produced zero events, even for a TypeScript extension writing
+        // synchronously. The quit path is therefore handled in `ui.ts`'s `shutdown()`,
+        // which runs the same hooks and awaits them. This handler covers the other
+        // moment the session ends: being swapped for another one.
+        hxf.on("session_shutdown", async (event, ctx) => {
+            if (!config.hooks.SessionEnd)
+                return;
+            const { outcome } = await runHooksFor(config, "SessionEnd", { hook_event_name: "SessionEnd", cwd: ctx.cwd, reason: event.reason }, { cwd: ctx.cwd });
+            if (outcome.error)
+                ctx.ui.notify(`SessionEnd hook: ${outcome.error}`, "warning");
+        });
+        // `Stop` is notification-only: it fires when the run will not continue on its
+        // own, which is the moment an integration wants to know about.
+        hxf.on("agent_settled", async (_event, ctx) => {
+            if (!config.hooks.Stop)
+                return;
+            const { outcome } = await runHooksFor(config, "Stop", { hook_event_name: "Stop", cwd: ctx.cwd }, { cwd: ctx.cwd });
+            if (outcome.error)
+                ctx.ui.notify(`Stop hook: ${outcome.error}`, "warning");
+        });
+    };
+}

package/dist/hooks.js

@@ -0,0 +1,443 @@
+/**
+ * User-configured hooks: shell commands that run at lifecycle points.
+ *
+ * Why this exists: every extension in this CLI is compiled into the bundle. A
+ * user who wants "run prettier after every edit" or "refuse any `rm -rf`" or
+ * "add our house rules to every prompt" has to edit the source and rebuild — or
+ * repeat themselves every session. Claude Code answers this with **hooks**: a
+ * JSON config naming a shell command per lifecycle point, and a stdin/stdout
+ * contract the command speaks. That is the right shape for this because the
+ * command can be anything the user already has — a script, `jq`, a linter — with
+ * no build step and no TypeScript.
+ *
+ * The SDK's extension API is the substrate (`hxf.on(...)` exposes 48 events), but
+ * it requires code in the bundle. This module is the declarative layer on top: a
+ * config file, mapped onto the SDK's own events.
+ *
+ *   <AGENT_DIR>/hooks.json
+ *
+ * ## The contract (deliberately Claude Code's, so it is already familiar)
+ *
+ * The command receives a JSON payload on **stdin** and answers on **stdout**:
+ *
+ * - **exit 0** — allowed. `stdout` may carry JSON with a `hookSpecificOutput`
+ *   block (see below). Plain text on stdout is added as context where the event
+ *   has a place for it.
+ * - **exit 2** — blocked. `stderr` is the reason the model and the user are
+ *   shown. This is Claude Code's convention and it is the useful one: a hook
+ *   needs a way to say no that is not the same as "the hook crashed".
+ * - **any other exit** — the hook failed. It is reported and the action is
+ *   allowed, because a broken linter must not become a broken session.
+ *
+ * `hookSpecificOutput` fields, matching Claude Code:
+ *
+ * ```json
+ * { "hookSpecificOutput": {
+ *     "hookEventName": "PreToolUse",
+ *     "permissionDecision": "deny",
+ *     "permissionDecisionReason": "no rm -rf in this repo",
+ *     "additionalContext": "…" } }
+ * ```
+ *
+ * ## What is supported, and what is not
+ *
+ * Supported: `PreToolUse` (block a call, or rewrite its arguments),
+ * `PostToolUse` (add context after one), `UserPromptSubmit` (add context to a
+ * prompt, or block it), `SessionStart` (add context once per session), `Stop`
+ * (notification when a run settles), `PreCompact` (observe a compaction),
+ * `SessionEnd` (observe a shutdown).
+ *
+ * Not supported, and named rather than silently ignored: `SubagentStop`,
+ * `Notification`, `PermissionRequest`, `PostToolUseFailure` do not map onto an
+ * event this CLI can act on yet. An unknown name is reported at load, never
+ * dropped quietly — a hook the user wrote that never fires is worse than a
+ * config error.
+ *
+ * ## Rules that are load-bearing
+ *
+ * - **A rewritten tool input is validated before it is used.** `updatedInput` is
+ *   the most dangerous field in the contract: it replaces what the tool will
+ *   actually do. Claude Code rejects a rewrite that fails the tool's schema, and
+ *   so do we — an unvalidated rewrite turns a guard into a weapon. The schema
+ *   comes from the SDK's own `getAllTools()`, so it is the same one the provider
+ *   was given.
+ * - **A rewrite is applied only when nothing blocks.** A hook that denies wins
+ *   over one that rewrites: refusing is the stronger statement.
+ * - **A hook is a subprocess on an interactive path, so it must be async and
+ *   bounded.** Every spawn is `spawn` (never `execFileSync`) with a per-hook
+ *   timeout, because a hung hook would otherwise freeze the TUI for as long as
+ *   the process lives. On timeout the hook is killed and the action is allowed.
+ * - **A hook that cannot run is not a reason to refuse to work.** A missing
+ *   config, unreadable file, bad JSON, or a command that does not exist all
+ *   degrade to "no hooks" with a diagnostic.
+ * - **The config is read once per session**, not per tool call. Re-reading a file
+ *   on every `tool_call` is a synchronous disk hit on the hot path.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Value } from "typebox/value";
+import { AGENT_DIR } from "./paths.js";
+/** The user's hook config. Named here so the docs and the check script agree. */
+export const HOOKS_FILE = join(AGENT_DIR, "hooks.json");
+/**
+ * A hook config is a payload, not a program. Past this size it is skipped rather
+ * than truncated, for the same reason `APPEND_SYSTEM.md` is: half a config is a
+ * different config.
+ */
+const MAX_BYTES = 64 * 1024;
+/** Claude Code's default. Long enough for a real linter, short enough to not wedge a turn. */
+export const DEFAULT_TIMEOUT_S = 30;
+/** The events this CLI can actually act on. Anything else is reported. */
+export const SUPPORTED_EVENTS = ["PreToolUse", "PostToolUse", "UserPromptSubmit", "SessionStart", "Stop", "PreCompact", "SessionEnd"];
+/**
+ * Validate a rewritten tool input against the tool's own schema.
+ *
+ * The reference is the SDK's own extension runtime: it exposes `typebox/value`
+ * as a **virtual module** for extensions (`core/extensions/virtual-modules.js`),
+ * and uses it to validate the same tool inputs. Writing a hand-rolled checker
+ * instead would be a second, weaker opinion on a question the toolchain already
+ * answers — and the failure mode is the worst kind: a rewrite that passes our
+ * check and then breaks the tool.
+ *
+ * `typebox` is a direct dependency of the SDK, and the schema it gives us
+ * (`ToolInfo.parameters`) is the very one the provider was handed, so this is
+ * the same validation the model's own call goes through.
+ *
+ * Returns `undefined` when the value is acceptable, or a reason it is not.
+ */
+export function checkToolInput(schema, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return "the rewrite is not a JSON object";
+    }
+    if (schema === null || typeof schema !== "object")
+        return undefined;
+    try {
+        if (Value.Check(schema, value))
+            return undefined;
+        const first = [...Value.Errors(schema, value)][0];
+        if (!first)
+            return "the rewrite does not match the tool's schema";
+        const at = "instancePath" in first ? String(first.instancePath) : "";
+        const where = at && at !== "/" ? ` at \`${at}\`` : "";
+        return `the rewrite does not match the tool's schema${where}: ${first.message}`;
+    }
+    catch (error) {
+        // A schema TypeBox cannot walk (an exotic tool, a future shape) must not
+        // become a reason to refuse the call: the rewrite is dropped and the tool
+        // runs with its original arguments.
+        return `the tool's schema could not be checked: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+/**
+ * Read and validate the config. Never throws: a broken config must leave the
+ * session working, with a diagnostic saying what was wrong.
+ */
+export function loadHooks(path = HOOKS_FILE) {
+    const diagnostics = [];
+    const empty = { hooks: {} };
+    try {
+        if (!existsSync(path))
+            return { config: empty, diagnostics };
+        const raw = readFileSync(path, "utf8");
+        if (Buffer.byteLength(raw, "utf8") > MAX_BYTES) {
+            diagnostics.push({ source: path, message: `skipped: larger than ${MAX_BYTES} bytes` });
+            return { config: empty, diagnostics };
+        }
+        const parsed = JSON.parse(raw);
+        const result = validateHooks(parsed);
+        for (const message of result.diagnostics)
+            diagnostics.push({ source: path, message });
+        return { config: result.config, diagnostics };
+    }
+    catch (error) {
+        diagnostics.push({
+            source: path,
+            message: `unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return { config: empty, diagnostics };
+    }
+}
+/**
+ * Validate a parsed config. Pure, so the shape rules are testable without a
+ * session or a file — including the two that matter most: an unsupported event
+ * name is *reported*, and a malformed entry is dropped rather than taking the
+ * whole config with it.
+ */
+export function validateHooks(parsed) {
+    const diagnostics = [];
+    const config = { hooks: {} };
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { config, diagnostics: ["expected a JSON object with a `hooks` key"] };
+    }
+    const hooks = parsed.hooks;
+    if (hooks === undefined)
+        return { config, diagnostics: ["no `hooks` key"] };
+    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
+        return { config, diagnostics: ["`hooks` must be an object keyed by event name"] };
+    }
+    for (const [name, value] of Object.entries(hooks)) {
+        if (!SUPPORTED_EVENTS.includes(name)) {
+            diagnostics.push(`unknown event \`${name}\` — supported: ${SUPPORTED_EVENTS.join(", ")}`);
+            continue;
+        }
+        if (!Array.isArray(value)) {
+            diagnostics.push(`\`${name}\` must be an array of matchers`);
+            continue;
+        }
+        const matchers = [];
+        for (const entry of value) {
+            const matcher = validateMatcher(entry, name, diagnostics);
+            if (matcher)
+                matchers.push(matcher);
+        }
+        if (matchers.length)
+            config.hooks[name] = matchers;
+    }
+    return { config, diagnostics };
+}
+function validateMatcher(entry, event, diagnostics) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+        diagnostics.push(`\`${event}\`: a matcher must be an object`);
+        return undefined;
+    }
+    const record = entry;
+    const commands = Array.isArray(record.hooks) ? record.hooks : undefined;
+    if (!commands) {
+        diagnostics.push(`\`${event}\`: a matcher needs a \`hooks\` array`);
+        return undefined;
+    }
+    const hooks = [];
+    for (const command of commands) {
+        if (command === null || typeof command !== "object")
+            continue;
+        const c = command;
+        const type = typeof c.type === "string" ? c.type : "command";
+        if (type !== "command") {
+            diagnostics.push(`\`${event}\`: only \`type: "command"\` is supported, got \`${type}\``);
+            continue;
+        }
+        if (typeof c.command !== "string" || !c.command.trim()) {
+            diagnostics.push(`\`${event}\`: a hook needs a non-empty \`command\``);
+            continue;
+        }
+        const timeout = typeof c.timeout === "number" && Number.isFinite(c.timeout) && c.timeout > 0 ? c.timeout : undefined;
+        hooks.push({
+            type: "command",
+            command: c.command,
+            timeout,
+            ...(c.async === true ? { async: true } : {}),
+            ...(c.once === true ? { once: true } : {}),
+        });
+    }
+    if (!hooks.length)
+        return undefined;
+    const matcher = typeof record.matcher === "string" ? record.matcher : undefined;
+    return { matcher, hooks };
+}
+/**
+ * Which matchers fire for a tool. `undefined`, `""`, `*` and a `|`-separated
+ * list all work, because that is how Claude Code's `matcher` reads and a user
+ * arriving from there will write it that way. Case-insensitive: tool names are
+ * written `bash` here and `Bash` there.
+ */
+export function matchersFor(config, event, toolName) {
+    const matchers = config.hooks[event];
+    if (!matchers)
+        return [];
+    return matchers.filter((matcher) => {
+        const pattern = matcher.matcher?.trim();
+        if (!pattern || pattern === "*")
+            return true;
+        if (toolName === undefined)
+            return false;
+        const name = toolName.toLowerCase();
+        return pattern
+            .split("|")
+            .map((part) => part.trim().toLowerCase())
+            .filter(Boolean)
+            .includes(name);
+    });
+}
+/**
+ * Run one hook. Async and bounded: a hook that hangs is killed and reported, so
+ * a bad command cannot freeze the session.
+ */
+export function runHook(command, payload, options = { cwd: process.cwd() }) {
+    const timeoutS = options.timeoutS ?? DEFAULT_TIMEOUT_S;
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        const child = spawn(command, {
+            cwd: options.cwd,
+            shell: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        // A hook that exits without reading stdin closes the pipe under us, and the
+        // write then fails **asynchronously** — an unhandled `error` event on the
+        // socket, which takes the whole process down. `exit 0` and `exit 2` are both
+        // normal hooks and both do this, so the handler is not optional. (The
+        // try/catch around the `end()` call below does not catch it: by then the
+        // write has been queued.)
+        child.stdin?.on("error", () => { });
+        child.stdout?.on("error", () => { });
+        child.stderr?.on("error", () => { });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutS * 1000);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        };
+        child.on("error", (error) => {
+            stderr += error.message;
+            finish(null);
+        });
+        child.on("close", (code) => finish(code));
+        try {
+            child.stdin?.end(JSON.stringify(payload));
+        }
+        catch {
+            // A hook that closes stdin early is not an error; the exit code decides.
+        }
+    });
+}
+/**
+ * Read a hook's answer. Pure, so every branch is testable without spawning.
+ *
+ * The precedence is the point: an explicit `permissionDecision` beats the exit
+ * code, and `exit 2` beats stdout, because a hook that wrote a reason to stderr
+ * and exited 2 means it — that is the convention.
+ */
+export function interpretHookResult(result) {
+    const { code, stdout, stderr, timedOut } = result;
+    const trimmedErr = stderr.trim();
+    if (timedOut)
+        return { block: false, error: `timed out after ${DEFAULT_TIMEOUT_S}s and was killed` };
+    const parsed = parseJsonObject(stdout);
+    // `additionalContext` is the field Claude Code uses for "here is more context";
+    // it is honoured whatever the exit code, because a hook can both add context
+    // and refuse.
+    const specific = parsed?.hookSpecificOutput;
+    const context = typeof specific?.additionalContext === "string" ? specific.additionalContext : typeof parsed?.additionalContext === "string" ? parsed.additionalContext : undefined;
+    const decision = typeof specific?.permissionDecision === "string" ? specific.permissionDecision : undefined;
+    const decisionReason = typeof specific?.permissionDecisionReason === "string" ? specific.permissionDecisionReason : undefined;
+    // `updatedInput` replaces what the tool will actually do. It is read here and
+    // validated by the caller, which is the only place that has the tool's schema.
+    const rewritten = specific?.updatedInput;
+    const updatedInput = rewritten !== null && typeof rewritten === "object" && !Array.isArray(rewritten) ? rewritten : undefined;
+    if (decision === "deny" || decision === "block") {
+        return { block: true, reason: decisionReason || trimmedErr || "denied by a hook", context };
+    }
+    if (decision === "allow")
+        return { block: false, context, updatedInput };
+    if (code === 2)
+        return { block: true, reason: trimmedErr || "blocked by a hook", context };
+    if (code !== 0) {
+        return {
+            block: false,
+            context,
+            updatedInput,
+            error: `exited ${code === null ? "without a status" : code}${trimmedErr ? `: ${trimmedErr}` : ""}`,
+        };
+    }
+    // Exit 0 with plain text is the simple form: the text is the context.
+    if (!parsed && stdout.trim())
+        return { block: false, context: stdout.trim() };
+    return { block: false, context, updatedInput };
+}
+function parseJsonObject(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    try {
+        const value = JSON.parse(trimmed);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return value;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Commands already run, for `once`. Session-scoped by design. */
+const firedOnce = new Set();
+/** Reset the `once` ledger. Called when a session starts, so a resumed session re-arms. */
+export function resetOnceHooks() {
+    firedOnce.clear();
+}
+/**
+ * Run every matcher for an event and combine the outcomes. A block wins over
+ * context and over a rewrite: refusing is the stronger statement, and a hook that
+ * said no meant it. Contexts from every hook are kept, in order, so two hooks can
+ * each add a piece. A rewrite is last-writer-wins, because two hooks rewriting the
+ * same call cannot both be right.
+ *
+ * `async: true` and `once: true` are handled here rather than at each call site,
+ * so no event can forget them. An async hook is started and **not awaited**: it
+ * cannot contribute a decision, only a side effect.
+ */
+export async function runHooksFor(config, event, payload, options) {
+    const matchers = matchersFor(config, event, payload.tool_name);
+    if (!matchers.length)
+        return { outcome: { block: false }, ran: 0 };
+    const contexts = [];
+    let ran = 0;
+    let block;
+    let error;
+    let updatedInput;
+    for (const matcher of matchers) {
+        for (const hook of matcher.hooks) {
+            if (hook.once) {
+                const key = `${event}\u0000${hook.command}`;
+                if (firedOnce.has(key))
+                    continue;
+                firedOnce.add(key);
+            }
+            ran += 1;
+            if (hook.async) {
+                // Started, never awaited. A rejection is swallowed on purpose: an async
+                // hook has no channel to report on, and an unhandled rejection would take
+                // the process down for a log line.
+                void runHook(hook.command, payload, { cwd: options.cwd, timeoutS: hook.timeout }).catch(() => { });
+                continue;
+            }
+            const result = await runHook(hook.command, payload, {
+                cwd: options.cwd,
+                timeoutS: hook.timeout,
+            });
+            const outcome = interpretHookResult(result);
+            if (outcome.context)
+                contexts.push(outcome.context);
+            if (outcome.error)
+                error = outcome.error;
+            if (outcome.updatedInput)
+                updatedInput = outcome.updatedInput;
+            if (outcome.block && !block)
+                block = outcome;
+        }
+    }
+    if (block) {
+        return {
+            outcome: { block: true, reason: block.reason, context: contexts.join("\n\n") || undefined },
+            ran,
+        };
+    }
+    return {
+        outcome: { block: false, context: contexts.join("\n\n") || undefined, error, updatedInput },
+        ran,
+    };
+}