$ cat ~/map/pi-tool-timeout.md

pi-tool-timeout

前台工具的超时覆盖层：bash、powershell 默认 300 秒，grep、find 以包装时限执行。

extensions✓ 9月18日

事实速查

安装

运行 pi install git:github.com/GhabiX/pi-tool-timeout（文档同样给出本地路径与项目级安装方式）；面向 pi 0.85.x，需要 Node 22.19.0 或更新版本，装完重启 pi 或运行 /reload

## 速览

一个为 pi 前台工具调用补上默认超时的扩展：bash 与 powershell 在未显式设定预算时以 300 秒运行，grep 与 find 被包装上墙钟时限，显式设定的超时永远照旧生效。

$两个适配器、一套策略：tool_call 钩子为未填超时的 bash 与 powershell 调用补上 pi 原生 timeout 字段的 300；grep 与 find 的原生 schema 没有超时字段，则在 session_start 时为其加上该字段并用墙钟时限包装 execute。
$覆盖层不占有工具：原生超时工具的实际实现仍是属主，因此 shell 设置、渲染器、spawn 钩子与其他 bash 扩展照常工作；模型则通过随 systemPrompt 返回的按工具指引得知修正后的默认值。
$安装本身不会启用 grep 与 find：注册发生在默认活跃工具集就位之后，且此前的活跃集会被原样恢复，所以只有在你自己启用这两个工具时，包装版本才会生效。
$显式的正超时在任何地方都得到保留，父级的取消也绝不会被转换成超时。
$刻意的边界：没有重试策略、没有命令分类、没有后台执行、没有 UI、也没有配置系统——服务器、监视进程这类真正长活的工作应交给独立的终端后台工具。
$组合上限：pi 中同名扩展工具先到先得，因此只有在没有更早的扩展注册同名工具时，覆盖层才会包装内建工具，无法叠在既有的同名覆盖之上。

Q 我的 bash 命令会得到多长的超时？

调用未显式设置超时则是 300 秒；显式的正值按原样生效。技术上唯一的天花板是 Node 定时器约 24.8 天的极限，与 pi 原生 bash 定时器一致。

Q 安装它会改变哪些工具处于活跃状态吗？

不会。被包装的 grep 与 find 注册会恢复之前的活跃集，安装这个包本身不会启用它们；当你自行启用这两个工具时，包装才会生效。

Q 它能叠在另一个已经覆盖 bash 的扩展之上吗？

不能——pi 中同名扩展工具先到先得。只有当没有更早的扩展注册同名工具时，覆盖层才会包装内建工具。

最后更新: 2026年9月18日