@sema-agent/core 2.3.0 → 2.5.0

package/dist/agents/subagent.js

@@ -197,6 +197,7 @@ const ccElapsedTag = (ms) => {
     return sec >= 60 ? ` \u00b7 ${Math.floor(sec / 60)}m${sec % 60}s` : ` \u00b7 ${sec}s`;
 };
 const ccCompletionText = (desc, settled, rawStatus, elapsedMs) => `Agent "${desc}" ${settled === "killed" ? "stopped" : settled === "completed" ? "finished" : rawStatus}${ccElapsedTag(elapsedMs)}`;
+const BG_AGENT_COLLATERAL_REAP_REASON = "its parent run ended";
 const RESERVED_AGENT_NAMES = new Set([OUTPUT_TOOL_NAME, TOOL_SEARCH_NAME, OFFLOAD_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME, DEFAULT_SUBAGENT_TOOL_NAME, LEGACY_SUBAGENT_TOOL_NAME]);
 export const REPORT_FIELD_MAX = 300;
 function configError(message, code) {
@@ -220,6 +221,9 @@ export function classifySubagentError(child) {
                     : "logic";
     return { errorKind, retryable: errorKind !== "logic" };
 }
+function errorKindClause(c) {
+    return c !== undefined ? ` (error_kind: ${c.errorKind}, retryable: ${c.retryable})` : "";
+}
 const FAILED_SESSION_RETAIN_TTL_MS = 15 * 60 * 1000;
 const PARTIAL_FINDINGS_MAX_CHARS = 1200;
 const BG_NOTIFY_DRAIN_WINDOW_MS = 2_000;
@@ -415,12 +419,18 @@ export function createSubagentResume(deps) {
                     void _;
                 const child = await stream.result();
                 let status = child.status === "completed" ? "completed" : abort.signal.aborted ? "killed" : "failed";
+                const errCodeRevive = status === "failed" ? (child.errorCode ?? extractErrorCode(child.errorMessage)) : undefined;
+                const errClassRevive = status === "failed"
+                    ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
+                    : undefined;
                 if (reviveCycle !== undefined && deps.registry !== undefined && deps.taskId !== undefined) {
                     try {
                         const winner = deps.registry.settleRevivedAgent(deps.taskId, reviveCycle, {
                             status,
                             ...resultSettleFields(child.result),
                             ...(status !== "completed" ? { error: (child.errorMessage ?? `resumed run ${status}`).slice(0, 500) } : {}),
+                            ...(errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
+                            ...(errClassRevive !== undefined ? { retryable: errClassRevive.retryable, errorKind: errClassRevive.errorKind } : {}),
                         });
                         if (winner !== undefined)
                             status = winner;
@@ -431,21 +441,27 @@ export function createSubagentResume(deps) {
                 const stoppedByRevive = status === "killed" ? deps.registry?.getStopAttribution(deps.taskId ?? "") ?? "system" : undefined;
                 const completionIdRevive = deps.registry?.getCompletionId(deps.taskId ?? "");
                 const reviveName = deps.rowDescription ?? `sub-agent ${marker}`;
-                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: `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`,
-                    resumable: status !== "killed",
-                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: child.stats.costMicroUsd },
-                    ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
-                });
+                const failReasonRevive = status === "failed" ? child.errorMessage : undefined;
+                const reviveTerminalSummary = failReasonRevive !== undefined
+                    ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + errorKindClause(errClassRevive)
+                    : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`;
+                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,
+                        resumable: status !== "killed",
+                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: child.stats.costMicroUsd },
+                        ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
+                    });
                 const resumeFrame = {
                     task_id: deps.taskId ?? entry.childSessionId,
                     ...(entry.childSessionId !== undefined ? { sessionId: entry.childSessionId } : {}),
@@ -454,7 +470,9 @@ export function createSubagentResume(deps) {
                     status,
                     ...(stoppedByRevive !== undefined ? { stoppedBy: stoppedByRevive } : {}),
                     seq: entry.cycleSeq,
-                    summary: `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`,
+                    summary: reviveTerminalSummary,
+                    ...(failReasonRevive !== undefined ? { error: failReasonRevive.slice(0, REPORT_FIELD_MAX) } : {}),
+                    ...(status === "failed" && errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
                     ...(child.result ? { result: notifyResultField(child.result) } : {}),
                     ...(status === "killed" && child.result ? { partial: true } : {}),
                     ...resumeResidual(),
@@ -462,7 +480,7 @@ export function createSubagentResume(deps) {
                     usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: child.stats.costMicroUsd },
                     ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                 };
-                const gateOwner = status === "completed" && deps.notify !== undefined && deps.registry !== undefined && ledger.get(deps.parentToolCallId) === entry
+                const gateOwner = ownsTerminalFacesRevive && status === "completed" && deps.notify !== undefined && deps.registry !== undefined && ledger.get(deps.parentToolCallId) === entry
                     ? entry.childSessionId
                     : undefined;
                 const aliveBgCount = gateOwner !== undefined ? deps.registry.countRunningBackgroundForOwner(gateOwner) : 0;
@@ -476,7 +494,7 @@ export function createSubagentResume(deps) {
                         notify: deps.notify,
                     });
                 }
-                else {
+                else if (ownsTerminalFacesRevive) {
                     try {
                         deps.notify?.(resumeFrame, { priority: "later" });
                     }
@@ -485,11 +503,16 @@ export function createSubagentResume(deps) {
                 }
             }
             catch (e) {
+                const msgRevive = e instanceof Error ? e.message : String(e);
+                const errCodeReviveReject = abort.signal.aborted ? undefined : extractErrorCode(msgRevive);
+                const errClassReviveReject = abort.signal.aborted ? undefined : classifySubagentError({ status: "failed", errorMessage: msgRevive });
                 if (reviveCycle !== undefined && deps.registry !== undefined && deps.taskId !== undefined) {
                     try {
                         deps.registry.settleRevivedAgent(deps.taskId, reviveCycle, {
                             status: abort.signal.aborted ? "killed" : "failed",
-                            error: (e instanceof Error ? e.message : String(e)).slice(0, 500),
+                            error: msgRevive.slice(0, 500),
+                            ...(errCodeReviveReject !== undefined ? { errorCode: errCodeReviveReject } : {}),
+                            ...(errClassReviveReject !== undefined ? { retryable: errClassReviveReject.retryable, errorKind: errClassReviveReject.errorKind } : {}),
                         });
                     }
                     catch {
@@ -498,31 +521,36 @@ export function createSubagentResume(deps) {
                 const stoppedByReject = abort.signal.aborted ? deps.registry?.getStopAttribution(deps.taskId ?? "") ?? "system" : undefined;
                 const completionIdRejectRevive = deps.registry?.getCompletionId(deps.taskId ?? "");
                 const rejectName = deps.rowDescription ?? `sub-agent ${marker}`;
-                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),
-                    ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
-                });
-                try {
-                    deps.notify?.({
-                        task_id: deps.taskId ?? entry.childSessionId,
-                        ...(entry.childSessionId !== undefined ? { sessionId: entry.childSessionId } : {}),
-                        task_type: "background_agent",
-                        toolUseId: deps.parentToolCallId,
+                const ownsTerminalFacesReviveReject = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.claimAgentTerminalNotify(deps.taskId) : true;
+                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: ${e instanceof Error ? e.message : String(e)}`}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300),
+                        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 } : {}),
-                    }, { priority: "later" });
+                    });
+                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: "later" });
                 }
                 catch {
                 }
@@ -1588,6 +1616,40 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                     }
                     bg.registry.bindBackgroundAgentSession(taskId, forkedId);
+                    const forkBgHangAt = Date.now();
+                    bg.registry.attachAgentTerminalNotifier(taskId, () => {
+                        const stoppedByReap = bg.registry.getStopAttribution(taskId) ?? "system";
+                        const completionIdReap = bg.registry.getCompletionId(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",
+                            stoppedBy: stoppedByReap,
+                            summary: summaryReap,
+                            resumable: false,
+                            ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
+                        });
+                        try {
+                            notify?.({
+                                task_id: taskId,
+                                task_type: "background_agent",
+                                toolUseId: ctx.toolCallId,
+                                status: "killed",
+                                stoppedBy: stoppedByReap,
+                                summary: summaryReap,
+                                sessionId: forkedId,
+                                resumable: false,
+                                ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
+                            }, { priority: "later" });
+                        }
+                        catch {
+                        }
+                    });
                     if (agentName !== undefined) {
                         recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, sessionId: forkedId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: Date.now() });
                     }
@@ -1683,10 +1745,18 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                         const okBg = child.status === "completed";
                         const reapedBg = !okBg && abort.signal.aborted;
+                        const collateralBg = reapedBg && bg.registry.getAccessibleTask(taskId, { ...(bgOwner !== undefined ? { owner: bgOwner } : {}), ...(bgScope !== undefined ? { scope: bgScope } : {}) })?.status === "running";
+                        const failedFork = !okBg && !reapedBg;
+                        const errCodeFork = failedFork ? (child.errorCode ?? extractErrorCode(child.errorMessage)) : undefined;
+                        const errClassFork = failedFork
+                            ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
+                            : undefined;
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
                             status: okBg ? "completed" : reapedBg ? "killed" : "failed",
                             ...resultSettleFields(child.result),
-                            ...(!okBg ? { error: reapedBg ? BG_AGENT_REAP_STOP_ERROR : child.errorMessage ?? String(child.status) } : {}),
+                            ...(!okBg ? { error: reapedBg ? (collateralBg ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
+                            ...(errCodeFork !== undefined ? { errorCode: errCodeFork } : {}),
+                            ...(errClassFork !== undefined ? { retryable: errClassFork.retryable, errorKind: errClassFork.errorKind } : {}),
                         }) ?? (abort.signal.aborted ? "killed" : okBg ? "completed" : "failed");
                         const stoppedByBg = settledBg === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
                         const completionIdFork = bg.registry.getCompletionId(taskId);
@@ -1701,37 +1771,46 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const residualFork = residualFields();
                         const resumableFork = false;
                         const forkTranscriptId = child.sessionId ?? forkedId;
-                        sinkEmit({
-                            kind: "terminal",
-                            taskId,
-                            sessionScoped: sessionScopedBg === true,
-                            sessionId: forkTranscriptId,
-                            ...(stillbornFork ? {} : { transcriptId: forkTranscriptId }),
-                            parentToolCallId: ctx.toolCallId,
-                            status: settledBg,
-                            ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                            summary: `${ccCompletionText(shortDesc, settledBg, String(child.status), Date.now() - forkBgStartedAt)}`,
-                            ...residualFork,
-                            resumable: resumableFork,
-                            usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
-                            ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
-                        });
-                        try {
-                            notify?.({
-                                task_id: taskId,
-                                task_type: "background_agent",
-                                toolUseId: ctx.toolCallId,
+                        const failReasonFork = settledBg === "failed" ? child.errorMessage : undefined;
+                        const forkTerminalSummary = failReasonFork !== undefined
+                            ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(Date.now() - forkBgStartedAt)}`.slice(0, 300) + errorKindClause(errClassFork)
+                            : `${ccCompletionText(shortDesc, settledBg, String(child.status), Date.now() - forkBgStartedAt)}`;
+                        const ownsTerminalFacesFork = bg.registry.claimAgentTerminalNotify(taskId);
+                        if (ownsTerminalFacesFork)
+                            sinkEmit({
+                                kind: "terminal",
+                                taskId,
+                                sessionScoped: sessionScopedBg === true,
+                                sessionId: forkTranscriptId,
+                                ...(stillbornFork ? {} : { transcriptId: forkTranscriptId }),
+                                parentToolCallId: ctx.toolCallId,
                                 status: settledBg,
                                 ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                                summary: `${ccCompletionText(shortDesc, settledBg, String(child.status), Date.now() - forkBgStartedAt)}`,
-                                ...(child.sessionId ? { sessionId: child.sessionId } : {}),
-                                ...(child.result ? { result: notifyResultField(child.result) } : {}),
-                                ...(settledBg === "killed" && child.result ? { partial: true } : {}),
+                                summary: forkTerminalSummary,
                                 ...residualFork,
                                 resumable: resumableFork,
                                 usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
                                 ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
-                            }, { priority: "later" });
+                            });
+                        try {
+                            if (ownsTerminalFacesFork)
+                                notify?.({
+                                    task_id: taskId,
+                                    task_type: "background_agent",
+                                    toolUseId: ctx.toolCallId,
+                                    status: settledBg,
+                                    ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
+                                    summary: forkTerminalSummary,
+                                    ...(failReasonFork !== undefined ? { error: failReasonFork.slice(0, REPORT_FIELD_MAX) } : {}),
+                                    ...(settledBg === "failed" && errCodeFork !== undefined ? { errorCode: errCodeFork } : {}),
+                                    ...(child.sessionId ? { sessionId: child.sessionId } : {}),
+                                    ...(child.result ? { result: notifyResultField(child.result) } : {}),
+                                    ...(settledBg === "killed" && child.result ? { partial: true } : {}),
+                                    ...residualFork,
+                                    resumable: resumableFork,
+                                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
+                                    ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
+                                }, { priority: "later" });
                         }
                         catch {
                         }
@@ -1740,36 +1819,46 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         dropHostAbortListener();
                         void finishWorktree();
                         const killed = abort.signal.aborted;
+                        const msgFork = e instanceof Error ? e.message : String(e);
+                        const errCodeForkReject = killed ? undefined : extractErrorCode(msgFork);
+                        const errClassForkReject = killed ? undefined : classifySubagentError({ status: "failed", errorMessage: msgFork });
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
                             status: killed ? "killed" : "failed",
-                            error: killed ? BG_AGENT_REAP_STOP_ERROR : e instanceof Error ? e.message : String(e),
+                            error: killed ? BG_AGENT_REAP_STOP_ERROR : msgFork,
+                            ...(errCodeForkReject !== undefined ? { errorCode: errCodeForkReject } : {}),
+                            ...(errClassForkReject !== undefined ? { retryable: errClassForkReject.retryable, errorKind: errClassForkReject.errorKind } : {}),
                         }) ?? (killed ? "killed" : "failed");
                         const stoppedByBg = settledBg === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
                         const completionIdForkReject = bg.registry.getCompletionId(taskId);
-                        const summaryBg = `${shortDesc} — ${settledBg === "failed" ? `failed: ${e instanceof Error ? e.message : String(e)}` : settledBg}`.slice(0, 300);
-                        sinkEmit({
-                            kind: "terminal",
-                            taskId,
-                            sessionScoped: sessionScopedBg === true,
-                            sessionId: forkedId,
-                            transcriptId: forkedId,
-                            parentToolCallId: ctx.toolCallId,
-                            status: settledBg,
-                            ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
-                            summary: summaryBg,
-                            ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
-                        });
-                        try {
-                            notify?.({
-                                task_id: taskId,
-                                task_type: "background_agent",
-                                toolUseId: ctx.toolCallId,
-                                status: settledBg,
+                        const summaryBg = `${shortDesc} — ${settledBg === "failed" ? `failed: ${msgFork}` : settledBg}`.slice(0, 300) + (settledBg === "failed" ? errorKindClause(errClassForkReject) : "");
+                        const ownsTerminalFacesForkReject = bg.registry.claimAgentTerminalNotify(taskId);
+                        if (ownsTerminalFacesForkReject)
+                            sinkEmit({
+                                kind: "terminal",
+                                taskId,
+                                sessionScoped: sessionScopedBg === true,
                                 sessionId: forkedId,
+                                transcriptId: forkedId,
+                                parentToolCallId: ctx.toolCallId,
+                                status: settledBg,
                                 ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
                                 summary: summaryBg,
                                 ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
-                            }, { priority: "later" });
+                            });
+                        try {
+                            if (ownsTerminalFacesForkReject)
+                                notify?.({
+                                    task_id: taskId,
+                                    task_type: "background_agent",
+                                    toolUseId: ctx.toolCallId,
+                                    status: settledBg,
+                                    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: "later" });
                         }
                         catch {
                         }
@@ -1956,6 +2045,39 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const bgStartedAt = Date.now();
                 stepRecorder.lockTo(bgChildSessionId);
                 bg.registry.bindBackgroundAgentSession(taskId, bgChildSessionId);
+                bg.registry.attachAgentTerminalNotifier(taskId, () => {
+                    const stoppedByReap = bg.registry.getStopAttribution(taskId) ?? "system";
+                    const completionIdReap = bg.registry.getCompletionId(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",
+                        stoppedBy: stoppedByReap,
+                        summary: summaryReap,
+                        resumable: false,
+                        ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
+                    });
+                    try {
+                        notify?.({
+                            task_id: taskId,
+                            task_type: "background_agent",
+                            toolUseId: ctx.toolCallId,
+                            status: "killed",
+                            stoppedBy: stoppedByReap,
+                            summary: summaryReap,
+                            sessionId: bgChildSessionId,
+                            resumable: false,
+                            ...(completionIdReap !== undefined ? { completionId: completionIdReap } : {}),
+                        }, { priority: "later" });
+                    }
+                    catch {
+                    }
+                });
                 const bgDurableProbe = bg.registry.durableAgentRowProbe(taskId);
                 const bgRowConfirmed = async () => (bgDurableProbe ? await bgDurableProbe().catch(() => false) : false);
                 sinkEmit({
@@ -2259,11 +2381,19 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     const ok = child.status === "completed";
                     const reaped = !ok && abort.signal.aborted;
+                    const collateral = reaped && bg.registry.getAccessibleTask(taskId, { ...(bgOwner !== undefined ? { owner: bgOwner } : {}), ...(bgScope !== undefined ? { scope: bgScope } : {}) })?.status === "running";
+                    const failedBg = !ok && !reaped;
+                    const errCodeBg = failedBg ? (child.errorCode ?? extractErrorCode(child.errorMessage)) : undefined;
+                    const errClassBg = failedBg
+                        ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
+                        : undefined;
                     const settled = bg.registry.settleBackgroundAgent(taskId, {
                         status: ok ? "completed" : reaped ? "killed" : "failed",
                         seq: seqAtSettle ?? 1,
                         ...resultSettleFields(child.result),
-                        ...(!ok ? { error: reaped ? BG_AGENT_REAP_STOP_ERROR : child.errorMessage ?? String(child.status) } : {}),
+                        ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
+                        ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
+                        ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
                     }) ??
                         (abort.signal.aborted ? "killed" : ok ? "completed" : "failed");
                     if (!bgRetain && reviveRow === undefined && !(await bgRowConfirmed())) {
@@ -2279,21 +2409,27 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
                     const residual = residualFields();
                     const resumableBg = bgRetain !== undefined && settled !== "killed";
-                    sinkEmit({
-                        kind: "terminal",
-                        taskId,
-                        sessionScoped: sessionScopedBg === true,
-                        ...(child.sessionId ? { sessionId: child.sessionId, transcriptId: child.sessionId } : {}),
-                        parentToolCallId: ctx.toolCallId,
-                        status: settled,
-                        ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
-                        ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                        summary: `${ccCompletionText(shortDesc, settled, String(child.status), Date.now() - bgStartedAt)}${observerNote}`,
-                        ...residual,
-                        resumable: resumableBg,
-                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
-                        ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
-                    });
+                    const failReasonBg = settled === "failed" ? child.errorMessage : undefined;
+                    const bgTerminalSummary = failReasonBg !== undefined
+                        ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
+                        : `${ccCompletionText(shortDesc, settled, String(child.status), Date.now() - bgStartedAt)}${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 } : {}),
+                            ...(stoppedBy !== undefined ? { stoppedBy } : {}),
+                            summary: bgTerminalSummary,
+                            ...residual,
+                            resumable: resumableBg,
+                            usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
+                            ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
+                        });
                     const completionFrame = {
                         task_id: taskId,
                         task_type: "background_agent",
@@ -2301,7 +2437,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         status: settled,
                         ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
                         ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                        summary: `${ccCompletionText(shortDesc, settled, String(child.status), Date.now() - bgStartedAt)}${observerNote}`,
+                        summary: bgTerminalSummary,
+                        ...(failReasonBg !== undefined ? { error: failReasonBg.slice(0, REPORT_FIELD_MAX) } : {}),
+                        ...(settled === "failed" && errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
                         ...(child.sessionId ? { sessionId: child.sessionId } : {}),
                         ...(child.result ? { result: notifyResultField(child.result) } : {}),
                         ...(settled === "killed" && child.result ? { partial: true } : {}),
@@ -2310,7 +2448,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
                         ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
                     };
-                    const gateOwner = settled === "completed" && notify !== undefined ? bgRetain?.childSessionId : undefined;
+                    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) {
                         parkCompletionNotify({
@@ -2322,7 +2460,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             notify: notify,
                         });
                     }
-                    else {
+                    else if (ownsTerminalFaces) {
                         try {
                             notify?.(completionFrame, { priority: "later" });
                         }
@@ -2343,7 +2481,15 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             bgRetainLedger?.markSettled(ctx.toolCallId);
                     }
                     const msg = e instanceof Error ? e.message : String(e);
-                    const settled = bg.registry.settleBackgroundAgent(taskId, { status: killed ? "killed" : "failed", error: msg, seq: seqAtSettle ?? 1 }) ?? (killed ? "killed" : "failed");
+                    const errCodeBgReject = killed ? undefined : extractErrorCode(msg);
+                    const errClassBgReject = killed ? undefined : classifySubagentError({ status: "failed", errorMessage: msg });
+                    const settled = bg.registry.settleBackgroundAgent(taskId, {
+                        status: killed ? "killed" : "failed",
+                        error: msg,
+                        seq: seqAtSettle ?? 1,
+                        ...(errCodeBgReject !== undefined ? { errorCode: errCodeBgReject } : {}),
+                        ...(errClassBgReject !== undefined ? { retryable: errClassBgReject.retryable, errorKind: errClassBgReject.errorKind } : {}),
+                    }) ?? (killed ? "killed" : "failed");
                     if (!bgRetain && reviveRow === undefined && !(await bgRowConfirmed())) {
                         try {
                             await opts.runner.sessions.release(bgChildSessionId);
@@ -2355,31 +2501,36 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const stoppedBy = settled === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
                     const completionIdBgReject = bg.registry.getCompletionId(taskId);
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
-                    sinkEmit({
-                        kind: "terminal",
-                        taskId,
-                        sessionScoped: sessionScopedBg === true,
-                        sessionId: bgChildSessionId,
-                        transcriptId: bgChildSessionId,
-                        parentToolCallId: ctx.toolCallId,
-                        status: settled,
-                        ...(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),
-                        ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
-                    });
-                    try {
-                        notify?.({
-                            task_id: taskId,
-                            task_type: "background_agent",
-                            toolUseId: ctx.toolCallId,
-                            status: settled,
+                    const ownsTerminalFacesReject = bg.registry.claimAgentTerminalNotify(taskId);
+                    if (ownsTerminalFacesReject)
+                        sinkEmit({
+                            kind: "terminal",
+                            taskId,
+                            sessionScoped: sessionScopedBg === true,
                             sessionId: bgChildSessionId,
+                            transcriptId: bgChildSessionId,
+                            parentToolCallId: ctx.toolCallId,
+                            status: settled,
                             ...(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),
+                            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 } : {}),
-                        }, { priority: "later" });
+                        });
+                    try {
+                        if (ownsTerminalFacesReject)
+                            notify?.({
+                                task_id: taskId,
+                                task_type: "background_agent",
+                                toolUseId: ctx.toolCallId,
+                                status: settled,
+                                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: "later" });
                     }
                     catch {
                     }

package/dist/brain/errors.d.ts

@@ -12,4 +12,5 @@ export declare class BrainError extends Error {
 export declare function classifyHttp(status: number): BrainErrorCode;
 export declare function extractErrorCode(errorMessage: string | undefined): BrainErrorCode | undefined;
 export declare function stripErrorCodePrefix(errorMessage: string): string;
+export declare function describeNetworkError(e: unknown): string;
 export {};

package/dist/brain/errors.js

@@ -42,3 +42,17 @@ export function extractErrorCode(errorMessage) {
 export function stripErrorCodePrefix(errorMessage) {
     return errorMessage.replace(CODE_PREFIX_RE, "");
 }
+export function describeNetworkError(e) {
+    const top = e instanceof Error ? e.message : String(e);
+    const parts = [];
+    let cur = e instanceof Error ? e.cause : undefined;
+    for (let depth = 0; depth < 4 && cur !== undefined && cur !== null; depth++) {
+        const code = typeof cur.code === "string" ? cur.code : undefined;
+        const msg = cur instanceof Error ? cur.message : String(cur);
+        const piece = code !== undefined && !msg.includes(code) ? `${code}: ${msg}` : msg;
+        if (piece.length > 0 && piece !== top && !parts.includes(piece))
+            parts.push(piece);
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return parts.length > 0 ? `${top} (${parts.join(" ← ")})` : top;
+}