@sema-agent/server 7.146.0 → 7.148.0

package/dist/hooks/hook-runner.js

@@ -1,26 +1,28 @@
 import { spawn } from "node:child_process";
 import { composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import vm from "node:vm";
-import { hostShell, resolveHostShell, adoptHostForegroundChild, killTreeSoft, killTreeHard } from "../plugins/host-platform.js";
+import { hostShell, resolveHostShell, adoptHostForegroundChild, killTreeSoft, killTreeHard, signalProcessTree, reapedLeaderGroupAlive } from "../plugins/host-platform.js";
 import { classifyHooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_ENTRY_TYPES, HOOK_EVENTS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, hookMatcherForm, hookMatcherSelects, interpolateHookEnvVars, } from "@sema-agent/settings-schema/hooks";
-import { findUrlCredential, formatConfigPath, outgoingPath } from "@sema-agent/settings-schema";
+import { findUrlCredential, outgoingPath } from "@sema-agent/settings-schema";
 import { httpHookEnvVarsAllowed, httpHookUrlVerdict } from "@sema-agent/settings-schema";
 import { ENGINE_OWNED_HOOK_EVENTS } from "@sema-agent/settings-schema/hooks";
 import { describeToolCatalog } from "@sema-agent/core";
-import { hangClassic, wrapClassic } from "./classic-stations.js";
+import { hangClassic } from "./classic-stations.js";
 import { MAX_HOOK_NOTICE_TEXT_CHARS, boundedNoticeText } from "../fleet/fleet-bus.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { LIMIT_REASONS } from "../limit-refusal.js";
+import { LIMIT_REASONS, limitFacts } from "../limit-refusal.js";
+import { fieldCoordinate } from "../http/refusal-body.js";
 import { clipDataText, echoCallerText } from "../caller-text-echo.js";
 import { seatText } from "../trace/exit-seat.js";
 import { redactSecrets, buildDisplaySafeUrl } from "../trace/redact.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ccPromptSystemFor, wrapCondition, parseCcVerdict, CC_EVALUATOR_MAX_OUTPUT_TOKENS } from "./cc-stop-prompt.js";
 import { ccAgentHookSystemFor } from "./cc-agent-hook-prompt.js";
+import { createEgressFetch } from "../egress-redirect.js";
 import { renderBranchTranscript } from "./branch-transcript.js";
 import { buildRequestUrlCredentialRefusal, urlCredentialHeaderExit } from "../url-credential-refusal.js";
 import { HOOK_PHASES, HOOK_SOURCE_VOCABULARY_SENTENCE, hookLaneOf, hookPhaseOf, readHookGroupSource } from "./hook-source.js";
-import { commandLineChars, composeHookEnvLayer, hookPluginChars, planCommandSpawn, readHookArgs, readHookPlugin } from "./command-spawn.js";
+import { commandLineChars, composeHookEnvLayer, hookPluginChars, planCommandSpawn, readHookPlugin } from "./command-spawn.js";
 export const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export const MAX_HOOK_COMMAND_CHARS = 8_192;
 export const MAX_HOOK_TIMEOUT_SECONDS = 600;
@@ -42,31 +44,26 @@ function hookEnv(ctx) {
     return hookChildEnv(composeHookEnvLayer(ctx.shellEnv, ctx.cwd, undefined), false);
 }
 export const SETTINGS_HOOK_STATIONS = {
-    PreToolUse: ["classic.PreToolUse"],
-    PostToolUse: ["classic.PostToolUse"],
-    PostToolUseFailure: ["classic.PostToolUseFailure"],
-    PostToolBatch: ["classic.PostToolBatch"],
-    UserPromptSubmit: ["classic.UserPromptSubmit"],
-    Stop: ["classic.Stop", "classic.SubagentStop"],
-    StopFailure: ["classic.StopFailure"],
-    PreCompact: ["classic.PreCompact"],
-    PostCompact: ["classic.PostCompact"],
+    PreToolUse: "classic.PreToolUse",
+    PostToolUse: "classic.PostToolUse",
+    PostToolUseFailure: "classic.PostToolUseFailure",
+    PostToolBatch: "classic.PostToolBatch",
+    UserPromptSubmit: "classic.UserPromptSubmit",
+    Stop: "classic.Stop",
+    StopFailure: "classic.StopFailure",
+    PreCompact: "classic.PreCompact",
+    PostCompact: "classic.PostCompact",
 };
 function chainsBelowTaskOn(patterns, station) {
     return patterns.some((p) => p === station || (p.endsWith(".*") && station.startsWith(p.slice(0, -1))));
 }
-function managedTightenOnlyOn(lane, station, belowTaskChainPatterns) {
-    return lane === "managed" && chainsBelowTaskOn(belowTaskChainPatterns, station);
-}
-const MANAGED_REWRITE_UNSHOWN_REASON = "a managed PreToolUse hook rewrote this call's input, but this deployment runs its own handler for this call after the request's hooks and that handler never sees a rewrite made above it, so the rewrite cannot be honored and the call was not executed";
-const MANAGED_ALLOW_UNJUDGED_REASON = "a managed PreToolUse hook allowed this call, but this deployment runs its own handler for this call after the request's hooks, and a request hook's allow does not stand in for that handler's judgment, so the call was not executed (the same outcome as the same hook without a managed source)";
-function hangTranslator(on, event, translators, lane) {
+const REQUEST_HOOK_REWRITE_UNSHOWN_REASON = "a request PreToolUse hook rewrote this call's input, but this deployment runs its own handler for this call after the request's hooks and that handler never sees a rewrite made above it, so the rewrite cannot be honored and the call was not executed";
+const REQUEST_HOOK_ALLOW_UNJUDGED_REASON = "a request PreToolUse hook allowed this call, but this deployment runs its own handler for this call after the request's hooks, and a request hook's allow does not stand in for that handler's judgment, so the call was not executed";
+function hangTranslator(on, event, translators) {
     const translate = translators[event];
     if (translate === undefined)
         return;
-    const hang = lane === "managed" ? wrapClassic : hangClassic;
-    for (const station of SETTINGS_HOOK_STATIONS[event])
-        hang(on, station, translate);
+    hangClassic(on, SETTINGS_HOOK_STATIONS[event], translate);
 }
 export const SETTINGS_HOOKS_REGISTRATIONS = {
     managed: "settings.hooks.managed",
@@ -235,7 +232,6 @@ const HOOKS_WIRE_KEY_SHAPE = {
     source: `source must be one of ${HOOK_SOURCE_VOCABULARY_SENTENCE}`,
     plugin: "plugin must be { name, root, dataDir?, options? } — name a non-empty string, root and dataDir absolute paths with no \"..\" segment and no NUL byte, " +
         "options an object of string values whose keys are identifiers ([A-Za-z_][A-Za-z0-9_]*); nothing else",
-    args: "args must be an array of strings without NUL bytes (exec form: command is the executable, args its arguments)",
 };
 function hooksCapIssue(limit, event, path, count) {
     const c = HOOKS_CAPS[limit];
@@ -243,54 +239,61 @@ function hooksCapIssue(limit, event, path, count) {
 }
 const matcherPath = (event, groupIndex) => ["hooks", event, groupIndex, "matcher"];
 export function buildHooksRefusal(issue) {
-    const field = "settings.hooks";
     switch (issue.reason) {
-        case "dead_alias":
+        case "dead_alias": {
+            const field = hooksFieldCoordinate(matcherPath(issue.event, issue.groupIndex));
             return {
                 message: `settings.hooks.${issue.event}: matcher "${issue.alias}" is an alias; tool-event matchers match the tool's wire name (PostToolUse / PostToolUseFailure since 7.107.0) — use "${issue.canonical}"`,
-                field,
-                detail: { reason: issue.reason, event: issue.event, alias: issue.alias, canonical: issue.canonical, path: matcherPath(issue.event, issue.groupIndex) },
+                facts: { field, reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, alias: issue.alias, canonical: issue.canonical },
             };
-        case "over_budget":
+        }
+        case "over_budget": {
+            const field = hooksFieldCoordinate(matcherPath(issue.event, issue.groupIndex));
             return {
-                message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: evaluating the pattern did not finish within ${issue.budgetMs} ms (catastrophic regex backtracking) — rewrite it as a tool-name list or a pattern without nested repetition`,
-                field,
-                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, budgetMs: issue.budgetMs, path: matcherPath(issue.event, issue.groupIndex) },
+                message: `${field}: evaluating the pattern did not finish within ${issue.budgetMs} ms (catastrophic regex backtracking) — rewrite it as a tool-name list or a pattern without nested repetition`,
+                facts: { field, reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, budgetMs: issue.budgetMs },
             };
-        case "budget_exceeded":
+        }
+        case "budget_exceeded": {
+            const field = hooksFieldCoordinate(matcherPath(issue.event, issue.groupIndex));
             return {
-                message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: evaluating this configuration's regular-expression matchers took longer than ${issue.totalMs} ms in total (very slow patterns) — write tool names as a list such as "Read|Edit", or simplify the patterns`,
-                field,
-                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, totalMs: issue.totalMs, path: matcherPath(issue.event, issue.groupIndex) },
+                message: `${field}: evaluating this configuration's regular-expression matchers took longer than ${issue.totalMs} ms in total (very slow patterns) — write tool names as a list such as "Read|Edit", or simplify the patterns`,
+                facts: { field, reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, totalMs: issue.totalMs },
             };
-        case "invalid_regex":
+        }
+        case "invalid_regex": {
+            const field = hooksFieldCoordinate(matcherPath(issue.event, issue.groupIndex));
             return {
-                message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: ${JSON.stringify(issue.matcher)} is not a valid regular expression (${issue.compileError}) — fix the pattern, or write the tool names as a list such as "Read|Edit"`,
-                field,
-                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, path: matcherPath(issue.event, issue.groupIndex) },
+                message: `${field}: ${JSON.stringify(issue.matcher)} is not a valid regular expression (${issue.compileError}) — fix the pattern, or write the tool names as a list such as "Read|Edit"`,
+                facts: { field, reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex },
             };
-        case "unsupported_entry_type":
+        }
+        case "unsupported_entry_type": {
+            const field = hooksFieldCoordinate(issue.path);
             return {
-                message: `${hooksCoordinate(issue.path)}: this server does not run hook entries of type ${issue.type}; supported: ${SUPPORTED_HOOK_ENTRY_TYPES.join(" / ")}`,
-                field,
-                detail: { reason: issue.reason, path: hooksOutgoingPath(issue.path), type: issue.type },
+                message: `${field}: this server does not run hook entries of type ${issue.type}; supported: ${SUPPORTED_HOOK_ENTRY_TYPES.join(" / ")}`,
+                facts: { field, reason: issue.reason, type: issue.type },
             };
+        }
         case "over_cap":
         case "too_long": {
             const cap = issue;
-            return { message: HOOKS_CAPS[cap.limit].sentence(cap.event, cap.count), field, detail: { reason: cap.reason, path: hooksOutgoingPath(cap.path), count: cap.count, cap: cap.cap } };
+            return { message: HOOKS_CAPS[cap.limit].sentence(cap.event, cap.count), facts: { ...limitFacts(hooksFieldCoordinate(cap.path), HOOKS_CAPS[cap.limit].measure, cap.count, cap.cap), reason: cap.reason } };
+        }
+        case "unnamed_refusal": {
+            const field = hooksFieldCoordinate(issue.path);
+            return { message: `${field}: the hooks reader refused this configuration without naming a piece`, facts: { field, reason: issue.reason } };
+        }
+        case "wire_key_invalid": {
+            const field = hooksFieldCoordinate(issue.path);
+            return { message: `${field}: ${HOOKS_WIRE_KEY_SHAPE[issue.key]}`, facts: { field, reason: issue.reason, key: issue.key } };
         }
-        case "unnamed_refusal":
-            return { message: `${hooksCoordinate(issue.path)}: the hooks reader refused this configuration without naming a piece`, field, detail: { reason: issue.reason, path: hooksOutgoingPath(issue.path) } };
-        case "wire_key_invalid":
-            return { message: `${hooksCoordinate(issue.path)}: ${HOOKS_WIRE_KEY_SHAPE[issue.key]}`, field, detail: { reason: issue.reason, path: hooksOutgoingPath(issue.path), key: issue.key } };
         default: {
             const piece = issue;
             const key = piece.key !== undefined ? hooksOutgoingKey(piece.key) : undefined;
             return {
                 message: hooksPieceRefusal(piece),
-                field,
-                detail: { reason: piece.reason, path: hooksOutgoingPath(piece.path), ...(key !== undefined ? { key } : {}) },
+                facts: { field: hooksFieldCoordinate(piece.path), reason: piece.reason, ...(key !== undefined ? { key } : {}) },
             };
         }
     }
@@ -353,8 +356,8 @@ export function hooksUrlCredentialIssue(config) {
     return undefined;
 }
 export function buildHooksUrlCredentialRefusal(issue) {
-    const entry = `settings.hooks.${issue.event}[${issue.groupIndex}].hooks[${issue.entryIndex}]`;
-    return buildRequestUrlCredentialRefusal(`${entry}.url`, issue.credential, urlCredentialHeaderExit(`${entry}.headers`));
+    const entry = ["hooks", issue.event, issue.groupIndex, "hooks", issue.entryIndex];
+    return buildRequestUrlCredentialRefusal(hooksFieldCoordinate([...entry, "url"]), issue.credential, urlCredentialHeaderExit(hooksFieldCoordinate([...entry, "headers"])));
 }
 const HOOKS_PIECE_MEANING = {
     "hooks-not-object": "`hooks` must be an object keyed by hook event name",
@@ -372,8 +375,8 @@ const HOOKS_PIECE_MEANING = {
 export function hooksOutgoingPath(path) {
     return outgoingPath(path).map((seg) => (typeof seg === "string" ? echoCallerText(seg) : seg));
 }
-export function hooksCoordinate(path) {
-    return `settings.${formatConfigPath(hooksOutgoingPath(path))}`;
+export function hooksFieldCoordinate(path) {
+    return fieldCoordinate("settings", hooksOutgoingPath(path));
 }
 function hooksOutgoingKey(key) {
     return echoCallerText(String(outgoingPath([key])[0] ?? ""));
@@ -383,7 +386,7 @@ function hooksPieceIssue(piece) {
 }
 function hooksPieceRefusal(piece) {
     const field = piece.key !== undefined ? ` (field: ${hooksOutgoingKey(piece.key)})` : "";
-    return `${hooksCoordinate(piece.path)}: ${piece.reason} — ${HOOKS_PIECE_MEANING[piece.reason]}${field}`;
+    return `${hooksFieldCoordinate(piece.path)}: ${piece.reason} — ${HOOKS_PIECE_MEANING[piece.reason]}${field}`;
 }
 function hooksRefused(issue, pieces) {
     const error = buildHooksRefusal(issue).message;
@@ -432,16 +435,12 @@ export function parseHooksConfig(raw) {
                     return hooksRefused({ reason: "unsupported_entry_type", path: [...at, "type"], type: contractEntry.type });
                 let entry = contractEntry;
                 if (entry.type === "command") {
-                    const rawEntry = rawMember(rawMember(rawGroup, "hooks"), entryIndex);
-                    const rawArgs = rawMember(rawEntry, "args");
-                    const rawPlugin = rawMember(rawEntry, "plugin");
-                    const args = rawArgs === undefined ? undefined : readHookArgs(rawArgs);
-                    if (rawArgs !== undefined && args === undefined)
-                        return hooksRefused({ reason: "wire_key_invalid", path: [...at, "args"], key: "args" });
+                    const rawPlugin = rawMember(rawMember(rawMember(rawGroup, "hooks"), entryIndex), "plugin");
                     const plugin = rawPlugin === undefined ? undefined : readHookPlugin(rawPlugin);
                     if (rawPlugin !== undefined && plugin === undefined)
                         return hooksRefused({ reason: "wire_key_invalid", path: [...at, "plugin"], key: "plugin" });
-                    entry = { ...entry, ...(args !== undefined ? { args } : {}), ...(plugin !== undefined ? { plugin } : {}) };
+                    if (plugin !== undefined)
+                        entry = { ...entry, plugin };
                     const line = commandLineChars(entry);
                     if (line > MAX_HOOK_COMMAND_CHARS)
                         return hooksRefused(hooksCapIssue("command", event, [...at, "command"], line));
@@ -600,7 +599,7 @@ function noteMatcherOverBudget(ctx, args) {
         detail: `${what} \`${expression}\` did not finish within ${budgetMs} ms on \`${value}\`; treated as selected (${count} ${count === 1 ? "entry" : "entries"})`,
     });
 }
-function matcherGroupSelected(ctx, event, group, value, toolName) {
+function matcherGroupSelected(ctx, event, group, value, toolName, entries) {
     const answer = hookMatcherMatches(group.matcher, value);
     switch (answer) {
         case true:
@@ -611,7 +610,7 @@ function matcherGroupSelected(ctx, event, group, value, toolName) {
             ctx.logger.warn("hook_matcher_invalid", { event, matcher: echoCallerText(group.matcher ?? "", { maxChars: MATCHER_ECHO_CHARS }) });
             return "invalid";
         case "over_budget":
-            noteMatcherOverBudget(ctx, { event, scope: "matcher", expression: group.matcher ?? "", value, entries: group.hooks, ...(toolName !== undefined ? { toolName } : {}) });
+            noteMatcherOverBudget(ctx, { event, scope: "matcher", expression: group.matcher ?? "", value, entries, ...(toolName !== undefined ? { toolName } : {}) });
             return "over_budget";
         default: {
             const unreachable = answer;
@@ -654,6 +653,41 @@ export const PERMISSIVE_VERDICT_EVENTS = {
     PreModelSwitch: false,
     PostModelSwitch: false,
 };
+export const ON_FAILURE_BLOCK_EVENTS = {
+    PreToolUse: true,
+    PostToolUse: true,
+    PostToolUseFailure: true,
+    PostToolBatch: true,
+    Notification: true,
+    UserPromptSubmit: true,
+    UserPromptExpansion: true,
+    SessionStart: true,
+    SessionEnd: true,
+    Stop: false,
+    StopFailure: false,
+    SubagentStart: true,
+    SubagentStop: false,
+    PreCompact: true,
+    PostCompact: false,
+    PermissionRequest: true,
+    PermissionDenied: true,
+    Setup: true,
+    TeammateIdle: false,
+    TaskCreated: true,
+    TaskCompleted: false,
+    Elicitation: true,
+    ElicitationResult: true,
+    ConfigChange: true,
+    WorktreeCreate: true,
+    WorktreeRemove: true,
+    InstructionsLoaded: true,
+    CwdChanged: true,
+    FileChanged: true,
+    MessageDisplay: true,
+    DirectoryAdded: true,
+    PreModelSwitch: true,
+    PostModelSwitch: true,
+};
 const DISTRUST_DETAIL = {
     input_truncated: `the hook did not receive the whole payload (tool_input over ${MAX_TOOL_INPUT_CHARS} characters was replaced by a truncation marker, or a prompt / agent entry's payload text was clipped at that size); its allow / updatedInput are not honored`,
     matcher_over_budget: "the matcher (or the if condition's tool-name part) did not finish within its budget; the entry ran as selected, so its allow / updatedInput are not honored",
@@ -703,24 +737,26 @@ const VERDICT_GAP_CAUSE = {
     input_truncated: "verdict_unreadable",
     matcher_over_budget: "verdict_unreadable",
 };
-function createUnrunLedger(ctx, event, toolName) {
+function createUnrunLedger(ctx, event, toolName, once) {
     let managedVerdictGap;
     let haltNoted = false;
     const ledger = {
         halted(source, entry) {
-            if (haltNoted)
+            if (haltNoted || !isSyncEntry(entry))
                 return;
             haltNoted = true;
             ledger.unrun(source, entry, "budget_exhausted", ENGINE_BUDGET_SPENT_DETAIL);
         },
         untrusted(source, entry, reason) {
+            once.unsettled(entry);
             if (hookLaneOf(source) === "unmanaged")
                 return;
             managedVerdictGap ??= VERDICT_GAP_CAUSE[reason];
             noteVerdictUntrusted(ctx, { event, reason, entry, source, toolName });
         },
         unrun(source, entry, reason, detail) {
-            if (source === undefined || hookLaneOf(source) === "unmanaged")
+            once.unsettled(entry);
+            if (source === undefined || hookLaneOf(source) === "unmanaged" || !isSyncEntry(entry))
                 return;
             managedVerdictGap ??= VERDICT_GAP_CAUSE[reason];
             ctx.logger.warn("hook_managed_unrun", { event, reason, source: echoCallerText(source), type: entry.type, ...(toolName !== undefined ? { tool: toolName } : {}) });
@@ -800,6 +836,13 @@ function withBelowContext(parts, below) {
     const tail = belowString(below, "additionalContext");
     return tail === undefined ? [...parts] : [...parts, tail];
 }
+const ALSO_ASKS_SPEAKER = {
+    managed: "a managed PreToolUse hook",
+    unmanaged: "a PreToolUse hook",
+};
+function alsoAsks(lane, below, own) {
+    return below === undefined || below === own ? own : `${below} (${ALSO_ASKS_SPEAKER[lane]} also asks: ${own})`;
+}
 function readBelowPreToolUse(below) {
     const action = belowString(below, "action");
     const message = belowString(below, "message") ?? "a PreToolUse hook requires approval";
@@ -812,7 +855,7 @@ function readBelowPreToolUse(below) {
         allowed: action === "allow",
         ...(action === "ask" && (cause === undefined || cause === "asked") ? { asked: message } : {}),
         ...(action === "ask" && cause !== undefined && cause !== "asked" ? { unreadable: { message, cause: unreadableCause } } : {}),
-        realApproval: action === "ask" && typeof below === "object" && below !== null && Reflect.get(below, "requiresRealApproval") === true,
+        ...(action === "ask" && typeof below === "object" && below !== null && Object.hasOwn(below, "requiresRealApproval") && Reflect.get(below, "requiresRealApproval") === true ? { realApproval: true } : {}),
         ...(rewrite !== null && typeof rewrite === "object" ? { updatedInput: rewrite } : {}),
         ...(additionalContext !== undefined ? { additionalContext } : {}),
     };
@@ -824,7 +867,65 @@ function spawnPlannedCommand(plan, ctx, stdio) {
     const sh = hostShell();
     return spawn(sh.shell, [...sh.args, plan.command], { cwd: ctx.cwd, env, stdio, detached: true });
 }
-async function runCommandHook(entry, payload, ctx, halt) {
+function createHookTreeLadder(child, ctx, event) {
+    const leaderOurs = () => child.pid !== undefined && child.exitCode === null && child.signalCode === null;
+    const alive = () => leaderOurs() || (child.pid !== undefined && reapedLeaderGroupAlive(child.pid));
+    const shoot = (sig) => {
+        const pid = child.pid;
+        if (pid === undefined) {
+            child.kill(sig);
+            return;
+        }
+        if (leaderOurs()) {
+            signalProcessTree(pid, sig);
+            return;
+        }
+        if (!reapedLeaderGroupAlive(pid))
+            return;
+        try {
+            (sig === "SIGTERM" ? killTreeSoft : killTreeHard)(pid);
+        }
+        catch {
+            child.kill(sig);
+        }
+    };
+    let hardFired = false;
+    const hard = (end) => {
+        if (hardFired)
+            return;
+        hardFired = true;
+        shoot("SIGKILL");
+        const recheck = setTimeout(() => {
+            const clean = !alive();
+            if (!clean)
+                shoot("SIGKILL");
+            const fields = { event, type: "command", end, shots: clean ? 1 : 2, clean };
+            if (clean)
+                ctx.logger.info("hook_command_tree_swept", fields);
+            else
+                ctx.logger.warn("hook_command_tree_swept", fields);
+        }, HOOK_KILL_GRACE_MS);
+        recheck.unref();
+    };
+    return {
+        halt(onEscalate) {
+            shoot("SIGTERM");
+            const escalate = setTimeout(() => {
+                if (hardFired || !alive())
+                    return;
+                onEscalate();
+                hard("halt");
+            }, HOOK_KILL_GRACE_MS);
+            escalate.unref();
+        },
+        kill: hard,
+        ended() {
+            if (alive())
+                hard("exit");
+        },
+    };
+}
+async function runCommandHook(entry, payload, ctx, halt, event) {
     const plan = await planCommandSpawn(entry, ctx.cwd, ctx.shellEnv);
     if (plan.kind === "refused")
         return { code: null, stdout: "", stderr: "", timedOut: false, spawnError: plan.error };
@@ -849,6 +950,7 @@ async function runCommandHook(entry, payload, ctx, halt) {
             return;
         }
         const ticket = adoptHostForegroundChild(child);
+        const tree = createHookTreeLadder(child, ctx, event);
         let stdout = "";
         let stderr = "";
         let timedOut = false;
@@ -867,40 +969,16 @@ async function runCommandHook(entry, payload, ctx, halt) {
             timedOut = true;
             if (sent !== undefined)
                 sent = "SIGKILL";
-            try {
-                if (child.pid)
-                    process.kill(-child.pid, "SIGKILL");
-                else
-                    child.kill("SIGKILL");
-            }
-            catch {
-                child.kill("SIGKILL");
-            }
             settle(null);
+            tree.kill("timeout");
         }, timeoutMs);
-        const signalGroup = (sig) => {
-            try {
-                if (child.pid)
-                    (sig === "SIGTERM" ? killTreeSoft : killTreeHard)(child.pid);
-                else
-                    child.kill(sig);
-            }
-            catch {
-                child.kill(sig);
-            }
-        };
         const onHalt = () => {
             if (settled)
                 return;
             sent = "SIGTERM";
-            signalGroup("SIGTERM");
-            const escalate = setTimeout(() => {
-                if (child.exitCode !== null || child.signalCode !== null)
-                    return;
+            tree.halt(() => {
                 sent = "SIGKILL";
-                signalGroup("SIGKILL");
-            }, HOOK_KILL_GRACE_MS);
-            escalate.unref();
+            });
         };
         halt.addEventListener("abort", onHalt, { once: true });
         child.stdout?.on("data", (d) => {
@@ -919,7 +997,12 @@ async function runCommandHook(entry, payload, ctx, halt) {
                 resolve({ code: null, stdout, stderr, timedOut, spawnError: String(e) });
             }
         });
-        child.on("close", (code) => settle(code));
+        child.on("close", (code) => {
+            const natural = !settled && sent === undefined;
+            settle(code);
+            if (natural)
+                tree.ended();
+        });
         child.stdin?.on("error", () => { });
         child.stdin?.end(`${JSON.stringify(boundedToolInputPayload(payload))}\n`);
     });
@@ -937,18 +1020,11 @@ async function fireAsyncCommandHook(entry, payload, ctx, event, halt) {
             return;
         const child = spawnPlannedCommand(plan, ctx, ["pipe", "ignore", rewake ? "pipe" : "ignore"]);
         const ticket = adoptHostForegroundChild(child);
+        const tree = createHookTreeLadder(child, ctx, event);
         let killedByTimeout = false;
         const timer = setTimeout(() => {
             killedByTimeout = true;
-            try {
-                if (child.pid)
-                    process.kill(-child.pid, "SIGKILL");
-                else
-                    child.kill("SIGKILL");
-            }
-            catch {
-                child.kill("SIGKILL");
-            }
+            tree.kill("timeout");
         }, timeoutMs);
         timer.unref?.();
         let stderr = "";
@@ -967,6 +1043,8 @@ async function fireAsyncCommandHook(entry, payload, ctx, event, halt) {
         child.on("close", (code) => {
             clearTimeout(timer);
             ticket?.release();
+            if (!killedByTimeout)
+                tree.ended();
             noteAsyncOutcome(entry, ctx, event, payload, { code, rewake, killedByTimeout });
             if (!rewake || code !== 2)
                 return;
@@ -1086,6 +1164,7 @@ function httpHookWithheldSentence(event, block) {
     return `settings.hooks.${event}: http hook not sent — ${why} (rule: ${block.rule}); ${exit}`;
 }
 const MAX_BLANKED_REFERENCES_LOGGED = 16;
+const httpHookFetch = createEgressFetch("declare the final address as this hook entry's url");
 async function runHttpHook(entry, payload, ctx, event) {
     const block = httpHookUrlVerdict(entry.url, ctx.httpHookAllowlistLayers, SERVER_WORKSPACE_TRUST);
     if (block !== undefined)
@@ -1113,12 +1192,11 @@ async function runHttpHook(entry, payload, ctx, event) {
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), timeoutMs);
     try {
-        const res = await fetch(entry.url, {
+        const res = await httpHookFetch(entry.url, {
             method: "POST",
             headers,
             body: `${JSON.stringify(boundedToolInputPayload(payload))}\n`,
             signal: ac.signal,
-            redirect: "error",
         });
         let body = "";
         const reader = res.body?.getReader();
@@ -1190,18 +1268,39 @@ function boundedToolInputPayload(payload) {
     return bounded === p.tool_input ? payload : { ...p, tool_input: bounded };
 }
 function readHookStdout(ran, event, ctx, payload, ledger) {
-    const { run, entry } = ran;
-    const out = parseHookStdout(run.stdout);
+    const out = parseHookStdout(ran.run.stdout);
     if (out !== undefined)
         return out;
-    const t = run.stdout.trim();
-    if (t.startsWith("{") || t.startsWith("[")) {
-        ctx.logger.warn("hook_bad_json_output", { event, type: entry.type, preview: seatText("operator-log-text", t) });
-        noteHookFailure(ctx, { event, entry, reason: "bad_json", exitCode: run.code, stderr: run.stderr, toolName: toolNameOf(payload) });
-        ledger.unrun(ran.source, entry, "bad_json");
-    }
+    if (stdoutVerdictUnreadable(ran.run.stdout))
+        noteBadJson(ctx, ledger, event, ran, toolNameOf(payload));
     return undefined;
 }
+function stdoutVerdictUnreadable(stdout) {
+    if (parseHookStdout(stdout) !== undefined)
+        return false;
+    const t = stdout.trim();
+    return t.startsWith("{") || t.startsWith("[");
+}
+function noteBadJson(ctx, ledger, event, ran, toolName) {
+    const { run, entry } = ran;
+    ctx.logger.warn("hook_bad_json_output", { event, type: entry.type, preview: seatText("operator-log-text", run.stdout.trim()) });
+    noteHookFailure(ctx, { event, entry, reason: "bad_json", exitCode: run.code, stderr: run.stderr, toolName });
+    ledger.unrun(ran.source, entry, "bad_json");
+}
+const PERMISSION_DECISION_WORDS = new Set(["allow", "deny", "ask"]);
+function preToolUseDecisionOf(out) {
+    const hso = out?.hookSpecificOutput;
+    return hso !== null && typeof hso === "object" && hso.hookEventName === "PreToolUse" ? hso.permissionDecision : undefined;
+}
+function noteDecisionOutOfSet(ctx, ledger, ran, decision, toolName, effect) {
+    ctx.logger.warn("hook_permission_decision_unknown", {
+        event: "PreToolUse",
+        decision: seatText("operator-log-text", typeof decision === "string" ? decision : typeof decision),
+        tool: toolName,
+        effect,
+    });
+    ledger.unrun(ran.source, ran.entry, "decision_out_of_set");
+}
 function parseHookStdout(stdout) {
     const t = stdout.trim();
     if (!t.startsWith("{"))
@@ -1223,7 +1322,7 @@ function runRunnableEntry(entry, payload, ctx, event, llmExtra, halt) {
         case "agent":
             return runLlmHook(entry, payload, ctx, { system: ccAgentHookSystemFor(event), event });
         case "command":
-            return runCommandHook(entry, payload, ctx, halt);
+            return runCommandHook(entry, payload, ctx, halt, event);
         default: {
             const unreachable = entry;
             void unreachable;
@@ -1231,19 +1330,110 @@ function runRunnableEntry(entry, payload, ctx, event, llmExtra, halt) {
         }
     }
 }
+async function settleOnce(spentOf, body) {
+    const candidates = new Set();
+    let refused = false;
+    const once = {
+        spent: (entry) => spentOf.has(entry),
+        ran: (entry) => {
+            if (entry.once)
+                candidates.add(entry);
+        },
+        handedOff: (entry) => {
+            if (entry.once)
+                spentOf.add(entry);
+        },
+        unsettled: (entry) => {
+            candidates.delete(entry);
+        },
+        refused: (answer) => {
+            refused = true;
+            return answer;
+        },
+        mark: () => {
+            const at = new Set(candidates);
+            return () => {
+                candidates.clear();
+                for (const entry of at)
+                    candidates.add(entry);
+            };
+        },
+    };
+    const answer = await body(once);
+    if (!refused)
+        for (const entry of candidates)
+            spentOf.add(entry);
+    return answer;
+}
 function isSyncEntry(entry) {
     return !(entry.type === "command" && (entry.async === true || entry.asyncRewake === true));
 }
-async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceFired, halt, deadlineAt, ledger, llmExtra) {
+function blocksOnFailure(entry, event) {
+    if (!ON_FAILURE_BLOCK_EVENTS[event] || !isSyncEntry(entry))
+        return false;
+    if (entry.type !== "command" && entry.type !== "http")
+        return false;
+    const word = entry.onFailure;
+    switch (word) {
+        case "block":
+            return true;
+        case "continue":
+        case undefined:
+            return false;
+        default: {
+            const unreachable = word;
+            void unreachable;
+            return true;
+        }
+    }
+}
+function blockingFailureRun(event, cause) {
+    return { code: 2, stdout: "", stderr: `${event} hook did not reach a verdict (${cause}); blocking because onFailure is "block"`, timedOut: false };
+}
+function ranVerdictFlaw(event, run) {
+    if (run.code === 2)
+        return undefined;
+    if (run.code !== 0)
+        return { reason: "exit_nonzero" };
+    if (stdoutVerdictUnreadable(run.stdout))
+        return { reason: "bad_json" };
+    if (event !== "PreToolUse")
+        return undefined;
+    const out = parseHookStdout(run.stdout);
+    if (out?.continue === false || out?.decision === "block")
+        return undefined;
+    const decision = preToolUseDecisionOf(out);
+    return decision !== undefined && !PERMISSION_DECISION_WORDS.has(decision) ? { reason: "decision_out_of_set", decision } : undefined;
+}
+function noteRanVerdictFlaw(ctx, ledger, event, ran, flaw, toolName) {
+    switch (flaw.reason) {
+        case "exit_nonzero":
+            noteExitNonzero(ctx, ledger, event, ran, toolName);
+            return;
+        case "bad_json":
+            noteBadJson(ctx, ledger, event, ran, toolName);
+            return;
+        case "decision_out_of_set":
+            noteDecisionOutOfSet(ctx, ledger, ran, flaw.decision, toolName, 'hook ruling not honored (closed word set is allow|deny|ask); the entry\'s onFailure is "block", so this call is denied');
+            return;
+        default: {
+            const unreachable = flaw;
+            void unreachable;
+        }
+    }
+}
+async function runMatchingEntries(event, groups, matchValue, payload, ctx, once, halt, deadlineAt, ledger, llmExtra) {
     const results = [];
     let llmEntries = 0;
     const toolName = toolNameOf(payload);
     const inputTruncated = boundedToolInputPayload(payload) !== payload;
     const truncatedFor = (entry) => (entry.type === "prompt" || entry.type === "agent" ? llmHookArguments(payload).truncated : inputTruncated);
-    const settle = async (entry, onceKey) => {
+    const blockedBy = (entry, source, cause) => ({ entry, run: blockingFailureRun(event, cause), source });
+    let laneSpent = false;
+    const settle = async (entry) => {
         if (halt.signal.aborted)
             return { kind: "halted" };
-        if (entry.once && onceFired.has(onceKey))
+        if (entry.once && once.spent(entry))
             return { kind: "passed" };
         let ifOverBudget = false;
         if (entry.if !== undefined) {
@@ -1269,7 +1459,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
         }
         if (entry.type === "command" && entry.shell === "powershell") {
             ctx.logger.warn("hook_entries_skipped", { event, type: entry.type, reason: "powershell_not_supported" });
-            return isSyncEntry(entry) ? { kind: "unrun", reason: "powershell_unsupported" } : { kind: "passed" };
+            return { kind: "unrun", reason: "powershell_unsupported" };
         }
         if (entry.type === "prompt" || entry.type === "agent") {
             const carrier = entry.type === "prompt" ? ctx.hookLlm : ctx.hookAgent;
@@ -1283,17 +1473,15 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             }
         }
         if (entry.type === "command" && (entry.async || entry.asyncRewake)) {
-            if (entry.once)
-                onceFired.add(onceKey);
+            once.handedOff(entry);
             void fireAsyncCommandHook(entry, payload, ctx, event, halt.signal);
             return { kind: "passed" };
         }
-        if (Date.now() > deadlineAt) {
-            ctx.logger.warn("hook_event_deadline_exceeded", { event, budgetSec: MAX_HOOK_EVENT_TOTAL_SECONDS });
+        if (laneSpent || Date.now() > deadlineAt) {
+            if (!laneSpent)
+                ctx.logger.warn("hook_event_deadline_exceeded", { event, budgetSec: MAX_HOOK_EVENT_TOTAL_SECONDS });
             return { kind: "unrun", reason: "budget_exhausted" };
         }
-        if (entry.once)
-            onceFired.add(onceKey);
         if (entry.type === "prompt" || entry.type === "agent")
             llmEntries++;
         const run = await runRunnableEntry(entry, payload, ctx, event, llmExtra, halt.signal);
@@ -1326,20 +1514,35 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             return { kind: "unrun", reason: "bad_json" };
         return ifOverBudget ? { kind: "ran", run, overBudget: true } : { kind: "ran", run };
     };
-    for (const { group, index } of groups) {
-        const selected = matcherGroupSelected(ctx, event, group, matchValue, toolName);
+    for (const group of groups) {
+        const pending = laneSpent ? group.hooks.filter((entry) => blocksOnFailure(entry, event)) : group.hooks;
+        if (laneSpent && pending.length === 0)
+            continue;
+        const selected = matcherGroupSelected(ctx, event, group, matchValue, toolName, pending);
         if (selected === "invalid") {
-            for (const entry of group.hooks)
-                if (isSyncEntry(entry))
+            for (const entry of pending) {
+                if (!laneSpent)
                     ledger.unrun(group.source, entry, "matcher_invalid");
+                if (blocksOnFailure(entry, event))
+                    results.push(blockedBy(entry, group.source, "matcher_invalid"));
+            }
             continue;
         }
         if (selected === false)
             continue;
-        for (const [ei, entry] of group.hooks.entries()) {
-            const fate = await settle(entry, `${event}:${index}:${ei}`);
+        for (const entry of group.hooks) {
+            if (laneSpent && !blocksOnFailure(entry, event))
+                continue;
+            const fate = await settle(entry);
             switch (fate.kind) {
                 case "ran": {
+                    once.ran(entry);
+                    const flaw = blocksOnFailure(entry, event) ? ranVerdictFlaw(event, fate.run) : undefined;
+                    if (flaw !== undefined) {
+                        noteRanVerdictFlaw(ctx, ledger, event, { entry, run: fate.run, source: group.source }, flaw, toolName);
+                        results.push(blockedBy(entry, group.source, flaw.reason));
+                        break;
+                    }
                     const distrust = !PERMISSIVE_VERDICT_EVENTS[event]
                         ? undefined
                         : truncatedFor(entry)
@@ -1353,14 +1556,17 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                     break;
                 }
                 case "unrun":
-                    ledger.unrun(group.source, entry, fate.reason);
+                    if (!laneSpent)
+                        ledger.unrun(group.source, entry, fate.reason);
+                    if (blocksOnFailure(entry, event))
+                        results.push(blockedBy(entry, group.source, fate.reason));
                     if (fate.reason === "budget_exhausted")
-                        return results;
+                        laneSpent = true;
                     break;
                 case "passed":
                     break;
                 case "halted":
-                    if (isSyncEntry(entry) && halt.budgetSpent())
+                    if (halt.budgetSpent())
                         ledger.halted(group.source, entry);
                     return results;
                 default: {
@@ -1378,17 +1584,16 @@ function createEventClock() {
 }
 const ENGINE_BUDGET_SPENT_DETAIL = "the managed lane's handler ran past its engine budget (HOOKS_TIMEOUT_MS); the managed entries after this one did not run on this event";
 function hookPhasesOf(groups) {
-    const indexed = groups.map((group, index) => ({ group, index, phase: hookPhaseOf(group.source) }));
-    return HOOK_PHASES.map((phase) => ({ phase, groups: indexed.filter((g) => g.phase === phase).map(({ group, index }) => ({ group, index })) })).filter((l) => l.groups.length > 0);
+    return HOOK_PHASES.map((phase) => ({ phase, groups: groups.filter((g) => hookPhaseOf(g.source) === phase) })).filter((l) => l.groups.length > 0);
 }
 function trustRank(phase) {
     return HOOK_PHASES.length - 1 - HOOK_PHASES.indexOf(phase);
 }
-async function runEventLanes(event, groups, matchValue, payload, ctx, onceFired, halt, ledger, llmExtra) {
+async function runEventLanes(event, groups, matchValue, payload, ctx, once, halt, ledger, llmExtra) {
     const deadline = createEventClock();
     const ran = [];
     for (const lane of hookPhasesOf(groups)) {
-        for (const r of await runMatchingEntries(event, lane.groups, matchValue, payload, ctx, onceFired, halt, deadline(), ledger, llmExtra))
+        for (const r of await runMatchingEntries(event, lane.groups, matchValue, payload, ctx, once, halt, deadline(), ledger, llmExtra))
             ran.push({ ...r, phase: lane.phase });
     }
     return ran.sort((a, b) => trustRank(a.phase) - trustRank(b.phase)).map(({ entry, run, source }) => ({ entry, run, source }));
@@ -1404,9 +1609,9 @@ function basePayload(ctx, permissionMode) {
 function ignoreMatchers(groups) {
     return groups.map((g) => (g.matcher === undefined ? g : { ...g, matcher: undefined }));
 }
-async function runObserveOnlyEvent(event, groups, matchValue, payload, ctx, onceFired, halt) {
-    const ledger = createUnrunLedger(ctx, event, toolNameOf(payload));
-    const singles = await runEventLanes(event, groups, matchValue, payload, ctx, onceFired, halt, ledger);
+async function runObserveOnlyEvent(event, groups, matchValue, payload, ctx, once, halt) {
+    const ledger = createUnrunLedger(ctx, event, toolNameOf(payload), once);
+    const singles = await runEventLanes(event, groups, matchValue, payload, ctx, once, halt, ledger);
     for (const ran of singles) {
         const { run } = ran;
         if (run.code !== 0) {
@@ -1459,17 +1664,16 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
     if (!pre && !post && !postFailure && !postBatch && !promptSubmit && !stopEntries && !stopFailureEntries && !preCompactEntries && !postCompactEntries) {
         return undefined;
     }
-    const onceFired = new Set();
+    const onceSpent = new Set();
     const translators = {};
     if (pre) {
-        const tightenOnly = managedTightenOnlyOn(lane, "classic.PreToolUse", ctx.belowTaskChainPatterns);
-        translators.PreToolUse = async (e, halt, below) => {
+        const tightenOnly = chainsBelowTaskOn(ctx.belowTaskChainPatterns, "classic.PreToolUse");
+        translators.PreToolUse = (e, halt, below) => settleOnce(onceSpent, async (once) => {
             const prior = readBelowPreToolUse(below);
-            const realApproval = prior.realApproval ? { requiresRealApproval: true } : {};
             if (prior.denied)
                 return undefined;
             const toolName = e.tool;
-            const ledger = createUnrunLedger(ctx, "PreToolUse", toolName);
+            const ledger = createUnrunLedger(ctx, "PreToolUse", toolName, once);
             const deadline = createEventClock();
             let currentInput = prior.updatedInput ?? e.input;
             let rewritten = prior.updatedInput !== undefined;
@@ -1479,9 +1683,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             let unknownDecision = false;
             const contexts = { unmanaged: [], managedPlugin: [], managedPolicy: [] };
             const contextField = () => buildHookContextField([...[...HOOK_PHASES].sort((a, b) => trustRank(a) - trustRank(b)).flatMap((p) => contexts[p]), ...(prior.additionalContext !== undefined ? [prior.additionalContext] : [])]);
-            const runPass = async (phase, groups, once) => {
+            const strictness = prior.realApproval === true ? { requiresRealApproval: true } : {};
+            const runPass = async (phase, groups) => {
                 let rewroteBy;
-                for (const laneGroup of groups) {
+                for (const group of groups) {
                     const groupInput = currentInput;
                     const payload = {
                         ...basePayload(ctx, e.permissionMode),
@@ -1490,7 +1695,7 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                         tool_input: groupInput,
                         tool_use_id: e.tool_use_id,
                     };
-                    const singles = await runMatchingEntries("PreToolUse", [laneGroup], toolName, payload, ctx, once, halt, deadline(), ledger);
+                    const singles = await runMatchingEntries("PreToolUse", [group], toolName, payload, ctx, once, halt, deadline(), ledger);
                     for (const ran of singles) {
                         const { entry, run } = ran;
                         if (run.code === 2) {
@@ -1521,7 +1726,7 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                                 contexts[phase].push(clipDataText(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                                 spoke = true;
                             }
-                            const decision = h.permissionDecision;
+                            const decision = preToolUseDecisionOf(out);
                             if (decision === "deny") {
                                 const reason = clipDataText(typeof h.permissionDecisionReason === "string" ? h.permissionDecisionReason : "denied by a PreToolUse hook", MAX_HOOK_FEEDBACK_CHARS);
                                 return { deny: { action: "deny", message: reason, ...contextField() } };
@@ -1529,10 +1734,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                             const proposed = h.updatedInput !== null && typeof h.updatedInput === "object" ? h.updatedInput : undefined;
                             const proposesRewrite = proposed !== undefined && canonicalJsonStringify(proposed) !== canonicalJsonStringify(groupInput);
                             if (tightenOnly && ran.distrust === undefined && (decision === "allow" || (proposesRewrite && (decision === "ask" || decision === undefined)))) {
-                                return { deny: { action: "deny", message: proposesRewrite ? MANAGED_REWRITE_UNSHOWN_REASON : MANAGED_ALLOW_UNJUDGED_REASON, ...contextField() } };
+                                return { deny: { action: "deny", message: proposesRewrite ? REQUEST_HOOK_REWRITE_UNSHOWN_REASON : REQUEST_HOOK_ALLOW_UNJUDGED_REASON, ...contextField() } };
                             }
                             if (decision === "ask") {
-                                asked = clipDataText(typeof h.permissionDecisionReason === "string" ? h.permissionDecisionReason : "a PreToolUse hook requires approval", MAX_HOOK_FEEDBACK_CHARS);
+                                asked = alsoAsks(lane, prior.asked ?? prior.unreadable?.message, clipDataText(typeof h.permissionDecisionReason === "string" ? h.permissionDecisionReason : "a PreToolUse hook requires approval", MAX_HOOK_FEEDBACK_CHARS));
                                 spoke = true;
                             }
                             if (decision === "allow" || decision === undefined) {
@@ -1552,16 +1757,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                                     spoke = true;
                                 }
                             }
-                            else if (decision !== "deny" && decision !== "ask") {
+                            else if (!PERMISSION_DECISION_WORDS.has(decision)) {
                                 unknownDecision = true;
                                 spoke = true;
-                                ctx.logger.warn("hook_permission_decision_unknown", {
-                                    event: "PreToolUse",
-                                    decision: seatText("operator-log-text", typeof decision === "string" ? decision : typeof decision),
-                                    tool: toolName,
-                                    effect: "hook ruling not honored (closed word set is allow|deny|ask); this call falls back to the engine gate",
-                                });
-                                ledger.unrun(ran.source, entry, "decision_out_of_set");
+                                noteDecisionOutOfSet(ctx, ledger, ran, decision, toolName, "hook ruling not honored (closed word set is allow|deny|ask); this call falls back to the engine gate");
                             }
                         }
                     }
@@ -1570,54 +1769,52 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             };
             for (const lane of hookPhasesOf(pre)) {
                 if (lane.phase === "unmanaged") {
-                    const pass = await runPass(lane.phase, lane.groups, onceFired);
+                    const pass = await runPass(lane.phase, lane.groups);
                     if (pass.deny !== undefined)
-                        return pass.deny;
+                        return once.refused(pass.deny);
                     continue;
                 }
-                const onceBefore = new Set(onceFired);
-                const first = await runPass(lane.phase, lane.groups, onceFired);
+                const rollback = once.mark();
+                const first = await runPass(lane.phase, lane.groups);
                 if (first.deny !== undefined)
-                    return first.deny;
+                    return once.refused(first.deny);
                 if (first.rewroteBy === undefined)
                     continue;
                 contexts[lane.phase].length = 0;
-                const rejudgeOnce = new Set(onceBefore);
-                const second = await runPass(lane.phase, lane.groups, rejudgeOnce);
-                for (const key of rejudgeOnce)
-                    onceFired.add(key);
+                rollback();
+                const second = await runPass(lane.phase, lane.groups);
                 if (second.deny !== undefined)
-                    return second.deny;
+                    return once.refused(second.deny);
                 if (second.rewroteBy !== undefined) {
                     ledger.unrun(second.rewroteBy.source, second.rewroteBy.entry, "rewrite_unsettled", "the managed hooks of this phase rewrote the tool input again after being re-run on their own rewrite; approval required");
                 }
             }
             const managedGap = ledger.managedVerdictGap;
-            if (below !== undefined && !spoke && managedGap === undefined)
+            if (!spoke && managedGap === undefined)
                 return undefined;
             if (asked !== undefined) {
-                return { action: "ask", message: asked, questionCause: "asked", ...(rewritten ? { updatedInput: currentInput } : {}), ...realApproval, ...contextField() };
+                return { action: "ask", message: asked, questionCause: "asked", ...strictness, ...(rewritten ? { updatedInput: currentInput } : {}), ...contextField() };
             }
             if (managedGap !== undefined) {
                 return {
                     action: "ask",
                     message: "a managed PreToolUse hook did not run to a verdict — approval required",
                     questionCause: managedGap,
+                    ...strictness,
                     ...(rewritten ? { updatedInput: currentInput } : {}),
-                    ...realApproval,
                     ...contextField(),
                 };
             }
             if (prior.unreadable !== undefined) {
-                return { action: "ask", message: prior.unreadable.message, questionCause: prior.unreadable.cause, ...(rewritten ? { updatedInput: currentInput } : {}), ...realApproval, ...contextField() };
+                return { action: "ask", message: prior.unreadable.message, questionCause: prior.unreadable.cause, ...strictness, ...(rewritten ? { updatedInput: currentInput } : {}), ...contextField() };
             }
             if (unknownDecision) {
                 return {
                     action: "ask",
                     message: "a PreToolUse hook returned an unrecognized permissionDecision — approval required",
                     questionCause: "verdict_unreadable",
+                    ...strictness,
                     ...(rewritten ? { updatedInput: currentInput } : {}),
-                    ...realApproval,
                     ...contextField(),
                 };
             }
@@ -1627,10 +1824,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             if (rewritten || HOOK_PHASES.some((p) => contexts[p].length > 0) || prior.additionalContext !== undefined)
                 return carried;
             return undefined;
-        };
+        });
     }
     if (post) {
-        translators.PostToolUse = async (e, halt, below) => {
+        translators.PostToolUse = (e, halt, below) => settleOnce(onceSpent, async (once) => {
             const toolName = e.tool;
             const input = e.input;
             const output = e.output;
@@ -1646,8 +1843,8 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                 tool_response: { isError: output.isError, text: clipDataText(responseText, MAX_TOOL_RESPONSE_CHARS) },
                 tool_use_id: e.tool_use_id,
             };
-            const ledger = createUnrunLedger(ctx, "PostToolUse", toolName);
-            const singles = await runEventLanes("PostToolUse", post, toolName, payload, ctx, onceFired, halt, ledger);
+            const ledger = createUnrunLedger(ctx, "PostToolUse", toolName, once);
+            const singles = await runEventLanes("PostToolUse", post, toolName, payload, ctx, once, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1683,10 +1880,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             if (contexts.length === 0)
                 return undefined;
             return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
-        };
+        });
     }
     if (postFailure) {
-        translators.PostToolUseFailure = async (e, halt, below) => {
+        translators.PostToolUseFailure = (e, halt, below) => settleOnce(onceSpent, async (once) => {
             const toolName = e.tool;
             const f = e.failure;
             const contexts = [];
@@ -1699,8 +1896,8 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                 error: clipDataText(f.error, MAX_TOOL_RESPONSE_CHARS),
                 is_interrupt: f.isInterrupt,
             };
-            const ledger = createUnrunLedger(ctx, "PostToolUseFailure", toolName);
-            const singles = await runEventLanes("PostToolUseFailure", postFailure, toolName, payload, ctx, onceFired, halt, ledger);
+            const ledger = createUnrunLedger(ctx, "PostToolUseFailure", toolName, once);
+            const singles = await runEventLanes("PostToolUseFailure", postFailure, toolName, payload, ctx, once, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1732,10 +1929,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             if (contexts.length === 0)
                 return undefined;
             return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
-        };
+        });
     }
     if (postBatch) {
-        translators.PostToolBatch = async (e, halt, below) => {
+        translators.PostToolBatch = (e, halt, below) => settleOnce(onceSpent, async (once) => {
             const contexts = [];
             const payload = {
                 ...basePayload(ctx, e.permissionMode),
@@ -1747,8 +1944,8 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                     tool_response: { isError: c.isError, ...(c.response !== undefined ? { text: clipDataText(c.response, MAX_TOOL_RESPONSE_CHARS) } : {}) },
                 })),
             };
-            const ledger = createUnrunLedger(ctx, "PostToolBatch", undefined);
-            const singles = await runEventLanes("PostToolBatch", ignoreMatchers(postBatch), "", payload, ctx, onceFired, halt, ledger);
+            const ledger = createUnrunLedger(ctx, "PostToolBatch", undefined, once);
+            const singles = await runEventLanes("PostToolBatch", ignoreMatchers(postBatch), "", payload, ctx, once, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1776,19 +1973,19 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             if (contexts.length === 0)
                 return undefined;
             return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
-        };
+        });
     }
     if (promptSubmit) {
-        translators.UserPromptSubmit = async (e, halt, below) => {
+        translators.UserPromptSubmit = (e, halt, below) => settleOnce(onceSpent, async (once) => {
             const contexts = [];
             const payload = { ...basePayload(ctx, e.permissionMode), hook_event_name: "UserPromptSubmit", prompt: clipDataText(e.prompt, MAX_TOOL_INPUT_CHARS) };
-            const ledger = createUnrunLedger(ctx, "UserPromptSubmit", undefined);
-            const singles = await runEventLanes("UserPromptSubmit", ignoreMatchers(promptSubmit), "", payload, ctx, onceFired, halt, ledger);
+            const ledger = createUnrunLedger(ctx, "UserPromptSubmit", undefined, once);
+            const singles = await runEventLanes("UserPromptSubmit", ignoreMatchers(promptSubmit), "", payload, ctx, once, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
                     const reason = clipDataText(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a UserPromptSubmit hook";
-                    return { block: reason, ...buildHookContextField(contexts) };
+                    return once.refused({ block: reason, ...buildHookContextField(contexts) });
                 }
                 if (run.code !== 0) {
                     noteExitNonzero(ctx, ledger, "UserPromptSubmit", ran);
@@ -1801,11 +1998,11 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                     logHookSystemMessage(ctx, "UserPromptSubmit", out.systemMessage);
                 if (out.continue === false) {
                     const reason = clipDataText(typeof out.stopReason === "string" ? out.stopReason : "hook requested stop", MAX_HOOK_FEEDBACK_CHARS);
-                    return { block: reason, ...buildHookContextField(contexts) };
+                    return once.refused({ block: reason, ...buildHookContextField(contexts) });
                 }
                 if (out.decision === "block") {
                     const reason = clipDataText(typeof out.reason === "string" ? out.reason : "blocked by a UserPromptSubmit hook", MAX_HOOK_FEEDBACK_CHARS);
-                    return { block: reason, ...buildHookContextField(contexts) };
+                    return once.refused({ block: reason, ...buildHookContextField(contexts) });
                 }
                 const hso = out.hookSpecificOutput;
                 if (hso !== null && typeof hso === "object" && hso.hookEventName === "UserPromptSubmit") {
@@ -1817,10 +2014,10 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             if (contexts.length === 0)
                 return undefined;
             return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
-        };
+        });
     }
     if (stopEntries) {
-        translators.Stop = async (sctx, halt, below) => {
+        translators.Stop = (sctx, halt, below) => settleOnce(onceSpent, async (once) => {
             const payload = { ...basePayload(ctx, sctx.permissionMode), hook_event_name: "Stop", stop_hook_active: sctx.stopHookActive };
             let llmExtra;
             const wantsPrompt = stopEntries.some((g) => g.hooks.some((h) => h.type === "prompt"));
@@ -1848,7 +2045,7 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                 }
             }
             const stopGroups = ignoreMatchers(stopEntries);
-            const ledger = createUnrunLedger(ctx, "Stop", undefined);
+            const ledger = createUnrunLedger(ctx, "Stop", undefined, once);
             if (!llmExtra && wantsPrompt) {
                 for (const g of stopGroups)
                     for (const h of g.hooks)
@@ -1858,7 +2055,7 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
             const effectiveGroups = llmExtra || !wantsPrompt
                 ? stopGroups
                 : stopGroups.map((g) => ({ ...g, hooks: g.hooks.filter((h) => h.type !== "prompt") })).filter((g) => g.hooks.length > 0);
-            const singles = await runEventLanes("Stop", effectiveGroups, "", payload, ctx, onceFired, halt, ledger, llmExtra);
+            const singles = await runEventLanes("Stop", effectiveGroups, "", payload, ctx, once, halt, ledger, llmExtra);
             let block;
             let sawContinueFalse = false;
             const contexts = [];
@@ -1912,15 +2109,16 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                 return undefined;
             if (block === undefined && contexts.length === 0)
                 return undefined;
-            return {
+            const answer = {
                 ...belowMembers(below),
                 ...(block !== undefined ? { block } : {}),
                 ...buildHookContextField(withBelowContext(contexts, below)),
             };
-        };
+            return block !== undefined ? once.refused(answer) : answer;
+        });
     }
     if (stopFailureEntries) {
-        translators.StopFailure = async (fctx, halt) => {
+        translators.StopFailure = (fctx, halt) => settleOnce(onceSpent, async (once) => {
             const turnError = toAssistantTurnError(fctx.errorKind);
             const payload = {
                 ...basePayload(ctx, undefined),
@@ -1928,23 +2126,23 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                 error: turnError,
                 ...(fctx.error ? { error_details: clipDataText(redactSecrets(fctx.error), MAX_HOOK_FEEDBACK_CHARS) } : {}),
             };
-            await runObserveOnlyEvent("StopFailure", stopFailureEntries, turnError, payload, ctx, onceFired, halt);
-        };
+            await runObserveOnlyEvent("StopFailure", stopFailureEntries, turnError, payload, ctx, once, halt);
+        });
     }
     if (preCompactEntries) {
-        translators.PreCompact = async (pctx, halt, below) => {
+        translators.PreCompact = (pctx, halt, below) => settleOnce(onceSpent, async (once) => {
             const payload = {
                 ...basePayload(ctx, undefined),
                 hook_event_name: "PreCompact",
                 trigger: pctx.trigger,
                 custom_instructions: pctx.customInstructions ?? null,
             };
-            const ledger = createUnrunLedger(ctx, "PreCompact", undefined);
-            const singles = await runEventLanes("PreCompact", preCompactEntries, pctx.trigger, payload, ctx, onceFired, halt, ledger);
+            const ledger = createUnrunLedger(ctx, "PreCompact", undefined, once);
+            const singles = await runEventLanes("PreCompact", preCompactEntries, pctx.trigger, payload, ctx, once, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
-                    return { ...belowMembers(below), block: clipDataText(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a PreCompact hook" };
+                    return once.refused({ ...belowMembers(below), block: clipDataText(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a PreCompact hook" });
                 }
                 if (run.code !== 0) {
                     noteExitNonzero(ctx, ledger, "PreCompact", ran);
@@ -1959,31 +2157,31 @@ function createLaneRegistration(lane, config, ctx, budgetMs) {
                     ctx.logger.warn("hook_continue_false_unsupported", { event: "PreCompact" });
                 }
                 if (out.decision === "block") {
-                    return { ...belowMembers(below), block: clipDataText(typeof out.reason === "string" ? out.reason : "blocked by a PreCompact hook", MAX_HOOK_FEEDBACK_CHARS) };
+                    return once.refused({ ...belowMembers(below), block: clipDataText(typeof out.reason === "string" ? out.reason : "blocked by a PreCompact hook", MAX_HOOK_FEEDBACK_CHARS) });
                 }
             }
             return undefined;
-        };
+        });
     }
     if (postCompactEntries) {
-        translators.PostCompact = async (cctx, halt) => {
+        translators.PostCompact = (cctx, halt) => settleOnce(onceSpent, async (once) => {
             const payload = {
                 ...basePayload(ctx, undefined),
                 hook_event_name: "PostCompact",
                 trigger: cctx.trigger,
                 compact_summary: clipDataText(cctx.summary, MAX_TOOL_RESPONSE_CHARS),
             };
-            await runObserveOnlyEvent("PostCompact", postCompactEntries, cctx.trigger, payload, ctx, onceFired, halt);
-        };
+            await runObserveOnlyEvent("PostCompact", postCompactEntries, cctx.trigger, payload, ctx, once, halt);
+        });
     }
     const events = Object.keys(translators);
     return {
         name: SETTINGS_HOOKS_REGISTRATIONS[lane],
-        uses: { events: events.flatMap((event) => SETTINGS_HOOK_STATIONS[event]), calls: [] },
+        uses: { events: events.map((event) => SETTINGS_HOOK_STATIONS[event]), calls: [] },
         budgetMs,
         register(on) {
             for (const event of events)
-                hangTranslator(on, event, translators, lane);
+                hangTranslator(on, event, translators);
         },
     };
 }