@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/team/forced-dispatch.js

@@ -0,0 +1,208 @@
+/**
+ * `/subagent` — parse the user's arguments and compile them into ONE user turn
+ * (subagent-fanout 3.5.2 / 3.5.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and this module
+ * also produces text a model reads in a `cmd.exe` terminal.
+ *
+ * WHY A PROMPT AND NOT A DIRECT `dispatch()` CALL (D-8 / 3.5.1, option C). The
+ * alternative — the command splits the brief itself and calls
+ * `TeamRuntime.dispatch()` — needs a SECOND dispatch entry point (breaking I-1),
+ * a run lifecycle the command does not own (Esc, the lead's idle watchdog, the
+ * report rendered into the transcript, spend accounting, the concurrency lock),
+ * and a planner that cannot see the conversation. Compiling the user's intent
+ * into a normal user turn keeps all of that on the one path that already has it.
+ * The cost is that forcing is INSTRUCTION-LEVEL rather than mechanical, which is
+ * why the command body prints a plan ("the next turn dispatches them") instead
+ * of claiming results (D-10).
+ *
+ * TWO PURE FUNCTIONS, NO IO: parse and compile. Both are deterministic, so the
+ * whole surface is unit-testable without a terminal, a config file or a model.
+ */
+import { TEAM_LIMITS } from './limits.js';
+import { toSlug } from './normalize.js';
+/**
+ * Bumped whenever the directive's wording changes; the string appears VERBATIM
+ * on the directive's first line so a behaviour report ties to one revision with
+ * a single grep (D-15). The `-YYYY-MM` suffix is part of the version, not a
+ * comment: `v1` alone is easy to confuse with the other counters in this package.
+ */
+export const FORCED_DISPATCH_VERSION = 'v1-2026-10';
+/**
+ * A DECIMAL POSITIVE INTEGER, and nothing else.
+ *
+ * `0` is deliberately NOT accepted (R-P1-2). Writing `/subagent -n 0` means the
+ * user mistyped; silently clamping it to 1 would rewrite their intent, which is
+ * the one thing a clamp must never do. `-n 12` is different: 12 is unambiguous
+ * and merely exceeds the ceiling, so it is accepted and DISCLOSED as narrowed.
+ */
+const COUNT_PATTERN = /^[1-9][0-9]*$/;
+/** The flag name of a token, or `null` for a plain word (part of the brief). */
+function flagName(word) {
+    if (word.length < 2 || !word.startsWith('-'))
+        return null;
+    return word.replace(/^--?/, '').toLowerCase();
+}
+/** The brief, clipped with a VISIBLE marker (`forcedBriefChars`). */
+function clippedBrief(brief) {
+    const limit = TEAM_LIMITS.forcedBriefChars;
+    return brief.length > limit ? `${brief.slice(0, limit)}\n[brief truncated]` : brief;
+}
+/**
+ * Parse `/subagent` arguments. ONE parameter (R-P1-1): the structural bounds are
+ * constants this module imports, not a caller's opinion.
+ *
+ * NEVER THROWS and never guesses. Every malformed input maps to one of the four
+ * errors the command body has a sentence for, because "we did something
+ * reasonable with your typo" is indistinguishable from a bug at the terminal.
+ */
+export function parseSubagentArgs(raw) {
+    const words = raw.split(/\s+/).filter((word) => word.length > 0);
+    const brief = [];
+    const parts = [];
+    let count = null;
+    let readOnly = false;
+    // `--parts` was SEEN, even if every item it carried cleaned away. The conflict
+    // rule is about the two flags appearing together, not about the usable parts
+    // that survived: `-n 3 --parts ,,,` still names two sources for one number, and
+    // silently obeying the count would drop a flag the user typed.
+    let sawParts = false;
+    for (let index = 0; index < words.length;) {
+        const word = words[index];
+        const flag = flagName(word);
+        if (flag === null) {
+            brief.push(word);
+            index += 1;
+            continue;
+        }
+        if (flag === 'n' || flag === 'count') {
+            const value = words[index + 1];
+            if (value === undefined || !COUNT_PATTERN.test(value))
+                return { ok: false, error: 'count' };
+            count = Number(value);
+            index += 2;
+            continue;
+        }
+        if (flag === 'parts') {
+            const value = words[index + 1];
+            // A flag with no value is unusable rather than guessable, so it is
+            // reported as a bad option instead of being read as "no parts, then".
+            if (value === undefined)
+                return { ok: false, error: 'flag', token: word };
+            sawParts = true;
+            // A part that cleans to nothing is DROPPED rather than kept as an empty
+            // label; if every part cleans away the flag is treated as absent, because
+            // an empty part list cannot narrow a dispatch the brief still describes.
+            for (const item of value.split(',')) {
+                const slug = toSlug(item);
+                if (slug.length > 0 && !parts.includes(slug))
+                    parts.push(slug);
+            }
+            index += 2;
+            continue;
+        }
+        if (flag === 'read-only') {
+            readOnly = true;
+            index += 1;
+            continue;
+        }
+        // `-n=6` lands here: ONE spelling per option, so the `=` form is an unknown
+        // token rather than a second grammar with its own edge cases.
+        return { ok: false, error: 'flag', token: word };
+    }
+    // Count and parts answer the same question, so a request carrying both is
+    // refused instead of resolved in one direction the user did not choose.
+    if (count !== null && sawParts)
+        return { ok: false, error: 'conflict' };
+    const text = brief.join(' ').trim();
+    if (text.length === 0)
+        return { ok: false, error: 'brief' };
+    return {
+        ok: true,
+        args: {
+            brief: text,
+            count,
+            parts: parts.slice(0, TEAM_LIMITS.forcedPartsMax),
+            partsRequested: parts.length,
+            readOnly,
+        },
+    };
+}
+/**
+ * The sentence naming how many children to start.
+ *
+ * THE PERMISSION CLAUSE IS NOT OPTIONAL IN EITHER BRANCH. `--parts` REPLACES the
+ * count sentence, so a `readOnly` qualifier written only into the count branch
+ * disappears exactly when both flags are used - and `/subagent --read-only
+ * --parts api,ui <brief>` is one of the three examples the README advertises. The
+ * children would then be writeable while the notice said a read-only fan-out was
+ * forced (AC-13).
+ */
+function callSentence(request) {
+    const { count, readOnly, parts } = request;
+    if (parts.length > 0) {
+        const labels = 'Use those exact labels';
+        return `Call the \`task\` tool ONCE with one subagent per part: ${parts.join(', ')}. `
+            + (readOnly ? `${labels}; every spec readOnly: true.` : `${labels}.`);
+    }
+    const noun = count === 1 ? 'subagent' : 'subagents';
+    const permission = readOnly ? ', all readOnly: true' : '';
+    return `Call the \`task\` tool ONCE with exactly ${count} ${noun}${permission}.`;
+}
+/**
+ * The ONE user turn a `/subagent` invocation submits. Same input, same bytes -
+ * which is what makes the snapshot tests meaningful.
+ *
+ * THE ORDER OF THE SENTENCES IS THE ORDER OF THE MODEL'S DECISIONS: what to do
+ * (call `task` ONCE), what it must not do instead (work alone), then the lucky
+ * case (the brief does not split), then the brief itself, then the disclosure
+ * lines, then the per-spec rules.
+ */
+export function buildForcedDirective(request) {
+    const { brief, count, parts, maxSubagents, clamped, requested, planMode } = request;
+    // ONE SENTENCE PER LINE, and deliberately not hard-wrapped: the contract in
+    // 6.4 is checked by grepping phrases (`Call the `task` tool ONCE`, `Use those
+    // exact labels`), and a wrapper that split one of them across a newline would
+    // make the document and the artifact disagree about the same bytes.
+    const lines = [
+        `[forced team dispatch ${FORCED_DISPATCH_VERSION}] The user is forcing a parallel team `
+            + 'on this brief.',
+        callSentence(request),
+        'Then act on the combined report. Do not do the work yourself; the subagents exist to do it.',
+    ];
+    // NO "at least 2" FALLBACK FOR A SINGLE CHILD (R-P1-4): a sentence asking for
+    // at least two would be the louder instruction in a directive that asked for
+    // exactly one, and the model would follow it.
+    if (count > 1 && parts.length === 0) {
+        lines.push(`If the brief genuinely cannot be split into ${count} independent parts, use as many `
+            + 'as it splits into (at least 2) and say why in one line.');
+    }
+    lines.push('', 'Brief:', clippedBrief(brief), '');
+    // A PARTS LIST CAN BE NARROWED BY TWO DIFFERENT CEILINGS (R-P1-3), and the
+    // spec's sentence - "the configured maximum is N" - is only true when the
+    // POLICY ceiling is the one that bit. `parts.length >= maxSubagents` says it
+    // is; below that the structural `forcedPartsMax` did the cutting, and naming
+    // the configured maximum would point the user at a number they can change to
+    // fix a limit they cannot.
+    if (clamped) {
+        if (parts.length > 0) {
+            lines.push(parts.length >= maxSubagents
+                ? `You asked for ${requested} parts; the configured maximum is ${maxSubagents}, `
+                    + 'so the remaining parts are folded into these.'
+                : `You asked for ${requested} parts; only ${parts.length} fit in one directive, `
+                    + 'so the remaining parts are folded into these.');
+        }
+        else {
+            lines.push(`You asked for ${requested}; the configured maximum is ${maxSubagents}, `
+                + `so use ${count}.`);
+        }
+    }
+    if (planMode) {
+        lines.push('Plan mode is on; if the task tool is unavailable this turn, say so instead of '
+            + 'doing the work alone.');
+    }
+    lines.push('Rules for each spec: a self-contained prompt (the child has no memory of this '
+        + `conversation), a description of at most ${TEAM_LIMITS.descriptionChars} chars, a short `
+        + 'slug label, and a disjoint set of files per child.');
+    return lines.join('\n');
+}

package/dist/team/limits.d.ts

@@ -29,6 +29,11 @@ export declare const TEAM_LIMITS: {
      * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
      * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
      * for thirty can exceed it.
+     *
+     * 10 IS THE CEILING, 8 IS THE DEFAULT (`DEFAULT_TEAM_CONFIG`): different
+     * numbers on purpose (subagent-fanout D-1 / D-2). The default is a policy
+     * choice the user may move in either direction from the settings screen; this
+     * bound is what no user may move.
      */
     readonly hardMaxSubagents: 10;
     /** `SubagentSpec.description`, clamped (never rejected). */
@@ -36,6 +41,21 @@ export declare const TEAM_LIMITS: {
     /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
      *  this has to be generous enough to carry a whole brief. */
     readonly promptChars: 8000;
+    /**
+     * The brief `/subagent <brief>` copies into its forced-directive turn
+     * (subagent-fanout 3.5.4 / R-10). CHARACTERS, not bytes, because this bound
+     * feeds a user-visible truncation marker rather than a wire budget: past it
+     * the directive says `[brief truncated]` so a clipped instruction is never
+     * mistaken for a complete one.
+     */
+    readonly forcedBriefChars: 4000;
+    /**
+     * Parts `/subagent --parts a,b,c` may name BEFORE `maxSubagents` narrows them
+     * (subagent-fanout 3.5.2 rule 3). The second, smaller ceiling is the policy
+     * number and belongs to the command body; this one only bounds what one
+     * argument can carry.
+     */
+    readonly forcedPartsMax: 8;
     /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
      *  short enough that five of them fit one row of an 80-column terminal. */
     readonly labelChars: 12;
@@ -245,4 +265,4 @@ export declare const TEAM_SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
  * Bumped whenever the wording of either prompt block changes, so a behaviour
  * report can be tied to a block revision with one grep.
  */
-export declare const TEAM_BLOCK_VERSION = "v1-2026-07";
+export declare const TEAM_BLOCK_VERSION = "v2-2026-10";

package/dist/team/limits.js

@@ -36,6 +36,11 @@ export const TEAM_LIMITS = {
      * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
      * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
      * for thirty can exceed it.
+     *
+     * 10 IS THE CEILING, 8 IS THE DEFAULT (`DEFAULT_TEAM_CONFIG`): different
+     * numbers on purpose (subagent-fanout D-1 / D-2). The default is a policy
+     * choice the user may move in either direction from the settings screen; this
+     * bound is what no user may move.
      */
     hardMaxSubagents: HARD_MAX_SUBAGENTS,
     // --- Spec normalization (§3.3.1) ---
@@ -44,6 +49,21 @@ export const TEAM_LIMITS = {
     /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
      *  this has to be generous enough to carry a whole brief. */
     promptChars: 8000,
+    /**
+     * The brief `/subagent <brief>` copies into its forced-directive turn
+     * (subagent-fanout 3.5.4 / R-10). CHARACTERS, not bytes, because this bound
+     * feeds a user-visible truncation marker rather than a wire budget: past it
+     * the directive says `[brief truncated]` so a clipped instruction is never
+     * mistaken for a complete one.
+     */
+    forcedBriefChars: 4000,
+    /**
+     * Parts `/subagent --parts a,b,c` may name BEFORE `maxSubagents` narrows them
+     * (subagent-fanout 3.5.2 rule 3). The second, smaller ceiling is the policy
+     * number and belongs to the command body; this one only bounds what one
+     * argument can carry.
+     */
+    forcedPartsMax: 8,
     /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
      *  short enough that five of them fit one row of an 80-column terminal. */
     labelChars: 12,
@@ -259,4 +279,4 @@ export const TEAM_SUBAGENT_TOOL_NAMES = new Set(['team_send', 'team_wait']);
  * Bumped whenever the wording of either prompt block changes, so a behaviour
  * report can be tied to a block revision with one grep.
  */
-export const TEAM_BLOCK_VERSION = 'v1-2026-07';
+export const TEAM_BLOCK_VERSION = 'v2-2026-10';

package/dist/team/normalize.d.ts

@@ -30,6 +30,21 @@ export interface NormalizedSpecs {
     /** How many entries the model asked for, before dropping and capping. */
     requested: number;
 }
+/**
+ * The slug rule for a subagent label, EXPORTED because a second caller needs the
+ * same bytes: `/subagent --parts api,UI,tests` cleans its parts through this
+ * function rather than through a copy of the regex (subagent-fanout R-9 /
+ * R-P1-6). Two copies of `[^a-z0-9-]` would drift the first time either side
+ * gains a rule, and the user would see `UI` accepted by one and rewritten by the
+ * other.
+ *
+ * MAY RETURN THE EMPTY STRING. That is the difference from `slugLabel` below:
+ * an empty result is meaningful here ("this part cleans to nothing, drop it"),
+ * whereas a spec's label needs the positional fallback so a child is never
+ * nameless in the panel. The fallback is therefore the CALLER's decision, and
+ * this function stays a pure transformation.
+ */
+export declare function toSlug(raw: unknown): string;
 /**
  * Repair and bound a raw `subagents` array.
  *

package/dist/team/normalize.js

@@ -33,16 +33,33 @@ function clamp(text, maxChars) {
     return trimmed.length > maxChars ? trimmed.slice(0, maxChars) : trimmed;
 }
 /**
- * Slugify a label to `[a-z0-9-]{1,12}`. An empty result falls back to the
- * positional default so a child is never nameless in the panel.
+ * The slug rule for a subagent label, EXPORTED because a second caller needs the
+ * same bytes: `/subagent --parts api,UI,tests` cleans its parts through this
+ * function rather than through a copy of the regex (subagent-fanout R-9 /
+ * R-P1-6). Two copies of `[^a-z0-9-]` would drift the first time either side
+ * gains a rule, and the user would see `UI` accepted by one and rewritten by the
+ * other.
+ *
+ * MAY RETURN THE EMPTY STRING. That is the difference from `slugLabel` below:
+ * an empty result is meaningful here ("this part cleans to nothing, drop it"),
+ * whereas a spec's label needs the positional fallback so a child is never
+ * nameless in the panel. The fallback is therefore the CALLER's decision, and
+ * this function stays a pure transformation.
  */
-function slugLabel(raw, index) {
-    const slug = asString(raw)
+export function toSlug(raw) {
+    return asString(raw)
         .trim()
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, '-')
         .replace(/^-+|-+$/g, '')
         .slice(0, TEAM_LIMITS.labelChars);
+}
+/**
+ * Slugify a label to `[a-z0-9-]{1,12}`. An empty result falls back to the
+ * positional default so a child is never nameless in the panel.
+ */
+function slugLabel(raw, index) {
+    const slug = toSlug(raw);
     return slug.length > 0 ? slug : `a${index + 1}`;
 }
 /**

package/dist/team/prompt.d.ts

@@ -24,10 +24,13 @@ export interface TeamBlockParams {
  * for on EVERY turn of every team-enabled session, so anything that does not
  * change a delegation decision does not belong in it.
  *
- * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * "Two to four is usually enough" is where the requirement's "shu liang zi shi
  * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
- * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
- * that informs it.
+ * elsewhere (`team.maxSubagents`, quoted in the first paragraph); the CHOICE is
+ * the model's, and this paragraph is the only thing that informs it. It names a
+ * USUAL size rather than the maximum on purpose: the default fan-out moved to 8
+ * (subagent-fanout D-1), and a block that told the model "eight is normal"
+ * would turn every two-part job into an eight-agent bill.
  */
 export declare function buildTeamBlock(params: TeamBlockParams): string;
 export interface SubagentBlockParams {

package/dist/team/prompt.js

@@ -20,10 +20,13 @@ export { TEAM_BLOCK_VERSION };
  * for on EVERY turn of every team-enabled session, so anything that does not
  * change a delegation decision does not belong in it.
  *
- * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * "Two to four is usually enough" is where the requirement's "shu liang zi shi
  * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
- * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
- * that informs it.
+ * elsewhere (`team.maxSubagents`, quoted in the first paragraph); the CHOICE is
+ * the model's, and this paragraph is the only thing that informs it. It names a
+ * USUAL size rather than the maximum on purpose: the default fan-out moved to 8
+ * (subagent-fanout D-1), and a block that told the model "eight is normal"
+ * would turn every two-part job into an eight-agent bill.
  */
 export function buildTeamBlock(params) {
     const max = Math.max(1, Math.floor(params.maxSubagents));
@@ -39,8 +42,9 @@ export function buildTeamBlock(params) {
         '',
         'Do not delegate when: one part needs another part\'s result (do those in order',
         'yourself); two parts would edit the same file; the whole job is a few edits.',
-        'One well-scoped subagent is better than four vague ones. Two to four is the',
-        'usual size; more than that is rarely faster.',
+        'One well-scoped subagent is better than four vague ones. Two to four is',
+        'usually enough; go wider only when the parts are genuinely independent - a',
+        'narrow fan-out is cheaper and easier to read.',
         '',
         'Each subagent starts with no memory of this conversation, so its prompt must',
         'carry everything it needs: the goal, the files or areas it owns, and what to',

package/dist/team/runtime.d.ts

@@ -36,6 +36,7 @@ import type { TeamHumanQueue } from './human-queue.js';
 import { type OverseerProvider } from './overseer.js';
 import { type SubagentAgentFactory, type SubagentDeps } from './subagent.js';
 import type { DispatchOutcome, SubagentSpec, TeamEventListener, TeamSnapshot } from './types.js';
+import type { ToolGate } from '../tools/tool-gate.js';
 export interface TeamRuntimeDeps {
     /** Read LIVE: a settings-screen model or key edit must reach the next dispatch. */
     getConfig: () => CliConfig;
@@ -64,6 +65,14 @@ export interface TeamRuntimeDeps {
         sourceNames: string[];
     }) => void;
     humanQueue?: TeamHumanQueue;
+    /**
+     * The lead's caller-approval gate, one instance per child (headless-host-bridge
+     * section 2.3.7). Absent outside bridge mode, which is what keeps a dispatch's
+     * tool arrays identical to today's everywhere else.
+     */
+    toolGateFor?: (label: string) => ToolGate;
+    /** The two-phase executor ceiling for a gated tool; see `gatedToolTimeouts`. */
+    decisionBudgetMs?: number;
     /** Test seam (§8.1): a stub factory keeps the whole scheduler off the network. */
     agentFactory?: SubagentAgentFactory;
     /**

package/dist/team/runtime.js

@@ -465,6 +465,14 @@ export class TeamRuntime {
                 : {}),
             confirmTools: config.confirmTools,
             ...(this.deps.humanQueue ? { humanQueue: this.deps.humanQueue } : {}),
+            // Site two of two, in the same shape as the policy and compaction lines
+            // around it: declaring it on `TeamRuntimeDeps` and forgetting this line
+            // type-checks and forwards nothing, and the failure is silent - every child
+            // would run unapproved while the caller believes it is approving.
+            ...(this.deps.toolGateFor ? { toolGateFor: this.deps.toolGateFor } : {}),
+            ...(this.deps.decisionBudgetMs !== undefined
+                ? { decisionBudgetMs: this.deps.decisionBudgetMs }
+                : {}),
             agentFactory: this.deps.agentFactory ?? defaultSubagentFactory,
             ...(this.deps.review ? { review: this.deps.review } : {}),
             // Site two of two, and the omission is silent in the same way the policy

package/dist/team/subagent.d.ts

@@ -14,6 +14,7 @@ import type { ModelRole } from '../config/model-profiles.js';
 import { type AgentConfig, type AgentEvent, type AgentTool, type Message, type ProviderRegistry, type SkillRegistry, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { ChildContextManagerProvider } from '../compaction/child.js';
+import type { ToolGate } from '../tools/tool-gate.js';
 import type { CliConfig } from '../config/schema.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { ChildReviewProvider } from './child-reviewer.js';
@@ -123,6 +124,20 @@ export interface SubagentDeps {
      * `CompactionWiring.childFactory()`, which returns `null` when the key is off.
      */
     contextManagerFor?: ChildContextManagerProvider;
+    /**
+     * The caller's approval gate for THIS child (headless-host-bridge section 2.3.7).
+     *
+     * A FACTORY, NOT A GATE: every child gets its own instance because the scope -
+     * `{id,label,depth}` - is what tells the caller which subagent is asking, and one
+     * shared instance would report every child as the lead. The pending table behind
+     * it IS shared, so the capacity ceiling counts a whole fan-out together.
+     *
+     * ABSENT EVERYWHERE BUT BRIDGE MODE, which is what keeps a child's tool array
+     * identical to today's for `-p`, the TUI and every non-bridged dispatch.
+     */
+    toolGateFor?: (label: string) => ToolGate;
+    /** Added to each gated tool's executor timeout; see `gatedToolTimeouts`. */
+    decisionBudgetMs?: number;
 }
 export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */

package/dist/team/subagent.js

@@ -14,7 +14,7 @@ import { Agent, createSkillFindTool, } from '@aragon-agent/core';
 import { formatStreamError } from '../agent/reducer.js';
 import { buildSystemPrompt } from '../agent/system-prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
-import { createBuiltinTools } from '../tools/index.js';
+import { createBuiltinTools, gatedToolTimeouts, } from '../tools/index.js';
 import { describeToolActivity, pickActivityArgs, sanitizeActivity } from './activity.js';
 import { TEAM_LIMITS, TEAM_SUBAGENT_TOOL_NAMES } from './limits.js';
 import { appendTimeline } from './timeline.js';
@@ -24,6 +24,26 @@ 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);
+/**
+ * Hold a child's idle watchdog across a caller wait.
+ *
+ * The child's watchdog is its own (that is the point of a separate ceiling), so a
+ * four-minute approval would otherwise abort the child and take the dispatch with
+ * it - R-1, one level down. `finally` is what makes "paused" never outlive the
+ * wait, including on an abort.
+ */
+function pauseChildWatchdog(getAgent) {
+    return async (fn) => {
+        const agent = getAgent();
+        agent?.pauseIdleWatchdog();
+        try {
+            return await fn();
+        }
+        finally {
+            agent?.resumeIdleWatchdog();
+        }
+    };
+}
 /** The final assistant text of a turn, or `''` when the turn was tool calls only. */
 function assistantText(message) {
     if (!message || !Array.isArray(message.content))
@@ -59,6 +79,21 @@ export function buildSubagentTools(spec, deps, getAgent) {
     const tools = createBuiltinTools({
         getCwd: deps.getCwd,
         confirmTools: deps.confirmTools,
+        // THE CHILD ASKS THE CALLER TOO (section 2.3.7). Without this the approval
+        // gate would hold for the lead and be bypassed by one `task` call - the hole
+        // the `--deny-tool` pass-through above records, one feature later and with a
+        // human on the other end of it who believes they are approving everything.
+        //
+        // The watchdog pause is the CHILD'S OWN, never `TeamHumanQueue`'s: that queue
+        // is `--confirm`'s, and nesting a second pause is exactly what
+        // `withPausedWatchdog` forbids. `getAgent()` is the same live handle the queue
+        // and `team_wait` already use.
+        ...(deps.toolGateFor
+            ? {
+                toolGate: deps.toolGateFor(spec.label),
+                withToolWait: pauseChildWatchdog(getAgent),
+            }
+            : {}),
         // 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
@@ -253,6 +288,15 @@ export function createSubagent(spec, deps, hooks) {
         ...(deps.config.maxTokens !== undefined ? { maxTokens: deps.config.maxTokens } : {}),
         timeouts: {
             toolTimeout: deps.config.toolTimeoutMs,
+            // THE SAME TWO PHASES THE LEAD GETS (section 2.3.4). A child that asks the
+            // caller and waits is billed for the wait out of its tool's budget unless
+            // this is here, and the symptom would be "the approved command was killed
+            // mid-run" only inside a fan-out.
+            ...(deps.toolGateFor && deps.decisionBudgetMs !== undefined
+                ? {
+                    toolTimeoutOverrides: gatedToolTimeouts(deps.config.toolTimeoutMs, deps.decisionBudgetMs),
+                }
+                : {}),
             // 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

package/dist/team/task-tool.js

@@ -49,11 +49,11 @@ const TASK_DESCRIPTION = 'Run several independent subagents in parallel and get
     '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. A supervisor watches the ' +
-    'fan-out: a child that stalls or runs very long may be nudged with guidance ' +
-    'or replaced by a fresh attempt, and the report\'s Supervisor section ' +
-    'records every intervention.';
+    `${TEAM_LIMITS.descriptionChars} characters and a complete prompt. The current fan-out ` +
+    'maximum and concurrency are stated in <team_mode>; extra entries beyond it are ' +
+    'dropped, so keep within it. A supervisor watches the fan-out: a child that ' +
+    'stalls or runs very long may be nudged with guidance or replaced by a fresh ' +
+    'attempt, and the report\'s Supervisor section records every intervention.';
 export function createTaskTool(deps) {
     return {
         name: 'task',
@@ -64,8 +64,12 @@ export function createTaskTool(deps) {
             properties: {
                 subagents: {
                     type: 'array',
-                    description: `2-5 independent subagents to run in parallel (hard maximum ${TEAM_LIMITS.hardMaxSubagents}; ` +
-                        'extras are dropped).',
+                    // NO NUMBER HERE (subagent-fanout D-14): the width is a user setting
+                    // now (`team.maxSubagents`, 8 by default, 10 at most), so a literal
+                    // "2-5" in the schema would contradict the block the model reads in
+                    // the very same request. `<team_mode>` is the single authority.
+                    description: 'Independent subagents to run in parallel in ONE call. See <team_mode> for ' +
+                        'the current maximum and concurrency; extras are dropped.',
                     items: {
                         type: 'object',
                         properties: {

package/dist/tools/bash-tool.d.ts

@@ -19,12 +19,22 @@
  *      inheriting the pipe — `Start-Process`, `&`, `nohup`, and every
  *      `npm run dev` that re-execs — keeps that pipe open after the shell is
  *      long gone. The shell exited; the promise did not.
+ *
  *   2. `stdio` defaulted to `'pipe'` for stdin, so a command that PROMPTS —
  *      `npm init`, a package manager asking to install something, `sudo`, a git
  *      credential prompt — blocked on a read that could never be satisfied.
  *   3. An abort killed the tree and then went on waiting for a `'close'` that a
  *      detached grandchild was still holding.
  *
+ * WHY THE DRAIN WINDOW IS A BOUND AND NOT A VERDICT. The first build called
+ * anything still unsettled when that window closed "a held pipe" and printed
+ * the `'exit'` drain note on the strength of it. Under load the two disagree:
+ * the release gate caught a command that had printed two lines and exited
+ * immediately being reported as holding its output stream, because the timers
+ * phase came round before libuv delivered the close notification. The note is a
+ * claim about STATE, so it is decided by asking the streams
+ * (`proc/output-streams.ts`) instead of guessing from a clock.
+ *
  * The happy path is BYTE-IDENTICAL to the pre-change build: `$ cmd\n<output>\n
  * [exit code N]`, same truncation, same footer. That is what keeps the existing
  * `bash` assertions meaningful rather than rewritten.