@sema-agent/server 7.145.0 → 7.147.0

package/dist/hooks/hook-runner.js

@@ -7,7 +7,7 @@ import { findUrlCredential, formatConfigPath, outgoingPath } from "@sema-agent/s
 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 } from "./classic-stations.js";
+import { hangClassic, wrapClassic } 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";
@@ -19,8 +19,8 @@ import { ccPromptSystemFor, wrapCondition, parseCcVerdict, CC_EVALUATOR_MAX_OUTP
 import { ccAgentHookSystemFor } from "./cc-agent-hook-prompt.js";
 import { renderBranchTranscript } from "./branch-transcript.js";
 import { buildRequestUrlCredentialRefusal, urlCredentialHeaderExit } from "../url-credential-refusal.js";
-import { HOOK_PHASES, HOOK_SOURCE_VOCABULARY_SENTENCE, hookPhaseOf, readHookGroupSource } from "./hook-source.js";
-import { commandLineChars, composeHookEnvLayer, hookPluginChars, planCommandSpawn, readHookArgs, readHookPlugin } from "./command-spawn.js";
+import { HOOK_PHASES, HOOK_SOURCE_VOCABULARY_SENTENCE, hookLaneOf, hookPhaseOf, readHookGroupSource } from "./hook-source.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;
@@ -52,14 +52,27 @@ export const SETTINGS_HOOK_STATIONS = {
     PreCompact: ["classic.PreCompact"],
     PostCompact: ["classic.PostCompact"],
 };
-function hangTranslator(on, event, translators) {
+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 translate = translators[event];
     if (translate === undefined)
         return;
+    const hang = lane === "managed" ? wrapClassic : hangClassic;
     for (const station of SETTINGS_HOOK_STATIONS[event])
-        hangClassic(on, station, translate);
+        hang(on, station, translate);
 }
-export const SETTINGS_HOOKS_REGISTRATION = "settings.hooks";
+export const SETTINGS_HOOKS_REGISTRATIONS = {
+    managed: "settings.hooks.managed",
+    unmanaged: "settings.hooks",
+};
+const LANE_CHAIN_ORDER = ["managed", "unmanaged"];
 export const DEFAULT_SETTINGS_HOOKS_BUDGET_MS = MAX_HOOK_TIMEOUT_SECONDS * 1000;
 export function settingsHooksBudgetMs(config) {
     return config.hooksTimeoutMs ?? DEFAULT_SETTINGS_HOOKS_BUDGET_MS;
@@ -222,7 +235,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];
@@ -419,16 +431,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));
@@ -587,7 +595,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:
@@ -598,7 +606,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;
@@ -641,6 +649,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",
@@ -650,7 +693,7 @@ function noteVerdictUntrusted(ctx, args) {
         kind: "hook_verdict_untrusted",
         event: args.event,
         reason: args.reason,
-        lane: hookPhaseOf(args.source) === "unmanaged" ? "unmanaged" : "managed",
+        lane: hookLaneOf(args.source),
         hookName: boundedNoticeText(hookDisplayName(args.entry)),
         entryType: args.entry.type,
         ...(args.toolName !== undefined ? { toolName: args.toolName } : {}),
@@ -692,15 +735,22 @@ const VERDICT_GAP_CAUSE = {
 };
 function createUnrunLedger(ctx, event, toolName) {
     let managedVerdictGap;
-    return {
+    let haltNoted = false;
+    const ledger = {
+        halted(source, entry) {
+            if (haltNoted)
+                return;
+            haltNoted = true;
+            ledger.unrun(source, entry, "budget_exhausted", ENGINE_BUDGET_SPENT_DETAIL);
+        },
         untrusted(source, entry, reason) {
-            if (hookPhaseOf(source) === "unmanaged")
+            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 || hookPhaseOf(source) === "unmanaged")
+            if (source === undefined || hookLaneOf(source) === "unmanaged")
                 return;
             managedVerdictGap ??= VERDICT_GAP_CAUSE[reason];
             ctx.logger.warn("hook_managed_unrun", { event, reason, source: echoCallerText(source), type: entry.type, ...(toolName !== undefined ? { tool: toolName } : {}) });
@@ -721,6 +771,7 @@ function createUnrunLedger(ctx, event, toolName) {
             return managedVerdictGap;
         },
     };
+    return ledger;
 }
 function noteExitNonzero(ctx, ledger, event, ran, toolName, detail) {
     logHookCommandFailed(ctx, event, ran.run);
@@ -766,6 +817,39 @@ function buildHookContextField(parts) {
     const text = buildHookContext(parts);
     return text === undefined ? {} : { additionalContext: text };
 }
+function belowString(below, key) {
+    if (typeof below !== "object" || below === null || !Object.hasOwn(below, key))
+        return undefined;
+    const value = Reflect.get(below, key);
+    return typeof value === "string" ? value : undefined;
+}
+function belowMembers(below) {
+    return typeof below === "object" && below !== null ? { ...below } : {};
+}
+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})`;
+}
+function readBelowPreToolUse(below) {
+    const action = belowString(below, "action");
+    const message = belowString(below, "message") ?? "a PreToolUse hook requires approval";
+    const cause = belowString(below, "questionCause");
+    const rewrite = typeof below === "object" && below !== null && Object.hasOwn(below, "updatedInput") ? Reflect.get(below, "updatedInput") : undefined;
+    const additionalContext = belowString(below, "additionalContext");
+    const unreadableCause = cause === "verdict_unfinished" ? "verdict_unfinished" : "verdict_unreadable";
+    return {
+        denied: action === "deny",
+        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,
+        ...(rewrite !== null && typeof rewrite === "object" ? { updatedInput: rewrite } : {}),
+        ...(additionalContext !== undefined ? { additionalContext } : {}),
+    };
+}
 function spawnPlannedCommand(plan, ctx, stdio) {
     const env = hookChildEnv(plan.env, true);
     if (plan.kind === "exec")
@@ -1139,18 +1223,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("{"))
@@ -1183,14 +1288,70 @@ function runRunnableEntry(entry, payload, ctx, event, llmExtra, halt) {
 function isSyncEntry(entry) {
     return !(entry.type === "command" && (entry.async === true || entry.asyncRewake === true));
 }
+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, onceFired, 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 blockedBy = (entry, source, cause) => ({ entry, run: blockingFailureRun(event, cause), source });
+    let laneSpent = false;
     const settle = async (entry, onceKey) => {
-        if (halt.aborted)
+        if (halt.signal.aborted)
             return { kind: "halted" };
         if (entry.once && onceFired.has(onceKey))
             return { kind: "passed" };
@@ -1234,23 +1395,26 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
         if (entry.type === "command" && (entry.async || entry.asyncRewake)) {
             if (entry.once)
                 onceFired.add(onceKey);
-            void fireAsyncCommandHook(entry, payload, ctx, event, halt);
+            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);
+        const run = await runRunnableEntry(entry, payload, ctx, event, llmExtra, halt.signal);
         if (run.aborted !== undefined) {
             if (run.aborted.signal !== undefined)
                 ctx.logger.warn("hook_command_killed", { event, type: entry.type, killed: true, signal: run.aborted.signal });
             return { kind: "halted" };
         }
+        if (halt.signal.aborted)
+            return { kind: "halted" };
         if (run.withheld !== undefined) {
             const { list, rule, sources } = run.withheld;
             ctx.logger.warn("hook_http_withheld", { event, url: entry.type === "http" ? buildDisplaySafeUrl(entry.url) : null, list, rule, sources: [...sources] });
@@ -1274,19 +1438,35 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
         return ifOverBudget ? { kind: "ran", run, overBudget: true } : { kind: "ran", run };
     };
     for (const { group, index } of groups) {
-        const selected = matcherGroupSelected(ctx, event, group, matchValue, toolName);
+        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 (!isSyncEntry(entry))
+                    continue;
+                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()) {
+            if (laneSpent && !blocksOnFailure(entry, event))
+                continue;
             const fate = await settle(entry, `${event}:${index}:${ei}`);
             switch (fate.kind) {
                 case "ran": {
+                    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)
@@ -1300,13 +1480,18 @@ 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())
+                        ledger.halted(group.source, entry);
                     return results;
                 default: {
                     const unreachable = fate;
@@ -1317,14 +1502,12 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
     }
     return results;
 }
-function createLaneClocks() {
-    const startedAt = {};
-    return (phase) => {
-        const lane = phase === "unmanaged" ? "unmanaged" : "managed";
-        return (startedAt[lane] ??= Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
-    };
+function createEventClock() {
+    let deadlineAt;
+    return () => (deadlineAt ??= Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
 }
-function hookLanesOf(groups) {
+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);
 }
@@ -1332,12 +1515,10 @@ function trustRank(phase) {
     return HOOK_PHASES.length - 1 - HOOK_PHASES.indexOf(phase);
 }
 async function runEventLanes(event, groups, matchValue, payload, ctx, onceFired, halt, ledger, llmExtra) {
-    const deadlineFor = createLaneClocks();
+    const deadline = createEventClock();
     const ran = [];
-    for (const lane of hookLanesOf(groups)) {
-        if (halt.aborted)
-            break;
-        for (const r of await runMatchingEntries(event, lane.groups, matchValue, payload, ctx, onceFired, halt, deadlineFor(lane.phase), ledger, llmExtra))
+    for (const lane of hookPhasesOf(groups)) {
+        for (const r of await runMatchingEntries(event, lane.groups, matchValue, payload, ctx, onceFired, 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 }));
@@ -1372,12 +1553,26 @@ async function runObserveOnlyEvent(event, groups, matchValue, payload, ctx, once
         }
     }
 }
-export function createSettingsHooksRegistration(config, ctx, budgetMs) {
-    const configured = Object.keys(config).filter((e) => (config[e]?.length ?? 0) > 0);
-    const shellOwned = configured.filter((e) => HOOK_EVENT_OWNER[e] === "shell");
+export function createSettingsHooksRegistrations(config, ctx, budgetMs) {
+    const shellOwned = Object.keys(config).filter((e) => (config[e]?.length ?? 0) > 0 && HOOK_EVENT_OWNER[e] === "shell");
     if (shellOwned.length > 0) {
         ctx.logger.debug("hook_events_shell_owned", { events: shellOwned });
     }
+    return LANE_CHAIN_ORDER.flatMap((lane) => {
+        const registration = createLaneRegistration(lane, laneConfigOf(config, lane), ctx, budgetMs);
+        return registration === undefined ? [] : [registration];
+    });
+}
+function laneConfigOf(config, lane) {
+    const out = {};
+    for (const event of Object.keys(config)) {
+        const groups = config[event]?.filter((group) => hookLaneOf(group.source) === lane);
+        if (groups !== undefined && groups.length > 0)
+            out[event] = groups;
+    }
+    return out;
+}
+function createLaneRegistration(lane, config, ctx, budgetMs) {
     const lit = (e) => {
         const groups = config[e];
         return groups && groups.length > 0 ? groups : undefined;
@@ -1397,17 +1592,23 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
     const onceFired = new Set();
     const translators = {};
     if (pre) {
-        translators.PreToolUse = async (e, signal) => {
+        const tightenOnly = managedTightenOnlyOn(lane, "classic.PreToolUse", ctx.belowTaskChainPatterns);
+        translators.PreToolUse = async (e, halt, below) => {
+            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 deadlineFor = createLaneClocks();
-            let currentInput = e.input;
-            let rewritten = false;
-            let asked;
-            let allowedFor;
+            const deadline = createEventClock();
+            let currentInput = prior.updatedInput ?? e.input;
+            let rewritten = prior.updatedInput !== undefined;
+            let asked = prior.asked;
+            let spoke = false;
+            let allowedFor = prior.allowed ? { input: currentInput } : undefined;
             let unknownDecision = false;
             const contexts = { unmanaged: [], managedPlugin: [], managedPolicy: [] };
-            const contextField = () => buildHookContextField([...HOOK_PHASES].sort((a, b) => trustRank(a) - trustRank(b)).flatMap((p) => contexts[p]));
+            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) => {
                 let rewroteBy;
                 for (const laneGroup of groups) {
@@ -1419,7 +1620,7 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                         tool_input: groupInput,
                         tool_use_id: e.tool_use_id,
                     };
-                    const singles = await runMatchingEntries("PreToolUse", [laneGroup], toolName, payload, ctx, once, signal, deadlineFor(phase), ledger);
+                    const singles = await runMatchingEntries("PreToolUse", [laneGroup], toolName, payload, ctx, once, halt, deadline(), ledger);
                     for (const ran of singles) {
                         const { entry, run } = ran;
                         if (run.code === 2) {
@@ -1446,20 +1647,26 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                         const hso = out.hookSpecificOutput;
                         if (hso !== null && typeof hso === "object" && hso.hookEventName === "PreToolUse") {
                             const h = hso;
-                            if (typeof h.additionalContext === "string")
+                            if (typeof h.additionalContext === "string") {
                                 contexts[phase].push(clipDataText(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
-                            const decision = h.permissionDecision;
+                                spoke = true;
+                            }
+                            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() } };
                             }
+                            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() } };
+                            }
                             if (decision === "ask") {
-                                asked = clipDataText(typeof h.permissionDecisionReason === "string" ? h.permissionDecisionReason : "a PreToolUse hook requires approval", MAX_HOOK_FEEDBACK_CHARS);
+                                asked = alsoAsks(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 proposed = h.updatedInput !== null && typeof h.updatedInput === "object" ? h.updatedInput : undefined;
-                                const proposesRewrite = proposed !== undefined && canonicalJsonStringify(proposed) !== canonicalJsonStringify(groupInput);
-                                if (ran.distrust !== undefined && hookPhaseOf(ran.source) === "unmanaged" && (decision === "allow" || proposesRewrite)) {
+                                if (ran.distrust !== undefined && hookLaneOf(ran.source) === "unmanaged" && (decision === "allow" || proposesRewrite)) {
                                     noteVerdictUntrusted(ctx, { event: "PreToolUse", reason: ran.distrust, entry, source: ran.source, toolName });
                                 }
                                 const offered = ran.distrust === undefined ? proposed : undefined;
@@ -1468,26 +1675,24 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                                     currentInput = offered;
                                     rewritten = true;
                                     rewroteBy = ran;
+                                    spoke = true;
                                 }
-                                if (decision === "allow" && ran.distrust === undefined)
+                                if (decision === "allow" && ran.distrust === undefined) {
                                     allowedFor = { input: rewrites ? offered : groupInput };
+                                    spoke = true;
+                                }
                             }
-                            else if (decision !== "deny" && decision !== "ask") {
+                            else if (!PERMISSION_DECISION_WORDS.has(decision)) {
                                 unknownDecision = 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");
+                                spoke = true;
+                                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");
                             }
                         }
                     }
                 }
                 return { rewroteBy };
             };
-            for (const lane of hookLanesOf(pre)) {
+            for (const lane of hookPhasesOf(pre)) {
                 if (lane.phase === "unmanaged") {
                     const pass = await runPass(lane.phase, lane.groups, onceFired);
                     if (pass.deny !== undefined)
@@ -1511,38 +1716,45 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                     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)
+                return undefined;
             if (asked !== undefined) {
-                return { action: "ask", message: asked, questionCause: "asked", ...(rewritten ? { updatedInput: currentInput } : {}), ...contextField() };
+                return { action: "ask", message: asked, questionCause: "asked", ...(rewritten ? { updatedInput: currentInput } : {}), ...realApproval, ...contextField() };
             }
-            const managedGap = ledger.managedVerdictGap;
             if (managedGap !== undefined) {
                 return {
                     action: "ask",
                     message: "a managed PreToolUse hook did not run to a verdict — approval required",
                     questionCause: managedGap,
                     ...(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() };
+            }
             if (unknownDecision) {
                 return {
                     action: "ask",
                     message: "a PreToolUse hook returned an unrecognized permissionDecision — approval required",
                     questionCause: "verdict_unreadable",
                     ...(rewritten ? { updatedInput: currentInput } : {}),
+                    ...realApproval,
                     ...contextField(),
                 };
             }
             const carried = { ...(rewritten ? { updatedInput: currentInput } : {}), ...contextField() };
             if (allowedFor !== undefined && allowedFor.input === currentInput)
                 return { action: "allow", ...carried };
-            if (rewritten || HOOK_PHASES.some((p) => contexts[p].length > 0))
+            if (rewritten || HOOK_PHASES.some((p) => contexts[p].length > 0) || prior.additionalContext !== undefined)
                 return carried;
             return undefined;
         };
     }
     if (post) {
-        translators.PostToolUse = async (e, signal) => {
+        translators.PostToolUse = async (e, halt, below) => {
             const toolName = e.tool;
             const input = e.input;
             const output = e.output;
@@ -1559,7 +1771,7 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                 tool_use_id: e.tool_use_id,
             };
             const ledger = createUnrunLedger(ctx, "PostToolUse", toolName);
-            const singles = await runEventLanes("PostToolUse", post, toolName, payload, ctx, onceFired, signal, ledger);
+            const singles = await runEventLanes("PostToolUse", post, toolName, payload, ctx, onceFired, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1592,12 +1804,13 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                     }
                 }
             }
-            const additionalContext = buildHookContext(contexts);
-            return additionalContext === undefined ? undefined : { additionalContext };
+            if (contexts.length === 0)
+                return undefined;
+            return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
         };
     }
     if (postFailure) {
-        translators.PostToolUseFailure = async (e, signal) => {
+        translators.PostToolUseFailure = async (e, halt, below) => {
             const toolName = e.tool;
             const f = e.failure;
             const contexts = [];
@@ -1611,7 +1824,7 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                 is_interrupt: f.isInterrupt,
             };
             const ledger = createUnrunLedger(ctx, "PostToolUseFailure", toolName);
-            const singles = await runEventLanes("PostToolUseFailure", postFailure, toolName, payload, ctx, onceFired, signal, ledger);
+            const singles = await runEventLanes("PostToolUseFailure", postFailure, toolName, payload, ctx, onceFired, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1640,12 +1853,13 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                         contexts.push(clipDataText(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                 }
             }
-            const additionalContext = buildHookContext(contexts);
-            return additionalContext === undefined ? undefined : { additionalContext };
+            if (contexts.length === 0)
+                return undefined;
+            return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
         };
     }
     if (postBatch) {
-        translators.PostToolBatch = async (e, signal) => {
+        translators.PostToolBatch = async (e, halt, below) => {
             const contexts = [];
             const payload = {
                 ...basePayload(ctx, e.permissionMode),
@@ -1658,7 +1872,7 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                 })),
             };
             const ledger = createUnrunLedger(ctx, "PostToolBatch", undefined);
-            const singles = await runEventLanes("PostToolBatch", ignoreMatchers(postBatch), "", payload, ctx, onceFired, signal, ledger);
+            const singles = await runEventLanes("PostToolBatch", ignoreMatchers(postBatch), "", payload, ctx, onceFired, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1683,16 +1897,17 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                 if (out.hookSpecificOutput !== undefined)
                     ctx.logger.warn("hook_result_unsupported", { event: "PostToolBatch" });
             }
-            const additionalContext = buildHookContext(contexts);
-            return additionalContext === undefined ? undefined : { additionalContext };
+            if (contexts.length === 0)
+                return undefined;
+            return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
         };
     }
     if (promptSubmit) {
-        translators.UserPromptSubmit = async (e, signal) => {
+        translators.UserPromptSubmit = async (e, halt, below) => {
             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, signal, ledger);
+            const singles = await runEventLanes("UserPromptSubmit", ignoreMatchers(promptSubmit), "", payload, ctx, onceFired, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
@@ -1723,12 +1938,13 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                         contexts.push(clipDataText(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                 }
             }
-            const additionalContext = buildHookContext(contexts);
-            return additionalContext === undefined ? undefined : { additionalContext };
+            if (contexts.length === 0)
+                return undefined;
+            return { ...belowMembers(below), ...buildHookContextField(withBelowContext(contexts, below)) };
         };
     }
     if (stopEntries) {
-        translators.Stop = async (sctx, signal) => {
+        translators.Stop = async (sctx, halt, below) => {
             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"));
@@ -1766,7 +1982,7 @@ export function createSettingsHooksRegistration(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, signal, ledger, llmExtra);
+            const singles = await runEventLanes("Stop", effectiveGroups, "", payload, ctx, onceFired, halt, ledger, llmExtra);
             let block;
             let sawContinueFalse = false;
             const contexts = [];
@@ -1821,13 +2037,14 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
             if (block === undefined && contexts.length === 0)
                 return undefined;
             return {
+                ...belowMembers(below),
                 ...(block !== undefined ? { block } : {}),
-                ...buildHookContextField(contexts),
+                ...buildHookContextField(withBelowContext(contexts, below)),
             };
         };
     }
     if (stopFailureEntries) {
-        translators.StopFailure = async (fctx, signal) => {
+        translators.StopFailure = async (fctx, halt) => {
             const turnError = toAssistantTurnError(fctx.errorKind);
             const payload = {
                 ...basePayload(ctx, undefined),
@@ -1835,11 +2052,11 @@ export function createSettingsHooksRegistration(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, signal);
+            await runObserveOnlyEvent("StopFailure", stopFailureEntries, turnError, payload, ctx, onceFired, halt);
         };
     }
     if (preCompactEntries) {
-        translators.PreCompact = async (pctx, signal) => {
+        translators.PreCompact = async (pctx, halt, below) => {
             const payload = {
                 ...basePayload(ctx, undefined),
                 hook_event_name: "PreCompact",
@@ -1847,11 +2064,11 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                 custom_instructions: pctx.customInstructions ?? null,
             };
             const ledger = createUnrunLedger(ctx, "PreCompact", undefined);
-            const singles = await runEventLanes("PreCompact", preCompactEntries, pctx.trigger, payload, ctx, onceFired, signal, ledger);
+            const singles = await runEventLanes("PreCompact", preCompactEntries, pctx.trigger, payload, ctx, onceFired, halt, ledger);
             for (const ran of singles) {
                 const { entry, run } = ran;
                 if (run.code === 2) {
-                    return { block: clipDataText(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a PreCompact hook" };
+                    return { ...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);
@@ -1866,31 +2083,31 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                     ctx.logger.warn("hook_continue_false_unsupported", { event: "PreCompact" });
                 }
                 if (out.decision === "block") {
-                    return { block: clipDataText(typeof out.reason === "string" ? out.reason : "blocked by a PreCompact hook", MAX_HOOK_FEEDBACK_CHARS) };
+                    return { ...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, signal) => {
+        translators.PostCompact = async (cctx, halt) => {
             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, signal);
+            await runObserveOnlyEvent("PostCompact", postCompactEntries, cctx.trigger, payload, ctx, onceFired, halt);
         };
     }
     const events = Object.keys(translators);
     return {
-        name: SETTINGS_HOOKS_REGISTRATION,
+        name: SETTINGS_HOOKS_REGISTRATIONS[lane],
         uses: { events: events.flatMap((event) => SETTINGS_HOOK_STATIONS[event]), calls: [] },
         budgetMs,
         register(on) {
             for (const event of events)
-                hangTranslator(on, event, translators);
+                hangTranslator(on, event, translators, lane);
         },
     };
 }