@sema-agent/core 7.50.2 → 7.51.0

package/dist/agents/subagent.d.ts

@@ -30,11 +30,10 @@ import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js
  * key is ABSENT rather than zeroed — a fabricated 0 reads as "ran no tools", which is a claim, not a
  * gap. Duration is always knowable (the caller holds the lane's launch instant), so it is unconditional.
  *
- * TWO SPELLINGS, one meaning, matching each face's established vocabulary: the observer
- * ({@link import("../core/types.js").BackgroundChildEvent}) `usage` face is camelCase and already
- * DECLARES `toolUses`/`durationMs`; the model-facing `TaskNotificationPayload.usage` is rendered into
- * `<usage>` as JSON where the workflow lane and the Agent sync footer both spell them snake_case. No new
- * word is minted on either side.
+ * ONE mint, in the model-facing `TaskNotificationPayload.usage` spelling (rendered into `<usage>` as JSON,
+ * where the workflow lane and the Agent sync footer both spell them snake_case); the observer
+ * ({@link import("../core/types.js").BackgroundChildEvent}) face's camelCase `toolUses`/`durationMs` is
+ * that frame's projection (`backgroundChildTerminal`), so the two faces cannot report different numbers.
  *
  * Exported at MODULE level (not from the package index — the same posture as `completedAgentCard` and
  * `classifySubagentError`): the ABSENT arm is the point of the knownness rule and is not reachable
@@ -43,13 +42,6 @@ import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js
  * optional-and-missing shape the stats face declares, and a pin that only sees a live child cannot
  * tell "absent" apart from "zero".
  */
-export declare function delegatedGranularityFields(stats: {
-    toolCalls?: number;
-}, elapsedMs: number): {
-    toolUses?: number;
-    durationMs: number;
-};
-/** {@link delegatedGranularityFields}'s snake_case twin for the model-facing notification `usage`. */
 export declare function delegatedGranularityFieldsWire(stats: {
     toolCalls?: number;
 }, elapsedMs: number): {
@@ -60,7 +52,6 @@ export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type PeerSelfRef } from "./peer-admission.js";
 export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
-export declare function notifyResultField(result: string | undefined): string | undefined;
 /** What {@link layeredReviewSample} produced: the text actually sent, plus the honest read/total counts. */
 interface ReviewSample {
     text: string;

package/dist/agents/subagent.js

@@ -1,5 +1,8 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
+import { backgroundChildTerminal } from "../core/delegation-frames.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 { assertNoRetiredKeys } from "../core/retired-keys.js";
@@ -36,7 +39,7 @@ import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { readDurableOrgAdmission } from "../core/memory-admission.js";
 import { governanceRetryClass } from "../core/governance-codes.js";
 import { readSkillGrantCapture } from "../core/skill-grant.js";
-import { terminalFrameFacets } from "../core/task-notification.js";
+import { notifyResultField, terminalFrameFacets } from "../core/task-notification.js";
 import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS, DELEGATION_MAX_CONCURRENT_DEFAULT, DELEGATION_MAX_PER_SESSION_DEFAULT } from "../config/defaults.js";
 function rollupDelegatedCost(stats, nested) {
     if (stats.costMicroUsd === undefined)
@@ -49,8 +52,8 @@ function delegatedCostField(stats) {
     const total = rollupDelegatedCost(stats, stats.nested);
     return total !== undefined ? { costMicroUsd: total } : {};
 }
-export function delegatedGranularityFields(stats, elapsedMs) {
-    return { ...(stats.toolCalls !== undefined ? { toolUses: stats.toolCalls } : {}), durationMs: elapsedMs };
+export function delegatedGranularityFieldsWire(stats, elapsedMs) {
+    return { ...(stats.toolCalls !== undefined ? { tool_uses: stats.toolCalls } : {}), duration_ms: elapsedMs };
 }
 function providerFaultField(child) {
     if (child.apiFailure === undefined)
@@ -62,9 +65,6 @@ function providerFaultField(child) {
         },
     };
 }
-export function delegatedGranularityFieldsWire(stats, elapsedMs) {
-    return { ...(stats.toolCalls !== undefined ? { tool_uses: stats.toolCalls } : {}), duration_ms: elapsedMs };
-}
 export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
 import { createPeerInboundChainRef, createPeerSelfRef } from "./peer-admission.js";
@@ -84,14 +84,6 @@ function resultSettleFields(result) {
     const display = full.length > BG_AGENT_RESULT_MAX ? boundedRedactedSummary(result, BG_AGENT_RESULT_MAX) : full;
     return display === full ? { result: display } : { result: display, resultFull: full };
 }
-const BG_AGENT_NOTIFY_RESULT_MAX = 2_000;
-export function notifyResultField(result) {
-    if (!result)
-        return undefined;
-    return result.length > BG_AGENT_NOTIFY_RESULT_MAX
-        ? `${result.slice(0, BG_AGENT_NOTIFY_RESULT_MAX)}\n[result truncated: ${result.length} chars total — ask the agent for it via SendMessage, or read it with TaskOutput where mounted]`
-        : result;
-}
 const HANDBACK_REVIEW_SAMPLE_BUDGET = 12_000;
 const HANDBACK_REVIEW_SAMPLE_WINDOWS = 5;
 const HANDBACK_REVIEW_SAMPLE_MAX_WINDOWS = 16;
@@ -759,23 +751,6 @@ export function createSubagentResume(deps) {
                     named: deps.rowName !== undefined,
                 });
                 const ownsTerminalFacesRevive = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.claimAgentTerminalNotify(deps.taskId) : true;
-                if (ownsTerminalFacesRevive)
-                    reviveEmit?.({
-                        kind: "terminal",
-                        taskId: deps.taskId,
-                        sessionScoped: deps.sessionScoped === true,
-                        sessionId: entry.childSessionId,
-                        transcriptId: entry.childSessionId,
-                        ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}),
-                        status,
-                        seq: entry.cycleSeq,
-                        ...(stoppedByRevive !== undefined ? { stoppedBy: stoppedByRevive } : {}),
-                        summary: reviveTerminalSummary,
-                        ...resumeResidual(),
-                        resumable: resumableRevive,
-                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFields(child.stats, reviveElapsedMs) },
-                        ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
-                    });
                 const resumeFrame = {
                     task_id: deps.taskId ?? entry.childSessionId,
                     ...(entry.childSessionId !== undefined ? { sessionId: entry.childSessionId } : {}),
@@ -796,6 +771,8 @@ export function createSubagentResume(deps) {
                     usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, reviveElapsedMs) },
                     ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                 };
+                if (ownsTerminalFacesRevive)
+                    reviveEmit?.(backgroundChildTerminal(resumeFrame, { taskId: deps.taskId, sessionScoped: deps.sessionScoped === true, sessionId: entry.childSessionId, transcriptId: entry.childSessionId, ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}) }));
                 const gateOwner = ownsTerminalFacesRevive && status === "completed" && deps.notify !== undefined && deps.registry !== undefined && ledger.get(deps.parentToolCallId) === entry
                     ? entry.childSessionId
                     : undefined;
@@ -838,35 +815,24 @@ export function createSubagentResume(deps) {
                 const completionIdRejectRevive = deps.registry?.getCompletionId(deps.taskId ?? "");
                 const rejectName = deps.rowDescription ?? `sub-agent ${marker}`;
                 const ownsTerminalFacesReviveReject = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.claimAgentTerminalNotify(deps.taskId) : true;
+                const reviveRejectFrame = {
+                    task_id: deps.taskId ?? entry.childSessionId,
+                    ...(entry.childSessionId !== undefined ? { sessionId: entry.childSessionId } : {}),
+                    task_type: "background_agent",
+                    toolUseId: deps.parentToolCallId,
+                    status: abort.signal.aborted ? "killed" : "failed",
+                    seq: entry.cycleSeq,
+                    ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
+                    summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : `failed: ${msgRevive}`}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + (abort.signal.aborted ? "" : errorKindClause(errClassReviveReject)),
+                    ...(abort.signal.aborted ? {} : { error: msgRevive.slice(0, REPORT_FIELD_MAX) }),
+                    ...(!abort.signal.aborted && errCodeReviveReject !== undefined ? { errorCode: errCodeReviveReject } : {}),
+                    ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
+                };
                 if (ownsTerminalFacesReviveReject)
-                    reviveEmit?.({
-                        kind: "terminal",
-                        taskId: deps.taskId,
-                        sessionScoped: deps.sessionScoped === true,
-                        sessionId: entry.childSessionId,
-                        transcriptId: entry.childSessionId,
-                        ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}),
-                        status: abort.signal.aborted ? "killed" : "failed",
-                        seq: entry.cycleSeq,
-                        ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
-                        summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : "failed"}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + (abort.signal.aborted ? "" : errorKindClause(errClassReviveReject)),
-                        ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
-                    });
+                    reviveEmit?.(backgroundChildTerminal(reviveRejectFrame, { taskId: deps.taskId, sessionScoped: deps.sessionScoped === true, sessionId: entry.childSessionId, transcriptId: entry.childSessionId, ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}) }));
                 try {
                     if (ownsTerminalFacesReviveReject)
-                        deps.notify?.({
-                            task_id: deps.taskId ?? entry.childSessionId,
-                            ...(entry.childSessionId !== undefined ? { sessionId: entry.childSessionId } : {}),
-                            task_type: "background_agent",
-                            toolUseId: deps.parentToolCallId,
-                            status: abort.signal.aborted ? "killed" : "failed",
-                            seq: entry.cycleSeq,
-                            ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
-                            summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : `failed: ${msgRevive}`}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + (abort.signal.aborted ? "" : errorKindClause(errClassReviveReject)),
-                            ...(abort.signal.aborted ? {} : { error: msgRevive.slice(0, REPORT_FIELD_MAX) }),
-                            ...(!abort.signal.aborted && errCodeReviveReject !== undefined ? { errorCode: errCodeReviveReject } : {}),
-                            ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
-                        }, { priority: "next" });
+                        deps.notify?.(reviveRejectFrame, { priority: "next" });
                 }
                 catch {
                 }
@@ -2557,32 +2523,19 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const stoppedByReap = bg.registry.getStopAttribution(taskId) ?? "system";
                         const completionIdReap = bg.registry.getCompletionId(taskId);
                         const seqReap = bg.registry.backgroundAgentCycleSeq(taskId);
-                        const summaryReap = ccCompletionText(shortDesc, "killed", "killed", Date.now() - forkBgHangAt);
-                        sinkEmit({
-                            kind: "terminal",
-                            taskId,
-                            sessionScoped: sessionScopedBg === true,
-                            sessionId: forkedId,
-                            transcriptId: forkedId,
-                            parentToolCallId: ctx.toolCallId,
-                            status: "killed",
-                            ...(seqReap !== undefined ? { seq: seqReap } : {}),
-                            stoppedBy: stoppedByReap,
-                            summary: summaryReap,
-                            resumable: false,
-                            ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
-                        });
-                        notifier.notify(() => notify?.({
+                        const reapFrame = {
                             task_id: taskId,
                             task_type: "background_agent",
                             toolUseId: ctx.toolCallId,
                             status: "killed",
                             stoppedBy: stoppedByReap,
-                            summary: summaryReap,
+                            summary: ccCompletionText(shortDesc, "killed", "killed", Date.now() - forkBgHangAt),
                             sessionId: forkedId,
                             resumable: false,
                             ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
-                        }, { priority: "next" }), "subagent.reapTerminalNotify");
+                        };
+                        sinkEmit(backgroundChildTerminal(reapFrame, { taskId, sessionScoped: sessionScopedBg === true, sessionId: forkedId, transcriptId: forkedId, parentToolCallId: ctx.toolCallId, ...(seqReap !== undefined ? { generation: seqReap } : {}) }));
+                        notifier.notify(() => notify?.(reapFrame, { priority: "next" }), "subagent.reapTerminalNotify");
                     });
                     if (agentName !== undefined) {
                         recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, sessionId: forkedId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...(rowModelKey !== undefined ? { model: rowModelKey } : {}), ...(modelFallback !== undefined ? { modelFallback } : {}), ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
@@ -2752,44 +2705,30 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(forkElapsedMs)}`.slice(0, 300) + errorKindClause(errClassFork)
                             : `${ccCompletionText(shortDesc, settledBg, childFace.status, forkElapsedMs)}`;
                         const ownsTerminalFacesFork = bg.registry.claimAgentTerminalNotify(taskId);
+                        const forkFrame = {
+                            task_id: taskId,
+                            task_type: "background_agent",
+                            toolUseId: ctx.toolCallId,
+                            status: settledBg,
+                            ...terminalFrameFacets({ spawnName: agentName, result: forkBgResult, warning: forkBgWarning, compaction: child.compaction }),
+                            ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
+                            summary: forkTerminalSummary,
+                            ...(failReasonFork !== undefined ? { error: failReasonFork.slice(0, REPORT_FIELD_MAX) } : {}),
+                            ...(settledBg === "failed" && errCodeFork !== undefined ? { errorCode: errCodeFork } : {}),
+                            ...providerFaultField(child),
+                            ...(child.sessionId ? { sessionId: child.sessionId } : {}),
+                            ...(forkBgResult ? { result: notifyResultField(forkBgResult) } : {}),
+                            ...(settledBg === "killed" && child.result ? { partial: true } : {}),
+                            ...residualFork,
+                            resumable: resumableFork,
+                            usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, forkElapsedMs) },
+                            ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
+                        };
                         if (ownsTerminalFacesFork)
-                            sinkEmit({
-                                kind: "terminal",
-                                taskId,
-                                sessionScoped: sessionScopedBg === true,
-                                sessionId: forkTranscriptId,
-                                ...(stillbornFork ? {} : { transcriptId: forkTranscriptId }),
-                                parentToolCallId: ctx.toolCallId,
-                                status: settledBg,
-                                ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
-                                ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                                summary: forkTerminalSummary,
-                                ...residualFork,
-                                resumable: resumableFork,
-                                usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFields(child.stats, forkElapsedMs) },
-                                ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
-                            });
+                            sinkEmit(backgroundChildTerminal(forkFrame, { taskId, sessionScoped: sessionScopedBg === true, sessionId: forkTranscriptId, ...(stillbornFork ? {} : { transcriptId: forkTranscriptId }), parentToolCallId: ctx.toolCallId, ...(bgForkCycleSeq !== undefined ? { generation: bgForkCycleSeq } : {}) }));
                         try {
                             if (ownsTerminalFacesFork)
-                                notify?.({
-                                    task_id: taskId,
-                                    task_type: "background_agent",
-                                    toolUseId: ctx.toolCallId,
-                                    status: settledBg,
-                                    ...terminalFrameFacets({ spawnName: agentName, result: forkBgResult, warning: forkBgWarning, compaction: child.compaction }),
-                                    ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                                    summary: forkTerminalSummary,
-                                    ...(failReasonFork !== undefined ? { error: failReasonFork.slice(0, REPORT_FIELD_MAX) } : {}),
-                                    ...(settledBg === "failed" && errCodeFork !== undefined ? { errorCode: errCodeFork } : {}),
-                                    ...providerFaultField(child),
-                                    ...(child.sessionId ? { sessionId: child.sessionId } : {}),
-                                    ...(forkBgResult ? { result: notifyResultField(forkBgResult) } : {}),
-                                    ...(settledBg === "killed" && child.result ? { partial: true } : {}),
-                                    ...residualFork,
-                                    resumable: resumableFork,
-                                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, forkElapsedMs) },
-                                    ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
-                                }, { priority: "next" });
+                                notify?.(forkFrame, { priority: "next" });
                         }
                         catch {
                         }
@@ -2813,35 +2752,24 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const completionIdForkReject = bg.registry.getCompletionId(taskId);
                         const summaryBg = `${shortDesc} — ${settledBg === "failed" ? `failed: ${msgFork}` : settledBg}`.slice(0, 300) + (settledBg === "failed" ? errorKindClause(errClassForkReject) : "");
                         const ownsTerminalFacesForkReject = bg.registry.claimAgentTerminalNotify(taskId);
+                        const forkRejectFrame = {
+                            task_id: taskId,
+                            task_type: "background_agent",
+                            toolUseId: ctx.toolCallId,
+                            status: settledBg,
+                            ...terminalFrameFacets({ spawnName: agentName }),
+                            sessionId: forkedId,
+                            ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
+                            summary: summaryBg,
+                            ...(settledBg === "failed" ? { error: msgFork.slice(0, REPORT_FIELD_MAX) } : {}),
+                            ...(settledBg === "failed" && errCodeForkReject !== undefined ? { errorCode: errCodeForkReject } : {}),
+                            ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
+                        };
                         if (ownsTerminalFacesForkReject)
-                            sinkEmit({
-                                kind: "terminal",
-                                taskId,
-                                sessionScoped: sessionScopedBg === true,
-                                sessionId: forkedId,
-                                transcriptId: forkedId,
-                                parentToolCallId: ctx.toolCallId,
-                                status: settledBg,
-                                ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
-                                ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                                summary: summaryBg,
-                                ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
-                            });
+                            sinkEmit(backgroundChildTerminal(forkRejectFrame, { taskId, sessionScoped: sessionScopedBg === true, sessionId: forkedId, transcriptId: forkedId, parentToolCallId: ctx.toolCallId, ...(bgForkCycleSeq !== undefined ? { generation: bgForkCycleSeq } : {}) }));
                         try {
                             if (ownsTerminalFacesForkReject)
-                                notify?.({
-                                    task_id: taskId,
-                                    task_type: "background_agent",
-                                    toolUseId: ctx.toolCallId,
-                                    status: settledBg,
-                                    ...terminalFrameFacets({ spawnName: agentName }),
-                                    sessionId: forkedId,
-                                    ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                                    summary: summaryBg,
-                                    ...(settledBg === "failed" ? { error: msgFork.slice(0, REPORT_FIELD_MAX) } : {}),
-                                    ...(settledBg === "failed" && errCodeForkReject !== undefined ? { errorCode: errCodeForkReject } : {}),
-                                    ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
-                                }, { priority: "next" });
+                                notify?.(forkRejectFrame, { priority: "next" });
                         }
                         catch {
                         }
@@ -3147,33 +3075,20 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const stoppedByReap = bg.registry.getStopAttribution(taskId) ?? "system";
                     const completionIdReap = bg.registry.getCompletionId(taskId);
                     const seqReap = bg.registry.backgroundAgentCycleSeq(taskId);
-                    const summaryReap = ccCompletionText(shortDesc, "killed", "killed", Date.now() - bgStartedAt);
-                    sinkEmit({
-                        kind: "terminal",
-                        taskId,
-                        sessionScoped: sessionScopedBg === true,
-                        sessionId: bgChildSessionId,
-                        transcriptId: bgChildSessionId,
-                        parentToolCallId: ctx.toolCallId,
-                        status: "killed",
-                        ...(seqReap !== undefined ? { seq: seqReap } : {}),
-                        stoppedBy: stoppedByReap,
-                        summary: summaryReap,
-                        resumable: false,
-                        ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
-                    });
-                    notifier.notify(() => notify?.({
+                    const reapFrame = {
                         task_id: taskId,
                         task_type: "background_agent",
                         toolUseId: ctx.toolCallId,
                         status: "killed",
                         ...terminalFrameFacets({ spawnName: agentName }),
                         stoppedBy: stoppedByReap,
-                        summary: summaryReap,
+                        summary: ccCompletionText(shortDesc, "killed", "killed", Date.now() - bgStartedAt),
                         sessionId: bgChildSessionId,
                         resumable: false,
                         ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
-                    }, { priority: "next" }), "subagent.reapTerminalNotify");
+                    };
+                    sinkEmit(backgroundChildTerminal(reapFrame, { taskId, sessionScoped: sessionScopedBg === true, sessionId: bgChildSessionId, transcriptId: bgChildSessionId, parentToolCallId: ctx.toolCallId, ...(seqReap !== undefined ? { generation: seqReap } : {}) }));
+                    notifier.notify(() => notify?.(reapFrame, { priority: "next" }), "subagent.reapTerminalNotify");
                 });
                 const bgDurableProbe = bg.registry.durableAgentRowProbe(taskId);
                 const bgRowConfirmed = async () => (bgDurableProbe ? await bgDurableProbe().catch(() => false) : false);
@@ -3346,7 +3261,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ? `parked resume rolled back — the approval is still pending (retryable): ${msg}`
                             : disp === "failed"
                                 ? `parked resume failed — the approval is no longer redeemable: ${msg}`
-                                : `parked resume did not proceed (${disp}): ${msg}`);
+                                : `parked resume did not proceed (${disp}): ${msg}`, { cause: e });
                     };
                     try {
                         await opts.runner.sessions.acquire(bgChildSessionId, { requireExisting: true });
@@ -3364,7 +3279,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             catch {
                             }
                         }
-                        return rollbackAndThrow(e);
+                        return rollbackAndThrow(code === "not_found" ? Object.assign(new Error(thrownText(e), { cause: e }), { code: "resume.session_not_found" }) : e);
                     }
                     if (opts.tools === undefined && (opts.inheritedTools?.length ?? 0) > 0 && ctx.mountsCallerTool === undefined && pr.outcome.gate === "policy_ask" && pr.outcome.decision === "allow") {
                         let pending;
@@ -3376,7 +3291,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                         const name = pending?.kind === "tool_approval" ? pending.toolName : undefined;
                         if (name !== undefined && (opts.inheritedTools ?? []).some((t) => t.name === name) && !(bgSpec.tools ?? []).some((t) => t.name === name)) {
-                            return rollbackAndThrow(new Error(`the approved tool "${name}" is one the agent inherits from its spawning run, and this resume was driven without the \`mountsCallerTool\` seat, so the resumed agent would not have it. The host must pass the seat built from the row's own session (never a boot-time bundle: its task list has no session and would be shared by every revived agent). Deny still resolves this approval.`));
+                            return rollbackAndThrow(Object.assign(new Error(`the approved tool "${name}" is one the agent inherits from its spawning run, and this resume was driven without the \`mountsCallerTool\` seat, so the resumed agent would not have it. The host must pass the seat built from the row's own session (never a boot-time bundle: its task list has no session and would be shared by every revived agent). Deny still resolves this approval.`), { code: "resume.tool_unavailable" }));
                         }
                     }
                     {
@@ -3453,7 +3368,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     return await cpS.expire(pr.ticket.token, cp.scope);
                                 },
                             });
-                            throw new Error(`parked resume could not complete and the approval was REOPENED (still approvable/retryable): ${childResult.terminal.message ?? "failed"}`);
+                            throw new Error(`parked resume could not complete and the approval was REOPENED (still approvable/retryable): ${childResult.terminal.message ?? "failed"}`, { cause: childResult.terminal });
                         }
                     }
                     return childResult;
@@ -3614,22 +3529,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(bgElapsedMs)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
                         : `${ccCompletionText(shortDesc, settled, childFace.status, bgElapsedMs)}${observerNote}`;
                     const ownsTerminalFaces = bg.registry.claimAgentTerminalNotify(taskId);
-                    if (ownsTerminalFaces)
-                        sinkEmit({
-                            kind: "terminal",
-                            taskId,
-                            sessionScoped: sessionScopedBg === true,
-                            ...(child.sessionId ? { sessionId: child.sessionId, transcriptId: child.sessionId } : {}),
-                            parentToolCallId: ctx.toolCallId,
-                            status: settled,
-                            ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
-                            ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                            summary: bgTerminalSummary,
-                            ...residual,
-                            resumable: resumableBg,
-                            usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFields(child.stats, bgElapsedMs) },
-                            ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
-                        });
                     const completionFrame = {
                         task_id: taskId,
                         task_type: "background_agent",
@@ -3650,6 +3549,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, bgElapsedMs) },
                         ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
                     };
+                    if (ownsTerminalFaces)
+                        sinkEmit(backgroundChildTerminal(completionFrame, { taskId, sessionScoped: sessionScopedBg === true, ...(child.sessionId ? { sessionId: child.sessionId, transcriptId: child.sessionId } : {}), parentToolCallId: ctx.toolCallId, ...(bgCycleSeq !== undefined ? { generation: bgCycleSeq } : {}) }));
                     const gateOwner = ownsTerminalFaces && settled === "completed" && notify !== undefined ? bgRetain?.childSessionId : undefined;
                     const aliveBgCount = gateOwner !== undefined ? bg.registry.countRunningBackgroundForOwner(gateOwner) : 0;
                     if (gateOwner !== undefined && bgRetain !== undefined && aliveBgCount > 0) {
@@ -3706,36 +3607,25 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const completionIdBgReject = bg.registry.getCompletionId(taskId);
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
                     const ownsTerminalFacesReject = bg.registry.claimAgentTerminalNotify(taskId);
+                    const rejectFrame = {
+                        task_id: taskId,
+                        task_type: "background_agent",
+                        toolUseId: ctx.toolCallId,
+                        status: settled,
+                        ...terminalFrameFacets({ spawnName: agentName }),
+                        sessionId: bgChildSessionId,
+                        ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
+                        ...(stoppedBy !== undefined ? { stoppedBy } : {}),
+                        summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + (settled === "failed" ? errorKindClause(errClassBgReject) : ""),
+                        ...(settled === "failed" ? { error: msg.slice(0, REPORT_FIELD_MAX) } : {}),
+                        ...(settled === "failed" && errCodeBgReject !== undefined ? { errorCode: errCodeBgReject } : {}),
+                        ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
+                    };
                     if (ownsTerminalFacesReject)
-                        sinkEmit({
-                            kind: "terminal",
-                            taskId,
-                            sessionScoped: sessionScopedBg === true,
-                            sessionId: bgChildSessionId,
-                            transcriptId: bgChildSessionId,
-                            parentToolCallId: ctx.toolCallId,
-                            status: settled,
-                            ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
-                            ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                            summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + (settled === "failed" ? errorKindClause(errClassBgReject) : ""),
-                            ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
-                        });
+                        sinkEmit(backgroundChildTerminal(rejectFrame, { taskId, sessionScoped: sessionScopedBg === true, sessionId: bgChildSessionId, transcriptId: bgChildSessionId, parentToolCallId: ctx.toolCallId, ...(bgCycleSeq !== undefined ? { generation: bgCycleSeq } : {}) }));
                     try {
                         if (ownsTerminalFacesReject)
-                            notify?.({
-                                task_id: taskId,
-                                task_type: "background_agent",
-                                toolUseId: ctx.toolCallId,
-                                status: settled,
-                                ...terminalFrameFacets({ spawnName: agentName }),
-                                sessionId: bgChildSessionId,
-                                ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
-                                ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                                summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + (settled === "failed" ? errorKindClause(errClassBgReject) : ""),
-                                ...(settled === "failed" ? { error: msg.slice(0, REPORT_FIELD_MAX) } : {}),
-                                ...(settled === "failed" && errCodeBgReject !== undefined ? { errorCode: errCodeBgReject } : {}),
-                                ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
-                            }, { priority: "next" });
+                            notify?.(rejectFrame, { priority: "next" });
                     }
                     catch {
                     }
@@ -3747,11 +3637,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ]);
                     if (startup === "settled") {
                         if (parkedResume !== undefined) {
-                            const err = await bgChildPromise.then(() => undefined, (e) => childThrownText(e));
+                            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)) }));
                             return {
                                 isError: true,
-                                content: `Parked resume did not complete: ${(err ?? "the resumed run settled before its delivery lane bound").slice(0, 600)}`,
-                                details: { error: "parked_resume.startup_failed", task_id: taskId },
+                                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 } : {}) },
                             };
                         }
                         return {

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

@@ -16,8 +16,8 @@ import { type ToolNameListReading } from "../core/tool-name-list.js";
  *
  * 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`).
+ * tools of that peer, including ones it lists later; an entry no tool answers to is kept by name and reaches one mounted later.
+ * Judged at the prepare that receives it: a spelling no tool name can have is refused, an unknown name told (`sub-agent-deny-lists.ts`).
  *
  * 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).

package/dist/brain/anthropic.d.ts

@@ -42,4 +42,4 @@ export interface AnthropicBrainConfig extends StreamEngineConfig {
  * read-loop machinery lives in the shared {@link runStreamingBrain} engine (design/32); this adapter
  * owns the Anthropic request shaping + typed content-block SSE parsing + finalization.
  */
-export declare function createAnthropicBrain(config?: AnthropicBrainConfig): Brain;
+export declare function createAnthropicBrain(given?: AnthropicBrainConfig): Brain;

package/dist/brain/anthropic.js

@@ -7,7 +7,7 @@ import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCal
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -226,7 +226,9 @@ function closeToolUseBlock(acc, responseIds, closed) {
     acc.closedTc = { type: "toolCall", id: engineId, ...(wireId !== engineId ? { wireId } : {}), name: acc.toolName, arguments: args };
     return acc.closedTc;
 }
-export function createAnthropicBrain(config = {}) {
+const ANTHROPIC_LANE_DEFAULT = "https://api.anthropic.com";
+export function createAnthropicBrain(given = {}) {
+    const config = brainConfigSnapshot(given, "createAnthropicBrain config");
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     refuseRetiredTimeoutKnobs(config, "construction", "createAnthropicBrain config");
     const doFetch = resolveFetch(config);
@@ -244,7 +246,7 @@ export function createAnthropicBrain(config = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl, "https://api.anthropic.com");
+                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl, ANTHROPIC_LANE_DEFAULT);
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
                     optionsHeaders: options?.headers,
@@ -252,7 +254,7 @@ export function createAnthropicBrain(config = {}) {
                     configApiKey: config.apiKey,
                     configHeaders: config.headers,
                 });
-                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl, laneDefault: ANTHROPIC_LANE_DEFAULT });
                 if (!routeVerdict.ok)
                     throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
                 const apiKey = routeCredential.apiKey;
@@ -766,5 +768,5 @@ export function createAnthropicBrain(config = {}) {
             },
         });
     };
-    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
+    return { stream, adjudicateRoute: createBrainRouteJudge({ ...config, laneDefault: ANTHROPIC_LANE_DEFAULT }) };
 }

package/dist/brain/open-responses.d.ts

@@ -28,4 +28,4 @@ export interface OpenResponsesBrainConfig extends StreamEngineConfig {
  * Create a Brain that talks to an Open Responses endpoint. See the file header for the stateless
  * invariant, the capability-audit posture, and the reasoning-replay rule.
  */
-export declare function createOpenResponsesBrain(config?: OpenResponsesBrainConfig): Brain;
+export declare function createOpenResponsesBrain(given?: OpenResponsesBrainConfig): Brain;

package/dist/brain/open-responses.js

@@ -6,7 +6,7 @@ import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCal
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -219,7 +219,8 @@ function mapTerminalStopReason(incompleteReason, hadToolCalls) {
         return "length";
     return "stop";
 }
-export function createOpenResponsesBrain(config = {}) {
+export function createOpenResponsesBrain(given = {}) {
+    const config = brainConfigSnapshot(given, "createOpenResponsesBrain config");
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     refuseRetiredTimeoutKnobs(config, "construction", "createOpenResponsesBrain config");
     const doFetch = resolveFetch(config);

package/dist/brain/openai.d.ts

@@ -57,4 +57,4 @@ export declare function inferMaxTokensField(modelId: string): "max_completion_to
  * machinery lives in the shared {@link runStreamingBrain} engine (design/32); this adapter owns the
  * OpenAI request shaping + chat-completions SSE parsing + finalization.
  */
-export declare function createOpenAIBrain(config?: OpenAIBrainConfig): Brain;
+export declare function createOpenAIBrain(given?: OpenAIBrainConfig): Brain;