@aragon-agent/cli 0.6.38 → 0.6.40

package/README.md

@@ -305,7 +305,7 @@ printf '%s\n' \
 
 ### Limits
 
-Four things this does **not** do, stated plainly because the audience for this
+Six things this does **not** do, stated plainly because the audience for this
 section is the one that would be misled by their omission.
 
 1. **There is no filesystem sandbox.** Tool paths are not confined to the
@@ -330,6 +330,395 @@ section is the one that would be misled by their omission.
    hand-written `/save` files and never reaches a TUI checkpoint; `pinned`
    sessions and files whose owner process is still alive are never deleted.
    `sessions show` and `sessions rm` accept any id, because you named it.
+5. **A cancelled turn can leave one tool call unanswered.** If an abort lands
+   between the assistant message and the first tool execution, that `tool_use` has
+   no `tool_result`. This window predates `cancel_request` (an `interrupt` and a
+   spent `--max-turns` expose exactly the same one), it is not widened by it, and
+   the next compaction refuses to compress such a history rather than shipping it
+   to a provider. In practice the turn is over either way: a `cancel_request` stops
+   the work, and the conversation continues on the next `prompt`.
+6. **Schema validation strength depends on the machine.** `ajv` is an optional
+   dependency of Core. With it, every JSON Schema keyword is enforced; without it,
+   `required`, nested `properties`, `items`, `enum`, `const`, the length/number
+   bounds and `additionalProperties: false` are enforced by this CLI's own bounded
+   validator and `pattern` / `format` / `multipleOf` are not. A `$ref` target is
+   followed only by `ajv`: without it the referenced subschema is not checked at
+   all, so a schema that leans on `#/definitions/...` for its real constraints
+   needs `ajv` present. `aragon doctor` and `aragon info --json` both report which
+   one you have, because silently weaker validation is the one failure a schema is
+   supposed to prevent.
+
+## Let the caller decide
+
+`--permission-mode ask` turns the three static postures into a conversation. With
+`--input-format bridge` (which requires `--output-format stream-json`), a tool that
+can change the world asks first:
+
+```bash
+printf '%s\n' \
+  '{"type":"prompt","id":"u1","text":"run the test suite"}' \
+  '{"type":"end"}' \
+| aragon exec --input-format bridge --output-format stream-json --permission-mode ask
+```
+
+```json
+{"type":"decision_request","requestId":"req_1","sessionId":"s1","kind":"tool","createdAt":1730000000000,"deadlineAt":1730000300000,"timeoutMs":300000,"tool":{"name":"bash","callId":"t1","input":{"command":"npm test"},"summary":"Run: npm test","turn":1},"agent":{"id":"lead","label":"lead","depth":0},"seq":7}
+```
+
+Answer it with a `decision` frame that names the request:
+
+```json
+{"type":"decision","respondsTo":"req_1","decision":"deny","reason":"not in this sandbox"}
+```
+
+The model receives a `tool_result` with `isError: true` that quotes the reason and
+tells it not to retry the same call, so it routes around the refusal instead of
+looping. `"scope":"session"` on an `allow` stops that tool being asked about again
+for the rest of the process; it is never written to `config.json`.
+
+| `decision_request.kind` | Asked when | Answer fields |
+| --- | --- | --- |
+| `tool` | `write_file` / `edit_file` / `bash` / `skill_create`, if not pre-authorised | `decision`, `scope?`, `reason?` |
+| `questions` | the model calls `ask_user` | `answers[]`, `cancelled?` |
+| `plan` | the model calls `submit_plan` | `planDecision`, `feedback?` |
+| `skill_install` | the model calls `skill_install` | `decision` |
+
+Which tools are gated is `CALLER_GATED_TOOLS`, reported by `aragon info --json` as
+`bridge.gatedTools`, so you never have to infer it. `skill_install` is not in that
+list because it has its own approval; `skill_create` is, because it writes
+`SKILL.md` plus arbitrary bundled files and had no gate at all.
+
+Four ways a wait ends, and they read differently on purpose: an answer (`allow` or
+`deny`), `--decision-timeout` expiring (`The caller did not answer within 300000
+ms. The tool was not run.`), the turn being interrupted (`The turn was interrupted
+before the caller answered.`), and a frame that could not be trusted (fail-closed
+denial plus `error{code:'bridge_frame_invalid'}`). `--on-decision-timeout error`
+makes a timeout end the turn with `stopReason: "error"` and exit code 1; the
+default `deny` treats it as an ordinary refusal and keeps going. There is no
+`allow` setting: silently granting access is what `auto` already is.
+
+Idle-watchdog pausing, the executor's two-phase timeout and the 5-second abort
+grace are handled inside the CLI, so a caller that thinks for four minutes gets a
+tool that still has its whole budget left.
+
+| Inbound frame | Fields | Effect |
+| --- | --- | --- |
+| `prompt` | `text`, `id?` | a turn; the id is echoed onto its events |
+| `steer` | `text`, `id?` | running guidance; refused when idle |
+| `interrupt` | `requestId?`, `id?` | abort the turn in flight, or delete a queued one |
+| `decision` | `respondsTo`, `decision`/`answers`/`planDecision` | answers a decision |
+| `tool_result` | `respondsTo`, `content`, `isError?` | answers a `tool_invoke` |
+| `tool_register` | `tools[]`, `id?` | replaces the caller's tool set at the next turn boundary |
+| `ping` | `id?` | `pong` with the current `seq` |
+| `end` | — | no more input; settle, persist, `result` |
+| `user` | `text`, `content?` | the v1 spelling of `prompt` |
+
+Anything else is ignored, because forward compatibility has to run in both
+directions. An unknown `respondsTo` is *not* ignored: it is an `error` with
+`code: "bridge_unknown_request"`, since silence would leave you waiting forever.
+
+### Budgets and limits
+
+| Flag | Default | Range | Meaning |
+| --- | --- | --- | --- |
+| `--decision-timeout <ms>` | `300000` | 1000..1800000 | how long one decision may wait |
+| `--on-decision-timeout <mode>` | `deny` | `deny` \| `error` | what an unanswered decision means for the turn |
+| `--caller-tool-timeout <ms>` | `60000` | 1000..600000 | ceiling for one caller tool call |
+
+All three, `--permission-mode ask`, and `--input-format bridge` itself are usage
+errors (exit 2, empty stdout) without a bridge to talk to - and so is a positional
+prompt or `--prompt-file`, because bridge prompts come from stdin only.
+
+## Serve your own tools
+
+`tool_register` hands the model tools you implement. The frame declares the WHOLE
+set (an empty array withdraws everything), and it is validated before anything is
+written - name format, collisions with host/team/skill names, a JSON Schema whose
+`type` is `object`, and a 16 KiB schema ceiling:
+
+```json
+{"type":"tool_register","id":"u0","tools":[{"name":"db_query","description":"Read-only SQL against the reporting replica.","parameters":{"type":"object","properties":{"sql":{"type":"string"}},"required":["sql"]},"timeoutMs":20000}]}
+```
+
+```json
+{"type":"ack","id":"u0","accepted":true,"scope":"lead","tools":["db_query"],"appliedAtTurn":1,"seq":2}
+```
+
+The model then calls it, and you answer:
+
+```json
+{"type":"tool_invoke","requestId":"req_2","sessionId":"s1","callId":"t2","turn":1,"tool":"db_query","input":{"sql":"select count(*) from users"},"timeoutMs":20000,"deadlineAt":1730000060000,"agent":{"id":"lead","label":"lead","depth":0},"seq":12}
+{"type":"tool_result","respondsTo":"req_2","content":"count\n40"}
+```
+
+`content` is a string or a list of text parts; an `image` part is refused with
+`bridge_unsupported_content` rather than silently dropped. `durationMs` on the
+emitted `tool_result` is measured by the CLI - a tool cannot self-report its own
+cost. Results are clipped at 100000 bytes with a `[truncated at 100000 bytes]`
+footer. Text only, this round.
+
+Four refusals, each with its own code: `caller_tools_too_many`,
+`caller_tool_bad_name`, `caller_tool_conflict`, `caller_tool_bad_schema` (all
+delivered as `ack{accepted:false}` and leaving the registry untouched), plus
+`plan_mode_read_only` when the session is in plan mode - caller tools have side
+effects this process cannot see, so plan mode refuses the frame outright.
+
+**Caller tools live outside the host's wrappers.** They are handed straight to the
+registry, so they are not covered by the plan gate, by a skill's `allowed-tools`
+ceiling, or by the job-notice tail. Plan mode refuses them wholesale and a name
+collision is refused at registration; those are the only two defences, and they
+are the two that registration time can still enforce.
+
+A run with `task` passes caller tools to the **lead only**. A fan-out would call
+`db_query` once per child, which is not in your budget - so `ack.scope` says
+`"lead"` and `tool_invoke.agent` is always `{id:"lead",label:"lead",depth:0}`.
+
+### A complete run, and a reference host
+
+```bash
+node packages/cli/examples/bridge-host.mjs -- npx aragon exec \
+  --input-format bridge --output-format stream-json --permission-mode ask
+```
+
+`examples/bridge-host.mjs` is a zero-dependency host: it approves `bash`, denies
+everything that would write, answers `ask_user` with a canned option, and serves
+`db_query` from a fake table. It is the executable form of the two sections above,
+and `exec-bridge-docs.test.ts` keeps it honest (`node --check`, plus both headings
+have to exist).
+
+### Honest limits
+
+- **Approval is authorisation, not isolation.** A `bash` you approved runs with
+  your privileges and no sandbox, exactly as it does in `auto`.
+- **Tool arguments travel on the wire.** `tool_call`, `tool_invoke` and the audit
+  log all carry `input`, so never put a secret in a tool argument.
+- **`scope: "session"` lives in memory and dies with the process.** `--resume`
+  does not bring back "you allowed bash last time", deliberately.
+- **`seq` is per process.** A resumed session keeps the conversation, not the
+  counter.
+
+## Many conversations in one process
+
+`--threads` serves N **isolated** conversations from one process: each has its own
+controller, history, session file, `todo` list, prompt queue and account. One process
+serves fifty tenants instead of fifty processes each paying startup, a skills scan and a
+config load.
+
+```bash
+aragon exec --threads --input-format bridge --output-format stream-json
+```
+
+```jsonc
+{"type":"thread_open","id":"t1","threadId":"tenant-a"}
+{"type":"prompt","id":"p1","threadId":"tenant-a","text":"summarise the open issues"}
+{"type":"thread_open","id":"t2","threadId":"tenant-b"}
+{"type":"prompt","id":"p2","threadId":"tenant-b","text":"what changed in the last release?"}
+{"type":"thread_close","threadId":"tenant-a"}
+```
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--threads` | off | Thread multiplexing. Requires `--input-format bridge` **and** `--output-format stream-json`. |
+| `--max-open-threads <n>` | 4 | How many conversations may exist at once (1-8, including the default `main`). |
+| `--thread-concurrency <n>` | 2 | How many threads may hold a request in flight. Cannot exceed `--max-open-threads`. |
+
+Four rules that answer most questions:
+
+- **A frame without `threadId` lands on `main`**, which is opened for you. A v1 caller
+  that never heard of threads keeps working unchanged.
+- **`thread_open` is asynchronous, and its prompts are not dropped.** Send `thread_open`
+  and `prompt` back to back; the prompt is queued until the thread is ready.
+- **`interrupt` stays process-level.** `interrupt{threadId}` is refused with
+  `interrupt_is_process_level` - silently turning it into "cancel one request" would make
+  "the user pressed Ctrl-C" and "the backend withdrew a request" indistinguishable, and
+  their exit codes differ. Use `cancel_request{threadId}` for one request. `interrupt`
+  with a `requestId` and no `threadId` keeps its other meaning, unchanged since v1: it
+  deletes that one queued turn (exit code 0) and touches nothing else.
+- **Thread frames sent to a run without `--threads` are refused, not ignored.**
+  `thread_open` / `thread_close` / `thread_list` answer
+  `ack{accepted:false, code:'threads_disabled'}`, so a host that pointed the wrong
+  invocation at its thread client learns it immediately instead of waiting for an `ack`
+  that will never come.
+- **The process ends when stdin ends AND every thread is closed.** `end` (or closing stdin)
+  finishes every queue, `thread_close{settle}` waits for the request in flight, and only
+  then is `result` written - one `result` for the process, with `result.threads.items`
+  carrying each tenant's own account. `result.usage` / `result.cost` are the sums, and
+  `cost.known` is true only if **every** thread knew its price.
+
+`--max-turns` is refused with `--threads` (a process-wide turn budget has no honest
+meaning across N conversations); use `--request-max-turns`, which is per request. A thread
+never resumes: `--resume` stays a process-level, `main`-only feature.
+
+Each thread writes its own session file named `<base>-<threadId>` - the shape of the file
+is unchanged, the name is a convention. `aragon sessions` lists them like any other.
+Locking is unchanged, including its documented limit: a lock is stamped once and expires
+after 600 s, so a thread that runs longer than ten minutes can be overtaken in another
+process.
+
+## Intervene in the data flow: lifecycle hooks
+
+Approval answers *"may the model do this?"*. Hooks answer *"what exactly does it say, and
+what exactly does it see?"* - the question every compliance, redaction and tenant-scoping
+integration actually asks.
+
+```jsonc
+// 1. Install a redactor for one tool, on one thread (omit threadId for `main`).
+{"type":"hook_register","id":"h1","threadId":"tenant-a","hooks":[
+  {"point":"tool_post","tools":["read_file"],"name":"redactor","timeoutMs":2000}
+]}
+
+// 2. The CLI asks before the result reaches the model:
+{"type":"hook_request","requestId":"c1","hookRequestId":"hx-1","hookId":"h1",
+ "point":"tool_post","payload":{"tool":"read_file","callId":"c1",
+ "content":[{"type":"text","text":"AKIA..."}],"isError":false}}
+
+// 3. You answer with the round trip's id:
+{"type":"hook_answer","respondsTo":"hx-1","action":"replace","content":"[REDACTED]"}
+```
+
+Four points, one per edge of the data flow, and no fifth:
+
+| Point | Where | Legal actions | Use it for |
+| --- | --- | --- | --- |
+| `prompt_pre` | caller -> host | `allow`, `rewrite{text}`, `deny` | Tenant prefixes, input policy, flattening rich text |
+| `turn_start` | host -> model | `allow`, `inject{text}` | Retrieval, per-turn instructions |
+| `tool_pre` | model -> world | `allow`, `rewrite{input}`, `deny` | Inject `tenant_id`, force `--dry-run`, clamp paths |
+| `tool_post` | world -> model | `keep`, `replace{content}`, `deny` | Redaction, PII removal, compressing huge results |
+
+The details that decide whether an integration works:
+
+- **Answer `hookRequestId`, not `requestId`.** One hook fires many times inside one
+  request.
+- **`tool_pre` rewrites are re-validated** against the tool's own schema. An illegal
+  rewrite is refused as `invalid` rather than blamed on the model, and never reaches the
+  executor.
+- **`tool_post` is the outermost wrapper**, so it also covers denial text, a tool's own
+  error output and the `<job_notices>` tail of a background job - the three places a
+  secret actually leaks from.
+- **A human always approves the rewritten arguments**, never the ones that were replaced.
+- **An unanswered hook fails closed** after `--hook-timeout` (default 5 s): the tool does
+  not run and `tool_post` withholds the result. `--on-hook-timeout allow` is for purely
+  observational hooks, and clamps the timeout to 30 s so two round trips cannot eat a
+  tool's whole 120 s budget. `--on-hook-timeout error` also marks the request failed.
+- **Every `hook_request` gets exactly one `hook_resolved`** (`answered`, `timeout`,
+  `aborted`, `invalid`, `saturated`, `unregistered`), so your bookkeeping can close.
+- **Hooks do not wrap caller tools.** Tools you register with `tool_register` are yours,
+  executed as given: redact inside your own implementation (I-H11).
+- **Hooks are per thread.** A hook registered on `tenant-a` never sees `tenant-b`'s data.
+
+`packages/cli/examples/bridge-host-threads.mjs` is a complete host: two threads, one redactor, per-tenant
+accounting. `node packages/cli/examples/bridge-host-threads.mjs --dry-run` prints the frames without
+spawning anything.
+
+
+## Hand back a typed result
+
+`--result-schema <path>` replaces "the last paragraph the model happened to write"
+with **an object that satisfies your JSON Schema**. Nothing in the answer is left to
+a parser you have to write and then distrust.
+
+```json
+{"type":"object",
+ "properties":{"findings":{"type":"array","items":{"type":"string"}},"risk":"low|medium|high"},
+ "required":["findings"],"additionalProperties":false}
+```
+
+```bash
+aragon exec --output-format json --result-schema ./findings.json \
+  "List the risks in packages/cli/src/exec/options.ts"
+```
+
+```json
+{"type":"result","isError":false,"stopReason":"end_turn","exitCode":0,
+ "result":"{\"findings\":[\"…\"],\"risk\":\"low\"}",
+ "structured":{"value":{"findings":["…"],"risk":"low"},"schemaName":"findings.json",
+               "schemaBytes":183,"attempts":1,"acceptedAt":1730000000000},
+ "text":"Here is what I found, with two caveats.","...":"..."}
+```
+
+Four things to know, because each one is a place the obvious assumption is wrong:
+
+1. **`result.result` becomes the JSON text, and the prose moves to `result.text`.**
+   The `| jq -r .result` idiom in the CI section above keeps working, and under a
+   schema "the answer" is the object. Nothing is lost: the model's own words are in
+   `text` (and, for a stream, in the `assistant` events).
+2. **Failure is a shape, not a mood.** If the model never submits something that
+   validates, `result.structured` is an **explicit `null`** and
+   `error.code` is `result_schema_unsatisfied`. An absent field would be
+   indistinguishable from an older build that never had the feature, which is why the
+   failure case is `null` rather than missing.
+3. **The model gets told what was wrong, inside the same run.** A rejected submission
+   returns the failing field paths to the model, and `--result-repair-turns` (default
+   `1`, max `2`) lets it fix them and submit again. A repair is an ordinary turn, so
+   `--max-turns` still binds - and a schema run needs at least two of them, which is
+   why `--max-turns 1` plus `--result-schema` prints a warning rather than a refusal.
+4. **Validation has two layers, and you can see which one you have.** With `ajv`
+   installed, every JSON Schema keyword is enforced. Without it (it is an *optional*
+   dependency of Core) `required`, nested `properties`, `items` and
+   `additionalProperties: false` are still enforced by this CLI's own bounded
+   validator; `pattern`, `format` and `multipleOf` are not. `aragon doctor` prints
+   `ajv: present|absent`, and `aragon info --json` reports it as `result.ajv` - the
+   strength of the check is a property of the machine, so it is stated rather than
+   implied.
+
+`--on-result-unsatisfied error|continue` decides what an unsubmitted result means:
+`error` (the default) ends the run with exit `1`, `continue` keeps a long-lived bridge
+process serving the next request with exit `0` — and still sets `result.isError: true`,
+because a script that reads the exit code and a script that reads the JSON must not be
+told different things.
+
+## One request at a time: budgets, billing and cancellation
+
+With `--input-format bridge` a single process serves many `prompt` frames. Process
+budgets (`--max-turns`, `--max-duration`) bound the whole process, which is the wrong
+unit for a backend serving several users: one request can spend the entire allowance,
+and there is no way to stop just that one.
+
+Every `prompt` now ends with its own account:
+
+```json
+{"type":"request_end","requestId":"u1","requestSeq":1,"stopReason":"completed",
+ "isError":false,"turns":2,"durationMs":8123,
+ "usage":{"inputTokens":1234,"outputTokens":567,"totalTokens":1801},
+ "cost":{"amount":0.0123,"currency":"USD","known":true},
+ "result":"…","error":null,"seq":17}
+```
+
+The numbers are a **difference**, not a snapshot: two `request_end` usages add up to
+the process `result.usage`, and one request's `cost` is what running that request
+alone would have cost. `cost.known: false` means this model has no price table -
+reported as "unknown", never as a free ride.
+
+Two flags, both bridge-only, both absent by default:
+
+```bash
+# Two turns and at most 30 s per request; the process outlives both.
+aragon exec --input-format bridge --output-format stream-json \
+  --request-max-turns 2 --request-max-duration 30000 < prompts.ndjson
+```
+
+A request that runs out of budget ends with `request_end{stopReason:"max_turns"}`
+(or `"timeout"`) and **the process keeps serving**. The process-level `stopReason`
+and exit code are untouched: one user's ceiling is not the run's failure.
+
+And one request can be withdrawn without taking the process down:
+
+```json
+{"type":"cancel_request","id":"c1","requestId":"u2"}
+{"type":"ack","id":"c1","requestId":"u2","accepted":true,"code":"queued_cancelled"}
+{"type":"request_end","requestId":"u2","stopReason":"cancelled","isError":false,"turns":0,"...":"..."}
+```
+
+- A request still **queued** is deleted, and its `request_end` has `turns: 0` and no
+  `requestSeq` — it was never served, so it never had one.
+- A request **in flight** is stopped (`ack{accepted:true}`) and reports
+  `stopReason: "cancelled"`; the next `prompt` runs normally.
+- A request that is **already finished** answers `ack{accepted:false,
+  code:"unknown_turn"}` and aborts nothing. That is deliberate and load-bearing: a
+  late cancel for a completed request must never kill the next one.
+
+Use `interrupt` to stop the run (process-level, `128 + signo`) and `cancel_request` to
+stop one request. Two different questions, two frames.
 
 ## Usage
 
@@ -553,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 |
@@ -587,8 +977,11 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 
 ## Keybindings
 
+`Ctrl+G` 打开**快捷键抽屉**，把下面所有键位连同「作用关键词」和选中行的说明一次性列出来；`/keys` 打开同一份清单。详见 [快捷键抽屉与任务摘要](#快捷键抽屉与任务摘要)。
+
 | Key | Action |
 | --- | --- |
+| `Ctrl+G` | **快捷键抽屉**：自上而下列出全部快捷键、各自的作用关键词，选中行下方再给一句话说明。`Up`/`Down`（或 `k`/`j`）移动、`PgUp`/`PgDn` 翻页、`d` 切换状态详情行、`r` 重新生成任务摘要、`Esc` 关闭。再按一次 `Ctrl+G` 关闭；其它参考类浮层打开时按它会直接接管，等待决策的 `confirm` / `question` / `plan` 除外 |
 | `Enter` | 空闲时发送，运行时加入队列；收到 Core 已纳入会话的接收凭据后才移除 Queue 提示 |
 | `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | 插入换行。应用默认请求终端区分修饰键（Windows 用 win32-input-mode，macOS/Linux 用 kitty/modifyOtherKeys），Shift+Enter 在支持的终端开箱即用；不支持的终端用 Ctrl+J。参见 [终端设置](#terminal-setup-for-shiftenter) |
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
@@ -655,6 +1048,55 @@ Turn the whole thing off with `--no-mouse`, `ARAGON_MOUSE=0`, or
 nothing in full-screen mode — it does not fall back to editing your draft, which
 is what it used to do. Inline mode is unaffected either way.
 
+## 快捷键抽屉与任务摘要
+
+### 抽屉
+
+头部右上角现在只有一件事：`^G more`。按下去，右侧滑出一块只读的抽屉，把**所有**
+快捷键自上而下列出来——每一行是「键 + 作用关键词」，选中行下面再用一句话解释它是
+干什么的。`Ctrl+G` 再按一次关闭；任何其它浮层打开时按它，抽屉会直接接管（而不是
+被静默吞掉）——只有 `confirm` / `question` / `plan` 这类**等你决策**的浮层例外：
+它们只能由 `Esc` 收尾，抽屉不会把键盘抢走，头部此刻显示的也正是 `Esc close`。`/keys [query]` 是同一个入口的命令面：脚本、粘贴和读屏软件都得有路
+可走。
+
+- 分组固定为 `COMPOSE / RUN / PANELS / SESSION / VIEW`；窗口够高时组头单独成行，
+  80×24 这种常见尺寸下组头让位，把行数留给你真正要看的键。
+- 关键词列**从表里推导**（`min(最长键, ceil(内容宽 * 0.55))`），不是写死的常量：
+  任何一条关键词都**不会被截成残词**，放不下的那一行改成「键一行、关键词缩进一行」
+  堆叠显示，只有那一行变高。
+- 翻页 = 移动光标一页。窗口永远覆盖选中行，所以「这个键是干什么的」那句话不会滑出
+  屏幕。
+- 抽屉里只有两个动作键：`d` 切换状态详情行（原来 `Ctrl+G` 的功能搬到这里），
+  `r` 重新生成任务摘要。回车不会启动任何东西：误触成本最高的界面就是「按回车会开
+  新终端」的参考面。
+
+### 头部任务摘要
+
+「工作目录」右侧多了一格**任务摘要**：会话（或一次 `/clear` 之后的新任务）的第一
+条提示词提交时，用**fast 模型**把它压成几个词，语言跟随提示词本身——中文提示词出
+中文，英文出英文。它回答的是「我在干什么」，而 `provider:model` 回答「我在用什
+么」。
+
+- 一次任务只生成一次（头部是身份条，不是实时字幕）；`/task refresh` 或抽屉里的
+  `r` 是唯一的手动重算入口。
+- `/clear`、`/reset` 和会话切换都会清空它；`/clear screen` 只清屏，所以保留它。
+  `/resume` 恢复会话时，用恢复后的第一条用户消息重建一次。
+- fast 档不可用、超时、被中止、模型乱写、语言不符——全部收敛到同一条降级：**用户
+  自己那句话的前缀**。它不可能编造，语言必然匹配，头部也不会突然空掉。
+  `taskSummary.fallback=false` 时改为什么都不显示。
+- 摘要**不进**对话历史、不进会话文件、不进 `config.json`，它只是视图状态。
+- 隐私：提示词首句会被发到 fast 档所配置的供应商。`taskSummary.enabled=false`
+  是硬开关，也可以 `ARAGON_TASK_SUMMARY=0`。
+
+| 键 / 命令 | 作用 |
+| --- | --- |
+| `Ctrl+G` | 打开 / 关闭快捷键抽屉 |
+| `/keys [query]` | 打开抽屉，`query` 按 id / 键位 / 关键词预过滤 |
+| `/task` | 打印当前任务摘要、来源和生成时间 |
+| `/task refresh` | 用最后一条用户消息重新生成摘要 |
+| `aragon config set taskSummary.enabled false` | 关掉摘要与那次模型调用 |
+| `aragon config set taskSummary.fallback false` | 失败时显示空，而不是用户原话前缀 |
+
 ## Quick prompt library
 
 `↑` history remembers what you said. It does not remember what you say *every*
@@ -1150,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`
@@ -1638,6 +2090,39 @@ 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` → `Subagent fan-out`
+(row four, directly under *Subagent model*) holds the two numbers and the
+supervisor switch: `Max subagents`, `Run at once` and `Supervisor`, adjusted
+with `Left` / `Right`. Nothing is written until you press `Ctrl+S` **on the main
+settings page** — the arrows edit a draft, and `Esc` on the fan-out page returns
+to the main page rather than saving. The same numbers are reachable without the
+screen: `/team max <n>`, `/team overseer on|off`, or
+`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 with `/subagent`.** It compiles your
+intent into one user turn that tells the lead to call `task` once with that many
+children, so the escape hatch shares the single dispatch path — same Esc, same
+report, same spend accounting:
+
+```
+/subagent -n 6 review the error handling in packages/cli/src/team
+/subagent --parts api,ui,docs audit the request path
+/subagent --read-only --parts perf,memory profile the parser
+```
+
+With no argument it reports capacity, the subagent model, the supervisor and the
+team switch — 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.
+
 ```
 > read the auth middleware, map the route table, and check the migration
 
@@ -1652,12 +2137,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
@@ -2311,6 +2802,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` |
 
@@ -2318,6 +2810,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
@@ -2393,7 +2913,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:
 
 ```
@@ -2630,13 +3151,14 @@ 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.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. |
@@ -2667,6 +3189,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. |
@@ -3154,6 +3677,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 参数、环境变量、所选方案、旧式字段、默认值。界面显示启动覆盖；明确重新选择方案可对本次会话立即生效，重启仍遵循启动参数。专属密钥仅对对应角色和目标地址生效；主模型启动密钥不会跟随切换发往另一个网关。