@sema-agent/core 7.4.0 → 7.5.1

package/dist/core/runner/prepare-protocol-tools.d.ts

@@ -0,0 +1,91 @@
+import type { AgentTool } from "../../internal/harness.js";
+import { type MaterializedMcp, type McpDroppedTool } from "../mcp.js";
+import { type MaterializedA2a } from "../a2a.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
+import type { AnnounceOnceSink, IrreversibilityTier, Prepared, RollbackStack, ToolFaceSnapshot } from "./contracts.js";
+export interface PrepareProtocolToolsInput {
+    /** borrowed-readonly — the frozen preflight; only `mcp` (the declared server entries) is read: the
+     *  materialize input, the RefreshMcpTools mount predicate, and whether a real client was acquired. */
+    lockedPreflight: Pick<LockedPreflight, "mcp">;
+    /** borrowed-readonly — the REBOUND spec. Read: `principal` (the MCP header / the A2A identity), `tools`
+     *  (the caller names both reserved-name guards check against), `a2a` (the peer entries). Never mutated. */
+    spec: Pick<TaskSpec, "principal" | "tools" | "a2a">;
+    /** borrowed-readonly — the deployment seats the materializers and their operator faces read: `onElicit`
+     *  and `mcpImageResizer` ride into the MCP intake; `onError` takes the A2A warnings (no ledger — a peer is
+     *  re-read every prepare); `mcpRevocations` + `onNotice` make the revocation wiring. */
+    deps: Pick<RunnerDeps, "onElicit" | "mcpImageResizer" | "onError" | "mcpRevocations" | "onNotice">;
+    /** borrowed-readonly — the leg's reminder mark (the MCP intake's disclosure bounding reads it). */
+    reminderMark: string;
+    /** borrowed-mutable — the reminder-disclosure counters: the MCP intake's bounding writes them here, and
+     *  the run loop's attachment lanes keep writing the same object (`Prepared.reminderDisclosureCounts`). */
+    reminderDisclosureCounts: Prepared["reminderDisclosureCounts"];
+    /** borrowed-readonly — the run's invocation id (the revocation probe-failure notice names it). */
+    runId: string;
+    /** borrowed-readonly — the acquired session id (operator-line context). */
+    sessionId: string;
+    /** borrowed-mutable — the once-per-session ledger: its deduplicated operator sink (`onError`, one line per
+     *  (code, message) per session) and the announce-lane prune of tools already delivered on this branch.
+     *  The ledger module owns the record; this phase writes through those two methods and nothing else. */
+    onceLedger: AnnounceOnceSink & {
+        pruneDroppedTools(dropped: McpDroppedTool[]): void;
+    };
+    /** borrowed-mutable — the run's shared roster (identity is the contract: `Prepared.tools`, the wire order).
+     *  Writers here: three pushes (the MCP tools through the wrapper, RefreshMcpTools, the A2A tools through the
+     *  wrapper) and, at RUN time, the refresh closure's splice within a server's name-prefix domain. Later
+     *  phases push their own mounts; the roster's full writer table is the delegation-surface phase's. */
+    tools: AgentTool[];
+    /** borrowed-readonly — the large-result wrapper for protocol tools (per-tool `_meta` bar, 50K default). */
+    remoteToolOffload: (tool: AgentTool) => AgentTool;
+    /** borrowed-readonly — the frozen tool face; `exclude` is read at REFRESH time so a deployment-excluded
+     *  tool is never re-mounted by a model-triggered refresh. */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude">;
+    /** borrowed-mutable — the effect table the fold writes under a has-guard (`?? "write"` default) and the
+     *  refresh closure resets per prefix domain before re-folding; RefreshMcpTools registers itself `read`. */
+    toolEffects: Map<string, ToolEffect>;
+    /** borrowed-mutable — the explicit-negative axes (a caller's vouched `never` / `egress:false`); written by
+     *  the fold and reset per prefix domain by the refresh closure. */
+    axisExplicitNegatives: Map<string, {
+        irreversible?: false;
+        egress?: false;
+    }>;
+    /** borrowed-mutable — the irreversibility tier, tightened to `always` by the fold (monotone). */
+    irreversibilityTier: IrreversibilityTier;
+    /** borrowed-mutable — the irreversible set, added to by the fold (tighten-only). */
+    irreversibleTools: Set<string>;
+    /** borrowed-mutable — the egress set, added to by the fold (tighten-only; the effect:"write" invariant). */
+    egressTools: Set<string>;
+    /** borrowed-readonly — the run's abort controller; its `signal` rides into the A2A materialization. */
+    abortController: Pick<AbortController, "signal">;
+    /** borrowed-mutable — the driver-owned prepare-failure stack; this phase pushes one entry per REAL handle
+     *  acquired (the MCP clients, then the A2A peers) and nothing else touches it here. */
+    rollback: RollbackStack;
+}
+export interface PrepareProtocolToolsResult {
+    /** owned — the materialized MCP handle (`Prepared.mcp`): clients, axes, server instructions, statuses, the
+     *  refresh and the `dispose` the Runner's finish calls. Its prepare-failure release is the rollback entry
+     *  this phase pushed (only when a real client was acquired — the inert stub owns nothing). */
+    mcp: MaterializedMcp;
+    /** owned — the materialized A2A handle: the driver projects it onto `Prepared.a2a` only when it carries
+     *  tools. Same rollback posture as `mcp`, pushed after it (disposed before it on unwind). */
+    a2a: MaterializedA2a;
+    /** borrowed-mutable — the RefreshMcpTools rebuild seam (`current` undefined until installed). Writers: the
+     *  tool-disclosure mount, by exactly one of its two mutually exclusive arms (the deferred arm's
+     *  rematerialize; the else-arm's bare setTools + fingerprint sync). Read by the refresh closure at run time. */
+    rebuildHarnessToolsRef: {
+        current?: () => Promise<void>;
+    };
+    /** borrowed-mutable — the content-origin re-classification seat. Writer: the content-origin wrap section
+     *  (installs the re-runnable pass ONCE, when an engine-memory session mounted; undefined otherwise). Read by
+     *  the rebuild closures before a swapped-in tool becomes callable. */
+    contentOriginWrapRef: {
+        current?: () => void;
+    };
+    /** borrowed-mutable — whether the tool_call gate handler was REGISTERED at prepare time. Writer: the driver,
+     *  once, at gate registration. Read by the refresh closure's honesty warning. */
+    toolCallGateArmedRef: {
+        armed: boolean;
+    };
+}
+/** The M5 phase body — prepareTask's protocol-tools stretch, verbatim (see the module header). */
+export declare function prepareProtocolTools(input: PrepareProtocolToolsInput): Promise<PrepareProtocolToolsResult>;

package/dist/core/runner/prepare-protocol-tools.js

@@ -0,0 +1,182 @@
+import { Type } from "typebox";
+import { materializeMcpTools } from "../mcp.js";
+import { materializeA2aTools } from "../a2a.js";
+import { deliverEngineNotice } from "../types.js";
+export async function prepareProtocolTools(input) {
+    const { lockedPreflight, spec, deps, reminderMark, reminderDisclosureCounts, runId, sessionId, onceLedger, tools, remoteToolOffload, toolFaceSnapshot, toolEffects, axisExplicitNegatives, irreversibilityTier, irreversibleTools, egressTools, abortController, rollback } = input;
+    const mcp = lockedPreflight.mcp?.length
+        ? await materializeMcpTools(lockedPreflight.mcp, spec.principal, deps.onElicit, deps.mcpImageResizer, { reminderMark, counts: reminderDisclosureCounts }, mcpRevocationWiring(deps, runId))
+        : { tools: [], toolAxes: [], warnings: [], serverInstructions: [], instructionsDelta: { pendingAdds: [], pendingRemovals: [] }, droppedTools: [], statuses: [], refresh: async () => [], dispose: async () => { } };
+    if (lockedPreflight.mcp?.length)
+        rollback.push(function mcpDispose() { return mcp.dispose(); });
+    for (const w of mcp.warnings)
+        onceLedger.onError(w, { phase: "mcp", sessionId });
+    for (const d of mcp.droppedTools) {
+        onceLedger.onError(new Error(`MCP tool dropped at intake — ${d.tool} (server "${d.server}"): ${d.reason}`), { phase: "mcp", sessionId });
+    }
+    onceLedger.pruneDroppedTools(mcp.droppedTools);
+    {
+        const callerNames = new Set((spec.tools ?? []).flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+        const clash = mcp.tools.find((t) => [t.name, ...(t.aliases ?? [])].some((name) => callerNames.has(name)));
+        if (clash) {
+            await mcp.dispose();
+            const e = new Error(`Tool name "${clash.name}" is reserved by an injected MCP tool — a caller tool of the same name would silently shadow it.`);
+            e.code = "config.reserved_tool_name";
+            throw e;
+        }
+    }
+    tools.push(...mcp.tools.map((t) => remoteToolOffload(t)));
+    const rebuildHarnessToolsRef = {};
+    const contentOriginWrapRef = {};
+    const toolCallGateArmedRef = { armed: false };
+    if (lockedPreflight.mcp?.length) {
+        tools.push({
+            name: "RefreshMcpTools",
+            label: "RefreshMcpTools",
+            description: "Refresh the tool list of connected MCP servers. Never dials or re-dials connections — it only re-reads the tool list over the existing connection. The refreshed tools are available immediately; you can call them on your next step. Use when a server's expected tool is missing, or the tool list looks stale after a connection recovered. Omit `server` to refresh every connected server.",
+            parameters: Type.Object({
+                server: Type.Optional(Type.String({ description: "Name of a single MCP server to refresh; omit to refresh all connected servers." })),
+            }),
+            execute: async (_toolCallId, params) => {
+                const serverArg = params?.server;
+                const results = await mcp.refresh(typeof serverArg === "string" && serverArg.length > 0 ? serverArg : undefined);
+                const lines = [];
+                let changed = false;
+                let anyActiveFailure = false;
+                for (const r of results) {
+                    if (r.status !== "refreshed" || r.tools === undefined) {
+                        lines.push(`${r.server}: ${r.status}${r.error !== undefined ? ` (${r.error})` : ""}`);
+                        if (r.status === "failed")
+                            anyActiveFailure = true;
+                        continue;
+                    }
+                    const excludedSet = new Set(toolFaceSnapshot.exclude ?? []);
+                    const pushable = r.tools.filter((t) => !excludedSet.has(t.name));
+                    const excludedNow = r.tools.filter((t) => excludedSet.has(t.name)).map((t) => t.name);
+                    const domainSnapshot = (m) => new Map([...m].filter(([name]) => name.startsWith(r.prefix)));
+                    const restoreDomain = (m, snap) => {
+                        for (const name of [...m.keys()])
+                            if (name.startsWith(r.prefix))
+                                m.delete(name);
+                        for (const [name, v] of snap)
+                            m.set(name, v);
+                    };
+                    const priorDomainEffects = domainSnapshot(toolEffects);
+                    const priorDomainNegatives = domainSnapshot(axisExplicitNegatives);
+                    for (const name of priorDomainEffects.keys())
+                        toolEffects.delete(name);
+                    for (const name of priorDomainNegatives.keys())
+                        axisExplicitNegatives.delete(name);
+                    try {
+                        foldProtocolAxes((r.axes ?? []).filter((a) => !excludedSet.has(a.name)), "MCP");
+                    }
+                    catch (foldErr) {
+                        restoreDomain(toolEffects, priorDomainEffects);
+                        restoreDomain(axisExplicitNegatives, priorDomainNegatives);
+                        lines.push(`${r.server}: failed (${foldErr instanceof Error ? foldErr.message : String(foldErr)})`);
+                        anyActiveFailure = true;
+                        continue;
+                    }
+                    let domainAnchor = -1;
+                    for (let i = tools.length - 1; i >= 0; i--) {
+                        const t = tools[i];
+                        if (t.name.startsWith(r.prefix)) {
+                            domainAnchor = i;
+                            tools.splice(i, 1);
+                        }
+                    }
+                    const refreshedMounts = pushable.map((t) => remoteToolOffload(t));
+                    if (domainAnchor >= 0)
+                        tools.splice(domainAnchor, 0, ...refreshedMounts);
+                    else
+                        tools.push(...refreshedMounts);
+                    changed = true;
+                    const detail = [];
+                    const shownAdded = r.added.filter((n) => !excludedSet.has(n));
+                    if (shownAdded.length > 0)
+                        detail.push(`added: ${shownAdded.join(", ")}`);
+                    if (r.removed.length > 0)
+                        detail.push(`removed: ${r.removed.join(", ")}`);
+                    if (excludedNow.length > 0)
+                        detail.push(`excluded by deployment config (not mounted): ${excludedNow.join(", ")}`);
+                    if ((r.dropped?.length ?? 0) > 0)
+                        detail.push(`dropped: ${r.dropped.map((d) => `${d.tool} (${d.reason.length > 90 ? `${d.reason.slice(0, 90)}…` : d.reason})`).join("; ")}`);
+                    lines.push(`${r.server}: refreshed — ${pushable.length} tool${pushable.length === 1 ? "" : "s"}${detail.length > 0 ? ` (${detail.join("; ")})` : ""}`);
+                }
+                if (changed)
+                    await rebuildHarnessToolsRef.current?.();
+                if (changed && !toolCallGateArmedRef.armed && (irreversibleTools.size > 0 || egressTools.size > 0)) {
+                    lines.push("WARNING: refreshed tools declare irreversible/egress safety hints, but this task started with no approval gate registered (no policy/hooks and no gated tools at start) — these hints cannot arm a gate mid-task (RB-46); the refreshed tools run ungated on this deployment shape.");
+                }
+                const text = lines.length === 0 ? "No connected MCP servers to refresh." : lines.join("\n");
+                return {
+                    content: [{ type: "text", text }],
+                    details: { results },
+                    terminate: false,
+                    ...(anyActiveFailure && !changed ? { isError: true } : {}),
+                };
+            },
+        });
+        toolEffects.set("RefreshMcpTools", "read");
+    }
+    const foldProtocolAxes = (axes, protocolLabel) => {
+        for (const axis of axes) {
+            if (axis.irreversibility === "always") {
+                irreversibilityTier.set(axis.name, "always");
+                irreversibleTools.add(axis.name);
+            }
+            if (axis.irreversibility === "never") {
+                axisExplicitNegatives.set(axis.name, { ...axisExplicitNegatives.get(axis.name), irreversible: false });
+            }
+            if (axis.egress === false) {
+                axisExplicitNegatives.set(axis.name, { ...axisExplicitNegatives.get(axis.name), egress: false });
+            }
+            if (axis.egress) {
+                if (axis.effect !== undefined && axis.effect !== "write") {
+                    const e = new Error(`${protocolLabel} tool "${axis.name}" resolves to egress:true with effect:"${axis.effect}" — an egress tool (external write) must have effect:"write". Clear egress (toolAxes egress:false) if it is a pure read, or set effect:"write".`);
+                    e.code = "config.egress_requires_write_effect";
+                    throw e;
+                }
+                egressTools.add(axis.name);
+            }
+            if (!toolEffects.has(axis.name))
+                toolEffects.set(axis.name, axis.effect ?? "write");
+        }
+    };
+    foldProtocolAxes(mcp.toolAxes, "MCP");
+    const a2aDeclared = spec.a2a?.length ? spec.a2a : undefined;
+    const a2a = a2aDeclared
+        ? await materializeA2aTools(a2aDeclared, spec.principal, abortController.signal)
+        : { tools: [], toolAxes: [], warnings: [], statuses: [], refresh: async () => [], dispose: async () => { } };
+    if (a2aDeclared)
+        rollback.push(function a2aDispose() { return a2a.dispose(); });
+    for (const w of a2a.warnings)
+        deps.onError?.(w, { phase: "a2a", sessionId });
+    {
+        const callerNames = new Set((spec.tools ?? []).flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+        const clash = a2a.tools.find((t) => callerNames.has(t.name));
+        if (clash) {
+            await a2a.dispose();
+            await mcp.dispose();
+            const e = new Error(`Tool name "${clash.name}" is reserved by an injected A2A tool — a caller tool of the same name would silently shadow it.`);
+            e.code = "config.reserved_tool_name";
+            throw e;
+        }
+    }
+    tools.push(...a2a.tools.map((t) => remoteToolOffload(t)));
+    foldProtocolAxes(a2a.toolAxes, "A2A");
+    return { mcp, a2a, rebuildHarnessToolsRef, contentOriginWrapRef, toolCallGateArmedRef };
+}
+function mcpRevocationWiring(deps, runId) {
+    if (deps.mcpRevocations === undefined)
+        return undefined;
+    const ledger = deps.mcpRevocations;
+    return {
+        isRevoked: (name) => ledger.isRevoked(name),
+        onProbeFailure: (e) => deliverEngineNotice(deps.onNotice, {
+            code: "mcp.revocation_probe_failed",
+            message: `the mcpRevocations.isRevoked probe threw — MCP dispatch fails OPEN (no server treated as revoked) until the probe recovers: ${e instanceof Error ? e.message : String(e)}`,
+            detail: { message: e instanceof Error ? e.message : String(e), runId },
+        }),
+    };
+}

package/dist/core/runner/prepare-question-face.d.ts

@@ -0,0 +1,119 @@
+/**
+ * design/390 §1.2 M7 — prepareTask's QUESTION-FACE phase, verbatim from the driver: the leg's ONE checkpoint-store
+ * read, the durable mandate as it binds at the question seat, the content-ask binding table (with the leak
+ * bound the routing lane checks against — the constant below), the stranded-answer disclosure and the leg-end
+ * settle, the three-way mount decision (live face / durable face / override), and the AskUserQuestion mount
+ * with its redeemed-approval, posture, fallback and synthetic-continuation arms. The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * offload-reader mount before it and the scheduler mount after it (design/390 §1.5 S1: a stretch with no await
+ * is extracted as a sync function — an `async` wrapper would open a microtask window). Read-stability of the
+ * host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * One seat is a LIVE GETTER (design/238 D-3): the inherited-unavailable marker set is declared by the driver's
+ * gate-fold section AFTER this phase and read per call at RUN time, so it enters as `() => ReadonlySet` — a
+ * read before the driver declares it throws (temporal dead zone), which is the fail-loud an uninitialized
+ * live read owes.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import { type OnQuestion, type QuestionAnswer } from "../ask-question.js";
+import { type CheckpointStore } from "../checkpoint-store.js";
+import type { RunnerDeps, RuntimeCaps, TaskSpec } from "../types.js";
+import type { PrepareResume } from "./contracts.js";
+export declare const CONTENT_ASK_BINDING_CAP = 32;
+/** One gate-routed content-ask outcome, keyed by the call id it was produced for (see the table's own note). */
+export type ContentAskBinding = ({
+    kind: "answered";
+    answer: QuestionAnswer;
+} | {
+    kind: "failed";
+    error: unknown;
+}) & {
+    /** Digest of the exact question batch this outcome belongs to. The call id alone is not enough
+     *  to redeem a binding: it comes from the model/provider and can repeat, so an entry that
+     *  outlived its call (its call was allowed but never executed) could otherwise be handed to a
+     *  LATER call that happens to reuse the id. Matching on the batch as well means an outcome can
+     *  only ever be delivered for the question it was produced for. */
+    questionsHash: string;
+    /** The engine-minted per-delivery identity (see AskQuestionRequest.deliveryId) — carried so a
+     *  stranded-answer disclosure names DELIVERIES, not call ids: call ids can repeat, and a
+     *  disclosure keyed on them would collapse two lost answers into one. */
+    deliveryId: string;
+};
+export interface PrepareQuestionFaceInput {
+    /** borrowed-readonly — the run's frozen question seat (spec > deps), resolved once at the top of prepare;
+     *  the mount predicate and the live-face derivation both read this one value. */
+    frozenOnQuestion: OnQuestion | undefined;
+    /** borrowed-readonly — the REBOUND spec. Read: `checkpointStore` (the per-run off switch), `durableApproval`
+     *  (the durable face's opt-in), `interactiveTools` (the override), `principal` (the tool's source identity),
+     *  `interactiveQuestionFallback` (restores the continuation under a resolved posture). Never mutated. */
+    spec: Pick<TaskSpec, "checkpointStore" | "durableApproval" | "interactiveTools" | "principal" | "interactiveQuestionFallback">;
+    /** borrowed-readonly — the deployment seats: `checkpointStore` (the store the leg snapshot resolves against)
+     *  and `onError` (the stranded-answer and synthetic-continuation operator lines; swallow-guarded). */
+    deps: Pick<RunnerDeps, "checkpointStore" | "onError">;
+    /** borrowed-readonly — the principal's resolved runtime caps as of this point (`forceDurableGate` is the
+     *  mandate that outranks a live face only where a store exists to park the question). */
+    runtimeCaps: Pick<RuntimeCaps, "forceDurableGate"> | undefined;
+    /** borrowed-readonly — the resolved interaction posture (the door's value), threaded to the tool so both
+     *  no-answer arms harden under it. */
+    resolvedInteractionPosture: "interactive" | "headless" | undefined;
+    /** borrowed-readonly — the durable-resume carrier; only the redeemed content-ask call id and its questions
+     *  hash are read (the one call an operator's approval was spent on). */
+    resume: Pick<PrepareResume, "redeemedContentAskCallId" | "redeemedContentAskQuestionsHash"> | undefined;
+    /** borrowed-readonly — the acquired session id (the tool's source task id; operator-line context). */
+    sessionId: string;
+    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the question
+     *  tool) when the mount predicate holds; `contentAskRoutable` reads `includes` per call against the LIVE
+     *  array (the roster is edited in place after the mount). */
+    tools: AgentTool[];
+    /** borrowed-readonly — LIVE GETTER over the inherited-unavailable marker set (declared by the driver's
+     *  gate-fold section after this phase; `has` only, per call at run time). See the module header. */
+    inheritedUnavailableAsks: () => ReadonlySet<string>;
+}
+export interface PrepareQuestionFaceResult {
+    /** borrowed-readonly — THE leg's store snapshot (`resolveCheckpointStore(spec, deps)`): the mount face, the
+     *  routability predicate, the manifest and suspendAsk all read this one value. */
+    checkpointStore: CheckpointStore | undefined;
+    /** borrowed-readonly — the run's live question face through the shared predicate (the reserved resume
+     *  placeholder is a function and is NOT a live face), or undefined. */
+    liveQuestionFace: OnQuestion | undefined;
+    /** borrowed-mutable — the one-shot answer binding table for questions the GATE routed (scope = this leg).
+     *  Writers (R-3): the routing lane (`set`, cap-checked against {@link CONTENT_ASK_BINDING_CAP} before every
+     *  insertion), the mounted face here (`delete`, one-shot redemption or a mismatched-batch drop), the settle
+     *  here (`clear`). Identity is the contract (the routing lane and the face share this exact map). */
+    contentAskBindings: Map<string, ContentAskBinding>;
+    /** owned — THE routability predicate for a content ask (per call, against the live roster and the marker set). */
+    contentAskRoutable: (toolCallId: string) => boolean;
+    /** borrowed-mutable — late answers noted before the leg settles. Writer: the routing lane's delivery-race
+     *  watcher (`push`); reader: the settle here (merged into the result disclosure by delivery id). */
+    lateStrandedAnswers: Array<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+    /** owned — THE disclosure lane for an answer a person gave that no call could collect (swallow-guarded). */
+    discloseStrandedAnswers: (records: ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>, why: string) => void;
+    /** owned — the leg-end settle (`Prepared.settleContentAskBindings`): discloses surviving answers, clears the
+     *  table, returns the records the result carries. */
+    settleContentAskBindings: () => ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+    /** owned — whether a durable delivery face exists (store wired ∧ (durableApproval ∨ forceDurableGate));
+     *  the manifest's composition-lie detector reuses this exact value. */
+    durableQuestionFace: boolean;
+    /** owned — the face the tool was mounted with: the gate-bound answer for THIS call id if one exists (one-shot),
+     *  else the live face itself; the raw frozen seat when no live face exists. */
+    mountedQuestionFace: OnQuestion | undefined;
+    /** owned — whether THIS prepare mounted the first-party question tool (the routing lane keys on it, not on
+     *  the reserved name). */
+    questionToolMounted: boolean;
+    /** borrowed-readonly — the mounted tool object itself (the exact roster member), so the routing lane can
+     *  validate a batch against the schema the executing call is re-checked against; undefined when not mounted. */
+    mountedQuestionTool: AgentTool | undefined;
+}
+/** The M7 phase body — prepareTask's question-face stretch, verbatim (see the module header). */
+export declare function prepareQuestionFace(input: PrepareQuestionFaceInput): PrepareQuestionFaceResult;

package/dist/core/runner/prepare-question-face.js

@@ -0,0 +1,83 @@
+import { createAskUserQuestionTool, isLiveQuestionFace } from "../ask-question.js";
+import { boundInputHashOf } from "../canonical-json.js";
+import { resolveCheckpointStore } from "../checkpoint-store.js";
+export const CONTENT_ASK_BINDING_CAP = 32;
+export function prepareQuestionFace(input) {
+    const { frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, tools, inheritedUnavailableAsks } = input;
+    const onQuestion = frozenOnQuestion;
+    const liveQuestionFace = isLiveQuestionFace(onQuestion) ? onQuestion : undefined;
+    const contentAskBindings = new Map();
+    const checkpointStore = resolveCheckpointStore(spec, deps);
+    const questionParkStoreWired = checkpointStore !== undefined;
+    const questionDurableMandateBinding = runtimeCaps?.forceDurableGate === true && questionParkStoreWired;
+    const contentAskRoutable = (toolCallId) => liveQuestionFace !== undefined &&
+        mountedQuestionTool !== undefined &&
+        tools.includes(mountedQuestionTool) &&
+        !questionDurableMandateBinding &&
+        !inheritedUnavailableAsks().has(toolCallId);
+    const lateStrandedAnswers = [];
+    const discloseStrandedAnswers = (records, why) => {
+        if (records.length === 0)
+            return;
+        try {
+            deps.onError?.(new Error(`AskUserQuestion: ${records.length} question(s) were answered by a person but the call never ` +
+                `executed to collect the answer (${records.map((r) => `${r.toolCallId} [delivery ${r.deliveryId}]`).join(", ")}) — ${why}. The answer(s) were NOT ` +
+                `delivered to the model and are gone with this leg; re-ask if the decision is still needed.`), { phase: "degraded", sessionId, classification: "unconsumed-human-answer" });
+        }
+        catch {
+        }
+    };
+    const settleContentAskBindings = () => {
+        const stranded = [];
+        for (const [callId, bound] of contentAskBindings) {
+            if (bound.kind === "answered")
+                stranded.push({ deliveryId: bound.deliveryId, toolCallId: callId });
+        }
+        contentAskBindings.clear();
+        discloseStrandedAnswers(stranded, "the leg ended first (abort, batch teardown, or a loop failure)");
+        const byDelivery = new Map();
+        for (const r of [...stranded, ...lateStrandedAnswers])
+            byDelivery.set(r.deliveryId, r);
+        return [...byDelivery.values()];
+    };
+    const durableQuestionFace = questionParkStoreWired && (spec.durableApproval !== undefined || runtimeCaps?.forceDurableGate === true);
+    const mountedQuestionFace = liveQuestionFace !== undefined
+        ? async (req, signal) => {
+            const bound = contentAskBindings.get(req.toolCallId);
+            if (bound !== undefined) {
+                if (bound.questionsHash === boundInputHashOf(req.questions)) {
+                    contentAskBindings.delete(req.toolCallId);
+                    if (bound.kind === "answered")
+                        return bound.answer;
+                    throw bound.error;
+                }
+                contentAskBindings.delete(req.toolCallId);
+            }
+            return liveQuestionFace(req, signal);
+        }
+        : onQuestion;
+    const questionToolMounted = spec.interactiveTools === true || (spec.interactiveTools !== false && (onQuestion !== undefined || durableQuestionFace));
+    let mountedQuestionTool;
+    if (questionToolMounted)
+        tools.push((mountedQuestionTool =
+            createAskUserQuestionTool(mountedQuestionFace, { principal: spec.principal, sourceTaskId: sessionId }, {
+                ...(resume?.redeemedContentAskCallId !== undefined
+                    ? {
+                        redeemedApprovalCallId: resume.redeemedContentAskCallId,
+                        ...(resume.redeemedContentAskQuestionsHash !== undefined ? { redeemedApprovalQuestionsHash: resume.redeemedContentAskQuestionsHash } : {}),
+                    }
+                    : {}),
+                ...(resolvedInteractionPosture !== undefined ? { posture: resolvedInteractionPosture } : {}),
+                ...(spec.interactiveQuestionFallback === true ? { interactiveFallback: true } : {}),
+                onSyntheticContinuation: ({ questionId, reason }) => {
+                    deps.onError?.(new Error(`AskUserQuestion ${questionId}: no human answer was obtainable (` +
+                        (reason === "seam_absent"
+                            ? "no onQuestion seam is wired"
+                            : reason === "declined_unavailable"
+                                ? "the wired question channel reported nobody was reachable"
+                                : "the wired question channel failed") +
+                        `) — the model was instructed to self-answer and the run CONTINUES (warning, not a failure).`), { phase: "degraded", sessionId, classification: "no-human-autoanswered" });
+                },
+            })));
+    return { checkpointStore, liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, mountedQuestionFace, questionToolMounted, mountedQuestionTool };
+}

package/dist/core/runner/prepare-run-refs.d.ts

@@ -0,0 +1,89 @@
+/**
+ * design/390 §1.2 M3a — prepareTask's RUN-REFS phase, verbatim from the driver: the run's own edited-files
+ * ledger, the harness ref, the per-task skill scope, the display-forwarding wrapper, the three run-local refs
+ * (review request / stop-after-turn / plan mode) with the ctx primitives that write them, the subagent-retain
+ * ledger and the worktree-isolation helper. Nothing here has behavior of its own: the phase MINTS SEATS —
+ * mutable cells and the closures bound to them — that later phases, the tool ctx and the run loop read and
+ * write. The interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * file-history phase before it and the inherited-gate fold after it (design/390 §1.5 S1: a stretch with no
+ * await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ *
+ * Every cell that leaves here as `borrowed-mutable` carries its writer table on the Result member (design/238
+ * R-3): the closures minted here, the driver's harness build, the project-context phase's inherited-skill
+ * seed, the skill tool, and the run loop's two writes — nothing else writes them. Read-stability of the host
+ * handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ */
+import type { AgentHarness, ExecutionEnv } from "../../internal/harness.js";
+import type { SubagentWorktreeIsolation } from "../../agents/subagent.js";
+import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import type { TaskEvent, TaskSpec } from "../types.js";
+import { ActiveSkillScope } from "./active-skill-scope.js";
+import type { Prepared, RunInternals } from "./contracts.js";
+import { type EditedFilesLedger } from "./edited-files-ledger.js";
+export interface PrepareRunRefsInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `forwardSubagentEvents` (widens the forwarding filter),
+     *  `retainSubagentSessions` (the ledger opt-in and its config), `handsReadOnly` (a read-only run mints no
+     *  worktree helper). Never mutated. */
+    spec: Pick<TaskSpec, "forwardSubagentEvents" | "retainSubagentSessions" | "handsReadOnly">;
+    /** borrowed-readonly — the trusted spawn-side channel; only `onForwardEvent` (the deployment's display
+     *  sink) is read, once, to decide whether a forwarding wrapper exists at all. */
+    internals: Pick<RunInternals, "onForwardEvent"> | undefined;
+    /** borrowed-readonly — the run's resolved env; the worktree helper closes over it (lazy: no I/O until a
+     *  delegation actually mints a worktree). */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the SETTLED task root (`taskRootFinal`): the worktree helper's base repo root. */
+    taskRootFinal: string;
+}
+export interface PrepareRunRefsResult {
+    /** owned — the ledger's writer (`FileEditedHook`): handed to the hands/read-face phase as its post-write
+     *  seat; nothing else calls it. */
+    noteFileEdited: EditedFilesLedger["note"];
+    /** owned — the ledger's LIVE read face (`Prepared.editedFilesSnapshot`, read at result assembly). */
+    editedFilesSnapshot: EditedFilesLedger["snapshot"];
+    /** borrowed-mutable — the harness seat: holds the harness once built, so a tool's execute can read the model
+     *  the parent is CURRENTLY on (design/38 1B: the `ToolExecuteContext.model` snapshot a delegation tool uses
+     *  for `inherit`), and breaks the harness↔tool_search build cycle (design/36 rematerialize). Writers (R-3):
+     *  the driver, ONCE, when the harness is built (`harnessRef.current = harness`) — before any run. Readers:
+     *  `requestStopAfterTurn` here (mirrors the stop onto the harness's one-way flag), the tool ctx's model
+     *  snapshot, the rebuild seam and the delegation mounts. Identity is the contract: every closure minted
+     *  before the harness exists reads this exact cell. */
+    harnessRef: {
+        current?: AgentHarness;
+    };
+    /** borrowed-mutable — the per-task LIFO skill scope. Writers: the project-context phase (the inherited-
+     *  from-parent seed frame, `push`) and the `skill` tool minted over it (`push` on a manifest load; a frame
+     *  closes by `pop`). Readers: the tool ctx's `activeSkillScope()` snapshot and the skill-scope policy layer. */
+    skillScope: ActiveSkillScope;
+    /** owned — the FILTERED display-forwarding wrapper, or undefined when the deployment wired no sink (the
+     *  tool ctx then carries no `forwardEvent` key). */
+    forwardEvent: ((e: TaskEvent) => void) | undefined;
+    /** borrowed-mutable — the review-request cell (`Prepared.reviewRequestRef`). Writers: `requestReview` here
+     *  (the first request wins) and the run loop's turn-boundary consumer, which clears `pending` once the
+     *  `plan_review` checkpoint is minted. */
+    reviewRequestRef: Prepared["reviewRequestRef"];
+    /** owned — the ctx primitive that arms `reviewRequestRef` (design/80 D-B). */
+    requestReview: (opts?: {
+        reason?: string;
+    }) => void;
+    /** borrowed-mutable — the stop-after-turn latch (`Prepared.stopRequestedRef`). Writers: `requestStopAfterTurn`
+     *  here, and nothing else; the run loop reads it at a turn boundary. */
+    stopRequestedRef: Prepared["stopRequestedRef"];
+    /** owned — the ctx primitive: flips the latch and mirrors it onto the harness's one-way flag. */
+    requestStopAfterTurn: () => void;
+    /** borrowed-mutable — the plan-mode flag (`Prepared.planModeRef`). Writers: `enterPlanMode` here, and the run
+     *  loop's resume ladder, which re-arms it when a REJECTED `plan_review` resumes into a re-plan. Read by the
+     *  tool-call gate (the write-effect refusal). */
+    planModeRef: Prepared["planModeRef"];
+    /** owned — the ctx primitive (mounted on the ctx only under `enablePlanMode`). */
+    enterPlanMode: () => void;
+    /** ownership-ref — the parent-run subagent-retain ledger, or undefined when the spec did not opt in. Its
+     *  lifecycle protocol belongs to the Runner (disposed in the task's terminal finally, design/122 D4); a
+     *  prepare that throws has nothing to release here — the ledger is empty until a delegation retains. */
+    subagentRetain: SubagentRetainLedger | undefined;
+    /** owned — the Agent tool's worktree-isolation helper (lazy; write-capable runs only), or undefined. */
+    worktreeIsolation: SubagentWorktreeIsolation | undefined;
+}
+/** The M3a phase body — prepareTask's run-refs stretch, verbatim (see the module header). */
+export declare function prepareRunRefs(input: PrepareRunRefsInput): PrepareRunRefsResult;

package/dist/core/runner/prepare-run-refs.js

@@ -0,0 +1,39 @@
+import { createSubagentWorktreeHelper } from "../../agents/subagent.js";
+import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import { ActiveSkillScope } from "./active-skill-scope.js";
+import { createEditedFilesLedger } from "./edited-files-ledger.js";
+export function prepareRunRefs(input) {
+    const { spec, internals, executionEnv, taskRootFinal } = input;
+    const { note: noteFileEdited, snapshot: editedFilesSnapshot } = createEditedFilesLedger();
+    const harnessRef = {};
+    const skillScope = new ActiveSkillScope();
+    const forwardSink = internals?.onForwardEvent;
+    const forwardEvent = forwardSink
+        ? (e) => {
+            if (e.type === "task_progress")
+                forwardSink(e);
+            else if (spec.forwardSubagentEvents === true &&
+                (e.type === "text_delta" || e.type === "text_end" || e.type === "reasoning_delta" || e.type === "tool_start" || e.type === "tool_end")) {
+                forwardSink(e);
+            }
+        }
+        : undefined;
+    const reviewRequestRef = {};
+    const requestReview = (opts) => {
+        if (reviewRequestRef.pending === undefined) {
+            reviewRequestRef.pending = opts?.reason !== undefined ? { reason: opts.reason } : {};
+        }
+    };
+    const stopRequestedRef = { current: false };
+    const requestStopAfterTurn = () => {
+        stopRequestedRef.current = true;
+        harnessRef.current?.requestStopAfterTurn();
+    };
+    const planModeRef = { active: false };
+    const enterPlanMode = () => {
+        planModeRef.active = true;
+    };
+    const subagentRetain = spec.retainSubagentSessions ? new SubagentRetainLedger(spec.retainSubagentSessions) : undefined;
+    const worktreeIsolation = spec.handsReadOnly !== true ? createSubagentWorktreeHelper(executionEnv, taskRootFinal) : undefined;
+    return { noteFileEdited, editedFilesSnapshot, harnessRef, skillScope, forwardEvent, reviewRequestRef, requestReview, stopRequestedRef, requestStopAfterTurn, planModeRef, enterPlanMode, subagentRetain, worktreeIsolation };
+}

package/dist/core/runner/prepare-safety-scan.d.ts

@@ -1,4 +1,5 @@
 import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
+import type { IrreversibilityTier, ReversibilityProbes } from "./contracts.js";
 /** The namespaced-name shapes the protocol table currently owns, rendered for the two messages that have
  *  to name them (the caller-name reservation and the policy audit's unprefixed-name arm). Read from the
  *  table rather than written out: a message that hard-codes ONE protocol becomes wrong — while staying
@@ -38,14 +39,14 @@ export interface PrepareSafetyScanResult {
     /** borrowed-mutable — tools whose effect is irreversible (`always`, or `maybe` incl. by probe). */
     irreversibleTools: Set<string>;
     /** borrowed-mutable — static per-tool irreversibility tier (prepare-time resolution). */
-    irreversibilityTier: Map<string, "never" | "maybe" | "always">;
+    irreversibilityTier: IrreversibilityTier;
     /** borrowed-mutable — explicit NEGATIVE axis judgments (report-face only; `riskAxesOf` reads). */
     axisExplicitNegatives: Map<string, {
         irreversible?: false;
         egress?: false;
     }>;
     /** borrowed-mutable — declared reversibility probes by tool name. */
-    reversibilityProbes: Map<string, NonNullable<TaskSpec["tools"]>[number]["reversibilityProbe"]>;
+    reversibilityProbes: ReversibilityProbes;
     /** borrowed-readonly — the caller roster's own names, snapshotted before the first await. */
     ownToolNames: ReadonlySet<string>;
 }