[Bug] Bash / Read / Glob / Grep intermittently fail with `Tool <name> not found` (0 ms) on Windows — present in 0.15.9 and 0.15.10

[bachhn25810320367]

[Bug] Bash / Read / Glob / Grep intermittently fail with Tool <name> not found (0 ms) on Windows — present in 0.15.9 and 0.15.10

What happened? / 问题描述

The four filesystem/shell tools (bash, read, glob, grep) stop resolving. The model emits a tool call, the app receives it, and the tool immediately returns:

Tool bash not found
Tool read not found
Tool glob not found
Tool grep not found

The failure takes 0 ms, which means it never reaches the actual tool implementation — it is rejected at name-resolution time.

Two things make this hard to pin down, and both are the reason for this report:

1. It is intermittent, not a permanently dead registry. The same tool name, same app version, same session, alternates between working and failing:

2026-09-28T09:00:35Z  Bash  error    0ms
2026-09-28T09:02:24Z  Read  error    0ms
2026-09-28T09:02:28Z  Bash  error    0ms
2026-09-28T09:03:43Z  Bash  success 223ms     <-- works
2026-09-28T09:03:47Z  Bash  error    1ms
2026-09-28T09:04:13Z  Bash  error    0ms
2026-09-28T09:05:12Z  Bash  success 267ms     <-- works
2026-09-28T09:06:07Z  Bash  error    0ms
2026-09-28T09:07:08Z  Read  success 18ms      <-- works
2026-09-28T09:12:16Z  Glob  success           <-- last success ever recorded

2. It is not a 0.15.10 regression. The last recorded success is 2026-09-28T09:12:16Z. The updater installed 0.15.9 at 05:14:08Z and 0.15.10 at 15:52:10Z that same day. Between 09:16 and 15:52 — i.e. while 0.15.9 was running — there were 62 consecutive dead-tool calls, all errors, all 0–1 ms. So 0.15.9 is affected too, and downgrading is not a workaround.

As of 2026-09-29T09:55Z (this report) there have been zero successful executions of these four tools across 24 h, 2 sessions, and 2 full app restarts.

Steps to reproduce / 复现步骤

1. Run PI-Desktop on Windows 10 with a long-lived session that uses the agent harness heavily.

2. After roughly a day of use, the four tools begin failing.

3. Restart the app fully and open a new session — the tools still fail immediately, so it is not per-session state.

4. Check ~/.pi-desktop/logs/app/tool.log: every failure is tool.execution.failed with "durationMs":0 and a valid toolCallId, meaning the call is delivered to the app and fails inside the tool layer.

Expected behavior / 预期行为

A tool name that is present in the session's tool list resolves and executes.

Actual behavior / 实际行为

tools.find(o => o.name === call.name) returns undefined and the call is rejected with Tool <name> not found in 0 ms, with no diagnostic about which names were actually available.

Where the message comes from / 错误信息来源

I traced the string to the tool-dispatch helper in the bundled runtime (resources/agent-runtime/sidecar.js, 7.7 MB minified bundle). The three distinct not found formats in that bundle are distinguishable; the one that is actually emitted (unquoted, matching the observed text) is:

async function Aht(t, e, n, r, i) {
  let s = t.tools?.find(o => o.name === n.name);
  if (!s) return { kind: "immediate", result: i_(`Tool ${n.name} not found`), isError: !0 };
  ...
}

The lookup is a strict === with no case normalization and no fallback, and the immediate branch explains the 0 ms duration exactly.

The registered names are all lowercase / 注册名全为小写

Instantiating the real tool definitions from the standalone package @earendil-works/pi-coding-agent@0.87.1 (dist/core/tools/*.js) at runtime:

createReadToolDefinition             -> name: "read"
createBashToolDefinition             -> name: "bash"
createEditToolDefinition             -> name: "edit"
createWriteToolDefinition            -> name: "write"
createGrepToolDefinition             -> name: "grep"
createFindToolDefinition             -> name: "find"
createLsToolDefinition               -> name: "ls"
createPowerShellToolDefinition       -> name: "powershell"

Reproducing the dispatcher's lookup against that set:

tools.find(o => o.name === "read")  -> true
tools.find(o => o.name === "Read")  -> false
tools.find(o => o.name === "bash")  -> true
tools.find(o => o.name === "Bash")  -> false
tools.find(o => o.name === "glob")  -> false      <-- pi has no "glob" at all

Two observations:

• The canonical names are lowercase. A capitalized name can never satisfy the ===.

• pi core has no glob tool whatsoever — it has find and ls. So glob is not obtainable from pi core under any spelling, which suggests Glob is supplied by the desktop layer and is broken for a separate reason.

The bundled sidecar.js contains both spellings, which is consistent with an unfinished name migration (see #860):

  | capitalized | lowercase -- | -- | -- Bash / bash | 16 | 31 Read / read | 12 | 23 Edit / edit | 9 | 21 Grep / grep | 10 | 8 Glob / glob | 10 | 2

Write (312/312), Edit (156/168), Task (26/26), askTool (16/16) and plugin_pi_shellbridge_shell_run (416/449) were unaffected throughout — so the failure is specific to this group, not a general session failure.

App version / 应用版本

PI-Desktop 0.15.10 · win32 x64
resources/agent-runtime/sidecar.js  7,696,583 bytes  (2026-09-28 19:30 local)
pi-desktop-host-core.exe             15,870,464 bytes (2026-09-28 19:30 local)

Operating system / 操作系统

Windows 10 Pro, 10.0.19045 (MINGW64_NT-10.0-19045)
Electron 43.6.0 · Node v24.20.0

Extra environment / 其他环境信息

• Affected on both 0.15.9 and 0.15.10.

• The four tools have never recovered in 24 h / 2 sessions / 2 restarts.

• Bash and Read calls reach the app (valid toolCallId in the log), so this is not a model↔app transport failure.

Logs / 日志

Representative failure entries from ~/.pi-desktop/logs/app/tool.log:

{"ts":"2026-09-29T09:53:51.427Z","level":"error","channel":"app","category":"tool","event":"tool.execution.failed","message":"tool execution failed","sessionId":"<this-session>","turnId":"<...>","toolCallId":"call_function_...","data":{"toolName":"read","outcome":"error","durationMs":0,...}}
{"ts":"2026-09-29T09:53:53.389Z","level":"error","channel":"app","category":"tool","event":"tool.execution.failed","message":"tool execution failed","sessionId":"<this-session>","turnId":"<...>","toolCallId":"call_function_...","data":{"toolName":"bash","outcome":"error","durationMs":0,...}}
{"ts":"2026-09-29T09:54:15.243Z","level":"error","channel":"app","category":"tool","event":"tool.execution.failed","message":"tool execution failed","sessionId":"<this-session>","turnId":"<...>","toolCallId":"call_function_...","data":{"toolName":"grep","outcome":"error","durationMs":0,...}}

For contrast, a working call from the same log:

{"ts":"2026-09-28T09:07:08Z","level":"info",...,"data":{"toolName":"Read","outcome":"success","durationMs":18,...}}

What would help most / 最需要的信息

The single missing piece is the actual contents of t.tools at the moment of a failure. A one-line diagnostic in the dispatcher would settle it immediately:

let s = t.tools?.find(o => o.name === n.name);
if (!s) { console.warn('[pi] tool lookup miss', { called: n.name, available: t.tools?.map(x => x.name) }); ... }

Without it, Tool <name> not found is indistinguishable between "name not registered", "name registered with different case", and "tool list rebuilt mid-session" — which is exactly why this has been hard to diagnose from the outside.

Two smaller questions:

1. Is the tool list rebuilt per turn, per mode, or per compaction? A rebuild that drops the filesystem/shell group would explain the intermittency and the recovery.

2. Should the dispatcher normalize case, or should the name migration in refactor(tool-names): one canonical lowercase tool name, one normalization boundary #860 be finished on the desktop side so it matches pi core's lowercase canonical names?

Related

• [Bug] 目标/计划模式收窄了工具清单，但继承的历史仍包含被移除的工具 → 严格校验的上游会拒掉整轮（502） #1174 — tool list narrowed by goal/plan mode while inherited history keeps removed tools

• refactor(tool-names): one canonical lowercase tool name, one normalization boundary #860 — refactor(tool-names): one canonical lowercase tool name (opened, not merged)

• [Bug] Windows 10 Edit 工具总是失败 #1217 — Edit failing on Windows 10 / 0.15.10

• [Bug] Windows 下 npx 类型 MCP 无法启动，错误提示 command not found，但 npx 已安装且位于 PATH #789, [Bug] 0.15.6 stdio MCP still fails to spawn npx (command not found); fix landed in 0.15.8 #1096 — Windows "command not found" although the binary is installed and on PATH

[muzimu217]

提供一份代码层的诊断假设，供定位参考（基于 host-core/agent-runtime 源码阅读，非 Windows 环境复现）：

0ms 失败意味着拒绝发生在名字解析期，而不是工具执行期。 "Tool bash not found" 这类文本来自 agent 侧的工具目录（tool catalog）查找——模型发出的名字在当前会话的工具清单里查不到，立即以纯文本错误返回。这与超时类失败（会有真实耗时）是两条完全不同的路径。

为什么是间歇性的：工具清单是动态装配的。 每次请求的工具列表按当前 mode（Agent/Plan/Goal 切换时核心集与保留集重组，见 mode-tool-access.ts）、插件状态（插件 reload 时 host 侧对插件工具做整表替换——tools.set/registry 重建期间存在新旧清单交替的窗口）与会话状态（scheduled/subagent 注入）动态重建。任何一个重建窗口落在请求解析的瞬间，该请求就会拿到不含 bash 的清单——表现为 0ms "not found"；下一请求窗口关闭又正常。这与你们时间线里"同一秒级窗口内 success/error 交替"的形态一致。

"最后永久失败"的解释假设：某次插件 reload 或子进程（Windows 上 stdio 子进程启动更慢更易失败）失败后，目录停在了坏状态且没有再触发重建——从"间歇"恶化为"持续"。

对维护者的三条可操作建议：

1. 解析失败时快照日志：tool-not-found 返回前记录当前 catalog 的工具数与名单（debug 级即可）——一次复现就能区分"清单真的缺"还是"名字真的错"；
2. 核心四工具常驻：bash/read/glob/grep 的声明不参与插件 reload 的整表替换（类似 RETAINED_MODE_TOOLS 的做法），从结构上消灭核心工具的空窗；
3. Windows 插件注册延迟容错：插件子进程启动慢导致的注册延迟，考虑对"曾成功注册过的插件工具"保留旧条目直到新注册成功（stale-while-revalidate 语义）。

如果维护者需要，我可以进一步把"清单重建窗口"的代码位置（host 侧整表替换点与请求解析点的相对时序）整理成带文件行号的说明。