@trim21/personal-pi-extensions 0.1.572 → 0.1.573

package/README.md

@@ -134,7 +134,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` 不必重新读。
 
 ### 使用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.572",
+  "version": "0.1.573",
   "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);
+    }
+  }
+}

package/src/opencode/bash.md

@@ -4,4 +4,27 @@ 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 `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:
+
+- 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";
@@ -359,7 +375,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 +390,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 +478,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 +497,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 +533,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 +550,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
         content,
         details: {
           ...details,
+          reads: { [key]: snapshot },
           pendant: {
             subtitle: formatSubtitlePath(
               ctx.cwd,
@@ -544,6 +582,7 @@ function registerEditTool(
   pi: ExtensionAPI,
   getService: () => LspService,
   policy: RequestPolicy,
+  state: ReadsState,
 ): void {
   pi.registerTool({
     name: "edit",
@@ -606,12 +645,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 +678,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 +698,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 +756,7 @@ function registerWriteTool(
   pi: ExtensionAPI,
   getService: () => LspService,
   policy: RequestPolicy,
+  state: ReadsState,
 ): void {
   pi.registerTool({
     name: "write",
@@ -712,7 +767,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 +809,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 +846,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 +867,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);
 }