@trim21/personal-pi-extensions 0.1.641 → 0.1.643

package/README.md

@@ -137,7 +137,7 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
 写保护直接内置在各写工具（opencode 风格 `write`/`edit`、Claude Code 风格 `Write`/`Edit`）内部，通过 `src/lib/write-guard.ts` 的 `guardWriteAccess` 实现。读取工具（`read`、`ls`、`find`、`grep`）不受限制。
 
 - workspace 内或 `/tmp` 下的路径自动放行
-- 外部路径需通过确认对话框由用户审批（**Approve once** / **Block** / **Block with reason**），对话框内以 ```diff 代码块展示将要发生的变更预览（定位由各写工具注入自己的匹配实现，能定位时显示带行号的真实 patch，否则退化为参数 diff）
+- 外部路径需通过确认对话框由用户审批（**Approve once** / **Block** / **Block with reason**），对话框内以 ```diff 代码块展示将要发生的变更；预览由「将要写入的内容」直接算出，批准后写的就是这份内容（批准前若文件被外部改动则拒绝写入）
 - headless（无 UI）会话直接拒绝外部写入；Windows 上不提供审批路径，工作区外写入一律拒绝
 - `/bwrap-deny-request` 生效期间外部写入按无理由拒绝处理（`user deny <tool>: blocked`）
 - 无需配置，随各写工具自动生效
@@ -253,7 +253,7 @@ opencode 风格工具集，随 `src/opencode/index.ts` 一次加载：`read` / `
 
 ### edit
 
-`edit` 使用 [opencode](https://github.com/anomalyco/opencode) 的 schema 和模糊匹配引擎。核心 replacer 和 `replace()` 函数复制自 opencode，匹配引擎位于 `src/opencode/edit-engine.ts`；写保护审批弹窗（`src/lib/write-guard.ts`）的 diff 预览由调用方注入这套引擎，因此预览与落盘同语义。唯一的有意差异是去掉了原版的转义规范化（EscapeNormalizedReplacer）：它会把源码里合法的 `\n`、`\t` 等转义序列当成模型多转义的产物做启发式反转义，可能改坏内容。
+`edit` 使用 [opencode](https://github.com/anomalyco/opencode) 的 schema 和模糊匹配引擎。核心 replacer 和 `replace()` 函数复制自 opencode，匹配引擎位于 `src/opencode/edit-engine.ts`。唯一的有意差异是去掉了原版的转义规范化（EscapeNormalizedReplacer）：它会把源码里合法的 `\n`、`\t` 等转义序列当成模型多转义的产物做启发式反转义，可能改坏内容。
 
 支持的匹配策略：
 

package/package.json

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

package/src/claude-code/files.ts

@@ -345,31 +345,6 @@ export function registerFileTools(
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
       const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
-      await guardWriteAccess(ctx, {
-        toolName: "Edit",
-        absolutePath: filePath,
-        // 审批预览必须与落盘同语义：这里注入本工具自己的精确匹配（空 old_string
-        // 是创建/填充文件，按整文件写入预览）
-        change:
-          params.old_string === ""
-            ? { kind: "write", newText: params.new_string }
-            : {
-                kind: "edit",
-                oldText: params.old_string,
-                newText: params.new_string,
-                apply: (content) => ({
-                  contentOld: content,
-                  contentNew: applyExactEdit(
-                    content,
-                    params.old_string,
-                    params.new_string,
-                    params.replace_all ?? false,
-                  ),
-                }),
-              },
-        policy,
-        signal,
-      });
       const [message, details, diagnostics] = await withFileMutationQueue<
         [string, FileToolDetails, DiagnosticReport]
       >(filePath, async () => {
@@ -381,11 +356,12 @@ export function registerFileTools(
         // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
         if (oldString === "") {
           let exists = true;
+          let contentOld = "";
           try {
             const value = await stat(filePath);
             if (value.isFile()) {
-              const content = await readFile(filePath, "utf8");
-              if (content.trim() !== "") {
+              contentOld = await readFile(filePath, "utf8");
+              if (contentOld.trim() !== "") {
                 throw new Error("Cannot create new file - file already exists.");
               }
             }
@@ -396,6 +372,14 @@ export function registerFileTools(
               throw error;
             }
           }
+          // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+          await guardWriteAccess(ctx, {
+            toolName: "Edit",
+            absolutePath: filePath,
+            mutation: { contentOld, contentNew: newString },
+            policy,
+            signal,
+          });
           if (!exists) {
             await mkdir(dirname(filePath), { recursive: true });
           }
@@ -458,6 +442,13 @@ export function registerFileTools(
         signal?.throwIfAborted();
         const original = content.toString("utf8");
         const restored = applyExactEdit(original, oldString, newString, replaceAll);
+        await guardWriteAccess(ctx, {
+          toolName: "Edit",
+          absolutePath: filePath,
+          mutation: { contentOld: original, contentNew: restored },
+          policy,
+          signal,
+        });
         await writeFile(filePath, restored, "utf8");
         const snapshot = snapshotOf(restored);
         state.reads.set(key, snapshot);
@@ -532,13 +523,6 @@ export function registerFileTools(
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
       const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
-      await guardWriteAccess(ctx, {
-        toolName: "Write",
-        absolutePath: filePath,
-        change: { kind: "write", newText: params.content },
-        policy,
-        signal,
-      });
       const [message, details, diagnostics] = await withFileMutationQueue<
         [string, FileToolDetails, DiagnosticReport]
       >(filePath, async () => {
@@ -558,6 +542,14 @@ export function registerFileTools(
           }
         }
         signal?.throwIfAborted();
+        // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+        await guardWriteAccess(ctx, {
+          toolName: "Write",
+          absolutePath: filePath,
+          mutation: { contentOld: original ?? "", contentNew: params.content },
+          policy,
+          signal,
+        });
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, params.content, "utf8");
         const snapshot = snapshotOf(params.content);

package/src/lib/lsp/client.ts

@@ -282,21 +282,33 @@ export const clientDefaults = {
   maxOpenDocuments: 32,
 } as const;
 
-export interface CreateInput {
+/**
+ * 客户端可调项的唯一定义：`create()` 的覆盖参数、`lsp.ts` 的 `ResolvedLspConfig`
+ * 与 `resolveConfig` 共用同一份字段集合，新增旋钮只需在这里声明一次即可被
+ * 配置解析与客户端构造同时要求。超时均为解析后的毫秒数，缺省值见 clientDefaults。
+ */
+export interface LspClientOptions {
+  /** push 诊断去抖（ms）。 */
+  diagnosticsDebounceMs: number;
+  /** document 模式诊断等待上限（ms）。 */
+  diagnosticsDocumentWaitTimeoutMs: number;
+  /** 上一份诊断为空的文档的等待上限（ms）；缺省见 clientDefaults。 */
+  diagnosticsSilentWaitTimeoutMs: number;
+  /** full 模式诊断等待上限（ms）。 */
+  diagnosticsFullWaitTimeoutMs: number;
+  /** 单次 pull 诊断请求超时（ms）。 */
+  diagnosticsRequestTimeoutMs: number;
+  /** 服务器 initialize 握手超时（ms）。 */
+  initializeTimeoutMs: number;
+  /** 驻留文档上限（LRU 容量，缺省 32）；超过时淘汰最久未使用并 didClose。 */
+  maxOpenDocuments: number;
+}
+
+export interface CreateInput extends Partial<LspClientOptions> {
   serverID: string;
   server: LspServerHandle;
   root: string;
   directory: string;
-  /** 可覆盖的超时参数（缺省用 client 默认值，由全局/本地 lsp.json 配置注入）。 */
-  diagnosticsDebounceMs?: number;
-  diagnosticsDocumentWaitTimeoutMs?: number;
-  /** 上一份诊断为空的文档的等待上限；缺省见 clientDefaults。 */
-  diagnosticsSilentWaitTimeoutMs?: number;
-  diagnosticsFullWaitTimeoutMs?: number;
-  diagnosticsRequestTimeoutMs?: number;
-  initializeTimeoutMs?: number;
-  /** 驻留文档上限（LRU 容量，缺省 32）；超过时淘汰最久未使用并 didClose。 */
-  maxOpenDocuments?: number;
   /** 覆盖 rename 覆盖校验的轮询节奏（缺省见 DEFAULT_RENAME_VERIFICATION_TIMING）。 */
   renameVerificationTiming?: Partial<RenameVerificationTiming>;
 }

package/src/lib/lsp/lsp.ts

@@ -37,6 +37,7 @@ import {
   type Diagnostic,
   type Info as LspClient,
   type InspectLocation,
+  type LspClientOptions,
   LspMethodNotSupportedError,
   RenameNotPossibleError,
   WATCH_KIND_CHANGE,
@@ -68,7 +69,7 @@ const watchConfigSchema = Type.Object({
   ignore: Type.Optional(Type.Array(Type.String())),
 });
 
-/** lsp.json 的配置项（全局与本地同构；只描述用户可写的原始形态，缺省见 configDefaults）。 */
+/** lsp.json 的配置项（全局与本地同构；只描述用户可写的原始形态，缺省见 watchDefaults / clientDefaults）。 */
 const lspConfigSchema = Type.Object({
   /** 配置文件版本（当前 1）；未知版本会被 typebox 严格校验拒绝。 */
   version: Type.Optional(Type.Number()),
@@ -78,7 +79,7 @@ const lspConfigSchema = Type.Object({
   enabled: Type.Optional(Type.Array(Type.String())),
   /** 从启用集中排除的服务器 id（缺省 = 无）。 */
   disabled: Type.Optional(Type.Array(Type.String())),
-  /** 工作区文件监听配置（缺省全部字段见 configDefaults.watch）。 */
+  /** 工作区文件监听配置（缺省全部字段见 watchDefaults）。 */
   watch: Type.Optional(watchConfigSchema),
   /** 驻留文档上限（LRU 容量），超过时淘汰最久未使用并 didClose。 */
   maxOpenDocuments: Type.Optional(Type.Number({ minimum: 1 })),
@@ -99,18 +100,12 @@ const lspConfigSchema = Type.Object({
 /** 配置值（单文件解析结果）；超时字段为原始写法（number 或字符串），换算在 resolveConfig。 */
 export type LspConfig = Static<typeof lspConfigSchema>;
 
-/**
- * 解析期缺省（单一来源）。超时/LRU 与 client.create 共用 clientDefaults；
- * watch 无 client 对应项，数值在此集中。
- */
-const configDefaults = {
-  watch: {
-    enabled: true,
-    debounceMs: 300,
-    flushMs: 1_000,
-    maxBatch: 500,
-  },
-  maxOpenDocuments: clientDefaults.maxOpenDocuments,
+/** 解析期缺省：watch 段（无 client 对应项，数值在此集中）；客户端参数缺省见 clientDefaults。 */
+const watchDefaults = {
+  enabled: true,
+  debounceMs: 300,
+  flushMs: 1_000,
+  maxBatch: 500,
 } as const;
 
 /** 服务器启动失败后自动重试的冷却（ms）；冷却内跳过，之后下次触碰自动重试。 */
@@ -127,8 +122,12 @@ interface EffectiveWatchConfig {
   ignore: string[];
 }
 
-/** 全局 + 本地合并并解析后的生效配置：所有字段为确定值，无"未配置"歧义。 */
-export interface ResolvedLspConfig {
+/**
+ * 全局 + 本地合并并解析后的生效配置：所有字段为确定值，无"未配置"歧义。
+ * 客户端参数的整体形状复用 `LspClientOptions`（定义在 client.ts，与
+ * `create()` 的覆盖参数同源），因此这里不再逐字段重声明。
+ */
+export interface ResolvedLspConfig extends LspClientOptions {
   /** 合并后的服务器定义（未配置任何服务器时为空表）。 */
   servers: Record<string, ServerConfig>;
   /** enabled 白名单（undefined = 全部启用）。 */
@@ -137,15 +136,6 @@ export interface ResolvedLspConfig {
   disabled: Set<string> | undefined;
   /** 工作区监听配置（缺省值已应用）。 */
   watch: EffectiveWatchConfig;
-  /** 驻留文档 LRU 容量。 */
-  maxOpenDocuments: number;
-  /** 以下超时均为换算后的毫秒数（缺省见 configDefaults / clientDefaults）。 */
-  diagnosticsDebounceMs: number;
-  diagnosticsDocumentWaitTimeoutMs: number;
-  diagnosticsSilentWaitTimeoutMs: number;
-  diagnosticsFullWaitTimeoutMs: number;
-  diagnosticsRequestTimeoutMs: number;
-  initializeTimeoutMs: number;
 }
 
 /** "500" → 500、"5s" → 5000、"1m" → 60000；无效字符串返回 NaN（由调用方兜底缺省）。 */
@@ -177,7 +167,7 @@ function toMs(value: number | string | undefined): number | undefined {
 }
 
 /**
- * 把合并后的原始配置解析为生效配置：应用 configDefaults 缺省、字符串时长换算、
+ * 把合并后的原始配置解析为生效配置：应用 watchDefaults / clientDefaults 缺省、字符串时长换算、
  * 白名单转 Set；per-server 的 workingDir / rootMarkers 互斥校验在此完成
  * （配置解析期抛错，与 enabled 白名单校验同层）。
  */
@@ -195,13 +185,13 @@ export function resolveConfig(raw: LspConfig): ResolvedLspConfig {
     enabled: raw.enabled === undefined ? undefined : new Set(raw.enabled),
     disabled: raw.disabled === undefined ? undefined : new Set(raw.disabled),
     watch: {
-      enabled: raw.watch?.enabled ?? configDefaults.watch.enabled,
-      debounceMs: toMs(raw.watch?.debounceMs) ?? configDefaults.watch.debounceMs,
-      flushMs: configDefaults.watch.flushMs,
-      maxBatch: raw.watch?.maxBatch ?? configDefaults.watch.maxBatch,
+      enabled: raw.watch?.enabled ?? watchDefaults.enabled,
+      debounceMs: toMs(raw.watch?.debounceMs) ?? watchDefaults.debounceMs,
+      flushMs: watchDefaults.flushMs,
+      maxBatch: raw.watch?.maxBatch ?? watchDefaults.maxBatch,
       ignore: raw.watch?.ignore ?? [],
     },
-    maxOpenDocuments: raw.maxOpenDocuments ?? configDefaults.maxOpenDocuments,
+    maxOpenDocuments: raw.maxOpenDocuments ?? clientDefaults.maxOpenDocuments,
     diagnosticsDebounceMs: toMs(raw.diagnosticsDebounceMs) ?? clientDefaults.diagnosticsDebounceMs,
     diagnosticsDocumentWaitTimeoutMs:
       toMs(raw.diagnosticsDocumentWaitTimeoutMs) ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs,
@@ -848,19 +838,22 @@ export function createLspService(
           reportStartupFailure(key, adapter.id, root, "binary not found", notify);
           return;
         }
+        const overrides: Partial<LspClientOptions> = {};
+        if (adapter.diagnosticsWaitMs !== undefined) {
+          overrides.diagnosticsDocumentWaitTimeoutMs = adapter.diagnosticsWaitMs;
+        }
+        if (adapter.startupTimeoutMs !== undefined) {
+          overrides.initializeTimeoutMs = adapter.startupTimeoutMs;
+        }
         const client = await create({
           serverID: adapter.id,
           server: handle,
           root,
           directory: cwd,
-          diagnosticsDebounceMs: config.diagnosticsDebounceMs,
-          diagnosticsDocumentWaitTimeoutMs:
-            adapter.diagnosticsWaitMs ?? config.diagnosticsDocumentWaitTimeoutMs,
-          diagnosticsSilentWaitTimeoutMs: config.diagnosticsSilentWaitTimeoutMs,
-          diagnosticsFullWaitTimeoutMs: config.diagnosticsFullWaitTimeoutMs,
-          diagnosticsRequestTimeoutMs: config.diagnosticsRequestTimeoutMs,
-          initializeTimeoutMs: adapter.startupTimeoutMs ?? config.initializeTimeoutMs,
-          maxOpenDocuments: config.maxOpenDocuments,
+          // 客户端参数整体取自生效配置（ResolvedLspConfig extends LspClientOptions），
+          // 不做逐字段搬运：新增旋钮时漏接线会静默失效，这里靠展开消除该位置。
+          ...config,
+          ...overrides,
         });
         if (state.closing || state.disabled) {
           await client.shutdown();

package/src/lib/lsp/rename-tool.ts

@@ -194,18 +194,14 @@ export function registerLspRenameTool(
       if (applied.length === 0) {
         throw new Error("LSP rename returned no edits");
       }
+      // 先逐个文件审批、再逐个写盘：用户在第二个文件上拒绝时不该留下半个 rename。
+      // 变更前后内容已由 expandWorkspaceEdit 在内存里算好，审批框展示的就是要写入的
+      // 内容；对话框停留期间的外部改动由写保护的指纹校验兜住。
       for (const fileEdit of applied) {
         await guardWriteAccess(ctx, {
           toolName: "lsp-rename",
           absolutePath: fileEdit.path,
-          change: {
-            kind: "edit",
-            oldText: fileEdit.oldText,
-            newText: fileEdit.newText,
-            // LSP 编辑已在内存里展开成整文件的 old/new，落盘是覆盖写：预览直接用
-            // 这一对文本，不必再把整份旧内容交给匹配引擎去找
-            apply: () => ({ contentOld: fileEdit.oldText, contentNew: fileEdit.newText }),
-          },
+          mutation: { contentOld: fileEdit.oldText, contentNew: fileEdit.newText },
           policy: options.policy,
           signal,
         });

package/src/lib/write-guard.ts

@@ -11,17 +11,17 @@
  * - `/bwrap-deny-request` (non-sandbox request policy) refuses outside writes
  *   outright, with the same error as the user picking "Block".
  *
- * Callers have already parsed their tool arguments, so the guard only takes the
- * resolved pieces: the raw target path and the pending change. An edit carries
- * the caller's own matching implementation, so the previewed diff comes from the
- * same semantics that will write the file.
+ * Callers have already parsed their tool arguments and computed the result, so the
+ * guard takes the resolved pieces: the raw target path and the mutation (the file's
+ * content before and after). The preview is rendered from those two strings, so the
+ * approved diff is the change that gets written.
  */
 
-import { readFile } from "node:fs/promises";
 import { basename, isAbsolute, relative, sep } from "node:path";
 
 import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
 
+import { digestIfExists, snapshotOf } from "./file-reads.js";
 import { fenceCodeBlock } from "./markdown.js";
 import type { RequestPolicy } from "./request-policy.js";
 
@@ -59,80 +59,52 @@ function wrapDiff(patch: string): string {
 }
 
 /**
- * 审批预览用的应用函数：把这次改动套到文件内容上，返回 diff 用的前后文本。
- * 必须是该工具落盘时使用的同一套匹配实现——否则对话框展示的 diff 与实际写入
- * 可能不一致。
+ * 待审批的写入：内容由调用方先读盘并算好，批准后按 `contentNew` 落盘。
+ *
+ * 两份内容都是文件原始内容（保留 BOM 与行尾），不是匹配引擎的中间产物——这样
+ * 预览就是磁盘前后的真实对照，批准后的指纹校验也能与磁盘字节逐字节对上。
  */
-export type PendingChangeApply = (fileContent: string) => {
+export interface FileMutation {
+  /** 变更前的完整文件内容（文件不存在时为 ""）。 */
   readonly contentOld: string;
+  /** 变更后的完整内容——即批准后写进磁盘的字节。 */
   readonly contentNew: string;
-};
-
-/** 整文件写入：预览是完整的增删 patch，不需要匹配实现。 */
-export interface FileWriteChange {
-  readonly kind: "write";
-  readonly newText: string;
 }
 
-/**
- * 替换：`apply` 是调用方自己的匹配实现（精确匹配、模糊匹配，或已展开好的整文件
- * 编辑）。匹配不上时抛错即可，写保护会退化为参数 diff。
- */
-export interface FileEditChange {
-  readonly kind: "edit";
-  readonly oldText: string;
-  readonly newText: string;
-  readonly apply: PendingChangeApply;
-}
-
-/** The pending file change, described by the caller from already-parsed args. */
-export type PendingChange = FileWriteChange | FileEditChange;
-
 /** 预览统一按 LF 渲染：CRLF 文件的 diff 每行都带 \r，在对话框里显示成乱码。 */
 function normalizeToLF(text: string): string {
   return text.replaceAll("\r\n", "\n");
 }
 
-/** 参数 diff：调用方的匹配实现报告不出结果时的兜底形式。 */
-function parameterDiff(oldText: string, newText: string): string {
-  const removed = oldText.split("\n").map((line) => `-${line}`);
-  const added = newText.split("\n").map((line) => `+${line}`);
-  return [...removed, ...added].join("\n");
+/** 待审批写入的 diff 代码块：由将落盘的内容直接算出，不做第二次匹配。 */
+export function renderMutationPreview(resolvedPath: string, mutation: FileMutation): string {
+  return wrapDiff(
+    generateUnifiedPatch(
+      basename(resolvedPath),
+      normalizeToLF(mutation.contentOld),
+      normalizeToLF(mutation.contentNew),
+      2,
+    ),
+  );
 }
 
+/** 空内容的指纹：文件不存在与空文件在审批视角下等价。 */
+const EMPTY_DIGEST = snapshotOf("").digest;
+
 /**
- * Build a `diff` code block preview of the pending change.
- * Returns undefined when the diff cannot be computed.
+ * 批准后重新取一次磁盘指纹：用户停留在对话框上的这段时间文件可能被外部改动，
+ * 此时按审批所用的旧内容算出的 `contentNew` 会覆盖别人的改动。
  */
-export async function buildDiffPreview(
-  resolvedPath: string,
-  change: PendingChange,
-): Promise<string | undefined> {
-  let fileContent = "";
-  try {
-    fileContent = await readFile(resolvedPath, "utf8");
-  } catch {
-    // Unreadable or missing file: treat as empty so writes show as full additions.
-  }
-
-  if (change.kind === "write") {
-    // Whole-file write: show the full addition/replacement patch.
-    return wrapDiff(generateUnifiedPatch(basename(resolvedPath), fileContent, change.newText, 2));
+async function requireApprovedContentStillCurrent(opts: WriteGuardOptions): Promise<void> {
+  const { mutation } = opts;
+  if (mutation === undefined) {
+    return;
   }
-
-  // 定位由调用方的匹配实现负责（与其落盘同语义）；匹配不上时退回参数 diff。
-  try {
-    const { contentOld, contentNew } = change.apply(fileContent);
-    return wrapDiff(
-      generateUnifiedPatch(
-        basename(resolvedPath),
-        normalizeToLF(contentOld),
-        normalizeToLF(contentNew),
-        2,
-      ),
+  const current = (await digestIfExists(opts.absolutePath)) ?? EMPTY_DIGEST;
+  if (current !== snapshotOf(mutation.contentOld).digest) {
+    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.",
     );
-  } catch {
-    return wrapDiff(parameterDiff(change.oldText, change.newText));
   }
 }
 
@@ -159,9 +131,10 @@ export interface WriteGuardOptions {
   /** The resolved absolute target path (caller has already parsed its args). */
   absolutePath: string;
   /**
-   * 待审批的变更内容；缺省时审批对话框不展示 diff 预览，仅按路径审批。
+   * 待审批的写入（变更前后的完整内容）；缺省时审批对话框不展示 diff 预览，
+   * 仅按路径审批（流式落盘的工具用不上它）。
    */
-  change?: PendingChange;
+  mutation?: FileMutation;
   /** 调用方所在扩展入口持有的非沙盒请求策略（跨入口一致时绑同一个 pi.events）。 */
   policy: RequestPolicy;
   /** 工具调用的中止信号：透传给审批对话框，工具被取消时对话框一起关掉。 */
@@ -204,7 +177,8 @@ export async function guardWriteAccess(
   }
 
   for (;;) {
-    const diffPreview = opts.change ? await buildDiffPreview(absolutePath, opts.change) : undefined;
+    const diffPreview =
+      opts.mutation === undefined ? undefined : renderMutationPreview(absolutePath, opts.mutation);
     const title =
       `Model requests write access outside workspace:\n\n` +
       `  Tool:  ${opts.toolName}\n` +
@@ -220,6 +194,7 @@ export async function guardWriteAccess(
       throw new Error(`user deny ${opts.toolName}: cancelled`);
     }
     if (choice === "Approve once") {
+      await requireApprovedContentStillCurrent(opts);
       return;
     }
     if (choice === "Block") {

package/src/opencode/files.ts

@@ -632,27 +632,6 @@ function registerEditTool(
 
       const absolutePath = isAbsolute(filePath) ? filePath : resolvePath(ctx.cwd, filePath);
 
-      await guardWriteAccess(ctx, {
-        toolName: "edit",
-        absolutePath,
-        // 审批预览必须与落盘同语义：注入本工具自己的模糊匹配引擎（空 oldString
-        // 是创建新文件，按整文件写入预览）
-        change:
-          oldString === ""
-            ? { kind: "write", newText: newString }
-            : {
-                kind: "edit",
-                oldText: oldString,
-                newText: newString,
-                apply: (content) => {
-                  const applied = applyEdit(content, oldString, newString, replaceAll);
-                  return { contentOld: applied.contentOld, contentNew: applied.contentNew };
-                },
-              },
-        policy,
-        signal,
-      });
-
       const [message, details, diagnostics] = await withFileMutationQueue(
         absolutePath,
         async () => {
@@ -677,6 +656,14 @@ function registerEditTool(
               );
             }
             // opencode: writeWithDirs 自动创建父目录；newString 开头的 BOM 原样保留
+            // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+            await guardWriteAccess(ctx, {
+              toolName: "edit",
+              absolutePath,
+              mutation: { contentOld: "", contentNew: newString },
+              policy,
+              signal,
+            });
             await mkdir(dirname(absolutePath), { recursive: true });
             signal?.throwIfAborted();
             await writeFile(absolutePath, newString, "utf8");
@@ -720,6 +707,13 @@ function registerEditTool(
 
           const applied = applyEdit(rawContent, oldString, newString, replaceAll);
           signal?.throwIfAborted();
+          await guardWriteAccess(ctx, {
+            toolName: "edit",
+            absolutePath,
+            mutation: { contentOld: rawContent, contentNew: applied.finalContent },
+            policy,
+            signal,
+          });
           await writeFile(absolutePath, applied.finalContent, "utf8");
           const snapshot = snapshotOf(applied.finalContent);
           state.reads.set(key, snapshot);
@@ -810,13 +804,6 @@ function registerWriteTool(
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const { filePath: rawPath, content } = params;
       const absolutePath = resolvePath(ctx.cwd, rawPath);
-      await guardWriteAccess(ctx, {
-        toolName: "write",
-        absolutePath,
-        change: { kind: "write", newText: content },
-        policy,
-        signal,
-      });
       const dir = dirname(absolutePath);
 
       const [message, details, diagnostics] = await withFileMutationQueue(
@@ -832,29 +819,31 @@ function registerWriteTool(
           }
 
           // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
-          // 否则用新内容自带的 BOM
+          // 否则用新内容自带的 BOM。旧内容整读一次，既是 BOM 的来源，也是审批预览
+          // 的「变更前内容」。
           let existing: Buffer | undefined;
           try {
-            const fh = await open(absolutePath, "r");
-            try {
-              existing = Buffer.alloc(3);
-              const { bytesRead } = await fh.read(existing, 0, 3, 0);
-              if (bytesRead < 3) {
-                existing = undefined;
-              }
-            } finally {
-              await fh.close();
-            }
+            existing = await readFile(absolutePath);
           } catch {
-            // 文件不存在：无旧 BOM
+            // 文件不存在：无旧文件
           }
           const { bom: desiredBom, text: nextText } = resolveBom(existing, content);
+          const finalContent = desiredBom + nextText;
+
+          // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+          await guardWriteAccess(ctx, {
+            toolName: "write",
+            absolutePath,
+            mutation: { contentOld: existing?.toString("utf8") ?? "", contentNew: finalContent },
+            policy,
+            signal,
+          });
 
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
-          await writeFile(absolutePath, desiredBom + nextText, "utf8");
+          await writeFile(absolutePath, finalContent, "utf8");
           // 写后记账（key 在写入前已算过）：紧接着的 edit 不该再要求重新 read
-          const snapshot = snapshotOf(desiredBom + nextText);
+          const snapshot = snapshotOf(finalContent);
           state.reads.set(key, snapshot);
           const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
             signal,