@sema-agent/core 7.13.0 → 7.15.0

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

@@ -18,7 +18,7 @@
  */
 import type { AgentTool } from "../../internal/harness.js";
 import { type OnQuestion } from "../ask-question.js";
-import { type CheckpointStore } from "../checkpoint-store.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";
@@ -28,13 +28,15 @@ 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 REBOUND spec. Read: `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, "durableApproval" | "interactiveTools" | "principal" | "interactiveQuestionFallback">;
+    /** borrowed-readonly — the deployment seat `onError` (the stranded-answer and synthetic-continuation operator
+     *  lines; swallow-guarded). */
+    deps: Pick<RunnerDeps, "onError">;
+    /** borrowed-readonly — THE leg's checkpoint seat (minted once by the driver after the config doors); the mount face, the routability predicate, the manifest and suspendAsk all read this one value through the result. */
+    checkpointStore: CheckpointStore | undefined;
     /** 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;

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

@@ -1,16 +1,14 @@
 import { createAskUserQuestionTool, isLiveQuestionFace } from "../ask-question.js";
 import { boundInputHashOf } from "../canonical-json.js";
-import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { CONTENT_ASK_BINDING_CAP } from "./content-ask-bindings.js";
 import { RosterBuilder } from "../tool-roster.js";
 export { CONTENT_ASK_BINDING_CAP } from "./content-ask-bindings.js";
 export function prepareQuestionFace(input) {
-    const { frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks } = input;
+    const { frozenOnQuestion, spec, deps, checkpointStore, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks } = input;
     const tools = roster.tools;
     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 &&

package/dist/core/runner/prepare-safety-scan.js

@@ -23,7 +23,7 @@ export function prepareSafetyScan(input) {
                 ...(typeof t.modelGate === "string" ? { modelGate: t.modelGate } : {}),
             });
             if (bound !== undefined) {
-                const e = new Error(`Tool "${t.name.slice(0, 40)}" cannot ride a roster row: ${bound.message}.`);
+                const e = new Error(`A caller tool cannot ride a roster row: ${bound.message}.`);
                 e.code = bound.code;
                 throw e;
             }

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

@@ -68,12 +68,14 @@ import { defaultTaskRegistry } from "../task-registry.js";
 import { announcePeerLaneMount } from "../../agents/peer-session-drain.js";
 import { createSchedulerTools } from "../../tools/scheduler-tools.js";
 import { selfOrchestrationFailClosedReason } from "../../orchestration/workflow-script-runner.js";
-import { remainingBudgetMicroUsd } from "../checkpoint-store.js";
+import { remainingBudgetMicroUsd, resolveCheckpointStore } from "../checkpoint-store.js";
+import { checkpointSeatOf } from "../checkpoint-seat.js";
 import { durableParkGapFor } from "../park-selfcheck.js";
 import { deliverEngineNotice } from "../types.js";
 import { ToolRosterDeltaSeat } from "../tool-roster.js";
 import { faceOf } from "../tool-roster.js";
 import { catalogEntriesNamed, pathTargetOf } from "../tool-registry.js";
+import { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import { createStructuredProjector } from "./tool-output-projection.js";
 function warnCompactionWindowHazard(tracer, spec, model, compModel, hostTaskId) {
     if (compModel === undefined)
@@ -257,13 +259,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         runIdSink.runId = runId;
     const doors = prepareConfigDoors({ spec, deps, sessions, resume, internals });
     spec = doors.spec;
+    const checkpointStore = resolveCheckpointStore(spec, deps), checkpointSeat = checkpointSeatOf(spec, checkpointStore);
     const autoModeSeat = refuseInvalidAutoModeSeat(spec);
     const { toolFaceSnapshot, promptProfile, lockedPreflight, resolvedInteractionPosture, microCompactKnob, resolvedRole, model, thinking, compModel, fableMitigations, memoryDelegationEvidence, memoryProvenance, memoryCapturePolicy, usageWindows, brainCallGuardrailRef, brainCallGuardrailMs } = doors;
     announceToolModelGate(deps.onNotice, model.id, doors.modelGate);
     const modelGateManifest = toolModelGateManifest(doors.modelGate);
     const { toolEffects, egressTools, irreversibleTools, irreversibilityTier, axisExplicitNegatives, reversibilityProbes, ownToolNames } = prepareSafetyScan({ spec, deps });
-    let shellGatedBash = false;
-    let shellGatedMonitor = false;
+    let shellGatedTools = new Set();
     refuseRequireExistingWithoutSession(spec);
     const { acquired, session, conflictRef, wakeRecovered, resumeAtBeforeParentId } = await prepareAcquireReconcile({ sessions, spec, resume, toolEffects, ...(internals?.sessionPlacement !== undefined ? { placement: internals.sessionPlacement } : {}), ...(() => { const g = durableParkGapFor(deps, spec); return g !== undefined ? { durableParkGap: g } : {}; })() });
     const sessionId = acquired.sessionId;
@@ -366,8 +368,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         let resolvedReadFace;
         let readDenyAdditionsNormalized = [];
         let handsLessResolvedFace;
-        const { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx } = prepareInheritedGate({ spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun: () => { abortController.abort(); void harness.abort(); }, runtimeCaps: () => runtimeCaps, hooks: () => hooks, preToolUseObservational: () => preToolUseObservational, hookTimeoutMs: () => hookTimeoutMs, hookEnvFace: () => hookEnvFace, autoModeDecider: () => autoModeDecider, autoModeDenialTracking: () => autoModeDenialTracking, autoModeArming: () => autoModeArming, agentForkDenial: () => agentForkDenial, observersActive: () => observersActive, resolvedReadFace: () => resolvedReadFace, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized, handsLessResolvedFace: () => handsLessResolvedFace, centerAdoption: () => centerAdoptionRef.current, memoryEngineSession: () => memoryEngineSession });
-        const { roster, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline } = await prepareCapsAndWorkflow({ spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf, memoryEngineSession: () => memoryEngineSession, centerAdoption: () => centerAdoptionRef.current, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized });
+        const { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx } = prepareInheritedGate({ spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, checkpointSeat, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun: () => { abortController.abort(); void harness.abort(); }, runtimeCaps: () => runtimeCaps, hooks: () => hooks, preToolUseObservational: () => preToolUseObservational, hookTimeoutMs: () => hookTimeoutMs, hookEnvFace: () => hookEnvFace, autoModeDecider: () => autoModeDecider, autoModeDenialTracking: () => autoModeDenialTracking, autoModeArming: () => autoModeArming, agentForkDenial: () => agentForkDenial, observersActive: () => observersActive, resolvedReadFace: () => resolvedReadFace, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized, handsLessResolvedFace: () => handsLessResolvedFace, centerAdoption: () => centerAdoptionRef.current, memoryEngineSession: () => memoryEngineSession });
+        const { roster, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline } = await prepareCapsAndWorkflow({ spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, checkpointSeat, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf, memoryEngineSession: () => memoryEngineSession, centerAdoption: () => centerAdoptionRef.current, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized });
         const tools = roster.tools;
         const pausedRef = {};
         const remoteEnvFailures = [];
@@ -431,34 +433,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const callIssuedAtRef = {};
         const workCutRef = { continuation: false, abortedBeforeTurnEnd: false };
         const memoryWriteGateRef = {};
-        const handsReadFaceInput = { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, roster, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes, reminderMark, reminderDisclosureCounts, ...(trackFileEdit !== undefined ? { trackFileEdit } : {}), onFileEdited: noteFileEdited, ...(restoredFilePaths.length > 0 ? { restoredFilePaths } : {}) };
-        const handsReadFace = handsEnabled ? await prepareHandsMount(handsReadFaceInput) : resolveHandsLessReadFace(handsReadFaceInput);
-        const { readFileStateForCheckpoint, seedContextFiles, handsCwdRef, workspaceStateSettle, wsSnapshot, rebaseWsPath, backgroundTaskToolsActive, additionalRootsCanonical, additionalReadRootsCanonical, attachmentRootCanonical, readDenyMatcher, envHandToolNames, sealReadStateSeat } = handsReadFace;
-        resolvedReadFace = handsReadFace.resolvedReadFace;
-        readDenyAdditionsNormalized = handsReadFace.readDenyAdditionsNormalized;
-        handsLessResolvedFace = handsReadFace.handsLessResolvedFace;
-        shellGatedBash = handsReadFace.shellGatedBash;
-        shellGatedMonitor = handsReadFace.shellGatedMonitor;
-        const { worktreeSessionRef } = prepareDelegationSurface({ spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle });
-        const { checkpointStore, liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, questionToolMounted, mountedQuestionTool } = prepareQuestionFace({ frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks: () => inheritedUnavailableAsks });
-        if (spec.handsReadOnly !== true) {
-            const sessionScope = sessionId ?? spec.principal ?? spec.taskId ?? "default";
-            roster.mountAll(createSchedulerTools(executionEnv, {
-                scope: sessionScope,
-                ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
-                ...(sessionId !== undefined ? { sessionId } : {}),
-                requestStopAfterTurn,
-            }).map((t) => (envHandToolNames.add(t.name), t)), { source: "builtin", mountedBy: "scheduler" });
-        }
-        if (internals?.insideFork !== true &&
-            runnerSelf &&
-            sessionId !== undefined &&
-            hasSessionFork(runnerSelf.sessions) &&
-            agentForkDenial === "principal") {
-            deps.onError?.(new Error(`Fork DENIED for principal "${spec.principal ?? ""}" by runtimeCaps.allowFork=false ` +
-                `(per-principal entitlement governance, not a misconfiguration — Agent(subagent_type:"fork") will refuse honestly)`), { phase: "config", sessionId });
-        }
-        const { lspDiagnostics, nudgeLspOnEdit, lspRunIdent } = prepareLsp({ spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, roster, envHandToolNames });
+        const advertisedWritableDirs = handsEnabled
+            ? new AdvertisedWritableDirs(executionEnv, (dir, reason) => deps.onError?.(new Error(`${dir.advertiser} advertised writable directory skipped (cannot canonicalize): ${dir.path} — ${reason}`), { phase: "config", sessionId }))
+            : undefined;
+        const handsWriteHalfPlanned = handsEnabled && spec.handsReadOnly !== true;
         const memoryPairNameDomain = new Set();
         for (const t of tools) {
             memoryPairNameDomain.add(t.name);
@@ -477,14 +455,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 return { fault: true };
             }
         })();
-        const { memoryEngineSession, memoryBlock: memoryBlockFromEngine, memoryTools, recallDisciplineSegment: memoryRecallSegment, seedFiles: memorySeedFiles, admittedOrgScopes: memoryAdmittedOrgScopes, ownOrgVerdict: memoryOwnOrgVerdict, effectiveMemoryScopes: memoryEffectiveScopes, } = await prepareMemory({
+        const { memoryEngineSession, memoryTools, composeInjection: composeMemoryInjection, admittedOrgScopes: memoryAdmittedOrgScopes, ownOrgVerdict: memoryOwnOrgVerdict, effectiveMemoryScopes: memoryEffectiveScopes, } = await prepareMemory({
             spec,
             deps,
             sessionId,
             taskRootPath: taskRootFinal,
             memoryWriteGateRef,
             reminderMark,
-            writeToolsMounted: tools.some((t) => t.name === "Write") &&
+            writeToolsMounted: (handsWriteHalfPlanned || tools.some((t) => t.name === "Write")) &&
                 !(toolFaceSnapshot.exclude?.includes("Write") ?? false) &&
                 !(handsEnabled && isRemoteExecutionEnv(executionEnv) && spec.memoryPersistenceCapable !== true),
             memoryProvenance,
@@ -503,20 +481,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(internals?.memoryCaptureQueryDir !== undefined ? { parentCaptureQueryDir: internals.memoryCaptureQueryDir } : {}),
             ...(internals?.memoryCaptureAncestors !== undefined ? { captureAncestors: internals.memoryCaptureAncestors } : {}),
             memoryPersistenceDeclared: spec.memoryPersistenceCapable,
-            rosterCanPersist: spec.memoryPersistenceCapable ??
-                tools.some((t) => {
-                    if (toolFaceSnapshot.exclude?.includes(t.name) ?? false)
-                        return false;
-                    const effect = (t.effect ?? toolEffects.get(t.name) ?? "write");
-                    if (effect === "read")
-                        return false;
-                    const face = faceOf(t);
-                    const pt = face.pathTarget ?? pathTargetOf(t.name);
-                    const family = face.family ?? catalogEntriesNamed(t.name)[0]?.face.family;
-                    if (!((pt !== undefined && pt.access !== "read") || family === "shell"))
-                        return false;
-                    return !(handsEnabled && isRemoteExecutionEnv(executionEnv));
-                }),
+            ...(advertisedWritableDirs !== undefined ? { advertisedWritableDirs } : {}),
             memorySearchToolsPlanned,
             admissionCtx: {
                 orgMemoryDenied: complianceDenies.has("org_memory_mount"),
@@ -540,6 +505,33 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         if (internals?.ownOrgAdmissionRef !== undefined && ownOrgVerdictRef.current !== undefined) {
             internals.ownOrgAdmissionRef.current = ownOrgVerdictRef.current;
         }
+        const handsReadFaceInput = { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, ...(advertisedWritableDirs !== undefined ? { advertisedWritableDirs } : {}), firstPartyOffload, roster, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes, reminderMark, reminderDisclosureCounts, ...(trackFileEdit !== undefined ? { trackFileEdit } : {}), onFileEdited: noteFileEdited, ...(restoredFilePaths.length > 0 ? { restoredFilePaths } : {}) };
+        const handsReadFace = handsEnabled ? await prepareHandsMount(handsReadFaceInput) : resolveHandsLessReadFace(handsReadFaceInput);
+        const { readFileStateForCheckpoint, seedContextFiles, handsCwdRef, workspaceStateSettle, wsSnapshot, rebaseWsPath, backgroundTaskToolsActive, additionalRootsCanonical, additionalReadRootsCanonical, attachmentRootCanonical, readDenyMatcher, envHandToolNames, sealReadStateSeat } = handsReadFace;
+        resolvedReadFace = handsReadFace.resolvedReadFace;
+        readDenyAdditionsNormalized = handsReadFace.readDenyAdditionsNormalized;
+        handsLessResolvedFace = handsReadFace.handsLessResolvedFace;
+        shellGatedTools = handsReadFace.shellGatedTools;
+        const { worktreeSessionRef } = prepareDelegationSurface({ spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle });
+        const { liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, questionToolMounted, mountedQuestionTool } = prepareQuestionFace({ frozenOnQuestion, spec, deps, checkpointStore, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks: () => inheritedUnavailableAsks });
+        if (spec.handsReadOnly !== true) {
+            const sessionScope = sessionId ?? spec.principal ?? spec.taskId ?? "default";
+            roster.mountAll(createSchedulerTools(executionEnv, {
+                scope: sessionScope,
+                ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                requestStopAfterTurn,
+            }).map((t) => (envHandToolNames.add(t.name), t)), { source: "builtin", mountedBy: "scheduler" });
+        }
+        if (internals?.insideFork !== true &&
+            runnerSelf &&
+            sessionId !== undefined &&
+            hasSessionFork(runnerSelf.sessions) &&
+            agentForkDenial === "principal") {
+            deps.onError?.(new Error(`Fork DENIED for principal "${spec.principal ?? ""}" by runtimeCaps.allowFork=false ` +
+                `(per-principal entitlement governance, not a misconfiguration — Agent(subagent_type:"fork") will refuse honestly)`), { phase: "config", sessionId });
+        }
+        const { lspDiagnostics, nudgeLspOnEdit, lspRunIdent } = prepareLsp({ spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, roster, envHandToolNames });
         if (internals?.delegationProvenance !== undefined && resume !== undefined) {
             const live = internals.delegationProvenance.ref.current;
             const seed = resume.seed.delegationProvenance;
@@ -553,6 +545,21 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     live.incomplete = true;
             }
         }
+        const rosterCanPersist = spec.memoryPersistenceCapable ??
+            tools.some((t) => {
+                if (toolFaceSnapshot.exclude?.includes(t.name) ?? false)
+                    return false;
+                const effect = (t.effect ?? toolEffects.get(t.name) ?? "write");
+                if (effect === "read")
+                    return false;
+                const face = faceOf(t);
+                const pt = face.pathTarget ?? pathTargetOf(t.name);
+                const family = face.family ?? catalogEntriesNamed(t.name)[0]?.face.family;
+                if (!((pt !== undefined && pt.access !== "read") || family === "shell"))
+                    return false;
+                return !(handsEnabled && isRemoteExecutionEnv(executionEnv));
+            });
+        const { memoryBlock: memoryBlockFromEngine, recallDisciplineSegment: memoryRecallSegment, seedFiles: memorySeedFiles } = composeMemoryInjection({ rosterCanPersist });
         if (memorySeedFiles?.length && seedContextFiles) {
             try {
                 await seedContextFiles(memorySeedFiles);
@@ -563,7 +570,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
         const projectContext = await prepareProjectContext({ deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, roster, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume });
         const { memoryBlock: memoryBlockWithProject, instructionSources, projectInstructionContent, hasSkillManifest, skillsListing, sharedMemoryPairMounted, memoryEnginePairMounted } = projectContext;
-        const { provider, featureFlags, userSystemPrompt, userAppendSystemPrompt, mcpInstructionsBlock, envFacts, tzValid, userTz, gitStatusRef } = await preparePromptInputs({ spec, deps, failClosedReason: selfOrchestrationFailClosedReason(spec, deps), lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId });
+        const { provider, featureFlags, userSystemPrompt, userAppendSystemPrompt, mcpInstructionsBlock, envFacts, tzValid, userTz, gitStatusRef } = await preparePromptInputs({ spec, deps, failClosedReason: selfOrchestrationFailClosedReason(spec, deps), lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId, ...(advertisedWritableDirs !== undefined ? { advertisedWritableDirs } : {}) });
         const { deferred, memoryBlock } = prepareDeferClassify({ spec, deps, roster, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryBlock: memoryBlockWithProject, memoryRecallSegment, onceLedger, sessionId });
         prepareMemoryEngineSession({ memoryEngineSession, internals, memoryDelegationEvidence, externalContentTargetActive, lockedPreflight, mcp, sessionId, runId, deps, provenanceForChildrenRef, delegationSettlementRef, spec, envHandToolNames, roster, contentOriginWrapRef });
         const { systemPromptSeat, renderWithDate, systemBlocks, promptManifest, epochDeclaredSections, epochArtifactDigestForSnapshot, buildAssembleInputs, centerAdoptionRef } = await preparePromptAssembly({ session, deps, internals, resume, provider, userSystemPrompt, userAppendSystemPrompt, featureFlags, mcpInstructionsBlock, memoryBlock, envFacts, promptProfile, fableMitigations, tools, model, sessionId, reminderMark, onceLedger });
@@ -674,7 +681,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 releaseSignal = () => sig.removeEventListener("abort", onExternalAbort);
             }
         }
-        const { hooks, hookTimeoutMs, preToolUseObservational, ownGatePreToolUse, basePolicyForResumeEdit, denyNarrowingPolicy, policyLayers, effectivePolicy, inheritedUnavailableAsks, inheritedAskGrants, askSourceIdentity, riskAxesOf, ruleOffersOf, permissionRuleLane, permissionRuleOrgLane, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, foldAskClasses, ancestorSandboxAdmissions } = await preparePolicyChain({ spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedBash, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef });
+        const { hooks, hookTimeoutMs, preToolUseObservational, ownGatePreToolUse, basePolicyForResumeEdit, denyNarrowingPolicy, policyLayers, effectivePolicy, inheritedUnavailableAsks, inheritedAskGrants, askSourceIdentity, riskAxesOf, ruleOffersOf, permissionRuleLane, permissionRuleOrgLane, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, foldAskClasses, ancestorSandboxAdmissions } = await preparePolicyChain({ spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedTools, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef });
         const { onAsk, preToolContexts, blockedToolCalls, gateOutcomes, batchHaltRef, blockedTracked, incompleteSuspendAdapter, durableSuspendInfraReady, resourceSuspendEligible, usageGovernance, durableApproval, wiringManifest, parkLaneArmed, gateMachineryActive, hookIdentity, hookEnvFace } = prepareWiringManifest({ spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation, toolRoster });
         if (fileHistoryBoundary !== undefined) {
             harness.on("tool_call", async () => {
@@ -685,8 +692,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash });
         const { saga } = prepareSuspendSaga({ gateMachineryActive, abortController, harness, checkpointStore, deps, sessionId, hostTaskId, taskScope, liveSpendRef, resume, nestedStats, internals, activeTools, outputRef, readFileStateForCheckpoint, faceCheckpointSection, reminderMark, handsCwdRef, worktreeSessionRef, inheritedParentConstraints, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, autoModeIntent, inheritedAdmittedOrgScopes, ownOrgVerdictRef, orgGovernedProvenance, announcedListingsRef, gitStatusRef, hookIdentity, placementRootResolved, externalContentTargetActive, remoteEnvFailures, memoryEngineSession, suspendLoopRef, ownedEnv, incompleteSuspendAdapter });
         const { suspendForResource, suspendForPlatformLimit, suspendForReview } = prepareBoundaryParks({ saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, pausedRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter });
-        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedBash, shellGatedMonitor, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });
-        prepareGateStations({ askLane, parkAsk, tools, toolRosterDeltas: rosterSeat, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedBash, shellGatedMonitor, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash });
+        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });
+        prepareGateStations({ askLane, parkAsk, tools, toolRosterDeltas: rosterSeat, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash });
         const { microCompact, charsPerToken } = prepareContextLane({ model, deps, sessionId, runId, hostTaskId, offloadStore, microCompactKnob, harness, batchHaltRef, gitStatusRef, requestLossyRef, trimPressureRef });
         const preparedHolder = {};
         const { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved } = prepareTurnWiring({ deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder });

package/dist/core/runner/prepare-wiring-manifest.d.ts

@@ -30,7 +30,7 @@ import type { GateOutcome } from "../gate-outcome.js";
 import type { RunnerDeps, RuntimeCaps, TaskSpec, ToolEffect, ToolExecuteContext } from "../types.js";
 import { type UsageWindow } from "../usage-window-store.js";
 import type { ToolRoster } from "../tool-roster.js";
-import { type AutoModeArmReason, type WiringManifest, type WiringManifestMcpEntry } from "../wiring-manifest.js";
+import { type AutoModeArmFact, type WiringManifest, type WiringManifestMcpEntry } from "../wiring-manifest.js";
 import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, UsageGovernance } from "./contracts.js";
 export interface PrepareWiringManifestInput {
     /** borrowed-readonly — the REBOUND spec. Read: `onAsk` (the own seat), `onQuestion` (the question seam), `handsReadOnly` / `tools` (the ungated scan),
@@ -107,7 +107,7 @@ export interface PrepareWiringManifestInput {
      *  source of the hand band's write-capable names for the ungated-write warning (what actually MOUNTED). */
     toolRoster: ToolRoster;
     /** borrowed-readonly — the arming outcome the caps phase minted (the manifest's auto-mode face). */
-    autoModeArmReason: AutoModeArmReason;
+    autoModeArmReason: AutoModeArmFact;
     /** borrowed-readonly — the frozen preflight; only `mcp` (the declared servers the manifest face joins). */
     lockedPreflight: Pick<LockedPreflight, "mcp">;
     /** borrowed-mutable — the peer lane's late-bound facts. Writer here: `askEffective` ← the manifest's ask derivation (the

package/dist/core/runner/prepare-wiring-manifest.js

@@ -199,7 +199,7 @@ export function prepareWiringManifest(input) {
         memoryAdmissionWired: deps.memoryScopeAdmission !== undefined,
         retentionPolicyWired: deps.retentionPolicy !== undefined,
         ...(modelGateManifest !== undefined ? { modelGate: modelGateManifest } : {}),
-        autoMode: { armed: autoModeArmReason === "armed", reason: autoModeArmReason },
+        autoMode: { ...autoModeArmReason },
         mcp: mcpManifestEntries(lockedPreflight.mcp, mcp.statuses),
         tools: toolRoster,
     });

package/dist/core/runner/run-compaction-machinery.js

@@ -11,6 +11,8 @@ export function runCompactionMachinery(input) {
         const u = msg?.usage;
         if (!u)
             return;
+        if (msg.usageMissing === true)
+            stats.usageMissing = true;
         const fam = cacheFamilyOf(m);
         const price = runner.deps.pricing?.[m.id] ?? modelCostToPricing(m.cost);
         const priced = isModelPriced(m, runner.deps.pricing);

package/dist/core/runner/run-harness-handlers.js

@@ -77,8 +77,10 @@ export function createHarnessHandlers(input) {
                 rs.degrade.recordDegraded({ from: deg.from, to: deg.to, reason: deg.reason, atTurn: stats.turns + 1, ...(deg.chain && { chain: deg.chain }) });
         }
         if (m.role === "assistant" && "usage" in m && m.usage) {
-            if (m.usageMissing)
+            if (m.usageMissing) {
                 rs.turn.turnUsageMissing = true;
+                stats.usageMissing = true;
+            }
             const u = m.usage;
             stats.tokens += u.totalTokens || 0;
             const { totalInputTokens: turnTotal, uncachedInputTokens: turnUncached, costMicroUsd: turnCostMicroUsd, } = usageCostMicroUsd(rs.telemetry.cacheFamily, u, rs.telemetry.pricing);

package/dist/core/runner/stream-settle-backstop.js

@@ -83,7 +83,7 @@ export function streamSettleBackstop(input) {
                     ? { retryAfterMs: hinted }
                     : {};
             })(),
-            stats: { turns: 0, tokens: 0, toolCalls: 0, cachedTokens: 0, costMicroUsd: 0 },
+            stats: { turns: 0, tokens: 0, toolCalls: 0, cachedTokens: 0, costMicroUsd: 0, usageMissing: true },
         };
         emitTrace(entryTracer.tracer, () => ({
             kind: "task.end",

package/dist/core/runner/tool-defer-gate.d.ts

@@ -0,0 +1,86 @@
+import type { Model } from "../../internal/llm.js";
+import type { ToolSpec } from "../types.js";
+import type { ToolFingerprintInput } from "../cache-break-detector.js";
+/**
+ * The deferral GATE (design/36): which mounted tool names ship as placeholders on a request. Pure
+ * registry logic over names and sizes — no harness, no I/O. `tool-disclosure.ts` owns the placeholder
+ * and ToolSearch mechanics that act on the set this module decides; `prepare-defer-classify.ts` is the
+ * phase that assembles the inputs from the mounted face.
+ */
+/** The deferral gate's threshold: the engine's candidate set is deferred when its inlined size reaches
+ *  this fraction of the model's context window (that set measured, never the rest of the face). */
+export declare const DEFER_THRESHOLD_FRACTION = 0.1;
+/** The typed refusal a `deferMode` outside its declared domain (`"auto"` or absent) raises at the classifier —
+ *  a bad value never selects an arm silently. */
+export declare const DEFER_MODE_INVALID_CODE = "config.defer_mode_invalid";
+/** The deferral gate's verdict — the two deferral lists, what the gate measured, and whether it opened. */
+export interface DeferralGate {
+    /** The caller's LITERAL list: `TaskSpec.deferTools` names mounted on this face, minus the inline pins.
+     *  Deferred on every request, whatever the gate says — an intentional deferral is not a size question. */
+    explicit: Set<string>;
+    /** The engine's SELF-SELECTED candidates: `ToolSpec.defer === true`, every remote-protocol name, built-ins
+     *  that declare their own `defer`, and — under `deferMode: "auto"` — every caller spec; minus the inline
+     *  pins and minus `explicit`. Deferred iff the gate opens. */
+    gated: Set<string>;
+    /** Σ inlined chars (name + description + serialized schema) over `gated` — the bytes the gate could reclaim. */
+    gatedChars: number;
+    /** `floor(contextTokens × fraction) × CHARS_PER_TOKEN`; the char reading of the token threshold. */
+    thresholdChars: number;
+    /** Whether `gated` is deferred on this request: `gatedChars ≥ thresholdChars`. */
+    open: boolean;
+}
+/**
+ * Deferral has TWO rules, and only two.
+ *
+ * ① THE CALLER'S LIST IS LITERAL. `TaskSpec.deferTools` (arriving as `callerDeferNames`, pre-filtered to
+ *    mounted wire names, built-ins included) is deferred on every request; `alwaysLoad` (`ToolSpec.alwaysLoad`,
+ *    `alwaysLoadNames`) is inlined on every request and is judged FIRST — a pinned name is in neither list
+ *    and is never measured. Neither depends on the gate: they are the deployment's stated intent.
+ *
+ * ② THE ENGINE'S OWN CANDIDATES SIT BEHIND ONE THRESHOLD GATE. The candidates are declared: explicit
+ *    `ToolSpec.defer === true` on a caller spec, every REMOTE-PROTOCOL tool name (MCP servers AND A2A peers —
+ *    the caller unions them), and `builtinDeferNames` (mounted BUILT-INS that declare their own `defer`; a
+ *    built-in ToolSpec never reaches `specs`, so its declaration arrives as a mounted name). `deferMode:
+ *    "auto"` WIDENS the candidate set to every caller spec — undeclared caller tools included — and nothing
+ *    else: it is not a second gate, and engine built-ins the deployment did not name are candidates under no
+ *    setting. The gate decides the set all or nothing: deferred iff `gatedChars ≥ thresholdChars`, where the
+ *    threshold is {@link DEFER_THRESHOLD_FRACTION} of the model's context window (`contextTokens ??
+ *    contextWindow`, in chars at {@link CHARS_PER_TOKEN}). The measure is the candidate set ONLY — the bytes
+ *    the gate could reclaim — never the caller's list, the pins, or non-candidates: a request whose weight
+ *    sits elsewhere gains nothing from a ToolSearch round-trip, so nothing about it argues for one. A window
+ *    of zero reads as a zero threshold (every candidate byte is over budget), so the candidates defer.
+ *
+ * Invariants: `explicit ∩ gated = ∅`; `deferred = explicit ∪ (open ? gated : ∅)`; a pinned name is in no
+ * list; the same inputs always yield the same verdict (a pure function of the request).
+ */
+export declare function deferralGate(opts: {
+    specs: ReadonlyArray<ToolSpec>;
+    /** Every namespaced tool a remote protocol materialized for this task (MCP servers AND A2A peers —
+     *  the caller unions them). The remote-roster shape (many tools, schemas the deployment does not
+     *  control, drift between tasks) is the same for every protocol, so every protocol's names are
+     *  candidates by being remote. Only an inline pin (or the caller's own list) takes a name out. */
+    protocolToolNames: ReadonlyArray<string>;
+    /** The MOUNTED face — the tools whose full definitions the request would carry. The measure reads
+     *  each candidate's inlined size from here; a candidate absent from it weighs nothing. */
+    fullTools: ReadonlyArray<ToolFingerprintInput>;
+    /** `"auto"` widens the candidate set to every caller spec (see above). Any other value refuses. */
+    deferMode?: "auto";
+    model: Model;
+    /** Rule ① — `TaskSpec.deferTools`: ALREADY-MOUNTED wire names (built-ins included; `ToolSpec.defer`
+     *  only reaches caller specs) the caller defers on every request. Caller pre-filters to mounted names. */
+    callerDeferNames?: ReadonlyArray<string>;
+    /** Rule ② — mounted BUILT-INS that declare their own `defer` (the engine's declaration, not the
+     *  caller's), so they are candidates. Caller pre-filters to mounted names. */
+    builtinDeferNames?: ReadonlyArray<string>;
+    /** Rule ① — inline-pin names (`TaskSpec.alwaysLoadTools` + the MCP tools whose server declared
+     *  `_meta["anthropic/alwaysLoad"]`, caller-collected; A2A has no such per-skill declaration, so the
+     *  task-level list is a peer's only inline-keep channel): exempt from BOTH lists.
+     *  `ToolSpec.alwaysLoad` rides the specs directly and needs no entry here. */
+    alwaysLoadNames?: ReadonlyArray<string>;
+}): DeferralGate;
+/**
+ * Decide which tool names are deferred: the caller's literal list, plus the gated candidates when the gate
+ * opens. THIS CONTRACT (with {@link deferralGate}) IS THE SINGLE AUTHORITY on the deferral sources and the
+ * gate; the `TaskSpec` / `RunnerDeps` JSDoc points here.
+ */
+export declare function classifyDeferred(opts: Parameters<typeof deferralGate>[0]): Set<string>;

package/dist/core/runner/tool-defer-gate.js

@@ -0,0 +1,57 @@
+import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
+export const DEFER_THRESHOLD_FRACTION = 0.1;
+const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
+function inlinedChars(t) {
+    let schema = "";
+    try {
+        schema = JSON.stringify(t.parameters) ?? "";
+    }
+    catch {
+        schema = "";
+    }
+    return t.name.length + t.description.length + schema.length;
+}
+export const DEFER_MODE_INVALID_CODE = "config.defer_mode_invalid";
+export function deferralGate(opts) {
+    if (opts.deferMode !== undefined && opts.deferMode !== "auto") {
+        const e = new Error(`RunnerDeps.deferMode: invalid value ${JSON.stringify(opts.deferMode)} — expected "auto" or omitted; a bad value refuses loudly, nothing falls back to a default.`);
+        e.code = DEFER_MODE_INVALID_CODE;
+        throw e;
+    }
+    const pinned = new Set(opts.alwaysLoadNames ?? []);
+    for (const s of opts.specs) {
+        if (s.alwaysLoad === true)
+            pinned.add(s.name);
+    }
+    const explicit = new Set();
+    for (const name of opts.callerDeferNames ?? [])
+        if (!pinned.has(name))
+            explicit.add(name);
+    const gated = new Set();
+    const select = (name) => {
+        if (!pinned.has(name) && !explicit.has(name))
+            gated.add(name);
+    };
+    for (const s of opts.specs)
+        if (s.defer === true || opts.deferMode === "auto")
+            select(s.name);
+    for (const name of opts.protocolToolNames)
+        select(name);
+    for (const name of opts.builtinDeferNames ?? [])
+        select(name);
+    let gatedChars = 0;
+    for (const t of opts.fullTools)
+        if (gated.has(t.name))
+            gatedChars += inlinedChars(t);
+    const windowTokens = Math.max(0, opts.model.contextTokens ?? opts.model.contextWindow ?? 0);
+    const thresholdChars = Math.floor(windowTokens * DEFER_THRESHOLD_FRACTION) * CHARS_PER_TOKEN;
+    return { explicit, gated, gatedChars, thresholdChars, open: gatedChars >= thresholdChars };
+}
+export function classifyDeferred(opts) {
+    const gate = deferralGate(opts);
+    const deferred = new Set(gate.explicit);
+    if (gate.open)
+        for (const n of gate.gated)
+            deferred.add(n);
+    return deferred;
+}

package/dist/core/runner/tool-disclosure.d.ts

@@ -1,8 +1,5 @@
 import { type TSchema } from "typebox";
 import type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../../internal/harness-types.js";
-import type { Model } from "../../internal/llm.js";
-import type { ToolSpec } from "../types.js";
-import type { ToolFingerprintInput } from "../cache-break-detector.js";
 /**
  * Deferred-tool dynamic disclosure (design/36). A deployment with hundreds of tools / several MCP
  * servers can't inline every full JSON Schema into every request — turn-1 cache-creation tokens
@@ -56,39 +53,6 @@ export declare function deferHint(description: string, max?: number): string;
  * announcement, anywhere. A bare interpolation is a prompt-injection hole (council BUG, design/36).
  */
 export declare function safeName(name: string): string;
-/**
- * Decide which tool names are deferred. THIS CONTRACT IS THE SINGLE AUTHORITY on the default-mode
- * source list (TaskSpec/RunnerDeps JSDoc points here), so every arm the body implements is named:
- * deterministic by default = explicit `ToolSpec.defer === true`, plus every REMOTE-PROTOCOL tool name
- * (MCP servers AND A2A peers — most numerous / most drift-prone), plus `deferNames`, i.e. the
- * already-mounted wire names from `TaskSpec.deferTools` and from BUILT-INS that declare their own
- * `defer` (a built-in ToolSpec never reaches `specs`, so its declared deferral has to arrive here as a
- * mounted name — this is why the shared-memory pair defaults to deferred). With `deferMode: "auto"`, ADDITIONALLY
- * defer the remaining user tools when their combined inlined schema would exceed ~10% of the model's
- * context window — an explicit opt-in (council minor #6), because an implicit threshold makes the same
- * TaskSpec yield different tools[] across models/contexts. Explicit `defer` always wins — except
- * against an alwaysLoad pin (RB-400-a), which exempts a name from every deferral source.
- */
-export declare function classifyDeferred(opts: {
-    specs: ReadonlyArray<ToolSpec>;
-    /** Every namespaced tool a remote protocol materialized for this task (MCP servers AND A2A peers —
-     *  the caller unions them). The constant-defer arm is about the SHAPE of a remote roster (many tools,
-     *  schemas the deployment does not control, drift between tasks), which is the same for every protocol
-     *  in the table: naming one protocol here left the next one inlined by omission, with nobody deciding
-     *  that. Only an alwaysLoad pin exempts a name. */
-    protocolToolNames: ReadonlyArray<string>;
-    fullTools: ReadonlyArray<ToolFingerprintInput>;
-    deferMode?: "auto";
-    model: Model;
-    /** TaskSpec.deferTools — defer ALREADY-MOUNTED tools by wire name (built-ins included;
-     *  `ToolSpec.defer` only reaches caller specs). Caller pre-filters to mounted names. */
-    deferNames?: ReadonlyArray<string>;
-    /** RB-400-a — inline-pin names (`TaskSpec.alwaysLoadTools` + the MCP tools whose server declared
-     *  `_meta["anthropic/alwaysLoad"]`, caller-collected; A2A has no such per-skill declaration, so the
-     *  task-level list is a peer's only inline-keep channel): exempt from EVERY deferral source below.
-     *  `ToolSpec.alwaysLoad` rides the specs directly and needs no entry here. */
-    alwaysLoadNames?: ReadonlyArray<string>;
-}): Set<string>;
 /** Build the registry the search ranks over (deferred tools only — non-deferred are already visible). */
 export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, tools: ReadonlyArray<{
     name: string;

package/dist/core/runner/tool-disclosure.js

@@ -2,11 +2,8 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { defineTool, errorResult } from "../tools.js";
 import { formatZodValidationError, truncateError } from "../tool-errors.js";
-import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
 import { toolFace } from "../tool-catalog-entries.js";
 export const TOOL_SEARCH_NAME = "ToolSearch";
-const DEFER_AUTO_FRACTION = 0.1;
-const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
 export const TOOL_SEARCH_DEFAULT_MAX_RESULTS = 5;
 const MAX_QUERY_RESULTS = 25;
 export const DEFERRED_NO_PROGRESS_LIMIT = 3;
@@ -19,46 +16,6 @@ export function deferHint(description, max = 120) {
 export function safeName(name) {
     return name.replace(/[\x00-\x1f<>"`]/g, "");
 }
-function inlinedChars(t) {
-    let schema = "";
-    try {
-        schema = JSON.stringify(t.parameters) ?? "";
-    }
-    catch {
-        schema = "";
-    }
-    return t.description.length + schema.length;
-}
-export function classifyDeferred(opts) {
-    const pinned = new Set(opts.alwaysLoadNames ?? []);
-    for (const s of opts.specs) {
-        if (s.alwaysLoad === true)
-            pinned.add(s.name);
-    }
-    const deferred = new Set();
-    for (const s of opts.specs) {
-        if (s.defer === true && !pinned.has(s.name))
-            deferred.add(s.name);
-    }
-    for (const name of opts.protocolToolNames)
-        if (!pinned.has(name))
-            deferred.add(name);
-    for (const name of opts.deferNames ?? [])
-        if (!pinned.has(name))
-            deferred.add(name);
-    if (opts.deferMode === "auto") {
-        const callerNames = new Set(opts.specs.map((s) => s.name));
-        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name) && !pinned.has(t.name) && callerNames.has(t.name));
-        const inlineFace = opts.fullTools.filter((t) => !deferred.has(t.name));
-        const total = inlineFace.reduce((n, t) => n + inlinedChars(t), 0);
-        const window = (opts.model.contextTokens ?? opts.model.contextWindow ?? 0) * CHARS_PER_TOKEN;
-        if (window > 0 && total > DEFER_AUTO_FRACTION * window) {
-            for (const t of candidates)
-                deferred.add(t.name);
-        }
-    }
-    return deferred;
-}
 export function buildDeferredRegistry(deferred, tools) {
     const reg = new Map();
     for (const t of tools) {