@armadra/agent 0.6.2 → 0.6.4

package/docs/agents.md

@@ -38,7 +38,7 @@ model: fast # inherit（缺省）| fast | strong（models.aliases）| provider/m
 thinking: low
 max-turns: 20 # 缺省 30
 isolation: none # none（缺省）| worktree
-background: false
+background: false # 不写 = 按 config subagents.background
 runner: ama # ama（缺省）| claude | codex | acp:<程序>
 ---
 
@@ -60,16 +60,16 @@ runner: ama # ama（缺省）| claude | codex | acp:<程序>
 
 ### `task` 参数
 
-| 参数                                             | 说明                                                                       |
-| ------------------------------------------------ | -------------------------------------------------------------------------- |
-| `prompt`                                         | 必填，完整的任务说明                                                       |
-| `agent`                                          | 类型名，缺省 `general`；也可以是外部 Agent（见「外部 Agent」节）           |
-| `description`                                    | 显示用的短标签                                                             |
-| `background`                                     | `true`：立即返回 `taskId`，完成后父会话收到通知；缺省取类型的 `background` |
-| `taskId`                                         | 续聊：向已有任务的子会话追加一条消息（忽略 `agent` / `tools` / `model`）   |
-| `isolation`                                      | `worktree`：在独立 git worktree 里运行                                     |
-| `budgetUsd`                                      | 外部 Agent 的美元预算                                                      |
-| `tools` / `model` / `thinkingLevel` / `maxTurns` | 保留的高级参数（描述里不展开）                                             |
+| 参数                                             | 说明                                                                                                                                                     |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt`                                         | 必填，完整的任务说明                                                                                                                                     |
+| `agent`                                          | 类型名，缺省 `general`；也可以是外部 Agent（见「外部 Agent」节）                                                                                         |
+| `description`                                    | 显示用的短标签                                                                                                                                           |
+| `background`                                     | `true`：立即返回 `taskId`，完成后父会话收到通知；`false`：等结果。缺省取类型的 `background`，类型没写时按 `subagents.background`（见下文「前台与后台」） |
+| `taskId`                                         | 续聊：向已有任务的子会话追加一条消息（忽略 `agent` / `tools` / `model`）                                                                                 |
+| `isolation`                                      | `worktree`：在独立 git worktree 里运行                                                                                                                   |
+| `budgetUsd`                                      | 外部 Agent 的美元预算                                                                                                                                    |
+| `tools` / `model` / `thinkingLevel` / `maxTurns` | 保留的高级参数（描述里不展开）                                                                                                                           |
 
 同一条回复里的多个 `task` **并行**执行，由会话的任务池限流（`subagents.maxConcurrent`，缺省 4）；排队超过
 `subagents.maxPending`（缺省 16）直接报错，提示模型不要重试。并行且会写文件的任务请用 `isolation: "worktree"`。
@@ -79,9 +79,31 @@ runner: ama # ama（缺省）| claude | codex | acp:<程序>
 全文写到会话目录的 `outputs/<会话 id>-<taskId>.md`（内存会话写到系统临时目录）。轮数用尽且最后一步停在工具结果上时，
 ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[Turn limit reached; …]`，状态 `max_turns`。
 
+### 前台与后台
+
+是否后台的优先级：调用参数 `background` > 类型定义的 `background:` > config `subagents.background`。
+`subagents.background` 缺省 `auto`：交互界面、RPC、ACP 下后台（模型需要结果才写 `background: false`），`-p` 下前台；
+`always` / `never` 固定。两种缺省对应两版 `task` 工具描述，会话内不变，不影响缓存前缀稳定。
+
+前台任务运行中可以转后台，任务不中断，`task` 工具调用立即返回一段固定英文结果（含 `taskId` 与输出文件），完成后照常发
+`<task-notification>`：
+
+- 交互界面：`Ctrl+B` / `/tasks bg [id]` / Agent 栏里按 `b`（见 [tui.md](tui.md)「子 Agent」）；
+- RPC：`background_task { taskId? }`（[rpc.md](rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
+  不给 `taskId` 时转全部前台运行中任务，正在 `task_ctl wait` 的等待也一并打断；
+- 自动：`subagents.autoBackgroundAfterMs` 大于 0 时，前台任务运行超过该毫秒数自动转后台（缺省 0 关闭）。
+
+转后台发 `subagent_background { taskId, parentToolCallId, reason }` 事件（`user` / `timeout` / `host`）。
+父会话 `Esc` 中断只连带中止仍在前台的任务，后台任务不受影响；停止后台任务用 `task_ctl stop` 或 `/tasks stop`。
+
+`-p` 下（缺省前台）显式 `background: true` 仍生效：主回合结束后若还有任务在跑或通知待投递，stderr 一行提示，等它们结束、
+跑完通知回合再输出，输出的文本是最后一条助手回复；等待受 `--max-turns` / `--max-cost` / `limits.*` 约束（到限停止等待、
+退出码 8），`Ctrl+C` / SIGTERM 照常中止（未结束的任务随会话关闭被停止，退出码 130 / 143）。`--output-format json` 的结果带
+`tasks`（同 `getStats().tasks`）。
+
 ### 后台任务与 `task_ctl`
 
-`background: true` 立即返回 `taskId` 与输出文件路径。任务完成后，ama 在父会话空闲时投递一条 user 消息（`origin: "task"`）
+后台任务立即返回 `taskId` 与输出文件路径。任务完成后，ama 在父会话空闲时投递一条 user 消息（`origin: "task"`）
 并开始新回合；父正忙则等这一轮结束再投递，不打断。多条通知按完成顺序到达：
 
 ```text
@@ -95,13 +117,13 @@ ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[T
 
 `task_ctl` 的动作：
 
-| `action` | 说明                                                                               |
-| -------- | ---------------------------------------------------------------------------------- |
-| `list`   | 列出本会话的任务：编号、类型、状态、轮数、token、耗时、是否后台、描述              |
-| `wait`   | 等任务结束（`timeoutMs` 缺省 30 000，最多 600 000）；超时说明仍在运行              |
-| `stop`   | 停止任务，返回终态                                                                 |
-| `output` | 运行中返回已有输出，结束后返回最终文本（同样有 50 KB 上限）                        |
-| `send`   | 向任务追加一条消息并放到后台运行（等价于 `task{taskId, prompt, background:true}`） |
+| `action` | 说明                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| `list`   | 列出本会话的任务：编号、类型、状态、轮数、token、耗时、是否后台、描述                                   |
+| `wait`   | 等任务结束（`timeoutMs` 缺省 30 000，最多 600 000）；超时说明仍在运行；被转后台时立即返回并说明不必再等 |
+| `stop`   | 停止任务，返回终态                                                                                      |
+| `output` | 运行中返回已有输出，结束后返回最终文本（同样有 50 KB 上限）                                             |
+| `send`   | 向任务追加一条消息并放到后台运行（等价于 `task{taskId, prompt, background:true}`）                      |
 
 ### 续聊、保留与 resume
 
@@ -122,20 +144,22 @@ worktree 里的编辑不记进父会话的检查点。注意：worktree 不共
 
 ### 事件与统计
 
-RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
+RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
 `getStats().tasks` 给出任务总数、运行中数量与按状态的计数；子会话的缓存命中与重计费仍汇总在 `cache.subagents`。
 RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定义文件路径）。交互界面的 `/tasks`、`/agents` 与 task 工具行的折叠显示见 [tui.md](tui.md)「子 Agent」。
 
 ### 配置
 
-| 键                                | 说明                                        |
-| --------------------------------- | ------------------------------------------- |
-| `subagents.maxConcurrent`         | 同时运行的子 Agent，缺省 4                  |
-| `subagents.maxPending`            | 排队上限，缺省 16                           |
-| `subagents.defaultModel`          | 子 Agent 缺省模型，不设继承父会话           |
-| `agents.dirs`                     | 追加的定义目录                              |
-| `agents.<类型>.model`             | 某个类型的模型（如让 `explore` 用便宜模型） |
-| `models.aliases.fast` / `.strong` | 定义文件里 `model: fast / strong` 的映射    |
+| 键                                | 说明                                                                             |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `subagents.maxConcurrent`         | 同时运行的子 Agent，缺省 4                                                       |
+| `subagents.maxPending`            | 排队上限，缺省 16                                                                |
+| `subagents.defaultModel`          | 子 Agent 缺省模型，不设继承父会话                                                |
+| `subagents.background`            | `auto`（缺省）\| `always` \| `never`，见「前台与后台」；用户 / 项目 / 宿主级都认 |
+| `subagents.autoBackgroundAfterMs` | 前台任务运行超过该毫秒数自动转后台，缺省 0（关闭）；用户 / 项目级都认            |
+| `agents.dirs`                     | 追加的定义目录                                                                   |
+| `agents.<类型>.model`             | 某个类型的模型（如让 `explore` 用便宜模型）                                      |
+| `models.aliases.fast` / `.strong` | 定义文件里 `model: fast / strong` 的映射                                         |
 
 ### 限制
 

package/docs/en/host-api.md

@@ -164,4 +164,8 @@ Return `"warm"` / `"stop"` (a Promise is fine). `"stop"` skips the request and s
 
 ## Embedding in Armadra
 
-Armadra starts ama with a profile: `ama --profile <path>`. The profile's `host` points to its adapter (`ama-armadra.cjs`) and also carries instructions, skillDirs, hooksFile, authFile, sessionDir and `trustProject`. The adapter returns `undefined` when `ARMADRA_NODE_ID` is missing, so the same profile behaves as plain ama outside the canvas. Contract details are in [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.
+Armadra starts ama with a profile: `ama --profile <path>`. The profile's `host` points to its adapter (`ama-armadra.cjs`) and also carries instructions, skillDirs, hooksFile, authFile, sessionDir and `trustProject`. The adapter returns `undefined` when `ARMADRA_NODE_ID` is missing, so the same profile behaves as plain ama outside the canvas.
+
+Interface defaults with a profile: `ui.quietStartup: "header"` and `ui.statusLine: "compact"` (the last line is the status bar, which the host parses by `·`). The agent bar (`ui.agentBar`) is no longer off by default; it is `auto` as in a standalone terminal. A host that shows sub-tasks itself and does not want the bar writes `{ "ui": { "agentBar": "off" } }` into the config file its profile's `config` points to.
+
+Contract details are in [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.

package/docs/en/providers.md

@@ -170,7 +170,7 @@ ama auth logout chatgpt                # siwc revokes the refresh token first, t
 | Quota              | only known when exceeded (429); set a weekly cap for ama under ChatGPT → Settings → Usage → App limits                                                                                                                  | response headers, `codex.rate_limits` events, `ama auth status` queries `wham/usage`                                                                                            |
 | Logout             | calls `revocation_endpoint`, then deletes locally                                                                                                                                                                       | deletes locally only                                                                                                                                                            |
 
-**Model list**: `chatgpt` has no built-in model table (`chatgpt/<slug>` accepts any slug). After a successful `ama auth login chatgpt`, ama deletes the old cache and calls the model list endpoint once (siwc `GET /v1/models`, codex `GET /models?client_version=…`; read-only, no usage consumed; failures are silent and the output suggests `ama models discover chatgpt` instead) and caches the slugs and display names available to the account, with the flavor and a timestamp, in `<dataDir>/models/discovered/chatgpt.json` — an empty list is written as well when no model comes back, so no cache from the other sign-in method is left behind; `ama models discover chatgpt` rewrites the cache and `ama auth logout chatgpt` deletes it. When the registry is assembled the cache is merged into providers whose model table is empty, with metadata filled from the models.dev snapshot (the context window, input modalities and reasoning efforts reported by the codex backend are cached too and used when models.dev has nothing), so the `/model` picker and `ama models list` show the models; a cache whose flavor differs from the current sign-in counts as stale and is not merged (the picker suggests discovering again). Slugs missing from the cache still work with `--model chatgpt/<slug>`.
+**Model list**: `chatgpt` has no built-in model table (`chatgpt/<slug>` accepts any slug). After a successful `ama auth login chatgpt`, ama deletes the old cache and calls the model list endpoint once (siwc `GET /v1/models`, codex `GET /models?client_version=…`; read-only, no usage consumed; failures are silent and the output suggests `ama models discover chatgpt` instead) and caches the slugs and display names available to the account, with the flavor and a timestamp, in `<dataDir>/models/discovered/chatgpt.json` — an empty list is written as well when no model comes back, so no cache from the other sign-in method is left behind; `ama models discover chatgpt` rewrites the cache and `ama auth logout chatgpt` deletes it. When the registry is assembled the cache is merged into providers whose model table is empty, and the context window, input modalities and reasoning efforts reported by the backend (codex reports them; siwc entries are read the same way when present) are cached and take precedence over the models.dev snapshot — the subscription backend's effective window (such as 272k) can be far smaller than the API window models.dev lists, and the compaction threshold follows the backend window; fields the backend leaves out (such as the output limit) come from models.dev, and when neither has a context window a conservative 128k is used. A cache written by an older version without windows keeps using models.dev until `ama models discover chatgpt` refreshes it. This way the `/model` picker and `ama models list` show the models; a cache whose flavor differs from the current sign-in counts as stale and is not merged (the picker suggests discovering again). Slugs missing from the cache still work with `--model chatgpt/<slug>`.
 
 **codex `client_version`**: the codex backend filters models by `client_version` (each model has a minimum client version; omitting the parameter is a 400), and ama sends a Codex CLI version (default `0.160.0`), not its own version. If codex returns no models at login or discover time, that version is most likely too old: set a newer Codex CLI version with `ama config set auth.chatgpt.codexClientVersion <version>` (user level) or the environment variable `AMA_CHATGPT_CODEX_CLIENT_VERSION` (takes precedence), then run `ama models discover chatgpt`. Inference requests carry no version.
 

package/docs/en/rpc.md

@@ -41,16 +41,18 @@ A command has the shape `{ "id"?: string, "type": <command name>, ...parameters
 
 ### Prompts
 
-| Command       | Parameters                                                                              | `data`                                                          |
-| ------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `prompt`      | `message: string`, `images?: ImageBlock[]`, `streamingBehavior?: "steer" \| "followUp"` | `{ disposition: "started" \| "queued" \| "handled" }`           |
-| `steer`       | `message`, `images?`                                                                    | Same as above                                                   |
-| `follow_up`   | `message`, `images?`                                                                    | Same as above                                                   |
-| `abort`       | —                                                                                       | `{}` (answered once idle again; the queue is not cleared)       |
-| `clear_queue` | —                                                                                       | `{ steering: string[], followUp: string[] }` (the cleared text) |
+| Command       | Parameters                                                                                                     | `data`                                                          |
+| ------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `prompt`      | `message: string`, `images?: ImageBlock[]`, `streamingBehavior?: "steer" \| "followUp"`, `interrupt?: boolean` | `{ disposition: "started" \| "queued" \| "handled" }`           |
+| `steer`       | `message`, `images?`, `interrupt?: boolean`                                                                    | Same as above                                                   |
+| `follow_up`   | `message`, `images?`                                                                                           | Same as above                                                   |
+| `abort`       | —                                                                                                              | `{}` (answered once idle again; the queue is not cleared)       |
+| `clear_queue` | —                                                                                                              | `{ steering: string[], followUp: string[] }` (the cleared text) |
 
 Prompt commands **do not wait for the run to finish**: they are answered as soon as the session starts running (`before_agent_start` / `agent_start`), or the message is queued or handled (for example a slash command, or a hook block); progress arrives as events. Sending `prompt` while running without `streamingBehavior` fails with `code: "busy"`; with `steer` / `followUp` it is queued. Run failures after the response are reported as `{"type":"notification","level":"error","message":…}`.
 
+**Interrupt and send now**: with `interrupt: true` on `prompt` / `steer` (it takes precedence over `streamingBehavior`), a running session first takes the queued steers, stops the current turn (the model stream is cut, running tools finish as interrupted so every tool call has exactly one `aborted by user` result, and the interrupted assistant message is persisted with `stopReason: "aborted"`), then immediately starts a new turn with "queued steers… + this message" (joined by blank lines) and answers `{ disposition: "started" }`; the new user message has `origin: "interrupt"`. followUp messages stay queued and are delivered after the new turn; background sub-agents are not affected. When idle it is the same as leaving it out. A non-boolean `interrupt` → `invalid_arguments`; running with both the message and the queued steers empty → `invalid_arguments` (nothing is interrupted). Event order: `queue_update` (steers taken) → the old turn's `message_end` (aborted) → `agent_settled` → `agent_start` → the response → the new user `message_end` … (golden record `test/fixtures/rpc/interrupt.out.jsonl`). The new request starts with every message of the interrupted request, so the cache keeps hitting. In the SDK: `session.prompt(text, { interrupt: true })` / `session.steer(text, { interrupt: true })`.
+
 ### State
 
 | Command                   | Parameters | `data`                                                      |
@@ -171,7 +173,18 @@ After a session switch the server re-subscribes to events and sends `session_sta
 - Errors: `invalid_arguments` (out-of-range parameters, `before` not a turn id on this branch, `before` together with
   `since`) and `task_not_found`.
 
-43 commands in total; their names are the keys of `RpcCommandMap`.
+### Background sub-agents (wave 7)
+
+| Command           | Parameters | `data`                                                                                                                                                                                                                   |
+| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `background_task` | `taskId?`  | `{ backgrounded: string[] }`: the task ids actually moved. Without `taskId`, every running foreground task; an empty list for finished, already-background or unknown tasks; a non-string `taskId` → `invalid_arguments` |
+
+A moved foreground task is not interrupted: its `task` call returns at once with `tool_execution_end` (the result text starts with
+`[task tN] Moved to the background`, `details.status: "running"`), followed by `subagent_background`; when the task ends you get
+`subagent_end` as usual and, once the parent session is idle, the notification message with `origin: "task"`. Same semantics as
+`Ctrl+B` in the interactive UI.
+
+44 commands in total; their names are the keys of `RpcCommandMap`.
 
 ## Events
 
@@ -216,13 +229,14 @@ There is also the non-session event `{"type":"notification","level":"info"|"warn
 
 Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../agents.md), Chinese):
 
-| Event             | Fields                                                                                                                                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `subagent_start`  | `taskId`, `parentToolCallId`, `agent`, `runner` (`ama` / `claude` / `codex` / `acp:<program>`), `description`, `background`, `model?`, `sessionFile?`, `cwd`; sent again when the same `taskId` is continued |
-| `subagent_update` | `taskId`, `kind: tool \| text \| turn`, `toolName?`, `textDelta?` (merged over ≥ 250 ms), `turn`, `usage?`                                                                                                   |
-| `subagent_end`    | `taskId`, `status: completed \| failed \| aborted \| max_turns \| interrupted`, `usage?`, `cache?`, `outputFile?`, `worktree?: { branch, changed }`                                                          |
+| Event                 | Fields                                                                                                                                                                                                                      |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagent_start`      | `taskId`, `parentToolCallId`, `agent`, `runner` (`ama` / `claude` / `codex` / `acp:<program>`), `description`, `background`, `model?`, `sessionFile?`, `cwd`; sent again when the same `taskId` is continued                |
+| `subagent_update`     | `taskId`, `kind: tool \| text \| turn`, `toolName?`, `textDelta?` (merged over ≥ 250 ms), `turn`, `usage?`                                                                                                                  |
+| `subagent_background` | `taskId`, `parentToolCallId`, `reason: user \| timeout \| host` (a foreground task moved to the background: by hand in the interactive UI, when `subagents.autoBackgroundAfterMs` elapses, or by an RPC / SDK call; wave 7) |
+| `subagent_end`        | `taskId`, `status: completed \| failed \| aborted \| max_turns \| interrupted`, `usage?`, `cache?`, `outputFile?`, `worktree?: { branch, changed }`                                                                         |
 
-Approvals of sub-sessions and external agents are sent to this connection as `permission_request` as usual, with an optional `context` marking the origin (since wave 6, approvals of this session's own tool calls also carry `context.toolCallId`, the id of the tool call that triggered the approval, which traces use to compute approval wait time; external agent requests do not carry it): `depth` (1 = from a task sub-agent), `taskId` (the originating task), `origin` (permission requests from external agents: `agent`, `sessionId` (the external CLI's own session id), `toolCall: { title, kind, locations?, inputSummary? }`, `options`). Dialogs use it to show `[task:<agent>]` or `[claude · session abc1]`. For external agent requests `toolName` is `agent:<id>` and the answer applies to this one request only ("allow for this session" is remembered by the external agent itself); the first run of an external agent in a session additionally gets one confirmation with `toolName: "task"`, `input: { agent, mode, note }` (`context.taskId`). `test/fixtures/rpc/external.out.jsonl` is the golden record of the three approvals of `task(agent="acp:ama")` (the task tool, the first run, the child ama's bash), updated by `src/agents/external-rpc.test.ts` with `UPDATE_GOLDEN=1`. After a background task completes, the parent session receives a user message with `origin: "task"` (`<task-notification …>…</task-notification>`) and starts a new turn as usual. Task and type lists are returned by `get_tasks` / `get_agents` (shapes `TaskInfo` / `AgentInfo`; empty without the task tool), with data from the current session's `taskRegistryView(sessionId)` / `sessionAgents(sessionId)` (`src/agent/subagent-registry.ts`). `get_agents` also includes external agents (`installed` / `version` come from PATH and a `--version` probe, cached asynchronously when the session is created and refreshed when external tasks end or host injections change; before the cache is ready there is only the type catalog, see `cachedAgentInfos` in `src/agents/external.ts`). `test/fixtures/rpc/subagent.out.jsonl` is the golden record of a foreground `task(agent="explore")` plus `get_tasks` / `get_agents` (keeping only responses, `tool_execution_*`, `subagent_*` and `agent_settled`), updated by `src/agent/subagent-rpc.test.ts` with `UPDATE_GOLDEN=1`.
+Approvals of sub-sessions and external agents are sent to this connection as `permission_request` as usual, with an optional `context` marking the origin (since wave 6, approvals of this session's own tool calls also carry `context.toolCallId`, the id of the tool call that triggered the approval, which traces use to compute approval wait time; external agent requests do not carry it): `depth` (1 = from a task sub-agent), `taskId` (the originating task), `origin` (permission requests from external agents: `agent`, `sessionId` (the external CLI's own session id), `toolCall: { title, kind, locations?, inputSummary? }`, `options`). Dialogs use it to show `[task:<agent>]` or `[claude · session abc1]`. For external agent requests `toolName` is `agent:<id>` and the answer applies to this one request only ("allow for this session" is remembered by the external agent itself); the first run of an external agent in a session additionally gets one confirmation with `toolName: "task"`, `input: { agent, mode, note }` (`context.taskId`). `test/fixtures/rpc/external.out.jsonl` is the golden record of the three approvals of `task(agent="acp:ama")` (the task tool, the first run, the child ama's bash), updated by `src/agents/external-rpc.test.ts` with `UPDATE_GOLDEN=1`. After a background task completes, the parent session receives a user message with `origin: "task"` (`<task-notification …>…</task-notification>`) and starts a new turn as usual. Task and type lists are returned by `get_tasks` / `get_agents` (shapes `TaskInfo` / `AgentInfo`; empty without the task tool), with data from the current session's `taskRegistryView(sessionId)` / `sessionAgents(sessionId)` (`src/agent/subagent-registry.ts`). `get_agents` also includes external agents (`installed` / `version` come from PATH and a `--version` probe, cached asynchronously when the session is created and refreshed when external tasks end or host injections change; before the cache is ready there is only the type catalog, see `cachedAgentInfos` in `src/agents/external.ts`). `test/fixtures/rpc/subagent.out.jsonl` is the golden record of a foreground `task(agent="explore")` plus `get_tasks` / `get_agents` (keeping only responses, `tool_execution_*`, `subagent_*` and `agent_settled`), updated by `src/agent/subagent-rpc.test.ts` with `UPDATE_GOLDEN=1`. `test/fixtures/rpc/background.out.jsonl` is the golden record of `background_task` moving a running foreground `task` to the background, the task ending and its notification turn, updated by `src/modes/rpc/rpc-background.test.ts`.
 
 ### Throughput telemetry (wave 5)
 

package/docs/en/sessions.md

@@ -51,7 +51,9 @@ Top 5 tool calls
 | Errors / retries | Assistant messages with `stopReason: "error"`; `context_edit{reason:"retry"}` (failed attempts removed by automatic retry)                                                                                                                                                                                                                                                            |
 | Channel          | The `channel` of the latest `model_change` with the same provider / model as the request                                                                                                                                                                                                                                                                                              |
 
-`task` sub-sessions are separate files and count under their own cwd.
+`task` sub-sessions are separate files and count under their own cwd. The notification message a parent session receives when a
+background task finishes (`origin: "task"`) also starts a turn and counts under the parent; when `-p` waits for background tasks,
+those notification turns are written to the same session file.
 
 ### Performance and index