@nanmicoder/dsh-agent-teams 0.1.22 → 0.1.24-rc.1

package/lib/members.js

@@ -16,9 +16,10 @@ import { installModelSelection } from '@deepseek-ai/dsh-agent';
 import { foldSubagentDescriptor } from '@deepseek-ai/dsh-subagent';
 import { createUserMessage, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { join } from 'node:path';
-import { guardSubagentDelivery, installContinuableMemberSetup, memberToolFilter, queueMemberPrompt, restrictableToolNames, startMemberWithLenientFilter, steerMemberPrompt, sessionOwnEvents } from "./harness-compat.js";
+import { guardSubagentCreation, startMember, usesManagedActivations, guardSubagentDelivery, installContinuableMemberSetup, memberToolFilter, queueMemberPrompt, restrictableToolNames, startMemberWithLenientFilter, steerMemberPrompt, sessionOwnEvents } from "./harness-compat.js";
 import { markMailboxDelivered, appendMailbox, CAPTAIN_KEY, createMessage, readRetiredMemberIds, readTeamSync, readTeam, releaseMailboxDelivery, withTeamLock, writeTeam } from "./state.js";
 import { mailboxPrompt } from "./mailbox.js";
+import { nearestLiveLead } from "./lineage.js";
 import { appendTeamEvent, captainSessionOf } from "./events.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
@@ -32,6 +33,46 @@ export const PERSONA_PROTOCOL_MAX_CHARS = 400;
 function brandedSessionId(value) {
     return value;
 }
+/**
+ * Compose one member route from request, plugin configuration and the captain
+ * session, without performing any I/O. This is the single place where the
+ * precedence between the captain's route and a configured member default is
+ * decided, so a configured model can never be silently paired with whichever
+ * provider the captain happens to sit on (issue #189).
+ *
+ * Precedence: explicit request > plugin configuration > captain session. Model
+ * ids are used verbatim: a `/` inside a model id is part of that id and is
+ * never treated as a provider separator.
+ *
+ * `derivedProvider` is true only for a bare configured `memberModel` with no
+ * provider anywhere, which is the one shape whose owner must come from the
+ * provider catalogs.
+ * @param request - the captain-supplied and plugin-configured route halves.
+ * @param captain - the captain's current session route.
+ * @returns the composed route, or `undefined` when a half cannot be determined.
+ */
+export function composeMemberRoute(request, captain) {
+    const explicitProvider = request.provider?.trim();
+    const explicitModel = request.model?.trim();
+    const configuredModel = request.defaultModel?.trim();
+    const configuredProvider = request.defaultProvider?.trim();
+    if (explicitProvider !== undefined && explicitModel === undefined)
+        return undefined;
+    if (explicitProvider === '' || explicitModel === '' || configuredModel === '' || configuredProvider === '')
+        return undefined;
+    const providerValue = explicitProvider ?? configuredProvider ?? captain.provider;
+    const providerSource = explicitProvider !== undefined ? 'request' : configuredProvider !== undefined ? 'config' : 'captain';
+    const modelValue = explicitModel ?? configuredModel ?? captain.model;
+    const modelSource = explicitModel !== undefined ? 'request' : configuredModel !== undefined ? 'config' : 'captain';
+    return {
+        provider: { value: providerValue, source: providerSource },
+        model: { value: modelValue, source: modelSource },
+        // A named provider is authoritative, and a named model keeps the route the
+        // caller asked for. Only a model-only plugin default is allowed to have its
+        // owner discovered from the catalogs.
+        derivedProvider: providerSource === 'captain' && modelSource === 'config',
+    };
+}
 /**
  * Validate a resolved roster against every provider catalog before any child
  * session is created. Catalogs are advisory when empty (some adapters accept
@@ -80,6 +121,88 @@ export function steerCaptainReport(captain, from, content, receipt) {
         return false;
     }
 }
+/**
+ * Classify a final member turn failure against the durable record. Pure, so the
+ * policy is testable without a lock or a Harness.
+ *
+ * A failure may only mutate the attempt the plugin actually observed. When that
+ * attempt is gone — the member moved on to newer work, the task was
+ * reassigned to a newer attempt, or the member generation was replaced — the
+ * late error carries no authority and stays silent. When the failure belongs to
+ * the current generation but its work already settled, the task and member are
+ * left exactly as they are and only a durable captain note is added: otherwise
+ * an operator cannot tell a clean run from one whose member's last turn died
+ * (429, auth failure, crash) after the delivery landed (issue #205).
+ * @param observed - the live member/task capability captured at the error event.
+ * @param current - the current durable member record and open task, if any.
+ * @returns the disposition for this failure.
+ */
+export function classifyMemberFailure(observed, current) {
+    const member = current.member;
+    // Only the exact member generation observed at the error event may report it.
+    // A replaced generation (same name, new session id) or a member record that is
+    // gone cannot be failed by that child's late error.
+    if (member === undefined || member.id !== observed.memberId)
+        return 'ignored';
+    const task = current.task;
+    if (task === undefined) {
+        // No open attempt is owned by this generation any more, so nothing here may
+        // be mutated — but the failure itself must still be recorded. `working` is
+        // NOT evidence of newer work: `syncMemberStatus` writes it as soon as the
+        // turn runs, while a task completed earlier in that same turn leaves no open
+        // attempt behind (the reporter's run A). Only a *concrete* superseded open
+        // attempt — the branch below — or a replaced generation may stay silent.
+        return 'noted_settled';
+    }
+    if (task.id !== observed.task?.id || task.attemptId !== observed.task?.attemptId
+        || task.attempt !== observed.task?.attempt)
+        return 'ignored';
+    return 'failed_attempt';
+}
+/**
+ * The surviving durable record of the capability observed at the error event,
+ * or `undefined` when there is nothing honest to say about it.
+ *
+ * A task is only described as *settled* when its durable status is terminal
+ * (`completed`/`failed`/`cancelled`). A non-terminal record — for example a task
+ * that was claimed and then unclaimed or reassigned while the error was queued —
+ * must fall back to the plain "no open attempt" wording instead of implying a
+ * delivery landed.
+ */
+export function settledTaskRecord(observed, tasks) {
+    if (observed === undefined)
+        return undefined;
+    const record = tasks.find(candidate => candidate.id === observed.id);
+    if (record === undefined)
+        return undefined;
+    return TERMINAL_TASK_STATUSES.includes(record.status) ? record : undefined;
+}
+/**
+ * Build the durable captain note for one recorded failure. Pure, so the wording
+ * boundaries are testable without a lock or a Harness.
+ * @param memberName - the member that failed.
+ * @param summary - the failure message plus its code.
+ * @param disposition - what the failure was allowed to do.
+ * @param task - the open attempt that was failed, when there was one.
+ * @param settledRecord - the terminal record of the observed task, when it exists.
+ * @returns the exact message the captain will read.
+ */
+export function memberFailureMessage(memberName, summary, disposition, task, settledRecord) {
+    const head = `Member "${memberName}" hit an unrecoverable turn failure: ${summary}.`;
+    if (disposition === 'failed_attempt' && task !== undefined) {
+        return `${head} Task ${task.id} ("${task.subject}") was marked failed; reassign it or retry when ready.`;
+    }
+    if (settledRecord === undefined) {
+        return disposition === 'noted_settled'
+            ? `${head} No open attempt was owned; no task state was changed.`
+            : `${head} No open attempt was owned.`;
+    }
+    // Only a completed record supports a claim about delivered work. A failed or
+    // cancelled record is described by its actual closed state.
+    return settledRecord.status === 'completed'
+        ? `${head} Task ${settledRecord.id} ("${settledRecord.subject}") had already completed; its state and output were left unchanged. This member's last turn died after its work landed.`
+        : `${head} Task ${settledRecord.id} ("${settledRecord.subject}") was already closed as ${settledRecord.status}; its record was left unchanged. This member's last turn died after that task had closed.`;
+}
 /** Record a final turn failure, never an intermediate request retry. */
 export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName, failure, fallbackSession, observed) {
     const summary = `${failure.message} (code ${failure.code})`;
@@ -88,35 +211,42 @@ export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName,
         const team = await readTeam(stateRoot, teamId);
         if (team === undefined || team.halted === true || team.captainSessionId !== observed.captainSessionId)
             return;
-        const member = team.members.find(candidate => candidate.name === memberName
-            && candidate.id === observed.memberId && candidate.status !== 'removed');
-        if (member === undefined)
-            return;
+        const member = team.members.find(candidate => candidate.name === memberName && candidate.id === observed.memberId);
         const task = team.tasks.find(candidate => candidate.assignee === memberName
             && (candidate.status === 'claimed' || candidate.status === 'in_progress'));
         // A reassign, completion, or recreated member may win the lock while the
         // final error is queued. Only the capability observed at that event may fail.
-        if (task?.id !== observed.task?.id || task?.attemptId !== observed.task?.attemptId
-            || task?.attempt !== observed.task?.attempt)
-            return;
-        if (task === undefined && member.status !== 'working')
+        const disposition = classifyMemberFailure(observed, {
+            member,
+            task,
+            observedRecord: observed.task === undefined
+                ? undefined
+                : team.tasks.find(candidate => candidate.id === observed.task.id),
+        });
+        if (disposition === 'ignored')
             return;
-        if (task !== undefined) {
+        if (disposition === 'failed_attempt' && task !== undefined) {
             task.status = 'failed';
             task.output = summary;
             task.updatedAt = Date.now();
         }
-        if (ctx.agents.get(brandedSessionId(member.id))?.status !== 'running')
+        if (member !== undefined && ctx.agents.get(brandedSessionId(member.id))?.status !== 'running')
             member.status = 'idle';
+        // Only a terminal record of the observed task may be described, and only a
+        // completed one supports a claim about delivered work. Anything else — a
+        // never-assigned member, or a record left pending/claimed while the error was
+        // queued — gets the plain "no open attempt" wording.
+        const settledRecord = disposition === 'noted_settled'
+            ? settledTaskRecord(observed.task, team.tasks)
+            : undefined;
         const message = {
-            ...createMessage(memberName, CAPTAIN_KEY, task === undefined
-                ? `Member "${memberName}" hit an unrecoverable turn failure: ${summary}. No open attempt was owned.`
-                : `Member "${memberName}" hit an unrecoverable turn failure: ${summary}. Task ${task.id} ("${task.subject}") was marked failed; reassign it or retry when ready.`),
+            ...createMessage(memberName, CAPTAIN_KEY, memberFailureMessage(memberName, summary, disposition, task, settledRecord)),
             deliveryClaimedAt: Date.now(),
         };
-        await writeTeam(stateRoot, team);
+        if (disposition === 'failed_attempt')
+            await writeTeam(stateRoot, team);
         await appendMailbox(stateRoot, team.id, CAPTAIN_KEY, message);
-        if (task !== undefined) {
+        if (disposition === 'failed_attempt' && task !== undefined) {
             appendTeamEvent(ctx, captainSessionOf(ctx, team.captainSessionId, fallbackSession), 'agent-teams/task-updated', {
                 teamId, taskId: task.id, status: task.status, assignee: memberName, output: task.output,
             });
@@ -135,7 +265,7 @@ export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName,
         return false;
     // Use the same lease/acknowledgment contract as send_message, outside the
     // team lock: steering can synchronously start another agent turn.
-    const captain = ctx.agents.get(brandedSessionId(prepared.captainSessionId));
+    const captain = nearestLiveLead(ctx, { captainSessionId: prepared.captainSessionId });
     const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content, mailboxPrompt(teamId, CAPTAIN_KEY, [prepared.message]));
     await withTeamLock(lockKey, () => delivered
         ? markMailboxDelivered(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id])
@@ -194,11 +324,21 @@ function modelSelection(selection) {
  * An explicit effort overrides either policy; the sentinel "default" also
  * selects the target model's default. The final effort is validated against
  * the target model before a child is created.
+ *
+ * A configured `memberModel` is a route preference, not a blind model-id
+ * override: it is paired with `memberLlmProvider` (or its own `provider/model`
+ * form) when configured, and when only a bare model id is configured it is
+ * adopted by the captain's provider only if that provider actually advertises
+ * it. Otherwise the catalog decides: exactly one advertising provider wins,
+ * none or several produce an actionable error listing them (issue #189). A
+ * provider the caller *named* — explicitly or via configuration — is never
+ * silently switched away from.
  */
 export async function resolveMemberLlmSelection(ctx, captain, request, signal) {
     const explicitProvider = request.provider?.trim();
     const explicitModel = request.model?.trim();
     const defaultModel = request.defaultModel?.trim();
+    const defaultProvider = request.defaultProvider?.trim();
     const explicitEffort = request.reasoningEffort?.trim();
     const fallback = request.fallback;
     if (request.provider !== undefined && explicitProvider === '') {
@@ -210,24 +350,47 @@ export async function resolveMemberLlmSelection(ctx, captain, request, signal) {
     if (request.defaultModel !== undefined && defaultModel === '') {
         throw new Error('configured memberModel must not be empty');
     }
+    if (request.defaultProvider !== undefined && defaultProvider === '') {
+        throw new Error('configured memberLlmProvider must not be empty');
+    }
     if (request.reasoningEffort !== undefined && explicitEffort === '') {
         throw new Error('member reasoning effort must not be empty');
     }
+    // An explicit provider needs an explicit model; `memberModel` is used
+    // verbatim, so a `/` inside a model id is never a provider separator.
     if (explicitProvider !== undefined && explicitModel === undefined) {
         throw new Error('an explicit member LLM provider requires an explicit member model');
     }
     const current = captain.session.requestHeader()?.config;
     const currentProvider = current?.provider ?? captain.options.provider;
     const currentModel = current?.model ?? captain.options.model;
-    const provider = explicitProvider ?? currentProvider;
-    const model = explicitModel ?? defaultModel ?? currentModel;
-    if (provider === undefined || model === undefined) {
+    if (currentProvider === undefined || currentModel === undefined) {
+        throw new Error('cannot resolve the member LLM route from the current captain session');
+    }
+    // The plugin-wide default only applies where the caller did not choose a
+    // model. `request.defaultModel` belongs to the plugin configuration; a
+    // request-level `model` is a user choice and is never re-routed.
+    const composed = composeMemberRoute({
+        provider: request.provider,
+        model: request.model,
+        defaultModel: defaultModel,
+        defaultProvider: defaultProvider,
+    }, { provider: currentProvider, model: currentModel });
+    if (composed === undefined) {
         throw new Error('cannot resolve the member LLM route from the current captain session');
     }
+    // Only a bare configured `memberModel` may have its owner resolved from the
+    // catalogs. A named provider (explicit or configured) is authoritative — a
+    // model it does not advertise is a hard error, never a silent switch — and a
+    // model the caller named keeps that caller's route.
+    const provider = composed.derivedProvider
+        ? await resolveMemberModelOwner(ctx, currentProvider, composed.model.value, signal)
+        : composed.provider.value;
     // Effort ids belong to one exact provider/model capability. Preserve the
     // captain's effort only on the same route; a changed route must resolve its
     // own default. Explicit effort still wins, while "default" forces that
     // target-default behavior even when the route did not change.
+    const model = composed.model.value;
     const sameRoute = provider === currentProvider && model === currentModel;
     const reasoningEffort = explicitEffort === undefined
         ? sameRoute
@@ -236,13 +399,19 @@ export async function resolveMemberLlmSelection(ctx, captain, request, signal) {
         : explicitEffort === 'default'
             ? undefined
             : ReasoningEffortId(explicitEffort);
-    const resolved = await ctx.llm.resolveCallConfig({
-        provider,
-        model,
-        ...reasoningEffort === undefined
-            ? {}
-            : { reasoningEffort },
-    }, signal);
+    let resolved;
+    try {
+        resolved = await ctx.llm.resolveCallConfig({
+            provider,
+            model,
+            ...reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort },
+        }, signal);
+    }
+    catch (error) {
+        throw new Error(describeMemberRouteFailure(provider, model, error), { cause: error });
+    }
     return {
         provider: resolved.provider,
         model: resolved.model,
@@ -252,6 +421,54 @@ export async function resolveMemberLlmSelection(ctx, captain, request, signal) {
         ...fallback === undefined ? {} : { fallback },
     };
 }
+/**
+ * Pick the provider that owns a configured bare model id when the captain's
+ * provider does not advertise it. Only an unambiguous owner is accepted: zero
+ * advertising providers and several advertising providers both fail with the
+ * catalog, because guessing between real providers changes which account and
+ * quota the user's members run on (issue #189).
+ * @returns the resolved provider id.
+ */
+async function resolveMemberModelOwner(ctx, captainProvider, model, signal) {
+    // Enumeration is optional: an adapter that cannot list its providers must not
+    // turn a resolvable route into a crash. Such a route keeps the captain's
+    // provider and lets the durable adapter report the real failure.
+    const listProviders = ctx.llm.listProviders;
+    if (typeof listProviders !== 'function')
+        return captainProvider;
+    const owners = [];
+    for (const provider of listProviders.call(ctx.llm)) {
+        if (signal?.aborted === true)
+            throw signal.reason ?? new Error('member model resolution was cancelled');
+        const catalog = await ctx.llm.listModels(provider.id);
+        if (catalog.length === 0)
+            continue;
+        if (catalog.some((candidate) => candidate.id === model))
+            owners.push(provider.id);
+    }
+    if (owners.includes(captainProvider))
+        return captainProvider;
+    if (owners.length === 1)
+        return owners[0];
+    if (owners.length === 0) {
+        throw new Error(`no configured provider advertises the member model "${model}".`
+            + ` The captain's provider "${captainProvider}" does not serve it either.`
+            + ' Name the owner explicitly with memberLlmProvider, or pass provider + model to agent_teams_add_member.');
+    }
+    throw new Error(`the member model "${model}" is advertised by ${owners.length} providers (${owners.join(', ')}),`
+        + ' so its owner is ambiguous. Name it explicitly with memberLlmProvider, or pass provider + model to agent_teams_add_member.');
+}
+/** Turn a raw adapter failure into an actionable, route-naming error. */
+function describeMemberRouteFailure(provider, model, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : '';
+    const hint = code === 'UNKNOWN_MODEL' || code === 'NO_ADAPTER' || code === 'INVALID_CONFIG'
+        ? ` The member route was composed from the captain's session and the plugin configuration;`
+            + ' set memberLlmProvider when the configured member model belongs to a'
+            + " different provider than the captain's session."
+        : '';
+    return `cannot use the member LLM route "${provider}/${model}": ${message}${code === '' ? '' : ` (code ${code})`}.${hint}`;
+}
 /**
  * Install the member selection bridge for every fresh or cold-resumed
  * continuable child. Fresh creation reads the pending in-memory selection;
@@ -261,6 +478,7 @@ export async function resolveMemberLlmSelection(ctx, captain, request, signal) {
  */
 export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
     const pending = new Map();
+    const pendingSetup = new Map();
     installContinuableMemberSetup(ctx, (childCtx, child) => {
         const descriptor = foldSubagentDescriptor(sessionOwnEvents(child.session));
         if (descriptor?.mode !== 'continuable' || !descriptor.label.startsWith(MEMBER_LABEL_PREFIX)) {
@@ -293,11 +511,47 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
                 return { kind: 'reject' };
             return next();
         });
+        // New activations no longer persist persona/toolFilter in host descriptors.
+        // Install them before the first request, and restore the exact saved values
+        // after a cold resume. Historical descriptors remain owned by Harness.
+        const savedTeam = pending.has(key) ? undefined : readTeamSync(stateRoot, teamId);
+        const savedMember = savedTeam?.captainSessionId === parentSessionId
+            ? savedTeam.members.find(member => member.id === child.id && member.name === memberName)
+            : undefined;
+        const setup = pendingSetup.get(key) ?? savedMember?.runtimeSetup;
+        if (usesManagedActivations(ctx.subagents) && savedMember !== undefined
+            && setup === undefined && descriptor.toolFilter === undefined) {
+            disposeAdmission();
+            throw new Error('agent-teams: saved member runtime setup is missing; refusing an unrestricted resume');
+        }
+        let disposeSetup = () => undefined;
+        if (usesManagedActivations(ctx.subagents) && setup !== undefined) {
+            try {
+                const stopFilter = childCtx.tools.restrict(setup.toolFilter);
+                try {
+                    const stopPersona = childCtx.systemPrompt.section({
+                        name: 'deployment:persona-prefix',
+                        order: childCtx.systemPrompt.getSectionOrder('DEPLOYMENT_PERSONA_PREFIX'),
+                        text: setup.persona,
+                    });
+                    disposeSetup = () => { stopPersona(); stopFilter(); };
+                }
+                catch (error) {
+                    stopFilter();
+                    throw error;
+                }
+            }
+            catch (error) {
+                disposeAdmission();
+                throw error;
+            }
+        }
+        const cleanupAdmission = () => { disposeSetup(); disposeAdmission(); };
         let selection = pending.get(key);
         if (selection === undefined) {
             const team = readTeamSync(stateRoot, teamId);
             if (team?.captainSessionId !== parentSessionId)
-                return disposeAdmission;
+                return cleanupAdmission;
             const durableMember = team.members.find(member => member.name === memberName);
             selection = selectionFromMember(durableMember);
             if (selection !== undefined && (descriptor.agentProvider !== durableMember?.provider || descriptor.agentModel !== durableMember?.model)) {
@@ -354,7 +608,7 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
         });
         // Legacy teams still need failure reporting even without a saved route.
         if (selection === undefined)
-            return () => { disposeFailure(); disposeAdmission(); };
+            return () => { disposeFailure(); cleanupAdmission(); };
         const selectionRef = { current: modelSelection(selection), assembled: undefined };
         const disposeSelection = installModelSelection(childCtx, selectionRef);
         const fallback = selection.fallback;
@@ -384,7 +638,7 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
             disposeFallback();
             disposeSelection();
             disposeFailure();
-            disposeAdmission();
+            cleanupAdmission();
         };
     });
     return {
@@ -394,17 +648,20 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
             return parent !== undefined && descriptor?.mode === 'continuable'
                 && pending.has(pendingSelectionKey(parent, descriptor.label));
         },
-        async withPending(parentSessionId, label, selection, operation) {
+        async withPending(parentSessionId, label, selection, operation, setup) {
             const key = pendingSelectionKey(parentSessionId, label);
             if (pending.has(key)) {
                 throw new Error(`member model selection is already pending for "${label}"`);
             }
             pending.set(key, selection);
+            if (setup !== undefined)
+                pendingSetup.set(key, setup);
             try {
                 return await operation();
             }
             finally {
                 pending.delete(key);
+                pendingSetup.delete(key);
             }
         },
     };
@@ -491,8 +748,16 @@ Do not start work until the scheduler or captain assigns a task in this turn.`;
  * @param member - the member draft whose `id` is filled on success.
  * @param stateDir - configured state directory (for the persona).
  * @param signal - caller cancellation, forwarded to the start.
+ * @param initialPrompt - first turn text; the welcome message when omitted.
+ * @param resolvedFilter - the member's effective tool filter (a selected
+ *   policy, or the legacy captain-only filter when the member has none). The
+ *   caller resolves it so `spawnMember` forwards exactly one immutable filter
+ *   to `startContinuable`.
+ * @param relaxableDeny - deny names the lenient retry may drop for this
+ *   member; the caller narrows it for a policy member so a name the owner
+ *   declared is never silently removed.
  */
-export async function spawnMember(ctx, config, selections, llmSelection, captain, team, member, stateDir, signal, initialPrompt) {
+export async function spawnMember(ctx, config, selections, llmSelection, captain, team, member, stateDir, signal, initialPrompt, resolvedFilter, relaxableDeny) {
     // Fail loud at the first use: provider registration is a sibling plugin's
     // effect and may settle after this plugin mounts. Capability checks here
     // mirror what startContinuable would reject, with an actionable error.
@@ -504,40 +769,59 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
     if (provider.prepareContinuable === undefined) {
         throw new Error(`agent-teams: provider "${config.provider}" does not support continuable members`);
     }
-    if (!provider.capabilities.persona) {
+    const legacyCapabilities = provider.capabilities;
+    if (!usesManagedActivations(ctx.subagents) && !legacyCapabilities.persona) {
         throw new Error(`agent-teams: provider "${config.provider}" cannot apply a member persona`);
     }
-    if (!provider.capabilities.toolFilter) {
+    if (!usesManagedActivations(ctx.subagents) && !legacyCapabilities.toolFilter) {
         throw new Error(`agent-teams: provider "${config.provider}" cannot restrict captain-only tools for members`);
     }
     const label = `${MEMBER_LABEL_PREFIX}${team.id}:${member.name}`;
-    const start = await selections.withPending(captain.id, label, llmSelection, () => (startMemberWithLenientFilter(toolFilter => ctx.subagents.startContinuable({
-        provider: config.provider,
-        label,
-        request: {
-            prompt: [{ type: 'text', text: initialPrompt ?? memberWelcome(team, member.name) }],
-            parent: captain,
-            persona: memberPersona(team, member, stateDir, config.executionPrompt),
-            // Depth deny entries name host tools; resolve them against the
-            // running host's registry so a renamed delegation tool cannot abort
-            // the spawn (see memberToolFilter). Depth is still enforced by the
-            // parent-chain guard installed at plugin mount. A filter the host
-            // still rejects is retried without the names it reported.
-            toolFilter,
-            agentOptions: {
-                provider: llmSelection.provider,
-                model: llmSelection.model,
-                ...llmSelection.reasoningEffort === undefined
-                    ? {}
-                    : { reasoningEffort: ReasoningEffortId(llmSelection.reasoningEffort) },
+    // The legacy filter of a member without a configured tool policy: the
+    // captain-only deny list plus the depth entries this host registers.
+    const requestedFilter = resolvedFilter ?? memberToolFilter(config.maxDepth, restrictableToolNames(captain));
+    // The lenient retry may drop names this host reports unknown; keep the exact
+    // filter the host accepted for the durable member setup.
+    let acceptedFilter = requestedFilter;
+    const start = await startMemberWithLenientFilter(toolFilter => {
+        acceptedFilter = toolFilter;
+        const setup = { persona: memberPersona(team, member, stateDir, config.executionPrompt), toolFilter };
+        return selections.withPending(captain.id, label, llmSelection, () => startMember(ctx.subagents, {
+            provider: config.provider,
+            label,
+            request: {
+                prompt: [{ type: 'text', text: initialPrompt ?? memberWelcome(team, member.name) }],
+                parent: captain,
+                persona: memberPersona(team, member, stateDir, config.executionPrompt),
+                // Depth deny entries name host tools; resolve them against the
+                // running host's registry so a renamed delegation tool cannot abort
+                // the spawn (see memberToolFilter). Depth is still enforced by the
+                // parent-chain guard installed at plugin mount. A filter the host
+                // still rejects is retried without the names it reported.
+                toolFilter,
+                agentOptions: {
+                    provider: llmSelection.provider,
+                    model: llmSelection.model,
+                    ...llmSelection.reasoningEffort === undefined
+                        ? {}
+                        : { reasoningEffort: ReasoningEffortId(llmSelection.reasoningEffort) },
+                },
+                // Harness request.maxDepth caps the absolute depth of THIS creation;
+                // it is not inherited by later delegations. The guard below enforces
+                // the configured member-relative descendant budget instead.
             },
-            // Harness request.maxDepth caps the absolute depth of THIS creation;
-            // it is not inherited by later delegations. The guard below enforces
-            // the configured member-relative descendant budget instead.
-        },
-        signal,
-    }), memberToolFilter(config.maxDepth, restrictableToolNames(captain)))));
+            signal,
+        }), setup);
+    }, requestedFilter, relaxableDeny);
     member.id = start.childId;
+    if (usesManagedActivations(ctx.subagents)) {
+        member.runtimeSetup = { persona: memberPersona(team, member, stateDir, config.executionPrompt), toolFilter: acceptedFilter };
+    }
+    // Only a policy member carries a persisted filter snapshot; a member without
+    // a policy keeps its public record shape. Legacy descriptors or runtimeSetup
+    // restore the filter on cold resume, depending on the host generation.
+    if (member.toolFilter !== undefined)
+        member.toolFilter = { ...acceptedFilter };
 }
 /**
  * Deliver one message to a member as its next FIFO turn. Best effort: a
@@ -605,7 +889,6 @@ export function installRetiredMemberGuard(ctx, stateDir) {
 }
 /** Bound all descendant creation, including renamed tools and code-runtime calls. */
 export function installMemberDelegationGuard(ctx, stateDir, maxDepth) {
-    const runtime = ctx.subagents;
     let active = true;
     const check = (parent) => {
         if (!active)
@@ -617,7 +900,16 @@ export function installMemberDelegationGuard(ctx, stateDir, maxDepth) {
             if (descriptor?.label?.startsWith(MEMBER_LABEL_PREFIX)) {
                 const identity = descriptor.label.slice(MEMBER_LABEL_PREFIX.length);
                 const separator = identity.indexOf(':');
-                const team = readTeamSync(join(ancestor.session.header.cwd ?? process.cwd(), stateDir), identity.slice(0, separator));
+                let team;
+                try {
+                    team = readTeamSync(join(ancestor.session.header.cwd ?? process.cwd(), stateDir), identity.slice(0, separator));
+                }
+                catch (error) {
+                    // Distinguish "team state unreadable" (e.g. a corrupt team.json) from
+                    // the guarded rejections below: reject with an actionable message
+                    // instead of leaking the raw parse error through subagents.start.
+                    throw new Error(`AgentTeams delegation guard could not read the team state of "${identity.slice(0, separator)}" (its team.json may be corrupt or unreadable): ${String(error)}`);
+                }
                 const member = team?.members.find(item => item.id === ancestor.id && item.name === identity.slice(separator + 1));
                 if (member === undefined || member.status === 'removed' || member.stopping === true || team?.halted === true)
                     throw new Error('AgentTeams member is no longer admitting delegated work');
@@ -630,27 +922,8 @@ export function installMemberDelegationGuard(ctx, stateDir, maxDepth) {
             depth++;
         }
     };
-    ctx.effect(() => {
-        const start = runtime.start;
-        const continuable = runtime.startContinuable;
-        const startDescriptor = Object.getOwnPropertyDescriptor(runtime, 'start');
-        const continuableDescriptor = Object.getOwnPropertyDescriptor(runtime, 'startContinuable');
-        const guardedStart = async (name, request) => { check(request.parent); return start.call(runtime, name, request); };
-        const guardedContinuable = async (spec) => { check(spec.request.parent); return continuable.call(runtime, spec); };
-        runtime.start = guardedStart;
-        runtime.startContinuable = guardedContinuable;
-        return () => {
-            active = false;
-            for (const [key, fn, descriptor] of [['start', guardedStart, startDescriptor], ['startContinuable', guardedContinuable, continuableDescriptor]]) {
-                if (Object.getOwnPropertyDescriptor(runtime, key)?.value !== fn)
-                    continue;
-                if (descriptor === undefined)
-                    Reflect.deleteProperty(runtime, key);
-                else
-                    Object.defineProperty(runtime, key, descriptor);
-            }
-        };
-    }, 'agent-teams: member delegation budget');
+    guardSubagentCreation(ctx, check);
+    ctx.effect(() => () => { active = false; }, 'agent-teams: delegation guard lifetime');
 }
 /**
  * Snapshot the real driver activity for durable member ids.

package/lib/profiles.js

@@ -17,7 +17,7 @@ export const MAX_PROFILE_TASKS = 32;
 export const PROFILE_PROTOCOL_PROMPT_LIMIT = 240;
 const PROFILE_KEYS = ['description', 'protocol', 'executionPrompt', 'fallback', 'members', 'tasks', 'taskPlanning', 'reviewPolicy'];
 const REVIEW_POLICY_KEYS = ['requirementsMinRounds', 'requirementsMaxRounds', 'codeMaxRounds', 'maxRepairAttempts', 'requiredReviewers'];
-const MEMBER_KEYS = ['name', 'role', 'provider', 'model', 'reasoning_effort', 'executionPrompt', 'fallback'];
+const MEMBER_KEYS = ['name', 'role', 'provider', 'model', 'reasoning_effort', 'executionPrompt', 'fallback', 'tool_policy'];
 const FALLBACK_KEYS = ['provider', 'model'];
 const TASK_KEYS = ['id', 'subject', 'description', 'assignee', 'dependencies'];
 /**
@@ -322,10 +322,11 @@ function normalizeMember(value, path, profileName) {
     const reasoningEffort = optionalNonEmptyString(raw['reasoning_effort'], `${path}.reasoning_effort`);
     const executionPrompt = optionalNonEmptyString(raw['executionPrompt'], `${path}.executionPrompt`);
     const fallback = normalizeFallback(raw['fallback'], `${path}.fallback`);
+    const toolPolicy = optionalNonEmptyString(raw['tool_policy'], `${path}.tool_policy`);
     if (provider !== undefined && model === undefined) {
         throw new Error(`profile member "${name}" sets provider without model`);
     }
-    return omitUndefined({ name, role, provider, model, reasoningEffort, executionPrompt, fallback });
+    return omitUndefined({ name, role, provider, model, reasoningEffort, executionPrompt, fallback, toolPolicy });
 }
 function normalizeFallback(value, path) {
     if (value === undefined)