@sema-agent/core 7.5.1 → 7.6.0

package/dist/agents/subagent.js

@@ -14,7 +14,8 @@ import { resolveToolSubset, toolNameAllowed } from "./tool-filter.js";
 import { builtinAgentDefinitions } from "./builtin-agents.js";
 import { SUBAGENT_PROMPT } from "../prompts/default.js";
 import { hasSessionFork } from "../core/session.js";
-import { isDurablePause } from "./suspend-guard.js";
+import { isDurablePause, pauseFamily } from "./suspend-guard.js";
+import { terminalProjection } from "../core/runner/terminal-projection.js";
 import { delimitUntrusted, inlineUntrusted } from "../core/untrusted-text.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 import { boundedRedactedSummary } from "../core/untrusted-egress.js";
@@ -23,7 +24,6 @@ import { addWorktree } from "../core/git-worktree-env.js";
 import { shellQuote } from "../tools/fs/search.js";
 import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { readDurableOrgAdmission } from "../core/memory-admission.js";
-import { extractErrorCode } from "../brain/errors.js";
 import { governanceRetryClass } from "../core/governance-codes.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) {
@@ -349,39 +349,54 @@ function configError(message, code) {
     e.code = code;
     return e;
 }
-export function classifySubagentError(child) {
-    if (child.status !== "failed")
+export const SUBAGENT_ERROR_KINDS = ["rate_limit", "timeout", "network", "logic", "governance", "unknown"];
+const SUBAGENT_ERROR_KIND_BY_CODE = {
+    rate_limit: "rate_limit",
+    server: "network",
+    network: "network",
+    "limits.max_walltime_exceeded": "timeout",
+};
+const SUBAGENT_RETRYABLE = {
+    rate_limit: true,
+    timeout: true,
+    network: true,
+    logic: false,
+    governance: false,
+    unknown: false,
+};
+export function classifySubagentError(terminal) {
+    if (terminal.kind !== "failed")
         return undefined;
-    const code = child.errorCode ?? extractErrorCode(child.errorMessage);
-    const msg = (child.errorMessage ?? "").toLowerCase();
-    const governanceClass = code !== undefined ? governanceRetryClass(code) : undefined;
-    const errorKind = code === "rate_limit"
-        ? "rate_limit"
-        : code === "server" && (msg.includes("overloaded") || msg.includes("529"))
-            ? "overloaded"
-            : code === "limits.max_walltime_exceeded" || ((code === "network" || code === "server") && msg.includes("timeout"))
-                ? "timeout"
-                : code === "network" || code === "server"
-                    ? "network"
-                    : governanceClass !== undefined
-                        ? "governance"
-                        : "logic";
-    return { errorKind, retryable: errorKind === "governance" ? governanceClass === "transient" : errorKind !== "logic" };
+    const code = terminal.code;
+    if (code === undefined)
+        return { errorKind: "unknown", retryable: SUBAGENT_RETRYABLE.unknown };
+    const own = SUBAGENT_ERROR_KIND_BY_CODE[code];
+    if (own !== undefined)
+        return { errorKind: own, retryable: SUBAGENT_RETRYABLE[own] };
+    const governanceClass = governanceRetryClass(code);
+    if (governanceClass !== undefined)
+        return { errorKind: "governance", retryable: governanceClass === "transient" };
+    return { errorKind: "logic", retryable: SUBAGENT_RETRYABLE.logic };
+}
+function thrownErrorCode(e) {
+    const code = e !== null && typeof e === "object" ? e.code : undefined;
+    return typeof code === "string" ? code : undefined;
 }
 export function completedAgentCard(child, extras) {
+    const face = terminalProjection(child.terminal);
     return {
         type: "agent",
         ...(extras.attestation !== undefined ? { attestation: extras.attestation } : {}),
         ...(extras.subagentType !== undefined ? { subagent_type: extras.subagentType } : {}),
-        status: child.status,
+        status: face.status,
         taskId: child.taskId,
         sessionId: child.sessionId,
         result: child.result,
         ...(child.salvagedOutput !== undefined ? { salvagedOutput: child.salvagedOutput } : {}),
         ...(child.structuredOutput !== undefined ? { structuredOutput: child.structuredOutput } : {}),
-        ...(child.blockedReason !== undefined ? { blockedReason: child.blockedReason } : {}),
-        ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}),
-        ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}),
+        ...(face.blockedReason !== undefined ? { blockedReason: face.blockedReason } : {}),
+        ...(face.errorMessage !== undefined ? { errorMessage: face.errorMessage } : {}),
+        ...(face.errorCode !== undefined ? { errorCode: face.errorCode } : {}),
         ...providerFaultField(child),
         ...(child.retryAfterMs !== undefined ? { retryAfterMs: child.retryAfterMs } : {}),
         ...(child.degraded !== undefined ? { degraded: child.degraded } : {}),
@@ -397,16 +412,15 @@ export function completedAgentCard(child, extras) {
 export const SUBAGENT_SUSPENDED_AWAITING_APPROVAL = "suspended.awaiting_approval";
 export const SUBAGENT_SUSPENDED_NEEDS_REVIEW = "suspended.needs_review";
 export const SUBAGENT_SUSPENDED_CHECKPOINT_EXPIRED = "suspended.checkpoint_expired";
-function durablePauseDelegationReport(reportLabel, child) {
-    const needsReview = child.status === "needs_review";
-    const token = child.checkpointToken;
+function durablePauseDelegationReport(reportLabel, paused) {
+    const needsReview = pauseFamily(paused) === "needs_review";
+    const token = paused.token;
     return {
         isError: true,
         content: `[Sub-agent report${reportLabel}]\n` +
             `status: suspended\n` +
             `This delegation is PARKED at an approval gate — it did not fail, and it is not finished. ` +
-            `${needsReview ? "A human review" : "An approval"} it cannot grant itself is pending` +
-            `${token !== undefined ? `, held by checkpoint ${token}` : " (the run reported no checkpoint token)"}. ` +
+            `${needsReview ? "A human review" : "An approval"} it cannot grant itself is pending, held by checkpoint ${token}. ` +
             `The gated action has NOT run.\n` +
             `Only the deployment's approval channel can release it: you cannot approve it from here, and no ` +
             `result from it will arrive in this turn. Do not re-issue the same approval-gated action — an ` +
@@ -414,7 +428,7 @@ function durablePauseDelegationReport(reportLabel, child) {
             `this delegation, or report that it is awaiting approval.`,
         details: {
             error: needsReview ? SUBAGENT_SUSPENDED_NEEDS_REVIEW : SUBAGENT_SUSPENDED_AWAITING_APPROVAL,
-            ...(token !== undefined ? { checkpointToken: token } : {}),
+            checkpointToken: token,
         },
     };
 }
@@ -698,7 +712,8 @@ export function createSubagentResume(deps) {
                 for await (const _ of stream)
                     void _;
                 const child = await stream.result();
-                let status = child.status === "completed" ? "completed" : abort.signal.aborted ? "killed" : "failed";
+                const childFace = terminalProjection(child.terminal);
+                let status = child.terminal.kind === "completed" ? "completed" : abort.signal.aborted ? "killed" : "failed";
                 const resumeHandbackWarning = await reviewHandback({
                     review: deps.currentAutoModeReview,
                     toolCallId: deps.parentToolCallId,
@@ -707,16 +722,14 @@ export function createSubagentResume(deps) {
                     signal: abort.signal,
                 });
                 const resumeHandbackResult = withHandbackWarning(resumeHandbackWarning, child.result);
-                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;
+                const errCodeRevive = status === "failed" ? childFace.errorCode : undefined;
+                const errClassRevive = status === "failed" ? classifySubagentError({ kind: "failed", ...(childFace.errorCode !== undefined ? { code: childFace.errorCode } : {}) }) : undefined;
                 if (reviveCycle !== undefined && deps.registry !== undefined && deps.taskId !== undefined) {
                     try {
                         const winner = deps.registry.settleRevivedAgent(deps.taskId, reviveCycle, {
                             status,
                             ...resultSettleFields(resumeHandbackResult),
-                            ...(status !== "completed" ? { error: (child.errorMessage ?? `resumed run ${status}`).slice(0, 500) } : {}),
+                            ...(status !== "completed" ? { error: (childFace.errorMessage ?? `resumed run ${status}`).slice(0, 500) } : {}),
                             ...(errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
                             ...(errClassRevive !== undefined ? { retryable: errClassRevive.retryable, errorKind: errClassRevive.errorKind } : {}),
                         });
@@ -729,11 +742,11 @@ 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}`;
-                const failReasonRevive = status === "failed" ? child.errorMessage : undefined;
+                const failReasonRevive = status === "failed" ? childFace.errorMessage : undefined;
                 const reviveElapsedMs = Date.now() - reviveStartedAt;
                 const reviveTerminalSummary = failReasonRevive !== undefined
                     ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(reviveElapsedMs)}`.slice(0, 300) + errorKindClause(errClassRevive)
-                    : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(reviveElapsedMs)}`;
+                    : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.terminal.kind === "completed" ? "finished" : childFace.status}${ccElapsedTag(reviveElapsedMs)}`;
                 const reviveDurableProbe = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.durableAgentRowProbe(deps.taskId) : undefined;
                 const reviveDurableRow = reviveDurableProbe !== undefined ? await reviveDurableProbe().catch(() => false) : false;
                 const resumableRevive = resumabilityClaim({
@@ -805,8 +818,8 @@ 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 });
+                const errCodeReviveReject = abort.signal.aborted ? undefined : thrownErrorCode(e);
+                const errClassReviveReject = abort.signal.aborted ? undefined : classifySubagentError({ kind: "failed", ...(errCodeReviveReject !== undefined ? { code: errCodeReviveReject } : {}) });
                 if (reviveCycle !== undefined && deps.registry !== undefined && deps.taskId !== undefined) {
                     try {
                         deps.registry.settleRevivedAgent(deps.taskId, reviveCycle, {
@@ -1896,11 +1909,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     if (!isObserverTaskId(sid))
                         throw new ObserverStoppedByUserError("observer identity revoked — delivery refused");
                     const r = await opts.runner.runTask(spec, ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : undefined);
-                    if (r.status !== "completed") {
-                        if (r.errorCode === "resume.session_not_found") {
-                            throw new ObserverResumeStateError(`observer session no longer exists${r.errorMessage ? `: ${r.errorMessage}` : ""}`);
-                        }
-                        throw new Error(`observer run ended ${r.status}${r.errorMessage ? `: ${r.errorMessage}` : ""}`);
+                    if (r.terminal.kind !== "completed") {
+                        const failedText = r.terminal.kind === "failed" && r.terminal.message ? `: ${r.terminal.message}` : "";
+                        if (r.terminal.kind === "failed" && r.terminal.code === "resume.session_not_found")
+                            throw new ObserverResumeStateError(`observer session no longer exists${failedText}`);
+                        throw new Error(`observer run ended ${terminalProjection(r.terminal).status}${failedText}`);
                     }
                 };
                 const spawner = {
@@ -2047,7 +2060,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             });
             const provenanceRequest = ctx.delegationProvenanceForChildren?.();
             const childProvenanceRef = provenanceRequest !== undefined ? { current: newDelegationProvenanceAggregate() } : undefined;
-            const childAttestation = (status) => childProvenanceRef !== undefined ? reduceDelegationAttestation(childProvenanceRef.current, { completed: status === "completed" }) : undefined;
+            const childAttestation = (completed) => childProvenanceRef !== undefined ? reduceDelegationAttestation(childProvenanceRef.current, { completed }) : undefined;
             const liveCaptureFloor = reviveClaim === undefined
                 ? { optedOut: (await ctx.memoryCaptureOptedOut) === true, indeterminate: (await ctx.memoryCaptureIndeterminate) === true }
                 : undefined;
@@ -2135,7 +2148,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(def?.memory ? { memory: def.memory } : {}),
                 ...(def?.skills?.length ? { skills: def.skills } : {}),
                 ...(ctx.principal !== undefined ? { principal: ctx.principal } : {}),
-                ...(ctx.checkpointStoreDisabledForChildren === true ? { checkpointStore: null } : {}),
+                ...(ctx.checkpointStoreDisabledForChildren === true ? { checkpointStore: "disabled" } : {}),
                 ...(childOnAsk !== undefined ? { onAsk: childOnAsk } : {}),
                 ...(ctx.onQuestion !== undefined ? { onQuestion: ctx.onQuestion } : {}),
                 ...(ctx.interactiveTools === false ? { interactiveTools: false } : {}),
@@ -2409,10 +2422,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             };
                         }
                     }
-                    const settleForkRow = (status) => {
+                    const settleForkRow = (terminal) => {
                         if (forkSettlementSeat === undefined || forkSettleId === undefined)
                             return;
-                        const att = status !== undefined ? childAttestation(status) : undefined;
+                        const att = terminal !== undefined ? childAttestation(terminal.kind === "completed") : undefined;
                         const verdict = att === "external" ? "external" : att === "clean" ? "clean" : "unattestable";
                         let settled = false;
                         let lastErr;
@@ -2629,7 +2642,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     void opts.runner
                         .runTask(bgForkSpec, bgForkInternals)
                         .then(async (child) => {
-                        settleForkRow(child.status);
+                        const childFace = terminalProjection(child.terminal);
+                        settleForkRow(child.terminal);
                         dropHostAbortListener();
                         await finishWorktree();
                         try {
@@ -2651,25 +2665,23 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             signal: abort.signal,
                         });
                         const forkBgResult = withHandbackWarning(forkBgWarning, child.result);
-                        const okBg = child.status === "completed";
+                        const okBg = child.terminal.kind === "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 errCodeFork = failedFork ? childFace.errorCode : undefined;
+                        const errClassFork = failedFork ? classifySubagentError({ kind: "failed", ...(childFace.errorCode !== undefined ? { code: childFace.errorCode } : {}) }) : undefined;
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
                             cycle: 0,
                             status: okBg ? "completed" : reapedBg ? "killed" : "failed",
                             ...resultSettleFields(forkBgResult),
-                            ...(!okBg ? { error: reapedBg ? (collateralBg ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
+                            ...(!okBg ? { error: reapedBg ? (collateralBg ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : childFace.errorMessage ?? childFace.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);
-                        const stillbornFork = child.errorCode === "resume.session_not_found";
+                        const stillbornFork = child.terminal.kind === "failed" && child.terminal.code === "resume.session_not_found";
                         if (stillbornFork) {
                             try {
                                 await (releaseForked ? releaseForked() : opts.runner.sessions.release?.(forkedId));
@@ -2680,11 +2692,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const residualFork = residualFields();
                         const resumableFork = false;
                         const forkTranscriptId = child.sessionId ?? forkedId;
-                        const failReasonFork = settledBg === "failed" ? child.errorMessage : undefined;
+                        const failReasonFork = settledBg === "failed" ? childFace.errorMessage : undefined;
                         const forkElapsedMs = Date.now() - forkBgStartedAt;
                         const forkTerminalSummary = failReasonFork !== undefined
                             ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(forkElapsedMs)}`.slice(0, 300) + errorKindClause(errClassFork)
-                            : `${ccCompletionText(shortDesc, settledBg, String(child.status), forkElapsedMs)}`;
+                            : `${ccCompletionText(shortDesc, settledBg, childFace.status, forkElapsedMs)}`;
                         const ownsTerminalFacesFork = bg.registry.claimAgentTerminalNotify(taskId);
                         if (ownsTerminalFacesFork)
                             sinkEmit({
@@ -2728,13 +2740,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                     })
                         .catch((e) => {
-                        settleForkRow("failed");
+                        settleForkRow({ kind: "failed" });
                         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 errCodeForkReject = killed ? undefined : thrownErrorCode(e);
+                        const errClassForkReject = killed ? undefined : classifySubagentError({ kind: "failed", ...(errCodeForkReject !== undefined ? { code: errCodeForkReject } : {}) });
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
                             cycle: 0,
                             status: killed ? "killed" : "failed",
@@ -2826,7 +2838,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 let forkChild;
                 try {
                     forkChild = await opts.runner.runTask({ ...buildChildSpec(ctx.signal), sessionId: forkedId, requireExistingSession: true, objective: forkObjective }, forkInternals);
-                    if (forkChild.errorCode === "resume.session_not_found") {
+                    if (forkChild.terminal.kind === "failed" && forkChild.terminal.code === "resume.session_not_found") {
                         try {
                             await (releaseForked ? releaseForked() : opts.runner.sessions.release?.(forkedId));
                         }
@@ -2860,21 +2872,22 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     tasks: 1 + (nsf?.tasks ?? 0),
                     costMicroUsd: rollupDelegatedCost(forkChild.stats, nsf),
                 });
-                if (isDurablePause(forkChild.status)) {
-                    return durablePauseDelegationReport(` · ${FORK_SUBAGENT_TYPE}`, forkChild);
+                if (isDurablePause(forkChild.terminal)) {
+                    return durablePauseDelegationReport(` · ${FORK_SUBAGENT_TYPE}`, forkChild.terminal);
                 }
                 const wtLine = await finishWorktree();
-                const forkErr = classifySubagentError(forkChild);
+                const forkFace = terminalProjection(forkChild.terminal);
+                const forkErr = classifySubagentError(forkChild.terminal);
                 const forkLines = [
                     ...(forkHandbackWarning ? [forkHandbackWarning, ""] : []),
                     `[Sub-agent report · ${FORK_SUBAGENT_TYPE}${a.description ? ` · ${String(a.description)}` : ""}] (forked session …${forkedId.slice(-8)})`,
-                    `status: ${forkChild.status}`,
+                    `status: ${forkFace.status}`,
                     modelNote ?? "",
                     extraToolsNote ?? "",
                     bgIgnoredNote ?? "",
                     wtLine ?? "",
-                    forkChild.blockedReason ? `blocked_reason: ${inlineUntrusted(forkChild.blockedReason, REPORT_FIELD_MAX)}` : "",
-                    forkChild.errorMessage ? `error: ${inlineUntrusted(forkChild.errorMessage, REPORT_FIELD_MAX)}` : "",
+                    forkFace.blockedReason ? `blocked_reason: ${inlineUntrusted(forkFace.blockedReason, REPORT_FIELD_MAX)}` : "",
+                    forkFace.errorMessage ? `error: ${inlineUntrusted(forkFace.errorMessage, REPORT_FIELD_MAX)}` : "",
                     forkErr ? `error_kind: ${forkErr.errorKind} (retryable: ${forkErr.retryable})` : "",
                     `stats: turns=${forkChild.stats.turns} tokens=${forkChild.stats.tokens}`,
                     "",
@@ -2889,7 +2902,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         subagentType: FORK_SUBAGENT_TYPE,
                         error: forkErr,
                         ...(() => {
-                            const a = childAttestation(forkChild.status);
+                            const a = childAttestation(forkChild.terminal.kind === "completed");
                             return a !== undefined ? { attestation: a } : {};
                         })(),
                         ...(forkHandbackWarning !== undefined ? { handbackWarning: forkHandbackWarning } : {}),
@@ -2948,10 +2961,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         };
                     }
                 }
-                const settleDelegationRow = (status) => {
+                const settleDelegationRow = (terminal) => {
                     if (settlementSeat === undefined || bgSettleId === undefined)
                         return;
-                    const att = status !== undefined ? childAttestation(status) : undefined;
+                    const att = terminal !== undefined ? childAttestation(terminal.kind === "completed") : undefined;
                     const verdict = att === "external" ? "external" : att === "clean" ? "clean" : "unattestable";
                     let settled = false;
                     let lastErr;
@@ -3347,7 +3360,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     catch (e) {
                         return rollbackAndThrow(e);
                     }
-                    if (childResult.status === "failed") {
+                    if (childResult.terminal.kind === "failed") {
                         let reopened = false;
                         try {
                             const cp = (await bg.checkpointStore.get(pr.ticket.token));
@@ -3367,7 +3380,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.errorMessage ?? childResult.status}`);
+                            throw new Error(`parked resume could not complete and the approval was REOPENED (still approvable/retryable): ${childResult.terminal.message ?? "failed"}`);
                         }
                     }
                     return childResult;
@@ -3387,8 +3400,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : opts.runner.runTask(bgSpec, bgInternals);
                 void bgChildPromise
                     .then(async (child) => {
-                    settleDelegationRow(child.status);
-                    closeObserverWindow(child.status);
+                    const childFace = terminalProjection(child.terminal);
+                    settleDelegationRow(child.terminal);
+                    closeObserverWindow(childFace.status);
                     dropHostAbortListener();
                     await finishWorktree();
                     try {
@@ -3403,7 +3417,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     catch {
                     }
                     const seqAtSettle = bgRetain?.cycleSeq ?? (parkedResume !== undefined ? (reviveRow?.seq ?? 1) + 1 : reviveRow?.seq);
-                    const bgHandbackWarning = isDurablePause(child.status)
+                    const bgHandbackWarning = isDurablePause(child.terminal)
                         ? undefined
                         : await reviewHandback({
                             review: ctx.autoModeReview,
@@ -3414,15 +3428,16 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         });
                     const bgHandbackResult = withHandbackWarning(bgHandbackWarning, child.result);
                     if (bgRetain) {
-                        if (isDurablePause(child.status))
+                        if (isDurablePause(child.terminal))
                             bgRetainLedger?.abandon(ctx.toolCallId);
-                        else if (child.status !== "completed" && abort.signal.aborted)
+                        else if (child.terminal.kind !== "completed" && abort.signal.aborted)
                             void bgRetainLedger?.evict(ctx.toolCallId);
                         else
                             bgRetainLedger?.markSettled(ctx.toolCallId);
                     }
                     let unparkedPause;
-                    if (isDurablePause(child.status) && child.checkpointToken !== undefined) {
+                    if (isDurablePause(child.terminal)) {
+                        const pausedToken = child.terminal.token;
                         const cpStore = bg.checkpointStore;
                         const expireByStoreScope = async (token2) => {
                             try {
@@ -3437,7 +3452,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         };
                         const wired = bg.agentStore !== undefined && cpStore !== undefined && bg.ensureChildSessionDurable !== undefined;
                         if (wired) {
-                            const token = child.checkpointToken;
+                            const token = pausedToken;
                             if (abort.signal.aborted) {
                                 await expireByStoreScope(token);
                             }
@@ -3470,10 +3485,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             }
                         }
                         else {
-                            unparkedPause = { kind: "no_park_lane", checkpointToken: child.checkpointToken };
+                            unparkedPause = { kind: "no_park_lane", checkpointToken: pausedToken };
                         }
                     }
-                    const ok = child.status === "completed";
+                    const ok = child.terminal.kind === "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;
@@ -3481,21 +3496,19 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const errCodeBg = failedBg
                         ? unparkedPause !== undefined
                             ? unparkedPause.kind === "no_park_lane"
-                                ? child.status === "needs_review"
+                                ? child.terminal.kind === "paused" && pauseFamily(child.terminal) === "needs_review"
                                     ? SUBAGENT_SUSPENDED_NEEDS_REVIEW
                                     : SUBAGENT_SUSPENDED_AWAITING_APPROVAL
                                 : SUBAGENT_SUSPENDED_CHECKPOINT_EXPIRED
-                            : (child.errorCode ?? extractErrorCode(child.errorMessage))
-                        : undefined;
-                    const errClassBg = failedBg
-                        ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
+                            : childFace.errorCode
                         : undefined;
+                    const errClassBg = failedBg ? classifySubagentError({ kind: "failed", ...(childFace.errorCode !== undefined ? { code: childFace.errorCode } : {}) }) : undefined;
                     const settled = bg.registry.settleBackgroundAgent(taskId, {
                         cycle: 0,
                         status: ok ? "completed" : reaped ? "killed" : "failed",
                         seq: seqAtSettle ?? 1,
                         ...resultSettleFields(bgHandbackResult),
-                        ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : unparkedPauseReason ?? child.errorMessage ?? String(child.status) } : {}),
+                        ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : unparkedPauseReason ?? childFace.errorMessage ?? childFace.status } : {}),
                         ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
                         ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
                         ...(failedBg && child.retryAfterMs !== undefined ? { retryAfterMs: child.retryAfterMs } : {}),
@@ -3522,11 +3535,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         durableRow: bgDurableRow,
                         named: agentName !== undefined,
                     });
-                    const failReasonBg = settled === "failed" ? unparkedPauseReason ?? child.errorMessage : undefined;
+                    const failReasonBg = settled === "failed" ? unparkedPauseReason ?? childFace.errorMessage : undefined;
                     const bgElapsedMs = Date.now() - bgStartedAt;
                     const bgTerminalSummary = failReasonBg !== undefined
                         ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(bgElapsedMs)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
-                        : `${ccCompletionText(shortDesc, settled, String(child.status), bgElapsedMs)}${observerNote}`;
+                        : `${ccCompletionText(shortDesc, settled, childFace.status, bgElapsedMs)}${observerNote}`;
                     const ownsTerminalFaces = bg.registry.claimAgentTerminalNotify(taskId);
                     if (ownsTerminalFaces)
                         sinkEmit({
@@ -3584,7 +3597,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                 })
                     .catch(async (e) => {
-                    settleDelegationRow("failed");
+                    settleDelegationRow({ kind: "failed" });
                     closeObserverWindow("failed");
                     dropHostAbortListener();
                     void finishWorktree();
@@ -3597,8 +3610,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             bgRetainLedger?.markSettled(ctx.toolCallId);
                     }
                     const msg = e instanceof Error ? e.message : String(e);
-                    const errCodeBgReject = killed ? undefined : extractErrorCode(msg);
-                    const errClassBgReject = killed ? undefined : classifySubagentError({ status: "failed", errorMessage: msg });
+                    const errCodeBgReject = killed ? undefined : thrownErrorCode(e);
+                    const errClassBgReject = killed ? undefined : classifySubagentError({ kind: "failed", ...(errCodeBgReject !== undefined ? { code: errCodeBgReject } : {}) });
                     const settled = bg.registry.settleBackgroundAgent(taskId, {
                         cycle: 0,
                         status: killed ? "killed" : "failed",
@@ -3755,7 +3768,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             finally {
                 syncAdmission.release();
             }
-            await settleObserver(child.status);
+            const childFace = terminalProjection(child.terminal);
+            await settleObserver(childFace.status);
             const handbackWarning = await reviewHandback({
                 review: ctx.autoModeReview,
                 toolCallId: ctx.toolCallId,
@@ -3764,7 +3778,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     result: child.result,
                     steps: stepRecorder.recentSteps(),
                     edits: stepRecorder.editedFiles(),
-                    ...(child.result || child.status === "completed" ? {} : { partialText: assistantTextTail.trim() }),
+                    ...(child.result || child.terminal.kind === "completed" ? {} : { partialText: assistantTextTail.trim() }),
                 },
                 signal: ctx.signal,
             });
@@ -3775,14 +3789,14 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 tasks: 1 + (ns?.tasks ?? 0),
                 costMicroUsd: rollupDelegatedCost(child.stats, ns),
             });
-            if (isDurablePause(child.status)) {
+            if (isDurablePause(child.terminal)) {
                 if (retainEntry)
                     ctx.subagentRetain?.abandon(ctx.toolCallId);
-                return durablePauseDelegationReport(def ? ` · ${def.name}` : "", child);
+                return durablePauseDelegationReport(def ? ` · ${def.name}` : "", child.terminal);
             }
             let failureRetained = false;
             if (!retainEntry) {
-                if (child.status !== "completed" && opts.retainFailedSessions !== false) {
+                if (child.terminal.kind !== "completed" && opts.retainFailedSessions !== false) {
                     failureRetained = await retainFailedChildSession(child.sessionId);
                 }
                 if (!failureRetained) {
@@ -3794,16 +3808,16 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
             }
             const worktreeLine = await finishWorktree();
-            const errClass = classifySubagentError(child);
+            const errClass = classifySubagentError(child.terminal);
             const lines = [
                 ...(handbackWarning ? [handbackWarning, ""] : []),
                 `[Sub-agent report${def ? ` · ${def.name}` : ""}${a.description ? ` · ${String(a.description)}` : ""}]`,
-                `status: ${child.status}`,
+                `status: ${childFace.status}`,
                 modelNote ?? "",
                 extraToolsNote ?? "",
                 worktreeLine ?? "",
-                child.blockedReason ? `blocked_reason: ${inlineUntrusted(child.blockedReason, REPORT_FIELD_MAX)}` : "",
-                child.errorMessage ? `error: ${inlineUntrusted(child.errorMessage, REPORT_FIELD_MAX)}` : "",
+                childFace.blockedReason ? `blocked_reason: ${inlineUntrusted(childFace.blockedReason, REPORT_FIELD_MAX)}` : "",
+                childFace.errorMessage ? `error: ${inlineUntrusted(childFace.errorMessage, REPORT_FIELD_MAX)}` : "",
                 errClass ? `error_kind: ${errClass.errorKind} (retryable: ${errClass.retryable})` : "",
                 observerFailure !== undefined
                     ? `observer: failed (${inlineUntrusted(observerFailure, REPORT_FIELD_MAX)})`
@@ -3816,7 +3830,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 failureRetained
                     ? `session_retained: this child's session is kept for a short time (~15 min) so its transcript stays inspectable via transcript_id; it is released automatically afterwards.`
                     : "",
-                ...(child.status !== "completed"
+                ...(child.terminal.kind !== "completed"
                     ? (() => {
                         const rs = stepRecorder.recentSteps();
                         const ef = stepRecorder.editedFiles();
@@ -3837,7 +3851,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 "result:",
                 child.result
                     ? delimitUntrusted("sub-agent result", child.result)
-                    : child.status !== "completed" && assistantTextTail.trim() !== ""
+                    : child.terminal.kind !== "completed" && assistantTextTail.trim() !== ""
                         ? `partial findings (the child's last assistant text before it stopped):\n${delimitUntrusted("sub-agent partial findings", assistantTextTail.trim())}`
                         : "(no text result)",
                 "",
@@ -3853,7 +3867,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(def !== undefined ? { subagentType: def.name } : {}),
                     error: errClass,
                     ...(() => {
-                        const a = childAttestation(child.status);
+                        const a = childAttestation(child.terminal.kind === "completed");
                         return a !== undefined ? { attestation: a } : {};
                     })(),
                     ...(handbackWarning !== undefined ? { handbackWarning } : {}),