@bachi/pi-coder 1.0.0

package/extensions/bash-command-collapse.ts

@@ -0,0 +1,1476 @@
+/**
+ * Bash Command Collapse Extension
+ *
+ * 把 bash 工具调用里显示的 shell 命令折叠成前 N 个**视觉行** + 一行「被折叠内容有多大」
+ * 提示，避免超长命令（heredoc、多行管道、内联脚本）刷屏。纯显示层：发给模型的 tool call
+ * 参数、session 记录里的原文完全不变。
+ *
+ * 提示格式 `… (123 tokens hidden)`，token 为估算值。注意 thinking-collapse.ts 已经
+ * 换成滚动窗口、不再输出这个提示（底部 spinner 在数 token），所以这套提示格式现在
+ * 只剩 bash 命令折叠在用。
+ * ctrl+o（app.tools.expand）展开工具输出时，命令也会完整显示。
+ *
+ * ## 折叠视图：break-all 硬折行（不提前折行、不用 `…` 截断）
+ *
+ * 折行规则是 CSS `word-break: break-all` 那一套：按列预算逐个 grapheme 填充，**装满到
+ * 恰好放不下为止再断**，断点就在行末，不管它落在单词/路径中间。实现见 `hardWrapToWidth`。
+ *
+ * 为什么不用 pi-tui 的 `wrapTextWithAnsi`：它是**贪心词折行 + 长词按列断开**，装不进当前行
+ * 剩余空间的词会被**整块挑到下一行**再去断 —— 实测 79 列终端上 `$ cp <78 列路径>` 渲染成
+ * `$ cp` 单独一行 + 路径从中间断成两截：行尾白白空着几十列（就是“提前折行”那个难看的
+ * 样子），命令和它的参数还被拆开。硬折行则把每行填满，`$ ` 后面直接跟命令正文。
+ *
+ * 中间试过第三条路（commit 9024c26）：不折行、装不下就把行尾截成 `…`。它确实不会提前
+ * 折行，但一条长命令只剩一行可见内容、后面全丢，信息量太低 —— 现在改成硬折行后，
+ * 同样的预算能装满 3 整行正文，超出部分才走隐藏提示。
+ *
+ * 行数预算（`limit`，默认 3）按**视觉行**算而不是源行：一条超长单行命令占满整个预算
+ * 而不是刷十几行，而短行的多行命令（heredoc 等）仍然显示前 3 条源行 —— 两种情况都不
+ * 会失控。超出预算的内容（当前源行的尾巴 + 后面所有源行）计入 `… (N tokens hidden)`。
+ * 展开态（ctrl+o）/ `/bash-collapse off` 用同一套硬折行规则，只是不限行数 —— 折行规则
+ * 必须一致，否则展开态又会出现“提前折行”。
+ *
+ * ## 输出预览行数（pi 写死 5 行，这里改成 3 行）
+ *
+ * pi 把 bash 输出的预览行数写死在 `core/tools/renderers/bash.js` 的
+ * `const BASH_PREVIEW_LINES = 5`：模块私有常量，既没从包里导出，也不在
+ * `BashToolOptions` 里，`docs/settings.md` 里也没有对应设置项 —— **没有全局配置可改**，
+ * 只能在扩展里后处理（`withPreviewLimit` / `trimPreviewLines`）。
+ *
+ * 做法是拿 pi 渲好的组件做后处理而不是重写整个 resultRenderer，这样 pi 的语义
+ *（截断页脚剔除、warnings、`Took Xs`、展开态、图片）全部保留，我们只动预览那一段。
+ * 两个关键点：① **逐 child 渲染**而不是拿平铺行数组（平铺数组里分不清哪几行是预览）；
+ * ② 裁掉的行数必须补进提示行的计数，否则「隐藏了多少行」就谎了 —— pi 给了提示行就
+ * 在它那行**原地改数字**（保住 pi 的配色与真实键名），pi 没给（输出刚好 ≤ 5 行）
+ * 就自建一行，否则那 1~2 行会静默消失。
+ *
+ * 展开态（ctrl+o）自动不受影响：那时 pi 用的是 `new Text(...)` 而不是预览组件，
+ * 鸭子判定直接跳过，完整输出一行不裁。
+ *
+ * ## 输出树形 gutter（`│` / `└`）
+ *
+ * 给输出预览的每一行挂一个字符的缩进：除末行外是 `│ `，末行是 `└ `，对齐 codex
+ * 的 bash 输出样式 —— 命令在上、输出挂在一棵树下，层次一眼可辨：
+ *
+ * ```
+ * $ cat text.txt
+ * │ ... (7 earlier lines, ctrl+o to expand)
+ * │ hello world
+ * └ hello world
+ *
+ *  Took 2.4s
+ * ```
+ *
+ * （`Took Xs` 那行只在执行够久时才画 —— 上面这个例子里命令跑了 2.4s，
+ * 见下面「耗时页脚门槛」一节。）
+ *
+ * 实现挂在 `withPreviewLimit` 里（它本来就要逐 child 找出「哪个子组件是输出」，
+ * gutter 用的是同一条判定），细节与三个不能想当然的点见 `prefixTreeLines`。
+ * 两个刻意的设计决定：
+ *   ① **展开态（ctrl+o）不加 gutter** —— 展开态要的就是原样完整输出。pi 那时用的是
+ *     `new Text(...)`（有 `setText`），鸭子判定天然跳过它，所以这条不需要额外分支，
+ *     与「展开态不裁预览行」共用同一个机制。
+ *   ② **warnings / `Took Xs` 不进树** —— 它们是元信息页脚而不是命令输出，和命令
+ *     上方的 `… (N tokens hidden)` 提示一样留在树外（那条提示属于 renderCall 的
+ *     块，本来就不在结果组件里）。
+ * gutter 占 2 列，所以输出子组件必须按 `width - 2` 渲染（详见 `withPreviewLimit`）。
+ * `/bash-tree off` 可关；关掉后渲染路径与加 gutter 之前逐行一致。
+ *
+ * ## 耗时页脚门槛（短命令不画 `Took`）
+ *
+ * pi 内置的结果渲染器**无条件**在末尾画一行 `Took X.Xs`（`state.startedAt` 有值就画），
+ * 而它是个**独占一行**的页脚：对绝大多数几十毫秒的命令来说只是白占一行高度，还额外带进
+ * 一行分隔空行（页脚是 `new Text("\n" + …)`，那个前导 `\n` 就是正文与页脚之间的空白行）：
+ *
+ * ```
+ * $ echo hello
+ * └ hello
+ *
+ *  Took 0.1s
+ * ```
+ *
+ * 所以**短命令整条页脚都不画**（连那行分隔空行一起）—— 区块变成「命令行 + 输出 +
+ * 下边界空行」，一行都不浪费。门槛默认 2000ms（常量 `DEFAULT_MIN_TIME_FOOTER_MS`），
+ * `PI_BASH_MIN_TIME_MS` 启动时可改，`0` = 永远显示（等于关掉这个优化）。
+ *
+ * 判定用**真实耗时** `endedAt - startedAt`（与 pi 画那个数字用的是同一个量），不去解析
+ * 页脚上的文本 —— 文本是 `(ms / 1000).toFixed(1)` 四舍五入过的，拿它判会出现「显示 2.0s
+ * 其实只跑了 1.96s」这类边界偏差。门槛 >= 耗时即隐藏，所以能看见的数字必然 >= 2.0s，
+ * 不会出现自相矛盾的 `Took 1.9s`。
+ *
+ * 流式模式（`/bash-stream on`）下执行期中那个 `Elapsed X.Xs` 走同一条判定（同一个页脚，
+ * 只是文案跟着 `isPartial` 变）：短命令执行期间不会闪出那一行，跑过 2s 才出现 ——
+ * 正好是「值得看一眼」的时刻。非流式（默认）下只在执行结束时判一次，正是用户要的语义。
+ *
+ * 实现挂在 `withPreviewLimit` 里（它本来就要逐 child 渲染、也本来就把 warnings / `Took`
+ * 当「非输出 child」透传），判定见 `isTimeFooterChild`：末位 + 文本形态两条缺一不可。
+ *
+ * ## bash 命令语法高亮（轻量版）
+ *
+命令行按 shell 词法上色：命令名 `syntaxFunction`、选项 `-x/--xxx` `syntaxKeyword`、
+引号串与路径 `syntaxString`、`$VAR`/`NAME=` 赋值 `syntaxVariable`、`|`/`&&`/重定向
+`syntaxOperator`、`#` 注释 `syntaxComment`，`$ ` 前缀用 `toolTitle`（正常色，不用 dim）。配色走主题的 `syntax*`
+槽（和 markdown 代码块同一套），所以换主题自动跟着变。默认开，`PI_BASH_HIGHLIGHT=off`
+回到改动前的「整行 toolTitle 粗体」—— 刻意**没有** `/bash-highlight` 指令：纯观感开关，
+env 一个入口就够，没必要再占一条斜杠指令。
+
+参照 `@sting8k/pi-droid-styling` 的 `tool-tags/bash.ts`：它同样是**手写 shell 分词器**
+（`tokenizeShellLinePreservingText` + `colorShellWord`），只在分词失败（引号没闭合）时
+才退回 pi 导出的 `highlightCode(line, "bash")`。这里不采它的退回路径 —— `highlightCode`
+返回的是**带 ANSI 的整行**，而本扩展的折行是 break-all 硬折行、必须「先折纯文本、
+后上色」（反过来会把 SGR 序列从中间切断，见 renderCall 里的注释），带 ANSI 的行没法
+再喂给 `hardWrapRows`。所以分词失败就退回单色粗体，而不是换一个高亮器。
+
+对齐办法：token 偏移是**源行**坐标，碎片是**折行后**坐标，`hardWrapRows` 记下每条
+碎片对应原文的 `[start, end)` 字符区间，上色时按区间切 token。三条要点：
+  ① 一个 token 被折行切成两半时，两半是同一种颜色 —— 视觉上无碍，这就是用户说的
+    「有折行所以高亮可能不准，轻一些」的那部分。
+  ② 引号状态**跨源行**保留（`openQuote`），所以多行字符串（`git commit -m "…\n…"`）
+    的第二行不会被当成命令重新分词。heredoc 正文没有这个待遇（`<<EOF` 不是引号），
+    会按命令行上色 —— 无害，只是不准。
+  ③ 折叠预算用完就停止分词，被隐藏的尾巴不参与上色（也不参与 token 计数以外的任何
+    计算），所以折叠提示里的 token 估算仍然基于纯文本。
+
+## 输出正文的独立颜色（扩展 token `bashOutput`）
+
+pi 的内置 bash 结果渲染器把输出正文写死成 `theme.fg("toolOutput", line)` —— 那是**所有
+工具输出共用的槽**（read / grep / ls 的正文、`…` 占位符都吃它），想只调 bash 输出的颜色
+就得绕开它。做法是在**委托给内置渲染器的那个同步窗口**里把主题的 `toolOutput` 临时指向
+`bashOutput`（`withBashOutputColor()`），于是只有输出正文换色 —— 命令行（`toolTitle` +
+自绘语法高亮）、折叠提示（`muted` / `dim`）、树形 gutter（`muted`）、`Took Xs` 页脚
+（`muted`）一律不受影响，其他工具的输出也完全不受影响（它们的渲染器不在这个窗口里跑）。
+
+注意**传给 `renderResult` 的那个 theme 参数是没用的**：pi 的 bash 渲染器签名把第二个
+theme 参数写成 `_theme` 后根本不用它，输出行是用**模块级 theme 单例**上的色。
+那个单例（`Proxy` → `globalThis[Symbol.for("@earendil-works/pi-coding-agent:theme")]`）
+与扩展拿到的渲染器参数是同一个对象，所以改它的 `fgColors` 表就是改渲染器看到的色值。
+
+`bashOutput` 是本仓库自造的 token（pi 官方 schema 里没有，与 `toolDiffAddedBg` 那两个
+同一条路：TypeBox 校验对未知 key 放行、`createTheme()` 把它们收进前景表）。**主题没定义它
+就什么都不做**（探测方式是真调一次 `getFgAnsi()`，pi 对未知 token 抛
+`Unknown theme color: …`），所以内置主题与 summer-night / catppuccin 照旧走 `toolOutput`，
+目前只有 `ayu.json` 定义了这个 token。展开态（ctrl+o）同样是输出正文，一并生效。
+
+## 染色块的上下边界空行
+ *
+ * self 模式下 pi 不再套 `Box(1, 1, bgFn)`，所以底色块的上下内边距得自己画回来：
+ * 命令行**上面**一行、最后一行（通常是 `Took Xs`）**下面**一行，两行都是染了底色的
+ * 空行（Box.applyBg 会把每行补满到 width 再上色，空行也不例外），这样文字不会顶着
+ * 染色区的上/下边缘。对齐 pi 默认 shell 的观感（`Box(1, 1)` 就是这个效果），
+ * 但**中间**（命令与输出之间）仍然紧贴 —— 那是刻意去掉的，见 renderResult 里的注释。
+ *
+ * 为什么不能直接给两个 Box 各设 `paddingY: 1`：命令与结果是两个独立的 Box，各自的
+ * 垂直 padding 会叠加成「命令与输出之间三行空白」（实测过），所以只在最外侧补：
+ * 上边界放在 call 组件的首行，下边界放在 result 组件的末行。命令已出、结果还没到的
+ * 中间态（pending）由 call 组件自己补一行下边界，否则那几十毫秒~几十秒里块是
+ * 「上留白、下触底」的歪样子。
+ *
+ * 用法：
+ *   /bash-collapse            查看当前状态
+ *   /bash-collapse off        关闭折叠（完整显示）
+ *   /bash-collapse on         打开折叠（默认 3 行 + token 提示）
+ *   /bash-collapse 5          打开折叠并保留前 5 个视觉行（1-50）
+ *   /bash-preview             查看输出预览行数
+ *   /bash-preview 5           输出预览改成 5 行（1-50）
+ *   /bash-preview off         恢复 pi 内置的 5 行预览
+ *   /bash-tree                查看输出树形缩进状态
+ *   /bash-tree off            输出顶格显示（不挂 │ / └）
+ *   /bash-tree on             输出挂树形缩进（默认）
+ *   /bash-stream              查看当前输出方式
+  *   /bash-stream off          非流式（默认：命令与输出都一次性显示）
+ *   /bash-stream on           流式（pi 原生行为：命令逐字刷、输出边跑边刷）
+ *   /bash-timeout             查看 bash 执行期限（默认 / 上限 / env 覆盖）
+ *
+ * 附带第五个职责：**短命令不画耗时页脚** —— 默认执行时长 < 2s 就把 `Took 0.1s` 那一行
+ *（连它的前导分隔空行）整个去掉，详见上面「耗时页脚门槛」一节。`PI_BASH_MIN_TIME_MS`
+ * 可改门槛，`0` = 永远显示。
+ *
+ * 附带第四个职责：把 bash **输出预览**从 pi 内置的 5 行改成 3 行
+ *（`BASH_PREVIEW_LINES` 是 pi 的模块私有常量，没导出也没设置项，只能后处理，
+ * 详见下面「输出预览行数」一节）。`/bash-preview` 可改。
+ *
+ * 附带第三个职责：给每条 bash 命令**强制一个执行期限**（默认 120s、上限 600s，
+ * 照抄 Claude Code 的 BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS 策略，详见下面
+ * CLAUDE_CODE_DEFAULT_TIMEOUT_MS 那块的注释）。pi 内置 bash 的 timeout 无默认值，
+ * 不注入就会无限期等下去。
+ *
+ * 附带第二个职责：把 bash 工具调用的屏幕显示改成**非流式**（默认，对齐 opencode / codex）。
+ * pi **没有**任何设置项能做到这件事（settings.md 里 Shell 一节只有 shellPath /
+ * shellCommandPrefix / npmCommand）。而且这里有**两条独立的流式机制**，必须分别处理：
+ *
+ * （1）**输出流式**：内置 bash 的 execute 每收到 stdout/stderr 数据就 onUpdate() 一份快照，
+ *     节流 100ms（renderers/bash.js 的 BASH_UPDATE_THROTTLE_MS），经 tool_execution_update
+ *     事件到 TUI（interactive-mode.js）当 partial 结果重画一遍。
+ *     关掉的办法：把 onUpdate 传成 undefined —— execute 里每个更新点都有
+ *     `if (!onUpdate) return` 守卫，于是全程零更新。渲染器不受影响：组件在
+ *     `tool_execution_start` 就已创建（与更新无关），最终显示走 `tool_execution_end` →
+ *     `updateResult(result, isPartial=false)`，所以压掉 partial 只是少了中间帧，
+ *     结束那一次照常出（5 行预览 + 展开提示 + 截断提示 + "Took Xs"）。
+ *
+ * （2）**命令文本流式**：模型生成工具调用时参数是流式的（json 事件里能看到 toolcall_delta
+ *     一片一片到：`{"command": "echo a` / `; sleep 0` / `.3; echo` …），pi 每收一片就
+ *     updateArgs() → updateDisplay() → 重画一次 renderCall，于是命令一个字一个字冒出来。
+ *     这条与（1）**完全无关**，光压 onUpdate 管不到它。
+ *
+ *     关掉的办法是把两个时间点**分开**处理（对齐 codex / opencode）：
+ *       时间点一：命令字符全收完（`context.argsComplete`）→ renderCall 一次性出完整命令；
+ *       时间点二：命令执行完 → renderResult 把结果补刷到命令下面。
+ *     具体做法：renderCall 在「args 可能还在流」（`!argsComplete && isPartial === true`）时
+ *     返回**零行组件**（连占位行都不画）。
+ *     注意不能**只**用 isPartial 当阈值：isPartial 要等 final 结果才置 false，单用它会把
+ *     命令也压到结果之后，退化成「全等到结果才一次性出」。
+ *     （setArgsComplete() 在 assistant message_end 时调，比 tool_execution_start 早 ~60ms，
+ *     正好是“命令收完”这个语义点。）
+ *     也不能**只**用 argsComplete：它只在实时流里置位，`/resume` 等历史重建路径从不调
+ *     setArgsComplete（见 renderCall 里的详细说明），单用它会让恢复出来的 bash 块
+ *     只剩输出、命令行整行消失（这就是曾经的 resume bug）。
+ *     另外零行组件不会画出空盒子：Box.render 开头有 `childLines.length === 0 → []` 守卫
+ *     （paddingY 是在这之后才加的）。
+ *
+ * 实测证据：
+ *   - `pi -p --mode json` 跑真实 pi 数事件，同一条
+ *     `echo a; sleep 0.35; echo b; sleep 0.35; echo c`：扩展加载时 `tool_execution_update` = **0**，
+ *     `--no-extensions` 跑内置 bash 时 = **4**；两种情况的 tool result 都是 `"a\nb\nc\n"`。
+ *   - 直接调包根导出的 createBashToolDefinition 数 onUpdate 次数：传 onUpdate = 4 次
+ *     （1 次初始空更新 + 3 份输出快照），传 undefined = 0 次，final result 逐字节相同。
+ *   - **执行耗时不受影响**：同一条 `echo a; sleep 0.5; echo b`，流式平均 545ms / 非流式
+ *     平均 566ms（各跑 3 次，差 21ms 在噪声内）。所谓“变慢”是非流式的固有代价：
+ *     以前第一块输出 ~100ms 就冒出来了，现在整个命令跑完才显示，感知延迟 = 命令全时长。
+ *   - `echo hello` 的真实时间线：toolcall_start → toolcall_end 197ms（args 流式，模型侧）、
+ *     toolcall_end → tool_execution_start 63ms、tool_execution_start → end 只 31ms。
+ *     即“等了一下”的主体是模型在生成 tool call，不是命令执行。
+ *
+ * 为什么必须放在本扩展里而不是新开一个 bash-stream.ts：跨扩展的同名工具注册是
+ * **first registration per name wins**（runner.js getAllRegisteredTools 的注释原文，
+ * 按扩展加载顺序即文件名顺序遍历）。本文件排在前面，新开的那个会被**静默忽略**。
+ *
+ * 非流式的代价（刻意的，别顺手"优化"）：
+ *   - 命令收完到执行完之间**没有进度反馈**（只有那行命令，没有输出、没有计时）。
+ *     `renderResult` 里的每秒计时器只在 `options.isPartial` 时才起
+ *     （`if (state.startedAt !== undefined && options.isPartial && !state.interval)`），
+ *     没有 partial 就永远不起，也没有 "Elapsed" 跳动，直到结束才补上
+ *     「输出 + Took 12.3s」。命令通常很短所以可接受；真要盯长任务就 `/bash-stream on`。
+ *   - 发给模型的内容**完全不变**：onUpdate 只喂显示层（tool_execution_update →
+ *     tool-execution.js 的 isPartial），既不进 session 落盘也不进 tool result，
+ *     execute 的返回值一字不差；renderCall 也只改显示，tool call 参数与 session 原文不动。
+ */
+
+import type { BashToolOptions, ExtensionAPI, ThemeColor, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Box, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** 缩略保留的**视觉行**数（硬折行后一条超长单行命令也最多占这么多行）。 */
+const DEFAULT_LINES = 3;
+
+/**
+ * 输出预览保留的行数（pi 内置是 5，这里改成 3）。
+ *
+ * pi 把行数写死在 `core/tools/renderers/bash.js` 的 `const BASH_PREVIEW_LINES = 5`：
+ * 模块私有常量，既没从包里导出（`index.d.ts` 里没有），也不在 `BashToolOptions`
+ * 里，`docs/settings.md` 里也没有任何对应的设置项 —— 所以没有全局配置可改，
+ * 只能在扩展里后处理。详见文件头「输出预览行数」一节。
+ */
+const DEFAULT_OUTPUT_PREVIEW_LINES = 3;
+
+/**
+ * 耗时页脚的展示门槛（毫秒）：执行时长**短于**它就不画 `Took 0.1s` 那一行。
+ *
+ * pi 内置 `renderResult` 无条件在结果末尾画一行 `Took X.Xs`（`state.startedAt` 有值就画），
+ * 而它是个独占一行的页脚（外加自己那行前导空行）—— 对几十毫秒的命令来说纯属白占两行。
+ * 详见文件头「耗时页脚门槛」一节。
+ *
+ * `PI_BASH_MIN_TIME_MS` 启动时可改；`0` 是合法值 = 永远显示（等于关掉这个优化）。
+ */
+const DEFAULT_MIN_TIME_FOOTER_MS = 2000;
+
+/**
+ * 第三个职责：给每条 bash 命令**强制一个执行期限**（照抄 Claude Code 的策略）。
+ *
+ * 为什么必须有：pi 的内置 bash `timeout` 是可选参数且**无默认值**（schema 描述原文
+ * "Timeout in seconds (optional, no default timeout)"，settings.md 里也没有任何全局
+ * 工具超时项），所以模型不传 timeout 时，一条不退出的命令会让 pi **无限期等下去**。
+ * 而本扩展默认非流式（onUpdate 被摘掉），内置渲染器的 `Elapsed` 计时器只在
+ * `isPartial` 时才起（renderers/bash.js），于是屏幕上「进程卡死」与「纯粹耗时」
+ * 长得一模一样 —— 既不会自己脱困，也看不出该不该等。
+ *
+ * Claude Code 的做法（从 v2.1.268 二进制里扒出的原文，JS 是内嵌的）：
+ *   var xRo=120000, ARo=600000;                       // 默认 2min / 上限 10min
+ *   wCe(env)  → BASH_DEFAULT_TIMEOUT_MS 否则 xRo       // 默认
+ *   i7e(env)  → Math.max(BASH_MAX_TIMEOUT_MS 否则 ARo, wCe(env))   // 上限=max(配置,默认)
+ *   Math.min(z || Xe(), Be())                          // 模型传的 timeout **静默 clamp**
+ * 工具描述里还把数字告诉模型："You may specify an optional timeout in milliseconds
+ * (up to ${max}ms…). By default, your command will timeout after ${default}ms…"。
+ * 注意它的单位是 ms，pi 的 bash 参数是**秒**，所以下面统一除 1000。
+ *
+ * env 变量名沿用 Claude Code 的（BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS），
+ * 这样两边行为一致、迁移过来的配置直接可用；跟 Claude Code 一样在**调用时**读
+ * process.env（不是模块加载时），所以运行时改 env 也生效。
+ *
+ * 超时后 pi 自己会 `killProcessTree(pid)`（整棵进程树，孙进程一起清）并把
+ * "Command timed out after N seconds" 连同已有输出一起返回给模型 —— 这一步不用我们管。
+ * 代价（与 Claude Code 同）：合法的长命令（大 build、长跑测试）会被默认期限杀掉，
+ * 模型必须自己传更大的 timeout（上限 10min），或者用 env 抬高默认值。
+ *
+ * **对标审计（对 v2.1.268 二进制逐项核过，别凭文档印象怀疑下面的数值）**：
+ * Claude Code 的 env 白名单里只有三个 `BASH_*` 是它自己的 —— `BASH_DEFAULT_TIMEOUT_MS` /
+ * `BASH_MAX_TIMEOUT_MS` / `BASH_MAX_OUTPUT_LENGTH`（其余 `BASH_ARGC` / `BASH_SOURCE` 等
+ * 都是 bash 自身的内部变量）。前两个就是上面那两个，已对齐；第三个**不采**：它只
+ * 控制输出回读窗口（官方原文 "on its own only sizes the read-back window"），而 pi 的
+ * 截断是“保留最后 2000 行 / 50KB + 全文写临时文件”，两者机制不同且 pi 的
+ * `DEFAULT_MAX_LINES` / `DEFAULT_MAX_BYTES` 是模块常量、扩展改不了。
+ * 已知差异（刻意的，不要“顺手对齐”）：
+ *   ① **单位**：Claude Code 的 timeout 参数是 ms，pi 是秒 —— 所以 env 读 ms、内部除 1000，
+ *     工具描述也用秒（不改 pi 的参数单位，否则会跟它自己的 schema 矛盾）。
+ *   ② **非法值**：Claude Code 的 `z || Xe()` 会把**负数**原样透传（负数是 truthy），
+ *     我们则把 `<=0` / 非有限值一律归到默认 —— 因为 pi 的 `resolveTimeoutMs` 对 `<=0`
+ *     会直接 throw，不归就会把工具调用变成硬报错。NaN 两边行为一致（都落默认）。
+ *   ③ **超时语义**：pi 是 throw（tool result 带 isError=true）+ 已积累输出，
+ *     Claude Code 是普通结果 + 超时注释 —— 改不了（throw 发生在 `base.execute` 内部）。
+ *   ④ Claude Code 的第 2/3 层（`run_in_background` + `BashOutput`/`KillShell`（新名
+ *     `TaskOutput`/`TaskStop`）+ `/bashes` + Ctrl+B，以及 `CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS`
+ *     到点不杀、自动转后台）**未实现**：pi 没有对应物，要做得新增三个工具 + 进程登记表。
+ *   ⑤ pi 自己的硬上限 `MAX_TIMEOUT_MS = 2_147_483_647`（≈24.8 天）远高于我们 clamp 的
+ *     600s，所以不会撞上 pi 的报错。
+ */
+const CLAUDE_CODE_DEFAULT_TIMEOUT_MS = 120_000;
+const CLAUDE_CODE_MAX_TIMEOUT_MS = 600_000;
+
+/** 读 env 里的毫秒值；非正数/非数字一律当未配置（与 Claude Code 的 `!isNaN(r)&&r>0` 一致）。 */
+function readTimeoutEnvMs(name: string): number | undefined {
+	const raw = process.env[name]?.trim();
+	if (!raw) return undefined;
+	const value = Number(raw);
+	return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/** 默认期限（秒）。 */
+function defaultTimeoutSeconds(): number {
+	return (readTimeoutEnvMs("BASH_DEFAULT_TIMEOUT_MS") ?? CLAUDE_CODE_DEFAULT_TIMEOUT_MS) / 1000;
+}
+
+/** 期限上限（秒）：Claude Code 是 `Math.max(配置上限, 默认)`，抬高默认时上限跟着抬。 */
+function maxTimeoutSeconds(): number {
+	return Math.max(readTimeoutEnvMs("BASH_MAX_TIMEOUT_MS") ?? CLAUDE_CODE_MAX_TIMEOUT_MS, readTimeoutEnvMs("BASH_DEFAULT_TIMEOUT_MS") ?? CLAUDE_CODE_DEFAULT_TIMEOUT_MS) / 1000;
+}
+
+/**
+ * 算出这次执行的**有效期限（秒）**，即 Claude Code 那句 `Math.min(z || default, max)`：
+ *   - 模型没传 / 传了非法值（0、负数、NaN、字符串）→ 落到默认期限；
+ *   - 传了超过上限的值 → **静默 clamp 到上限**（不报错；Claude Code 同款行为，
+ *     它这个静默 clamp 是已知 issue #83824，这里照抄以保持两边一致）。
+ * 顺带避开 pi 的硬报错：内置 resolveTimeoutMs 对 <=0 / 非有限值会直接 throw。
+ */
+function effectiveTimeoutSeconds(requested: unknown): number {
+	const max = maxTimeoutSeconds();
+	const requestedSeconds = typeof requested === "number" ? requested : Number(requested);
+	if (!Number.isFinite(requestedSeconds) || requestedSeconds <= 0) return Math.min(defaultTimeoutSeconds(), max);
+	return Math.min(requestedSeconds, max);
+}
+
+/** CJK 等全角字符按 2 列宽度计，保证截出来的行数贴近终端实际行数。 */
+function charWidth(code: number): number {
+	if (
+		(code >= 0x1100 && code <= 0x115f) ||
+		(code >= 0x2e80 && code <= 0xa4cf) ||
+		(code >= 0xac00 && code <= 0xd7a3) ||
+		(code >= 0xf900 && code <= 0xfaff) ||
+		(code >= 0xfe30 && code <= 0xfe6f) ||
+		(code >= 0xff00 && code <= 0xff60) ||
+		(code >= 0xffe0 && code <= 0xffe6) ||
+		code >= 0x20000
+	) {
+		return 2;
+	}
+	return 1;
+}
+
+/** token 估算：宽字符（中日韩等）≈ 1 token/字，其余 ≈ 1 token/4 字符。 */
+function estimateTokens(text: string): number {
+	let wide = 0;
+	let narrow = 0;
+	for (const ch of text) {
+		if (charWidth(ch.codePointAt(0) ?? 0) === 2) wide++;
+		else narrow++;
+	}
+	return Math.max(1, Math.ceil(wide + narrow / 4));
+}
+
+/** 1234 → "1.2k"，避免提示行里出现五位数。 */
+function formatCount(n: number): string {
+	if (n < 1000) return String(n);
+	const k = n / 1000;
+	const text = k >= 10 ? k.toFixed(0) : k.toFixed(1);
+	return `${text.replace(/\.0$/, "")}k`;
+}
+
+/** grapheme 分段器（pi-tui 没导出它自己的实例，所以本地建一个；Node 内置 Intl.Segmenter）。 */
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** 一条折行碎片：`text` 是碎片本身，`start`/`end` 是它在**折行前原文**里的字符偏移。 */
+interface WrappedRow {
+	text: string;
+	start: number;
+	end: number;
+}
+
+/**
+ * **break-all 硬折行**（带偏移）：按列预算逐个 grapheme 填充，装满就断 —— 类似 CSS 的
+ * `word-break: break-all`，不管断点是不是单词/路径中间。除了碎片文本还记下它在原文里
+ * 的 `[start, end)` 字符区间，命令高亮靠它把「先折行、后上色」接起来 —— token 偏移是
+ * **源行**坐标、碎片是**折行后**坐标，没有这个区间就对不上号。
+ *
+ * 为什么不用 pi-tui 的 `wrapTextWithAnsi`：它是**贪心词折行 + 长词按列断开**，
+ * 一个装不进当前行剩余空间的词会被**整块挑到下一行**再去断 —— 实测 79 列终端上
+ * `$ cp <78 列路径>` 渲染成 `$ cp` 单独一行 + 路径从中间断成两截，行尾白白空着
+ * 几十列，命令和它的参数还被拆开。硬折行则把每行填到恰好装不下为止，断点就在
+ * 行末，不会提前折行。
+ *
+ * 按 grapheme 而不是按列硬切：emoji / 组合字符的 segment 长度 ≠ 1 个字符，
+ * 按字符下标切会把它们切成两半。宽字符（CJK 等，2 列）装不进剩下的 1 列时
+ * 在它**前面**断行（行尾留 1 列空白）—— 一个 grapheme 不可分。
+ *
+ * @param firstRowBudget 首行预算（给 timeout 后缀留位置）
+ * @param restRowBudget  其余行预算
+ */
+function hardWrapRows(text: string, firstRowBudget: number, restRowBudget: number): WrappedRow[] {
+	const rows: WrappedRow[] = [];
+	let row = "";
+	let rowWidth = 0;
+	let rowStart = 0;
+	let budget = Math.max(1, firstRowBudget);
+	for (const { segment, index } of graphemeSegmenter.segment(text)) {
+		const w = visibleWidth(segment);
+		// rowWidth > 0 守卫：单个 grapheme 比整行预算还宽时（极窄终端）也得放下，
+		// 否则会产生空行死循环
+		if (rowWidth > 0 && rowWidth + w > budget) {
+			rows.push({ text: row, start: rowStart, end: index });
+			budget = Math.max(1, restRowBudget);
+			row = segment;
+			rowWidth = w;
+			rowStart = index;
+		} else {
+			// row 为空说明这是本行第一个 grapheme，记下它的原文偏移
+			if (row === "") rowStart = index;
+			row += segment;
+			rowWidth += w;
+		}
+	}
+	rows.push({ text: row, start: rowStart, end: rowStart + row.length });
+	return rows;
+}
+
+/* -------------------------------------------------------------------------- *
+ * bash 命令语法高亮（见文件头「bash 命令语法高亮（轻量版）」一节）
+ * -------------------------------------------------------------------------- */
+
+type ShellTokenKind = "space" | "comment" | "operator" | "command" | "flag" | "string" | "path" | "variable" | "word";
+
+/** 一个词法单元；`start`/`end` 是**源行内**的字符偏移（不含 `$ ` 前缀）。 */
+interface ShellToken {
+	kind: ShellTokenKind;
+	start: number;
+	end: number;
+}
+
+/** token → 主题色槽。`null` = 不上色（空白原样输出）。 */
+const SHELL_TOKEN_COLORS: Record<ShellTokenKind, ThemeColor | null> = {
+	space: null,
+	comment: "syntaxComment",
+	operator: "syntaxOperator",
+	command: "syntaxFunction",
+	flag: "syntaxKeyword",
+	string: "syntaxString",
+	path: "syntaxString",
+	variable: "syntaxVariable",
+	word: "syntaxString",
+};
+
+/** `$VAR` / `${VAR}`。 */
+const SHELL_VAR_PATTERN = /\$\{?[A-Za-z_][A-Za-z0-9_]*\}?/;
+/** 赋值：`NAME=`。 */
+const SHELL_ASSIGN_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+ * 操作符，**先长后短**按顺序取第一个匹配。重定向那条带可选的数字 fd，所以
+ * `2>&1` 会被切成 `2>&`（操作符）+ `1`（词）而不是把 `2` 当成参数。
+ */
+const SHELL_OPERATOR_PATTERNS = [/^&&/, /^\|\|/, /^\|&/, /^;;/, /^<<-?/, /^\d*(?:>>|>&|<&|<|>)/, /^[|&;()]/];
+/** 能起头的操作符字符（粗筛用，避免对每个字符都跑一遍正则 —— 长命令行下是 O(n²)）。 */
+const SHELL_OPERATOR_CHARS = new Set(["|", "&", ";", "(", ")", "<", ">"]);
+/** 这些操作符后面接的是新命令（`cmd1 | cmd2`），其余（重定向等）后面接的是参数。 */
+const SHELL_COMMAND_NEXT_OPS = new Set(["|", "||", "&&", ";", "&", "|&", "("]);
+
+function stripOuterQuotes(word: string): string {
+	const match = /^(['"])([\s\S]*)\1$/.exec(word);
+	return match ? match[2]! : word;
+}
+
+/** 纯数字后面紧跟 `<`/`>` 才是 fd 重定向（`2>`）；否则 `foo2` 里的 `2` 属于词。 */
+function isFdRedirectAt(line: string, pos: number): boolean {
+	let j = pos;
+	while (j < line.length && line[j]! >= "0" && line[j]! <= "9") j++;
+	const next = line[j];
+	return next === "<" || next === ">";
+}
+
+/** 在 `pos` 处匹配一个操作符；不是操作符返回 null。 */
+function matchShellOperatorAt(line: string, pos: number): string | null {
+	const char = line[pos]!;
+	if (!SHELL_OPERATOR_CHARS.has(char) && !(char >= "0" && char <= "9")) return null;
+	const rest = line.slice(pos);
+	for (const pattern of SHELL_OPERATOR_PATTERNS) {
+		const match = pattern.exec(rest);
+		if (match) return match[0];
+	}
+	return null;
+}
+
+/**
+ * 词的归类。顺序有意义：赋值 > 引号串 > 选项 > `$VAR` > 路径 > 命令/参数。
+ * `"--foo"` 算引号串而不是选项；`$HOME/x` 算变量而不是路径（`$` 优先）。
+ */
+function classifyShellWord(word: string, commandExpected: boolean): ShellTokenKind {
+	const normalized = stripOuterQuotes(word);
+	if (SHELL_ASSIGN_PATTERN.test(normalized)) return "variable";
+	if (word.startsWith("'") || word.startsWith('"')) return "string";
+	if (word.startsWith("-") && word.length > 1) return "flag";
+	if (SHELL_VAR_PATTERN.test(normalized)) return "variable";
+	// 含 `/` 就是路径；额外的分支覆盖裸的 `.` / `..` / `~`
+	if (normalized.includes("/") || /^\.{1,2}(?:\/|$)/.test(normalized) || normalized.startsWith("~/")) return "path";
+	return commandExpected ? "command" : "word";
+}
+
+/**
+ * 给一条源行分词。token **连续覆盖整行**（含空白 token），所以折行碎片可以直接按
+ * 偏移切片上色，不用再去猜碎片和 token 的对应关系。
+ *
+ * `openQuote` 是上一条源行留下的未闭合引号：多行字符串的第二行整段算 string，
+ * 不会被当成一条新命令重新分词。分词**不会失败**（不像参照插件那样返回 undefined
+ * 退回 highlightCode）—— 引号没闭合就一路吃到行尾并把状态传给下一条源行。
+ */
+function tokenizeShellLine(line: string, openQuote: string | null): { tokens: ShellToken[]; openQuote: string | null } {
+	const tokens: ShellToken[] = [];
+	let quote = openQuote;
+	let commandExpected = true;
+	let i = 0;
+
+	while (i < line.length) {
+		const char = line[i]!;
+
+		// 跨行未闭合的引号：吃到本行的闭合引号为止，没有闭合就吃掉整行尾巴
+		if (quote) {
+			let j = i;
+			while (j < line.length) {
+				const c = line[j]!;
+				if (c === "\\" && quote === '"' && j + 1 < line.length) {
+					j += 2;
+					continue;
+				}
+				if (c === quote) break;
+				j++;
+			}
+			if (j >= line.length) {
+				tokens.push({ kind: "string", start: i, end: line.length });
+				i = line.length;
+				continue;
+			}
+			tokens.push({ kind: "string", start: i, end: j + 1 });
+			i = j + 1;
+			quote = null;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			let j = i;
+			while (j < line.length && /\s/.test(line[j]!)) j++;
+			tokens.push({ kind: "space", start: i, end: j });
+			i = j;
+			continue;
+		}
+
+		// `#` 只在**词首**才是注释（`foo#bar` 里的 `#` 是普通字符）
+		if (char === "#") {
+			tokens.push({ kind: "comment", start: i, end: line.length });
+			i = line.length;
+			continue;
+		}
+
+		const operator = matchShellOperatorAt(line, i);
+		if (operator !== null) {
+			tokens.push({ kind: "operator", start: i, end: i + operator.length });
+			commandExpected = SHELL_COMMAND_NEXT_OPS.has(operator);
+			i += operator.length;
+			continue;
+		}
+
+		// 词：吃到空白 / 操作符 / 行尾为止，中途遇到引号就连引号一起吞
+		let j = i;
+		let wordQuote: string | null = null;
+		while (j < line.length) {
+			const c = line[j]!;
+			if (wordQuote) {
+				if (c === "\\" && wordQuote === '"' && j + 1 < line.length) {
+					j += 2;
+					continue;
+				}
+				if (c === wordQuote) wordQuote = null;
+				j++;
+				continue;
+			}
+			if (/\s/.test(c)) break;
+			if (c === "'" || c === '"') {
+				wordQuote = c;
+				j++;
+				continue;
+			}
+			if (SHELL_OPERATOR_CHARS.has(c)) break;
+			if (c >= "0" && c <= "9" && isFdRedirectAt(line, j)) break;
+			j++;
+		}
+		const word = line.slice(i, j);
+		tokens.push({ kind: classifyShellWord(word, commandExpected), start: i, end: j });
+		// 赋值前缀（`FOO=bar cmd`）后面仍然跟的是命令，其余词都把「该出命令了」清掉
+		if (!SHELL_ASSIGN_PATTERN.test(stripOuterQuotes(word))) commandExpected = false;
+		i = j;
+		if (wordQuote) quote = wordQuote; // 引号没闭合 → 传给下一条源行
+	}
+
+	return { tokens, openQuote: quote };
+}
+
+/**
+ * 给一条折行碎片上色。`prefix` 是这条源行在折行文本里的前缀（第一条源行是 `$ `，
+ * 其余为空），`line` 是**不含前缀**的源行原文 —— token 偏移就是按它算的。
+ * `tokens` 为 null（高亮关掉）时退回改动前的整行单色粗体 —— 连 `$ ` 也一起粗体，
+ * 逐字符和改动前一致。
+ */
+function styleWrappedRow(row: WrappedRow, prefix: string, line: string, tokens: ShellToken[] | null, theme: any): string {
+	if (!tokens) return theme.fg("toolTitle", theme.bold(row.text));
+	// `$ ` 前缀不参与分词（否则裸 `$` 会被当成命令名上色），单独用正常色 `toolTitle`
+	const prefixEnd = Math.min(row.end, prefix.length);
+	let out = row.start < prefixEnd ? theme.fg("toolTitle", row.text.slice(0, prefixEnd - row.start)) : "";
+	const from = Math.max(0, row.start - prefix.length);
+	const to = Math.max(from, row.end - prefix.length);
+	if (to <= from) return out;
+
+	let cursor = from;
+	for (const token of tokens) {
+		if (token.end <= from) continue;
+		if (token.start >= to) break;
+		const start = Math.max(token.start, cursor);
+		const end = Math.min(token.end, to);
+		if (start >= end) continue;
+		const text = line.slice(start, end);
+		const color = SHELL_TOKEN_COLORS[token.kind];
+		// 命令名保留粗体，当作整块的视觉锚点（改动前整行都是粗体）
+		out += color === null ? text : theme.fg(color, token.kind === "command" ? theme.bold(text) : text);
+		cursor = end;
+	}
+	// token 连续覆盖整行，所以正常走不到这里；真走到就按老样子兜底，不丢字符
+	if (cursor < to) out += theme.fg("toolTitle", theme.bold(line.slice(cursor, to)));
+	return out;
+}
+
+/**
+ * 一条源行 → 折行碎片（带偏移）+ 该行的 token。高亮关掉时不分词，`nextQuote` 原样
+ * 透传（此时引号状态没有意义）。
+ */
+function wrapAndTokenizeLine(
+	prefix: string,
+	line: string,
+	firstRowBudget: number,
+	restRowBudget: number,
+	openQuote: string | null,
+	highlight: boolean,
+): { rows: WrappedRow[]; tokens: ShellToken[] | null; nextQuote: string | null } {
+	const rows = hardWrapRows(prefix + line, firstRowBudget, restRowBudget);
+	if (!highlight) return { rows, tokens: null, nextQuote: openQuote };
+	const result = tokenizeShellLine(line, openQuote);
+	return { rows, tokens: result.tokens, nextQuote: result.openQuote };
+}
+
+/** pi 的 agent 目录（`PI_CODING_AGENT_DIR` 可覆盖，否则 `~/.pi/agent`）。 */
+function resolveAgentDir(): string {
+	const envDir = process.env.PI_CODING_AGENT_DIR;
+	return envDir ? (envDir.startsWith("~") ? join(homedir(), envDir.slice(1)) : envDir) : join(homedir(), ".pi", "agent");
+}
+
+/**
+ * `app.tools.expand` 的键名文本，给自建的提示行用。
+ *
+ * 为什么不直接用 pi 导出的 `keyText` / `keyHint`：扩展里 `import` 到的
+ * `@earendil-works/pi-coding-agent` / `pi-tui` 是 loader alias 指向的 **npm/dist 副本**，
+ * 与 pi 运行时（bundle）用的是两个不同的模块实例。实测（在 `~/.pi/agent/npm` 下直接
+ * `node` 跑）：`keyHint("app.tools.expand", "to expand")` **直接抛**
+ * `Theme not initialized. Call initTheme() first.`（它读的是副本自己的 theme 单例，
+ * 而 pi 只初始化了 bundle 那份），`keyText(...)` 则返回 `""`（副本的 keybindings
+ * 表是空的）。而 renderResult 抛异常会被 pi 静默 catch 并退回 `createResultFallback()`，
+ * 整个自定义渲染就没了 —— 所以这两个函数绝不能 import，只能读配置文件。
+ *
+ * 默认值 `ctrl+o` 就是 pi 的默认绑定（`docs/keybindings.md` 的 `app.tools.expand` 行）。
+ */
+function expandKeyText(): string {
+	try {
+		const parsed = JSON.parse(readFileSync(join(resolveAgentDir(), "keybindings.json"), "utf8"));
+		const bound = parsed?.["app.tools.expand"];
+		const keys = Array.isArray(bound) ? bound : [bound];
+		const text = keys.filter((k: unknown): k is string => typeof k === "string" && k.trim() !== "").join("/");
+		if (text) return text;
+	} catch {
+		// 没配置文件 / 解析失败 / 没绑这个键，都用默认值
+	}
+	return "ctrl+o";
+}
+
+/**
+ * 归一耗时页脚门槛（毫秒）：未设置 / 空串 / 非法值（NaN、负数）一律落到默认 2000；
+ * **`0` 是合法值**（永远显示，等于关掉这个优化）—— 所以不能用 `value || DEFAULT` 那种写法。
+ * 与 `clampPreviewLines` 一样在扩展注册时读一次。
+ */
+function resolveMinTimeFooterMs(raw: string | undefined): number {
+	if (raw === undefined || raw.trim() === "") return DEFAULT_MIN_TIME_FOOTER_MS;
+	const value = Number(raw.trim());
+	return Number.isFinite(value) && value >= 0 ? value : DEFAULT_MIN_TIME_FOOTER_MS;
+}
+
+/**
+ * 把输出预览行数归一到 1-50 的整数；非法值（NaN / <=0 / 小数）一律落到默认 3。
+ * 刻意用 Number 而不是 parseInt：parseInt("2.5") 会静默变成 2，而这里是归一到默认。
+ */
+function clampPreviewLines(value: number): number {
+	if (!Number.isFinite(value) || value < 1 || value > 50 || !Number.isInteger(value)) return DEFAULT_OUTPUT_PREVIEW_LINES;
+	return value;
+}
+
+/**
+ * 读 shellPath / shellCommandPrefix 设置，让覆盖后的 bash 工具和内置工具行为一致
+ * （内置工具由 AgentSession 用 settings 里的这两个值构造）。
+ */
+function readShellOptions(): BashToolOptions {
+	const paths = [join(resolveAgentDir(), "settings.json"), join(process.cwd(), ".pi", "settings.json")];
+
+	const merged: Record<string, unknown> = {};
+	for (const path of paths) {
+		try {
+			const parsed = JSON.parse(readFileSync(path, "utf8"));
+			if (parsed && typeof parsed === "object") Object.assign(merged, parsed);
+		} catch {
+			// 缺文件 / 解析失败都按默认值处理
+		}
+	}
+
+	const options: BashToolOptions = {};
+	if (typeof merged.shellPath === "string" && merged.shellPath) {
+		options.shellPath = merged.shellPath.startsWith("~") ? join(homedir(), merged.shellPath.slice(1)) : merged.shellPath;
+	}
+	if (typeof merged.shellCommandPrefix === "string") {
+		options.commandPrefix = merged.shellCommandPrefix;
+	}
+	return options;
+}
+
+/**
+ * 剥掉组件渲染结果的前导空行。
+ *
+ * 内置 bash 的 renderResult 会在输出前插一个前导空行（`new Text("\n" + styledOutput)`），
+ * 在默认 shell 下那是“命令与输出之间的一行间距”；但本扩展走 self 模式，命令与输出是
+ * 两个独立的块，这一行会叠上两个 Box 各自的 paddingY，变成三行空白（实测）。
+ * 先判 ANSI 再 trim：行里可能带前景色转义序列，直接 trim() 不会为空。
+ * 只剥**前导**空行：输出与 "Took" 之间那个空行（也是 `\n` 前缀）刻意保留，
+ * 用来分隔正文与耗时页脚。
+ */
+function stripLeadingBlanks(inner: any) {
+	return {
+		render(width: number): string[] {
+			const lines: string[] = inner.render(width);
+			let i = 0;
+			while (i < lines.length && lines[i].replace(/\x1b\[[0-9;]*m/g, "").trim() === "") i++;
+			return i > 0 ? lines.slice(i) : lines;
+		},
+		invalidate() {
+			inner.invalidate?.();
+		},
+	};
+}
+
+/**
+ * 给染色块补一行**下边界**空行（染底色的空行，见文件头「染色块的上下边界空行」）。
+ * 空行是作为子组件的行加进去的，所以会走 Box.applyBg —— 补满到 width 再上色，
+ * 与 paddingY 画出来的边界行完全同色同宽。
+ */
+function withBottomBlank(inner: any) {
+	return {
+		render(width: number): string[] {
+			return [...inner.render(width), ""];
+		},
+		invalidate() {
+			inner.invalidate?.();
+		},
+	};
+}
+
+/**
+ * 树形 gutter 占的列数（`│ ` / `└ ` = 1 个制表符（box-drawing 竖线 / 拐角，不是 TAB）+ 1 个空格）。
+ * 输出子组件必须按 `width - GUTTER_WIDTH` 渲染，否则加上前缀就超宽。
+ */
+const GUTTER_WIDTH = 2;
+
+/**
+ * 给输出行画**树形 gutter**：除末行外每行前面挂 `│ `，末行挂 `└ `（对齐 codex
+ * 的 bash 输出样式），让输出与命令行之间的层次关系一眼可辨。
+ *
+ * 三个不能想当然的点：
+ *   ① **前导空行不上前缀**：那是命令与输出之间的分隔行，外层
+ *     `stripLeadingBlanks` 还要靠「这一行是空的」把它剥掉 —— 一旦挂上前缀
+ *     就变成非空行，剥不掉了（行里还可能带前景色转义序列，所以判空必须先剔
+ *     ANSI 再 trim，跟 `stripLeadingBlanks` 的判法一致）。
+ *   ② `└` 挂在**最后一个非空行**上而不是数组末行：pi 的输出是 `.trim()` 过的，
+ *     正常不会有尾部空行，但万一有，`└ ` 挂在空行上会变成一行只有拐角符。
+ *     尾部空行照旧挂 `│ `，竖线保持连续。
+ *   ③ 输出**内部的空行也要挂 `│`**（只跳前导那一段），否则竖线断在半路，
+ *     看上去不像一棵树。
+ * 全是空行时直接原样返回（没内容可挂）。
+ */
+function prefixTreeLines(lines: string[], theme: any, gutter: boolean): string[] {
+	if (!gutter || lines.length === 0) return lines;
+	const isBlank = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "").trim() === "";
+	let start = 0;
+	while (start < lines.length && isBlank(lines[start])) start++;
+	if (start >= lines.length) return lines;
+	let last = lines.length - 1;
+	while (last > start && isBlank(lines[last])) last--;
+	return lines.map((line, i) => (i < start ? line : theme.fg("muted", i === last ? "└ " : "│ ") + line));
+}
+
+/**
+ * 耗时页脚的**纯文本形态**：`Took 0.1s`（执行完）/ `Elapsed 1.2s`（流式执行中，每秒跳）。
+ * 小数位数由 pi 的 `formatDuration` 决定（`(ms / 1000).toFixed(1)`，恒为一位）。
+ */
+const TIME_FOOTER_PATTERN = /^(?:Took|Elapsed) \d+\.\d+s$/;
+
+/** 去掉 SGR 转义序列（页脚那行是 `theme.fg("muted", …)` 包着的，判形态 / 判空都得先剥）。 */
+function stripAnsiCodes(text: string): string {
+	return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * 这个 child 是不是 pi 画的**耗时页脚**（`new Text("\n" + theme.fg("muted", "Took 0.1s"), 0, 0)`）。
+ *
+ * 两条缺一不可：
+ *   ① `setText` 存在 = 是 pi-tui 的 `Text` —— 不能用 `instanceof`，理由与预览组件那条鸭子
+ *      判定完全相同（扩展 import 到的 pi-tui 是 loader alias 指向的 npm/dist 副本，与 pi
+ *      运行时 bundle 里的 `Text` 不是同一个类对象，`instanceof` 跨实例必然 false）；
+ *   ② 剥 ANSI、trim 之后正好是 `Took 0.1s` / `Elapsed 1.2s` 这个形态。
+ * 位置条件（**必须是末位 child**）由 `shouldHideTimeFooter` 带着判：pi 的
+ * `rebuildBashResultRenderComponent` 按「输出 → warnings → 页脚」的顺序 addChild，
+ * 所以页脚恒为末位。两条一起才敢下结论说末位那个就是页脚 —— 只看末位会把「输出正文恰好
+ * 是一行 `Took 1.2s`」删掉（展开态下正文就是一个 `Text`），只看形态则会把碰巧长得像的
+ * 末位子组件删掉。
+ */
+function isTimeFooterChild(child: any): boolean {
+	if (typeof child?.setText !== "function" || typeof child.text !== "string") return false;
+	return TIME_FOOTER_PATTERN.test(stripAnsiCodes(child.text).trim());
+}
+
+/**
+ * 该不该把耗时页脚整个丢掉：**短于门槛的执行不画那一行**（默认 2000ms，见
+ * `DEFAULT_MIN_TIME_FOOTER_MS`）。
+ *
+ * `elapsedMs === undefined` 表示压根不知道耗时（`state.startedAt` 为空 —— `/resume` 恢复的
+ * 历史块不调 `markExecutionStarted`）—— 那种情况下 pi 本来就没有页脚可画，所以一律返回
+ * false、不动手：即展开态里「输出正文恰好是一行 `Took 1.2s`」不会被误删。
+ * 门槛与耗时比的是**同一个量**（`endedAt - startedAt`，见 renderResult 里的 `elapsedMs`），
+ * 不是页脚上那个四舍五入后的数字。
+ */
+function shouldHideTimeFooter(lastChild: any, elapsedMs: number | undefined, minTimeFooterMs: number): boolean {
+	if (elapsedMs === undefined || elapsedMs >= minTimeFooterMs) return false;
+	return isTimeFooterChild(lastChild);
+}
+
+/**
+ * 把 pi 内置 bash 渲染器的**输出预览**从 5 行裁到 `previewLines` 行，给输出
+ * 挂上树形 gutter（`gutter` 为 true 时），并在短命令上丢掉耗时页脚。
+ *
+ * pi 的行数写死在它的 `BASH_PREVIEW_LINES = 5`（模块私有常量，改不了，也没有
+ * 设置项），所以只能在拿到它的组件之后做后处理。详见文件头「输出预览行数」一节。
+ *
+ * 做法：**逐个 child 渲染**而不是拿整个 Container 的平铺行数组 —— 平铺数组里分不清
+ * 哪几行属于预览（预览行、warnings 行、Took 行都是纯文本 + 不同前景色，按颜色猜很
+ * 脆弱）。child 结构实测过：输出非空时 `children[0]` 就是预览组件，行形状固定是
+ * `["", (提示行?), ...预览行]`；后面的 warnings / `Took Xs` 都是 `Text` 实例
+ *（各自的 `\n` 前缀渲染成一行空行 + 正文）。
+ *
+ * 预览组件的判定用**鸭子类型**（`typeof child.setText !== "function"`）而不是
+ * `instanceof Text`：扩展 import 到的 pi-tui 是 loader alias 指向的 npm/dist 副本，
+ * 与 pi 运行时（bundle）用的 Text 不是同一个类对象，`instanceof` 跨模块实例必然 false。
+ *
+ * **展开态（ctrl+o）自动不受影响**：那时 pi 用的是 `new Text("\n" + styledOutput)`
+ * 而不是预览组件，所以鸭子判定直接跳过它，完整输出一行不裁、**也不挂 gutter**
+ * （展开态要的就是原样输出）—— 正是想要的。
+ *
+ * 耗时页脚的过滤（`shouldHideTimeFooter`）也在这里：末位 child 是 `Took X.Xs` 页脚、
+ * 且实际耗时短于门槛时，把它整个跳过（连它那行前导空行一起 —— 那是正文与页脚之间的
+ * 分隔行，页脚不画时不该留）。详见文件头「耗时页脚门槛」一节。
+ */
+function withPreviewLimit(inner: any, previewLines: number, theme: any, gutter: boolean, elapsedMs: () => number | undefined, minTimeFooterMs: number) {
+	return {
+		render(width: number): string[] {
+			const out: string[] = [];
+			let trimmed = false;
+			// gutter 占 2 列，所以**输出子组件必须按 width - 2 渲染**：pi 的预览行是按
+			// 传进去的宽度折行 / 截断的（`truncateToVisualLines` 内部用 `Text.render(width)`），
+			// 按整宽渲染再加前缀就会超出终端宽度。其余子组件（warnings / Took）不上
+			// 前缀，照旧按整宽渲染。
+			const contentWidth = gutter ? Math.max(1, width - GUTTER_WIDTH) : width;
+			// 耗时页脚的判定放在 render 里而不是拿组件时就算死：流式模式下 pi 每秒
+			// `invalidate()` 一次（内置 renderResult 里那个 setInterval），跨过门槛的
+			// 那一刻页脚就能出现，不用等下一次 partial 结果。
+			let children: any[] = inner.children ?? [];
+			if (shouldHideTimeFooter(children[children.length - 1], elapsedMs(), minTimeFooterMs)) {
+				children = children.slice(0, -1);
+			}
+			for (const child of children) {
+				const isOutput = !trimmed && typeof child.setText !== "function";
+				const lines: string[] = child.render(isOutput ? contentWidth : width);
+				if (!isOutput) {
+					out.push(...lines);
+					continue;
+				}
+				trimmed = true;
+				out.push(...prefixTreeLines(trimPreviewLines(lines, previewLines, contentWidth, theme), theme, gutter));
+			}
+			return out;
+		},
+		invalidate() {
+			inner.invalidate?.();
+		},
+	};
+}
+
+/**
+ * 裁掉预览行里超出预算的部分（保留**尾部** —— pi 的预览本来就是输出的最后几行），
+ * 并把被裁掉的行数补进提示行的计数。
+ *
+ * 提示行的两种情况：
+ *   ① pi 已经给了提示行（输出 > 5 行）—— 就在它那一行**原地改数字**，
+ *     这样 pi 的配色与真实键名（`keyHint` 渲出来的 dim 键名 + muted 描述）一字不动，
+ *     不用重建样式。正则匹配的是 SGR 包裹里的纯 ASCII 数字与文本，所以直接在
+ *     带样式的字符串上替换是安全的。
+ *   ② pi 没给提示行（输出刚好 ≤ 5 行，但我们裁到了 3 行）—— 必须自己造一行，
+ *     否则那 1~2 行就**静默消失**了。用传进来的 `theme`（pi 运行时真正初始化过的那份）
+ *     复刻 pi 的格式与配色，键名读 `keybindings.json`（见 `expandKeyText`）。
+ */
+function trimPreviewLines(lines: string[], previewLines: number, width: number, theme: any): string[] {
+	if (lines.length <= 1) return lines;
+	const head = lines[0]; // 前导空行（去留由外层 stripLeadingBlanks 决定）
+	let rest = lines.slice(1);
+	let hintLine: string | undefined;
+	const firstPlain = (rest[0] ?? "").replace(/\x1b\[[0-9;]*m/g, "");
+	if (firstPlain.startsWith("... (") && firstPlain.includes("earlier lines")) {
+		hintLine = rest[0];
+		rest = rest.slice(1);
+	}
+	if (rest.length <= previewLines) return lines;
+	const dropped = rest.length - previewLines;
+	const kept = rest.slice(dropped);
+	const hint = hintLine
+		? hintLine.replace(/(\(\s*)(\d+)(\s*earlier lines)/, (_m, open, count, tail) => `${open}${Number(count) + dropped}${tail}`)
+		: truncateToWidth(
+				theme.fg("muted", `... (${dropped} earlier lines,`) + " " + theme.fg("dim", expandKeyText()) + theme.fg("muted", " to expand") + theme.fg("muted", ")"),
+				width,
+				"...",
+			);
+	return [head, hint, ...kept];
+}
+
+/**
+ * 按执行状态选整块底色，与 tool-execution.js `updateDisplay()` 里的 bgFn 一致
+ * （pending / error / success）。默认 shell 下这个 bgFn 由 pi 套在整个 contentBox 上；
+ * 切到 `renderShell: "self"` 后 pi 不再套（selfRenderContainer 是个纯 Container），
+ * 所以得自己用 Box + theme.bg 把底色块画回来，否则 bash 输出会失去现在的背景块。
+ */
+function stateBgFn(theme: any, isPartial: boolean, isError: boolean) {
+	if (isPartial) return (text: string) => theme.bg("toolPendingBg", text);
+	if (isError) return (text: string) => theme.bg("toolErrorBg", text);
+	return (text: string) => theme.bg("toolSuccessBg", text);
+}
+
+/**
+ * 在**同步窗口**内把主题的 `toolOutput` 临时换成 `bashOutput`，让 pi 内置 bash 结果渲染器
+ * 画出来的输出正文用上自己的颜色槽（详见文件头「输出正文的独立颜色」一节）。
+ *
+ * 为什么必须是「换主题表」而不是「把主题对象换给渲染器」：pi 的 bash 渲染器**根本不看传进去
+ * 的那个 theme 参数**（`renderResult(result, options, _theme, context)`），它用的是模块级的
+ * `theme` 单例（`Proxy` → `globalThis[Symbol.for("@earendil-works/pi-coding-agent:theme")]`）。
+ * 那个单例与传给扩展的渲染器参数**是同一个对象**（单例就是为跨 loader 共用而设计的），
+ * 所以直接改它的 `fgColors` 表，渲染器下一次 `theme.fg("toolOutput", line)` 就会命中新色值。
+ *
+ * 四个要点：
+ *   ① **只在同步窗口内换**：`base.renderResult()` 是同步的，输出行（含展开态那份）全部在
+ *      这次调用里 `theme.fg("toolOutput", …)` 烘焙成字符串，所以 try/finally 里换进换出
+ *      不会有第二个渲染插进来；换颜色也**不会**泄漏给其他工具（read / grep 的输出是它们
+ *      自己的渲染器画的，不在这个窗口里）。
+ *   ② **主题里没有 `bashOutput` 就什么都不做**（内置主题与 summer-night / catppuccin 都没
+ *      这个 token）—— 探测方式是真调一次 `theme.getFgAnsi()`，pi 对未知 token 抛
+ *      `Unknown theme color: …`。
+ *   ③ `fgColors` 是 pi `Theme` 类的公开字段（`Map<string, string>`，存的是**已解析的
+ *      SGR 前缀**）；哪天 pi 把它藏起来/改名，这里就自动退化成原样调用（返回前那个
+ *      `typeof … .set` 判定），不会抛异常、只是颜色不生效。
+ *   ④ 只动 `toolOutput`：命令标题 / `... (N earlier lines …)` 提示 / `Took Xs` 页脚走的是
+ *      `toolTitle` / `muted`，命令行与折叠提示是扩展自绘的，一律不受影响。
+ */
+function withBashOutputColor<T>(theme: any, render: () => T): T {
+	const fgColors = theme?.fgColors;
+	if (typeof fgColors?.set !== "function" || typeof fgColors?.get !== "function") return render();
+	let override: string;
+	try {
+		override = theme.getFgAnsi("bashOutput");
+	} catch {
+		return render();
+	}
+	const previous = fgColors.get("toolOutput");
+	fgColors.set("toolOutput", override);
+	try {
+		return render();
+	} finally {
+		if (previous === undefined) fgColors.delete("toolOutput");
+		else fgColors.set("toolOutput", previous);
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	let enabled = true;
+	let maxLines = DEFAULT_LINES;
+	// 输出预览行数：pi 内置写死 5（`BASH_PREVIEW_LINES`，模块私有常量 + 无设置项），
+	// 所以只能在扩展里后处理。/bash-preview 可改；PI_BASH_PREVIEW 启动时覆盖。
+	let previewLines = clampPreviewLines(Number(process.env.PI_BASH_PREVIEW));
+	// 输出树形 gutter（`│ ` / `└ `）：默认开（对齐 codex）。PI_BASH_TREE=off 启动时关闭。
+	// 与 previewLines 相互独立：`/bash-preview off` 恢复 pi 的 5 行预览后 gutter 照旧生效。
+	let treeEnabled = process.env.PI_BASH_TREE?.trim().toLowerCase() !== "off";
+	// 流式输出开关：默认关（非流式，对齐 opencode / codex）。PI_BASH_STREAM=on 恢复 pi 原生流式。
+	let streaming = process.env.PI_BASH_STREAM?.trim().toLowerCase() === "on";
+	// 耗时页脚门槛（毫秒）：短于它的执行不画 `Took X.Xs` 那一行（详见文件头「耗时页脚门槛」）。
+	// PI_BASH_MIN_TIME_MS=0 永远显示。与 previewLines / treeEnabled 一样在注册时读一次。
+	const minTimeFooterMs = resolveMinTimeFooterMs(process.env.PI_BASH_MIN_TIME_MS);
+	// 命令语法高亮开关：默认开。PI_BASH_HIGHLIGHT=off 启动时关闭（回到整行 toolTitle 粗体）。
+	// 刻意**不注册 /bash-highlight 指令** —— 这是个纯观感开关，env 一个入口就够，
+	// 没必要再占一条斜杠指令（与 /bash-collapse / /bash-tree 那种需要随时切换的不同）。
+	// 展开态（ctrl+o）与折叠态走同一套分词，所以开关对两边同时生效。
+	const highlightEnabled = process.env.PI_BASH_HIGHLIGHT?.trim().toLowerCase() !== "off";
+
+	// cwd 只是兜底：内置 execute 用的是 ctx.cwd（每次调用的当前 session cwd）。
+	const base: ToolDefinition<any, any, any> = createBashToolDefinition(process.cwd(), readShellOptions());
+
+	const statusText = () => `保留前 ${maxLines} 个视觉行（break-all 硬折行），超出部分显示 token 估算`;
+	const streamStatusText = () =>
+		streaming
+			? "流式（命令逐字刷、输出边跑边刷，含 Elapsed 计时）"
+			: "非流式（命令收完一次性出，结果执行完补刷到下面）";
+
+	pi.registerTool({
+		name: base.name,
+		label: base.label,
+		// 照抄 Claude Code：把默认期限和上限**写进工具描述**告诉模型，否则模型不知道
+		// 可以传 timeout，长命令就会被默认期限杀掉却不知道该调大。
+		// （内置描述结尾本来只是 "Optionally provide a timeout in seconds."，没给数字。）
+		description: `${base.description} By default, your command will time out after ${defaultTimeoutSeconds()} seconds. You may specify an optional timeout in seconds (up to ${maxTimeoutSeconds()} seconds); larger values are clamped to that maximum.`,
+		parameters: base.parameters,
+		// prompt 元数据不会从内置工具继承，必须显式带上
+		promptSnippet: base.promptSnippet,
+		promptGuidelines: base.promptGuidelines,
+		constrainedSampling: base.constrainedSampling,
+		executionMode: base.executionMode,
+		prepareArguments: base.prepareArguments,
+		// `renderShell: "self"` 是为了让“流式接命令字符时屏幕上一行都不出”成为可能。
+		// 默认 shell 下 ToolExecutionComponent 构造里常驻一个 `Spacer(1)`，而 render() 走
+		// `super.render(width)`（Container）会把所有子组件都画出来 —— 所以即使 renderCall
+		// 返回零行组件，仍会渲染出那一行空行（实测 `[""]`）。而 `hideComponent` 那条路
+		// 走不到：updateDisplay() 里只要 callRenderer 成功返回组件就把 `hasContent` 置 true，
+		// 三个分支全都置 true，所以末尾 `if (… && !hasContent …) hideComponent = true` 永远不成立。
+		// self 模式下 render() 绕过 super.render()，只画 selfRenderContainer，于是那个 Spacer
+		// 根本不会被渲染；且开头有 `contentLines.length === 0 → return []` 守卫，
+		// 真正做到“空就什么都不出”。代价是 pi 不再给整块套 bgFn，所以 renderCall /
+		// renderResult 两边都自己包一层 Box 把底色块画回来（见 stateBgFn）。
+		renderShell: "self",
+		// renderResult 委托内置 bash 的实现（输出预览 / 截断提示 / "Took Xs" 都是它画的），
+		// 只在外层包一个 Box 把底色块补回来，页脚那行则在 withPreviewLimit 里按门槛滤掉。
+		// 注意传给内置的 `lastComponent` 必须是
+		// **内层**组件而不是我们的 Box —— 内置实现会 `context.lastComponent ?? new
+		// BashResultRenderComponent()` 然后对它 clear() / addChild()，喂个 Box 进去会嵌套错乱。
+		// 所以内层组件存在 context.state 里跨次复用（state 本来就用来存 startedAt/endedAt/interval）。
+		renderResult(result, options, theme, context) {
+			const state = context.state;
+			// renderCall 靠这个标记决定要不要自己补下边界空行（结果还没到时才补）。
+			// 放在委托内置实现**之前**置位：万一内置实现抛异常，pi 会退回自己的
+			// fallback 结果组件，那时下边界已经由它那边负责了。
+			state.resultSeen = true;
+			// 输出正文换用主题的 `bashOutput` 槽（主题没定义就原样；详见 withBashOutputColor）
+			const inner = withBashOutputColor(theme, () =>
+				base.renderResult(result, options, theme, { ...context, lastComponent: state.innerComponent }),
+			);
+			state.innerComponent = inner;
+			// isError 必须从 **context** 读，不能从 result 读：pi 调 resultRenderer 时传的是
+			// `{ content: this.result.content, details: this.result.details }`，**没有 isError 字段**
+			// （tool-execution.js 的 updateDisplay），isError 只在 getRenderContext() 里
+			// （`isError: this.result?.isError ?? false`）。读 result.isError 会永远拿到 undefined，
+			// 于是失败的命令也会染成 success 底色。
+			//
+			// paddingY 必须用 0，且要剥掉 inner 的前导空行 —— 否则命令与输出之间会有
+			// **三个**空行（实测过）：① callBox 的下 padding、② resultBox 的上 padding、
+			// ③ 内置 renderResult 自己的 `new Text("\n" + styledOutput)` 前导空行。
+			// 第③行在默认 shell 下是“命令与输出之间的一行间距”（那时两者在同一个
+			// contentBox 里，只有这一行），但 self 模式下两者是两个独立的 Box，
+			// 各自的 paddingY 会叠加上去，所以这里把三者全部去掉，让输出紧贴命令。
+			// 整块的**下边界**空行则由 withBottomBlank 补回来（只补最外侧那一行，
+			// 不会落到命令与输出之间）。
+			// 耗时页脚门槛判据（见文件头「耗时页脚门槛」）：与 pi 画那行字用的是**同一个量**
+			// —— `state.endedAt ?? Date.now()` 减 `state.startedAt`（内置 renderResult 刚在上面
+			// 那次调用里补上了 endedAt）。做成**函数**、在 render 时才求值：流式模式下每秒
+			// invalidate 一次，跨过门槛的那一刻页脚自然出现，不用等下一次 partial 结果。
+			// startedAt 为空 = pi 根本没画页脚（`/resume` 恢复的历史块不调 markExecutionStarted），
+			// 这时返回 undefined，过滤逻辑一律不动手。
+			const elapsedMs = () => (state.startedAt === undefined ? undefined : (state.endedAt ?? Date.now()) - state.startedAt);
+			const box = new Box(1, 0, stateBgFn(theme, options.isPartial, context.isError === true));
+			box.addChild(
+				withBottomBlank(
+					stripLeadingBlanks(withPreviewLimit(inner, Math.max(1, Math.round(previewLines)), theme, treeEnabled, elapsedMs, minTimeFooterMs)),
+				),
+			);
+			return box;
+		},
+
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			// 关流式就是把 onUpdate 摘掉：内置 execute 的每个更新点都有 !onUpdate 守卫，
+			// 于是渲染器只会收到最后那次 final 结果。返回值与 details 不受影响。
+			//
+			// 同时把**有效期限**注进 params：pi 内置 bash 无默认 timeout，不注入的话
+			// 一条不退出的命令会无限期挂着。注入只影响这次执行 —— session 里落盘的
+			// toolCall.arguments 是模型原样发来的那份，不会被改写。
+			const nextParams = { ...params, timeout: effectiveTimeoutSeconds(params?.timeout) };
+			return base.execute(toolCallId, nextParams, signal, streaming ? onUpdate : undefined, ctx);
+		},
+
+		renderCall(args, theme, context) {
+			// 内置 renderCall 靠这里记时（"Took 1.2s"），覆盖后需要自己维护
+			const state = context.state;
+			if (context.executionStarted && state.startedAt === undefined) {
+				state.startedAt = Date.now();
+				state.endedAt = undefined;
+			}
+
+			// 非流式模式下管住**命令文本的逐字刷新**，但要分两个时间点（对齐 codex / opencode）：
+			//   时间点一：命令字符全收完（argsComplete）→ 一次性把完整命令打到屏幕上；
+			//   时间点二：命令执行完 → 结果由 renderResult 补刷到命令下面。
+			// 两个点必须分开：用 isPartial 做阈值会把命令也压到结果之后才出，变成
+			// 「全等到结果才一次性出」，那不是想要的效果。
+			//
+			// 为什么命令会逐字刷：模型生成 tool call 时参数是流式的（toolcall_delta 一片
+			// 一片到），pi 每收一片就 updateArgs() → updateDisplay() → 重画一次 renderCall。
+			// 所以收完前返回**零行组件**（连占位行都不画），argsComplete 后才出完整命令。
+			// 实测这段时间占大头：`echo hello` 从 toolcall_start 到 tool_execution_end 约 290ms，
+			// 其中 args 流式 197ms、toolcall_end→execution_start 63ms、命令执行只 31ms。
+			//
+			// argsComplete 在 assistant message_end 时置位（setArgsComplete），比
+			// tool_execution_start 早 ~60ms，正好是“命令收完”这个语义点。
+			// 返回零行组件是安全的：Box.render 开头有 `childLines.length === 0 → []` 守卫
+			// （paddingY 是在这之后才加的），所以不会画出空的带底色块。
+			// （updateDisplay 每次都传全新的 context，getRenderContext 现拼对象，
+			// 所以 argsComplete 读得到实时值。）
+			//
+			// **但 argsComplete 只在实时流里置位**，所以判定条件是「args 可能还在流」
+			// 而不是「args 还没收完」：pi 的 interactive-mode.js 只在 `message_end` 分支调
+			// `component.setArgsComplete()`，而 `/resume`（以及 renderInitialMessages /
+			// compaction_end / rebuildChatFromMessages）走的 `renderSessionItems` 重建历史时
+			// 只 `new ToolExecutionComponent(...)` + `component.updateResult(message)`，
+			// **从不调 setArgsComplete / markExecutionStarted** —— 历史块的 argsComplete
+			// 永远是 false。若只按 argsComplete 判定，恢复出来的 bash 块就只剩输出、
+			// 命令行整行消失（实测过：RESTORE 渲染出 ["", " hello"]，LIVE 渲染出
+			// ["", " $ echo hello", " hello", "", " Took 0.0s"]）。
+			// isPartial 正好补上这个缺口：构造时默认 true，只有 updateResult(result, false)
+			// 会置 false —— 实时流里那必然发生在 argsComplete 之后（tool_execution_end），
+			// 历史重建里则发生在第一次渲染之后。两种路径都能出命令，而流式阶段
+			// （isPartial 仍为 true）照旧一行都不画。
+			// 副作用（可接受）：实时流里按 Esc 中断一个还没收完参数的 tool call 时，
+			// message_end(aborted) 会 updateResult(isPartial=false) 而不置 argsComplete，
+			// 于是命令行会显示出来（args 不全时是 `$ ...` 占位）—— 能看到被中断的是
+			// 什么命令，比只显示一行报错更有用。
+			if (!streaming && !context.argsComplete && context.isPartial === true) {
+				return {
+					render(): string[] {
+						return [];
+					},
+					invalidate() {},
+				};
+			}
+
+			const rawCommand = args?.command;
+			const invalid = rawCommand !== undefined && rawCommand !== null && typeof rawCommand !== "string";
+			const command = typeof rawCommand === "string" ? rawCommand : "";
+			const timeout = args?.timeout;
+
+			const commandDisplay = invalid ? theme.fg("error", "[invalid arg]") : command ? command : theme.fg("toolOutput", "...");
+			const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
+			const styledFull = theme.fg("toolTitle", theme.bold(`$ ${commandDisplay}`)) + timeoutSuffix;
+
+			// 缓存放在组件闭包里而不是 state：流式阶段 args 会不断变长，
+			// 而 state 是整行共享的，按 width 缓存会返回旧命令的行。
+			let cachedWidth: number | undefined;
+			let cachedExpanded: boolean | undefined;
+			let cachedEnabled: boolean | undefined;
+			let cachedLimit: number | undefined;
+			let cachedResultSeen: boolean | undefined;
+			let cachedLines: string[] | undefined;
+
+			const component = {
+				render(width: number): string[] {
+					const wrapWidth = Math.max(20, width || 80);
+					const limit = Math.max(1, Math.round(maxLines));
+					// 缓存键要带上 enabled / limit，否则 /bash-collapse 切换后已渲染的行不会刷新
+					const resultSeen = state.resultSeen === true;
+					if (
+						cachedLines &&
+						cachedWidth === wrapWidth &&
+						cachedExpanded === context.expanded &&
+						cachedEnabled === enabled &&
+						cachedLimit === limit &&
+						cachedResultSeen === resultSeen
+					)
+						return cachedLines;
+
+					let result: string[];
+					// invalid（args.command 不是字符串）/ 空命令走 pi-tui 折行分支：这两种文本固定是
+					// `$ [invalid arg]` / `$ ...`，短到根本不会折行，而那个分支能原样保留
+					// 嵌套样式（error 色 / toolOutput 色），不用在硬折分支里重建
+					if (enabled && !context.expanded && !invalid) {
+						// 折叠态：**break-all 硬折行** + 视觉行数预算（`limit`，默认 3 行）。
+						// 详见文件头「折叠视图：break-all 硬折行」一节。
+						// 先折**纯文本**再逐行上样式：反过来会把 SGR 序列从中间切断。
+						const commandLines = (command || "...").split("\n");
+						const suffixWidth = visibleWidth(timeoutSuffix);
+						// 首行（且仅首行）要给 timeout 后缀留位置，否则长命令会把后缀挤掉
+						const firstRowBudget = suffixWidth > 0 ? Math.max(4, wrapWidth - suffixWidth) : wrapWidth;
+						const shown: string[] = [];
+						const hiddenParts: string[] = [];
+						let budgetExhausted = false;
+						// 引号状态跨源行保留（多行字符串的第二行不会被当成新命令分词）
+						let openQuote: string | null = null;
+						for (let i = 0; i < commandLines.length && !budgetExhausted; i++) {
+							const line = commandLines[i]!;
+							const prefix = i === 0 ? "$ " : "";
+							const { rows, tokens, nextQuote } = wrapAndTokenizeLine(prefix, line, i === 0 ? firstRowBudget : wrapWidth, wrapWidth, openQuote, highlightEnabled);
+							openQuote = nextQuote;
+							for (let r = 0; r < rows.length; r++) {
+								if (shown.length >= limit) {
+									// 预算用完：本源行剩下的碎片（拼回去就是它的尾巴）
+									// + 后续源行全部隐藏。硬折行不丢字符，所以碎片直接
+									// join("") 就是原文尾巴（不用像旧代码那样用
+									// startsWith 反推截断点）。用的是**纯文本**碎片，所以
+									// token 估算不会把 SGR 序列算进去。
+									hiddenParts.push(rows.slice(r).map((piece) => piece.text).join(""));
+									for (let j = i + 1; j < commandLines.length; j++) hiddenParts.push(commandLines[j]!);
+									budgetExhausted = true;
+									break;
+								}
+								shown.push(styleWrappedRow(rows[r]!, prefix, line, tokens, theme) + (i === 0 && r === 0 ? timeoutSuffix : ""));
+							}
+						}
+						result = shown;
+						// 只要有任何内容被折掉或被折叠就出提示：一行长命令硬折后可能
+						// 刚好装满预算（行数 == limit），靠「行数 > limit」判定会漏
+						const hidden = hiddenParts.join("\n");
+						if (hidden.trim() !== "") {
+							const hint = theme.fg("muted", `… (${formatCount(estimateTokens(hidden))} tokens hidden)`);
+							result = [...shown, truncateToWidth(hint, wrapWidth, "…")];
+						}
+					} else if (invalid || !command) {
+						// invalid（args.command 不是字符串）/ 空命令：文本固定是 `$ [invalid arg]`
+						// / `$ ...`，短到根本不会折行，而折行分支能原样保留嵌套样式
+						//（error 色 / toolOutput 色），不用在硬折分支里重建
+						result = wrapTextWithAnsi(styledFull, wrapWidth);
+					} else {
+						// 展开态（ctrl+o）/ 关闭折叠：要的就是完整命令，**同样用 break-all
+						// 硬折行** —— 贪心词折行在这里一样会把长路径整块挪到下一行
+						// 再从中间断开（就是用户看到的 `$ ` 后面直接折行），展开态只是
+						// 不限行数，折行规则必须一致。
+						const commandLines = command.split("\n");
+						const suffixWidth = visibleWidth(timeoutSuffix);
+						const firstRowBudget = suffixWidth > 0 ? Math.max(4, wrapWidth - suffixWidth) : wrapWidth;
+						const rows: string[] = [];
+						let openQuote: string | null = null;
+						for (let i = 0; i < commandLines.length; i++) {
+							const line = commandLines[i]!;
+							const prefix = i === 0 ? "$ " : "";
+							const { rows: pieces, tokens, nextQuote } = wrapAndTokenizeLine(prefix, line, i === 0 ? firstRowBudget : wrapWidth, wrapWidth, openQuote, highlightEnabled);
+							openQuote = nextQuote;
+							for (const piece of pieces) rows.push(styleWrappedRow(piece, prefix, line, tokens, theme));
+						}
+						result = rows.map((row, idx) => row + (idx === 0 ? timeoutSuffix : ""));
+					}
+
+					// 染色块的上下边界空行（见文件头「染色块的上下边界空行」）：
+					// 上边界永远补；下边界只在结果还没到时补 —— 结果到了之后紧接着就是
+					// resultBox，那时补会在命令与输出之间多出一行空白。
+					// 判定用 state.resultSeen（renderResult 置位），不用 isPartial：
+					// 流式模式下 partial 结果也会调 renderResult，isPartial 仍是 true，
+					// 用它会在命令与输出之间留下空白。
+					result = ["", ...result, ...(resultSeen ? [] : [""])];
+
+					cachedWidth = wrapWidth;
+					cachedExpanded = context.expanded;
+					cachedEnabled = enabled;
+					cachedLimit = limit;
+					cachedResultSeen = resultSeen;
+					cachedLines = result;
+					return result;
+				},
+				invalidate() {
+					cachedWidth = undefined;
+					cachedExpanded = undefined;
+					cachedEnabled = undefined;
+					cachedLimit = undefined;
+					cachedResultSeen = undefined;
+					cachedLines = undefined;
+				},
+			};
+
+			// self 模式下 pi 不给整块套底色，自己包一层 Box 保持原有的背景块观感。
+			// paddingY 用 0：命令与结果是两个独立的 Box，各自的垂直 padding 会叠加成
+			// 命令与输出之间的多余空行（详见 renderResult 里那条注释）。
+			const box = new Box(1, 0, stateBgFn(theme, context.isPartial === true, context.isError === true));
+			box.addChild(component);
+			return box;
+		},
+	});
+
+	pi.registerCommand("bash-collapse", {
+		description: "折叠 bash 命令显示：off | on | <视觉行数 1-50>",
+		handler: async (args, ctx) => {
+			const arg = args.trim();
+
+			if (arg === "off") {
+				enabled = false;
+				ctx.ui.notify("bash 命令折叠已关闭（完整显示）", "info");
+				return;
+			}
+
+			if (arg === "" || arg === "on") {
+				enabled = true;
+				ctx.ui.notify(`bash 命令折叠已开启，${statusText()}`, "info");
+				return;
+			}
+
+			const parsed = Number.parseInt(arg, 10);
+			if (!Number.isFinite(parsed) || parsed < 1 || parsed > 50) {
+				ctx.ui.notify("用法：/bash-collapse off | on | <视觉行数 1-50>", "warning");
+				return;
+			}
+
+			enabled = true;
+			maxLines = parsed;
+			ctx.ui.notify(`bash 命令折叠已开启，${statusText()}`, "info");
+		},
+	});
+
+	pi.registerCommand("bash-preview", {
+		description: "bash 输出预览行数：off（pi 内置 5 行）| <行数 1-50>",
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+
+			if (arg === "off") {
+				previewLines = 5; // pi 的 BASH_PREVIEW_LINES，等于不裁
+				ctx.ui.notify("bash 输出预览已恢复 pi 内置的 5 行", "info");
+				return;
+			}
+
+			if (arg === "") {
+				ctx.ui.notify(`当前输出预览：前 ${previewLines} 行（pi 内置是 5 行，超出部分带 earlier lines 提示）`, "info");
+				return;
+			}
+
+			// 用 Number 而不是 parseInt：parseInt("2.5") 会静默变成 2（与
+			// clampPreviewLines 的归一策略一致，小数应当被拒而不是静默截断）
+			const parsed = Number(arg);
+			const next = clampPreviewLines(parsed);
+			if (next !== parsed) {
+				ctx.ui.notify("用法：/bash-preview off | <行数 1-50 的整数>", "warning");
+				return;
+			}
+
+			previewLines = next;
+			ctx.ui.notify(`bash 输出预览已改为前 ${previewLines} 行`, "info");
+		},
+	});
+
+	// 输出树形 gutter 开关。默认开；展开态（ctrl+o）不受这个开关影响 —— 鸭子判定
+	// 已经跳过了 `Text` 分支（见文件头「输出树形 gutter」一节）。
+	// 空参数只报状态、不改状态，与 /bash-collapse / /bash-preview / /bash-stream 的约定一致。
+	pi.registerCommand("bash-tree", {
+		description: "bash 输出的树形缩进（│ / └）：off | on",
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+
+			if (arg === "") {
+				ctx.ui.notify(`当前输出树形缩进：${treeEnabled ? "开（每行 │、末行 └）" : "关（输出顶格显示）"}`, "info");
+				return;
+			}
+
+			if (arg === "off") {
+				treeEnabled = false;
+				ctx.ui.notify("bash 输出的树形缩进已关闭（输出顶格显示）", "info");
+				return;
+			}
+
+			if (arg === "on") {
+				treeEnabled = true;
+				ctx.ui.notify("bash 输出的树形缩进已开启（展开态不受影响）", "info");
+				return;
+			}
+
+			ctx.ui.notify("用法：/bash-tree off | on", "warning");
+		},
+	});
+
+	pi.registerCommand("bash-stream", {
+		description: "bash 屏幕显示：off（默认，命令收完一次性出、结果补刷）| on（pi 原生流式）",
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+
+			if (arg === "off") {
+				streaming = false;
+				ctx.ui.notify(streamStatusText(), "info");
+				return;
+			}
+
+			if (arg === "on") {
+				streaming = true;
+				ctx.ui.notify(streamStatusText(), "info");
+				return;
+			}
+
+			if (arg === "") {
+				ctx.ui.notify(`当前：${streamStatusText()}`, "info");
+				return;
+			}
+
+			ctx.ui.notify("用法：/bash-stream off | on", "warning");
+		},
+	});
+
+	// 只读查看当前生效的期限：默认值、上限、以及 env 有没有覆盖。
+	// 值在 execute 里每次调用时重算，所以这里显示的永远是下一次执行的真实期限。
+	pi.registerCommand("bash-timeout", {
+		description: "查看 bash 执行期限（默认 / 上限 / env 覆盖）",
+		handler: async (_args, ctx) => {
+			const override = (name: string) => {
+				const value = readTimeoutEnvMs(name);
+				return value === undefined ? "未设置" : `${name}=${value}ms`;
+			};
+			ctx.ui.notify(
+				`默认 ${defaultTimeoutSeconds()}s，上限 ${maxTimeoutSeconds()}s；env：${override("BASH_DEFAULT_TIMEOUT_MS")} / ${override("BASH_MAX_TIMEOUT_MS")}（改完需重启 pi）`,
+				"info",
+			);
+		},
+	});
+}