@armadra/agent 0.2.1 → 0.4.0

package/dist/tui/theme.js

@@ -1,15 +1,20 @@
 /**
  * 主题与颜色能力（设计 §12.7）。[B4]
  *
- * - `dark` / `light` 两套语义色（§12.7 的 11 个名字），以 24 位 RGB 定义。
- * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（xterm 缺省调色板取近）→ 无色。
+ * - `dark` / `light` 两套语义色（14 个名字，终端界面视觉设计 v1 §2.1），以 24 位 RGB 定义；取值都落在
+ *   xterm 256 色立方 / 灰阶上，所以 256 色回退无损。
+ * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（内置色板按 `THEME_ANSI16` 查表，
+ *   覆盖色按 xterm 缺省调色板取近）→ 无色。
+ * - `bg("selection")` 在 < 256 色时退化为 `accent` 粗体前景（16 色下底色太跳，且常留「尾巴」）。
  * - `NO_COLOR`（非空）或 `TERM=dumb` → 无色；不探测终端背景（不发查询序列）。
  * - 样式用各自的关闭码（39 / 49 / 22 / 23 / 24）而不是全重置，可以嵌套。
  */
+import { detectAscii, glyphsFor } from "./glyphs.js";
 export const THEME_PALETTES = {
     dark: {
         text: "#e4e4e4",
-        dim: "#808080",
+        muted: "#a8a8a8",
+        dim: "#6c6c6c",
         accent: "#5fafff",
         success: "#5fd787",
         warning: "#ffd75f",
@@ -17,12 +22,15 @@ export const THEME_PALETTES = {
         user: "#87afff",
         assistant: "#e4e4e4",
         tool: "#af87ff",
-        border: "#5f5f5f",
+        border: "#585858",
         code: "#ffaf5f",
+        link: "#87d7ff",
+        selection: "#303030",
     },
     light: {
         text: "#1c1c1c",
-        dim: "#6c6c6c",
+        muted: "#585858",
+        dim: "#8a8a8a",
         accent: "#005fd7",
         success: "#008700",
         warning: "#af5f00",
@@ -30,10 +38,73 @@ export const THEME_PALETTES = {
         user: "#005faf",
         assistant: "#1c1c1c",
         tool: "#8700af",
-        border: "#a8a8a8",
+        border: "#bcbcbc",
         code: "#875f00",
+        link: "#0087af",
+        selection: "#e4e4e4",
+    },
+};
+/**
+ * 16 色下的索引（xterm 0–15）。距离取近对饱和色不可靠（`#ff5f5f` 会落到灰 8），所以内置色板查表；
+ * `selection` 在 16 色下不作 bg，表里给前景兜底值。
+ */
+export const THEME_ANSI16 = {
+    dark: {
+        text: 7,
+        muted: 7,
+        dim: 8,
+        accent: 12,
+        success: 10,
+        warning: 11,
+        error: 9,
+        user: 12,
+        assistant: 7,
+        tool: 13,
+        border: 8,
+        code: 11,
+        link: 14,
+        selection: 8,
+    },
+    light: {
+        text: 0,
+        muted: 8,
+        dim: 8,
+        accent: 4,
+        success: 2,
+        warning: 3,
+        error: 1,
+        user: 4,
+        assistant: 0,
+        tool: 5,
+        border: 7,
+        code: 3,
+        link: 6,
+        selection: 7,
     },
 };
+/** 阈值档位：≥ dangerAt error，≥ warnAt warning，否则 success（状态栏 ctx、Meter、/session 共用）。 */
+export function levelColor(ratio, thresholds = {}) {
+    if (ratio >= (thresholds.dangerAt ?? 0.9))
+        return "error";
+    if (ratio >= (thresholds.warnAt ?? 0.7))
+        return "warning";
+    return "success";
+}
+/**
+ * `auto` → dark / light：不发查询序列，只看环境。`COLORFGBG` 的最后一段是背景色号（0–6、8 暗，
+ * 7、9–15 亮）；没有时 Apple Terminal 按 dark；其余缺省 dark。只是猜，文档建议显式配置。
+ */
+export function resolveThemeName(name, env = process.env) {
+    if (name === "dark" || name === "light")
+        return name;
+    const colorfgbg = env["COLORFGBG"];
+    if (colorfgbg !== undefined && colorfgbg !== "") {
+        const bg = Number(colorfgbg.split(";").at(-1));
+        if (Number.isInteger(bg) && bg >= 0 && bg <= 15)
+            return bg === 7 || bg >= 9 ? "light" : "dark";
+    }
+    return "dark";
+}
 /** 由环境推断颜色深度。 */
 export function detectColorDepth(env = process.env, isTTY = process.stdout.isTTY === true) {
     if (env["NO_COLOR"] !== undefined && env["NO_COLOR"] !== "")
@@ -116,8 +187,10 @@ export function rgbTo16(rgb) {
     }
     return best;
 }
-/** 生成前景 / 背景开启序列；depth 0 返回空串。 */
-export function colorCode(hex, depth, background) {
+/**
+ * 生成前景 / 背景开启序列；depth 0 返回空串。`ansi16` 给定时 16 色下直接用它（内置色板查表）。
+ */
+export function colorCode(hex, depth, background, ansi16) {
     if (depth === 0)
         return "";
     const rgb = parseHex(hex);
@@ -125,23 +198,25 @@ export function colorCode(hex, depth, background) {
         return `\x1b[${background ? 48 : 38};2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
     if (depth === 256)
         return `\x1b[${background ? 48 : 38};5;${rgbTo256(rgb)}m`;
-    const idx = rgbTo16(rgb);
+    const idx = ansi16 ?? rgbTo16(rgb);
     const base = idx < 8 ? (background ? 40 : 30) + idx : (background ? 100 : 90) + idx - 8;
     return `\x1b[${base}m`;
 }
 class PaletteTheme {
     name;
     caps;
+    glyphs;
     fgCodes;
     bgCodes;
-    constructor(name, palette, caps) {
+    constructor(name, palette, caps, glyphs, ansi16 = {}) {
         this.name = name;
         this.caps = caps;
+        this.glyphs = glyphs;
         const fg = {};
         const bg = {};
         for (const key of Object.keys(palette)) {
-            fg[key] = colorCode(palette[key], caps.colors, false);
-            bg[key] = colorCode(palette[key], caps.colors, true);
+            fg[key] = colorCode(palette[key], caps.colors, false, ansi16[key]);
+            bg[key] = colorCode(palette[key], caps.colors, true, ansi16[key]);
         }
         this.fgCodes = fg;
         this.bgCodes = bg;
@@ -151,6 +226,8 @@ class PaletteTheme {
         return code === "" ? text : `${code}${text}\x1b[39m`;
     }
     bg(color, text) {
+        if (color === "selection" && this.caps.colors < 256)
+            return this.bold(this.fg("accent", text));
         const code = this.bgCodes[color];
         return code === "" ? text : `${code}${text}\x1b[49m`;
     }
@@ -168,16 +245,25 @@ class PaletteTheme {
     }
 }
 export function createTheme(name = "dark", options = {}) {
-    const palette = { ...THEME_PALETTES[name], ...options.overrides };
-    return new PaletteTheme(name, palette, options.caps ?? detectCapabilities());
+    const overrides = options.overrides ?? {};
+    const palette = { ...THEME_PALETTES[name], ...overrides };
+    const ansi16 = { ...THEME_ANSI16[name] };
+    for (const key of Object.keys(overrides))
+        delete ansi16[key];
+    const glyphs = glyphsFor(options.ascii ?? detectAscii());
+    return new PaletteTheme(name, palette, options.caps ?? detectCapabilities(), glyphs, ansi16);
 }
-/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本。 */
-export function plainTheme() {
-    return new PlainTheme();
+/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本；字形缺省 Unicode。 */
+export function plainTheme(options = {}) {
+    return new PlainTheme(glyphsFor(options.ascii === true));
 }
 class PlainTheme {
+    glyphs;
     name = "plain";
     caps = { colors: 0 };
+    constructor(glyphs) {
+        this.glyphs = glyphs;
+    }
     fg(_color, text) {
         return text;
     }

package/dist/tui.d.ts

@@ -13,7 +13,8 @@ export { VirtualScreen, type ScreenModes } from "./tui/vt-screen.js";
 export { StdinBuffer, defaultEscTimeout, type StdinBufferOptions } from "./tui/stdin-buffer.js";
 export { parseKey, matchesKey, normalizeKeyId, isPasteData, unwrapPaste, isPrintableText, PASTE_START, PASTE_END, type KeyEvent, } 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, type ThemeName, type CreateThemeOptions, } from "./tui/theme.js";
+export { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, THEME_ANSI16, resolveThemeName, levelColor, type ThemeName, type CreateThemeOptions, } from "./tui/theme.js";
+export { UNICODE_GLYPHS, ASCII_GLYPHS, detectAscii, resolveAscii, glyphsFor, } from "./tui/glyphs.js";
 export { Keybindings, defaultKeybindings, DEFAULT_KEYBINDINGS, parseKeybindings, loadKeybindingsFile, isActionId, type ActionId, type KeybindingOverrides, type ParsedKeybindings, } from "./tui/keybindings.js";
 export { Container } from "./tui/components/container.js";
 export { Text, TruncatedText, type TextOptions } from "./tui/components/text.js";
@@ -23,8 +24,9 @@ export { Editor, loadHistoryFile, type EditorOptions, type AutocompleteProvider,
 export { PasteStore, shouldCollapse, formatMarker, PASTE_LINE_THRESHOLD, PASTE_CHAR_THRESHOLD, } from "./tui/components/editor-paste.js";
 export { SelectList, filterItems, type SelectItem, type SelectListOptions, } from "./tui/components/select-list.js";
 export { Box, type BoxOptions } from "./tui/components/box.js";
+export { Card, type CardOptions } from "./tui/components/card.js";
 export { Spacer } from "./tui/components/spacer.js";
-export { Loader, LOADER_FRAMES, formatElapsed, type LoaderOptions, } from "./tui/components/loader.js";
+export { Loader, LOADER_FRAMES, formatElapsed, type LoaderOptions, type LoaderVerbOptions, } from "./tui/components/loader.js";
 export { compositeOverlays, type OverlayAnchor, type OverlayOptions, type OverlayLayer, } from "./tui/components/overlay.js";
 export { KeyValue, type KeyValueRow, type KeyValueOptions } from "./tui/components/key-value.js";
 export { Meter, METER_FULL, METER_EMPTY, type MeterOptions } from "./tui/components/meter.js";

package/dist/tui.js

@@ -13,7 +13,8 @@ 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 { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, THEME_ANSI16, resolveThemeName, levelColor, } from "./tui/theme.js";
+export { UNICODE_GLYPHS, ASCII_GLYPHS, detectAscii, resolveAscii, glyphsFor, } from "./tui/glyphs.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";
@@ -23,6 +24,7 @@ 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 { Card } from "./tui/components/card.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";

package/docs/codemode.md

@@ -2,23 +2,37 @@
 
 设计依据见 [design.md](design.md) §5.5、§5.6、§9.1。
 
-`codemode` 工具让模型写一段 JavaScript，在脚本里经 `tools.*` 编排多次工具调用，只有脚本输出回到模型。长流程、工具密集的任务里，它把多次往返合成一次，减少往返次数与缓存读取；短任务收益不明显，因此是可选的调用方式。
+`codemode` 工具让模型写一段 JavaScript，在脚本里经 `tools.*` 编排多次工具调用，只有脚本输出回到模型。长流程、工具密集的任务里，它把多次往返合成一次，减少往返次数与缓存读取；短任务里模型照常直接调用工具，codemode 只多占约 400 token 前缀，所以 `default` 预设在网络隔离的运行时上缺省开着它。
 
 ## 打开
 
-| 写法                                        | 模型看到的工具                                                                      |
-| ------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `--tools-preset codemode`（`only`）         | 只有 `codemode`；全部内置工具与宿主工具只能在脚本里调用，声明列在 `codemode` 描述里 |
-| `--codemode on` / `codemode.mode: "on"`     | 预设的工具 + `codemode`；其它工具描述末尾加一行提示                                 |
-| `--codemode off` / 缺省（非 codemode 预设） | 不注册 `codemode`                                                                   |
+| 写法                                                             | 模型看到的工具                                                                                                             |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `--tools-preset codemode-only`（`only`；旧名 `codemode` 仍可用） | 只有 `codemode`；全部内置工具与宿主工具只能在脚本里调用，声明列在 `codemode` 描述里                                        |
+| `--codemode on` / `codemode.mode: "on"`                          | 预设的工具 + `codemode`；其它工具描述不变，`codemode` 描述一行列出可在脚本里调用的直接工具（参数相同）与仅脚本可调的工具名 |
+| `--codemode off` / `codemode.mode: "off"`                        | 不注册 `codemode`                                                                                                          |
+
+`codemode.mode` 不写时**跟随预设**：
+
+| 预设                      | Node ≥ 25（沙箱隔离网络） | 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 是否隔离网络）。
+
+`coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限它的活动集（read 与宿主工具）：`tools.bash`、`tools.write` 在脚本里同样不存在，协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
 
 `codemode` 本身的权限类随沙箱能力：网络隔离（Node ≥ 25，见下文沙箱）时是 `read` 类，`default` 权限模式下免审批——脚本只能经 `tools.*` 做事，每次内层调用仍逐个经过权限管线；网络未隔离（Node 22 / 24）时是 `execute` 类，`default` 模式下每次都要审批，`-p` 等无人值守场景直接拒绝，此时常用做法是在配置里放行它：
 
 ```json
-{ "version": 1, "tools": { "preset": "codemode" }, "permission": { "allow": ["codemode"] } }
+{ "version": 1, "tools": { "preset": "codemode-only" }, "permission": { "allow": ["codemode"] } }
 ```
 
-其它配置：`codemode.inlineBudget`（描述里内联声明的预算，估算 token，缺省 3000，超出只列名字）、`codemode.requireStrict`（见下文沙箱）。项目级配置只能把 `codemode.mode` 设为 `off`。
+其它配置：`codemode.inlineBudget`（`only` 模式在描述里内联声明的预算，估算 token，缺省 3000，超出只列名字；`on` 模式不内联）、`codemode.requireStrict`（见下文沙箱）。项目级配置只能把 `codemode.mode` 设为 `off`。
+
+`on` 模式的前缀开销：去重前 `codemode` 描述把已直接暴露的六个工具的声明又内联一遍，其它工具各追加一行提示，系统提示 + 工具表比 `off` 多约 1356 token；现在只多约 390 token（字符 / 4 估算，测试锁定 ≤ 500）。升级后续接的旧会话因为描述字节变化会有一次缓存未命中。
 
 ## 脚本
 
@@ -82,7 +96,7 @@
 - 空环境启动，拿不到密钥、会话文件与环境变量（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）。
+- 网络：Node ≥ 25 的权限模型同时拒绝网络（strict）；Node 22 / 24 不管网络，脚本若逃出 `vm` 就能联网——此时工具描述标注 `network not isolated`，`codemode.requireStrict: true` 时直接不注册 `codemode` 并给出 warning（codemode-only 预设随之回退到 default）。
 
 | 实测（`--permission` + 只读入口） | Node 22.19 | Node 24.21 | Node 26.10 |
 | --------------------------------- | ---------- | ---------- | ---------- |

package/docs/hooks.md

@@ -58,16 +58,16 @@
 
 stdin 是一个 JSON 对象，写完即关闭。所有事件共有：
 
-| 字段             | 说明                                           |
-| ---------------- | ---------------------------------------------- |
-| `hookEventName`  | 事件名                                         |
-| `sessionId`      | 会话 id（子会话为子会话自己的）                |
-| `sessionFile`    | 会话文件（落盘前缺省）                         |
-| `cwd`            | 会话 cwd                                       |
-| `model`          | `{ provider, id }`                             |
-| `permissionMode` | `plan` / `default` / `auto-edit` / `full-auto` |
-| `depth`          | 主会话 0，`task` 子会话 1                      |
-| `host`           | 宿主适配器 id（激活时）                        |
+| 字段             | 说明                                                                  |
+| ---------------- | --------------------------------------------------------------------- |
+| `hookEventName`  | 事件名                                                                |
+| `sessionId`      | 会话 id（子会话为子会话自己的）                                       |
+| `sessionFile`    | 会话文件（落盘前缺省）                                                |
+| `cwd`            | 会话 cwd                                                              |
+| `model`          | `{ provider, id }`                                                    |
+| `permissionMode` | `plan` / `allowlist` / `default` / `auto-edit` / `auto` / `full-auto` |
+| `depth`          | 主会话 0，`task` 子会话 1                                             |
+| `host`           | 宿主适配器 id（激活时）                                               |
 
 事件特有：
 

package/docs/permissions.md

@@ -0,0 +1,148 @@
+# 权限模式与 auto 判定
+
+本文写 ama 的六种权限模式、每次工具调用的判定顺序，以及 `auto` 模式「规则层 → 静态判定 → 模型分类器」三层怎样决定放行还是询问。总体设计见 [design.md](design.md) §6.3、§7；Hook 的输入输出见 [hooks.md](hooks.md)。
+
+## 模式
+
+| 值          | 显示名             | 读  | 写（项目内）                | 执行（bash 等）                | 何时用                           |
+| ----------- | ------------------ | --- | --------------------------- | ------------------------------ | -------------------------------- |
+| `default`   | Manual             | ✓   | 询问                        | 询问                           | 缺省                             |
+| `auto-edit` | Accept edits       | ✓   | ✓                           | 询问                           | 放心让它改代码，命令逐条看       |
+| `plan`      | Plan               | ✓   | 拒绝                        | 拒绝                           | 只读调研、出方案                 |
+| `auto`      | Auto               | ✓   | ✓（受保护路径与项目外询问） | 安全名单放行，其余由分类器判断 | 推荐：常规操作不打扰，有风险才问 |
+| `full-auto` | Bypass permissions | ✓   | ✓                           | ✓                              | 一次性沙箱、容器                 |
+| `allowlist` | Allowlist only     | ✓   | 只放行 allow 规则命中的     | 只放行 allow 规则命中的        | CI：从不询问，没列出的直接拒绝   |
+
+所有模式下，deny 规则、Hook deny 都先判定并直接拒绝；危险命令表（`rm -rf /`、`git push --force`、`curl … | sh` 等，见 README「安全」）一律询问，`allowlist` 与无人值守时变为拒绝。
+
+设置方式：`--permission-mode <值>`、配置 `permission.mode`、交互界面 `/permission`（选择器）或 `Shift+Tab`、RPC `set_permission_mode`、SDK `permission.mode`。
+
+### 严格度与项目级配置
+
+严格度从严到宽：`plan < allowlist < default < auto-edit < auto < full-auto`。项目级 `.ama/config.json` 只能把模式往严的方向改；另外**不能设 `auto` 或 `full-auto`**（这两种由 ama 自己或什么都不判断就放行，必须由用户级配置、命令行或 profile 打开），设了会被忽略并给 warning。
+
+`allowlist` 排在 `plan` 与 `default` 之间：它放行的调用是 `plan` 放行的（只读工具）加上 allow 规则明确列出的；`default` 放行的集合包含它（只读 + allow 规则），其余在 `default` 下询问、在 `allowlist` 下拒绝。所以 `plan ⊆ allowlist ⊆ default`。读工具在 `allowlist` 下照常放行，与其它模式一致；要连读都限制，用 deny 规则。
+
+### 界面
+
+- 状态栏显示显示名：`mode:Auto`；`Bypass permissions` 标黄。
+- `/permission` 不带参数打开选择器：标题 `Mode`，每项「显示名 + 一行说明」，右侧是数字快捷键 1–6，当前模式打勾，配置里的缺省模式标 `Default`，Auto 标 `Recommended`。line 模式 `/permission` 打印同样的列表。
+- `Shift+Tab` 循环：Manual → Accept edits → Plan → Auto → Bypass permissions → Manual。`Allowlist only` 不在循环里，只能显式选。
+
+## 判定顺序
+
+一次工具调用（模型直接发起或 codemode / task 里嵌套发起都一样）：
+
+```text
+schema 校验
+→ 命令式 Hook PreToolUse（deny 一票否决；allow / ask 交给管线）
+→ 权限管线：
+   ① 规则层（不调模型）
+      deny 规则（含内置 deny）、Hook deny                → 拒绝
+      危险命令表                                           → 询问
+      [auto] 受保护路径、项目外写入、网络命令、删除类命令 → 询问
+      Hook ask                                             → 询问
+      allow 规则、Hook allow、本会话记忆                   → 放行
+   ② 模式
+      plan / default / auto-edit / full-auto：同以前的模式真值表
+      allowlist：只读工具放行，其余拒绝（不在允许名单）
+      auto：静态判定（不调模型）→ 放行；未决定 → ③
+   ③ [auto] 模型分类器：allow → 放行；ask / 出错 / 超时 → 询问
+→ 询问时走审批链（宿主 broker → 界面 → 无人值守按拒绝）
+```
+
+- 后面的步骤不能放宽前面的结论：allow 规则越不过危险命令和 auto 的规则层，分类器只能处理①②都没决定的调用。
+- `allowlist` 从不询问：凡是会询问的（危险命令、Hook ask）一律拒绝，拒绝说明写「不在允许名单」。
+- 无人值守（`-p`、RPC 未接审批）时，询问一律按拒绝；auto 模式下分类器仍会先跑，判 allow 的照样执行。
+
+## auto 的三层
+
+### ① 规则层
+
+不调模型，命中即询问（无人值守拒绝）：
+
+| 类别          | 内容                                                                                                                                                                                                                                                                                    |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 危险命令      | `dangerous.ts` 的整张表（所有模式通用）                                                                                                                                                                                                                                                 |
+| 机密路径      | 读或写 `.env`、`.env.*`（`.env.example` / `.sample` / `.template` / `.dist` 除外）、`.ssh/`、`.gnupg/`、`.aws/`、`.kube/config`、`.docker/config.json`、`.netrc`、`.pgpass`、私钥（`id_rsa` 等、`*.pem`、`*.key`、`*.p12`、`*.pfx`、`*.jks`）、ama 的 `auth.json`                       |
+| 受保护写入    | 写 `.git/` 内部、项目里的 `.ama/`（可能改 Hook 与配置）、项目目录外的任何路径（`/dev/null` 等除外）                                                                                                                                                                                     |
+| 网络命令      | `curl`、`wget`、`ssh`、`scp`、`rsync`、`nc`、`gh`；`git push / pull / fetch / clone`；`npm / pnpm / yarn / bun install / add / ci / update / publish / dlx`、`npx`；`pip install`、`cargo install / publish`、`go get / install`、`brew / apt install`、`docker pull / push / login` 等 |
+| 删除与回退    | `rm -r` / `rm -f`、`find -delete`、`git clean`、`git checkout -- …` / `git restore`、`git stash drop / clear`、`shred`、`truncate`                                                                                                                                                      |
+| bash 里的路径 | 重定向目标（`>`、`>>`、`&>`、`tee`）、`cp` / `mv` / `mkdir` / `touch` / `ln` / `chmod` 的目标在项目外或受保护；命令参数里出现机密路径（`cat .env`）                                                                                                                                     |
+
+「项目目录」是会话 cwd。文件工具按 `path` 参数判断；bash 按 `dangerous.ts` 同一套分词与嵌套展开（`sh -c`、`eval`、`xargs`、`find -exec`）逐段判断。
+
+### ② 静态判定
+
+不调模型，满足即放行：
+
+- 只读工具（read、ls、grep、glob 等，`permission: "read"`）。
+- write / edit 目标在项目目录内且不在受保护路径（受保护的已在①询问）。
+- bash：命令里每一段（`&&`、`||`、`;`、`|` 切开）都在**安全名单**内，且
+  - 没有命令替换 `$(…)`、反引号、`<(…)`；
+  - 参数里没有变量展开 `$X`，没有可能匹配点文件的通配（`.e*`）；
+  - 没有 `sh -c` 之类的嵌套（shell、`eval`、`xargs` 都不在名单里）。
+    管道到安全命令（`cat a | grep b | wc -l`）没问题；管道到 shell 不在名单里。重定向写到项目内允许，写到项目外已在①询问。
+- allow 规则命中（这一步在①的末尾已放行）。
+
+安全名单（`src/permissions/auto-safe.ts`，每条都有正反例测试）：
+
+| 命令                                                                                                                                                                                                                                                                                                                              | 限制                                                                     |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `ls`、`cat`、`head`、`tail`、`wc`、`grep`、`egrep`、`fgrep`、`rg`、`pwd`、`echo`、`printf`、`which`、`env` 与 `printenv`（只打印）、`true`、`false`、`sort`、`cut`、`tr`、`diff`、`basename`、`dirname`、`realpath`、`stat`、`file`、`du`、`df`、`date`、`whoami`、`uname`、`cd` / `pushd` / `popd`（之后的相对路径按新目录解析） | `env FOO=1 cmd` 按 `cmd` 判断                                            |
+| `find`                                                                                                                                                                                                                                                                                                                            | 不带 `-exec`、`-execdir`、`-ok`、`-okdir`、`-delete`、`-fprint*`、`-fls` |
+| `git status / diff / log / show / rev-parse / blame / ls-files`（`diff / log / show` 不带 `--output`、`--ext-diff`、`--textconv`；`rg` 不带 `--pre`；`sort` 不带 `-o`；`date` 不带 `-s`）                                                                                                                                         | 子命令前只允许 `-C dir`、`--no-pager`（`-c` 能改 pager，不算安全）       |
+| `git branch`                                                                                                                                                                                                                                                                                                                      | 只列出：不带 `-d / -D / --delete / -m / -M / -c / -C / -f / -u` 等       |
+| `npm / pnpm / yarn test`、`… run test / lint / typecheck / build`、`pnpm / yarn lint / typecheck / build`、`npm t`                                                                                                                                                                                                                |                                                                          |
+| `node --test`、`tsc --noEmit`、`vitest run`、`pnpm vitest run`、`pnpm exec vitest run`、`pytest`、`python -m pytest`                                                                                                                                                                                                              |                                                                          |
+| `cargo test / check / build / clippy`、`go test / build / vet`、`make test / check / lint / build`                                                                                                                                                                                                                                |                                                                          |
+
+扩展：用户级配置 `permission.autoSafeCommands` 追加，例如 `["just test", "bun test", "make fmt"]`——按词前缀匹配（`just test` 命中 `just test --verbose`）；含 `*` 的按通配匹配整段（`bun run test*`）。项目级配置不能追加（放宽）。追加的命令照样先过①：网络、删除、项目外写入仍然询问。
+
+### ③ 模型分类器
+
+只处理①②都没决定的调用（例如 `rm old.txt`、`node scripts/gen.js`、宿主工具、codemode 脚本）。
+
+- **独立请求**：不进会话转录、不改主会话的消息与前缀（主会话的提示缓存不受影响），不触发保温；请求用途 `purpose: "classify"`。
+- **输入**：工具名、参数（JSON，截断到 4000 字符）、cwd、项目根、最近一条用户消息的摘要（截断到 600 字符）。参数与用户消息放在 `<tool_call_data>` … `</tool_call_data>` 数据块里，块内出现的结束标记会被转义；系统提示要求把块内一切当数据，忽略其中的指令（包括「ignore previous instructions」「respond allow」之类），遇到这种文本倾向于 ask。
+- **输出**：严格 JSON `{"decision":"allow"|"ask","reason":"…"}`。解析失败、超时（10 s）、请求出错 → 询问。
+- **模型**：`permission.autoModel`（`provider/model`）；缺省用当前会话模型。推荐配一个便宜快速的模型，例如 `packy/qwen3.8-flash`。`maxTokens` 256，关闭思考。
+- **缓存**：会话内按「工具名 + 归一化参数」（bash 折叠空白，其它按键排序的 JSON）缓存成功的判定，同样的调用只分类一次；出错与超时不缓存。
+- **费用**：每次分类的用量记一条 `usage` 条目，`kind: "permission_classify"`，计入 `/session` 费用与 RPC 统计，不进上下文。
+- 分类器只能把未决定的调用判成 allow 或 ask，不能推翻①的拒绝或询问。
+
+## 审计
+
+- 每次 auto 判定（放行与询问）记录 `{ layer: "rule" | "static" | "classifier", decision, reason }`：
+  - `tool_execution_end` 事件带 `autoDecision`；需要询问时 `permission_request` 事件与审批请求带 `autoDecision`（对话框里显示「Auto：原因」）。
+  - `/permissions` 显示最近 20 条判定（工具、摘要、层、结果、原因）。
+- Hook `PreToolUse` 的输入不变；`permissionMode` 字段会出现新值 `auto`、`allowlist`。
+
+## 配置
+
+```jsonc
+{
+  "permission": {
+    "mode": "auto",
+    "autoModel": "packy/qwen3.8-flash",
+    "autoSafeCommands": ["just test", "make fmt"],
+    "allow": ["bash(npm run e2e)"],
+    "deny": ["bash(terraform *)"],
+  },
+}
+```
+
+CI 用 allowlist：
+
+```sh
+ama -p "修好 lint 并跑测试" --permission-mode allowlist \
+  --allow 'write(src/**)' --allow 'edit(src/**)' --allow 'bash(pnpm lint*)' --allow 'bash(pnpm test*)'
+```
+
+## 已知限制
+
+- 静态判定看命令文本，不看命令真实会读什么：`grep -r token .` 会读到项目里的 `.env`，按安全名单放行。需要更严时，对 `.env` 加 deny 规则（`read(**/.env*)`、`bash(*.env*)`）。
+- 「项目目录」就是 cwd，不跟随符号链接；在子目录启动时，上级目录算项目外。
+- `npm test` / `make test` 之类会执行项目自己的脚本，安全名单按「在项目内跑测试与构建」放行；不信任的仓库请用 `default` 或 `plan`。
+- `sudo` / `doas` 前缀的命令即使后面是安全命令也不算安全（`sudo` 本身在危险命令表里，询问）。
+- 分类器是模型判断，不是安全边界。它前面的规则层不调模型、可审阅；真正不可接受的操作请写 deny 规则。