@nanmicoder/dsh-agent-teams 0.1.17 → 0.1.19

package/lib/harness-compat.js

@@ -1,4 +1,6 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SubagentError } from '@deepseek-ai/dsh-subagent';
+import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
 /**
  * Exact protocol exported by dsh-subagent/internal in Alpha.5 and rc.1.
  * That subpath does not exist in Alpha.2, so importing it statically prevents
@@ -105,6 +107,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;
@@ -177,3 +200,86 @@ export function guardSubagentDelivery(ctx, isRetired) {
         };
     }, 'agent-teams: retired member guard');
 }
+/**
+ * Names the host's `tools.restrict()` would admit for this agent's layer
+ * chain, or undefined when the host does not expose its registry view.
+ * restrict() rejects unknown names with a hard error, so the spawn path must
+ * check entries against this view before forwarding them. Source:
+ * dsh-tools view()/restrict() in 0.1.5-rc.1; older Harness generations lack
+ * the surface and keep the verbatim list.
+ */
+export function restrictableToolNames(agent) {
+    const tools = agent?.ctx?.tools;
+    if (typeof tools?.view !== 'function')
+        return undefined;
+    try {
+        const names = tools.view.call(tools, agent.ctx)?.restrictableNames;
+        return names instanceof Set ? names : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Member `toolFilter` for one spawn. Captain-only names are registered by
+ * this plugin itself and always resolvable; the depth-related entries name
+ * HOST tools and are only known under some compositions, so they must be
+ * resolved against the running host's registry: the delegation tool name is
+ * host configuration (dsh-tool-subagent `toolName`, default `subagent`,
+ * renamed per composition, e.g. `subagent_fork` in web-style profiles), and
+ * forwarding a name the host dropped aborts every member spawn (#163, #164).
+ * Depth enforcement itself does not depend on these names —
+ * installMemberDelegationGuard bounds descendant creation by parent chain.
+ */
+export function memberToolFilter(maxDepth, knownTools) {
+    const depthDeny = maxDepth === 0 ? ['subagent', 'send_message'] : [];
+    return {
+        deny: [
+            ...CAPTAIN_TOOL_NAMES,
+            ...(knownTools === undefined ? depthDeny : depthDeny.filter(name => knownTools.has(name))),
+        ],
+    };
+}
+/**
+ * Names a `tools.restrict()` rejection reported as unknown, or an empty list
+ * for every other failure. The host names the offenders verbatim
+ * (`tools.restrict() names unknown global tool "x"; known global tools: …`);
+ * only that report may relax a filter (#164, #166).
+ */
+function unknownToolNames(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes('unknown global tool'))
+        return [];
+    return [...message.matchAll(/"([^"]+)"/g)].map(match => match[1]);
+}
+/**
+ * Start one member, dropping any filter name the host reports as unknown and
+ * retrying.
+ *
+ * Resolving the filter against the registry view ({@link memberToolFilter})
+ * only covers hosts that expose one. A rejected filter still leaves the member
+ * without a session for the lifetime of the team, so the start must survive the
+ * cases that resolution cannot see — no registry view, a name that is known but
+ * not restrictable, a composition that mounted differently than expected. The
+ * host names the offenders in its rejection, so they are removed and the start
+ * retried; the retry only runs while the deny list strictly shrinks, and any
+ * failure that is not an unknown-name report propagates untouched.
+ * @param start - performs one start attempt for the given `toolFilter`.
+ * @param filter - the filter to attempt first.
+ * @returns the started member.
+ */
+export async function startMemberWithLenientFilter(start, filter) {
+    let deny = [...filter.deny];
+    for (;;) {
+        try {
+            return await start({ deny });
+        }
+        catch (error) {
+            const unknown = unknownToolNames(error);
+            const remaining = deny.filter(name => !unknown.includes(name));
+            if (unknown.length === 0 || remaining.length === deny.length)
+                throw error;
+            deny = remaining;
+        }
+    }
+}

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. When a quality contract itself is wrong (a verify command that cannot pass, an inScope that forbids the file the objective requires), fix it with agent_teams_amend_task — captain-only, non-terminal tasks only, frozen after a passing review, and every amendment is recorded in the task's revisions ledger — instead of letting the worker dead-lock or game the gate.
 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,15 +16,13 @@ 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, 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 { appendTeamEvent, captainSessionOf } from "./events.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
-import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
 export const PERSONA_PROTOCOL_MAX_CHARS = 400;
-/** Captain-only AgentTeams tools hidden from newly spawned members. */
-const MEMBER_DENIED_TOOLS = CAPTAIN_TOOL_NAMES;
 /**
  * Restore the SessionId brand on a value that round-tripped through the
  * durable team file. The brand is erased by JSON serialization; the value
@@ -70,10 +68,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 +136,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 +278,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 +354,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 +384,7 @@ export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
             disposeFallback();
             disposeSelection();
             disposeFailure();
+            disposeAdmission();
         };
     });
     return {
@@ -432,7 +446,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 +458,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 +492,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.
@@ -497,14 +511,19 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
         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, () => (ctx.subagents.startContinuable({
+    const start = await selections.withPending(captain.id, label, llmSelection, () => (startMemberWithLenientFilter(toolFilter => ctx.subagents.startContinuable({
         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] },
+            // 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,
@@ -512,10 +531,12 @@ 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,
-    })));
+    }), memberToolFilter(config.maxDepth, restrictableToolNames(captain)))));
     member.id = start.childId;
 }
 /**
@@ -535,9 +556,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 +603,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.
  *