@trim21/personal-pi-extensions 0.1.572 → 0.1.574

package/src/opencode/bash.md

@@ -4,4 +4,29 @@ Executes a given bash command synchronously and returns its output.
 
 Commands run in a sandbox: no write access outside the workspace and no network access. Use the `dangerouslyDisableSandbox` parameter to request unsandboxed execution; the user must approve this request.
 
-Long command output is automatically truncated and the full output is saved to a file. Avoid piping commands through `tail` to limit output unless you have a specific reason.
+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 `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)
+- Communication: Output text directly (NOT echo/printf)
+  While the Bash tool can do similar things, it's better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+- You may specify an optional timeout in milliseconds (up to 7200000ms / 2 hours). By default, your command will timeout after 120000ms (2 minutes).
+- Prefer to use the workdir argument over `cd ...`
+- When issuing multiple commands:
+- If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
+- If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
+- Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
+- DO NOT use newlines to separate commands (newlines are ok in quoted strings).
+- For git commands:
+- Prefer to create a new commit rather than amending an existing commit.
+- Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+- Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+- Avoid unnecessary `sleep` commands:
+- Do not sleep between commands that can run immediately — just run them.
+- Do not retry failing commands in a sleep loop — diagnose the root cause.

package/src/opencode/files.ts

@@ -10,7 +10,13 @@
  *   字符截断、1 起始 offset、目录排序；读取后等待并报告该文档的诊断。
  *   不接 PDF、不接 <system-reminder>；图片 magic 检测保留。
  * - edit：匹配引擎 + 把 old/new 转到文件换行后再替换；写后等待文档诊断。
- * - write：BOM 保留（source.bom || next.bom）；写后同 edit 的诊断输出。
+ *   edit 要求文件已被 read 读过且内容未变（read 记账见下）。
+ * - write：BOM 保留（source.bom || next.bom）；写后同 edit 的诊断输出。write 本身
+ *   不要求先 read，但会刷新记账，保证紧接着的 edit 不必重新 read。
+ *
+ * read 记账：read / edit / write / lsp-rename 各自把受影响文件的内容指纹写进
+ * details.reads（随 session 持久化），session_start / session_tree 时从当前分支
+ * 重放。这是 edit 的 read-before-edit 守卫的基础。
  *
  * 匹配引擎在 edit-engine.ts，也被 lib/write-guard 复用。
  */
@@ -29,6 +35,16 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import {
+  createReadsState,
+  fileDigest,
+  type FileSnapshot,
+  type ReadsState,
+  readStateKey,
+  requireCurrentRead,
+  restoreReads,
+  snapshotOf,
+} from "../lib/file-reads.js";
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
 import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
 import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
@@ -313,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);
 
@@ -359,7 +376,12 @@ async function formatDirectoryEntries(dirPath: string): Promise<string[]> {
   return results;
 }
 
-function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void {
+// ── read-before-edit 记账 ────────────────────────────────────────────────────
+
+/** 会更新 reads 记账（src/lib/file-reads.ts）并随 details 持久化快照的工具名。 */
+const READS_TOOL_NAMES = new Set(["read", "edit", "write", "lsp-rename"]);
+
+function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state: ReadsState): void {
   pi.registerTool({
     name: "read",
     label: "read",
@@ -369,7 +391,10 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
       "Use read to examine files instead of cat, sed, or tail. A negative offset reads from the end of the file (offset=-2 reads the last 2 lines).",
     ],
     parameters: Type.Object({
-      filePath: Type.String({ description: "The absolute path to the file or directory to read" }),
+      filePath: Type.String({
+        description:
+          "The path to the file or directory to read (absolute or relative to the working directory)",
+      }),
       offset: Type.Optional(
         Type.Integer({
           description:
@@ -454,9 +479,15 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
           { type: "text", text: "Image read successfully" },
           { type: "image", data: base64, mimeType },
         ];
+        const key = await readStateKey(absolutePath);
+        const snapshot = snapshotOf(buffer, false);
+        state.reads.set(key, snapshot);
         return {
           content,
-          details: { pendant: { subtitle: formatSubtitlePath(ctx.cwd, absolutePath) } },
+          details: {
+            reads: { [key]: snapshot },
+            pendant: { subtitle: formatSubtitlePath(ctx.cwd, absolutePath) },
+          },
         };
       }
 
@@ -467,6 +498,11 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
         };
       }
 
+      // 记账指纹先于分页读取：文件若在读取期间被改动，指纹对应的是改动前的
+      // 内容，后续 edit 会要求重新 read（失败方向安全）。
+      const key = await readStateKey(absolutePath);
+      const snapshot: FileSnapshot = { digest: await fileDigest(absolutePath), textEditable: true };
+
       const effectiveOffset = offset || 1;
       const page = await readLines(absolutePath, {
         offset: effectiveOffset,
@@ -498,6 +534,8 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
         outputText = `${header}${numbered}\n\n(End of file - total ${page.count} lines)${footer}`;
       }
 
+      state.reads.set(key, snapshot);
+
       // opencode: 与 edit / write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
       const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
         signal,
@@ -513,6 +551,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
         content,
         details: {
           ...details,
+          reads: { [key]: snapshot },
           pendant: {
             subtitle: formatSubtitlePath(
               ctx.cwd,
@@ -544,6 +583,7 @@ function registerEditTool(
   pi: ExtensionAPI,
   getService: () => LspService,
   policy: RequestPolicy,
+  state: ReadsState,
 ): void {
   pi.registerTool({
     name: "edit",
@@ -606,12 +646,16 @@ function registerEditTool(
             await mkdir(dirname(absolutePath), { recursive: true });
             signal?.throwIfAborted();
             await writeFile(absolutePath, newString, "utf8");
+            // 新建文件无需先 read（无处可读），写后记账；realpath 要等文件落盘
+            const key = await readStateKey(absolutePath);
+            const snapshot = snapshotOf(newString);
+            state.reads.set(key, snapshot);
             const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
               signal,
             });
             return [
               "Edit applied successfully.",
-              { diff: "", patch: "", firstChangedLine: 0 },
+              { diff: "", patch: "", firstChangedLine: 0, reads: { [key]: snapshot } },
               diagnostics,
             ] as const;
           }
@@ -635,10 +679,16 @@ function registerEditTool(
             throw new Error(`Could not edit file: ${filePath}. ${msg}.`, { cause: error });
           }
 
+          // 指纹校验必须发生在写入之前：未 read 或外部已改动都拒绝编辑
           const rawContent = await readFile(absolutePath, "utf8");
+          const key = await readStateKey(absolutePath);
+          requireCurrentRead(state, key, absolutePath, rawContent);
+
           const applied = applyEdit(rawContent, oldString, newString, replaceAll);
           signal?.throwIfAborted();
           await writeFile(absolutePath, applied.finalContent, "utf8");
+          const snapshot = snapshotOf(applied.finalContent);
+          state.reads.set(key, snapshot);
 
           const diffOld = normalizeToLF(applied.contentOld);
           const diffNew = normalizeToLF(applied.contentNew);
@@ -649,7 +699,12 @@ function registerEditTool(
           });
           return [
             "Edit applied successfully.",
-            { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },
+            {
+              diff: diffResult.diff,
+              patch,
+              firstChangedLine: diffResult.firstChangedLine,
+              reads: { [key]: snapshot },
+            },
             diagnostics,
           ] as const;
         },
@@ -702,6 +757,7 @@ function registerWriteTool(
   pi: ExtensionAPI,
   getService: () => LspService,
   policy: RequestPolicy,
+  state: ReadsState,
 ): void {
   pi.registerTool({
     name: "write",
@@ -712,7 +768,8 @@ function registerWriteTool(
     promptGuidelines: ["Use write only for new files or complete rewrites."],
     parameters: Type.Object({
       filePath: Type.String({
-        description: "The absolute path to the file to write (must be absolute, not relative)",
+        description:
+          "The path to the file to write (absolute or relative to the working directory)",
       }),
       content: Type.String({ description: "The content to write to the file" }),
     }),
@@ -753,11 +810,15 @@ function registerWriteTool(
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
           await writeFile(absolutePath, desiredBom + nextText, "utf8");
+          // write 不要求先 read，但写后记账：紧接着的 edit 不该再要求重新 read
+          const key = await readStateKey(absolutePath);
+          const snapshot = snapshotOf(desiredBom + nextText);
+          state.reads.set(key, snapshot);
           const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
             signal,
           });
 
-          return ["Wrote file successfully.", {}, diagnostics] as const;
+          return ["Wrote file successfully.", { reads: { [key]: snapshot } }, diagnostics] as const;
         },
       );
 
@@ -786,10 +847,11 @@ export function registerFileTools(
   pi: ExtensionAPI,
   getService: () => LspService,
   policy: RequestPolicy,
+  state: ReadsState,
 ): void {
-  registerReadTool(pi, getService);
-  registerEditTool(pi, getService, policy);
-  registerWriteTool(pi, getService, policy);
+  registerReadTool(pi, getService, state);
+  registerEditTool(pi, getService, policy, state);
+  registerWriteTool(pi, getService, policy, state);
   // lsp-rename / inspect 工具由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
@@ -806,16 +868,42 @@ export default function opencodeFileTools(
   // 聚合入口（index.ts）注入与 bash runtime 共享的那一份；独立入口自建并靠
   // pi.events 跟随同一开关。
   const policy = options?.policy ?? createRequestPolicy(pi.events);
+  const state = createReadsState();
   const manager = createLspManager(
     pi,
     {
       onEnabled: (pi, service) => {
-        registerLspRenameTool(pi, service, { policy });
+        registerLspRenameTool(pi, service, {
+          policy,
+          recordReads: async (applied) => {
+            const reads: Record<string, FileSnapshot> = {};
+            for (const fileEdit of applied) {
+              const key = await readStateKey(fileEdit.path);
+              const snapshot = snapshotOf(fileEdit.newText);
+              state.reads.set(key, snapshot);
+              reads[key] = snapshot;
+            }
+            return reads;
+          },
+        });
         registerLspInspectTools(pi, service);
       },
     },
     options,
   );
+
+  // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的已读
+  // 记账随之丢失，这里从当前分支的历史工具结果恢复；digest 仍是当时的值，文件
+  // 若在此期间被外部修改，edit 时的指纹对比照样要求重新 read。
+  pi.on("session_start", (_event, ctx) => {
+    restoreReads(state, ctx.sessionManager, READS_TOOL_NAMES);
+  });
+  // rewind / 树内跳转走 branch()，只发 session_tree：重放当前分支，丢弃被抛弃
+  // 分支的记账，避免 state 与当前分支脱节。
+  pi.on("session_tree", (_event, ctx) => {
+    restoreReads(state, ctx.sessionManager, READS_TOOL_NAMES);
+  });
+
   // 文件工具无条件注册；service 惰性获取，disabled 时为 no-op。
-  registerFileTools(pi, () => manager.mustLazyGetService(), policy);
+  registerFileTools(pi, () => manager.mustLazyGetService(), policy, state);
 }

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));