@armadra/agent 0.4.0 → 0.5.1

package/dist/tui/keybindings.js

@@ -33,14 +33,19 @@ export const DEFAULT_KEYBINDINGS = {
     "tui.select.confirm": ["enter", "tab"],
     "tui.select.cancel": ["escape", "ctrl+c"],
     "app.interrupt": ["escape"],
+    "app.rewind": ["escape"],
     "app.clear": ["ctrl+c"],
     "app.exit": ["ctrl+d"],
     "app.message.followUp": ["alt+enter"],
     "app.message.dequeue": ["alt+up"],
-    "app.permission.cycle": ["shift+tab"],
+    "app.permission.cycle": ["shift+tab", "tab"],
     "app.tools.expand": ["ctrl+o"],
     "app.model.select": ["ctrl+l"],
     "app.thinking.select": ["ctrl+t"],
+    /** [W5-A] 底部信息行 full ↔ compact（只影响本会话）。 */
+    "app.statusLine.toggle": ["ctrl+g"],
+    /** [W5-U] 粘贴剪贴板图片（写进数据目录，输入框插入 `@路径`）。 */
+    "app.paste.image": ["ctrl+v"],
 };
 export function isActionId(id) {
     return Object.prototype.hasOwnProperty.call(DEFAULT_KEYBINDINGS, id);

package/docs/acp.md

@@ -0,0 +1,78 @@
+# ACP（Agent Client Protocol）
+
+ama 在 ACP 两侧都能用：
+
+- **服务端**：`ama --mode acp` 把 ama 暴露为 ACP Agent，供 Zed、JetBrains、Armadra 的 ACP 节点驱动；
+- **客户端**：ama 经 ACP 驱动外部 Agent（Gemini CLI、OpenCode、Kimi、Copilot 等原生 ACP，或装了适配器的 Claude Code / Codex），见 [agents.md](agents.md)。
+
+协议栈零依赖、手写，只维护一份：`@armadra/agent/acp` 导出类型、分帧、客户端与假 Agent，Armadra 直接复用。设计依据见 [wave5-plan.md](wave5-plan.md) §5（D14）。
+
+## 线路
+
+JSON-RPC 2.0 over NDJSON（stdio）：只按 `\n` 切行，64 KiB 分片写并等待背压，与 [rpc.md](rpc.md) 的「线路」一致。stdout 只有协议行，诊断写 stderr。由客户端以 `initialize` 起头，没有 `hello`。
+
+## `ama --mode acp`
+
+```sh
+ama --mode acp                      # 与 -p 互斥；其余参数（--model、--profile、--trust 等）照常
+```
+
+| 方法                     | ama 的行为                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize`             | `protocolVersion: 1`；`loadSession: true`，`sessionCapabilities: { list, resume, close }`，`promptCapabilities: { image: true, embeddedContext: true }`；不要认证 |
+| `session/new`            | 新开会话（启动时那个空会话第一次直接认领）；`cwd` 必须是 ama 的启动目录（按 realpath 比较），否则 invalid params                                                  |
+| `session/load`           | 切到该会话并以 `session/update` 回放历史（用户消息、回复、思考、工具调用）                                                                                        |
+| `session/resume`         | 切到该会话，不回放                                                                                                                                                |
+| `session/list`           | 启动目录下的会话（标题取会话名或首条提示）                                                                                                                        |
+| `session/close`          | 中断运行并释放活动会话                                                                                                                                            |
+| `session/prompt`         | 文本与图片照收；`resource_link` 以 `@uri` 文本给出，嵌入资源取文本。回合结束：中断 → `cancelled`，输出截断 → `max_tokens`，出错 → JSON-RPC 错误                   |
+| `session/cancel`（通知） | 中断当前回合                                                                                                                                                      |
+| `session/set_mode`       | 模式 id 就是 ama 的权限模式（`plan`、`allowlist`、`default`、`auto-edit`、`auto`、`full-auto`）                                                                   |
+
+一次只有一个活动会话；对非活动会话发 `session/prompt` 时（空闲）先切过去，运行中切换报 invalid request。
+
+### 事件映射
+
+| ama                 | `session/update`                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| 文本增量 / 思考增量 | `agent_message_chunk` / `agent_thought_chunk`                                      |
+| 模型发出工具调用    | `tool_call`（`pending`，带 `rawInput`、`kind`、`locations`）                       |
+| 工具开始 / 结束     | `tool_call_update`（`in_progress` → `completed` / `failed`，结果只带前 4 KB 文本） |
+| `todo` 更新         | `plan`                                                                             |
+| 每轮结束            | `usage_update`（上下文已用、窗口、会话累计美元）                                   |
+| 权限模式变化        | `current_mode_update`                                                              |
+
+codemode 内层调用不单列。`session/prompt` 的结果带本回合 token 用量（`inputTokens`、`outputTokens`、`cachedReadTokens`、`cachedWriteTokens`、`totalTokens`）。
+
+### 审批
+
+ama 需要询问的调用经 `session/request_permission` 交给客户端，三个选项：`allow_once`（允许）、`allow_always`（本会话允许）、`reject_once`（拒绝）。`toolCall.toolCallId` 关联到先前 `tool_call` 的 id。客户端回 `cancelled`、连接断开或回合被中断时，按无人作答处理（拒绝）。auto 模式下 ama 自己的分类器照常工作——这只影响 ama 自己的工具；ama 驱动的外部 Agent 发来的请求只交给人（见 [agents.md](agents.md)）。
+
+不声明、也不使用客户端的 `fs` / `terminal` 能力：ama 自己读写、自己跑命令，按自己的权限管线。
+
+### 退出
+
+stdin 关闭后等已开始的运行结束再退出（0）；SIGINT / SIGTERM 中断后退出 130 / 143。宿主看到的模式是 `rpc`（`HostApi.mode`）。SDK 直接 `bootstrap(--mode acp)` 时得到 `mode: "rpc"` 的 Runtime，再交给 `runAcpMode`。
+
+## 作为客户端
+
+模型经 `task(agent="acp:<程序>")` 使用 ACP Agent（ama 自己是 `task(agent="acp:ama")`，见 [agents.md](agents.md)「在 task 里使用」）。
+
+`AcpClient`（`@armadra/agent/acp`）：`initialize`、`newSession`、`resumeSession`（优先，不回放）、`loadSession`、`listSessions`、`closeSession`、`prompt`、`setMode`、`cancel`。
+
+- 声明的客户端能力为空：Agent 发来的 `fs/*`、`terminal/*` 请求回 method not found。
+- `session/request_permission` 交给 `onPermission`；没有处理器时回首个 `reject_once`（无人值守）。
+- `cancel(sessionId)` 发 `session/cancel`，并让该会话挂起的权限请求回 `cancelled`（规范要求）。
+- 只接受 Agent 自己给出的 `optionId`。
+
+`AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：续接优先 `session/resume`，其次 `session/load`（回放的历史丢弃），都不支持就新开并提示；按 ama 模式 `session/set_mode`，只读模式找不到对应模式 id 时拒绝启动。
+
+## 测试替身
+
+`runFakeAcpAgent(input, output)` 是进程内的假 ACP Agent，`fakeAcpAgentPath()` 是它的可执行入口（`node <path> [--minimal]`）。行为由提示里的标记决定：`[permission]`（请求权限，四个选项）、`[slow]`（等到 cancel）、`[plan]`、`[think]`、`[refuse]`，其余回 `echo: <文本>`。`--minimal` 不声明 resume / load / list / close，也不给模式，用来测降级路径。
+
+黄金记录在 `test/fixtures/acp/`：`driver-{allow,reject,cancel}.jsonl`（ama 驱动假 Agent 的三条路径）与 `mode-prompt.jsonl`（`ama --mode acp` 一轮往返）。`UPDATE_GOLDEN=1` 重写。
+
+## 兼容性
+
+按 ACP v1（含 2026 年稳定的 `session/list`、`session/resume`、`session/close`、`usage_update`）。v2 计划取消 `session/load`，ama 作客户端时已优先 `resume`。

package/docs/agents.md

@@ -0,0 +1,250 @@
+# Agent：子 Agent 与外部 Agent
+
+模型只认识两个工具：`task`（委派）与 `task_ctl`（管理后台任务）。`task(agent=…)` 的 `agent` 既可以是 ama 自己的子 Agent
+类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](wave5-plan.md) §7、D13、D22–D24。
+
+## 子 Agent
+
+### 何时可用
+
+`task` 与 `task_ctl` 同进退：`default` 预设下只在 codemode 脚本里可调用，`--tools …,task` 或 `tools.default: ["+task"]`
+时直接暴露；嵌入宿主时宿主可以禁用。子 Agent 运行在同一进程的新会话里（全新上下文，看不到父对话，`prompt` 要写全），
+有自己的 JSONL（与父会话同目录，头的 `parentSession` 指回父文件）。深度最多 1：子 Agent 里调用 `task` / `task_ctl` 会被拒绝。
+
+### 内置类型
+
+| 类型              | 工具       | 权限                                  | 角色说明（追加在子会话系统提示末尾）       |
+| ----------------- | ---------- | ------------------------------------- | ------------------------------------------ |
+| `general`（缺省） | 父的活动集 | 与父相同                              | 直接完成、不再委派，结束时给精简报告       |
+| `explore`         | 父的活动集 | plan 模式：写类工具与非只读 bash 被拒 | 只定位不评审，返回路径与行号，说明搜索范围 |
+| `plan`            | 父的活动集 | plan 模式                             | 输出分步计划、关键文件与取舍，不修改文件   |
+
+只读靠权限层：只读类型的子会话用一条 plan 模式的权限管线（规则与父相同），需要确认的调用一律直接拒绝，**不弹审批**。
+工具表与父会话逐字节相同（`task` / `task_ctl` 也在表里，运行时拒绝），子会话的首个请求能复用父会话已缓存的 tools + system
+前缀；角色说明是系统提示最后一个节（`role`），父会话的全部节都是它的前缀。只有类型声明了 `tools` / `disallowed-tools`
+（或调用时传了 `tools`）时工具表才不同，此时首个请求不命中父的缓存。
+
+### 定义文件
+
+一个 `*.md` 是一个类型，frontmatter 与 Skill 同一套写法（字段名 kebab-case），正文是角色说明：
+
+```markdown
+---
+name: reviewer # ^[a-z0-9-]{1,64}$，缺省取文件名
+description: 只读审查改动，按文件与行号报告问题。 # 必填，≤ 1024 字符，出现在 task 工具描述里
+tools: read, grep, glob, bash # 白名单；与 disallowed-tools 二选一
+permission-mode: plan # plan | inherit（缺省）；只能比父更严
+model: fast # inherit（缺省）| fast | strong（models.aliases）| provider/model
+thinking: low
+max-turns: 20 # 缺省 30
+isolation: none # none（缺省）| worktree
+background: false
+runner: ama # ama（缺省）| claude | codex | acp:<程序>
+---
+
+引用改动时写 file:line，先列严重问题。
+```
+
+发现顺序（同名先发现者胜，并给出提示；内置类型可被同名定义覆盖）：
+
+1. `--agent-dir <目录>`（可重复），之后是 profile 的 `agentDirs`；
+2. config 的 `agents.dirs`；
+3. `~/.config/ama/agents/*.md`（用户级）；
+4. `<项目>/.ama/agents/*.md`（项目级，**需要信任**；未信任时跳过并在启动时提示）。
+
+不合格的文件不加载并给出提示（名字非法、缺 description、`tools` 与 `disallowed-tools` 同时给出、取值不认识等）。
+不支持的字段（`hooks`、`mcpServers`、`memory`、`color`、`initialPrompt`、`skills`）忽略；子会话本来就继承父的 Skill 索引。
+
+模型选择：调用参数 `model` > 定义的 `model`（非 inherit）> config `agents.<类型>.model` > `subagents.defaultModel` > 父当前模型。
+`fast` / `strong` 经 `models.aliases` 映射，没配置时用父模型并提示。
+
+### `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` | 保留的高级参数（描述里不展开）                                             |
+
+同一条回复里的多个 `task` **并行**执行，由会话的任务池限流（`subagents.maxConcurrent`，缺省 4）；排队超过
+`subagents.maxPending`（缺省 16）直接报错，提示模型不要重试。并行且会写文件的任务请用 `isolation: "worktree"`。
+与 `edit` 等串行工具出现在同一批时，按工具执行规则整批串行。
+
+结果是子 Agent 的最终报告，前面带 `[task tN]`。超过 50 KB 时保留开头 70% 与结尾 30%，中间注明省略了多少字节，
+全文写到会话目录的 `outputs/<会话 id>-<taskId>.md`（内存会话写到系统临时目录）。轮数用尽且最后一步停在工具结果上时，
+ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[Turn limit reached; …]`，状态 `max_turns`。
+
+### 后台任务与 `task_ctl`
+
+`background: true` 立即返回 `taskId` 与输出文件路径。任务完成后，ama 在父会话空闲时投递一条 user 消息（`origin: "task"`）
+并开始新回合；父正忙则等这一轮结束再投递，不打断。多条通知按完成顺序到达：
+
+```text
+<task-notification taskId="t3" agent="explore" status="completed" turns="7" tokens="12.3k" outputFile="…">
+…最终报告（≤ 50 KB）…
+</task-notification>
+```
+
+系统提示的规则里写明这类消息是后台任务的报告、不是用户发言。被 `task_ctl stop` 停止或随会话关闭的任务不发通知。
+后台任务的审批照常交给父会话的界面 / RPC 客户端（`-p` 下需要确认的调用视同拒绝）；后台任务的全文总会写到输出文件。
+
+`task_ctl` 的动作：
+
+| `action` | 说明                                                                               |
+| -------- | ---------------------------------------------------------------------------------- |
+| `list`   | 列出本会话的任务：编号、类型、状态、轮数、token、耗时、是否后台、描述              |
+| `wait`   | 等任务结束（`timeoutMs` 缺省 30 000，最多 600 000）；超时说明仍在运行              |
+| `stop`   | 停止任务，返回终态                                                                 |
+| `output` | 运行中返回已有输出，结束后返回最终文本（同样有 50 KB 上限）                        |
+| `send`   | 向任务追加一条消息并放到后台运行（等价于 `task{taskId, prompt, background:true}`） |
+
+### 续聊、保留与 resume
+
+每个任务有会话内唯一的 `taskId`（`t1`、`t2` …）。子会话结束后不立即释放，最多保留 16 个（最久未用的先释放内存；
+JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的直接追加消息，已释放的按会话文件重新打开再追加——
+同一个任务始终写同一个 JSONL。父会话在任务开始、每次续聊与结束时写一条 `custom{ama.task}`
+（[session-format.md](session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
+内存会话（`--no-session`）的任务被释放后不能续聊。
+
+### worktree 隔离
+
+`isolation: "worktree"` 时，ama 在父 cwd 所在仓库里执行
+`git worktree add -b ama/task-<名字> <仓库>/.ama/worktrees/<名字>`（名字 = 会话 id 前 8 位 + `taskId`），子会话的 cwd 是
+worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净且没有新提交）就删掉 worktree 与分支；有改动则保留，结果末尾给出
+分支名、路径与 `git diff --stat`（含未跟踪文件），由你决定是否合并。`.ama/worktrees/` 下自动写一个 `.gitignore`（`*`），
+父仓库的 `git status` 与 grep / glob 都看不到这些目录。不在 git 仓库里时直接报错，不会退回共享目录。
+worktree 里的编辑不记进父会话的检查点。注意：worktree 不共享依赖（`node_modules` 等），不保证能直接构建或运行测试。
+
+### 事件与统计
+
+RPC / SDK 事件 `subagent_start` / `subagent_update` / `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` 的映射    |
+
+### 限制
+
+- 子 Agent 不能再委派（深度 1）；协调多个 Agent 的场景交给宿主（如 Armadra 画布）。
+- 只读类型的 bash 只放行 plan 模式认可的只读命令，识别不了的一律拒绝，宁可少用。
+- 不读取 `.claude/agents`；不支持 fork 模式（继承父对话的子 Agent）。
+
+## 外部 Agent
+
+ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agent，结果作为 `task` 的工具结果回到协调者（按资料处理，不是指令）。
+
+### 支持的 Agent 与驱动
+
+每个 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：表里有同名程序就用它的参数，否则不带参数启动                                                        | —                   |
+
+版本越过已验证区间时仍会启动，但会提示协议可能有变化（Claude 的 stream-json 控制协议不是公开接口，Codex app-server 标为实验）。`/agents` 与 RPC `get_agents` 列出探测结果（只查 PATH 与 `--version`，不联网、不计费；结果缓存在 `<数据目录>/drivers.json`）。
+
+### 在 `task` 里使用
+
+- **名字**：`task(agent="claude")`、`"codex"`、`"acp:<程序>"`（如 `acp:ama`、`acp:gemini`），以及上表的其它 id（`gemini`、`qwen` …；
+  裸 `ama` 不是外部 Agent，ama 自己经 ACP 写 `acp:ama`）；定义文件里 `runner: claude | codex | acp:<程序>` 的类型同样走这里。
+  启动时 PATH 上找得到的 `claude` / `codex` 写进 task 工具描述的类型清单（只查 PATH，不起进程）；其余名字按需解析、不进描述
+  （描述在会话内字节不变，缓存前缀不受影响）。
+- **首次确认**：每个会话第一次以某个外部 Agent 运行时问一次「将以你在该 CLI 的现有登录运行，模式 Y」（`execute` 类）：
+  allow 规则 `task` 或 `task(<id>)`（如 `task(claude)`、`task(acp:*)`）与 `full-auto` 直接放行；deny 规则 `task(<id>)` 拒绝；
+  `allowlist` 与无人值守（`-p`）没有 allow 规则时拒绝；其余交给人（不经 auto 分类器）。同一 Agent 本会话只问一次。
+  宿主注入的 runner 不问（审批由宿主管）。Manual 模式下 `task(agent="claude")` 本来要问两次（task 调用本身一次、首次运行一次），
+  交互界面合并为一次：task 调用的审批框写明「以你在该 CLI 的登录运行（含本会话首次运行确认）」，允许后紧接着的首次运行
+  确认自动通过；中间夹了别的审批、被拒、超过 60 秒或不是这次调用建立的任务时照常弹出（[tui.md](tui.md)「子 Agent」）。
+- **前台 / 后台 / 续聊**：与 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` 与 RPC `get_agents` 列出类型目录与外部 Agent（`installed` / `version`，会话建立时异步探测并缓存）；`/tasks` 查看任务输出、
+  停止任务。界面见 [tui.md](tui.md)「子 Agent」。
+- 外部 Agent 自己报告的提示（预算用尽、超时、模式降级、拒答提问等）在交互界面的消息区显示为一行 `[claude · t3] …`，
+  其它入口只写进诊断日志（`[task tN] …`，没有对应事件）。
+
+### 权限：只交给人
+
+- 外部 Agent 先按它自己的策略判断；它决定要问人的请求才到 ama，到了以后**只走审批通道**（宿主 → 界面 → 无人值守拒绝）。ama 的 auto 分类器与模型都不参与，模型没有回答审批的工具。
+- 对话框标出来源（`[claude · 会话 abc12345]`，三种来源标注见 [permissions.md](permissions.md)「审批对话框的来源标注」）；RPC 的 `permission_request` 带 `context.origin`（Agent、会话、工具标题与种类、路径、选项）与 `context.taskId`（来源任务）。
+- 选项：「允许」→ 允许一次；「本会话允许」→ 交给外部 Agent 自己记住（Codex `acceptForSession`；Claude 只回传它给出的会话范围建议，会写配置文件的建议不替你接受）；「拒绝」→ 拒绝一次。会改外部 CLI 持久配置的选项（Codex execpolicy 修订、永久拒绝）不提供。
+- 无人值守（`-p`、RPC 未声明 approvals）：一律拒绝；Claude 以 `--permission-prompts none` 启动，Codex 用 `approval_policy = never`。
+- 中断、`task_ctl stop`、超时：挂起的请求回「已取消」。
+- 外部 Agent 向你**提问**（Claude `AskUserQuestion`、Codex `requestUserInput`、MCP elicitation）时 ama 不代答：拒绝并请它把问题写进最终回复，界面给出提示。
+
+### 模式：不比 ama 宽
+
+外部 Agent 的模式不得比 ama 当前模式宽；用户级 `agents.<id>.maxMode` 可以显式放宽。父会话在 `plan` 或 `allowlist` 时外部 Agent 只能只读（`allowlist` 也按 `plan`：外部 Agent 的放行规则来自它自己的配置，与 ama 不等价）。
+
+| ama 模式    | Claude Code `--permission-mode`      | Codex `approval_policy` / `sandbox`                        | ACP `session/set_mode`                                   |
+| ----------- | ------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
+| `plan`      | `plan`                               | `never` / `read-only`                                      | `plan`（没有只读模式的 Agent 拒绝启动）                  |
+| `allowlist` | `plan`                               | `never` / `read-only`                                      | `plan`                                                   |
+| `default`   | `manual`（旧版本 `default`）         | `on-request` / `read-only`                                 | 同名模式，没有则用它的缺省模式（需要授权的操作仍交给你） |
+| `auto-edit` | `acceptEdits`                        | `untrusted` / `workspace-write`                            | 同上                                                     |
+| `auto`      | `auto`                               | `on-request` / `workspace-write`                           | 同上                                                     |
+| `full-auto` | `auto`（从不给 `bypassPermissions`） | `never` / `workspace-write`（从不给 `danger-full-access`） | 同上                                                     |
+
+一次性打印模式不能审批，只在只读任务下用。
+
+### 环境与账户
+
+外部 Agent 用你在该 CLI 里的现有登录。为了不把订阅计费切成 API 计费，ama 起子进程时**缺省剥离**：全部内置供应商的 API key 变量、`*_BASE_URL`、`AMA_*`、`CODEX_API_KEY`、`ANTHROPIC_AUTH_TOKEN`，以及 `ARMADRA_*`（`ARMADRA_ASKPASS_*` 除外，见「嵌入宿主」）；其余（PATH、HOME、LANG、代理、SSH、各 CLI 自己的配置目录与令牌）保留。确实要传的用 `agents.<id>.env.passthrough` 列出（`config.json`，只认用户级）：
+
+```json
+{
+  "agents": {
+    "maxConcurrent": 3,
+    "sessionBudgetUsd": 5,
+    "claude": { "maxConcurrent": 2, "model": "sonnet", "env": { "passthrough": ["HTTPS_PROXY"] } },
+    "codex": { "maxMode": "auto-edit" }
+  }
+}
+```
+
+`--bare`（只认 API key）永不使用。
+
+### 信任、并发、预算、记账
+
+- **信任**：只在 ama 已信任的目录里起外部 Agent（`claude -p` 会跳过目录信任对话框并执行项目 hooks 与配置）；未信任时 `task` 报错并提示 `ama trust`。
+- **并发**：外部 Agent 总共 `agents.maxConcurrent`（缺省 3），每个 Agent 另有上限（`agents.<id>.maxConcurrent`，claude 缺省 2）；超出排队，排队可被中断。与 ama 子会话的并发分开计。
+- **预算**：`task` 的 `budgetUsd`（Claude 透传 `--max-budget-usd`，其余按用量累计、超限中断）；`agents.sessionBudgetUsd` 是本会话外部 Agent 的美元总额，用尽后不再启动。Codex 订阅 token、Copilot premium request 按各自单位记，不换算美元；Claude 的 `total_cost_usd` 是它自己的估算。
+- **记账**：每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`（外部 CLI 自己的会话 id，用于续聊）；`/session` 与 `get_session_stats` 的 `external` 段按 Agent 汇总。ama 会话只存最终文本、工具摘要、用量与引用，外部 Agent 的原始事件只在内存里显示，不落盘。
+- **看门狗**：单回合缺省 30 分钟；中断后 15 秒内没有回合结束就关 stdin 再结束进程树；空闲 10 分钟关进程，能续接的下次续聊时以 resume 重开。外部 Agent 进程登记在 `<数据目录>/drivers/pids.json`，ama 异常退出留下的孤儿在下次使用时清理（核对命令行，pid 被复用的不杀）。
+
+### 嵌入宿主
+
+有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。
+
+**在 Armadra 画布终端里直接运行 ama（没有 `--host`）**：此时 ama 按独立模式工作，自己启动的外部 Agent 是这个终端节点里的子进程，不会出现在画布上，也不经连线授权；需要让多个 Agent 在画布上协同，就在画布上连线 Agent 节点，或以宿主模式嵌入 ama。终端带着该节点的身份变量（`ARMADRA_NODE_ID`、`ARMADRA_SESSION_ID`、Hook 端点、`ARMADRA_CANVAS_CONTROL` 等），ama 起子进程时一律剥离（askpass 除外），否则 Armadra 装在 Claude / Codex 上的 Hook 会把子 Agent 的事件记到这个节点名下。
+
+### 本地验证真实 CLI
+
+CI 不跑真实 CLI。本机已登录 `claude` / `codex` 时：
+
+```sh
+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`），都不发起计费请求。

package/docs/codemode.md

@@ -14,17 +14,19 @@
 
 `codemode.mode` 不写时**跟随预设**：
 
-| 预设                      | Node ≥ 25（沙箱隔离网络） | Node 22 / 24                                                           |
-| ------------------------- | ------------------------- | ---------------------------------------------------------------------- |
-| `default`                 | `on`                      | `off`，启动时提示一次（每个配置目录一次，记在数据目录 `notices.json`） |
-| `codemode-only`           | `only`                    | `only`（`execute` 类，见下）                                           |
-| `minimal` / `coordinator` | `off`                     | `off`                                                                  |
+| 预设                      | 网络隔离（Node ≥ 25，或 Node 22 / 24 + 操作系统沙箱） | Node 22 / 24 且没有操作系统沙箱                                        |
+| ------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- |
+| `default`                 | `on`                                                  | `off`，启动时提示一次（每个配置目录一次，记在数据目录 `notices.json`） |
+| `codemode-only`           | `only`                                                | `only`（`execute` 类，见下）                                           |
+| `minimal` / `coordinator` | `off`                                                 | `off`                                                                  |
 
-缺省配置里不写 `codemode.mode`（`ama init` 生成的 `config.json` 也不写），所以这张映射以后调整时老用户同样生效。`ama config show` / `ama doctor` 显示生效模式与原因（跟随哪个预设、Node 是否隔离网络）。
+操作系统沙箱指 macOS 的 `sandbox-exec`、Linux 的 bubblewrap（退而 `unshare -r -n`），见下文沙箱与 [sandbox.md](sandbox.md)；Windows 没有，Node 22 / 24 上行为同右列。
+
+缺省配置里不写 `codemode.mode`（`ama init` 生成的 `config.json` 也不写），所以这张映射以后调整时老用户同样生效。`ama config show` / `ama doctor` 显示生效模式与原因（跟随哪个预设、网络由 Node 还是操作系统沙箱隔离）；`ama doctor` 另列操作系统沙箱能力。
 
 `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限它的活动集（read 与宿主工具）：`tools.bash`、`tools.write` 在脚本里同样不存在，协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
 
-`codemode` 本身的权限类随沙箱能力：网络隔离（Node ≥ 25，见下文沙箱）时是 `read` 类，`default` 权限模式下免审批——脚本只能经 `tools.*` 做事，每次内层调用仍逐个经过权限管线；网络未隔离（Node 22 / 24）时是 `execute` 类，`default` 模式下每次都要审批，`-p` 等无人值守场景直接拒绝，此时常用做法是在配置里放行它：
+`codemode` 本身的权限类随沙箱能力：网络隔离（Node ≥ 25，或有操作系统沙箱，见下文沙箱）时是 `read` 类，`default` 权限模式下免审批——脚本只能经 `tools.*` 做事，每次内层调用仍逐个经过权限管线；网络未隔离（Node 22 / 24 且没有操作系统沙箱）时是 `execute` 类，`default` 模式下每次都要审批，`-p` 等无人值守场景直接拒绝，此时常用做法是在配置里放行它：
 
 ```json
 { "version": 1, "tools": { "preset": "codemode-only" }, "permission": { "allow": ["codemode"] } }
@@ -96,7 +98,8 @@
 - 空环境启动，拿不到密钥、会话文件与环境变量（Windows 上 libuv 会从父进程补入 PATH、SYSTEMROOT、USERPROFILE 等系统变量，不含密钥）；不授予文件写、子进程、worker、addon、inspector 权限；Node 22.0–22.12 用 `--experimental-permission`；嵌入 Electron 时设 `ELECTRON_RUN_AS_NODE=1`。
 - 子进程里用 `node:vm` 建只含 ECMAScript 内建对象的上下文（`codeGeneration: { strings: false, wasm: false }`，沙箱对象空原型）；全局函数都在上下文内定义，只经一个宿主函数交换 JSON 字符串；子进程主 realm 也禁止字符串生成代码，经构造器链逃逸拿不到 `Function("return process")`。
 - `tools.*` 经 stdin / stdout 的 JSON 行协议回调父进程执行。
-- 网络：Node ≥ 25 的权限模型同时拒绝网络（strict）；Node 22 / 24 不管网络，脚本若逃出 `vm` 就能联网——此时工具描述标注 `network not isolated`，`codemode.requireStrict: true` 时直接不注册 `codemode` 并给出 warning（codemode-only 预设随之回退到 default）。
+- 操作系统沙箱（[sandbox.md](sandbox.md)）：探测到可用的 macOS `sandbox-exec` / Linux `bwrap`（退而 `unshare -r -n`）时，上面整条命令行经它启动，内核拒绝网络（含 DNS）与一切写入。探测是启动时跑一次最小探针（嵌套在别的沙箱里、容器里没有用户命名空间都会失败），结果进程内缓存；`sandbox.enabled: "off"`（只认用户级 / profile）或 `AMA_SANDBOX=off` 关闭。
+- 网络：Node ≥ 25 的权限模型同时拒绝网络（strict），操作系统沙箱叠加作纵深防御；Node 22 / 24 的权限模型不管网络，有操作系统沙箱时由它拒绝（strict，子进程必须经它启动，包装不了直接报错）；两者都没有时脚本若逃出 `vm` 就能联网——此时工具描述标注 `network not isolated`、状态栏标 `net!`，`codemode.requireStrict: true` 时直接不注册 `codemode` 并给出 warning（codemode-only 预设随之回退到 default）。
 
 | 实测（`--permission` + 只读入口） | Node 22.19 | Node 24.21 | Node 26.10 |
 | --------------------------------- | ---------- | ---------- | ---------- |
@@ -104,6 +107,7 @@
 | 写文件                            | 拒绝       | 拒绝       | 拒绝       |
 | 起子进程 / worker                 | 拒绝       | 拒绝       | 拒绝       |
 | 联网（fetch / TCP）               | **允许**   | **允许**   | 拒绝       |
+| 联网，经 macOS `sandbox-exec`     | 拒绝       | 拒绝       | 拒绝       |
 
 沙箱防的是脚本**绕过权限管线**，不是对抗性的代码执行环境；脚本能造成的副作用都来自它调用的工具，而工具调用照常受 Hook、权限与审批约束。
 

package/docs/hooks.md

@@ -38,17 +38,19 @@
 
 ## 事件
 
-| 事件               | 时机                                                       | stdout JSON 可改变什么                                                                                                    | 退出码 2                            |
-| ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `SessionStart`     | 会话创建 / 恢复后、首次提示前（`source`）                  | `additionalContext` → 系统提示的 `hooks` 节；`decision: "block"` → 启动失败                                               | 启动失败，退出码 6（换会话时忽略）  |
-| `UserPromptSubmit` | 用户提示展开后、入转录前                                   | `decision: "block"` + `reason` 阻止本次提示；`updatedPrompt` 替换提示；`additionalContext` 作为 custom 消息随提示进上下文 | 阻止，reason 显示给用户             |
-| `PreToolUse`       | schema 校验之后、权限管线之前                              | `decision: "allow" \| "deny" \| "ask"`、`reason`、`updatedInput` 替换工具输入                                             | deny，stderr 作为 reason 进工具结果 |
-| `PostToolUse`      | 工具执行后、结果入转录前                                   | `additionalContext` 追加到工具结果末尾；`decision: "block"` 把结果改为错误                                                | 结果标为错误，stderr 追加进结果     |
-| `Stop`             | 运行将要结束（`agent_before_settle`，没有排队的 followUp） | `decision: "block"` + `reason` → 以 reason 作为新的 user 消息**再跑一轮**（每次运行最多 3 次）                            | 同左                                |
-| `SubagentStop`     | `task` 子会话将要结束                                      | 同 Stop，作用于子会话                                                                                                     | 同左                                |
-| `PreCompact`       | 档二摘要压缩前                                             | `customInstructions` 追加到摘要提示；`decision: "block"` 取消本次压缩                                                     | 取消压缩                            |
-| `Notification`     | 需要用户注意：审批等待、运行结束、错误、重试               | 无（纯通知）                                                                                                              | 忽略                                |
-| `SessionEnd`       | 退出或换会话前（`reason: exit \| new \| switch`）          | 无                                                                                                                        | 忽略                                |
+| 事件               | 时机                                                                      | stdout JSON 可改变什么                                                                                                    | 退出码 2                            |
+| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `SessionStart`     | 会话创建 / 恢复后、首次提示前（`source`）                                 | `additionalContext` → 系统提示的 `hooks` 节；`decision: "block"` → 启动失败                                               | 启动失败，退出码 6（换会话时忽略）  |
+| `UserPromptSubmit` | 用户提示展开后、入转录前                                                  | `decision: "block"` + `reason` 阻止本次提示；`updatedPrompt` 替换提示；`additionalContext` 作为 custom 消息随提示进上下文 | 阻止，reason 显示给用户             |
+| `PreToolUse`       | schema 校验之后、权限管线之前                                             | `decision: "allow" \| "deny" \| "ask"`、`reason`、`updatedInput` 替换工具输入                                             | deny，stderr 作为 reason 进工具结果 |
+| `PostToolUse`      | 工具执行后、结果入转录前                                                  | `additionalContext` 追加到工具结果末尾；`decision: "block"` 把结果改为错误                                                | 结果标为错误，stderr 追加进结果     |
+| `Stop`             | 运行将要结束（`agent_before_settle`，没有排队的 followUp）                | `decision: "block"` + `reason` → 以 reason 作为新的 user 消息**再跑一轮**（每次运行最多 3 次）                            | 同左                                |
+| `SubagentStop`     | `task` 子会话将要结束                                                     | 同 Stop，作用于子会话                                                                                                     | 同左                                |
+| `PreCompact`       | 档二摘要压缩前                                                            | `customInstructions` 追加到摘要提示；`decision: "block"` 取消本次压缩                                                     | 取消压缩                            |
+| `Notification`     | 需要用户注意：审批等待、运行结束、错误、重试                              | 无（纯通知）                                                                                                              | 忽略                                |
+| `SessionEnd`       | 退出或换会话前（`reason: exit \| new \| switch`）                         | 无                                                                                                                        | 忽略                                |
+| `PostRewind`       | 回滚完成后（`/rewind`、RPC `rewind`、SDK `session.rewind()`；预览不触发） | 无（纯通知，不可阻止）                                                                                                    | 忽略                                |
+| `PostCompact`      | 档二摘要压缩写入之后（自动与手动；失败或取消不触发）                      | `additionalContext` 作为 custom 消息（`ama.hook_context`）追加在上下文末尾；不可阻止                                      | 忽略                                |
 
 每个事件只接受上表的决策；`deny` 与 `block` 在两类事件间互换（`UserPromptSubmit` 返回 `deny` 视为 `block`，`PreToolUse` 返回 `block` 视为 `deny`），其它不接受的决策忽略并记 warning。
 
@@ -71,16 +73,18 @@ stdin 是一个 JSON 对象，写完即关闭。所有事件共有：
 
 事件特有：
 
-| 事件                    | 字段                                                                                                  |
-| ----------------------- | ----------------------------------------------------------------------------------------------------- |
-| `SessionStart`          | `source: startup \| resume \| new \| fork`                                                            |
-| `SessionEnd`            | `reason: exit \| new \| switch`                                                                       |
-| `UserPromptSubmit`      | `prompt`                                                                                              |
-| `PreToolUse`            | `toolCallId`、`toolName`、`toolInput`、`viaCodemode?`、`parentToolCallId?`                            |
-| `PostToolUse`           | 同上 + `toolResult: { content, isError }`（content 为文本）                                           |
-| `Stop` / `SubagentStop` | `lastAssistantText`、`stopHookActive`（本次运行已被 Stop Hook 续跑过；处理器应避免再 block 造成循环） |
-| `PreCompact`            | `tokensBefore`、`trigger: auto \| manual`                                                             |
-| `Notification`          | `notification: { kind: approval \| settled \| error \| retry, message }`                              |
+| 事件                    | 字段                                                                                                             |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `SessionStart`          | `source: startup \| resume \| new \| fork`                                                                       |
+| `SessionEnd`            | `reason: exit \| new \| switch`                                                                                  |
+| `UserPromptSubmit`      | `prompt`                                                                                                         |
+| `PreToolUse`            | `toolCallId`、`toolName`、`toolInput`、`viaCodemode?`、`parentToolCallId?`                                       |
+| `PostToolUse`           | 同上 + `toolResult: { content, isError }`（content 为文本）                                                      |
+| `Stop` / `SubagentStop` | `lastAssistantText`、`stopHookActive`（本次运行已被 Stop Hook 续跑过；处理器应避免再 block 造成循环）            |
+| `PreCompact`            | `tokensBefore`、`trigger: auto \| manual`                                                                        |
+| `PostCompact`           | `tokensBefore`、`tokensAfter`（压缩后估算，含摘要与回注块）、`trigger: auto \| manual`                           |
+| `Notification`          | `notification: { kind: approval \| settled \| error \| retry, message }`                                         |
+| `PostRewind`            | `entryId`（回滚到的用户消息）、`mode: both \| conversation \| code`、`files`（被恢复或删除的文件，仅对话时为空） |
 
 **codemode**：脚本里经 `tools.*` 发起的每次调用都单独经过 PreToolUse / PostToolUse，matcher 按**真实工具名**匹配（`bash`，不是 `codemode`），输入多两个字段：`viaCodemode: true` 与 `parentToolCallId`（外层 `codemode` 调用的 id）。`codemode` 调用本身也作为一次工具调用经过两个事件。模型直接发起的调用不带这两个字段。
 
@@ -103,7 +107,7 @@ interface HookOutput {
   reason?: string;
   updatedInput?: unknown; // PreToolUse
   updatedPrompt?: string; // UserPromptSubmit
-  additionalContext?: string; // SessionStart / UserPromptSubmit / PostToolUse
+  additionalContext?: string; // SessionStart / UserPromptSubmit / PostToolUse / PostCompact
   customInstructions?: string; // PreCompact
   continue?: false; // 任何事件：结束当前运行
   suppressOutput?: true;