@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tui.js

@@ -0,0 +1,31 @@
+/**
+ * `@armadra/agent/tui` 子路径：组件库再导出（设计 D1、§12.1）。[B0] 所有。
+ *
+ * B0 只导出组件模型契约；B4 完成组件库后在本文件末尾追加各组件的再导出
+ * （TUI、ProcessTerminal / MemoryTerminal、Container、Text、Markdown、Editor、SelectList、Box、
+ * Spacer、Loader、Overlay、主题与 ansi 工具）——这是 B4 唯一允许改动的 B0 文件。
+ */
+export { CURSOR_MARKER, isFocusable } from "./tui/component.js";
+// ---- B4 组件库再导出 ----
+export { TUI, SYNC_BEGIN, SYNC_END, WRITE_CHUNK_SIZE, MIN_RENDER_INTERVAL_MS, } from "./tui/tui.js";
+export { ProcessTerminal, MemoryTerminal, BRACKETED_PASTE_ON, BRACKETED_PASTE_OFF, SHOW_CURSOR, HIDE_CURSOR, } from "./tui/terminal.js";
+export { VirtualScreen } from "./tui/vt-screen.js";
+export { StdinBuffer, defaultEscTimeout } from "./tui/stdin-buffer.js";
+export { parseKey, matchesKey, normalizeKeyId, isPasteData, unwrapPaste, isPrintableText, PASTE_START, PASTE_END, } from "./tui/keys.js";
+export { visibleWidth, truncateToWidth, sliceByColumn, wrapTextWithAnsi, padToWidth, stripAnsi, codePointWidth, graphemeWidth, SGR_RESET, } from "./tui/ansi.js";
+export { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, } from "./tui/theme.js";
+export { Keybindings, defaultKeybindings, DEFAULT_KEYBINDINGS, parseKeybindings, loadKeybindingsFile, isActionId, } from "./tui/keybindings.js";
+export { Container } from "./tui/components/container.js";
+export { Text, TruncatedText } from "./tui/components/text.js";
+export { Markdown, parseMarkdown, renderInline, renderBlock, } from "./tui/components/markdown.js";
+export { EditorBuffer, } from "./tui/components/editor-buffer.js";
+export { Editor, loadHistoryFile, } from "./tui/components/editor.js";
+export { PasteStore, shouldCollapse, formatMarker, PASTE_LINE_THRESHOLD, PASTE_CHAR_THRESHOLD, } from "./tui/components/editor-paste.js";
+export { SelectList, filterItems, } from "./tui/components/select-list.js";
+export { Box } from "./tui/components/box.js";
+export { Spacer } from "./tui/components/spacer.js";
+export { Loader, LOADER_FRAMES, formatElapsed, } from "./tui/components/loader.js";
+export { compositeOverlays, } from "./tui/components/overlay.js";
+// ---- W3-B9a-2 组件 ----
+export { KeyValue } from "./tui/components/key-value.js";
+export { Meter, METER_FULL, METER_EMPTY } from "./tui/components/meter.js";

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 包版本。[B0] 所有。
+ *
+ * 补全说明：§1.2 没有这个文件，但 `ama --version`、`HostApi.agent.version`、会话头
+ * `agent.version` 都要它。bundle 构建时 esbuild 把 `__AMA_VERSION__` 定义为字面量；
+ * 未打包时（dist/ 或 vitest 跑 src/）从包根的 package.json 读取——两处都在本文件的 `../`。
+ */
+export declare const AMA_VERSION: string;

package/dist/version.js

@@ -0,0 +1,24 @@
+/**
+ * 包版本。[B0] 所有。
+ *
+ * 补全说明：§1.2 没有这个文件，但 `ama --version`、`HostApi.agent.version`、会话头
+ * `agent.version` 都要它。bundle 构建时 esbuild 把 `__AMA_VERSION__` 定义为字面量；
+ * 未打包时（dist/ 或 vitest 跑 src/）从包根的 package.json 读取——两处都在本文件的 `../`。
+ */
+import { readFileSync } from "node:fs";
+function readPackageVersion() {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        const pkg = JSON.parse(raw);
+        if (typeof pkg === "object" && pkg !== null && "version" in pkg) {
+            const { version } = pkg;
+            if (typeof version === "string")
+                return version;
+        }
+    }
+    catch {
+        // 落到下面的兜底值
+    }
+    return "0.0.0-unknown";
+}
+export const AMA_VERSION = typeof __AMA_VERSION__ === "string" ? __AMA_VERSION__ : readPackageVersion();

package/docs/codemode.md

@@ -0,0 +1,102 @@
+# codemode
+
+设计依据见 [design.md](design.md) §5.5、§5.6、§9.1。
+
+`codemode` 工具让模型写一段 JavaScript，在脚本里经 `tools.*` 编排多次工具调用，只有脚本输出回到模型。长流程、工具密集的任务里，它把多次往返合成一次，减少往返次数与缓存读取；短任务收益不明显，因此是可选的调用方式。
+
+## 打开
+
+| 写法                                        | 模型看到的工具                                                                      |
+| ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `--tools-preset codemode`（`only`）         | 只有 `codemode`；全部内置工具与宿主工具只能在脚本里调用，声明列在 `codemode` 描述里 |
+| `--codemode on` / `codemode.mode: "on"`     | 预设的工具 + `codemode`；其它工具描述末尾加一行提示                                 |
+| `--codemode off` / 缺省（非 codemode 预设） | 不注册 `codemode`                                                                   |
+
+`codemode` 本身的权限类随沙箱能力：网络隔离（Node ≥ 25，见下文沙箱）时是 `read` 类，`default` 权限模式下免审批——脚本只能经 `tools.*` 做事，每次内层调用仍逐个经过权限管线；网络未隔离（Node 22 / 24）时是 `execute` 类，`default` 模式下每次都要审批，`-p` 等无人值守场景直接拒绝，此时常用做法是在配置里放行它：
+
+```json
+{ "version": 1, "tools": { "preset": "codemode" }, "permission": { "allow": ["codemode"] } }
+```
+
+其它配置：`codemode.inlineBudget`（描述里内联声明的预算，估算 token，缺省 3000，超出只列名字）、`codemode.requireStrict`（见下文沙箱）。项目级配置只能把 `codemode.mode` 设为 `off`。
+
+## 脚本
+
+输入是原始 JavaScript（不是 JSON，不要代码块），作为 async 函数体执行，可用顶层 `await` 与 `return`。首行可选：
+
+```js
+// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}
+```
+
+- `max_output_tokens`（缺省 10 000，按字符 / 4 估算）：输出超出时保留首尾，全文写 `<会话目录>/outputs/<toolCallId>.txt`（内存会话写系统临时目录）。单条工具结果上限（`tools.maxToolResultChars`，缺省 30 000 字符）更小时以它为准。
+- `timeout_ms`（缺省 300 000，上限 3 600 000）：整个脚本的硬期限，到点杀掉子进程树。
+
+| 全局                           | 作用                                                                              |
+| ------------------------------ | --------------------------------------------------------------------------------- |
+| `tools.<name>(args)`           | 调用会话里任一未禁用的工具（含宿主注册的 `canvas_*`），走与模型直接调用相同的门禁 |
+| `text(v)` / `console.log(...)` | 追加输出；字符串原样，其它值按 JSON（`console.info / warn / error / debug` 相同） |
+| `return v`                     | 同 `text(v)`                                                                      |
+| `store(key, v)` / `load(key)`  | 跨次保留小块 JSON；`store(key, undefined)` 删除                                   |
+| `ALL_TOOLS`                    | 可调用工具名（执行时的清单，含描述冻结之后才注册的宿主工具）                      |
+| `describeTool(name)`           | 单个工具的 TypeScript 声明                                                        |
+
+没有 `require`、`import`、`process`、`fetch`、定时器；`eval` 与 `new Function` 被拒绝。工具只能写成 `tools.read({ path })`，不能直接 `read(...)`。
+
+### 给模型的描述
+
+描述首段写明规则（只有 `tools.<name>(args)`；没有 require / import / process / fetch / 定时器；不要把工具当函数直接调用），随后是一段 6 行示例脚本：`Promise.all` 并发两个 `tools.read`、过滤、`return`。实测 Kimi、MiniMax 在旧描述下会在脚本里写 `require` / `import`，或在 `only` 模式下直接调用 `read`。两类错误都给出正确写法：
+
+- 脚本因 `require` / `import` / `process` / `fetch` / 定时器失败：`Script error` 后追加一行 `Only tools.<name>(args) is available in codemode scripts …`；脚本里直接调用工具名（`read is not defined`）：追加 `Call tools as tools.read({...}), not read(...).`
+- `only` 模式下系统提示的工具行写明 `codemode` 是唯一工具，规则节加一条「read / edit / bash 等不能直接调用，放进脚本里以 `tools.<name>(args)` 调用」。
+- `only` 模式下模型仍绕过 `codemode` 直接调用工具时：错误结果是 `Tool read is only callable inside a codemode script: tools.read({...})`（真不存在的工具仍是 `Tool X not found`）。
+
+### 返回值
+
+- `bash` 解析为 `{ output, truncated, fullOutputPath?, exitCode, wallTimeMs }`，非零退出码同样解析；`output` 是模型可见的版本（2000 行 / 50 KB 尾截断），`fullOutputPath` 存在时可再 `tools.read` 全文。
+- 其它内置工具解析为文本；宿主 / SDK 工具返回 `structured` 时解析为它，否则为文本。
+- 工具失败、被 Hook / 权限 / 用户拒绝、参数非法 → 以 `Error` reject，消息是工具的错误文本；用 `Promise.allSettled` 保留其余结果。
+- 同一脚本内最多 8 个调用同时进行，多出的排队；脚本里不能调用 `codemode`。
+
+### 结果
+
+`Script completed` / `Script failed` + 用时 + 输出；失败时保留已产生的输出，末尾附 `Script error: …`（带脚本行号）。已完成的工具调用不回滚；脚本结束时仍在跑的调用被取消，未 await 的 Promise 被丢弃。
+
+### store
+
+脚本成功结束且写过 store 时，追加一条 `custom{customType:"ama.codemode-store"}` 条目，内容是完整快照；读取取活动分支上最近一条，所以 `/resume` 后值仍在，切分支、fork 后只看本分支写过的值。单值 JSON ≤ 262 144 字符，合计 ≤ 1 048 576 字符；超限时 `store()` 抛 `RangeError`。失败的脚本不提交。
+
+## Hook 与事件
+
+- `codemode` 本身作为一次工具调用经过 PreToolUse、权限与 PostToolUse。
+- 脚本里的每次 `tools.*` 再各自经过完整流程，Hook 按**真实工具名**匹配（`bash`，不是 `codemode`）；Hook 输入多两个字段：`viaCodemode: true` 与 `parentToolCallId`（外层 `codemode` 调用的 id）。
+- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。
+
+## 沙箱
+
+每次执行起一个子进程：
+
+```text
+<node> --permission --allow-fs-read=<ama-sandbox.cjs> --disallow-code-generation-from-strings <ama-sandbox.cjs> --ama-codemode-sandbox
+```
+
+- 空环境启动，拿不到密钥、会话文件与环境变量（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 预设随之回退到 default）。
+
+| 实测（`--permission` + 只读入口） | Node 22.19 | Node 24.21 | Node 26.10 |
+| --------------------------------- | ---------- | ---------- | ---------- |
+| 读其它文件                        | 拒绝       | 拒绝       | 拒绝       |
+| 写文件                            | 拒绝       | 拒绝       | 拒绝       |
+| 起子进程 / worker                 | 拒绝       | 拒绝       | 拒绝       |
+| 联网（fetch / TCP）               | **允许**   | **允许**   | 拒绝       |
+
+沙箱防的是脚本**绕过权限管线**，不是对抗性的代码执行环境；脚本能造成的副作用都来自它调用的工具，而工具调用照常受 Hook、权限与审批约束。
+
+## 缓存
+
+`codemode` 的描述（含工具声明）在第一次读取时确定并冻结，同一会话内字节稳定；之后宿主注册的工具不改变描述（`only` 模式下也不进活动集），但脚本里可以调用，`ALL_TOOLS` / `describeTool` 能查到。
+
+- 脚本里的内层调用不进转录、不进模型上下文，所以一段脚本无论调用多少次工具，前缀都只多一次 `codemode` 调用与它的结果。
+- 一段脚本可能跑几分钟（长测试、批量读写），这正是缓存保温覆盖的场景：保温不区分 codemode，运行期间（`cache.warming: "streaming"`，缺省）在 TTL 到期前重放上一次请求续上缓存，脚本结束后的下一次请求仍按读价计费。保温的前提与经济性见 [providers.md](providers.md)「保温」。
+- `/cache fingerprint` 打印最近一次请求的 system / 工具表哈希；开了 codemode 之后哈希在会话内应保持不变。

package/docs/hooks.md

@@ -0,0 +1,196 @@
+# 命令式 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。
+
+## 配置
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "bash",
+        "hooks": [{ "type": "command", "command": "./scripts/guard.sh", "timeoutMs": 10000 }]
+      },
+      { "matcher": "write|edit", "hooks": [{ "type": "command", "command": "ama-fmt-check" }] }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "edit",
+        "hooks": [{ "type": "command", "command": "prettier --check \"$AMA_FILE\"" }]
+      }
+    ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "./scripts/inject-context.sh" }] }
+    ]
+  }
+}
+```
+
+| 位置                       | 来源      | 说明                                                            |
+| -------------------------- | --------- | --------------------------------------------------------------- |
+| `~/.config/ama/hooks.json` | `user`    | 用户级（`AMA_CONFIG_DIR` 可改配置目录）                         |
+| profile 的 `hooksFile`     | `profile` | 宿主（如 Armadra）提供，视同用户级                              |
+| `<cwd>/.ama/hooks.json`    | `project` | 项目级，**需要信任**；未信任时跳过，`ama doctor` 与启动画面提示 |
+
+三份按「用户 → profile → 项目」**拼接**各事件的数组，不覆盖。文件语法或字段错误（含非法 matcher）→ 启动失败，退出码 3。`config.json` 的 `hooks.timeoutMs` 设缺省超时（缺省 60 000 ms），单条命令的 `timeoutMs` 优先，上限 600 000 ms。`/hooks` 与 `ama doctor` 列出已加载的 Hook 及来源。SDK 的 `createAgentSession({ hooks })` 直接传 `HookConfig`，缺省不读文件系统里的 hooks.json。
+
+## 事件
+
+| 事件               | 时机                                                       | 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`）          | 无                                                                                                                        | 忽略                                |
+
+每个事件只接受上表的决策；`deny` 与 `block` 在两类事件间互换（`UserPromptSubmit` 返回 `deny` 视为 `block`，`PreToolUse` 返回 `block` 视为 `deny`），其它不接受的决策忽略并记 warning。
+
+任何事件的 stdout 都可以带 `"continue": false`：请求结束当前运行（reason 显示给用户）。`"suppressOutput": true` 被接受并合并，但当前界面本来就不显示 Hook 的 stdout，暂无可见效果。
+
+## 输入（stdin）
+
+stdin 是一个 JSON 对象，写完即关闭。所有事件共有：
+
+| 字段             | 说明                                           |
+| ---------------- | ---------------------------------------------- |
+| `hookEventName`  | 事件名                                         |
+| `sessionId`      | 会话 id（子会话为子会话自己的）                |
+| `sessionFile`    | 会话文件（落盘前缺省）                         |
+| `cwd`            | 会话 cwd                                       |
+| `model`          | `{ provider, id }`                             |
+| `permissionMode` | `plan` / `default` / `auto-edit` / `full-auto` |
+| `depth`          | 主会话 0，`task` 子会话 1                      |
+| `host`           | 宿主适配器 id（激活时）                        |
+
+事件特有：
+
+| 事件                    | 字段                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `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 }`                              |
+
+**codemode**：脚本里经 `tools.*` 发起的每次调用都单独经过 PreToolUse / PostToolUse，matcher 按**真实工具名**匹配（`bash`，不是 `codemode`），输入多两个字段：`viaCodemode: true` 与 `parentToolCallId`（外层 `codemode` 调用的 id）。`codemode` 调用本身也作为一次工具调用经过两个事件。模型直接发起的调用不带这两个字段。
+
+环境变量（便于 shell 脚本）：`AMA_HOOK_EVENT`、`AMA_SESSION_ID`、`AMA_CWD`，工具事件另有 `AMA_TOOL_NAME`，`read` / `write` / `edit` 另有 `AMA_FILE`（目标路径）。
+
+## 输出（退出码与 stdout）
+
+| 退出码                | 含义                                                                     |
+| --------------------- | ------------------------------------------------------------------------ |
+| `0`                   | 放行；stdout 若是 JSON 对象则解析（空或非 JSON = 无决策）                |
+| `2`                   | 阻止：按上表「退出码 2」列处理，stderr 文本作为 reason；stdout 不再解析  |
+| 其它非零 / 被信号杀死 | Hook 自身错误，**不阻塞**：记 warning（附 stderr 末 3 行），按无决策继续 |
+| 超时                  | 同非阻塞错误；**但 PreToolUse 超时按 deny**（fail-safe）                 |
+
+stdout JSON：
+
+```ts
+interface HookOutput {
+  decision?: "allow" | "deny" | "ask" | "block";
+  reason?: string;
+  updatedInput?: unknown; // PreToolUse
+  updatedPrompt?: string; // UserPromptSubmit
+  additionalContext?: string; // SessionStart / UserPromptSubmit / PostToolUse
+  customInstructions?: string; // PreCompact
+  continue?: false; // 任何事件：结束当前运行
+  suppressOutput?: true;
+}
+```
+
+字段类型不对的丢弃并记 warning。stdout / stderr 各最多收集 1 MiB。
+
+## 合并与顺序
+
+同一事件下所有匹配的 Hook **并行**启动，全部结束后按配置顺序合并：
+
+- 决策取最严：`deny > block > ask > allow`；reason 取决定性那条 Hook 的。
+- `updatedInput` / `updatedPrompt` 只在**恰好一个** Hook 返回时采用；多个则全部忽略并 warning。
+- `additionalContext` / `customInstructions` 按配置顺序拼接。
+- 任一 Hook 返回 `continue: false` 即请求结束运行。
+
+一次工具调用的完整顺序（[design.md](design.md) §6.3）：
+
+```text
+模型产出工具调用
+  1. schema 校验（失败 → 错误结果，不再往下）
+  2. PreToolUse Hook（并行，合并为 allow / ask / deny / 无；updatedInput 替换输入）
+  3. 权限管线：① deny 规则或 Hook deny → deny
+               ② 危险命令识别（bash）→ ask（无人值守时 deny）
+               ③ 权限模式决定 ask / allow
+               ④ allow 规则或 Hook allow 把 ③ 的 ask 变 allow（不能越过 ①②）；Hook ask 把 allow 变 ask
+  4. 结果为 ask → 审批链：宿主 broker → 界面对话框 / RPC 客户端 → 无人作答 deny；超时 10 分钟 deny
+  5. 执行工具
+  6. PostToolUse Hook（追加上下文 / 改为错误）→ 结果入转录
+```
+
+Hook 在权限管线之前，是因为它是用户策略（可以改输入、可以否决）；Hook 的 allow 只能免去模式带来的审批，不能放宽 deny 规则与危险命令识别。
+
+## matcher
+
+只对 `PreToolUse` / `PostToolUse` 生效，其它事件忽略 matcher。
+
+| 写法              | 匹配                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------- |
+| 缺省、`""`、`*`   | 全部工具                                                                                              |
+| `bash`            | 精确匹配工具名                                                                                        |
+| `write\|edit`     | 多选（括号外的 `\|` 分隔）                                                                            |
+| `canvas_*`        | glob：`*` 任意字符串、`?` 单个字符                                                                    |
+| `bash(git push*)` | 先匹配工具名，再对参数文本做 glob：bash 是 `command`，文件类工具是 `path`，其它工具是输入的 JSON 文本 |
+| `/regex/flags`    | 对工具名做正则                                                                                        |
+
+## 运行环境
+
+- POSIX：`/bin/sh -c <command>`，独立进程组；超时或运行被中断时向整组发 SIGTERM，1 秒后 SIGKILL。
+- Windows：Git Bash（`AMA_HOOK_SHELL` 指定，或常见安装位置）；找不到时 `cmd /d /s /c`。
+- cwd 为会话 cwd；Hook 以 ama 进程的权限运行，继承环境变量。
+
+## 信任
+
+- 用户级与 profile 的 Hook 总是加载。项目级 `.ama/hooks.json`（与 `.ama/skills/`、`.ama/prompts/`、祖先 `.agents/skills/`）在目录被**信任**之前不加载。
+- 信任的粒度是目录（含子目录），记在 `~/.config/ama/trust.json`。决策顺序：`--trust` / `--no-trust` → `trust.json` 里最近祖先的记录 → 交互模式询问一次（可记住）→ 非交互模式缺省不信任。宿主 profile 可设 `trustProject: true`。
+- 信任一个仓库 = 允许它的 Hook 以你的身份执行命令。信任不会放开权限：项目级 `config.json` 仍只能收紧规则。
+
+## 事件观察
+
+每条 Hook 结束后发 `hook_executed{event, command, exitCode, durationMs}`（RPC 事件与宿主事件都有），超时或被信号杀死时 `exitCode` 为 null。
+
+## 示例
+
+阻止推送到 main：
+
+```sh
+#!/bin/sh
+# .ama/guard.sh；hooks.json：{"matcher":"bash(git push*)","hooks":[{"type":"command","command":"./.ama/guard.sh"}]}
+input=$(cat)
+case "$input" in
+  *'main'*) echo "不要直接推送 main，请开分支" >&2; exit 2 ;;
+esac
+exit 0
+```
+
+编辑后跑格式检查，把结果交给模型：
+
+```json
+{
+  "matcher": "edit|write",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "prettier --check \"$AMA_FILE\" >/dev/null 2>&1 || echo '{\"additionalContext\":\"prettier 检查失败，请修正格式\"}'"
+    }
+  ]
+}
+```

package/docs/host-api.md

@@ -0,0 +1,161 @@
+# 宿主适配器 API（@armadra/agent/host）
+
+宿主适配器是一个本地 JS 模块，ama 启动时加载它并交给它一个 `HostApi`：它可以注册工具、追加系统提示、观察事件、回答审批、注入用户消息、在界面上显示通知与状态。Armadra 画布就是以宿主适配器的形式接入的（画布工具 `canvas_*` / `context_*` 都由适配器注册）。类型定义在 `src/host/types.ts`，从 `@armadra/agent/host` 导出，`HOST_API_VERSION = 1`。设计依据见 [design.md](design.md) §6.2、§6.3、§11.1 第 13 步。
+
+## 模块形状
+
+```js
+// my-host.mjs
+export const hostApi = 1;
+export function create(api) {
+  if (!api.env.MY_HOST_ENABLED) return undefined; // 不激活：ama 退化为普通独立模式
+  api.tools.register({
+    name: "my_lookup",
+    description: "Look up a ticket by id.",
+    parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    permission: "read",
+    async execute(input) {
+      return { content: `ticket ${input.id}: …` };
+    },
+  });
+  api.instructions.add({
+    kind: "text",
+    name: "my-host",
+    text: "Tickets live in the tracker; use my_lookup.",
+  });
+  api.events.on("agent_settled", () => api.ui.setStatus("my-host", "idle"));
+  return { id: "my-host", dispose() {} };
+}
+```
+
+- 导出 `hostApi`（必须等于 `HOST_API_VERSION`）与 `create(api)`；也可以放在默认导出（ESM `export default { hostApi, create }` 或 CJS `module.exports = { hostApi, create }`）。
+- `create` 返回 `HostAdapter`（`{ id: string, dispose?() }`，`id` 非空）激活；返回 `undefined` 表示本次不激活。可以是 async。
+- `dispose()` 在退出时调用（`session_shutdown` 事件之后），幂等。
+
+## 加载
+
+- 来源：`--host <模块>` 或 profile 的 `host`（命令行优先）；相对路径按 cwd 解析。
+- `.mjs` 用动态 `import()`；`.cjs` 用 `require`；`.js` 先 `require`，遇到 ESM（`ERR_REQUIRE_ESM` 等）再 `import()`。单文件发行版 `ama.cjs` 里同样能加载 ESM 适配器。
+- 时机：启动序列第 13 步——配置、资源、模型与工具注册表就绪之后，组装会话之前。`create()` 里注册的工具与指令进入首个请求的系统提示与工具表，前缀从第一个请求起就稳定。
+- 失败：
+
+| 情形                                          | 退出码 |
+| --------------------------------------------- | ------ |
+| 文件不存在、加载抛错、缺 `hostApi` / `create` | 6      |
+| `hostApi` 不等于 `HOST_API_VERSION`           | 78     |
+| `create()` 抛错或 10 秒内未返回               | 6      |
+| 返回的适配器缺 `id`                           | 6      |
+
+## HostApi
+
+| 成员                                            | 说明                                                                                                                                          |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                       | `HOST_API_VERSION`                                                                                                                            |
+| `agent`                                         | `{ name: "ama", version }`                                                                                                                    |
+| `env`                                           | 启动时环境变量的冻结副本                                                                                                                      |
+| `mode`                                          | `interactive` / `line` / `print` / `rpc`                                                                                                      |
+| `session.id()` / `file()` / `cwd()` / `model()` | 当前会话（换会话后跟随新会话）；`file()` 在首次请求落盘前为 `undefined`                                                                       |
+| `tools.register(tool)`                          | 注册工具（形状见下）；名字须匹配 `^[a-z][a-z0-9_]{1,63}$`，同名已存在抛 `tool_exists`。建议加前缀（`canvas_*`）                               |
+| `tools.disable(name)`                           | 隐藏内置工具（如 Armadra 禁用 `task`），系统提示的工具节随之不再列它                                                                          |
+| `tools.list()`                                  | 当前全部工具名                                                                                                                                |
+| `instructions.add(source)`                      | 追加到系统提示最后的 `host` 节；`{ kind: "file", path }` 或 `{ kind: "text", text, name? }`                                                   |
+| `events.on(name, handler)`                      | 观察事件（下表），返回注销函数                                                                                                                |
+| `approvals.setBroker(broker)`                   | 设置审批回答者（见「审批」）                                                                                                                  |
+| `messages.sendUser(text, origin?)`              | 以 user 消息注入：空闲时开始一次运行（`"started"`），运行中按 steer 入队（`"queued"`）；`origin` 缺省 `"host"`，落盘在消息上，界面标 `↳ host` |
+| `ui.notify(message, level?)`                    | 交互 / line 模式进消息区；rpc 模式变成 `notification` 事件（stderr 另有一份）；print 模式写 stderr                                            |
+| `ui.setStatus(key, text?)`                      | 状态栏的宿主项；`text` 为空或缺省则移除该键                                                                                                   |
+| `log(level, message, detail?)`                  | 日志；`warn` / `error` 写 stderr                                                                                                              |
+| `cache?.onWarmingDecision(handler)`             | 缓存保温的否决钩子（见「缓存保温」）；可选面，旧版本运行时没有它，用前判断 `api.cache !== undefined`                                          |
+
+`create()` 期间会话还没组装完：`session.*` 返回启动时确定的值，`sendUser` 会以 `busy` 拒绝——要在启动时发消息，等 `session_start` 事件之后再调用。
+
+### 工具定义
+
+```ts
+interface ToolDefinition<I = unknown> {
+  name: string;
+  label?: string; // TUI 标题
+  description: string;
+  parameters: JsonSchema;
+  permission: "read" | "write" | "execute"; // 权限管线的分类
+  executionMode?: "sequential" | "parallel"; // 缺省 read 并行、其余串行
+  annotations?: { readOnly?: boolean; destructive?: boolean; openWorld?: boolean };
+  promptSnippet?: string; // 系统提示 tools 节一行
+  promptGuidelines?: string[]; // 系统提示 rules 节
+  execute(input: I, ctx: ToolContext): Promise<ToolResult>;
+  renderCall?(input: I, width: number): string[];
+  renderResult?(result: ToolResult, width: number, expanded: boolean): string[];
+}
+interface ToolResult {
+  content: string | ContentBlock[];
+  isError?: boolean;
+  details?: unknown; // 落盘，不进上下文
+  structured?: unknown; // codemode 脚本里 tools.<name>() 的返回值
+  terminate?: boolean; // 整批结果都为 true 才提前结束本次运行
+}
+```
+
+`ToolContext` 提供 `toolCallId`、`cwd`、`sessionId`、`sessionFile?`、`signal`、`depth`、`model?`、`thinkingLevel?`、`outputDir?`、`onUpdate(partial)`（运行中输出）、`readFiles` / `markRead`、`tools.executeTool(name, input)`（嵌套调用，受同一管线）、`session.appendCustom` / `lastCustom`（不进上下文的 custom 条目，见 [session-format.md](session-format.md)）、`spawnSubagent?`、`log`。
+
+宿主工具与内置工具走同一条路径：schema 校验 → 命令式 Hook PreToolUse → 权限管线（按 `permission` 分类）→ 审批 → 执行 → PostToolUse。在 codemode 脚本里也能以 `tools.<name>()` 调用。
+
+## 事件
+
+`events.on` 的处理器只观察：抛错只记日志，不影响运行；处理器依次调用并等待，`session_shutdown` 被 await（退出前可以做清理）。
+
+| 事件                                                              | 载荷                                                                           | 来源                                        |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
+| `session_start`                                                   | `sessionId`、`sessionFile?`、`cwd`、`reason: startup \| resume \| new \| fork` | 启动与换会话                                |
+| `before_agent_start`                                              | `prompt`                                                                       | 用户提示展开后、运行开始前                  |
+| `agent_start` / `turn_start` / `turn_end` / `agent_before_settle` | `{}`                                                                           | 运行与回合                                  |
+| `agent_end`                                                       | `stopReason`、`willRetry`                                                      |                                             |
+| `agent_settled`                                                   | `warning?`                                                                     | 运行彻底结束                                |
+| `tool_call`                                                       | `toolCallId`、`toolName`、`input`                                              | 工具开始执行（已通过权限）                  |
+| `tool_result`                                                     | `toolCallId`、`toolName`、`isError`                                            | 工具执行结束                                |
+| `tool_approval_requested`                                         | `requestId`、`toolName`                                                        | 需要审批                                    |
+| `tool_approval_resolved`                                          | `requestId`、`decision`                                                        | 审批结论                                    |
+| `session_compact`                                                 | `tokensBefore`                                                                 | 压缩成功                                    |
+| `model_select`                                                    | `model: { provider, id }`                                                      | 切换模型                                    |
+| `hook_executed`                                                   | `event`、`command`、`exitCode`、`durationMs`                                   | 每条命令式 Hook 结束                        |
+| `cache_miss`                                                      | `missedTokens`、`missedCost?`、`reason`、`detail?`、`idleMs`                   | 一次缓存未命中（含低于界面门槛的）          |
+| `context_pressure`                                                | `percent`、`threshold: 70 \| 90`、`remainingTokens?`、`estimatedTurnsLeft?`    | 上下文占用跨过 70% / 90%                    |
+| `session_shutdown`                                                | `{}`                                                                           | 退出前（之后跑 SessionEnd Hook、`dispose`） |
+
+需要逐 token 的流式内容或完整事件流时用 RPC 或 SDK 的 `subscribe`，宿主事件是精简过的。
+
+## 审批
+
+`approvals.setBroker({ ask(request, signal) })`：工具调用需要确认时，审批链依次问**宿主 broker → UI（TUI 对话框 / RPC 客户端 / SDK 回调）→ 无人作答 deny**。
+
+- `ask` 返回 `"allow"` / `"deny"` / `"allow_session"` 作答；返回 `undefined` 交给下一个回答者；抛错按 deny。
+- `request`：`requestId`、`toolName`、`input`、`reason: "mode" | "dangerous" | "hook"`、`hookReason?`、`preview?`（执行前预览，见 [rpc.md](rpc.md)「审批」）、`context?`（`depth > 0` 表示来自 `task` 子 Agent；codemode 内层调用带 `parentToolCallId`）。
+- 超时（缺省 10 分钟，`AMA_APPROVAL_TIMEOUT_MS`）或运行被中断时 `signal` abort，结论为 deny。审批串行，同一时刻只有一个请求在等。
+- 时机：broker 每次审批时现取，可以在 `create()` 里设，也可以之后任何时候设或替换；最后一次 `setBroker` 生效。
+- 宿主 broker 只决定「谁来回答 ask」，不能放宽 deny 规则、命令式 Hook 的 deny 与危险命令识别（[design.md](design.md) §6.3）。
+
+## 缓存保温
+
+`api.cache.onWarmingDecision(handler)` 在每次缓存保温请求前以内置决策调用 `handler(decision)`：
+
+```ts
+interface WarmDecision {
+  action: "warm" | "stop"; // 内置决策
+  phase: "streaming" | "idle";
+  promptTokens: number; // 上一次真实请求的 input + cacheRead + cacheWrite
+  warmCost: number | undefined; // 一次保温的花费（美元）
+  missCost: number | undefined; // 不保温而失效时多付的金额
+  probability: number; // 失效后仍会再发请求的概率：streaming 1、idle 0.15
+  reason?: string; // stop 的原因
+}
+```
+
+返回 `"warm"` / `"stop"`（可以是 Promise）。返回 `"stop"` 即不发并停止本轮保温（内置决策本是 warm 时，停止原因记为 `declined`）；返回 `"warm"` 可以覆盖内置的 stop。处理器出错回落内置决策。注册多个时最后注册且未注销的那个生效；返回值是注销函数。保温机制本身见 [providers.md](providers.md)「缓存」。
+
+## 退出
+
+- 进程退出：`session_shutdown` 事件（await）→ SessionEnd Hook（`reason: "exit"`）→ `adapter.dispose()` → 会话 dispose。`dispose` 抛错只记 warning。
+- `/new`、`/resume`、`/fork` 与 RPC 换会话：适配器保持激活，不发 `session_shutdown`；顺序是 SessionEnd Hook（`new` / `switch`）→ 旧会话 dispose → 新会话的 `session_start` → SessionStart Hook。`api.session.*` 随之指向新会话。
+
+## 嵌入 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)。