@trim21/personal-pi-extensions 0.1.572 → 0.1.574

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`
@@ -134,7 +136,9 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
 - 上下文感知匹配（ContextAwareReplacer）
 - 多次出现替换（MultiOccurrenceReplacer）
 
-所有匹配策略按顺序尝试，第一个匹配成功即返回。同时自动处理 BOM、CRLF/LF 行尾转换和文件写入队列。
+所有匹配策略按顺序尝试，第一个匹配成功即返回。同时自动处理 BOM、CRLF/LF 行尾转换和文件写入队列。`filePath` 接受绝对路径或相对工作目录的路径。
+
+edit 要求目标文件已被 `read` 读过且内容未变（内容指纹比对，与 Claude Code 风格 Edit 同一套语义）：没读过报 `File has not been read yet. Read it first before editing it.`，读后文件被外部改动报 `File has been modified since read...`，两种情况都要重新 `read`。`read`/`edit`/`write`/`lsp-rename` 都会刷新记账并随工具结果持久化，session 恢复 / fork / rewind 后依然有效；`write` 本身不要求先读，但写后会刷新记账，紧随其后的 `edit` 不必重新读。
 
 ### 使用
 
@@ -144,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.572",
+  "version": "0.1.574",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/claude-code/common.ts

@@ -1,40 +1,15 @@
 import { readdirSync } from "node:fs";
 import { realpath, stat } from "node:fs/promises";
-import {
-  basename,
-  dirname,
-  extname,
-  isAbsolute,
-  join,
-  normalize,
-  relative,
-  resolve,
-  sep,
-} from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-import { type Static, Type } from "typebox";
-import { Value } from "typebox/value";
+import { resolvePathArg } from "../lib/path.js";
 
-const fileSnapshotSchema = Type.Object({
-  digest: Type.String(),
-  textEditable: Type.Boolean(),
-});
-
-export type FileSnapshot = Static<typeof fileSnapshotSchema>;
-
-export interface ClaudeCodeState {
-  readonly reads: Map<string, FileSnapshot>;
-}
-
-export function createClaudeCodeState(): ClaudeCodeState {
-  return { reads: new Map() };
-}
-
-export function requireAbsolutePath(filePath: string, parameter = "file_path"): string {
-  if (!isAbsolute(filePath)) {
-    throw new Error(`The ${parameter} parameter must be an absolute path, not a relative path.`);
-  }
-  return normalize(filePath);
+/**
+ * 解析 `file_path`：绝对路径规整化后原样使用，相对路径（含 `~` 前缀）按调用
+ * cwd 展开。工具内部一律用解析后的绝对路径，写保护与 reads 记账都依赖它。
+ */
+export function resolveToolFilePath(filePath: string, cwd: string): string {
+  return resolve(resolvePathArg(cwd, filePath));
 }
 
 /** Resolve a search root path against the working directory. */
@@ -49,10 +24,6 @@ export function toRelativePath(filePath: string, cwd: string): string {
   return relativePath.startsWith("..") ? filePath : relativePath;
 }
 
-export function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
-  return left.digest === right.digest;
-}
-
 /**
  * 同目录下"同名不同扩展名"的文件（如请求 foo.ts 不存在，目录里有 foo.js），
  * 对齐 Claude Code 的 findSimilarFile。返回文件名（不含路径）。
@@ -114,17 +85,3 @@ export async function didYouMean(filePath: string, cwd: string): Promise<string
   if (cwdSuggestion) return cwdSuggestion;
   return findSimilarFile(filePath);
 }
-
-/**
- * 从工具结果 details 里恢复文件已读记账（跨进程 resume / reload / fork）。
- * 数据来自 session 文件，可能缺失或损坏：逐条 TypeBox 校验，非法条目丢弃。
- * 只接受 plain object，数组、null 等异常形态直接返回空 map。
- */
-export function deserializeReads(data: unknown): Map<string, FileSnapshot> {
-  const reads = new Map<string, FileSnapshot>();
-  if (typeof data !== "object" || data === null || Array.isArray(data)) return reads;
-  for (const [filePath, snapshot] of Object.entries(data)) {
-    if (Value.Check(fileSnapshotSchema, snapshot)) reads.set(filePath, snapshot);
-  }
-  return reads;
-}

package/src/claude-code/edit-utils.ts

@@ -1,120 +1,12 @@
 /**
- * Claude Code 风格 Edit 的字符串匹配工具（移植自真实 Claude Code 的
- * FileEditTool/utils.ts）。
+ * Claude Code 风格 Edit 的展示辅助。
  *
- * - findActualString：先精确匹配，失败则做引号规范化匹配（文件里的花引号
- *   与模型输出的直引号等价），返回文件中的真实文本；
- * - preserveQuoteStyle：当 old_string 通过引号规范化命中时，把 new_string
- *   里的直引号换成文件使用的花引号风格，保持文件的排版一致。
+ * 上游 Claude Code 还带一套引号规范化（花引号与直引号互相等价匹配，并把
+ * new_string 改写成文件的花引号风格），这里刻意没有移植：它无法用语言语法
+ * 判断两个引号是否语义等价（markdown 里 `'` 与 `’` 就是两个字符），而且会
+ * 替模型改写它没有写的字符。Edit 只做精确匹配。
  */
 
-export const LEFT_SINGLE_CURLY_QUOTE = "‘";
-export const RIGHT_SINGLE_CURLY_QUOTE = "’";
-export const LEFT_DOUBLE_CURLY_QUOTE = "“";
-export const RIGHT_DOUBLE_CURLY_QUOTE = "”";
-
-/** 把花引号规范化为直引号（匹配与替换两侧都用它做归一）。 */
-export function normalizeQuotes(str: string): string {
-  return str
-    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
-    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
-    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
-    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"');
-}
-
-/**
- * 在文件内容中查找与搜索串匹配的实际文本。
- * 先精确匹配；失败则把两侧花引号归一为直引号后重试，返回文件中的原文。
- */
-export function findActualString(fileContent: string, searchString: string): string | null {
-  if (fileContent.includes(searchString)) return searchString;
-  const normalizedSearch = normalizeQuotes(searchString);
-  const normalizedFile = normalizeQuotes(fileContent);
-  const searchIndex = normalizedFile.indexOf(normalizedSearch);
-  if (searchIndex !== -1) {
-    return fileContent.slice(searchIndex, searchIndex + searchString.length);
-  }
-  return null;
-}
-
-/** 引号前是空白/行首/开括号/破折号时视为开引号，否则视为闭引号。 */
-function isOpeningContext(chars: string[], index: number): boolean {
-  if (index === 0) return true;
-  const prev = chars[index - 1];
-  return (
-    prev === " " ||
-    prev === "\t" ||
-    prev === "\n" ||
-    prev === "\r" ||
-    prev === "(" ||
-    prev === "[" ||
-    prev === "{" ||
-    prev === "\u2014" || // em dash
-    prev === "\u2013" // en dash
-  );
-}
-
-function applyCurlyDoubleQuotes(str: string): string {
-  const chars = [...str];
-  const result: string[] = [];
-  for (let i = 0; i < chars.length; i++) {
-    if (chars[i] === '"') {
-      result.push(isOpeningContext(chars, i) ? LEFT_DOUBLE_CURLY_QUOTE : RIGHT_DOUBLE_CURLY_QUOTE);
-    } else {
-      result.push(chars[i]);
-    }
-  }
-  return result.join("");
-}
-
-function applyCurlySingleQuotes(str: string): string {
-  const chars = [...str];
-  const result: string[] = [];
-  for (let i = 0; i < chars.length; i++) {
-    if (chars[i] === "'") {
-      // 缩写中的撇号（如 don't）用右花引号，不做开/闭判断
-      const prev = i > 0 ? chars[i - 1] : "";
-      const next = i + 1 < chars.length ? chars[i + 1] : "";
-      const prevIsLetter = /\p{L}/u.test(prev);
-      const nextIsLetter = /\p{L}/u.test(next);
-      if (prevIsLetter && nextIsLetter) {
-        result.push(RIGHT_SINGLE_CURLY_QUOTE);
-      } else {
-        result.push(
-          isOpeningContext(chars, i) ? LEFT_SINGLE_CURLY_QUOTE : RIGHT_SINGLE_CURLY_QUOTE,
-        );
-      }
-    } else {
-      result.push(chars[i]);
-    }
-  }
-  return result.join("");
-}
-
-/**
- * 当 old_string 通过引号规范化命中（oldString !== actualOldString）时，
- * 把 new_string 中的直引号换成文件实际使用的花引号风格。
- */
-export function preserveQuoteStyle(
-  oldString: string,
-  actualOldString: string,
-  newString: string,
-): string {
-  if (oldString === actualOldString) return newString;
-  const hasDoubleQuotes =
-    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
-    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE);
-  const hasSingleQuotes =
-    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
-    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE);
-  if (!hasDoubleQuotes && !hasSingleQuotes) return newString;
-
-  let result = newString;
-  if (hasDoubleQuotes) result = applyCurlyDoubleQuotes(result);
-  if (hasSingleQuotes) result = applyCurlySingleQuotes(result);
-  return result;
-}
-
 /**
  * patch 显示用：把行首 tab 转成 2 空格（对齐 Claude Code 的
  * convertLeadingTabsToSpaces）。仅用于 details 里展示的 diff，不影响写盘内容。

package/src/claude-code/files.ts

@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto";
 import { constants, readFileSync, type Stats } from "node:fs";
-import { access, mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, extname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -14,6 +13,15 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import {
+  createReadsState,
+  type FileSnapshot,
+  type ReadsState,
+  readStateKey,
+  requireCurrentRead,
+  restoreReads,
+  snapshotOf,
+} from "../lib/file-reads.js";
 import { appendLspDiagnosticText, type DiagnosticReport } from "../lib/lsp/diagnostic.js";
 import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
 import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
@@ -22,16 +30,8 @@ import { formatSubtitlePath } from "../lib/path.js";
 import type { ToolPendant } from "../lib/pendant.ts";
 import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
-import {
-  type ClaudeCodeState,
-  createClaudeCodeState,
-  deserializeReads,
-  didYouMean,
-  type FileSnapshot,
-  requireAbsolutePath,
-  snapshotsEqual,
-} from "./common.js";
-import { convertLeadingTabsToSpaces, findActualString, preserveQuoteStyle } from "./edit-utils.js";
+import { didYouMean, resolveToolFilePath } from "./common.js";
+import { convertLeadingTabsToSpaces } from "./edit-utils.js";
 
 const SAMPLE_BYTES = 4096;
 
@@ -76,10 +76,6 @@ export interface FileToolDetails {
   reads?: Record<string, FileSnapshot>;
 }
 
-function snapshotOf(content: Uint8Array | string, textEditable = true): FileSnapshot {
-  return { digest: createHash("sha256").update(content).digest("hex"), textEditable };
-}
-
 async function assertReadableFile(filePath: string): Promise<Stats> {
   const value = await stat(filePath);
   if (value.isDirectory()) {
@@ -192,53 +188,9 @@ export function exactReplace(
   return content.slice(0, index) + newString + content.slice(index + oldString.length);
 }
 
-/**
- * reads 记账 key：解析 symlink 后的真实路径，与 withFileMutationQueue 的队列
- * key 对齐。文件尚不存在（Write 新建 / Edit 空 old_string 创建）时 realpath
- * 抛 ENOENT，回退到已规范化路径。
- */
-async function readStateKey(filePath: string): Promise<string> {
-  try {
-    return await realpath(filePath);
-  } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error.code === "ENOENT" || error.code === "ENOTDIR")
-    ) {
-      return filePath;
-    }
-    throw error;
-  }
-}
-
-/**
- * 校验「已读且未变」。key 与 currentContent 由调用方提供：调用方每次工具调用
- * 只 realpath / readFile 一次，避免重复 IO。
- */
-function requireCurrentRead(
-  state: ClaudeCodeState,
-  key: string,
-  filePath: string,
-  currentContent: Uint8Array,
-): void {
-  const readSnapshot = state.reads.get(key);
-  if (!readSnapshot) {
-    throw new Error("File has not been read yet. Read it first before writing to it.");
-  }
-  if (!readSnapshot.textEditable) {
-    throw new Error(`Cannot edit or overwrite a binary file with a text tool: ${filePath}`);
-  }
-  if (!snapshotsEqual(readSnapshot, snapshotOf(currentContent))) {
-    throw new Error(
-      "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.",
-    );
-  }
-}
-
 export function registerFileTools(
   pi: ExtensionAPI,
-  state: ClaudeCodeState,
+  state: ReadsState,
   getService: () => LspService,
   policy: RequestPolicy,
 ): void {
@@ -248,7 +200,7 @@ export function registerFileTools(
     description: [
       "Reads a file from the local filesystem. You can access any file directly using this tool.",
       "Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.",
-      "The file_path parameter must be an absolute path. By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit.",
+      "The file_path parameter accepts an absolute path or a path relative to the working directory. By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit.",
       "Read parts of files with offset and limit instead of running head/tail via Bash: a positive offset is the starting line number, a negative offset counts from the end of the file (offset=-5 reads the last 5 lines, like tail -n 5).",
       "Results use cat -n style line numbers starting at 1. Images are returned visually.",
       "This tool reads files, not directories.",
@@ -257,7 +209,10 @@ export function registerFileTools(
     promptGuidelines: [READ_PROMPT],
     parameters: Type.Object(
       {
-        file_path: Type.String({ description: "The absolute path to the file to read" }),
+        file_path: Type.String({
+          description:
+            "The path to the file to read (absolute or relative to the working directory)",
+        }),
         offset: Type.Optional(
           Type.Integer({
             description:
@@ -273,7 +228,7 @@ export function registerFileTools(
     ),
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
-      const filePath = requireAbsolutePath(params.file_path);
+      const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
       if (params.offset !== undefined && !Number.isSafeInteger(params.offset)) {
         throw new Error("offset must be an integer");
       }
@@ -389,7 +344,10 @@ export function registerFileTools(
     promptGuidelines: [EDIT_PROMPT],
     parameters: Type.Object(
       {
-        file_path: Type.String({ description: "The absolute path to the file to modify" }),
+        file_path: Type.String({
+          description:
+            "The path to the file to modify (absolute or relative to the working directory)",
+        }),
         old_string: Type.String({ description: "The text to replace" }),
         new_string: Type.String({
           description: "The text to replace it with (must be different from old_string)",
@@ -402,7 +360,7 @@ export function registerFileTools(
     ),
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
-      const filePath = requireAbsolutePath(params.file_path);
+      const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
       await guardWriteAccess(ctx, {
         toolName: "Edit",
         absolutePath: filePath,
@@ -505,8 +463,7 @@ export function registerFileTools(
         const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
         const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
         const normalized = original.replaceAll("\r\n", "\n");
-        const actualOldString = findActualString(normalized, oldString) ?? oldString;
-        const matches = normalized.split(actualOldString).length - 1;
+        const matches = normalized.split(oldString).length - 1;
         if (matches === 0) {
           throw new Error(`String to replace not found in file.\nString: ${oldString}`);
         }
@@ -515,22 +472,21 @@ export function registerFileTools(
             `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
           );
         }
-        const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
         // 删除场景（new_string 为空）：old_string 不以换行结尾且文件里是
         // "old_string\n" 时连换行一起删，避免留下空行（对齐 Claude Code
         // applyEditToFile 的 stripTrailingNewline 语义）
-        let searchString = actualOldString;
+        let searchString = oldString;
         if (
-          actualNewString === "" &&
-          !actualOldString.endsWith("\n") &&
-          normalized.includes(actualOldString + "\n")
+          newString === "" &&
+          !oldString.endsWith("\n") &&
+          normalized.includes(oldString + "\n")
         ) {
-          searchString = actualOldString + "\n";
+          searchString = oldString + "\n";
         }
         // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
         const updated = replaceAll
-          ? normalized.split(searchString).join(actualNewString)
-          : normalized.replace(searchString, () => actualNewString);
+          ? normalized.split(searchString).join(newString)
+          : normalized.replace(searchString, () => newString);
         const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
         await writeFile(filePath, restored, "utf8");
         const snapshot = snapshotOf(restored);
@@ -596,7 +552,8 @@ export function registerFileTools(
     parameters: Type.Object(
       {
         file_path: 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" }),
       },
@@ -604,7 +561,7 @@ export function registerFileTools(
     ),
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
-      const filePath = requireAbsolutePath(params.file_path);
+      const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
       await guardWriteAccess(ctx, {
         toolName: "Write",
         absolutePath: filePath,
@@ -684,24 +641,11 @@ export function registerFileTools(
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */
 const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write", "lsp-rename"]);
 
-/**
- * 从当前分支的历史工具结果重建已读记账。先清空再重放，保证 state 只反映
- * 当前分支：rewind / fork / resume 后，被抛弃分支上的 Read 不再残留。
- */
 function restoreFileReads(
-  state: ClaudeCodeState,
+  state: ReadsState,
   sessionManager: ExtensionContext["sessionManager"],
 ): void {
-  state.reads.clear();
-  for (const entry of sessionManager.getBranch()) {
-    if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
-    if (!FILE_TOOL_NAMES.has(entry.message.toolName)) continue;
-    const details = entry.message.details as { reads?: unknown } | undefined;
-    if (!details?.reads) continue;
-    for (const [filePath, snapshot] of deserializeReads(details.reads)) {
-      state.reads.set(filePath, snapshot);
-    }
-  }
+  restoreReads(state, sessionManager, FILE_TOOL_NAMES);
 }
 
 export interface ClaudeCodeFileToolOptions extends LspServiceOptions {
@@ -719,7 +663,7 @@ export default function claudeCodeFileTools(
   pi: ExtensionAPI,
   options?: ClaudeCodeFileToolOptions,
 ): void {
-  const state = createClaudeCodeState();
+  const state = createReadsState();
   // 聚合入口（index.ts）注入与 bash runtime 共享的那一份；独立入口（spawn-agent
   // 按工具名 `-e` 加载本文件）自建一份，靠 pi.events 跟随同一开关。
   const policy = options?.policy ?? createRequestPolicy(pi.events);

package/src/claude-code/read.md

@@ -4,7 +4,7 @@ Reads a file from the local filesystem. You can access any file directly by usin
 
 Usage:
 
-- The file_path parameter must be an absolute path, not a relative path
+- The file_path parameter accepts an absolute path or a path relative to the working directory
 - By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit to read specific portions
 - When you already know which part of the file you need, only read that part. This can be important for larger files.
 - Do not use head/tail (or sed -n) via the Bash tool to read parts of files — use offset and limit here instead. They are line-based: `offset=5, limit=10` reads 10 lines starting at line 5 (like `sed -n '5,14p'`), and a negative offset counts from the end of the file — `offset=-5` reads the last 5 lines (like `tail -n 5`). Line numbers in the output are always absolute.

package/src/lib/file-reads.ts

@@ -0,0 +1,125 @@
+/**
+ * read-before-edit 记账：已读文件的内容指纹快照 + 会话分支重放。
+ *
+ * claude-code 与 opencode 两套工具集共用这一份机制（守卫语义、错误文案、
+ * details.reads 格式一致），差异只有两点：
+ * - 工具名集合：claude-code 是大写 Read/Edit/Write，opencode 是小写；
+ * - 指纹来源：claude-code 手里已有内容，直接 snapshotOf(content)；opencode 的
+ *   read 是流式分页读取，整文件指纹用 fileDigest(path)。
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { realpath } from "node:fs/promises";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+const fileSnapshotSchema = Type.Object({
+  digest: Type.String(),
+  textEditable: Type.Boolean(),
+});
+
+export type FileSnapshot = Static<typeof fileSnapshotSchema>;
+
+/** 已读文件记账：key 为解析 symlink 后的路径 → 读取时的内容指纹。 */
+export interface ReadsState {
+  readonly reads: Map<string, FileSnapshot>;
+}
+
+export function createReadsState(): ReadsState {
+  return { reads: new Map() };
+}
+
+export function snapshotOf(content: Uint8Array | string, textEditable = true): FileSnapshot {
+  return { digest: createHash("sha256").update(content).digest("hex"), textEditable };
+}
+
+/** 整文件指纹：流式读取，避免为记账把大文件整个读进内存。 */
+export async function fileDigest(filePath: string): Promise<string> {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(filePath)) {
+    hash.update(chunk as Buffer);
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * 记账 key：解析 symlink 后的真实路径。文件尚不存在（Write 新建 / Edit 空
+ * old_string 创建）时 realpath 抛 ENOENT，回退到调用方给出的路径。
+ */
+export async function readStateKey(filePath: string): Promise<string> {
+  try {
+    return await realpath(filePath);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return filePath;
+    }
+    throw error;
+  }
+}
+
+export function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
+  return left.digest === right.digest;
+}
+
+/** 校验「已读且未变」：未读过、非文本、指纹不符都拒绝写入。 */
+export function requireCurrentRead(
+  state: ReadsState,
+  key: string,
+  filePath: string,
+  currentContent: Uint8Array | string,
+): void {
+  const readSnapshot = state.reads.get(key);
+  if (!readSnapshot) {
+    throw new Error("File has not been read yet. Read it first before writing to it.");
+  }
+  if (!readSnapshot.textEditable) {
+    throw new Error(`Cannot edit or overwrite a binary file with a text tool: ${filePath}`);
+  }
+  if (!snapshotsEqual(readSnapshot, snapshotOf(currentContent))) {
+    throw new Error(
+      "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.",
+    );
+  }
+}
+
+/**
+ * 从工具结果 details 恢复已读记账（跨进程 resume / reload / fork）。数据来自
+ * session 文件，可能缺失或损坏：逐条 TypeBox 校验，非法条目丢弃。只接受
+ * plain object，数组、null 等异常形态直接返回空 map。
+ */
+export function deserializeReads(data: unknown): Map<string, FileSnapshot> {
+  const reads = new Map<string, FileSnapshot>();
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return reads;
+  for (const [filePath, snapshot] of Object.entries(data)) {
+    if (Value.Check(fileSnapshotSchema, snapshot)) reads.set(filePath, snapshot);
+  }
+  return reads;
+}
+
+/**
+ * 先清空再重放当前分支，保证 state 只反映当前分支：rewind / fork / resume 后，
+ * 被抛弃分支上的已读不再残留。工具名集合由调用方给出（两套工具集大小写不同）。
+ */
+export function restoreReads(
+  state: ReadsState,
+  sessionManager: ExtensionContext["sessionManager"],
+  toolNames: ReadonlySet<string>,
+): void {
+  state.reads.clear();
+  for (const entry of sessionManager.getBranch()) {
+    if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+    if (!toolNames.has(entry.message.toolName)) continue;
+    const details = entry.message.details as { reads?: unknown } | undefined;
+    if (!details?.reads) continue;
+    for (const [filePath, snapshot] of deserializeReads(details.reads)) {
+      state.reads.set(filePath, snapshot);
+    }
+  }
+}