@aragon-agent/cli 0.5.2 → 0.5.3

package/dist/team/subagent.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `createSubagent` — one child `Agent`, its tool set, and the instrumentation
+ * that turns core events into a `SubagentRun` (team-subagents §3.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * A CHILD IS BUILT FROM THE SAME FACTORY THE LEAD USES. That is the point: the
+ * `--confirm` gate, the skills ceiling and the plan-mode gate are re-applied one
+ * level down by the same wrappers, so delegation cannot be a way around any of
+ * them (§3.11 / R-6). What a child does NOT get is spelled out below, and each
+ * omission has a reason that is a correctness boundary rather than caution.
+ */
+import { type AgentConfig, type AgentEvent, type AgentTool, type ProviderRegistry, type SkillRegistry, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+import type { AgentMode } from '../agent/agent-mode.js';
+import type { CliConfig } from '../config/schema.js';
+import { TeamBus } from './bus.js';
+import type { TeamHumanQueue, WatchdogPausable } from './human-queue.js';
+import type { SubagentRun, SubagentSpec } from './types.js';
+/**
+ * The slice of `Agent` a child is used through.
+ *
+ * Structural rather than the concrete class so `TeamRuntime` can be handed a
+ * stub factory and the whole scheduler can be tested without a network — the
+ * same seam `HeadlessController` already uses.
+ */
+export interface SubagentAgentLike extends WatchdogPausable {
+    prompt(text: string): Promise<void>;
+    abort(): void;
+    subscribe(listener: (event: AgentEvent) => void): () => void;
+}
+export type SubagentAgentFactory = (config: AgentConfig) => SubagentAgentLike;
+/** The default factory: a real `Agent` from `@aragon-agent/core`. */
+export declare const defaultSubagentFactory: SubagentAgentFactory;
+/** Everything a child needs that is the same for every child in a dispatch. */
+export interface SubagentDeps {
+    bus: TeamBus;
+    config: CliConfig;
+    providerRegistry: ProviderRegistry;
+    getCwd: () => string;
+    /** The lead's live session mode. Read at CALL time, never cached. */
+    getMode: () => AgentMode;
+    getApiKey: (providerId: string) => string | undefined;
+    /**
+     * The lead's `SkillRegistry`, used for `skill_find` ONLY.
+     *
+     * `undefined` when skills are off, in which case the child gets no skill tool
+     * at all — the same shape `--no-skills` produces for the lead.
+     */
+    skillRegistry?: SkillRegistry;
+    /** The lead's always-on skill bodies, spliced into every child's prompt. */
+    alwaysBlock?: string;
+    toolPolicy?: () => ToolPolicyDecision;
+    /** Already label-decorating; see `TeamRuntime` (§3.11 / P1-3). */
+    onChildToolPolicyEvent?: (e: {
+        label: string;
+        tool: string;
+        verdict: ToolPolicyVerdict;
+        sourceNames: string[];
+    }) => void;
+    confirmTools: boolean;
+    /** Present only when `--confirm` is on AND a human channel exists. */
+    humanQueue?: TeamHumanQueue;
+    agentFactory: SubagentAgentFactory;
+}
+export interface SubagentHooks {
+    /** Coalesced at the source (§5.2); phase transitions always pass. */
+    onUpdate: (run: SubagentRun) => void;
+    onUsage: (label: string, usage: TokenUsage) => void;
+}
+export interface SubagentHandle {
+    spec: SubagentSpec;
+    run: SubagentRun;
+    agent: SubagentAgentLike;
+    tools: AgentTool[];
+    unsubscribe: () => void;
+}
+/**
+ * Build a child's tool array.
+ *
+ * Exported so `team-tool-gate.test.ts` can assert what a child may and may not
+ * call without constructing an `Agent` or reaching a network — the tool set IS
+ * the security boundary here, so it has to be directly checkable.
+ */
+export declare function buildSubagentTools(spec: SubagentSpec, deps: SubagentDeps, getAgent: () => WatchdogPausable | null): AgentTool[];
+/**
+ * Construct a child and wire its instrumentation.
+ *
+ * The returned agent has NOT been prompted; `TeamRuntime` owns scheduling.
+ */
+export declare function createSubagent(spec: SubagentSpec, deps: SubagentDeps, hooks: SubagentHooks): SubagentHandle;

package/dist/team/subagent.js

@@ -0,0 +1,294 @@
+/**
+ * `createSubagent` — one child `Agent`, its tool set, and the instrumentation
+ * that turns core events into a `SubagentRun` (team-subagents §3.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * A CHILD IS BUILT FROM THE SAME FACTORY THE LEAD USES. That is the point: the
+ * `--confirm` gate, the skills ceiling and the plan-mode gate are re-applied one
+ * level down by the same wrappers, so delegation cannot be a way around any of
+ * them (§3.11 / R-6). What a child does NOT get is spelled out below, and each
+ * omission has a reason that is a correctness boundary rather than caution.
+ */
+import { Agent, createSkillFindTool, } from '@aragon-agent/core';
+import { formatStreamError } from '../agent/reducer.js';
+import { buildSystemPrompt } from '../agent/system-prompt.js';
+import { createBuiltinTools } from '../tools/index.js';
+import { pickActivityArgs, sanitizeActivity } from './activity.js';
+import { TEAM_LIMITS, TEAM_SUBAGENT_TOOL_NAMES } from './limits.js';
+import { isRetryableStreamError } from './retry.js';
+import { makeTeamSend, makeTeamWait, withMailboxTail } from './comm-tools.js';
+import { buildSubagentBlock } from './prompt.js';
+/** The default factory: a real `Agent` from `@aragon-agent/core`. */
+export const defaultSubagentFactory = (config) => new Agent(config);
+/** The final assistant text of a turn, or `''` when the turn was tool calls only. */
+function assistantText(message) {
+    if (!message || !Array.isArray(message.content))
+        return '';
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === 'text')
+            parts.push(block.text);
+    }
+    return parts.join('').trim();
+}
+/**
+ * Build a child's tool array.
+ *
+ * Exported so `team-tool-gate.test.ts` can assert what a child may and may not
+ * call without constructing an `Agent` or reaching a network — the tool set IS
+ * the security boundary here, so it has to be directly checkable.
+ */
+export function buildSubagentTools(spec, deps, getAgent) {
+    const commTools = [
+        makeTeamSend(deps.bus, spec.label),
+        makeTeamWait(deps.bus, spec.label, {
+            getAgent,
+            maxWaitMs: deps.config.team.subagentTimeoutMs,
+        }),
+    ];
+    const tools = createBuiltinTools({
+        getCwd: deps.getCwd,
+        confirmTools: deps.confirmTools,
+        // Queued through the ONE human slot, with this child's watchdog paused for
+        // the whole queue wait (§3.11 / I-4 / P0-4).
+        ...(deps.confirmTools && deps.humanQueue
+            ? {
+                // `req.signal` is the CHILD's `ctx.signal`, carried through
+                // `ConfirmRequest` because `withConfirmation` is the only frame that
+                // holds it. Without it an abort mid-dispatch would still pop a dialog
+                // for every request left in the FIFO, one after another, at a user who
+                // has just pressed Esc — AC-16's "leaves nothing pending" would hold
+                // for the queue's unit test and not for the session.
+                confirm: (req) => deps.humanQueue.request(getAgent(), spec.label, req, req.signal),
+            }
+            : {}),
+        // `skill_find` ONLY, and this is a CORRECTNESS BOUNDARY rather than
+        // conservatism (D-16 / P0-3 / R-16). `skill_find` is a pure registry lookup.
+        // `skill` is not: `createSkillTool` calls `enterFrame()` on the registry it
+        // is handed, and the only registry in the process is the LEAD's. A child
+        // loading a skill would push a frame onto the lead's turn-scoped ceiling —
+        // narrowing what the LEAD may do once the report returns — and fire
+        // `onChange` -> `refreshSkills()` -> `rebuildSystemPrompt()`, rewriting the
+        // lead's system prompt from inside the tool call the lead is blocked in,
+        // from up to `maxConcurrent` places at once. Nothing in the child's report
+        // would show any of it.
+        //
+        // The capability is not simply dropped: the lead's always-on skill bodies
+        // are spliced into every child's system prompt below, so global skill
+        // knowledge still reaches children. A child that needs a specific skill body
+        // says so in its summary and the lead loads it.
+        //
+        // `skill_install` / `skill_create` are excluded for the original reason:
+        // they mutate the user's skill root and route to an approval gate no child
+        // can reach.
+        skillTools: deps.skillRegistry
+            ? [createSkillFindTool({ registry: deps.skillRegistry })]
+            : [],
+        // No `ask_user`, no `submit_plan`: there is no human attached to a child, and
+        // registering tools it could never use burns a turn — the same argument that
+        // keeps them out of headless mode.
+        planTools: [],
+        teamTools: commTools,
+        // `spec.readOnly` forces the plan gate on for this child even in a BUILD
+        // session. TIGHTENING ONLY (D-13): there is no field anywhere that gives a
+        // child more permission than the session it was spawned from. Read LIVE, so
+        // a mid-dispatch Shift+Tab to PLAN tightens every running child at its next
+        // tool call.
+        agentMode: () => (spec.readOnly ? 'plan' : deps.getMode()),
+        ...(deps.toolPolicy
+            ? {
+                toolPolicy: deps.toolPolicy,
+                // Decorated with the child's label, NOT the lead's raw handler (P1-3).
+                // `evaluateToolCall` returns a notice naming a tool and a skill but no
+                // agent, so three children hitting one refusal would surface three
+                // unattributable notices; and the lead's deny-escalation counter is
+                // turn-scoped, so passing it through would advance it three times for
+                // what is one refusal repeated.
+                onToolPolicyEvent: (e) => deps.onChildToolPolicyEvent?.({ ...e, label: spec.label }),
+                // The two comm tools are not in the LEAD's registered tool list, so
+                // the ceiling would refuse them and dead-end the channel.
+                policyExempt: TEAM_SUBAGENT_TOOL_NAMES,
+            }
+            : {}),
+    });
+    // Mail rides on the NEXT tool result of whatever the child does next (D-4), so
+    // every tool it can call has to carry the tail — the comm tools included, or a
+    // child that only ever messages would never receive.
+    return tools.map((t) => withMailboxTail(t, deps.bus, spec.label));
+}
+/**
+ * Construct a child and wire its instrumentation.
+ *
+ * The returned agent has NOT been prompted; `TeamRuntime` owns scheduling.
+ */
+export function createSubagent(spec, deps, hooks) {
+    const run = {
+        label: spec.label,
+        description: spec.description,
+        phase: 'queued',
+        turns: 0,
+        toolCalls: 0,
+        usage: { inputTokens: 0, outputTokens: 0 },
+        filesTouched: [],
+        messagesSent: 0,
+    };
+    // The tools have to exist before `new Agent(...)` does, so `team_wait` and the
+    // confirm queue read the agent through this holder rather than capturing it.
+    // Resolving it eagerly would capture `null` for the child's whole life and
+    // silently drop the watchdog pause (see `TeamWaitDeps.getAgent`).
+    let agentRef = null;
+    const getAgent = () => agentRef;
+    const tools = buildSubagentTools(spec, deps, getAgent);
+    const model = {
+        providerId: deps.config.provider,
+        modelId: deps.config.model,
+        ...(deps.config.baseUrl ? { baseUrl: deps.config.baseUrl } : {}),
+    };
+    const agent = deps.agentFactory({
+        systemPrompt: buildSystemPrompt({
+            cwd: deps.getCwd(),
+            tools,
+            skillsBlock: deps.alwaysBlock ?? '',
+            agentMode: spec.readOnly ? 'plan' : deps.getMode(),
+            // A child has no overlay, so the plan block must describe the headless
+            // shape: write the plan as the final message rather than calling tools it
+            // does not have.
+            planInteractive: false,
+            subagentBlock: buildSubagentBlock({
+                label: spec.label,
+                description: spec.description,
+                peers: deps.bus.peersOf(spec.label),
+            }),
+        }),
+        model,
+        tools,
+        thinkingLevel: deps.config.thinkingLevel,
+        // The LEAD's registry instance, REUSED (P2-2). It holds adapter state, and
+        // constructing five of them per dispatch is pure waste.
+        providerRegistry: deps.providerRegistry,
+        // The lead's closure, so a settings-screen key edit reaches children too.
+        getApiKey: deps.getApiKey,
+        ...(deps.config.maxTokens !== undefined ? { maxTokens: deps.config.maxTokens } : {}),
+        timeouts: {
+            toolTimeout: deps.config.toolTimeoutMs,
+            // A child keeps its OWN idle watchdog, and that is a feature: a wedged
+            // child is aborted by its own ceiling without taking the dispatch with it
+            // (§3.8). The two places a child legitimately blocks on something other
+            // than its own LLM or tool — `team_wait` and the confirm queue — pause it
+            // explicitly.
+            idleTimeout: deps.config.idleTimeoutMs,
+        },
+    });
+    agentRef = agent;
+    let lastEmit = 0;
+    let lastPhase = run.phase;
+    // The tail of the text the child is writing right now (F-1). Bounded on every
+    // append: a long turn would otherwise grow this without limit, and it is the
+    // only per-token allocation this feature adds.
+    let textTail = '';
+    const emit = () => {
+        const now = Date.now();
+        // Phase transitions always pass; everything else is coalesced. Five children
+        // streaming tokens must not push five React renders per token, and the
+        // streaming coalescer in `App.tsx` protects the transcript, not this path.
+        if (run.phase === lastPhase && now - lastEmit < TEAM_LIMITS.agentUpdateThrottleMs)
+            return;
+        lastPhase = run.phase;
+        lastEmit = now;
+        // Exactly one sanitize per PUBLISHED frame rather than one per token (P2-2):
+        // `emit()` throws away all but one result per throttle window, so two
+        // regexes per token would be paid for a value nobody reads. `textTail` is
+        // cleared on `turn_start` and `tool_execution_end`, so an empty tail is how
+        // "not writing anything right now" is expressed.
+        run.activity =
+            textTail.length > 0 ? sanitizeActivity(textTail, TEAM_LIMITS.activityChars) : undefined;
+        hooks.onUpdate({ ...run, filesTouched: [...run.filesTouched] });
+    };
+    const noteFile = (toolName, args) => {
+        if (toolName !== 'write_file' && toolName !== 'edit_file')
+            return;
+        const path = args?.path;
+        if (typeof path !== 'string' || path.length === 0)
+            return;
+        if (run.filesTouched.includes(path))
+            return;
+        if (run.filesTouched.length >= TEAM_LIMITS.filesTouchedMax)
+            return;
+        run.filesTouched.push(path);
+    };
+    const unsubscribe = agent.subscribe((event) => {
+        switch (event.type) {
+            case 'turn_start':
+                run.phase = 'thinking';
+                textTail = '';
+                run.activity = undefined; // a new turn is not the last turn's work
+                run.activityArgs = undefined;
+                break;
+            case 'turn_end': {
+                run.turns += 1;
+                run.usage = {
+                    inputTokens: run.usage.inputTokens + event.usage.inputTokens,
+                    outputTokens: run.usage.outputTokens + event.usage.outputTokens,
+                };
+                hooks.onUsage(spec.label, event.usage);
+                const text = assistantText(event.message);
+                // The LAST non-empty assistant text wins, which is exactly the child's
+                // final message once the loop stops calling tools. Capturing it here
+                // rather than parsing `agent_end.messages` keeps a partial summary from
+                // an aborted run, which the report renders as partial rather than lost.
+                if (text.length > 0)
+                    run.summary = text;
+                if (run.turns >= deps.config.team.maxTurnsPerSubagent) {
+                    run.truncated = true;
+                    agent.abort();
+                }
+                break;
+            }
+            case 'tool_execution_start':
+                run.phase = event.toolName === 'team_wait' ? 'waiting' : 'tool';
+                run.lastTool = event.toolName;
+                run.toolCalls += 1;
+                textTail = '';
+                run.activity = undefined; // prose is stale now
+                run.activityArgs = pickActivityArgs(event.args); // PICKED, not raw (P1-4)
+                noteFile(event.toolName, event.args);
+                break;
+            case 'tool_execution_end':
+                run.phase = 'thinking';
+                textTail = '';
+                run.activity = undefined;
+                // CLEARED, like `activity` (P1-5). Leaving it set would keep the picked
+                // strings alive for the whole run and past it - `publish()` copies the
+                // run into the snapshot and into every event, and `dispatch()` copies it
+                // into the outcome the transcript holds - for a value nothing renders
+                // once the phase is back to `thinking`.
+                run.activityArgs = undefined;
+                // Read from the BUS, not counted from tool calls: a refused send is an
+                // attempt, not a message, and the panel's `mail N` readout has to agree
+                // with what the recipients actually received.
+                if (event.toolName === 'team_send')
+                    run.messagesSent = deps.bus.sentCount(spec.label);
+                if (event.toolName === 'team_wait') {
+                    run.blockedWaits = deps.bus.blockedWaitCount(spec.label);
+                }
+                break;
+            case 'message_update':
+                if (event.streamEvent.type === 'error') {
+                    run.error = formatStreamError(event.streamEvent.error);
+                    run.retryable = isRetryableStreamError(event.streamEvent.error);
+                }
+                else if (event.streamEvent.type === 'text_delta') {
+                    // O(1) per delta: one bounded concat and one bounded slice, and
+                    // NOTHING else. The sanitize happens once per emitted frame instead,
+                    // inside `emit()` above (P2-2).
+                    textTail = (textTail + event.streamEvent.delta).slice(-TEAM_LIMITS.activityTailChars);
+                }
+                break;
+            default:
+                break;
+        }
+        emit();
+    });
+    return { spec, run, agent, tools, unsubscribe };
+}

package/dist/team/task-tool.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `task` — the delegation tool, registered on a LEAD only (team-subagents §3.3 /
+ * §4.1).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * THE BATCH SHAPE IS FORCED BY THE CORE LOOP, NOT CHOSEN FOR TASTE (D-1 / I-1 /
+ * R-1). `agent-loop.ts` executes tool calls in a `for...of` with an `await`
+ * inside, strictly sequentially, so N single-spec `task` calls would produce N
+ * SERIAL subagents — the exact opposite of this feature. Making that loop
+ * concurrent is not an available fix: plan mode pins the sequencing as invariant
+ * I-P11, because the human-input bridge holds ONE outstanding request slot and
+ * is correct only while tool calls never overlap. Breaking it would silently
+ * mis-route a plan approval to a question wizard. So the fan-out lives inside
+ * one tool call, where the scheduling is ours.
+ *
+ * THE SCHEMA DECLARES SHAPE, NOT POLICY (§3.3.1). Every bound lives in the
+ * `description` — which is what the model reads — and is enforced by
+ * `normalizeSubagentSpecs`, which is deterministic and unit-tested. `maxItems`
+ * in the schema would behave differently depending on whether `ajv`, an OPTIONAL
+ * dependency of core, happened to install.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { ModelCost } from '@aragon-agent/core';
+import type { TeamRuntime } from './runtime.js';
+export interface TaskToolDeps {
+    runtime: TeamRuntime;
+    /** Read LIVE, never cached: `/team off` flips this, it does not unregister. */
+    isTeamEnabled: () => boolean;
+    maxSubagents: () => number;
+    /** Whether a usable key exists for the active provider right now (P2-3). */
+    hasApiKey: () => boolean;
+    activeProvider: () => string;
+    /** The lead's cost table, so the report header states real spend (R-5). */
+    modelCost: () => ModelCost | undefined;
+    /**
+     * Run the dispatch with the LEAD's idle watchdog paused, `try/finally` inside.
+     *
+     * THE SINGLE MOST LIKELY WAY TO SHIP THIS FEATURE BROKEN (I-3 / R-3). The
+     * watchdog fires on EVENT SILENCE, not on inactivity, and a lead blocked
+     * inside `task` emits nothing — so a six-minute dispatch under the default
+     * 210 s `idleTimeoutMs` is aborted at 210 s with `[Agent] idle watchdog fired`
+     * on stderr and no other explanation.
+     */
+    withPausedWatchdog: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+export declare function createTaskTool(deps: TaskToolDeps): AgentTool;

package/dist/team/task-tool.js

@@ -0,0 +1,118 @@
+/**
+ * `task` — the delegation tool, registered on a LEAD only (team-subagents §3.3 /
+ * §4.1).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * THE BATCH SHAPE IS FORCED BY THE CORE LOOP, NOT CHOSEN FOR TASTE (D-1 / I-1 /
+ * R-1). `agent-loop.ts` executes tool calls in a `for...of` with an `await`
+ * inside, strictly sequentially, so N single-spec `task` calls would produce N
+ * SERIAL subagents — the exact opposite of this feature. Making that loop
+ * concurrent is not an available fix: plan mode pins the sequencing as invariant
+ * I-P11, because the human-input bridge holds ONE outstanding request slot and
+ * is correct only while tool calls never overlap. Breaking it would silently
+ * mis-route a plan approval to a question wizard. So the fan-out lives inside
+ * one tool call, where the scheduling is ours.
+ *
+ * THE SCHEMA DECLARES SHAPE, NOT POLICY (§3.3.1). Every bound lives in the
+ * `description` — which is what the model reads — and is enforced by
+ * `normalizeSubagentSpecs`, which is deterministic and unit-tested. `maxItems`
+ * in the schema would behave differently depending on whether `ajv`, an OPTIONAL
+ * dependency of core, happened to install.
+ */
+import { errorResult, textResult } from '@aragon-agent/core';
+import { TEAM_LIMITS } from './limits.js';
+import { normalizeSubagentSpecs } from './normalize.js';
+import { buildDispatchReport } from './report.js';
+const BUSY_REFUSAL = 'A team dispatch is already running. Wait for its report before starting another.';
+const TEAM_OFF_REFUSAL = 'Team mode is off for this session. Do this work yourself, in order.';
+/**
+ * The model-facing description. Deliberately close to Claude Code's `Task` tool
+ * (R-f): what a model already knows about that transfers directly, and the one
+ * visible difference — the batch — is stated in the first sentence.
+ */
+const TASK_DESCRIPTION = 'Run several independent subagents in parallel and get one combined report. Each ' +
+    'subagent is a fresh agent with the same tools and working directory but NO memory of ' +
+    'this conversation - its prompt must be self-contained. Use this when a task splits ' +
+    'into 2 or more parts that do not depend on each other\'s output, especially reading or ' +
+    'searching several areas at once. Do NOT use it when one part needs another part\'s ' +
+    'result (do those yourself, in order), when two parts would edit the same file, or for ' +
+    'a change small enough to just make. Subagents cannot dispatch further subagents and ' +
+    'cannot ask the user anything. Give each a description of at most ' +
+    `${TEAM_LIMITS.descriptionChars} characters and a complete prompt. Extra entries beyond the ` +
+    'configured maximum are dropped, so keep within it.';
+export function createTaskTool(deps) {
+    return {
+        name: 'task',
+        label: 'Dispatch subagents',
+        description: TASK_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                subagents: {
+                    type: 'array',
+                    description: `2-5 independent subagents to run in parallel (hard maximum ${TEAM_LIMITS.hardMaxSubagents}; ` +
+                        'extras are dropped).',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: {
+                                type: 'string',
+                                description: `Short id, <= ${TEAM_LIMITS.labelChars} chars, e.g. "api". Shown in the UI.`,
+                            },
+                            description: {
+                                type: 'string',
+                                description: `<= ${TEAM_LIMITS.descriptionChars} chars. What this subagent is for.`,
+                            },
+                            prompt: {
+                                type: 'string',
+                                description: 'The full brief. Self-contained: the subagent cannot see this conversation.',
+                            },
+                            readOnly: {
+                                type: 'boolean',
+                                default: false,
+                                description: 'Refuse all writes and shell for this subagent.',
+                            },
+                        },
+                        required: ['description', 'prompt'],
+                    },
+                },
+            },
+            required: ['subagents'],
+        },
+        async execute(_id, params, ctx) {
+            // 1. Already dispatching. Unreachable while I-1 holds; present so the
+            //    guarantee belongs to this module (R-14).
+            if (deps.runtime.isBusy())
+                return textResult(BUSY_REFUSAL);
+            // 2. Turned off mid-session. `task` is registered ONCE at construction and
+            //    the array is immutable (§4.5 / D-17), so `/team off` cannot
+            //    unregister it — it flips this closure instead. Read live, never
+            //    cached.
+            if (!deps.isTeamEnabled())
+                return textResult(TEAM_OFF_REFUSAL);
+            // 3. No usable key (P2-3). `preflight()` runs before the LOOP, not before
+            //    a tool call, so a key emptied through the settings screen mid-session
+            //    would otherwise produce N identical stream failures — N times the
+            //    cost of one refusal, and a report the model may well retry.
+            if (!deps.hasApiKey()) {
+                return textResult(`Team dispatch skipped: no API key for ${deps.activeProvider()}. Do this work ` +
+                    'yourself, or ask the user to set a key.');
+            }
+            // 4. Repair, never reject. Zero survivors is the single hard failure.
+            const { specs, requested } = normalizeSubagentSpecs(params.subagents, deps.maxSubagents());
+            if (specs.length === 0) {
+                return errorResult('No usable subagent specs: each needs a description and a prompt.');
+            }
+            // 5. Pause the lead's watchdog for the whole dispatch (I-3).
+            const outcome = await deps.withPausedWatchdog(() => deps.runtime.dispatch(specs, requested, ctx.signal));
+            // 6. ALWAYS A NON-ERROR RESULT, abort and all-children-failed included.
+            //    A cancellation or a partial result rendered as a tool FAILURE invites
+            //    the model to retry the whole fan-out, which is the most expensive
+            //    possible reaction (the same reasoning as `ask_user`'s cancelled
+            //    shape, and D-14 one level up).
+            const cost = deps.modelCost();
+            return textResult(buildDispatchReport(outcome, cost ? { cost } : {}));
+        },
+    };
+}