@sema-agent/core 7.52.0 → 7.54.0

package/dist/agents/subagent.js

@@ -2,10 +2,10 @@ import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { backgroundChildTerminal } from "../core/delegation-frames.js";
 import { bindDelegationName } from "../core/delegation-name.js";
-import { resumeStartupCauseOf } from "../core/resume-startup-cause.js";
-import { errorCodeOf } from "../core/runner/terminal-account.js";
-import { applyParentSpecSeat, memoryTurnedOff, parentSpecSeatOfCtx } from "../core/parent-spec-seat.js";
-import { assertClampRecord, childClampSeats, clampSeatsOf, clampSourceOf, engineHeadlessLegSeats, foldClampSources, postureUnderClamps } from "../core/child-clamp-seats.js";
+import { resumeRefusalDetailOf, resumeStartupCauseOf } from "../core/resume-startup-cause.js";
+import { errorCodeOf, thrownFailureOf } from "../core/runner/terminal-account.js";
+import { applyParentSpecSeat, parentSpecSeatOfCtx } from "../core/parent-spec-seat.js";
+import { applyClampSeats, 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";
@@ -265,6 +265,11 @@ export function forkGovernanceDenial(enableFork, allowFork) {
         return "principal";
     return undefined;
 }
+const UNDECLARED_EXTRA_TOOL_REFUSAL = {
+    undeclared_name: "the extraTools factory of this delegation tool injected a tool its declared extra tools do not name — the declaration is the upper bound of what the factory may inject.",
+    undeclared_origin: "the extraTools factory of this delegation tool injected a tool of a content class beyond the one its declared extra tools state — the declaration is the upper bound of what the factory may inject.",
+};
+const WORKTREE_NOT_A_REPOSITORY = "isolation.not_a_repository";
 const worktreeUnavailableSentence = (reason) => `Sub-agent not started: isolation "worktree" is unavailable on this run (${reason}). Retry without the isolation parameter.`;
 const WORKTREE_UNAVAILABLE = {
     readOnly: worktreeUnavailableSentence("no worktree capability — a read-only run mints no worktree"),
@@ -273,7 +278,20 @@ const WORKTREE_UNAVAILABLE = {
     seatSilent: worktreeUnavailableSentence("the runner this tool runs children on does not declare whether it can place a child in a tree other than the caller's (its seat has no canRerootChild), and an undeclared answer is read as no; use a Runner, or add that method to the seat"),
 };
 const placementRefused = (terminal) => terminal?.kind === "failed" && terminal.code === "isolation.unavailable";
-const isolationUnavailable = (content) => ({
+const NOT_STARTED_RESULTS = new WeakSet();
+function notStartedResult(result) {
+    const details = result.details;
+    if (typeof details === "object" && details !== null)
+        NOT_STARTED_RESULTS.add(details);
+    return result;
+}
+export function isNotStartedDelegationResult(result) {
+    if (typeof result !== "object" || result === null)
+        return false;
+    const details = result.details;
+    return typeof details === "object" && details !== null && NOT_STARTED_RESULTS.has(details);
+}
+const isolationUnavailable = (content) => notStartedResult({
     isError: true,
     content,
     details: { error: "isolation.unavailable" },
@@ -285,7 +303,7 @@ export function createSubagentWorktreeHelper(baseEnv, repoRoot) {
             const probe = await baseEnv.exec("git rev-parse --is-inside-work-tree", { cwd: repoRoot });
             if (!probe.ok || probe.value.exitCode !== 0) {
                 const detail = probe.ok ? (probe.value.stderr || probe.value.stdout).trim().split("\n")[0] : thrownText(probe.error);
-                throw new Error(`the working directory ${repoRoot} is not a git repository${detail ? ` (${detail})` : ""}`);
+                throw Object.assign(new Error(`the working directory ${repoRoot} is not a git repository${detail ? ` (${detail})` : ""}`), { code: WORKTREE_NOT_A_REPOSITORY });
             }
             const { env, worktreeDir } = await addWorktree(baseEnv, {
                 repoRoot,
@@ -492,10 +510,11 @@ 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)',
+    "currentClamps.memoryOff": "the waker's memory-off floor is `currentClamps.memory: { enabled: false }` (the clamp table's own seat, with the one member it clamps)",
 });
 export function createSubagentResume(deps) {
     assertNoRetiredKeys(deps, RETIRED_RESUME_CLAMP_KEYS, "createSubagentResume");
-    assertClampRecord(deps.currentClamps, "createSubagentResume currentClamps", undefined, ["memoryOff"]);
+    assertClampRecord(deps.currentClamps, "createSubagentResume currentClamps");
     const notifier = createSafeNotifier(deps.onNotifyError !== undefined ? { onError: deps.onNotifyError } : undefined);
     const resume = async (content) => {
         const ledger = deps.ledger;
@@ -555,17 +574,15 @@ export function createSubagentResume(deps) {
             entry.resumeCount += 1;
             entry.cycleSeq += 1;
             const wakeClamps = foldClampSources(entry.specSnapshot, deps.currentClamps);
-            const resumeSpec = {
+            const resumeSpec = applyClampSeats({
                 ...entry.specSnapshot,
                 objective: createResumePrompt(marker, content, deps.peerOrigin !== undefined ? "peer" : "operator"),
                 sessionId: entry.childSessionId,
                 requireExistingSession: true,
                 ...(deps.currentOnQuestion !== undefined ? { onQuestion: deps.currentOnQuestion } : {}),
                 ...childClampSeats(wakeClamps),
-                ...clampSeatsOf(wakeClamps, "specSeat"),
-                ...(deps.currentClamps?.memoryOff === true ? { memory: memoryTurnedOff(entry.specSnapshot.memory) } : {}),
                 signal: abort.signal,
-            };
+            }, clampSeatsOf(wakeClamps, "specSeat"));
             if (deps.registry !== undefined && deps.taskId !== undefined && deps.taskAccess !== undefined) {
                 const revived = await deps.registry.reviveBackgroundAgent(deps.taskId, deps.taskAccess, abort);
                 if (!revived.ok) {
@@ -1063,10 +1080,10 @@ function chargeLocalDelegationInFlight(anchor, key) {
             live.delete(key);
     };
 }
-const spawnAbortedResult = (wt) => ({
+const spawnAbortedResult = (wt, fault) => notStartedResult({
     isError: true,
     content: `Sub-agent not started: the delegating call was aborted.${wt ? `\n${wt}` : ""}`,
-    details: { error: "aborted" },
+    details: { error: "aborted", ...fault },
 });
 const noopRelease = () => undefined;
 const DELEGATION_POOL_DEFAULT_SCOPE = "default";
@@ -1460,22 +1477,22 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             const parentSpecSeat = parentSpecSeatOfCtx(ctx);
             const reviveClaim = ctx.reviveClaim;
             if (reviveClaim !== undefined && opts.background === undefined) {
-                return {
+                return notStartedResult({
                     isError: true,
                     content: "Sub-agent not revived: this delegation tool has no background surface (run_in_background is not available here), and a revival is a background run by definition.",
                     details: { error: "revive.no_background" },
-                };
+                });
             }
             const prompt = String(a.prompt ?? "").trim();
             if (!prompt) {
-                return { isError: true, content: "Sub-agent not started: 'prompt' was empty.", details: { error: "empty prompt" } };
+                return notStartedResult({ isError: true, content: "Sub-agent not started: 'prompt' was empty.", details: { error: "empty prompt" } });
             }
             if (a.subagent_type !== undefined && typeof a.subagent_type !== "string") {
-                return {
+                return notStartedResult({
                     isError: true,
                     content: `Sub-agent not started: subagent_type must be a string. Available subagent_type values: ${acceptedSubagentTypes().join(", ")}.`,
                     details: { error: "unknown subagent_type" },
-                };
+                });
             }
             const requestedType = a.subagent_type ?? "";
             let rawType = requestedType;
@@ -1485,11 +1502,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const wanted = normalizeSubagentType(requestedType);
                     const hits = wanted === "" ? [] : accepted.filter((n) => normalizeSubagentType(n) === wanted);
                     if (hits.length > 1) {
-                        return {
+                        return notStartedResult({
                             isError: true,
                             content: `Sub-agent not started: subagent_type "${requestedType}" is ambiguous — it matches ${hits.join(", ")}. Use the exact name.`,
                             details: { error: "ambiguous subagent_type" },
-                        };
+                        });
                     }
                     if (hits.length === 1)
                         rawType = hits[0];
@@ -1497,62 +1514,62 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             }
             const wantsFork = forkOffered && rawType === FORK_SUBAGENT_TYPE;
             if (reviveClaim !== undefined && wantsFork) {
-                return { isError: true, content: `Sub-agent not revived: a "${FORK_SUBAGENT_TYPE}" agent cannot be revived — launch a new agent with the needed context instead.`, details: { error: "revive.fork_unsupported" } };
+                return notStartedResult({ isError: true, content: `Sub-agent not revived: a "${FORK_SUBAGENT_TYPE}" agent cannot be revived — launch a new agent with the needed context instead.`, details: { error: "revive.fork_unsupported" } });
             }
             const omitted = rawType === "" || (!generalPurposeShadowed && rawType === GENERAL_PURPOSE_SUBAGENT_TYPE);
             const def = hasAgents && !wantsFork && !omitted ? agentMap.get(rawType) : undefined;
             const wantsBackground = opts.background !== undefined && (a.run_in_background !== false || def?.background === true);
             const spawnAgentType = wantsFork ? FORK_SUBAGENT_TYPE : omitted ? GENERAL_PURPOSE_SUBAGENT_TYPE : rawType;
             if (!def && !wantsFork && !omitted) {
-                return {
+                return notStartedResult({
                     isError: true,
                     content: `Sub-agent not started: unknown subagent_type "${rawType}". Available subagent_type values: ${acceptedSubagentTypes().join(", ")}.`,
                     details: { error: "unknown subagent_type" },
-                };
+                });
             }
             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" } };
+                return notStartedResult({ 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" } };
+                return notStartedResult({ 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" } };
+                return notStartedResult({ isError: true, content: "Sub-agent not started: name must be a string.", details: { error: "name.invalid" } });
             }
             const agentName = a.name;
             if (agentName !== undefined) {
                 if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(agentName)) {
-                    return {
+                    return notStartedResult({
                         isError: true,
                         content: "Sub-agent not started: name must start with a letter or digit and contain only letters, digits, underscores, or hyphens (max 64 chars).",
                         details: { error: "name.invalid" },
-                    };
+                    });
                 }
                 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" } };
+                    return notStartedResult({ 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 {
+                    return notStartedResult({
                         isError: true,
                         content: "Sub-agent not started: teammates cannot spawn other teammates — the team roster is flat. To spawn a subagent instead, omit the `name` parameter.",
                         details: { error: "name.nested_teammate" },
-                    };
+                    });
                 }
             }
             if (a.cwd !== undefined && typeof a.cwd !== "string") {
-                return { isError: true, content: "Sub-agent not started: cwd must be an absolute path string.", details: { error: "cwd.relative" } };
+                return notStartedResult({ isError: true, content: "Sub-agent not started: cwd must be an absolute path string.", details: { error: "cwd.relative" } });
             }
             const childCwd = a.cwd;
             if (childCwd !== undefined) {
                 if (!isAbsolute(childCwd)) {
-                    return { isError: true, content: "Sub-agent not started: cwd must be an absolute path.", details: { error: "cwd.relative" } };
+                    return notStartedResult({ isError: true, content: "Sub-agent not started: cwd must be an absolute path.", details: { error: "cwd.relative" } });
                 }
                 if ((a.isolation ?? def?.isolation) === "worktree") {
-                    return {
+                    return notStartedResult({
                         isError: true,
                         content: 'Sub-agent not started: cwd and isolation "worktree" are mutually exclusive — the worktree defines its own working directory.',
                         details: { error: "cwd.isolation_conflict" },
-                    };
+                    });
                 }
             }
             if (wantsFork) {
@@ -1560,21 +1577,21 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const who = ctx.forkAccess.denied === "task"
                         ? "this task (enableFork: false)"
                         : `this principal (runtimeCaps.allowFork: false)`;
-                    return {
+                    return notStartedResult({
                         isError: true,
                         content: `Sub-agent not started: subagent_type "${FORK_SUBAGENT_TYPE}" is disabled for ${who}. Delegate without subagent_type instead.`,
                         details: { error: "fork.disabled" },
-                    };
+                    });
                 }
                 if (ctx.insideFork === true) {
-                    return { isError: true, content: `Sub-agent not started: subagent_type "${FORK_SUBAGENT_TYPE}" is not available inside a forked agent.`, details: { error: "fork.nested" } };
+                    return notStartedResult({ isError: true, content: `Sub-agent not started: subagent_type "${FORK_SUBAGENT_TYPE}" is not available inside a forked agent.`, details: { error: "fork.nested" } });
                 }
                 if (ctx.sessionId === undefined || (ctx.hostSessionFork === undefined && !hasSessionFork(opts.runner.sessions))) {
-                    return {
+                    return notStartedResult({
                         isError: true,
                         content: `Sub-agent not started: subagent_type "${FORK_SUBAGENT_TYPE}" is unavailable here (this run has no fork-capable durable session). Delegate without subagent_type instead.`,
                         details: { error: "fork.unavailable" },
-                    };
+                    });
                 }
             }
             const modelObjectForm = typeof a.model === "object" &&
@@ -1584,18 +1601,18 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 typeof a.model.api === "string";
             if (a.model !== undefined && typeof a.model !== "string" && !modelObjectForm) {
                 const typeDesc = Array.isArray(a.model) ? "an array" : a.model === null ? "null" : typeof a.model === "object" ? "an object" : `a ${typeof a.model}`;
-                return {
+                return notStartedResult({
                     isError: true,
                     content: `Sub-agent not started: \`model\` must be a model name (string) from this deployment's catalog — got ${typeDesc}. Omit the parameter to run the agent type's own model.`,
                     details: { error: "model.invalid" },
-                };
+                });
             }
             if (typeof a.model === "string" && a.model.trim() === "" && !wantsFork && reviveClaim === undefined) {
-                return {
+                return notStartedResult({
                     isError: true,
                     content: "Sub-agent not started: `model` was empty. Name a model from this deployment's catalog, or omit the parameter to run the agent type's own model.",
                     details: { error: "model.empty" },
-                };
+                });
             }
             const requestedModel = typeof a.model === "string" && a.model.trim() !== "" ? a.model.trim() : undefined;
             let perCallModel;
@@ -1640,11 +1657,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 budget -= k.length + 2;
                             }
                             const rosterEcho = shown.length === rosterKeys.length ? shown.join(", ") : `${shown.join(", ")}, … (${rosterKeys.length - shown.length} more)`;
-                            return {
+                            return notStartedResult({
                                 isError: true,
                                 content: `Sub-agent not started: unknown model "${inlineUntrusted(requestedModel, 80)}". Available model values: ${inlineUntrusted(rosterEcho, ROSTER_ECHO_MAX + 32)}. Omit \`model\` to run the agent type's own model, or inherit the caller's.`,
                                 details: { error: "model.unknown" },
-                            };
+                            });
                         }
                     }
                 }
@@ -1693,11 +1710,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             const inheritedSkillGrants = readSkillGrantCapture(ctx.activeSkillGrants?.());
             const inheritedAllowedTools = ctx.activeRequestAllowedTools?.();
             if (inheritedSkillGrants === undefined) {
-                return {
+                return notStartedResult({
                     isError: true,
                     content: "Sub-agent not started: the parent's skill grants could not be read for the child (an unrecognizable capture); a child started without them would lose the parent's disallowed-tools refusals.",
                     details: { error: "skill_grants.unreadable" },
-                };
+                });
             }
             let worktreeDir;
             if (reviveClaim === undefined && (a.isolation ?? def?.isolation) === "worktree") {
@@ -1711,15 +1728,18 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     worktreeDir = (await iso.mint(ctx.toolCallId)).worktreeDir;
                 }
                 catch (e) {
-                    return {
+                    return notStartedResult({
                         isError: true,
-                        content: `Sub-agent not started: worktree isolation failed — ${thrownText(e)}. Retry without the isolation parameter, or fix the repository state.`,
-                        details: { error: "isolation.failed" },
-                    };
+                        content: errorCodeOf(e) === WORKTREE_NOT_A_REPOSITORY
+                            ? "Sub-agent not started: worktree isolation failed — the working directory is not a git repository. Retry without the isolation parameter."
+                            : "Sub-agent not started: worktree isolation failed. Retry without the isolation parameter, or fix the repository state.",
+                        details: { error: "isolation.failed", cause: thrownText(e) },
+                    });
                 }
             }
             let worktreeKeptPath;
             let childPlacement;
+            let worktreeFault;
             const finishWorktree = async (terminal) => {
                 if (worktreeDir === undefined)
                     return undefined;
@@ -1737,9 +1757,15 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 catch (e) {
                     worktreeKeptPath = worktreeDir;
-                    return `worktree: ${worktreeDir} (cleanup check failed: ${thrownText(e)})`;
+                    worktreeFault = thrownText(e);
+                    return `worktree: ${worktreeDir} (cleanup check failed — the directory is kept on disk)`;
                 }
             };
+            const reportedWorktreeLine = (line) => (line !== undefined && worktreeFault !== undefined ? `${line}: ${worktreeFault}` : line);
+            const faultDetails = (cause) => ({
+                ...(cause !== undefined ? { cause: thrownText(cause) } : {}),
+                ...(worktreeFault !== undefined ? { worktreeCause: worktreeFault } : {}),
+            });
             let injectedTools = [];
             let extraToolsNote;
             const treeBudget = extraToolsBudget ?? { used: 0 };
@@ -1779,13 +1805,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 const notStarted = async (why, details) => {
                     const wt = await finishWorktree();
-                    return { isError: true, content: `Sub-agent not started: ${why.slice(0, 1600)}${wt ? `\n${wt}` : ""}`, details };
+                    return notStartedResult({ isError: true, content: `Sub-agent not started: ${why.slice(0, 1600)}${wt ? `\n${wt}` : ""}`, details: { ...details, ...faultDetails() } });
                 };
                 if (ctx.signal?.aborted)
                     return notStarted("the parent task was aborted while extraTools was being evaluated.", { error: "aborted" });
                 const undeclared = opts.extraToolNames !== undefined ? firstUndeclaredExtraTool(opts.extraToolNames, injectedTools, toolName) : undefined;
                 if (undeclared !== undefined)
-                    return (reportExtraToolsError(extraToolNamesError(undeclared.sentence, undeclared.reason)), notStarted(undeclared.sentence, { error: EXTRA_TOOL_NAMES_CODE, reason: undeclared.reason }));
+                    return (reportExtraToolsError(extraToolNamesError(undeclared.sentence, undeclared.reason)), notStarted(UNDECLARED_EXTRA_TOOL_REFUSAL[undeclared.reason], { error: EXTRA_TOOL_NAMES_CODE, reason: undeclared.reason, cause: undeclared.sentence }));
             }
             const inherited = opts.tools === undefined && extraToolsNote === undefined ? inheritedChildPool(opts.inheritedTools ?? [], ctx.mountsCallerTool, wantsBackground && agentName === undefined && !wantsFork) : [];
             if (extraToolsNote !== undefined && opts.tools === undefined && (opts.inheritedTools?.length ?? 0) > 0)
@@ -2087,6 +2113,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(inheritedSkillGrants.length > 0 ? { inheritedSkillGrants } : {}),
                 ...(inheritedAllowedTools !== undefined && inheritedAllowedTools.length > 0 ? { inheritedAllowedTools: [...inheritedAllowedTools] } : {}),
                 ...(childProvenanceRef !== undefined && provenanceRequest !== undefined ? { delegationProvenance: { ref: childProvenanceRef, contentSafety: provenanceRequest } } : {}),
+                ...(reviveClaim === undefined && ctx.crossBoundaryTreeForChildren !== undefined ? { crossBoundaryTree: ctx.crossBoundaryTreeForChildren } : {}),
                 ...(treeScope !== undefined ? { registryScope: treeScope } : {}),
                 ...(ctx.checkpointScopeForChildren !== undefined ? { checkpointScope: ctx.checkpointScopeForChildren } : {}),
                 ...(ctx.inheritedGateForChildren ? { inheritedGate: ctx.inheritedGateForChildren() } : {}),
@@ -2360,16 +2387,16 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 if (ctx.signal?.aborted) {
                     await cancelObserver();
                     const wt = await finishWorktree();
-                    return spawnAbortedResult(wt);
+                    return spawnAbortedResult(wt, faultDetails());
                 }
                 if (spawnVerdict.kind === "block") {
                     await cancelObserver();
                     const wt = await finishWorktree();
-                    return {
+                    return notStartedResult({
                         isError: true,
                         content: `Sub-agent not started: blocked by the auto-mode classifier${spawnVerdict.reason ? `: ${inlineUntrusted(spawnVerdict.reason)}` : ""}.${wt ? `\n${wt}` : ""}`,
-                        details: { error: "autoMode.spawn_blocked" },
-                    };
+                        details: { error: "autoMode.spawn_blocked", ...faultDetails() },
+                    });
                 }
             }
             if (wantsFork) {
@@ -2387,11 +2414,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 catch (e) {
                     const wt = await finishWorktree();
-                    return { isError: true, content: `Sub-agent not started: session fork failed (${thrownText(e)}).${wt ? `\n${wt}` : ""}`, details: { error: "fork failed" } };
+                    return notStartedResult({ isError: true, content: `Sub-agent not started: session fork failed.${wt ? `\n${wt}` : ""}`, details: { error: "fork failed", ...faultDetails(e) } });
                 }
                 if (!forkedId) {
                     const wt = await finishWorktree();
-                    return { isError: true, content: `Sub-agent not started: source session not found or fork unavailable.${wt ? `\n${wt}` : ""}`, details: { error: "source not found", forkLane: ctx.hostSessionFork ? "host" : "child-runner", ...(ctx.sessionId !== undefined ? { sourceSessionId: ctx.sessionId } : {}) } };
+                    return notStartedResult({ isError: true, content: `Sub-agent not started: source session not found or fork unavailable.${wt ? `\n${wt}` : ""}`, details: { error: "source not found", forkLane: ctx.hostSessionFork ? "host" : "child-runner", ...(ctx.sessionId !== undefined ? { sourceSessionId: ctx.sessionId } : {}), ...faultDetails() } });
                 }
                 const forkInternals = { ...childInternals, insideFork: true, ...(ctx.reminderMark !== undefined ? { reminderMark: ctx.reminderMark } : {}) };
                 stepRecorder.lockTo(forkedId);
@@ -2425,7 +2452,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             }
                             await cancelObserver();
                             const wt = await finishWorktree();
-                            return errorResult(`Sub-agent not started in background: ${admission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: admission.refusal.code, code: admission.refusal.code });
+                            return notStartedResult(errorResult(`Sub-agent not started in background: ${admission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: admission.refusal.code, code: admission.refusal.code, ...faultDetails() }));
                         }
                     }
                     const forkSettlementSeat = ctx.delegationSettlement?.();
@@ -2437,11 +2464,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         catch (e) {
                             dropHostAbortListener();
                             const wt = await finishWorktree();
-                            return {
+                            return notStartedResult({
                                 isError: true,
-                                content: `Sub-agent not started in background: the delegation settlement account could not record the launch (${(thrownText(e)).slice(0, 300)}) — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
-                                details: { error: "settlement_write_ahead_failed" },
-                            };
+                                content: `Sub-agent not started in background: the delegation settlement account could not record the launch — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
+                                details: { error: "settlement_write_ahead_failed", ...faultDetails(e) },
+                            });
                         }
                     }
                     const settleForkRow = (terminal) => {
@@ -2496,6 +2523,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(rowModelKey !== undefined ? { model: rowModelKey } : {}),
                             deliveryChannel: "attaching",
                             toolUseId: ctx.toolCallId,
+                            ...(ctx.crossBoundaryTreeForChildren !== undefined ? { crossBoundaryTree: ctx.crossBoundaryTreeForChildren } : {}),
                             ...(bg.agentStore !== undefined ? { store: bg.agentStore } : {}),
                             abort,
                         });
@@ -2515,7 +2543,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             catch {
                             }
                         }
-                        return { isError: true, content: `Sub-agent not started in background: ${thrownText(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
+                        return notStartedResult({ isError: true, content: `Sub-agent not started in background: the background task could not be registered.${wt ? `\n${wt}` : ""}`, details: { error: "register_failed", ...faultDetails(e) } });
                     }
                     if (forkEntryGate.key !== undefined)
                         chargeDelegationEntryHandle(bg.registry, forkEntryGate.key, bg.agentStore, taskId);
@@ -2809,7 +2837,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     await cancelObserver();
                     const wt = await finishWorktree();
-                    return spawnAbortedResult(wt);
+                    return spawnAbortedResult(wt, faultDetails());
                 }
                 const syncForkAdmission = syncForkEntryGate.admit("local");
                 if (!syncForkAdmission.admitted) {
@@ -2820,7 +2848,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     await cancelObserver();
                     const wt = await finishWorktree();
-                    return errorResult(`Sub-agent not started: ${syncForkAdmission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: syncForkAdmission.refusal.code, code: syncForkAdmission.refusal.code });
+                    return notStartedResult(errorResult(`Sub-agent not started: ${syncForkAdmission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: syncForkAdmission.refusal.code, code: syncForkAdmission.refusal.code, ...faultDetails() }));
                 }
                 let forkChild;
                 try {
@@ -2862,7 +2890,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 if (isDurablePause(forkChild.terminal)) {
                     return durablePauseDelegationReport(` · ${FORK_SUBAGENT_TYPE}`, forkChild.terminal);
                 }
-                const wtLine = await finishWorktree();
+                const wtLine = reportedWorktreeLine(await finishWorktree());
                 const forkFace = childTerminalFace(forkChild.terminal);
                 const forkErr = classifySubagentError(forkChild.terminal);
                 const forkLines = [
@@ -2931,7 +2959,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         dropHostAbortListener();
                         await cancelObserver();
                         const wt = await finishWorktree();
-                        return errorResult(`Sub-agent not started in background: ${admission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: admission.refusal.code, code: admission.refusal.code });
+                        return notStartedResult(errorResult(`Sub-agent not started in background: ${admission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: admission.refusal.code, code: admission.refusal.code, ...faultDetails() }));
                     }
                 }
                 const settlementSeat = ctx.delegationSettlement?.();
@@ -2944,11 +2972,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         dropHostAbortListener();
                         await cancelObserver();
                         const wt = await finishWorktree();
-                        return {
+                        return notStartedResult({
                             isError: true,
-                            content: `Sub-agent not started in background: the delegation settlement account could not record the launch (${(thrownText(e)).slice(0, 300)}) — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
-                            details: { error: "settlement_write_ahead_failed" },
-                        };
+                            content: `Sub-agent not started in background: the delegation settlement account could not record the launch — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
+                            details: { error: "settlement_write_ahead_failed", ...faultDetails(e) },
+                        });
                     }
                 }
                 const settleDelegationRow = (terminal) => {
@@ -3038,6 +3066,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(rowModelKey !== undefined ? { model: rowModelKey } : {}),
                             deliveryChannel: "attaching",
                             toolUseId: ctx.toolCallId,
+                            ...(ctx.crossBoundaryTreeForChildren !== undefined ? { crossBoundaryTree: ctx.crossBoundaryTreeForChildren } : {}),
                             ...(bg.agentStore !== undefined ? { store: bg.agentStore } : {}),
                             abort,
                         });
@@ -3053,7 +3082,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         catch {
                         }
                     }
-                    return { isError: true, content: `Sub-agent not started in background: ${thrownText(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
+                    return notStartedResult({ isError: true, content: `Sub-agent not started in background: the background task could not be registered.${wt ? `\n${wt}` : ""}`, details: { error: "register_failed", ...faultDetails(e) } });
                 }
                 if (capLedgerKey !== undefined)
                     chargeDelegationEntryHandle(bg.registry, capLedgerKey, bg.agentStore, reviveRow === undefined ? taskId : undefined);
@@ -3640,18 +3669,23 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ]);
                     if (startup === "settled") {
                         if (parkedResume !== undefined) {
-                            const failure = await bgChildPromise.then((r) => ({ err: undefined, cause: resumeStartupCauseOf(r.terminal.kind === "failed" ? r.terminal.code : undefined) }), (e) => ({ err: childThrownText(e), cause: resumeStartupCauseOf(errorCodeOf(e)) }));
+                            const failure = await bgChildPromise.then((r) => ({ err: undefined, cause: resumeStartupCauseOf(r.terminal.kind === "failed" ? r.terminal.code : undefined), refusal: undefined }), (e) => ({ err: childThrownText(e), cause: resumeStartupCauseOf(errorCodeOf(e)), refusal: resumeRefusalDetailOf(thrownFailureOf(e, "").detail) }));
                             return {
                                 isError: true,
                                 content: `Parked resume did not complete: ${(failure.err ?? "the resumed run settled before its delivery lane bound").slice(0, 600)}`,
-                                details: { error: "parked_resume.startup_failed", task_id: taskId, ...(failure.cause !== undefined ? { cause: failure.cause } : {}) },
+                                details: {
+                                    error: "parked_resume.startup_failed",
+                                    task_id: taskId,
+                                    ...(failure.cause !== undefined ? { cause: failure.cause } : {}),
+                                    ...(failure.refusal !== undefined ? { detail: failure.refusal } : {}),
+                                },
                             };
                         }
-                        return {
+                        return notStartedResult({
                             isError: true,
                             content: `Sub-agent not revived: the revival failed during startup (its transcript session may be gone or the run could not prepare). This cycle settled failed; the message was NOT delivered — it remains queued and will be delivered if a later revival succeeds, so do not blindly resend the same content.`,
                             details: { error: "revive.startup_failed", task_id: taskId },
-                        };
+                        });
                     }
                 }
                 return {
@@ -3679,13 +3713,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             if (ctx.signal?.aborted) {
                 await cancelObserver();
                 const wt = await finishWorktree();
-                return spawnAbortedResult(wt);
+                return spawnAbortedResult(wt, faultDetails());
             }
             const syncAdmission = syncEntryGate.admit("local");
             if (!syncAdmission.admitted) {
                 await cancelObserver();
                 const wt = await finishWorktree();
-                return errorResult(`Sub-agent not started: ${syncAdmission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: syncAdmission.refusal.code, code: syncAdmission.refusal.code });
+                return notStartedResult(errorResult(`Sub-agent not started: ${syncAdmission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: syncAdmission.refusal.code, code: syncAdmission.refusal.code, ...faultDetails() }));
             }
             const syncStartedAt = Date.now();
             let retainEntry;
@@ -3780,7 +3814,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                 }
             }
-            const worktreeLine = await finishWorktree(child.terminal);
+            const worktreeLine = reportedWorktreeLine(await finishWorktree(child.terminal));
             if (worktreeDir !== undefined && placementRefused(child.terminal))
                 return isolationUnavailable(WORKTREE_UNAVAILABLE.notHonored);
             const errClass = classifySubagentError(child.terminal);

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

@@ -1,5 +1,5 @@
 import type { AgentDefinition, ToolSpec } from "../core/types.js";
-import type { ToolLegKind, ToolSelector, ToolSelectorLayer } from "../core/tool-face.js";
+import { type ToolLegKind, type ToolSelector, type ToolSelectorLayer } from "../core/tool-face.js";
 import { type ProtocolId } from "../core/protocol-table.js";
 import { type ToolNameListReading } from "../core/tool-name-list.js";
 /**
@@ -121,6 +121,9 @@ type UniverseTool = {
     readonly name: string;
     readonly aliases?: readonly string[];
 };
+/** Do the layers ABOVE a leg decide a protocol row of these kinds? Yes when some kind of the row shares its spawner's tool surface
+ *  ({@link SPAWNER_SURFACE_LEG_KINDS}): the leg holds it exactly when its spawner may. Any other row is the leg's own channel. */
+export declare function protocolRowUnderCeiling(rowLegs: readonly ToolLegKind[]): boolean;
 /** The wire names a leg of these kinds relies on (the catalog's protocol column). */
 export declare function protocolToolNames(legs: readonly ToolLegKind[]): string[];
 /** Is this value a layer — an object (not a list) with the two lists `allow` / `deny`? One that is not admits NOTHING here;
@@ -130,11 +133,29 @@ export declare function isToolSelectorLayer(layer: unknown): layer is ToolSelect
  * 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.
+ * and whatever the ceiling says too, unless a kind of its row shares its spawner's tool surface ({@link protocolRowUnderCeiling}):
+ * 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 compileToolSelector(layers: readonly ToolSelectorLayer[], legs?: readonly ToolLegKind[]): ToolSelector;
+/**
+ * What a leg's tool valve leaves mounted — its one reading: nothing under the run's whole-face switch (`excludeAllTools`: every
+ * tool unmounts, protocol tools included), else what the compiled selector admits. The valve unmounts by it, and every question
+ * prepare asks about the post-valve roster before the valve runs (the full shell's reachability, the memory write channel, the
+ * persistence verdict, the two memory pairs' planning) asks it too.
+ */
+export declare function valveLeaves(spec: {
+    readonly excludeAllTools?: true;
+}, selector: Pick<ToolSelector, "admits">): (tool: UniverseTool) => boolean;
+/**
+ * The valve's reading at the SERVER level — {@link valveLeaves} asked of a whole peer before any of its tools is known: can the valve
+ * leave a tool of the peer `prefix` (`mcp__srv__`) at all? Nothing under the run's whole-face switch; else what the compiled selector's
+ * lists can reach of the peer ({@link ToolSelector.admitsPeer} — read off the lists, never off what the server lists). A peer this
+ * answers `false` for leaves no tool on the roster whatever it lists, so a run has no reason to dial it or to teach its instructions.
+ */
+export declare function valveLeavesPeer(spec: {
+    readonly excludeAllTools?: true;
+}, selector: Pick<ToolSelector, "admitsPeer">): (prefix: string) => boolean;
 /** 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;