@sema-agent/server 7.145.0 → 7.146.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,7 +19,7 @@ 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 { HOOK_PHASES, HOOK_SOURCE_VOCABULARY_SENTENCE, hookLaneOf, hookPhaseOf, readHookGroupSource } from "./hook-source.js";
 import { commandLineChars, composeHookEnvLayer, hookPluginChars, planCommandSpawn, readHookArgs, readHookPlugin } from "./command-spawn.js";
 export const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export const MAX_HOOK_COMMAND_CHARS = 8_192;
@@ -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;
@@ -650,7 +663,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 +705,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 +741,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 +787,36 @@ 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 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")
@@ -1190,7 +1241,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
     const inputTruncated = boundedToolInputPayload(payload) !== payload;
     const truncatedFor = (entry) => (entry.type === "prompt" || entry.type === "agent" ? llmHookArguments(payload).truncated : inputTruncated);
     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,7 +1285,7 @@ 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) {
@@ -1245,12 +1296,14 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             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] });
@@ -1307,6 +1360,8 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 case "passed":
                     break;
                 case "halted":
+                    if (isSyncEntry(entry) && halt.budgetSpent())
+                        ledger.halted(group.source, entry);
                     return results;
                 default: {
                     const unreachable = fate;
@@ -1317,14 +1372,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 +1385,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 +1423,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 +1462,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 +1490,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 +1517,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));
+                                spoke = true;
+                            }
                             const decision = h.permissionDecision;
                             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);
+                                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,12 +1545,16 @@ 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") {
                                 unknownDecision = true;
+                                spoke = true;
                                 ctx.logger.warn("hook_permission_decision_unknown", {
                                     event: "PreToolUse",
                                     decision: seatText("operator-log-text", typeof decision === "string" ? decision : typeof decision),
@@ -1487,7 +1568,7 @@ export function createSettingsHooksRegistration(config, ctx, budgetMs) {
                 }
                 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 +1592,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 +1647,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 +1680,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 +1700,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 +1729,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 +1748,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 +1773,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 +1814,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 +1858,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 +1913,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 +1928,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 +1940,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 +1959,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);
         },
     };
 }

package/dist/hooks/hook-source.d.ts

@@ -1,6 +1,6 @@
 /**
  * 请求面**来源**闭集 —— 一个 hook 组(`settings.hooks[event][i].source`)是谁写的。词表与「托管与否」的映射**只在这里**;
- * hooks 执行器按它分车道(`hook-runner.ts` 的三相),将来请求面别处的来源键(MCP 服务器条目)读同一张词表,不另立第二份。
+ * hooks 执行器按它分相、分车道(`hook-runner.ts` 的三相 / 两张注册),将来请求面别处的来源键(MCP 服务器条目)读同一张词表,不另立第二份。
  *
  * 词表(闭集;集外词 = 形错,受理面整份拒,fail-closed;缺席 = 非托管):
  *  · `managedPolicy`          —— 组织策略(托管设置)。**托管**,且是终判相。
@@ -28,7 +28,7 @@ type HookSourcePrefix = keyof typeof HOOK_SOURCE_PREFIX_PHASE;
 export type HookGroupSource = HookSourceWord | `${HookSourcePrefix}:${string}`;
 /**
  * 执行相 —— **固定次序**就是这张数组的次序:非托管 → 托管插件 → 托管策略(终判)。后一相在前一相的最终输入上跑;结果按信任序(倒序)读。
- * 托管 = 后两相;非托管与托管各一只事件墙钟(见 `hook-runner.ts`)。
+ * 托管 = 后两相;相按 {@link hookLaneOf} 归两条车道(每道一张引擎注册,见 `hook-runner.ts`)。
  */
 export declare const HOOK_PHASES: readonly ["unmanaged", "managedPlugin", "managedPolicy"];
 export type HookPhase = (typeof HOOK_PHASES)[number];
@@ -36,6 +36,18 @@ export type HookPhase = (typeof HOOK_PHASES)[number];
 export declare const MAX_HOOK_SOURCE_NAME_CHARS = 128;
 /** 受理面的读法:合形 ⇒ 来源;否则 `undefined`(调用方铸拒)。只认 own 词(`Object.hasOwn`:原型上的名字不是词表成员)。 */
 export declare function readHookGroupSource(raw: unknown): HookGroupSource | undefined;
+/**
+ * 车道 —— **一条车道 = 一张引擎注册**(`hook-runner.ts` 的 `SETTINGS_HOOKS_REGISTRATIONS`):非托管相一道;托管两相(插件相 + 策略相)同一道。
+ * 每条车道自带引擎的 handler 预算与本服务的事件墙钟 / LLM 条数 / 账本,两道之间不共用任何一只钟。相 → 道只在这张表(`satisfies`:加一个相不写道 = 编译红)。
+ */
+declare const HOOK_PHASE_LANE: {
+    readonly unmanaged: "unmanaged";
+    readonly managedPlugin: "managed";
+    readonly managedPolicy: "managed";
+};
+export type HookLane = (typeof HOOK_PHASE_LANE)[HookPhase];
+/** 来源 → 车道(经相;缺席 ⇒ 非托管)。帧上的 `lane` 位、车道注册的分组都读这一只。 */
+export declare function hookLaneOf(source: HookGroupSource | undefined): HookLane;
 /** 来源 → 相。缺席 ⇒ 非托管(老包不带 `source`:行为与此前逐字同)。 */
 export declare function hookPhaseOf(source: HookGroupSource | undefined): HookPhase;
 /** 拒句里的词表(由两张表派生,不另写一份)。 */

package/dist/hooks/hook-source.js

@@ -27,6 +27,14 @@ export function readHookGroupSource(raw) {
         return undefined;
     return raw;
 }
+const HOOK_PHASE_LANE = {
+    unmanaged: "unmanaged",
+    managedPlugin: "managed",
+    managedPolicy: "managed",
+};
+export function hookLaneOf(source) {
+    return HOOK_PHASE_LANE[hookPhaseOf(source)];
+}
 export function hookPhaseOf(source) {
     if (source === undefined)
         return "unmanaged";

package/dist/http/active-run-conflict.d.ts

@@ -16,7 +16,7 @@
 import { type GovernancePosture } from "../runtime-governance.js";
 import type { ShellGateDoctrine } from "@sema-agent/core";
 import { type RunRecord } from "../plugins/store-contracts.js";
-import { type PendingRowBinding } from "../plugins/checkpoint-store-sql.js";
+import { type PendingRowBinding } from "../plugins/checkpoint-store-face.js";
 /** 与 runs.ts/tasks.ts 三个 409 位共享的旧文案(byte-frozen:api-error-text-freeze 门认这句)。 */
 export declare const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an active run \u2014 POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)";
 /**

package/dist/http/active-run-conflict.js

@@ -1,6 +1,6 @@
 import { governanceOriginOf } from "../runtime-governance.js";
 import { isParkedRunStatus } from "../plugins/store-contracts.js";
-import { LIVE_RUN_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
+import { LIVE_RUN_GATE_KINDS } from "../plugins/checkpoint-store-face.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { refusalBody } from "./refusal-body.js";
 import { trustedCheckpointId } from "../checkpoint-identity.js";