@sema-agent/core 7.5.1 → 7.6.0

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -0,0 +1,174 @@
+/**
+ * design/390 §1.2 M20 — prepareTask's two GATE STATIONS, verbatim from the driver: the `tool_call` station (the final-roster
+ * effect sync, the write-protection judge compiled once per task, the arming predicate, the compliance and plan-mode
+ * short-circuits, the `runToolGate` call with every seat it is handed, the lifecycle sweep, the deferred sandbox-admission
+ * disclosure, the PreToolUse context stash, the settlement sideband write and the bare-human-rejection boundary) and the
+ * `tool_result` station (the PostToolUse / PostToolUseFailure seats and the PreToolUse context drain). The two module-scope
+ * helpers only these stations called moved with them (the settlement screen, the rejection-boundary judgment). The
+ * interface is the dependency list the stations had implicitly (design/238 R-1).
+ *
+ * The stations REGISTER handlers on the harness (the side effect this phase exists for) and report only two observation
+ * seats back; the order they register in — after the file-history boundary lease the driver registers, and in this order
+ * (call before result) — is the order handlers run in.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the handlers run per tool call / per tool
+ * result), so the phase adds no yield between the park closure before it and the context lane after it (design/390 §1.5).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * The `tool_call` station is built exactly when the ask lane and the park closure are (the same predicate as the whole
+ * gate-machinery block, kept as the block's one guard here); the `tool_result` station keys off the hook record alone, as
+ * it always did.
+ *
+ * Every station this file holds is a `denySource` / settlement WRITE site the decomposition's next slice maps onto one
+ * gate outcome; nothing here changes a word, a source or an order — the stations are moved, not re-adjudicated.
+ */
+import type { AgentHarness, AgentTool } from "../../internal/harness.js";
+import type { AskClass } from "../ask-class.js";
+import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
+import { type ComplianceCapability } from "../compliance.js";
+import { type HookEnvCapabilities, type HookInvocationIdentity, type Hooks } from "../hooks.js";
+import type { ToolPolicy } from "../tool-policy.js";
+import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes } from "./contracts.js";
+import type { StopForDenialLimit } from "./denial-limit-arms.js";
+import type { PermissionRuleLanes } from "./permission-rule-lanes.js";
+export interface PrepareGateStationsInput {
+    /** borrowed-readonly — the in-stream ask lane, or undefined when the gate machinery is inactive (then no `tool_call`
+     *  station is built). Read: `adjudicate`, `resolveAskBound`, `notifyPermissionDenied`, `notifyHookError`. */
+    askLane: AskLane | undefined;
+    /** borrowed-readonly — the park closure and the content-ask routing closure, or undefined (same law). Handed to the gate. */
+    parkAsk: ParkAsk | undefined;
+    /** borrowed-readonly — the FINAL mount roster: iterated once for the effect sync and the write-protection arming. Never
+     *  mutated here. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the effect collection. Writer here: the final-roster sync fills MISSING entries from each
+     *  first-party tool's declared effect (never overrides a scanned one); the plan-mode deny reads it per call. */
+    toolEffects: Map<string, ToolEffect>;
+    /** borrowed-readonly — the deployment seats these stations read, as a Pick over the SAME `deps` object (receiver
+     *  preserved for `deps.onError?.()`): the write-protection table and its data root, the tracer, the error face. */
+    deps: Pick<RunnerDeps, "writeProtectedPaths" | "memoryEngineDir" | "tracer" | "onError">;
+    /** borrowed-mutable — the protocol-tools phase's arming belt. Writer here: `armed` ← the registration predicate, the
+     *  one write; the refresh seam reads it. */
+    toolCallGateArmedRef: {
+        armed: boolean;
+    };
+    /** borrowed-readonly — the policy chain's effective policy, or undefined; presence only (the arming predicate). */
+    effectivePolicy: ToolPolicy | undefined;
+    /** borrowed-readonly — the resolved hook record: `preToolUse` presence (arming), the two post seats and the failure seat
+     *  (the `tool_result` station), called through the record so a class-instance keeps its receiver. */
+    hooks: Hooks | undefined;
+    /** borrowed-readonly — the egress vocabulary: arming, and the per-call `egress` flag handed to the gate. */
+    egressTools: ReadonlySet<string>;
+    /** borrowed-readonly — the irreversible vocabulary: arming only. */
+    irreversibleTools: ReadonlySet<string>;
+    /** borrowed-readonly — the REBOUND spec: `enablePlanMode` (arming) and `signal` (the failure seat's interrupt fact). */
+    spec: Pick<TaskSpec, "enablePlanMode" | "signal">;
+    /** borrowed-readonly — the compliance denials (the web_fetch veto's call-time lock, and its arming term). */
+    complianceDenies: ReadonlySet<ComplianceCapability>;
+    /** borrowed-mutable — the built harness. Writer here: `on("tool_call")` / `on("tool_result")` — the registrations this
+     *  phase exists for, in this order, after the driver's boundary-lease handler. */
+    harness: Pick<AgentHarness, "on">;
+    /** borrowed-mutable — the blocked/suspended call ids (`Prepared.blockedToolCalls`). Writers here: the head-of-evaluation
+     *  hygiene `delete`, the two short-circuits' and the gate outcome's `add`, the `tool_result` station's one-shot `delete`. */
+    blockedToolCalls: Set<string>;
+    /** borrowed-mutable — the duplicate-frame ask-grant record. Writer here: the head-of-evaluation and lifecycle-end `delete`. */
+    inheritedAskGrants: Map<string, unknown>;
+    /** borrowed-mutable — the inherited-unavailable marker set. Writer here: the lifecycle-end `delete`; `has` is handed to
+     *  the gate as the read-only `isMarkedUnresolvable`. */
+    inheritedUnavailableAsks: Set<string>;
+    /** borrowed-mutable — the per-call ask-class record the sandbox admission reads. Writer here: the lifecycle-end `delete`. */
+    foldAskClasses: Map<string, Array<{
+        cls: AskClass;
+        layer: string;
+    }>>;
+    /** borrowed-mutable — the deferred ancestor sandbox admissions. Writer here: the unconditional read-and-`delete` after the
+     *  fold settles. */
+    ancestorSandboxAdmissions: Map<string, Array<{
+        cls: AskClass;
+        layer: string;
+    }>>;
+    /** borrowed-mutable — PreToolUse `additionalContext` per call id. Writers here: the `tool_call` station's stash (`set`, only
+     *  for calls that will execute) and the `tool_result` station's one-shot drain (`delete`). */
+    preToolContexts: Map<string, string[]>;
+    /** borrowed-mutable — the gate-outcome sideband (`Prepared.gateOutcomes`). Writer here: the single screened write per
+     *  gated call (the two short-circuits and the gate's terminal exits); the frame mint reads and deletes. */
+    gateOutcomes: Prepared["gateOutcomes"];
+    /** borrowed-mutable — the turn halt fact (`Prepared.batchHaltRef`). Writer here: the bare-rejection boundary (`current`). */
+    batchHaltRef: Prepared["batchHaltRef"];
+    /** borrowed-readonly — whether blocked/suspended ids are tracked at all (the post-tool callbacks exist). */
+    blockedTracked: boolean;
+    /** borrowed-readonly — the leg's identity envelope every HookToolContext and PermissionDeniedPayload carries. */
+    hookIdentity: HookInvocationIdentity;
+    /** borrowed-readonly — the leg's reminder provenance mark (every model-facing deny reason and hook context carries it). */
+    reminderMark: string;
+    /** borrowed-readonly — the plan-mode latch (`Prepared.planModeRef`); `active` is read per call. Not written here. */
+    planModeRef: Prepared["planModeRef"];
+    /** borrowed-readonly — the per-task identity (the trace rows' taskId). */
+    hostTaskId: string;
+    /** borrowed-readonly — the acquired session id (the settlement defects' error tag). */
+    sessionId: string;
+    /** borrowed-readonly — the screening face as the gate must see it (the observational wrapper or the face itself). */
+    ownGatePreToolUse: Hooks["preToolUse"] | undefined;
+    /** borrowed-readonly — the validated per-prepare hook seat bound. */
+    hookTimeoutMs: number;
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined; `current` is read per screening / per post seat. Not
+     *  written here. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the read-only env capability face every hook context carries, or undefined. */
+    hookEnvFace: HookEnvCapabilities | undefined;
+    /** borrowed-readonly — the per-tool irreversibility tier handed to the gate per call. */
+    irreversibilityTier: IrreversibilityTier;
+    /** borrowed-readonly — the per-tool reversibility probes handed to the gate per call. */
+    reversibilityProbes: ReversibilityProbes;
+    /** borrowed-readonly — prepare's abort seat; only `.signal` is read (the gate's probe bound, the post seats' bound, the
+     *  failure seat's interrupt fact). */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — whether Bash is coarsely shell-gated (the gate's `shellGated` attribution). */
+    shellGatedBash: boolean;
+    /** borrowed-readonly — whether Monitor is coarsely shell-gated (same). */
+    shellGatedMonitor: boolean;
+    /** borrowed-readonly — the auto-mode decider, or undefined (the classifier lane the gate routes a surviving ask through). */
+    autoModeDecider: AutoModeDecider | undefined;
+    /** borrowed-readonly — the auto-mode denial tracker, or undefined (handed to the gate beside the decider). */
+    autoModeDenialTracking: AutoModeDenialTracker | undefined;
+    /** borrowed-readonly — the headless denial-limit stop seat (wired unconditionally). */
+    stopForDenialLimit: StopForDenialLimit;
+    /** borrowed-readonly — the persisted allow-rule lane, or undefined (absent entirely with no store). */
+    permissionRuleLane: PermissionRuleLanes["personal"];
+    /** borrowed-readonly — the org rule lane, or undefined (absent on an ungoverned deployment). */
+    permissionRuleOrgLane: PermissionRuleLanes["org"];
+    /** borrowed-readonly — whether the ENGINE's question tool is what is mounted under the reserved name (the org lane's
+     *  content-ask exemption predicate). */
+    questionToolMounted: boolean;
+    /** borrowed-readonly — whether sandbox admission is armed (isolated env + park prerequisites). */
+    sandboxAdmissionArmed: boolean;
+    /** borrowed-readonly — the per-tool boundary-capability fact the sandbox admission reads. */
+    sandboxBoundaryCapable: (toolName: string) => boolean;
+    /** borrowed-readonly — the sandbox-admission trace sink (the deferred ancestor disclosure and the gate's own). */
+    emitSandboxAdmitted: (info: {
+        toolCallId: string;
+        toolName: string;
+        askClasses: ReadonlyArray<{
+            cls: AskClass;
+            layer: string;
+        }>;
+        boundary: "sandbox_internal";
+    }) => void;
+    /** borrowed-readonly — the effective delegation facts (the rejection boundary's isDelegatedChild). */
+    delegation: {
+        isDelegatedChild: boolean;
+    };
+    /** borrowed-readonly — the own hook-crash reporter (an expired post seat is reported through it). */
+    notifyOwnHookCrash: (err: unknown) => void;
+}
+export interface PrepareGateStationsResult {
+    /** owned — whether the `tool_call` station registered (the arming predicate's value; observation seat only). */
+    toolCallStationArmed: boolean;
+    /** owned — whether the `tool_result` station registered (a post or screening hook is wired; observation seat only). */
+    toolResultStationArmed: boolean;
+}
+/** The M20 phase body — prepareTask's two gate stations, verbatim (see the module header). */
+export declare function prepareGateStations(input: PrepareGateStationsInput): PrepareGateStationsResult;

package/dist/core/runner/prepare-gate-stations.js

@@ -0,0 +1,265 @@
+import { SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
+import { complianceCallDenial } from "../compliance.js";
+import { cloneObserverInput, formatHookFeedback, hookSeatExpiredError, runHookSeat, runToolGate } from "../hooks.js";
+import { PRESENT_PLAN_TOOL_NAME } from "../present-plan-tool.js";
+import { screenGateOutcome } from "../gate-outcome.js";
+import { directDeny } from "./gate-exit.js";
+import { emitTrace } from "../trace.js";
+import { createWriteProtectionCheck } from "../write-protect.js";
+import { PATH_CONFINABLE_WRITE_TOOLS } from "./session-rule-policy.js";
+function screenGateResult(result) {
+    if (result.suspend !== undefined)
+        return { defects: [] };
+    const gate = result.gate;
+    if (gate === undefined)
+        return { defects: ["a tool-gate result carried no outcome record on a terminal exit — every terminal exit mints one; the frame carries none"] };
+    const defects = screenGateOutcome(gate);
+    const blocked = result.block === true;
+    if ((gate.disposition.kind === "denied") !== blocked) {
+        defects.push(`a tool-gate result's outcome reads "${gate.disposition.kind}" on ${blocked ? "a blocked" : "an executing"} call — the two faces of one verdict disagree; the frame carries no outcome`);
+    }
+    return defects.length > 0 ? { defects } : { gate, defects };
+}
+function maybeHumanRejectionHalt(input) {
+    const d = input.gate?.disposition;
+    const s = input.gate?.settlement;
+    const bare = d?.kind === "denied" && d.deniedBy === "ask_resolution" && s?.kind === "human_refused" && s.note === undefined;
+    if (!bare || input.isDelegatedChild)
+        return undefined;
+    return {
+        reason: `This tool call was NOT executed: the user rejected the "${input.toolName}" tool call in the same ` +
+            `assistant message, which stops the rest of the batch. Nothing was run for this call — ` +
+            `re-issue it after the user's direction only if it is still needed.`,
+        details: {
+            error: "gate.batch_halted",
+            code: "gate.batch_halted",
+            rejectedToolCallId: input.toolCallId,
+            rejectedToolName: input.toolName,
+        },
+    };
+}
+export function prepareGateStations(input) {
+    const { askLane, parkAsk, tools, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedBash, shellGatedMonitor, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash } = input;
+    if (askLane !== undefined && parkAsk !== undefined) {
+        const { adjudicate, resolveAskBound, notifyPermissionDenied, notifyHookError } = askLane;
+        const { resolveContentAsk, suspendAsk } = parkAsk;
+        for (const t of tools) {
+            const eff = t.effect;
+            if (eff !== undefined && !toolEffects.has(t.name))
+                toolEffects.set(t.name, eff);
+        }
+        const writeProtectionCheck = createWriteProtectionCheck(deps.writeProtectedPaths, deps.memoryEngineDir !== undefined ? { dataRoot: deps.memoryEngineDir } : undefined);
+        const writeProtectionArmed = writeProtectionCheck !== undefined && tools.some((t) => PATH_CONFINABLE_WRITE_TOOLS.has(t.name));
+        toolCallGateArmedRef.armed =
+            effectivePolicy !== undefined ||
+                hooks?.preToolUse !== undefined ||
+                egressTools.size > 0 ||
+                irreversibleTools.size > 0 ||
+                spec.enablePlanMode === true ||
+                complianceDenies.has("web_fetch") ||
+                writeProtectionArmed;
+        if (toolCallGateArmedRef.armed) {
+            harness.on("tool_call", async (e) => {
+                blockedToolCalls.delete(e.toolCallId);
+                inheritedAskGrants.delete(e.toolCallId);
+                {
+                    const complianceDeny = complianceCallDenial(complianceDenies, e.toolName);
+                    if (complianceDeny !== undefined) {
+                        if (blockedTracked)
+                            blockedToolCalls.add(e.toolCallId);
+                        const gate = directDeny("compliance");
+                        gateOutcomes.set(e.toolCallId, gate);
+                        if (notifyPermissionDenied) {
+                            await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: complianceDeny, gate, identity: hookIdentity });
+                        }
+                        return { block: true, reason: formatHookFeedback(complianceDeny, reminderMark), preToolContext: [] };
+                    }
+                }
+                if (planModeRef.active && (toolEffects.get(e.toolName) ?? "write") !== "read") {
+                    if (blockedTracked)
+                        blockedToolCalls.add(e.toolCallId);
+                    const planDenyReason = `Plan mode is active — "${e.toolName}" is a write/mutating tool and is read-only-blocked. ` +
+                        `Research with read-only tools, then call ${PRESENT_PLAN_TOOL_NAME} with your plan to get it approved before acting.`;
+                    const gate = directDeny("plan_mode");
+                    gateOutcomes.set(e.toolCallId, gate);
+                    if (notifyPermissionDenied) {
+                        await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: planDenyReason, gate, identity: hookIdentity });
+                    }
+                    return {
+                        block: true,
+                        reason: formatHookFeedback(planDenyReason, reminderMark),
+                        preToolContext: [],
+                    };
+                }
+                let result;
+                try {
+                    result = await runToolGate({
+                        onNotifyError: (f) => emitTrace(deps.tracer, () => ({ kind: "observer.notify_failed", version: 1, taskId: hostTaskId, site: f.site, message: f.error.message, ts: Date.now() })),
+                        event: e,
+                        ...(e.signal !== undefined ? { callSignal: e.signal } : {}),
+                        identity: hookIdentity,
+                        reminderMark,
+                        preToolUse: ownGatePreToolUse,
+                        hookTimeoutMs,
+                        ...(handsCwdRef !== undefined ? { trackedCwd: () => handsCwdRef.current } : {}),
+                        ...(hookEnvFace !== undefined ? { hookEnv: hookEnvFace } : {}),
+                        adjudicate,
+                        resolveAsk: resolveAskBound,
+                        suspendAsk,
+                        resolveContentAsk,
+                        egress: egressTools.has(e.toolName),
+                        peerMessage: e.toolName === SEND_MESSAGE_TOOL_NAME,
+                        ...(writeProtectionCheck !== undefined ? { writeProtectionCheck } : {}),
+                        irreversibility: irreversibilityTier.get(e.toolName),
+                        reversibilityProbe: reversibilityProbes.get(e.toolName),
+                        abortSignal: abortController.signal,
+                        ...(notifyPermissionDenied ? { permissionDenied: notifyPermissionDenied } : {}),
+                        onHookError: notifyHookError,
+                        shellGated: (e.toolName === "Bash" && shellGatedBash) || (e.toolName === "Monitor" && shellGatedMonitor),
+                        ...(autoModeDecider ? { autoMode: { decider: autoModeDecider, ...(autoModeDenialTracking !== undefined ? { denialTracking: autoModeDenialTracking } : {}) } } : {}),
+                        onHeadlessDenialLimit: stopForDenialLimit,
+                        ...(permissionRuleLane
+                            ? {
+                                persistedRules: {
+                                    admits: permissionRuleLane.admits,
+                                    onResolved: (info) => emitTrace(deps.tracer, () => ({
+                                        kind: "permission.persisted_rule_allowed",
+                                        version: 2,
+                                        taskId: hostTaskId,
+                                        toolName: info.toolName,
+                                        toolCallId: info.toolCallId,
+                                        rules: [...info.rules],
+                                        ts: Date.now(),
+                                    })),
+                                },
+                            }
+                            : {}),
+                        ...(permissionRuleOrgLane
+                            ? {
+                                orgRules: {
+                                    adjudicate: permissionRuleOrgLane.adjudicate,
+                                    contentAskToolMounted: questionToolMounted,
+                                    onUnavailable: (info) => emitTrace(deps.tracer, () => ({
+                                        kind: "permission.org_snapshot_unavailable",
+                                        version: 1,
+                                        taskId: hostTaskId,
+                                        toolName: info.toolName,
+                                        toolCallId: info.toolCallId,
+                                        message: info.message,
+                                        ts: Date.now(),
+                                    })),
+                                },
+                            }
+                            : {}),
+                        isMarkedUnresolvable: (toolCallId) => inheritedUnavailableAsks.has(toolCallId),
+                        ...(sandboxAdmissionArmed
+                            ? {
+                                sandboxAdmission: {
+                                    askClassesOf: (toolCallId) => foldAskClasses.get(toolCallId),
+                                    boundaryCapable: sandboxBoundaryCapable(e.toolName),
+                                    onAdmitted: emitSandboxAdmitted,
+                                },
+                            }
+                            : {}),
+                    });
+                }
+                finally {
+                    inheritedUnavailableAsks.delete(e.toolCallId);
+                    inheritedAskGrants.delete(e.toolCallId);
+                    foldAskClasses.delete(e.toolCallId);
+                }
+                const ancestorAdmitted = ancestorSandboxAdmissions.get(e.toolCallId);
+                ancestorSandboxAdmissions.delete(e.toolCallId);
+                if (ancestorAdmitted !== undefined && !result.block && !result.suspend) {
+                    emitSandboxAdmitted({ toolCallId: e.toolCallId, toolName: e.toolName, askClasses: ancestorAdmitted, boundary: "sandbox_internal" });
+                    result.preToolContext.push(`permission.sandbox_admitted: this call's inherited pending approval was auto-admitted because the deployment declares an isolated sandbox execution env and the request stays inside it. Recorded for audit.`);
+                }
+                if (!result.block && !result.suspend && result.preToolContext.length > 0) {
+                    preToolContexts.set(e.toolCallId, result.preToolContext);
+                }
+                if (blockedTracked && (result.block || result.suspend)) {
+                    blockedToolCalls.add(e.toolCallId);
+                }
+                const screened = screenGateResult(result);
+                for (const defect of screened.defects)
+                    deps.onError?.(new Error(defect), { phase: "config", sessionId });
+                if (screened.gate !== undefined)
+                    gateOutcomes.set(e.toolCallId, screened.gate);
+                if (result.block) {
+                    const haltRemaining = maybeHumanRejectionHalt({
+                        gate: screened.gate,
+                        isDelegatedChild: delegation.isDelegatedChild === true,
+                        toolName: e.toolName,
+                        toolCallId: e.toolCallId,
+                    });
+                    if (haltRemaining !== undefined) {
+                        batchHaltRef.current = { rejectedToolCallId: e.toolCallId };
+                        return { block: true, reason: result.reason, haltRemaining };
+                    }
+                    return { block: true, reason: result.reason };
+                }
+                return result.updatedInput !== undefined ? { updatedInput: result.updatedInput } : undefined;
+            });
+        }
+    }
+    const toolResultStationArmed = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure);
+    if (toolResultStationArmed) {
+        harness.on("tool_result", async (e) => {
+            if (blockedToolCalls.delete(e.toolCallId)) {
+                return undefined;
+            }
+            let content = e.content;
+            let changed = false;
+            if (e.isError) {
+                if (hooks?.postToolUseFailure) {
+                    let clonedDetails = e.details;
+                    try {
+                        clonedDetails = structuredClone(e.details);
+                    }
+                    catch {
+                    }
+                    const failureSeat = await runHookSeat("postToolUseFailure", { timeoutMs: hookTimeoutMs, signal: abortController.signal }, (sig) => hooks.postToolUseFailure(e.toolName, e.input, {
+                        error: e.content
+                            .filter((c) => c.type === "text")
+                            .map((c) => c.text)
+                            .join("\n"),
+                        isInterrupt: abortController.signal.aborted || spec.signal?.aborted === true,
+                        content: e.content.map((c) => ({ ...c })),
+                        details: clonedDetails,
+                    }, { toolCallId: e.toolCallId, toolName: e.toolName, signal: sig, ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}), ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}), identity: hookIdentity }));
+                    if (failureSeat.expired) {
+                        notifyOwnHookCrash(hookSeatExpiredError("postToolUseFailure", hookTimeoutMs, failureSeat.cause, "the observation was abandoned and its additionalContext dropped; the failure result itself is unchanged"));
+                    }
+                    const patch = failureSeat.expired ? undefined : failureSeat.value;
+                    if (patch?.additionalContext) {
+                        content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext, reminderMark) }];
+                        changed = true;
+                    }
+                }
+            }
+            else if (hooks?.postToolUse) {
+                const successSeat = await runHookSeat("postToolUse", { timeoutMs: hookTimeoutMs, signal: abortController.signal }, (sig) => hooks.postToolUse(e.toolName, e.input, { content: e.content, details: e.details, isError: e.isError }, { toolCallId: e.toolCallId, toolName: e.toolName, signal: sig, ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}), ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}), identity: hookIdentity }));
+                if (successSeat.expired) {
+                    notifyOwnHookCrash(hookSeatExpiredError("postToolUse", hookTimeoutMs, successSeat.cause, "the seat was abandoned; the tool result is delivered to the model UNMODIFIED (no updatedOutput, no additionalContext)"));
+                }
+                const patch = successSeat.expired ? undefined : successSeat.value;
+                if (patch?.updatedOutput) {
+                    content = patch.updatedOutput;
+                    changed = true;
+                }
+                if (patch?.additionalContext) {
+                    content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext, reminderMark) }];
+                    changed = true;
+                }
+            }
+            const pre = preToolContexts.get(e.toolCallId);
+            if (pre) {
+                preToolContexts.delete(e.toolCallId);
+                content = [...content, ...pre.map((t) => ({ type: "text", text: formatHookFeedback(t, reminderMark) }))];
+                changed = true;
+            }
+            return changed ? { content } : undefined;
+        });
+    }
+    return { toolCallStationArmed: toolCallGateArmedRef.armed, toolResultStationArmed };
+}

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -160,9 +160,9 @@ export interface PrepareHandsReadFaceInput {
      *  when no file restore ran. Fail-closed by construction — dropping a read record only ever
      *  produces refusals. */
     restoredFilePaths?: readonly string[];
-    /** borrowed (ref cell; the REF itself is never replaced) — design/138 S2-C late-bound memory
+    /** borrowed-readonly — (ref cell; the REF itself is never replaced) design/138 S2-C late-bound memory
      *  write gate: the band's beforeWrite closure reads `.current` call-time; prepareMemory (driver,
-     *  after this phase) installs the gate. Declared in the driver because the SAME ref feeds
+     *  after this phase) installs the gate — the one writer; this phase only reads. Declared in the driver because the SAME ref feeds
      *  prepareMemory. */
     memoryWriteGateRef: {
         current?: BeforeWriteHook;
@@ -199,10 +199,10 @@ export interface PrepareHandsReadFaceInput {
      *  band's Read/notebook/PDF trailer outlets bump keys on it at tool-execute time (the driver owns
      *  the object and folds it into result stats). */
     reminderDisclosureCounts: import("../reminder-disclosure.js").ReminderDisclosureCounts;
-    /** design/381 — the first-touch history hook prepare built (present iff a fileHistoryStore is
+    /** borrowed-readonly — design/381: the first-touch history hook prepare built (present iff a fileHistoryStore is
      *  wired and the run mounts a real fs env); threaded to the write band's trackFileEdit seat. */
     trackFileEdit?: import("../types.js").TrackFileEditHook;
-    /** borrowed — the mutation lane's LANDED observation seat (the accumulator behind
+    /** borrowed-readonly — the mutation lane's LANDED observation seat (the accumulator behind
      *  `TaskResult.editedFiles`); threaded to the write band's onFileEdited seat. Unlike
      *  `trackFileEdit` it does NOT depend on a wired history store: it observes what this run's hands
      *  did, so it is present on every run that mounts the band. */

package/dist/core/runner/prepare-inherited-gate.d.ts

@@ -238,13 +238,13 @@ export interface PrepareInheritedGateResult {
     notifyOwnHookCrash: (err: unknown) => void;
     /** owned — the FROZEN question seat (spec over deps), the content-ask twin of `frozenOnAsk`. */
     frozenOnQuestion: OnQuestion | undefined;
-    /** borrowed-mutable — the delegation runtime-provenance arming face. Writers: the memory phase's content-origin wrap section,
-     *  once per leg when armed. Read lazily by delegation tools through the ctx. */
+    /** borrowed-mutable — the delegation runtime-provenance arming face. Writer: the memory-engine-session phase
+     *  (prepareMemoryEngineSession), once per leg when it arms. Read lazily by delegation tools through the ctx. */
     provenanceForChildrenRef: {
         current?: DelegationContentSafety;
     };
-    /** borrowed-mutable — the delegation-settlement coordinates. Writers: the memory phase, once per leg when a session exists.
-     *  Read lazily by delegation tools through the ctx. */
+    /** borrowed-mutable — the delegation-settlement coordinates. Writer: the memory-engine-session phase, once per leg when the
+     *  mounted session carries a settlement seat. Read lazily by delegation tools through the ctx. */
     delegationSettlementRef: {
         current?: {
             controlDir: string;

package/dist/core/runner/prepare-inherited-gate.js

@@ -221,7 +221,7 @@ export function prepareInheritedGate(input) {
             delegationSettlement: delegationSettlementForChildren,
             ...(autoModeDecider ? { autoModeReview: { decider: autoModeDecider } } : {}),
             ...(spec.durableApproval !== undefined ? { durableApprovalForChildren: { ...spec.durableApproval } } : {}),
-            ...(spec.checkpointStore === null ? { checkpointStoreDisabledForChildren: true } : {}),
+            ...(spec.checkpointStore === "disabled" ? { checkpointStoreDisabledForChildren: true } : {}),
             taskId: hostTaskId,
             ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
             ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),

package/dist/core/runner/prepare-memory-engine-session.d.ts

@@ -0,0 +1,84 @@
+/**
+ * design/390 §1.2 M12 — prepareTask's MEMORY-ENGINE-SESSION phase, verbatim from the driver: the content-origin
+ * classification + one-way session pollution wrap section (design/178 §3 / design/180 half A / design/324 /
+ * design/336 §3.3 + §5.5 / design/378 D-4 / design/380 O9a). Its arming predicate (a mounted memory session OR an
+ * upstream recorder channel), the chain-narrowed classification config, the children's provenance seat, the
+ * declared-MCP-class announcement, the settlement seat, the per-tool wrap with its three record verbs (mark /
+ * recordExternal / recordIncomplete), the Read tool's recall-taint arm and the delegation arm's three-valued
+ * attestation judgment all live here; the announcement helper only this section called moved with it. The
+ * interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the awaits sit inside the wrappers it
+ * installs, which run at tool-call time), so the phase adds no yield between the deferred classification before it
+ * and the prompt assembly after it (design/390 §1.5: a stretch with no await is extracted as a sync function).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * One read changed spelling and nothing else: the declared-class announcement read `mcp?.statuses` while `mcp` had
+ * long been the protocol-tools phase's non-null handle; the optional chain was dead and is now the plain member read.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { MaterializedMcp } from "../mcp.js";
+import { type DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared, RunInternals } from "./contracts.js";
+export interface PrepareMemoryEngineSessionInput {
+    /** borrowed-readonly — the mounted engine session, or undefined (the ARMING fact's first half). Read: `pollution`
+     *  (the mark face), `contentSafety` (the own half of the narrowing), `settlement` (the seat + the receipt ledger),
+     *  `recallTaint` (the Read arm's judge). Never mutated; the wrappers call `pollution.markPolluted` at tool-call time. */
+    memoryEngineSession: Prepared["memoryEngineSession"];
+    /** borrowed-mutable — the trusted spawn-side channel; only `delegationProvenance` (the ARMING fact's second half: the
+     *  recorder channel with the chain's frozen `contentSafety`). Writers: the wrappers this phase installs set
+     *  `delegationProvenance.ref.current.sawExternal` / `.incomplete` at tool-call time (monotonic, never cleared). */
+    internals: Pick<RunInternals, "delegationProvenance"> | undefined;
+    /** borrowed-readonly — the doors' per-leg SNAPSHOT of `RunnerDeps.memoryDelegationEvidence` (screened in the
+     *  synchronous pre-await stretch; never a live deps re-read here). */
+    memoryDelegationEvidence: "static-face" | "attested-only";
+    /** borrowed-readonly — the run's external-content-target fold (live adapter declaration OR the persisted bit). */
+    externalContentTargetActive: boolean;
+    /** borrowed-readonly — the frozen preflight; only `mcp` (the declared entries the announcement walks). */
+    lockedPreflight: Pick<LockedPreflight, "mcp">;
+    /** borrowed-readonly — the materialized MCP handle; only `statuses` (the announcement's mounted-tool count). */
+    mcp: Pick<MaterializedMcp, "statuses">;
+    /** borrowed-readonly — the acquired session id (notice detail). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (notice detail; the once-per-leg claims are per-RUN claims). */
+    runId: string;
+    /** borrowed-readonly — the deployment seats; only `onNotice` (the declared-class line and the waiver notice). */
+    deps: Pick<RunnerDeps, "onNotice">;
+    /** borrowed-mutable — the children's provenance seat (the inherited-gate phase mints it; `inheritedGateForChildren`
+     *  reads it late). Writer: THIS phase, once at arming, to the effective (chain-narrowed) config. */
+    provenanceForChildrenRef: {
+        current?: DelegationContentSafety;
+    };
+    /** borrowed-mutable — the children's settlement seat (the inherited-gate phase mints it). Writer: THIS phase, once at
+     *  arming, when the memory session mounted a settlement (memoryProvenance "carry"). */
+    delegationSettlementRef: {
+        current?: {
+            controlDir: string;
+            sessionId: string;
+        };
+    };
+    /** borrowed-readonly — the REBOUND spec; only `tools` (the RAW caller specs: caller-tool names and the marker-bearing
+     *  delegation entries — the assembled roster objects carry neither marker). Never mutated. */
+    spec: Pick<TaskSpec, "tools">;
+    /** borrowed-readonly — the env-hand roster (membership minted at the mount sites); read by the classification. */
+    envHandToolNames: ReadonlySet<string>;
+    /** borrowed-mutable — the run's ONE tool roster. Writer here: the wrap pass REPLACES entries in place
+     *  (`tools[i] = wrapped`, identity-tracked so a re-run never stacks wrappers); see the roster's writer table on
+     *  {@link Prepared.tools}. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the re-runnable wrap pass's seat (the protocol-tools phase mints it; the rebuild seam re-runs it
+     *  after a refresh re-splice). Writer: THIS phase installs the pass and runs it once. */
+    contentOriginWrapRef: {
+        current?: () => void;
+    };
+}
+export interface PrepareMemoryEngineSessionResult {
+    /** owned — whether the section ARMED on this leg (a memory session or a recorder channel existed): armed ⇒ every
+     *  roster tool was classified and the polluting/delegation/Read-plane ones wrapped; not armed ⇒ zero wraps, zero
+     *  announcements, both children's seats untouched. */
+    armed: boolean;
+}
+/** The M12 phase body — prepareTask's content-origin wrap stretch, verbatim (see the module header). */
+export declare function prepareMemoryEngineSession(input: PrepareMemoryEngineSessionInput): PrepareMemoryEngineSessionResult;