@aragon-agent/cli 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -9,6 +9,96 @@ were written.
 
 ### Added
 
+- **Team subagents.** The agent can now hand independent parts of a job to up to
+  five short-lived subagents that run in parallel, then read one combined report
+  of what each of them found. It decides for itself whether to delegate, so a
+  session that never calls the new `task` tool is byte-for-byte the session that
+  existed before. On by default; `--no-team` or `team.enabled: false` turns it
+  off, and `aragon config set team.maxSubagents <n>` sets the width (1-10; the
+  10 is a hard ceiling no config file can raise).
+
+  A subagent is a full agent with the same tools and working directory but no
+  memory of your conversation, so its brief has to be self-contained. It cannot
+  delegate further and it cannot ask you anything. Plan mode and a skill's
+  `allowed-tools` ceiling both reach one level down, so delegating is never a
+  way around either; `--confirm` queues subagent confirmations one at a time and
+  labels each with the subagent that is asking.
+
+  Subagents can message each other with `team_send` / `team_wait`, delivered by
+  attaching the message to the recipient's next tool result rather than
+  interrupting it. The limits are deliberate — 6 messages each, one every 15
+  seconds, 24 per dispatch — and every refusal is a plain result naming the
+  limit rather than an error, because an error invites the retry the limits
+  exist to prevent.
+
+  While a dispatch runs, a roster sits between the transcript and the composer
+  and the status bar carries `agents 3/5`; both disappear when it finishes and
+  the transcript keeps a card you can expand with `Ctrl+O`. `Esc` aborts every
+  subagent and returns the partial report. Under `-p` the transitions go to
+  stderr and the subagents' tokens are folded into the `[usage]` footer, so the
+  cost readout cannot under-report what the team spent.
+
+  Full documentation, including the limits table and how team mode interacts
+  with plan mode, skills and `--confirm`, is in the README.
+
+- **The subagent roster now shows what each subagent is doing, and shows the
+  ones that are working.** Where every row used to say `thinking` for minutes at
+  a time, it now says `bash: npm test -w cli`, `read: src/api/routes.ts`,
+  `waiting for a2`, or the tail of the sentence the subagent is currently
+  writing. On a narrow terminal the same row falls back to a file name and a
+  program name rather than wrapping, and the elapsed clock keeps its place at
+  every width.
+
+  The five visible rows are now the five that matter: whatever is running comes
+  first, then whatever is queued, then the most recent results. Above five
+  subagents the old panel showed the five that had finished first and hid
+  everything still working behind `+3 more`, which is the opposite of what the
+  roster is for. `+3 more` now says how many of the hidden ones are still going.
+
+- **A subagent no longer waits two minutes for a message nobody can send.**
+  `team_wait` now checks whether anyone could actually answer before it blocks:
+  if the teammate it named has already finished, does not exist, or is itself
+  waiting in a way that cannot be released in time, it returns straight away and
+  says which. Nothing is refused that could still have been answered — including
+  by a third teammate further down the chain — and the subagent is told what to
+  do instead rather than handed an error.
+
+- **A subagent whose very first request dies on a rate limit is retried once.**
+  Only a genuine cold start qualifies: no turn completed and no tool ran, so
+  there is nothing to undo. It restarts after two seconds, the roster says
+  `starting (retry)`, and the report notes `retried 1x`. Pressing `Esc`, a
+  timeout, or any subagent that had already begun work is never retried.
+
+### Changed
+
+- **`config.json` holds settings again.** The prompts you type are no longer
+  stored in it. They move to `~/.aragon-agent/prompt-history.jsonl` — one JSON
+  object per line, `0600` on POSIX — and the submit counter and the "notice
+  already shown" flag move to `~/.aragon-agent/state.json`. `↑` and `↓` behave
+  exactly as before.
+
+  Two things get better. Opening `config.json` to change your model no longer
+  means scrolling past a transcript of your own typing, and copying it to
+  another machine no longer carries your prompts along. And submitting a message
+  no longer rewrites the file that holds your API keys: `config.json` is written
+  when you change a setting, and at no other time.
+
+  **Your history and counters are migrated automatically, once, at the next
+  launch.** Nothing is printed, because nothing changes for you. The dead
+  `recentModels` key — which nothing has ever written — is dropped.
+
+  If you go back to 0.5.x after upgrading, that version does not know about the
+  new file and `↑` will look empty. Nothing has been lost: the entries are still
+  in `prompt-history.jsonl`, and upgrading again brings them back.
+
+### Added
+
+- **`aragon history`** — `path`, `list` (`-n`, `--json`) and `clear --yes` for
+  the prompt history, alongside the existing `aragon logs` commands. Entries are
+  stored verbatim, so `clear` is how you erase them; `aragon config set
+  historyEnabled false` stops new ones being recorded without deleting or hiding
+  what is already there.
+
 - **The mouse wheel scrolls what is under the pointer.** In full-screen mode the
   wheel now scrolls the transcript three rows per notch (a page with `Shift`),
   scrolls an open overlay when the pointer is over one, and steps prompt history

package/README.md

@@ -72,6 +72,8 @@ aragon --help  | -h             Print help
 | `--no-fullscreen` | Force the inline renderer (the 0.2.0 behavior) |
 | `--no-exit-transcript` | Do not replay the session summary after exiting |
 | `--plan` / `--no-plan` | Start the session in PLAN mode (read-only research + review) or force BUILD |
+| `--team` / `--no-team` | Enable or disable team subagents. `--no-team` does not register the `task` tool at all |
+| `--team-max <n>` | Max subagents per dispatch for this run, clamped to `[1, 10]` |
 | `--no-skills` | Disable the skill system entirely (no catalog, no skill tools) |
 | `--skill <name>` | Force-load a skill's full body for this run (repeatable) |
 | `--skills-yes` | Approve skill installs for this run (CI / headless) |
@@ -96,6 +98,7 @@ Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
 | `/save [file]` | Save the session to JSON |
 | `/resume [file]` | Load a saved session |
 | `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
+| `/team [on\|off\|max <n>]` | Team subagents: status and the live roster, the on/off switch, the fan-out width |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
 | `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
 | `/copy` | Copy the last answer to the clipboard |
@@ -308,6 +311,82 @@ When skills are enabled, four more are added — the two read tools `skill` and
 below). `--no-skills` removes them again. Updating a skill is deliberately not
 among them; that is a `aragon skills update` decision for you, not the model.
 
+With team mode on — which is the default — one more is added: `task`, the
+delegation tool (see below). `--no-team` removes it again.
+
+## Team subagents
+
+The agent can hand parts of a job to short-lived **subagents** that run in
+parallel, then read one combined report of what they each found. It decides for
+itself whether to delegate; a session that never calls `task` is the session
+that existed before this feature.
+
+```
+> read the auth middleware, map the route table, and check the migration
+
+ ◆ team  2 running · 1 done · 84s                             ✉ 1
+ ⠋ a1  read the auth middleware      tool: grep         22.1s
+ ⠙ a2  map the route table           thinking           31.6s
+ ✔ a3  check the migration           done  4 turns      18.2s
+```
+
+**What a subagent is.** A full agent with its own message history, the same
+tools and the same working directory — but no memory of your conversation, so
+its brief has to be self-contained. It cannot delegate further (depth is capped
+at one by construction) and it cannot ask you anything.
+
+**Delegate wide, not deep.** Two to four subagents is the usual size. The
+default cap is 5 per dispatch and 3 in flight at once; the hard maximum is 10
+and no config file can raise it. `maxConcurrent` is separate from `maxSubagents`
+on purpose: five simultaneous streams against one API key is a reliable way to
+collect rate-limit errors, and each one would land in the report as a failed
+subagent.
+
+**The report.** One text result: a header with the ok/failed counts, aggregate
+tokens and cost, then one section per subagent with its status, timing, the
+files it wrote and its own final summary. A failed subagent never fails the
+dispatch — partial results are the normal outcome of a fan-out. When two
+subagents wrote the same file the header says so, phrased as a warning rather
+than a fact: the file list is derived from `write_file` / `edit_file`, so a
+write made through `bash` is invisible to it.
+
+**Talking to each other.** Subagents get two extra tools, `team_send` and
+`team_wait`. Messages are delivered by attaching them to the recipient's next
+tool result, so nobody has to poll and nobody's work is interrupted. The limits
+are the point rather than an afterthought: **6 messages per subagent, one every
+15 seconds, 24 per dispatch**, a broadcast costing two. Every refusal is a plain
+result naming the limit, never an error — an error reads as a malfunction and
+invites a retry, which is the behaviour the limits exist to prevent.
+
+**What you see.** While a dispatch runs, the roster above sits between the
+transcript and the composer and the status bar carries `agents 3/5` (`[3]` under
+100 columns). Both disappear when it finishes and the transcript keeps a card
+with the per-agent results; `Ctrl+O` expands it to their summaries. Under `-p`
+the same transitions go to stderr as `[team] a1 ok 22.1s 7 tools` lines, and the
+children's tokens are folded into the `[usage]` footer.
+
+**Interaction with the other subsystems.**
+
+- **Plan mode reaches one level down.** In PLAN, every subagent is built with
+  the same read-only gate, so `write_file` / `edit_file` / `bash` are refused
+  inside them too. Parallel research is plan mode's best use, so `task` itself
+  is allowed. A single subagent can be pinned read-only with `readOnly: true`
+  even in a BUILD session — the field can only ever tighten.
+- **A skill's `allowed-tools` ceiling reaches one level down too**, so
+  delegating is not a way around it. Subagents get `skill_find` but not `skill`:
+  loading a skill mutates a turn-scoped registry the lead owns, and three
+  subagents doing it at once would narrow what the lead may do next in a way
+  nothing would report. Always-on skills still reach them.
+- **`--confirm`** queues subagent confirmations one at a time, labelled with the
+  subagent that is asking (`[a2] Write: src/routes.ts`).
+- **Logs.** `dispatch_start` and `dispatch_end` are recorded at `info` with the
+  ok / failed / aborted counts and aggregate usage; phase transitions at
+  `debug`. A `team_send` subject is recorded, never its body; a subagent's brief
+  and summary only at `trace`.
+
+**`Esc`** aborts the whole dispatch — every subagent within a couple of seconds
+— and the report comes back marked `ABORTED` with whatever was finished.
+
 ## Skills
 
 A skill is a reusable expert procedure stored on disk: a directory containing a
@@ -597,13 +676,16 @@ env / `.env` → CLI flags**.
   `GOOGLE_API_KEY` / `GEMINI_API_KEY`, plus `ARAGON_PROVIDER`, `ARAGON_MODEL`,
   `ARAGON_BASE_URL`, `ARAGON_THINKING`, `ARAGON_MAX_TOKENS`, `ARAGON_THEME`,
   `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
+  `ARAGON_TEAM` (`0` disables team subagents), `ARAGON_TEAM_MAX` (fan-out width),
   `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
   `ARAGON_SKILLS_DISABLED` (comma-separated names), `ARAGON_LOG_LEVEL`,
   `ARAGON_LOG_FILE` (`0` disables), `ARAGON_LOG_DIR`.
   `ARAGON_HOME` is the exception that **cannot** come from `.env`: it is read
   before any `.env` is loaded. See [Files & logs](#files--logs).
 - **User config file** (`aragon config path`): JSON, written `0600` on POSIX.
-  Holds provider/model/keys and MRU lists. Keys are masked in the UI and never
+  Holds provider / model / keys and your preferences, and nothing else — the
+  prompts you type and the counters behind one-time notices live in their own
+  files (see [Files & logs](#files--logs)). Keys are masked in the UI and never
   logged. It lives in your home directory — see [Files & logs](#files--logs) —
   and editing it by hand is supported: `aragon config edit` opens it, and an
   invalid edit is reported rather than silently resetting every setting.
@@ -616,6 +698,13 @@ env / `.env` → CLI flags**.
 | `planModeDefault` | `false` | Start every session in plan mode. `--no-plan` still overrides it for a single run. |
 | `planModeMaxAskRounds` | `4` | `ask_user` rounds allowed per user message, clamped to `[1, 10]`. The counter resets on your next message; steering does **not** reset it. |
 | `planModeHumanTimeoutMs` | `1800000` | Ceiling on a single question / plan wait, clamped to `[60000, 7200000]`. Thirty minutes is far outside "went to get coffee", but a ceiling has to exist so an unattended terminal cannot wedge a CI job forever. |
+| `historyEnabled` | `true` | Record submitted prompts to `prompt-history.jsonl` for `↑` recall. Setting it to `false` stops new writes; it does not delete what is already stored (that is `aragon history clear --yes`) and does not stop reading. See [Prompt history](#prompt-history). |
+| `team.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered — `/team on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
+| `team.maxSubagents` | `5` | Subagents per dispatch, clamped to `[1, 10]`. The 10 is the hard ceiling and is enforced twice — on the config value and again on what the model asks for — so hand-editing this file cannot raise it. |
+| `team.maxConcurrent` | `3` | Subagents in flight at once, clamped to `[1, 10]` and capped at `maxSubagents`. A separate knob because provider rate limits are a different constraint from context economics. |
+| `team.subagentTimeoutMs` | `300000` | One subagent's wall clock before it is aborted, clamped to `[30000, 1800000]`. A wedged subagent dies on its own ceiling without taking the dispatch with it. |
+| `team.dispatchTimeoutMs` | `900000` | The whole dispatch's wall clock, clamped to `[60000, 3600000]`. |
+| `team.maxTurnsPerSubagent` | `24` | Runaway-loop cap, clamped to `[4, 100]`. A subagent stopped here is reported as `stopped: turn cap reached`, with whatever it had produced. |
 | `skills.enabled` | `true` | Master switch for the skill system. |
 | `skills.requireApproval` | `true` | Require a human to approve `skill_install` / `skill_create`. |
 | `skills.catalogMaxBytes` | `6000` | Level 1 catalog ceiling, in UTF-8 **bytes**, clamped to `[500, 40000]`. |
@@ -649,6 +738,8 @@ Everything AragonAgent keeps for you lives under one directory in your home:
 ~/.aragon-agent/                    (Windows: C:\Users\<you>\.aragon-agent\)
 ├── config.json                     settings + API keys (0600 on POSIX)
 ├── config.json.bak                 written by `aragon config edit` before it opens
+├── prompt-history.jsonl            prompts you submitted, for ↑ recall (0600 on POSIX)
+├── state.json                      UI bookkeeping: submit count, one-shot notices
 ├── logs/
 │   ├── aragon-2026-07-27.log       today, JSON Lines
 │   └── aragon-2026-07-27.1.log     rotated at log.maxFileBytes
@@ -657,6 +748,11 @@ Everything AragonAgent keeps for you lives under one directory in your home:
 └── skill-usage.json
 ```
 
+`config.json` holds **settings only**. What you typed and how often you have
+typed it live in the two files next to it, so that editing your config means
+scrolling past your own settings and nothing else, and so that submitting a
+prompt no longer rewrites the file that holds your API keys.
+
 `ARAGON_HOME` moves the whole tree. **It cannot come from a `.env` file** — the
 path is resolved when the process starts, long before a `.env` is read — so set
 it as a real environment variable. `aragon config home` always prints the
@@ -669,6 +765,33 @@ directories are **left in place** so that reinstalling an older build stays
 lossless; `aragon config home` names them, and you can delete them once you are
 satisfied.
 
+### Prompt history
+
+Every prompt you submit is appended to `~/.aragon-agent/prompt-history.jsonl`,
+one JSON object per line, so that `↑` recalls it — in this session and in every
+later one. It is written `0600` on POSIX, it never leaves the machine, and it is
+**stored verbatim**: a redacted history would recall the wrong text, which is
+worse than not recalling at all.
+
+The last 100 distinct prompts are what `↑` walks. The file is rewritten down to
+that many entries once it passes 400 lines, and a single submission longer than
+16 KiB is not recorded at all rather than recorded truncated.
+
+```bash
+aragon history path           # where it is, plus a reminder of what is in it
+aragon history list -n 50     # the 50 most recent, newest first
+aragon history list --json    # raw entries with timestamps
+aragon history clear --yes    # delete the file
+```
+
+Set `historyEnabled` to `false` (`aragon config set historyEnabled false`) to
+stop recording. Switching it off does **not** delete what is already stored —
+`aragon history clear --yes` does that — and reading keeps working either way,
+so you can look before you erase.
+
+Upgrading from 0.5.x moves an existing `promptHistory` out of `config.json` into
+this file once, automatically and silently.
+
 ### What gets logged
 
 Logs are local files. Nothing is uploaded, ever — there is no network path out
@@ -705,6 +828,10 @@ aragon logs tail --level warn # only warn and above
 aragon logs clear --yes       # delete every log file
 aragon logs open              # open the directory in your file manager
 
+aragon history path           # where prompt history is kept
+aragon history list -n 50     # the 50 most recent prompts, newest first
+aragon history clear --yes    # delete the prompt history
+
 aragon config home            # the user-state root (and whether ARAGON_HOME set it)
 aragon config get log.level   # one value; secrets always masked
 aragon config list --json     # everything; secrets always masked here too

package/dist/agent/controller.d.ts

@@ -9,8 +9,9 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
-import type { CliConfig, ThemeName } from '../config/schema.js';
+import type { CliConfig, TeamConfig, ThemeName } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
+import type { TeamEvent, TeamSnapshot } from '../team/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
 import type { AgentMode } from './agent-mode.js';
@@ -80,6 +81,9 @@ export declare class AgentController {
     private askRounds;
     /** Static: whether this session could ever render a question overlay. */
     private readonly planInteractive;
+    private readonly teamRegistered;
+    private teamEnabled;
+    private readonly teamRuntime;
     constructor(config: CliConfig, deps?: ControllerDeps);
     private resolveKey;
     /**
@@ -177,8 +181,54 @@ export declare class AgentController {
      * path must not leave the watchdog disarmed for the rest of the run. Also used
      * by the `--confirm` gate, which had exactly this bug — a user who took four
      * minutes over `Proceed? (y/N)` had their run killed by the watchdog.
+     *
+     * RENAMED FROM `withHumanWait`, WITH THE OLD NAME KEPT AS AN ALIAS (D-12). The
+     * mechanism is not about humans any more — a `task` dispatch is a long wait
+     * with no human in it at all — but the plan tools and the `--confirm` gate read
+     * correctly with the old name at their call sites, and renaming those would be
+     * churn in files this change should barely touch.
+     *
+     * NOT RE-ENTRANT, and that matters here: `IdleWatchdog.pause()` sets a boolean
+     * rather than a counter, so a nested call's `finally` re-arms the watchdog
+     * while the outer wait is still going. That is why a child's `--confirm`
+     * dialog does NOT route through this (see the constructor's `humanQueue`).
      */
+    withPausedWatchdog<T>(fn: () => Promise<T>): Promise<T>;
+    /** @see withPausedWatchdog — the name the plan tools and `--confirm` use. */
     withHumanWait<T>(fn: () => Promise<T>): Promise<T>;
+    /** Whether `task` is in `this.tools`. Fixed at construction; see the fields. */
+    isTeamRegistered(): boolean;
+    /** Whether `task` will actually dispatch. Flipped live by `/team on|off`. */
+    isTeamEnabled(): boolean;
+    /**
+     * Flip the live switch and re-render the prompt.
+     *
+     * Turning it ON in a session that started with `--no-team` deliberately does
+     * NOT register the tool (D-17): the array is immutable, and advertising an
+     * unregistered tool is the dead end P0-2 is about. `/team` reports that
+     * honestly by checking `isTeamRegistered()` first.
+     */
+    setTeamEnabled(enabled: boolean): void;
+    getTeamConfig(): TeamConfig;
+    /**
+     * Adopt a new team config for this session and re-render the prompt (the block
+     * quotes the numbers). Clamped here as well as on the persist path, so a bad
+     * value can never reach the runtime.
+     */
+    setTeamConfig(patch: Partial<TeamConfig>): TeamConfig;
+    /** Refused mid-dispatch by `/team`; half a dispatch under two ceilings is not
+     *  a result anything can afterwards explain (the reasoning `/reload` uses). */
+    isTeamBusy(): boolean;
+    getTeamSnapshot(): TeamSnapshot | null;
+    /**
+     * Subscribe to the CLI-local team event stream.
+     *
+     * Returns a no-op unsubscribe when team mode was off at construction, so every
+     * caller can subscribe unconditionally.
+     */
+    subscribeTeam(listener: (event: TeamEvent) => void): () => void;
+    /** Abort every child and clear timers. Idempotent; safe to call twice. */
+    dispose(): void;
     setModel(provider: string, model: string, baseUrl?: string): void;
     setThinkingLevel(level: ThinkingLevel): void;
     setMaxTokens(value: number | undefined): void;

package/dist/agent/controller.js

@@ -9,10 +9,14 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
-import { isAdapterProvider } from '../config/schema.js';
+import { clampTeamConfig, isAdapterProvider } from '../config/schema.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
+import { TeamRuntime } from '../team/runtime.js';
+import { TeamHumanQueue } from '../team/human-queue.js';
+import { createTaskTool } from '../team/task-tool.js';
+import { buildTeamBlock } from '../team/prompt.js';
 import { createPlanTools } from '../tools/plan-tools.js';
 import { DENY_ALL_HUMAN_INPUT } from '../tools/human-input.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
@@ -48,6 +52,25 @@ export class AgentController {
     askRounds = 0;
     /** Static: whether this session could ever render a question overlay. */
     planInteractive;
+    // -----------------------------------------------------------------------
+    // Team mode (team-subagents §4.5) — TWO FLAGS, AND THEY ARE NOT THE SAME.
+    //
+    // `teamRegistered` is decided ONCE, at construction, and can never change:
+    // it is whether the `task` tool is in `this.tools` at all. The array is
+    // immutable for the life of the session (see the note in the constructor),
+    // so `/team on` in a session started with `--no-team` CANNOT add it.
+    //
+    // `teamEnabled` is live. `/team off` flips it, which makes `task` refuse
+    // through its own guard and drops `<team_mode>` from the next prompt rebuild
+    // — `rebuildSystemPrompt()` IS a live path, unlike the tool array.
+    //
+    // Conflating them is P0-2: the prompt would advertise a tool that was never
+    // registered, every call would come back "unknown tool", and the model would
+    // have no way to discover why (D-17 / R-18).
+    // -----------------------------------------------------------------------
+    teamRegistered;
+    teamEnabled;
+    teamRuntime;
     constructor(config, deps = {}) {
         this.config = config;
         this.cwd = config.cwd;
@@ -81,6 +104,40 @@ export class AgentController {
             this.skills.reportUnknownForcedSkills();
         }
         const confirm = deps.confirm;
+        // --- Team mode ---------------------------------------------------------
+        this.teamRegistered = config.team.enabled;
+        this.teamEnabled = config.team.enabled;
+        this.teamRuntime = this.teamRegistered
+            ? new TeamRuntime({
+                getConfig: () => this.config,
+                providerRegistry: this.providerRegistry,
+                getCwd: () => this.cwd,
+                getMode: () => this.effectiveMode,
+                getApiKey: (id) => this.resolveKey(id),
+                // `skill_find` only, and the lead's always-on bodies. See the long
+                // note in `subagent.ts` for why `skill` itself is withheld (D-16).
+                ...(this.skillsEnabled
+                    ? {
+                        skillRegistry: this.skills.getRegistry(),
+                        alwaysBlock: () => this.skills.alwaysBlock(),
+                        toolPolicy: () => this.skills.toolPolicyDecision(() => this.toolNames()),
+                        // Label-decorating, and it DOES NOT advance the lead's
+                        // escalation counter (P1-3). That counter exists to tell ONE
+                        // agent to stop retrying ONE tool; a child cannot retry the
+                        // lead's turn, and letting children spend the lead's budget
+                        // makes the escalation fire on the lead's next legitimate call.
+                        onChildToolPolicyEvent: (e) => deps.notify?.('warn', `[${e.label}] ${e.verdict.message ?? `Blocked ${e.tool}`}`),
+                    }
+                    : {}),
+                // NOT routed through `withHumanWait` (I-3, and this one is subtle):
+                // the lead's watchdog is ALREADY paused for the whole dispatch, and
+                // `IdleWatchdog.pause()` is a boolean rather than a counter — so a
+                // nested resume when one child's dialog closed would re-arm the lead
+                // mid-dispatch and abort it at `idleTimeoutMs`. The queue pauses the
+                // CHILD's watchdog instead, which is the one that needs it (P0-4).
+                ...(confirm ? { humanQueue: new TeamHumanQueue(confirm) } : {}),
+            })
+            : null;
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
             confirmTools: config.confirmTools,
@@ -110,6 +167,27 @@ export class AgentController {
                 withHumanWait: (fn) => this.withHumanWait(fn),
                 onPlanApproved: () => this.setAgentMode('build', { force: true }),
             }),
+            // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
+            // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
+            // `createBuiltinTools` produces, so appending `task` here would turn that
+            // test red with a message about two lists of names.
+            //
+            // Empty when team mode was off at construction, which leaves the array
+            // byte-identical to the pre-team build (AC-11).
+            teamTools: this.teamRuntime
+                ? [
+                    createTaskTool({
+                        runtime: this.teamRuntime,
+                        // Read LIVE: `/team off` flips the flag, it cannot unregister.
+                        isTeamEnabled: () => this.teamEnabled,
+                        maxSubagents: () => this.config.team.maxSubagents,
+                        hasApiKey: () => this.hasApiKey(),
+                        activeProvider: () => this.config.provider,
+                        modelCost: () => this.getModelInfo().cost,
+                        withPausedWatchdog: (fn) => this.withPausedWatchdog(fn),
+                    }),
+                ]
+                : [],
             // Read at CALL time, never cached: the mode flips mid-run when the user
             // approves a plan, and a cached 'plan' would refuse the work they just
             // authorized.
@@ -149,6 +227,11 @@ export class AgentController {
                 toolTimeoutOverrides: {
                     ask_user: config.planModeHumanTimeoutMs,
                     submit_plan: config.planModeHumanTimeoutMs,
+                    // A fan-out is not a hung tool either. Like the two above, this
+                    // number only bites BECAUSE `task` races `ctx.signal` — the
+                    // executor's timeout is cooperative, so an override is inert for any
+                    // tool that does not listen (I-2).
+                    ...(this.teamRegistered ? { task: config.team.dispatchTimeoutMs } : {}),
                 },
             },
         });
@@ -193,6 +276,16 @@ export class AgentController {
             agentMode: this.effectiveMode,
             planInteractive: this.planInteractive,
             planMaxAskRounds: this.config.planModeMaxAskRounds,
+            // BOTH flags, and both are required (§4.5). `teamRegistered` false means
+            // there is no `task` tool to advertise; `teamEnabled` false means the user
+            // turned it off for this session. Advertising in either case would
+            // describe a capability the model does not have.
+            teamBlock: this.teamRegistered && this.teamEnabled
+                ? buildTeamBlock({
+                    maxSubagents: this.config.team.maxSubagents,
+                    maxConcurrent: this.config.team.maxConcurrent,
+                })
+                : '',
         });
     }
     rebuildSystemPrompt() {
@@ -293,6 +386,13 @@ export class AgentController {
     }
     abort() {
         this.agent.abort();
+        // DELIBERATE REDUNDANCY (§3.8). Aborting the lead already aborts the
+        // in-flight `task` call's `ctx.signal`, which the runtime listens to — that
+        // path is correct today. Calling it directly as well makes "no child
+        // survives its dispatch" a property of THIS class rather than a consequence
+        // of signal plumbing three modules away, which is the same argument
+        // `App.tsx` records for `cancelPendingHuman()` on `agent_end`.
+        this.teamRuntime?.abortAll();
     }
     steer(text) {
         // Mid-run interjection: promote the queue, keep what is already in force
@@ -393,8 +493,19 @@ export class AgentController {
      * path must not leave the watchdog disarmed for the rest of the run. Also used
      * by the `--confirm` gate, which had exactly this bug — a user who took four
      * minutes over `Proceed? (y/N)` had their run killed by the watchdog.
+     *
+     * RENAMED FROM `withHumanWait`, WITH THE OLD NAME KEPT AS AN ALIAS (D-12). The
+     * mechanism is not about humans any more — a `task` dispatch is a long wait
+     * with no human in it at all — but the plan tools and the `--confirm` gate read
+     * correctly with the old name at their call sites, and renaming those would be
+     * churn in files this change should barely touch.
+     *
+     * NOT RE-ENTRANT, and that matters here: `IdleWatchdog.pause()` sets a boolean
+     * rather than a counter, so a nested call's `finally` re-arms the watchdog
+     * while the outer wait is still going. That is why a child's `--confirm`
+     * dialog does NOT route through this (see the constructor's `humanQueue`).
      */
-    async withHumanWait(fn) {
+    async withPausedWatchdog(fn) {
         this.agent.pauseIdleWatchdog();
         try {
             return await fn();
@@ -403,6 +514,70 @@ export class AgentController {
             this.agent.resumeIdleWatchdog();
         }
     }
+    /** @see withPausedWatchdog — the name the plan tools and `--confirm` use. */
+    withHumanWait(fn) {
+        return this.withPausedWatchdog(fn);
+    }
+    // -----------------------------------------------------------------------
+    // Team mode (team-subagents §4.5)
+    // -----------------------------------------------------------------------
+    /** Whether `task` is in `this.tools`. Fixed at construction; see the fields. */
+    isTeamRegistered() {
+        return this.teamRegistered;
+    }
+    /** Whether `task` will actually dispatch. Flipped live by `/team on|off`. */
+    isTeamEnabled() {
+        return this.teamEnabled;
+    }
+    /**
+     * Flip the live switch and re-render the prompt.
+     *
+     * Turning it ON in a session that started with `--no-team` deliberately does
+     * NOT register the tool (D-17): the array is immutable, and advertising an
+     * unregistered tool is the dead end P0-2 is about. `/team` reports that
+     * honestly by checking `isTeamRegistered()` first.
+     */
+    setTeamEnabled(enabled) {
+        this.teamEnabled = enabled;
+        this.rebuildSystemPrompt();
+    }
+    getTeamConfig() {
+        return this.config.team;
+    }
+    /**
+     * Adopt a new team config for this session and re-render the prompt (the block
+     * quotes the numbers). Clamped here as well as on the persist path, so a bad
+     * value can never reach the runtime.
+     */
+    setTeamConfig(patch) {
+        const team = clampTeamConfig({ ...this.config.team, ...patch });
+        this.config = { ...this.config, team };
+        this.rebuildSystemPrompt();
+        return team;
+    }
+    /** Refused mid-dispatch by `/team`; half a dispatch under two ceilings is not
+     *  a result anything can afterwards explain (the reasoning `/reload` uses). */
+    isTeamBusy() {
+        return this.teamRuntime?.isBusy() ?? false;
+    }
+    getTeamSnapshot() {
+        return this.teamRuntime?.snapshot() ?? null;
+    }
+    /**
+     * Subscribe to the CLI-local team event stream.
+     *
+     * Returns a no-op unsubscribe when team mode was off at construction, so every
+     * caller can subscribe unconditionally.
+     */
+    subscribeTeam(listener) {
+        if (!this.teamRuntime)
+            return () => { };
+        return this.teamRuntime.subscribe(listener);
+    }
+    /** Abort every child and clear timers. Idempotent; safe to call twice. */
+    dispose() {
+        this.teamRuntime?.dispose();
+    }
     // -----------------------------------------------------------------------
     // Mutators
     // -----------------------------------------------------------------------

package/dist/agent/headless.d.ts

@@ -6,12 +6,24 @@
  */
 import type { AgentEvent, ModelInfo } from '@aragon-agent/core';
 import type { PreflightResult } from './controller.js';
+import type { TeamEvent } from '../team/types.js';
 /** The minimal controller surface headless mode needs (real or stubbed). */
 export interface HeadlessController {
     preflight(): PreflightResult;
     subscribe(listener: (event: AgentEvent) => void): () => void;
     prompt(text: string): Promise<void>;
     getModelInfo(): ModelInfo;
+    /**
+     * The CLI-local team stream — OPTIONAL, deliberately (team-subagents §3.12 /
+     * P1-6).
+     *
+     * This interface is minimal so tests can satisfy it with an object literal.
+     * Making the member REQUIRED would break every existing stub for no benefit,
+     * and the subscription genuinely is optional: a controller with no team
+     * runtime has no team events. `runHeadless` calls it with `?.`, which keeps
+     * the `--no-team` headless path byte-identical to today's.
+     */
+    subscribeTeam?(listener: (event: TeamEvent) => void): () => void;
 }
 export interface HeadlessOptions {
     quiet?: boolean;