@sema-agent/core 5.12.0 → 5.14.0

package/dist/agents/subagent.js

@@ -17,7 +17,9 @@ import { uuidv7 } from "../internal/harness.js";
 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 } from "../config/defaults.js";
 function rollupDelegatedCost(stats, nested) {
     if (stats.costMicroUsd === undefined)
@@ -52,6 +54,39 @@ export function notifyResultField(result) {
         ? `${result.slice(0, BG_AGENT_NOTIFY_RESULT_MAX)}\n[result truncated: ${result.length} chars total — call TaskOutput for the full text]`
         : result;
 }
+const HANDBACK_ASK_MESSAGE = "Subagent has finished and is handing back control to the main agent. Review the subagent's work and flag if any action may violate security policy.";
+async function reviewHandback(opts) {
+    const { review, evidence, signal } = opts;
+    if (review === undefined)
+        return undefined;
+    if (signal?.aborted === true)
+        return undefined;
+    if (!evidence.result && !evidence.steps && !evidence.edits && !evidence.partialText)
+        return undefined;
+    const verdict = await review.decider
+        .decide({
+        req: {
+            toolName: opts.toolName,
+            args: {
+                result: evidence.result?.slice(0, 2_000),
+                toolSteps: evidence.steps,
+                editedFiles: evidence.edits,
+                ...(evidence.partialText ? { partialFindings: evidence.partialText.slice(0, 2_000) } : {}),
+            },
+            toolCallId: opts.toolCallId,
+        },
+        askMessage: HANDBACK_ASK_MESSAGE,
+    }, signal)
+        .catch(() => ({ kind: "unavailable", cause: "error" }));
+    if (verdict.kind !== "block")
+        return undefined;
+    return `SECURITY WARNING: This subagent performed actions that may violate security policy. Reason: ${inlineUntrusted(verdict.reason ?? "(no reason given)")}. Review the subagent's actions carefully before acting on its output.`;
+}
+function withHandbackWarning(warning, result) {
+    if (warning === undefined)
+        return result;
+    return result ? `${warning}\n\n${result}` : warning;
+}
 export function inheritedManifestScopeFor(snapshot) {
     if (!snapshot || snapshot.length === 0)
         return undefined;
@@ -221,6 +256,7 @@ export function classifySubagentError(child) {
         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"))
@@ -229,10 +265,10 @@ export function classifySubagentError(child) {
                 ? "timeout"
                 : code === "network" || code === "server"
                     ? "network"
-                    : code !== undefined && code.startsWith("usage.")
+                    : governanceClass !== undefined
                         ? "governance"
                         : "logic";
-    return { errorKind, retryable: errorKind !== "logic" && errorKind !== "governance" };
+    return { errorKind, retryable: errorKind === "governance" ? governanceClass === "transient" : errorKind !== "logic" };
 }
 export function completedAgentCard(child, extras) {
     return {
@@ -249,6 +285,7 @@ export function completedAgentCard(child, extras) {
         ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}),
         ...(child.retryAfterMs !== undefined ? { retryAfterMs: child.retryAfterMs } : {}),
         ...(child.degraded !== undefined ? { degraded: child.degraded } : {}),
+        ...(extras.handbackWarning !== undefined ? { handbackWarning: extras.handbackWarning } : {}),
         ...(extras.error ? { error_kind: extras.error.errorKind, retryable: extras.error.retryable } : {}),
         stats: child.stats,
         ...(child.model !== undefined ? { model: child.model, resolvedModel: child.model } : {}),
@@ -284,7 +321,7 @@ function durablePauseDelegationReport(reportLabel, child) {
 function unparkedDurablePauseReason(d) {
     return d.kind === "no_park_lane"
         ? `the agent hit an approval gate and paused durably, but this delegation cannot be parked ` +
-            `(parking needs an explicitly named child plus a durable agent row, a checkpoint store and the ` +
+            `(parking needs a durable agent row, a checkpoint store and the ` +
             `durable-session capability). Its checkpoint ${d.checkpointToken} is still committed and the ` +
             `approval must be resolved through the deployment's approval channel; the gated action never ran.`
         : `the agent hit an approval gate and paused durably, but the park did not take (` +
@@ -295,6 +332,10 @@ function unparkedDurablePauseReason(d) {
 function errorKindClause(c) {
     return c !== undefined ? ` (error_kind: ${c.errorKind}, retryable: ${c.retryable})` : "";
 }
+function stripSpawnTurnQuestionFace(spec) {
+    const { onQuestion: spawnTurnQuestionFace, ...rest } = spec;
+    return { spec: rest, internalsFlag: spawnTurnQuestionFace !== undefined ? { questionFaceStripped: true } : {} };
+}
 const FAILED_SESSION_RETAIN_TTL_MS = 15 * 60 * 1000;
 const PARTIAL_FINDINGS_MAX_CHARS = 1200;
 const BG_NOTIFY_DRAIN_WINDOW_MS = 2_000;
@@ -501,6 +542,13 @@ export function createSubagentResume(deps) {
                             }
                             catch {
                             }
+                            try {
+                                const resumedOrgVerdict = entry.internalsSnapshot.ownOrgAdmissionRef?.current;
+                                if (resumedOrgVerdict !== undefined)
+                                    deps.registry.recordBackgroundAgentOrgAdmission(deps.taskId, resumedOrgVerdict);
+                            }
+                            catch {
+                            }
                         },
                     }
                     : {}),
@@ -528,6 +576,14 @@ export function createSubagentResume(deps) {
                     void _;
                 const child = await stream.result();
                 let status = child.status === "completed" ? "completed" : abort.signal.aborted ? "killed" : "failed";
+                const resumeHandbackWarning = await reviewHandback({
+                    review: deps.currentAutoModeReview,
+                    toolCallId: deps.parentToolCallId,
+                    toolName: "Agent(handback)",
+                    evidence: { result: child.result, steps: resumeStepRecorder.recentSteps(), edits: resumeStepRecorder.editedFiles() },
+                    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 } : {}) })
@@ -536,7 +592,7 @@ export function createSubagentResume(deps) {
                     try {
                         const winner = deps.registry.settleRevivedAgent(deps.taskId, reviveCycle, {
                             status,
-                            ...resultSettleFields(child.result),
+                            ...resultSettleFields(resumeHandbackResult),
                             ...(status !== "completed" ? { error: (child.errorMessage ?? `resumed run ${status}`).slice(0, 500) } : {}),
                             ...(errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
                             ...(errClassRevive !== undefined ? { retryable: errClassRevive.retryable, errorKind: errClassRevive.errorKind } : {}),
@@ -583,7 +639,7 @@ export function createSubagentResume(deps) {
                     summary: reviveTerminalSummary,
                     ...(failReasonRevive !== undefined ? { error: failReasonRevive.slice(0, REPORT_FIELD_MAX) } : {}),
                     ...(status === "failed" && errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
-                    ...(child.result ? { result: notifyResultField(child.result) } : {}),
+                    ...(resumeHandbackResult ? { result: notifyResultField(resumeHandbackResult) } : {}),
                     ...(status === "killed" && child.result ? { partial: true } : {}),
                     ...resumeResidual(),
                     resumable: status !== "killed",
@@ -1302,7 +1358,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const runObserverLeg = async (spec) => {
                     if (!isObserverTaskId(sid))
                         throw new ObserverStoppedByUserError("observer identity revoked — delivery refused");
-                    const r = await opts.runner.runTask(spec);
+                    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}` : ""}`);
@@ -1441,8 +1497,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(inheritedManifestScope ? { inheritedManifestScope } : {}),
                 ...(treeScope !== undefined ? { registryScope: treeScope } : {}),
                 ...(ctx.inheritedGateForChildren ? { inheritedGate: ctx.inheritedGateForChildren() } : {}),
+                ownOrgAdmissionRef: { current: reviveClaim !== undefined ? readDurableOrgAdmission(reviveClaim.row) : undefined },
                 ...(childDefaultPersona !== undefined ? { defaultSystemPrompt: childDefaultPersona } : {}),
                 isDelegatedChild: true,
+                ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}),
                 parentToolCallId: ctx.toolCallId,
                 ...(childAgentName ? { agentName: childAgentName } : {}),
                 ...(agentName !== undefined ? { explicitAgentName: agentName } : {}),
@@ -1511,11 +1569,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 limits: childLimits,
                 signal,
             });
-            const tryRetainChild = async (ledger, entryTtlMs, preMintedSessionId, durableProbe, releaseAnchor) => {
+            const tryRetainChild = async (ledger, entryTtlMs, preMintedSessionId, durableProbe, releaseAnchor, internalsExtra) => {
                 if (!ledger)
                     return undefined;
                 const childSessionId = preMintedSessionId ?? uuidv7();
-                const { signal: _spawnSignal, onQuestion: _spawnTurnQuestionFace, ...plainSpec } = buildChildSpec(undefined);
+                const retainStrip = stripSpawnTurnQuestionFace(buildChildSpec(undefined));
+                const { signal: _spawnSignal, ...plainSpec } = retainStrip.spec;
                 let entry = ledger.register(ctx.toolCallId, {
                     childSessionId,
                     runner: opts.runner,
@@ -1532,7 +1591,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(plainSpec.deferTools !== undefined ? { deferTools: [...plainSpec.deferTools] } : {}),
                         ...(plainSpec.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...plainSpec.alwaysLoadTools] } : {}),
                     }),
-                    internalsSnapshot: { ...childInternals },
+                    internalsSnapshot: { ...childInternals, ...retainStrip.internalsFlag, ...(internalsExtra ?? {}) },
                     release: async () => {
                         try {
                             await opts.runner.sessions.unpin?.(childSessionId);
@@ -1595,14 +1654,14 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 if (ledger !== undefined && !ledger.disposed) {
                     if (opts.background)
                         ensureSessionReapHook(opts.background.registry);
-                    const { signal: _spawnSignal, onQuestion: _spawnTurnQuestionFace, ...plainSpec } = buildChildSpec(undefined);
+                    const failedRetainStrip = stripSpawnTurnQuestionFace(buildChildSpec(undefined));
+                    const { signal: _spawnSignal, ...plainSpec } = failedRetainStrip.spec;
                     const entry = ledger.register(ctx.toolCallId, {
                         childSessionId,
                         runner: opts.runner,
                         ttlMs: FAILED_SESSION_RETAIN_TTL_MS,
                         ...(childAgentName !== undefined ? { agentName: childAgentName } : {}),
                         ...(agentName !== undefined ? { explicitAgentName: agentName } : {}),
-                        ...(agentName !== undefined ? { explicitAgentName: agentName } : {}),
                         specSnapshot: Object.freeze({
                             ...plainSpec,
                             tools: [...(plainSpec.tools ?? [])],
@@ -1613,7 +1672,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(plainSpec.deferTools !== undefined ? { deferTools: [...plainSpec.deferTools] } : {}),
                             ...(plainSpec.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...plainSpec.alwaysLoadTools] } : {}),
                         }),
-                        internalsSnapshot: { ...childInternals },
+                        internalsSnapshot: { ...childInternals, ...failedRetainStrip.internalsFlag },
                         release: releaseChild,
                     });
                     if (entry) {
@@ -1713,7 +1772,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         else if (!sessionScopedBg)
                             ctx.signal.addEventListener("abort", onHostAbort, { once: true });
                     }
-                    const dropTurnBoundQuestionFace = sessionScopedBg ? { onQuestion: undefined } : {};
                     const shortDesc = `fork: ${(typeof a.description === "string" && a.description.trim() ? a.description.trim() : prompt).slice(0, 180)}`;
                     const bgOwner = sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
                     const bgScope = treeScope;
@@ -1806,7 +1864,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         startedAt: Date.now(),
                     });
                     const forkBgStartedAt = Date.now();
-                    const bgForkSpec = { ...buildChildSpec(abort.signal), sessionId: forkedId, requireExistingSession: true, objective: forkObjective, ...dropTurnBoundQuestionFace };
+                    const bgForkSpecBase = { ...buildChildSpec(abort.signal), sessionId: forkedId, requireExistingSession: true, objective: forkObjective };
+                    const forkQuestionStrip = sessionScopedBg ? stripSpawnTurnQuestionFace(bgForkSpecBase) : undefined;
+                    const bgForkSpec = forkQuestionStrip !== undefined ? forkQuestionStrip.spec : bgForkSpecBase;
                     const s2ForkNotifyReady = (inject) => {
                         bg.registry.attachAgentNotify(taskId, inject);
                     };
@@ -1830,7 +1890,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const bgForkInternals = bgSink
                         ? {
                             ...forkInternals,
+                            ...(forkQuestionStrip !== undefined ? forkQuestionStrip.internalsFlag : {}),
                             onNotifyInjectorReady: s2ForkNotifyReady,
+                            delegationTaskType: "background_agent",
                             onForwardEvent: (e) => {
                                 try {
                                     recordingForward(e, { bgAgentId: taskId });
@@ -1861,7 +1923,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                         : {
                             ...forkInternals,
+                            ...(forkQuestionStrip !== undefined ? forkQuestionStrip.internalsFlag : {}),
                             onNotifyInjectorReady: s2ForkNotifyReady,
+                            delegationTaskType: "background_agent",
                             onForwardEvent: (e) => {
                                 try {
                                     recordingForward(e, { bgAgentId: taskId });
@@ -1886,6 +1950,14 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                         catch {
                         }
+                        const forkBgWarning = await reviewHandback({
+                            review: ctx.autoModeReview,
+                            toolCallId: ctx.toolCallId,
+                            toolName: "Agent(fork handback)",
+                            evidence: { result: child.result, steps: stepRecorder.recentSteps(), edits: stepRecorder.editedFiles() },
+                            signal: abort.signal,
+                        });
+                        const forkBgResult = withHandbackWarning(forkBgWarning, child.result);
                         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";
@@ -1897,7 +1969,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
                             cycle: 0,
                             status: okBg ? "completed" : reapedBg ? "killed" : "failed",
-                            ...resultSettleFields(child.result),
+                            ...resultSettleFields(forkBgResult),
                             ...(!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 } : {}),
@@ -1948,7 +2020,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     ...(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) } : {}),
+                                    ...(forkBgResult ? { result: notifyResultField(forkBgResult) } : {}),
                                     ...(settledBg === "killed" && child.result ? { partial: true } : {}),
                                     ...residualFork,
                                     resumable: resumableFork,
@@ -2051,6 +2123,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const wt = await finishWorktree();
                     return { isError: true, content: `Fork failed: the forked run threw (${e instanceof Error ? e.message : String(e)}).${wt ? `\n${wt}` : ""}`, details: { error: "fork run failed" } };
                 }
+                const forkHandbackWarning = await reviewHandback({
+                    review: ctx.autoModeReview,
+                    toolCallId: ctx.toolCallId,
+                    toolName: "Agent(fork handback)",
+                    evidence: { result: forkChild.result, steps: stepRecorder.recentSteps(), edits: stepRecorder.editedFiles() },
+                    signal: ctx.signal,
+                });
                 const nsf = forkChild.stats.nested;
                 ctx.reportUsage?.({
                     tokens: forkChild.stats.tokens + (nsf?.tokens ?? 0),
@@ -2064,6 +2143,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const wtLine = await finishWorktree();
                 const forkErr = classifySubagentError(forkChild);
                 const forkLines = [
+                    ...(forkHandbackWarning ? [forkHandbackWarning, ""] : []),
                     `[Sub-agent report · ${FORK_SUBAGENT_TYPE}${a.description ? ` · ${String(a.description)}` : ""}] (forked session …${forkedId.slice(-8)})`,
                     `status: ${forkChild.status}`,
                     modelNote ?? "",
@@ -2085,6 +2165,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     details: completedAgentCard(forkChild, {
                         subagentType: FORK_SUBAGENT_TYPE,
                         error: forkErr,
+                        ...(forkHandbackWarning !== undefined ? { handbackWarning: forkHandbackWarning } : {}),
                         ...(worktreeKeptPath !== undefined ? { worktreePath: worktreeKeptPath } : {}),
                         ...(() => {
                             const ts = toolStatsCounter.snapshot();
@@ -2253,7 +2334,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : ctx.subagentRetain;
                 if (sessionScopedBg && bgRetainLedger)
                     ensureSessionReapHook(bg.registry);
-                const bgRetain = await tryRetainChild(bgRetainLedger, sessionScopedBg && ctx.subagentRetain ? ctx.subagentRetain.ttlMs : undefined, bgChildSessionId, bgDurableProbe, () => bg.registry.releaseDurableTranscriptAnchor(taskId));
+                const bgRetain = await tryRetainChild(bgRetainLedger, sessionScopedBg && ctx.subagentRetain ? ctx.subagentRetain.ttlMs : undefined, bgChildSessionId, bgDurableProbe, () => bg.registry.releaseDurableTranscriptAnchor(taskId), {
+                    delegationTaskType: "background_agent",
+                });
                 if (bgRetain) {
                     bg.registry.markRetainedContinuation(taskId);
                     const origRelease = bgRetain.release;
@@ -2263,23 +2346,26 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     };
                 }
                 const forwardDurableApproval = ctx.durableApprovalForChildren !== undefined &&
-                    agentName !== undefined &&
                     bg.agentStore !== undefined &&
                     bg.checkpointStore !== undefined &&
                     bg.ensureChildSessionDurable !== undefined;
-                const bgSpec = {
+                const bgSpecBase = {
                     ...buildChildSpec(abort.signal),
                     sessionId: bgChildSessionId,
                     ...(forwardDurableApproval ? { durableApproval: { ...ctx.durableApprovalForChildren } } : {}),
                     ...(reviveRow !== undefined ? { requireExistingSession: true } : {}),
-                    ...(outlivesThisRequest ? { onQuestion: undefined } : {}),
                 };
+                const bgQuestionStrip = outlivesThisRequest ? stripSpawnTurnQuestionFace(bgSpecBase) : undefined;
+                const bgSpec = bgQuestionStrip !== undefined ? bgQuestionStrip.spec : bgSpecBase;
                 let reviveAttachedResolve;
                 const reviveAttached = reviveRow !== undefined ? new Promise((r) => (reviveAttachedResolve = r)) : undefined;
                 const s2NotifyReady = (inject) => {
                     bg.registry.attachAgentNotify(taskId, inject);
                     if (parkedResume !== undefined)
                         bg.registry.finalizeParkedResume(taskId);
+                    const legOrgVerdict = childInternals.ownOrgAdmissionRef?.current;
+                    if (legOrgVerdict !== undefined)
+                        bg.registry.recordBackgroundAgentOrgAdmission(taskId, legOrgVerdict);
                     reviveAttachedResolve?.();
                 };
                 const bgActivityBeat = createBgActivityBeat(ctx.toolCallId, (toolStarts) => {
@@ -2302,7 +2388,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const bgInternals = bgSink
                     ? {
                         ...childInternals,
+                        ...(bgQuestionStrip !== undefined ? bgQuestionStrip.internalsFlag : {}),
                         onNotifyInjectorReady: s2NotifyReady,
+                        delegationTaskType: "background_agent",
                         onForwardEvent: (e) => {
                             try {
                                 recordingForward(e, { bgAgentId: taskId });
@@ -2333,7 +2421,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     : {
                         ...childInternals,
+                        ...(bgQuestionStrip !== undefined ? bgQuestionStrip.internalsFlag : {}),
                         onNotifyInjectorReady: s2NotifyReady,
+                        delegationTaskType: "background_agent",
                         onForwardEvent: (e) => {
                             try {
                                 recordingForward(e, { bgAgentId: taskId });
@@ -2485,6 +2575,16 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     catch {
                     }
                     const seqAtSettle = bgRetain?.cycleSeq ?? (parkedResume !== undefined ? (reviveRow?.seq ?? 1) + 1 : reviveRow?.seq);
+                    const bgHandbackWarning = isDurablePause(child.status)
+                        ? undefined
+                        : await reviewHandback({
+                            review: ctx.autoModeReview,
+                            toolCallId: ctx.toolCallId,
+                            toolName: "Agent(handback)",
+                            evidence: { result: child.result, steps: stepRecorder.recentSteps(), edits: stepRecorder.editedFiles() },
+                            signal: abort.signal,
+                        });
+                    const bgHandbackResult = withHandbackWarning(bgHandbackWarning, child.result);
                     if (bgRetain) {
                         if (isDurablePause(child.status))
                             bgRetainLedger?.abandon(ctx.toolCallId);
@@ -2507,7 +2607,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 return false;
                             }
                         };
-                        const wired = agentName !== undefined && bg.agentStore !== undefined && cpStore !== undefined && bg.ensureChildSessionDurable !== undefined;
+                        const wired = bg.agentStore !== undefined && cpStore !== undefined && bg.ensureChildSessionDurable !== undefined;
                         if (wired) {
                             const token = child.checkpointToken;
                             if (abort.signal.aborted) {
@@ -2566,7 +2666,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         cycle: 0,
                         status: ok ? "completed" : reaped ? "killed" : "failed",
                         seq: seqAtSettle ?? 1,
-                        ...resultSettleFields(child.result),
+                        ...resultSettleFields(bgHandbackResult),
                         ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : unparkedPauseReason ?? child.errorMessage ?? String(child.status) } : {}),
                         ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
                         ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
@@ -2618,7 +2718,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(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) } : {}),
+                        ...(bgHandbackResult ? { result: notifyResultField(bgHandbackResult) } : {}),
                         ...(settled === "killed" && child.result ? { partial: true } : {}),
                         ...residual,
                         resumable: resumableBg,
@@ -2775,6 +2875,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(opts.background ? { registry: opts.background.registry } : {}),
                         ...(opts.onObserverError !== undefined ? { onNotifyError: (f) => opts.onObserverError?.(f.error, { site: f.site }) } : {}),
                         ...(ctx.onQuestion !== undefined ? { currentOnQuestion: ctx.onQuestion } : {}),
+                        ...(ctx.autoModeReview !== undefined ? { currentAutoModeReview: ctx.autoModeReview } : {}),
                     });
                     notifier.notify(() => ctx.onSubagentSpawn?.(createSteerHandle(stream, ctx.toolCallId, childAgentName, settled, {
                         resume,
@@ -2799,26 +2900,18 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 child = await opts.runner.runTask(buildChildSpec(ctx.signal), childInternals);
             }
             await settleObserver(child.status);
-            let handbackWarning;
-            if (ctx.autoModeReview) {
-                const handbackSteps = stepRecorder.recentSteps();
-                const handbackEdits = stepRecorder.editedFiles();
-                if (child.result || handbackSteps || handbackEdits) {
-                    const handbackVerdict = await ctx.autoModeReview.decider
-                        .decide({
-                        req: {
-                            toolName: "Agent(handback)",
-                            args: { result: child.result?.slice(0, 2_000), toolSteps: handbackSteps, editedFiles: handbackEdits },
-                            toolCallId: ctx.toolCallId,
-                        },
-                        askMessage: "Subagent has finished and is handing back control to the main agent. Review the subagent's work and flag if any action may violate security policy.",
-                    }, ctx.signal)
-                        .catch(() => ({ kind: "unavailable", cause: "error" }));
-                    if (handbackVerdict.kind === "block") {
-                        handbackWarning = `SECURITY WARNING: This subagent performed actions that may violate security policy. Reason: ${inlineUntrusted(handbackVerdict.reason ?? "(no reason given)")}. Review the subagent's actions carefully before acting on its output.`;
-                    }
-                }
-            }
+            const handbackWarning = await reviewHandback({
+                review: ctx.autoModeReview,
+                toolCallId: ctx.toolCallId,
+                toolName: "Agent(handback)",
+                evidence: {
+                    result: child.result,
+                    steps: stepRecorder.recentSteps(),
+                    edits: stepRecorder.editedFiles(),
+                    ...(child.result || child.status === "completed" ? {} : { partialText: assistantTextTail.trim() }),
+                },
+                signal: ctx.signal,
+            });
             const ns = child.stats.nested;
             ctx.reportUsage?.({
                 tokens: child.stats.tokens + (ns?.tokens ?? 0),
@@ -2903,6 +2996,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 details: completedAgentCard(child, {
                     ...(def !== undefined ? { subagentType: def.name } : {}),
                     error: errClass,
+                    ...(handbackWarning !== undefined ? { handbackWarning } : {}),
                     ...(modelFallback !== undefined ? { modelFallback } : {}),
                     ...(worktreeKeptPath !== undefined ? { worktreePath: worktreeKeptPath } : {}),
                     ...(() => {

package/dist/brain/anthropic.js

@@ -5,7 +5,7 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
 import { isThinkingLevel, reasoningBudgetShare, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const MIN_THINKING_TOKENS = 1024;
@@ -233,7 +233,7 @@ export function createAnthropicBrain(config = {}) {
             config,
             httpLabel: "anthropic",
             stallTimeouts: options?.stallTimeouts,
-            buildRequest: () => {
+            buildRequest: (overrides) => {
                 const apiKey = options?.apiKey ?? config.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "https://api.anthropic.com").replace(/\/+$/, "");
                 const nonEmptyBlocks = context.systemBlocks?.filter((b) => b.text.length > 0);
@@ -248,7 +248,7 @@ export function createAnthropicBrain(config = {}) {
                         : undefined;
                 const body = {
                     model: model.id,
-                    max_tokens: options?.maxTokens ?? model.maxTokens ?? config.defaultMaxTokens ?? 4096,
+                    max_tokens: overrides?.maxOutputTokens ?? options?.maxTokens ?? model.maxTokens ?? config.defaultMaxTokens ?? 4096,
                     messages: toAnthropicMessages(context, model),
                     stream: true,
                 };
@@ -266,7 +266,7 @@ export function createAnthropicBrain(config = {}) {
                         body.thinking = { type: "adaptive" };
                     }
                     else {
-                        const hardCap = options?.maxTokens !== undefined;
+                        const hardCap = overrides?.maxOutputTokens !== undefined || options?.maxTokens !== undefined;
                         if (hardCap && body.max_tokens < MIN_THINKING_TOKENS * 2) {
                             body.thinking = undefined;
                             delete body.thinking;
@@ -322,11 +322,28 @@ export function createAnthropicBrain(config = {}) {
                 headers["anthropic-version"] = config.version ?? "2023-06-01";
                 if (apiKey)
                     headers["x-api-key"] = apiKey;
-                thinkingRequested = body.thinking !== undefined;
-                sentMaxTokens = body.max_tokens;
-                sentMaxTokensLane =
-                    options?.maxTokens !== undefined ? "options" : model.maxTokens !== undefined ? "model" : "config-default";
-                return { url: `${root}/v1/messages`, headers, body: JSON.stringify(applyExtraBody(body, model.extraBody, ANTHROPIC_RESERVED)) };
+                const builtThinkingRequested = body.thinking !== undefined;
+                const builtMaxTokens = body.max_tokens;
+                const builtMaxTokensLane = overrides?.maxOutputTokens !== undefined
+                    ? "engine"
+                    : options?.maxTokens !== undefined
+                        ? "options"
+                        : model.maxTokens !== undefined
+                            ? "model"
+                            : "config-default";
+                const wire = applyExtraBody(body, model.extraBody, ANTHROPIC_RESERVED);
+                return {
+                    url: `${root}/v1/messages`,
+                    headers,
+                    body: JSON.stringify(wire),
+                    outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.anthropic),
+                    capDerivedPaths: [...OUTPUT_CAP_KEYS.anthropic, "thinking.budget_tokens"],
+                    onCommitted: () => {
+                        thinkingRequested = builtThinkingRequested;
+                        sentMaxTokens = builtMaxTokens;
+                        sentMaxTokensLane = builtMaxTokensLane;
+                    },
+                };
             },
             makeParser: (ctrl) => {
                 const { out, partial } = ctrl;
@@ -588,7 +605,13 @@ export function createAnthropicBrain(config = {}) {
                         const safetyCut = stopReason === "refusal";
                         const contextWindowExceeded = stopReason === "model_context_window_exceeded";
                         const emptyNoFinish = noUsableContent && stopReason == null && !degenerate;
-                        const maxTokensNote = `effective max_tokens=${sentMaxTokens ?? "?"} (from ${sentMaxTokensLane === "options" ? "options.maxTokens" : sentMaxTokensLane === "model" ? "model.maxTokens" : "config default"})`;
+                        const maxTokensNote = `effective max_tokens=${sentMaxTokens ?? "?"} (from ${sentMaxTokensLane === "options"
+                            ? "options.maxTokens"
+                            : sentMaxTokensLane === "engine"
+                                ? "the engine's context-overflow recovery"
+                                : sentMaxTokensLane === "model"
+                                    ? "model.maxTokens"
+                                    : "config default"})`;
                         const errorMessage = degenerate
                             ? DEGENERATE_MESSAGE
                             : safetyCut

package/dist/brain/context-overflow.d.ts

@@ -0,0 +1,20 @@
+export declare const FLOOR_OUTPUT_TOKENS = 3000;
+export interface ContextOverflowReport {
+    inputTokens: number;
+    maxTokens: number;
+    contextLimit: number;
+}
+export declare function parseContextOverflow(status: number, body: string): ContextOverflowReport | undefined;
+export type OutputCapAdjustment = {
+    outcome: "adjust";
+    maxOutputTokens: number;
+    current: number;
+} | {
+    outcome: "below_floor";
+    available: number;
+} | {
+    outcome: "no_progress";
+    available: number;
+    current: number;
+};
+export declare function planOutputCapAdjustment(report: ContextOverflowReport, otherCapsInEffect?: readonly (number | undefined)[]): OutputCapAdjustment;

package/dist/brain/context-overflow.js

@@ -0,0 +1,58 @@
+export const FLOOR_OUTPUT_TOKENS = 3000;
+const CONTEXT_HEADROOM_TOKENS = 1000;
+const CONTEXT_OVERFLOW_RE = /^input length and `max_tokens` exceed context limit: (\d+) \+ (\d+) > (\d+)(?!\w|[.,]\d|\s\d|[+\-*/])/;
+const CONTEXT_OVERFLOW_PREFIX = "input length and `max_tokens` exceed context limit:";
+function providerDiagnostic(body) {
+    const trimmed = body.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const err = parsed.error;
+    if (typeof err !== "object" || err === null || Array.isArray(err))
+        return undefined;
+    const message = err.message;
+    return typeof message === "string" ? message : undefined;
+}
+function reportFrom(diagnostic) {
+    const message = diagnostic.trimStart();
+    const m = CONTEXT_OVERFLOW_RE.exec(message);
+    if (m === null)
+        return undefined;
+    if (message.slice(m[0].length).includes(CONTEXT_OVERFLOW_PREFIX))
+        return undefined;
+    const [, rawInput, rawMax, rawLimit] = m;
+    if (rawInput === undefined || rawMax === undefined || rawLimit === undefined)
+        return undefined;
+    const inputTokens = Number.parseInt(rawInput, 10);
+    const maxTokens = Number.parseInt(rawMax, 10);
+    const contextLimit = Number.parseInt(rawLimit, 10);
+    if (!Number.isSafeInteger(inputTokens) || !Number.isSafeInteger(maxTokens) || !Number.isSafeInteger(contextLimit)) {
+        return undefined;
+    }
+    if (inputTokens <= contextLimit - maxTokens)
+        return undefined;
+    return { inputTokens, maxTokens, contextLimit };
+}
+export function parseContextOverflow(status, body) {
+    if (status !== 400)
+        return undefined;
+    const diagnostic = providerDiagnostic(body);
+    return diagnostic === undefined ? undefined : reportFrom(diagnostic);
+}
+export function planOutputCapAdjustment(report, otherCapsInEffect = []) {
+    const available = Math.max(0, report.contextLimit - report.inputTokens - CONTEXT_HEADROOM_TOKENS);
+    if (available < FLOOR_OUTPUT_TOKENS)
+        return { outcome: "below_floor", available };
+    const current = Math.min(report.maxTokens, ...otherCapsInEffect.filter((c) => c !== undefined));
+    if (available >= current)
+        return { outcome: "no_progress", available, current };
+    return { outcome: "adjust", maxOutputTokens: available, current };
+}