@aragon-agent/cli 0.6.39 → 0.6.42

package/CHANGELOG.md

@@ -8,6 +8,74 @@ were written.
 ## Unreleased
 
 ### Added
+- **Automatic skill triage, and no round limit on questions.** Two changes that
+  share one idea: replace a hard limit with guidance the agent can act on.
+  `ask_user` is no longer capped at four rounds per turn — the cap, its prompt
+  wording (`you may ask up to 4 rounds`), its tool-result counters
+  (`roundsUsed` / `roundsRemaining`) and its `/plan status` readout are all gone,
+  because an agent that is told it is running out of questions behaves like it.
+  What replaced it is a de-duplication guard: a question batch you have already
+  **answered** in this turn returns a note instead of reopening the overlay, while
+  a **cancelled** one records nothing, so an accidental `Esc` never retires a
+  question. Steering does not reset the guard, because a steer resumes the same
+  turn. `planModeMaxAskRounds` is retired rather than defaulted to a large number:
+  `config set` names the reason and exits `2`, and the key disappears from
+  `config.json` at the next write. The single-wait ceiling
+  (`planModeHumanTimeoutMs`) is untouched — it protects an unattended terminal, not
+  the agent's vocabulary.
+  Skill use now begins with a step instead of a hope. Every task gets a
+  `<skill_triage>` protocol fixing *when* to decide (after the project guidance and
+  the directory listing, before any plan or edit) plus up to three ranked
+  `<skill_candidates>` computed locally from your message against the installed
+  records — no model call, no file read, no `SKILL.md` body, so the disclosure
+  ladder keeps its lower levels untouched. When a strongly-matching skill was
+  available and the turn did real work without loading it, the run ends with one
+  `info` line and a pointer to `/skills route`; that fires at most once per skill
+  per session, because a line printed every turn is a line you learn to skip.
+  `/skills route <text>` explains any decision (including the runner-up and the
+  threshold on a miss), `/skills triage on|off` flips the feature live, and
+  `skills.triage` (default `true`) makes it permanent — off restores the previous
+  prompt byte for byte. Subagents are deliberately not triaged: a child has no
+  `skill` tool, so candidates would advertise a capability it does not have.
+- **`/team <brief>` forces team mode and starts the work in one line.** Typing
+  `/team write today's AI briefing` no longer answers `Unknown argument` — it arms a
+  SESSION-level forced mode and submits that brief as an ordinary turn. The lead
+  analyses and plans it, then has to call `task`: three layers say so, and only the
+  third is mechanical. The submitted directive (unchanged bytes) covers the first
+  turn, a new `<forced_team_mode>` prompt block covers every later turn, and an
+  end-of-turn gate covers a model that did neither — when a turn used tools and
+  dispatched nothing, the app asks once in the transcript
+  (`Forced team mode: no dispatch last turn - asking the agent to dispatch now.`)
+  and re-prompts with the armed count. The gate is bounded on three sides, because
+  a helpful nudge that fires for ever is a bill: at most one nudge per user
+  request (a human submit refills the budget, a turn never does), never for a pure
+  question that used no tools, and never after Esc or an error. A turn that
+  already tried `task` — even one the tool refused — counts as an attempt, so a
+  closed capability cannot be mistaken for a disobedient model. While the session
+  is armed the status bar carries `Team 4` (`T4` when narrow), the only
+  persistent signal that `/team` happened. Forced mode is never persisted: no
+  new `config.json` key, no session-file field, and `aragon exec` is unchanged.
+  `/team on` arms without starting, `/team off` leaves, `/team` reports, and a
+  quoted `"/team \"off\""` is a brief named `off` rather than the keyword.
+
+- **`/subagent`: force a parallel fan-out with one command.** The escape hatch for
+  "I want a team on this, not the model's judgement": `/subagent -n 6 review the error
+  handling in packages/cli/src/team`, `/subagent --parts api,ui,docs audit the request
+  path`, `/subagent --read-only profile the parser`. With no argument it reports live
+  capacity, the subagent model, the supervisor and the team switch, and it answers even in
+  a `--no-team` session rather than pretending. The command compiles your intent into ONE
+  user turn that tells the lead to call `task` once, so it shares the single dispatch path
+  (same Esc, same report, same spend accounting) - the forcing is instruction-level, and
+  the notice says what the next turn will do instead of claiming children have started.
+  A count above `team.maxSubagents` is narrowed AND disclosed (`asked for 12;
+  team.maxSubagents is 8`), a parts list is narrowed by both the structural 8 and the
+  configured width, and `-n 0` is an error rather than a silent 1.
+- **`/settings` → `Subagent fan-out`.** A fourth root row holding `Max subagents`,
+  `Run at once` and `Supervisor`, adjusted with `Left` / `Right` and saved by the same
+  single transaction as every other settings row (`Ctrl+S` on the main page; the fan-out
+  page's footer says so instead of promising a key it does not listen for). Narrowing the
+  population narrows the pool with it, and the follow-down is committed, so widening again
+  does not silently restore a pool you did not choose.
 - **`--threads`: one process, N isolated conversations.** A headless `aragon exec`
   process used to be one conversation: the seventh tenant's messages appeared in the
   third tenant's history, one `todo` list served everybody, and `interrupt` ended the
@@ -55,6 +123,38 @@ were written.
   spawning anything.
 
 ### Changed
+- **`/team` is now an action, and its configuration verbs are gone.** `status` and
+  `on` / `off` survive as SESSION control words (enter, leave, report), and `off`
+  no longer saves anything: **`/team on|off` used to write `config.json` and no
+  longer does**, so a mode you switch for this conversation is not silently a mode
+  for every later one. The four settings that used to live on the command moved to
+  `Settings > Team`, which is now the only persistent writer: `Team mode` (new —
+  the capability switch, previously only reachable as `/team on|off`), `Max
+  subagents`, `Run at once` and `Supervisor`. `max <n>`, `overseer on|off` and
+  `model <name>` are not verbs any more — `/team max 6` is a brief that starts work
+  on the text "max 6", because a command that both changes configuration and
+  executes work leaves you unable to predict what it did. `/subagent` remains as a
+  DEPRECATED ALIAS of `/team` (same arguments, one extra toast); nothing about its
+  behaviour changed except that a team-off session is now turned on for the session
+  in place instead of being refused. The settings page is retitled `Team` (it was
+  `Subagent fan-out`) and its root row prints `off - no subagents` while the
+  capability is off, rather than two numbers that describe nothing you can spend.
+  A session started with `--no-team` shows `on (next launch)` on the `Team mode`
+  row instead of claiming that saving will change the running session — the tool
+  array is immutable, and the row says so. One internal truth was deleted rather
+  than patched: `AgentController` no longer keeps a private `teamEnabled` copy of
+  `config.team.enabled`, so a settings save takes effect on the next turn instead of
+  at the next launch.
+- **The subagent fan-out default is now 8 per dispatch and 8 in flight at once** (it was
+  5 and 3). The perceived "only 3 subagents" was the concurrency ceiling, not the
+  population - changing only the population would have shown nothing, because children
+  4..8 would simply queue. `maxConcurrent` stays a separate knob precisely so a single API
+  key collecting 429s can be fixed by lowering `Run at once`; the settings row and the
+  README both say which number to lower. The hard ceiling is unchanged at 10: 8 is a
+  default you can move, 10 is the limit you cannot. **A persisted `5`/`3` pair from an
+  older install is migrated to `8`/`8` once**, with a `team.fanoutMigrated` marker so a
+  deliberate return to 5/3 sticks instead of being widened again on every launch. A
+  configuration whose values are anything else is never touched.
 - `makeExecController` now separates PROCESS-LEVEL log mounts from PER-CONTROLLER ones:
   `run_exec`, the `onFailure` handler and the untrusted-skill notices happen once per
   process (selected by the new `ExecControllerDeps.processLevelMounts`, which only the
@@ -68,6 +168,15 @@ were written.
   the same bytes it wrote before.
 
 ### Fixed
+- Changing only the fan-out width no longer drops the subagent model a session kit
+  installed. The settings save read "the `team` section was written" as "the user
+  re-decided the subagent slot", so adjusting `Max subagents` silently released a slot the
+  kit held - with every value on screen still correct. Only an explicit `model` /
+  `modelProfileId` decision releases the slot now, and the fan-out page can express
+  nothing else.
+- The `task` tool's description no longer states a fixed width (`2-5 independent
+  subagents`, `hard maximum 10`), which contradicted the configured maximum in the very
+  same request. It points at `<team_mode>`, which is generated from the live config.
 - A process-level signal now has exactly ONE owner in thread mode (it used to be
   installed by every runner into a single process-wide slot, so the last one won): the
   terminator fans out to all threads, `result` is written before the process exits, and a

package/README.md

@@ -942,6 +942,7 @@ ignores them rather than rejecting the library):
 | `/thinking <level>` | Set the thinking level |
 | `/max-tokens [<n>\|auto\|default]` | Output token cap; with no argument, reports the setting **and** the effective cap for the live model |
 | `/agents` | Open the **subagent board**: every child of the current (or most recent) dispatch, its full facts, its result and its 24-event timeline. The same board as `Ctrl+B`. Read-only - it can never nudge, kill or re-dispatch a child |
+| `/subagent [<brief>]` | **Force the next turn to fan out.** With no argument it reports the live capacity, the subagent model, the supervisor and the team switch. With a brief it submits one directive telling the lead to call `task` once with that wide a team: `-n 4` fixes the count, `--parts api,ui,docs` names the split, `--read-only` denies every child writes and shell. A count above `team.maxSubagents` is narrowed **and disclosed**, and `-n 0` is an error rather than a silent 1. The forcing is instruction-level, not mechanical: the proof is the `task` card in the next turn |
 | `/tools` | List active tools |
 | `/clear` | Start a new conversation: interrupt the run, archive the old session, clear the context, transcript, queues and todo panel. `/clear screen` only clears the screen |
 | `/reset` | Alias of `/clear` - one implementation, so the two cannot drift apart |
@@ -950,7 +951,7 @@ ignores them rather than rejecting the library):
 | `/resume [file]` | Load a saved session. This session moves to a NEW id, and the spend counter restarts |
 | `/session [copy\|pin]` | Report this session's id, file and branch parent; `copy` puts `aragon --resume <id>` on the clipboard; `pin` makes `sessions prune` skip the file forever |
 | `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
-| `/team [on\|off\|max <n>\|overseer on\|off\|model [main\|fast\|<profile-name>]]` | Team subagents: status and the live roster, the on/off switch, the fan-out width, the dispatch supervisor |
+| `/team [on\|off\|status]` / `/team [-n <n>] [--parts a,b,c] [--read-only] <brief>` | **Force team mode and start now.** `/team <brief>` arms forced team mode and submits that work as a normal turn: the lead analyses and plans it, then calls `task` — the directive, the `<forced_team_mode>` prompt block and a mechanical end-of-turn gate all say so. `/team on` arms without submitting, `/team off` leaves, `/team` reports. The configuration it used to carry (team switch, width, concurrency, supervisor, subagent model) lives in `Settings > Team` |
 | `/todo [on\|off\|panel on\|off\|follow <mode>\|acceptance on\|off\|reset\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, acceptance criteria, and picking an unfinished plan back up |
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
 | `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
@@ -1591,6 +1592,16 @@ questions.
 Cancelling either one is not an error. The agent is told to proceed on stated
 assumptions rather than to retry.
 
+**There is no limit on how many rounds of questions the agent may ask.** Call it
+for the fifth, tenth or twentieth time and it still works; the only bound is a
+30-minute ceiling on a *single* wait (`planModeHumanTimeoutMs`), which exists so an
+unattended terminal cannot wedge a CI job — it says nothing about how often the
+agent may ask. The one thing the agent cannot do is re-ask a batch of questions you
+have already **answered** in the same turn: that call returns a note saying so, as
+a non-error result, and the overlay does not open. A *cancelled* round records
+nothing, so an `Esc` you did not mean leaves the question askable — a mis-touch
+must never cost you the chance to answer. `/plan status` reports only the mode.
+
 **Dismissing a plan is not how you stop.** `Esc` on a plan card asks for a
 *better* plan — the agent is told to refine it and submit again — so a model that
 keeps submitting keeps getting cards. To stop the run itself, close the card with `Esc`, then **press `Esc`
@@ -2071,14 +2082,61 @@ that existed before this feature.
 **Which model a subagent runs on is your setting, not the model's.** The
 default (`team.model: 'main'`) keeps main-agent parity: every child runs the
 lead's own connection. Switch it to the **fast tier** or a **saved profile**
-from the settings screen's *Subagent model* row or with
-`/team model main|fast|<profile-name>` — useful when a fan-out of read-only
-scouts does not need the main model. The choice is re-resolved on every
+from the settings screen's *Subagent model* row — useful when a fan-out of
+read-only scouts does not need the main model. The choice is re-resolved on every
 dispatch, and an unusable one (tier off, profile deleted, key missing) falls
 back to the main model with a disclosed line in the dispatch report instead of
 failing the dispatch. The model itself still cannot downgrade its own
 delegation: a stale `model` key in a `task` call is ignored, exactly as before.
 
+**How wide a fan-out is also your setting.** `/settings` → `Team` (row four,
+directly under *Subagent model*) holds four values: `Team mode`, `Max subagents`,
+`Run at once` and `Supervisor`, adjusted with `Left` / `Right` (`Enter` toggles
+the two on/off rows). Nothing is written until you press `Ctrl+S` **on the main
+settings page** — the arrows edit a draft, and `Esc` on the `Team` page returns
+to the main page rather than saving. `Team mode` is the capability switch that
+used to be `/team on|off`, and it is the only place that saves it; a session
+started with `--no-team` shows `on (next launch)` rather than pretending the
+tool can still be added. The numbers are also settable without the screen:
+`aragon config set team.maxSubagents <n>`.
+
+Narrowing `Max subagents` also narrows `Run at once`, because a pool wider than
+its own population is meaningless; the follow-down is committed, so widening the
+population again does not silently restore a pool you did not ask for. And the
+width change never touches the model a session kit installed: only an explicit
+model choice releases that slot.
+
+**Or bypass the model's judgement entirely: `/team <brief>`.** The command plus
+the work in one line compiles your intent into a single user turn that tells the
+lead to call `task` once with that many children, so it shares the one dispatch
+path — same Esc, same report, same spend accounting — and then stays on:
+
+```
+/team -n 6 review the error handling in packages/cli/src/team
+/team --parts api,ui,docs audit the request path
+/team --read-only --parts perf,memory profile the parser
+```
+
+Forced mode is SESSION state, not a saved setting: the next message of any kind
+dispatches too, until `/team off`. It is enforced three ways, and the third one
+does not depend on the model's cooperation — the submitted directive, a
+`<forced_team_mode>` block in every later system prompt, and an end-of-turn gate
+that asks once (`Forced team mode: no dispatch last turn - asking the agent to
+dispatch now.`) when a turn used tools and dispatched nothing. The gate never
+fires twice for one request: a human submit refills the budget, a turn does not.
+While it is armed the status bar carries `Team 4` (`T4` on a narrow terminal).
+
+`/team` with no argument reports the forced state, capacity, the subagent model
+and where the switches live — and answers even in a `--no-team` session, where
+the honest answer is that this session has no team capability. Narrowing is
+always disclosed (`asked for 12; team.maxSubagents is 8`), `-n 0` is refused
+rather than silently becoming 1, and the notice says what the **next turn** will
+do rather than claiming children have started. `"off"` in quotes is a brief
+named `off`, not the keyword.
+
+`/subagent` is a **deprecated alias** of `/team`: same arguments, same
+behaviour, plus one toast saying so.
+
 ```
 > read the auth middleware, map the route table, and check the migration
 
@@ -2093,12 +2151,18 @@ 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.
+**Delegate wide, not deep.** Two to four subagents is usually enough. The
+default is **8 per dispatch and 8 in flight at once** (it was 5 and 3 before
+subagent-fanout); the hard maximum is 10 and no config file can raise it, so 8
+is a default you can move in either direction and 10 is the ceiling you cannot.
+Both numbers live in `/settings` (`Subagent fan-out`) and in
+`team.maxSubagents` / `team.maxConcurrent`.
+
+`maxConcurrent` is separate from `maxSubagents` on purpose: eight 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. **If you see rate-limit
+errors, lower `Run at once`** — that is the one number to change, and it is the
+only reason the two knobs are separate.
 
 **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
@@ -2134,9 +2198,9 @@ nothing is killed. A subagent still ends on the user's Esc, the explicit
 watchdog (lengthened 4× while supervised), or the supervisor's own
 replace/abandon verdict. One boundary to know: a session with NO fast wiring
 at all and `team.overseer: true` runs children with no wall clock whatsoever
-— they finish, or die on their own un-lengthened watchdog. `/team overseer
-off` is the escape hatch back to the legacy regime where
-`team.subagentTimeoutMs` is a hard abort again.
+— they finish, or die on their own un-lengthened watchdog. `Settings > Team` →
+`Supervisor` (or `aragon config set team.overseer false`) is the escape hatch
+back to the legacy regime where `team.subagentTimeoutMs` is a hard abort again.
 
 **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
@@ -2752,6 +2816,7 @@ This is the part that makes skills cheap enough to install a lot of:
 | Level | What the model gets | When |
 | --- | --- | --- |
 | 1 | Name, scope, and a one-line "what + when" | Always, in the system prompt. Whole catalog capped at 6 000 bytes. |
+| 1.5 | `<skill_triage>` protocol + up to 3 ranked `<skill_candidates>` | Always (protocol), rebuilt per task (candidates). ≤ 1 500 + ≤ 900 bytes. |
 | 2 | The full `SKILL.md` body + a list of bundled files | Only when the model calls `skill(name=…)` |
 | 3 | The bundled files themselves | Only when it reads them with `read_file` / `bash` |
 
@@ -2759,6 +2824,34 @@ A skill costs a line in the prompt rather than its whole body, so installing
 many of them stays cheap. The model decides on its own whether a task matches a
 skill — you do not have to name one.
 
+**Level 1.5 is what turns that from a claim into a step.** Reading a catalog is
+not the same as being told to read it: the catalog's own preamble is a statement
+("if a task matches one, load it"), and a statement the model has seen forty times
+is the one it skims. So the prompt now carries a `<skill_triage>` protocol that
+fixes *when* the decision happens — after the project guidance and the directory
+listing, before any plan or edit — plus a short candidate list computed from your
+message against the in-memory skill records (name, description, keywords). Both are
+local string work: no model call, no file read, no body loaded, so "which skills
+could apply?" costs zero context bytes beyond the block itself.
+
+Two consequences worth knowing:
+
+- **It is a guess, not a verdict.** The block says so in as many words, and the
+  model is told to load nothing when nothing fits. It never loads a skill for you.
+- **Silence on success, one line on failure.** When a strongly-matching skill was
+  available and the turn did real work without loading it, the run ends with one
+  `info` line naming the skill and pointing at `/skills route`. That happens at
+  most once per skill per session — a message printed every turn is a message you
+  learn to skip.
+
+`/skills route <text>` shows the scoring for any phrasing you type (or with no
+argument, for the last real task), including the runner-up and the threshold when
+nothing qualified. `/skills triage off` turns the whole level off for the session
+and `skills.triage=false` makes it permanent; either way the prompt returns to its
+pre-feature bytes. **Subagents are not triaged** — a child has no `skill` tool, so
+proposing skills to it would describe a capability it does not have; name the skill
+in the `task` description instead.
+
 At Level 2 the file list is split into what to read and what to run, and carries
 the skill's absolute root so the model can build real paths. The accompanying
 guidance is **platform-specific**: on Windows the `bash` tool runs `cmd.exe`, so
@@ -2834,7 +2927,8 @@ keeping `installedAt` and recording `updatedAt` + `previousVersion`.
 
 Interactively the same lives under `/skills …` (`/skills update <name> [--force]`,
 `/skills update --all`, `/skills list --sort=recent`, `/skills policy [mode]`,
-`/skills unload`, `/skills usage [--reset]`). Every usable skill also becomes a
+`/skills unload`, `/skills usage [--reset]`, `/skills triage [on|off]`,
+`/skills route [text]`). Every usable skill also becomes a
 slash command:
 
 ```
@@ -3071,19 +3165,20 @@ env / `.env` → CLI flags**.
 | `renderGovernor` | `true` | Widen the streaming frame interval when a frame is genuinely expensive. See [Render performance](#render-performance). |
 | `maxRenderIntervalMs` | `320` | Ceiling of the governor ladder, clamped to `[33, 1000]`. `33` flattens it to the pre-0.6 cadence without disabling the mechanism. |
 | `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. |
+| ~~`planModeMaxAskRounds`~~ | — | **Removed.** `ask_user` has no round limit any more, so there is nothing to configure. `aragon config set planModeMaxAskRounds 5` now prints an explanation and exits `2`; an existing key is removed from `config.json` at the next write. |
 | `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. |
 | `paste` | `true` | Recognise pasted text before Ink's key parser sees it: line breaks become buffer newlines instead of fifteen separate messages, escape SEQUENCES are removed whole (deleting only the introducer byte is what put `[38;2;18;52;86m` on screen and in the model's input) as are stray control bytes, and a paste above 6 lines or 400 characters collapses to a one-line placeholder that expands when you send. `false` treats pasted bytes as keystrokes, which is what 0.6.2 did. |
 | `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.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered. Written by the `Team mode` row in `Settings > Team` and nowhere else — `/team` never saves configuration. In a session already started with `--no-team` the row reads `on (next launch)`, rather than advertising a tool that is not there. |
+| `team.maxSubagents` | `8` | Subagents per dispatch, clamped to `[1, 10]`. 8 is the default; 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. A persisted `5`/`3` pair from an older install is migrated to `8`/`8` once (`fanoutMigrated` records that it happened, so moving back to 5/3 sticks). |
+| `team.maxConcurrent` | `8` | 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: lower this one if you collect 429s. |
+| `team.fanoutMigrated` | absent | Written only by the one-shot fan-out migration. Never set it by hand; a `true` here tells the next launch "5/3 was my choice, leave it alone". |
 | `team.subagentTimeoutMs` | `0` | One subagent's wall clock, clamped to `[0, 1800000]`. With `team.overseer: false` it is a hard abort (the legacy regime). With the supervisor on (the default) it **never aborts anything** — a positive value is only a compatibility source for the supervisor's first cadence check. `0` (the default) = use `team.overseerIntervalMs` / the structural 5 min instead. |
 | `team.dispatchTimeoutMs` | `0` | The whole dispatch's wall clock (and the `task` tool timeout), clamped to `[0, 3600000]`. `0` (the default) = no ceiling; only Esc ends a dispatch early. |
 | `team.maxTurnsPerSubagent` | `0` | Runaway-loop cap, clamped to `[0, 100]`. `0` (the default) = no cap, matching the lead. A subagent stopped at a positive cap is reported as `stopped: turn cap reached`, with whatever it had produced. |
-| `team.overseer` | `true` | The dispatch supervisor: one per dispatch on the fast model, ticking on a geometric cadence over every live subagent and deciding wait / nudge / replace / abandon. With the fast tier missing a tick degrades to an announced unassisted wait — never a kill; with this `false`, children run under the legacy hard ceilings exactly. `/team overseer on\|off` flips it live, and it is read per dispatch. |
+| `team.overseer` | `true` | The dispatch supervisor: one per dispatch on the fast model, ticking on a geometric cadence over every live subagent and deciding wait / nudge / replace / abandon. With the fast tier missing a tick degrades to an announced unassisted wait — never a kill; with this `false`, children run under the legacy hard ceilings exactly. The `Supervisor` row in `Settings > Team` flips it live (a settings save rebuilds the prompt), and it is read per dispatch. |
 | `team.overseerIntervalMs` | `0` | Supervisor cadence base, clamped to `[0, 3600000]`. `0` (the default) = the structural 300 s; a positive `team.subagentTimeoutMs` is honoured first when this is `0` (compat). Later checks grow ×1.6, clamped to `[60 s, 900 s]`; any nudge/replace/abandon resets that child's cadence to the base. Only meaningful while `team.overseer` is true. |
-| `team.model` | `"main"` | Which model every subagent runs on: `'main'` (the default - the lead's own connection), `'fast'` (the fast tier, re-resolved per dispatch), or `'profile'` (the entry named by `team.modelProfileId`). A **user-owned setting** — the model itself still cannot downgrade its own delegation, and an unusable choice falls back to the main model with a disclosed line in the dispatch report. Also settable via `/team model main\|fast\|<profile-name>` and the settings screen's **Subagent model** row. |
+| `team.model` | `"main"` | Which model every subagent runs on: `'main'` (the default - the lead's own connection), `'fast'` (the fast tier, re-resolved per dispatch), or `'profile'` (the entry named by `team.modelProfileId`). A **user-owned setting** — the model itself still cannot downgrade its own delegation, and an unusable choice falls back to the main model with a disclosed line in the dispatch report. Settable only through the settings screen's **Subagent model** row: `/team` no longer writes configuration. |
 | `team.modelProfileId` | `null` | The profile entry `team.model: 'profile'` binds to. Reference existence is not validated here — a dangling id degrades to the main model at resolution time, so deleting a profile never breaks a dispatch. |
 | `todo.enabled` | `true` | Master switch for todo planning. `false` means the `todo_write` tool is never registered — `/todo on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
 | `todo.panel` | `true` | Render the right-hand rail. Independent of `todo.enabled` on purpose: a screen-reader user wants the planning discipline without the column, and the system prompt varies one sentence accordingly. |
@@ -3108,6 +3203,7 @@ env / `.env` → CLI flags**.
 | `skills.integrity` | `warn` | What to do when `SKILL.md` no longer matches the copy you approved. `off` skips the check; `warn` flags it in `/skills list` and once per session; `strict` removes it from the catalog and makes `skill()` refuse it. Defaults to `warn` because editing an installed skill is a legitimate thing to do — `strict` suits CI and managed environments. |
 | `skills.usageTracking` | `true` | Keep local per-skill use counters to rank the catalog. Name, count and timestamp only; never transmitted. Inspect with `aragon skills usage`, erase with `--reset --yes`. |
 | `skills.toolPolicy` | `enforce` | How hard a skill's `allowed-tools` bites, for the turn it is loaded in. `off` disables it and says nothing about it to the model; `warn` runs the tool and reports it; `enforce` refuses. Unlike `skills.integrity`, a false positive here means a skill AUTHOR under-declared their own skill — which `aragon skills doctor` reports before it can bite. |
+| `skills.triage` | `true` | Put a short `<skill_candidates>` list in the system prompt for each new task, so "is an installed skill relevant?" is a step the agent is required to take instead of one it has to remember. Default on; turning it off restores the pre-feature prompt byte for byte. Matching is local over in-memory skill records — no model call, no file read. Explain any decision with `/skills route`, flip it live with `/skills triage off`. |
 | `log.level` | `info` | `silent` · `error` · `warn` · `info` · `debug` · `trace`. See [Files & logs](#files--logs) for what each level records. |
 | `log.toFile` | `true` | Write records to a file at all. `false` here is respected; `--log-file` overrides it for one run. |
 | `log.dir` | `""` | Log directory. Empty means `<home>/logs`. Only **absolute** paths are accepted — a relative one would mean a different directory for every working directory you launch from. |
@@ -3595,6 +3691,16 @@ VS Code 用户设置添加 `"terminal.integrated.copyOnSelection": false`，快
 
 编辑方案时可以当场验证：**Test connection**（Ctrl+R）用草稿里的服务商、模型、地址和解析后的密钥做一次真实往返，成功显示 `OK 812 ms` 与用量，失败给出分类结论和第二行“怎么办”；**Discover models**（Ctrl+F）列出该密钥实际可访问的模型供选择，只写回模型字段，不动上下文窗口与凭据。两者都作用于未保存的草稿，`Discover` 零 token；探测期间 Esc 只取消探测而不丢弃表单，修改服务商、模型或密钥后旧结论立刻回到未测试。
 
+## 子代理扇出宽度与 `/subagent`
+
+子代理扇出的默认值现在是**每次派单 8 个、同时最多 8 个在跑**（原为 5 和 3）。用户感知的“最多只有 3 个”来自并发上限而不是派单上限——只把派单数改大而并发不动，观感不会有任何变化，所以两个数一起改。硬上限仍是 10：8 是默认值，10 是天花板，中间由用户自己决定。
+
+在 `/settings` 的第 4 行 **Subagent fan-out** 里可以改这三个值：**Max subagents**、**Run at once**、**Supervisor**，用左右方向键调整。页内只改草稿，回到根设置页按 Ctrl+S 才真正落盘（本页页脚如实写着这一点，因为子页上根本没有 Ctrl+S 监听者）。把扇出调窄时并发会跟着下调，并且这个跟随**会写进补丁**：再把扇出调宽时并发停在你选的位置，不会被悄悄拉回。只改宽度**不会**释放会话 kit 给的子代理模型，只有显式改子代理模型才会。
+
+磁盘上仍带着旧默认值 5/3 的配置会在首次启动时被一次性迁移到 8/8，并写下 `team.fanoutMigrated` 标记；之后你手工改回 5/3 会一直保持，不会被再次迁移。其他任何组合（2/2、5/5、10/10）都不迁移。
+
+想绕开“模型自己决定要不要派单”时用 **`/subagent`**：它把你的意图编译成一条用户回合，要求 lead 在同一条 `task` 路径上一次性派出指定数量的子代理，因此 Esc、报告、费用记账、并发锁全部沿用既有实现。`-n 6` 指定数量，`--parts api,ui,docs` 指定拆分维度，`--read-only` 让每个子代理都不能写文件也不能跑 shell。不带参数时打印容量、子代理模型、监察开关与 team 开关，`--no-team` 会话里也照实回答。参数被收窄一定伴随披露（`asked for 12; team.maxSubagents is 8`），`-n 0` 直接报错而不是静默变成 1；提示语说的是“下一轮会派单”，不会假装子代理已经开始。并发报 429 时把 **Run at once** 调低即可。
+
 **Current custom** 保留旧式连接，可继续编辑原连接字段。创建方案时从磁盘上的旧式配置预填，不复制环境变量或 `--api-key` 的运行时密钥。专属密钥可保持、替换或切换为共享/环境凭据；修改服务商或地址后，必须明确选择保留原密钥，或重新输入。空地址在方案中表示服务商默认地址，快速方案不会继承主网关。
 
 启动优先级为 CLI 参数、环境变量、所选方案、旧式字段、默认值。界面显示启动覆盖；明确重新选择方案可对本次会话立即生效，重启仍遵循启动参数。专属密钥仅对对应角色和目标地址生效；主模型启动密钥不会跟随切换发往另一个网关。

package/dist/agent/controller.d.ts

@@ -25,6 +25,7 @@ import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
 import type { FilePatch } from '../tools/patch.js';
 import type { SubagentModelResolution } from '../team/model.js';
+import type { ForcedTeamState } from '../team/forced-mode.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
 import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
@@ -36,6 +37,7 @@ import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot
 import type { AcceptanceItem, TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
+import type { SkillRoutingReport } from '../skills/triage.js';
 import { type ConversationResetOptions, type ConversationResetResult } from './conversation-reset.js';
 import type { AgentMode } from './agent-mode.js';
 import type { NoticeLevel } from './reducer.js';
@@ -183,16 +185,19 @@ export interface ControllerDeps {
      */
     modelWindows?: ModelWindows;
 }
-/** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
+/**
+ * What `setAgentMode` actually adopted — see `AgentController.setAgentMode`.
+ *
+ * THIS IS ALSO WHAT `/plan status` REPORTS. A `PlanStatus extends AgentModeState`
+ * with `askRoundsUsed` / `maxAskRounds` existed until the round cap was deleted;
+ * keeping an empty sub-interface around would only leave a comment that every
+ * later reader has to work through to learn that nothing is missing.
+ */
 export interface AgentModeState {
     effective: AgentMode;
     /** Non-null only while a `plan -> build` switch is waiting for `agent_end`. */
     pending: AgentMode | null;
 }
-export interface PlanStatus extends AgentModeState {
-    askRoundsUsed: number;
-    maxAskRounds: number;
-}
 export interface PreflightResult {
     ok: boolean;
     message?: string;
@@ -235,6 +240,21 @@ export declare class AgentController {
     private readonly skills;
     private readonly skillsEnabled;
     private onSkillsChanged?;
+    /**
+     * This turn's routing result, or `null` when triage is off or nothing scored.
+     *
+     * It also carries the task it was computed for (`SkillRoutingReport.task`), so
+     * there is no separate copy of the turn's text to keep in step with it.
+     */
+    private turnRouting;
+    /** The previous turn's routing, for `/skills route` with no argument. */
+    private lastSkillRouting;
+    /** Did this turn call `skill(name)` successfully? The only proof of adoption. */
+    private skillLoadedThisTurn;
+    /** Tool calls this turn, EXCLUDING `skill` / `skill_find` (see §4.2.7). */
+    private toolCallsThisTurn;
+    /** Skills already reported as "not loaded" — a session says it once (I-T5). */
+    private readonly skillTriageNoticed;
     /** Mutable session cwd — tools resolve relative paths against this. */
     private cwd;
     /**
@@ -259,12 +279,25 @@ export declare class AgentController {
     private readonly structuredResultBlock;
     private effectiveMode;
     private pendingMode;
-    private askRounds;
+    /**
+     * Fingerprints of the question SETS the user ANSWERED in this turn. Bounded,
+     * and the bound is storage hygiene rather than a refusal rule — see
+     * `ASK_GUARD_LIMITS`.
+     *
+     * Replaces a numeric round counter that capped `ask_user` at four calls. There
+     * is no cap now; the only thing this prevents is the same batch of questions
+     * being put to the user twice, which is noise rather than information.
+     *
+     * Cleared in `prepareUserTurn` for a NEW turn only. A steer continuation is the
+     * same turn — clearing there would disable the guard exactly when a long turn
+     * most needs it (§4.1.6).
+     */
+    private readonly askedFingerprints;
     /** Static: whether this session could ever render a question overlay. */
     private readonly planInteractive;
     private readonly teamRegistered;
-    private teamEnabled;
     private readonly teamRuntime;
+    private forcedTeam;
     private readonly todoRegistered;
     private todoEnabled;
     private readonly todos;
@@ -445,6 +478,24 @@ export declare class AgentController {
      * semantics depend on whether a notice happened to be pending.
      */
     private flushPendingNotices;
+    /**
+     * THE BOUNDARY OF ONE TURN — and there are TWO call sites, which is the reason
+     * this takes an explicit flag instead of resetting everything unconditionally.
+     *
+     * `startPrompt` passes `{ steering: false }`: the user typed something new, so
+     * this really is a new turn. `continue()` passes `{ steering: true }` with the
+     * CONCATENATED queued steering text, which resumes the SAME turn.
+     *
+     * A steer continuation must not re-triage (the candidates would change mid-turn,
+     * and rebuilding the prompt aborts an idle compaction for no gain) and must not
+     * clear the answered-question guard (a long turn interrupted by one steer is
+     * exactly when a repeat question is most likely). Hence per-turn state is
+     * initialised in ONE branch.
+     *
+     * `steering` is REQUIRED and positional-second so each call site states which
+     * kind of turn it is starting, rather than letting a default make "new turn" the
+     * thoughtless option.
+     */
     private prepareUserTurn;
     /** Cancel pending startup as well as any engine run already in progress. */
     abort(): void;
@@ -583,9 +634,53 @@ export declare class AgentController {
      */
     applyPendingMode(): AgentModeState | null;
     /** Named read surface for `/plan status`, so no command reaches into internals. */
-    getPlanStatus(): PlanStatus;
-    /** Spend one `ask_user` round. Called from the tool, never from the UI. */
-    private takeAskRound;
+    getPlanStatus(): AgentModeState;
+    /**
+     * READ-ONLY guard probe, called by `ask_user` BEFORE it opens the overlay.
+     *
+     * No side effect of any kind: a check that also writes cannot be placed before
+     * the question without recording an answer that has not happened yet, and the
+     * "a cancelled round stays askable" rule would then be unimplementable.
+     */
+    private hasAnswered;
+    /**
+     * Record an ANSWERED question set, called by `ask_user` after a real answer.
+     *
+     * Evicts the oldest entry past `ASK_GUARD_LIMITS.maxRemembered`. That eviction
+     * is memory hygiene and NOT a refusal rule — a bounded rejection would be the
+     * deleted round cap wearing a bigger number.
+     */
+    private noteAnswered;
+    /** `/skills route` with no argument: the LAST turn's real routing result. */
+    getSkillRouting(): SkillRoutingReport | null;
+    /**
+     * One line when a confidently-matched skill was NOT loaded — and silence every
+     * other time (D-8).
+     *
+     * THE DISCIPLINE IS "SILENT ON SUCCESS, VISIBLE ON FAILURE". Announcing the
+     * candidates every turn would be ignored by the third day; announcing nothing
+     * ever would make the whole feature unfalsifiable. "A skill covered this task,
+     * you did the work anyway, and you never opened it" is precisely the failure this
+     * feature exists to fix, so it is the one case that speaks — and it names the
+     * command that explains it.
+     *
+     * SEVEN CONDITIONS, and the first one is the one that is easy to get wrong.
+     *
+     * 0. This turn was NOT aborted and NOT ended by an error.
+     *    `agent_end` is emitted unconditionally from a `finally` block in
+     *    `core/src/engine/agent.ts` and its payload carries no reason, no `aborted`
+     *    and no `error` field — so "did this turn finish normally?" has to be read
+     *    from this class's own state. `stopEngine()` sets `abortRequested` before it
+     *    calls `agent.abort()` and `agent_start` clears it, which makes it an exact
+     *    answer. Without this condition an Esc mis-touch would produce a line
+     *    criticising the model for not loading a skill: commentary in response to an
+     *    interruption.
+     *
+     * Conditions 5 and 0 are not redundant: 0 decides what counts as the end of a
+     * turn, 5 decides whether the turn did any work. With only 5, a tool call made
+     * before an abort would still trigger the notice.
+     */
+    private maybeReportSkillTriage;
     /**
      * Run `fn` with the idle watchdog paused.
      *
@@ -610,17 +705,47 @@ export declare class AgentController {
     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`. */
+    /**
+     * Whether `task` will actually dispatch - a DERIVED value.
+     *
+     * One truth (`config.team.enabled`) plus one immutable snapshot
+     * (`teamRegistered`). The previous version read a private copy that `/team
+     * on|off` hand-synchronised, which worked only while that command was the sole
+     * writer; the settings screen writes the config directly, so the copy would
+     * have kept saying `on` (P1-4 / AC-25).
+     */
     isTeamEnabled(): boolean;
     /**
      * Flip the live switch and re-render the prompt.
      *
+     * THE NAME IS KEPT (three call sites plus the settings path) but the body is
+     * one write: `setTeamConfig()` already clamps, bumps the revision and rebuilds,
+     * so there is no second place where a half-applied state can exist.
+     *
      * 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;
+    /**
+     * Arm forced team mode for this session (team-command-forced-dispatch §3.5).
+     *
+     * Returns the count actually adopted. The clamp is `[1, team.maxSubagents]`:
+     * `0`, a negative and a fraction are refused by the parser upstream (`-n 0` is
+     * a syntax error, not a clamp), so this is the boundary check of a value that
+     * crossed a module line - which is the one place `CLAUDE.md` asks for it, not a
+     * second validation of the same input.
+     *
+     * THE COUNT IS FROZEN for the rest of the session: `/team -n 2 <brief>` then a
+     * plain message keeps two children per turn, so the user's one expressed intent
+     * does not silently widen back to four.
+     */
+    armForcedTeam(count: number): number;
+    /** Disarm. IDEMPOTENT: disarming an unarmed session rewrites nothing. */
+    disarmForcedTeam(): void;
+    /** The armed state, read at render time by the chip and by `/team`'s status. */
+    getForcedTeam(): ForcedTeamState | null;
     getTeamConfig(): TeamConfig;
     /**
      * Adopt a new team config for this session and re-render the prompt (the block
@@ -634,8 +759,8 @@ export declare class AgentController {
      * One authority for the `task` report's disclosure line and its price
      * table: both read through here, so the header can never name one model
      * while pricing another. Re-resolved on every call for the reason
-     * `resolveFastTier` records - `/fast off`, a settings save and `/team model`
-     * all rewrite the inputs mid-session.
+     * `resolveFastTier` records - `/fast off`, a settings save and the `Subagent
+     * model` row all rewrite the inputs mid-session.
      */
     subagentModelResolution(): SubagentModelResolution;
     /** Refused mid-dispatch by `/team`; half a dispatch under two ceilings is not
@@ -677,7 +802,7 @@ export declare class AgentController {
      * THIS EXISTS BECAUSE `persistConfig` DOES NOT TOUCH THE RUNTIME (P1-2 /
      * AC-38). `App` reads `controller.getConfig()` on every render, and that
      * returns THIS object; the App's `persistConfig` only writes the file. So
-     * `/todo panel off` must call both, exactly as `/team max` does — with only
+     * `/todo panel off` must call both, exactly as settings' `Team` page does — with
      * the persist call the command reports success and changes nothing until the
      * next launch.
      *