@ai-zen/cli 1.0.0-alpha.31 → 1.0.0-alpha.32

package/CHANGELOG.md

@@ -1,1349 +1,1502 @@
+## [1.0.0-alpha.32] - 2026-11-03
+
+> This release does one thing: it removes the startup splash animation. Previously every `ai`
+> startup waited about 1.8s for the reveal + sweep before entering the chat, and that pure
+> blocking sat right in front of "read config → resume session → create session". Now it goes
+> straight into the chat, and the branding moved into the chat area itself, landing in the
+> vertical middle when the conversation is empty.
+
+### 💥 Behavior changes
+
+- **No splash animation on startup** — removed `splash.tsx` and the `await mount(<Splash />)`
+  in `runTui()`. The old implementation revealed line by line over 330ms + a 700ms diagonal
+  gradient sweep + a 1100ms hold and auto fade-out, about 1.8s in total; after removal the
+  remaining blank window measured about 66ms (`readConfig` three times + `AgentRepository.list`,
+  all local file reads), so initialization was not moved into the chat screen.
+- **An empty conversation shows the brand block in the vertical middle of the chat area** — logo
+  (6 lines of ASCII on wide terminals, degrading to `◢ AI · ZEN ◣` on narrow ones) + tagline +
+  the three version numbers `CLI / sdk / core`, each line centered on its own. It is now
+  ordinary transcript content: it scrolls up naturally with messages and can be scrolled back
+  into view; it yields as soon as the first message is typed (including the optimistic echo).
+  The gradient is fixed at phase 0 and runs no timers.
+- **The version numbers moved** — previously they appeared once on the splash, now they hang in
+  the brand block; the bottom status bar (model · Agent · reasoning effort | per-turn /
+  cumulative usage · rate | keybindings) is unchanged, character for character.
+- **`computeChatLayout` gains `anchor: "bottom" | "center"`** (defaults to `bottom`, existing
+  behavior unchanged): an empty conversation passes `center`, splitting the remainder below one
+  screenful evenly between top and bottom. Pinning to the top leaves a big empty band in the
+  middle, pinning to the bottom presses right onto the input box, and neither looks good.
+- Bottom-pinning semantics are unchanged: once there are messages, the whole remainder is still
+  added at the head, so the bottom edge of the latest line sits right against the divider.
+
+### 🧪 Tests
+
+- 806 cases all green, `tsc` (production / test configs) and `npm run build` clean.
+- Added: 6 cases in `welcome.test.ts` (wide / narrow logo selection, tagline, three version
+  spots, per-character coloring, per-line centering), 2 chat screen cases (appears on an empty
+  conversation / disappears after the first message), 1 case for `anchor: center`; removed the
+  2 Splash cases.
+- Known leftover: the two `↑` history cases in `chat.test.tsx` were already flaky in the
+  previous release (`flush(20)` colliding with the 60ms frame batching), unrelated to this
+  release, not yet addressed.
+
 ## [1.0.0-alpha.31] - 2026-11-03
 
-> 本版把 CLI 接到重审后的 SDK 上：`@ai-zen/agents-sdk` alpha.26 + `@ai-zen/agents-core`
-> 4.5.4。CLI 自己的改动很小（交接期间让护栏自己让行、交接文件名去掉会话 id 后缀），
-> 但 SDK 那 24 条修复全部随本版到达用户 —— 其中几条是「一条普通命令就能让进程卡死」
-> 或「工具报成功其实啥也没干」级别的。
+> This release attaches the CLI to the re-reviewed SDK: `@ai-zen/agents-sdk` alpha.26 +
+> `@ai-zen/agents-core` 4.5.4. The CLI's own changes are small (guardrails stand down by
+> themselves during handoff, handoff document filenames drop the session id suffix), but all
+> 24 SDK fixes reach users with this release — several of them are of the "one ordinary command
+> is enough to wedge the process" or "the tool reported success but did nothing at all" kind.
 >
-> 口径没变：工具层不承担安全边界（模型不是攻击者），只修正常用法会踩到的东西。
-
-### 💥 行为变更（来自 SDK alpha.26）
-
-- **`exec` 的退出码不再是 `null`** —— 命令正常结束报 `0`，非零如实返回；模型不再把
-  成功的命令误判成「没有正常结束」。
-- **超时会回收整个进程组** —— 以前只杀 shell，`cmd | cat`、`sh -c '… &'` 的孙进程留成孤儿
-  （`sleep 45 &` 还能当常驻进程用，绕过 `spawn`）。现在 `detached` + `kill(-pid)` 整组回收。
-- **`exec` 输出截断如实标注** —— `maxBuffer` 显式设到 16MB，真截断时报 `truncated`，
-  不再把 `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` 当退出码、同时谎称「完整内容已落盘」。
-- **`download_file` 新增必填 `timeout`（毫秒）**，并改流式写盘（200MB 文件不再吃 650MB 堆）；
-  中断时不再删除同路径下原本就存在的文件。
-- **`spawn` 不再假报成功** —— 返回字段 `success` 改为 `started`，并写明「不跟踪退出状态」；
-  命令不存在 / 语法错误 / `exit 3` 不会再显示成成功。
-- **`glob` / `find_text` 对不存在的目录报错**，不再静默返回 `[]` 让你以为文件不存在。
-- **`generate_image` 支持只返回 `b64_json` 的端点** —— 落盘后给本地路径，不再
-  `success: true` 却一张图都没有。
-- **`edit` / `batch_edit` 修掉两个会毁文件的坑** —— 空 `oldText` 会让进程同步死循环（连
-  `Ctrl+C` 都没用）；替换文本里的 `$&`、`$$` 会被当成替换模式，静默写坏文件。
-- **`permissions` 真正生效** —— 被 deny 的 skill 不能再靠点名加载；`mcps` 里没允许的 server
-  即使别的 Agent 连上了也调不到。
-- **MCP 连接更稳** —— 建连中退出不会「复活」连接（stdio 子进程不再留孤儿）；运行期断线
-  会把状态标回 `disconnected`（`load_mcp` 不再返回过期清单）；建连有 60s 超时。
-
-### 🛠️ CLI 自身
-
-- **交接/迁移期间的护栏让行由护栏自己判断**（`isSuspended: () => handoffService.busy`）。
-  以前是趁交接前把 `lastUsage` 清零 —— 那是同一事实的两份拷贝，改一份另一份会过期。
-  现在 `lastUsage` 是从 `messages` 派生的只读值，换掉 `messages` 就自动跟随。
-- **交接文档文件名去掉会话 id 后缀**：`<YYYYMMDD-HHmmss>.md`。会话名往往是手改的，
-  带上只会更难认；同一秒并发交接本就该避免，不为它加随机后缀。
-
-### 🧪 测试
-
-- 799 用例全绿（含构建与 e2e 门禁），`tsc` 双配置（生产 / 测试）干净。
-- 新增：护栏接线用例（交接中让行、结束后恢复硬线）；用量构造改为「带 usage 的 assistant
-  消息」（`lastUsage` 已只读）。
+> The stance is unchanged: the tool layer does not carry the safety boundary (the model is not
+> an attacker); it only fixes things normal usage runs into.
+
+### 💥 Behavior changes (from SDK alpha.26)
+
+- **The `exec` exit code is no longer `null`** — a command that ends normally reports `0`, and
+  non-zero codes are returned truthfully; the model no longer misreads a successful command as
+  "did not end normally".
+- **A timeout reclaims the whole process group** — previously only the shell was killed, so the
+  grandchildren of `cmd | cat`, `sh -c '… &'` were left as orphans (`sleep 45 &` could even
+  serve as a resident process, bypassing `spawn`). Now `detached` + `kill(-pid)` reclaims the
+  entire group.
+- **`exec` output truncation is labeled truthfully** — `maxBuffer` is explicitly set to 16MB, a
+  real truncation reports `truncated`, and `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` is no longer
+  taken as an exit code while falsely claiming "the full content was written to disk".
+- **`download_file` gains a required `timeout` (milliseconds)** and now writes to disk as a
+  stream (a 200MB file no longer eats 650MB of heap); on interruption it no longer deletes a
+  file that already existed at the same path.
+- **`spawn` no longer reports false success** — the returned field `success` becomes `started`,
+  and it states that "exit status is not tracked"; a missing command / syntax error / `exit 3`
+  no longer displays as success.
+- **`glob` / `find_text` report an error for nonexistent directories**, no longer silently
+  returning `[]` and letting you believe the file does not exist.
+- **`generate_image` supports endpoints that only return `b64_json`** — after writing to disk
+  it gives a local path, no more `success: true` with not a single image.
+- **`edit` / `batch_edit` fix two file-destroying pitfalls** — an empty `oldText` puts the
+  process into a synchronous infinite loop (not even `Ctrl+C` helps); `$&` and `$$` in the
+  replacement text are taken as replacement patterns and silently corrupt the file.
+- **`permissions` actually take effect** — a denied skill can no longer be loaded by naming it;
+  a server not allowed in `mcps` cannot be called even if another Agent has connected to it.
+- **MCP connections are more stable** — quitting mid-connect no longer "resurrects" the
+  connection (stdio child processes are no longer left orphaned); a runtime disconnect marks the
+  status back to `disconnected` (`load_mcp` no longer returns a stale manifest); connecting has
+  a 60s timeout.
+
+### 🛠️ CLI itself
+
+- **Stand-down of the guardrails during handoff/migration is decided by the guardrails themselves**
+  (`isSuspended: () => handoffService.busy`). Previously `lastUsage` was zeroed right before
+  handoff — that was two copies of the same fact, and changing one left the other stale. Now
+  `lastUsage` is a read-only value derived from `messages`; replacing `messages` follows
+  automatically.
+- **Handoff document filenames drop the session id suffix**: `<YYYYMMDD-HHmmss>.md`. Session
+  names are usually edited by hand, so carrying them only makes files harder to recognize;
+  concurrent handoffs within the same second should be avoided anyway, and no random suffix is
+  added for it.
+
+### 🧪 Tests
+
+- 799 cases all green (including the build and e2e gates), `tsc` clean on both configs
+  (production / test).
+- Added: guardrail wiring cases (stand down during handoff, restore the hard line afterwards);
+  usage construction switched to an "assistant message with usage" (`lastUsage` is read-only
+  now).
 
 ## [1.0.0-alpha.30] - 2026-11-02
 
-> 本版把 22 条审查问题一次收口。有三处直接改变手感：补全菜单改为底部锚定、多行输入里
-> `↑`/`↓` 先移光标、输入区限高 8 行；另外详情屏不再暴露 `custom`，换成了「恢复出厂设置」。
+> This release closes out 22 review issues in one pass. Three of them change the feel directly:
+> the completion menu is anchored to the bottom, `↑`/`↓` move the cursor first in multi-line
+> input, and the input area is capped at 8 lines; the detail screen also no longer exposes
+> `custom`, replaced by "restore factory defaults".
 >
-> 注：`1.0.0-alpha.28` / `.29` 的条目此前也只在本地（registry 上的 `alpha` 停在 alpha.27），
-> 本版一并带出去。
-
-### 💥 行为变更
-
-- **补全菜单改为底部锚定** —— `/` 命令与 `@` 路径共用一套 `BottomMenu`：`items[0]` 紧贴输入框，
-  其余向上生长、装不下从顶端丢弃；行数上限由布局按剩余空间放行（不再固定 8 行），
-  渲染与 IME 光标读同一个 `layout.hintRows`。说明文字不再把命令名挤成一截。
-- **`↑` / `↓` 先移动光标** —— 多行草稿里到首行 / 末行才翻历史（原来一按就跳历史）。
-- **输入区限高 8 行**，窗口跟随光标（原来钉住末尾，光标退到第一行时会消失在框外）。
-- **`↑` 翻历史带图片** —— 历史数据源统一到 `messages`，回到带图消息时图片一起恢复；
-  `file_id` 类型的历史图片只能恢复文本（本地没有副本）。
-- **`/load` 列表只显示会话文件名** —— 不再逐个读会话文件解析摘要。
-- **`/save <名字>`** —— 另存为指定文件名（旧文件名消失、last-session 指针跟随）；
-  重名且不是当前会话时先二次确认。
-- **详情屏不再有 `custom` 开关，改为「恢复出厂设置」** —— 出厂模型 / 图片模型用出厂定义
-  **整条替换**（`custom` 随之消失 = 重新归 SDK 托管）；默认 Agent 只把提示词换回出厂，
-  名称 / 描述 / 模型 / 权限全部保留；出厂清单里没有同 id 的（自建）不显示该动作。
-- **粘贴文本 256KB 上限** —— 超了报错且**不截断**（半截代码 / 半截 JSON 比不粘更坑）。
-- **写句子不再乱弹 `@` 菜单** —— token 边界补上 `。 、 ！ ？ （ ） 《 》 【 】 〔 〕 「 」 『 』 … — ～`。
-- **没有端点时禁止新建模型 / 图片模型** —— 以前能创建出 `endpointId: ""` 的空壳。
-- **坏掉的 `mcp.json` 不再冒充空配置** —— MCP 屏写明「无法解析」、照样能编辑，
-  保存产出的正是一份格式正确的新文件（那是修复，不是覆盖丢数据）。
-
-### 🐛 修复
-
-- KV 编辑器删掉末项后回车崩溃（光标钳到新的末项）。
-- `SelectList` 列表变短后回车崩溃（渲染与确认都走 `safeIndex`）。
-- 自动落盘失败混在 info 语气里上报。
-- `/back` 撤回后不落盘（存档里还留着被撤回的消息）。
-- 删掉默认 Agent 时没清 `config.defaultAgent`，下次启动死在「Agent 未绑定模型」。
-- stdout 被提前关闭时打 EPIPE 堆栈（按正常结束处理）。
-- `/load` `/back` 选择器条数预算少扣 2 行，最后两条被吸底布局吃掉。
-- `truncate` 按字素簇截断，不再把 emoji 劈成孤立代理项。
-- e2e 断言与事实不符（`ai hook` 写 stdout、退出码 0），且被 `vitest.config.ts` 排除、
-  永远不会红 —— 断言修正后从 5 红变全绿。
-
-### 🔒 安全
-
-- **`@ai-zen/agents-sdk` 升到 `1.0.0-alpha.25`**：`EntityRepository.path()` 校验实体 id 不得逃出
-  仓储目录（`resolve` + `root + sep`，裸 `startsWith` 拦不住 `<root>-evil`）。`/save ../x`
-  现在明确报错，不再可能写到会话目录之外。这一版同时带上 SDK 的端点 `capabilities`
-  迁移回填（老的 `deepseek` 端点会补上 `filesApi`，图片改走 Files API）。
-
-### ✅ 测试
-
-- 单测 **57 文件 / 798 例通过**，e2e **9 passed / 3 skipped**（3 条需真 API key），
-  `tsc --noEmit` 干净。
-- 发布门禁 `prepublishOnly` 改为 `npm run test:all`（单测 + 构建 + e2e）；
-  `npm test` 语义不变，仍只跑类型 + 单测。
-- 测试耗时 43.6s → ~8s：去掉 `isolate`、单 fork、依赖注入替换全部模块级 `vi.mock`。
+> Note: the `1.0.0-alpha.28` / `.29` entries had so far only existed locally (the registry's
+> `alpha` tag stopped at alpha.27); this release carries them out as well.
+
+### 💥 Behavior changes
+
+- **The completion menu is anchored to the bottom** — `/` commands and `@` paths share one
+  `BottomMenu`: `items[0]` sits right above the input box, the rest grows upward and is dropped
+  from the top when it does not fit; the row cap is granted by the layout according to the
+  remaining space (no longer fixed at 8 rows), and rendering and the IME cursor read the same
+  `layout.hintRows`. Descriptions no longer squeeze the command name into a stub.
+- **`↑` / `↓` move the cursor first** — in a multi-line draft they page through history only at
+  the first / last line (previously one press jumped to history).
+- **The input area is capped at 8 lines**, and the window follows the cursor (previously it was
+  pinned to the end, so the cursor disappeared outside the box when it went back to the first
+  line).
+- **`↑` history paging carries images** — the history data source is unified on `messages`, so
+  going back to a message with images restores the images as well; history images of type
+  `file_id` can only restore text (there is no local copy).
+- **The `/load` list shows session filenames only** — no longer reading each session file to
+  parse a summary.
+- **`/save <name>`** — save as a specified filename (the old filename disappears, the
+  last-session pointer follows); if the name is taken and is not the current session, a second
+  confirmation is asked first.
+- **The detail screen no longer has a `custom` toggle, replaced by "restore factory defaults"**
+  — the factory model / image model are **replaced wholesale** with the factory definition
+  (`custom` disappears with it = managed by the SDK again); the default Agent only swaps the
+  prompt back to the factory one, keeping the name / description / model / permissions all
+  intact; entries with no matching id in the factory list (self-built) do not show the action.
+- **256KB cap on pasted text** — exceeding it reports an error and does **not truncate** (half
+  a piece of code / half a JSON is worse than not pasting).
+- **Writing sentences no longer pops up the `@` menu at random** — the token boundary adds
+  `。 、 ！ ？ （ ） 《 》 【 】 〔 〕 「 」 『 』 … — ～`.
+- **No endpoint, no new model / image model** — previously an empty shell with
+  `endpointId: ""` could be created.
+- **A broken `mcp.json` no longer passes itself off as empty config** — the MCP screen states
+  "cannot be parsed" and stays editable, and saving produces exactly a new, correctly formatted
+  file (that is a repair, not a data-losing overwrite).
+
+### 🐛 Fixes
+
+- The KV editor crashed on Enter after deleting the last item (the cursor is clamped to the new
+  last item).
+- `SelectList` crashed on Enter after the list got shorter (both rendering and confirmation go
+  through `safeIndex`).
+- Automatic save failures were reported in an info tone.
+- `/back` did not save after reverting (the reverted messages stayed in the archive).
+- Deleting the default Agent did not clear `config.defaultAgent`, and the next startup died on
+  "Agent has no model bound".
+- An EPIPE stack trace was printed when stdout was closed early (now handled as a normal exit).
+- The `/load` `/back` selector row budget under-counted by 2 rows, so the bottom-pinned layout
+  ate the last two entries.
+- `truncate` truncates by grapheme cluster and no longer splits emoji into lone surrogates.
+- The e2e assertion did not match reality (`ai hook` writes to stdout, exit code 0) and was
+  excluded by `vitest.config.ts`, so it could never go red — after correcting the assertion it
+  went from 5 red to all green.
+
+### 🔒 Security
+
+- **`@ai-zen/agents-sdk` bumped to `1.0.0-alpha.25`**: `EntityRepository.path()` now validates
+  that an entity id cannot escape the repository directory (`resolve` + `root + sep`; a bare
+  `startsWith` cannot stop `<root>-evil`). `/save ../x` now reports a clear error and can no
+  longer write outside the session directory. This release also carries the SDK's endpoint
+  `capabilities` migration backfill (old `deepseek` endpoints get `filesApi`, and images move
+  to the Files API).
+
+### ✅ Tests
+
+- Unit tests **57 files / 798 cases passing**, e2e **9 passed / 3 skipped** (3 need a real API
+  key), `tsc --noEmit` clean.
+- The release gate `prepublishOnly` changed to `npm run test:all` (unit tests + build + e2e);
+  `npm test` keeps its semantics and still runs only types + unit tests.
+- Test time 43.6s → ~8s: removed `isolate`, single fork, dependency injection replaced all
+  module-level `vi.mock`.
 
 ## [1.0.0-alpha.29] - 2026-10-31
 
-> `Ctrl+V` 从「弹一句未支持」变成**真的粘贴**：剪贴板里有图片就附在消息上，
-> 没有就退回粘贴文本。
+> `Ctrl+V` goes from "pops up an unsupported notice" to **actually pasting**: if the clipboard
+> holds an image it is attached to the message, otherwise it falls back to pasting text.
 
-### ✨ 新功能
+### ✨ New features
 
-- **粘贴图片** —— `Ctrl+V`（kitty 协议下 `⌘V`）先问系统剪贴板要图片，有图就附到待发送
-  消息上，输入框上方出现 `📎 已附加 N 张图片 · Ctrl+V 再加 · Esc 清空`；没有图片则
-  当作普通粘贴，把剪贴板文本插到光标处。按平台探测：
+- **Pasting images** — `Ctrl+V` (or `⌘V` under the kitty protocol) first asks the system
+  clipboard for an image; if there is one it is attached to the message being composed, and
+  `📎 N images attached · Ctrl+V to add more · Esc to clear` appears above the input box; with
+  no image it counts as an ordinary paste, inserting the clipboard text at the cursor. Probed
+  per platform:
 
-  | 平台 | 图片 | 文本 |
+  | Platform | Image | Text |
   |---|---|---|
-  | macOS | `osascript -e "get the clipboard as «class PNGf»"`（stdout 是 `«data PNGf<HEX>»`） | `pbpaste` |
-  | Linux | `wl-paste --type image/png`（Wayland）→ `xclip -t image/png -o`（X11） | `wl-paste --no-newline` → `xclip -o` |
+  | macOS | `osascript -e "get the clipboard as «class PNGf»"` (stdout is `«data PNGf<HEX>»`) | `pbpaste` |
+  | Linux | `wl-paste --type image/png` (Wayland) → `xclip -t image/png -o` (X11) | `wl-paste --no-newline` → `xclip -o` |
   | Windows | PowerShell `Get-Clipboard -Format Image` → PNG → base64 | `Get-Clipboard -Raw` |
 
-- **全程不落盘** —— 图片以 base64 直接交给 SDK 的 `fileToContentSection()`（它的
-  `FileSource` 本来就有 `{ base64, mime }` 变体）：上传 Files API 还是内联 base64、
-  模型不支持视觉时怎么退化，全部由 SDK 按当前端点决定，CLI 不重复实现、也不硬编码端点。
-- **一条消息最多 4 张**（`MAX_PASTED_IMAGES`）：一张截图内联后常 1~3MB，再多一次请求
-  就是几十 MB。超限、图片过大（>20MB）、剪贴板为空、没有剪贴板工具，各有独立提示。
-
-### 🎨 交互
-
-- **图片优先、文本兑底**，顺序不能反：文本先粘进去就来不及了（草稿里已经多了一坨东西）。
-- `Esc` 有附件时**先清附件、草稿保留** —— 误粘一张总有退路，又不必让 `ESC` 变成
-  「清空一切」的随机键。
-- 附件提示行恒为一行，行数同时计入 `computeChatLayout`（占高）与
-  `computeInputCursorPosition`（IME 光标 y）—— 差一行输入框就整体位移，这条有前科。
-- 乐观回显按「文本段 + 图片占位块」构造，与实际发送的结构一致（否则图片那几条会在
-  真实消息落地前闪一下不见）；转录里内联图片只显示 `[图片]`，不把几十万字符的
-  data URL 铺到屏幕上（远程 URL 才带地址）。
-
-### 🐛 修复
-
-- **带图片的消息会丢掉 cwd 注入** —— `CwdTrackerPlugin` 原来只找 `content` 是字符串的
-  用户消息，换成内容块数组后会被直接跳过，那一轮模型看到的还是上一轮的工作目录。
-  现在追加到**最后一个 text 段**上；数组里没有 text 段时补一段。
-- README / getting-started 里「`PgUp`/`PgDn`（或 `Alt+V`/`Ctrl+V`）翻页」是错的：
-  `Ctrl+V` 从未兼任翻页（`common-keys.ts` 只认 `Alt+V`），已修正。
-
-### ✅ 测试
-
-- 新增 33 例：`clipboard.test.ts` 15（三平台命令选择 / osascript 十六进制解析 / 缺工具 /
-  空输出 / 超限 / CRLF 归一）、`user-content.test.ts` 6（文本段在首位 / 部分失败 /
-  全失败退回纯文本 / warning 透传）、`cwd-tracker-plugin.test.ts` 4（字符串 / 内容块 /
-  只有图片 / 不重复注入）、`pasted-images.test.tsx` 3（恒一行 / 布局多占一行 / 光标 y 同步）、
-  `chat.test.tsx` +5（无图粘文本 / 有图出附件行 / Esc 清附件保草稿 / 发送带图 / 空剪贴板提示）。
-- 全量 **57 文件 / 741 例通过**，`tsc --noEmit` 0 错误。
-- 真产物验证（本机 Linux、无剪贴板工具）：`readClipboardImage() → { kind: "none" }`、
-  `readClipboardText() → null`，11ms 不抛错；不打桩地跑真实 SDK 转换，`vision: true` 得到
-  `image_url` 内联块，`vision` 缺省得到文本提示 + warning。
+- **Nothing ever touches the disk** — images are handed to the SDK's `fileToContentSection()`
+  as raw base64 (its `FileSource` already has a `{ base64, mime }` variant): whether to upload
+  to the Files API or inline base64, and how to degrade when the model does not support vision,
+  is entirely decided by the SDK per current endpoint — the CLI neither reimplements it nor
+  hardcodes endpoints.
+- **At most 4 images per message** (`MAX_PASTED_IMAGES`): one screenshot is often 1–3MB once
+  inlined, and a few more in a single request easily reach tens of MB. Over the cap, an
+  oversized image (>20MB), an empty clipboard and a missing clipboard tool each have their own
+  message.
+
+### 🎨 Interaction
+
+- **Images first, text as the fallback**, and the order cannot be reversed: pasting the text
+  first leaves no room (there is already a chunk in the draft by then).
+- **`Esc` with attachments clears the attachments first and keeps the draft** — a mistaken paste
+  always has a way back, and `Esc` does not have to become a random key that "clears everything".
+- The attachment hint row is always one line, and its row count is counted both in
+  `computeChatLayout` (height) and in `computeInputCursorPosition` (IME cursor y) — one row off
+  and the whole input box shifts; this has happened before.
+- The optimistic echo is built from "text segments + image placeholder blocks", matching the
+  structure actually sent (otherwise the image entries would flash and vanish before the real
+  message lands); inline images in the transcript show only `[image]`, so a data URL of hundreds
+  of thousands of characters is not painted on screen (only remote URLs carry an address).
+
+### 🐛 Fixes
+
+- **Messages with images lost the cwd injection** — `CwdTrackerPlugin` used to look only for
+  user messages whose `content` was a string, and skipped them outright once content became a
+  block array, so the model saw the working directory of the previous turn for that round. Now
+  it appends to the **last text segment**; when the array has no text segment, one is added.
+- "`PgUp`/`PgDn` (or `Alt+V`/`Ctrl+V`) page through" in README / getting-started was wrong:
+  `Ctrl+V` never doubled as paging (`common-keys.ts` only accepts `Alt+V`), now corrected.
+
+### ✅ Tests
+
+- 33 cases added: `clipboard.test.ts` 15 (three-platform command selection / osascript hex
+  parsing / missing tool / empty output / over the limit / CRLF normalization),
+  `user-content.test.ts` 6 (text segment first / partial failure / total failure falls back to
+  plain text / warning passthrough), `cwd-tracker-plugin.test.ts` 4 (string / content blocks /
+  images only / no duplicate injection), `pasted-images.test.tsx` 3 (always one line / layout
+  takes one extra row / cursor y stays in sync), `chat.test.tsx` +5 (paste text without images /
+  attachment row with images / Esc clears attachments and keeps the draft / send with images /
+  empty clipboard notice).
+- Full run **57 files / 741 cases passing**, `tsc --noEmit` 0 errors.
+- Real-artifact verification (local Linux, no clipboard tool): `readClipboardImage() → { kind: "none" }`,
+  `readClipboardText() → null`, 11ms without throwing; running the real SDK conversion without
+  stubs, `vision: true` yields an `image_url` inline block and a missing `vision` yields a text
+  hint + warning.
 
 ## [1.0.0-alpha.28] - 2026-10-31
 
-> 输入框里敲 `@` 唤起**文件路径补全** —— 补进去的是相对路径文本，模型用 `read` 工具自己去读。
-
-### ✨ 新功能
-
-- **`@` 文件路径补全** —— 敲 `@` 弹出项目内候选，`↑`/`↓` 选择、`Tab` 或 `Enter` 补进草稿、
-  `Esc` 只关菜单（不动草稿）。三层拆分，与仓库既有风格一致：
-  - `tui/mention.ts`（纯逻辑）：`extractMention()` 判「光标在不在一个 `@token` 里」、
-    `rankPaths()` 子序列模糊排序、`menuWindow()` 视窗、`mentionMenuRows()` 行数；
-  - `tui/file-index.ts`（IO）：`git ls-files -co --exclude-standard` 优先（尊重 `.gitignore`、
-    含未跟踪文件），非 git 目录回落 `fs.glob` 并排除 `node_modules` / `.git` / `dist`；
-    15s 缓存、20000 条封顶、5s 超时；
-  - `screens/chat.tsx`：按键 → 候选 → `replaceRange()` 落字的接线。
-- **判据落在字符事实上**：从光标往回扫到空白 / 行首，途中遇到 `@` 且其前一个是行首、空白或
-  分隔符才算 mention。于是 `a@b.com` 不会弹菜单；`@src/tui`、`(@src/x)`、`"@src/x"` 都会；
-  光标停在 token 中间（`@src|/foo.ts`）时 query 截止于光标、`end` 向后吃掉整个 token ——
-  补全替换的是整段，不会留下半截残字。
-- **排序**：贪婪子序列 + 跳跃惩罚 + 连续命中奖励；**整体前缀 > 文件名前缀**，同分时浅的 / 短的
-  优先。实测本仓：`@` → 182 条索引里取 50 条（1.1ms）、`@chat` 命中 19 条（0.2ms）、
-  `@file-index` 精确命中 2 条（0.1ms）。
-- **目录可逐层往下钻**：选中目录补尾斜杠（`@src/tui/`），补完菜单重新过滤出该目录下内容，
-  于是能一路 `@src/` → `@src/tui/` → 目标文件。
-
-### 🎨 交互
-
-- `Tab` / `Enter` = **补全不发送**（选完继续接着写，避免误发半截消息）；`Esc` 只关菜单，
-  不清草稿（原 `Esc` 语义是清空草稿，`@` 打一半按 Esc 会连正文一起没）。
-- 候选可能几十条，菜单**最多占 8 行**并随高亮滚动；索引未就绪时先占一行「正在扫描项目文件…」。
-- 行数有**唯一真源** `mentionMenuRows()`：`computeChatLayout` 的 `hintCount`、IME 光标的 y 坐标、
-  `MentionMenu` 实际渲染三处同源，并有用例断言 `mentionMenuRows(n) === menuWindow(n)` 的行数。
-- 占位提示改为「输入消息，/ 命令，@ 文件…」，让这个入口能被看见。
-
-### 🔧 重构
-
-- `useInputEditing` 新增 `replaceRange(start, end, text)`：整段替换**并记撤销快照**，
-  补错了 `Ctrl+_` 能退回（用 `setInputText` 会绕过撤销栈）。
-
-### ✅ 测试
-
-- 新增 39 例：`mention.test.ts` 22（提取 / 插入 / 排序 / 视窗 / 行数一致）、
-  `file-index.test.ts` 9（git 清单归一 / 缓存 TTL / cwd 切换 / 兜底 / 异常收敛 / 真磁盘）、
-  `components-mention.test.tsx` 5（8 行封顶 / 滚动跟随 / 目录尾斜杠 / 扫描占位 / 无匹配不占行）、
-  `chat.test.tsx` +6（弹菜单 / Tab 补全不发送 / Enter 补全 / ↓ 换高亮 / Esc 只关菜单 / 无匹配照常发）、
-  `use-input-editing.test.tsx` +3（区间替换 / 可撤销 / 越界钳制）。
-- 全量 **53 文件 / 708 例通过**，`tsc --noEmit` 0 错误。
+> Typing `@` in the input box brings up **file path completion** — what gets inserted is the
+> relative path text, and the model reads the file itself with the `read` tool.
+
+### ✨ New features
+
+- **`@` file path completion** — typing `@` pops up in-project candidates, `↑`/`↓` to select,
+  `Tab` or `Enter` to insert into the draft, `Esc` to close the menu only (without touching the
+  draft). Three layers, consistent with the existing style of the repo:
+  - `tui/mention.ts` (pure logic): `extractMention()` decides whether the cursor is inside an
+    `@token`, `rankPaths()` fuzzy subsequence ranking, `menuWindow()` the viewport,
+    `mentionMenuRows()` the row count;
+  - `tui/file-index.ts` (IO): `git ls-files -co --exclude-standard` preferred (honors
+    `.gitignore`, includes untracked files), falling back to `fs.glob` outside a git directory
+    and excluding `node_modules` / `.git` / `dist`; 15s cache, 20000 entries capped, 5s timeout;
+  - `screens/chat.tsx`: the wiring from keybinding → candidates → `replaceRange()` insertion.
+- **The criterion rests on character facts**: scan back from the cursor to whitespace / line
+  start, and an `@` encountered on the way counts as a mention only if it is preceded by line
+  start, whitespace or a separator. So `a@b.com` does not pop up the menu, while `@src/tui`,
+  `(@src/x)` and `"@src/x"` all do; when the cursor sits in the middle of a token
+  (`@src|/foo.ts`), the query ends at the cursor and `end` eats the whole token forward —
+  completion replaces the whole span and leaves no partial leftovers.
+- **Ranking**: greedy subsequence + gap penalty + consecutive-hit bonus; **whole-span prefix >
+  filename prefix**, and on a tie the shallower / shorter one wins. Measured on this repo: `@`
+  takes 50 out of 182 indexed entries (1.1ms), `@chat` hits 19 (0.2ms), `@file-index` matches 2
+  exactly (0.1ms).
+- **Directories can be drilled into level by level**: selecting a directory appends a trailing
+  slash (`@src/tui/`), and after insertion the menu refilters to that directory's contents, so
+  you can walk `@src/` → `@src/tui/` → the target file.
+
+### 🎨 Interaction
+
+- `Tab` / `Enter` = **complete without sending** (keep writing after picking, to avoid sending
+  half a message by mistake); `Esc` only closes the menu and does not clear the draft (the old
+  `Esc` semantic was to clear the draft, so pressing Esc halfway through an `@` took the body
+  with it).
+- Candidates can number in the dozens; the menu **takes at most 8 rows** and scrolls with the
+  highlight; while the index is not ready, one row of "Scanning project files…" is shown first.
+- The row count has a **single source of truth** `mentionMenuRows()`: `computeChatLayout`'s
+  `hintCount`, the IME cursor y coordinate and `MentionMenu`'s actual rendering draw from the
+  same source, with a case asserting `mentionMenuRows(n) === menuWindow(n)`.
+- The placeholder changed to "Type a message, / for commands, @ for files…" so this entry point
+  can be seen.
+
+### 🔧 Refactors
+
+- `useInputEditing` gains `replaceRange(start, end, text)`: it replaces the span **and records
+  an undo snapshot**, so a wrong completion can be taken back with `Ctrl+_` (using
+  `setInputText` would bypass the undo stack).
+
+### ✅ Tests
+
+- 39 cases added: `mention.test.ts` 22 (extraction / insertion / ranking / viewport / row count
+  consistency), `file-index.test.ts` 9 (git listing normalization / cache TTL / cwd switch /
+  fallback / error convergence / real disk), `components-mention.test.tsx` 5 (8-row cap /
+  scrolling follows / directory trailing slash / scanning placeholder / no match takes no row),
+  `chat.test.tsx` +6 (menu pops up / Tab completes without sending / Enter completes / ↓ changes
+  the highlight / Esc only closes the menu / no match still sends), `use-input-editing.test.tsx`
+  +3 (range replacement / undoable / out-of-range clamping).
+- Full run **53 files / 708 cases passing**, `tsc --noEmit` 0 errors.
 
 ## [1.0.0-alpha.27] - 2026-10-29
 
-> SDK 的警告与错误现在会进通知栏——**通用通道**，不为某个功能单独接线。
-
-### ✨ 新功能
-
-- **SDK 日志 → 通知栏**（`sdk-log.ts` 从「只落盘」改成 tee）—— `installSdkLogger()`
-  过去把 SDK 日志**整体接管到文件**（不然 `console.log` 会撕坏 Ink 的帧），代价是
-  「SDK 说了什么」在界面上一个字都看不见，只能事后翻 `~/.ai-zen/logs/sdk.log`。
-  现在 `warn` / `error` 除了落盘，还会转给通知栏：
-  - **晚绑定**：`installSdkLogger()` 跑在 Ink 渲染之前，而通知栏活在 `Chat` 的 React
-    state 里。`Chat` 挂载时注册 sink；注册前攒最近 5 条、注册时补推 —— 启动期的
-    问题恰恰最该看见。
-  - **去重**：同一句话反复刷（例如每轮都失败一次）只上栏一次。
-  - **封顶 20 条**：到顶后补一句 `More SDK warnings suppressed — see <日志路径>`，
-    之后不再刷。SDK 的日志量按「每次请求 / 每次刷新」计，不封顶会把栏位和 React
-    状态一起冲垮。
-  - `info` 只进文件 —— SDK 打 info 很密（mcp manifest、工具发现），上栏等于刷屏。
-  - 以后 SDK 任何新特性只要打 `warn` / `error`，界面上自动就有，**不必再为它传回调**。
-    这条通道只用既有的 `setLogger`，与 SDK 版本解耦。
-- **通知栏新增 `warn` 档** —— `NoticeTone` 由 `info | error` 扩为 `info | warn | error`，
-  `NoticeBar` 用 `theme.warn` 着色。警告既不该降级成普通提示（会漏看），也不该冒充
-  错误（会误导）。
-
-### 🔧 依赖
-
-- `@ai-zen/agents-sdk` `1.0.0-alpha.23` → `1.0.0-alpha.24`：`tools/` 目录的加载改为
-  fail-safe —— 无 `export` 的文件不再被求值、求值期抑制 `process.exit` / `abort`
-  并把 `console` 输出改指 stderr、单文件 import 加超时。
-
-  这修的是一次真实事故：一个无参数时 `process.exit(2)` 的开发脚本放进
-  `.ai-zen/tools/` 后，SDK 在建会话途中 `import()` 了它，于是**每次启动都在初始化
-  途中把 CLI 杀掉**，屏幕上只剩最后一帧，看着像「卡住不启动」；同目录另几个脚本还在
-  每次启动时静默重写项目里的 PNG 资产。现在这类文件会被跳过（或被抑制），并通过上面
-  那条通道在通知栏报出来。
-
-### ✅ 测试
-
-- 新增 `src/sdk-log-notice.test.ts` 6 例：`warn`/`error` 上栏、`info` 不上栏、
-  启动期缓冲补推、去重、封顶收尾、静默模式不上栏。
-- 全量 **50 文件 / 663 例通过**（alpha.26 时 49 文件 / 657 例），`tsc --noEmit` 0 错误。
+> SDK warnings and errors now go to the notice bar — a **generic channel**, not wired up
+> separately for each feature.
+
+### ✨ New features
+
+- **SDK logs → notice bar** (`sdk-log.ts` goes from "write to disk only" to a tee) —
+  `installSdkLogger()` used to **take over SDK logs wholesale into a file** (otherwise
+  `console.log` would tear up Ink's frames), at the cost that a single word of "what the SDK
+  said" was invisible in the UI and could only be found afterwards in `~/.ai-zen/logs/sdk.log`.
+  Now `warn` / `error` are also forwarded to the notice bar besides being written to disk:
+  - **Late binding**: `installSdkLogger()` runs before Ink renders, while the notice bar lives
+    in `Chat`'s React state. `Chat` registers a sink on mount; the latest 5 messages are
+    buffered before registration and pushed on registration — startup problems are exactly what
+    most needs to be seen.
+  - **Dedup**: the same sentence repeating (for example failing once per turn) reaches the bar
+    only once.
+  - **Capped at 20 rows**: after the cap, one extra line `More SDK warnings suppressed — see <log path>`
+    is appended and nothing more is pushed. SDK log volume is counted per "request / refresh",
+    and without a cap the bar and the React state would be flooded together.
+  - `info` goes to the file only — the SDK logs info densely (mcp manifest, tool discovery), and
+    putting it on the bar is spam.
+  - From now on, any new SDK feature that logs `warn` / `error` is automatically visible in the
+    UI, **no callback needs to be passed for it**. This channel only uses the existing
+    `setLogger` and is decoupled from the SDK version.
+- **The notice bar gains a `warn` tone** — `NoticeTone` expands from `info | error` to
+  `info | warn | error`, and `NoticeBar` colors it with `theme.warn`. A warning should neither be
+  downgraded to an ordinary notice (it would be missed) nor pass itself off as an error (it
+  would mislead).
+
+### 🔧 Dependencies
+
+- `@ai-zen/agents-sdk` `1.0.0-alpha.23` → `1.0.0-alpha.24`: loading of the `tools/` directory
+  became fail-safe — files without `export` are no longer evaluated, `process.exit` / `abort`
+  are suppressed during evaluation while `console` output is redirected to stderr, and importing
+  a single file now has a timeout.
+
+  This fixes a real incident: a dev script that called `process.exit(2)` when run without
+  arguments was placed in `.ai-zen/tools/`, the SDK `import()`-ed it midway through creating a
+  session, and so **every startup killed the CLI during initialization**, leaving only the last
+  frame on screen and looking like "stuck on startup"; several other scripts in the same
+  directory silently rewrote PNG assets in the project on every startup. Such files are now
+  skipped (or suppressed) and reported in the notice bar through the channel above.
+
+### ✅ Tests
+
+- 6 cases added in `src/sdk-log-notice.test.ts`: `warn`/`error` reach the bar, `info` does not,
+  buffered startup messages are pushed later, dedup, cap wrap-up, silent mode does not touch the
+  bar.
+- Full run **50 files / 663 cases passing** (49 files / 657 cases at alpha.26), `tsc --noEmit`
+  0 errors.
 
 ## [1.0.0-alpha.26] - 2026-10-29
 
-> `/update` 从「一个转圈 + 一句结果」改成**每一步都说清在干什么**，
-> 并补上了此前名不副实的「重启生效」——现在是真的重启进程。
-
-### ✨ 新功能
-
-- **装完可以一键重启** —— 装完弹确认框「已装好 vX，重启后才会生效…现在重启？」，
-  默认高亮「是」（`/migrate` 用的同一套 `Confirm` 浮层，回车即走）；确认后先落盘当前
-  对话再重启，新进程按常规启动即**续接上一轮会话**。拒绝也不拦人，照旧给「重启 ai 后
-  生效」的提示。
-- **过程信息不再缺席** —— 依次报出「正在查询最新版本…」→「发现 vX（当前 vY），
-  开始安装…」→「✅ 已安装 …」；移交终端给 npm 之前，先在真实 TTY 上打一段头部：
-  装什么包、当前版本、`npm root -g` 得到的安装位置、以及实际执行的命令。
-
-### 🐛 修复
-
-- **「重启生效」原本是空头支票** —— 旧实现只 `push` 一句「重启 ai 后生效」，
-  `/update` 自己也从不重启。而 `exit({ restart: true })` 那条路（`/model`、`/lang` 在用）
-  只是同进程重挂载 `<Chat/>`，内存里还是旧模块图，对「磁盘上的代码变了」这种升级
-  等于没装。现在改为**真·重新 exec 自己**：`spawn` 新进程跑新 dist，父进程在挂起态
-  等它退出后跟着退。
-- **`/update` 期间的转圈是「冻住」的** —— `readDistTags()` 用的是 `spawnSync`，
-  同步阻塞事件循环，Ink 的动画定时器跟着停摆 1–3 秒。改为异步 `spawn`，并加 20 秒
-  超时兜底（断网时不会再无限期挂着）。
-- **转圈上的文案是「处理中…」** —— 这个文案来自生成阶段 `phaseLabel(session.phase)`，
-  而 `/update` 根本没有生成轮次，`phase` 为 `null` 就兜底成了通用的「处理中…」，
-  与正在发生的事毫无关系。新增 `busySpinnerLabel()`：有生成阶段仍由 SDK 阶段驱动，
-  阻塞型命令期间改显 `/update 执行中…`。
-
-### 🔧 改进
-
-- **查询与安装都加 `--prefer-online`** —— npm 会缓存 packument，刚发版时
-  `npm view` 可能仍拿到旧 dist-tags，把「有新版」误判成「已是最新」（发布当天踩过）；
-  安装侧同理。另加 `--no-fund` 减噪。
-
-### ⚠️ 两个容易踩的终端细节（写在代码注释里）
-
-- **重启必须在挂起态里退出**：`suspendTerminal` 的 `beginSuspend()` 关 raw 模式，
-  `endSuspend()` 会把它重新打开；若等 `suspendTerminal` 返回后再 `process.exit`，
-  终端就停在 raw 模式，回到 shell 后按键全是乱码。
-- **重启前要先 `disableMouseTracking()`**：鼠标上报由 `mount()` 按 Ink 实例开关，
-  而挂起期间实例并未退出 —— 不关的话，子进程若异常死亡，终端会一直把滚轮写成
-  转义序列。
-
-### 📖 文档
-
-- `README.md` / `README.zh.md` / `docs/{zh,en}/getting-started.md` —— `/update` 的描述
-  订正：原文写「全局安装 alpha 通道」，实际是在**全部** dist-tags 里挑 semver 最大者
-  （所以 alpha 比 `latest` 新时会装 alpha），并补上「逐步骤显示进度、装完可一键重启」。
-
-### ✅ 测试
-
-- 全量 **49 文件 / 657 例通过**（alpha.25 时 649 例），`tsc --noEmit` 0 错误。
-- `/update` 用例 6 → 11 例：新增「确认后重启 + 重启前落盘」「拒绝重启则不落盘也不重启」
-  「新会话无用户消息不落盘」「三条过程通知按序上报」「终端头部含版本/位置/命令」
-  「查询带 `--prefer-online`」。
-- 新增 `busySpinnerLabel` 3 例，含回归守卫：命令执行期间**不得**回落成「处理中…」。
+> `/update` changes from "one spinner + one result line" to **saying what it is doing at every
+> step**, and fills in the previously nominal "takes effect after restart" — it now really
+> restarts the process.
+
+### ✨ New features
+
+- **One key to restart after install** — a confirmation box pops up after install: "vX is
+  installed, it takes effect after a restart… restart now?", with "Yes" highlighted by default
+  (the same `Confirm` overlay used by `/migrate`, Enter goes ahead); after confirming, the
+  current conversation is saved first and then the process restarts, and the new process
+  **resumes the previous session** on a normal start. Declining blocks nothing and still gives
+  the "takes effect after restarting ai" hint.
+- **Progress information is no longer missing** — it reports in order "Querying the latest
+  version…" → "Found vX (current vY), installing…" → "✅ Installed …"; before handing the
+  terminal over to npm, it prints a header on the real TTY: which package is being installed,
+  the current version, the install location from `npm root -g`, and the command actually
+  executed.
+
+### 🐛 Fixes
+
+- **"Takes effect after restart" was an empty promise** — the old implementation only `push`-ed
+  one "takes effect after restarting ai" line, and `/update` itself never restarted. And the
+  `exit({ restart: true })` path (used by `/model`, `/lang`) merely remounted `<Chat/>` in the
+  same process, so the in-memory module graph stayed old, which for an upgrade like "the code on
+  disk changed" amounts to not installing at all. It now **really re-execs itself**: `spawn` a
+  new process running the new dist, and the parent waits in a suspended state and exits after
+  the child exits.
+- **The spinner during `/update` was "frozen"** — `readDistTags()` used `spawnSync`, blocking
+  the event loop synchronously, so Ink's animation timer stalled for 1–3 seconds. Changed to an
+  async `spawn` with a 20 second timeout (no more hanging indefinitely when offline).
+- **The spinner label was "Processing…"** — that label comes from `phaseLabel(session.phase)` in
+  the generation phase, but `/update` has no generation turn at all, so `phase` was `null` and
+  the fallback became the generic "Processing…", having nothing to do with what was happening.
+  Added `busySpinnerLabel()`: with a generation phase it is still driven by the SDK phase, and
+  during blocking commands it shows `/update running…` instead.
+
+### 🔧 Improvements
+
+- **`--prefer-online` on both the query and the install** — npm caches the packument, so right
+  after a release `npm view` may still return old dist-tags and mistake "there is a new version"
+  for "already the latest" (this happened on release day); the install side likewise. Also added
+  `--no-fund` to cut noise.
+
+### ⚠️ Two terminal gotchas (written in code comments)
+
+- **The restart must exit inside the suspended state**: `beginSuspend()` in `suspendTerminal`
+  turns raw mode off, and `endSuspend()` turns it back on; if `process.exit` is called after
+  `suspendTerminal` returns, the terminal stays in raw mode and every key is garbage after
+  returning to the shell.
+- **`disableMouseTracking()` must be called before the restart**: mouse reporting is toggled by
+  `mount()` per Ink instance, and the instance has not exited during suspension — without
+  turning it off, if the child process dies abnormally, the terminal keeps writing wheel events
+  as escape sequences.
+
+### 📖 Docs
+
+- `README.md` / `README.zh.md` / `docs/{zh,en}/getting-started.md` — the `/update` description is
+  corrected: the original said "installs the alpha channel globally", while it actually picks
+  the highest semver among **all** dist-tags (so alpha is installed when it is newer than
+  `latest`), and "shows progress step by step, one-key restart after install" was added.
+
+### ✅ Tests
+
+- Full run **49 files / 657 cases passing** (649 cases at alpha.25), `tsc --noEmit` 0 errors.
+- `/update` cases went from 6 to 11: added "restart after confirmation + save before restart",
+  "declining the restart neither saves nor restarts", "a new session with no user messages is
+  not saved", "three progress notices reported in order", "the terminal header contains
+  version/location/command", "the query carries `--prefer-online`".
+- 3 cases added for `busySpinnerLabel`, including a regression guard: the label **must not** fall
+  back to "Processing…" while a command is running.
 
 ## [1.0.0-alpha.25] - 2026-10-29
 
-> 升级到 SDK `1.0.0-alpha.23`（面向模型与用户的文案全面英文化），
-> 并补上缺失的 `LICENSE` 文件。
-
-### 🔧 依赖
+> Upgraded to SDK `1.0.0-alpha.23` (model-facing and user-facing copy is now fully in English),
+> and added the missing `LICENSE` file.
 
-- `@ai-zen/agents-sdk` `1.0.0-alpha.22` → `1.0.0-alpha.23`。
+### 🔧 Dependencies
 
-### 💬 行为变化（来自 SDK）
+- `@ai-zen/agents-sdk` `1.0.0-alpha.22` → `1.0.0-alpha.23`.
 
-- **SDK 内置文案全部改为英文** —— 工具 schema 描述、出厂系统提示词、注入语、
-  工具返回值、错误信息、出厂 Skill 与 catalog 数据一律固定英文，SDK 内不再有
-  任何中文文案，也**不引入 i18n**（理由：`tokenThresholds` / `maxToolOutput`
-  都是绝对量，工具 schema 换语言就是另一组 token 数，性能基准会失去单一变量）。
-- **回复语言改为「跟随用户」** —— 出厂系统提示词里「请用中文回复」被替换为
-  `Always reply in the same language the user writes in.`，按每条消息自适应。
-- **对 CLI 无破坏性影响** —— CLI 自带 `i18n` 字典（`src/i18n`），界面文案与
-  通知全部由 CLI 自己渲染，不解析 SDK 的文案字符串；对 SDK 的用法仅限于类型导入
-  与 `AgentRepository` / `ConfigManager` / `setLogger` / `HandoffService` 等结构性
-  API。49 文件 / 649 例测试在升级前后逐项一致。
+### 💬 Behavior changes (from SDK)
 
-### 📄 许可证
+- **All built-in SDK copy is now English** — tool schema descriptions, the factory system prompt,
+  injected wording, tool return values, error messages, factory Skills and catalog data are all
+  fixed English; the SDK no longer contains any Chinese copy, and **no i18n is introduced**
+  (reason: `tokenThresholds` / `maxToolOutput` are absolute quantities, and changing the language
+  of tool schemas means a different set of token counts, which would remove the single variable
+  from performance benchmarks).
+- **Reply language becomes "follow the user"** — "please reply in Chinese" in the factory system
+  prompt is replaced by `Always reply in the same language the user writes in.`, adapting per
+  message.
+- **No breaking impact on the CLI** — the CLI ships its own `i18n` dictionary (`src/i18n`), and
+  all UI copy and notices are rendered by the CLI itself without parsing SDK copy strings; SDK
+  usage is limited to type imports and structural APIs such as `AgentRepository` /
+  `ConfigManager` / `setLogger` / `HandoffService`. The 49 files / 649 test cases are identical
+  item by item before and after the upgrade.
 
-- **新增 `LICENSE`** —— 此前 `package.json` 声明了 `"license": "MIT"`，但仓库里
-  没有许可证正文，npm 包内自然也没有。现补上 MIT 全文（与 `agents` 仓库根
-  `LICENSE` 一致，`Copyright (c) 2024 LZQCN`）。
-  `files` 字段未改动：npm 对 `LICENSE` 强制包含，`npm pack` 已确认 tarball 内含该文件。
+### 📄 License
 
-### 📖 文档
+- **Added `LICENSE`** — `package.json` declared `"license": "MIT"` before, but the repository
+  had no license text, and naturally the npm package did not either. The full MIT text is added
+  now (identical to `LICENSE` at the root of the `agents` repository,
+  `Copyright (c) 2024 LZQCN`). The `files` field is unchanged: npm includes `LICENSE` forcibly,
+  and `npm pack` confirmed the tarball contains the file.
 
-- `docs/{zh,en}/getting-started.md` —— 运行时依赖清单的 SDK 版本从 `1.0.0-alpha.18`
-  订正为 `1.0.0-alpha.23`，`@ai-zen/agents-core` 从 `^4.5.2` 订正为 `^4.5.3`
-  （与实际 `package.json` 对齐）。
-- `docs/{zh,en}/index.md` —— 许可证一节改为指向仓库根的 `LICENSE` 文件，并说明全文
-  随包一同发布。
-- `README.md` / `README.zh.md` —— 启动界面示例中的版本号同步为 `1.0.0-alpha.25`。
+### 📖 Docs
 
-### ✅ 测试
+- `docs/{zh,en}/getting-started.md` — the SDK version in the runtime dependency list is corrected
+  from `1.0.0-alpha.18` to `1.0.0-alpha.23`, and `@ai-zen/agents-core` from `^4.5.2` to `^4.5.3`
+  (aligned with the actual `package.json`).
+- `docs/{zh,en}/index.md` — the license section now points to the `LICENSE` file at the
+  repository root and states that the full text ships with the package.
+- `README.md` / `README.zh.md` — the version number in the startup screen example is synced to
+  `1.0.0-alpha.25`.
 
-- 全量 **49 文件 / 649 例通过**，`tsc --noEmit` 0 错误，与 alpha.24 基线一致
-  （本次仅升依赖，无源码改动）。
+### ✅ Tests
 
+- Full run **49 files / 649 cases passing**, `tsc --noEmit` 0 errors, consistent with the alpha.24
+  baseline (this release only bumps dependencies, no source changes).
 ## [1.0.0-alpha.24] - 2026-10-28
 
-> 三件事：**看不见的上下文**现在看得见了（不进上下文的消息划删除线），
-> 升级有了 `/update`，中断策略从写死的常量变成可配置项。
-
-### ✨ 新功能
-
-- **不进上下文的消息划删除线** —— 判据与 core 的 `formatHistory()` 同源
-  （`status == undefined || Completed` 且非 `omit`），而策略早已在 `Agent.run()` 收尾时
-  结算进字段（`keep`→`Completed`、`drop`→`Aborted`，工具轮次 `fill`→`Completed`、
-  `drop`→`omit`），渲染层不重复推导策略。
-  - 流式中那条（`Pending` / `Writing`）不划线：它在 `formatHistory` 里同样不在，但那是
-    「尚未」而不是「被丢弃」。
-  - `hidden` 仍彻底不渲染；`omit` 不再让消息凭空消失（原先 `hidden || omit` 一起
-    `return []`，用户中断一轮工具调用后那几条会无声蒸发）。
-- **`/update`** —— 装 registry 上最新的发布版：读 `npm view @ai-zen/cli dist-tags --json`，
-  取**所有 tag 里 semver 最大**的那个。只认 `latest` 会把跑 alpha 的用户降级（实际发布
-  状态就是 `latest 0.9.0 < alpha 1.0.0-alpha.23`）；目标不比当前进程新则不装（本地开发版
-  不会被「升级」降级）。安装走 `suspendTerminal` + `stdio: inherit`，npm 的进度与报错直接
-  打在真实终端上；装完读 `npm root -g` 下的 `package.json` 判定版本（`npm view` 查 registry
-  有几分钟延迟），并提示重启（内存里还是旧代码，不自动重启以免丢会话）。
-- **中断策略可配置** —— SDK 升级到 `1.0.0-alpha.22`：`AppConfig` 新增
-  `abortedMessageStrategy`（`keep` / `drop`，出厂 `keep`）与 `abortedToolRoundStrategy`
-  （`fill` / `drop`，出厂 `fill`），`createAgent()` 不传参数时直接读 `scope.config`。
-  配置中心「默认项」新增两项即可切换；它们只在**建 Agent** 时读取，所以关掉配置中心时
-  宿主会自动重建会话（`WizardCloseResult.sessionOptionsChanged`），不必再手敲 `/reload`。
-
-### ♻️ 重构
-
-- **CLI 不再写死 `abortedMessageStrategy: "keep"`** —— 写死会盖掉用户的选择。现在配置即
-  事实：`config.json` 里写什么就用什么，`agent-creator` 只负责建 Agent。
-- **配置迁移补齐策略字段**（SDK 侧）—— 缺失或非法值一律写回出厂默认并落盘一次，各端不必
-  各自 `?? "keep"` 兜底。
-- **新增 `src/version-compare.ts`** —— semver 比较（核心段 / 预发布标识 / 忽略 build），
-  供 `/update` 从多个 dist-tag 里挑最新；不为此引 `semver` 依赖。
-
-### ✅ 测试
-
-- 全量 **49 文件 / 649 例通过**（alpha.23 时 626 例）。
-- 新增：`version-compare.test.ts` 10 例、`chat-commands-update.test.ts` 6 例（tag 选择、
-  已是最新不安装、安装失败、npm 缺失、dist-tags 查不到），`messageToLines` 删除线 3 例，
-  策略 setter / 向导两屏 / 宿主重载 4 例。
-- 端到端实测（临时 `AI_ZEN_DIR`）：出厂默认 `config: keep fill → agent: keep fill`，
-  改成 drop 并重建后 `config: drop drop → agent: drop drop`。
-
-### 🔧 依赖
-
-- `@ai-zen/agents-sdk` `1.0.0-alpha.21` → `1.0.0-alpha.22`。
+> Three things: **invisible context** is now visible (messages that never enter the context are struck through),
+> upgrades have `/update`, and the abort strategy went from a hardcoded constant to a configurable option.
+
+### ✨ New features
+
+- **Messages that never enter the context are struck through** — the predicate shares its source with core's
+  `formatHistory()` (`status == undefined || Completed` and not `omit`), while the strategy was already settled into the
+  field when `Agent.run()` wraps up (`keep`→`Completed`, `drop`→`Aborted`; tool rounds `fill`→`Completed`,
+  `drop`→`omit`), so the render layer does not re-derive the strategy.
+  - The streaming one (`Pending` / `Writing`) is not struck through: it is absent from `formatHistory` as well, but that
+    means "not yet" rather than "dropped".
+  - `hidden` still does not render at all; `omit` no longer makes messages vanish into thin air (previously `hidden || omit`
+    both `return []`, so after a user aborted a round of tool calls those messages evaporated silently).
+- **`/update`** — installs the newest published version from the registry: reads
+  `npm view @ai-zen/cli dist-tags --json` and takes the one with **the highest semver across all tags**. Honoring only
+  `latest` would downgrade users running alpha builds (the actual published state is
+  `latest 0.9.0 < alpha 1.0.0-alpha.23`); if the target is not newer than the current process, nothing is installed
+  (a local dev build is not "upgraded" into a downgrade). Installation goes through `suspendTerminal` +
+  `stdio: inherit`, so npm progress and errors land directly on the real terminal; afterwards the version is read from
+  the `package.json` under `npm root -g` (`npm view` against the registry lags by a few minutes), and a restart is
+  suggested (old code is still in memory; no automatic restart, to avoid losing the session).
+- **Configurable abort strategy** — SDK upgraded to `1.0.0-alpha.22`: `AppConfig` gains
+  `abortedMessageStrategy` (`keep` / `drop`, factory `keep`) and `abortedToolRoundStrategy`
+  (`fill` / `drop`, factory `fill`); `createAgent()` reads `scope.config` directly when no arguments are passed.
+  Two new items under the configuration center's "Defaults" are enough to switch them; they are read only **when an
+  Agent is created**, so closing the configuration center makes the host rebuild the session automatically
+  (`WizardCloseResult.sessionOptionsChanged`), with no need to type `/reload` by hand.
+
+### ♻️ Refactors
+
+- **CLI no longer hardcodes `abortedMessageStrategy: "keep"`** — hardcoding overrides the user's choice. Configuration
+  is now the source of truth: whatever `config.json` says is used, and `agent-creator` only creates the Agent.
+- **Config migration backfills the strategy fields** (SDK side) — missing or invalid values are always written back as
+  the factory default and persisted once, so no client needs its own `?? "keep"` fallback.
+- **New `src/version-compare.ts`** — semver comparison (core segments / prerelease identifiers / build ignored),
+  used by `/update` to pick the newest among multiple dist-tags; no `semver` dependency is pulled in for it.
+
+### ✅ Tests
+
+- Full run: **49 files / 649 cases passed** (626 cases at alpha.23).
+- New: `version-compare.test.ts` 10 cases, `chat-commands-update.test.ts` 6 cases (tag selection, already newest so
+  no install, install failure, npm missing, dist-tags unavailable), `messageToLines` strikethrough 3 cases,
+  strategy setters / two wizard screens / host reload 4 cases.
+- End-to-end check (temporary `AI_ZEN_DIR`): factory default `config: keep fill → agent: keep fill`; after switching
+  to drop and rebuilding, `config: drop drop → agent: drop drop`.
+
+### 🔧 Dependencies
+
+- `@ai-zen/agents-sdk` `1.0.0-alpha.21` → `1.0.0-alpha.22`.
 
 ## [1.0.0-alpha.23] - 2026-10-28
 
-> 子 Agent 从「通知栏里报一句运行中」升级为一条**可切换的栏目**：主 / 子 Agent
-> 各自的消息分栏展示，执行状态内联在标签上。
-
-### ✨ 新功能
-
-- **主子 Agent 切换栏目** —— 对话中出现子 Agent 时，消息列表下方多出一条栏目
-  `主AGENT  ◈子AGENT1  ◈子AGENT2`，当前项背景色高亮；`←` / `→` 切换后，消息列表
-  即换成该 Agent 自己的对话。
-  - **数据源**：core 的 `onSubAgentStart` 钩子给出子 Agent 实例；`AgentTool` /
-    `AgentToolLazy` 在委派结束后**不销毁**实例，`messages` 始终可读——所以只要存下
-    引用，就能回看子 Agent 的完整过程（思考、工具调用、多轮推理），而不只是最终结果。
-  - **生命周期与内循环对齐**：子 Agent 是内循环里工具调用的产物，本轮内循环全部结束时
-    （`send` 收尾；异常 / 中止走 `finally`，同样清）整条栏目清空，展示序号归零。
-  - **执行状态内联**：`◈` + 颜色（运行中蓝、完成绿、失败红），运行中的蓝点每 500ms
-    在亮 / 暗之间闪烁。**不再**往通知栏推「子任务运行中 / 已完成」——那会让通知栏
-    凭空多出一行，整帧高度跟着跳。
-  - **`←` / `→` 按状态分流**：输入框为空（光标停在 0，左右键本无事可做）或生成中
-    （输入框已被 Spinner 顶替）时切换栏目；输入框有内容时仍是移光标，不牺牲任何编辑能力。
-  - 发送消息时自动切回主 Agent 视图（否则用户看不到自己的提问）。
-
-### 🐛 修复
-
-- **`/new`、`/reload` 后子 Agent 残留** —— 这两个操作只换 `agent`、不重建 `ChatSession`
-  实例，子 Agent 视图不会自然消失；现随 `reset` / `reload` / `migrate` 显式清空。
-- **视图 id 与展示序号混用** —— 序号每轮归零，若 id 也跟着归零，下一轮的 `sub-1` 会与
-  上一轮同名，而选中态按 id 匹配，残留的选中 id 会「接上」新出现的子 Agent。现拆成
-  两个计数器：id 永久递增、只让展示序号归零。
-
-### ♻️ 重构
-
-- **修正 `sub-agent-guard-plugin` 的过时注释** —— 原注释称 `call_skill_sub_agent`
-  「不分发 onSubAgentStart、暂不覆盖」，但 skill 子 Agent 统一到 `AgentToolLazy` 之后
-  它其实是被覆盖的（core 只有两条委派路径，均分发该钩子）。这条错注释在本次实现
-  前期直接误导了对覆盖面的判断。
-
-### ✅ 测试
-
-- 全量 **47 文件 / 626 例通过**（发布 alpha.22 时 604 例）。
-- 新增护栏：栏目条目顺序与 1 空格 padding、符号 `◈` 与三色映射、超宽仍单行、
-  按序编号、结束转 `done`、出错转 `failed` 且不被 `end` 覆盖、进度不进通知栏、
-  执行期间有内容而收尾后清空、`reset` / `reload` 也清空、`←`/`→` 切换数据源与
-  输入非空时不切换、布局高度与 IME 偏移。
-- 破坏性验证：去掉 `computeChatLayout` 里的 `agentTabLines` → 布局用例红
-  （`expected 4 to be 5`）；命令说明写长 → 宽度护栏红（`expected 62 to be <= 36`）。
+> Sub-agents went from "one line in the notice bar saying it is running" to a **switchable tab row**: main and
+> sub-agent messages are shown in separate columns, with execution status inlined on the labels.
+
+### ✨ New features
+
+- **Main/sub-agent tab row** — when a sub-agent appears in the conversation, a tab row appears below the message
+  list, `MAIN AGENT  ◈SUB AGENT1  ◈SUB AGENT2`, with the current item highlighted by background color; after
+  switching with `←` / `→`, the message list is replaced by that Agent's own conversation.
+  - **Data source**: core's `onSubAgentStart` hook hands over the sub-agent instance; `AgentTool` /
+    `AgentToolLazy` **do not destroy** the instance after delegation ends, so `messages` is always readable — keeping
+    a reference is enough to review the sub-agent's whole process (reasoning, tool calls, multi-round inference),
+    not just the final result.
+  - **Lifecycle aligned with the inner loop**: a sub-agent is a product of a tool call inside the inner loop; when
+    this round's inner loop ends entirely (`send` wraps up; exceptions / aborts go through `finally` and clear as
+    well) the whole tab row is emptied and the display index resets to zero.
+  - **Inline execution status**: `◈` + color (running blue, done green, failed red); the running blue dot blinks
+    between bright and dim every 500ms. It **no longer** pushes "sub-task running / done" into the notice bar —
+    that would add a row out of nowhere and make the whole frame height jump.
+  - **`←` / `→` routed by state**: switches tabs when the input line is empty (cursor at 0, where left/right have
+    nothing to do) or while generating (the input line has been replaced by the spinner); when the input line has
+    content the keys still move the cursor, sacrificing no editing capability.
+  - Sending a message switches back to the main Agent view automatically (otherwise the user cannot see their own
+    question).
+
+### 🐛 Fixes
+
+- **Sub-agents left over after `/new` and `/reload`** — those two operations only swap `agent` and do not rebuild
+  the `ChatSession` instance, so the sub-agent view does not disappear on its own; it is now cleared explicitly on
+  `reset` / `reload` / `migrate`.
+- **View id and display index mixed up** — the index resets every round; if the id reset too, next round's `sub-1`
+  would share a name with the previous round's, and since selection is matched by id, a leftover selected id would
+  "latch onto" a newly appeared sub-agent. They are now two counters: the id increments forever, and only the
+  display index resets.
+
+### ♻️ Refactors
+
+- **Fixed the outdated comment in `sub-agent-guard-plugin`** — the original comment claimed `call_skill_sub_agent`
+  "does not dispatch onSubAgentStart, not covered yet", but after skill sub-agents were unified onto `AgentToolLazy`
+  it in fact is covered (core has only two delegation paths, both dispatch the hook). That wrong comment directly
+  misled the assessment of the covered surface early in this implementation.
+
+### ✅ Tests
+
+- Full run: **47 files / 626 cases passed** (604 cases when alpha.22 was released).
+- New guards: tab entry order and 1-space padding, the `◈` symbol and the three-color mapping, still a single line
+  when over-wide, sequential numbering, switching to `done` at the end, switching to `failed` on error without being
+  overwritten by `end`, progress kept out of the notice bar, content present during execution but cleared after
+  wrapping up, cleared on `reset` / `reload` too, `←`/`→` switching the data source and not switching when the input
+  is non-empty, layout height and IME offset.
+- Break checks: removing `agentTabLines` from `computeChatLayout` → layout case red
+  (`expected 4 to be 5`); making a command description longer → width guard red (`expected 62 to be <= 36`).
 
 ## [1.0.0-alpha.22] - 2026-10-28
 
-> 这一版是**整体代码评审 + 治本修复**的成果：先通读 `src/` 全部非测试代码做全量评审
-> （P0~P3 共 30 项，其中 3 项经实测查证为非问题、未改代码），再按「能查根因就查、
-> 不加兜底/不吞异常/不做多余校验」的原则逐项落地，最后补上 Ctrl+C 中断交接。
+> This release is the result of a **full code review plus root-cause fixes**: first a complete review of all
+> non-test code in `src/` (30 items P0~P3, 3 of them verified by experiment to be non-issues and left unchanged),
+> then each item landed on the principle "trace the root cause if you can, no defensive fallbacks / no swallowed exceptions / no redundant validation", and finally Ctrl+C abort for handoff was added.
 
-### 🐛 修复
+### 🐛 Fixes
 
-- **折行按字素簇计宽，修掉 emoji 撑破整帧布局（P0）** —— `toCells` / `wrapSpans` / `clipSpans` / `toChars` / `segmentsWidth` 原先按 **code point** 遍历文本：VS16 序列（`✌️` = `U+270C U+FE0F`）被算成 1 列而实际占 2 列 → 行超宽 → Ink 在渲染期二次折行 → 实际帧高比 `computeChatLayout` 预算多一行 → **输入框被顶出屏幕**；ZWJ 家族（`👨‍👩‍👧`）被算成 6 列而实际占 2 列 → 每两个簇就折一次。现在全部改走 `graphemes()` + `clusterWidth()`，与 Ink 排版同一把尺子。
-- **阈值写入不再整对象替换** —— `updateModel` 是浅合并，此前调用方直接构造 `{ handoff, guard }`，会把 `tokenThresholds` 里其它字段（SDK 后续新增的压缩阈值等）一并清空。新增 `mergeTokenThresholds()`，所有阈值写入走它。
-- **`/migrate` 之后屏幕一片空白** —— 迁移用 `prune` 策略把 `messages` 砍到 1~2 条，但 `transcriptFrom` 仍停在旧值，`messages.slice(transcriptFrom)` 恒为空：迁移成功、上下文有内容，屏幕上却什么都没有。现在迁移成功后重置转录显示起点（同 `/new` 的做法）。
-- **通知栏只剩最后一条** —— 订阅端是单值 state，同一批摘要 / 分阶段进度会被逐条覆盖。改为保留最近 4 条的队列（`MAX_NOTICE_HISTORY`），并让同一批摘要合成**一条多行**，既全部显示又只占一个槽位；排版决策（折行 / 多条让位 / 条内截断）收进 `notice.ts` 纯逻辑，新增可独立渲染的 `NoticeBar`。
-- **`ai hook --help` 以非零码退出** —— 「想看用法」与「写错了子动作」此前混为一谈。现在 `ai hook` / `ai hook --help` 正常输出、退出码 0；`ai hook boom` 报错并 exit 1。`ai help` / `ai version` 单词形式等价于对应选项，但**只在它是唯一参数时**判定（`ai help me refactor this` 仍是在提问）。
-- **`ai hook install` 漏清重复块** —— rc 里可能残留多个钩子块（老版本 + 新版本各写一次），旧实现只看第一块，于是「第一块恰好是最新版 → 判定已安装 → 后面的旧块永远留着」。改为取全部块，只有「恰好一块且内容一致」才算已安装。
-- **会话落盘不是原子写** —— SDK 的 `EntityRepository.write()` 是直接覆盖，进程在写一半时被杀（Ctrl+C / OOM / 断电）就留下半截 JSON，`read()` 解析失败返回 null，**整段历史就此丢失**（会话文件可达数 MB，写入窗口并不小）。改为「写 `<id>.json.tmp` → `rename`」，任何时刻读到的要么是旧文件、要么是完整新文件。
-- **Ctrl+C 无法中断会话交接** —— 两处根因：`summary` 模式的独立模型请求没有任何取消点；`self` 模式虽能被 `agent.abort()` 打断，但 abort 不抛错，中止后被误判成「模型没写出文档」，于是**重试一轮、再降级 summary 再跑一轮**——用户以为取消了，实际多烧两轮全量输入。现在交接接受 `AbortSignal`：取消时抛 `HandoffAbortedError`、**不降级不重试**、清掉写了一半的文档、`migrate` 也不改动会话历史；TUI 里 Ctrl+C 会先走交接的取消通道，提示「已取消」而不是报错。（依赖 `@ai-zen/agents-sdk` 同名改动）
-- **通知栏文案整体右移 2 列** —— 缩进被加了两遍：`NoticeBar` 的 `paddingX={1}` 一层，`notice.ts` 又硬拼 `  ` 一层，于是文案比同屏的分隔线与 `❯` 输入行多缩 2 列；迁移一次推 4 条通知时最刺眼。现在横向定位只归容器管，逻辑层只管折行。顺带去掉 `· ` / `✖ ` 前缀——语气已由 `tone` 着色表达（error 走红色），符号纯属占位；多行通知每行都从行首开始。配置更新的子项摘要改为「一个汉字宽度」（2 列）缩进，不再带项目符号。
+- **Line wrapping measures width by grapheme cluster, fixing emoji blowing up the whole frame layout (P0)** — `toCells` / `wrapSpans` / `clipSpans` / `toChars` / `segmentsWidth` used to walk the text by **code point**: a VS16 sequence (`✌️` = `U+270C U+FE0F`) was counted as 1 column although it occupies 2 → the line got too wide → Ink wrapped a second time while rendering → the actual frame was one row taller than `computeChatLayout` had budgeted → **the input line was pushed off screen**; ZWJ families (`👨‍👩‍👧`) were counted as 6 columns although they occupy 2 → a wrap every two clusters. All of it now goes through `graphemes()` + `clusterWidth()`, the same ruler Ink lays out with.
+- **Threshold writes no longer replace the whole object** — `updateModel` is a shallow merge, and callers used to construct `{ handoff, guard }` directly, which wiped every other field in `tokenThresholds` (compression thresholds the SDK added later, and so on). New `mergeTokenThresholds()`; all threshold writes go through it.
+- **Blank screen after `/migrate`** — migration uses the `prune` strategy to cut `messages` down to 1~2, but `transcriptFrom` stayed at its old value, so `messages.slice(transcriptFrom)` was always empty: the migration succeeded and the context had content, yet the screen showed nothing. The transcript display origin is now reset after a successful migration (the same approach as `/new`).
+- **Notice bar kept only the last entry** — the subscriber side is a single-value state, so a batch of summaries / staged progress overwrote each other one by one. It is now a queue keeping the most recent 4 (`MAX_NOTICE_HISTORY`), and a batch of summaries is merged into **one multi-line** entry, so everything is shown while occupying a single slot; layout decisions (wrapping / yielding when there are several / truncation within an entry) moved into `notice.ts` as pure logic, plus a new independently renderable `NoticeBar`.
+- **`ai hook --help` exits with a non-zero code** — "wanted to see usage" and "wrote the wrong sub-action" used to be conflated. Now `ai hook` / `ai hook --help` print normally and exit 0; `ai hook boom` reports an error and exits 1. The bare-word forms `ai help` / `ai version` are equivalent to the corresponding options, but **only when the word is the sole argument** (`ai help me refactor this` is still a question).
+- **`ai hook install` failed to clean up duplicate blocks** — an rc file may hold several hook blocks (an old version and a new one each wrote once), and the old implementation looked only at the first, so "the first block happens to be the newest → judged installed → the old blocks behind it stay forever". It now takes all blocks and counts as installed only when there is exactly one block and its content matches.
+- **Conversation persistence was not an atomic write** — the SDK's `EntityRepository.write()` overwrites directly, so a process killed mid-write (Ctrl+C / OOM / power loss) leaves half a JSON, `read()` fails to parse and returns null, and **the whole history is lost** (conversation files can reach several MB, so the write window is not small). It now writes `<id>.json.tmp` → `rename`, so any read at any moment sees either the old file or a complete new one.
+- **Ctrl+C could not abort a session handoff** — two root causes: the standalone model request in `summary` mode had no cancellation point at all; `self` mode could be interrupted by `agent.abort()`, but abort does not throw, so after the abort it was misjudged as "the model did not write a document", and the code **retried one round, then downgraded to summary and ran another round** — the user thought they had cancelled while two more full-input rounds burned. Handoff now accepts an `AbortSignal`: cancellation throws `HandoffAbortedError`, **no downgrade and no retry**, the half-written document is cleaned up, and `migrate` leaves the conversation history untouched; in the TUI, Ctrl+C first goes through the handoff's cancellation path and reports "cancelled" instead of an error. (Depends on the same-named change in `@ai-zen/agents-sdk`.)
+- **Notice bar text shifted right by 2 columns** — the indent was applied twice: one layer from `NoticeBar`'s `paddingX={1}`, another layer from `notice.ts` hard-concatenating two spaces, so the text sat 2 columns further right than the separator and the `❯` input row on the same screen; it was most glaring when a migration pushed 4 notices at once. Horizontal positioning is now owned solely by the container and the logic layer only wraps. The `· ` / `✖ ` prefixes were dropped along the way — tone is already expressed by `tone` coloring (error goes red), so the symbols were pure placeholders; every line of a multi-line notice now starts at column 0. The per-item summary of configuration updates is now indented by one CJK character width (2 columns) instead of carrying a bullet.
 
-### ✨ 新功能
+### ✨ New features
 
-- **`/load` 列表显示会话摘要** —— 会话 id 是时间戳（`chat_2026_10_28_00_56_34`），直接当标签列出来完全分不清哪条是哪条。现在取首条用户消息的第一行作为标签。实现上先只 `stat`、排序后**只为将要显示的那几条**解析内容，会话攒到上百条时 `/load` 也不会被拖慢。
+- **`/load` list shows conversation summaries** — a conversation id is a timestamp (`chat_2026_10_28_00_56_34`), so listing them directly as labels made it impossible to tell which was which. The first line of the first user message is now taken as the label. Implementation-wise it only `stat`s first, and after sorting parses content **only for the few entries about to be displayed**, so `/load` is not slowed down even when conversations pile up into the hundreds.
 
-### ♻️ 重构
+### ♻️ Refactors
 
-- **`chat.tsx` 五步拆 hook：1085 → 830 行** —— 只留会话生命周期与渲染组装，其余拆成 5 个可单测的 hook：`use-chat-viewport`（视口与滚动换算，所有动作经 `clampViewTop()`）、`use-overlays`（确认框 / 选择器的 resolve 生命周期，关状态与结算在同一次函数式更新里完成）、`use-wizard-host`（向导宿主，依赖注入）、`use-input-editing`（文本 / 光标 / 历史 / kill ring / undo / stash）、`common-keys`（两个 `useInput` 共用的键位 + Ctrl+D 双击退出）。
-- **斜杠命令改为表驱动** —— 557 行的 `switch` 换成 `HANDLERS: Record<CommandName, CommandHandler>` + 18 个处理器：「新增命令忘了写处理器」从运行时静默落到「未知命令」变成**编译错误**；命令名解析只剩 registry 一处（`parseCommandInput` / `parseCommandArgs` 共用同一套切分），`blocksInput` 成为命令元数据而不再是宿主白名单。
-- **向导字段工厂去噪** —— `commit` / `toggle` 签名放宽为 `string | null | Promise<string | null>`，删掉 23 处 `Promise.resolve(...)` 噪音；`nameField()` / `endpointIdField()` / `customPatch()` 等收掉 8 处重复段；`DetailFieldKind` 的 `"map"` 改名 `"open"`（语义本就是「按 Enter 进子屏」）。
-- **会话落盘收敛为唯一入口** —— 「读旧记录拿 `createdAt` → 写 → 更新指针」原先在 5 个地方各写一遍并且已经漂移（`saveConversation()` 漏写 `cwd`、stdio 的 `--save` 不更新指针、还写了一个已废弃的 `modelId`）。收敛到 `persistConversation()`，各处差异只剩「是否更新指针」一个显式开关。
-- **初始化与单例改为缓存 Promise** —— `getScope()` / `ensureConfigDir()` 缓存实例时，`if (x) return x` 之后到赋值之间有一段 `await`，并发调用会一起穿透（建出两个 Scope → MCP 双连接、双份工具发现）。改缓存 Promise 让并发调用共享同一次初始化，失败不缓存。
-- **删死代码与不可达兜底** —— 死字段 `ConversationContext.running|input|shouldSend`、从未启用的 i18n 复数机制（`pluralRules` + `key_one/_other`）、`noticeLines()` 末尾不可达的截断兜底（穷举 84 组证明从不执行）、`pick(direct, …)` 从没人传过的参数、`useChatViewport` 零引用的 `scrollTo` 导出、所有命令都空转一遍的 `parseHandoffMode`；`cwd` / `previewLimit` 从「可选 + 内部兜底」收成必填，兜底只保留在 SDK 可选字段的真实边界上。
-- **命令说明文案精简** —— 斜杠菜单与 `/help` 都是一行一条，说明过长会把整行塞满。按「只写做什么、不写实现细节」重写：砍掉内部概念（`scope`、写入配置、重建会话）与冗余限定词，括号只留用户必须预期的后果（替换会话 / 重建 / 不切换会话）。中文最长 59 → **34**、英文 73 → **49**（平均 19.3 / 33.8），`/mcp` 从全场最长退到中游。
-- **权限四维上屏走词条** —— `tools` / `skills` / `mcps` / `subagents` 是配置里的键，直接上屏等于把内部标识暴露给用户，映射到 `perm.*` 词条。
+- **`chat.tsx` split into five hooks: 1085 → 830 lines** — only conversation lifecycle and render assembly are left; the rest became 5 unit-testable hooks: `use-chat-viewport` (viewport and scroll arithmetic, every action going through `clampViewTop()`), `use-overlays` (resolve lifecycle of confirm boxes / selectors, with closing and settling done in the same functional update), `use-wizard-host` (wizard host, dependency injection), `use-input-editing` (text / cursor / history / kill ring / undo / stash), `common-keys` (keybindings shared by the two `useInput` handlers + double Ctrl+D to quit).
+- **Slash commands are table-driven** — the 557-line `switch` became `HANDLERS: Record<CommandName, CommandHandler>` + 18 handlers: "added a command but forgot the handler" changed from silently falling through to "unknown command" at runtime into a **compile error**; command-name parsing lives only in the registry (`parseCommandInput` / `parseCommandArgs` share one tokenizer), and `blocksInput` became command metadata instead of a host whitelist.
+- **Wizard field factory de-noised** — the `commit` / `toggle` signatures were widened to `string | null | Promise<string | null>`, removing 23 `Promise.resolve(...)` noise sites; `nameField()` / `endpointIdField()` / `customPatch()` and friends absorbed 8 duplicated chunks; `DetailFieldKind`'s `"map"` was renamed to `"open"` (the semantics were always "Enter opens a sub-screen").
+- **Conversation persistence converged into a single entry point** — "read the old record for `createdAt` → write → update the pointer" used to be written out in 5 places and had already drifted (`saveConversation()` missing `cwd`, stdio's `--save` not updating the pointer, and a deprecated `modelId` still being written). Everything converges on `persistConversation()`, and the only remaining difference is one explicit switch: whether to update the pointer.
+- **Initialization and singletons cache promises** — when `getScope()` / `ensureConfigDir()` cached instances, there was an `await` between `if (x) return x` and the assignment, so concurrent calls fell through together (two Scopes built → MCP connected twice, tool discovery done twice). Caching the promise lets concurrent calls share one initialization; failures are not cached.
+- **Dead code and unreachable fallbacks removed** — the dead fields `ConversationContext.running|input|shouldSend`, the never-enabled i18n plural machinery (`pluralRules` + `key_one/_other`), the unreachable truncation fallback at the end of `noticeLines()` (84 combinations enumerated to prove it never runs), the `pick(direct, …)` parameter nobody ever passed, the zero-reference `scrollTo` export of `useChatViewport`, and `parseHandoffMode`, which every command ran to no effect; `cwd` / `previewLimit` went from "optional + internal fallback" to required, with fallbacks kept only at the real boundary of the SDK's optional fields.
+- **Command descriptions trimmed** — the slash menu and `/help` are one line per command, and an over-long description fills the whole line. Rewritten on the principle "say what it does, not how it is implemented": internal concepts dropped (`scope`, writing config, rebuilding the session) along with redundant qualifiers, and parentheses keep only the consequences the user must expect (replaces the conversation / rebuilds / does not switch conversation). Longest Chinese 59 → **34**, English 73 → **49** (mean 19.3 / 33.8), and `/mcp` fell from the longest to mid-pack.
+- **The four permission dimensions go on screen through dictionary entries** — `tools` / `skills` / `mcps` / `subagents` are keys in the configuration, and showing them directly would expose internal identifiers to the user, so they map to `perm.*` entries.
 
-### ⚡ 性能
+### ⚡ Performance
 
-- **`graphemes()` 加快速路径** —— 折行是每帧热路径，但绝大多数文本（ASCII / CJK / 代码）每一簇就是一个 code point，不需要 `Intl.Segmenter`。先用一次正则判定「是否可能出现多 code point 合为一簇」（astral / CRLF / ZWNJ·ZWJ / 韩文组合字母 / `\p{M}` 组合附加符），命中才走分词器。一帧 60 行中文：**655 µs → 52 µs**（省 604 µs，帧预算 1%）。判定条件宁可误报不可漏报，新增 6 例护栏覆盖各类形态。
+- **Fast path for `graphemes()`** — wrapping is a per-frame hot path, but for the vast majority of text (ASCII / CJK / code) every cluster is a single code point and `Intl.Segmenter` is unnecessary. One regex first decides "could multiple code points form one cluster" (astral / CRLF / ZWNJ·ZWJ / Hangul composing jamo / `\p{M}` combining marks), and only on a hit does it go to the segmenter. One frame of 60 lines of Chinese: **655 µs → 52 µs** (604 µs saved, 1% of the frame budget). The predicate prefers false positives over false negatives, and 6 new guard cases cover the various forms.
 
-### 🔧 依赖
+### 🔧 Dependencies
 
-- 升级 `@ai-zen/agents-sdk` 至 `1.0.0-alpha.21`（交接取消能力）。
+- Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.21` (handoff cancellation).
 
-### ✅ 测试
+### ✅ Tests
 
-- 全量 **46 文件 / 604 例通过**（评审前 36 文件 / 487 例，净增 10 文件 / 117 例护栏）。
-- 重点新增：`use-chat-viewport` 7 例、`use-overlays` 6 例、`use-wizard-host` 9 例、`use-input-editing` 13 例、`common-keys` 10 例、`chat.test.tsx` 7 例集成护栏、`lines.test.ts` 12 例（字素簇折行）、`notice-bar` 4 例、`conversation-persist` 10 例（含 spy `fs.rename` 钉住原子写）。
-- 破坏性验证（每项都确认护栏会红）：折行改回 code point、`clampCursor` 改 `Array.from`、翻页步长改 `budget`、删掉 PgUp 分支、去掉 `\p{M}`、原子写改回直写、`clearDraft` 去掉历史游标复位。
+- Full run: **46 files / 604 cases passed** (36 files / 487 cases before the review; a net gain of 10 files / 117 guard cases).
+- Notable additions: `use-chat-viewport` 7 cases, `use-overlays` 6 cases, `use-wizard-host` 9 cases, `use-input-editing` 13 cases, `common-keys` 10 cases, `chat.test.tsx` 7 integration guard cases, `lines.test.ts` 12 cases (grapheme-cluster wrapping), `notice-bar` 4 cases, `conversation-persist` 10 cases (including a spy on `fs.rename` pinning the atomic write).
+- Break checks (each confirmed to turn the guard red): wrapping back to code points, `clampCursor` switched to `Array.from`, paging step switched to `budget`, the PgUp branch removed, `\p{M}` dropped, atomic write back to direct write, the history cursor reset removed from `clearDraft`.
 
 ## [1.0.0-alpha.21] - 2026-10-27
 
-### ✨ 新功能
-
-- **状态栏改为三个信息块，并统计生成速率** —— 此前状态栏是一条按优先级排列的文本流，窄屏折行时会把 `本轮 1284 tok` 这类单元从中间劈开，也让「哪段信息属于一类」看不出来。
-  - 现在分成三块：① 模型 · Agent · 思考强度　② 本轮 / 累计 token 用量 · 生成速率　③ 快捷键提示（垫底）。
-  - **换行以块为单位**：新增 `packSegments()`（`src/tui/status-segments.ts`）——放得下就并排（` · ` 连接），放不下就把**整块**挪到下一行；只有单块自身超过一整行时才退化成块内折行（优先空格断、CJK 硬断、行首孤儿 `·` 丢弃、行尾空格裁掉）。行边界只会落在块边界上。
-  - **行数确定**：`statusBarRows()` 在纯逻辑里量出实际行数并交给 `computeChatLayout({ statusBarLines })`，测量与渲染是同一个函数——窄屏下状态栏变高不会把输入框顶出屏幕。
-  - 数字与单位用 NBSP 绑定（`本轮␣1284␣tok`），块内也不会被拆成两行。
-  - **生成速率两口径，不混成一个数**：生成中 `⚡ 47 tok/s` 是估算值（按输出增量折算，CJK 0.7 / 字、其它非空白 0.25 / 字符、空白 0.1，取最近 2 秒滑动窗口）；一轮结束后改用 `⚡ 均 38 tok/s`，分母是「首字 → 末字」跨度，分子是 API 返回的真实 `usage.completion_tokens`（多轮工具调用逐轮累加）。跨度 < 400ms 不显示，避免首包爆发把速率放成几百。
-- **新增 `/agent`：会话内快速切换主 Agent** —— 选择器列出 `~/.ai-zen/agents/*.json` 的全部主 Agent，标注当前项与其绑定的模型名（换 Agent 等于连模型一起换）。
-  - 支持 `/agent <id>` 直切；无参弹选择器。
-  - 切换前做完整链路预检：Agent 存在 → 绑定了模型 → 模型还在配置里 → 端点在 → 端点有 Key。跑不起来的标「不可用」并给出原因，而不是切过去之后卡在启动错误屏。
-  - 写入 `config.defaultAgent`（与 `/config` →「默认 Agent」同一字段），随后重建会话；**消息与上下文保留**。不改 Agent 定义本身（提示词 / 权限 / `modelParams` 一概不碰）。
-- **新增 `/mcp`：直达 MCP 管理界面** —— 不另建一套编辑器，直接把配置中心里已有的 MCP 屏打开（增 / 删 / 改 / 启停 / 全局⇄项目作用域切换都在那一屏）。关闭向导后沿用既有 `mcpChanged` 路径自动 `session.reload()`，新服务器当场生效。
-  - 默认落点：项目级有服务器就进 `project`，否则进 `global`（项目级为空时进去只会看到空列表）。`/mcp global`、`/mcp project`（可缩写 `g` / `p`）可指定。
-- **新增 `/reload`：刷新运行环境** —— `session.reload()` 内含 `resetScope()`（断开旧 MCP 连接、丢掉配置快照）→ 重建 Agent → 重新发现工具 / Skill / MCP。手改 `mcp.json` / `skills/` / `tools/` 后一条命令生效，**消息与上下文保留**，无需重启 CLI。
-- **中断时保留已输出的思考与内容** —— 按 `Ctrl+C` / `Esc` 停下后，模型**已经吐出来的那半句话不再凭空消失**。此前中断只是把在途消息标成 `Aborted`，而历史过滤器只放行 `completed`，于是屏幕上还留着的思考与回答在下一轮请求里整条不见，模型下一轮像失忆一样重来。
-  - 根因在上游：core 的 `abort()` 只管打标记、`formatHistory()` 只按状态过滤，两者都不关心「已经输出了什么」。core `4.5.3` 新增 `abortedMessageStrategy`（`drop` / `keep`，默认 `drop`），并导出 `reconcileAbortedMessages()`，在工具轮次归一**之后**收尾纯内容消息。
-  - CLI 显式设成 `keep`：确有输出的被中断 assistant 会被恢复为 `completed` 进入上下文。**空输出不保留**（避免空消息污染上下文）、**带工具调用的不归它管**（仍走「整轮进出」，否则会出现「有调用无结果」的非法历史）。
-  - SDK 依赖随之升级到 `1.0.0-alpha.20`（`createAgent` 新增第三参 `CreateAgentOptions`，顺带把此前完全没暴露的 `abortedToolRoundStrategy` / `abortedToolRoundReason` 一起接出来），core 升到 `4.5.3`。
-- **界面国际化（中文 / English）** —— 首次启动按系统语言识别（`LC_ALL` → `LC_MESSAGES` → `LANG` → Node 的 `Intl` locale，**兜底英文**），识别结果写入 `~/.ai-zen/cli/preferences.json`，之后以偏好为准（改了系统语言也不会让界面语言悄悄漂移）。`/lang` 可随时切换，`/lang zh` / `/lang en` 直接指定。
-  - 词典编译进产物（`src/i18n/{zh,en}.ts` + 配置中心专区 `{zh,en}-wizard.ts`）：key 扁平化，`{n}` 插值；切换语言只换一个引用，不重读磁盘、不重启。缺词条时返回 key 本身（不做跨语言静默回退，否则英文界面里会突然冒出中文）。`t()` 支持 `_one` / `_other` 复数变体（由 `Intl.PluralRules` 选），但 `i18n/index.test.ts` 要求**中英 key 集合完全一致**，故现有词条统一用 `(s)` 写法，不开变体。
-  - 语言偏好放 CLI 独立的 `preferences.json`，**不塞进共享的 `config.json`** —— 那是 CLI 与 Desktop 共用的 `AppConfig` 契约，塞进去会被桌面端当未知字段丢掉。
-  - 覆盖范围是**整套 TUI 界面**：主对话框（状态栏三块、输入占位与提示、通知、思考档位标签、生成中提示）、命令层（`/help`、斜杠菜单、各命令的选择器与反馈）、配置中心全部屏幕（端点 / 模型 / 图片模型 / MCP / Agent 定义 / 权限 / 默认项 / 工具输出上限 / 新建引导 / KV 与多行文本编辑器）、交接方式选择器与确认框、启动屏与启动错误屏，以及业务模块返回的 summary（`/model` `/agent` `/think` 的切换结果、交接进度与降级提示）。
-  - `COMMAND_REGISTRY` 里存的是 **i18n key 而不是文案** —— 它是纯数据模块、加载时机早于语言初始化，存文案会把「加载那一刻的语言」定死；渲染时由 `getCommandHints()` 现取。启动屏的 `TAGLINE` 常量同理改成了 `tagline()` 函数。
-  - **管道模式不做 i18n**：`ai <提示词>` / 管道输入的所有输出与报错**一律英文**（它是给脚本用的，不应随人的界面语言变），故 stdio 路径**不初始化语言**，行为与 `preferences.json` 彻底解耦。
-  - **`ai --help` 与 `ai hook install / uninstall` 走 i18n**：两者都在 TUI 之外打印，因此在各自分支里先 `initLocale()` 再取词条；`HELP_TEXT` 那个模块级常量相应改成 `helpText()` 现拼（常量会把加载那一刻的语言定死）。
-  - **会话 id 改名**：`对话_2025年07月01日14时30分00秒` → `chat_2026_10_28_00_56_34`（英文前缀 + 全下划线时间戳，中英一致、文件名安全）。它同时是文件名，跟着语言变会让历史文件与新文件混排，故时间戳由新增的 `formatFileStamp()` 生成；而**显示用**的 `formatShortTime()` 反而改为随语言切换。管道模式 `--save` 不再自己拼名字，改为调用 `generateConversationId()`，两处重复拼接一并消掉。
-  - **注入历史的「工作目录」提示改为英文并显式标记**：`[system-injected: working directory changed — not written by the user]` —— 翻存档或交接文档时一眼能分辨哪些内容不是用户敲的；`stripCwdNote()` 同时认新旧两代格式，避免旧存档把这段笔记渲染到屏幕上。
-  - 新建 Sub-agent 时写进 tool schema 的 `task` 参数描述也走词典（中 `完整的任务描述` / 英 `Full task description`）—— 这是唯一一处「协议内容也翻译」的例外，代价是同一份定义在不同界面语言下创建会得到不同的 schema 文本。
-  - 唯一不翻的注入内容就是上述工作目录提示；`hook.ts` 写进 rc 文件的三个代码块标记串（`# === ai hook (开始) ===` 等）也保持原样 —— 翻了就再也找不到旧块。
-  - 时间格式随语言切换 dayjs locale 与 pattern：中文 `7月1日 14:30` / `昨天 14:30`，英文 `Jul 1, 14:30` / `Yesterday 14:30`。
-  - 顺带排掉两个隐藏地雷：状态栏曾用**文案**判断思考强度是否置灰（`effort === "关"`），英文界面下永远不成立，改为档位语义的 `effortDimmed()`；输入区占位提示曾硬编码在 `inputLines()` 里（渲染层却走 `t()`），英文界面下量输入行高度会短一行、连带硬件光标 y 偏移，现在两处同源。
-
-### 🔧 行为变更
-
-- **消息栏的「思考中…」拆成六态：连接中 / 排队中 / 思考中 / 调用工具 / 等待工具返回 / 输出中** —— 原先那行只有「思考中…」一个词，但一轮对话里模型其实走过几个阶段，用同一个词概括在多数时候是**说错话**：等首 token 时并没有在思考，工具执行时模型根本没在跑。
-  - 判据只用**事件与 delta 的形状**（`src/tui/phase.ts`，纯逻辑可单测）：`connecting` = 请求发出到响应头到达；`queued` = `open` 之后、首个内容 chunk 之前；`thinking` = 收到 `reasoning_content`；`tool-calling` = 收到 `tool_calls` / `function_call`（带工具名，后续只带参数分片时沿用首个 delta 里的名字）；`tool-waiting` = `parsed` 且本轮带工具调用；`streaming` = 收到 `content`。一个 chunk 里同时出现时优先级是 tool_calls > content > reasoning。
-  - 「连接中」这一段靠新增的 `PhasePlugin`（`chat-session.ts`）提供：SDK 的 `open` 事件是在 `chat.completions.create()` **await 返回之后**才发的，只代表响应头到了，之前的 DNS / TCP / TLS / 服务端受理全静默。
-  - **子 Agent 的输出不推进主阶段**：委派期间主 Agent 正在等工具返回，若把子 Agent 的 delta 也算进主阶段，界面会跳成「输出中」，正好盖掉用户最需要知道的那句话。子 Agent 的 chunk 仍计入速率、仍触发重绘。
-  - spinner 那一行加了 `truncate`：busy 时输入区高度被 `computeChatLayout` 固定为 1 行（`inputHeight = 1`），标签一旦折行就会把输入框顶出屏幕。
-- **状态栏去掉「⏳ 生成中」** —— 本轮到底在干什么已由消息栏 spinner 逐阶段说明，状态栏再挂一个笼统的「生成中」只是重复占宽度（窄屏下还把快捷键提示挤到下一行）。
-
-- **shell 钩子改为进入 TUI（此前的管道模式是实现错误）** —— 钩子装在 `command_not_found_handle` / `command_not_found_handler` 上，触发场景是「人坐在交互终端前把命令敲错了」，但函数体写的是 `ai "$@"`，而 `decideMode()` 的规则是「有位置参数 → stdio」，于是钩子会话必然落到管道模式：吐一段文字到 stdout 就退出，**没有历史、不能追问**。`mode.ts` 头顶那张分类表把「脚本调用」与「人手动触发」混成了一个判据，所以这不是补丁能修的，是分类本身错了。
-  - 函数体现在是 `ai --tui --new "$@"`：新增 `--tui` 标志显式覆盖「有参数 → stdio」的判定，进 TUI 并把原命令**作为首条消息自动发送**（不预填到输入框——钩子的语义就是「这条命令跑不了，你帮我处理」，再让人敲一次回车没有意义）。
-  - 首条消息**强制当普通用户消息**发送，不经斜杠命令解析：敲错的可能是 `/opt/bin/foo` 这种以 `/` 开头的命令，否则会被当成 CLI 命令而报「未知命令」。`runSubmit()` 为此多了 `asMessage` 选项。
-  - `--tui` 在非 TTY 环境（脚本 / 管道）报错退出（退出码 2、英文提示），**不**降级成管道模式 —— 否则整屏界面内容会被写进管道。
-  - 首条消息只在首次挂载时发送：切模型 / `/lang` 等引起的重挂载不会重发。
-  - **钩子会话总是新开会话**：函数体多一个 `--new`（`ai --tui --new "$@"`）。否则敲错一次命令，那条命令就被追加进该目录原有的长对话里，上下文与会话名一起被搅乱。`--new` 是通用标志，手动用同样有效：`ai --new` 跳过 `last-session.json` 指针直接新建；它**只作用于 TUI 路径**，出现在 stdio 路径上时静默忽略（一次 stdio 调用本就是一次性会话，不存在续接）。
-  - **`ai hook install` 现在会自我升级**：此前只要 rc 文件里存在 `MARKER_START` 就打印「已安装」直接返回，于是函数体改过之后（比如本次加了 `--new`）老用户永远升不上去。现在会把已安装块与当前版本归一化比对（去空行、逐行 trim），不一致就原地覆盖并提示「已更新到最新版本」（新增词条 `hook.updated`）。
-
-- **`/migration` 不再是 `/migrate` 的别名** —— 只保留 `/migrate`，`/migration` 现在报「未知命令」。registry、命令执行器、`blocksInput` 判定与四份文档同步。
-- **SDK 全局日志默认写入 `~/.ai-zen/logs/sdk.log`** —— 以前默认**丢弃**，只有 `AIZ_DEBUG_SDK=1` 才落盘到 `/tmp`。但 SDK 的 `warn` / `error` 承载「MCP 连不上」「Skill 解析失败」这类关键诊断，默认丢弃等于故障无痕。现在默认落盘（单文件 2MB 封顶后轮转为 `sdk.log.1`），`AIZ_DEBUG_SDK=0` 可彻底关掉，`AIZ_SDK_LOG_FILE` 可改路径。界面上依旧一个字都不显示。
-
-### 🐛 修复
-
-- **修复 IME（输入法）候选框「有时候定位不准」** —— 硬件光标位置以前靠 `displayWidth()` 自己算。但宽度是个陷阱：Ink 排版时用 `string-width`，我们手写的表在若干字符上与它不一致（`⚡` `✅` `✨` `⭐` 我们算 1 列、Ink 算 2 列；ZWJ 组合 emoji `👨‍👩‍👧` 我们算 8 列、Ink 算 2 列；keycap `1️⃣` 我们算 3、Ink 算 2），输入里一出现这类字符，x 就会偏。现在改为**渲染后实测**：
-  - 光标所在字符包进独立 `<Box ref>`（行内嵌套的 `<Text>` 片段在 yoga 里没有节点，`measureElement()` 对它返回 `null`，实测），用 Ink 7 的 `measureElement()` 读它拓印到帧内的绝对坐标 —— 宽度由渲染器自己算，不再经过我们的模型。
-  - 拆行后原本整行 `truncate` 的兜底会丢：一旦内容超宽（如宽度模型把 `⚡` 算成 1 列）这行会被顶成两行，整帧高一行、底部被顶出屏幕。解法是把溢出交给**可截断的邻段**吸收——`before` / `after` 段 `flexShrink={1} minWidth={0}` + `wrap="truncate"`，光标块 `flexShrink={0}`；实测容器 40 列、`before` 60 列时仍是**一行**。
-  - 测量只能在渲染后（`useEffect`）做，而 Ink 的 `setCursorPosition` 只在 commit 阶段（`useInsertionEffect`）推送，所以存在一次 commit 的延迟：首次渲染先用旧手算值顶一帧，下一帧被实测值纠正（多一趟渲染，Ink 自带节流）。
-  - 占位提示行（未输入任何内容）不走实测，仍用前缀后的固定位置。
-- **占位提示态不再自绘「假光标」** —— 输入框为空时会显示灰字提示「输入消息，/ 查看命令…」，末尾原本还画了一个 `▏`。但硬件光标这时就停在提示语开头（`x = 前缀宽`），终端自己会把它显示出来，再画一个方块等于屏幕上两个光标，而且位置还在提示语末尾，反而误导。现在占位态只留提示文字。
-- **修复「输入 emoji 后反显光标消失 / 真实光标错位」** —— 根因有两个，都是把「字符」当成了 code point：
-  - **光标停在字素簇中间**：`✌️` 是 `U+270C U+FE0F` **两个 code point、一个字素簇**（`👨‍👩‍👧` 五个、`🇨🇳` 两个区域指示符）。按 code point 切分时，光标能停在 `✌` 与 `U+FE0F` 之间，于是反显的是一串**变体选择符** —— Ink 的输出里反显段直接消失（实测：`at=U+FE0F` 时帧里既无反显转义也没字符）。同时退格会只删掉半个 emoji、留下孤立的 `U+FE0F`。现在全部光标运算（折行、移动、删除、插入、撤销）改用 `Intl.Segmenter` 的**字素簇**为单位（`graphemes()`，Node 内置无需依赖）。
-  - **宽度表换成 Ink 自己的尺子**：`displayWidth()` 不再用手写的 `isWide` 区间表，直接调用 **`string-width`**（Ink 排版用的就是它，见 `ink/build/output.js`）；单簇宽度带缓存，折行热路径几乎零成本。从此折行、状态栏装行、光标列号与渲染器同源 —— 状态栏那条「预留 1 列余量」也降级为纯安全边际。
-  - **光标单位改成字素簇**：`✌️` 是 `U+270C U+FE0F` **两个 code point、一个字素簇**（`👨‍👩‍👧` 五个、`🇨🇳` 两个区域指示符）。按 code point 切分时，光标能停在 `✌` 与 `U+FE0F` 之间，于是反显的是一串**变体选择符** —— Ink 的输出里反显段直接消失（实测：`at=U+FE0F` 时帧里既无反显转义也没字符）。同时退格会只删掉半个 emoji、留下孤立的 `U+FE0F`。现在全部光标运算（折行、移动、删除、插入、撤销）改用 `Intl.Segmenter` 的**字素簇**为单位（`graphemes()`，Node 内置无需依赖）。
-  - **新增直接依赖** `string-width@^8.3.0`（纯 ESM，本就在 Ink 的依赖树里，体积无变化）。
-- **通知栏行数未计入光标 y** —— 渲染顺序是「对话区 → 通知栏 → 斜杠菜单 → 分隔线 → 输入行」，而 y 公式漏了通知栏一段。于是任何通知出现时硬件光标都会整体上浮那么多行；`/help` 一次塞最多 8 行通知，候选框能浮进对话区。现已补上 `noticeCount`（现作为实测未就绪时的兜底算法保留）。
-- **修复 SDK 日志「接管了却照样糊界面」** —— 加载 MCP 时 `[load_mcp]` 连同整份 tools / resources 清单直接砸在渲染区外面。原因是 SDK 有 4 个模块在**模块顶层**执行 `const log = getLogger()`：模块求值那一刻就把 `console.log` 的函数引用冻进了常量，`setLogger()` 事后只替换内部变量，改不动已经抓走的引用；ESM 的静态 import 又保证这些模块在 `runTui()` 之前就已求值 —— 于是 CLI 无论怎么接管都会漏。
-  - 修在 SDK 侧（不改 CLI 侧骗 console 的 workaround）：4 处全部改为**运行时取 logger**（`getLogger().info(...)` 等）；`skillTools` 那处是从未被调用的死代码，连同 import 一并删除。至此 SDK 内 10 处日志调用全部经由 `getLogger()` 单一出口，不存在 console 旁路。
-
-### 📝 文档
-
-- README（中 / 英）与 `docs/{zh,en}/getting-started.md` 的命令表新增 `/agent`、`/reload`、`/mcp` 三行。
-- README（中 / 英）与 `docs/{zh,en}/index.md` 的状态栏说明从「一条按优先级的文本流」改为「三个信息块 + 按块换行」。
-- `docs/{zh,en}/mcp.md` 的「管理」章节补充 `/mcp` 直达入口与 `/reload` 刷新；`docs/{zh,en}/migration.md` 去掉「别名 `/migration`」。
-- README（中 / 英）新增「界面语言」一节：识别优先级、`preferences.json` 与 `/lang`、覆盖范围，以及刻意不翻的三类内容。
-- `docs/manifest.json` 与 README 中的版本号更新为 `1.0.0-alpha.21`。
-- README（中 / 英）的「环境变量」补 `AIZ_DEBUG_SDK=0` / `AIZ_SDK_LOG_FILE`，「文件系统布局」补 `~/.ai-zen/logs/`，键位表下补一段「中断后已输出的思考与内容会保留」的说明。
-- README（中 / 英）与 `docs/{zh,en}/getting-started.md` 的命令表补 `/lang`；「文件系统布局」与 `docs/{zh,en}/configuration.md` 的目录树补 `~/.ai-zen/cli/preferences.json`（CLI 本地偏好）。
-
-### ⚠️ 已知取舍
-
-- **emoji 的渲染宽度可能仍与终端对不上，这是终端层的事**：代码侧已经做到与渲染器同源（`displayWidth` = Ink 用的 `string-width`，光标位置用 `measureElement` 实测），但**终端自己对 emoji / East Asian Ambiguous 字符的列宽判定**仍可能与 Unicode 表不同（部分终端把 `✌️` 渲染成 1 列而不是 2 列，且没有查询接口）。那种情况下整行文本的相对位置就已经由终端决定了，光标只能跟着 Ink 的模型走。输入 / 删除 / 光标单位层面的 emoji 问题已在本次修完。
-- **光标是「终端光标 + 字符反显」两套并存，这是故意的**：光标处的字符仍用 `<Text inverse>` 反显成一个方块，位置的真相源是实测出来的硬件光标。两者视觉上会叠成一个略重的方块——接受这个重影，因为任一层失效时另一层还能报位置（某些终端 / 多路复用器里硬件光标不显示，或 Ink 卸载时反显又没了）。以后别把反显当重复渲染删掉。
-- **块不被劈开 ⇒ 行数随宽度变化**：80 列下三块各占一行（3 行），120 列可把身份与用量并成 1 行（共 2 行）。旧的「一条流」能压到 2 行，代价是把 `本轮 / 累计` 拆到两行——信息完整性优先。
-- **生成中的速率是估算值**：SDK 只在每个请求的**最后一个 chunk** 才给 `usage`（`stream_options.include_usage`），拿不到逐 token 用量；把估算与精确值混成一个数字才是误导，因此分成「实时估算」与「本轮均速」两种写法。
-- **`/mcp` 只覆盖配置层**：服务器当前是否连通、暴露了多少工具，在 SDK 里是插件私有状态（`McpScopePlugin` 的 `mcpManager`），没有公开 API，界面不展示连接状态。
-- **`/reload` 有一两秒空档**：重建 Agent 且重连 MCP，服务器多的场景会有可感知延迟；期间消息与上下文不受影响。
-
-### ✅ 测试
-
-- 全量 **33 文件 / 440 例通过**，`npx tsc --noEmit -p tsconfig.test.json` 干净。
-- 新增 `src/i18n/index.test.ts`（14 例：语言识别优先级 / `C`·`POSIX` 跳过 / 兜底英文 / 插值 / 缺词条回退 key / 中英词条一一对应）与 `src/i18n/preferences.test.ts`（9 例：文件缺失·损坏·非法值的容错、原子写、`initLocale` 只识别一次并落盘）；`reasoning-effort.test.ts` 补 5 例「置灰不靠文案判断」。
-- pty 真机验收：`LANG=en_US.UTF-8` 首次启动→英文并落盘 `en`；`/lang` 切中文→状态栏/输入框/通知全部跟随，且**重启后保持中文**（偏好先于系统语言）；`/lang en` 切回英文正常。
-- pty 真机验收（阶段 2）：英文下斜杠菜单显示 `❯ /help  Show this help`、`/help` 输出全英文列表；`/lang zh` 后斜杠菜单与 `/help` 整体切回中文。
-- pty 真机验收（阶段 3 / 4，隔离的 `AI_ZEN_DIR` + `LANG=en_US.UTF-8`）：首次启动识别为英文并落盘；启动屏 `The AI collaboration desk in your terminal`；主屏 `Type a message, / for commands…`、`thinking default · total 0 tok`；配置中心 `◆ Configuration` 与 `+ New model — marked as custom automatically` / `openai · factory-managed · vision`；模型详情 `◆ Model · GPT-6 Astra` / `factory-managed (editing switches it to custom)` / `Delete model`；新建模型与新建端点引导屏全英文。把 `preferences.json` 改回 `zh` 后**在 `LANG=en_US.UTF-8` 下重启仍为中文界面**（偏好优先于系统语言），配置中心与模型列表中文文案与改造前一致。
-- **断言中文的测试一律显式锁语言**：`setLocale("zh")` 加在 `screens.test.tsx`、`config-wizard.test.tsx`、`reasoning-effort.test.ts`、`registry.test.ts`、`agent-prompt.test.tsx`、`handoff-choice.test.ts`、`config-editor.test.ts`、`agent-switch.test.ts`、`model-switch.test.ts`、`handoff-service.test.ts`、`auto-migrate-confirm.test.ts` —— 默认语言是 `en`，不锁就会在 CI 上莫名其妙地红。
-- `mode.test.ts` 新增 6 例 `--tui`：有参数进 TUI 且参数作为首条消息、无参数时同不带 `--tui`、以 `/` 开头的命令不被当选项 / 子命令、`--tui --help` 时 help 优先、非 TTY 拒绝而非降级、`--` 之后的 `--tui` 是普通参数。
-- `mode.test.ts` 新增 8 例 `--new`：单独用时进 TUI 且 `newSession: true`、`--tui --new <命令>` 同时带首条消息与新会话、与 `--tui` 顺序无关、有参数时落到 stdio 并被忽略、非 TTY 时落到 stdio 并被忽略、`--tui --new` 非 TTY 仍拒绝而非降级、`--new --help` 时 help 优先、`--` 之后的 `--new` 是普通参数。
-- 新增 `src/hook.test.ts`（9 例，全部在临时 HOME 下跑，**不触碰真实 `~/.bashrc`**）：写入的函数体含 `ai --tui --new "$@"` 且只有一个块、保留 rc 原有内容、重复安装幂等、**已装旧函数体（`ai --tui "$@"`）时原地升级**、历史 aiz 块迁移、zsh 走 `command_not_found_handler` 且写入 `.zshrc`；卸载移除块并保留其余内容、未安装时不动文件、rc 文件不存在时不报错。
-- pty 真机验收（钩子路径）：`ai --tui gti status` 进 TUI 并自动把 `gti status` 当用户消息发出（界面显示 `❯ 你 / gti status`），模型报错（故意的本地假端点）后界面仍存活可继续追问；`ai --tui /opt/bin/nonexistent --flag` 同样当**普通消息**发出，不被斜杠命令解析吃掉；`ai --tui` 在非 TTY 下退出码 2；写进 `~/.bashrc` 的函数体为 `ai --tui --new "$@"` 且 `bash -n` 语法通过。
-- pty 真机验收（`--new`，隔离 `AI_ZEN_DIR` + 预置 `last-session.json` 指向旧会话）：`ai` 续接并显示旧消息 `MARKER-OLD-QUESTION`；`ai --new` 停在**空对话**；`ai --tui --new gti status` 空对话且首条消息自动发出；`--help` 中英两个界面都列出 `--new`。
-- 本次改动后全量 **36 文件 / 487 例通过**，`npx tsc --noEmit` 与 `-p tsconfig.test.json` 均干净。
-- 新增 `src/tui/phase.test.ts`（15 例：六态各自的推进、工具名沿用、无 delta 的收尾 chunk 不改阶段、content 压过 reasoning、`reset` 归零、中英文案六者互不相同）；`chat-session.test.ts` 补 3 例（按 SDK 事件时序推进、子 Agent 输出不覆盖主阶段、`send` 结束阶段归零）。
-- pty 真机验收（本地 mock SSE 服务端按阶段分段吐流）：依次抓到「连接中…」→「排队中…（等待首 token）」→「思考中…」→「输出中…」→「调用工具 no_such_tool…」→「等待 sub_agent_default 返回…」；状态栏同期只有 `⚡ 4.2 tok/s` 与本轮 / 累计 token，无「生成中」。
-- 新增 `src/agent-switch.test.ts`（10 例）、`src/mcp-command.test.ts`（6 例）、`src/tui/token-rate.test.ts`（20 例）、`src/tui/status-segments.test.ts`（17 例）、`src/tui/screens/input-row.test.tsx`（7 例）、`src/tui/text.test.ts`（18 例）；`input-editing.test.ts` 补 3 例「emoji 不被拆半个」的用例。
-- `src/tui/screens.test.tsx` 增加状态栏三块顺序、块内不被拆、宽屏并排、以及「Ink 实际渲染行数 == `statusBarRows` 量出行数」的断言；`computeInputCursorPosition` 补「通知栏行数参与 y」的用例。
-- `input-row.test.tsx` 里那条 `⚡` 用例同时断言「手算给 8、实测给 9」——本次改动的理由就在这两行里。
+### ✨ New features
+
+- **Status bar split into three information blocks, plus a generation rate** — the status bar used to be one priority-ordered stream of text, and when it wrapped on a narrow screen it cut units like `this round 1284 tok` in half while also making it impossible to tell which pieces of information belonged together.
+  - It is now three blocks: ① model · Agent · reasoning effort　② this round / cumulative token usage · generation rate　③ keybinding hints (at the bottom).
+  - **Wrapping is per block**: new `packSegments()` (`src/tui/status-segments.ts`) — if it fits, blocks sit side by side (joined by ` · `); if not, the **whole block** moves to the next line; only a single block longer than a whole line degrades to wrapping inside the block (prefer breaking at spaces, hard break for CJK, drop an orphan `·` at line start, trim trailing spaces). Line boundaries only ever fall on block boundaries.
+  - **Row count is deterministic**: `statusBarRows()` measures the actual row count in pure logic and hands it to `computeChatLayout({ statusBarLines })`; measurement and rendering are the same function, so a taller status bar on a narrow screen never pushes the input line off screen.
+  - Numbers and units are bound with NBSP (`this round␣1284␣tok`), so they are not split across two lines inside a block either.
+  - **Two measures for the generation rate, never mixed into one number**: while generating, `⚡ 47 tok/s` is an estimate (derived from output deltas, CJK 0.7 / character, other non-whitespace 0.25 / character, whitespace 0.1, over a sliding window of the last 2 seconds); after a round ends it switches to `⚡ avg 38 tok/s`, where the denominator is the first-char → last-char span and the numerator is the real `usage.completion_tokens` returned by the API (accumulated round by round for multi-round tool calls). A span < 400ms is not shown, so a burst on the first packet cannot inflate the rate into the hundreds.
+- **New `/agent`: switch the main Agent quickly inside a conversation** — the selector lists every main Agent in `~/.ai-zen/agents/*.json`, marking the current one and the model it is bound to (switching Agent means switching the model with it).
+  - Supports `/agent <id>` for a direct switch; no argument opens the selector.
+  - A full-chain precheck runs before switching: Agent exists → bound to a model → the model is still in the configuration → the endpoint exists → the endpoint has a key. Ones that cannot run are marked "unavailable" with a reason, instead of switching and then being stuck on the startup error screen.
+  - Writes `config.defaultAgent` (the same field as `/config` → "Default Agent") and then rebuilds the session; **messages and context are kept**. The Agent definition itself is not modified (prompt / permissions / `modelParams` all untouched).
+- **New `/mcp`: jump straight to the MCP management screen** — no separate editor is built; the existing MCP screen in the configuration center is opened directly (add / delete / edit / enable-disable / global⇄project scope switching all live on that screen). After the wizard closes it reuses the existing `mcpChanged` path to call `session.reload()` automatically, so new servers take effect on the spot.
+  - Default landing: if the project scope has servers, go to `project`, otherwise `global` (entering the project scope when it is empty shows only an empty list). `/mcp global`, `/mcp project` (abbreviable to `g` / `p`) can specify it.
+- **New `/reload`: refresh the runtime environment** — `session.reload()` contains `resetScope()` (disconnect the old MCP connections, drop the config snapshot) → rebuild the Agent → rediscover tools / Skills / MCP. After hand-editing `mcp.json` / `skills/` / `tools/`, one command makes it take effect, **messages and context are kept**, and the CLI need not be restarted.
+- **Keep the reasoning and content already output when aborting** — after stopping with `Ctrl+C` / `Esc`, the half sentence the model **already emitted no longer vanishes into thin air**. Previously abort only marked the in-flight message `Aborted`, while the history filter let only `completed` through, so the reasoning and answer still visible on screen disappeared entirely from the next request, and the model started over the next round as if it had amnesia.
+  - The root cause is upstream: core's `abort()` only sets a flag and `formatHistory()` only filters by status, and neither cares about "what has already been output". core `4.5.3` adds `abortedMessageStrategy` (`drop` / `keep`, default `drop`) and exports `reconcileAbortedMessages()`, which settles pure content messages **after** tool rounds are normalized.
+  - The CLI sets it explicitly to `keep`: an aborted assistant message that really produced output is restored to `completed` and enters the context. **Empty output is not kept** (to avoid empty messages polluting the context) and **messages with tool calls are not its business** (they still follow "whole round in, whole round out", otherwise the history would be illegal with "a call but no result").
+  - The SDK dependency is upgraded to `1.0.0-alpha.20` accordingly (`createAgent` gains a third parameter `CreateAgentOptions`, which also surfaces the previously unexposed `abortedToolRoundStrategy` / `abortedToolRoundReason`), and core goes to `4.5.3`.
+- **UI internationalization (Chinese / English)** — the first launch detects the system language (`LC_ALL` → `LC_MESSAGES` → `LANG` → Node's `Intl` locale, **English as the fallback**), the result is written to `~/.ai-zen/cli/preferences.json`, and the preference wins from then on (changing the system language later does not let the UI language drift quietly). `/lang` switches at any time; `/lang zh` / `/lang en` set it directly.
+  - Dictionaries are compiled into the bundle (`src/i18n/{zh,en}.ts` plus the configuration center section `{zh,en}-wizard.ts`): flattened keys, `{n}` interpolation; switching language swaps one reference, with no disk re-read and no restart. A missing entry returns the key itself (no silent cross-language fallback, which would make Chinese pop up in the English UI). `t()` supports `_one` / `_other` plural variants (chosen by `Intl.PluralRules`), but `i18n/index.test.ts` requires the **Chinese and English key sets to be identical**, so existing entries use the `(s)` form uniformly and no variants are enabled.
+  - The language preference lives in the CLI's own `preferences.json` and is **not stuffed into the shared `config.json`** — that is the `AppConfig` contract shared by the CLI and Desktop, and anything stuffed in there would be dropped by the desktop app as an unknown field.
+  - Coverage is **the whole TUI**: the main conversation screen (three status bar blocks, input placeholder and hints, notices, reasoning effort labels, generating hints), the command layer (`/help`, the slash menu, selectors and feedback of every command), every screen of the configuration center (endpoints / models / image models / MCP / Agent definitions / permissions / defaults / tool output limits / creation wizard / KV and multi-line text editors), the handoff mode selector and confirm boxes, the startup screen and the startup error screen, plus the summaries returned by business modules (the switch results of `/model` `/agent` `/think`, handoff progress and downgrade hints).
+  - `COMMAND_REGISTRY` stores **i18n keys rather than display text** — it is a pure data module loaded before language initialization, so storing text would freeze "the language at load time"; rendering calls `getCommandHints()` to fetch it on the spot. The startup screen's `TAGLINE` constant became a `tagline()` function for the same reason.
+  - **Pipeline mode does not do i18n**: all output and errors of `ai <prompt>` / piped input are **English only** (it is for scripts and should not follow a person's UI language), so the stdio path **does not initialize the language** and its behavior is fully decoupled from `preferences.json`.
+  - **`ai --help` and `ai hook install / uninstall` go through i18n**: both print outside the TUI, so each branch calls `initLocale()` before fetching entries; the module-level `HELP_TEXT` constant became `helpText()` assembled on demand (a constant would freeze the language at load time).
+  - **Conversation id renamed**: the old localized `dialogue_<date and time with Chinese units>` form → `chat_2026_10_28_00_56_34` (English prefix + all-underscore timestamp, identical in Chinese and English, filename-safe). It is also the file name, and letting it follow the language would mix old and new history files, so the timestamp is produced by the new `formatFileStamp()`; **display** times, by contrast, now follow the language via `formatShortTime()`. Pipeline mode's `--save` no longer assembles a name itself and calls `generateConversationId()` instead, removing the duplicated assembly in both places.
+  - **The "working directory" note injected into history switched to English with an explicit marker**: `[system-injected: working directory changed — not written by the user]` — flipping through an archive or a handoff document makes it obvious at a glance which content the user did not type; `stripCwdNote()` recognizes both generations of the format, so old archives do not render this note on screen.
+  - The `task` parameter description written into the tool schema when creating a sub-agent also comes from the dictionary (Chinese `Complete task description` / English `Full task description`) — the only exception where "protocol content is translated too"; the cost is that the same definition created under different UI languages yields different schema text.
+  - The only injected content left untranslated is the working-directory note above; the three code-block marker strings `hook.ts` writes into the rc file (such as `# === ai hook (开始) ===`) also stay as they are — translated, the old block could never be found again.
+  - Time formats switch dayjs locale and pattern along with the language: Chinese renders a localized month-day form plus time with a "yesterday" prefix, English `Jul 1, 14:30` / `Yesterday 14:30`.
+  - Two hidden mines were cleared along the way: the status bar used to decide whether reasoning effort is dimmed by **display text** (`effort === "off"`), which never held in the English UI, and now uses `effortDimmed()` based on the level's semantics; the input area placeholder used to be hardcoded inside `inputLines()` (while the render layer went through `t()`), so in the English UI the measured input row height came out one line short and dragged the hardware cursor's y offset along — both now share one source.
+
+### 🔧 Behavior changes
+
+- **The message row's "thinking…" split into six states: connecting / queued / thinking / calling a tool / waiting for a tool result / streaming** — that row used to have only the single word "thinking…", but a model actually goes through several stages within one round, and summing them up with one word is **plain wrong** most of the time: it is not thinking while waiting for the first token, and while a tool runs the model is not running at all.
+  - The predicate uses only **the shape of events and deltas** (`src/tui/phase.ts`, pure logic and unit-testable): `connecting` = from request dispatch to response headers; `queued` = after `open` and before the first content chunk; `thinking` = `reasoning_content` received; `tool-calling` = `tool_calls` / `function_call` received (with a tool name, reusing the name from the first delta when later chunks carry only argument fragments); `tool-waiting` = `parsed` and this round has tool calls; `streaming` = `content` received. When several appear in one chunk the priority is tool_calls > content > reasoning.
+  - The "connecting" stage is provided by the new `PhasePlugin` (`chat-session.ts`): the SDK's `open` event is emitted **after the `await` of `chat.completions.create()` returns** and only means the response headers arrived; the DNS / TCP / TLS / server acceptance before that is entirely silent.
+  - **Sub-agent output does not advance the main stage**: during delegation the main Agent is waiting for a tool result, and counting the sub-agent's deltas into the main stage would make the UI jump to "streaming", covering exactly the sentence the user most needs to know. Sub-agent chunks still count toward the rate and still trigger a redraw.
+  - The spinner row got `truncate`: while busy the input area height is fixed at 1 row by `computeChatLayout` (`inputHeight = 1`), and a wrapped label would push the input line off screen.
+- **"⏳ Generating" removed from the status bar** — what this round is doing is already explained stage by stage by the message row spinner, and another generic "generating" in the status bar only duplicates it and eats width (on a narrow screen it also squeezes the keybinding hints onto the next line).
+
+- **Shell hook switched to entering the TUI (the earlier pipeline mode was an implementation error)** — the hook is installed on `command_not_found_handle` / `command_not_found_handler`, and the triggering situation is "a person sitting at an interactive terminal typed a command wrong", yet the function body was `ai "$@"`, while the rule in `decideMode()` is "positional arguments → stdio", so the hook session inevitably fell into pipeline mode: it spat some text to stdout and exited, **with no history and no follow-up questions**. The classification table at the top of `mode.ts` merged "script invocation" and "manually triggered by a person" into one predicate, so this was not something a patch could fix — the classification itself was wrong.
+  - The function body is now `ai --tui --new "$@"`: the new `--tui` flag explicitly overrides the "has arguments → stdio" decision, enters the TUI and **sends the original command automatically as the first message** (not pre-filled into the input line — the semantics of the hook are "this command cannot run, handle it for me", and making the user press Enter again is pointless).
+  - The first message is **forced to be sent as an ordinary user message** and skips slash-command parsing: the mistyped command could be something like `/opt/bin/foo` starting with `/`, which would otherwise be treated as a CLI command and reported as "unknown command". `runSubmit()` gained an `asMessage` option for this.
+  - In non-TTY environments (scripts / pipes) `--tui` reports an error and exits (exit code 2, English message) and does **not** degrade into pipeline mode — otherwise a whole screen of UI content would be written into the pipe.
+  - The first message is sent only on the first mount: remounts caused by switching models / `/lang` do not resend it.
+  - **Hook sessions always start a new conversation**: the function body has an extra `--new` (`ai --tui --new "$@"`). Otherwise one mistyped command would be appended to the long conversation that already existed in that directory, scrambling both the context and the conversation name. `--new` is a general flag and works the same when used manually: `ai --new` skips the `last-session.json` pointer and starts a new conversation; it **only affects the TUI path** and is silently ignored on the stdio path (a stdio invocation is a one-shot conversation anyway, so there is nothing to continue).
+  - **`ai hook install` now upgrades itself**: previously it printed "installed" and returned as soon as `MARKER_START` existed in the rc file, so after the function body changed (say, `--new` added this time) existing users could never upgrade. It now normalizes the installed blocks and the current version and compares them (blank lines removed, every line trimmed), overwrites in place when they differ, and reports "updated to the latest version" (new entry `hook.updated`).
+
+- **`/migration` is no longer an alias of `/migrate`** — only `/migrate` remains, and `/migration` now reports "unknown command". The registry, the command executor, the `blocksInput` decision and the four documents were updated together.
+- **SDK global logs go to `~/.ai-zen/logs/sdk.log` by default** — previously they were **discarded** by default, and only `AIZ_DEBUG_SDK=1` wrote them to `/tmp`. But the SDK's `warn` / `error` carry critical diagnostics such as "MCP cannot connect" and "Skill failed to parse", and discarding them by default meant failures left no trace. They are now written by default (rotated to `sdk.log.1` after a 2MB cap per file), `AIZ_DEBUG_SDK=0` turns it off completely, and `AIZ_SDK_LOG_FILE` changes the path. The UI still shows not a single character of it.
+
+### 🐛 Fixes
+
+- **Fixed the IME candidate window being "sometimes mispositioned"** — the hardware cursor position used to be computed by `displayWidth()`. But width is a trap: Ink lays out with `string-width`, and the hand-written table disagreed with it on several characters (`⚡` `✅` `✨` `⭐` were counted as 1 column against Ink's 2; the ZWJ emoji `👨‍👩‍👧` as 8 columns against 2; the keycap `1️⃣` as 3 against 2), so as soon as such a character appeared in the input, x drifted. It is now **measured after rendering**:
+  - The character at the cursor is wrapped in its own `<Box ref>` (inline nested `<Text>` fragments have no node in yoga and `measureElement()` returns `null` for them, verified by experiment), and Ink 7's `measureElement()` reads the absolute coordinates it is imprinted at within the frame — width is computed by the renderer itself and no longer passes through the hand-written model.
+  - After splitting rows, the previous whole-row `truncate` fallback would be lost: once the content is too wide (e.g. the width model counts `⚡` as 1 column) the row is pushed into two rows, the whole frame grows a row and the bottom is pushed off screen. The solution hands the overflow to the **truncatable adjacent segments** — `before` / `after` use `flexShrink={1} minWidth={0}` + `wrap="truncate"` and the cursor block uses `flexShrink={0}`; measured with a 40-column container and a 60-column `before`, it was still **one row**.
+  - Measurement can only happen after rendering (`useEffect`), while Ink pushes `setCursorPosition` only in the commit phase (`useInsertionEffect`), so there is a one-commit delay: the first render puts up one frame with the old hand-computed value, and the next frame is corrected by the measured value (one extra render pass, which Ink throttles itself).
+  - The placeholder row (nothing typed yet) does not go through measurement and still uses the fixed position after the prefix.
+- **The placeholder state no longer draws a "fake cursor"** — when the input line is empty it shows the gray hint "Type a message, / for commands…", and a `▏` used to be drawn at the end as well. But the hardware cursor already sits at the start of the hint (`x = prefix width`), the terminal displays it on its own, and drawing another block means two cursors on screen — and positioned at the end of the hint, which is misleading. The placeholder state now keeps only the hint text.
+- **Fixed "the inverse cursor disappears / the real cursor is misaligned after typing emoji"** — two root causes, both treating a "character" as a code point:
+  - **The cursor could stop in the middle of a grapheme cluster**: `✌️` is `U+270C U+FE0F`, **two code points, one grapheme cluster** (`👨‍👩‍👧` five, `🇨🇳` two regional indicators). When splitting by code point the cursor could stop between `✌` and `U+FE0F`, so the inverse display became a string of **variation selectors** — in Ink's output the inverse segment disappears entirely (measured: with `at=U+FE0F` the frame carries neither the inverse escape nor any character). Backspace also deleted only half an emoji and left an orphan `U+FE0F`. All cursor arithmetic (wrapping, moving, deleting, inserting, undoing) now uses `Intl.Segmenter`'s **grapheme clusters** as the unit (`graphemes()`, built into Node with no dependency).
+  - **The width table switched to Ink's own ruler**: `displayWidth()` no longer uses the hand-written `isWide` range table but calls **`string-width`** directly (that is what Ink lays out with, see `ink/build/output.js`); per-cluster widths are cached, so the wrapping hot path costs almost nothing. From now on wrapping, status bar packing, cursor column numbers and the renderer share one source — and the status bar's "reserve 1 extra column" degraded to a pure safety margin.
+  - **Cursor unit changed to grapheme clusters**: `✌️` is `U+270C U+FE0F`, **two code points, one grapheme cluster** (`👨‍👩‍👧` five, `🇨🇳` two regional indicators). When splitting by code point the cursor could stop between `✌` and `U+FE0F`, so the inverse display became a string of **variation selectors** — in Ink's output the inverse segment disappears entirely (measured: with `at=U+FE0F` the frame carries neither the inverse escape nor any character). Backspace also deleted only half an emoji and left an orphan `U+FE0F`. All cursor arithmetic (wrapping, moving, deleting, inserting, undoing) now uses `Intl.Segmenter`'s **grapheme clusters** as the unit (`graphemes()`, built into Node with no dependency).
+  - **New direct dependency** `string-width@^8.3.0` (pure ESM, already in Ink's dependency tree, no size change).
+- **Notice bar rows were not counted in the cursor y** — the render order is "conversation area → notice bar → slash menu → separator → input row", and the y formula was missing the notice bar. So whenever a notice appeared the hardware cursor floated up by that many rows; `/help` pushes up to 8 rows of notices at once, and the candidate window could float into the conversation area. `noticeCount` is now included (kept as the fallback algorithm while the measurement is not ready).
+- **Fixed SDK logs "taken over and still smearing the UI"** — when loading MCP, `[load_mcp]` along with the whole tools / resources listing smashed straight outside the render area. The reason was that 4 SDK modules run `const log = getLogger()` **at module top level**: the moment the module is evaluated the `console.log` function reference is frozen into a constant, and `setLogger()` only swaps an internal variable afterwards, unable to change the reference already captured; ESM static imports also guarantee those modules are evaluated before `runTui()` — so no matter how the CLI took over, it leaked.
+  - Fixed on the SDK side (not with a CLI-side workaround that lies to console): all 4 sites now **take the logger at runtime** (`getLogger().info(...)` and so on); the `skillTools` site was dead code that was never called and was removed along with its import. All 10 log calls inside the SDK now go through the single `getLogger()` exit; no console bypass remains.
+
+### 📝 Docs
+
+- README (zh / en) and `docs/{zh,en}/getting-started.md`: the command table gained three rows, `/agent`, `/reload`, `/mcp`.
+- README (zh / en) and `docs/{zh,en}/index.md`: the status bar description changed from "one priority-ordered stream of text" to "three information blocks + per-block wrapping".
+- `docs/{zh,en}/mcp.md`: the "Management" section gained the `/mcp` direct entry and the `/reload` refresh; `docs/{zh,en}/migration.md` dropped the `/migration` alias.
+- README (zh / en) gained a "UI language" section: detection priority, `preferences.json` and `/lang`, coverage, and the three kinds of content deliberately left untranslated.
+- Version numbers in `docs/manifest.json` and the READMEs updated to `1.0.0-alpha.21`.
+- README (zh / en): "Environment variables" gained `AIZ_DEBUG_SDK=0` / `AIZ_SDK_LOG_FILE`, "Filesystem layout" gained `~/.ai-zen/logs/`, and a note was added under the keybinding table saying reasoning and content already output are kept after an abort.
+- README (zh / en) and `docs/{zh,en}/getting-started.md`: the command table gained `/lang`; the directory trees in "Filesystem layout" and `docs/{zh,en}/configuration.md` gained `~/.ai-zen/cli/preferences.json` (CLI-local preferences).
+
+### ⚠️ Known trade-offs
+
+- **Emoji render width may still disagree with the terminal, and that is the terminal layer's business**: the code side now shares one source with the renderer (`displayWidth` = the `string-width` Ink uses, cursor position measured with `measureElement`), but **the terminal's own column-width judgment for emoji / East Asian Ambiguous characters** may still differ from the Unicode tables (some terminals render `✌️` as 1 column instead of 2, and offer no query interface). In that case the relative position of the whole line is already decided by the terminal, and the cursor can only follow Ink's model. The emoji problems at the input / delete / cursor-unit level are all fixed in this release.
+- **The cursor is "terminal cursor + inverse character" side by side, deliberately**: the character at the cursor is still inverted into a block with `<Text inverse>`, and the source of truth for position is the measured hardware cursor. Visually the two stack into a slightly heavy block — accept the ghosting, because when either layer fails the other can still report the position (some terminals / multiplexers do not show the hardware cursor, or the inverse display is gone when Ink unmounts). Do not delete the inverse as duplicate rendering later.
+- **Blocks are not split ⇒ row count varies with width**: at 80 columns the three blocks each take a row (3 rows), at 120 columns identity and usage can sit on one row (2 rows in total). The old "one stream" could be squeezed into 2 rows, at the cost of splitting `this round / cumulative` across two rows — information integrity wins.
+- **The rate while generating is an estimate**: the SDK only provides `usage` in the **last chunk** of each request (`stream_options.include_usage`) and offers no per-token usage; mixing estimates and exact values into one number is the misleading option, hence the two forms "real-time estimate" and "round average".
+- **`/mcp` only covers the configuration layer**: whether a server is currently reachable and how many tools it exposes is plugin-private state in the SDK (`McpScopePlugin`'s `mcpManager`) with no public API, so the UI does not show connection status.
+- **`/reload` has a gap of a second or two**: it rebuilds the Agent and reconnects MCP, so with many servers there is a perceptible delay; messages and context are unaffected during it.
+
+### ✅ Tests
+
+- Full run: **33 files / 440 cases passed**, `npx tsc --noEmit -p tsconfig.test.json` clean.
+- New `src/i18n/index.test.ts` (14 cases: language detection priority / `C`·`POSIX` skipped / English fallback / interpolation / missing entry falls back to the key / Chinese and English entries correspond one to one) and `src/i18n/preferences.test.ts` (9 cases: tolerance of a missing, corrupt or invalid file, atomic write, `initLocale` detecting only once and persisting); `reasoning-effort.test.ts` gained 5 cases for "dimming does not rely on display text".
+- pty acceptance on a real terminal: `LANG=en_US.UTF-8` first launch → English, with `en` persisted; `/lang` to Chinese → status bar / input line / notices all follow, and **Chinese is kept after a restart** (the preference beats the system language); `/lang en` back to English works.
+- pty acceptance (stage 2): in English the slash menu shows `❯ /help  Show this help` and `/help` outputs an all-English list; after `/lang zh` the slash menu and `/help` switch back to Chinese as a whole.
+- pty acceptance (stages 3 / 4, isolated `AI_ZEN_DIR` + `LANG=en_US.UTF-8`): first launch detected as English and persisted; the startup screen shows `The AI collaboration desk in your terminal`; the main screen shows `Type a message, / for commands…` and `thinking default · total 0 tok`; the configuration center shows `◆ Configuration` with `+ New model — marked as custom automatically` / `openai · factory-managed · vision`; the model detail screen shows `◆ Model · GPT-6 Astra` / `factory-managed (editing switches it to custom)` / `Delete model`; the new-model and new-endpoint wizard screens are entirely English. After setting `preferences.json` back to `zh`, **a restart under `LANG=en_US.UTF-8` still shows the Chinese UI** (the preference beats the system language), and the Chinese text in the configuration center and model list matches the pre-rework state.
+- **Tests asserting Chinese always pin the language explicitly**: `setLocale("zh")` added in `screens.test.tsx`, `config-wizard.test.tsx`, `reasoning-effort.test.ts`, `registry.test.ts`, `agent-prompt.test.tsx`, `handoff-choice.test.ts`, `config-editor.test.ts`, `agent-switch.test.ts`, `model-switch.test.ts`, `handoff-service.test.ts`, `auto-migrate-confirm.test.ts` — the default language is `en`, and without pinning they would go red on CI for no apparent reason.
+- `mode.test.ts` gained 6 cases for `--tui`: with arguments it enters the TUI and the arguments become the first message; without arguments it behaves the same as without `--tui`; a command starting with `/` is not taken as an option / sub-command; `--tui --help` gives help priority; non-TTY is rejected rather than degraded; a `--tui` after `--` is an ordinary argument.
+- `mode.test.ts` gained 8 cases for `--new`: used alone it enters the TUI with `newSession: true`; `--tui --new <command>` carries both the first message and the new session; the order relative to `--tui` does not matter; with arguments it falls to stdio and is ignored; in non-TTY it falls to stdio and is ignored; `--tui --new` in non-TTY is still rejected rather than degraded; `--new --help` gives help priority; a `--new` after `--` is an ordinary argument.
+- New `src/hook.test.ts` (9 cases, all run under a temporary HOME, **never touching the real `~/.bashrc`**): the written function body contains `ai --tui --new "$@"` and exactly one block, existing rc content is preserved, repeated installation is idempotent, **an old function body already installed (`ai --tui "$@"`) is upgraded in place**, historical aiz blocks are migrated, zsh uses `command_not_found_handler` and writes to `.zshrc`; uninstalling removes the block and keeps the rest, leaves the file alone when nothing is installed, and does not error when the rc file does not exist.
+- pty acceptance (hook path): `ai --tui gti status` enters the TUI and automatically sends `gti status` as a user message (the UI shows `❯ you / gti status`), and after the model errors out (a deliberate local fake endpoint) the UI survives and further questions are possible; `ai --tui /opt/bin/nonexistent --flag` is likewise sent as an **ordinary message** and is not eaten by slash-command parsing; `ai --tui` in non-TTY exits with code 2; the function body written to `~/.bashrc` is `ai --tui --new "$@"` and passes `bash -n` syntax checking.
+- pty acceptance (`--new`, isolated `AI_ZEN_DIR` + a preset `last-session.json` pointing at an old conversation): `ai` continues it and shows the old message `MARKER-OLD-QUESTION`; `ai --new` lands in an **empty conversation**; `ai --tui --new gti status` starts empty and sends the first message automatically; `--help` lists `--new` in both the Chinese and English UI.
+- Full run after this change: **36 files / 487 cases passed**, `npx tsc --noEmit` and `-p tsconfig.test.json` both clean.
+- New `src/tui/phase.test.ts` (15 cases: the progression of each of the six states, tool name reuse, a trailing chunk without deltas not changing the stage, content beating reasoning, `reset` returning to zero, the six Chinese and English strings all differing from each other); `chat-session.test.ts` gained 3 cases (progression following the SDK event order, sub-agent output not overriding the main stage, the stage returning to zero when `send` ends).
+- pty acceptance (a local mock SSE server emitting the stream in stages): "connecting…" → "queued… (waiting for the first token)" → "thinking…" → "streaming…" → "calling tool no_such_tool…" → "waiting for sub_agent_default…" were all observed in order; the status bar carried only `⚡ 4.2 tok/s` and this round / cumulative tokens over the same period, with no "generating".
+- New `src/agent-switch.test.ts` (10 cases), `src/mcp-command.test.ts` (6 cases), `src/tui/token-rate.test.ts` (20 cases), `src/tui/status-segments.test.ts` (17 cases), `src/tui/screens/input-row.test.tsx` (7 cases), `src/tui/text.test.ts` (18 cases); `input-editing.test.ts` gained 3 cases for "an emoji is never cut in half".
+- `src/tui/screens.test.tsx` gained assertions for the order of the three status bar blocks, blocks not being split, side-by-side layout on wide screens, and "the row count Ink actually renders == the row count `statusBarRows` measures"; `computeInputCursorPosition` gained a case for "notice bar rows participate in y".
+- The `⚡` case in `input-row.test.tsx` asserts both "hand-computation gives 8, measurement gives 9" — the reason for this change is in those two lines.
 
 ## [1.0.0-alpha.20] - 2026-10-27
 
-### ✨ 新功能
+### ✨ New features
 
-- **对话屏支持鼠标滚轮滚动** —— 此前滚轮只能滚终端自己的回滚缓冲（`alternateScreen: false` 走内联渲染），滚上去看到的是历史帧快照，状态栏与输入框会直接滚出视野。
-  - 新增 `src/tui/mouse.ts`：挂载时下发 `DECSET 1000`（按钮事件，含滚轮）+ `1006`（SGR 扩展坐标）；`mount()` 的退出、`farewell()`、信号与未捕获异常兜底**三处**都下发关闭序列，进程崩了也不会把 `^[[<64;…M` 喷进 shell。
-  - `parseWheel()` 剥掉 Shift(4) / Meta(8) / Ctrl(16) 修饰位后取滚轮码（`64` 上、`65` 下），横向滚轮 `66` / `67` 直接忽略；一格滚 3 行。
-  - 滚轮与 `PgUp`/`PgDn`、按行滚动共用同一套视口钳制 —— 抽出纯函数 `clampViewTop()`（`screens/layout.ts`），越界方向自然吃掉，返回 `null` 即贴底跟随最新内容。生成过程中滚动不会被拉回底部。
-  - **`isTerminalReply()` 纳入鼠标序列**：点击 / 拖拽 / 滚轮一律在源头丢弃。这一步是必须的 —— Ink 会把整条 SGR 序列当 `char` 交给 `useInput`（实测为 `"[<64;10;5M"`，所有键标志位 false），不拦就会落进输入框变成正文。
-  - 必须用 `1006`（SGR 坐标）而不是老的 X10 编码：后者被 Ink 的解析器拆成 `[M` + 三个普通字符两条事件，三个字符会直接被当正文插入（已实测）。
-  - 启动屏「任意键跳过」不再把鼠标事件当成按键。
+- **The chat screen supports mouse wheel scrolling** — previously the wheel could only scroll the terminal's own scrollback buffer (`alternateScreen: false` uses inline rendering), and scrolling up showed snapshots of historical frames while the status bar and input line scrolled out of view entirely.
+  - New `src/tui/mouse.ts`: on mount it emits `DECSET 1000` (button events, wheel included) + `1006` (SGR extended coordinates); the close sequence is emitted in **three** places — `mount()`'s exit, `farewell()`, and the signal / uncaught exception fallback — so a crashing process does not spray `^[[<64;…M` into the shell.
+  - `parseWheel()` strips the Shift(4) / Meta(8) / Ctrl(16) modifier bits and takes the wheel code (`64` up, `65` down); horizontal wheel `66` / `67` is ignored outright; one notch scrolls 3 rows.
+  - The wheel shares one viewport clamp with `PgUp`/`PgDn` and line-wise scrolling — extracted into the pure function `clampViewTop()` (`screens/layout.ts`); scrolling against the boundary is absorbed naturally, and returning `null` means "glued to the bottom, following the newest content". Scrolling during generation is not snapped back to the bottom.
+  - **`isTerminalReply()` now covers mouse sequences**: clicks / drags / wheel events are dropped at the source. This step is mandatory — Ink hands the whole SGR sequence to `useInput` as `char` (measured as `"[<64;10;5M"`, all key flags false), and without filtering it lands in the input line as text.
+  - `1006` (SGR coordinates) must be used rather than the old X10 encoding: Ink's parser splits the latter into two events, `[M` plus three ordinary characters, and those three characters get inserted as text directly (verified by experiment).
+  - The startup screen's "press any key to skip" no longer treats mouse events as keys.
 
-### 📝 文档
+### 📝 Docs
 
-- README（中 / 英）键位表新增「鼠标滚轮」一行，并写明两个坑：开启上报后**拖选复制需按住 `Shift`**（回退到终端原生选择）；**`tmux` 用户需 `set -g mouse off`**，否则滚轮会先被 copy-mode 拦下。
-- `docs/manifest.json`、`docs/{zh,en}/getting-started.md`、README 中的版本号与运行时依赖版本对齐（`agents-core ^4.5.2`、`agents-sdk 1.0.0-alpha.18`）。
+- README (zh / en): the keybinding table gained a "mouse wheel" row, documenting two gotchas: with reporting enabled **drag-select copy requires holding `Shift`** (falling back to the terminal's native selection); **`tmux` users need `set -g mouse off`**, otherwise the wheel is intercepted by copy-mode first.
+- Version numbers and runtime dependency versions in `docs/manifest.json`, `docs/{zh,en}/getting-started.md` and the READMEs aligned (`agents-core ^4.5.2`, `agents-sdk 1.0.0-alpha.18`).
 
-### ⚠️ 已知取舍（终端机制使然，非缺陷）
+### ⚠️ Known trade-offs (inherent to the terminal, not defects)
 
-- 鼠标上报是终端级开关：点击 / 拖拽不再交给终端做原生选择，复制需按住 `Shift`（iTerm2 / Windows Terminal / kitty 等均如此）。
-- 应用内滚动只动视口，不产生终端 scrollback —— 想回看历史用滚轮 / `PgUp`，而不是终端的回滚条。
-- 老版 Windows `conhost` 不支持 `1006`，滚轮在那种终端上表现为无反应。
+- Mouse reporting is a terminal-level switch: clicks / drags no longer go to the terminal for native selection, and copying requires holding `Shift` (true for iTerm2 / Windows Terminal / kitty and others).
+- In-app scrolling only moves the viewport and produces no terminal scrollback — to review history use the wheel / `PgUp`, not the terminal scrollbar.
+- Old Windows `conhost` does not support `1006`, so the wheel appears to do nothing in that terminal.
 
-### ✅ 测试
+### ✅ Tests
 
-- 全量 **25 文件 / 316 例通过**（新增 `src/tui/mouse.test.ts` 1 文件 11 例；`screens.test.tsx` 新增滚轮解析、`clampViewTop` 钳制、启动屏鼠标守卫三组用例）。
-- 真机（pty）端到端验证：滚轮方向解析、修饰位剥离、点击丢弃、普通打字不受影响、退出时下发关闭序列。
+- Full run: **25 files / 316 cases passed** (new `src/tui/mouse.test.ts`, 1 file, 11 cases; `screens.test.tsx` gained three groups: wheel parsing, `clampViewTop` clamping, startup screen mouse guard).
+- End-to-end check on a real terminal (pty): wheel direction parsing, modifier stripping, clicks dropped, ordinary typing unaffected, close sequence emitted on exit.
 
 ## [1.0.0-alpha.19] - 2026-10-22
 
-### 🐛 修复
+### 🐛 Fixes
 
-- **修复升级后首次启动报「Agent「default」未绑定模型」** —— alpha.18 把模型真相源改成 `AgentDefinition.modelId`，并把「为历史 Agent 补齐 modelId」放在 `bootstrap()` 里。但 TUI 的**续接会话**路径（`resumeLastSession()` 命中上一轮存档）根本不会经过 `resolveTarget()`，也就不会读取配置，于是 `bootstrap()` 从未执行：Agent 还是没绑模型、`config.defaultModel` 也还在，启动直接失败。
-  - `runTui()` 开头显式 `await ensureConfigDir()`，配置初始化早于任何 Agent 读取；
-  - `modelOf()` 自身也先读一次配置（双重保险），即使调用方漏了也不会再撞到这个错误。
-- 新增回归测试：老配置（有 `defaultModel`、Agent 无 `modelId`）读一次配置后，模型被搬到 Agent 上、`config.json` 里的旧字段被清除。
+- **Fixed the "Agent 'default' is not bound to a model" error on the first launch after upgrading** — alpha.18 moved the model source of truth to `AgentDefinition.modelId` and put "backfill modelId for historical Agents" inside `bootstrap()`. But the TUI's **session continuation** path (`resumeLastSession()` hitting the previous archive) never goes through `resolveTarget()` and therefore never reads the configuration, so `bootstrap()` never ran: the Agent still had no model, `config.defaultModel` was still there, and startup failed outright.
+  - `runTui()` now explicitly `await ensureConfigDir()` at the start, so configuration initialization precedes any Agent read;
+  - `modelOf()` also reads the configuration once itself (double insurance), so a missed caller can no longer hit this error.
+- New regression test: with an old configuration (has `defaultModel`, Agent has no `modelId`), after one configuration read the model is moved onto the Agent and the old field in `config.json` is cleared.
 
-### ✅ 测试
+### ✅ Tests
 
-- 全量 **24 文件 / 299 例通过**。
+- Full run: **24 files / 299 cases passed**.
 
 ## [1.0.0-alpha.18] - 2026-10-22
 
-### 🐛 修复
+### 🐛 Fixes
 
-- **修复「模型显示与实际请求不是同一个」导致的 401 死锁** —— 此前模型有三处来源：状态栏与会话存档里的 `modelId`、Agent 定义里的 `modelId`、以及配置里的 `defaultModel`。三者一旦分叉，就会：
-  - 状态栏写着 `deepseek-flash`，请求实际发给 GLM，而 bigmodel 的 key 无效 → 看到 401；
-  - 想切回 DeepSeek 时，`/model` 拿**显示层**的值判断，发现「已经是当前模型」直接返回，实际模型一个字都没改——于是怎么切都还是 401，只能删配置。
+- **Fixed the 401 deadlock caused by "the displayed model is not the model actually requested"** — the model used to come from three places: the `modelId` in the status bar and the session archive, the `modelId` in the Agent definition, and the `defaultModel` in config. Once the three diverged:
+  - the status bar said `deepseek-flash`, the request actually went to GLM, and bigmodel's key was invalid → 401;
+  - when switching back to DeepSeek, `/model` judged by the **display layer** value, found that it was "already the current model" and returned immediately, without changing the actual model at all — so no amount of switching fixed the 401, and the only way out was deleting the config.
 
-  现在模型**只存在 `AgentDefinition.modelId` 一处**，状态栏、凭据预检、上下文阈值与 SDK 实发请求全部读它。
+  The model now **exists in exactly one place, `AgentDefinition.modelId`**, and the status bar, the credential pre-check, the context thresholds and the request the SDK actually sends all read it.
 
-### 🔧 行为变更（不兼容）
+### 🔧 Behavior changes (incompatible)
 
-- **升级 `@ai-zen/agents-sdk` 至 `1.0.0-alpha.17`**：配置层不再有 `defaultModel`，缺失 `modelId` 的 Agent 会直接报错（默认 Agent 出厂自带 `deepseek-flash`）；历史配置升级时会把老的 `defaultModel` 搬进默认 Agent，不改变你正在用的模型。
-- **会话存档不再记 `modelId`** —— 续接对话时模型完全由 Agent 定义决定；旧存档里的该字段读取时忽略。
-- **`/model` 只写 Agent 定义** —— 不再有「Agent 未绑定就改全局默认模型」的分支。
-- **切模型即重置思考强度** —— `AgentDefinition.modelParams` 在切模型时**直接清空**（不保留、不迁移、不逐键剔除），让目标模型走自己的 `defaultParams`。原因：思考参数是模型相关的，DeepSeek 关思考的 `thinking: {type:"disabled"}` 带到 GLM-5.3 上会被直接拒绝——此前会出现「一个不肯关思考的模型 + 一个说要关的参数」同时发出去。想调再用 `/think` 选一次。
-- **配置中心移除「默认模型」项** —— 模型改在 Agent 详情页的「模型」字段里选（影响范围从「全局默认」变成「该 Agent」）。
+- **Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.17`**: the config layer no longer has `defaultModel`, and an Agent missing `modelId` errors out immediately (the default Agent ships with `deepseek-flash`); when upgrading historical configs, the old `defaultModel` is moved into the default Agent, so the model in use does not change.
+- **Session archives no longer record `modelId`** — when a conversation is resumed, the model is determined entirely by the Agent definition; the field in old archives is ignored on read.
+- **`/model` only writes the Agent definition** — the branch that changed the global default model when the Agent had no binding no longer exists.
+- **Switching models resets reasoning effort** — `AgentDefinition.modelParams` is **cleared outright** when the model is switched (no retention, no migration, no per-key removal), so the target model uses its own `defaultParams`. Rationale: thinking parameters are model-specific, and DeepSeek's `thinking: {type:"disabled"}` for turning thinking off is rejected outright by GLM-5.3 — previously "a model unwilling to turn thinking off + a parameter saying to turn it off" could be sent together. To tune it again, select once more with `/think`.
+- **Removed the "default model" entry from the configuration center** — the model is now chosen in the "model" field of the Agent detail screen (scope changes from "global default" to "that Agent").
 
-### ✅ 测试
+### ✅ Tests
 
-- 全量 **24 文件 / 298 例通过**。
-- 新增 `model-switch` 用例：切换即清空 `modelParams`（不是只剔除思考键）、原本没有也不多写空对象。
+- Full run of **24 files / 298 cases passed**.
+- New `model-switch` cases: switching clears `modelParams` (not merely removing the thinking keys), and no extra empty object is written when there was none.
 
 ## [1.0.0-alpha.17] - 2026-10-22
 
-### 🔧 行为变更
+### 🔧 Behavior changes
 
-- **升级 `@ai-zen/agents-sdk` 至 `1.0.0-alpha.16`（内含 core `4.5.2`）：模型参数不再能覆盖请求体的固定字段** —— core 之前把模型参数 spread 在请求体最外层，于是 `Model.defaultParams` / `AgentDefinition.modelParams` 里若出现 `model` / `messages` / `tools` / `stream` / `stream_options`，会静默覆盖框架自己填的值。最惨的是 `stream: false`：流式被关掉而调用方仍按异步流解析，整轮直接失败。现在固定字段永远胜出。
-  - 对 `/think` 与思考档位**没有影响**：写入的都是 `thinking` / `reasoning_effort` 这类非固定键，照常透传。
-  - 唯一需要注意的是别在 `modelParams` 里手写上面那五个键——写了也不会生效。
+- **Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.16` (bundling core `4.5.2`): model parameters can no longer override the fixed fields of the request body** — core previously spread the model parameters at the outermost level of the request body, so if `model` / `messages` / `tools` / `stream` / `stream_options` appeared in `Model.defaultParams` / `AgentDefinition.modelParams`, they silently overrode the values the framework itself filled in. Worst of all was `stream: false`: streaming was turned off while the caller still parsed an async stream, failing the whole turn. Fixed fields now always win.
+  - This has **no effect** on `/think` and the effort levels: what gets written are non-fixed keys such as `thinking` / `reasoning_effort`, which pass through as before.
+  - The only thing to watch is not to hand-write those five keys in `modelParams` — writing them has no effect.
 
 ## [1.0.0-alpha.16] - 2026-10-22
 
-### 🔧 行为变更（不兼容）
+### 🔧 Behavior changes (incompatible)
 
-- **升级 `@ai-zen/agents-sdk` 至 `1.0.0-alpha.15`：思考档位不再「存档位名」，改存展开后的参数** —— 上一版把档位名写在 Agent 定义的 `reasoningEffort` 上，运行期由 SDK 查表翻译成请求参数。那等于把「什么叫 `max`」这件产品语义塞进了运行时。现在改成**配置即事实**：
-  - `/think` 把选中档位的参数补丁直接写进 `AgentDefinition.modelParams`（如 `{"thinking":{"type":"enabled"},"reasoning_effort":"high"}`），SDK 只做一次 `{...defaultParams, ...modelParams}` 浅合并；
-  - **旧 `reasoningEffort` 自动迁移**：读 Agent 定义时展开成 `modelParams` 并写回；模型没关联策略的只删旧字段（不会瞎猜参数）。
-- **思考策略表的归属调整为「SDK 提供、CLI 使用」** —— 表的类型、出厂内容与读写放在 SDK（CLI 与桌面端共享同一份「智谱 5.3 只认 low/high/max」的知识），CLI 只负责**利用**它：限制 `/think` 的可选档位、把档位展开成参数写进 Agent。`Scope` 不再需要注入策略表。
+- **Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.15`: effort levels no longer store the level name but the expanded parameters** — the previous version wrote the level name into the Agent definition's `reasoningEffort`, and at runtime the SDK looked it up in a table and translated it into request parameters. That pushed the product semantics of "what `max` means" into the runtime. It is now **configuration is the fact**:
+  - `/think` writes the selected level's parameter patch directly into `AgentDefinition.modelParams` (e.g. `{"thinking":{"type":"enabled"},"reasoning_effort":"high"}`), and the SDK only performs a single shallow merge of `{...defaultParams, ...modelParams}`;
+  - **the old `reasoningEffort` is migrated automatically**: when the Agent definition is read it is expanded into `modelParams` and written back; when the model has no associated preset, only the old field is deleted (no guessing at parameters).
+- **Ownership of the reasoning preset table adjusted to "provided by the SDK, used by the CLI"** — the table's types, factory content and read/write live in the SDK (the CLI and the desktop share the same knowledge that "Zhipu 5.3 only accepts low/high/max"), and the CLI only **consumes** it: limiting the levels `/think` offers and expanding a level into parameters written into the Agent. `Scope` no longer needs the preset table injected.
 
-### 🚀 新功能
+### 🚀 New features
 
-- **状态栏档位改为「从生效参数反查」** —— 显示的就是真正会发给 API 的那几个参数匹配到的档位（模型默认参数也算），不再依赖 Agent 上的档位声明。三种状态：命中某档 → 「低/中/高…」；有 Agent 覆盖但匹配不上任何档位（手改过参数）→「自定义」；完全匹配不上 →「默认」。
-- **`/config` →「模型」详情页的「思考策略」字段**继续可用，显示该策略及其档位（如 `zhipu-5.3（low / high / max）`），写错名字当场拦下。
+- **The status bar level is now looked up from the effective parameters** — it shows the level matched by the parameters that will actually be sent to the API (the model defaults included), no longer relying on the level declaration on the Agent. Three states: matches a level → "low / medium / high…"; there is an Agent override but it matches no level (parameters were edited by hand) → "custom"; no match at all → "default".
+- **The "reasoning preset" field in `/config` → "model" detail screen** remains available, showing the preset and its levels (e.g. `zhipu-5.3（low / high / max）`), and a wrong name is rejected on the spot.
 
-### ✅ 测试
+### ✅ Tests
 
-- `src/reasoning-effort.test.ts` 重写（19 例）：写入的是展开参数而非档位名、`max` → `off` 不残留 `reasoning_effort`、保留 `temperature` 等无关参数、`null` 清空后连 `modelParams` 一起删、往返一致（写进去能反查回原档位）。
-- 新增 `src/agents-store.test.ts`（4 例）：旧 `reasoningEffort` 展开并写回磁盘、无策略时只删字段、无旧字段时不写盘、迁移后能反查回原档位。
-- 全量 **24 文件 / 299 例通过**。
+- `src/reasoning-effort.test.ts` rewritten (19 cases): what is written is the expanded parameters rather than the level name; `max` → `off` leaves no residual `reasoning_effort`; unrelated parameters such as `temperature` are preserved; `null` clears and removes `modelParams` together; round trips are consistent (what was written can be looked up back to the original level).
+- New `src/agents-store.test.ts` (4 cases): the old `reasoningEffort` is expanded and written back to disk; only the field is deleted when there is no preset; nothing is written to disk when the old field is absent; the original level can be looked up again after migration.
+- Full run of **24 files / 299 cases passed**.
 
 ## [1.0.0-alpha.15] - 2026-10-22
 
-### 🔧 行为变更（不兼容）
+### 🔧 Behavior changes (incompatible)
 
-- **升级 `@ai-zen/agents-sdk` 至 `1.0.0-alpha.14`：思考能力改为声明式策略表** —— 上一版用 `Model.reasoning: { efforts, disable? }` 表达厂商差异，`disable` 一词双义、`off` 靠拼接、还用全局枚举假装各家档位等价。现在协议差异全部搬进一张表：
-  - 新增 `~/.ai-zen/reasoning-presets.json`（首次启动自动释放，出厂三张：`openai` / `zhipu-5.3` / `deepseek`）；模型只记 `reasoningPreset` 这个名字；
-  - `/think` 的可选档位改为读策略表 —— 表里有 `off` 才能关思考，没有就不给这个选项；
-  - 模型没关联策略、或策略名在表里不存在 → 一律视为不可调档（状态栏 `—`），绝不把来路不明的参数发出去；
-  - 档位中文标签改为「已知档位查表 + 未知档位名原样显示」，用户自建的档位名（如 `turbo`）不会显示成空白。
-- `src/stdio-runner.ts` / `src/tui/chat-session.ts` 的 `TokenThresholds` 改为直接从 SDK 导入（此前是绕开 alpha.13 缺导出的派生类型）。
+- **Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.14`: reasoning capability changed to a declarative preset table** — the previous version expressed vendor differences with `Model.reasoning: { efforts, disable? }`, where `disable` carried two meanings, `off` relied on concatenation, and a global enum pretended that every vendor's levels were equivalent. All protocol differences are now moved into one table:
+  - new `~/.ai-zen/reasoning-presets.json` (released automatically on first start, three factory presets: `openai` / `zhipu-5.3` / `deepseek`); a model only records the name `reasoningPreset`;
+  - the levels `/think` offers now come from the preset table — thinking can only be turned off if the table has `off`, and that option is not offered otherwise;
+  - a model with no preset associated, or with a preset name absent from the table → always treated as not adjustable (`—` in the status bar), and parameters of unknown origin are never sent;
+  - level labels became "look up known levels in the table + display unknown level names as-is", so level names created by users (e.g. `turbo`) are no longer shown as blank.
+- `TokenThresholds` in `src/stdio-runner.ts` / `src/tui/chat-session.ts` now imported directly from the SDK (previously a derived type that worked around the missing export in alpha.13).
 
-### 🚀 新功能
+### 🚀 New features
 
-- **`/config` →「模型」详情页新增「思考策略」字段** —— 显示该模型当前引用的策略及其档位（如 `zhipu-5.3（low / high / max）`），可直接改成表里另一个策略名；写错名字当场拦下并列出可选策略，留空 = 不调档。自建模型从此能指向内置策略，不必手改 JSON。
-- **策略表可自行编辑** —— 加一张表、调档位补丁都行；给某张表标 `"custom": true` 后 SDK 升级不再覆盖它，其余策略仍随 SDK 同步。
+- **New "reasoning preset" field in `/config` → "model" detail screen** — shows the preset the model currently references and its levels (e.g. `zhipu-5.3（low / high / max）`), and can be changed directly to another preset name from the table; a wrong name is rejected on the spot with the available presets listed, and leaving it empty = no level adjustment. Custom models can now point at a built-in preset without hand-editing JSON.
+- **The preset table can be edited** — adding a table or adjusting level patches is fine; once a table is marked `"custom": true`, SDK upgrades no longer overwrite it, while the remaining presets still sync with the SDK.
 
-### ✅ 测试
+### ✅ Tests
 
-- `src/reasoning-effort.test.ts` 重写（14 例）：可选档位 = 策略表的键、未知档位名原样显示、未关联策略/策略名不存在时抛错、状态栏在非法声明时回退「默认」。
-- 配置向导新增 2 例：写入合法策略名、非法策略名被拦下且不写盘。
-- 全量 **23 文件 / 290 例通过**。
+- `src/reasoning-effort.test.ts` rewritten (14 cases): available levels = the keys of the preset table; unknown level names displayed as-is; an error is thrown when no preset is associated / the preset name does not exist; the status bar falls back to "default" on an illegal declaration.
+- Configuration wizard: 2 new cases: writing a valid preset name; an invalid preset name is rejected and nothing is written to disk.
+- Full run of **23 files / 290 cases passed**.
 
 ## [1.0.0-alpha.14] - 2026-10-22
 
-### 🚀 新功能
+### 🚀 New features
 
-- **输入框键位对齐 Claude Code / readline** —— 编辑快捷键统一为业界通行的一套：
-  - 按词操作：`Alt+B` / `Alt+F` 跨词移动（macOS 上 `Option+←/→` 发的就是 `ESC b` / `ESC f`，此前完全不响应）；`Alt+Backspace`、`Alt+D`、`Ctrl+Delete` 按词删除
-  - 整段操作：`Ctrl+K` 删到行尾、`Ctrl+U` 删到行首、`Ctrl+W` **删到前一空白**（标点不切分，`src/utils/foo.ts` 一次删完）
-  - kill ring：`Ctrl+Y` 取回刚删的文本，`Alt+Y` 循环取回更早的；`Ctrl+_` 撤销上一次输入编辑；`Ctrl+S` 暂存 / 恢复草稿
-  - 移动与历史：`Ctrl+A` / `Ctrl+E` 行首 / 行尾，`Ctrl+P` / `Ctrl+N` 历史上下
-  - 新增纯函数层 `src/tui/input-editing.ts`（`deleteToPrevWhitespace` / `killedText` / kill ring / 撤销栈），12 例单测
-- **macOS 按键诊断** —— `AIZ_DEBUG_KEYS=1` 时把终端环境（`TERM` / `TERM_PROGRAM`）与每次按键（`input` + 修饰位 + `raw` 状态）写入 `/tmp/aiz-key-debug.log`（`AIZ_KEYS_FILE` 可改路径），用于定位「某个键在我机器上没反应」：没新行=键被系统截走，`flags` 不符=匹配逻辑问题，`raw=false`=按键被终端自己解释。
-- **`/model` 切换当前会话的模型并写入配置** —— 无参弹模型选择器（标注当前），`/model <id>` 直切。写入位置按「会话模型真正的来源」决定：Agent 定义显式绑定了模型 → 改该 Agent 的 `modelId`；没绑定（走默认模型）→ 改 `config.json` 的 `defaultModel`。切换后重建 Scope 与会话（消息与上下文保留），状态栏模型名随之更新。判定逻辑抽为 `src/model-switch.ts`（`resolveModelWriteTarget` / `switchModel`，7 例单测）。
-- **思考强度展示与切换（`/think`，别名 `/effort`）** —— 状态栏在模型名后展示当前强度（`关` / `极低` / `低` / `中` / `高` / `极高` / `最高`；模型可调但 Agent 未声明时显示`默认`，模型不可调时显示 `—`）。`/think` 无参弹选择器（标注当前）、`/think high` 直设、`/think default` 清除声明恢复跟随模型默认。
-  - **档位存在 Agent 定义上**（`AgentDefinition.reasoningEffort`），不在模型上：同一个模型可以给编程 / 小说 / 闲聊三个 Agent 配不同强度，而模型的 `defaultParams` 不动。
-  - **可选档位由模型能力决定**（`Model.reasoning.efforts`，SDK 按厂商官方文档声明）：智谱 GLM-5.3 系只有 `low/high/max` 且不能关（传 `medium` 或 `disabled` 会 400），DeepSeek 是 `off/low/high/max`，OpenAI 是 `off/minimal/low/medium/high`；模型没声明就一个档位都不给，绝不推测。
-  - 读写与校验抽为 `src/reasoning-effort.ts`（`effortChoices` / `describeEffort` / `setAgentEffort`，9 例单测）。
-- **SDK 日志接管** —— TUI 启动即 `setLogger()`，关掉 SDK 的 `console.log` 兜底（否则 `load_mcp` 的 manifest 会直写 stdout 撕裂界面）；`AIZ_DEBUG_SDK=1` 时改为落盘 `/tmp/aiz-sdk.log`（`AIZ_SDK_LOG_FILE` 可改路径），6 例单测。
+- **Input line keys aligned with Claude Code / readline** — editing shortcuts unified to the industry-standard set:
+  - word operations: `Alt+B` / `Alt+F` move by word (on macOS `Option+←/→` sends `ESC b` / `ESC f`, which previously did not respond at all); `Alt+Backspace`, `Alt+D`, `Ctrl+Delete` delete by word
+  - whole-segment operations: `Ctrl+K` deletes to end of line, `Ctrl+U` deletes to start of line, `Ctrl+W` **deletes to the previous whitespace** (punctuation does not split, so `src/utils/foo.ts` goes in one go)
+  - kill ring: `Ctrl+Y` retrieves the text just deleted, `Alt+Y` cycles through earlier ones; `Ctrl+_` undoes the last input edit; `Ctrl+S` stashes / restores the draft
+  - movement and history: `Ctrl+A` / `Ctrl+E` start / end of line, `Ctrl+P` / `Ctrl+N` previous / next history
+  - new pure-function layer `src/tui/input-editing.ts` (`deleteToPrevWhitespace` / `killedText` / kill ring / undo stack), 12 unit tests
+- **macOS key diagnostics** — with `AIZ_DEBUG_KEYS=1` the terminal environment (`TERM` / `TERM_PROGRAM`) and every key press (`input` + modifier bits + `raw` state) are written to `/tmp/aiz-key-debug.log` (path configurable via `AIZ_KEYS_FILE`), for tracking down "a key does nothing on my machine": no new line = the key was intercepted by the system, `flags` mismatch = a matching logic problem, `raw=false` = the key was interpreted by the terminal itself.
+- **`/model` switches the current session's model and writes the config** — with no argument it opens a model picker (annotating the current one), and `/model <id>` switches directly. The write target depends on "where the session model really comes from": model bound explicitly in the Agent definition → that Agent's `modelId` is changed; not bound (using the default model) → `defaultModel` in `config.json` is changed. After switching, the Scope and session are rebuilt (messages and context retained) and the model name in the status bar updates. The decision logic is extracted into `src/model-switch.ts` (`resolveModelWriteTarget` / `switchModel`, 7 unit tests).
+- **Reasoning effort display and switching (`/think`, alias `/effort`)** — the status bar shows the current effort after the model name (`off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`; `default` when the model is adjustable but the Agent has no declaration, `—` when the model is not adjustable). `/think` with no argument opens a picker (annotating the current one), `/think high` sets directly, `/think default` clears the declaration and follows the model default again.
+  - **The level lives on the Agent definition** (`AgentDefinition.reasoningEffort`), not on the model: the same model can have different efforts for the coding / novel / chat Agents, while the model's `defaultParams` stay untouched.
+  - **Available levels are decided by model capability** (`Model.reasoning.efforts`, declared by the SDK per the vendor's official docs): Zhipu GLM-5.3 only has `low/high/max` and cannot be turned off (passing `medium` or `disabled` returns 400), DeepSeek is `off/low/high/max`, OpenAI is `off/minimal/low/medium/high`; a model with no declaration offers no level at all — never guessed.
+  - Read/write and validation are extracted into `src/reasoning-effort.ts` (`effortChoices` / `describeEffort` / `setAgentEffort`, 9 unit tests).
+- **SDK logging takeover** — the TUI calls `setLogger()` on startup, disabling the SDK's `console.log` fallback (otherwise the `load_mcp` manifest writes straight to stdout and tears the UI apart); with `AIZ_DEBUG_SDK=1` it writes to `/tmp/aiz-sdk.log` instead (path configurable via `AIZ_SDK_LOG_FILE`), 6 unit tests.
 
-### 🔧 行为变更（不兼容）
+### 🔧 Behavior changes (incompatible)
 
-- **升级 `@ai-zen/agents-sdk` 至 `1.0.0-alpha.13`，上下文阈值改为结构体** —— `Model.maxContextTokens` 被 `Model.tokenThresholds: { handoff, guard }` 取代（`maxContextChars` 淘汰）：
-  - `handoff`：交接软线，`prompt_tokens` 超过它触发任务交接；
-  - `guard`：强行阻断硬线，每次请求**前**超过它即中断本轮并报错。
-  - 两条线都是**绝对值**，`ContextGuardPlugin` 的 `ratio` / `suspendedRatio` / `isSuspended` 已从 SDK 删除——想调松就改数字。代价是交接回合不再有 2.0 倍额外放宽，出厂把 `guard` 配成 `handoff × 1.5`（375K）以留出缓冲。
-  - 旧配置**自动迁移**：SDK 的 `ConfigManager.read()` 读到即迁（`maxContextTokens` → `handoff`，`maxContextChars` 按 `/4` 折算，缺 `guard` 按 1.5 倍补一次，旧键删除），检测到差异才写回磁盘。用户无需手改 `config.json`。
-  - 配置中心里原来的「迁移阈值」一项拆成「交接阈值」与「阻断阈值」两行，并校验软线必须小于硬线。
+- **Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.13`, context thresholds changed to a struct** — `Model.maxContextTokens` is replaced by `Model.tokenThresholds: { handoff, guard }` (`maxContextChars` retired):
+  - `handoff`: the soft handoff line; `prompt_tokens` exceeding it triggers a task handoff;
+  - `guard`: the hard cutoff line; exceeding it **before** each request aborts the turn with an error.
+  - both lines are **absolute values**, and `ratio` / `suspendedRatio` / `isSuspended` of `ContextGuardPlugin` are removed from the SDK — loosen things by changing the numbers. The cost is that the handoff turn no longer gets the 2.0× extra allowance; by default `guard` is configured as `handoff × 1.5` (375K) to leave headroom.
+  - old configs are **migrated automatically**: the SDK's `ConfigManager.read()` migrates on read (`maxContextTokens` → `handoff`, `maxContextChars` converted by `/4`, a missing `guard` filled in once at 1.5×, old keys deleted), writing back to disk only when a difference is detected. Users do not need to hand-edit `config.json`.
+  - the former "migration threshold" entry in the configuration center is split into "handoff threshold" and "guard threshold" rows, and the soft line is validated to be less than the hard line.
 
-- **`Ctrl+N` 由「换行」改为「历史下一条」** —— 换行改用 `Ctrl+J` / `Ctrl+Enter` / `Alt+Enter` / `Shift+Enter` / `\` + `Enter`
-- **`Ctrl+V` 不再兼任「翻页」** —— 预留给 Claude Code 的「粘贴图片」；当前按下会提示暂未实现。翻页用 `PgUp` / `PgDn`，按行滚动用 `Shift+↑ ↓` / `Alt+↑ ↓`
-- **`Ctrl+U` 由「清空整个输入框」改为「删到行首」** —— macOS 的 iTerm2 与 Terminal.app 会把 `⌘⌫` 映射成 `Ctrl+U`，原先的语义会让 Mac 用户一按 ⌘⌫ 就丢掉整段草稿；清空全部改由 `Esc` 负责
-- **`Ctrl+C` 空闲时不再直接退出** —— 有草稿时先清空并提示，再按一次才退出
-- **`Ctrl+D` 改为双击确认退出** —— 有草稿时改为 readline 语义（删光标后一个字符）
-- **忙碌期（生成 / 迁移中）`Esc` 现在等于中断本轮**
+- **`Ctrl+N` changed from "newline" to "next history entry"** — newline is now `Ctrl+J` / `Ctrl+Enter` / `Alt+Enter` / `Shift+Enter` / `\` + `Enter`
+- **`Ctrl+V` no longer doubles as "page down"** — reserved for Claude Code's "paste image"; pressing it now shows a not-implemented-yet notice. Paging uses `PgUp` / `PgDn`, scrolling by line uses `Shift+↑ ↓` / `Alt+↑ ↓`
+- **`Ctrl+U` changed from "clear the whole input box" to "delete to start of line"** — iTerm2 and Terminal.app on macOS map `⌘⌫` to `Ctrl+U`, and the old semantics made Mac users lose an entire draft with a single ⌘⌫; clearing everything is now handled by `Esc`
+- **`Ctrl+C` no longer exits directly when idle** — with a draft, it clears the draft first with a notice, and a second press exits
+- **`Ctrl+D` changed to double-press to confirm exit** — with a draft, readline semantics apply (delete one character after the cursor)
+- **`Esc` during a busy period (generating / migrating) now aborts the current turn**
 
-### ⏳ 暂未实现
+### ⏳ Not implemented yet
 
-- **粘贴图片（`Ctrl+V`）** —— 需要先解决「文件 → 内容块」的端点能力探测（Files API 上传 vs base64 内联），不能把上传端点硬编码成某个 id；随后的 SDK 改造再做，本轮已把该功能代码移除，避免半成品上线。
+- **Pasting images (`Ctrl+V`)** — the endpoint capability probe for "file → content block" has to be solved first (Files API upload vs base64 inline), and the upload endpoint must not be hardcoded to a particular id; the subsequent SDK rework comes after, and the code for this feature was removed in this round to avoid shipping a half-finished feature.
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/tui/input-editing.test.ts`（12 例）+ `src/tui/key-debug.test.ts`（4 例）+ `src/sdk-log.test.ts`（6 例）+ `src/model-switch.test.ts`（7 例）+ `src/reasoning-effort.test.ts`（9 例）+ 输入工具函数 8 例；全量 **23 文件 / 286 例** 通过，`tsc` 与 `build` 零错误。
+- New `src/tui/input-editing.test.ts` (12 cases) + `src/tui/key-debug.test.ts` (4 cases) + `src/sdk-log.test.ts` (6 cases) + `src/model-switch.test.ts` (7 cases) + `src/reasoning-effort.test.ts` (9 cases) + 8 cases for the input utility functions; full run of **23 files / 286 cases** passed, `tsc` and `build` with zero errors.
 
-### 📄 文档
+### 📄 Docs
 
-- `README{,.zh}.md` 重写「键盘与终端兼容」小节：改为业界通行路线「Option 当 Meta + readline 系 Ctrl 键」，附 Apple Terminal / iTerm2 / VS Code / Ghostty 的具体设置路径；说明 `⌘` 需 kitty 键盘协议才会上报、`⌘⌫` 被终端映射为 `Ctrl+U` 的原因；补充按键诊断用法。`README{,.zh}.md` 与 `docs/{zh,en}/getting-started.md` 的命令表新增 `/model`、`/think`（含「配置文件来源」对照），`docs/manifest.json` 版本号同步。
+- Rewrote the "keyboard and terminal compatibility" section of `README{,.zh}.md`: switched to the industry-standard route "Option as Meta + readline-style Ctrl keys", with the concrete settings paths for Apple Terminal / iTerm2 / VS Code / Ghostty; explained that `⌘` only reports with the kitty keyboard protocol, and why `⌘⌫` is mapped to `Ctrl+U` by the terminal; added the usage of key diagnostics. The command tables in `README{,.zh}.md` and `docs/{zh,en}/getting-started.md` gained `/model` and `/think` (with a "config file source" comparison), and the version in `docs/manifest.json` was synced.
 
 ## [1.0.0-alpha.13] - 2026-10-21
 
-### 🚀 新功能
+### 🚀 New features
 
-- **交接二次确认统一为「三选一」** —— 自动迁移、手动 `/migrate`、手动 `/handoff` 三条链路此前交互不一致（自动是 2 项选择器 + Esc 跳过；`/migrate` 是 yes/no 确认；`/handoff` 不询问）。现统一为同一个「交接方式」选择器：
-  - **当前会话自己写交接文档**（`self`，保真 · 可核实真实状态）
-  - **单独 Agent 写交接文档**（`summary`，独立摘要 · 快且省，不核实文件）
-  - **不交接**（跳过本次；`Esc` 同效）
+- **Handoff confirmation unified to a three-way choice** — the three paths of automatic migration, manual `/migrate` and manual `/handoff` previously behaved inconsistently (automatic: a 2-item picker + Esc to skip; `/migrate`: a yes/no confirmation; `/handoff`: no question). They are now unified into the same "handoff mode" picker:
+  - **the current session writes the handoff doc itself** (`self`, faithful · the real state can be verified)
+  - **a separate Agent writes the handoff doc** (`summary`, independent summary · fast and cheap, files are not verified)
+  - **no handoff** (skip this time; `Esc` does the same)
 
-  命令后显式带 `self` / `summary`（如 `/migrate self`）时直接执行、不再询问。选择器抽为共用模块 `src/tui/screens/handoff-choice.ts`，三处复用同一份选项与文案。
+  When `self` / `summary` is given explicitly after the command (e.g. `/migrate self`), it executes directly without asking. The picker is extracted into the shared module `src/tui/screens/handoff-choice.ts`, with the same options and copy reused in all three places.
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **自动「不交接」的确认提示被覆盖** —— `notice` 通道只保留最新一条，原先「已跳过本次任务迁移」与「可随时 /migrate…」分两条推送，后者覆盖前者；现合并为单条，跳过确认可见。
+- **The confirmation notice for an automatic "no handoff" was overwritten** — the `notice` channel keeps only the latest entry, and the previous "this task migration has been skipped" and "you can /migrate at any time…" were pushed as two entries, the latter overwriting the former; they are now merged into a single entry, so the skip confirmation is visible.
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/tui/screens/handoff-choice.test.ts`（5 例）：三选一取值顺序、`self`/`summary` 原样返回、「不交接」/`Esc` → `null`、标题透传。全量 **18 文件 / 237 用例**通过，`tsc` 与 `build` 零错误。
+- New `src/tui/screens/handoff-choice.test.ts` (5 cases): the value order of the three-way choice, `self`/`summary` returned as-is, "no handoff"/`Esc` → `null`, title passed through. Full run of **18 files / 237 cases** passed, `tsc` and `build` with zero errors.
 
-### 📄 文档
+### 📄 Docs
 
-- `docs/{zh,en}/migration.md`「触发方式」同步为统一的三选一交互（手动命令均会先询问，除非显式指定执行者）；`docs/manifest.json`、`README{,.zh}.md` 版本号同步。
+- The "trigger methods" section of `docs/{zh,en}/migration.md` synced to the unified three-way choice (manual commands always ask first unless the executor is specified explicitly); the versions in `docs/manifest.json` and `README{,.zh}.md` synced.
 
 ## [1.0.0-alpha.12] - 2026-10-20
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **自动迁移后旧会话被覆盖、历史丢失** —— `ChatSession` 曾把会话 id 存两份（`this.currentId` 与 `ctx.currentId`）。手动 `/migrate` 与 `/new` 会同步两份，但**自动迁移**由 SDK 的 `AutoMigratePlugin` 直接驱动 `HandoffService.migrate()`，**不经过 `ChatSession` 的任何方法**，新 id 只写进了 `ctx.currentId`。于是 `ConversationPersistPlugin.getId()` 仍返回旧 id，迁移后第一次落盘就把 `prune` 产生的「系统提示 + 交接断点」写进**旧会话文件**，把已保存的完整历史覆盖掉（用户表现为「交接之后历史全没了，只剩交接文档」）。
-  - 修法：`currentId` / `currentName` 改为**代理 `ctx` 的 getter/setter**，消灭双真相源——谁更新 `ctx` 都立刻生效。
-  - `ConversationContext.currentId` 由 `string | undefined` 收紧为 `string`；`reset()` 中两行冗余双写随之删除。
-- **测试污染**：`chat-session.test.ts` 的端到端用例会把交接文档写进 `<cwd>/.ai-zen/handoffs`，现改指临时目录并自动清理。
+- **After automatic migration the old session was overwritten and history was lost** — `ChatSession` used to store the session id in two places (`this.currentId` and `ctx.currentId`). Manual `/migrate` and `/new` synced both, but **automatic migration** is driven by the SDK's `AutoMigratePlugin` calling `HandoffService.migrate()` directly and **goes through no method of `ChatSession`**, so the new id was written only into `ctx.currentId`. `ConversationPersistPlugin.getId()` therefore still returned the old id, and the first write after migration stored the "system prompt + handoff breakpoint" produced by `prune` into the **old session file**, overwriting the complete saved history (users saw "all history gone after the handoff, only the handoff doc left").
+  - Fix: `currentId` / `currentName` became **getters/setters proxying `ctx`**, eliminating the second source of truth — whoever updates `ctx` takes effect immediately.
+  - `ConversationContext.currentId` narrowed from `string | undefined` to `string`; the two redundant double writes in `reset()` were removed accordingly.
+- **Test pollution**: the end-to-end case in `chat-session.test.ts` wrote handoff docs into `<cwd>/.ai-zen/handoffs`; it now points at a temp directory with automatic cleanup.
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 3 例：`ctx` 变更即时生效、赋值回写 `ctx`、端到端（真实 `handoffService.migrate()` 后 id 必须跟随；该用例在修复前会失败，已反向验证）。全量 **17 文件 / 232 用例**通过，`tsc`（含测试工程）与 `build` 零错误。
+- 3 new cases: `ctx` changes take effect immediately; assignment writes back to `ctx`; end to end (the id must follow after a real `handoffService.migrate()`; this case does fail before the fix, verified in reverse). Full run of **17 files / 232 cases** passed, `tsc` (including the test project) and `build` with zero errors.
 
-### 📄 文档
+### 📄 Docs
 
-- `docs/{zh,en}/migration.md`「迁移链路」补充「会话 id 只有一个真相源」的约束与失效表现；`docs/manifest.json`、`README{,.zh}.md` 版本号同步。
-- 依赖仍为 `@ai-zen/agents-sdk` `1.0.0-alpha.11`（本次无 SDK 改动）。
+- The "migration chain" section of `docs/{zh,en}/migration.md` gained the constraint "the session id has a single source of truth" and its failure symptoms; the versions in `docs/manifest.json` and `README{,.zh}.md` synced.
+- The dependency is still `@ai-zen/agents-sdk` `1.0.0-alpha.11` (no SDK changes this time).
 
 ## [1.0.0-alpha.11] - 2026-10-20
 
-### ⚠️ 依赖
+### ⚠️ Dependencies
 
-- `@ai-zen/agents-sdk` `1.0.0-alpha.10 → 1.0.0-alpha.11`（`createCallMcpTool` 新增 `env` 参数为破坏性变更；CLI 不直接调用该工厂，无代码改动）。
+- `@ai-zen/agents-sdk` `1.0.0-alpha.10 → 1.0.0-alpha.11` (the new `env` parameter of `createCallMcpTool` is a breaking change; the CLI does not call that factory directly, so there are no code changes).
 
-### 🔧 变更（随 SDK）
+### 🔧 Changes (with SDK)
 
-- **`call_mcp_tool` 输出保护**：调用 MCP 工具时，文本输出超过 `maxToolOutput`（默认 32768 字符）会完整落盘为 `result.txt`，只返回警告 + 头尾预览，可用 `read` 分批读取——不再一次把上万字符灌进上下文。
-- **图片 / 音频 / 二进制资源原样返回**：MCP 返回的 `image` / `audio` / `resource.blob` 转成 `image_url` / `file` 内容块透传（`resource.text` 并入正文、`resource_link` 转为可读线索），不再静默丢弃；媒体不受 `maxToolOutput` 约束。
+- **`call_mcp_tool` output protection**: when an MCP tool is called, text output exceeding `maxToolOutput` (32768 characters by default) is written in full to `result.txt`, and only a warning plus a head/tail preview is returned, readable in batches with `read` — no more pouring tens of thousands of characters into the context at once.
+- **Images / audio / binary resources returned as-is**: the `image` / `audio` / `resource.blob` returned by MCP are converted into `image_url` / `file` content blocks and passed through (`resource.text` merged into the body, `resource_link` turned into readable clues), no longer dropped silently; media is not subject to `maxToolOutput`.
 
-### 📄 文档
+### 📄 Docs
 
-- `docs/{zh,en}/mcp.md` 说明「仅文本受输出保护、媒体不受上限约束」；`docs/{zh,en}/getting-started.md`、`docs/manifest.json`、`README{,.zh}.md` 版本同步。
+- `docs/{zh,en}/mcp.md` explains "only text is subject to output protection; media is not limited by the cap"; the versions in `docs/{zh,en}/getting-started.md`, `docs/manifest.json` and `README{,.zh}.md` synced.
 
 ## [1.0.0-alpha.10] - 2026-10-20
 
-### 💥 变更
+### 💥 Changes
 
-- **交接与迁移拆成两条命令**（语义唯一，命名与实现对齐）：
-  - **`/handoff`** —— 原 agent 停手、核实状态、把交接文档写到 `<项目>/.ai-zen/handoffs/`，**会话照旧**（不弹确认，可反复执行；交接回合留在 `agent.messages` 里，可继续要求细化同一份文档）；
-  - **`/migrate`**（别名 `/migration`）—— 同一次交接 + 清历史 + 开新会话（需确认）。
-  - 两条都支持 `self` / `summary` 参数（如 `/handoff summary`、`/migrate self`）跳过默认选择。
-- **自动迁移改为「执行者三选一」选择器**：上下文超阈值时不再只问「是否迁移」，而是选择 **原 agent 自交接（默认高亮，保真）/ 独立摘要（便宜）/ 跳过本次**。选择器复用既有 picker 浮层（`setPickerState`）。非交互环境（管道、重定向、e2e）无选择通道，按默认执行者迁移，不阻塞、不额外输出。
-- **交接文档目录**：新增 `PROJECT_HANDOFFS_DIR = <cwd>/.ai-zen/handoffs`，交接文档落在项目内，可随仓库共享/评审。
+- **Handoff and migration split into two commands** (single semantics, naming aligned with the implementation):
+  - **`/handoff`** — the original agent stops, verifies the state and writes the handoff doc to `<project>/.ai-zen/handoffs/`, with the **session unchanged** (no confirmation, repeatable; the handoff turn stays in `agent.messages`, so you can keep asking to refine the same doc);
+  - **`/migrate`** (alias `/migration`) — the same handoff + clear history + start a new session (confirmation required).
+  - both support the `self` / `summary` argument (e.g. `/handoff summary`, `/migrate self`) to skip the default choice.
+- **Automatic migration changed to an "executor three-way choice" picker**: when the context exceeds the threshold it no longer only asks "whether to migrate", but offers **self-handoff by the original agent (highlighted by default, faithful) / independent summary (cheap) / skip this time**. The picker reuses the existing picker overlay (`setPickerState`). Non-interactive environments (pipes, redirection, e2e) have no choice channel and migrate with the default executor, without blocking or extra output.
+- **Handoff doc directory**: new `PROJECT_HANDOFFS_DIR = <cwd>/.ai-zen/handoffs`, so handoff docs live inside the project and can be shared / reviewed with the repository.
 
-### ♻️ 重构
+### ♻️ Refactors
 
-- **`src/migration-service.ts` → `src/handoff-service.ts`**：`createMigrationService` → `createHandoffService`，钩子从 `onBeforeMigrate` / `onMigrated` 改为 `onBeforeHandoff` / `onHandoff` / `onMigrated`。存档旧会话移到 `onHandoff`（此时已包含交接回合，归档可审计）；`/handoff` 不切换会话也因此不需要额外存档（`ConversationPersistPlugin` 每轮已落盘）。
-- **`src/auto-migrate-confirm-plugin.ts` → `src/auto-migrate-confirm.ts`**：`AutoMigrateConfirmPlugin`（继承 + 重写 `onAfterSend`）退化为 `createAutoMigratePlugin()` 工厂——「何时迁移」仍在 SDK 插件里，「用谁交接」通过 SDK 新增的 `resolveMode` 回调注入，不再重复实现阈值判断。
-- `src/agent-creator.ts` 抽出并导出 `listSkillDirs()`：Scope 装配与交接服务（读取 `handoff` Skill 正文）共用同一份目录优先级，避免两处各算一遍。
-- `ChatSessionOptions.requestConfirm` → `requestMode`（返回 `HandoffMode | null`）；`ChatSession.migrate()` / `handoff()` 返回文档路径；`ConversationContext.migrationService` → `handoffService`。
-- `ContextGuardPlugin` 接线 `isSuspended: () => handoffService.busy`：交接回合护栏从 `× 1.5` 放宽到 `× 2`。
-- 斜杠命令解析支持参数：命令名取首个 token（`/migrate summary` 不再被当成未知命令）。
+- **`src/migration-service.ts` → `src/handoff-service.ts`**: `createMigrationService` → `createHandoffService`, and the hooks change from `onBeforeMigrate` / `onMigrated` to `onBeforeHandoff` / `onHandoff` / `onMigrated`. Archiving the old session moved to `onHandoff` (which now already contains the handoff turn, making the archive auditable); `/handoff` does not switch sessions and therefore needs no extra archiving (`ConversationPersistPlugin` already writes to disk every turn).
+- **`src/auto-migrate-confirm-plugin.ts` → `src/auto-migrate-confirm.ts`**: `AutoMigrateConfirmPlugin` (inheriting and overriding `onAfterSend`) degenerated into the `createAutoMigratePlugin()` factory — "when to migrate" stays in the SDK plugin, and "who does the handoff" is injected through the SDK's new `resolveMode` callback, with the threshold logic no longer reimplemented.
+- `src/agent-creator.ts` extracted and exported `listSkillDirs()`: Scope assembly and the handoff service (which reads the body of the `handoff` Skill) share the same directory priority, so it is not computed twice.
+- `ChatSessionOptions.requestConfirm` → `requestMode` (returning `HandoffMode | null`); `ChatSession.migrate()` / `handoff()` return the doc path; `ConversationContext.migrationService` → `handoffService`.
+- `ContextGuardPlugin` wired with `isSuspended: () => handoffService.busy`: the handoff-turn guard is relaxed from `× 1.5` to `× 2`.
+- Slash command parsing supports arguments: the command name is the first token (`/migrate summary` is no longer treated as an unknown command).
 
-### ⚠️ 依赖
+### ⚠️ Dependencies
 
-- `@ai-zen/agents-sdk` `1.0.0-alpha.9 → 1.0.0-alpha.10`（`TaskMigrationService` → `HandoffService` 为破坏性变更）。
+- `@ai-zen/agents-sdk` `1.0.0-alpha.9 → 1.0.0-alpha.10` (`TaskMigrationService` → `HandoffService` is a breaking change).
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/handoff-service.test.ts`（迁移清 `lastUsage` / 新会话落盘 / `/handoff` 不切会话）、`src/auto-migrate-confirm.test.ts`（非交互默认值、选择透传、取消跳过、busy 让行）。全量 **17 文件 / 229 用例**通过，`tsc --noEmit`（含测试工程）与 `build` 零错误。
+- New `src/handoff-service.test.ts` (migration clears `lastUsage` / the new session is written to disk / `/handoff` does not switch sessions), `src/auto-migrate-confirm.test.ts` (non-interactive default, choice passed through, cancel skips, busy yields). Full run of **17 files / 229 cases** passed, `tsc --noEmit` (including the test project) and `build` with zero errors.
 
-### 📄 文档
+### 📄 Docs
 
-- `docs/{en,zh}/migration.md` 重写为「任务交接与迁移」：两条命令的差异、两种执行者的取舍、自交接的代码级保障（守卫/放宽/防递归）、文档位置与命名、模板由 `handoff` Skill 承载（`metadata.custom: "true"` 退出同步、可项目级覆盖）、成本说明。网站镜像同步。
-- `README.md` / `README.zh.md` 命令表与「任务交接与迁移」章节、`docs/{en,zh}/index.md` 特性与导航同步。
+- `docs/{en,zh}/migration.md` rewritten as "task handoff and migration": the difference between the two commands, the trade-offs of the two executors, the code-level guarantees of self-handoff (guard / relaxation / recursion prevention), doc location and naming, the template carried by the `handoff` Skill (`metadata.custom: "true"` opts out of sync and can be overridden per project), and cost notes. The website mirror synced.
+- The command table and the "task handoff and migration" chapter of `README.md` / `README.zh.md`, and the features and navigation of `docs/{en,zh}/index.md`, synced.
 
 ## [1.0.0-alpha.9] - 2026-10-14
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **自动迁移与 CLI 的交互适配（两处）**：
-  - **迁移期间输入框未真正拦住** —— 主输入 `useInput` 的 `isActive` 此前只挡「确认框 / 选择器 / 配置向导」，未挡「生成中」态。自动迁移在 `send()` 内 `await onAfterSend` 执行（`busy` 为真、输入框已被 Spinner 顶替），但按键仍会被静默吞进隐藏的输入缓冲、待本轮结束才浮现。现令主输入在 `busy` 时整体失活，另设「忙碌期」处理器仅放行 `Ctrl+C` 中止 / `Ctrl+D` 退出 / `PgUp`·`Shift+↑↓` 回看；`/migrate` 手动迁移同样纳入 `busy`。
-  - **迁移完成后仍被总上下文护栏拦截** —— 迁移（prune）会物理重置上下文，却遗留 `agent.lastUsage`（迁移前那一次请求的 `prompt_tokens`）。`ContextGuardPlugin`（`onInnerLoopStart`，硬上限 `maxTokens × 1.5`）据此误判，迁移后第一条消息即被 `ContextOverflowError` 中断。现于迁移后清空 `agent.lastUsage`，护栏首轮无据可查而放行，待下一次响应以真实用量回填。
+- **Interaction adaptations between automatic migration and the CLI (two places)**:
+  - **The input line did not really block during migration** — the `isActive` of the main `useInput` only blocked the "confirmation box / picker / configuration wizard", not the "generating" state. Automatic migration runs inside `send()` via `await onAfterSend` (`busy` is true and the input line has been replaced by the Spinner), yet keystrokes were still swallowed silently into the hidden input buffer and only surfaced once the turn ended. The main input is now fully deactivated while `busy`, with a separate "busy period" handler that only passes `Ctrl+C` to abort / `Ctrl+D` to exit / `PgUp`·`Shift+↑↓` to look back; manual `/migrate` is included in `busy` as well.
+  - **Still blocked by the overall context guard after migration** — migration (prune) physically resets the context but left `agent.lastUsage` behind (the `prompt_tokens` of the request before migration). `ContextGuardPlugin` (`onInnerLoopStart`, hard cap `maxTokens × 1.5`) misjudged from it, and the first message after migration was aborted with `ContextOverflowError`. `agent.lastUsage` is now cleared after migration, so the guard has nothing to go on in the first round and lets it pass, until the next response fills in the real usage.
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/migration-service.test.ts`：断言迁移后 `agent.lastUsage` 被清空（移除修复后该用例确会失败）。全量单测 **17 文件 / 227 用例**通过，`tsc --noEmit` 与 `pnpm build` 零错误。
+- New `src/migration-service.test.ts`: asserts that `agent.lastUsage` is cleared after migration (this case does indeed fail when the fix is removed). Full run of **17 files / 227 cases** passed, `tsc --noEmit` and `pnpm build` with zero errors.
 
 ## [1.0.0-alpha.8] - 2026-10-14
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **修复长时间 TUI 会话内存无界增长导致的 OOM（崩溃）** —— CLI 入口此前从未设定 `NODE_ENV`，React 因而按 `process.env.NODE_ENV !== "production"` 载入 **development** 版 `react-reconciler`；该开发构建每次渲染都会调用 `performance.measure()`（User Timing API），而 Node 的 performance 条目缓冲**无上限、从不逐出**，长时间流式会话下条目持续累积，约 55 分钟即将堆顶到 `heap_size_limit`（本机 ~1GB）触发 OOM。现于 `src/index.ts` 顶部设 `process.env.NODE_ENV ||= "production"`；因 ESM 静态 `import` 会被提升到模块体之前执行，对 TUI 入口 `./tui/index.js` 改用动态 `import()`，确保 React/Ink 在 `NODE_ENV` 设定**之后**才被求值，从而加载 production 版 reconciler（该版不调用 `performance.measure`）。显式 `NODE_ENV=development` 仍保留开发构建，便于排查。
+- **Fixed the OOM (crash) caused by unbounded memory growth in long TUI sessions** — the CLI entry never set `NODE_ENV`, so React loaded the **development** build of `react-reconciler` per `process.env.NODE_ENV !== "production"`; that dev build calls `performance.measure()` (User Timing API) on every render, and Node's performance entry buffer is **unbounded and never evicted**, so entries kept accumulating during long streaming sessions and the heap approached `heap_size_limit` (about 1GB on this machine) after roughly 55 minutes, triggering OOM. `process.env.NODE_ENV ||= "production"` is now set at the top of `src/index.ts`; because ESM static `import`s are hoisted and evaluated before the module body, the TUI entry `./tui/index.js` now uses a dynamic `import()`, ensuring React/Ink is evaluated **after** `NODE_ENV` is set and thus loads the production reconciler (which does not call `performance.measure`). An explicit `NODE_ENV=development` still keeps the dev build for debugging.
 
-### ✅ 测试
+### ✅ Tests
 
-- **端到端实证** —— 真实 ESM 下经入口加载 Ink 并连续重渲染 300 次：修复后 `performance.measure` 条目 **0 → 0**（production reconciler），显式 `NODE_ENV=development` 对照组 **0 → 905**（dev 埋点仍在）。全量单测 **16 文件 / 226 用例**通过，`tsc --noEmit` 与 `pnpm build` 零错误。
+- **End-to-end proof** — loading Ink through the entry point under real ESM and re-rendering 300 times in a row: after the fix, `performance.measure` entries went **0 → 0** (production reconciler), while the control group with an explicit `NODE_ENV=development` went **0 → 905** (dev instrumentation still in place). Full run of **16 files / 226 cases** passed, `tsc --noEmit` and `pnpm build` with zero errors.
 
 ## [1.0.0-alpha.7] - 2026-10-14
 
-### 📄 文档
+### 📄 Docs
 
-- **状态栏 token 用量纳入文档** —— `docs/zh|en/index.md` 的「主要特性」补上「状态栏实时展示 模型 · Agent · 本轮/累计 token 用量 · 生成状态」（此前仅在 README 提及），累计口径为 `sumUsage(agent.messages)`（含所有层级的子 Agent）。
-- 修正 `TODO.md` 中已过时的路径引用（`src/tui/config-wizard.tsx` → 目录 `src/tui/config-wizard/`）。
+- **Status bar token usage added to the docs** — the "main features" section of `docs/zh|en/index.md` gained "the status bar shows in real time the model · Agent · current-turn/cumulative token usage · generation state" (previously mentioned only in the README), with cumulative usage defined as `sumUsage(agent.messages)` (including sub-agents at all levels).
+- Fixed the outdated path reference in `TODO.md` (`src/tui/config-wizard.tsx` → directory `src/tui/config-wizard/`).
 
-### ⚠️ 依赖
+### ⚠️ Dependencies
 
-- `@ai-zen/agents-core` `^4.5.0 → ^4.5.1`、`@ai-zen/agents-sdk` `1.0.0-alpha.8 → 1.0.0-alpha.9`
+- `@ai-zen/agents-core` `^4.5.0 → ^4.5.1`, `@ai-zen/agents-sdk` `1.0.0-alpha.8 → 1.0.0-alpha.9`
 
-> 纯文档修正，无代码变更。
+> Docs-only correction, no code changes.
 
 ## [1.0.0-alpha.6] - 2026-10-14
 
-### ♻️ 重构
+### ♻️ Refactors
 
-- **累计用量改用 SDK 的 `sumUsage`，移除 CLI 自建的内存累加器** —— 依赖 `@ai-zen/agents-sdk` `1.0.0-alpha.8` / `@ai-zen/agents-core` `4.5.0`：除助手消息的 `usage` 外，委派产生的用量现由 core 在委派边界钉到工具消息的 `subAgentUsage` 上。故 `ChatSession.totalUsage` 直接 `sumUsage(agent.messages)` 即可（含所有层级的子 Agent），删掉 `src/usage.ts` 与 `onSubAgentEnd` 内存回灌——子 Agent 开销随消息持久化，续接 / `/load` 亦不丢，且不再有双重计数风险。
+- **Cumulative usage now uses the SDK's `sumUsage`, and the CLI's own in-memory accumulator is removed** — depends on `@ai-zen/agents-sdk` `1.0.0-alpha.8` / `@ai-zen/agents-core` `4.5.0`: besides the `usage` of assistant messages, usage produced by delegation is now pinned by core onto the tool message's `subAgentUsage` at the delegation boundary. So `ChatSession.totalUsage` can simply be `sumUsage(agent.messages)` (covering sub-agents at every level), `src/usage.ts` and the `onSubAgentEnd` in-memory back-feed are deleted — sub-agent cost is persisted along with messages and is not lost on resume / `/load`, and the double-counting risk is gone.
 
-### ⚠️ 依赖
+### ⚠️ Dependencies
 
-- `@ai-zen/agents-sdk` `1.0.0-alpha.7 → 1.0.0-alpha.8`、`@ai-zen/agents-core` `^4.4.0 → ^4.5.0`
+- `@ai-zen/agents-sdk` `1.0.0-alpha.7 → 1.0.0-alpha.8`, `@ai-zen/agents-core` `^4.4.0 → ^4.5.0`
 
-### ✅ 测试
+### ✅ Tests
 
-- 移除 `src/usage.test.ts`（逻辑下沉 core，已由 core 覆盖）；`chat-session.test.ts` 的 `totalUsage` 用例改为覆盖「assistant 的 usage + 工具消息的 subAgentUsage」求和。全量单测 **16 文件 / 226 用例**通过，`tsc --noEmit` 与 `npm run build` 零错误。
+- Removed `src/usage.test.ts` (the logic moved down into core and is already covered there); the `totalUsage` case in `chat-session.test.ts` now covers summing "the assistant's usage + the tool message's subAgentUsage". Full unit suite **16 files / 226 cases** pass, `tsc --noEmit` and `npm run build` report zero errors.
 
 ## [1.0.0-alpha.5] - 2026-10-14
 
-### 🚀 新功能
+### 🚀 New features
 
-- **状态栏展示 token 累计消耗** —— 依托 `@ai-zen/agents-sdk` `1.0.0-alpha.7` / `@ai-zen/agents-core` `4.4.0` 为每条 assistant 消息钉上的 `usage`，新增 `src/usage.ts`（`addUsage` / `sumMessagesUsage` 纯函数）与 `ChatSession.totalUsage`：对本会话全部 assistant 消息的 `usage` 求和即计费口径的累计消耗；子 Agent 的 messages 不在父 Agent 中，故在 `onSubAgentEnd` 单独累加并入、`/new` 时归零。状态栏由「`{tokens} tok`」升级为「`本轮 x · 累计 y tok`」（本轮 = `lastUsage.total_tokens`，累计 = `totalUsage.total_tokens`）。
-- **依赖升级** —— `@ai-zen/agents-sdk` `1.0.0-alpha.6 → 1.0.0-alpha.7`、`@ai-zen/agents-core` `^4.3.2 → ^4.4.0`（后者新增 `AgentNS.Message.usage` 逐条 token 用量）。
+- **Status bar shows cumulative token consumption** — built on the `usage` that `@ai-zen/agents-sdk` `1.0.0-alpha.7` / `@ai-zen/agents-core` `4.4.0` pin onto each assistant message, added `src/usage.ts` (`addUsage` / `sumMessagesUsage` pure functions) and `ChatSession.totalUsage`: summing the `usage` of all assistant messages in the session gives the cumulative consumption on the billing basis; a sub-agent's messages are not in the parent agent, so they are accumulated separately in `onSubAgentEnd` and folded in, and reset to zero on `/new`. The status bar is upgraded from "`{tokens} tok`" to "`this round x · cumulative y tok`" (this round = `lastUsage.total_tokens`, cumulative = `totalUsage.total_tokens`).
+- **Dependency upgrade** — `@ai-zen/agents-sdk` `1.0.0-alpha.6 → 1.0.0-alpha.7`, `@ai-zen/agents-core` `^4.3.2 → ^4.4.0` (the latter adds `AgentNS.Message.usage`, per-message token usage).
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/usage.test.ts`（4 例）；`chat-session.test.ts` 增补 `totalUsage` 求和用例；`screens.test.tsx` 的 `StatusBar` 用例更新。全量单测 **17 文件 / 230 用例**通过，`tsc --noEmit` 与 `npm run build` 零错误。
+- Added `src/usage.test.ts` (4 cases); `chat-session.test.ts` gained a summation case for `totalUsage`; the `StatusBar` cases in `screens.test.tsx` were updated. Full unit suite **17 files / 230 cases** pass, `tsc --noEmit` and `npm run build` report zero errors.
 
 ## [1.0.0-alpha.4] - 2026-10-13
 
-### ♻️ 重构
+### ♻️ Refactors
 
-- **TUI 渲染直接以 `agent.messages` 为唯一数据源** —— 移除 `ChatEvent` / `chatReducer` / `LiveAssistant` / `Block` / `messagesToBlocks` 等自定义中间模型。SDK 在流式期间会**实时更新 `agent.messages`**（`Agent.parseStreamData` 把每个 delta 增量写进当前那条 message），因此跨消息顺序（数组序）与单条 assistant 内部顺序（`思考 → 工具 → 正文`）天然保持，直接渲染即可，杜绝「第二套真相」的失真与维护负担。已完成消息的折行 / 高亮按「消息 + 列宽 + 内容签名」缓存（`cachedMessageToLines`），流式中那条靠内容签名自动失效。
-- **notice / error 改为独立栏位** —— 系统级提示（命令反馈 / 迁移进度 / 报错）不再混入对话转录，也**绝不写进 `agent.messages`**（那会被 `formatHistory()` 原样发给模型、污染上下文）；改在输入框上方的独立一行渲染（`src/tui/screens/notice.ts`）。
+- **TUI rendering uses `agent.messages` directly as the single source of truth** — removed custom intermediate models such as `ChatEvent` / `chatReducer` / `LiveAssistant` / `Block` / `messagesToBlocks`. During streaming the SDK **updates `agent.messages` in real time** (`Agent.parseStreamData` writes each delta incrementally into the current message), so the cross-message order (array order) and the order inside a single assistant message (`thinking → tool → text`) are preserved naturally and rendering directly is enough, which rules out the distortion and maintenance burden of a "second source of truth". Wrapping / highlighting of completed messages is cached by "message + column width + content signature" (`cachedMessageToLines`), and the in-flight message is invalidated automatically through its content signature.
+- **notice / error moved to a dedicated slot** — system-level notices (command feedback / migration progress / errors) no longer mix into the chat transcript, and are **never written into `agent.messages`** (that would be sent to the model verbatim by `formatHistory()` and pollute the context); they now render on a dedicated row above the input line (`src/tui/screens/notice.ts`).
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **流式增量渲染**：Ink 开启 `incrementalRendering` —— 从「每帧 erase 整屏 + 重写整屏」（`createStandard`）切到「只重绘变化的行」（`createIncremental`），每帧输出量由 O(屏幕大小) 降到 O(变化量)，SSH / 弱网下流式更稳。
-- **流式合帧**（`src/tui/screens/frame-buffer.ts`）：内容变更先攒入缓冲，按 60ms（约 16fps，低于 Ink 默认 30fps 输出节流）批量触发重渲染，把上屏频率从「每个 delta 一次」降到固定帧率。
-- **渲染缓存**：长对话下历史消息的折行 / 高亮免于每帧重算，成本不再随对话增长而恶化。
-- **思考与工具调用之间补一个空行**，排版更清晰。
+- **Incremental streaming rendering**: Ink enables `incrementalRendering` — switching from "erase the whole screen and rewrite it every frame" (`createStandard`) to "redraw only the changed lines" (`createIncremental`), bringing per-frame output from O(screen size) down to O(change size), so streaming is steadier over SSH / weak networks.
+- **Streaming frame coalescing** (`src/tui/screens/frame-buffer.ts`): content changes are buffered first and re-rendering is flushed in batches every 60ms (about 16fps, below Ink's default 30fps output throttle), taking the paint rate from "once per delta" down to a fixed frame rate.
+- **Render cache**: in long conversations the wrapping / highlighting of historical messages no longer needs to be recomputed every frame, so the cost no longer degrades as the conversation grows.
+- **A blank line is added between thinking and tool calls**, for a clearer layout.
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `frame-buffer.test.ts`、`notice.test.ts`；`screens.test.tsx` 重写为基于 `messageToLines` / `transcriptLines` / `computeChatLayout(transcript)`。
-- `tsc` 零错误；全量单测 **16 文件 / 225 用例**通过；`npm run build` 通过。
-- 真机（pty）验证：SSH / 弱网下流式稳定，长对话滚动流畅。
+- Added `frame-buffer.test.ts`, `notice.test.ts`; `screens.test.tsx` rewritten on top of `messageToLines` / `transcriptLines` / `computeChatLayout(transcript)`.
+- `tsc` reports zero errors; full unit suite **16 files / 225 cases** pass; `npm run build` passes.
+- Verified on a real terminal (pty): streaming is stable over SSH / weak networks, and scrolling in long conversations is smooth.
 
 ## [1.0.0-alpha.3] - 2026-10-13
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **内置工具改名（统一 `snake_case`：多词收敛、单词简化）** —— 随 `@ai-zen/agents-sdk` `1.0.0-alpha.6` 落地：SDK 将内置工具名统一为 `snake_case`，并把单词工具简化为单词 —— `readFile` → `read`、`writeFile` → `write`、`exec_async` → `spawn`、`findText` → `find_text`、`batchEdit` → `batch_edit`、`inspectFile` → `inspect_file`、`downloadFile` → `download_file`、`generateImage` → `generate_image`、`viewImage` → `view_image`、`indexedSearch` → `indexed_search`；工具类名同步为 `ReadTool` / `WriteTool` / `SpawnTool`。**若你在 Agent 定义、权限白名单（`tools.allow` / `tools.deny`）或自定义提示词里引用了旧工具名，请同步更新为 `snake_case` 新名**（旧名仅保留在 CHANGELOG 历史条目中）。
+- **Built-in tools renamed (unified on `snake_case`: multi-word names collapsed, single-word names simplified)** — landed with `@ai-zen/agents-sdk` `1.0.0-alpha.6`: the SDK unifies built-in tool names on `snake_case` and simplifies single-word tools to one word — `readFile` → `read`, `writeFile` → `write`, `exec_async` → `spawn`, `findText` → `find_text`, `batchEdit` → `batch_edit`, `inspectFile` → `inspect_file`, `downloadFile` → `download_file`, `generateImage` → `generate_image`, `viewImage` → `view_image`, `indexedSearch` → `indexed_search`; tool class names are likewise now `ReadTool` / `WriteTool` / `SpawnTool`. **If your Agent definitions, permission allow lists (`tools.allow` / `tools.deny`) or custom prompts reference the old tool names, update them to the new `snake_case` names** (old names survive only in historical CHANGELOG entries).
 
-### 🚀 新功能
+### 🚀 New features
 
-- **正文 / 思考按 Markdown 源码着色** —— AI 回答本身即 Markdown，现交给 `highlight.js` 的 `markdown` 词法着色：标题（`#`）、粗体、斜体、行内代码、列表、引用、链接各有配色；**围栏代码块保留围栏行**（开 / 闭围栏以低调暗灰渲染）并继续按标注语言做语法高亮。标记符（`#` / `**` / 反引号 等）**原样保留、只染色**（源码着色，非语义渲染）。正文用**空格优先折行**，避免把英文单词从中间切断。
+- **Text / thinking colored by Markdown source** — AI answers are Markdown already, so they are now colored by `highlight.js`'s `markdown` lexer: headings (`#`), bold, italic, inline code, lists, quotes and links each get their own color; **fenced code blocks keep their fence lines** (opening / closing fences rendered in subdued dark gray) and continue to be syntax-highlighted by the annotated language. Markers (`#` / `**` / backticks, etc.) **are kept as-is and only colored** (source coloring, not semantic rendering). Text wraps **preferring spaces**, so English words are not cut in the middle.
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **正文默认文本色改用终端默认前景色** —— 此前正文基础色写死近白 `#e2e8f0`，在**亮色主题终端**里会「白底白字」看不见。现正文（含未指定颜色的默认分段）一律回落**终端默认前景色**，绝对色只留给标题 / 代码等强调项；同步移除语法色板里两处近白 token 色（`variable` / `params`）。
+- **The default text color falls back to the terminal default foreground** — the base text color used to be hardcoded near-white `#e2e8f0`, which was invisible "white on white" in **light-theme terminals**. Text (including default segments with no color assigned) now always falls back to the **terminal default foreground**, with absolute colors kept only for emphasis such as headings / code; the two near-white token colors in the syntax palette (`variable` / `params`) are removed at the same time.
 
-### ⚠️ 依赖升级
+### ⚠️ Dependency upgrades
 
-- **`@ai-zen/agents-core` 升至 `^4.3.2`、`@ai-zen/agents-sdk` 升至 `1.0.0-alpha.6`** ——
-  - core `4.3.1`：**中断的并行工具轮次归一化** —— 一轮回复里并行调用的多个工具若被中断（`Ctrl+C`），未完成的工具结果会在历史里被补齐 / 归一，避免下一轮因 `tool_calls` 数量与实际工具结果数量不匹配而被服务端拒绝（默认 `fill`：保留 assistant 正文并补齐未完成结果）。
-  - core `4.3.2` / sdk `1.0.0-alpha.4…6`：内置工具统一 `snake_case` + 单词简化、`exec_async` → `spawn`、类名对齐（见「破坏性变更」）。
-  - CLI 侧仅同步工具名（文档 / 测试 fixture / 提示语），运行时行为全量委托 SDK，无需其它适配。
+- **`@ai-zen/agents-core` raised to `^4.3.2`, `@ai-zen/agents-sdk` raised to `1.0.0-alpha.6`** —
+  - core `4.3.1`: **normalization of interrupted parallel tool rounds** — when several tools called in parallel within one reply are interrupted (`Ctrl+C`), unfinished tool results are filled in / normalized in the history, so the next round is not rejected by the server because the number of `tool_calls` does not match the number of actual tool results (default `fill`: keep the assistant text and fill in unfinished results).
+  - core `4.3.2` / sdk `1.0.0-alpha.4…6`: built-in tools unified on `snake_case` + single-word simplification, `exec_async` → `spawn`, class names aligned (see "Breaking changes").
+  - On the CLI side only tool names were synced (docs / test fixtures / prompts); runtime behavior is fully delegated to the SDK, with no other adaptation needed.
 
-### ✅ 测试
+### ✅ Tests
 
-- `tsc --noEmit`（`tsconfig.test.json`）零错误；全量单测 **15 文件 / 235 用例**通过
-- 修复 `config-wizard.test.tsx` 两个预存失败：为向导注入终端尺寸（新增可选 `terminalSize` prop），消除 `ink-testing-library` 假 stdout 缺 `rows` 时 `terminal-size` 探测本机行数、把吸底帧撑到 38 行的干扰
-- 渲染核验：标题 / 粗体 / 行内代码 / 列表 / 引用 / 链接与围栏代码块均按预期着色，普通正文无颜色（回落终端默认）
+- `tsc --noEmit` (`tsconfig.test.json`) reports zero errors; full unit suite **15 files / 235 cases** pass
+- Fixed two pre-existing failures in `config-wizard.test.tsx`: terminal size is now injected into the wizard (new optional `terminalSize` prop), removing the interference where `ink-testing-library`'s fake stdout lacked `rows`, so `terminal-size` probed the host machine's row count and stretched the bottom-anchored frame to 38 rows
+- Render verification: headings / bold / inline code / lists / quotes / links and fenced code blocks are colored as expected, and plain text has no color (terminal default)
 
 ## [1.0.0-alpha.2] - 2026-10-03
 
-### ⚠️ 依赖升级
+### ⚠️ Dependency upgrades
 
-- **`@ai-zen/agents-sdk` 升至 `1.0.0-alpha.3`** — 拉取 SDK 对内置工具 `generateImage` 参数描述的修正。原描述写着「配置中的图片模型可通过 `aiz config show` 查看」，等于**指路让模型去执行宿主 CLI 命令**；而**工具描述会随每次请求的 `tools` 字段进入每一层 agent 的上下文**——模型据此 `exec("aiz config show")`，CLI 又把这条命令解析为**纯 stdio 模式**、以 `config show` 为提示词**再拉起一个 agent**，其工具描述里又是同一句指引，遂形成**自指型递归**（每层都真连 API，越套越深）。SDK 现已把该描述改为「若指定的模型不存在，本工具会返回当前可用的模型列表」，与 `call()` 的实际行为一致，且不再引导模型去执行宿主 CLI。该版本**无破坏性变更**，CLI 源码无需适配（类型 / 默认配置全量委托 SDK，版本横幅由实际安装版本读取，工具清单由 SDK 静态注册表自动发现）。
+- **`@ai-zen/agents-sdk` raised to `1.0.0-alpha.3`** — picks up the SDK's fix to the parameter description of the built-in tool `generateImage`. The old description said "the image model in the configuration can be viewed via `aiz config show`", which effectively **pointed the model at running a host CLI command**; and **tool descriptions enter every layer of agent context with the `tools` field of each request** — the model therefore ran `exec("aiz config show")`, the CLI parsed that command as **pure stdio mode** and launched **another agent** with `config show` as the prompt, whose tool description carried the same instruction again, forming a **self-referential recursion** (every layer really hit the API, nesting deeper and deeper). The SDK now rewrites the description to "if the specified model does not exist, this tool returns the list of currently available models", which matches `call()`'s actual behavior and no longer steers the model toward running the host CLI. This version has **no breaking changes**, and the CLI source needs no adaptation (types / default config are fully delegated to the SDK, the version banner reads the actually installed version, and the tool list is auto-discovered from the SDK's static registry).
 
-### 📝 文档
+### 📝 Docs
 
-- `docs/zh|en/getting-started.md`：运行时依赖版本同步为 `@ai-zen/agents-sdk` `1.0.0-alpha.3`
-- `docs/manifest.json`：版本号同步为 `1.0.0-alpha.2`
-- 中英 README 启动横幅示例版本同步为 `v1.0.0-alpha.2`
+- `docs/zh|en/getting-started.md`: runtime dependency version synced to `@ai-zen/agents-sdk` `1.0.0-alpha.3`
+- `docs/manifest.json`: version number synced to `1.0.0-alpha.2`
+- The example startup banner version in the Chinese and English READMEs synced to `v1.0.0-alpha.2`
 
-### ✅ 测试
+### ✅ Tests
 
-- `tsc --noEmit`（`tsconfig.test.json`）与 `npm run build` 零错误
-- 全量单测 13 文件 / 224 用例通过
+- `tsc --noEmit` (`tsconfig.test.json`) and `npm run build` report zero errors
+- Full unit suite: 13 files / 224 cases pass
 
 ## [1.0.0-alpha.1] - 2026-09-30
 
-> 本版本汇总**相对上一发布版本 `0.9.0`** 的全部变化。
+> This release summarizes all changes **relative to the previous release `0.9.0`**.
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **启动命令由 `aiz` / `zen` 改为 `ai`** —— `package.json` 的 `bin` 改为 `{ "ai", "aiz", "zen" }`；`aiz` / `zen` 作为**过渡别名**保留，未来版本移除。
-- **引入双模式运行，两种模式互不混合** —— 带位置参数、或 stdin/stdout 非 TTY（管道 / 重定向 / CI）时启用**纯 stdio 模式**：无任何额外交互，最终 assistant 文本以纯文本写入 `stdout`（零 ANSI / emoji 前缀 / spinner），日志、进度、工具过程与错误摘要一律走 `stderr`，成功退出码 `0`、失败非 `0`、默认不落盘；仅在**无参数且 stdin/stdout 均为 TTY** 时进入 **TUI 模式**。
-- **交互界面整体重写为 Ink（React）全屏 TUI** —— 取代原 inquirer 行式对话；随之**移除主菜单**（`/menu` 与 `src/menus/*`）以及 `inquirer` / `@types/inquirer` / `chalk` 依赖。
+- **The startup command changes from `aiz` / `zen` to `ai`** — `bin` in `package.json` becomes `{ "ai", "aiz", "zen" }`; `aiz` / `zen` are kept as **transitional aliases** and will be removed in a future version.
+- **Dual-mode operation introduced, the two modes never mix** — when positional arguments are present, or stdin/stdout are not a TTY (pipe / redirection / CI), **pure stdio mode** is used: no extra interaction at all, the final assistant text is written to `stdout` as plain text (zero ANSI / emoji prefixes / spinner), while logs, progress, tool activity and error summaries all go to `stderr`, with exit code `0` on success and non-`0` on failure, and nothing written to disk by default; **TUI mode** is entered only when there are **no arguments and both stdin/stdout are TTYs**.
+- **The whole interactive UI was rewritten as an Ink (React) full-screen TUI** — replacing the former inquirer line-based conversation; the **main menu is removed** (`/menu` and `src/menus/*`) along with the `inquirer` / `@types/inquirer` / `chalk` dependencies.
 
-### ✨ 新增
+### ✨ Added
 
-- **TUI 全屏交互界面（Ink + React）**：
-  - 动画渐变 ASCII 启动界面，结束后直接进入对话（有上一轮会话则自动续接）；
-  - 对话区**吸底**（分隔线 / 输入行 / 状态栏固定底部，整帧高度恒为「终端行数 − 1」以避开 Ink 全屏分支）；
-  - 流式输出（思考 / 正文 / 工具调用分行）、历史按行裁剪自底滚动；
-  - **多行输入**（`Enter` 发送、`Ctrl+N` / `Ctrl+J` 换行）与**光标编辑**（`←`/`→`/`Home`/`End`/`Backspace`/`Delete`，`Ctrl`/`Meta` + `←`/`→` 跨词，反显光标 + 硬件光标同步）；
-  - **应用内翻页**（`PgUp`/`PgDn` 翻页、`Shift`/`Alt` + `↑`/`↓` 单行滚动、发送自动回底）；
-  - 输入历史、内联 `/` 命令菜单、状态栏、确认框。
-- **语法高亮**：工具调用参数按 **JSON** 高亮、正文与思考里的**围栏代码块**按语言高亮。高亮**数据**委托 `highlight.js`（经 `lowlight` 产出 hast），CLI 仅把 `hljs-*` scope 映射为 Ink `<Text>` 颜色 —— 与同为 Ink/React 的 Google Gemini CLI 做法一致。
-- **对话内命令**：`/help`、`/load`、`/clear`、`/new`、`/save`、`/config`、`/key`、`/migrate`、`/back`、`/editor`、`/exit`（`registry.ts` 为命令清单唯一来源，`/help` 与输入补全自动同步）。
-- **首启凭据引导 + 配置中心（Ink 原生）**：端点缺 API Key 时先弹凭据设置屏；`/config` 配置中心管理端点、模型、图片模型、默认项（默认模型 / 图片模型 / Agent / 迁移模型）、工具输出上限、**MCP 服务器**（全局 / 项目作用域）与 **Agent 定义**（顶层 Agent + Sub-agent，含四维权限）；编辑「出厂托管」条目自动转 `custom: true`，危险操作二次确认并做引用守卫。
-- **多行文本走系统编辑器**：Agent 提示词、Sub-agent 函数说明 / 参数 schema 等多行字段按 `Enter` 调起 `$EDITOR`（Windows 默认 `notepad`）；参数 schema 以 `.json` 打开并即时校验。
-- **会话持久化改革：会话即文件 + 单指针** —— 每轮结束落盘、`cli/last-session.json` 记录上一轮会话 id、首条消息后才落盘、`/save` 幂等；继续 / 加载时按消息重建历史。
-- **纯 stdio 模式配套**：`ai --help` / `-h`、`ai --version` / `-v`、`ai --save`；SDK 日志与 `console.log` 统一改道 `stderr` 以保证 stdout 纯净。
-- **IME 候选框跟随光标**：用 Ink `useCursor()` 把硬件光标同步到编辑光标，中文输入法候选框正确定位。
+- **Full-screen TUI (Ink + React)**:
+  - animated gradient ASCII splash screen, going straight into the conversation when it ends (auto-resuming the previous session if there is one);
+  - the chat area is **bottom-anchored** (separator / input line / status bar fixed at the bottom, with the whole frame always "terminal rows − 1" tall to stay out of Ink's full-screen branch);
+  - streaming output (thinking / text / tool calls on separate rows), with history trimmed by line and scrolling from the bottom;
+  - **multi-line input** (`Enter` sends, `Ctrl+N` / `Ctrl+J` insert a newline) and **cursor editing** (`←`/`→`/`Home`/`End`/`Backspace`/`Delete`, `Ctrl`/`Meta` + `←`/`→` by word, inverse-video cursor + hardware cursor sync);
+  - **in-app paging** (`PgUp`/`PgDn` page, `Shift`/`Alt` + `↑`/`↓` scroll one line, sending jumps back to the bottom);
+  - input history, inline `/` command menu, status bar, confirmation dialogs.
+- **Syntax highlighting**: tool call arguments highlighted as **JSON**, and **fenced code blocks** in text and thinking highlighted by language. The highlighting **data** is delegated to `highlight.js` (via `lowlight` producing hast), and the CLI only maps `hljs-*` scopes to Ink `<Text>` colors — the same approach as the Ink/React-based Google Gemini CLI.
+- **In-conversation commands**: `/help`, `/load`, `/clear`, `/new`, `/save`, `/config`, `/key`, `/migrate`, `/back`, `/editor`, `/exit` (`registry.ts` is the single source of the command list, and `/help` and input autocomplete stay in sync automatically).
+- **First-run credential onboarding + configuration center (Ink native)**: when the endpoint has no API key, a credential setup screen is shown first; the `/config` configuration center manages endpoints, models, image models, defaults (default model / image model / Agent / migration model), tool output limits, **MCP servers** (global / project scope) and **Agent definitions** (top-level Agents + sub-agents, with four dimensions of permissions); editing a "factory-managed" entry automatically switches it to `custom: true`, and dangerous operations require a second confirmation and are guarded by reference checks.
+- **Multi-line text goes through the system editor**: multi-line fields such as agent prompts and sub-agent function descriptions / parameter schemas open `$EDITOR` on `Enter` (`notepad` by default on Windows); parameter schemas open as `.json` and are validated immediately.
+- **Session persistence overhaul: a session is a file + a single pointer** — written to disk at the end of every round, `cli/last-session.json` records the previous round's session id, nothing is written to disk until the first message, and `/save` is idempotent; resume / load rebuilds the history from messages.
+- **Extras for pure stdio mode**: `ai --help` / `-h`, `ai --version` / `-v`, `ai --save`; SDK logs and `console.log` are uniformly redirected to `stderr` to keep stdout clean.
+- **IME candidate window follows the cursor**: Ink's `useCursor()` syncs the hardware cursor to the editing cursor, so the Chinese IME candidate window is positioned correctly.
 
-### 🔧 变更
+### 🔧 Changes
 
-- **依赖**：新增 `ink` / `react`（运行时）、`ink-testing-library` / `@types/react`（开发）；新增语法高亮 `highlight.js` / `lowlight`（运行时）与 `@types/hast`（开发）；**移除** `inquirer` / `@types/inquirer` / `chalk`。
-- **升级 `@ai-zen/agents-sdk`**：`1.0.0-alpha.0` → `1.0.0-alpha.1` → `1.0.0-alpha.2`（出厂模型目录刷新、模型清单托管、默认 `mcp.json` 增补 `chrome-devtools` 等；CLI 侧代码零改动）。
-- **TUI 输出统一走 Ink**：迁移进度、会话落盘失败等提示不再 `console.log` / `console.warn` 直写终端（会撕裂 Ink 帧），改为经回调渲染为 notice 块；启动 Logo 渐变也改为 Ink 逐字符 `<Text color>`。
-- **配置向导 / 覆盖层统一「吸底」布局**，列表项与键位提示裁成**严格单行**，修复 VS Code 终端里内容被裁切的问题。
-- **终端状态安全与干净退出**：`SIGINT` / `SIGTERM` / 未捕获异常均卸载 Ink、恢复 raw mode 与光标；`Ctrl+C` 语义为「忙时取消本轮、空闲时退出」；退出显式暂停 stdin 并终止进程（`farewell()`）。
-- **移除旧行式链路（死代码）**：`src/conversation-runner.ts`、`src/slash-hint-prompt.ts`、`src/delta-renderer.ts`、inquirer 版 `src/config-wizard.ts`、`src/draft-*.ts` 等；新增 `src/mode.ts` / `src/stdio-runner.ts` / `src/session-pointer.ts` / `src/conversation-persist-plugin.ts` / `src/config-editor.ts` 与 `src/tui/*` 新实现。
-- 文档：中英 README 与 `docs/zh|en/*` 同步（运行模式、`ai` 命令名、配置中心、多行编辑器等），`docs/manifest.json` 同步。
+- **Dependencies**: added `ink` / `react` (runtime), `ink-testing-library` / `@types/react` (dev); added syntax highlighting `highlight.js` / `lowlight` (runtime) and `@types/hast` (dev); **removed** `inquirer` / `@types/inquirer` / `chalk`.
+- **Upgraded `@ai-zen/agents-sdk`**: `1.0.0-alpha.0` → `1.0.0-alpha.1` → `1.0.0-alpha.2` (factory model catalog refresh, model list hosting, `chrome-devtools` and others added to the default `mcp.json`; zero code changes on the CLI side).
+- **TUI output uniformly goes through Ink**: notices such as migration progress and session write failures no longer use `console.log` / `console.warn` to write directly to the terminal (which tears Ink frames) and are rendered as notice blocks via callbacks; the startup logo gradient also uses Ink per-character `<Text color>`.
+- **The config wizard / overlays are unified on a "bottom-anchored" layout**, with list items and key hints trimmed to a **strict single line**, fixing content clipping in the VS Code terminal.
+- **Terminal state safety and clean exit**: `SIGINT` / `SIGTERM` / uncaught exceptions all uninstall Ink and restore raw mode and the cursor; `Ctrl+C` means "cancel the current round when busy, exit when idle"; exiting explicitly pauses stdin and terminates the process (`farewell()`).
+- **Removed the old line-based pipeline (dead code)**: `src/conversation-runner.ts`, `src/slash-hint-prompt.ts`, `src/delta-renderer.ts`, the inquirer-based `src/config-wizard.ts`, `src/draft-*.ts` and so on; added the new implementations `src/mode.ts` / `src/stdio-runner.ts` / `src/session-pointer.ts` / `src/conversation-persist-plugin.ts` / `src/config-editor.ts` and `src/tui/*`.
+- Docs: the Chinese and English READMEs and `docs/zh|en/*` synced (run modes, the `ai` command name, the configuration center, the multi-line editor, etc.), and `docs/manifest.json` synced.
 
-### ✅ 测试
+### ✅ Tests
 
-- 全量单测 **13 文件 / 224 例**，`tsc --noEmit` 与 `npm run build` 零错误；e2e **12 例**真连 DeepSeek API（覆盖双模式、stdio 纯净性、退出码、`--save` 落盘）。
-- 新增测试文件：`mode.test.ts`、`stdio-runner.test.ts`、`theme.test.ts`、`screens.test.tsx`、`tui/config-wizard.test.tsx`、`tui/agent-prompt.test.tsx`、`tui/highlight.test.ts`、`sub-agent-guard-plugin.test.ts`、`auto-migrate-confirm-plugin.test.ts`、`conversation-commands/registry.test.ts`。
-- 真实 PTY 实测：启动 → 对话 → 流式 → `/load` → `/clear` → 退出交还 shell；首启凭据链路；配置中心各子屏。
+- Full unit suite **13 files / 224 cases**, `tsc --noEmit` and `npm run build` report zero errors; e2e **12 cases** really hitting the DeepSeek API (covering both modes, stdio purity, exit codes, `--save` persistence).
+- New test files: `mode.test.ts`, `stdio-runner.test.ts`, `theme.test.ts`, `screens.test.tsx`, `tui/config-wizard.test.tsx`, `tui/agent-prompt.test.tsx`, `tui/highlight.test.ts`, `sub-agent-guard-plugin.test.ts`, `auto-migrate-confirm-plugin.test.ts`, `conversation-commands/registry.test.ts`.
+- Verified on a real PTY: startup → conversation → streaming → `/load` → `/clear` → exit and hand the shell back; the first-run credential flow; each sub-screen of the configuration center.
 
 ## [0.9.0] - 2026-09-30
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **升级 `@ai-zen/agents-sdk` 到 `1.0.0-alpha.0`（Provider → Scope 架构重构）** — SDK 1.0.0-alpha.0 将全局入口对象 `Provider` 改名为 `Scope`，把四类能力来源疏散为 5 个可组合的 `ScopePlugin`，并移除 `Provider.create()`（改为显式装配）。CLI 侧同步适配 `src/agent-creator.ts`：
-  - 导入 `Scope` / `allInOne` 取代 `Provider`
+- **Upgraded `@ai-zen/agents-sdk` to `1.0.0-alpha.0` (Provider → Scope architecture refactor)** — SDK 1.0.0-alpha.0 renames the global entry object `Provider` to `Scope`, spreads the four capability sources into 5 composable `ScopePlugin`s, and removes `Provider.create()` (replaced by explicit assembly). The CLI side adapted `src/agent-creator.ts` accordingly:
+  - import `Scope` / `allInOne` instead of `Provider`
   - `Provider.create({ config, agentsDir, subAgentsPaths, skillsPaths, toolsPaths, mcpPaths })` → `new Scope({ config, agentsDir }).use(...allInOne({ subAgentsPaths, skillsPaths, toolsPaths, mcpPaths }))` + `await scope.init()`
-  - 单例/工厂改名：`getProvider` → `getScope`、`resetProvider` → `resetScope`；`createAgent` 内部改调 `sdkCreateAgent(scope, agentId)`
-  - 依赖声明由 `^0.12.0` 改为精确 `1.0.0-alpha.0`（alpha 阶段锁定）
+  - singleton / factory renames: `getProvider` → `getScope`, `resetProvider` → `resetScope`; `createAgent` now calls `sdkCreateAgent(scope, agentId)` internally
+  - the dependency declaration changed from `^0.12.0` to the exact `1.0.0-alpha.0` (pinned during the alpha phase)
 
-### 📝 文档
+### 📝 Docs
 
-- 中英 README 与 `docs/zh|en/{tools,mcp,skills}.md`：`Provider` / `getProvider()` 同步为 `Scope` / `getScope()`
-- `docs/zh|en/getting-started.md`：运行时依赖版本同步为 `@ai-zen/agents-sdk` `1.0.0-alpha.0`
-- `docs/manifest.json`：版本号同步为 `0.9.0`
+- Chinese and English READMEs and `docs/zh|en/{tools,mcp,skills}.md`: `Provider` / `getProvider()` synced to `Scope` / `getScope()`
+- `docs/zh|en/getting-started.md`: runtime dependency version synced to `@ai-zen/agents-sdk` `1.0.0-alpha.0`
+- `docs/manifest.json`: version number synced to `0.9.0`
 
-### ✅ 测试
+### ✅ Tests
 
-- `tsc --noEmit`（`tsconfig.test.json`）与 `npm run build` 零错误
-- 全量单测 9 文件 / 74 用例通过
-- e2e 6 用例通过（含真实 DeepSeek API 对话，验证 CLI → SDK `1.0.0-alpha.0` → API 全链路）
+- `tsc --noEmit` (`tsconfig.test.json`) and `npm run build` report zero errors
+- Full unit suite: 9 files / 74 cases pass
+- 6 e2e cases pass (including a real DeepSeek API conversation, verifying the whole CLI → SDK `1.0.0-alpha.0` → API chain)
 
 ## [0.8.2] - 2026-09-29
 
-### ⚠️ 依赖升级
+### ⚠️ Dependency upgrades
 
-- **`@ai-zen/agents-sdk` 升至 `^0.12.0`** — SDK 0.12.0 新增内置工具 `inspectFile`（内置工具类 19 → 20）、`readFile` 的 `range` 分批读取参数，新增配置项 `maxToolOutput`（缺省 32768 字符）与工具输出保护行为，并精简了 `batchEdit` 的输出。该版本**无破坏性变更**，CLI 源码无需适配：类型与默认配置全量委托 SDK，`src/version.ts` 由实际安装版本读取，工具清单由 SDK 静态注册表自动发现，故版本横幅随之显示 sdk `0.12.0`
+- **`@ai-zen/agents-sdk` raised to `^0.12.0`** — SDK 0.12.0 adds the built-in tool `inspectFile` (built-in tool classes 19 → 20) and the `range` batched-read parameter of `readFile`, adds the config option `maxToolOutput` (32768 characters by default) with tool output protection behavior, and trims the output of `batchEdit`. This version has **no breaking changes**, and the CLI source needs no adaptation: types and default config are fully delegated to the SDK, `src/version.ts` reads the actually installed version, and the tool list is auto-discovered from the SDK's static registry, so the version banner now shows sdk `0.12.0`
 
-### 📝 文档
+### 📝 Docs
 
-- 同步内置工具计数 19 → 20：中英 README、`docs/zh|en/tools.md`、`docs/zh|en/index.md` 与 `docs/manifest.json`
-- 工具表补充 `inspectFile`（勘察文件结构概况），并为 `readFile` 补注 `range` 参数
-- `docs/zh|en/tools.md` 新增「输出保护」说明：超限时 `exec` / `findText` / `glob` / `ls` 落盘并返回警告，`readFile` / `inspectFile` 仅警告不落盘
-- `docs/zh|en/getting-started.md` 的运行时依赖版本同步为 `@ai-zen/agents-sdk` `^0.12.0`
+- Synced the built-in tool count 19 → 20: the Chinese and English READMEs, `docs/zh|en/tools.md`, `docs/zh|en/index.md` and `docs/manifest.json`
+- Added `inspectFile` (surveying a file's structural overview) to the tool table, and documented the `range` parameter for `readFile`
+- `docs/zh|en/tools.md` gained an "output protection" section: when a limit is exceeded, `exec` / `findText` / `glob` / `ls` write to disk and return a warning, while `readFile` / `inspectFile` only warn without writing to disk
+- The runtime dependency version in `docs/zh|en/getting-started.md` synced to `@ai-zen/agents-sdk` `^0.12.0`
 
-### ✅ 测试
+### ✅ Tests
 
-- 沿用既有 9 文件 / 74 用例，全部通过；`tsc --noEmit` 与 `npm run build`（`0.8.2`）均通过
+- Reuses the existing 9 files / 74 cases, all passing; `tsc --noEmit` and `npm run build` (`0.8.2`) both pass
 
 ## [0.8.1] - 2026-09-28
 
-### 🚀 新功能
+### 🚀 New features
 
-- **Skill 子 Agent 纳入子 Agent 上下文护栏与流式渲染** — 依托 SDK 0.11.0 将 `call_skill_sub_agent` 统一到 `AgentToolLazy`，技能子 Agent 自此与常规 SubAgent 共享同一套委派边界（`onSubAgentStart` / `onSubAgentEnd` 钩子与 `sub-agent-start` / `sub-agent-end` 事件）。故 0.8.0 引入的 `SubAgentGuardInstallerPlugin` 与子 Agent 流式渲染**自动覆盖**该路径，本次 CLI 无源码改动（0.8.0 CHANGELOG「覆盖范围」中「技能子 Agent 不在覆盖范围」的说明随之失效）
+- **Skill sub-agents are brought under the sub-agent context guard and streaming rendering** — relying on SDK 0.11.0 unifying `call_skill_sub_agent` under `AgentToolLazy`, skill sub-agents now share the same delegation boundary with regular SubAgents (`onSubAgentStart` / `onSubAgentEnd` hooks and `sub-agent-start` / `sub-agent-end` events). So the `SubAgentGuardInstallerPlugin` and the sub-agent streaming rendering introduced in 0.8.0 **automatically cover** that path, and this time the CLI has no source changes (the note in the 0.8.0 CHANGELOG's "coverage" saying "skill sub-agents are not covered" no longer applies)
 
-### ⚠️ 依赖升级
+### ⚠️ Dependency upgrades
 
-- **`@ai-zen/agents-core` 升至 `^4.3.0`、`@ai-zen/agents-sdk` 升至 `^0.11.0`** — `src/version.ts` 由实际安装版本读取，版本横幅随之显示 core `4.3.0` / sdk `0.11.0`。SDK 0.11.0 的破坏性变更（`createCallSkillSubAgentTool` 移除第三参 `provider`）仅影响直接调用该工厂函数的代码；CLI 经 `Provider.instantiate` 间接使用，无需适配
+- **`@ai-zen/agents-core` raised to `^4.3.0`, `@ai-zen/agents-sdk` raised to `^0.11.0`** — `src/version.ts` reads the actually installed version, so the version banner now shows core `4.3.0` / sdk `0.11.0`. SDK 0.11.0's breaking change (removal of `createCallSkillSubAgentTool`'s third parameter `provider`) only affects code that calls that factory function directly; the CLI uses it indirectly through `Provider.instantiate` and needs no adaptation
 
-### ✅ 测试
+### ✅ Tests
 
-- 沿用既有 9 文件 / 74 用例，全部通过；`tsc --noEmit` 与 `npm run build`（`0.8.1`）均通过
+- Reuses the existing 9 files / 74 cases, all passing; `tsc --noEmit` and `npm run build` (`0.8.1`) both pass
 
 ## [0.8.0] - 2026-09-28
 
-### 🚀 新功能
+### 🚀 New features
 
-- **子 Agent 上下文护栏（`SubAgentGuardInstallerPlugin`）** — 补上「主 Agent 有护栏、子 Agent 无护栏」的缺口（新增 `src/sub-agent-guard-plugin.ts`）：
-  - **背景**：SDK 的子 Agent 由 `AgentTool` / `AgentToolLazy` 在委派时 `new Agent({...})` 构建，新建实例不携带任何插件（`Agent._plugins` 每实例私有，不向子 Agent 传播），且子 Agent 走 `run()` 而非 `send()`（`onBeforeSend` / `onAfterSend` 不会触发）——因此主 Agent 上的 `ContextGuardPlugin` 与自动迁移插件对子 Agent 完全无效，子 Agent 的内循环没有约束
-  - **介入点**：core 4.2.0 的 `onSubAgentStart` 钩子在「子 Agent 已构建、尚未 `run()`」时由宿主 Agent 分发，载荷携带子 Agent 实例；`use()` 只是把插件推入 `_plugins`，而钩子分发每次都实时遍历该列表，故在钩子内安插对**本次 `run()` 立即生效**（无需 `init()`，`AgentTool` 也不调用子 Agent 的 `init()`）
-  - **约束口径**：把主 Agent 同款的 `ContextGuardPlugin` 装到子 Agent 上——同一 `maxTokens`（当前模型 `maxContextTokens`）、同样不传 ratio（沿用 SDK 默认 1.5），使「上下文 token 超过 `maxTokens` × 1.5 即中断」对子 Agent 同样成立；**不设轮次上限、不设工具调用次数上限**（仅此一项限制）
-  - **中断语义为「软中断」**：子 Agent 的 run 立即结束，异常经 `AgentTool` 的 `finally`（分发 `onSubAgentEnd`）上抛至父 Agent，而父 Agent 默认 `allowJsonParseError = true`，故被降级为一条工具结果文本（`执行工具 X 时出错: …`），父 Agent 继续下一轮——停掉烧钱的子 Agent，但不终止用户对话
-  - **递归覆盖**：安装器在委派时把自身一并装给子 Agent，故子 Agent 再委派（孙级）同样受约束（默认 SubAgent 定义为 `subagents: deny`，该路径默认不触发，仅在放开递归时生效）
-  - **覆盖范围**：仅 core 的 `AgentTool` / `AgentToolLazy` 两条委派路径（均分发 `onSubAgentStart`）；SDK 的 `call_skill_sub_agent`（技能子 Agent）不分发该钩子，本次不覆盖
+- **Sub-agent context guard (`SubAgentGuardInstallerPlugin`)** — closes the gap where "the main Agent has a guard while sub-agents have none" (added `src/sub-agent-guard-plugin.ts`):
+  - **Background**: SDK sub-agents are built by `AgentTool` / `AgentToolLazy` via `new Agent({...})` at delegation time; a newly built instance carries no plugins (`Agent._plugins` is per-instance and does not propagate to sub-agents), and sub-agents go through `run()` rather than `send()` (`onBeforeSend` / `onAfterSend` never fire) — therefore the `ContextGuardPlugin` and the auto-migration plugin on the main Agent have no effect at all on sub-agents, and a sub-agent's inner loop is unconstrained
+  - **Intervention point**: core 4.2.0's `onSubAgentStart` hook is dispatched by the host Agent at the moment "the sub-agent has been built and `run()` has not been called yet", with a payload carrying the sub-agent instance; `use()` merely pushes a plugin into `_plugins`, and the hook dispatch iterates that list live every time, so installing into the sub-agent inside the hook takes effect **for the current `run()` immediately** (no `init()` needed, and `AgentTool` does not call a sub-agent's `init()` either)
+  - **Constraint policy**: install the same `ContextGuardPlugin` the main Agent uses onto the sub-agent — the same `maxTokens` (the current model's `maxContextTokens`), likewise without a ratio (keeping the SDK default 1.5), so that "context tokens exceeding `maxTokens` × 1.5 aborts" holds for sub-agents as well; **no round limit and no tool-call-count limit are set** (this is the only constraint)
+  - **Interruption semantics are a "soft abort"**: the sub-agent's run ends immediately, the exception is thrown up to the parent Agent through `AgentTool`'s `finally` (which dispatches `onSubAgentEnd`), and since the parent Agent has `allowJsonParseError = true` by default, it is downgraded to a single tool result text (`error while executing tool X: …`) and the parent Agent proceeds to the next round — the money-burning sub-agent is stopped without terminating the user's conversation
+  - **Recursive coverage**: the installer installs itself into the sub-agent at delegation time, so further delegation by the sub-agent (grandchild level) is constrained as well (the default SubAgent definition is `subagents: deny`, so that path does not trigger by default and only takes effect when recursion is opened up)
+  - **Coverage**: only core's two delegation paths `AgentTool` / `AgentToolLazy` (both dispatch `onSubAgentStart`); the SDK's `call_skill_sub_agent` (skill sub-agents) does not dispatch that hook and is not covered here
 
-### ⚠️ 依赖升级
+### ⚠️ Dependency upgrades
 
-- **`@ai-zen/agents-core` 升至 `^4.2.0`、`@ai-zen/agents-sdk` 升至 `^0.10.0`** — `src/version.ts` 由实际安装版本读取，版本横幅随之显示 core `4.2.0` / sdk `0.10.0`；SDK 0.10.0 新增的 `load_mcp` `include_manifest` 开关为向后兼容的可选参数（默认 `true`，行为与升级前逐字一致），CLI 无需适配
+- **`@ai-zen/agents-core` raised to `^4.2.0`, `@ai-zen/agents-sdk` raised to `^0.10.0`** — `src/version.ts` reads the actually installed version, so the version banner now shows core `4.2.0` / sdk `0.10.0`; the `include_manifest` switch of `load_mcp` added in SDK 0.10.0 is a backward-compatible optional parameter (default `true`, behavior byte-for-byte identical to before the upgrade), so the CLI needs no adaptation
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **子 Agent 事件对齐 core 4.2.0 的改名与载荷结构** — core 4.2.0 将事件 `sub-agent` 更名为 `sub-agent-start`，载荷由 `{ agent: 子 Agent, ctx }` 改为 `SubAgentContext = { agent: 主 Agent, subAgent: 子 Agent, toolCallContext }`。`src/conversation-runner.ts` 同步适配：事件监听与注销改用 `sub-agent-start`（此前监听旧名将不再触发，子 Agent 流式渲染会静默失效）；子 Agent 实例改取自 `subAgent` 字段，工具名改取自 `toolCallContext.tool_call.function.name`（此前读取已不存在的 `ctx` 字段会在 `sub-agent-end` 回调中抛错）
+- **Sub-agent events aligned with core 4.2.0's renames and payload structure** — core 4.2.0 renames the event `sub-agent` to `sub-agent-start` and changes the payload from `{ agent: sub-agent, ctx }` to `SubAgentContext = { agent: main agent, subAgent: sub-agent, toolCallContext }`. `src/conversation-runner.ts` adapted accordingly: event listening and unsubscription now use `sub-agent-start` (listening to the old name no longer fires, which would silently disable sub-agent streaming rendering); the sub-agent instance is now read from the `subAgent` field, and the tool name from `toolCallContext.tool_call.function.name` (previously reading the now-nonexistent `ctx` field threw inside the `sub-agent-end` callback)
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/sub-agent-guard-plugin.test.ts`（6 个用例）：安装器的装载清单与「不拒绝委派」、安插后对本次 `run()` 立即生效（无需 `init()`）、用量恰好等于硬上限时放行、首轮无 usage 数据时放行、阈值随传入 `maxTokens` 变化、孙级传染
-- `tsc --noEmit` 类型检查、全量单测与 `npm run build` 通过（74 passed / 9 files）
+- Added `src/sub-agent-guard-plugin.test.ts` (6 cases): the installer's plugin list and "does not reject delegation", immediate effect on the current `run()` after installation (no `init()` needed), pass-through when usage exactly equals the hard limit, pass-through on the first round with no usage data, the threshold following the passed `maxTokens`, and grandchild-level propagation
+- `tsc --noEmit` type checking, the full unit suite and `npm run build` pass (74 passed / 9 files)
 
 ## [0.7.0] - 2026-09-20
 
-### 🚀 新功能
+### 🚀 New features
 
-- **自动迁移二次确认** — 上下文 token 超限触发的自动迁移不再静默执行，迁移前先向用户确认（新增 `src/auto-migrate-confirm-plugin.ts`）：
-  - `AutoMigrateConfirmPlugin` 继承 SDK 的 `AutoMigratePlugin`，**仅在「超阈值」与「调用迁移」之间插入一次确认**：阈值判断、迁移调用与错误处理仍复用基类，实际迁移仍委托共享的 `migrationService`（与 `/migrate` 同一条链路）——即 SDK 侧「只负责触发」的语义不变，确认是 CLI 层的增量
-  - 确认框展示当前用量与阈值（如 `260000/250000 tokens`）并说明影响（生成交接文档 → 保存当前对话 → 开启新会话继续），**默认「是」**（回车即迁移，与 `/migrate` 默认值一致）
-  - 选择「否」仅跳过**本次**迁移，不记录隐式状态：当前对话不受影响（历史未被剔除），可继续提问或随时 `/migrate`；仍处超限状态时下次发送后再次询问，并提示继续增长至严重超限会被 `ContextGuardPlugin` 中断
-  - **非交互环境不询问**：仅在 stdin 与 stdout 均为 TTY 时弹出确认框；管道、重定向、e2e 脚本无确认通道，保持既有静默自动迁移行为（不阻塞等待输入、不额外输出，管道语义不变）
-  - 对话装配处（`src/conversation-runner.ts`）改注册 `AutoMigrateConfirmPlugin`，其余插件（`ContextGuardPlugin` 护栏位置）不变
-- **对话内命令提示** — 对话输入行键入 `/` 即实时列出可用命令及说明，继续输入按前缀收敛候选，无匹配时提示「无匹配命令（输入 /help 查看全部）」：
-  - 新增 `src/slash-hint-prompt.ts`：继承 inquirer 的 input 提示并覆写 `render`，将候选命令作为底栏（`bottomContent`）交由 inquirer 的 `ScreenManager` 渲染，复用其折行、终端缩放、擦除与光标归位处理，渲染表现与其它提示一致
-  - **仅提示，不改变提交语义**：回车始终提交输入原文，命令仍由 `dispatchCommand` 按完整名称精确匹配分发（不做前缀补全、不做高亮选择）
-  - 非 TTY 环境（stdin/stdout 重定向、e2e 脚本）自动不渲染提示，退化为普通输入行，既有输出行为不变
-  - 普通聊天内容（非 `/` 开头）不产生任何提示
-- 对话主循环输入改由 `src/slash-hint-prompt.ts` 的 `askInput()` 提供（`src/conversation-runner.ts` 不再直接构造输入提示）
+- **Second confirmation for auto-migration** — auto-migration triggered by exceeding the context token limit no longer runs silently; the user is asked to confirm before migrating (added `src/auto-migrate-confirm-plugin.ts`):
+  - `AutoMigrateConfirmPlugin` extends the SDK's `AutoMigratePlugin` and **only inserts one confirmation between "threshold exceeded" and "migration invoked"**: threshold checking, migration invocation and error handling still reuse the base class, and the actual migration is still delegated to the shared `migrationService` (the same chain as `/migrate`) — i.e. the SDK-side semantics of "only responsible for triggering" are unchanged, and the confirmation is an increment on the CLI layer
+  - The confirmation dialog shows the current usage and the threshold (e.g. `260000/250000 tokens`) and explains the impact (generate a handoff document → save the current conversation → start a new session and continue), and **defaults to "yes"** (Enter migrates, consistent with `/migrate`'s default)
+  - Choosing "no" only skips **this** migration and records no implicit state: the current conversation is unaffected (the history is not trimmed), and the user can keep asking or run `/migrate` at any time; when still over the limit, the prompt appears again after the next send, noting that continued growth into severe overflow will be aborted by `ContextGuardPlugin`
+  - **No prompt in non-interactive environments**: the confirmation dialog is only shown when both stdin and stdout are TTYs; pipes, redirection and e2e scripts have no confirmation channel, so the existing silent auto-migration behavior is kept (no blocking on input, no extra output, pipe semantics unchanged)
+  - The conversation wiring (`src/conversation-runner.ts`) now registers `AutoMigrateConfirmPlugin`, while the other plugins (including the `ContextGuardPlugin` guard position) are unchanged
+- **In-conversation command hints** — typing `/` on the chat input line immediately lists the available commands and their descriptions; further input narrows the candidates by prefix, and when nothing matches it shows "no matching command (type /help to see all)":
+  - Added `src/slash-hint-prompt.ts`: it extends inquirer's input prompt and overrides `render`, handing the candidate commands to inquirer's `ScreenManager` as the bottom bar (`bottomContent`), so its wrapping, terminal resize, erasing and cursor restoration handling is reused and rendering matches the other prompts
+  - **Hints only, submission semantics unchanged**: Enter always submits the input verbatim, and commands are still dispatched by `dispatchCommand` using exact matching on the full name (no prefix completion, no highlighted selection)
+  - In non-TTY environments (stdin/stdout redirected, e2e scripts) the hint is simply not rendered and it degrades to a plain input line, with the existing output behavior unchanged
+  - Ordinary chat content (not starting with `/`) produces no hint at all
+- The main conversation loop now gets its input from `askInput()` in `src/slash-hint-prompt.ts` (`src/conversation-runner.ts` no longer constructs the input prompt directly)
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **对话命令清单收敛为唯一来源** — 新增 `src/conversation-commands/registry.ts` 集中声明命令名、别名与说明，由分发（`index.ts`）、帮助（`help.ts`）与输入提示三处共用：
-  - **别名不再重复登记**：registry 声明的别名由 `index.ts` 自动展开为处理函数表的键；registry 声明了命令却未注册处理函数时于启动阶段即报错（fail-fast）
-  - `/help` 输出改由 registry 渲染，命令列按最长命令串对齐，与输入提示列宽一致（命令与说明文案保持不变）
-  - `getCommandNames()` 迁至 registry，`conversation-commands/index.ts` 原样再导出，调用方无需改动
+- **The conversation command list is collapsed into a single source** — added `src/conversation-commands/registry.ts`, which declares command names, aliases and descriptions in one place, shared by dispatch (`index.ts`), help (`help.ts`) and input hints:
+  - **Aliases are no longer registered twice**: aliases declared by the registry are automatically expanded by `index.ts` into keys of the handler table; if the registry declares a command with no registered handler, an error is raised at startup (fail-fast)
+  - `/help` output is now rendered by the registry, with the command column aligned to the longest command string and consistent with the input hint's column width (the command and description texts are unchanged)
+  - `getCommandNames()` moved to the registry, and `conversation-commands/index.ts` re-exports it as before, so callers need no changes
 
-### ⚠️ 依赖约束
+### ⚠️ Dependency constraints
 
-- **引用了 inquirer 内部模块** `inquirer/lib/prompts/input.js` — inquirer 9 未导出 BasePrompt/InputPrompt，实现命令提示底栏只能深层导入（inquirer@9 的 `package.json` 无 `exports` 字段，ESM 深层导入已在 Node 26 + inquirer 9.3.8 下实测可用）。类型声明见 `src/typings/inquirer-internals.d.ts`；**升级 inquirer 主版本时须回归验证该模块路径与 `render` 行为**
-- **未新增运行时依赖**，`pnpm-lock.yaml` 不变
+- **References the inquirer internal module** `inquirer/lib/prompts/input.js` — inquirer 9 does not export BasePrompt/InputPrompt, so implementing the command-hint bottom bar requires a deep import (inquirer@9's `package.json` has no `exports` field, and ESM deep imports were verified working on Node 26 + inquirer 9.3.8). Type declarations live in `src/typings/inquirer-internals.d.ts`; **when upgrading inquirer's major version, that module path and the `render` behavior must be re-verified**
+- **No new runtime dependency**, `pnpm-lock.yaml` unchanged
 
-### ✅ 测试
+### ✅ Tests
 
-- 新增 `src/auto-migrate-confirm-plugin.test.ts`（阈值判断、确认与拒绝分支、非交互降级、TTY 判定与默认确认文案）
-- 新增 `src/slash-hint-prompt.test.ts`（提示文本生成 + 底栏渲染，覆盖 TTY / 非 TTY / 已提交 / 错误行分支）
-- 新增 `src/conversation-commands/registry.test.ts`（元数据、别名折叠、前缀匹配、命令分发与别名等价）
-- `tsc` 类型检查与全量单测通过（68 passed / 8 files），`npm run build` 成功
-- 构建产物在真实 TTY 下实测：输入 `/` 列出全部命令、`/b` 收敛为 `/back`、回车提交原文且提示行正确擦除；`/help` 输出格式与列宽正常
+- Added `src/auto-migrate-confirm-plugin.test.ts` (threshold checks, the confirm and decline branches, non-interactive degradation, TTY detection and the default confirmation text)
+- Added `src/slash-hint-prompt.test.ts` (hint text generation + bottom bar rendering, covering the TTY / non-TTY / submitted / error-line branches)
+- Added `src/conversation-commands/registry.test.ts` (metadata, alias folding, prefix matching, command dispatch and alias equivalence)
+- `tsc` type checking and the full unit suite pass (68 passed / 8 files), and `npm run build` succeeds
+- The build output was verified on a real TTY: typing `/` lists all commands, `/b` narrows to `/back`, Enter submits the raw text and the hint line is erased correctly; `/help` output format and column widths are normal
 
 ## [0.6.3] - 2026-09-01
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **修复迁移后旧消息既未标记 omit 也未物理删除的问题（依赖升级）** — 上游 `@ai-zen/agents-sdk` 0.9.3 修复 `createAgent` 直接引用 `definition.messages` 导致对话 `append` 反向污染 Agent 定义模板的缺陷；此前该缺陷使任务迁移 `prune`/`omit` 策略失效（旧消息不被清理、却能注入断点消息）
-- **恢复草稿/已保存对话时拷贝消息数组** — `src/agent-creator.ts` 由直接引用改为 `agent.messages = [...messages]`，避免后续 `append` 改写草稿/对话存档的内存数组
-- **依赖跟随升级** — `@ai-zen/agents-sdk` 至 `0.9.3`（借助 caret 范围自动解析）
+- **Fixed old messages being neither marked omit nor physically deleted after migration (dependency upgrade)** — upstream `@ai-zen/agents-sdk` 0.9.3 fixes the defect where `createAgent` referenced `definition.messages` directly, causing conversation `append` to pollute the Agent definition template in reverse; that defect had made task migration's `prune`/`omit` strategies ineffective (old messages were not cleaned up, yet breakpoint messages could be injected)
+- **Copy the message array when restoring a draft / saved conversation** — `src/agent-creator.ts` changed from a direct reference to `agent.messages = [...messages]`, so later `append` calls do not rewrite the in-memory array of a draft / conversation archive
+- **Dependencies upgraded along** — `@ai-zen/agents-sdk` to `0.9.3` (resolved automatically through the caret range)
 
-### ✅ 测试
+### ✅ Tests
 
-- `tsc` 类型检查与全量单测通过（37 passed / 5 files）
+- `tsc` type checking and the full unit suite pass (37 passed / 5 files)
 
 ## [0.6.2] - 2026-08-31
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **启动版本 banner 增强** — 新增 `src/version.ts`，统一从实际安装包读取版本号（而非依赖声明中的版本范围）；主菜单版本行由仅打印 CLI 版本扩展为同时展示 CLI / SDK / Core 三版本，例如 `AI-Zen CLI v0.6.2 · SDK 0.9.2 · Core 4.1.0`
-- **适配 `@ai-zen/agents-core` 4.1.0 类型变更** — 上游将 `AgentNS.Message.id` 由可选改为**强制必填**（构造时自动生成）。`src/menus/agents.ts` 与 `src/conversation-commands/back.test.ts` 中直接构造的裸消息对象改用 `Message` 内置工厂方法创建（`Message.System` / `Message.User` / `Message.Assistant`，以及 `new Message(...)`），由 core 统一生成消息 `id`
-- **依赖跟随升级** — `@ai-zen/agents-sdk` 至 `0.9.2`、`@ai-zen/agents-core` 至 `4.1.0`（借助 caret 范围自动解析）
+- **Startup version banner enhanced** — added `src/version.ts`, which uniformly reads version numbers from the actually installed packages (rather than the version ranges in the dependency declarations); the main menu version row is expanded from printing only the CLI version to showing the CLI / SDK / Core versions together, e.g. `AI-Zen CLI v0.6.2 · SDK 0.9.2 · Core 4.1.0`
+- **Adapted to `@ai-zen/agents-core` 4.1.0 type changes** — upstream changed `AgentNS.Message.id` from optional to **mandatory** (auto-generated on construction). Bare message objects constructed directly in `src/menus/agents.ts` and `src/conversation-commands/back.test.ts` now use `Message`'s built-in factory methods (`Message.System` / `Message.User` / `Message.Assistant`, and `new Message(...)`), letting core generate the message `id` uniformly
+- **Dependencies upgraded along** — `@ai-zen/agents-sdk` to `0.9.2`, `@ai-zen/agents-core` to `4.1.0` (resolved automatically through the caret ranges)
 
-### ✅ 测试
+### ✅ Tests
 
-- 依赖升级后 `tsc` 类型检查与全量单测通过（37 passed / 5 files），`npm run build` 成功
+- After the dependency upgrade, `tsc` type checking and the full unit suite pass (37 passed / 5 files), and `npm run build` succeeds
 
 ## [0.6.1] - 2026-08-28
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **升级 `@ai-zen/agents-sdk` 到 0.9.0** — 迁移服务新增 `strategy` 开关：
-  - **`omit`（默认）**：历史消息标记 `omit: true` 保留可审计，追加「对话断点」消息为新上下文起点
-  - **`prune`（CLI 采用）**：物理剔除历史，仅保留系统提示 + 交接断点（即先前替换行为）
-  - CLI `migration-service.ts` 显式启用 `strategy: "prune"`，与端侧「迁移后开启新会话」的产品语义一致，**对外使用无差异**
+- **Upgraded `@ai-zen/agents-sdk` to 0.9.0** — the migration service gains a `strategy` switch:
+  - **`omit` (default)**: historical messages are marked `omit: true` and kept for auditability, and a "conversation breakpoint" message is appended as the starting point of the new context
+  - **`prune` (used by the CLI)**: history is physically removed, keeping only the system prompt + handoff breakpoint (i.e. the previous replacement behavior)
+  - CLI `migration-service.ts` explicitly enables `strategy: "prune"`, consistent with the client-side product semantics of "start a new session after migration", with **no difference in external usage**
 
-### ✅ 测试
+### ✅ Tests
 
-- 依赖升级后单测全量通过（37 passed），`tsc --noEmit` 零错误
+- After the dependency upgrade the full unit suite passes (37 passed), and `tsc --noEmit` reports zero errors
 
 ## [0.6.0] - 2026-08-24
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **升级 `@ai-zen/agents-sdk` 到 0.8.0** — 任务迁移能力在 SDK 内完成重构（详见 SDK CHANGELOG）：
-  - **`TaskMigrationService` 变为实例化、自包含迁移服务** —— 构造仅接收 `{ onBeforeMigrate?, onMigrated?, logger? }`（钩子平铺，无 `hooks` 包装），`migrate({ agent })` 直接复用传入 `agent` 的 `client`/`model`/`modelConfig` 生成交接文档，无需 Provider、无需独立迁移 Agent；暴露结构化 `MigrationContext`
-  - **`AutoMigratePlugin` 收敛为仅触发角色** —— 构造注入 `{ service, maxTokens }`，只检测 token 超限并委托 `service.migrate`
-  - **CLI 移除 `createMigrationAgent`** —— 删除 `src/agent-creator.ts` 中依赖已删除 `TaskMigrationService.createAgentDefinition` 的迁移 Agent 构建；手动迁移命令与自动迁移回调统一改为使用 SDK 迁移服务实例，钩子平铺在服务构造上
+- **Upgraded `@ai-zen/agents-sdk` to 0.8.0** — the task migration capability was refactored inside the SDK (see the SDK CHANGELOG for details):
+  - **`TaskMigrationService` becomes an instantiable, self-contained migration service** — the constructor takes only `{ onBeforeMigrate?, onMigrated?, logger? }` (hooks flat, no `hooks` wrapper), and `migrate({ agent })` directly reuses the passed `agent`'s `client`/`model`/`modelConfig` to generate the handoff document, with no Provider and no dedicated migration Agent needed; it exposes a structured `MigrationContext`
+  - **`AutoMigratePlugin` narrows to a trigger-only role** — the constructor injects `{ service, maxTokens }`, and it only detects token overflow and delegates to `service.migrate`
+  - **The CLI removes `createMigrationAgent`** — the migration Agent construction in `src/agent-creator.ts` that depended on the deleted `TaskMigrationService.createAgentDefinition` is removed; the manual migration command and the auto-migration callback both now use the SDK migration service instance, with hooks flat on the service constructor
 
-### 🚀 新功能
+### 🚀 New features
 
-- **手动任务迁移命令 `/migrate`** — 对话中随时输入 `/migrate` 即可主动触发任务迁移，无需等待 token 超限：
-  - 迁移动作：保存当前对话 → 生成交接文档 → 开启新会话（注入交接文档为上下文）→ 新对话落盘为草稿（`_current.json`）
-  - 与自动迁移联动复用 SDK 的 `TaskMigrationService.migrate`，通过 `onMigrated` 钩子处理后保存
-  - 非破坏性：旧对话已保存到 `conversations/`，生成失败时可重试或继续当前对话
+- **Manual task migration command `/migrate`** — typing `/migrate` in a conversation triggers task migration at any time, without waiting for the token limit to be exceeded:
+  - Migration steps: save the current conversation → generate a handoff document → start a new session (injecting the handoff document as context) → write the new conversation to disk as a draft (`_current.json`)
+  - Reuses the SDK's `TaskMigrationService.migrate` together with auto-migration, handling the post-migration save through the `onMigrated` hook
+  - Non-destructive: the old conversation is already saved under `conversations/`, so on failure the user can retry or continue the current conversation
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **迁移服务单实例收敛** — 将 `TaskMigrationService` 实例挂载到 `ConversationContext.migrationService`，自动迁移（`AutoMigratePlugin` 触发）与手动迁移（`/migrate` 命令）共用**同一个实例**；迁移前后处理（保存旧对话 / 开启新会话 / 落盘草稿）统一收敛到该服务钩子，消除自动与手动两侧各自 `new TaskMigrationService` 及重复的后处理实现
-- **迁移服务抽离为独立模块** — 新增 `src/migration-service.ts`，由 `createMigrationService(ctx)` 统一构建迁移服务实例（含迁移前后钩子）；`saveCurrentConversation` 提升为 `conversation-repository.ts` 的共享 `saveConversation`，供迁移钩子与错误保存共用
+- **The migration service is collapsed to a single instance** — the `TaskMigrationService` instance is mounted on `ConversationContext.migrationService`, shared by auto-migration (triggered by `AutoMigratePlugin`) and manual migration (the `/migrate` command) as **the same instance**; pre/post-migration handling (saving the old conversation / starting a new session / writing the draft to disk) is unified into that service's hooks, eliminating the separate `new TaskMigrationService` on both the automatic and the manual side and the duplicated post-processing implementations
+- **The migration service is extracted into a standalone module** — added `src/migration-service.ts`, where `createMigrationService(ctx)` builds the migration service instance uniformly (including the pre/post-migration hooks); `saveCurrentConversation` is promoted to the shared `saveConversation` in `conversation-repository.ts`, used by both the migration hooks and error saving
 
-### ✅ 测试
+### ✅ Tests
 
-- SDK 侧：`TaskMigrationService`（含 `migrate` / 序列化 / 钩子上下文）、`AutoMigratePlugin`（触发委托断言）全量通过（447 passed / 2 skipped）
-- CLI 侧：`pretest` 类型检查与全量单测通过（37 passed），`npm run build` 成功
+- SDK side: `TaskMigrationService` (including `migrate` / serialization / hook context) and `AutoMigratePlugin` (trigger delegation assertions) all pass (447 passed / 2 skipped)
+- CLI side: `pretest` type checking and the full unit suite pass (37 passed), and `npm run build` succeeds
 
 ## [0.5.0] - 2026-08-23
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **升级 `@ai-zen/agents-core` 到 4.0.0、`@ai-zen/agents-sdk` 到 0.7.0** — 随底层核心重构（官方 OpenAI SDK + 插件化 Agent 驱动层）：
-  - **`createModel()` 返回结构变化** — 从返回旧 `ChatCompletionModel` 实例改为 `{ client, model, modelConfig }`（openai SDK client + 模型名 + 模型参数）；`createMigrationAgent` 相应解构后传入 `SdkAgent` 新构造签名
-  - **`SdkAgent` 构造签名变化** — 由 `{ ..., model }`（模型对象）改为 `{ client, model, modelConfig }`
-  - **CLI 其余部分完全兼容** — 流式事件（`open`/`chunk`/`error`/`sub-agent`/`sub-agent-end`）、插件（`AutoMigratePlugin`/`AutoRefreshToolsPlugin`/`ContextGuardPlugin`）、`AgentNS` 类型（`Delta`/`StreamResponseData`/`Message`）在 core 4.0.0 / sdk 0.7.0 中原样保留，`AgentPlugin`/`SendContext` 由 sdk 重新导出，无破坏
+- **Upgraded `@ai-zen/agents-core` to 4.0.0 and `@ai-zen/agents-sdk` to 0.7.0** — along with the underlying core refactor (official OpenAI SDK + plugin-based Agent driver layer):
+  - **`createModel()` return structure changed** — instead of returning an old `ChatCompletionModel` instance it now returns `{ client, model, modelConfig }` (openai SDK client + model name + model parameters); `createMigrationAgent` destructures it accordingly and passes it to `SdkAgent`'s new constructor signature
+  - **`SdkAgent` constructor signature changed** — from `{ ..., model }` (a model object) to `{ client, model, modelConfig }`
+  - **The rest of the CLI is fully compatible** — stream events (`open`/`chunk`/`error`/`sub-agent`/`sub-agent-end`), plugins (`AutoMigratePlugin`/`AutoRefreshToolsPlugin`/`ContextGuardPlugin`) and `AgentNS` types (`Delta`/`StreamResponseData`/`Message`) are kept as-is in core 4.0.0 / sdk 0.7.0, and `AgentPlugin`/`SendContext` are re-exported by the sdk, with no breakage
 
-### ✅ 测试
+### ✅ Tests
 
-- 依赖升级后单测全量通过（37 passed / 0 failed），`tsc --noEmit` 零错误
+- After the dependency upgrade the full unit suite passes (37 passed / 0 failed), and `tsc --noEmit` reports zero errors
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **`test:all` / `test:e2e` 前置构建** — e2e 测试运行 `dist/index.js`，此前若 `dist` 缺失或为旧构建会导致 e2e 失败（升级后曾因旧 `dist` 报 `AgentContext must have a client`）。现于 e2e 前自动 `npm run build`，干净环境（CI clone 后）可开箱运行
+- **`test:all` / `test:e2e` pre-build** — e2e tests run `dist/index.js`, and previously a missing or stale `dist` caused e2e failures (after an upgrade it once reported `AgentContext must have a client` because of a stale `dist`). `npm run build` now runs automatically before e2e, so a clean environment (a fresh CI clone) works out of the box
 
 ## [0.4.0] - 2026-08-05
 
-### 🚀 新功能
+### 🚀 New features
 
-- **升级 `@ai-zen/agents-core` 到 3.4.0、`@ai-zen/agents-sdk` 到 0.6.0** — 随底层升级带来开箱即用的增强能力：
-  - **内置工具中断信号（abort）支持** — `sleep`/`exec`/`downloadFile`/`generateImage`/`glob`/`findText` 及 subAgent 体系监听 `abort` 信号，CLI 终止对话时超长耗时操作可及时中断，避免资源滞留（`exec` 可区分 `aborted` 与 `timeout` 终止原因）
-  - **工具定义内聚重构** — `Tool` 基类瘦身（不再强制传 `type`/`function`），定义与实现同处一类，回调签名由 `this` 注入改为显式 `(parsed_args, ctx)` 传参，`SdkCallbackTool` 构造改为 `{env}` 容器并透传完整 `ToolCallContext`
-  - **MCP 工具 signal 透传** — `call_mcp_tool` / `read_mcp_resource` 支持中断
-  - cli 层未直接使用上述受影响 API，升级为无破坏性平滑升级，功能不受影响
+- **Upgraded `@ai-zen/agents-core` to 3.4.0 and `@ai-zen/agents-sdk` to 0.6.0** — the underlying upgrade brings out-of-the-box enhancements:
+  - **Abort signal support for built-in tools** — `sleep`/`exec`/`downloadFile`/`generateImage`/`glob`/`findText` and the subAgent system listen to the `abort` signal, so long-running operations can be interrupted promptly when the CLI terminates a conversation, avoiding stranded resources (`exec` can distinguish `aborted` from `timeout` termination reasons)
+  - **Tool definition cohesion refactor** — the `Tool` base class is slimmed down (no longer requires passing `type`/`function`), definition and implementation live in the same class, the callback signature changes from `this` injection to explicit `(parsed_args, ctx)` parameters, and the `SdkCallbackTool` constructor becomes an `{env}` container passing through the full `ToolCallContext`
+  - **MCP tool signal pass-through** — `call_mcp_tool` / `read_mcp_resource` support interruption
+  - The CLI layer does not use the affected APIs directly, so this is a smooth non-breaking upgrade with no functional impact
 
-### ✅ 测试
+### ✅ Tests
 
-- 依赖升级后单测全量通过（37 passed / 0 failed）
+- After the dependency upgrade the full unit suite passes (37 passed / 0 failed)
 
 ## [0.3.5] - 2026-08-13
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **升级 `@ai-zen/agents-core` 到 3.3.1、`@ai-zen/agents-sdk` 到 0.5.7** — 跟随上游内部重构，开箱即用，CLI 无代码改动：
-  - **`innerLoopTasks` 拆分为双集合语义** — Core 3.3.1 新增 `innerLoopsTasks`（整组任务记录）与 `innerLoopTasks`（当前轮活跃任务）；`abort()` 只中止当前轮活跃任务，不再误标已完成的轮次
-  - **内循环开头统一追加 Assistant 占位** — `send()` / `AgentTool` 不再手动追加 Assistant，由 `run()` 每次内循环开头统一处理，多轮工具调用同样收敛到该处
-  - **SDK 0.5.7 同步升级** — 依赖 core 3.3.1，全部 426 个测试（含真实 DeepSeek e2e）通过，完全兼容
+- **Upgraded `@ai-zen/agents-core` to 3.3.1 and `@ai-zen/agents-sdk` to 0.5.7** — following upstream internal refactors, out of the box, with no CLI code changes:
+  - **`innerLoopTasks` split into two set semantics** — Core 3.3.1 adds `innerLoopsTasks` (whole-group task records) and `innerLoopTasks` (tasks active in the current round); `abort()` now only aborts tasks active in the current round and no longer mislabels completed rounds
+  - **An Assistant placeholder is appended uniformly at the start of the inner loop** — `send()` / `AgentTool` no longer append the Assistant manually; `run()` handles it uniformly at the start of every inner loop, and multi-round tool calls converge there as well
+  - **SDK 0.5.7 upgraded in sync** — depends on core 3.3.1, all 426 tests (including real DeepSeek e2e) pass, fully compatible
 
 ## [0.3.4] - 2026-08-14
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **升级 `@ai-zen/agents-core` 到 3.3.0、`@ai-zen/agents-sdk` 到 0.5.6** — 跟随上游统一重构，开箱即用，CLI 无代码改动：
-  - **`ToolCallContext` 统一贯穿「拦截决策 → 执行」** — Core 3.3.0 将 `FunctionCallContext` 统一为 `ToolCallContext`：`onToolCall` 钩子与 `Tool.exec(ctx)` 收同一个实例；新增 `tool_call`（统一形状）、`tool`（匹配到的工具）、`signal`（中止信号）字段，`toolCall` 改名为 `tool_call`。保留 `@deprecated FunctionCallContext` 兼容别名，旧代码无需改动
-  - **新增 `onToolCall` 拦截钩子** — Core 3.3.0 与 SDK 0.5.6 同时提供：每个工具调用执行前可**拒绝**（返回字符串 = 拒绝原因作为工具结果回给 LLM、工具不执行、继续下一轮）；SDK 侧 `AgentPlugin` 支持该钩子（多插件按注册顺序调用，任一返回字符串即拒绝）
+- **Upgraded `@ai-zen/agents-core` to 3.3.0 and `@ai-zen/agents-sdk` to 0.5.6** — following the upstream unified refactor, out of the box, with no CLI code changes:
+  - **`ToolCallContext` runs through "interception decision → execution"** — Core 3.3.0 unifies `FunctionCallContext` into `ToolCallContext`: the `onToolCall` hook and `Tool.exec(ctx)` receive the same instance; the fields `tool_call` (unified shape), `tool` (the matched tool) and `signal` (abort signal) are added, and `toolCall` is renamed to `tool_call`. A `@deprecated FunctionCallContext` compatibility alias is kept, so old code needs no changes
+  - **New `onToolCall` interception hook** — provided by both Core 3.3.0 and SDK 0.5.6: before each tool call executes it can **reject** it (returning a string = the rejection reason returned to the LLM as the tool result, the tool does not execute, and the next round continues); on the SDK side `AgentPlugin` supports the hook (multiple plugins are called in registration order, and the first string returned rejects)
 
 ## [0.3.3] - 2026-08-05
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **依赖声明统一为版本范围** — `@ai-zen/agents-core` 与 `@ai-zen/agents-sdk` 由精确版本（`3.2.0` / `0.5.3`）改为 caret 范围（`^3.2.0` / `^0.5.3`），与 SDK 侧对 core 的 `workspace:^`（发布为 `^3.x`）语义对齐。允许各自主版本范围内的兼容升级，避免升级版本时反复改动依赖声明；实际解析版本保持 `3.2.0` / `0.5.3`（当前 latest），功能不受影响
+- **Dependency declarations unified as version ranges** — `@ai-zen/agents-core` and `@ai-zen/agents-sdk` changed from exact versions (`3.2.0` / `0.5.3`) to caret ranges (`^3.2.0` / `^0.5.3`), aligned with the SDK side's `workspace:^` for core (published as `^3.x`). This allows compatible upgrades within each major version and avoids repeatedly editing dependency declarations when upgrading; the resolved versions remain `3.2.0` / `0.5.3` (current latest), with no functional impact
 
 ## [0.3.2] - 2026-08-05
 
-### 🚀 新功能
+### 🚀 New features
 
-- **接入 `ContextGuardPlugin` 上下文安全护栏** — 在 `conversation-runner.ts` 的插件装配中注册 SDK 0.5.3 提供的 `ContextGuardPlugin`（置于 `AutoMigratePlugin` 之前，复用同一 `maxTokens`）。每次内循环发请求前检测用量，超过 `maxTokens×1.2`（超阈 20%）即抛出 `ContextOverflowError` 中断对话，防止读入超大文件等突发超限撑爆上下文；与迁移插件区间互补：正常超限走交接迁移，严重超限由护栏直接中断报错
+- **Wired in the `ContextGuardPlugin` context guard** — registers the `ContextGuardPlugin` provided by SDK 0.5.3 in `conversation-runner.ts`'s plugin assembly (placed before `AutoMigratePlugin`, reusing the same `maxTokens`). Before each inner-loop request it checks usage and, once `maxTokens×1.2` (20% over the threshold) is exceeded, throws `ContextOverflowError` to abort the conversation, preventing sudden overflow (such as reading a huge file) from blowing up the context; it complements the migration plugin's range: normal overflow goes through handoff migration, while severe overflow is aborted directly by the guard with an error
 
-### ✨ 优化
+### ✨ Optimizations
 
-- **修正 `conversation-runner.ts` 插件注册注释编号** — 统一连续编号（1 cwdTracker / 2 autoRefreshTools / 3 draftPlugin / 4 contextGuard / 5 autoMigrate），消除此前重复编号
+- **Fixed the plugin registration comment numbering in `conversation-runner.ts`** — unified consecutive numbering (1 cwdTracker / 2 autoRefreshTools / 3 draftPlugin / 4 contextGuard / 5 autoMigrate), removing the previous duplicate numbering
 
 ## [0.3.1] - 2026-08-05
 
-### 🚀 新功能
+### 🚀 New features
 
-- **升级 `@ai-zen/agents-sdk` 到 0.5.3** — 随 SDK 新能力开箱即用：
-  - **初始化默认释放 socket-pty MCP 配置** — SDK `bootstrap()` 新增 `ensureDefaultMcpConfig()`，CLI 首启在 `~/.ai-zen/mcp.json` 自动写入含 `socket-pty` 终端的默认 MCP 配置（`npx -y @ai-zen/socket-pty mcp`），文件已存在则幂等不覆盖
-  - **`load_mcp` 透传 server description** — 枚举各 MCP 服务器描述供 LLM 参考（对齐 `load_skill`）
-  - **新增 `ContextGuardPlugin` 上下文安全护栏** — 在发请求前检测用量，超过 `maxTokens×1.2`（超阈 20%）时抛出 `ContextOverflowError` 中断对话，防止读入超大文件导致上下文失控；与 `AutoMigratePlugin` 职责分离、区间互补
+- **Upgraded `@ai-zen/agents-sdk` to 0.5.3** — new SDK capabilities available out of the box:
+  - **A default socket-pty MCP config is released on initialization** — SDK `bootstrap()` adds `ensureDefaultMcpConfig()`; on first start the CLI automatically writes a default MCP config containing the `socket-pty` terminal (`npx -y @ai-zen/socket-pty mcp`) to `~/.ai-zen/mcp.json`, idempotently and without overwriting an existing file
+  - **`load_mcp` passes through the server description** — enumerates each MCP server's description for the LLM to reference (aligned with `load_skill`)
+  - **New `ContextGuardPlugin` context guard** — checks usage before sending a request and, once `maxTokens×1.2` (20% over the threshold) is exceeded, throws `ContextOverflowError` to abort the conversation, preventing a huge file read from letting the context run away; responsibilities are separated from `AutoMigratePlugin` and the ranges complement each other
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **自动迁移后未立即保存新对话为草稿** — `AutoMigratePlugin` 的迁移发生在 `onAfterSend`（所有内循环已结束、`DraftPlugin` 的 `onInnerLoopEnd` 不再触发），迁移替换 `agent.messages` 后的新开场白未被及时落盘，用户在中途退出会丢失迁移后的开场白。现于 `onMigrated` 回调中迁移完成后立即将新消息写入草稿（`_current.json`），与「原对话先保存为 `conversations/`」形成完整闭环
+- **The new conversation was not saved as a draft immediately after auto-migration** — `AutoMigratePlugin` migrates in `onAfterSend` (all inner loops have ended, so `DraftPlugin`'s `onInnerLoopEnd` no longer fires), so the new opening message produced after migration replaced `agent.messages` was not written to disk in time, and a user exiting midway lost the post-migration opening. The new messages are now written to the draft (`_current.json`) immediately after migration completes in the `onMigrated` callback, closing the loop together with "the original conversation is saved to `conversations/` first"
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **MCP 配置结构统一为业界标准 `mcpServers`** — 以 SDK（`discoverMcpServers`）为准，CLI 的 `McpConfig` 顶层字段由 `servers` 改为 `mcpServers`、server 传输字段由 `transport` 改为 `type`。消除格式漂移，CLI 管理界面（`zen config`）与 SDK 默认释放的 mcp.json 完全对齐，socket-pty 默认配置可被正确显示与管理
+- **The MCP config structure is unified on the industry-standard `mcpServers`** — following the SDK (`discoverMcpServers`), the CLI's `McpConfig` top-level field changes from `servers` to `mcpServers`, and the server transport field from `transport` to `type`. This eliminates format drift, fully aligning the CLI management UI (`zen config`) with the mcp.json released by the SDK by default, so the default socket-pty config can be displayed and managed correctly
 
-### ✅ 测试
+### ✅ Tests
 
-- 更新 `config.test.ts` 中 MCP 读写相关断言以匹配新的 `mcpServers` 结构与 `type` 字段
+- Updated the MCP read/write assertions in `config.test.ts` to match the new `mcpServers` structure and `type` field
 
 ## [0.3.0] - 2026-08-01
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **会话/草稿持久化下放 CLI** — SDK 0.5.0 移除了会话/草稿产品层（`ConversationRepository` / `DraftRepository` / `AutoDraftPlugin`）。CLI 自建本地存储：
-  - 新增 `src/conversation-repository.ts` — `conversationRepository`（复用 SDK `EntityRepository`）
-  - 新增 `src/draft-repository.ts` — `DraftRepository` + `draftRepository` 单例（草稿无 id 字段，单独实现）
-  - 新增 `src/draft-plugin.ts` — CLI 草稿插件 `DraftPlugin`（替代被移除的 `AutoDraftPlugin`，`onInnerLoopEnd` 自动保存）
-- **更新 `@ai-zen/agents-sdk` 到 0.5.0** — 内置工具类化（`SdkCallbackTool` + `ToolEnv` 注入）、`Provider` 支持 `cwd`/`env`、`generateImage` 类化为 `GenerateImageTool`
+- **Session/draft persistence moved down into the CLI** — SDK 0.5.0 removed the session/draft product layer (`ConversationRepository` / `DraftRepository` / `AutoDraftPlugin`). The CLI builds its own local storage:
+  - Added `src/conversation-repository.ts` — `conversationRepository` (reusing the SDK's `EntityRepository`)
+  - Added `src/draft-repository.ts` — `DraftRepository` + the `draftRepository` singleton (drafts have no id field, so it is implemented separately)
+  - Added `src/draft-plugin.ts` — the CLI draft plugin `DraftPlugin` (replacing the removed `AutoDraftPlugin`, auto-saving in `onInnerLoopEnd`)
+- **Updated `@ai-zen/agents-sdk` to 0.5.0** — built-in tools turned into classes (`SdkCallbackTool` + `ToolEnv` injection), `Provider` supports `cwd`/`env`, `generateImage` turned into the `GenerateImageTool` class
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **依赖同步线上版本** — `@ai-zen/agents-core` `3.0.1`、`@ai-zen/agents-sdk` `0.5.0`（开发期曾使用本地 `link:` 调试，已还原为 npm 版本号）
+- **Dependencies synced to the published versions** — `@ai-zen/agents-core` `3.0.1`, `@ai-zen/agents-sdk` `0.5.0` (a local `link:` was used for debugging during development and has been restored to npm version numbers)
 
 ## [0.2.3] - 2026-07-29
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **更新 `@ai-zen/agents-sdk` 到 0.4.0** — load_mcp 返回值改为结构化 JSON（含完整 inputSchema），日志 API 改为全局单例 `getLogger()`/`setLogger()`
+- **Updated `@ai-zen/agents-sdk` to 0.4.0** — the load_mcp return value changed to structured JSON (including the full inputSchema), and the logging API changed to the global singleton `getLogger()`/`setLogger()`
 
 ## [0.2.2] - 2026-07-27
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **更新 `@ai-zen/agents-sdk` 到 0.3.4** — 包含 AutoMigratePlugin 钩子重命名（`onHandoff` → `onMigrated`）
-- **保存旧对话的时机修正** — 从 `onMigrated`（原 `onHandoff`）移至 `onBeforeMigrate`，确保保存的是完整的旧对话历史
+- **Updated `@ai-zen/agents-sdk` to 0.3.4** — includes the AutoMigratePlugin hook rename (`onHandoff` → `onMigrated`)
+- **Fixed the timing of saving the old conversation** — moved from `onMigrated` (formerly `onHandoff`) to `onBeforeMigrate`, ensuring that what is saved is the complete old conversation history
 
 ## [0.2.1] - 2026-07-27
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **更新 `@ai-zen/agents-sdk` 到 0.3.3** — 包含默认 Agent/SubAgent 提示词优化（信息明确性要求、矛盾检测）
+- **Updated `@ai-zen/agents-sdk` to 0.3.3** — includes default Agent/SubAgent prompt improvements (information explicitness requirements, contradiction detection)
 
 ## [0.2.0] - 2026-07-26
 
-### 💥 破坏性变更
+### 💥 Breaking changes
 
-- **同步 SDK 0.3.2 异步 API** — `@ai-zen/agents-sdk` 从 `0.3.1` → `0.3.2`
-- **`readConfig()` / `saveConfig()` 改为 async** — 因 SDK `ConfigManager` 全面异步化
-- **`createAgent()` 恢复为 async** — 因 SDK `createAgent()` 改回异步
-- **`installHook()` / `uninstallHook()` 改为 async** — Shell hook 安装/卸载使用 `fs.promises`
+- **Synced to SDK 0.3.2's async API** — `@ai-zen/agents-sdk` from `0.3.1` → `0.3.2`
+- **`readConfig()` / `saveConfig()` changed to async** — because the SDK's `ConfigManager` is fully async
+- **`createAgent()` restored to async** — because the SDK's `createAgent()` is async again
+- **`installHook()` / `uninstallHook()` changed to async** — shell hook install/uninstall uses `fs.promises`
 
-### 🎯 优化
+### 🎯 Optimizations
 
-- **全面消除同步文件 IO** — `config.ts`、`hook.ts`、`conversations.ts`、`config-display.ts` 中所有 `existsSync`、`readFileSync`、`writeFileSync`、`readdirSync`、`statSync`、`renameSync`、`appendFileSync`、`mkdirSync`、`unlinkSync` 替换为 `fs.promises` 异步 API
-- **`getConversationsList()` 改为 async** — 对话列表读取使用异步文件 API
-- **MCP 配置读写异步化** — `readMcpConfig()`、`writeMcpConfig()`、`readProjectMcpConfig()` 均改为 async
+- **Synchronous file IO fully eliminated** — every `existsSync`, `readFileSync`, `writeFileSync`, `readdirSync`, `statSync`, `renameSync`, `appendFileSync`, `mkdirSync` and `unlinkSync` in `config.ts`, `hook.ts`, `conversations.ts` and `config-display.ts` is replaced with the async `fs.promises` API
+- **`getConversationsList()` changed to async** — the conversation list is read through async file APIs
+- **MCP config read/write made async** — `readMcpConfig()`, `writeMcpConfig()` and `readProjectMcpConfig()` are all async now
 
-### ✅ 测试
+### ✅ Tests
 
-- 同步更新 `config.test.ts` 为 `async`/`await`，全部 43 个测试通过（含 6 个 E2E）
+- `config.test.ts` updated in sync to `async`/`await`, all 43 tests pass (including 6 E2E)
 
 ## [0.1.7] - 2026-07-21
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **更新依赖**: `@ai-zen/agents-core` → `3.0.0-alpha.4`, `@ai-zen/agents-sdk` → `0.2.7`
+- **Updated dependencies**: `@ai-zen/agents-core` → `3.0.0-alpha.4`, `@ai-zen/agents-sdk` → `0.2.7`
 
 ## [0.1.6] - 2026-07-20
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **更新 `@ai-zen/agents-sdk` 到 0.2.6** — 包含默认 SubAgent 函数名和描述修复，LLM 现在能正确识别子 Agent
+- **Updated `@ai-zen/agents-sdk` to 0.2.6** — includes fixes to the default SubAgent function name and description, so the LLM can now identify sub-agents correctly
 
 ## [0.1.5] - 2026-07-20
 
-### 🔧 修复
+### 🔧 Fixes
 
-- **更新 `@ai-zen/agents-sdk` 到 0.2.5** — 包含默认 SubAgent 权限修复，`general-assistant` 现在能正常使用工具
+- **Updated `@ai-zen/agents-sdk` to 0.2.5** — includes a fix to default SubAgent permissions, so `general-assistant` can now use tools normally