@armadra/agent 0.7.6 → 0.8.1

package/docs/en/{rpc.md → reference/rpc.md}

@@ -1,11 +1,11 @@
 # RPC protocol (stdio JSONL)
 
-English · [简体中文](../rpc.md)
+English · [简体中文](../../reference/rpc.md)
 
-> Translated from the Chinese [docs/rpc.md](../rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/reference/rpc.md](../../reference/rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
 > authoritative.
 
-`ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../design.md) §13.2 (Chinese).
+`ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../../design/design.md) §13.2 (Chinese).
 
 ## Wire
 
@@ -35,7 +35,7 @@ A command has the shape `{ "id"?: string, "type": <command name>, ...parameters
 
 - A response carries the request's `id` back (only string ids). Commands are processed concurrently: `prompt` does not block later commands, so responses may arrive in a different order than requests; match them by `id`.
 - On failure `error` is human-readable text and `code` is the `AmaError.code` (when there is one). Unknown commands → `code: "invalid_arguments"`.
-  **Hosts must decide by `code` and never parse `error` / `message`**: human-readable text follows the interface language (`AMA_LANG`, `--lang`, `ui.language`; bilingual since wave 6, see [i18n.md](../i18n.md), Chinese). The same holds for the `message` of `notification` events.
+  **Hosts must decide by `code` and never parse `error` / `message`**: human-readable text follows the interface language (`AMA_LANG`, `--lang`, `ui.language`; bilingual since wave 6, see [i18n.md](../../guides/i18n.md), Chinese). The same holds for the `message` of `notification` events.
 - A line that is not valid JSON or lacks `type` → `{ "type": "response", "command": "parse", "success": false, "error": … }`, without `id`.
 - Commands that need extension methods of the session implementation (marked † below) return `code: "not_implemented"` on sessions that are not `AgentSessionImpl`; sessions created by the CLI and the SDK are all `AgentSessionImpl`.
 
@@ -100,7 +100,7 @@ Prompt commands **do not wait for the run to finish**: they are answered as soon
 
 ### Rewind
 
-Details in [rewind-plan.md](../rewind-plan.md) §3 (Chinese). Rewind points are the user messages on the active path that start new turns (steers and queued messages belong to the current turn and are not listed). Calling while running returns `busy`.
+Details in [rewind-plan.md](../../history/rewind-plan.md) §3 (Chinese). Rewind points are the user messages on the active path that start new turns (steers and queued messages belong to the current turn and are not listed). Calling while running returns `busy`.
 
 | Command             | Parameters                                                                                                | `data`                                                                                                                                                                                            |
 | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -111,7 +111,7 @@ Details in [rewind-plan.md](../rewind-plan.md) §3 (Chinese). Rewind points are
 
 `CodeRestoreResult`: `restored` / `deleted` / `conflicts` (left untouched with `skip`, overwritten with `overwrite`) / `skipped: { path, reason }[]` (`symlink` / `hardlink` / `not_regular` / `parent_moved` / `too_large` / `backup_missing`) / `failed: { path, message }[]` / `insertions` / `deletions`; paths inside cwd are relative (`/`-separated). Error codes: restoring code without a checkpoint → `no_checkpoint`; everything failed and nothing was restored → `rewind_failed` (the conversation is left alone); the entry is not a rewind point on the active path → `invalid_arguments`. For conversation-only or code-only rewinds, a `custom_message{customType: "ama.rewind-note"}` is appended to the end of the context before the next prompt, telling the model which files disagree with the conversation.
 
-After a session switch the server re-subscribes to events and sends `session_start` for the new session (`reason` `new` / `resume` / `fork`). `new_session` does not use the `parentSession` parameter yet. Entry shapes are in [session-format.md](../session-format.md) (Chinese).
+After a session switch the server re-subscribes to events and sends `session_start` for the new session (`reason` `new` / `resume` / `fork`). `new_session` does not use the `parentSession` parameter yet. Entry shapes are in [session-format.md](../../reference/session-format.md) (Chinese).
 
 ### Approvals
 
@@ -120,7 +120,7 @@ After a session switch the server re-subscribes to events and sends `session_sta
 | `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans" \| "compact_events")[]` | `{ capabilities }`                                                                                               |
 | `permission_response`     | `requestId: string`, `decision: "allow" \| "deny" \| "allow_session"`                 | `{ accepted: boolean }` (false = not currently waiting for this id; kept and applied when that request is asked) |
 
-`compact_events` (docs/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
+`compact_events` (docs/history/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
 
 ### Tools, permissions, discovery
 
@@ -144,7 +144,7 @@ After a session switch the server re-subscribes to events and sends `session_sta
 
 ### Traces (wave 6)
 
-`get_trace` returns the session trace (the same tree as the TUI `/trace` and `ama sessions trace`, see [tui.md](tui.md)
+`get_trace` returns the session trace (the same tree as the TUI `/trace` and `ama sessions trace`, see [tui.md](../guides/tui.md)
 "Traces"). There is no new event: after `entry_appended`, fetch again with the previous `cursor.since` to refresh incrementally.
 
 | Parameter    | Meaning                                                                                                                                                                                   |
@@ -227,7 +227,7 @@ There is also the non-session event `{"type":"notification","level":"info"|"warn
 
 `parentToolCallId` appears only on inner calls made through `tools.*` inside codemode scripts; its value is the id of the outer `codemode` call, which clients use to fold the display. Inner calls do not enter the transcript.
 
-Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
+Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/history/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
 
 ### Compact events (`compact_events`)
 
@@ -243,7 +243,7 @@ In the full shapes, the result of one tool call appears once each in `message_st
 
 ### Sub-agent events (wave 5)
 
-Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../agents.md), Chinese):
+Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../../guides/agents.md), Chinese):
 
 | Event                 | Fields                                                                                                                                                                                                                      |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -349,7 +349,7 @@ The `data` of `get_session_stats` is `SessionStats`:
 {"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
 ```
 
-`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
+`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](../guides/tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
 
 It also carries `context: { tokens, window, percent }` (context used, window size and usage 0–100, defined like `contextTokens` / `contextWindow` / `contextPercent` in the table above); an unknown item is omitted (for a model without a window only `tokens` is present), and when all are unknown there is no `context`.
 
@@ -363,7 +363,7 @@ It also carries `context: { tokens, window, percent }` (context used, window siz
 
 ## Plan approval
 
-Plan mode and the plan format are described in [plan.md](../plan.md) (Chinese).
+Plan mode and the plan format are described in [plan.md](../../guides/plan.md) (Chinese).
 
 1. When a turn ends in plan mode with plain text and the reply contains a `<proposed_plan>` block, the server saves the plan and sends `plan_proposed{ planId, version, markdown, steps, filePath? }` (`steps[]`: `{ id, text, dependsOn?, agent? }`), followed by `agent_settled` as usual.
 2. The client answers only if it declared `set_client_capabilities{capabilities:["plans"]}`; otherwise the config `plan.unattended` applies: `stop` by default (the plan stays proposed, no mode switch, no execution; the client can still answer later with `plan_response`), and `approve` approves and executes within the same run.
@@ -381,7 +381,7 @@ Plan mode and the plan format are described in [plan.md](../plan.md) (Chinese).
 
 - stdin closed: no more commands are accepted and approvals are withdrawn (later asks resolve as unanswered → deny); in-flight commands and started runs finish and their responses are written, then the exit code is 0. So `printf '{"type":"prompt","message":"hi"}\n' | ama --mode rpc` gets a complete reply; to stop early, send `abort` first.
 - SIGINT / SIGTERM: the current run is interrupted and the process exits in order, with exit code 130 / 143.
-- Startup failures use the CLI exit codes ([design.md](../design.md) §11.3, Chinese): config error 3, no model or key 4, session error 5, host / hook startup failure 6, host API version mismatch 78.
+- Startup failures use the CLI exit codes ([design.md](../../design/design.md) §11.3, Chinese): config error 3, no model or key 4, session error 5, host / hook startup failure 6, host API version mismatch 78.
 
 ## Examples
 

package/docs/{agents.md → guides/agents.md}

@@ -1,7 +1,7 @@
 # Agent：子 Agent 与外部 Agent
 
 模型只认识两个工具：`task`（委派）与 `task_ctl`（管理后台任务）。`task(agent=…)` 的 `agent` 既可以是 ama 自己的子 Agent
-类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](wave5-plan.md) §7、D13、D22–D24。
+类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](../history/wave5-plan.md) §7、D13、D22–D24。
 
 ## 子 Agent
 
@@ -92,7 +92,7 @@ ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报
 `<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`；
+- RPC：`background_task { taskId? }`（[rpc.md](../reference/rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
   不给 `taskId` 时转全部前台运行中任务，正在 `task_ctl wait` 的等待也一并打断；
 - 自动：`subagents.autoBackgroundAfterMs` 大于 0 时，前台任务运行超过该毫秒数自动转后台（缺省 0 关闭）。
 
@@ -133,7 +133,7 @@ ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报
 每个任务有会话内唯一的 `taskId`（`t1`、`t2` …）。子会话结束后不立即释放，最多保留 4 个（`subagents.retainSessions`；
 最久未用的先释放内存，JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的直接追加消息，已释放的按会话文件重新打开再追加——
 同一个任务始终写同一个 JSONL。父会话在任务开始、每次续聊与结束时写一条 `custom{ama.task}`
-（[session-format.md](session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
+（[session-format.md](../reference/session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
 内存会话（`--no-session`）的任务被释放后不能续聊。子会话转录常达数十 MB，保留得越多常驻内存越大；频繁轮换续聊
 5 个以上任务时可调大保留数，代价只是被释放的任务续聊时多一次从磁盘重开。
 
@@ -159,7 +159,7 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 - 类型声明了 `tools` / `disallowed-tools`（或参数给了 `tools`）时，工具表不变，不可用的工具在执行层拒绝
   （`Tool "X" is not available in this session.`），并在 `<task>` 里列出。只读类型照旧走只读管线。
 - `<task>` 同时列出按深度拒绝的 `task` / `task_ctl` 并要求不要调用它们（执行层仍是深度拒绝的文案）。实测仍有模型把父消息里
-  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](benchmarks/efficiency-2026-10.md)「F2」）。
+  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](../benchmarks/efficiency-2026-10.md)「F2」）。
 - `isolation: "worktree"` 时子会话的 cwd 是 worktree，`<task>` 里说明上文的相对路径指父目录；cwd 节变化以尾部补丁发送，
   不影响已缓存的前缀。
 
@@ -171,12 +171,12 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 何时用 fork：子任务需要你已经读过、讨论过的内容时。fork 的首个请求把父上下文整段带上，按命中价计费；fresh 只发系统提示、
 工具表与任务说明，但你得在 `prompt` 里写清全部背景，子 Agent 往往还要重新读文件。
 
-| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
-| ------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
-| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                              | 需要父上下文时几乎总划算     |
-| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                            | 需要父上下文、且要重读较多时 |
-| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                    | 视中转而定                   |
-| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                            | 需要父上下文时               |
+| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](../benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
+| ------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------- |
+| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                                 | 需要父上下文时几乎总划算     |
+| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                               | 需要父上下文、且要重读较多时 |
+| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                       | 视中转而定                   |
+| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                               | 需要父上下文时               |
 
 fork 的成本不止首请求：子会话**每一回合**都重读整段父前缀。按命中价折算，8k 父上下文 × 30 回合在 DeepSeek（1/50）上约
 4.8k 全价 token，在 Kimi / Anthropic（1/4–1/10）上约 24k–60k，中转落空时全价。所以 DeepSeek 上子任务只要重读 ≥ 1 份
@@ -189,7 +189,7 @@ fork 的成本不止首请求：子会话**每一回合**都重读整段父前
 
 ### 事件与统计
 
-RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
+RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](../reference/rpc.md)「子 Agent 事件」。
 `getStats().tasks` 给出任务总数、运行中数量与按状态的计数；子会话的缓存命中与重计费仍汇总在 `cache.subagents`。
 RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定义文件路径）。交互界面的 `/tasks`、`/agents` 与 task 工具行的折叠显示见 [tui.md](tui.md)「子 Agent」。
 
@@ -222,15 +222,48 @@ ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agen
 
 每个 Agent 有一条候选链，按优先级取第一个已安装、且支持当前模式的：原生 ACP > 已装的 ACP 适配器 > 原生结构化协议 > 一次性打印模式。
 
-| `agent`                                   | 候选（优先级从高到低）                                                                                              | 已验证版本          |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------- |
-| `claude`                                  | `claude-agent-acp`（ACP 适配器）→ `claude -p` stream-json（原生）→ `claude -p --output-format json`（一次性，只读） | stream-json：2.1.x  |
-| `codex`                                   | `codex-acp`（ACP 适配器）→ `codex app-server`（原生）→ `codex exec --json`（一次性，只读）                          | app-server：0.160.x |
-| `gemini`                                  | `gemini --acp` → `gemini -p --output-format stream-json`（一次性，只读）                                            | 未验证              |
-| `qwen`                                    | `qwen --acp`（0.23.x 有不发权限请求的问题，只在 plan 下用）                                                         | 未验证              |
-| `kimi` / `opencode` / `goose` / `copilot` | 各自的 ACP 子命令                                                                                                   | 未验证              |
-| `ama`                                     | `ama --mode acp`                                                                                                    | 随 ama              |
-| `acp:<program>`                           | 任意 ACP Agent：表里有同名程序就用它的参数，否则不带参数启动                                                        | —                   |
+| `agent`          | 候选（优先级从高到低）                                                                                              | 已验证版本                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `claude`         | `claude-agent-acp`（ACP 适配器）→ `claude -p` stream-json（原生）→ `claude -p --output-format json`（一次性，只读） | 适配器 0.89.x；stream-json 2.1.x     |
+| `codex`          | `codex-acp`（ACP 适配器）→ `codex app-server`（原生）→ `codex exec --json`（一次性，只读）                          | 适配器 2.2.x；app-server 0.160–0.162 |
+| `copilot`        | `copilot --acp --stdio`                                                                                             | 1.0.95                               |
+| `opencode`       | `opencode acp`                                                                                                      | 1.18.x                               |
+| `pi`             | `pi --mode rpc`（原生；审批经 ama 加载的审批闸扩展，见下）                                                          | 1.1.x                                |
+| `cursor`         | `cursor-agent acp`（按官方文档：模式 `agent` / `plan` / `ask`）                                                     | 未验证（本机未装）                   |
+| `gemini`         | `gemini --acp` → `gemini -p --output-format stream-json`（一次性，只读）                                            | 未验证                               |
+| `qwen`           | `qwen --acp`（0.23.x 有不发权限请求的问题，只在 plan 下用）                                                         | 未验证                               |
+| `kimi` / `goose` | 各自的 ACP 子命令                                                                                                   | 未验证                               |
+| `ama`            | `ama --mode acp`                                                                                                    | 随 ama                               |
+| `acp:<program>`  | 任意 ACP Agent：表里有同名程序就用它的参数，否则不带参数启动                                                        | —                                    |
+
+pi 的社区 ACP 适配器 `pi-acp` 不收录：pi 本身没有审批通道，适配器不发 `session/request_permission`，工具会不经人直接执行。
+ama 改为直接驱动 `pi --mode rpc`，并以 `-e` 给这一次运行加载一个最小扩展（写在每个会话自己的临时目录，关会话即删，不碰 pi 的配置）：
+只读内置工具（`read` / `grep` / `find` / `ls`）以外的调用都经 RPC 的扩展对话框交给 ama——`plan` / `allowlist` 直接拒绝（并以
+`--tools` 只开只读工具），`auto-edit` 及更宽的模式放行 `edit` / `write`，其余交给人。用户自己的扩展弹出的对话框一律取消、不代答。
+
+#### 实测能力矩阵（2026-10-10）
+
+每条路径在临时目录各跑两个会话：非 git 目录里两轮「只回 OK」+ 一次触发审批的写文件（`default` 模式）；git 目录里长输出时中断，再续一轮。
+模型用各家最便宜的：Claude `haiku`、Codex `gpt-6-luna`、Copilot `gpt-5-mini`、OpenCode `opencode/mimo-v2.6-flash-free`、pi `openai-codex/gpt-6-luna`。
+记录与原始数字见 [benchmarks/external-agents-2026-10.md](../benchmarks/external-agents-2026-10.md)。
+
+| 路径                       | 两轮续聊 | 审批写文件                                        | 中断后续聊    | 用量 / 上下文                     | 非 git 目录    |
+| -------------------------- | -------- | ------------------------------------------------- | ------------- | --------------------------------- | -------------- |
+| Claude stream-json 2.1.295 | 通过     | 通过（`Write` 交人）                              | 通过（1.9 s） | 美元 + token；上下文（本次新增）  | 通过           |
+| claude-agent-acp 0.89.0    | 通过     | 通过                                              | 通过（2.3 s） | 美元 + token + 上下文             | 通过           |
+| Codex app-server 0.162.1   | 通过     | 通过（命令提权交人）                              | 通过（2.5 s） | token + 上下文                    | 通过           |
+| codex-acp 2.2.2            | 通过     | 未触发：只读沙箱下模型没申请提权，直接报写入被拒  | 通过（2.6 s） | token + 上下文                    | 通过           |
+| `codex exec`（一次性）     | 通过     | 不支持（只读）                                    | 结束进程      | token                             | 通过（修复后） |
+| Copilot ACP 1.0.95         | 通过     | 通过                                              | 通过（4.6 s） | 请求数；token + 上下文            | 通过           |
+| OpenCode ACP 1.18.35       | 通过     | 未触发：OpenCode 自己的权限配置放行编辑，没有问人 | 通过（6.2 s） | token + 上下文（免费模型 0 美元） | 通过           |
+| pi RPC 1.1.0               | 通过     | 通过（经审批闸交人）                              | 通过（2.7 s） | 美元（pi 按价目估算）+ 上下文     | 通过           |
+| Cursor ACP                 | —        | —                                                 | —             | —                                 | 未验证         |
+
+模式映射按实测写进驱动表：claude-agent-acp 的 `auto-edit` → `acceptEdits`、`full-auto` → `auto`（用户把缺省设成
+`bypassPermissions` 时也会被改回 ama 对应的模式）；codex-acp 的 `plan` / `default` → `read-only`、`auto-edit` → `workspace-write`、
+`auto` / `full-auto` → `agent`；Copilot 的模式 id 是 URL（`…/session-modes#agent|plan|autopilot`），`plan` 对 `#plan`、其余对 `#agent`。
+从不映射到放开全部权限的模式（`bypassPermissions`、`agent-full-access`、`autopilot`）。OpenCode 的模式来自用户自己的 agent 配置，
+没有同名模式时按它的缺省运行并提示；没有只读模式时 `plan` 拒绝启动。
 
 版本越过已验证区间时仍会启动，但会提示协议可能有变化（Claude 的 stream-json 控制协议不是公开接口，Codex app-server 标为实验）。`/agents` 与 RPC `get_agents` 列出探测结果（只查 PATH 与 `--version`，不联网、不计费；结果缓存在 `<数据目录>/drivers.json`）。
 
@@ -249,7 +282,9 @@ ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agen
 - **前台 / 后台 / 续聊**：与 ama 子会话相同——结果是外部 Agent 的最终文本加工具摘要与修改的文件（≤ 50 KB）；
   `background: true` 完成后收到 `<task-notification>`；`task{taskId}` / `task_ctl send` 在同一外部会话里续聊（进程还在就直接
   追加一轮；空闲关闭或被停止过的，以外部会话 id `resume` 重开）；`task_ctl stop` 发协议级中断，挂起的审批回「已取消」。
-- **模型**：`agents.<id>.model` 或 `task` 的 `model` 参数原样交给外部 CLI；`subagents.defaultModel`（ama 的模型）不传。
+- **模型**：`agents.<id>.model` 或 `task` 的 `model` 参数原样交给外部 CLI（原生驱动用各自的 `--model` / `-m`；ACP Agent
+  经 category `model` 的会话配置项设置，按值、名称或 `provider/model` 的模型部分匹配，没有匹配时提示并用它的缺省模型）；
+  `subagents.defaultModel`（ama 的模型）不传。
 - `/agents` 与 RPC `get_agents` 列出类型目录与外部 Agent（`installed` / `version`，会话建立时异步探测并缓存）；`/tasks` 查看任务输出、
   停止任务。界面见 [tui.md](tui.md)「子 Agent」。
 - 外部 Agent 自己报告的提示（预算用尽、超时、模式降级、拒答提问等）在交互界面的消息区显示为一行 `[claude · t3] …`，
@@ -277,7 +312,8 @@ ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agen
 | `auto`      | `auto`                               | `on-request` / `workspace-write`                           | 同上                                                     |
 | `full-auto` | `auto`（从不给 `bypassPermissions`） | `never` / `workspace-write`（从不给 `danger-full-access`） | 同上                                                     |
 
-ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，按上表同一映射在配置项的可选值里找，经 `session/set_config_option` 设置（见 [acp.md](acp.md)「作为客户端」）。
+上表 ACP 一列是缺省规则；模式 id 与 ama 不同名的 Agent 在驱动表里有显式映射（见上文「实测能力矩阵」后的说明）。
+ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，按上表同一映射在配置项的可选值里找，经 `session/set_config_option` 设置（见 [acp.md](../reference/acp.md)「作为客户端」）。
 
 一次性打印模式不能审批，只在只读任务下用。
 
@@ -320,4 +356,13 @@ CI 不跑真实 CLI。本机已登录 `claude` / `codex` 时：
 AMA_E2E_AGENTS=1 pnpm vitest run src/drivers/agents.e2e.test.ts src/agents/external-task.e2e.test.ts
 ```
 
-驱动层每家两轮「只回 OK」加一次触发审批的写文件（临时目录），会使用你的订阅额度；Claude 跑前后比对 `~/.claude` 下 settings 文件的指纹。`task` 层每家一次写文件（首次确认与写文件审批由测试代替人允许）加一轮 `taskId` 续聊；父会话用 fake 供应商。驱动的单元测试用 `test/fixtures/drivers/` 下的手写录制回放，`task` 层的零费用端到端是 ama 驱动 ama（`src/agents/external-task.test.ts`），都不发起计费请求。
+驱动层每家两轮「只回 OK」加一次触发审批的写文件（临时目录），会使用你的订阅额度；Claude 跑前后比对 `~/.claude` 下 settings 文件的指纹。`task` 层每家一次写文件（首次确认与写文件审批由测试代替人允许）加一轮 `taskId` 续聊；父会话用 fake 供应商。
+
+逐条驱动路径实测（上面的能力矩阵）用 `AMA_E2E_AUDIT` 指定 `<agent>/<驱动种类>[@模型]`，强制只走这一条路径：
+
+```sh
+AMA_E2E_AUDIT="claude/claude-stream@haiku,codex/oneshot@gpt-6-luna,pi/pi-rpc@openai-codex/gpt-6-luna" \
+  AMA_E2E_AUDIT_OUT=/tmp/audit.jsonl pnpm vitest run src/drivers/agents-audit.e2e.test.ts
+```
+
+驱动的单元测试用 `test/fixtures/drivers/` 下的录制回放（pi 的两段是 2026-10 实录，其余手写），`task` 层的零费用端到端是 ama 驱动 ama（`src/agents/external-task.test.ts`），都不发起计费请求。

package/docs/{codemode.md → guides/codemode.md}

@@ -1,6 +1,6 @@
 # codemode
 
-设计依据见 [design.md](design.md) §5.5、§5.6、§9.1。
+设计依据见 [design.md](../design/design.md) §5.5、§5.6、§9.1。
 
 `codemode` 工具让模型写一段 JavaScript，在脚本里经 `tools.*` 编排多次工具调用，只有脚本输出回到模型。长流程、工具密集的任务里，它把多次往返合成一次，减少往返次数与缓存读取；短任务里模型照常直接调用工具，codemode 只多占约 400 token 前缀，所以 `default` 预设在网络隔离的运行时上缺省开着它。
 
@@ -24,7 +24,7 @@
 
 缺省配置里不写 `codemode.mode`（`ama init` 生成的 `config.json` 也不写），所以这张映射以后调整时老用户同样生效。`ama config show` / `ama doctor` 显示生效模式与原因（跟随哪个预设、网络由 Node 还是操作系统沙箱隔离）；`ama doctor` 另列操作系统沙箱能力。
 
-`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
+`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](../design/design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
 
 `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限它的活动集（read 与宿主工具）：`tools.bash`、`tools.write` 在脚本里同样不存在，协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
 
@@ -87,7 +87,7 @@
 
 - `codemode` 本身作为一次工具调用经过 PreToolUse、权限与 PostToolUse。
 - 脚本里的每次 `tools.*` 再各自经过完整流程，Hook 按**真实工具名**匹配（`bash`，不是 `codemode`）；Hook 输入多两个字段：`viaCodemode: true` 与 `parentToolCallId`（外层 `codemode` 调用的 id）。
-- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。`ama --mode acp` 把每次内层调用单列为一条 `tool_call`（标题前缀 `codemode › `，`_meta.ama.parentToolCallId` 指向外层），其权限请求关联到这条内层调用（见 [acp.md](acp.md)）。
+- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。`ama --mode acp` 把每次内层调用单列为一条 `tool_call`（标题前缀 `codemode › `，`_meta.ama.parentToolCallId` 指向外层），其权限请求关联到这条内层调用（见 [acp.md](../reference/acp.md)）。
 
 ## 沙箱
 

package/docs/{hooks.md → guides/hooks.md}

@@ -1,6 +1,6 @@
 # 命令式 Hook（hooks.json）
 
-命令式 Hook 是在固定时机运行的 shell 命令：ama 把事件写成 JSON 交给命令的 stdin，按退出码与 stdout JSON 决定放行、阻止或改写。它是**用户策略**层——可以改工具输入、一票否决工具调用、给提示追加上下文、让运行再跑一轮。类型定义在 `src/hooks/types.ts`（经 `@armadra/agent` 导出 `HookInput`、`HookOutput`、`HookConfig` 等）。设计依据见 [design.md](design.md) §6.1、§6.3、§7.3。
+命令式 Hook 是在固定时机运行的 shell 命令：ama 把事件写成 JSON 交给命令的 stdin，按退出码与 stdout JSON 决定放行、阻止或改写。它是**用户策略**层——可以改工具输入、一票否决工具调用、给提示追加上下文、让运行再跑一轮。类型定义在 `src/hooks/types.ts`（经 `@armadra/agent` 导出 `HookInput`、`HookOutput`、`HookConfig` 等）。设计依据见 [design.md](../design/design.md) §6.1、§6.3、§7.3。
 
 ## 配置
 
@@ -125,7 +125,7 @@ interface HookOutput {
 - `additionalContext` / `customInstructions` 按配置顺序拼接。
 - 任一 Hook 返回 `continue: false` 即请求结束运行。
 
-一次工具调用的完整顺序（[design.md](design.md) §6.3）：
+一次工具调用的完整顺序（[design.md](../design/design.md) §6.3）：
 
 ```text
 模型产出工具调用

package/docs/guides/i18n.md

@@ -0,0 +1,93 @@
+# 界面语言（中英双语）
+
+> 第六波（docs/history/wave6-plan.md §5、D18–D23）。本文是开发约定：怎么选语言、文案放哪、键怎么起名、怎么测。
+> 调研依据见 [research/wave6/R8-i18n.md](../research/wave6/R8-i18n.md)。
+
+## 语言怎么定
+
+优先级从高到低，**进程启动时定一次**，不做运行中切换：
+
+1. 环境变量 `AMA_LANG`（`zh` / `en`，`zh_CN` 之类也认；写错的值忽略）；
+2. 命令行 `--lang zh|en`（也可写在子命令前：`ama --lang en doctor`）；SDK `createRuntime({ language })` / `createAgentSession({ language })` 等价；
+3. profile 的 `language`（嵌入宿主跟随画布界面语言）；
+4. 配置 `ui.language`（`auto` / `zh` / `en`，缺省 `auto`；用户级 / 项目级都可设）；
+5. `LC_ALL` → `LC_MESSAGES` → `LANG` 第一个非空值：`zh*` 为中文，其余（含 `C`、`POSIX`、`en_*`）为英文；
+6. 都没有：英文。
+
+`cli/main.ts` 在解析参数后、任何输出前按 1、2、用户级 `ui.language`、5 定语言；bootstrap 合并 profile 与项目级后，若它们给了 `ui.language` / `language`，再补定一次（仍以 1、2 为准）。`ama doctor` 显示「界面语言：zh（来源 LANG=zh_CN.UTF-8）」（`resolveLocaleWithSource`）。
+
+**界面语言只影响给人看的文字。** 发给模型的一切（系统提示、工具描述、工具结果里的标记、截断 / 裁剪占位、外部 Agent 报告、Hook 阻止理由、拒绝理由）固定英文，两种语言下请求逐字节相同。想让模型用某种语言回复，用 `ui.replyLanguage`（在 `rules` 节末尾追加一句英文规则，不设时零字节变化）。
+
+## 文案放哪
+
+```text
+src/i18n/
+  index.ts      Locale、resolveLocale / resolveLocaleWithSource、setLocale / getLocale、msg()、messagesFor()
+  types.ts      Messages<T>
+  format.ts     plural()、formatDuration()
+  catalog.ts    汇总全部领域（第六波 C0 一次登记，之后无人再改）
+  messages/<领域>.ts
+```
+
+| 领域文件                                                                    | 归属批次                              |
+| --------------------------------------------------------------------------- | ------------------------------------- |
+| `cli`、`subcommands`                                                        | W6-I1                                 |
+| `interactive`、`approval`、`plan`、`rewind`、`panels`、`permissions`        | W6-I2                                 |
+| `report`、`print`、`drivers`、`session`、`errors`                           | W6-I3                                 |
+| `config`                                                                    | W6-I4                                 |
+| `agents` / `trace` / `memory` / `auth` / `settings`                         | W6-A / W6-T1、T2 / W6-M / W6-O / W6-S |
+| `acp`（子对象 `core` / `auth` / `session` / `tools` / `config` / `client`） | ACP-C0 建，各子对象归 ACP 补全的批次  |
+
+每个领域文件同时导出 `en`（形状源）与 `zh`：
+
+```ts
+import { plural } from "../format.js";
+import type { Messages } from "../types.js";
+
+export const en = {
+  limitTurns: (limit: number) => `ama: reached the turn limit ${limit}; run ended early`,
+  dirSummary: (files: number, size: string) => `directory, ${plural(files, "file")}, ${size}`,
+  approval: { title: "Approve tool call", keys: { allow: "allow", deny: "deny" } },
+};
+
+export const zh = {
+  limitTurns: (limit) => `ama: 已达到回合上限 ${limit}，运行在完成前结束`,
+  dirSummary: (files, size) => `目录，${files} 个文件，${size}`,
+  approval: { title: "Approve tool call", keys: { allow: "allow", deny: "deny" } },
+} satisfies Messages<typeof en>;
+```
+
+`satisfies Messages<typeof en>` 让缺键、多键、参数个数 / 类型不符都在 `tsc` 期报错——两种语言必须同时给。
+
+取用：`const m = msg().print; io.stderr(m.limitTurns(limit))`。用嵌套属性访问，不用字符串键。
+
+## 键名规范
+
+- 领域文件名即一级命名空间（`msg().approval…`）；
+- 叶子 camelCase，按「组件.用途」分组：`approval.title`、`approval.keys.allow`、`rewind.skip.failed`；
+- 不以文案内容命名（`notInstalled` 可以，`weiAnZhuang` 不行）；
+- **整句一个键，禁止片段拼接**：英文语序不同，`"追加写入" + 词 + 路径` 这种要写成一个函数，条件分支写进函数体；
+- 插值写成箭头函数，参数类型写在 en 上；复数只英文需要，用 `plural(n, "file")`（不规则词给第三参数）；
+- 紧凑时长 `formatDuration(ms)`（`45s` / `2m 10s` / `1h24m`）两种语言共用；`formatTokens` / `formatUsd` / `formatPercent`、日期（ISO）与 compact 状态行记号（`ctx`、`cache`、`$`、`↑ ↓`、`⎇`、`·`）不译；
+- 枚举值、命令名、配置键、动作 id、错误码不译。
+
+## 不要这样做
+
+- **模块顶层求值**：`const HELP = msg().cli.help` 会按 import 时的语言定死（SDK / 嵌入场景显示错语言）。改成函数或 getter；`scripts/check-i18n.mjs` 会拦。
+- **按文案判断逻辑**：`text === "未安装"`、`reason.startsWith("失败")`。界面文案会随语言变，逻辑用枚举 / 码（第六波 C0 已把三处改掉）。用户**输入**的别名（`批准`、`步骤`、粘贴标记 `[粘贴 #` / `[paste #`）两种语言同时识别，与界面语言无关。
+- **模型侧模块 import `src/i18n`**：系统提示、工具（`src/tools/**`）、Plan 提示、内置子 Agent、Skill、压缩、codemode 声明、Memory 工具不得 import——`src/i18n/guard.test.ts` 守着。这些模块需要给人看的错误时抛 `AmaError(code, englishMessage, { detail })`，由界面层按 `detail` 渲染（例：`tools/image-file.ts` → `modes/image-input.ts` 的 `msg().errors.imageFile(detail)`）。
+- **宿主解析 `message`**：RPC / ACP 的 `error.message`、`-p` 的 stderr 是人读文本，会随语言变；宿主按 `code` 判断。
+
+## 测试
+
+- 测试缺省钉 zh：`test/helpers/setup.ts` 设 `AMA_LANG=zh` 并 `setLocale("zh")`，子进程也是 zh。迁移批次的验收是现有 zh 帧黄金与断言**字节不变**。
+- en 用例自己 `setLocale("en")`（或传 `AMA_LANG=en`），用完在 `afterEach` 里 `setLocale("zh")`；en 帧黄金放 `test/fixtures/tui/en/`。
+- `src/cli/lang-independence.test.ts`：同一脚本在 zh / en 下各跑一遍，发给供应商的请求逐字节相同。
+- `scripts/check-i18n.mjs`（`pnpm check:i18n`，在 `pnpm ci` 里）：
+  1. 严格（W6-I5 起，基线已清零删除）：`src/**` 源码里含汉字的代码行（注释不算）**出现即失败**。不扫的文件（测试、测试支撑、`src/i18n/`、models.dev 上游快照）在脚本的 `SKIPPED`，允许的行（用户输入别名、粘贴标记识别、价格覆盖数据的 `_reason`）在 `ALLOWED_LINES`，每条都写了理由；新增条目要在 PR 里说明；
+  2. `en` 目录里不得有汉字，`zh` 目录里不得留 `TODO`；
+  3. 顶层常量不得立即调用 `msg()`。
+
+## 体积
+
+bundle 用 `charset: "utf8"` 输出（中文按 UTF-8 原样，不转 `\uXXXX`），抵消英文目录带来的增量。

package/docs/{memory.md → guides/memory.md}

@@ -1,6 +1,6 @@
 # 记忆（Memory）
 
-> 第六波 W6-M（设计见 [wave6-plan.md](wave6-plan.md) §3、D8–D12；调研 [research/wave6/R7-memory.md](research/wave6/R7-memory.md)）。
+> 第六波 W6-M（设计见 [wave6-plan.md](../history/wave6-plan.md) §3、D8–D12；调研 [research/wave6/R7-memory.md](../research/wave6/R7-memory.md)）。
 
 跨会话的个人笔记：你说「记住……」，模型把它写成一条 Markdown，下次会话开始时索引进系统提示，正文按需读取。
 **缺省关闭**；关闭时不读盘、不注册工具、不渲染节，发给模型的请求与没有这个功能时逐字节相同。

package/docs/{permissions.md → guides/permissions.md}

@@ -1,6 +1,6 @@
 # 权限模式与 auto 判定
 
-本文写 ama 的六种权限模式、每次工具调用的判定顺序，以及 `auto` 模式「规则层 → 静态判定 → 模型分类器」三层怎样决定放行还是询问。总体设计见 [design.md](design.md) §6.3、§7；Hook 的输入输出见 [hooks.md](hooks.md)。
+本文写 ama 的六种权限模式、每次工具调用的判定顺序，以及 `auto` 模式「规则层 → 静态判定 → 模型分类器」三层怎样决定放行还是询问。总体设计见 [design.md](../design/design.md) §6.3、§7；Hook 的输入输出见 [hooks.md](hooks.md)。
 
 ## 模式
 
@@ -42,7 +42,7 @@
 | 外部 Agent（claude / codex / ACP）请求权限 | `[claude · 会话 abc12345]`                | 外部 Agent 给的标题、种类、涉及路径与输入摘要 | 只交给人：宿主 → 界面 → 无人值守拒绝，auto 分类器与模型不参与              |
 | 外部 Agent 本会话首次运行                  | 标题「首次运行外部 Agent」                | 说明（以你在该 CLI 的登录运行）与模式         | allow / deny 规则 `task(<id>)`、`full-auto` 放行，其余交给人（不经分类器） |
 
-外部 Agent 的「本会话允许」由它自己记住。Manual 模式下 `task(agent=…)` 的 task 调用审批与首次运行确认合并为一次（见 [agents.md](agents.md)「在 task 里使用」）。RPC 的 `context` 是 `{ depth, taskId, origin }`（[rpc.md](rpc.md)「审批」）。
+外部 Agent 的「本会话允许」由它自己记住。Manual 模式下 `task(agent=…)` 的 task 调用审批与首次运行确认合并为一次（见 [agents.md](agents.md)「在 task 里使用」）。RPC 的 `context` 是 `{ depth, taskId, origin }`（[rpc.md](../reference/rpc.md)「审批」）。
 
 ## plan 模式与只读命令
 

package/docs/{plan.md → guides/plan.md}

@@ -1,6 +1,6 @@
 # Plan 模式
 
-plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批准后再切回执行模式按计划推进。本文写流程、计划格式、审批的几种入口、配置与持久化；权限细节见 [permissions.md](permissions.md)「plan 模式与只读命令」，设计依据见 [wave5-plan.md](wave5-plan.md) §6。
+plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批准后再切回执行模式按计划推进。本文写流程、计划格式、审批的几种入口、配置与持久化；权限细节见 [permissions.md](permissions.md)「plan 模式与只读命令」，设计依据见 [wave5-plan.md](../history/wave5-plan.md) §6。
 
 ## 流程
 
@@ -54,7 +54,7 @@ plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 交互（TUI）                          | 用户在底部审批框里选：批准并执行 / 批准，在新上下文执行（两者接着选执行模式：回到进入前的模式 / Accept edits / Auto）/ 继续修改（框内或外部编辑器写意见）/ 放弃并退出 Plan；`e` 在 `$VISUAL` / `$EDITOR` 里改计划，Esc 放弃但留在 Plan。见 [tui.md](tui.md)「Plan 审批」 |
 | 交互（line，`--no-tui`）             | `/plan approve [模式\|fresh]`、`/plan reject`；回复 `1` / `2` / `3` 也能批准（进入前的模式 / Accept edits / Auto），其它内容作为修改意见、留在 plan                                                                                                                      |
-| RPC，声明了 `plans` 能力             | 客户端：`plan_proposed` → `plan_response`（见 [rpc.md](rpc.md)「计划审批」）                                                                                                                                                                                             |
+| RPC，声明了 `plans` 能力             | 客户端：`plan_proposed` → `plan_response`（见 [rpc.md](../reference/rpc.md)「计划审批」）                                                                                                                                                                                |
 | SDK，给了 `plan.onProposed`          | 回调：运行结束后调用，返回 `{ decision, mode?, feedback?, editedMarkdown? }`；返回 undefined 留待 `session.plan.respond()`                                                                                                                                               |
 | `-p`、未声明能力的 RPC、无回调的 SDK | 配置 `plan.unattended`：`stop`（缺省）落盘计划后停下，不切模式、不执行；`approve` 在同一次运行里自动批准并执行                                                                                                                                                           |
 
@@ -65,7 +65,7 @@ plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批
 - **revise**：留在 plan；`feedback` 作为普通用户消息开回合，模型整份重写计划，新版本号 +1，旧版标 superseded。
 - **reject**：计划标 rejected，留在 plan。交互界面的「放弃，退出 Plan 模式」在 reject 之后切回进入前的模式；审批框里按 Esc 是 reject 但留在 plan。
 
-**进度记法**：活动工具集里有 `todo`（`tools.default: ["+todo"]`、`--tools …,todo`）时，交接消息请模型「按 todo 推进，每完成一步 todo update」；没有时（`default` 预设缺省不含 todo，见 D20 与 [docs/benchmarks/](https://github.com/Owlbay/armadra-agent/tree/main/docs/benchmarks)）请模型每完成一步在回复里**单独一行**写 `[DONE:<步骤 id>]`（如 `[DONE:S1]`），ama 在回合结束时读这些标记：对应的计划待办标 done，没有进行中的项时下一个 pending 转 in_progress，照常落 `ama.todo`、发 `todo_updated`，界面与 RPC 的进度显示不受影响。「在新上下文执行」的首条消息用同样的规则。
+**进度记法**：活动工具集里有 `todo`（`tools.default: ["+todo"]`、`--tools …,todo`）时，交接消息请模型「按 todo 推进，每完成一步 todo update」；没有时（`default` 预设缺省不含 todo，见 D20 与 [docs/benchmarks/](https://github.com/AMA-Link/armadra-agent/tree/main/docs/benchmarks)）请模型每完成一步在回复里**单独一行**写 `[DONE:<步骤 id>]`（如 `[DONE:S1]`），ama 在回合结束时读这些标记：对应的计划待办标 done，没有进行中的项时下一个 pending 转 in_progress，照常落 `ama.todo`、发 `todo_updated`，界面与 RPC 的进度显示不受影响。「在新上下文执行」的首条消息用同样的规则。
 
 客户端改过的全文（`editedMarkdown`，界面里「在外部编辑器里改」）先落一份新版本，交接消息用改后的全文。
 
@@ -100,7 +100,7 @@ plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批
 
 ## 接口
 
-- RPC：命令 `plan_response` / `get_plan` / `get_todos`，能力 `plans`，事件 `plan_proposed` / `plan_resolved` / `todo_updated`，见 [rpc.md](rpc.md)。
+- RPC：命令 `plan_response` / `get_plan` / `get_todos`，能力 `plans`，事件 `plan_proposed` / `plan_resolved` / `todo_updated`，见 [rpc.md](../reference/rpc.md)。
 - SDK：`createAgentSession({ plan: { bash?, directory?, unattended?, model?, thinkingLevel?, onProposed? } })`；返回的会话有 `session.plan.current()`、`session.plan.respond(response)`、`session.plan.todos()`。
 - 进程内：`planController(session)`（`src/agent/session-plan.ts`）给界面用——`pending()`、`respond()`、`proposeFromLastReply()`、`adopt()`、`setAttendance()`。
 - 交互界面：底部审批框（四个选项 + 执行模式、`e` 编辑计划、Esc 留在 Plan）、`/plan` 面板，`/plan <目标>` 进入 Plan 并发出目标，`/plan approve [模式|fresh]` / `/plan reject` 不开对话框直接作答；见 [tui.md](tui.md)「Plan 审批」。

package/docs/{providers.md → guides/providers.md}

@@ -1,6 +1,6 @@
 # 供应商与模型
 
-内置供应商、模型引用、API Key、自定义供应商与中转站、各协议的 compat 开关，以及缓存。设计依据见 [design.md](design.md) §3、§9.1。
+内置供应商、模型引用、API Key、自定义供应商与中转站、各协议的 compat 开关，以及缓存。设计依据见 [design.md](../design/design.md) §3、§9.1。
 
 ## 配置目录
 
@@ -223,12 +223,13 @@ developer 消息（前缀依然稳定）。compat `toolsInNamespace: true` 时
 
 **错误码**（错误文案以码开头，宿主按码判断）：
 
-| 码               | 来源                                                                                                         | 处理                                  |
-| ---------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
-| `quota_exceeded` | siwc 429 `subscription_sharing_usage_limit_exceeded`；codex 429 `usage_limit_reached` / `usage_not_included` | 不重试；附重置时间并发 `quota_update` |
-| `auth_expired`   | 401 刷新一次仍失败、刷新永久失败、条目 `needsLogin`                                                          | 不重试；重新 `ama auth login chatgpt` |
-| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | 不重试、不重登；排查见下              |
-| （原样）         | 503 等                                                                                                       | 走会话层现有的退避重试                |
+| 码                  | 来源                                                                                                         | 处理                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `quota_exceeded`    | siwc 429 `subscription_sharing_usage_limit_exceeded`；codex 429 `usage_limit_reached` / `usage_not_included` | 不重试；附重置时间并发 `quota_update`                                                   |
+| `auth_expired`      | 401 刷新一次仍失败、刷新永久失败、条目 `needsLogin`                                                          | 不重试；重新 `ama auth login chatgpt`                                                   |
+| `not_eligible`      | siwc 403 `subscription_sharing_user_not_eligible`                                                            | 不重试、不重登；排查见下                                                                |
+| `model_unavailable` | codex 400「model is not supported when using Codex with a ChatGPT account」                                  | 不重试；后端模型表变了（发现缓存过期），运行 `ama models discover chatgpt` 刷新后换模型 |
+| （原样）            | 503 等                                                                                                       | 走会话层现有的退避重试                                                                  |
 
 **`not_eligible` 排查**：账户不能把套餐额度共享给 ama。可能的原因：账户套餐（额度共享只对 Plus / Pro 开放）；工作空间
 账户（Team / Enterprise / Edu 可能未开放）；地区受限或预览期尚未开放——**Pro 账户仍报此错时最可能是这一条**。可以改用
@@ -628,9 +629,9 @@ OpenRouter 的 Messages 接口只在 `message_delta` 里给缓存 usage，解析
 
 长任务的主要用量是缓存读取：前缀一旦变化，此后每次请求都要按全价重读。ama 分三层处理缓存：**协议层**按各家写法打断点、发缓存键与保留层级，并标记响应里有没有缓存字段；**会话层**记录每次请求的前缀指纹，检测未命中、判定端点报不报缓存、在长工具运行期间保温；**展示层**是状态栏、`/session`、RPC 统计与 `ama models cache-probe`（界面怎么读见 [tui.md](tui.md)「缓存与上下文」）。
 
-前缀稳定由组装保证：系统提示节顺序固定、不含时间戳，工具按名排序，会话中途的变化只以 system 补丁追加在末尾（[session-format.md](session-format.md)「消息」）。
+前缀稳定由组装保证：系统提示节顺序固定、不含时间戳，工具按名排序，会话中途的变化只以 system 补丁追加在末尾（[session-format.md](../reference/session-format.md)「消息」）。
 
-**开头的 system 与工具声明在会话内只写一次。** 对话开始之后的节补丁（resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了，宿主 instructions 刷新，压缩后记忆节重新渲染）不改写开头：没有打开 `supportsMidConvoSystemMessages` 的协议把它渲染成 `<system-reminder>` 包裹的 user 消息，插在补丁所在的位置，之前的请求仍是逐字节前缀。实测 DeepSeek 接受对话中途的 system 消息、前缀缓存也保持，但模型仍按开头那条回答，所以 DeepSeek 不打开这个开关（[cache-midconvo-2026-10-09](benchmarks/cache-midconvo-2026-10-09.md)）。
+**开头的 system 与工具声明在会话内只写一次。** 对话开始之后的节补丁（resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了，宿主 instructions 刷新，压缩后记忆节重新渲染）不改写开头：没有打开 `supportsMidConvoSystemMessages` 的协议把它渲染成 `<system-reminder>` 包裹的 user 消息，插在补丁所在的位置，之前的请求仍是逐字节前缀。实测 DeepSeek 接受对话中途的 system 消息、前缀缓存也保持，但模型仍按开头那条回答，所以 DeepSeek 不打开这个开关（[cache-midconvo-2026-10-09](../benchmarks/cache-midconvo-2026-10-09.md)）。
 
 工具表同理：对话开始后新加的工具追加在工具表末尾；**移除工具不删声明**，提醒里写一句 `Tool "X" is no longer available in this session; calls to it are rejected.`，模型仍去调用时执行层拒绝（`Tool "X" is not available in this session.`）；再加回只提醒 `Tool "X" is available again.`，声明沿用第一次发送的版本。系统提示的 `tools` / `rules` 两节在对话开始后也冻结为已发送的文本。
 
@@ -747,7 +748,7 @@ xAI、Mistral、OpenRouter、Google 没有承诺的 TTL，留空：不保温、
 | 取消   | 换模型、换思考级别、压缩、`/tree`、退出时取消，下一次真实请求再开始                                                                                                                        |
 | 记账   | 成功的保温追加 `usage{kind:"cache_warm"}` 条目（不进上下文），计入 `/session` 费用与 RPC 统计；事件 `cache_warm{scheduled｜sent｜stopped}`                                                 |
 
-宿主可以经 `api.cache.onWarmingDecision` 否决或强制每一次保温（[host-api.md](host-api.md)「缓存保温」）。子会话缺省不保温（`cache.warmSubagents: true` 打开）。按目录价格估算，长工具运行期间几乎总是划算；空闲保温只对贵模型、长前缀划算。
+宿主可以经 `api.cache.onWarmingDecision` 否决或强制每一次保温（[host-api.md](../reference/host-api.md)「缓存保温」）。子会话缺省不保温（`cache.warmSubagents: true` 打开）。按目录价格估算，长工具运行期间几乎总是划算；空闲保温只对贵模型、长前缀划算。
 
 ### 压缩摘要续写
 

package/docs/{sessions.md → guides/sessions.md}

@@ -1,6 +1,6 @@
 # 会话统计、检索、复用、导出与检查点
 
-这几条命令都只读会话目录（`<数据目录>/sessions`，`--session-dir` 可改；文件格式见 [session-format.md](session-format.md)）：不加锁、不修复半行、不改文件，正在运行的会话也能读。会话文件按块逐行读取，不整份读进内存：`ama sessions list` 只解析每个文件的头、首条条目、改名与首条提示，其余行只看类型，几十 MB 的会话也不会让内存随文件大小上涨；`--resume` 打开会话同样逐行解析。范围缺省是**当前目录**的会话，`--all` 看全部。
+这几条命令都只读会话目录（`<数据目录>/sessions`，`--session-dir` 可改；文件格式见 [session-format.md](../reference/session-format.md)）：不加锁、不修复半行、不改文件，正在运行的会话也能读。会话文件按块逐行读取，不整份读进内存：`ama sessions list` 只解析每个文件的头、首条条目、改名与首条提示，其余行只看类型，几十 MB 的会话也不会让内存随文件大小上涨；`--resume` 打开会话同样逐行解析。范围缺省是**当前目录**的会话，`--all` 看全部。
 
 ## 统计：`ama stats`
 
@@ -154,7 +154,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 - `--no-content`：只留结构、时间与数字（没有提示、参数、结果，也没有错误原文），适合只想分享性能问题时。
 - `--children`：内嵌 ama 子 Agent 子会话里节点的预览；缺省只嵌它们的结构与数字。外部 Agent 本来就只有骨架。
 - 预览按条截断（参数 500、其余 2000 字符），整份预览上限 4 MB 字符，超出后更早的预览置空并在详情里注明。
-- `--json`（或 `--format json`）：与 RPC `get_trace` 同形的 JSON（[rpc.md](rpc.md)「轨迹」），包含全部回合、已加载的子会话轨迹与本会话节点的 `previews`
+- `--json`（或 `--format json`）：与 RPC `get_trace` 同形的 JSON（[rpc.md](../reference/rpc.md)「轨迹」），包含全部回合、已加载的子会话轨迹与本会话节点的 `previews`
   （`--no-content` 时没有）。
 - 输出：`--html <文件>`（文件名以 `.html` / `.htm` 结尾时才当作值，否则用 `--output`）或 `--output <文件>` 写文件（0600），否则写 stdout。
   `--open` 写好后用系统浏览器打开（没给文件时写到临时目录）。
@@ -163,7 +163,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 
 ## 检查点与文件备份
 
-回滚代码（`/rewind`，设计见 [rewind-plan.md](rewind-plan.md)）依赖检查点：每个新回合开始时，ama 记下 edit / write 改过的文件当时的内容。
+回滚代码（`/rewind`，设计见 [rewind-plan.md](../history/rewind-plan.md)）依赖检查点：每个新回合开始时，ama 记下 edit / write 改过的文件当时的内容。
 
 - **存储位置**：备份按内容 sha256 存在 `<数据目录>/file-history/blobs/<前 2 位>/<sha256>`，原字节、不压缩；多个会话、多个检查点共用，同内容只存一份。会话文件里只有 `ama.checkpoint` / `ama.checkpoint-track` 两类 `custom` 条目（记哈希，不进上下文）。会话目录不在缺省位置时（`--session-dir`、宿主 profile 的 `sessionDir`），目录登记在 `file-history/roots.json`，清理时一并扫描。
 - **跟踪范围**：edit / write（含 codemode 内层调用与 task 子会话）第一次写某文件之前备份它；之后每个新回合按当前磁盘内容重拍已跟踪的文件，所以 bash 或手动对这些文件的改动也会进下一个检查点。bash 新建或改动的其它文件不跟踪。
@@ -192,7 +192,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 
 ## 回滚（会话内）
 
-`/rewind`、RPC `rewind`、SDK `session.rewind()` 回到某条用户消息之前（设计见 [rewind-plan.md](rewind-plan.md)）：
+`/rewind`、RPC `rewind`、SDK `session.rewind()` 回到某条用户消息之前（设计见 [rewind-plan.md](../history/rewind-plan.md)）：
 
 - 回滚点是活动路径上开启新回合的用户消息，从旧到新；运行中插话、排队消息与 Stop Hook 续跑的消息并入当前回合，不单列。运行中回滚报 `busy`。
 - 对话回滚复用 `/tree` 换叶子：离开的分支留在文件里，可以再从 `/tree` 回去；模型、思考级别与权限模式保持当前，不随回滚改变。之后第一次请求的 system、工具表与落点之前的消息和回滚前逐字节相同，提示缓存照常命中。
@@ -200,7 +200,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 - 仅对话或仅代码时，下一次提示前在末尾追加一条 `ama.rewind-note` 告诉模型哪些文件与对话不一致；对话 + 代码不追加。
 - 内存会话与 `checkpoints.mode: "off"` 不建检查点，只能仅对话。
 - 运行中 Esc 中断、本回合还没有任何回复或工具调用时，撤回该回合并回填原消息（`ui.restoreOnCancel`，缺省 true）。
-- 回到图片被降级之前时图片从会话文件回读；文件已被外部改写、读不回时图片保留为空，并告警一次（`AMA_LOG`，TUI 显示在通知区；见 [session-format.md](session-format.md)「内存表示」）。
+- 回到图片被降级之前时图片从会话文件回读；文件已被外部改写、读不回时图片保留为空，并告警一次（`AMA_LOG`，TUI 显示在通知区；见 [session-format.md](../reference/session-format.md)「内存表示」）。
 
 ## 请求明细（设计，未实现）