@sema-agent/core 7.5.0 → 7.5.2

package/dist/core/runner/prepare-prompt-inputs.d.ts

@@ -0,0 +1,119 @@
+/**
+ * design/390 M10 — prepareTask's PROMPT-INPUTS phase: the prompt provider selection, the runtime
+ * feature flags the harness-context block gates on (so it never claims a mechanism the task lacks),
+ * the three-source user system prompt + the caller's append block, the fenced MCP server-instructions
+ * block, the environment facts (client zone + date basis, knowledge cutoff, the deployment's sandbox
+ * axes, resume-continuity facts on a durable-resume leg only, the hands facts + the one batched env
+ * probe with its cwd/pwd alignment guard) and the git-status lane probe. The body is the driver's
+ * stretch moved verbatim; the interface is the dependency list it had implicitly (design/238 R-1).
+ *
+ * ASYNC BY CONTENT: the stretch awaits the env probe (hands) and the git-status lane probe (always).
+ * It sits past prepareTask's first await, so the driver's `await` adds no window a caller could reach.
+ *
+ * The one input computed by the DRIVER rather than read here: `failClosedReason` — the
+ * self-orchestration fail-closed advisory's text. Its helper takes the whole `TaskSpec`/`RunnerDeps`
+ * (it audits several deployment seats), which this phase's narrow `spec`/`deps` seats cannot satisfy
+ * (design/238 R-4); the driver evaluates the helper in the Input literal and this phase only announces
+ * the result on the operator lane, exactly where the stretch always did.
+ *
+ * Nothing here throws on its own: the env probe and the alignment guard are best-effort (a stub/odd env
+ * just omits the shell-derived facts), and the git lane degrades through `onDegrade` → `deps.onError`.
+ */
+import type { ExecutionEnv, ThinkingLevel } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import { type EnvironmentFacts, type PromptProvider } from "../../prompts/default.js";
+import type { ReadFace } from "../../tools/fs/index.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { MaterializedMcp } from "../mcp.js";
+import type { ResolvedRole } from "../roles.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { PrepareResume, PromptFeatureFlags, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { type GitStatusLaneRef } from "./git-status-frame.js";
+export interface PreparePromptInputsInput {
+    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `promptProvider`, `hooks` (flag), `systemPrompt`
+     *  / `appendSystemPrompt` (the user prompt sources), `clientContext` (zone, email), `envFacts` (the
+     *  deployment's sandbox + resume facts), `compaction` (the within-task flag). Never mutated. */
+    spec: Pick<TaskSpec, "promptProvider" | "hooks" | "systemPrompt" | "appendSystemPrompt" | "clientContext" | "envFacts" | "compaction">;
+    /** borrowed-readonly — deployment deps: `promptProvider` (fallback), `hooks` (flag), `onError` (the
+     *  operator lane: fail-closed advisory, cwd misalignment, git-lane degrade), `modelKnowledgeCutoffs`.
+     *  Receiver preserved (`deps.onError?.(…)`). */
+    deps: Pick<RunnerDeps, "promptProvider" | "hooks" | "onError" | "modelKnowledgeCutoffs">;
+    /** borrowed-readonly — the self-orchestration fail-closed advisory (null = nothing to announce),
+     *  evaluated by the DRIVER against the whole spec/deps (see the module header). */
+    failClosedReason: string | null;
+    /** borrowed-readonly — the locked preflight; only `toolPolicy` presence is read (the policy flag). */
+    lockedPreflight: Pick<LockedPreflight, "toolPolicy">;
+    /** borrowed-readonly — whether self-orchestration is ACTIVE (the same gate that mounted the
+     *  workflow tool): drives the orchestration prompt flags. */
+    selfOrchestrationActive: boolean;
+    /** borrowed-readonly — the task's execution env: `isIsolated` for the isolation flag, `exec` for the
+     *  one batched probe, `canonicalPath` for the alignment guard. Never re-bound, never destroyed here. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the session's reminder mark (rides the prompt facts for the declaration). */
+    reminderMark: string;
+    /** borrowed-readonly — the resolved read face (the open-reads flag + the structured env fact). */
+    resolvedReadFace: ReadFace | undefined;
+    /** borrowed-readonly — the frozen tool face; only `defer` is read (the Workflow short-pointer flag). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "defer">;
+    /** borrowed-readonly — the resolved prompt profile (rides the flags to the legacy ctx). */
+    promptProfile: "simple" | "classic";
+    /** borrowed-readonly — the fable-mitigations profile axis (rides the flags with the profile). */
+    fableMitigations: boolean;
+    /** borrowed-readonly — trusted internals: `goalMode` (goal flag), `isolation` (worktree flag),
+     *  `defaultSystemPrompt` (the third prompt source). `undefined` on a standalone prepare. */
+    internals: Pick<RunInternals, "goalMode" | "isolation" | "defaultSystemPrompt"> | undefined;
+    /** borrowed-readonly — the resolved, role-folded reasoning tier (the awareness flag's input). */
+    thinking: ThinkingLevel | undefined;
+    /** borrowed-readonly — the factory-minted isolated env, read for PRESENCE only (the worktree flag's
+     *  belt over the fail-closed isolation guard). */
+    ownedEnv: ExecutionEnv | undefined;
+    /** borrowed-readonly — the leg's effective-delegation facts; only `isNonForkChild` is read. */
+    delegation: {
+        readonly isNonForkChild: boolean;
+    };
+    /** borrowed-readonly — the resolved role; only its `systemPrompt` preset is read (second source). */
+    resolvedRole: Pick<ResolvedRole, "systemPrompt">;
+    /** borrowed-readonly — the materialized MCP roster; only `serverInstructions` is read (fenced). */
+    mcp: Pick<MaterializedMcp, "serverInstructions">;
+    /** borrowed-readonly — the resolved model (id for the env line + the cutoff lookup). */
+    model: Model;
+    /** borrowed-readonly — the run's external-content-target fold (the single-source disclosure fact). */
+    externalContentTargetActive: boolean;
+    /** borrowed-readonly — the durable-resume carrier, read for PRESENCE only (resume facts copy on a
+     *  resume leg and never on a fresh one). */
+    resume: PrepareResume | undefined;
+    /** borrowed-readonly — whether a real execution env is mounted (the hands facts + both probes). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the FINAL task root: the env `cwd` fact and the git lane's root. */
+    taskRootFinal: string;
+    /** borrowed-readonly — the canonical extra working roots (copied into the env facts). */
+    additionalRootsCanonical: readonly string[];
+    /** borrowed-readonly — the canonical extra read-only roots (copied into the env facts). */
+    additionalReadRootsCanonical: readonly string[];
+    /** borrowed-readonly — the acquired session's id (operator-line context). */
+    sessionId: string;
+}
+export interface PreparePromptInputsResult {
+    /** owned — the prompt provider in force (`spec` ?? `deps` ?? the default). */
+    provider: PromptProvider;
+    /** owned — the runtime feature flags (see {@link PromptFeatureFlags}). */
+    featureFlags: PromptFeatureFlags;
+    /** owned — the user system prompt: `spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals.defaultSystemPrompt`. */
+    userSystemPrompt: string | undefined;
+    /** owned — the caller's append block (`spec.appendSystemPrompt`). */
+    userAppendSystemPrompt: string | undefined;
+    /** owned — the fenced MCP server-instructions block, or undefined when no server declared any. */
+    mcpInstructionsBlock: string | undefined;
+    /** owned — the environment facts the env tail renders from. Filled here; no later phase writes it
+     *  (the run loop re-renders only the date through `renderWithDate`). */
+    envFacts: EnvironmentFacts;
+    /** owned — whether the client zone validated (the date-change seam re-renders in the same zone). */
+    tzValid: boolean;
+    /** owned — the client's declared zone as given (paired with `tzValid`; unvalidated on its own). */
+    userTz: string | undefined;
+    /** owned — the git-status lane's run-local state (empty on a hands-less leg); the run loop and the
+     *  checkpoint serializer mutate its fields from here on (`announced`, `pendingReceipt`, …). */
+    gitStatusRef: GitStatusLaneRef;
+}
+/** The M10 phase body — prepareTask's prompt-inputs stretch, verbatim (see the module header). */
+export declare function preparePromptInputs(input: PreparePromptInputsInput): Promise<PreparePromptInputsResult>;

package/dist/core/runner/prepare-prompt-inputs.js

@@ -0,0 +1,141 @@
+import { defaultPromptProvider, formatLocalDate, isValidTimeZone } from "../../prompts/default.js";
+import { isIsolated } from "../remote-env.js";
+import { probeGitStatusLane } from "./git-status-frame.js";
+import { fenceMcpServerInstructions } from "./turn-attachments.js";
+const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
+export async function preparePromptInputs(input) {
+    const { spec, deps, failClosedReason, lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId } = input;
+    const provider = spec.promptProvider ?? deps.promptProvider ?? defaultPromptProvider;
+    const promptPolicyEnabled = Boolean(lockedPreflight.toolPolicy);
+    const promptHooks = spec.hooks ?? deps.hooks;
+    const promptHooksEnabled = Boolean(promptHooks?.preToolUse || promptHooks?.postToolUse);
+    if (failClosedReason) {
+        deps.onError?.(new Error(failClosedReason), { phase: "config", sessionId });
+    }
+    const featureFlags = {
+        policyEnabled: promptPolicyEnabled,
+        hooksEnabled: promptHooksEnabled,
+        isolationEnabled: isIsolated(executionEnv),
+        reminderMark,
+        readFaceOpen: resolvedReadFace === "open",
+        orchestrationEnabled: selfOrchestrationActive,
+        orchestrationDeferred: selfOrchestrationActive && (toolFaceSnapshot.defer?.includes("Workflow") ?? false),
+        promptProfile,
+        fableMitigations,
+        goalEnabled: internals?.goalMode === true,
+        awarenessEnabled: thinking !== undefined && ULTRA_REASONING_TIERS.has(thinking),
+        worktreeIsolated: internals?.isolation === "worktree" && ownedEnv !== undefined,
+        withinTaskCompactionEnabled: (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true),
+        isSubagent: delegation.isNonForkChild,
+    };
+    const userSystemPrompt = spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals?.defaultSystemPrompt;
+    const userAppendSystemPrompt = spec.appendSystemPrompt;
+    const mcpInstructionsBlock = mcp.serverInstructions.length
+        ? `# MCP Server Instructions\n${mcp.serverInstructions.map((s) => fenceMcpServerInstructions(s.server, s.text)).join("\n\n")}`
+        : undefined;
+    const userTz = spec.clientContext?.timeZone;
+    const tzValid = userTz !== undefined && isValidTimeZone(userTz);
+    const envFacts = { date: formatLocalDate(new Date(), tzValid ? userTz : undefined), modelId: model.id };
+    if (tzValid)
+        envFacts.timeZone = userTz;
+    if (spec.clientContext?.userEmail)
+        envFacts.userEmail = spec.clientContext.userEmail;
+    const declaredCutoff = deps.modelKnowledgeCutoffs?.[model.id];
+    if (declaredCutoff)
+        envFacts.knowledgeCutoff = declaredCutoff;
+    if (spec.envFacts?.profile)
+        envFacts.sandboxProfile = spec.envFacts.profile;
+    if (spec.envFacts?.capabilities && spec.envFacts.capabilities.length > 0)
+        envFacts.sandboxCapabilities = [...spec.envFacts.capabilities];
+    if (spec.envFacts?.pkgSource)
+        envFacts.sandboxPkgSource = spec.envFacts.pkgSource;
+    if (spec.envFacts?.egress === "none" || spec.envFacts?.egress === "allowlist" || spec.envFacts?.egress === "full")
+        envFacts.sandboxEgress = spec.envFacts.egress;
+    if (spec.envFacts?.scratchpadDir)
+        envFacts.scratchpadDir = spec.envFacts.scratchpadDir;
+    if (externalContentTargetActive)
+        envFacts.externalContentTarget = true;
+    if (resume !== undefined && spec.envFacts?.resumeFacts) {
+        const rf = spec.envFacts.resumeFacts;
+        const copy = {};
+        if (rf.processes === "preserved" || rf.processes === "lost")
+            copy.processes = rf.processes;
+        if (rf.scratch === "preserved" || rf.scratch === "lost")
+            copy.scratch = rf.scratch;
+        if (typeof rf.note === "string" && rf.note.length > 0)
+            copy.note = rf.note;
+        if (Object.keys(copy).length > 0)
+            envFacts.resumeFacts = copy;
+    }
+    if (handsEnabled) {
+        envFacts.cwd = taskRootFinal;
+        if (additionalRootsCanonical.length > 0) {
+            envFacts.additionalDirectories = [...additionalRootsCanonical];
+        }
+        if (resolvedReadFace !== undefined)
+            envFacts.readFace = resolvedReadFace;
+        if (additionalReadRootsCanonical.length > 0) {
+            envFacts.additionalReadDirectories = [...additionalReadRootsCanonical];
+        }
+        try {
+            const probe = await executionEnv.exec('uname -s; uname -r; (git rev-parse --is-inside-work-tree 2>/dev/null || echo false); (git symbolic-ref --short -q HEAD 2>/dev/null || echo "HEAD (detached)"); (git rev-parse --show-toplevel 2>/dev/null || echo); (test -n "$(git status --porcelain 2>/dev/null | head -1)" && echo dirty || echo clean); (s=$(ps -p $$ -o comm= 2>/dev/null); s=${s##*/}; echo "${s#-}"); (test "$(git rev-parse --git-dir 2>/dev/null)" != "$(git rev-parse --git-common-dir 2>/dev/null)" && echo linked || echo main); (pwd -P 2>/dev/null || pwd)', { cwd: envFacts.cwd, timeout: 10 });
+            if (probe.ok && probe.value.exitCode === 0) {
+                const lines = probe.value.stdout.split("\n");
+                if (lines.length >= 6) {
+                    const [osName, osVer, git, branch, worktreeRoot, dirty] = lines;
+                    if (osName?.trim())
+                        envFacts.platform = osName.trim();
+                    if (osVer?.trim())
+                        envFacts.osVersion = osVer.trim();
+                    envFacts.isGitRepo = (git ?? "").trim() === "true";
+                    if (envFacts.isGitRepo) {
+                        const b = (branch ?? "").trim();
+                        if (b)
+                            envFacts.gitBranch = b;
+                        const root = (worktreeRoot ?? "").trim();
+                        if (root)
+                            envFacts.gitWorktreeRoot = root;
+                        const d = (dirty ?? "").trim();
+                        if (d === "dirty" || d === "clean")
+                            envFacts.gitDirty = d === "dirty";
+                    }
+                    const sh = (lines[6] ?? "").trim();
+                    if (sh)
+                        envFacts.shell = sh;
+                    if (envFacts.isGitRepo && (lines[7] ?? "").trim() === "linked")
+                        envFacts.isLinkedWorktree = true;
+                    const probedPwd = (lines[8] ?? "").trim();
+                    if (probedPwd && envFacts.cwd && probedPwd !== envFacts.cwd) {
+                        const canonOf = async (p) => {
+                            try {
+                                const c = await executionEnv.canonicalPath(p);
+                                return c.ok ? c.value : p;
+                            }
+                            catch {
+                                return p;
+                            }
+                        };
+                        const canonicalProbed = await canonOf(probedPwd);
+                        if (canonicalProbed !== (await canonOf(envFacts.cwd))) {
+                            try {
+                                deps.onError?.(new Error(`execution-env cwd misalignment: task root is "${envFacts.cwd}" but the env's shell reports pwd "${canonicalProbed}" — per-exec cwd injection may be ignored on this lane (execs/artifacts can land outside the workspace root)`), { phase: "config", sessionId });
+                            }
+                            catch {
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+        }
+    }
+    const gitStatusRef = await probeGitStatusLane({
+        executionEnv,
+        envFacts,
+        handsEnabled,
+        taskRoot: taskRootFinal,
+        onDegrade: (reason) => deps.onError?.(new Error(`env git snapshot degraded — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" }),
+    });
+    return { provider, featureFlags, userSystemPrompt, userAppendSystemPrompt, mcpInstructionsBlock, envFacts, tzValid, userTz, gitStatusRef };
+}

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 memory-engine-session phase
+     *  (installs the re-runnable pass ONCE when it arms — a mounted engine-memory session or an upstream recorder
+     *  channel; 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,179 @@
+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) {
+            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) {
+            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,101 @@
+/**
+ * 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 } 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";
+import { type ContentAskBinding } from "./content-ask-bindings.js";
+export { CONTENT_ASK_BINDING_CAP, type ContentAskBinding } from "./content-ask-bindings.js";
+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;