@trim21/personal-pi-extensions 0.1.573 → 0.1.575

package/README.md

@@ -11,6 +11,8 @@
 | [bwrap](#bwrap)                 | 基于 bubblewrap 的 OS 级沙箱，提供文件系统和网络隔离    |
 | [写保护（内置）](#写保护内置)   | 写工具内置：限制文件写入在 workspace 内，外部写入需审批 |
 | [opencode-edit](#opencode-edit) | 替换内置 edit 工具，使用 opencode 的 schema 和匹配引擎  |
+| [opencode-grep](#opencode-grep) | opencode 风格 grep，基于 ripgrep 的内容搜索             |
+| [opencode-glob](#opencode-glob) | opencode 风格 glob，基于 ripgrep 的文件名匹配           |
 | [vision-agent](#vision-agent)   | 视觉代理：主模型不支持视觉时，spawn 子 agent 识别图片   |
 | [session-name](#session-name)   | 首个 user prompt 自动生成会话名，失败仅告警不命名       |
 | [todowrite](#todowrite)         | opencode 风格的任务列表工具，完整列表替换语义           |
@@ -19,7 +21,7 @@
 | [openai-cost](#openai-cost)     | OpenAI Chat Completions，费用取自响应 `usage.cost`      |
 
 > **两套工具风格，按预期只启用其中一套**：本包同时提供 opencode 风格
-> （小写 `read`/`edit`/`write`/`bash`/`todowrite`/`question`）与 Claude Code
+> （小写 `read`/`edit`/`write`/`grep`/`glob`/`bash`/`todowrite`/`question`）与 Claude Code
 > 风格（大写 `Read`/`Edit`/`Write`/`Bash`/`Grep`/`Glob`/`TodoWrite`/
 > `AskUserQuestion`）两套工具集，二者共享 bwrap 沙箱与写保护实现。两套同时
 > 启用会带来预期外的冗余：同名命令重复注册（如 `/bwrap` 出现 `/bwrap:1`
@@ -146,6 +148,32 @@ pi -e ./src/opencode-edit.ts
 
 ---
 
+## opencode-grep
+
+opencode 风格的 `grep` 工具，替换 pi 内置 `grep`。参数与输出格式对齐 opencode 的 [`grep`](https://github.com/anomalyco/opencode) 工具：`pattern` / `path` / `include`，输出以 `Found N matches` 开头，按文件分组（`<绝对路径>:` + `  Line N: <文本>`）。隐藏文件参与搜索、`.git` 排除、结果上限 100 条（触顶时提示 `(more matches available)` 并附截断说明）。
+
+执行层在 `src/opencode/ripgrep.ts`：`rg` 子进程流式读取 stdout，读满 100 条即终止进程，宽泛 pattern 不会把整个结果集读进内存；退出码语义与上游一致（1 = 无匹配，2 = 部分文件读失败仍返回已有结果，正则语法错误单独报错）。
+
+与上游的三处有意差异：行文本去掉 rg JSON 带出的行尾换行（否则每条匹配后面会多一个空行）；`path` 指向文件时只搜该文件（上游按目录搜索）；`path` 不存在时报错（含同目录相近名字提示），而不是静默返回 `No files found`。
+
+### 使用
+
+随 `src/opencode/index.ts` 一起加载。
+
+---
+
+## opencode-glob
+
+opencode 风格的 `glob` 工具（与 pi 内置 `find` 并存）。参数 `pattern` / `path`，内部是 `rg --files` 语义：尊重 `.gitignore`、不列隐藏文件、不按修改时间排序、排除 `.git`，输出绝对路径，上限 100 条（截断时附 `(Results are truncated: ...)`）。与 Claude Code 风格 `Glob` 的差异（`--no-ignore` / `--hidden` / `--sort=modified`）是各自跟随上游的结果。
+
+`path` 不存在或指向文件时报错（含同目录相近名字提示）。
+
+### 使用
+
+随 `src/opencode/index.ts` 一起加载。
+
+---
+
 ## vision-agent
 
 视觉代理扩展。主模型不支持视觉（如 DeepSeek）时自动启用 `describe_image` 工具；主模型支持视觉时自动隐藏，图片由 pi 原生透传。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.573",
+  "version": "0.1.575",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/opencode/bash.md

@@ -6,8 +6,10 @@ Commands run in a sandbox: no write access outside the workspace and no network
 
 Long command output is automatically truncated and the full output is saved to a file. Avoid piping commands through `tail` or `2>&1 | tee test.log` to limit output unless you have a specific reason.
 
-IMPORTANT: Avoid using this tool to run `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
 
+- File search: Use `glob` (NOT find or ls)
+- Content search: Use `grep` (NOT grep or rg)
 - Read files: Use `read` (NOT cat/head/tail)
 - Edit files: Use `edit` (NOT sed/awk)
 - Write files: Use `write` (NOT echo >/cat <<EOF)

package/src/opencode/files.ts

@@ -329,7 +329,8 @@ function truncationFromPage(page: LinePage): TruncationResult {
   };
 }
 
-async function didYouMean(filePath: string): Promise<string> {
+/** 同目录下名字相近的候选（供 read / edit / grep 的路径错误提示复用）。 */
+export async function didYouMean(filePath: string): Promise<string> {
   const dir = dirname(filePath);
   const base = basename(filePath);
 

package/src/opencode/glob.md

@@ -0,0 +1,6 @@
+### glob tool
+
+- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/\*.js" or "src/**/*.ts"
+- Returns matching file paths
+- Use this tool when you need to find files by name patterns

package/src/opencode/glob.ts

@@ -0,0 +1,120 @@
+/**
+ * opencode 风格 glob 工具。
+ *
+ * 对齐上游 packages/opencode/src/tool/glob.ts：参数只有 pattern / path，内部执行
+ * rg --files（附带 --no-config、pattern 的 --glob，并排除 .git 目录），上限 100 条，
+ * 输出绝对路径，空结果 "No files found"。与 claude-code 风格 Glob 的差异是刻意
+ * 跟随上游的：尊重 .gitignore、不列隐藏文件、不按修改时间排序。
+ *
+ * 一处有意差异：path 不存在或不是目录时报错（上游直接让 rg 失败），并给出同目录
+ * 相近名字的提示。
+ */
+
+import { readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { didYouMean } from "./files.js";
+import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
+
+/** Tool guidance, kept in markdown so it reads like documentation. */
+const GLOB_PROMPT = readFileSync(fileURLToPath(new URL("glob.md", import.meta.url)), "utf8").trim();
+
+export function buildGlobArgs(pattern: string): string[] {
+  return ["--no-config", "--files", `--glob=${pattern}`, "--glob=!**/.git/**", "."];
+}
+
+/** rg --files 输出的路径：去掉前导 `./`，分隔符统一成 `/`。 */
+function normalizeRipgrepPath(text: string): string {
+  return text.replace(/^(?:\.[\\/])+/u, "").replaceAll("\\", "/");
+}
+
+export function renderGlobOutput(files: readonly string[], truncated: boolean): string {
+  if (files.length === 0) return "No files found";
+  const output = [...files];
+  if (truncated) {
+    output.push(
+      "",
+      `(Results are truncated: showing first ${RIPGREP_RESULT_LIMIT} results. Consider using a more specific path or pattern.)`,
+    );
+  }
+  return output.join("\n");
+}
+
+async function glob(
+  params: { pattern: string; path?: string },
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+): Promise<{ text: string; search: string; count: number; truncated: boolean }> {
+  // resolve 对绝对路径原样返回，相对路径按调用 cwd 解析
+  const search = resolve(ctx.cwd, params.path ?? ".");
+  let info;
+  try {
+    info = await stat(search);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      const suggestion = await didYouMean(search);
+      throw new Error(
+        `Directory does not exist: ${params.path ?? search}. Note: your current working directory is ${ctx.cwd}.${suggestion}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+  if (!info.isDirectory()) {
+    throw new Error(`glob path must be a directory: ${search}`);
+  }
+
+  const { items, truncated } = await runRipgrep(buildGlobArgs(params.pattern), {
+    cwd: search,
+    signal,
+    limit: RIPGREP_RESULT_LIMIT,
+    parse: (line) => (line.length === 0 ? undefined : normalizeRipgrepPath(line)),
+  });
+  const files = items.map((file) => resolve(search, file));
+  return { text: renderGlobOutput(files, truncated), search, count: files.length, truncated };
+}
+
+export default function opencodeGlob(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "glob",
+    label: "glob",
+    description: [
+      "Fast file pattern matching that works with any codebase size.",
+      'Supports glob patterns such as "**/*.js" and "src/**/*.ts"; results are capped at 100 files.',
+    ].join("\n"),
+    promptSnippet: "Find files by name patterns",
+    promptGuidelines: [GLOB_PROMPT],
+    parameters: Type.Object(
+      {
+        pattern: Type.String({ description: "The glob pattern to match files against" }),
+        path: Type.Optional(
+          Type.String({
+            description:
+              'The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.',
+          }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const { text, search, count, truncated } = await glob(params, ctx, signal);
+      return {
+        content: [{ type: "text" as const, text }],
+        details: {
+          pendant: {
+            subtitle:
+              count === 0
+                ? `no files in ${search}`
+                : `${count} file${count === 1 ? "" : "s"}${truncated ? " (truncated)" : ""}`,
+          },
+        },
+      };
+    },
+  });
+}

package/src/opencode/grep.md

@@ -0,0 +1,9 @@
+### grep tool
+
+- Fast content search tool that works with any codebase size
+- Searches file contents using regular expressions
+- Supports full regex syntax (eg. "log.*Error", "function\s+\w+", etc.)
+- Filter files by pattern with the include parameter (eg. "_.js", "_.{ts,tsx}")
+- Returns file paths and line numbers with matching lines
+- Use this tool when you need to find files containing specific patterns
+- If you need to count matches per file or use flags this tool does not expose, use the Bash tool with `rg` (ripgrep) directly instead of shelling out to `grep`.

package/src/opencode/grep.ts

@@ -0,0 +1,206 @@
+/**
+ * opencode 风格 grep 工具。
+ *
+ * 对齐上游 packages/opencode/src/tool/grep.ts：参数只有 pattern / path / include，
+ * 输出以 `Found N matches` 开头、按文件分组（`<path>:` + `  Line N: <text>`），
+ * 结果上限 100 条，隐藏文件参与搜索、.git 排除。
+ *
+ * 三处有意差异（都是上游实现的毛病）：
+ * - 行文本去掉 rg JSON 带出的行尾换行，否则每条匹配后面多一个空行；
+ * - `path` 指向文件时只搜该文件（上游仍按目录搜索，仅把结果路径按目录解析）；
+ * - `path` 不存在时报错（对齐 claude-code 的 Grep），而不是静默返回 No files found。
+ */
+
+import { readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { parseWithSchema } from "../lib/parse-with-schema.js";
+import { didYouMean } from "./files.js";
+import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
+
+/** Tool guidance, kept in markdown so it reads like documentation. */
+const GREP_PROMPT = readFileSync(fileURLToPath(new URL("grep.md", import.meta.url)), "utf8").trim();
+
+/** 单行文本上限（上游 2000 字符，超出截断加省略号）。 */
+const MAX_LINE_LENGTH = 2000;
+
+/** 单条 rg JSON 记录上限（上游 64 KiB）。 */
+const MAX_RECORD_BYTES = 64 * 1024;
+
+/** rg --json 的 match 记录（只取工具用到的字段）。 */
+const rawMatchSchema = Type.Object({
+  data: Type.Object({
+    path: Type.Object({ text: Type.String() }),
+    lines: Type.Object({ text: Type.String() }),
+    line_number: Type.Integer(),
+  }),
+});
+
+export interface GrepMatch {
+  /** 相对 rg cwd 的路径，调用方负责解析成绝对路径。 */
+  path: string;
+  line: number;
+  text: string;
+}
+
+/** rg 输出的路径：去掉前导 `./`，分隔符统一成 `/`。 */
+function normalizeRipgrepPath(text: string): string {
+  return text.replace(/^(?:\.[\\/])+/u, "").replaceAll("\\", "/");
+}
+
+/** 行文本：去掉行尾换行，超长截断（不留半个 surrogate pair）。 */
+function normalizeLineText(text: string): string {
+  const line = text.replace(/[\r\n]+$/u, "");
+  if (line.length <= MAX_LINE_LENGTH) return line;
+  return line.slice(0, MAX_LINE_LENGTH).replace(/[\uD800-\uDBFF]$/u, "") + "...";
+}
+
+/**
+ * 解析一行 rg --json 输出。非 match 记录（begin/end/summary）返回 undefined；
+ * match 记录形状不符或超过大小上限则抛错（损坏的输出不该被当成空结果）。
+ */
+export function parseGrepRecord(line: string): GrepMatch | undefined {
+  if (Buffer.byteLength(line, "utf8") > MAX_RECORD_BYTES) {
+    throw new Error(`ripgrep JSON record exceeded ${MAX_RECORD_BYTES} bytes`);
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(line);
+  } catch (error) {
+    throw new Error("Invalid ripgrep JSON output", { cause: error });
+  }
+  if (typeof json !== "object" || json === null || (json as { type?: unknown }).type !== "match") {
+    return undefined;
+  }
+  const record = parseWithSchema(rawMatchSchema, json);
+  return {
+    path: normalizeRipgrepPath(record.data.path.text),
+    line: record.data.line_number,
+    text: normalizeLineText(record.data.lines.text),
+  };
+}
+
+export function buildGrepArgs(
+  pattern: string,
+  include: string | undefined,
+  target: string,
+): string[] {
+  return [
+    "--no-config",
+    "--json",
+    "--hidden",
+    "--no-messages",
+    ...(include ? [`--glob=${include}`] : []),
+    "--glob=!**/.git/**",
+    "--",
+    pattern,
+    target,
+  ];
+}
+
+/** 渲染搜索结果：上游格式，按文件分组。 */
+export function renderGrepOutput(matches: readonly GrepMatch[], truncated: boolean): string {
+  if (matches.length === 0) return "No files found";
+  const output = [`Found ${matches.length} matches${truncated ? " (more matches available)" : ""}`];
+  let current = "";
+  for (const match of matches) {
+    if (current !== match.path) {
+      if (current !== "") output.push("");
+      current = match.path;
+      output.push(`${match.path}:`);
+    }
+    output.push(`  Line ${match.line}: ${match.text}`);
+  }
+  if (truncated) {
+    output.push("", "(Results truncated. Consider using a more specific path or pattern.)");
+  }
+  return output.join("\n");
+}
+
+/** 搜索根：绝对路径原样，相对路径按调用 cwd 解析。 */
+export function resolveSearchRoot(path: string | undefined, cwd: string): string {
+  if (path === undefined || path === "") return cwd;
+  return isAbsolute(path) ? path : join(cwd, path);
+}
+
+async function grep(
+  params: { pattern: string; path?: string; include?: string },
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+): Promise<{ text: string; subtitle: string }> {
+  if (params.pattern === "") {
+    throw new Error("pattern is required");
+  }
+  const requested = resolveSearchRoot(params.path, ctx.cwd);
+  let info;
+  try {
+    info = await stat(requested);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      const suggestion = await didYouMean(requested);
+      throw new Error(
+        `Path does not exist: ${params.path ?? requested}. Note: your current working directory is ${ctx.cwd}.${suggestion}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+  // 目录：rg 的 cwd 即该目录、目标为 "."；文件：cwd 取其父目录、目标为该文件
+  const searchDir = info.isDirectory() ? requested : dirname(requested);
+  const target = info.isDirectory() ? "." : requested;
+  const { items, truncated } = await runRipgrep(
+    buildGrepArgs(params.pattern, params.include, target),
+    { cwd: searchDir, signal, limit: RIPGREP_RESULT_LIMIT, parse: parseGrepRecord },
+  );
+  const matches = items.map((match) => ({ ...match, path: resolve(searchDir, match.path) }));
+  const fileCount = new Set(matches.map((match) => match.path)).size;
+  return {
+    text: renderGrepOutput(matches, truncated),
+    subtitle:
+      matches.length === 0
+        ? "no matches"
+        : `${matches.length} match${matches.length === 1 ? "" : "es"} in ${fileCount} file${fileCount === 1 ? "" : "s"}${truncated ? " (truncated)" : ""}`,
+  };
+}
+
+export default function opencodeGrep(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "grep",
+    label: "grep",
+    description: [
+      "Fast content search with ripgrep: returns matching file paths with line numbers.",
+      "Hidden files are searched and .git is excluded; results are capped at 100 matches.",
+    ].join("\n"),
+    promptSnippet: "Search file contents with ripgrep",
+    promptGuidelines: [GREP_PROMPT],
+    parameters: Type.Object(
+      {
+        pattern: Type.String({ description: "The regex pattern to search for in file contents" }),
+        path: Type.Optional(
+          Type.String({
+            description: "The file or directory to search in. Defaults to the working directory.",
+          }),
+        ),
+        include: Type.Optional(
+          Type.String({
+            description: 'File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")',
+          }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const { text, subtitle } = await grep(params, ctx, signal);
+      return {
+        content: [{ type: "text" as const, text }],
+        details: { pendant: { subtitle } },
+      };
+    },
+  });
+}

package/src/opencode/index.ts

@@ -1,9 +1,10 @@
 /**
  * opencode —— 统一注册 opencode 风格工具扩展。
  *
- * 聚合 files（read / edit / write 统一构建，共享 LSP service）、todo /
- * question / bash，一次加载全部注册；各工具的公开 API（匹配引擎、纯函数等）
- * 也从这里重新导出，方便测试与其他模块（如 lib/write-guard）引用。
+ * 聚合 files（read / edit / write 统一构建，共享 LSP service）、grep /
+ * glob（ripgrep 搜索）、todo / question / bash，一次加载全部注册；各工具的
+ * 公开 API（匹配引擎、纯函数等）也从这里重新导出，方便测试与其他模块
+ * （如 lib/write-guard）引用。
  *
  * Usage:
  *   pi -e ./opencode/index.ts
@@ -18,6 +19,8 @@ import { createBwrapRuntime } from "../bwrap/runtime.js";
 import { createRequestPolicy } from "../lib/request-policy.js";
 import opencodeBash from "./bash.js";
 import opencodeFileTools from "./files.js";
+import opencodeGlob from "./glob.js";
+import opencodeGrep from "./grep.js";
 import opencodeQuestion from "./question.js";
 import opencodeTodo from "./todo.js";
 
@@ -38,6 +41,8 @@ export {
   resolveBom,
   type TruncationResult,
 } from "./files.js";
+export { default as opencodeGlob } from "./glob.js";
+export { default as opencodeGrep } from "./grep.js";
 export { default as opencodeQuestion } from "./question.js";
 export { default as opencodeTodo } from "./todo.js";
 
@@ -46,6 +51,8 @@ export default function opencode(pi: ExtensionAPI) {
   // 独立入口（web/fetch.ts 等）各自创建一份并经 pi.events 保持同步。
   const policy = createRequestPolicy(pi.events);
   opencodeFileTools(pi, { policy });
+  opencodeGrep(pi);
+  opencodeGlob(pi);
   opencodeTodo(pi);
   opencodeQuestion(pi);
   opencodeBash(pi, createBwrapRuntime(policy));

package/src/opencode/ripgrep.ts

@@ -0,0 +1,159 @@
+/**
+ * ripgrep 运行器，供 opencode 风格 grep / glob 复用。
+ *
+ * 对齐上游 packages/core/src/ripgrep.ts 的 run()：以 `rg` 子进程流式读取
+ * stdout，按解析结果计数，读满 limit + 1 条即杀掉进程提前结束（宽泛 pattern
+ * 不会把整个结果集读进内存）。退出码语义与上游一致：0 成功、1 无匹配、2 部分
+ * 文件读失败（仍返回已收集的结果），正则语法错误单独报错。
+ */
+
+import { spawn } from "node:child_process";
+
+/** 单次搜索最多返回的结果数（上游 limit = 100）。 */
+export const RIPGREP_RESULT_LIMIT = 100;
+
+/** stderr 最多保留的字节数（上游 ERROR_BYTES）。 */
+const ERROR_BYTES = 8 * 1024;
+
+export interface RipgrepRunOptions<R> {
+  cwd: string;
+  signal?: AbortSignal;
+  /** 最多返回的解析结果数；读满 limit + 1 条即终止 rg。 */
+  limit: number;
+  /** 解析一行 stdout；返回 undefined 表示该行不是结果（如 rg 的 begin/end/summary 记录）。 */
+  parse: (line: string) => R | undefined;
+}
+
+export interface RipgrepRunResult<R> {
+  items: R[];
+  /** 结果数超过 limit，已提前终止 rg（可能还有更多结果）。 */
+  truncated: boolean;
+}
+
+const isInvalidPattern = (stderr: string) =>
+  stderr.includes("regex parse error") || stderr.includes("error parsing regex");
+
+/**
+ * 跑一次 rg 并返回解析后的结果。
+ *
+ * 路径类参数用 `--` 与 pattern 分隔，pattern 不会被当成选项；调用方负责给出
+ * `--no-config`、`--glob` 等选项。
+ */
+export function runRipgrep<R>(
+  args: string[],
+  options: RipgrepRunOptions<R>,
+): Promise<RipgrepRunResult<R>> {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn("rg", args, { cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      reject(error instanceof Error ? error : new Error(String(error)));
+      return;
+    }
+
+    const { signal } = options;
+    // 事件回调之间共享的状态放进对象：闭包里的 let 会被 TS 控制流判定为「恒假」，
+    // 触发 eslint 的 no-unnecessary-condition 误报
+    const state = { done: false, settled: false, truncated: false };
+    let stderr = "";
+    let parseError: Error | undefined;
+    let pending = "";
+    const items: R[] = [];
+
+    const stop = () => {
+      if (state.done) return;
+      state.done = true;
+      child.kill("SIGTERM");
+    };
+
+    /** 收尾（resolve/reject 只会发生一次，并摘掉 abort 监听）。 */
+    const settle = (finish: () => void) => {
+      if (state.settled) return;
+      state.settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      finish();
+    };
+
+    const parseLine = (line: string) => {
+      if (state.done || line.length === 0) return;
+      let item: R | undefined;
+      try {
+        item = options.parse(line);
+      } catch (error) {
+        // 解析失败来自事件回调，必须转成 reject，否则会变成未捕获异常
+        parseError = error instanceof Error ? error : new Error(String(error));
+        stop();
+        return;
+      }
+      if (item === undefined) return;
+      items.push(item);
+      if (items.length > options.limit) {
+        state.truncated = true;
+        stop();
+      }
+    };
+
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => {
+      if (stderr.length < ERROR_BYTES) stderr += chunk;
+    });
+
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      pending += chunk;
+      const lines = pending.split("\n");
+      // 末尾没有换行的部分是不完整记录，留到下一块
+      pending = lines.pop() ?? "";
+      for (const line of lines) parseLine(line);
+    });
+
+    child.on("error", (error) => {
+      // spawn 失败（rg 不在 PATH 等）时 close 不保证触发，必须在这里收尾，
+      // 否则 promise 永远不落定，工具调用会挂住
+      settle(() => {
+        reject(
+          (error as NodeJS.ErrnoException).code === "ENOENT"
+            ? new Error("ripgrep (rg) was not found on PATH; install ripgrep to use this tool.", {
+                cause: error,
+              })
+            : error,
+        );
+      });
+    });
+
+    const onAbort = () => stop();
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    // pending 里剩下的内容按定义是不完整记录（rg 的记录一律以 \n 收尾，
+    // 被 kill 时可能停在半条），直接丢掉
+    child.on("close", (code) => {
+      settle(() => {
+        // 取消优先于结果与退出码：调用方靠 throwIfAborted 统一处理取消
+        if (signal?.aborted) {
+          reject(signal.reason instanceof Error ? signal.reason : new Error("Aborted"));
+          return;
+        }
+        if (parseError) {
+          reject(parseError);
+          return;
+        }
+        if (state.truncated) {
+          resolve({ items: items.slice(0, options.limit), truncated: true });
+          return;
+        }
+        const message = stderr.trim();
+        if (code === 2 && isInvalidPattern(message)) {
+          reject(new Error(`Invalid pattern: ${message}`));
+          return;
+        }
+        if (code !== 0 && code !== 1 && code !== 2) {
+          reject(new Error(message || `ripgrep exited with code ${code}`));
+          return;
+        }
+        // 退出码 1 = 无匹配；退出码 2 = 部分文件读失败，已有结果照常返回
+        resolve({ items: code === 1 ? [] : items, truncated: false });
+      });
+    });
+  });
+}

package/src/spawn-agent.ts

@@ -101,12 +101,19 @@ const SETTINGS_PATH = join(getAgentDir(), "settings.json");
  * (read/edit/write) likewise share opencode/files.ts (they share the LSP
  * service instance); that file also registers the shared `lsp-rename` and
  * LSP inspect tools, which stay hidden unless a subagent declares them.
+ *
+ * The lowercase search tools map to the opencode implementations: `grep`
+ * overrides pi's built-in grep, and `glob` adds a tool pi has no built-in for
+ * (its `find` stays available). Each is a self-contained file registering one
+ * tool, so they load independently — `grep` without `glob`.
  */
 const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   read: "opencode/files.ts",
   edit: "opencode/files.ts",
   write: "opencode/files.ts",
   bash: "opencode/bash.ts",
+  grep: "opencode/grep.ts",
+  glob: "opencode/glob.ts",
   Grep: "claude-code/grep.ts",
   Glob: "claude-code/glob.ts",
   Read: "claude-code/files.ts",