@sema-agent/core 7.51.2 → 7.53.0

package/dist/agents/subagent.js

@@ -1,6 +1,7 @@
 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";
@@ -264,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"),
@@ -272,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" },
@@ -284,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,
@@ -1062,10 +1081,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";
@@ -1358,7 +1377,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
         ...(forkOffered ? [{ name: FORK_SUBAGENT_TYPE, ...(depthPermitsNesting ? { canRedelegate: true } : {}) }] : []),
     ];
     const agentToolPool = delegationPoolFace(opts.tools ?? opts.inheritedTools ?? [], opts.extraTools !== undefined, opts.extraToolNames);
-    return {
+    return bindDelegationName(delegationToolName, {
         name: opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME,
         ...toolFace("agent"),
         agentListing,
@@ -1459,22 +1478,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;
@@ -1484,11 +1503,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];
@@ -1496,62 +1515,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) {
@@ -1559,21 +1578,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" &&
@@ -1583,18 +1602,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;
@@ -1639,11 +1658,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" },
-                            };
+                            });
                         }
                     }
                 }
@@ -1692,11 +1711,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") {
@@ -1710,15 +1729,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;
@@ -1736,9 +1758,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 };
@@ -1778,13 +1806,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)
@@ -1813,7 +1841,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             }
             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 childListsDigest = toolListsDigest(childOwnLayer.allow, childOwnLayer.deny);
+            const childListsJudged = agentToolPool !== undefined ? childListsDigest : undefined;
             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;
@@ -2079,7 +2108,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 : undefined;
             const childInternals = {
                 ...(ctx.toolSelector !== undefined ? { toolCeiling: childCeiling, ...(childListsJudged !== undefined ? { toolListsJudged: childListsJudged } : {}) } : {}),
-                ownToolListsWhere: delegationListWhere(toolName, def?.name),
+                ...(childListsDigest !== undefined ? { ownToolLists: { toolName, ...(def !== undefined ? { definition: def.name } : {}), lists: childListsDigest } } : {}),
                 ...(parentMcp?.pool !== undefined && childMcp !== undefined && childMcp.length > 0 ? { mcpPool: parentMcp.pool } : {}),
                 ...(childPick.modelRef !== undefined ? { inheritedModelRef: childPick.modelRef } : {}),
                 ...(inheritedSkillGrants.length > 0 ? { inheritedSkillGrants } : {}),
@@ -2358,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) {
@@ -2385,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);
@@ -2423,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?.();
@@ -2435,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) => {
@@ -2513,7 +2542,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);
@@ -2807,7 +2836,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) {
@@ -2818,7 +2847,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 {
@@ -2860,7 +2889,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 = [
@@ -2929,7 +2958,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?.();
@@ -2942,11 +2971,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) => {
@@ -3051,7 +3080,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);
@@ -3645,11 +3674,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 details: { error: "parked_resume.startup_failed", task_id: taskId, ...(failure.cause !== undefined ? { cause: failure.cause } : {}) },
                             };
                         }
-                        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 {
@@ -3677,13 +3706,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;
@@ -3778,7 +3807,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);
@@ -3853,5 +3882,5 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }),
             };
         },
-    };
+    });
 }