@sema-agent/core 5.16.0 → 5.17.0

package/dist/core/runner/prepare-task.js

@@ -20,7 +20,7 @@ import { createSubagentWorktreeHelper, forkGovernanceDenial } from "../../agents
 import { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME } from "../../agents/agent-transcript-tool.js";
 import { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
 import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
-import { askApproverIdentity, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets } from "../tool-policy.js";
+import { askApproverIdentity, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, describeThrown, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, tryCloneArgs } from "../tool-policy.js";
 import { ActiveSkillScope, createActiveSkillScopePolicy } from "./active-skill-scope.js";
 import { CHANGED_FILES_MTIME_EPS_MS, fenceMcpServerInstructions, renderAgentListingDelta } from "./turn-attachments.js";
 import { inlineUntrusted } from "../untrusted-text.js";
@@ -39,6 +39,8 @@ import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, createOffloadPersist, firstPartyOf
 import { OUTPUT_TOOL_NAME, REPORT_FINDINGS_TOOL_NAME, SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, createOutputTool, createReportBlockedTool, createReportFindingsTool, createSkillTool, normalizeSkills } from "./synthetic-tools.js";
 import { compileOutputSchema } from "./strict-output-schema.js";
 import { TOOL_SEARCH_NAME, buildDeferredRegistry, classifyDeferred, extractDiscoveredToolNames, createPlaceholderTool, createToolSearchTool, staticSchemaRenderable, } from "./tool-disclosure.js";
+import { createSharedMemoryTools } from "../shared-memory/tools.js";
+import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
 import { composeMemoryBlock } from "../memory.js";
 import { preflightLockedConfig } from "../locked-config.js";
 import { COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, complianceCallDenial, resolveComplianceDenies } from "../compliance.js";
@@ -75,7 +77,7 @@ import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { resolveKey } from "../../tools/fs/safety.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
-import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, remainingBudgetMicroUsd, resolveCheckpointStore, } from "../checkpoint-store.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveAskEffective, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
@@ -166,6 +168,9 @@ export function resolveEnvLifetimeExpiry(env, observedAt) {
         return { unanchored: true };
     return { expiresAt: anchor + lifetimeMs };
 }
+function isLiveApproverSeat(onAsk) {
+    return typeof onAsk === "function";
+}
 const DEFAULT_UNATTENDED_APPROVAL_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 function sanitizedTtlMs(ttlMs) {
     if (ttlMs === undefined)
@@ -180,6 +185,12 @@ export const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
 export function checkpointScopeOf(spec) {
     return spec.durableApproval?.scope || spec.principal || DEFAULT_IRREVERSIBLE_SCOPE;
 }
+class ParkRefusal extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ParkRefusal";
+    }
+}
 export { resolveCheckpointStore } from "../checkpoint-store.js";
 export function isFableFamilyModelId(id) {
     const tail = id.toLowerCase().split("/").pop() ?? "";
@@ -619,6 +630,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
     }
     const taskScope = internals?.registryScope ?? spec.principal ?? "default";
+    internals?.peerSelfRef?.addAxis("s", sessionId);
+    internals?.peerSelfRef?.addAxis("t", hostTaskId);
     const offloadScope = spec.principal ?? "default";
     if (internals?.registryScope !== undefined && internals.registryScope !== offloadScope) {
         deps.onError?.(new Error(`offload/tool-result namespace note: this run mounts in registry domain "${internals.registryScope}" but its offloaded tool results live under the TRUST identity "${offloadScope}" (principal${spec.principal === undefined ? " absent → default" : ""}). Before 2.13.0 the registry domain named this namespace too; if a deployment used registryScope as its ref-tenancy boundary, that boundary is now the principal — pass one, or read refs under "${offloadScope}".`), { phase: "config", sessionId });
@@ -1046,7 +1059,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(ownSessionRulesRef.current !== undefined ? [ownSessionRulesRef.current] : []),
             ];
             const ownCallerPolicy = lockedPreflight.toolPolicy;
-            const durableMandate = runtimeCaps?.forceDurableGate === true || (spec.durableApproval !== undefined && frozenOnAsk === undefined);
+            const durableMandate = runtimeCaps?.forceDurableGate === true ||
+                (spec.durableApproval !== undefined && !isLiveApproverSeat(frozenOnAsk));
             const parentConstraints = [
                 ...(inheritedParentConstraints ?? []),
                 ...(ownCallerPolicy !== undefined
@@ -1103,6 +1117,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
             ...(internals?.rootSessionId !== undefined ? { rootSessionId: internals.rootSessionId } : {}),
             ...(internals?.explicitAgentName !== undefined ? { spawnedAgentName: internals.explicitAgentName } : {}),
+            ...(internals?.peerSelfRef !== undefined ? { peerSelfRef: internals.peerSelfRef } : {}),
+            ...(internals?.peerInboundChainRef !== undefined ? { peerInboundChainRef: internals.peerInboundChainRef } : {}),
             ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
             ...(sessions.fork !== undefined
                 ? {
@@ -1589,6 +1605,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
                 ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
                 ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
+                ...(deps.hands?.readCyberReminder !== undefined ? { readCyberReminder: deps.hands.readCyberReminder } : {}),
                 beforeWrite: async (w) => {
                     const deploymentGate = deps.hands?.beforeWrite;
                     if (deploymentGate) {
@@ -1650,7 +1667,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             ...(req.row.agentType !== undefined ? { subagent_type: req.row.agentType } : {}),
                             ...(req.row.name !== undefined ? { name: req.row.name } : {}),
                             ...(req.row.model !== undefined ? { model: req.row.model } : {}),
-                        }, enrichSpecToolCtx({ toolCallId: `rv-${randomBytes(8).toString("hex")}`, reviveClaim: { row: req.row, rev: req.rev } }));
+                        }, enrichSpecToolCtx({ toolCallId: `rv-${randomBytes(8).toString("hex")}`, reviveClaim: { row: req.row, rev: req.rev, ...(req.peerSeed !== undefined ? { peerSeed: req.peerSeed } : {}) } }));
                         const o = (typeof out === "string" ? { content: out } : out);
                         return {
                             content: typeof o.content === "string" ? o.content : JSON.stringify(o.content),
@@ -1668,13 +1685,18 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(sessionId !== undefined ? { sessionId } : {}),
                     ...(internals?.onTaskNotification !== undefined ? { notify: internals.onTaskNotification } : {}),
                     ...(internals?.onSubagentSpawn !== undefined ? { sink: internals.onSubagentSpawn } : {}),
-                    ...(internals?.parentNotify !== undefined ? { uplink: internals.parentNotify } : {}),
+                    ...(internals?.parentNotify !== undefined
+                        ? { uplink: internals.parentNotify, ...(internals.parentPeerRef !== undefined ? { uplinkRecipient: internals.parentPeerRef } : {}) }
+                        : {}),
                     ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
                     ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
                     ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
                     ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
                     enrichCtx: enrichSpecToolCtx,
                     ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
+                    ...(deps.peerAdmission !== undefined ? { admission: deps.peerAdmission } : {}),
+                    ...(internals?.peerSelfRef !== undefined ? { peerSelf: internals.peerSelfRef } : {}),
+                    ...(internals?.peerInboundChainRef !== undefined ? { peerInbound: internals.peerInboundChainRef } : {}),
                     ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
                     ...(deps.mailboxStore !== undefined ? { mailbox: deps.mailboxStore } : {}),
@@ -1963,6 +1985,33 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             tools.push(createSkillTool(skillSpecs, skillScope));
         }
+        const sharedMemoryProvider = deps.sharedMemoryStores;
+        let sharedMemoryPairMounted = false;
+        if (sharedMemoryProvider !== undefined) {
+            const excluded = new Set(toolFaceSnapshot.exclude ?? []);
+            const mountedNameDomain = new Set();
+            for (const t of tools) {
+                mountedNameDomain.add(t.name);
+                for (const alias of t.aliases ?? [])
+                    mountedNameDomain.add(alias);
+            }
+            const excludedName = SHARED_MEMORY_TOOL_NAMES.find((n) => excluded.has(n));
+            const occupiedName = SHARED_MEMORY_TOOL_NAMES.find((n) => mountedNameDomain.has(n));
+            if (excludedName !== undefined || occupiedName !== undefined) {
+                deps.onError?.(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: ` +
+                    (excludedName !== undefined
+                        ? `excludeTools removes "${excludedName}"`
+                        : `this task already declares a tool named "${occupiedName}" (the built-in yields to it)`) +
+                    " — the pair mounts together or not at all."), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
+            }
+            else {
+                tools.push(...createSharedMemoryTools({
+                    provider: sharedMemoryProvider,
+                    context: { sessionId, taskId: hostTaskId, ...(spec.principal !== undefined ? { principal: spec.principal } : {}) },
+                }).map((s) => defineTool(s)));
+                sharedMemoryPairMounted = true;
+            }
+        }
         const skillsListing = skillSpecs.length > 0
             ? {
                 entries: skillSpecs.map((s) => ({
@@ -2142,6 +2191,56 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     tools[i] = { ...t, description: t.descriptionClassic };
             }
         }
+        const userToolNames = (spec.tools ?? []).map((t) => t.name);
+        const protocolToolNames = [...mcp.tools.map((t) => t.name), ...a2a.tools.map((t) => t.name)];
+        const mcpAlwaysLoadNames = mcp.tools
+            .filter((t) => t.mcpAlwaysLoad === true && !(toolFaceSnapshot.defer ?? []).includes(t.name))
+            .map((t) => t.name);
+        const classifyDeferredOverFace = (face, builtinDeferNames) => {
+            const deferredSet = classifyDeferred({
+                specs: spec.tools ?? [],
+                protocolToolNames,
+                fullTools: face.filter((t) => userToolNames.includes(t.name) || protocolToolNames.includes(t.name)),
+                deferMode: deps.deferMode,
+                model,
+                deferNames: [...(toolFaceSnapshot.defer ?? []), ...builtinDeferNames].filter((n) => face.some((t) => t.name === n)),
+                alwaysLoadNames: [
+                    ASK_USER_QUESTION_TOOL_NAME,
+                    ...(toolFaceSnapshot.alwaysLoad ?? []),
+                    ...mcpAlwaysLoadNames,
+                ],
+            });
+            for (const n of [...deferredSet]) {
+                if (!face.some((t) => t.name === n))
+                    deferredSet.delete(n);
+            }
+            return deferredSet;
+        };
+        const sharedMemoryPair = SHARED_MEMORY_TOOL_NAMES.filter((n) => tools.some((t) => t.name === n));
+        let deferred;
+        if (sharedMemoryPairMounted && sharedMemoryPair.length > 0) {
+            const withoutPair = tools.filter((t) => !sharedMemoryPair.some((n) => n === t.name));
+            const d1 = classifyDeferredOverFace(tools, sharedMemoryPair);
+            const d0 = classifyDeferredOverFace(withoutPair, []);
+            const soleCause = d0.size === 0 && d1.size > 0;
+            const supportNameTaken = tools.some((t) => t.name === TOOL_SEARCH_NAME || (t.aliases ?? []).includes(TOOL_SEARCH_NAME));
+            if (soleCause && supportNameTaken) {
+                for (let i = tools.length - 1; i >= 0; i--) {
+                    if (sharedMemoryPair.some((n) => n === tools[i].name))
+                        tools.splice(i, 1);
+                }
+                sharedMemoryPairMounted = false;
+                deps.onError?.(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
+                    `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — the pair mounts together or not at all.`), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
+                deferred = d0;
+            }
+            else {
+                deferred = d1;
+            }
+        }
+        else {
+            deferred = classifyDeferredOverFace(tools, []);
+        }
         let centerAdoption;
         let centerAdoptionFresh = false;
         {
@@ -2181,7 +2280,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             isDefaultProvider: provider === defaultPromptProvider,
             userSystemPrompt,
             userAppendSystemPrompt,
-            tools,
+            tools: tools.map((t) => (t.aliases === undefined ? { ...t } : { ...t, aliases: [...t.aliases] })),
             facts: {
                 supervisorEnabled: false,
                 teammateEnabled: internals?.explicitAgentName !== undefined && tools.some((t) => t.name === SEND_MESSAGE_TOOL_NAME),
@@ -2261,27 +2360,6 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 });
             }
         }
-        const userToolNames = (spec.tools ?? []).map((t) => t.name);
-        const protocolToolNames = [...mcp.tools.map((t) => t.name), ...a2a.tools.map((t) => t.name)];
-        const deferred = classifyDeferred({
-            specs: spec.tools ?? [],
-            protocolToolNames,
-            fullTools: tools.filter((t) => userToolNames.includes(t.name) || protocolToolNames.includes(t.name)),
-            deferMode: deps.deferMode,
-            model,
-            deferNames: (toolFaceSnapshot.defer ?? []).filter((n) => tools.some((t) => t.name === n)),
-            alwaysLoadNames: [
-                ASK_USER_QUESTION_TOOL_NAME,
-                ...(toolFaceSnapshot.alwaysLoad ?? []),
-                ...mcp.tools
-                    .filter((t) => t.mcpAlwaysLoad === true && !(toolFaceSnapshot.defer ?? []).includes(t.name))
-                    .map((t) => t.name),
-            ],
-        });
-        for (const n of [...deferred]) {
-            if (!tools.some((t) => t.name === n))
-                deferred.delete(n);
-        }
         const activeTools = new Set();
         const fpRef = {};
         const turnSnapshotRef = {};
@@ -2291,6 +2369,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             .map((s) => ({ name: inlineUntrusted(s.name, 160), ...(s.error !== undefined ? { error: inlineUntrusted(s.error, 240) } : {}) }));
         let toolsDeltaRef;
         let toolMaterializeStatic = false;
+        let deferDirectCall = false;
         const staticFaceForRef = {};
         if (deferred.size > 0 || failedMcpServers.length > 0) {
             toolsDeltaRef = { pending: [], pendingRemoved: [], pendingReadded: [], pendingFailed: failedMcpServers };
@@ -2313,6 +2392,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             const laneDegrade = requestedStrategy === "static" && spec.deferSelfResolve === false;
             const materializeStatic = requestedStrategy === "static" && !laneDegrade;
             toolMaterializeStatic = materializeStatic;
+            deferDirectCall = spec.deferSelfResolve !== false;
             promptManifest.toolDisclosure = {
                 deferredTools: deferred.size,
                 strategy: materializeStatic ? "static" : "swap",
@@ -3336,15 +3416,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             });
             const commitSuspendSaga = async (token, cp, remoteEnv, remoteHandle) => {
                 if (!checkpointStore)
-                    return false;
+                    return { ok: false };
                 if (memoryEngineSession)
                     await memoryEngineSession.harvest("checkpoint");
                 try {
                     await checkpointStore.put(token, cp);
-                    return true;
+                    return { ok: true };
                 }
                 catch (putErr) {
                     deps.onError?.(putErr, { phase: "config", sessionId });
+                    const reason = "the approval checkpoint could not be persisted (the store rejected the write; the deployment's error face carries the store's own message)";
                     if (remoteEnv !== undefined && remoteHandle?.snapshotId !== undefined) {
                         const { outcome: back, attempts: backAttempts } = await restoreWorkspaceWithRetry(remoteEnv, remoteHandle.snapshotId, {
                             abortSignal: abortController.signal,
@@ -3352,7 +3433,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         if (back.ok) {
                             const init = await remoteEnv.postResumeInit();
                             if (init.ok)
-                                return false;
+                                return { ok: false, reason };
                             remoteEnvFailures.push(remoteEnvFailureNote("postResumeInit", init.error, 1));
                             deps.onError?.(init.error, { phase: "config", sessionId });
                         }
@@ -3362,9 +3443,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         }
                         abortController.abort();
                         void harness.abort();
-                        return false;
+                        return { ok: false, reason };
                     }
-                    return false;
+                    return { ok: false, reason };
                 }
             };
             const publishCommittedSuspend = (token, gate, scope, remoteHandle) => {
@@ -3452,7 +3533,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     resourceLedger: resourceLedgerOut,
                     ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
                 };
-                if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
+                if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).ok)
                     return false;
                 publishCommittedSuspend(token, gate, scope, remoteHandle);
                 try {
@@ -3537,7 +3618,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         ...(spec.principal ? { principal: spec.principal } : {}),
                         ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
                     };
-                    if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
+                    if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).ok)
                         return false;
                     publishCommittedSuspend(token, gate, scope, remoteHandle);
                     try {
@@ -3633,7 +3714,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             };
             const suspendAsk = parkLaneArmed && checkpointStore !== undefined
                 ? async (req, postHookArgs, safety, liveFaceUnavailable) => {
-                    const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : onAsk !== undefined;
+                    const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
                     if (syncFirstEligible &&
                         runtimeCaps?.forceDurableGate !== true &&
                         liveFaceUnavailable !== true &&
@@ -3646,13 +3727,50 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     let remoteHandle;
                     const remoteEnv = suspendableEnv;
                     try {
+                        const parked = tryCloneArgs(postHookArgs);
+                        if (!parked.ok) {
+                            throw new ParkRefusal(`the arguments of "${req.toolName}" cannot be captured onto an approval checkpoint (unclonable value: ${parked.reason}) — ` +
+                                `a durable approval row must hold an inert snapshot of exactly what a human approves and a resume executes`, { cause: parked.cause });
+                        }
+                        let backendFidelity;
+                        try {
+                            backendFidelity = resolveDeclaredFidelity(checkpointStore, "checkpointStore");
+                        }
+                        catch (err) {
+                            throw new ParkRefusal(`the checkpoint backend declares an unrecognized encoding fidelity, so the width of the snapshot this row may hold is unknown (${describeThrown(err)}) — ` +
+                                `refusing to park rather than guess which values would survive it`, { cause: err });
+                        }
+                        const captured = encodeAtFidelity(backendFidelity, parked.value);
+                        if (!captured.ok) {
+                            throw new ParkRefusal(`the arguments of "${req.toolName}" cannot be encoded by this checkpoint backend (${describeThrown(captured.cause)}) — ` +
+                                `a durable approval row must hold an inert snapshot of exactly what a human approves and a resume executes`, { cause: captured.cause });
+                        }
+                        const parkedArgs = captured.value;
+                        const projectionMovedArgs = backendFidelity !== "structured-clone" && !samePlainValue(parked.value, parkedArgs);
+                        if (projectionMovedArgs && basePolicyForResumeEdit !== undefined) {
+                            const presented = encodeAtFidelity(backendFidelity, parkedArgs);
+                            if (!presented.ok) {
+                                throw new ParkRefusal(`the stored form of "${req.toolName}"'s arguments could not be presented for re-adjudication (${describeThrown(presented.cause)})`, { cause: presented.cause });
+                            }
+                            const reprojected = refuseOutOfContractDecision(await basePolicyForResumeEdit.check({ toolName: req.toolName, args: presented.value, toolCallId: req.toolCallId }, abortController.signal));
+                            const demanded = reprojected.updatedInput !== undefined ? tryCloneArgs(reprojected.updatedInput) : undefined;
+                            const rewroteTheFiledValue = reprojected.updatedInput !== undefined &&
+                                !(demanded?.ok === true &&
+                                    samePlainValue(demanded.value, parkedArgs) &&
+                                    samePlainValue(reprojected.updatedInput, parkedArgs));
+                            if (reprojected.action === "deny" || rewroteTheFiledValue) {
+                                throw new ParkRefusal(`the arguments of "${req.toolName}" change shape when stored by this checkpoint backend, and the deployment's tool policy does not accept the stored shape` +
+                                    `${reprojected.action === "deny" && reprojected.message ? `: ${reprojected.message}` : ""} — ` +
+                                    `refusing to file a row whose executable form nothing adjudicated`);
+                            }
+                        }
                         if (offloadStore && isVolatileOffloadStore(offloadStore) && !offloadStore.isEmpty()) {
-                            throw new Error("durable suspend requires a durable toolResultStore (the default InMemoryToolResultStore " +
+                            throw new ParkRefusal("durable suspend requires a durable toolResultStore (the default InMemoryToolResultStore " +
                                 "holds offloaded results that are lost across a cross-replica resume); inject " +
                                 "RunnerDeps.toolResultStore or disable offload.");
                         }
                         if (ownedEnv !== undefined && remoteEnv === undefined && parkOnlyRemoteEnv === undefined) {
-                            throw new Error(incompleteSuspendAdapter !== undefined
+                            throw new ParkRefusal(incompleteSuspendAdapter !== undefined
                                 ? `durable suspend is not supported with this per-task executionEnvFactory env: it declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")}, so a snapshot taken now could never be restored. Implement the full RemoteExecutionEnv restore surface, or declare capabilities.suspendable:false if the workspace is externally durable (the park-only lane).`
                                 : "durable suspend is not supported with a non-remote per-task executionEnvFactory env: the " +
                                     "minted env is destroyed on suspend, so a resumed file/shell tool would act on a fresh " +
@@ -3661,7 +3779,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         }
                         const leafId = await session.getLeafId();
                         if (!leafId) {
-                            throw new Error("cannot suspend: session has no committed leaf to resume from");
+                            throw new ParkRefusal("cannot suspend: session has no committed leaf to resume from");
                         }
                         const { messages } = await session.buildContext();
                         const { batchToolCallIds, completedCallIds } = batchContextAt(messages, req.toolCallId);
@@ -3688,7 +3806,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         token = mintCheckpointToken();
                         const riskDescriptor = buildRiskDescriptor({
                             toolName: req.toolName,
-                            args: postHookArgs,
+                            args: parkedArgs,
                             safety,
                             shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
                             ...(effectiveShellGate !== "off" ? { shellGateDoctrine: effectiveShellGate } : {}),
@@ -3731,12 +3849,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                 kind: "tool_approval",
                                 toolCallId: req.toolCallId,
                                 toolName: req.toolName,
-                                args: postHookArgs,
+                                args: parkedArgs,
                                 ...(() => {
-                                    const preview = approvalPreviewOf(req.toolName, postHookArgs);
+                                    const preview = approvalPreviewOf(req.toolName, parkedArgs);
                                     return preview !== undefined ? { preview } : {};
                                 })(),
-                                boundInputHash: boundInputHashOf(postHookArgs),
+                                boundInputHash: boundInputHashOf(parkedArgs),
                                 batchToolCallIds,
                                 completedCallIds,
                             },
@@ -3761,10 +3879,15 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     }
                     catch (err) {
                         deps.onError?.(err, { phase: "config", sessionId });
-                        return undefined;
+                        return {
+                            parkFailed: err instanceof ParkRefusal
+                                ? err.message
+                                : "the durable approval park could not be prepared (the deployment's error face carries the exception)",
+                        };
                     }
-                    if (!(await commitSuspendSaga(token, cp, remoteEnv, remoteHandle))) {
-                        return undefined;
+                    const committed = await commitSuspendSaga(token, cp, remoteEnv, remoteHandle);
+                    if (!committed.ok) {
+                        return committed.reason !== undefined ? { parkFailed: committed.reason } : undefined;
                     }
                     publishCommittedSuspend(token, gate, cp.scope, remoteHandle);
                     try {
@@ -4139,7 +4262,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -42,6 +42,7 @@ import { refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.
 import { defaultTaskRegistry } from "../task-registry.js";
 import { discloseDroppedPending, isDelegatedAgentTerminal, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
+import { createPeerInboundChainRef, createPeerSelfRef } from "../../agents/peer-admission.js";
 import { workflowSizeGuidelineChangeNotice } from "../../orchestration/workflow-size-guideline.js";
 import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
 function createRunState() {
@@ -576,7 +577,9 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                         skillsListing: rs.attach.skillsListingOn,
                         mcpInstructions: mcpInstructionsOn,
                     },
-                    ...(undiscoveredTools !== undefined && undiscoveredTools.length > 0 ? { undiscoveredTools } : {}),
+                    ...(undiscoveredTools !== undefined && undiscoveredTools.length > 0
+                        ? { undiscoveredTools, deferDirectCall: prepared.deferDirectCall }
+                        : {}),
                     ...(changed !== undefined ? { changedFiles: changed } : {}),
                     ...(budgetUsdOn && rs.budget.maxCostMicroUsd !== undefined
                         ? { budgetUsd: { used: stats.costMicroUsd / 1e6, total: rs.budget.maxCostMicroUsd / 1e6 } }
@@ -1821,8 +1824,12 @@ export class Runner {
                     resolve("queued");
             });
         };
+        const peerSelfRef = internals?.peerSelfRef ?? createPeerSelfRef(internals?.registryScope ?? spec.principal ?? "default");
+        const peerInboundChainRef = internals?.peerInboundChainRef ?? createPeerInboundChainRef();
         const prepared = await prepareTask(spec, this.deps, this.sessions, prepareResume, {
             ...(internals ?? {}),
+            peerSelfRef,
+            peerInboundChainRef,
             detachHub,
             onTaskNotification: (notification, opts) => {
                 try {
@@ -1849,6 +1856,11 @@ export class Runner {
             for (const p of payloads)
                 this.pendingSessionNotifications.pend(notificationSessionId, p);
         };
+        prepared.harness.onEngineNoteConsumed = (p) => {
+            const peer = p?.peer;
+            if (peer !== undefined && Array.isArray(peer.hopChain))
+                peerInboundChainRef.current = [...peer.hopChain];
+        };
         if (notifyRef)
             notifyRef.inject = injectTaskNotification;
         try {

package/dist/core/runner/turn-attachments.d.ts

@@ -94,6 +94,7 @@ export interface AttachmentInputs {
         mcpInstructions?: boolean;
     };
     undiscoveredTools?: readonly string[];
+    deferDirectCall?: boolean;
     changedFiles?: ReadonlyArray<{
         path: string;
         mtimeMs: number;
@@ -118,7 +119,7 @@ export interface AttachmentInputs {
     mcpDroppedTools?: ReadonlyArray<McpDroppedTool>;
 }
 export declare function collectDueAttachments(state: AttachmentState, inp: AttachmentInputs): readonly TurnAttachment[];
-export declare function renderToolSearchUsageReminder(undiscovered: readonly string[]): string;
+export declare function renderToolSearchUsageReminder(undiscovered: readonly string[], directCallEnabled?: boolean): string;
 export declare function renderDateChange(newDate: string): string;
 export declare function collectDateChange(state: DateChangeState, today: string): TurnAttachment | undefined;
 export declare function collectInstructionsChange(state: InstructionsChangeState, probed: ReadonlyArray<{

package/dist/core/runner/turn-attachments.js

@@ -145,7 +145,7 @@ export function collectDueAttachments(state, inp) {
         const sinceUse = state.toolSearchLastUseTurn === undefined ? Number.POSITIVE_INFINITY : cadenceNow - state.toolSearchLastUseTurn;
         if (sinceUse >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS && cadenceNow - state.lastToolSearchReminderTurn >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS) {
             state.lastToolSearchReminderTurn = cadenceNow;
-            (out ??= []).push({ source: "tool_search_usage_reminder", body: renderToolSearchUsageReminder(inp.undiscoveredTools) });
+            (out ??= []).push({ source: "tool_search_usage_reminder", body: renderToolSearchUsageReminder(inp.undiscoveredTools, inp.deferDirectCall !== false) });
         }
     }
     if (inp.config.planModeReminder && inp.planActive) {
@@ -248,14 +248,17 @@ function renderTaskReminder(state) {
     }
     return message;
 }
-export function renderToolSearchUsageReminder(undiscovered) {
+export function renderToolSearchUsageReminder(undiscovered, directCallEnabled = true) {
     const shown = undiscovered.slice(0, TOOL_SEARCH_REMINDER_CONFIG.MAX_NAMES);
     const more = undiscovered.length - shown.length;
     const names = `${shown.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
     return (`Some available tools' schemas are not loaded in this conversation yet: ${names}. Before concluding a ` +
         `capability is missing or building a workaround, use ${TOOL_SEARCH_TOOL_NAME} to find and load relevant tools — ` +
-        `keywords to search, or query "select:<name>[,<name>...]" for specific tools. Calling a tool before its schema ` +
-        `is loaded will fail. This is just a gentle reminder - ignore if not applicable to the current work.`);
+        `keywords to search, or query "select:<name>[,<name>...]" for specific tools. ` +
+        (directCallEnabled
+            ? `You do not have these tools' parameters, so activate one rather than guessing its arguments. `
+            : `Calling a tool before its schema is loaded will fail. `) +
+        `This is just a gentle reminder - ignore if not applicable to the current work.`);
 }
 export function renderDateChange(newDate) {
     return `The date has changed. Today's date is now ${newDate}. DO NOT mention this to the user explicitly because they are already aware.`;
@@ -400,8 +403,8 @@ export function renderToolsDelta(input) {
     if (added.length > 0) {
         const swapped = input.staticFace === true ? (input.swappedUnderStatic ?? []).filter((n) => added.includes(n)) : [];
         blocks.push((input.staticFace === true
-            ? "The following deferred tools are now active — call them directly. Their parameter schemas were " +
-                "provided in the ToolSearch result (the tools list itself keeps compact placeholder entries):\n"
+            ? "The following deferred tools are now active — call them directly. The tools list keeps compact " +
+                'placeholder entries, so re-run ToolSearch ("select:<name>") if you need a parameter schema:\n'
             : "The following deferred tools are now available. Their full schemas are loaded — call them " +
                 "directly like any other tool:\n") +
             added.map((n) => `- ${n}`).join("\n") +

package/dist/core/session-reconcile.js

@@ -10,6 +10,20 @@ const INTERRUPTED_IDEMPOTENT = "[INTERRUPTED] The previous run ended before this
     "what you intended. If you decide not to re-issue it, verify the current state first.";
 const INTERRUPTED_NEVER_STARTED = "[INTERRUPTED] The run was aborted before this tool call started. It was never executed and had " +
     "no side effects — it is safe to re-issue this call if you still need it.";
+const INTERRUPTED_REPEAT_UNKNOWN = "[INTERRUPTED] Same as an earlier interrupted call in this batch: no result was recorded and the outcome is " +
+    "UNKNOWN — verify before relying on it.";
+const INTERRUPTED_REPEAT_SAFE = "[INTERRUPTED] Same as an earlier interrupted call in this batch: this tool is read-only/idempotent, so just " +
+    "call it again if you still need the result.";
+const INTERRUPTED_REPEAT_IDEMPOTENT = "[INTERRUPTED] Same as an earlier interrupted call in this batch: it is safe to REPLAY — re-issue it, or verify " +
+    "the current state if you decide not to.";
+const INTERRUPTED_REPEAT_NEVER_STARTED = "[INTERRUPTED] Same as an earlier interrupted call in this batch: it never started and had no side effects — " +
+    "safe to re-issue.";
+const REPEAT_TEXT = {
+    never_started: INTERRUPTED_REPEAT_NEVER_STARTED,
+    read: INTERRUPTED_REPEAT_SAFE,
+    idempotent: INTERRUPTED_REPEAT_IDEMPOTENT,
+    unknown: INTERRUPTED_REPEAT_UNKNOWN,
+};
 export function findOrphanToolCalls(messages, suspendedBatch) {
     const resolvedAt = new Map();
     const callSitesAt = new Map();
@@ -70,11 +84,15 @@ export async function reconcileInterruptedSession(session, toolEffects, suspende
     const { messages } = await session.buildContext();
     const orphans = findOrphanToolCalls(messages, suspendedBatch).filter((o) => o.kind !== "result");
     const recovered = [];
+    const statedInFull = new Set();
     for (const orphan of orphans) {
         const effect = toolEffects?.get(orphan.toolName) ?? "write";
         const effectText = effect === "read" ? INTERRUPTED_SAFE : effect === "idempotent" ? INTERRUPTED_IDEMPOTENT : INTERRUPTED_UNKNOWN;
         const neverStarted = startedToolCallIds !== undefined && !startedToolCallIds.has(orphan.toolCallId);
-        const text = neverStarted ? INTERRUPTED_NEVER_STARTED : effectText;
+        const fullText = neverStarted ? INTERRUPTED_NEVER_STARTED : effectText;
+        const cls = neverStarted ? "never_started" : effect === "read" ? "read" : effect === "idempotent" ? "idempotent" : "unknown";
+        const text = statedInFull.has(cls) ? REPEAT_TEXT[cls] : fullText;
+        statedInFull.add(cls);
         const errorKind = neverStarted ? "interrupted_never_started" : "interrupted_outcome_unknown";
         const entryId = await session.appendMessage({
             role: "toolResult",

package/dist/core/shared-memory/contract.d.ts

@@ -0,0 +1,17 @@
+import type { SharedMemorySnapshot, SharedMemoryStoreInfo, SharedMemoryStoreProvider } from "./types.js";
+export interface SharedMemoryFixture {
+    state: SharedMemorySnapshot["state"];
+    stores: Array<{
+        info: SharedMemoryStoreInfo;
+        documents: Array<{
+            path: string;
+            content: string;
+            updatedAt?: string;
+        }>;
+    }>;
+}
+export interface SharedMemoryStoreContractHooks {
+    make: (fixture: SharedMemoryFixture) => Promise<SharedMemoryStoreProvider> | SharedMemoryStoreProvider;
+    runAssertion?: (name: string, fn: () => Promise<void>) => void | Promise<void>;
+}
+export declare function sharedMemoryStoreContract(hooks: SharedMemoryStoreContractHooks): Promise<void>;