@armadra/agent 0.6.2 → 0.6.3

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

@@ -171,7 +171,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 +227,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
 

package/docs/en/tui.md

@@ -15,16 +15,12 @@ Running `ama` directly in a terminal (stdin / stdout both TTYs, `TERM` not `dumb
 The visual spec (colors, glyphs, screen-by-screen mockups) is in [tui-design.md](../tui-design.md) (Chinese). Hierarchy is expressed by indentation: column 0 holds the user `›`, the tool `⏺` and notice symbols, column 2 the result connector `⎿`, column 4 the tool output; the structure stays readable without colors (`NO_COLOR`, `capture-pane` without `-e`).
 
 ```
-╭──────────────────────────────────────────────────────────────╮
-│ ✻ ama 0.3.0                                                  │   ← startup header (normal)
-│                                                              │
-│ Model   anthropic/claude-sonnet-4-5 · thinking medium        │
-│ Dir     ~/Projects/demo · trusted (trust.json)               │
-│ Mode    Accept edits · preset default                        │
-│ Loaded  AGENTS.md · 2 Skills                                 │
-│                                                              │
-│ /help commands · Shift+Tab mode · Ctrl+O expand tool output  │
-╰──────────────────────────────────────────────────────────────╯
+ ▄███▄  ██▄   ▄██  ▄███▄    ama 0.6.2                     ← startup header (normal)
+██▀ ▀██ ███▄ ▄███ ██▀ ▀██   anthropic/claude-sonnet-4-5@messages · thinking medium
+███████ ██ ▀█▀ ██ ███████   ~/Projects/demo · trusted (trust.json)
+██   ██ ██     ██ ██   ██   Accept edits · preset default
+▀▀   ▀▀ ▀▀     ▀▀ ▀▀   ▀▀   AGENTS.md · 2 Skill
+                            /help commands · Shift+Tab mode · Ctrl+O expand tool output
 
 › read the README                                  ← user message (continuation lines indented 2)
 
@@ -44,23 +40,26 @@ The visual spec (colors, glyphs, screen-by-screen mockups) is in [tui-design.md]
 › Type a message, / commands, @ files, Shift+Enter newline   ← input box (placeholder)
 ────────────────────────────────────────────────
 tps: 100 tok/s • 546 tok / 5.5s (avg 100 · ttft 1.4s)    ↑12k ↓1.2k · cache 80% ♨ · [-]   ← rate line (full)
-Accept edits     claude-opus-5-5 medium | Ctx 3.0% | proj ⎇ main 5ae9e54 (+12,-3) | $0.26 | 2h24m
+Accept edits     claude-opus-5-5 medium | Ctx 3.0% | proj ⎇ main 5ae9e54 ↑2 (+12,-3) | $0.26 | 2h24m
+Session: 10.0% | Reset: 2h 18m | Weekly: 31.0% | Weekly Reset: 6d 5h     ← subscription quota line (full, ChatGPT subscription model)
 ```
 
 - **User messages**: start with `›`, continuation lines indented 2 columns; steers while running are marked `↳ steer`, messages queued after this turn `↳ after`, and messages injected by the host (the Armadra canvas) `↳ host` (the `origin` in the session file stays steer / followUp / host).
 - **Thinking blocks**: `ui.showThinking` = `collapsed` (default: "thinking…" → "thinking · 1.2k tokens", `Ctrl+O` expands it to an indented body of at most 60 lines) / `full` (always expanded) / `hidden`.
 - **Tool calls**: titled `⏺ tool name summary`; `⏺` is the accent color while running, green on success, red on failure. The second line after `⎿` is the result summary: lines read, `N changes · +a −b`, `exit 0 · 2.1s · 48 lines`, matches and files, `N inner calls · M lines of script output`, `sub-agent · running 1m05s` / `done · 1m42s · ↑28k ↓4.1k`; while running the summary line carries a spinner in the same frame as the bottom and the seconds. Bodies show the first 3 lines folded; `edit` shows a diff (first 12 lines, with line numbers at ≥ 60 columns); running `bash` scrolls its last 8 lines. `Ctrl+O` expands / folds everything (thinking blocks included). Inner calls of a codemode script hang under the outer call (folded, only the titles and summaries of the latest 5 are listed).
 - **Notices**: `✗` errors, `↻ retry n/m`, `!` warnings (cache misses, remaining context), `⛔` hook blocks, host notifications, explanations of denied or timed-out approvals; compaction / branch summaries are left-bar cards (`▎ context compacted  128k → 24k tokens`).
-- **Running**: `⠋ verb · elapsed · …`, with the verb taken from the deepest current state: waiting for confirmation (approval open), `running bash` / `running 3 tools`, `retry 2/3 · in 2s`, compacting context, replying `· ↓≈1.2k` (estimated tokens of this output), thinking.
-- **Status bar**: always the last line, with the mode always on the far left. In `compact` the separator is always `·` (embedding hosts parse it), in `full` it is `|`. The layout follows `ui.statusLine`: `full` (two lines) by default in a standalone terminal, `compact` (one line, same layout as before) by default in an embedding host with a profile; `Ctrl+G` or `/statusline [full|compact]` switches at runtime for this session only. With `full` the input box is the 4th line from the bottom (`compact` keeps it 3rd from the bottom).
+- **Running**: `⠋ verb · elapsed · …`, with the verb taken from the deepest current state: waiting for confirmation (approval open), `running bash` / `running 3 tools`, `retry 2/3 · in 2s`, compacting context, replying `· ↓≈1.2k` (estimated tokens of this output), thinking. While a foreground sub-agent task blocks the turn, `Ctrl+B to background` is appended; while the agent bar has tasks, `↓ Agent bar` is appended (`↓ handle approval` instead when an approval is docked): `⠏ running task · 4s · Esc to interrupt · Ctrl+B to background · ↓ Agent bar`; items are dropped whole from the end when the line does not fit.
+- **Status bar**: the mode is always on the far left; the status bar is the last line except for the subscription quota line in the `full` layout (`compact` always keeps it last). In `compact` the separator is always `·` (embedding hosts parse it), in `full` it is `|`. The layout follows `ui.statusLine`: `full` (two lines) by default in a standalone terminal, `compact` (one line, same layout as before) by default in an embedding host with a profile; `Ctrl+G` or `/statusline [full|compact]` switches at runtime for this session only. With `full` the input box is the 4th line from the bottom (`compact` keeps it 3rd from the bottom).
   - **`full` top line (rate line)**: `tps: <rate> tok/s • <output tokens> tok / <elapsed> (avg <session average> · ttft <time to first token>)`. While streaming the rate is the instantaneous value over the last 2 s (`tps:` in the accent color); afterwards it is the request's average; whole replies generated in under 0.25 s get no rate and show `—`; elapsed time starts at the first token; in ASCII `•` becomes `*`. The right side holds usage items: `↑` input (including cache reads and writes) `↓` output · cache · re-billing · queue count · codemode · tool preset (when not default) · host status, with `[-]` at the end hinting that it folds. Only chat requests count (compaction summaries, warming and the classifier do not). When narrow, these drop in order: output / elapsed, codemode, queue count, tokens, cache, re-billing, preset, host status, avg, ttft; `tps` and `[-]` never drop.
-  - **`full` bottom line**: on the left `permission mode | shift+tab to switch`, on the right `model thinking-level | Ctx 3.0% | <dir name> ⎇ <branch> <short commit> (+a,-d) | $cost | session duration` (Ctx with one decimal, no meter even when wide); when narrow, these drop in order: the switch hint, thinking level, line changes, directory name, branch and commit, duration, cost, context, model.
-  - **`compact`**: one line; on the right model · thinking level · `↑ ↓` · cache · cost · re-billing · context usage · dir ⎇ branch commit +a −b · session duration · queue count · codemode · preset · host status; when narrow, these drop in order: the switch hint, host status, preset, re-billing, cost, cache, tokens, thinking level, queue count, codemode, line changes, directory name, branch and commit, duration, context, model.
-  - **git**: branch and short commit are read directly from `.git/HEAD` (worktrees understood; detached shows only the short commit; outside git the whole part is omitted, leaving only the directory name). `+a −b` is the working tree (staged included) line diff against HEAD, computed in the background with `git diff --numstat HEAD` after a turn ends, a writing tool finishes, a rewind or `/tree`, at most once every 10 seconds; if it takes longer than 2 seconds or fails, line changes are hidden for the rest of the session; `AMA_STATUS_GIT=0` turns it off.
+  - **`full` bottom line**: on the left `permission mode | shift+tab to switch`, on the right `model thinking-level | Ctx 3.0% | <dir name> ⎇ <branch> <short commit> ↑N ↓N (+a,-d) | $cost | session duration` (Ctx with one decimal, no meter even when wide); when narrow, these drop in order: the switch hint, thinking level, line changes, directory name, branch and commit, duration, cost, context, model.
+  - **Subscription quota line** (third `full` line, below the status bar): when the current model uses a ChatGPT subscription (the `chatgpt` provider) it shows `Session: <used %> | Reset: <time to reset> | Weekly: <used %> | Weekly Reset: <time to reset>` (Chinese labels in the Chinese interface), from the latest `quota_update` (the codex flavor's `x-codex-primary/secondary-*` response headers and `codex.rate_limits` events; siwc only has it after a 429). Reset times are relative (`2h 18m`, `6d 5h`) and refresh once a minute. Before the first request the codex flavor shows "Quota: shown after the first request" (the first request brings the quota back, so holding the line avoids the row count jumping); siwc without data takes no line (it only gets a quota when over the limit, so a placeholder would stay forever); non-subscription models show nothing. Below 80 columns it compresses to `5h 10% ↻2h18m · wk 31% ↻6d5h`, dropping the reset times first when narrower. A window that is not 5 hours / 7 days is labelled with its actual length. `Ctrl+G` / `/statusline compact` folds the quota line together with the rate line (`compact` stays a single line; hosts anchor on "last line = status bar").
+  - **Colors** (`full`): labels, units, separators and parentheses dim gray; the rate number purple, output / elapsed / avg blue, ttft purple; model and thinking level blue; Ctx and quota percentages by threshold green / yellow / red (≥ 70% yellow, ≥ 90% red); directory and branch green, short commit dim, `↑N` ahead orange, `↓N` behind red, `(+a,-d)` green / red; cost yellow; duration and reset times purple. All come from theme semantic colors with dark / light and 16-color mappings; `NO_COLOR` and ASCII drop the colors and keep the structure. `compact` colors are unchanged.
+  - **`compact`**: one line; on the right model · thinking level · `↑ ↓` · cache · cost · re-billing · context usage · dir ⎇ branch commit +a −b · session duration · queue count · codemode · preset · host status · a short subscription quota item (`5h 10% wk 31%`, only with quota data; no `·` inside the item); when narrow, these drop in order: the quota item, the switch hint, host status, preset, re-billing, cost, cache, tokens, thinking level, queue count, codemode, line changes, directory name, branch and commit, duration, context, model.
+  - **git**: branch and short commit are read directly from `.git/HEAD` (worktrees understood; detached shows only the short commit; outside git the whole part is omitted, leaving only the directory name). `+a −b` is the working tree (staged included) line diff against HEAD, computed in the background with `git diff --numstat HEAD` after a turn ends, a writing tool finishes, a rewind or `/tree`, at most once every 10 seconds; if it takes longer than 2 seconds or fails, line changes are hidden for the rest of the session; `AMA_STATUS_GIT=0` turns it off. In `full`, `↑N` / `↓N` count the commits the current branch is ahead of / behind its upstream: when the branch has an upstream in the git config (`branch.<name>.merge`), the same throttled cycle then runs `git rev-list --left-right --count @{upstream}...HEAD` (same 2-second timeout; after a timeout it stops for the session); zero, no upstream or detached shows nothing; ASCII uses `^N` / `vN`.
   - **Cost** includes sub-tasks, warming, the classifier and external agent usage priced in USD (other units only in `/session`); **duration** counts from when this process opened the current session (`Ns` / `Nm` / `NhMm`).
   - When bash commands run in the OS sandbox (`sandbox.bash: "auto"` and available on this machine, see [sandbox.md](../sandbox.md), Chinese), the usage items gain a sandbox marker, dropped first together with codemode when space runs out.
   - During a model fallback (`fallbackModel`: when the main model is overloaded or retries are exhausted, one retry with the fallback model) the model item shows `main model → fallback model` (the fallback in yellow); it disappears once the fallback model replies and the main model is restored, and the message area gets an explanatory line.
-  - Model names abbreviate with width (provider dropped below 100 columns, channel below 60, version suffix below 48); `compact` at ≥ 110 columns shows context as a meter `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`; changing numbers reserve their widest shape, so items never flicker in and out as values change. In ASCII mode `⎇` → `git`, `−` → `-`, `♨` → `~`.
+  - Model names abbreviate with width (provider dropped below 100 columns, channel below 60, version suffix below 48); `compact` at ≥ 110 columns shows context as a meter `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`; changing numbers reserve their widest shape, so items never flicker in and out as values change. In ASCII mode `⎇` → `git`, `−` → `-`, `♨` → `~`, `↻` → `@`.
 - **Exit**: a session summary line and the resume command are appended at the end of the message area and stay in the terminal scrollback:
 
 ```
@@ -117,26 +116,27 @@ Trade-offs: the status bar shows the latest hit rate (the session total lives in
 
 ## Keys
 
-| Key                      | Effect                                                                                                                                                                                                                        |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Enter                    | Send; while running = steer (inserted into the current turn)                                                                                                                                                                  |
-| Alt+Enter                | While running, queue after this turn (followUp); when idle, same as Enter                                                                                                                                                     |
-| Shift+Enter / Ctrl+J     | New line                                                                                                                                                                                                                      |
-| Esc                      | Interrupt: queued messages go back into the input box, then the current run stops; closes completion first when it is open                                                                                                    |
-| Esc Esc (idle)           | Empty input: open the rewind list (same as `/rewind`); with text: clear it and save it into input history                                                                                                                     |
-| Alt+↑                    | Recall the last queued message                                                                                                                                                                                                |
-| Shift+Tab / Tab          | Cycle permission modes Manual → Accept edits → Plan → Auto → Bypass permissions (Tab only on an empty input with completion closed, otherwise still completion; entering Bypass asks to confirm, see "Entering Bypass" below) |
-| Ctrl+O                   | Expand / fold tool output and thinking blocks                                                                                                                                                                                 |
-| Ctrl+L / Ctrl+T          | Pick model / thinking level                                                                                                                                                                                                   |
-| Ctrl+G                   | Bottom info line two lines (full) ↔ one line (compact), this session only                                                                                                                                                     |
-| Ctrl+V                   | Paste an image from the clipboard: saved in the data directory, `@<path>` inserted at the cursor (same as `/paste`)                                                                                                           |
-| Ctrl+C                   | Clear the input; on an empty input, press again within 1.5 seconds to quit (exit code 130)                                                                                                                                    |
-| Ctrl+D                   | Quit on an empty input                                                                                                                                                                                                        |
-| Tab                      | Complete                                                                                                                                                                                                                      |
-| ↑ / ↓                    | Browse history on a single line (`<data dir>/history`, 500 entries)                                                                                                                                                           |
-| Ctrl+B / ↓ (empty input) | Enter the agent bar (when there are sub-agent tasks; with text Ctrl+B still moves the cursor left, use ↓ in tmux), see "Sub-agents" (from wave 6 W6-A)                                                                        |
-
-Keys can be overridden in `~/.config/ama/keybindings.json`: keys are action ids (`app.interrupt`, `app.rewind`, `app.message.followUp`, `app.statusLine.toggle`, `app.paste.image`, `app.agents.focus`, `tui.editor.newLine` …), values are a key or an array of keys, and an empty array disables the action. `app.rewind` is the key double-pressed while idle (Esc by default, at most 800 ms apart).
+| Key                  | Effect                                                                                                                                                                                                                        |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Enter                | Send; while running = steer (inserted into the current turn)                                                                                                                                                                  |
+| Alt+Enter            | While running, queue after this turn (followUp); when idle, same as Enter                                                                                                                                                     |
+| Shift+Enter / Ctrl+J | New line                                                                                                                                                                                                                      |
+| Esc                  | Interrupt: queued messages go back into the input box, then the current run stops (with foreground sub-agent tasks; background tasks keep running, as the hint says); closes completion first when it is open                 |
+| Esc Esc (idle)       | Empty input: open the rewind list (same as `/rewind`); with text: clear it and save it into input history                                                                                                                     |
+| Alt+↑                | Recall the last queued message                                                                                                                                                                                                |
+| Shift+Tab / Tab      | Cycle permission modes Manual → Accept edits → Plan → Auto → Bypass permissions (Tab only on an empty input with completion closed, otherwise still completion; entering Bypass asks to confirm, see "Entering Bypass" below) |
+| Ctrl+O               | Expand / fold tool output and thinking blocks                                                                                                                                                                                 |
+| Ctrl+L / Ctrl+T      | Pick model / thinking level                                                                                                                                                                                                   |
+| Ctrl+G               | Bottom info line two lines (full) ↔ one line (compact), this session only                                                                                                                                                     |
+| Ctrl+V               | Paste an image from the clipboard: saved in the data directory, `@<path>` inserted at the cursor (same as `/paste`)                                                                                                           |
+| Ctrl+C               | Clear the input; on an empty input, press again within 1.5 seconds to quit (exit code 130)                                                                                                                                    |
+| Ctrl+D               | Quit on an empty input                                                                                                                                                                                                        |
+| Tab                  | Complete                                                                                                                                                                                                                      |
+| ↑ / ↓                | Browse history on a single line (`<data dir>/history`, 500 entries)                                                                                                                                                           |
+| ↓ (empty input)      | Enter the agent bar (whenever there are sub-agent tasks); with text it still moves down / through history and hints once, see "Sub-agents"                                                                                    |
+| Ctrl+B               | When foreground sub-agent tasks (or a `task_ctl wait`) block the turn, move them all to the background, whatever is in the input box; otherwise cursor left. In tmux press `C-b C-b`, see "Sub-agents"                        |
+
+Keys can be overridden in `~/.config/ama/keybindings.json`: keys are action ids (`app.interrupt`, `app.rewind`, `app.message.followUp`, `app.statusLine.toggle`, `app.paste.image`, `app.agents.focus`, `app.tasks.background`, `tui.editor.newLine` …), values are a key or an array of keys, and an empty array disables the action. `app.rewind` is the key double-pressed while idle (Esc by default, at most 800 ms apart).
 
 ## Rewind
 
@@ -315,12 +315,17 @@ Sub-agents started by the `task` tool ([agents.md](../agents.md), Chinese) fold
 ⏺ task check test coverage gaps in src/tui
   ⎿ ⠋ explore · running 1m05s · 3 turns · read grep bash · ↑12k ↓3.4k
 ⏺ task background review
-  ⎿ done · 0.0s
+  ⎿ started in the background
     ↳ t2 explore · running 40s · 1 turn · read
+⏺ task scan
+  ⎿ moved to the background · 12s
+    ↳ t3 explore · running 30s · 2 turns · grep
 ```
 
-- The status line shows the type (external agents show a runner such as `claude (claude)`), status and elapsed time, turns, the latest 3 tools and usage; after a foreground task ends it is replaced by the result summary. A background task's (`background: true`) tool call returns immediately, with an extra follow-up status line below (refreshed every second while running); when it completes, the `<task-notification>` the model receives shows in the message area as a single line (e.g. "↳ sub-agent notification: t2 explore done · 7 turns · see /tasks for output"), plus a yellow notice on failure or stop.
-- `/tasks`: focus the agent bar (below); `/tasks <id>` opens that task's sub-agent view directly; `/tasks stop <id>` stops it. With `ui.agentBar: "off"` (the default in embedding hosts) `/tasks` is still the task picker (newest on top, Enter shows the output, running tasks can be stopped). Line mode: `/tasks` lists, `/tasks <id>` shows output, `/tasks stop <id>` stops.
+- The status line shows the type (external agents show a runner such as `claude (claude)`), status and elapsed time, turns, the latest 3 tools and usage; after a foreground task ends it is replaced by the result summary. A background task's tool call (background is the default in the interactive UI, see [agents.md](../agents.md) "foreground and background", Chinese) returns immediately; the summary line says "started in the background", with an extra follow-up status line below (refreshed every second while running). A foreground task moved to the background shows "moved to the background · elapsed" with the same follow-up line (the explanation meant for the model is hidden; `Ctrl+O` shows it). A task moved by the auto timeout (`subagents.autoBackgroundAfterMs`) or by the host also gets a one-line notice; when it completes, the `<task-notification>` the model receives shows in the message area as a single line (e.g. "↳ sub-agent notification: t2 explore done · 7 turns · see /tasks for output"), plus a yellow notice on failure or stop.
+- `/tasks`: focus the agent bar (below); `/tasks <id>` opens that task's sub-agent view directly; `/tasks stop <id>` stops it; `/tasks bg [id]` moves it to the background (without an id: every blocking foreground task, same as `Ctrl+B`). With `ui.agentBar: "off"` `/tasks` is still the task picker (newest on top, Enter shows the output, running tasks can be stopped). Line mode: `/tasks` lists, `/tasks <id>` shows output, `/tasks stop <id>` stops, `/tasks bg [id]` moves to the background (typed while running it is still a command, not a steer).
+- Moving to the background (`Ctrl+B`, key action `app.tasks.background`): while the main turn waits for a foreground task (`task` with `background: false`, the `-p` default, or `task_ctl wait`), press it and the tool call returns at once, the task keeps running, the main turn carries on and you can keep sending messages; when the task ends the `<task-notification>` arrives and opens a turn as usual. The hint says "Moved to the background: t2; you'll be notified when it finishes". With nothing to move, `Ctrl+B` falls through to the editor (cursor left) and is not swallowed. tmux's default prefix is `C-b`: in tmux press `C-b C-b` (default `send-prefix`) to pass it to ama, or press `b` in the agent bar; you can also rebind it in `keybindings.json`.
+- Esc interrupts only the foreground: Esc while running stops the main turn and the sub-tasks still in the foreground; tasks already in the background keep running, and the hint says "Interrupted (background task t2 keeps running; Esc doesn't affect it)".
 - `/agents`: the available types: name, runner, source (built-in / user / project / profile / host), external agents marked installed with a version or not installed, plus a one-line description.
 - Notices reported by external agents themselves (budget exhausted, timeout, mode downgrade …) show in the message area as a single line `[claude · t3] …`.
 
@@ -335,11 +340,13 @@ Above the status line (below the hint line) the bar lists sub-agent tasks, one l
 1 more
 ```
 
-- States: queued (the concurrency pool is full) / running (elapsed time, turns, latest tool) / awaiting approval (the approval dialog currently holds its request) / done / failed / stopped (plus out of turns and interrupted); `⏺` is the accent color while running, green when done, red on failure, yellow / dim otherwise; `*` in ASCII.
+- States: queued (the concurrency pool is full) / running (elapsed time, turns, latest tool) / awaiting approval (the approval dialog currently holds its request, or it is docked in the bar; the row is yellow) / done / failed / stopped (plus out of turns and interrupted); `⏺` is the accent color while running, green when done, red on failure, yellow / dim otherwise; `*` in ASCII.
 - When it shows: while any task is queued, running or awaiting approval; tasks that ended in this session and have not been looked at in the view stay until viewed, at most 10 minutes. Tasks already finished when a session is resumed are not shown (`/tasks` lists them).
-- Entering: `Ctrl+B` with an empty input box (whenever there are tasks), or `↓` (while the bar is visible) — tmux's default prefix swallows `Ctrl+B`, so use `↓` there; with text in the input box `Ctrl+B` still moves the cursor left and `↓` still moves down / through history. The key action is `app.agents.focus`, configurable in `keybindings.json`.
-- In the bar: `↑` `↓` select (lists every task of the session, the window scrolls along; `↑` on the first item returns to the input box), Enter opens the sub-agent view, Esc / `Ctrl+B` return to the input box; typing returns to the input box with the text filled in. The last line is a key hint.
-- Embedding hosts (with a profile) default to `ui.agentBar: "off"`: no bar, and `Ctrl+B` / `↓` go to the editor as usual.
+- Entering: press `↓` with an empty input box and no completion open, whenever the session has tasks (even after the bar has collapsed, same as `/tasks`); the same inside and outside tmux. It works while a turn runs too; the `↓ Agent bar` at the end of the running line is the reminder. The key action is `app.agents.focus` (only `down` by default), configurable in `keybindings.json`.
+- When the key does not get you in, a one-line hint shows for 3 seconds: text in the input box — "Input is not empty; clear it and press ↓ for the Agent bar" (once per draft, with the cursor on the last line; `↓` still moves down); the bar is off — "Agent bar is off (ui.agentBar); use /tasks"; no tasks — "No sub-agent tasks yet". While browsing input history with `↑` `↓`, `↓` only steps through history.
+- `Ctrl+B` does not enter the bar; it moves foreground tasks to the background (above). For the old "`Ctrl+B` enters the bar", set `"app.agents.focus": ["down", "ctrl+b"]` in `keybindings.json` and rebind `app.tasks.background`.
+- In the bar: `↑` `↓` select (lists every task of the session, the window scrolls along; `↑` on the first item returns to the input box), Enter opens the sub-agent view (a docked approval of the selected task pops up right away), `b` / `Ctrl+B` moves the selected foreground task to the background (a one-line hint when it is not running in the foreground), `x` stops the selected task (the first press hints "Press x again to stop t2"; it stops only on a second press within 1.5 seconds), Esc returns to the input box; other letters return to the input box with the text filled in. The last line is the key hint `↑↓ select · Enter open · b background · x stop · Esc back`; narrow screens drop the `b` / `x` items.
+- Embedding hosts (with a profile) no longer turn the bar off by default; a host that shows sub-tasks itself and does not want the bar sets `ui.agentBar: "off"` in its profile (see [host-api.md](host-api.md) "Embedding in Armadra"). With the bar off it is not shown, and `↓` with tasks points to `/tasks`.
 
 ### Sub-agent view
 
@@ -360,8 +367,17 @@ t2 explore · running 1m05s · 3 turns · ↑12k ↓3.4k · Esc back · /tasks s
 - The body follows live: for ama sub-agents it shows every message and tool call of the sub-session (rendered like the message area); when the sub-session handle has been released (at most 16 are kept) or the session was resumed, the sub-session file is loaded read-only and live events are attached when the task runs again. External agents (claude / codex / ACP) show the live output held in this process's memory (text, thinking, tool start / end, turns, notices; at most 2000 items / 1 MB, never written to disk); after ama restarts only one line remains, saying to use the original CLI's resume <session id> for the full text.
 - With an empty input box: `↑` / PgUp scroll up (pausing follow, with "follow paused · End to resume" at the bottom), `↓` / PgDn scroll down, End (or `f` while paused) resumes following; `←` `→` switch to the previous / next task; Esc returns to the main screen. With text in the input box, Esc clears it first.
 - Enter sends the input to this sub-agent (recorded in the sub-session as a user message with `origin: "direct"`, see [session-format.md](../session-format.md), Chinese): ama sub-agent running → delivered when its current turn ends; external agent running or task still queued → continued after this run ends; finished → continued in the background (like `task_ctl send`; the main session receives the `<task-notification>` as usual when it completes). A line at the bottom reports the result. The parent session's model does not know you talked to the sub-agent directly; the result comes back through the completion notification.
-- Nothing is interrupted from the view: Esc only goes back. To stop the task use `/tasks stop <id>`, which also works in the view's input box (the only command the view accepts).
-- When the viewed task waits for approval the title says "awaiting approval", and the approval dialog pops up over the view as usual (with the `[task:<type>]` origin).
+- Nothing is interrupted from the view: Esc only goes back. To stop the task use `/tasks stop <id>`; to move it to the background use `Ctrl+B` or `/tasks bg [id]`. Both work in the view's input box (the only commands the view accepts).
+- When the viewed task waits for approval the title says "awaiting approval", and the approval dialog pops up over the view as usual (with the `[task:<type>]` origin); if its approval is docked in the bar, opening the view pops it up.
+
+### Docked approvals of background tasks
+
+When a background task (including one moved to the background) needs approval, it does not interrupt what you are doing:
+
+- While the main session is running, the input box has a draft, or another overlay is open, no dialog pops up; the request is **docked**: the task's row in the agent bar says "needs approval" (yellow) and the running line shows `↓ handle approval`; the sub-task waits meanwhile.
+- It pops up on its own once the main session is idle, the input box is empty and no overlay is open; entering the bar, selecting it and pressing Enter (opening the view) pops it up immediately.
+- If the main session or a foreground task asks for approval while one is docked: approvals are serialized, so the docked one pops up first and theirs follow; the main session's approvals are never held back.
+- Approvals of foreground tasks and of the main session pop up immediately as before; timeouts (deny after 10 minutes by default), aborts and unattended rules are unchanged. RPC clients receive `permission_request` as usual and decide how to present it.
 
 Origin labels on approval boxes:
 
@@ -413,12 +429,13 @@ Requires memory to be enabled (`ama memory enable` or `--memory`, see [memory.md
 
 ## Startup screen
 
-`ui.quietStartup` / `--quiet-startup`: `normal` shows a boxed startup header: title, model and thinking level, directory (`~` abbreviated) and trust state, permission mode / preset / codemode, loaded context files / Skills / prompt templates / hooks, warning count and common keys; below 56 columns or with `ui.compact` the box is dropped and each item takes one line. `header` is a single line `✻ ama version · model · mode · /help` (the profile default); `silent` shows nothing. When `--resume` has no id, the model has no key, the session directory does not exist or project resources need trust, a small selection / input prompt appears before the interface starts, collapsing into one line on screen once answered.
+`ui.quietStartup` / `--quiet-startup`: `normal` shows an "AMA" logo with an info column: version, model and thinking level, directory (`~` abbreviated) and trust state, permission mode / preset / codemode, loaded context files / Skills / prompt templates / hooks, warning count and common keys. At 72 columns or wider the logo sits on the left and the info on the right; at 48–71 columns the logo is on top; below 48 columns a two-line header is shown instead (version · model · thinking / mode · directory · trust). `ui.logo: "off"` or `ui.compact` shows only the info column. The logo takes the theme's accent → user → tool colors letter by letter; ASCII mode swaps in a glyph made of `_ / \ |`. On startup a one-off "light-up" sweep plays for about a second (the glyph starts dim, a highlight band sweeps left to right, then it settles); it redraws in place and leaves no frames in the scrollback, and any key settles it at once while the key still goes to the input box. The settled frame is shown directly with `ui.animation: false`, `NO_COLOR` / a colorless terminal, a non-TTY, an embedding host (profile.host), a `CI` environment, a prompt given on the command line (`ama "…"`), a terminal shorter than 16 rows or content taller than one screen; the line interface, `-p`, RPC and ACP draw no startup header. `header` is a single line `✻ ama version · model · mode · /help` (the profile default); `silent` shows nothing. When `--resume` has no id, the model has no key, the session directory does not exist or project resources need trust, a small selection / input prompt appears before the interface starts, collapsing into one line on screen once answered.
 
 ## In tmux / Armadra terminal nodes
 
 - Bracketed paste: enabled at startup; pasted multi-line content enters the input box as a whole (folded into a paste placeholder with the line count beyond 10 lines or 1 000 characters), and an Enter right after a paste sends directly, which suits writes from external programs.
 - Terminal capabilities are not queried, and mouse and the Kitty keyboard protocol are not enabled, so no replies get mixed into input; tmux ≥ 3.4 passes synchronized output through, and older versions display fine too.
+- tmux's default prefix `C-b` is taken by the tmux client: to move tasks to the background press `C-b C-b` (`send-prefix` passes it through), or `↓` into the agent bar and press `b`; entering the bar uses `↓`, which the prefix does not affect.
 - When the window size changes the last screen is redrawn in full; history in the scrollback is unaffected.
 - Automatic fallback: non-TTY, `TERM=dumb`, `--no-tui` or a failed terminal initialization use line mode, with the same commands and approval prompts.
 
@@ -430,8 +447,9 @@ The `ui` section of `config.json` (settable at project level too):
 | ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ui.theme`        | `dark`        | `dark` / `light` / `auto`; auto only looks at `COLORFGBG` (no terminal query) and uses dark when unsure; configuring it explicitly is recommended |
 | `ui.ascii`        | auto-detected | ASCII glyphs (`›` → `>`, `⏺` → `*`, `⎿` → `L`, box lines → `+ - \|`, a 4-frame spinner)                                                           |
-| `ui.compact`      | `false`       | No blank lines between message blocks, no box around the startup header                                                                           |
-| `ui.animation`    | `true`        | `false`: the spinner stays still as `·` while running and redraws only when seconds change                                                        |
+| `ui.compact`      | `false`       | No blank lines between message blocks, no logo in the startup header                                                                              |
+| `ui.logo`         | `auto`        | The "AMA" logo in the startup header; `off` shows only the info column                                                                            |
+| `ui.animation`    | `true`        | `false`: the spinner stays still as `·` while running and redraws only when seconds change; the startup logo does not animate                     |
 | `ui.markdown`     | `true`        | `false`: assistant text is not rendered as Markdown                                                                                               |
 | `ui.showThinking` | `collapsed`   | See "Layout"                                                                                                                                      |
 | `ui.quietStartup` | `normal`      | See "Startup screen"                                                                                                                              |
@@ -505,29 +523,29 @@ tui.setFocus(editor);
 tui.start();
 ```
 
-| Export                                                                    | Purpose                                                                                                                                                                                  |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Component`, `Focusable`, `CURSOR_MARKER`                                 | The component contract: `render(width)` returns lines (each with visible width ≤ width), `handleInput?(data)`, `invalidate()`; the focused component emits `CURSOR_MARKER` at the cursor |
-| `TUI`                                                                     | Root container and differential rendering (main screen, synchronized output): `addChild`, `start` / `stop`, `requestRender`, `setFocus`, `addInputListener`, `showOverlay`               |
-| `ProcessTerminal`, `MemoryTerminal`, `VirtualScreen`                      | A real terminal (raw mode, bracketed paste); an in-memory terminal and a VT screen (tests, frame goldens)                                                                                |
-| `Container`, `Text`, `TruncatedText`, `Markdown`, `Box`, `Card`, `Spacer` | Basic components; `Card` is a left-bar card, `Box` accepts `borderColor`                                                                                                                 |
-| `Loader`                                                                  | Running indicator: `setVerb(verb, extras, { elapsed })`, `frame` / `onFrame` (changes glyph in the same frame as other components), `animation: false`                                   |
-| `Editor`, `EditorBuffer`, `PasteStore`                                    | Multi-line editor (history, the `AutocompleteProvider` completion interface, paste folding)                                                                                              |
-| `SelectList`                                                              | Filterable selection list: groups, badges, number keys, `stacked`, `currentValue` (✓), `footer` key hints                                                                                |
-| `KeyValue`, `Meter`                                                       | Two-column aligned key-value table (`wrap` wraps aligned to the value column); a meter (`levelColor` threshold coloring)                                                                 |
-| `compositeOverlays`, `OverlayOptions`                                     | Overlay compositing (centered / bottom-anchored)                                                                                                                                         |
-| `createTheme`, `plainTheme`, `detectCapabilities`, `Theme`                | Themes and color capability detection (`NO_COLOR`, 16 / 256 / truecolor); 14 semantic colors, `resolveThemeName("auto")`                                                                 |
-| `Theme.glyphs`, `UNICODE_GLYPHS`, `ASCII_GLYPHS`, `detectAscii`           | Glyph tables (`›` `⏺` `⎿` `✻` `▎`, box lines, spinner frames …) with ASCII fallback; `createTheme(name, { ascii })`                                                                      |
-| `Keybindings`, `DEFAULT_KEYBINDINGS`, `loadKeybindingsFile`               | Action id → keys, overridden by `keybindings.json`                                                                                                                                       |
-| `parseKey`, `matchesKey`, `StdinBuffer`                                   | Key sequence parsing and Esc timeout splitting (`AMA_TUI_ESC_TIMEOUT`)                                                                                                                   |
-| `visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi`, `sliceByColumn` …  | Width computation and truncation aware of ANSI and wide characters                                                                                                                       |
+| Export                                                                    | Purpose                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Component`, `Focusable`, `CURSOR_MARKER`                                 | The component contract: `render(width)` returns lines (each with visible width ≤ width), `handleInput?(data)`, `invalidate()`; the focused component emits `CURSOR_MARKER` at the cursor                                          |
+| `TUI`                                                                     | Root container and differential rendering (main screen, synchronized output): `addChild`, `start` / `stop`, `requestRender`, `setFocus`, `addInputListener`, `showOverlay`                                                        |
+| `ProcessTerminal`, `MemoryTerminal`, `VirtualScreen`                      | A real terminal (raw mode, bracketed paste); an in-memory terminal and a VT screen (tests, frame goldens)                                                                                                                         |
+| `Container`, `Text`, `TruncatedText`, `Markdown`, `Box`, `Card`, `Spacer` | Basic components; `Card` is a left-bar card, `Box` accepts `borderColor`                                                                                                                                                          |
+| `Loader`                                                                  | Running indicator: `setVerb(verb, extras, { elapsed, optional })` (`optional` extras are dropped whole when the line does not fit), `frame` / `onFrame` (changes glyph in the same frame as other components), `animation: false` |
+| `Editor`, `EditorBuffer`, `PasteStore`                                    | Multi-line editor (history, the `AutocompleteProvider` completion interface, paste folding)                                                                                                                                       |
+| `SelectList`                                                              | Filterable selection list: groups, badges, number keys, `stacked`, `currentValue` (✓), `footer` key hints                                                                                                                         |
+| `KeyValue`, `Meter`                                                       | Two-column aligned key-value table (`wrap` wraps aligned to the value column); a meter (`levelColor` threshold coloring)                                                                                                          |
+| `compositeOverlays`, `OverlayOptions`                                     | Overlay compositing (centered / bottom-anchored)                                                                                                                                                                                  |
+| `createTheme`, `plainTheme`, `detectCapabilities`, `Theme`                | Themes and color capability detection (`NO_COLOR`, 16 / 256 / truecolor); 14 semantic colors, `resolveThemeName("auto")`                                                                                                          |
+| `Theme.glyphs`, `UNICODE_GLYPHS`, `ASCII_GLYPHS`, `detectAscii`           | Glyph tables (`›` `⏺` `⎿` `✻` `▎`, box lines, spinner frames …) with ASCII fallback; `createTheme(name, { ascii })`                                                                                                               |
+| `Keybindings`, `DEFAULT_KEYBINDINGS`, `loadKeybindingsFile`               | Action id → keys, overridden by `keybindings.json`                                                                                                                                                                                |
+| `parseKey`, `matchesKey`, `StdinBuffer`                                   | Key sequence parsing and Esc timeout splitting (`AMA_TUI_ESC_TIMEOUT`)                                                                                                                                                            |
+| `visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi`, `sliceByColumn` …  | Width computation and truncation aware of ANSI and wide characters                                                                                                                                                                |
 
 ## Testing
 
 Frame goldens all live in `test/fixtures/tui/`; `MemoryTerminal` reconstructs the screen (without color, verifying only layout and glyphs):
 
 - `src/modes/interactive/interactive-mode.test.ts`: a complete read-file run at 80x24 and 40x24 (startup, input, tool running, finish, `Ctrl+O` expand, exit summary) → `run-*.txt`; approvals, cache notices and more.
-- `src/modes/interactive/interactive-frames.test.ts`: startup headers (`startup-normal-*`, `header-quiet-*`), tool hierarchy (`tools-*`), notices (`notices-*`), running verbs (`loader-verbs-*`), the `/session` panel (`panel-session-*`), a whole run in ASCII mode (`ascii-run-*`).
+- `src/modes/interactive/interactive-frames.test.ts`: startup headers (`startup-normal-*`, `header-quiet-*`; logo variants and the animation in `startup-logo.test.ts` / `startup-logo-*`), tool hierarchy (`tools-*`), notices (`notices-*`), running verbs (`loader-verbs-*`), the `/session` panel (`panel-session-*`), a whole run in ASCII mode (`ascii-run-*`).
 - Wave 5 (W5-U): `plan-dialog.test.ts` (`plan-dialog-*`: four options, execution mode, feedback, external editor, ASCII, 40 columns), `approval-origin.test.ts` (`approval-origin-*`, `approval-task-agent-*`, `approval-first-run-*`, `approval-task-external-*` and the first-run merge), `subagent-view.test.ts` (`subagent-view-*`), `tasks-panel.test.ts` (`tasks-picker-*`, `tasks-output-*`, `agents-panel-*`), `harness-notices.test.ts` (`harness-notices-*`), `interactive-w5.test.ts` (plan → approval → execution, `/plan`, background tasks into `/tasks`, Ctrl+V; `interactive-plan-*`, `interactive-tasks-*`).
 - `src/tui/tui-frames.test.ts`: component level (conversation, Markdown, editor placeholder / multi-line / paste / completion); `status-widths.txt` of `status-bar.test.ts`; approvals and mode pickers in `approval-dialog.test.ts` and `pickers.test.ts`.
 

package/docs/host-api.md

@@ -159,4 +159,8 @@ interface WarmDecision {
 
 ## 嵌入 Armadra
 
-Armadra 用 profile 启动 ama：`ama --profile <path>`，profile 的 `host` 指向它的适配器（`ama-armadra.cjs`），另带 instructions、skillDirs、hooksFile、authFile、sessionDir、`trustProject`。适配器在 `ARMADRA_NODE_ID` 缺失时返回 `undefined`，同一个 profile 在画布外退化为普通 ama。契约细节见 Armadra 仓库 [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md)。
+Armadra 用 profile 启动 ama：`ama --profile <path>`，profile 的 `host` 指向它的适配器（`ama-armadra.cjs`），另带 instructions、skillDirs、hooksFile、authFile、sessionDir、`trustProject`。适配器在 `ARMADRA_NODE_ID` 缺失时返回 `undefined`，同一个 profile 在画布外退化为普通 ama。
+
+有 profile 时的界面缺省：`ui.quietStartup: "header"`、`ui.statusLine: "compact"`（最后一行是状态栏，宿主按 `·` 解析）。Agent 栏（`ui.agentBar`）不再缺省关闭，与独立终端一样是 `auto`；宿主自己展示子任务、不要栏时在 profile 的 `config` 指向的配置文件里写 `{ "ui": { "agentBar": "off" } }`。
+
+契约细节见 Armadra 仓库 [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md)。

package/docs/providers.md

@@ -189,8 +189,10 @@ ama auth logout chatgpt                # siwc 先撤销 refresh token 再删本
 模型列表接口（siwc `GET /v1/models`、codex `GET /models?client_version=…`，只读、不消耗额度；失败静默，改提示
 `ama models discover chatgpt`），把账户可用的 slug 与显示名连同 flavor、时间戳缓存到
 `<dataDir>/models/discovered/chatgpt.json`——返回 0 个也写空表，免得残留另一种登录方式的缓存；`ama models discover
-chatgpt` 也重写这份缓存，`ama auth logout chatgpt` 删掉它。组装注册表时缓存并入模型表为空的供应商，元数据用 models.dev
-快照补全（codex 后端另给的上下文窗口、输入模态、推理强度也存进缓存，models.dev 补不到时用它），`/model` 选择器、
+chatgpt` 也重写这份缓存，`ama auth logout chatgpt` 删掉它。组装注册表时缓存并入模型表为空的供应商，后端给的上下文窗口、
+输入模态、推理强度（codex 后端给；siwc 条目带了也取）存进缓存并优先于 models.dev 快照——订阅后端的生效窗口（如 272k）
+可能远小于 models.dev 记的 API 版窗口，压缩阈值按后端窗口算；后端没给的字段（输出上限等）用 models.dev 补，两边都没有
+上下文窗口时按保守缺省 128k。旧版本写的缓存不含窗口就照旧用 models.dev，重新 `ama models discover chatgpt` 即刷新。`/model` 选择器、
 `ama models list` 照常列出；缓存的 flavor 与当前登录不符时视为过期、不并入（选择器提示重新发现）。缓存里没有的 slug
 仍可 `--model chatgpt/<slug>` 使用。