@sema-agent/server 7.147.0 → 7.149.0

package/dist/hooks/hook-runner.js

@@ -1,22 +1,24 @@
 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";
@@ -34,39 +36,37 @@ const MIN_HOOK_CONTEXT_PARTIAL_CHARS = 256;
 const MAX_TOOL_RESPONSE_CHARS = 32_768;
 const MAX_TOOL_INPUT_CHARS = 262_144;
 const HOOK_ENV_ALLOWLIST = ["PATH", "HOME", "SHELL", "USER", "LOGNAME", "TERM", "TZ", "LANG", "LC_ALL", "LC_CTYPE", "LC_MESSAGES", "TMPDIR"];
-function hookChildEnv(layer, spawning) {
-    const o = { policy: [...HOOK_ENV_ALLOWLIST], allow: [], grants: [layer] };
+function hookChildEnv(layer, putBack, spawning) {
+    const o = { policy: [...HOOK_ENV_ALLOWLIST], allow: putBack, grants: [layer] };
     return spawning ? hostSubprocessEnv({ site: "server.hooks.spawn-env", ...o }) : composeHostSubprocessEnv(o);
 }
+function hookChildView(ctx) {
+    return (layer) => hookChildEnv(layer, ctx.hookEnvAllow, false);
+}
 function hookEnv(ctx) {
-    return hookChildEnv(composeHookEnvLayer(ctx.shellEnv, ctx.cwd, undefined), false);
+    return hookChildView(ctx)(composeHookEnvLayer(ctx.shellEnv, ctx.cwd, undefined));
 }
 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",
@@ -242,54 +242,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 } : {}) },
             };
         }
     }
@@ -352,8 +359,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",
@@ -371,8 +378,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] ?? ""));
@@ -382,7 +389,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;
@@ -733,24 +740,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 } : {}) });
@@ -830,8 +839,12 @@ function withBelowContext(parts, below) {
     const tail = belowString(below, "additionalContext");
     return tail === undefined ? [...parts] : [...parts, tail];
 }
-function alsoAsks(below, own) {
-    return below === undefined || below === own ? own : `${below} (a managed PreToolUse hook also asks: ${own})`;
+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");
@@ -845,20 +858,78 @@ 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 } : {}),
     };
 }
 function spawnPlannedCommand(plan, ctx, stdio) {
-    const env = hookChildEnv(plan.env, true);
+    const env = hookChildEnv(plan.env, ctx.hookEnvAllow, true);
     if (plan.kind === "exec")
         return spawn(plan.file, [...plan.args], { cwd: ctx.cwd, env, stdio, detached: true });
     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) {
-    const plan = await planCommandSpawn(entry, ctx.cwd, ctx.shellEnv);
+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, hookChildView(ctx));
     if (plan.kind === "refused")
         return { code: null, stdout: "", stderr: "", timedOut: false, spawnError: plan.error };
     if (plan.kind === "shell") {
@@ -882,6 +953,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;
@@ -900,40 +972,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) => {
@@ -952,7 +1000,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`);
     });
@@ -961,7 +1014,7 @@ async function fireAsyncCommandHook(entry, payload, ctx, event, halt) {
     try {
         const rewake = entry.asyncRewake === true;
         const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
-        const plan = await planCommandSpawn(entry, ctx.cwd, ctx.shellEnv);
+        const plan = await planCommandSpawn(entry, ctx.cwd, ctx.shellEnv, hookChildView(ctx));
         if (plan.kind === "refused")
             throw new Error(plan.error);
         if (plan.kind === "shell")
@@ -970,18 +1023,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 = "";
@@ -1000,6 +1046,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;
@@ -1119,6 +1167,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)
@@ -1146,12 +1195,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();
@@ -1277,7 +1325,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;
@@ -1285,6 +1333,41 @@ 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));
 }
@@ -1342,7 +1425,7 @@ function noteRanVerdictFlaw(ctx, ledger, event, ran, flaw, toolName) {
         }
     }
 }
-async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceFired, halt, deadlineAt, ledger, llmExtra) {
+async function runMatchingEntries(event, groups, matchValue, payload, ctx, once, halt, deadlineAt, ledger, llmExtra) {
     const results = [];
     let llmEntries = 0;
     const toolName = toolNameOf(payload);
@@ -1350,10 +1433,10 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
     const truncatedFor = (entry) => (entry.type === "prompt" || entry.type === "agent" ? llmHookArguments(payload).truncated : inputTruncated);
     const blockedBy = (entry, source, cause) => ({ entry, run: blockingFailureRun(event, cause), source });
     let laneSpent = false;
-    const settle = async (entry, onceKey) => {
+    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) {
@@ -1379,7 +1462,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;
@@ -1393,8 +1476,7 @@ 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" };
         }
@@ -1403,8 +1485,6 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 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);
@@ -1437,15 +1517,13 @@ 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) {
+    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 pending) {
-                if (!isSyncEntry(entry))
-                    continue;
                 if (!laneSpent)
                     ledger.unrun(group.source, entry, "matcher_invalid");
                 if (blocksOnFailure(entry, event))
@@ -1455,12 +1533,13 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
         }
         if (selected === false)
             continue;
-        for (const [ei, entry] of group.hooks.entries()) {
+        for (const entry of group.hooks) {
             if (laneSpent && !blocksOnFailure(entry, event))
                 continue;
-            const fate = await settle(entry, `${event}:${index}:${ei}`);
+            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);
@@ -1490,7 +1569,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 case "passed":
                     break;
                 case "halted":
-                    if (isSyncEntry(entry) && halt.budgetSpent())
+                    if (halt.budgetSpent())
                         ledger.halted(group.source, entry);
                     return results;
                 default: {
@@ -1508,17 +1587,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 }));
@@ -1534,9 +1612,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) {
@@ -1589,17 +1667,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;
@@ -1609,9 +1686,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),
@@ -1620,7 +1698,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) {
@@ -1659,13 +1737,14 @@ 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 = alsoAsks(prior.asked ?? prior.unreadable?.message, 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) {
+                            const counted = decision === "allow" || decision === "ask" || decision === undefined;
+                            if (counted) {
                                 if (ran.distrust !== undefined && hookLaneOf(ran.source) === "unmanaged" && (decision === "allow" || proposesRewrite)) {
                                     noteVerdictUntrusted(ctx, { event: "PreToolUse", reason: ran.distrust, entry, source: ran.source, toolName });
                                 }
@@ -1694,54 +1773,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(),
                 };
             }
@@ -1751,10 +1828,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;
@@ -1770,8 +1847,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) {
@@ -1807,10 +1884,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 = [];
@@ -1823,8 +1900,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) {
@@ -1856,10 +1933,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),
@@ -1871,8 +1948,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) {
@@ -1900,19 +1977,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);
@@ -1925,11 +2002,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") {
@@ -1941,10 +2018,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"));
@@ -1972,7 +2049,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)
@@ -1982,7 +2059,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 = [];
@@ -2036,15 +2113,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),
@@ -2052,23 +2130,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);
@@ -2083,31 +2161,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);
         },
     };
 }