@nanmicoder/dsh-agent-teams 0.1.17 → 0.1.18

package/lib/harness-compat.js

@@ -1,3 +1,4 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SubagentError } from '@deepseek-ai/dsh-subagent';
 /**
  * Exact protocol exported by dsh-subagent/internal in Alpha.5 and rc.1.
@@ -105,6 +106,27 @@ export async function queueMemberPrompt(runtime, parent, childId, content, signa
         return unsupported('missing host FIFO delivery');
     return queue.call(runtime, parent, childId, content, source, signal);
 }
+/** Coordination joins the nearest step, including waking an idle/cold child. */
+export async function steerMemberPrompt(runtime, parent, childId, content, signal, live) {
+    const host = boundary(runtime);
+    const source = { kind: 'plugin', plugin: 'dsh-agent-teams' };
+    const deliver = host[hostPromptDeliver];
+    if (typeof deliver === 'function')
+        return deliver.call(runtime, parent, childId, content, source, signal, 'steer');
+    if (typeof host.sendMessage === 'function')
+        return host.sendMessage.call(runtime, parent, childId, content, { signal });
+    if (typeof host.followup === 'function') {
+        if (live === undefined)
+            return queueMemberPrompt(runtime, parent, childId, content, signal);
+        if (live.id !== childId || live.session.header.parentSession !== parent.id)
+            throw new Error('invalid member steering authority');
+        signal.throwIfAborted();
+        const message = createUserMessage({ content, source });
+        live.steer(message);
+        return message.id;
+    }
+    return unsupported('missing step-boundary message delivery');
+}
 /** Guard all resumable delivery paths, preserving the native service receiver. */
 export function guardSubagentDelivery(ctx, isRetired) {
     const runtime = ctx.subagents;

package/lib/index.js

@@ -80,7 +80,7 @@ export const Config = z.object({
             dependencies: z.array(z.string()),
         })),
     })).default({}),
-    memberMaxDepth: z.natural().default(1),
+    memberMaxDepth: z.natural().default(0),
     maxMembers: z.natural().min(1).default(8),
     promptSectionOrder: z.natural().default(117),
     slashCommand: z.boolean().default(true),
@@ -90,11 +90,11 @@ export function usageSectionText(toolNames, profilesText = '') {
     return `AgentTeams captain protocol:
 1. Inspect current team state when needed, using agent_teams_status. Continue existing work without duplicating its roster/tasks. Create only when no current team exists, with the user's goal as description and approval="required"; automatic approval requires an explicit request to run immediately. Staged plans never spawn or schedule work.
 2. Add each needed role once; members inherit your model route unless another is requested/needed. A requested profile goes to create({profile}); it supplies its roster. Seed profiles also supply tasks; captain-planning profiles require your DAG. Do not duplicate either.
-3. Build the complete smallest useful DAG while staged. Every task needs a subject; dependencies represent prerequisites. Give every required contributor a task or explicit message. Present the plan and end your turn for review; never approve in that planning turn. Approve only after a later explicit user approval or the Web action.
+3. Build the complete smallest useful DAG while staged. For an ordinary research/audit plan, pass the roster and dependency graph together in create({plan:{members,tasks}}) to avoid repeated setup rounds. Every task needs a subject; pass kind and assignee explicitly when the plan specifies them. Titles, descriptions and member roles do not set these fields. Dependencies represent prerequisites. Give every required contributor a task or explicit message. Present the plan and end your turn for review; never approve in that planning turn. Approve only after a later explicit user approval or the Web action.
 4. Respect Web approve/return/discard control messages. On return, ask what to change before editing; after the answer, use one atomic agent_teams_edit_plan batch (edit downstream references before removals), summarize and await review again. Never inspect or edit .agent-teams state files or plugin source code to revise plans. Discard does not authorize a replacement.
 5. The scheduler dispatches ready tasks after approval. Delegate; do not duplicate slow work or send messages merely to start a stage. Handle reports/user work, then yield when waiting is all that remains: reports wake you automatically. Use status after a delivery or user request, never busy-poll or wait for unassigned members.
 6. Tasks carry attempt_id capabilities. Use the current attempt_id; stale means ownership changed. Pause members only on explicit request; later guidance via send_message continues that same attempt. Retry, transfer or take over through reassign_task first; it revokes the old attempt and waits for quiescence. Prefer a member. Captain implementation/review takeover requires a user request. Every takeover is one ready task at a time, finished in this turn; never yield with captain-owned work open.
-7. Quality kinds (requirements, implementation, verification, review, repair, integration) require objective + acceptance; implementation/repair also require inScope + verify. Derive paths/commands from the workspace/profile, never assume src/ or pnpm test. Review/requirements complete only with verdict=pass; needs_revision/reject fail with findings. Never approve your own implementation or ask for a deliberate failure.
+7. In a running team, correct never-started pending tasks with edit_plan update_task; preserve dependency and ownership contracts instead of cancelling and recreating the graph. A captain can cancel a never-started pending task directly. Active attempts still require reassign_task. Quality kinds (requirements, implementation, verification, review, repair, integration) require objective + acceptance; implementation/repair also require inScope + verify. Derive paths/commands from the workspace/profile, never assume src/ or pnpm test. Review/requirements complete only with verdict=pass; needs_revision/reject fail with findings. Never approve your own implementation or ask for a deliberate failure.
 8. When full quality mode is requested: requirements → implementation → verification → review → integration. Plan the entire DAG while staged, including implementation before requirements finishes and integration depending on review round 1. Failed review automatically adds repair + next review and rewires pending downstream gates. Do not recreate this loop, omit integration or depend on a failed task. Review acceptance judges the latest implementation. Do not put smoke-test scripts into task instructions.
 9. Halted means the user stopped work (including the captain turn). Resume only on a later explicit user request with a reason, via agent_teams_resume or create_task({resume:true,resumeReason}); creating tasks alone never resumes. Escalated means the review loop hit its limit, not a halt. Deployment requires explicit user confirmation.
 10. Wait for all required tasks to be terminal and members idle/ready, present results, then delete/archive unless the user wants to continue. Never discard unfinished work without authorization.
@@ -107,7 +107,7 @@ export function apply(ctx, config) {
         memberModel: config.memberModel,
         executionPrompt: config.executionPrompt,
         fallback: config.fallback,
-        memberMaxDepth: config.memberMaxDepth ?? 1,
+        memberMaxDepth: config.memberMaxDepth ?? 0,
         maxMembers: config.maxMembers ?? 8,
         profiles: config.profiles ?? {},
     };

package/lib/mailbox.js

@@ -0,0 +1,154 @@
+import { join } from 'node:path';
+import { acknowledgeMailbox, CAPTAIN_KEY, discardMailboxMessages, findTeamByCaptain, readMailbox, readTeam, sanitizeKey, withTeamLock } from "./state.js";
+import { sessionOwnEvents } from "./harness-compat.js";
+const PREFIX = 'AgentTeams inbox receipt: ';
+export function isCurrentMail(team, message) {
+    if (message.discardedAt !== undefined)
+        return false;
+    if (message.attemptId === undefined)
+        return true;
+    return team.tasks.some(task => task.id === message.taskId && task.attemptId === message.attemptId
+        && task.assignee === message.to && (task.status === 'claimed' || task.status === 'in_progress'));
+}
+function mailboxBody(recipient, messages) {
+    return messages.map(message => recipient === CAPTAIN_KEY
+        ? `AgentTeams message from member ${message.from}:\n\n${message.content}`
+        : `AgentTeams message from ${message.from}${message.attemptId === undefined ? '' : ` for task ${message.taskId}, attempt_id ${message.attemptId}`}:\n\n${message.content}`).join('\n\n');
+}
+export function mailboxPrompt(teamId, recipient, messages) {
+    return PREFIX + JSON.stringify({ teamId, recipient, ids: messages.map(message => message.id) }) + '\n\n' + mailboxBody(recipient, messages);
+}
+function parseReceipt(text) {
+    if (!text.startsWith(PREFIX))
+        return undefined;
+    try {
+        const value = JSON.parse(text.slice(PREFIX.length).split('\n')[0]);
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        const raw = value;
+        if (typeof raw['teamId'] !== 'string' || typeof raw['recipient'] !== 'string'
+            || !Array.isArray(raw['ids']) || !raw['ids'].every(id => typeof id === 'string'))
+            return undefined;
+        if (raw['teamId'] !== sanitizeKey(raw['teamId']))
+            return undefined;
+        return { teamId: raw['teamId'], recipient: raw['recipient'], ids: raw['ids'] };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Only messages actually admitted to this recipient's step become read. */
+export function installMailboxAdmission(ctx, stateDir) {
+    ctx.on('agent/pre-step', async (payload, next) => {
+        const decision = await next();
+        if (decision.kind !== 'enter')
+            return decision;
+        const root = join(payload.agent.session.header.cwd ?? process.cwd(), stateDir);
+        // The native runtime also wakes a parent when a background activation
+        // settles. A successfully delivered Team report already carries that
+        // result. Keep abnormal endings and missing reports as fallback signals.
+        const successfulSettlements = new Set(decision.messages.flatMap(input => {
+            const source = input.source;
+            return source?.kind === 'subagent-settled'
+                && source.summary === `Background subagent ${source.senderSessionId} finished and will do no further work unless you send it more.`
+                ? [source.senderSessionId] : [];
+        }));
+        const redundantSettlements = new Set();
+        if (successfulSettlements.size > 0) {
+            const owned = await findTeamByCaptain(root, payload.agent.id);
+            if (owned !== undefined)
+                await withTeamLock(`team:${root}:${owned.id}`, async () => {
+                    const team = await readTeam(root, owned.id);
+                    if (team?.captainSessionId !== payload.agent.id || team.halted)
+                        return;
+                    const reports = await readMailbox(root, team.id, CAPTAIN_KEY);
+                    for (const member of team.members) {
+                        if (!successfulSettlements.has(member.id) || member.status === 'removed' || member.stopping)
+                            continue;
+                        const tasks = team.tasks.filter(task => task.assignee === member.name);
+                        if (tasks.some(task => task.status === 'claimed' || task.status === 'in_progress'))
+                            continue;
+                        const latest = tasks.filter(task => (task.attempt ?? 0) > 0 || task.status === 'completed').sort((a, b) => b.updatedAt - a.updatedAt)[0];
+                        if (latest?.status === 'completed' && reports.some(report => report.from === member.name && report.ts >= latest.updatedAt
+                            && report.discardedAt === undefined && (report.deliveredAt !== undefined || report.readAt !== undefined))) {
+                            redundantSettlements.add(member.id);
+                        }
+                    }
+                });
+        }
+        const batches = new Map();
+        const inputs = decision.messages.map(input => {
+            // Alpha.5/0.1.2-rc.1 public steering prepends a native sender block.
+            // The host-authored receipt remains a separate text block after it.
+            const receipt = input.content.flatMap(block => block.type === 'text' ? [parseReceipt(block.text)] : []).find(value => value !== undefined);
+            if (receipt === undefined)
+                return { input };
+            const key = JSON.stringify([receipt.teamId, receipt.recipient]);
+            let batch = batches.get(key);
+            if (batch === undefined) {
+                batch = { receipt, ids: new Set(), current: new Map() };
+                batches.set(key, batch);
+            }
+            for (const id of receipt.ids)
+                batch.ids.add(id);
+            return { input, receipt, batch };
+        });
+        // One read/acknowledgement per recipient per step, even for a large burst.
+        for (const batch of batches.values()) {
+            const { receipt } = batch;
+            await withTeamLock(`team:${root}:${receipt.teamId}`, async () => {
+                const team = await readTeam(root, receipt.teamId);
+                if (team === undefined)
+                    return;
+                const recipientId = receipt.recipient === CAPTAIN_KEY ? team.captainSessionId
+                    : team.members.find(member => member.name === receipt.recipient && member.status !== 'removed' && member.stopping !== true)?.id;
+                if (recipientId !== payload.agent.id)
+                    return;
+                const selected = (await readMailbox(root, team.id, receipt.recipient)).filter(message => batch.ids.has(message.id));
+                const current = selected.filter(message => message.readAt === undefined && isCurrentMail(team, message));
+                await discardMailboxMessages(root, team.id, receipt.recipient, selected.filter(message => !isCurrentMail(team, message)).map(message => message.id));
+                await acknowledgeMailbox(root, team.id, receipt.recipient, current.map(message => message.id));
+                batch.current = new Map(current.map(message => [message.id, message]));
+            });
+        }
+        const admitted = [];
+        for (const { input, receipt, batch } of inputs) {
+            if (input.source?.kind === 'subagent-settled' && redundantSettlements.has(input.source.senderSessionId)
+                && input.source.summary === `Background subagent ${input.source.senderSessionId} finished and will do no further work unless you send it more.`)
+                continue;
+            if (receipt === undefined || batch === undefined) {
+                admitted.push(input);
+                continue;
+            }
+            const messages = [];
+            for (const id of receipt.ids) {
+                const message = batch.current.get(id);
+                if (message === undefined)
+                    continue;
+                batch.current.delete(id);
+                messages.push(message);
+            }
+            if (messages.length > 0)
+                admitted.push({ ...input, content: [{ type: 'text', text: mailboxBody(receipt.recipient, messages) }] });
+        }
+        // Reject only a new turn whose sole trigger was obsolete mail. During an
+        // existing turn, a status tool may have consumed this same mail already;
+        // dropping its duplicate must not block the pending tool-result response.
+        if (decision.messages.length > 0 && admitted.length === 0) {
+            const events = sessionOwnEvents(payload.agent.session);
+            let continuing = false;
+            for (let i = events.length - 1; i >= 0; i--) {
+                const event = events[i];
+                if (event.type === 'step/start' && event.data.turn === payload.turn) {
+                    continuing = true;
+                    break;
+                }
+                if (event.type === 'turn/start')
+                    break;
+            }
+            if (!continuing)
+                return { kind: 'reject' };
+        }
+        return { ...decision, messages: admitted };
+    });
+}

package/lib/members.js

@@ -1,6 +1,6 @@
 /**
  * Member subagent lifecycle: spawn a continuable child per member, deliver
- * messages into its FIFO inbox, and observe its activity.
+ * task turns and step-boundary messages, and observe its activity.
  *
  * Members are durable continuable subagents of the captain, so a member keeps
  * its conversation across turns and across harness restarts: the captain
@@ -16,8 +16,9 @@ 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, queueMemberPrompt, sessionOwnEvents } from "./harness-compat.js";
-import { acknowledgeMailbox, appendMailbox, CAPTAIN_KEY, createMessage, readRetiredMemberIds, readTeamSync, readTeam, releaseMailboxDelivery, withTeamLock, writeTeam } from "./state.js";
+import { guardSubagentDelivery, installContinuableMemberSetup, queueMemberPrompt, 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 { appendTeamEvent, captainSessionOf } from "./events.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
 import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
@@ -70,10 +71,10 @@ export function selectFallbackRoute(current, fallback, failureCode, alreadySwitc
     return { retry: true, switched: true, selection: fallback };
 }
 /** Deliver a durable member report to the live captain at its next model step. */
-export function steerCaptainReport(captain, from, content) {
+export function steerCaptainReport(captain, from, content, receipt) {
     try {
         captain.steer(createUserMessage({
-            content: [{ type: 'text', text: `AgentTeams message from member ${from}:\n\n${content}` }],
+            content: [{ type: 'text', text: receipt ?? `AgentTeams message from member ${from}:\n\n${content}` }],
             source: { kind: 'plugin', plugin: 'dsh-agent-teams' },
         }));
         return true;
@@ -138,9 +139,9 @@ export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName,
     // 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 delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content);
+    const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content, mailboxPrompt(teamId, CAPTAIN_KEY, [prepared.message]));
     await withTeamLock(lockKey, () => delivered
-        ? acknowledgeMailbox(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id])
+        ? markMailboxDelivered(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id])
         : releaseMailboxDelivery(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id]));
     return true;
 }
@@ -280,11 +281,26 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
         const workspace = child.session.header.cwd ?? process.cwd();
         const stateRoot = join(workspace, stateDir);
         const key = pendingSelectionKey(parentSessionId, descriptor.label);
+        // Internal settlement wakeups bypass the public delivery guard. Recheck
+        // exact durable membership on every proposed step, including cold resume.
+        const disposeAdmission = childCtx.on('agent/pre-step', async (payload, next) => {
+            if (payload.agent.id !== child.id)
+                return next();
+            const admitted = await withTeamLock(`team:${stateRoot}:${teamId}`, async () => {
+                const team = await readTeam(stateRoot, teamId);
+                return team?.captainSessionId === parentSessionId && team.phase !== 'staged' && team.halted !== true
+                    && team.members.some(member => member.id === child.id && member.name === memberName && member.status !== 'removed' && member.stopping !== true)
+                    && !team.tasks.some(task => task.reassigning === true && task.assignee === memberName);
+            });
+            if (!admitted)
+                return { kind: 'reject' };
+            return next();
+        });
         let selection = pending.get(key);
         if (selection === undefined) {
             const team = readTeamSync(stateRoot, teamId);
             if (team?.captainSessionId !== parentSessionId)
-                return () => undefined;
+                return disposeAdmission;
             const durableMember = team.members.find(member => member.name === memberName);
             selection = selectionFromMember(durableMember);
             if (selection !== undefined && (descriptor.agentProvider !== durableMember?.provider || descriptor.agentModel !== durableMember?.model)) {
@@ -341,7 +357,7 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
         });
         // Legacy teams still need failure reporting even without a saved route.
         if (selection === undefined)
-            return disposeFailure;
+            return () => { disposeFailure(); disposeAdmission(); };
         const selectionRef = { current: modelSelection(selection), assembled: undefined };
         const disposeSelection = installModelSelection(childCtx, selectionRef);
         const fallback = selection.fallback;
@@ -371,6 +387,7 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
             disposeFallback();
             disposeSelection();
             disposeFailure();
+            disposeAdmission();
         };
     });
     return {
@@ -432,7 +449,7 @@ Team context:
 ${injectedPrompt === undefined || injectedPrompt === '' ? '' : `- Execution guidance:
 ${injectedPrompt}
 `}- The team state lives under ${stateDir}/${team.id}/ (team.json and inbox/*.jsonl). You may inspect these files read-only for diagnostics, but never edit them directly; use the agent_teams_* tools so JSON escaping and concurrent updates stay safe.
-- The captain and your teammates reach you through messages. Each message you receive is a new turn: act on it and end your turn with a concise reply.
+- The captain and your teammates reach you through messages. Coordination arrives at your nearest model step. Apply it to your current attempt; a task assignment starts a separate turn.
 When you receive a task, treat the assignment prompt's dependency results as source material. Do not ignore them.
 
 Working rules:
@@ -444,8 +461,8 @@ Working rules:
    - include a concise output in either case;
    - a stale-attempt rejection means the captain reassigned or took over the task; stop touching that task and wait for new work.
    claimed cannot jump to completed. Mark in_progress first, then completed or failed.
-   Include attempt_id on every update. Then send_message to captain and become idle.
-4. Send a short report to the captain with agent_teams_send_message (to=captain) when you complete a task or hit a blocker.
+   Include attempt_id on every update. Then report once as described below and become idle.
+4. Send one short report with agent_teams_send_message (to=captain) when you complete a task or hit a blocker. The captain is also your parent: this single message satisfies both reporting duties. Do not repeat it through the native send_message tool or send acknowledgments that add no new information.
 5. To ask a teammate something, use agent_teams_send_message with to=<teammate name>; the message lands in their mailbox and wakes them directly — teammates talk to each other without the captain in the loop. The same applies to the captain (to=captain).
 6. After your turn becomes idle, the shared task scheduler may assign your next ready task automatically. Never claim a second task while you still own unfinished work.
 7. If you already own an open attempt (claimed or in_progress) and receive mail, treat it as guidance for that same attempt_id unless the mail explicitly tells you to stop or fail. Do not claim a new task in that turn.
@@ -478,7 +495,7 @@ Do not start work until the scheduler or captain assigns a task in this turn.`;
  * @param stateDir - configured state directory (for the persona).
  * @param signal - caller cancellation, forwarded to the start.
  */
-export async function spawnMember(ctx, config, selections, llmSelection, captain, team, member, stateDir, signal) {
+export async function spawnMember(ctx, config, selections, llmSelection, captain, team, member, stateDir, signal, initialPrompt) {
     // 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.
@@ -501,10 +518,10 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
         provider: config.provider,
         label,
         request: {
-            prompt: [{ type: 'text', text: memberWelcome(team, member.name) }],
+            prompt: [{ type: 'text', text: initialPrompt ?? memberWelcome(team, member.name) }],
             parent: captain,
             persona: memberPersona(team, member, stateDir, config.executionPrompt),
-            toolFilter: { deny: [...MEMBER_DENIED_TOOLS] },
+            toolFilter: { deny: [...MEMBER_DENIED_TOOLS, ...(config.maxDepth === 0 ? ['subagent', 'send_message'] : [])] },
             agentOptions: {
                 provider: llmSelection.provider,
                 model: llmSelection.model,
@@ -512,7 +529,9 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
                     ? {}
                     : { reasoningEffort: ReasoningEffortId(llmSelection.reasoningEffort) },
             },
-            ...config.maxDepth !== undefined ? { maxDepth: config.maxDepth } : {},
+            // 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,
     })));
@@ -535,9 +554,13 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
  * @param signal - caller cancellation, forwarded to the delivery.
  * @returns whether the member inbox accepted the message.
  */
-export async function deliverToMember(ctx, captain, childId, text, signal) {
+export async function deliverToMember(ctx, captain, childId, text, signal, mode = 'queue') {
     try {
-        await queueMemberPrompt(ctx.subagents, captain, brandedSessionId(childId), [{ type: 'text', text }], signal);
+        const content = [{ type: 'text', text }];
+        if (mode === 'steer')
+            await steerMemberPrompt(ctx.subagents, captain, brandedSessionId(childId), content, signal, ctx.agents.get(brandedSessionId(childId)));
+        else
+            await queueMemberPrompt(ctx.subagents, captain, brandedSessionId(childId), content, signal);
         return true;
     }
     catch (error) {
@@ -578,6 +601,55 @@ export function installRetiredMemberGuard(ctx, stateDir) {
         return retired.has(childId);
     });
 }
+/** 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)
+            return;
+        let ancestor = parent;
+        let depth = 1;
+        while (ancestor !== undefined) {
+            const descriptor = foldSubagentDescriptor(sessionOwnEvents(ancestor.session));
+            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));
+                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');
+                if (depth > maxDepth)
+                    throw new Error(`AgentTeams member delegation limit (${maxDepth}) reached; report to the captain instead of spawning another agent`);
+                return;
+            }
+            const parentId = ancestor.session.header.parentSession;
+            ancestor = parentId === undefined ? undefined : ctx.agents.get(parentId);
+            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');
+}
 /**
  * Snapshot the real driver activity for durable member ids.
  *

package/lib/quality-gates.js

@@ -269,13 +269,14 @@ export function validateCreateTask(team, input) {
     if (kind === 'implementation') {
         const requirements = team.tasks.filter((item) => taskKindOf(item) === 'requirements');
         const passed = requirements.some((item) => item.status === 'completed' && item.verdict === 'pass');
-        const stagedBehindRequirements = team.phase === 'staged' && requirements.some((item) => (dependencyClosureContains(team.tasks, dependencies, item.id)));
-        if (requirements.length > 0 && !passed && !stagedBehindRequirements) {
+        const behindRequirements = requirements.some((item) => (dependencyClosureContains(team.tasks, dependencies, item.id)));
+        // Planning an implementation is safe in either approval mode when its
+        // dependency chain fences execution behind requirements. Scheduling and
+        // claiming still wait for successful dependency completion.
+        if (requirements.length > 0 && !passed && !behindRequirements) {
             return {
                 ok: false,
-                error: team.phase === 'staged'
-                    ? 'implementation must depend on the staged requirements task; it will run only after requirements passes'
-                    : 'implementation is blocked until a requirements task completes with verdict=pass',
+                error: 'implementation must depend on a requirements task until requirements completes with verdict=pass',
             };
         }
     }
@@ -515,6 +516,20 @@ export function buildCoverageMatrix(goalItems, tasks) {
 }
 export function canDeclareDelivery(team) {
     const blockers = [];
+    if (team.phase === 'staged')
+        blockers.push('team plan is awaiting approval');
+    if (team.halted === true)
+        blockers.push('team is halted');
+    if (team.escalated === true)
+        blockers.push('team requires escalation resolution');
+    if (team.tasks.length === 0)
+        blockers.push('team has no completed work');
+    for (const item of team.tasks.filter(item => !isQualityKind(taskKindOf(item)))) {
+        if (item.status !== 'completed' && item.status !== 'cancelled')
+            blockers.push(`${item.id} (${taskKindOf(item)}) is not completed`);
+    }
+    if (team.tasks.length > 0 && team.tasks.every(item => item.status === 'cancelled'))
+        blockers.push('all work was cancelled');
     const quality = team.tasks.filter((item) => isQualityKind(taskKindOf(item)));
     const implementations = quality.filter((item) => taskKindOf(item) === 'implementation' || taskKindOf(item) === 'repair');
     const reviews = quality.filter((item) => taskKindOf(item) === 'review');
@@ -796,7 +811,7 @@ export function describeQualityLoop(team) {
             halted: false,
             escalated: team.escalated === true,
             deliverable: true,
-            summary: 'All required quality gates passed. The captain may report delivery.',
+            summary: 'All required work and quality gates passed. The captain may report delivery.',
         };
     }
     if (team.escalated === true) {

package/lib/scheduler.js

@@ -13,7 +13,8 @@
  */
 import { join } from 'node:path';
 import { deliverToMember } from "./members.js";
-import { acknowledgeMailbox, beginTaskAttempt, CAPTAIN_KEY, claimMailboxDelivery, findTeamByParticipant, invalidateTaskAttempt, readTeam, readUnreadMailbox, releaseMailboxDelivery, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
+import { isCurrentMail, mailboxPrompt } from "./mailbox.js";
+import { markMailboxDelivered, discardMailboxMessages, beginTaskAttempt, CAPTAIN_KEY, claimMailboxDelivery, findTeamByParticipant, invalidateTaskAttempt, readTeam, readPendingMailbox, releaseMailboxDelivery, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
 /** Per-dependency output cap in the assignment prompt. */
 export const DEPENDENCY_OUTPUT_MAX_CHARS = 2_000;
 /** Combined dependency-output budget in the assignment prompt. */
@@ -103,6 +104,8 @@ function liveMember(ctx, member) {
     return ctx.agents.get(member.id);
 }
 function isMemberAvailable(ctx, member) {
+    if (member.stopping === true)
+        return false;
     const live = liveMember(ctx, member);
     return live === undefined || live.status === 'idle';
 }
@@ -168,13 +171,6 @@ When finishing: use status=completed only when the task's success criteria are s
 
 State policy: ${stateDir}/${teamId}/ is read-only diagnostics; mutate team state only through agent_teams_* tools.`;
 }
-function fallbackMailboxPrompt(messages) {
-    return [
-        'AgentTeams delivered messages that were persisted while live delivery was unavailable:',
-        ...messages.map(message => `\nFrom ${message.from}:\n${message.content}`),
-        '\nHandle these messages in this turn. Task assignments still require agent_teams_claim_task and the current attempt_id.',
-    ].join('\n');
-}
 /** Install one scheduler and its member activity observer. */
 export function installTeamScheduler(ctx, config) {
     const memberQueues = new Map();
@@ -227,16 +223,28 @@ export function installTeamScheduler(ctx, config) {
                 if (captain === undefined)
                     return;
                 let member = team.members.find(candidate => candidate.name === memberName && candidate.status !== 'removed');
-                if (member === undefined || member.id === '' || !isMemberAvailable(ctx, member))
+                if (member === undefined || !isMemberAvailable(ctx, member))
                     return;
                 // A mailbox-only fallback is real pending work. Deliver it before a
                 // fresh task and acknowledge only after Harness accepts the follow-up.
-                const unread = await readUnreadMailbox(stateRoot, team.id, member.name);
+                const unread = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                    const fresh = await readTeam(stateRoot, team.id);
+                    if (fresh === undefined)
+                        return [];
+                    const pending = await readPendingMailbox(stateRoot, fresh.id, member.name);
+                    await discardMailboxMessages(stateRoot, fresh.id, member.name, pending.filter(message => !isCurrentMail(fresh, message)).map(message => message.id));
+                    const current = pending.filter(message => isCurrentMail(fresh, message));
+                    await claimMailboxDelivery(stateRoot, fresh.id, member.name, current.map(message => message.id));
+                    return current;
+                });
                 if (unread.length > 0) {
-                    await withTeamLock(teamLockKey(stateRoot, team.id), () => (claimMailboxDelivery(stateRoot, team.id, member.name, unread.map(message => message.id))));
-                    const accepted = await deliverToMember(ctx, captain, member.id, fallbackMailboxPrompt(unread), new AbortController().signal);
+                    const prompt = mailboxPrompt(team.id, member.name, unread);
+                    const signal = new AbortController().signal;
+                    const accepted = config.dispatch === undefined
+                        ? await deliverToMember(ctx, captain, member.id, prompt, signal, 'steer')
+                        : await config.dispatch(captain, team.id, member.name, prompt, signal, 'steer');
                     if (accepted) {
-                        await withTeamLock(teamLockKey(stateRoot, team.id), () => (acknowledgeMailbox(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                        await withTeamLock(teamLockKey(stateRoot, team.id), () => (markMailboxDelivered(stateRoot, team.id, member.name, unread.map(message => message.id))));
                     }
                     else {
                         await withTeamLock(teamLockKey(stateRoot, team.id), () => (releaseMailboxDelivery(stateRoot, team.id, member.name, unread.map(message => message.id))));
@@ -248,7 +256,7 @@ export function installTeamScheduler(ctx, config) {
                     if (fresh === undefined || fresh.halted === true || fresh.phase === 'staged')
                         return undefined;
                     const currentMember = fresh.members.find(candidate => candidate.name === memberName && candidate.status !== 'removed');
-                    if (currentMember === undefined || currentMember.id === '' || !isMemberAvailable(ctx, currentMember))
+                    if (currentMember === undefined || !isMemberAvailable(ctx, currentMember))
                         return undefined;
                     const owned = ownedOpenTask(fresh.tasks, currentMember.name);
                     // An idle edge observed by this scheduler parks the exact open
@@ -318,7 +326,11 @@ export function installTeamScheduler(ctx, config) {
                 });
                 if (ticket === undefined)
                     return;
-                const accepted = await deliverToMember(ctx, captain, ticket.memberId, assignmentPrompt(ticket, config.stateDir, team.id), new AbortController().signal);
+                const prompt = assignmentPrompt(ticket, config.stateDir, team.id);
+                const signal = new AbortController().signal;
+                const accepted = config.dispatch === undefined
+                    ? await deliverToMember(ctx, captain, ticket.memberId, prompt, signal)
+                    : await config.dispatch(captain, team.id, ticket.memberName, prompt, signal, 'queue', ticket.attemptId);
                 if (accepted)
                     return;
                 // Roll back only our exact failed dispatch. A concurrent captain

package/lib/snapshot.js

@@ -76,7 +76,7 @@ export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state, opt
                         : activity.get(member.id) === 'idle' || activity.get(member.id) === 'ready'
                             ? 'idle'
                             : 'unknown')
-                    : state.phase === 'staged' ? 'idle' : 'unknown',
+                    : 'idle',
             progress: owned.length === 0 ? 0 : Math.round((done / owned.length) * 100),
             done,
             total: owned.length,