@sema-agent/core 7.48.0 → 7.49.0

package/dist/agents/subagent.js

@@ -1,7 +1,8 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { applyParentSpecSeat, memoryTurnedOff, parentSpecSeatOfCtx } from "../core/parent-spec-seat.js";
-import { childClampSeats, engineHeadlessLegSeats, postureUnderClamps } from "../core/child-clamp-seats.js";
+import { assertClampRecord, childClampSeats, clampSeatsOf, clampSourceOf, engineHeadlessLegSeats, foldClampSources, postureUnderClamps } from "../core/child-clamp-seats.js";
+import { assertNoRetiredKeys } from "../core/retired-keys.js";
 import { stripSpawnTurnQuestionFace } from "../core/ask-question.js";
 import { withDelegationProvenance } from "../core/tool-policy.js";
 import { errorResult } from "../core/tools.js";
@@ -15,13 +16,15 @@ export { childThinkingSeat, deploymentSubagentThinking, deploymentSubagentTierMo
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
 import { OFFLOAD_TOOL_NAME } from "../core/tool-result-store.js";
-import { readToolNameList, resolveAgentToolSubset, snapshotDefinitionLists, snapshotToolNameList, toolNameAllowed, toolNameListFlaw } from "./tool-filter.js";
+import { compileToolSelector, delegationListWhere, snapshotDefinitionLists, toolListsDigest, toolNameAllowed, toolNameListFlaw } from "./tool-filter.js";
+import { readToolNameList, snapshotToolNameList } from "../core/tool-name-list.js";
 import { EXTRA_TOOL_NAMES_CODE, delegationPoolFace, extraToolNamesError, firstUndeclaredExtraTool, readExtraToolNames } from "./extra-tool-names.js";
 import { builtinAgentDefinitions } from "./builtin-agents.js";
+import { normalizePeerName, reservedPeerNameReason } from "./cross-session-ref.js";
 import { SUBAGENT_PROMPT } from "../prompts/default.js";
 import { hasSessionFork } from "../core/session.js";
 import { isDurablePause, pauseFamily } from "./suspend-guard.js";
-import { terminalProjection } from "../core/runner/terminal-projection.js";
+import { childRejection, childTerminalFace, childThrownText } from "./child-failure.js";
 import { forwardSafely } from "../core/runner/forward-sink.js";
 import { delimitUntrusted, inlineUntrusted } from "../core/untrusted-text.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
@@ -70,7 +73,7 @@ import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "./l
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
-import { inheritedChildPool, teammateInheritedFamily } from "./inherited-tool-pool.js";
+import { inheritedChildPool, inheritedMcpDeclarations } from "./inherited-tool-pool.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
 const BG_AGENT_RESULT_MAX = 4_000;
 const BG_AGENT_RESULT_FULL_MAX = 200_000;
@@ -388,7 +391,7 @@ function thrownErrorCode(e) {
     return typeof code === "string" ? code : undefined;
 }
 export function completedAgentCard(child, extras) {
-    const face = terminalProjection(child.terminal);
+    const face = childTerminalFace(child.terminal);
     return {
         type: "agent",
         ...(extras.attestation !== undefined ? { attestation: extras.attestation } : {}),
@@ -492,7 +495,13 @@ function createSteerHandle(stream, parentToolCallId, agentName, settled, retain)
             : {}),
     };
 }
+const RETIRED_RESUME_CLAMP_KEYS = Object.freeze({
+    "currentClamps.readFaceRoots": 'the waker\'s read-face clamp is `currentClamps.readFace: "roots"` (the clamp table\'s own seat name)',
+    "currentClamps.writeFaceRoots": 'the waker\'s write-face clamp is `currentClamps.writeFace: "roots"` (the clamp table\'s own seat name)',
+});
 export function createSubagentResume(deps) {
+    assertNoRetiredKeys(deps, RETIRED_RESUME_CLAMP_KEYS, "createSubagentResume");
+    assertClampRecord(deps.currentClamps, "createSubagentResume currentClamps", undefined, ["memoryOff"]);
     const notifier = createSafeNotifier(deps.onNotifyError !== undefined ? { onError: deps.onNotifyError } : undefined);
     const resume = async (content) => {
         const ledger = deps.ledger;
@@ -551,26 +560,16 @@ export function createSubagentResume(deps) {
             marker = `resume-${markerFragment()}`;
             entry.resumeCount += 1;
             entry.cycleSeq += 1;
+            const wakeClamps = foldClampSources(entry.specSnapshot, deps.currentClamps);
             const resumeSpec = {
                 ...entry.specSnapshot,
                 objective: createResumePrompt(marker, content, deps.peerOrigin !== undefined ? "peer" : "operator"),
                 sessionId: entry.childSessionId,
                 requireExistingSession: true,
                 ...(deps.currentOnQuestion !== undefined ? { onQuestion: deps.currentOnQuestion } : {}),
-                ...childClampSeats({
-                    handsReadOnly: entry.specSnapshot.handsReadOnly === true || deps.currentClamps?.handsReadOnly === true,
-                    interactiveTools: entry.specSnapshot.interactiveTools === false || deps.currentClamps?.interactiveTools === false ? false : undefined,
-                    approvalReach: entry.specSnapshot.approvalReach === "none" || deps.currentClamps?.approvalReach === "none" ? "none" : undefined,
-                    readFace: entry.specSnapshot.readFace === "roots" || deps.currentClamps?.readFaceRoots === true ? "roots" : entry.specSnapshot.readFace,
-                    writeFace: entry.specSnapshot.writeFace === "roots" || deps.currentClamps?.writeFaceRoots === true ? "roots" : entry.specSnapshot.writeFace,
-                    readDenyPatterns: [...(entry.specSnapshot.readDenyPatterns ?? []), ...(deps.currentClamps?.readDenyPatterns ?? [])],
-                }),
-                ...(entry.specSnapshot.oneShot === true || deps.currentClamps?.oneShot === true ? { oneShot: true } : {}),
-                ...(entry.specSnapshot.memoryPersistenceCapable === false || deps.currentClamps?.memoryPersistenceCapable === false
-                    ? { memoryPersistenceCapable: false }
-                    : {}),
+                ...childClampSeats(wakeClamps),
+                ...clampSeatsOf(wakeClamps, "specSeat"),
                 ...(deps.currentClamps?.memoryOff === true ? { memory: memoryTurnedOff(entry.specSnapshot.memory) } : {}),
-                ...(deps.currentClamps?.fileHistory === "disabled" ? { fileHistory: "disabled" } : {}),
                 signal: abort.signal,
             };
             if (deps.registry !== undefined && deps.taskId !== undefined && deps.taskAccess !== undefined) {
@@ -714,7 +713,7 @@ export function createSubagentResume(deps) {
                 for await (const _ of stream)
                     void _;
                 const child = await stream.result();
-                const childFace = terminalProjection(child.terminal);
+                const childFace = childTerminalFace(child.terminal);
                 let status = child.terminal.kind === "completed" ? "completed" : abort.signal.aborted ? "killed" : "failed";
                 const resumeHandbackWarning = await reviewHandback({
                     review: deps.currentAutoModeReview,
@@ -820,7 +819,7 @@ export function createSubagentResume(deps) {
                 }
             }
             catch (e) {
-                const msgRevive = thrownText(e);
+                const msgRevive = childThrownText(e);
                 const errCodeReviveReject = abort.signal.aborted ? undefined : thrownErrorCode(e);
                 const errClassReviveReject = abort.signal.aborted ? undefined : classifySubagentError({ kind: "failed", ...(errCodeReviveReject !== undefined ? { code: errCodeReviveReject } : {}) });
                 if (reviveCycle !== undefined && deps.registry !== undefined && deps.taskId !== undefined) {
@@ -1400,6 +1399,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
         ...(depth === 0 && opts.allowTools !== undefined ? { agentToolLevelAllowTools: opts.allowTools } : {}),
         ...(depth === 0 && opts.denyTools !== undefined ? { agentToolLevelDenyTools: opts.denyTools } : {}),
         ...(agentToolPool !== undefined ? { agentToolPool } : {}),
+        ...(opts.tools === undefined ? { agentToolInheritsMcp: true } : {}),
         ...(rosterNames !== undefined ? { agentModels: rosterNames } : {}),
         executionMode: "parallel",
         description: `Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.\n` +
@@ -1542,9 +1542,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     details: { error: "unknown subagent_type" },
                 };
             }
-            const allowFlaw = toolNameListFlaw(`delegation tool "${toolName}": ${def !== undefined ? `agent definition "${def.name}"` : "the tool-level list"}`, "allowed", def !== undefined ? def.allowTools : opts.allowTools);
+            const allowFlaw = toolNameListFlaw(delegationListWhere(toolName, def?.name), "allowed", def !== undefined ? def.allowTools : opts.allowTools);
             if (allowFlaw !== undefined)
                 return { isError: true, content: `Sub-agent not started: ${inlineUntrusted(allowFlaw, 480)}`, details: { error: "config.agent.unknown_tool" } };
+            const denyFlaw = toolNameListFlaw(delegationListWhere(toolName, def?.name), "denied", def !== undefined ? def.denyTools : opts.denyTools);
+            if (denyFlaw !== undefined)
+                return { isError: true, content: `Sub-agent not started: ${inlineUntrusted(denyFlaw, 480)}`, details: { error: "config.agent.unknown_tool" } };
             if (a.name !== undefined && typeof a.name !== "string") {
                 return { isError: true, content: "Sub-agent not started: name must be a string.", details: { error: "name.invalid" } };
             }
@@ -1557,12 +1560,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         details: { error: "name.invalid" },
                     };
                 }
-                if (agentName.toLowerCase() === "main") {
-                    return {
-                        isError: true,
-                        content: 'Sub-agent not started: "main" is reserved — SendMessage routes it to the main conversation.',
-                        details: { error: "name.reserved" },
-                    };
+                if (reservedPeerNameReason(agentName) !== undefined) {
+                    return { isError: true, content: normalizePeerName(agentName) === "main" ? 'Sub-agent not started: "main" is reserved — SendMessage routes it to the main conversation.' : 'Sub-agent not started: name must not be a reserved name ("main", "team-lead", "user" or "system", in any spelling) or have the shape of an agent id — those already address an agent directly.', details: { error: "name.reserved" } };
                 }
                 if (ctx.spawnedAgentName !== undefined && reviveClaim === undefined) {
                     return {
@@ -1845,17 +1844,19 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 childPool = [...(opts.tools ?? inherited.filter((t) => ![t.name, ...(t.aliases ?? [])].some((n) => taken.has(n)))), ...accepted];
             }
-            const subset = resolveAgentToolSubset(childPool, def ? def.allowTools : opts.allowTools, def ? def.denyTools : opts.denyTools);
-            const allowed = new Set([...subset.handed, ...(agentName !== undefined ? teammateInheritedFamily(childPool.filter((t) => inherited.includes(t)), def ? def.denyTools : opts.denyTools) : [])]);
-            const childTools = childPool.filter((t) => allowed.has(t));
-            const childExcludeTools = ctx.excludeTools !== undefined || subset.withheldHands.length > 0 ? [...new Set([...(ctx.excludeTools ?? []), ...subset.withheldHands])] : undefined;
+            const governingLists = def !== undefined ? { allow: def.allowTools, deny: def.denyTools } : { allow: opts.allowTools, deny: opts.denyTools };
+            const childOwnLayer = Object.freeze({ ...(governingLists.allow != null ? { allow: Object.freeze([...governingLists.allow]) } : {}), deny: Object.freeze([...(governingLists.deny ?? [])]) });
+            const childListsJudged = toolListsDigest(childOwnLayer.allow, childOwnLayer.deny);
+            const childCeiling = ctx.toolSelector?.layers ?? [];
+            const parentMcp = opts.tools === undefined && extraToolsNote === undefined ? ctx.mountedMcp?.() : undefined;
+            const childMcp = parentMcp !== undefined ? inheritedMcpDeclarations(parentMcp, compileToolSelector([...childCeiling, childOwnLayer])) : undefined;
+            const childTools = [...childPool];
             const childSystemPrompt = def?.systemPrompt ?? opts.systemPrompt;
             const childDefaultPersona = childSystemPrompt === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
             const defMaxTurns = typeof def?.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0 ? def.maxTurns : undefined;
             const childLimits = defMaxTurns !== undefined ? { ...opts.limits, maxTurns: defMaxTurns } : opts.limits;
             const nextExcluded = def ? new Set([...excluded, def.name]) : excluded;
-            const defAllowsDelegation = def === undefined || toolNameAllowed(opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME, def.allowTools, def.denyTools);
-            if (depth + 1 < maxDepth && defAllowsDelegation) {
+            if (depth + 1 < maxDepth) {
                 childTools.push(createSubagentToolNode(opts, depth + 1, nextExcluded, treeBudget));
             }
             const childAgentName = (typeof a.description === "string" && a.description.trim() ? a.description.trim() : undefined) ?? def?.name;
@@ -1873,7 +1874,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             let observerDegradedCount = 0;
             let observerDegradedFirst;
             const noteObserverFailure = (err) => {
-                const msg = (thrownText(err)).slice(0, REPORT_FIELD_MAX);
+                const msg = childThrownText(err).slice(0, REPORT_FIELD_MAX);
                 if (observerPairing !== undefined && observerPairing.state === "armed") {
                     observerDegradedCount++;
                     if (observerDegradedFirst === undefined)
@@ -1926,13 +1927,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(ctx.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: ctx.getApiKeyAndHeaders } : {}),
                     ...(ctx.checkpointStoreForChildren !== undefined ? { checkpointStore: ctx.checkpointStoreForChildren } : {}),
                     tools: [reportTool],
-                    ...(childExcludeTools !== undefined ? { excludeTools: [...childExcludeTools] } : {}),
                     ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
                     ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                     ...(ctx.restoreGatedTools !== undefined ? { restoreGatedTools: ctx.restoreGatedTools === true ? true : [...ctx.restoreGatedTools] } : {}),
                     ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
                     ...engineHeadlessLegSeats(),
-                    ...childClampSeats({ handsReadOnly: ctx.handsReadOnly, interactiveTools: ctx.interactiveTools, approvalReach: ctx.approvalReach, readFace: ctx.readFace, writeFace: ctx.writeFace, readDenyPatterns: ctx.readDenyPatterns }),
+                    ...childClampSeats(clampSourceOf(ctx)),
                     enableBlockedReport: false,
                     limits: {
                         maxTurns: typeof observerDef.maxTurns === "number" && Number.isFinite(observerDef.maxTurns) && observerDef.maxTurns > 0 ? observerDef.maxTurns : 8,
@@ -1952,15 +1952,14 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(parentGate.shellGate !== undefined ? { shellGate: parentGate.shellGate } : {}),
                             admittedOrgScopes: parentGate.admittedOrgScopes,
                         };
-                    const observerInternals = ctx.interactionPosture !== undefined || pickedRef !== undefined || observerGate !== undefined
-                        ? { ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}), ...(pickedRef !== undefined ? { inheritedModelRef: pickedRef } : {}), ...(observerGate !== undefined ? { inheritedGate: observerGate } : {}) }
-                        : undefined;
+                    const observerInternals = { ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}), ...(pickedRef !== undefined ? { inheritedModelRef: pickedRef } : {}), ...(observerGate !== undefined ? { inheritedGate: observerGate } : {}), toolCeiling: [...childCeiling, childOwnLayer], observerLeg: true };
                     const r = await opts.runner.runTask(spec, observerInternals);
                     if (r.terminal.kind !== "completed") {
-                        const failedText = r.terminal.kind === "failed" && r.terminal.message ? `: ${r.terminal.message}` : "";
+                        const endedFace = childTerminalFace(r.terminal);
+                        const failedText = r.terminal.kind === "failed" && endedFace.errorMessage ? `: ${endedFace.errorMessage}` : "";
                         if (r.terminal.kind === "failed" && r.terminal.code === "resume.session_not_found")
                             throw new ObserverResumeStateError(`observer session no longer exists${failedText}`);
-                        throw new Error(`observer run ended ${terminalProjection(r.terminal).status}${failedText}`);
+                        throw new Error(`observer run ended ${endedFace.status}${failedText}`);
                     }
                 };
                 const spawner = {
@@ -2112,11 +2111,15 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ? { optedOut: (await ctx.memoryCaptureOptedOut) === true, indeterminate: (await ctx.memoryCaptureIndeterminate) === true }
                 : undefined;
             const childInternals = {
+                ...(ctx.toolSelector !== undefined ? { toolCeiling: childCeiling, ...(childListsJudged !== undefined ? { toolListsJudged: childListsJudged } : {}) } : {}),
+                ownToolListsWhere: delegationListWhere(toolName, def?.name),
+                ...(parentMcp?.pool !== undefined && childMcp !== undefined && childMcp.length > 0 ? { mcpPool: parentMcp.pool } : {}),
                 ...(childPick.modelRef !== undefined ? { inheritedModelRef: childPick.modelRef } : {}),
                 ...(inheritedSkillGrants.length > 0 ? { inheritedSkillGrants } : {}),
                 ...(inheritedAllowedTools !== undefined && inheritedAllowedTools.length > 0 ? { inheritedAllowedTools: [...inheritedAllowedTools] } : {}),
                 ...(childProvenanceRef !== undefined && provenanceRequest !== undefined ? { delegationProvenance: { ref: childProvenanceRef, contentSafety: provenanceRequest } } : {}),
                 ...(treeScope !== undefined ? { registryScope: treeScope } : {}),
+                ...(ctx.checkpointScopeForChildren !== undefined ? { checkpointScope: ctx.checkpointScopeForChildren } : {}),
                 ...(ctx.inheritedGateForChildren ? { inheritedGate: ctx.inheritedGateForChildren() } : {}),
                 ...(ctx.questionFaceStripped === true ? { questionFaceStripped: true } : {}),
                 ownOrgAdmissionRef: { current: reviveClaim !== undefined ? readDurableOrgAdmission(reviveClaim.row) : undefined },
@@ -2200,14 +2203,16 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...childSeat,
                 ...childThinking,
                 tools: childTools,
+                ...(childMcp !== undefined && childMcp.length > 0 ? { mcp: childMcp } : {}),
                 systemPrompt: childSystemPrompt,
                 ...(def?.memory ? { memory: def.memory } : {}),
                 ...(def?.skills?.length ? { skills: def.skills } : {}),
                 ...(def?.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: def.memoryPersistenceCapable } : {}),
                 ...(ctx.checkpointStoreForChildren !== undefined ? { checkpointStore: ctx.checkpointStoreForChildren } : {}),
                 ...(childOnAsk !== undefined ? { onAsk: childOnAsk } : {}),
-                ...childClampSeats({ handsReadOnly: ctx.handsReadOnly, interactiveTools: ctx.interactiveTools, approvalReach: ctx.approvalReach, readFace: ctx.readFace, writeFace: ctx.writeFace, readDenyPatterns: ctx.readDenyPatterns }),
-                ...(childExcludeTools !== undefined ? { excludeTools: [...childExcludeTools] } : {}),
+                ...childClampSeats(clampSourceOf(ctx)),
+                ...(childOwnLayer.allow !== undefined ? { allowTools: [...childOwnLayer.allow] } : {}),
+                ...(childOwnLayer.deny.length > 0 ? { excludeTools: [...childOwnLayer.deny] } : {}),
                 ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
                 ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                 ...(ctx.restoreGatedTools !== undefined ? { restoreGatedTools: ctx.restoreGatedTools === true ? true : [...ctx.restoreGatedTools] } : {}),
@@ -2235,6 +2240,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(plainSpec.limits ? { limits: { ...plainSpec.limits } } : {}),
                         ...(plainSpec.memory !== undefined && typeof plainSpec.memory === "object" ? { memory: { ...plainSpec.memory } } : {}),
                         ...(plainSpec.clientContext !== undefined ? { clientContext: { ...plainSpec.clientContext } } : {}),
+                        ...(plainSpec.allowTools !== undefined ? { allowTools: [...plainSpec.allowTools] } : {}),
                         ...(plainSpec.excludeTools !== undefined ? { excludeTools: [...plainSpec.excludeTools] } : {}),
                         ...(plainSpec.deferTools !== undefined ? { deferTools: [...plainSpec.deferTools] } : {}),
                         ...(plainSpec.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...plainSpec.alwaysLoadTools] } : {}),
@@ -2317,6 +2323,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(plainSpec.limits ? { limits: { ...plainSpec.limits } } : {}),
                             ...(plainSpec.memory !== undefined && typeof plainSpec.memory === "object" ? { memory: { ...plainSpec.memory } } : {}),
                             ...(plainSpec.clientContext !== undefined ? { clientContext: { ...plainSpec.clientContext } } : {}),
+                            ...(plainSpec.allowTools !== undefined ? { allowTools: [...plainSpec.allowTools] } : {}),
                             ...(plainSpec.excludeTools !== undefined ? { excludeTools: [...plainSpec.excludeTools] } : {}),
                             ...(plainSpec.deferTools !== undefined ? { deferTools: [...plainSpec.deferTools] } : {}),
                             ...(plainSpec.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...plainSpec.alwaysLoadTools] } : {}),
@@ -2689,7 +2696,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     void opts.runner
                         .runTask(bgForkSpec, bgForkInternals)
                         .then(async (child) => {
-                        const childFace = terminalProjection(child.terminal);
+                        const childFace = childTerminalFace(child.terminal);
                         settleForkRow(child.terminal);
                         dropHostAbortListener();
                         await finishWorktree(child.terminal);
@@ -2792,7 +2799,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         dropHostAbortListener();
                         void finishWorktree();
                         const killed = abort.signal.aborted;
-                        const msgFork = thrownText(e);
+                        const msgFork = childThrownText(e);
                         const errCodeForkReject = killed ? undefined : thrownErrorCode(e);
                         const errClassForkReject = killed ? undefined : classifySubagentError({ kind: "failed", ...(errCodeForkReject !== undefined ? { code: errCodeForkReject } : {}) });
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
@@ -2902,7 +2909,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     catch {
                     }
                     const wt = await finishWorktree();
-                    return { isError: true, content: `Fork failed: the forked run threw (${thrownText(e)}).${wt ? `\n${wt}` : ""}`, details: { error: "fork run failed" } };
+                    return { isError: true, content: `Fork failed: the forked run threw (${childThrownText(e)}).${wt ? `\n${wt}` : ""}`, details: { error: "fork run failed" } };
                 }
                 finally {
                     syncForkAdmission.release();
@@ -2925,7 +2932,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     return durablePauseDelegationReport(` · ${FORK_SUBAGENT_TYPE}`, forkChild.terminal);
                 }
                 const wtLine = await finishWorktree();
-                const forkFace = terminalProjection(forkChild.terminal);
+                const forkFace = childTerminalFace(forkChild.terminal);
                 const forkErr = classifySubagentError(forkChild.terminal);
                 const forkLines = [
                     ...(forkHandbackWarning ? [forkHandbackWarning, ""] : []),
@@ -3466,7 +3473,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : opts.runner.runTask(bgSpec, bgInternals);
                 void bgChildPromise
                     .then(async (child) => {
-                    const childFace = terminalProjection(child.terminal);
+                    const childFace = childTerminalFace(child.terminal);
                     settleDelegationRow(child.terminal);
                     closeObserverWindow(childFace.status);
                     dropHostAbortListener();
@@ -3676,7 +3683,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         else
                             bgRetainLedger?.markSettled(ctx.toolCallId);
                     }
-                    const msg = thrownText(e);
+                    const msg = childThrownText(e);
                     const errCodeBgReject = killed ? undefined : thrownErrorCode(e);
                     const errClassBgReject = killed ? undefined : classifySubagentError({ kind: "failed", ...(errCodeBgReject !== undefined ? { code: errCodeBgReject } : {}) });
                     const settled = bg.registry.settleBackgroundAgent(taskId, {
@@ -3740,7 +3747,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ]);
                     if (startup === "settled") {
                         if (parkedResume !== undefined) {
-                            const err = await bgChildPromise.then(() => undefined, (e) => (thrownText(e)));
+                            const err = await bgChildPromise.then(() => undefined, (e) => childThrownText(e));
                             return {
                                 isError: true,
                                 content: `Parked resume did not complete: ${(err ?? "the resumed run settled before its delivery lane bound").slice(0, 600)}`,
@@ -3822,7 +3829,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     catch (e) {
                         await settleObserver("failed");
-                        throw e;
+                        throw childRejection(e);
                     }
                     finally {
                         settleResolve();
@@ -3830,13 +3837,18 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                 }
                 else {
-                    child = await opts.runner.runTask(buildChildSpec(ctx.signal), childInternals);
+                    try {
+                        child = await opts.runner.runTask(buildChildSpec(ctx.signal), childInternals);
+                    }
+                    catch (e) {
+                        throw childRejection(e);
+                    }
                 }
             }
             finally {
                 syncAdmission.release();
             }
-            const childFace = terminalProjection(child.terminal);
+            const childFace = childTerminalFace(child.terminal);
             await settleObserver(childFace.status);
             const handbackWarning = await reviewHandback({
                 review: ctx.autoModeReview,

package/dist/agents/suspend-guard.d.ts

@@ -1,7 +1,7 @@
 import type { PausedCause, TaskResult, TerminalCause } from "../core/types.js";
 /**
  * design/45 §11 Q6 — the **durable-suspend hard boundary** (v1). A `paused` terminal is only safe to
- * handle at the **top-level `runTask`** boundary: the orchestrators (cascade / verify / teacher / team)
+ * handle at the **top-level `runTask`** boundary: the orchestrators (cascade / verify / repair-loop)
  * run their work as *nested* `runTask`s, and none of them can drive a resume from the inside. If a nested
  * task pauses on a durable gate, the orchestrator must **fail fast** — not silently treat it as an
  * ordinary failure (which would escalate/re-run side effects) and not release its pinned session (which

package/dist/agents/tool-filter.d.ts

@@ -1,27 +1,25 @@
 import type { AgentDefinition, ToolSpec } from "../core/types.js";
+import type { ToolLegKind, ToolSelector, ToolSelectorLayer } from "../core/tool-face.js";
+import { type ProtocolId } from "../core/protocol-table.js";
+import { type ToolNameListReading } from "../core/tool-name-list.js";
 /**
- * Per-agent tool allow/deny (design/38 1A). Statically narrows a tool POOL to the subset a delegated
- * sub-agent / team member may use — assembly-time filtering (the tool simply never appears in the
- * child's `tools[]`), distinct from design/37's execution-time policy interception.
+ * The tool selector (design/38 1A, one operation since #1623): what tools a run may use, read once over the universe it can get
+ * (its pool, every tool the engine mounts on it, the protocol tools it connects) at its own prepare —
+ * `available = universe ∩ ceiling ∩ allow − deny` — and on every later roster change. The same compiled object answers the
+ * root run (`TaskSpec.allowTools` / `TaskSpec.excludeTools`) and every child (its definition's lists, under the ceiling of the
+ * run that spawned it), so there is no spawn-time filter and no complement anywhere.
  *
- * Resolution order (council finding 6): `pool → ∩ allowTools → − denyTools`.
- *  - `allowTools` undefined OR contains `"*"` → start from the whole pool; otherwise keep only the named
- *    tools (an explicit allowlist; `[]` means "no work tools", which is intentional, not a mistake).
- *  - `denyTools` then removes named tools from whatever remains (a denied tool always loses).
+ *  - an allowed list absent, or holding `"*"`, sets no allowlist on its layer; otherwise the layer keeps only what it names
+ *    (`[]` keeps nothing — intentional, not a mistake);
+ *  - a denied list removes what it names from whatever remains (a denied tool always loses);
+ *  - a layer above a run (its ceiling) bounds it: a child's `"*"` never widens what its parent could use.
  *
- * Allowlist is the security-recommended shape (finding 5): a denylist-only config silently exposes any
- * newly-added sensitive tool to every agent. Names not present in the pool are ignored (no error) — an
- * allow/deny list is a filter over what's available, not an assertion that those tools exist.
+ * An entry is read as the reference reads a rule string ({@link readDeniedEntry}: `Tool(content)` names `Tool`, the content is
+ * not read, the whole tool is hidden); a protocol spelling (`mcp__srv`, `mcp__srv__*`, a glob over the tool segment) reaches the
+ * tools of that peer, including ones it lists later. Each list is judged at the prepare that receives it: a name that names no
+ * tool is refused (`sub-agent-deny-lists.ts`).
  *
- * Anchored (dual-leg verified): this spawn-time item-level filter IS the upstream shape for allow
- * entries — CC's resolveAgentTools partitions unknown names into an `invalidTools` bucket nobody
- * consumes at runtime, and a live 2.1.207 probe shows the agent stays listed/delegable with the
- * unknown item silently dropped, zero warnings. A DENY entry is read as the reference reads it
- * ({@link readDeniedEntry}: `Tool(content)` names `Tool`, the content is not read, the whole tool is hidden). The
- * list is judged once before the run, from every place a deployment writes one (prepare's
- * `judgeDeniedToolNames`): a spelling that can name no tool is refused, the rest is told to the host.
- *
- * Note: `"*"` in `allowTools` is the "allow all" sentinel, so a tool literally NAMED `"*"` cannot be
+ * Note: `"*"` in an allowed list is the "allow all" sentinel, so a tool literally NAMED `"*"` cannot be
  * the sole allowed tool via this path (tool names are conventionally identifiers, so this is moot).
  */
 /**
@@ -40,28 +38,6 @@ export type DeniedEntryReading = {
     readonly type: string;
 };
 export declare function readDeniedEntry(entry: unknown): DeniedEntryReading;
-/** A fixed label of a host value's TYPE for a sentence that must not print or convert the value (`typeof` and the array test only). */
-export declare function valueTypeLabel(value: unknown): string;
-/**
- * How a tool-name list's VALUE (an agent definition's allowed-tools or denied-tools list) reads as a list. A host that reads its
- * definitions from a file can hand over anything, and a list can be hostile as a container (an accessor or a proxy trap that
- * throws, an overridden iterator, holes): it is read BY INDEX over its length, once, into a dense copy — no iterator of the host
- * runs, a hole reads as `undefined` (an entry that is not a string) — and a value that is not an array, or an array whose read
- * throws, is reported as such and never printed or converted.
- */
-export type ToolNameListReading = {
-    readonly kind: "entries";
-    readonly entries: readonly unknown[];
-} | {
-    readonly kind: "not_a_list";
-    readonly type: string;
-} | {
-    readonly kind: "unreadable";
-};
-export declare function readToolNameList(value: unknown): ToolNameListReading;
-/** A tool-name list as the mount keeps it: the dense copy when it reads as a list, the failure marker when it cannot be read, else
- *  the value itself (not a list: the judge refuses it, and its type never changes). */
-export declare function snapshotToolNameList(value: unknown): unknown;
 /** The two tool-name lists of a definition, and the words a sentence calls each. */
 export type ToolNameListSide = "allowed" | "denied";
 /** The sentence for an entry that is not a string: it can be no tool name; the sentence names its place and its type, never its value. */
@@ -70,6 +46,16 @@ export declare function notAStringSentence(where: string, side: ToolNameListSide
 export declare function notAListSentence(where: string, side: ToolNameListSide, list: Exclude<ToolNameListReading, {
     kind: "entries";
 }>): string;
+/** Whose lists a delegated child's own are, in the words every sentence about them uses (the judgment before the run, the spawn-time
+ *  check, the child's own prepare): the agent definition it was spawned as, or — with none — the delegation tool's tool-level list. */
+export declare function delegationListWhere(toolName: string, definitionName: string | undefined): string;
+/**
+ * The digest of a run's own two tool lists as its selector reads them (an absent denied list reads as an empty one): sha256 over the
+ * binding serializer's canonical form — the serializer the checkpoint row digest uses. It is the evidence that the spawning run judged
+ * EXACTLY these lists (`RunInternals.toolListsJudged`, and the row's `CheckpointState.toolListsJudged` on a resume); `undefined` for
+ * lists the serializer cannot encode, which therefore never match any evidence.
+ */
+export declare function toolListsDigest(allow: readonly unknown[] | undefined, deny: readonly unknown[] | undefined): string | undefined;
 /**
  * Why a host-written tool-name list cannot be one, as a sentence — or `undefined` when it is absent (`undefined` / `null`) or a list
  * of strings. The one reading the judgment before the run and the spawn-time check of a tool that never went through prepare share.
@@ -79,34 +65,59 @@ export declare function toolNameListFlaw(where: string, side: ToolNameListSide,
  *  run, the roster, the filter at each spawn) takes instead of the host's container. */
 export declare function snapshotDefinitionLists(def: AgentDefinition): AgentDefinition;
 /**
- * The names an allowed-tools value admits, or `undefined` when it names no allowlist: absent, `null`, or a list holding the
- * wildcard. A list admits its string entries (an entry that is not a string admits nothing); a value that is not a list admits
- * NOTHING — the judge before the run refuses it, and a reader that meets it first fails closed.
+ * What ONE tool-name list reaches — the single reading every consumer of an allowed or a denied list takes (the spawn-time
+ * filter, the nested-delegation check, the memory content-origin face, the judgment before the run):
+ *  - `names`: exact spellings; a tool answers to its wire name and to every alias it declares;
+ *  - `covering`: the protocol spellings that cover a SET — a peer (`mcp__srv`), the same set written with the star
+ *    (`mcp__srv__*`), a glob over the tool segment (`mcp__srv__get_*`) — matched by the allow layer's own covering matcher,
+ *    peers compared exactly, both sides in the same namespace;
+ *  - `wholeProtocols`: a denied list's `mcp__*` — every tool of that protocol. An allowed list reads it as nothing (the
+ *    reference's allow resolution has no such form: it keeps no MCP tool by it).
  */
-export declare function allowedToolNames(allowTools: unknown): ReadonlySet<string> | undefined;
+export interface ToolNameListReach {
+    readonly names: ReadonlySet<string>;
+    readonly covering: readonly string[];
+    readonly wholeProtocols: ReadonlySet<ProtocolId>;
+}
 /**
- * Membership check for ONE tool name under the same allow/deny semantics as {@link resolveToolSubset}
- * (canonicalized both sides; `"*"` allow sentinel; deny wins). Used by the delegation tool to decide
- * whether a chosen agent DEFINITION may re-delegate: a per-agent allow/deny that excludes the
- * delegation tool's own name suppresses the nested delegation tool (upstream parity — the built-in
- * Explore/Plan denials include Agent, and the delegation tool is filtered like any other). The
- * TOOL-level allow/deny keeps its own semantics (delegation governed by `maxDepth`).
+ * What an allowed-tools value admits, or `undefined` when it names no allowlist: absent, `null`, or a list holding the
+ * wildcard. A list admits its string entries (an entry that is not a string admits nothing); a value that is not a list admits
+ * NOTHING — the judge before the run refuses it, and a reader that meets it first fails closed.
  */
-export declare function toolNameAllowed(name: string, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): boolean;
-export declare function resolveToolSubset<T extends {
+export declare function readAllowedToolList(allowTools: unknown): ToolNameListReach | undefined;
+/** What a denied value hides: its string entries read as {@link readDeniedEntry} reads them (an entry that is not a string, or a value that is not a list, hides nothing). */
+export declare function readDeniedToolList(denyTools: unknown): ToolNameListReach;
+/** Does the list reach this tool — through its wire name, any alias it declares, or a protocol spelling that covers it? The one matcher. */
+export declare function listReaches(reach: ToolNameListReach, tool: {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+}): boolean;
+/** A member of a universe: a wire name and the other spellings it answers to. */
+type UniverseTool = {
     readonly name: string;
     readonly aliases?: readonly string[];
-} = ToolSpec>(pool: ReadonlyArray<T>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): T[];
+};
+/** The wire names a leg of these kinds relies on (the catalog's protocol column). */
+export declare function protocolToolNames(legs: readonly ToolLegKind[]): string[];
 /**
- * What ONE agent's tool-name lists leave it, read once over everything it can get: the tools the delegation tool hands it
- * (`handed` — its pool and the factory's products, the subset in pool order) and the engine's hand tools its own run mounts
- * over an execution environment ({@link HAND_TOOLS} — `withheldHands`, the wire names the lists take away, which the spawn
- * adds to the child's exclusion list: the one fact every reader of "is this tool mounted" consults). One
- * {@link resolveToolSubset} call over both halves, so a name reads the same whichever half carries it. The exclusion list
- * unmounts by wire name, so a withheld hand name that a handed tool is mounted under stays off it (it would take the kept
- * tool with it); a handed tool's alias does not count — the exclusion never reaches an alias, so the hand tool stays withheld.
+ * Compile ONE run's tool selector from its layers (the ceiling it was spawned under, then its own lists — the LAST layer is its own)
+ * and the kinds of leg it is. Each list is read by the one reading ({@link readAllowedToolList} / {@link readDeniedToolList}) and
+ * matched by the one matcher ({@link listReaches}); a protocol tool of one of `legs` is admitted whatever the leg's own lists say —
+ * and whatever the ceiling says too, unless its row is one the leg shares with its spawner (`protocolUnderCeiling`: the ceiling
+ * layers decide it). Whether a list may reach a protocol tool at all is judged at prepare. The layers are kept as handed — the
+ * producer passes frozen copies of the lists it read.
  */
-export declare function resolveAgentToolSubset(pool: ReadonlyArray<ToolSpec>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): {
-    handed: ToolSpec[];
-    withheldHands: string[];
-};
+export declare function compileToolSelector(layers: readonly ToolSelectorLayer[], legs?: readonly ToolLegKind[]): ToolSelector;
+/** One protocol tool a denylist reaches, and whose list it is: the leg's own (the last layer) or one it inherits (a ceiling layer). */
+export interface DeniedProtocolTool {
+    readonly name: string;
+    readonly own: boolean;
+}
+/** The protocol tools of these leg kinds that a layer's denylist reaches — a contradiction the run refuses (the leg relies on the tool) —
+ *  once per side that reaches it (a tool both its own list and an inherited one deny is two hits). */
+export declare function deniedProtocolTools(layers: readonly ToolSelectorLayer[], legs: readonly ToolLegKind[]): DeniedProtocolTool[];
+/** Is ONE tool name admitted by one allowed / denied pair (`"*"` sentinel; deny wins) — the selector's own answer for a single layer. */
+export declare function toolNameAllowed(name: string, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): boolean;
+/** The members of a pool one allowed / denied pair admits, in pool order (a fresh array; the pool is never mutated) — the selector's own answer for a single layer. */
+export declare function resolveToolSubset<T extends UniverseTool = ToolSpec>(pool: ReadonlyArray<T>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): T[];
+export {};