@sema-agent/core 7.52.0 → 7.53.0

package/dist/core/runner/prepare-config-doors.js

@@ -3,17 +3,23 @@ import { assertContainmentFaceValue } from "../../tools/fs/index.js";
 import { MICRO_COMPACT_MACHINES } from "../context-edit.js";
 import { assertAddOnlySeats } from "../child-clamp-seats.js";
 import { assertNoRetiredRunnerDeps } from "./retired-runner-deps.js";
-import { resolveCheckpointStore } from "../checkpoint-store.js";
+import { recordedModeSeed, resolveCheckpointStore } from "../checkpoint-store.js";
+import { asResumeConfigRefusal, refusePermissionModeDoors } from "../mode-policy.js";
+import { resolveOutputStyleFrame } from "../output-style.js";
+import { screenUserAttachments } from "../user-attachment.js";
+import { screenUserInvokedSkills } from "../skill-grant.js";
+import { readSkillsSeat } from "./skills-seat.js";
+import { screenHandsBandOptions } from "../hands-band-screen.js";
 import { assertAutoConsolidationWirable } from "./memory-consolidation-driver.js";
 import { isModelPriced, malformedPricingField, modelCostToPricing } from "../pricing.js";
-import { preflightLockedConfig } from "../locked-config.js";
+import { ENTER_AS_IS, preflightLockedConfig } from "../locked-config.js";
 import { assertRetentionCapability } from "../retention.js";
 import { resolveModel, resolveTaskModel, roleModelIfSet } from "../roles.js";
 import { resolveSkillListingBudget } from "../skill-listing-budget.js";
 import { describeRejectedValue } from "../tool-search-setting.js";
 import { applyToolModelGate, assertRestoreGatedToolsValue, modelIdTail } from "../tool-model-gate.js";
 import { resolveUsageWindows } from "../usage-window-store.js";
-import { deriveAskEffective, resolveAskSeat, resolveQuestionSeam } from "../wiring-manifest.js";
+import { deriveAskEffective, resolveAskSeat, resolveQuestionSeam, screenApprovalReach } from "../wiring-manifest.js";
 import { resolveHost } from "../../prompt-assembly/select.js";
 import { resolvePromptBinding } from "../../prompt-assembly/overlay.js";
 import { assertPeerPresenceValue } from "../../agents/peer-directory.js";
@@ -48,8 +54,8 @@ export function limitConfigError(code, message) {
 export function resolveTaskLimits(limits) {
     if (limits === undefined)
         return undefined;
-    if (typeof limits !== "object" || Array.isArray(limits)) {
-        throw limitConfigError("config.limit_invalid", `TaskSpec.limits must be an object (got ${Array.isArray(limits) ? "an array" : typeof limits})`);
+    if (typeof limits !== "object" || limits === null || Array.isArray(limits)) {
+        throw limitConfigError("config.limit_invalid", `TaskSpec.limits must be an object (got ${limits === null ? "null" : Array.isArray(limits) ? "an array" : typeof limits})`);
     }
     const raw = limits;
     const legal = TASK_LIMIT_KEYS;
@@ -66,13 +72,13 @@ export function resolveTaskLimits(limits) {
         if (value === undefined)
             continue;
         if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-            throw limitConfigError("config.limit_invalid", `TaskSpec.limits.${key} must be a finite, non-negative number (got ${String(value)}) — an unevaluable ceiling is not a ceiling, and folding it to a default would run the task under a limit nobody chose.`);
+            throw limitConfigError("config.limit_invalid", `TaskSpec.limits.${key} must be a finite, non-negative number (got ${describeRejectedValue(value)}) — an unevaluable ceiling is not a ceiling, and folding it to a default would run the task under a limit nobody chose.`);
         }
     }
     const notice = raw.approachNotice;
     if (notice !== undefined && notice !== false) {
         if (typeof notice !== "object" || notice === null || Array.isArray(notice)) {
-            throw limitConfigError("config.limit_invalid", `TaskSpec.limits.approachNotice must be \`false\` or { at?: [first, second] } (got ${String(notice)})`);
+            throw limitConfigError("config.limit_invalid", `TaskSpec.limits.approachNotice must be \`false\` or { at?: [first, second] } (got ${describeRejectedValue(notice)})`);
         }
         const at = notice.at;
         if (at !== undefined) {
@@ -147,34 +153,51 @@ function resolveClearOnRejection(bag) {
     }
     return declared ?? true;
 }
-export function prepareConfigDoors(input) {
-    const { deps, sessions, resume, internals } = input;
-    let spec = input.spec;
-    assertNoRetiredRunnerDeps(deps);
-    assertPeerPresenceValue(spec.peerPresence);
-    assertRestoreGatedToolsValue(spec.restoreGatedTools);
-    const microCompactKnob = resolveMicroCompactKnob(deps.microCompact);
+function deploymentWord(raw, seat, words, absent, code, why) {
+    if (raw === undefined)
+        return absent;
+    const word = words.find((w) => w === raw);
+    if (word !== undefined)
+        return word;
+    const got = typeof raw === "string" ? JSON.stringify(raw.length > 64 ? `${raw.slice(0, 64)}…` : raw) : raw === null ? "null" : Array.isArray(raw) ? "an array" : typeof raw;
+    const spelled = words.map((w) => `"${w}"`);
+    throw limitConfigError(code, `RunnerDeps.${seat} must be ${spelled.slice(0, -1).join(", ")} or ${spelled.at(-1)} when present (got ${got}) — ${why}`);
+}
+export const checkpointStoreSeat = (spec) => (spec.checkpointStore !== undefined ? "taskConfig" : "deps");
+export function assertResumeConfigRecord(config) {
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+        throw limitConfigError("config.invalid_argument", `the resume's taskConfig must be an object — the TaskSpec the run suspended with (got ${config === null ? "null" : Array.isArray(config) ? "an array" : typeof config})`);
+    }
+}
+export function configValueDoors(input, enter = ENTER_AS_IS) {
+    const { spec, deps, resumeLeg, sessions } = input;
+    enter("deps", () => assertNoRetiredRunnerDeps(deps));
+    enter("taskConfig", () => assertPeerPresenceValue(spec.peerPresence));
+    enter("taskConfig", () => assertRestoreGatedToolsValue(spec.restoreGatedTools));
+    const microCompactKnob = enter("deps", () => resolveMicroCompactKnob(deps.microCompact));
+    const toolFaceListRefusal = (message, reason) => {
+        const e = new Error(message);
+        e.code = "config.tool_face_control";
+        e.detail = { reason };
+        return e;
+    };
     const assertToolNameListValue = (value, seat) => {
         if (value === undefined)
             return;
         if (!Array.isArray(value)) {
-            const e = new Error(`TaskSpec.${seat} must be an array of tool names or absent (got ${value === null ? "null" : typeof value}) — a garbage list must refuse loudly, never be read as "no ${seat}".`);
-            e.code = "config.tool_face_control";
-            throw e;
+            throw toolFaceListRefusal(`TaskSpec.${seat} must be an array of tool names or absent (got ${value === null ? "null" : typeof value}) — a garbage list must refuse loudly, never be read as "no ${seat}".`, "not_a_list");
         }
         const entries = value;
         for (const entry of entries) {
             if (typeof entry !== "string") {
-                const e = new Error(`TaskSpec.${seat} entries must be strings (got ${entry === null ? "null" : typeof entry}).`);
-                e.code = "config.tool_face_control";
-                throw e;
+                throw toolFaceListRefusal(`TaskSpec.${seat} entries must be strings (got ${entry === null ? "null" : typeof entry}).`, "not_a_string");
             }
         }
     };
-    assertToolNameListValue(spec.allowTools, "allowTools");
-    assertToolNameListValue(spec.excludeTools, "excludeTools");
-    assertToolNameListValue(spec.deferTools, "deferTools");
-    assertToolNameListValue(spec.alwaysLoadTools, "alwaysLoadTools");
+    enter("taskConfig", () => assertToolNameListValue(spec.allowTools, "allowTools"));
+    enter("taskConfig", () => assertToolNameListValue(spec.excludeTools, "excludeTools"));
+    enter("taskConfig", () => assertToolNameListValue(spec.deferTools, "deferTools"));
+    enter("taskConfig", () => assertToolNameListValue(spec.alwaysLoadTools, "alwaysLoadTools"));
     const toolFaceLists = {
         allow: spec.allowTools ? Object.freeze([...spec.allowTools]) : undefined,
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
@@ -186,116 +209,131 @@ export function prepareConfigDoors(input) {
                 ? Object.freeze([...spec.restoreGatedTools])
                 : undefined,
     };
-    const promptProfile = resolveModelPromptTraits({ id: "" }, spec, internals).promptProfile;
-    const promptHost = resolveHost(spec);
-    const promptBinding = resolvePromptBinding(spec);
-    if (spec.resumeAt !== undefined) {
-        if (resume) {
-            const e = new Error("resumeAt cannot be combined with a durable resume");
-            e.code = "resume_at.conflicts_resume";
+    const promptHost = enter("taskConfig", () => resolveHost(spec));
+    const promptBinding = enter("taskConfig", () => resolvePromptBinding(spec));
+    if (spec.resumeAt !== undefined)
+        enter("taskConfig", () => {
+            if (resumeLeg) {
+                const e = new Error("resumeAt cannot be combined with a durable resume");
+                e.code = "resume_at.conflicts_resume";
+                throw e;
+            }
+            if (!spec.sessionId) {
+                const e = new Error("resumeAt requires a sessionId (the session to branch)");
+                e.code = "resume_at.no_session";
+                throw e;
+            }
+        });
+    enter("taskConfig", () => assertContainmentFaceValue(spec.readFace, "read", "spec"));
+    enter("deps", () => assertContainmentFaceValue(deps.readFace, "read", "deps"));
+    enter("taskConfig", () => assertContainmentFaceValue(spec.writeFace, "write", "spec"));
+    enter("deps", () => assertContainmentFaceValue(deps.writeFace, "write", "deps"));
+    enter("taskConfig", () => assertAddOnlySeats(spec));
+    const memoryDelegationEvidence = enter("deps", () => deploymentWord(deps.memoryDelegationEvidence, "memoryDelegationEvidence", ["static-face", "attested-only"], "static-face", "config.memory_delegation_evidence", "an unevaluable evidence standard is refused loudly, never folded to either standard."));
+    const memoryProvenance = enter("deps", () => deploymentWord(deps.memoryProvenance, "memoryProvenance", ["off", "carry"], "carry", "config.memory_provenance", "an unevaluable provenance mode is refused loudly, never folded to either mode."));
+    const memoryCapturePolicy = enter("deps", () => deploymentWord(deps.memoryCapturePolicy, "memoryCapturePolicy", ["open", "governed", "capture-required"], "open", "config.memory_capture_policy", "an unevaluable capture posture is refused loudly, never folded to any posture (the fault arms differ per posture, so a guess would pick a polarity nobody configured)."));
+    enter("deps", () => assertAutoConsolidationWirable(deps));
+    if (spec.resumeAtMode !== undefined)
+        enter("taskConfig", () => {
+            if (spec.resumeAt === undefined) {
+                const e = new Error(`resumeAtMode ${describeRejectedValue(spec.resumeAtMode)} requires resumeAt (there is no branch target to position against)`);
+                e.code = "resume_at.mode_without_target";
+                throw e;
+            }
+            if (spec.resumeAtMode !== "at" && spec.resumeAtMode !== "before") {
+                const e = new Error(`resumeAtMode ${describeRejectedValue(spec.resumeAtMode)} is invalid — expected "at" (inclusive branch, the default) or "before" (exclusive branch)`);
+                e.code = "resume_at.invalid_mode";
+                throw e;
+            }
+        });
+    if (spec.toolMaterializeStrategy !== undefined && spec.toolMaterializeStrategy !== "swap" && spec.toolMaterializeStrategy !== "static")
+        enter("taskConfig", () => {
+            const e = new Error(`toolMaterializeStrategy must be "swap" or "static" (got ${JSON.stringify(spec.toolMaterializeStrategy)}).`);
+            e.code = "config.tool_materialize_invalid";
             throw e;
-        }
-        if (!spec.sessionId) {
-            const e = new Error("resumeAt requires a sessionId (the session to branch)");
-            e.code = "resume_at.no_session";
+        });
+    if (spec.memoryPersistenceCapable !== undefined && typeof spec.memoryPersistenceCapable !== "boolean")
+        enter("taskConfig", () => {
+            const e = new Error(`memoryPersistenceCapable must be a boolean when present (got ${JSON.stringify(spec.memoryPersistenceCapable)}) — a non-boolean would silently read as capable.`);
+            e.code = "config.memory_persistence_invalid";
             throw e;
-        }
-    }
-    assertContainmentFaceValue(spec.readFace, "read", "spec");
-    assertContainmentFaceValue(deps.readFace, "read", "deps");
-    assertContainmentFaceValue(spec.writeFace, "write", "spec");
-    assertContainmentFaceValue(deps.writeFace, "write", "deps");
-    assertAddOnlySeats(spec);
-    const memoryDelegationEvidenceRaw = deps.memoryDelegationEvidence;
-    if (memoryDelegationEvidenceRaw !== undefined && memoryDelegationEvidenceRaw !== "static-face" && memoryDelegationEvidenceRaw !== "attested-only") {
-        const evidence = memoryDelegationEvidenceRaw;
-        const got = typeof evidence === "string"
-            ? JSON.stringify(evidence.length > 64 ? `${evidence.slice(0, 64)}…` : evidence)
-            : evidence === null
-                ? "null"
-                : Array.isArray(evidence)
-                    ? "an array"
-                    : typeof evidence;
-        const e = new Error(`RunnerDeps.memoryDelegationEvidence must be "static-face" or "attested-only" when present (got ${got}) — ` +
-            `an unevaluable evidence standard is refused loudly, never folded to either standard.`);
-        e.code = "config.memory_delegation_evidence";
-        throw e;
-    }
-    const memoryDelegationEvidence = memoryDelegationEvidenceRaw === "attested-only" ? "attested-only" : "static-face";
-    const memoryProvenanceRaw = deps.memoryProvenance;
-    if (memoryProvenanceRaw !== undefined && memoryProvenanceRaw !== "off" && memoryProvenanceRaw !== "carry") {
-        const got = typeof memoryProvenanceRaw === "string"
-            ? JSON.stringify(memoryProvenanceRaw.length > 64 ? `${memoryProvenanceRaw.slice(0, 64)}…` : memoryProvenanceRaw)
-            : memoryProvenanceRaw === null
-                ? "null"
-                : Array.isArray(memoryProvenanceRaw)
-                    ? "an array"
-                    : typeof memoryProvenanceRaw;
-        const e = new Error(`RunnerDeps.memoryProvenance must be "off" or "carry" when present (got ${got}) — ` + `an unevaluable provenance mode is refused loudly, never folded to either mode.`);
-        e.code = "config.memory_provenance";
-        throw e;
-    }
-    const memoryProvenance = memoryProvenanceRaw === "off" ? "off" : "carry";
-    const memoryCapturePolicyRaw = deps.memoryCapturePolicy;
-    if (memoryCapturePolicyRaw !== undefined && memoryCapturePolicyRaw !== "open" && memoryCapturePolicyRaw !== "governed" && memoryCapturePolicyRaw !== "capture-required") {
-        const got = typeof memoryCapturePolicyRaw === "string"
-            ? JSON.stringify(memoryCapturePolicyRaw.length > 64 ? `${memoryCapturePolicyRaw.slice(0, 64)}…` : memoryCapturePolicyRaw)
-            : memoryCapturePolicyRaw === null
-                ? "null"
-                : Array.isArray(memoryCapturePolicyRaw)
-                    ? "an array"
-                    : typeof memoryCapturePolicyRaw;
-        const e = new Error(`RunnerDeps.memoryCapturePolicy must be "open", "governed" or "capture-required" when present (got ${got}) — ` +
-            `an unevaluable capture posture is refused loudly, never folded to any posture (the fault arms differ per posture, so a guess would pick a polarity nobody configured).`);
-        e.code = "config.memory_capture_policy";
-        throw e;
-    }
-    const memoryCapturePolicy = memoryCapturePolicyRaw === "governed" ? "governed" : memoryCapturePolicyRaw === "capture-required" ? "capture-required" : "open";
-    assertAutoConsolidationWirable(deps);
-    if (spec.resumeAtMode !== undefined) {
-        if (spec.resumeAt === undefined) {
-            const e = new Error(`resumeAtMode "${spec.resumeAtMode}" requires resumeAt (there is no branch target to position against)`);
-            e.code = "resume_at.mode_without_target";
+        });
+    if (spec.toolMaterializeStrategy === "static" && spec.deferSelfResolve === false)
+        enter("taskConfig", () => {
+            const e = new Error(`toolMaterializeStrategy "static" cannot be combined with deferSelfResolve: false — with the direct-call ` +
+                `lane disabled a placeholder is never swapped and never self-resolves, so no deferred tool could ever be ` +
+                `called. Use "swap", or leave deferSelfResolve on.`);
+            e.code = "config.tool_materialize_unreachable";
             throw e;
-        }
-        if (spec.resumeAtMode !== "at" && spec.resumeAtMode !== "before") {
-            const e = new Error(`resumeAtMode "${String(spec.resumeAtMode)}" is invalid — expected "at" (inclusive branch, the default) or "before" (exclusive branch)`);
-            e.code = "resume_at.invalid_mode";
-            throw e;
-        }
-    }
-    if (spec.toolMaterializeStrategy !== undefined && spec.toolMaterializeStrategy !== "swap" && spec.toolMaterializeStrategy !== "static") {
-        const e = new Error(`toolMaterializeStrategy must be "swap" or "static" (got ${JSON.stringify(spec.toolMaterializeStrategy)}).`);
-        e.code = "config.tool_materialize_invalid";
-        throw e;
-    }
-    if (spec.memoryPersistenceCapable !== undefined && typeof spec.memoryPersistenceCapable !== "boolean") {
-        const e = new Error(`memoryPersistenceCapable must be a boolean when present (got ${JSON.stringify(spec.memoryPersistenceCapable)}) — a non-boolean would silently read as capable.`);
-        e.code = "config.memory_persistence_invalid";
-        throw e;
-    }
-    if (spec.toolMaterializeStrategy === "static" && spec.deferSelfResolve === false) {
-        const e = new Error(`toolMaterializeStrategy "static" cannot be combined with deferSelfResolve: false — with the direct-call ` +
-            `lane disabled a placeholder is never swapped and never self-resolves, so no deferred tool could ever be ` +
-            `called. Use "swap", or leave deferSelfResolve on.`);
-        e.code = "config.tool_materialize_unreachable";
-        throw e;
-    }
-    if (resume === undefined && spec.objective.trim().length === 0) {
+        });
+    if (!resumeLeg && (spec.objective ?? "").trim().length === 0) {
         const e = new Error("TaskSpec.objective is empty — a task needs an instruction (an empty user message is rejected by strict model endpoints and would fail every later request of the session).");
         e.code = "config.empty_objective";
         throw e;
     }
-    const lockedPreflight = preflightLockedConfig(spec, deps);
-    assertRetentionCapability({
-        policy: deps.retentionPolicy,
-        locked: lockedPreflight.lockedKeys.has("retentionPolicy"),
+    const lockedPreflight = preflightLockedConfig(spec, deps, enter);
+    const declaredSkills = spec.skills;
+    const skills = declaredSkills === undefined ? undefined : enter("taskConfig", () => readSkillsSeat(declaredSkills));
+    enter("deps", () => screenHandsBandOptions(deps.hands));
+    const skillListingSeats = { fraction: spec.skillListingBudgetFraction, maxDescChars: spec.skillListingMaxDescChars };
+    enter("taskConfig", () => resolveSkillListingBudget(skillListingSeats));
+    enter("taskConfig", () => resolveTaskLimits(spec.limits));
+    enter("taskConfig", () => resolveAttachmentsConfig(spec.attachments));
+    if (spec.resourceSuspend !== undefined)
+        enter("taskConfig", () => {
+            const declared = spec.resourceSuspend;
+            if (typeof declared !== "object" || declared === null || Array.isArray(declared)) {
+                throw limitConfigError("config.limit_invalid", `TaskSpec.resourceSuspend must be an object carrying a non-empty \`scope\` (got ${declared === null ? "null" : Array.isArray(declared) ? "an array" : typeof declared}) — it is the allocation every resource checkpoint is filed under.`);
+            }
+            const rsus = declared;
+            if (typeof rsus.scope !== "string" || rsus.scope === "") {
+                throw limitConfigError("config.limit_invalid", `TaskSpec.resourceSuspend.scope must be a non-empty string (got ${describeRejectedValue(rsus.scope)}) — it is the multi-tenant isolation key every resource checkpoint is filed under.`);
+            }
+            for (const key of ["totalBudgetUsd", "totalTokens", "maxSlices", "ttlMs"]) {
+                const value = rsus[key];
+                if (value === undefined)
+                    continue;
+                if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+                    throw limitConfigError("config.limit_invalid", `TaskSpec.resourceSuspend.${key} must be a finite, non-negative number (got ${describeRejectedValue(value)}) — an unevaluable allocation is not an allocation, and a NaN here blinds even the validated per-slice window.`);
+                }
+            }
+        });
+    const usageWindows = enter("deps", () => resolveUsageWindows(deps.usageWindows));
+    const taskGuardrail = spec.limits?.brainCallGuardrailMs;
+    const brainCallGuardrailMs = enter(taskGuardrail != null ? "taskConfig" : "deps", () => resolveBrainCallGuardrailMs(taskGuardrail ?? deps.brainCallGuardrailMs));
+    const checkpointStore = enter(checkpointStoreSeat(spec), () => resolveCheckpointStore(spec, deps));
+    const taskStore = checkpointStoreSeat(spec) === "taskConfig" ? checkpointStore : undefined;
+    const retention = { policy: deps.retentionPolicy, locked: lockedPreflight.lockedKeys.has("retentionPolicy") };
+    enter("deps", () => assertRetentionCapability({
+        ...retention,
         stores: [
             { name: "sessionStore", store: sessions },
-            { name: "checkpointStore", store: resolveCheckpointStore(spec, deps) },
+            { name: "checkpointStore", store: taskStore === undefined ? checkpointStore : undefined },
             { name: "toolResultStore", store: deps.toolResultStore },
         ],
+    }));
+    if (taskStore !== undefined)
+        enter("taskConfig", () => assertRetentionCapability({ ...retention, stores: [{ name: "checkpointStore", store: taskStore }] }));
+    return { toolFaceLists, promptHost, promptBinding, lockedPreflight, skillListingSeats, skills, microCompactKnob, memoryDelegationEvidence, memoryProvenance, memoryCapturePolicy, usageWindows, brainCallGuardrailMs };
+}
+export function refuseResumeDoors(config, recordedGate, deps, sessions) {
+    asResumeConfigRefusal("taskConfig", () => {
+        refusePermissionModeDoors(config);
+        resolveOutputStyleFrame(config.outputStyle);
+        screenApprovalReach(config.approvalReach);
+        screenUserInvokedSkills(config);
+        screenUserAttachments(config.userAttachments, { resumeLeg: true });
     });
+    const { lockedPreflight, skills } = configValueDoors({ spec: config, deps, resumeLeg: true, sessions }, asResumeConfigRefusal);
+    asResumeConfigRefusal("inheritedGate", () => void recordedModeSeed(recordedGate));
+    return { ...config, ...(config.mcp !== undefined ? { mcp: lockedPreflight.mcp ?? [] } : {}), ...(config.a2a !== undefined ? { a2a: lockedPreflight.a2a ?? [] } : {}), skills };
+}
+export function prepareConfigDoors(input) {
+    const { deps, sessions, resume, internals } = input;
+    let spec = input.spec;
+    const { toolFaceLists, promptHost, promptBinding, lockedPreflight, skillListingSeats, skills, microCompactKnob, memoryDelegationEvidence, memoryProvenance, memoryCapturePolicy, usageWindows, brainCallGuardrailMs } = configValueDoors({ spec, deps, resumeLeg: resume !== undefined, sessions });
+    spec = Object.create(Object.getPrototypeOf(spec), { ...Object.getOwnPropertyDescriptors(spec), skills: { value: skills, enumerable: skills !== undefined, writable: false, configurable: false } });
+    const promptProfile = resolveModelPromptTraits({ id: "" }, spec, internals).promptProfile;
     const resolvedInteractionPosture = spec.interactionPosture ?? internals?.parentInteractionPosture ?? deps.interactionPosture;
     const askSeat = resolveAskSeat(spec, deps);
     {
@@ -344,25 +382,7 @@ export function prepareConfigDoors(input) {
             }
         }
     }
-    resolveTaskLimits(spec.limits);
-    resolveAttachmentsConfig(spec.attachments);
-    if (spec.resourceSuspend !== undefined) {
-        const rsus = spec.resourceSuspend;
-        if (typeof rsus.scope !== "string" || rsus.scope === "") {
-            throw limitConfigError("config.limit_invalid", `TaskSpec.resourceSuspend.scope must be a non-empty string (got ${String(rsus.scope)}) — it is the multi-tenant isolation key every resource checkpoint is filed under.`);
-        }
-        for (const key of ["totalBudgetUsd", "totalTokens", "maxSlices", "ttlMs"]) {
-            const value = rsus[key];
-            if (value === undefined)
-                continue;
-            if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-                throw limitConfigError("config.limit_invalid", `TaskSpec.resourceSuspend.${key} must be a finite, non-negative number (got ${String(value)}) — an unevaluable allocation is not an allocation, and a NaN here blinds even the validated per-slice window.`);
-            }
-        }
-    }
-    const usageWindows = resolveUsageWindows(deps.usageWindows);
     const brainCallGuardrailRef = {};
-    const brainCallGuardrailMs = resolveBrainCallGuardrailMs(spec.limits?.brainCallGuardrailMs ?? deps.brainCallGuardrailMs);
     const mountedRoster = spec.tools;
     if (spec.agents !== undefined && spec.agents.length > 0) {
         const pool = spec.tools ?? [];
@@ -427,11 +447,7 @@ export function prepareConfigDoors(input) {
     if (gateDecision.survivors !== undefined) {
         spec = { ...spec, tools: gateDecision.survivors };
     }
-    const skillListingBudget = resolveSkillListingBudget({
-        fraction: spec.skillListingBudgetFraction,
-        maxDescChars: spec.skillListingMaxDescChars,
-        model,
-    });
+    const skillListingBudget = resolveSkillListingBudget({ ...skillListingSeats, model });
     const modelGate = Object.freeze({
         removedByClass: gateDecision.removedByClass,
         unknownClasses: gateDecision.unknownClasses,

package/dist/core/runner/prepare-defer-classify.js

@@ -9,6 +9,7 @@ import { classifyDeferredWithGate } from "./tool-defer-gate.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { resolveToolSearch, toolSearchSettingOf } from "../tool-search-setting.js";
 import { RosterBuilder } from "../tool-roster.js";
+import { valveLeaves } from "../../agents/tool-filter.js";
 function explicitlyDeferredMemoryTrio(mounted, roster, callerDeferNames) {
     return mounted ? MEMORY_ENGINE_TOOL_NAMES.filter((n) => roster.some((t) => t.name === n) && (callerDeferNames ?? []).includes(n)) : [];
 }
@@ -19,12 +20,8 @@ export function prepareDeferClassify(input) {
     const { spec, deps, roster, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
     const tools = roster.tools;
     let memoryBlock = input.memoryBlock;
-    if (spec.excludeAllTools === true) {
-        roster.unmountWhere(() => true);
-    }
-    else {
-        roster.unmountWhere((t) => !toolFaceSnapshot.selector.admits(t));
-    }
+    const leaves = valveLeaves(spec, toolFaceSnapshot.selector);
+    roster.unmountWhere((t) => !leaves(t));
     if (handsEnabled) {
         const fullShellOnRoster = tools.some((t) => t.name === "Bash" && getToolContract(t, "core").contractId === FULL_SHELL_CONTRACT_ID);
         if (fullShellOnRoster !== fullShellReachable) {
@@ -48,7 +45,7 @@ export function prepareDeferClassify(input) {
         .map((t) => t.name);
     const resolvedToolSearch = resolveToolSearch(deps.toolSearch);
     const toolSearchSeat = toolSearchSettingOf(resolvedToolSearch);
-    const toolSearchAdmitted = toolFaceSnapshot.selector.admits({ name: TOOL_SEARCH_NAME });
+    const toolSearchAdmitted = leaves({ name: TOOL_SEARCH_NAME });
     const classifyDeferredOverFace = (face, builtinDeferNames) => {
         const mounted = new Set(face.map((t) => t.name));
         const classified = classifyDeferredWithGate({

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -30,11 +30,11 @@ export interface PrepareDelegationSurfaceInput {
     /** borrowed-readonly — the REBOUND spec. Read: `tools` (the shadow checks and the revival spawner's delegation-tool
      *  lookup), `oneShot` (the read/kill faces' completion promises), `retainBackgroundProcesses` (the Monitor receipt),
      *  `handsReadOnly` is NOT read here (the hands mount decided the surface). Never mutated. */
-    spec: Pick<TaskSpec, "tools" | "oneShot" | "retainBackgroundProcesses">;
+    spec: Pick<TaskSpec, "tools" | "oneShot" | "retainBackgroundProcesses" | "excludeAllTools">;
     /** borrowed-readonly — the deployment seats the mounts read: `workflowRunStore` / `backgroundAgentStore` / `mailboxStore` (the
      *  read/kill faces and the tier-3 revival seams), `rosterStore`, `peerLane`, `peerDirectory`, `onNotice`,
      *  `onBackgroundChildEvent`, `tracer`. */
-    deps: Pick<RunnerDeps, "workflowRunStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "peerLane" | "peerDirectory" | "onNotice" | "onBackgroundChildEvent" | "tracer">;
+    deps: Pick<RunnerDeps, "workflowRunStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "peerLane" | "peerDirectory" | "principalInboxConsumer" | "onNotice" | "onBackgroundChildEvent" | "tracer">;
     /** borrowed-readonly — the trusted spawn-side channel: `parentNotify` (the delegated-child door), the uplink / sibling /
      *  identity seats the SendMessage mount forwards, `onTaskNotification`, `onSubagentSpawn`. Never mutated. */
     internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "uplinkSessionId" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;

package/dist/core/runner/prepare-delegation-surface.js

@@ -1,8 +1,9 @@
 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 { listAgentsMountable, mountListAgents, peerLaneSendMessageSeats } from "../../agents/peer-session-drain.js";
+import { listAgentsMountable, mountListAgents, peerLaneSendMessageSeats, terminalsDrainPrincipalInbox } from "../../agents/peer-session-drain.js";
 import { resolvePeerLaneConfig } from "../../agents/peer-admission.js";
 import { createReadInboxTool, READ_INBOX_TOOL_NAME } from "../../agents/read-inbox-tool.js";
+import { valveLeaves } from "../../agents/tool-filter.js";
 import { createMonitorTool } from "../../tools/monitor.js";
 import { createWorktreeTools } from "../../tools/worktree.js";
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
@@ -15,6 +16,7 @@ export function prepareDelegationSurface(input) {
     const { spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, taskRootCanonical, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, sessionBox, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, checkpointSeat, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle } = input;
     let worktreeSessionRef;
     const delegationSurfaceActive = backgroundTaskToolsActive || workflowToolsActive;
+    const leaves = valveLeaves(spec, toolFaceSnapshot.selector);
     let sendMessageTier;
     if (delegationSurfaceActive || internals?.parentNotify !== undefined || peerLaneActive) {
         if (delegationSurfaceActive) {
@@ -54,7 +56,7 @@ export function prepareDelegationSurface(input) {
                 ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
                 ...(deps.mailboxStore !== undefined ? { mailbox: deps.mailboxStore } : {}),
                 ...(reviveSpawn !== undefined ? { reviveSpawn } : {}),
-                ...(peerLaneActive ? peerLaneSendMessageSeats({ peerDirectory: deps.peerDirectory, sessionId, scope: taskScope, ...(internals?.explicitAgentName !== undefined ? { name: internals.explicitAgentName } : {}), refs: peerLaneRefs, listingMounted: listAgentsMountable({ selector: toolFaceSnapshot.selector, specTools: spec.tools ?? [] }) }) : {}),
+                ...(peerLaneActive ? peerLaneSendMessageSeats({ peerDirectory: deps.peerDirectory, sessionId, scope: taskScope, ...(internals?.explicitAgentName !== undefined ? { name: internals.explicitAgentName } : {}), refs: peerLaneRefs, listingMounted: listAgentsMountable({ leaves, specTools: spec.tools ?? [] }) }) : {}),
                 onNotifyError: (f) => emitTrace(deps.tracer, () => ({ kind: "observer.notify_failed", version: 1, taskId: hostTaskId, site: f.site, message: f.error.message, ts: Date.now() })),
                 onTranscriptIntegrityGap: (handle, scope) => deliverEngineNotice(deps.onNotice, {
                     code: "delegation.transcript_integrity",
@@ -80,11 +82,11 @@ export function prepareDelegationSurface(input) {
             }
         }
     }
-    if (sessionBox !== undefined && internals?.onTaskNotification !== undefined && toolFaceSnapshot.selector.admits({ name: READ_INBOX_TOOL_NAME }) && !(spec.tools ?? []).some((t) => t.name === READ_INBOX_TOOL_NAME)) {
+    if (sessionBox !== undefined && internals?.onTaskNotification !== undefined && leaves({ name: READ_INBOX_TOOL_NAME }) && !(spec.tools ?? []).some((t) => t.name === READ_INBOX_TOOL_NAME)) {
         toolEffects.set(READ_INBOX_TOOL_NAME, "read");
-        roster.mount(firstPartyOffload(createReadInboxTool({ pull: () => peerLaneRefs.pull })), { source: "builtin", mountedBy: "peerLane" });
+        roster.mount(firstPartyOffload(createReadInboxTool({ pull: () => peerLaneRefs.pull, ...(terminalsDrainPrincipalInbox(deps) ? { coversPrincipalInbox: true } : {}) })), { source: "builtin", mountedBy: "peerLane" });
     }
-    const listAgents = (peerLaneActive || delegationSurfaceActive) && peerSendMessageBuiltIn && listAgentsMountable({ selector: toolFaceSnapshot.selector, specTools: spec.tools ?? [] }) ? mountListAgents({ ...(peerLaneActive ? { peerDirectory: deps.peerDirectory } : {}), freshWindowMs: resolvePeerLaneConfig(deps.peerLane, deps.onNotice).listingFreshWindowMs, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), ...(sendMessageTier !== undefined ? { continuationTier: sendMessageTier } : {}), ...(checkpointSeat !== undefined ? { readSeats: { checkpointSeat } } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
+    const listAgents = (peerLaneActive || delegationSurfaceActive) && peerSendMessageBuiltIn && listAgentsMountable({ leaves, specTools: spec.tools ?? [] }) ? mountListAgents({ ...(peerLaneActive ? { peerDirectory: deps.peerDirectory } : {}), freshWindowMs: resolvePeerLaneConfig(deps.peerLane, deps.onNotice).listingFreshWindowMs, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), ...(sendMessageTier !== undefined ? { continuationTier: sendMessageTier } : {}), ...(checkpointSeat !== undefined ? { readSeats: { checkpointSeat } } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
     if (listAgents !== undefined)
         roster.mount(firstPartyOffload(listAgents), { source: "builtin", mountedBy: "peerLane" });
     if (backgroundTaskToolsActive) {

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

@@ -88,7 +88,7 @@ export interface PrepareHandsReadFaceInput {
     /** borrowed-readonly — the task-spec seats this phase reads, as a Pick over the SAME spec object
      *  (R-4). `tools` feeds only the band shadow check; `envFacts` only the advertised scratchpad;
      *  `retainBackgroundProcesses` only the band's retain lane (Bash's lifetime sentence + row stamp). */
-    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "writeFace" | "oneShot" | "resumeAt" | "retainBackgroundProcesses" | "sessionId" | "tools">;
+    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "writeFace" | "oneShot" | "resumeAt" | "retainBackgroundProcesses" | "sessionId" | "tools" | "excludeAllTools">;
     /** borrowed-readonly — the deployment seats this phase reads, as a Pick over the SAME deps
      *  object (R-4: `deps.onError?.()` keeps its receiver; a new deps read must widen this Pick).
      *  `readDenyBuiltinTiers`/`readDenyBuiltinExclude` are SNAPSHOTTED before the first await that

package/dist/core/runner/prepare-hands-readface.js

@@ -21,6 +21,7 @@ import { RosterBuilder } from "../tool-roster.js";
 import { unionAddOnly } from "../child-clamp-seats.js";
 import { assertStringArraySeat } from "../read-face-seats.js";
 import { modePolicyOf } from "../mode-policy.js";
+import { valveLeaves } from "../../agents/tool-filter.js";
 const faceClampAnnouncedSinks = { read: new WeakSet(), write: new WeakSet() };
 const faceClampConsoleAnnounced = { read: false, write: false };
 function announceDeploymentFaceClamp(kind, sink) {
@@ -370,7 +371,7 @@ export async function prepareHandsMount(input) {
                 return memoryWriteGate?.(w);
             },
             mountBackgroundTaskTools: false,
-            monitorToolActive: backgroundTaskToolsActive && toolFaceSnapshot.selector.admits({ name: "Monitor" }),
+            monitorToolActive: backgroundTaskToolsActive && valveLeaves(spec, toolFaceSnapshot.selector)({ name: "Monitor" }),
         });
         {
             const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));

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

@@ -14,6 +14,7 @@ import { SessionModeSeats } from "./session-mode-seats.js";
 import { recordedModeSeed } from "../checkpoint-store.js";
 import { frozenSkillGrants } from "../skill-grant.js";
 import { attachRebuiltDenialTrackers, createDenialLimitStop } from "./denial-limit-arms.js";
+import { valveLeaves } from "../../agents/tool-filter.js";
 export function prepareInheritedGate(input) {
     const { spec, deps, askSeat, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, pathRuleAnchors, toolFaceSnapshot, mountsCallerTool, promptProfile, resolvedInteractionPosture, permissionModeSeat, handsEnabled, reportUsage, harnessRef, skillGrants, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun } = input;
     const liveInheritedGate = internals?.inheritedGate;
@@ -192,8 +193,7 @@ export function prepareInheritedGate(input) {
     const fullShellReachable = handsEnabled &&
         !(executionEnv instanceof StubExecutionEnv) &&
         spec.handsReadOnly !== true &&
-        spec.excludeAllTools !== true &&
-        toolFaceSnapshot.selector.admits({ name: "Bash" });
+        valveLeaves(spec, toolFaceSnapshot.selector)({ name: "Bash" });
     const { gateStopRef, stopForDenialLimit } = createDenialLimitStop({ sessionId, runId, onNotice: deps.onNotice, abort: abortRun });
     const delegationEntryCapsResolved = resolveDelegationEntryCaps(deps.delegationEntryCaps);
     const enrichSpecToolCtx = (ctx) => {

package/dist/core/runner/prepare-listings.d.ts

@@ -5,7 +5,7 @@ import type { ResolvedSkillListingBudget } from "../skill-listing-budget.js";
 export interface PrepareListingsInput {
     /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `tools` (the roster-bearing delegation tool, by its `agentListing`
      *  marker), `sessionId` (continuation ⇒ seeded/removal projections), `attachments` (the two opt-outs). Never mutated. */
-    spec: Pick<TaskSpec, "agents" | "tools" | "sessionId" | "attachments">;
+    spec: Pick<TaskSpec, "agents" | "tools" | "sessionId" | "attachments" | "excludeAllTools">;
     /** borrowed-readonly — the once-per-session ledger: its deduplicated operator sink (`onError`) and
      *  the whole announced snapshot (`arms()`) the mirror is seeded from. */
     onceLedger: AnnounceOnceSink & {

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

@@ -1,17 +1,19 @@
 import { formatLocalDate } from "../../prompts/default.js";
+import { valveLeaves } from "../../agents/tool-filter.js";
 import { SKILL_TOOL_NAME } from "./synthetic-tools.js";
 import { renderAgentListingDelta } from "./turn-attachments.js";
 export function prepareListings(input) {
     const { spec, onceLedger, sessionId, toolFaceSnapshot, activeTools, deferred, resume, skillsListing, listingBudget, listingRideRef, renderWithDate, envFacts, tzValid, userTz, dateAnchor } = input;
     const rosterBearingSpec = (spec.tools ?? []).find((t) => t.agentListing !== undefined && t.agentListing.length > 0);
+    const leaves = valveLeaves(spec, toolFaceSnapshot.selector);
     const rosterFaceDeferred = rosterBearingSpec !== undefined &&
-        toolFaceSnapshot.selector.admits(rosterBearingSpec) &&
+        leaves(rosterBearingSpec) &&
         (toolFaceSnapshot.defer?.includes(rosterBearingSpec.name) ?? false) &&
         deferred.has(rosterBearingSpec.name) &&
         !activeTools.has(rosterBearingSpec.name);
     const agentListingSpec = rosterBearingSpec !== undefined &&
         !rosterFaceDeferred &&
-        toolFaceSnapshot.selector.admits(rosterBearingSpec)
+        leaves(rosterBearingSpec)
         ? rosterBearingSpec
         : undefined;
     const agentListing = agentListingSpec

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

@@ -12,12 +12,8 @@
  * installs, which run at tool-call time), so the phase adds no yield between the deferred classification before it
  * and the prompt assembly after it (a stretch with no await is extracted as a sync function).
  * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
- *
- * One read changed spelling and nothing else: the declared-class announcement read `mcp?.statuses` while `mcp` had
- * long been the protocol-tools phase's non-null handle; the optional chain was dead and is now the plain member read.
  */
 import type { LockedPreflight } from "../locked-config.js";
-import type { MaterializedMcp } from "../mcp.js";
 import { type DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { Prepared, RunInternals } from "./contracts.js";
@@ -40,8 +36,6 @@ export interface PrepareMemoryEngineSessionInput {
     lockedPreflight: Pick<LockedPreflight, "mcp">;
     /** borrowed-readonly — the run's MCP mount, read at call time (present iff the run declared a server): the children a delegation tool spawns inherit it, so its tools are rows of their pool. */
     mountedMcp?: () => import("../mounted-mcp.js").MountedMcp;
-    /** borrowed-readonly — the materialized MCP handle; only `statuses` (the announcement's mounted-tool count). */
-    mcp: Pick<MaterializedMcp, "statuses">;
     /** borrowed-readonly — the acquired session id (notice detail). */
     sessionId: string;
     /** borrowed-readonly — the run's invocation id (notice detail; the once-per-leg claims are per-RUN claims). */