@sema-agent/core 5.55.0 → 5.57.0

package/dist/agents/subagent.js

@@ -1032,6 +1032,134 @@ export function delegationEntryLedgerFootprint(registry) {
         handles += s.size;
     return { keys: byKey.size, handles };
 }
+const localDelegationInFlight = new WeakMap();
+function localDelegationInFlightCount(anchor, key) {
+    return localDelegationInFlight.get(anchor)?.get(key) ?? 0;
+}
+function chargeLocalDelegationInFlight(anchor, key) {
+    let byKey = localDelegationInFlight.get(anchor);
+    if (byKey === undefined) {
+        byKey = new Map();
+        localDelegationInFlight.set(anchor, byKey);
+    }
+    byKey.set(key, (byKey.get(key) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const live = localDelegationInFlight.get(anchor);
+        if (live === undefined)
+            return;
+        const n = (live.get(key) ?? 0) - 1;
+        if (n > 0)
+            live.set(key, n);
+        else
+            live.delete(key);
+    };
+}
+const spawnAbortedResult = (wt) => ({
+    isError: true,
+    content: `Sub-agent not started: the delegating call was aborted.${wt ? `\n${wt}` : ""}`,
+    details: { error: "aborted" },
+});
+const noopRelease = () => undefined;
+const DELEGATION_POOL_DEFAULT_SCOPE = "default";
+async function untilAbort(p, signal) {
+    if (signal === undefined)
+        return await p;
+    if (signal.aborted)
+        throw new Error("delegation entry gate: aborted before the durable floor was read");
+    let onAbort;
+    try {
+        return await Promise.race([
+            p,
+            new Promise((_resolve, reject) => {
+                onAbort = () => reject(new Error("delegation entry gate: aborted while reading the durable floor"));
+                signal.addEventListener("abort", onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+async function openDelegationEntryGate(input) {
+    const { poolAnchor, registry, store, root, caps, revival, signal } = input;
+    if (root === undefined)
+        return { key: undefined, admit: () => ({ admitted: true, release: noopRelease }) };
+    const scope = input.scope ?? DELEGATION_POOL_DEFAULT_SCOPE;
+    const key = JSON.stringify([scope, root]);
+    let storedHandles = [];
+    let storedEnumerationOk = false;
+    if (store !== undefined && !revival) {
+        try {
+            storedHandles = (await untilAbort(store.listBySession(scope, root), signal)).map((r) => r.handle);
+            storedEnumerationOk = true;
+        }
+        catch {
+            storedHandles = [];
+        }
+    }
+    const admit = (kind) => {
+        const activeFace = registry === undefined ? undefined : registry.activeDelegationHandles;
+        const active = typeof activeFace === "function" ? activeFace.call(registry, scope, root) : [];
+        const local = localDelegationInFlightCount(poolAnchor, key);
+        const running = active.length + local;
+        if (running >= caps.maxConcurrent) {
+            return {
+                admitted: false,
+                refusal: {
+                    code: "delegation.concurrency_cap",
+                    text: `this session tree already has ${running} agents running — the concurrency cap (${caps.maxConcurrent}; RunnerDeps.delegationEntryCaps.maxConcurrent) refuses another. ${kind === "registered" ? "Wait for one to complete (you will be notified) or stop one, then relaunch." : "Wait for one of them to finish or stop one, then try again."}`,
+                },
+            };
+        }
+        if (!revival) {
+            const ledger = delegationEntryLedger(poolAnchor, key);
+            let retained;
+            if (store !== undefined && storedEnumerationOk) {
+                const keep = new Set([...storedHandles, ...active]);
+                if (kind === "registered") {
+                    for (const h of [...ledger])
+                        if (!keep.has(h))
+                            ledger.delete(h);
+                    retained = new Set([...storedHandles, ...ledger]).size;
+                }
+                else {
+                    const survivors = new Set(storedHandles);
+                    for (const h of ledger)
+                        if (keep.has(h))
+                            survivors.add(h);
+                    retained = survivors.size;
+                }
+            }
+            else {
+                retained = ledger.size;
+            }
+            const cumulative = retained + local;
+            if (cumulative >= caps.maxCumulativePerSession) {
+                return {
+                    admitted: false,
+                    refusal: {
+                        code: "delegation.session_cap",
+                        text: `this session tree has already launched ${cumulative} agents in its retained window — the cumulative cap (${caps.maxCumulativePerSession}; RunnerDeps.delegationEntryCaps.maxCumulativePerSession) refuses more. Continue an existing agent (SendMessage) instead of launching new ones.`,
+                    },
+                };
+            }
+        }
+        return { admitted: true, release: kind === "local" ? chargeLocalDelegationInFlight(poolAnchor, key) : noopRelease };
+    };
+    return { key, admit };
+}
+function chargeDelegationEntryHandle(registry, key, store, handle) {
+    if (handle !== undefined)
+        delegationEntryLedger(registry, key).add(handle);
+    bindDelegationLedgerKeyStore(registry, key, store);
+    armDelegationLedgerLifecycle(registry);
+    sweepDelegationLedgerRound(registry, 3);
+}
 export function normalizeSubagentType(value) {
     return value.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "");
 }
@@ -1314,7 +1442,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
         prepareArguments: (args) => foldGeneralPurposeAlias(args, generalPurposeShadowed),
         execute: async (args, ctx) => {
             const a = foldGeneralPurposeAlias(args, generalPurposeShadowed);
-            const wantsBackground = opts.background !== undefined && a.run_in_background !== false;
             const reviveClaim = ctx.reviveClaim;
             if (reviveClaim !== undefined && opts.background === undefined) {
                 return {
@@ -1358,6 +1485,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             }
             const omitted = rawType === "" || (!generalPurposeShadowed && rawType === GENERAL_PURPOSE_SUBAGENT_TYPE);
             const def = hasAgents && !wantsFork && !omitted ? agentMap.get(rawType) : undefined;
+            const wantsBackground = opts.background !== undefined && (a.run_in_background !== false || def?.background === true);
             const spawnAgentType = wantsFork ? FORK_SUBAGENT_TYPE : omitted ? GENERAL_PURPOSE_SUBAGENT_TYPE : rawType;
             if (!def && !wantsFork && !omitted) {
                 return {
@@ -1789,6 +1917,21 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 return { ...(recentSteps ? { recentSteps } : {}), ...(editedFiles ? { editedFiles } : {}) };
             };
             const treeScope = reviveClaim?.row.scope ?? ctx.principal ?? opts.background?.scope;
+            const entryCapPoolAnchor = opts.background?.registry ?? opts;
+            const entryCaps = ctx.delegationEntryCaps ?? { maxConcurrent: DELEGATION_MAX_CONCURRENT_DEFAULT, maxCumulativePerSession: DELEGATION_MAX_PER_SESSION_DEFAULT };
+            const entryCapRoot = reviveClaim !== undefined
+                ? (reviveClaim.row.rootSessionId ?? reviveClaim.row.parentSessionId ?? (reviveClaim.row.sessionScoped ? reviveClaim.row.owner : undefined))
+                : (ctx.rootSessionId ?? ctx.sessionId);
+            const openEntryGate = () => openDelegationEntryGate({
+                poolAnchor: entryCapPoolAnchor,
+                registry: opts.background?.registry,
+                store: opts.background?.agentStore,
+                scope: treeScope,
+                root: entryCapRoot,
+                caps: entryCaps,
+                revival: reviveClaim !== undefined,
+                signal: ctx.signal,
+            });
             const provenanceRequest = ctx.delegationProvenanceForChildren?.();
             const childProvenanceRef = provenanceRequest !== undefined ? { current: newDelegationProvenanceAggregate() } : undefined;
             const childAttestation = (status) => childProvenanceRef !== undefined ? reduceDelegationAttestation(childProvenanceRef.current, { completed: status === "completed" }) : undefined;
@@ -2053,7 +2196,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 if (ctx.signal?.aborted) {
                     await cancelObserver();
                     const wt = await finishWorktree();
-                    return { isError: true, content: `Sub-agent not started: the delegating call was aborted.${wt ? `\n${wt}` : ""}`, details: { error: "aborted" } };
+                    return spawnAbortedResult(wt);
                 }
                 if (spawnVerdict.kind === "block") {
                     await cancelObserver();
@@ -2106,6 +2249,21 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     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;
+                    const forkEntryGate = await openEntryGate();
+                    {
+                        const admission = forkEntryGate.admit("registered");
+                        if (!admission.admitted) {
+                            dropHostAbortListener();
+                            try {
+                                await (releaseForked ? releaseForked() : opts.runner.sessions.release?.(forkedId));
+                            }
+                            catch {
+                            }
+                            await cancelObserver();
+                            const wt = await finishWorktree();
+                            return errorResult(`Sub-agent not started in background: ${admission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: admission.refusal.code, code: admission.refusal.code });
+                        }
+                    }
                     const forkSettlementSeat = ctx.delegationSettlement?.();
                     const forkSettleId = forkSettlementSeat !== undefined ? `bg-${uuidv7()}` : undefined;
                     if (forkSettlementSeat !== undefined && forkSettleId !== undefined) {
@@ -2195,6 +2353,8 @@ 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" } };
                     }
+                    if (forkEntryGate.key !== undefined)
+                        chargeDelegationEntryHandle(bg.registry, forkEntryGate.key, bg.agentStore, taskId);
                     childInternals.peerSelfRef?.addAxis("h", taskId);
                     bg.registry.bindBackgroundAgentSession(taskId, forkedId);
                     const forkBgHangAt = Date.now();
@@ -2507,6 +2667,28 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const bgIgnoredNote = a.run_in_background === true
                     ? `note: run_in_background was ignored for subagent_type "${FORK_SUBAGENT_TYPE}" — the fork ran synchronously (this delegation tool has no background surface configured).`
                     : undefined;
+                const syncForkEntryGate = await openEntryGate();
+                if (ctx.signal?.aborted) {
+                    try {
+                        await (releaseForked ? releaseForked() : opts.runner.sessions.release?.(forkedId));
+                    }
+                    catch {
+                    }
+                    await cancelObserver();
+                    const wt = await finishWorktree();
+                    return spawnAbortedResult(wt);
+                }
+                const syncForkAdmission = syncForkEntryGate.admit("local");
+                if (!syncForkAdmission.admitted) {
+                    try {
+                        await (releaseForked ? releaseForked() : opts.runner.sessions.release?.(forkedId));
+                    }
+                    catch {
+                    }
+                    await cancelObserver();
+                    const wt = await finishWorktree();
+                    return errorResult(`Sub-agent not started: ${syncForkAdmission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: syncForkAdmission.refusal.code, code: syncForkAdmission.refusal.code });
+                }
                 let forkChild;
                 try {
                     forkChild = await opts.runner.runTask({ ...buildChildSpec(ctx.signal), sessionId: forkedId, requireExistingSession: true, objective: forkObjective }, forkInternals);
@@ -2527,6 +2709,9 @@ 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" } };
                 }
+                finally {
+                    syncForkAdmission.release();
+                }
                 const forkHandbackWarning = await reviewHandback({
                     review: ctx.autoModeReview,
                     toolCallId: ctx.toolCallId,
@@ -2601,51 +2786,15 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const shortDesc = reviveRow?.description ?? String(a.description ?? "sub-agent").slice(0, 200);
                 const bgOwner = reviveRow !== undefined ? reviveRow.owner : sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
                 const bgScope = treeScope;
-                const capScope = bgScope;
-                const capRoot = reviveRow !== undefined
-                    ? (reviveRow.rootSessionId ?? reviveRow.parentSessionId ?? (reviveRow.sessionScoped ? reviveRow.owner : undefined))
-                    : (ctx.rootSessionId ?? ctx.sessionId);
-                const entryCaps = ctx.delegationEntryCaps ?? { maxConcurrent: DELEGATION_MAX_CONCURRENT_DEFAULT, maxCumulativePerSession: DELEGATION_MAX_PER_SESSION_DEFAULT };
-                const capLedgerKey = capScope !== undefined && capRoot !== undefined ? JSON.stringify([capScope, capRoot]) : undefined;
-                if (capScope !== undefined && capRoot !== undefined) {
-                    let storedHandles = [];
-                    let storedEnumerationOk = false;
-                    if (bg.agentStore !== undefined && reviveRow === undefined) {
-                        try {
-                            storedHandles = (await bg.agentStore.listBySession(capScope, capRoot)).map((r) => r.handle);
-                            storedEnumerationOk = true;
-                        }
-                        catch {
-                            storedHandles = [];
-                        }
-                    }
-                    const capRefusal = async (code, text) => {
+                const bgEntryGate = await openEntryGate();
+                const capLedgerKey = bgEntryGate.key;
+                {
+                    const admission = bgEntryGate.admit("registered");
+                    if (!admission.admitted) {
                         dropHostAbortListener();
                         await cancelObserver();
                         const wt = await finishWorktree();
-                        return errorResult(`Sub-agent not started in background: ${text}${wt ? `\n${wt}` : ""}`, { error: code, code });
-                    };
-                    const activeFace = bg.registry.activeDelegationHandles;
-                    const active = typeof activeFace === "function" ? activeFace.call(bg.registry, capScope, capRoot) : [];
-                    if (typeof activeFace === "function" && active.length >= entryCaps.maxConcurrent) {
-                        return await capRefusal("delegation.concurrency_cap", `this session tree already has ${active.length} background agents running — the concurrency cap (${entryCaps.maxConcurrent}; RunnerDeps.delegationEntryCaps.maxConcurrent) refuses another. Wait for one to complete (you will be notified) or stop one, then relaunch.`);
-                    }
-                    if (reviveRow === undefined) {
-                        const ledger = delegationEntryLedger(bg.registry, capLedgerKey);
-                        let cumulative;
-                        if (bg.agentStore !== undefined && storedEnumerationOk) {
-                            const keep = new Set([...storedHandles, ...active]);
-                            for (const h of [...ledger])
-                                if (!keep.has(h))
-                                    ledger.delete(h);
-                            cumulative = new Set([...storedHandles, ...ledger]).size;
-                        }
-                        else {
-                            cumulative = ledger.size;
-                        }
-                        if (cumulative >= entryCaps.maxCumulativePerSession) {
-                            return await capRefusal("delegation.session_cap", `this session tree has already launched ${cumulative} background agents in its retained window — the cumulative cap (${entryCaps.maxCumulativePerSession}; RunnerDeps.delegationEntryCaps.maxCumulativePerSession) refuses more. Continue an existing agent (SendMessage) instead of launching new ones.`);
-                        }
+                        return errorResult(`Sub-agent not started in background: ${admission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: admission.refusal.code, code: admission.refusal.code });
                     }
                 }
                 const settlementSeat = ctx.delegationSettlement?.();
@@ -2770,13 +2919,8 @@ 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" } };
                 }
-                if (capLedgerKey !== undefined && reviveRow === undefined)
-                    delegationEntryLedger(bg.registry, capLedgerKey).add(taskId);
-                if (capLedgerKey !== undefined) {
-                    bindDelegationLedgerKeyStore(bg.registry, capLedgerKey, bg.agentStore);
-                    armDelegationLedgerLifecycle(bg.registry);
-                    sweepDelegationLedgerRound(bg.registry, 3);
-                }
+                if (capLedgerKey !== undefined)
+                    chargeDelegationEntryHandle(bg.registry, capLedgerKey, bg.agentStore, reviveRow === undefined ? taskId : undefined);
                 childInternals.peerSelfRef?.addAxis("h", taskId);
                 if (agentName !== undefined) {
                     recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
@@ -3411,49 +3555,66 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 };
             }
             let child;
+            const syncEntryGate = await openEntryGate();
+            if (ctx.signal?.aborted) {
+                await cancelObserver();
+                const wt = await finishWorktree();
+                return spawnAbortedResult(wt);
+            }
+            const syncAdmission = syncEntryGate.admit("local");
+            if (!syncAdmission.admitted) {
+                await cancelObserver();
+                const wt = await finishWorktree();
+                return errorResult(`Sub-agent not started: ${syncAdmission.refusal.text}${wt ? `\n${wt}` : ""}`, { error: syncAdmission.refusal.code, code: syncAdmission.refusal.code });
+            }
             const syncStartedAt = Date.now();
             let retainEntry;
-            if (ctx.onSubagentSpawn || observerPairing) {
-                retainEntry = ctx.onSubagentSpawn ? await tryRetainChild(ctx.subagentRetain) : undefined;
-                if (retainEntry)
-                    stepRecorder.lockTo(retainEntry.childSessionId);
-                const stream = opts.runner.runTaskStream({ ...buildChildSpec(ctx.signal), ...(retainEntry ? { sessionId: retainEntry.childSessionId } : {}) }, undefined, childInternals);
-                observedSteerRef.steer = (text, o) => stream.steer(text, o);
-                let settleResolve;
-                const settled = new Promise((r) => { settleResolve = r; });
-                if (ctx.onSubagentSpawn) {
-                    const resume = createSubagentResume({
-                        ledger: ctx.subagentRetain,
-                        parentToolCallId: ctx.toolCallId,
-                        runner: opts.runner,
-                        ...(opts.background?.notify ? { notify: opts.background.notify } : {}),
-                        sink: ctx.onSubagentSpawn,
-                        ...(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,
-                        ...(retainEntry ? { childSessionId: retainEntry.childSessionId } : {}),
-                    })), "subagent.onSubagentSpawn");
-                }
-                try {
-                    for await (const ev of stream)
-                        observerTap?.record(ev);
-                    child = await stream.result();
-                }
-                catch (e) {
-                    await settleObserver("failed");
-                    throw e;
+            try {
+                if (ctx.onSubagentSpawn || observerPairing) {
+                    retainEntry = ctx.onSubagentSpawn ? await tryRetainChild(ctx.subagentRetain) : undefined;
+                    if (retainEntry)
+                        stepRecorder.lockTo(retainEntry.childSessionId);
+                    const stream = opts.runner.runTaskStream({ ...buildChildSpec(ctx.signal), ...(retainEntry ? { sessionId: retainEntry.childSessionId } : {}) }, undefined, childInternals);
+                    observedSteerRef.steer = (text, o) => stream.steer(text, o);
+                    let settleResolve;
+                    const settled = new Promise((r) => { settleResolve = r; });
+                    if (ctx.onSubagentSpawn) {
+                        const resume = createSubagentResume({
+                            ledger: ctx.subagentRetain,
+                            parentToolCallId: ctx.toolCallId,
+                            runner: opts.runner,
+                            ...(opts.background?.notify ? { notify: opts.background.notify } : {}),
+                            sink: ctx.onSubagentSpawn,
+                            ...(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,
+                            ...(retainEntry ? { childSessionId: retainEntry.childSessionId } : {}),
+                        })), "subagent.onSubagentSpawn");
+                    }
+                    try {
+                        for await (const ev of stream)
+                            observerTap?.record(ev);
+                        child = await stream.result();
+                    }
+                    catch (e) {
+                        await settleObserver("failed");
+                        throw e;
+                    }
+                    finally {
+                        settleResolve();
+                        ctx.subagentRetain?.markSettled(ctx.toolCallId);
+                    }
                 }
-                finally {
-                    settleResolve();
-                    ctx.subagentRetain?.markSettled(ctx.toolCallId);
+                else {
+                    child = await opts.runner.runTask(buildChildSpec(ctx.signal), childInternals);
                 }
             }
-            else {
-                child = await opts.runner.runTask(buildChildSpec(ctx.signal), childInternals);
+            finally {
+                syncAdmission.release();
             }
             await settleObserver(child.status);
             const handbackWarning = await reviewHandback({

package/dist/agents/team.d.ts

@@ -1,5 +1,5 @@
 import type { Runner } from "../core/runner/runtask.js";
-import type { McpServerSpec, ModelRef, ModelRole, TaskResult, ToolSpec } from "../core/types.js";
+import type { McpServerSpec, ModelRef, ModelRole, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
 export interface TeamMember {
     /** The member's role / specialty, e.g. "安全评审" or "performance". */
     role: string;
@@ -99,6 +99,15 @@ export interface TeamDiscussionOptions {
         denyTools?: string[];
         mcp?: McpServerSpec[];
     };
+    /**
+     * Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders} (forwarded into every member /
+     * summary / synthesizer run, which resolve it against their own resolved models). Without this
+     * seat a team whose member/synthesizer models live on per-model-credential routes had NO way to
+     * carry the resolver: every nested run fell to the brain's construction-time credential, which the
+     * key↔URL pairing gate refuses off the deployment root — the teacher/verify delegation family
+     * carries the same seat for the same reason.
+     */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
     /** Progress callback. */
     onEvent?: (e: TeamEvent) => void;
     /**

package/dist/agents/team.js

@@ -117,6 +117,7 @@ export async function runTeamDiscussion(opts) {
                 limits: memberLimits,
                 signal: opts.signal,
                 ...(opts.principal !== undefined ? { principal: opts.principal } : {}),
+                ...(opts.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.getApiKeyAndHeaders } : {}),
             }, { isDelegatedChild: true });
             tokens += res.stats.tokens + (res.stats.nested?.tokens ?? 0);
             turns += res.stats.turns + (res.stats.nested?.turns ?? 0);

package/dist/brain/anthropic.js

@@ -5,7 +5,8 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders, takeHeaderCasefold } from "./request-params.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
@@ -234,7 +235,17 @@ export function createAnthropicBrain(config = {}) {
             httpLabel: "anthropic",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const apiKey = options?.apiKey ?? config.apiKey;
+                const routeCredential = resolveRouteCredential({
+                    optionsApiKey: options?.apiKey,
+                    optionsHeaders: options?.headers,
+                    modelHeaders: model.headers,
+                    configApiKey: config.apiKey,
+                    configHeaders: config.headers,
+                });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                if (!routeVerdict.ok)
+                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const apiKey = routeCredential.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "https://api.anthropic.com").replace(/\/+$/, "");
                 const nonEmptyBlocks = context.systemBlocks?.filter((b) => b.text.length > 0);
                 const system = nonEmptyBlocks?.length
@@ -302,8 +313,7 @@ export function createAnthropicBrain(config = {}) {
                     betas.push("interleaved-thinking-2025-05-14");
                 }
                 const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                if (options?.apiKey !== undefined)
-                    stripAuthHeaders(headers);
+                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
                 if (betas.length > 0) {
                     const existing = (takeHeaderCasefold(headers, "anthropic-beta") ?? "").split(",").map((b) => b.trim()).filter(Boolean);
                     for (const beta of betas) {
@@ -680,5 +690,5 @@ export function createAnthropicBrain(config = {}) {
             },
         });
     };
-    return { stream };
+    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
 }

package/dist/brain/circuit-breaker.js

@@ -153,5 +153,6 @@ export function createCircuitBreakerBrain(inner, opts = {}) {
         })();
         return out;
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => inner.adjudicateRoute?.(model, perModelAuth);
+    return { stream, adjudicateRoute };
 }

package/dist/brain/degrading.js

@@ -144,6 +144,8 @@ export function createDegradingBrain(opts) {
                         break;
                     if (hop.model.id === failedModelId)
                         continue;
+                    if (hop.brain.adjudicateRoute?.(hop.model)?.ok === false)
+                        continue;
                     chainPath.push(hop.model.id);
                     degradeInfo = {
                         from: model.id,
@@ -182,5 +184,6 @@ export function createDegradingBrain(opts) {
         })();
         return out;
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => opts.primary.adjudicateRoute?.(model, perModelAuth);
+    return { stream, adjudicateRoute };
 }

package/dist/brain/failover.js

@@ -82,5 +82,20 @@ export function createFailoverBrain(brains) {
         })();
         return out;
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => {
+        let firstRefusal;
+        let sawUnjudged = false;
+        for (const b of brains) {
+            const verdict = b.adjudicateRoute?.(model, perModelAuth);
+            if (verdict === undefined) {
+                sawUnjudged = true;
+                continue;
+            }
+            if (verdict.ok)
+                return verdict;
+            firstRefusal ??= verdict;
+        }
+        return sawUnjudged ? undefined : firstRefusal;
+    };
+    return { stream, adjudicateRoute };
 }

package/dist/brain/open-responses.js

@@ -5,7 +5,8 @@ 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, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
@@ -228,7 +229,17 @@ export function createOpenResponsesBrain(config = {}) {
             httpLabel: "responses",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const apiKey = options?.apiKey ?? config.apiKey;
+                const routeCredential = resolveRouteCredential({
+                    optionsApiKey: options?.apiKey,
+                    optionsHeaders: options?.headers,
+                    modelHeaders: model.headers,
+                    configApiKey: config.apiKey,
+                    configHeaders: config.headers,
+                });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                if (!routeVerdict.ok)
+                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const apiKey = routeCredential.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
                 if (!root) {
                     throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
@@ -265,8 +276,7 @@ export function createOpenResponsesBrain(config = {}) {
                 if (effort !== undefined)
                     body.reasoning = { effort };
                 const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                if (options?.apiKey !== undefined)
-                    stripAuthHeaders(headers);
+                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
@@ -738,5 +748,5 @@ export function createOpenResponsesBrain(config = {}) {
             },
         });
     };
-    return { stream };
+    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
 }