@trim21/personal-pi-extensions 0.1.679 → 0.1.681

package/README.md

@@ -31,24 +31,31 @@
 
 `codemode` 让模型写一段 JavaScript（作为 async 函数体，`await` 与 `return` 都可用），在
 进程内的 worker 线程里用 QuickJS wasm VM 执行。VM 里没有 node、文件系统、网络、timer
-或模块加载，脚本唯一的出口是 `call(name, args)`。
-
-- **嵌套调用经工具总线**：`call("Read", { file_path })` 最终执行的是 `Read` 工具自己的
-  `execute`，所以工具的审批照常生效（写工作区外会弹 write-guard，Bash 沙箱外执行会弹
-  自己的提权确认）。codemode 不额外加确认层：脚本里连发十次写操作就是十次工具自己的
-  审批（需要审批的那些）。
-- **可调用集合** = 总线上实际注册的工具减去 `codemode` 自身，执行时再与当前 active
-  列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` / `--tools`、
-  子代理的工具白名单都同样约束脚本。
+或模块加载，脚本的出口只有 `call(name, args)` 与 `fs.read` / `fs.write` 两个文件原语。
+
+- **嵌套调用经工具总线**：`call("Bash", { command })` 最终执行的是 `Bash` 工具自己的
+  `execute`，所以工具的审批照常生效（Bash 沙箱外执行会弹自己的提权确认）。codemode
+  不额外加确认层：脚本里连发十次调用就是十次工具自己的审批（需要审批的那些）。
+- **可调用集合** = 总线上实际注册的工具减去排除名单（`codemode` 自身、`spawn-agent`、
+  以及两套文件工具集的 `Read`/`Edit`/`Write` 与 `read`/`edit`/`write`），执行时再与当前
+  active 列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` /
+  `--tools`、子代理的工具白名单都同样约束脚本。
+- **文件读写只有 `fs` 一条路**：`fs.read(path)` 返回文件全文的原始 UTF-8 文本（不加行号、
+  不截断、不设大小上限，只有内容不是合法 UTF-8 时报错），`fs.write(path, content)` 整体写入并自动创建
+  父目录，相对路径相对当前 cwd。`fs.write` 与写类工具共用同一套保护：写前要求「已读且读后
+  未变」（记账与文件工具共享，工具读过的文件脚本可以直接写），工作区外写入走 write-guard
+  的 diff 审批，headless / Windows / `/bwrap-deny-request` 下直接拒绝。文件读写工具本身
+  不在可调用集合里，脚本要改一行内容也走 `fs.read` + `fs.write`（行级替换用 `Edit` 工具
+  直接改，不进脚本）。
 - **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
   中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
 - **返回值**：声明了 `structuredSchema` 的工具（如 gh-readonly 的读类工具）把结果放在
   `structuredResult` 里，`call()` 解包成对象给脚本；`{ ok: false, error }` 会 reject 成
-  `CallFailedError`（脚本可按 `instanceof CallFailedError` 区分工具失败与自身运行期错误）。
+  `CallFailedError`（脚本可按 `instanceof CallFailedError` 区分调用失败与自身运行期错误）。
   没有声明输出结构的工具回退成工具输出的文本。
-- **脚本接口**：`call` / `CallFailedError` / `ALL_TOOLS` / `text` / `image` / `exit` /
-  `console.*` / `store.set` / `store.get` / `store.list`（会话内持久的键值表）；首行可选
-  `// @options: {"max_output_tokens": 10000}`。
+- **脚本接口**：`call` / `CallFailedError` / `ALL_TOOLS` / `fs.read` / `fs.write` /
+  `text` / `image` / `exit` / `console.*` / `store.set` / `store.get` / `store.list`
+  （会话内持久的键值表）；首行可选 `// @options: {"max_output_tokens": 10000}`。
   脚本没有超时：死循环由调用方中止（Esc）结束，等嵌套调用返回（含用户审批弹窗）多久都不算超时。
 - **工具描述**里给出每个可调用工具的 `declare function call(name, args): Promise<T>` 重载，
   参数与返回类型都取自工具自己的 schema，所以模型在写脚本前就知道返回值形状。
@@ -57,7 +64,10 @@
   时头尾截断并把全文落到 `$TMPDIR/pi-codemode-*.txt`。
 - **构建**：worker 入口是 esbuild 产物 `src/codemode/worker.js`（随仓库提交，
   `pnpm run build:codemode-worker` 重新生成，pre-commit 会自动跑）；`quickjs-wasi` 的
-  wasm 在注册工具时编译一次，之后每次执行复用。
+  wasm 在注册工具时编译一次，之后每次执行复用。产物必须**自包含**：它由 `new Worker(url)`
+  作为普通 Node 模块加载，不像主线程那样经 jiti 从 pi 的 `node_modules` 解析裸包名，所以
+  除了 `quickjs-wasi`（我们自己的 dependency）之外的依赖都要打包进去——否则用户装好包后
+  worker 会在启动时报 `Cannot find package`。
 
 ## 工具启用配置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.679",
+  "version": "0.1.681",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -28,7 +28,7 @@
     "aft-search": "jiti bin/aft-search.ts",
     "build:holder": "esbuild src/bwrap/holder.ts --format=esm --target=node24 --outfile=src/bwrap/holder.js",
     "prepare": "husky",
-    "build:codemode-worker": "esbuild src/codemode/worker.ts --bundle --packages=external --format=esm --target=node24 --outfile=src/codemode/worker.js"
+    "build:codemode-worker": "esbuild src/codemode/worker.ts --bundle --platform=node --external:quickjs-wasi --format=esm --target=node24 --outfile=src/codemode/worker.js"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": ">=0.84.1",

package/src/claude-code/files.ts

@@ -595,8 +595,14 @@ export function registerFileTools(
   // 它们由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
-/** 会更新 reads state 并随 details 持久化快照的工具名。 */
-const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write", "lsp-rename"]);
+/**
+ * 会更新 reads state 并随 details 持久化快照的工具名。
+ *
+ * 含 `codemode`：脚本的 `fs.read` / `fs.write`（src/codemode/fs.ts）与本工具集共用
+ * 同一个 ReadsState，脚本记下的已读落在 codemode 自己的工具结果里，重放分支时要一起
+ * 收回来（见 `restoreReads`）。
+ */
+const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write", "lsp-rename", "codemode"]);
 
 export interface ClaudeCodeFileToolOptions extends LspServiceOptions {
   /** 与 bash runtime 共享的非沙盒请求策略；独立入口不传，自建一份。 */
@@ -619,6 +625,8 @@ export interface FileToolset {
   register(bus: ToolBus): void;
   onLspEnabled(bus: ToolBus, service: LspService): void;
   restoreReads(ctx: ExtensionContext): void;
+  /** 与工具共用的已读记账：codemode 的 fs 原语拿它做 stale 保护（两边互通）。 */
+  readonly reads: ReadsState;
 }
 
 /**
@@ -668,6 +676,8 @@ export function createClaudeCodeFileTools(
     restoreReads(ctx) {
       restoreReads(state, ctx.sessionManager, FILE_TOOL_NAMES);
     },
+
+    reads: state,
   };
 
   // 独立入口没有注入 manager 时自建一份（入口共享的那份由入口创建）。

package/src/codemode/declarations.ts

@@ -102,13 +102,20 @@ export function toScriptTools(tools: readonly ToolLike[]): ScriptTool[] {
   }));
 }
 
-/** 渲染脚本侧的声明：每个工具一条 `call` 重载，外加 `CallFailedError` 与全局辅助函数。 */
+/** 渲染脚本侧的声明：每个工具一条 `call` 重载，外加 `fs` 原语、`CallFailedError` 与全局辅助函数。 */
 export function renderDeclarations(tools: readonly ToolLike[]): string {
   return [
     ...tools.map((tool) => renderOverload(tool)),
     // 动态名字的兜底重载，必须放最后
     "declare function call(name: string, args?: unknown): Promise<unknown>;",
     "declare const ALL_TOOLS: Array<{ name: string; description?: string }>;",
+    // 文件原语：直接读写文件。它们不是工具，所以不在上面的 call 重载里。
+    [
+      "declare const fs: {",
+      "  read(path: string): Promise<string>;",
+      "  write(path: string, content: string): Promise<void>;",
+      "};",
+    ].join("\n"),
     'declare class CallFailedError extends Error { readonly name: "CallFailedError"; }',
     "declare function text(value: unknown): void;",
     "declare function image(value: unknown): void;",

package/src/codemode/fs.ts

@@ -0,0 +1,138 @@
+/**
+ * codemode 的文件原语（`fs.read` / `fs.write`）：宿主用 `node:fs/promises` 直接读写，
+ * 不走工具总线——它们不是工具，不出现在工具列表里，也不参与工具开关与 active 工具求交。
+ *
+ * 两条保护与文件工具完全一致，而且共用同一份状态：
+ * - stale 保护：写入前要求目标文件「已读且读后未变」（`file-reads.ts` 的
+ *   `requireCurrentRead`），文件不存在时允许直接创建；读与写都记账，因此工具读过的
+ *   文件脚本可以直接写，反之亦然。
+ * - 审批：写入经 write-guard（工作区内与 `/tmp` 放行，区外弹 diff 审批，headless /
+ *   Windows / 请求策略下直接拒绝）。
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type FileSnapshot,
+  type ReadsState,
+  recordRead,
+  requireCurrentRead,
+  snapshotOf,
+} from "../lib/file-reads.js";
+import { parseWithSchema } from "../lib/parse-with-schema.js";
+import type { RequestPolicy } from "../lib/request-policy.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+
+const readArgsSchema = Type.Object({ path: Type.String() });
+const writeArgsSchema = Type.Object({ path: Type.String(), content: Type.String() });
+
+const FS_READ = "fs.read";
+const FS_WRITE = "fs.write";
+
+export interface FsCallContext {
+  ctx: ExtensionContext;
+  signal?: AbortSignal;
+}
+
+/** 一次 fs 原语的结果：`value` 回给脚本，`reads` 是本次新增的已读记账（进 details.reads）。 */
+export interface FsCallResult {
+  value?: unknown;
+  reads?: Record<string, FileSnapshot>;
+}
+
+export interface CodemodeFs {
+  /** 该名字是否归 fs 原语（`fs.read` / `fs.write`）。 */
+  handles(name: string): boolean;
+  /** 执行一次 fs 原语；失败抛错，由调用方转成脚本侧的错误。 */
+  execute(name: string, args: unknown, call: FsCallContext): Promise<FsCallResult>;
+}
+
+export interface CodemodeFsOptions {
+  /** 与写类工具共享的请求策略：`/bwrap-deny-request` 生效时工作区外写入直接拒绝。 */
+  policy: RequestPolicy;
+  /** 与文件工具共享的已读记账。 */
+  reads: ReadsState;
+}
+
+/**
+ * 解码 UTF-8：`ignoreBOM: true` 表示不特殊处理 BOM（即保留它），这样内容与磁盘字节
+ * 一一对应——记账指纹与审批预览都是按原始字节比对的，丢掉 BOM 会让两者对不上。
+ */
+function decodeUtf8(buffer: Uint8Array, path: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer);
+  } catch {
+    throw new Error(
+      `Cannot read "${path}" as UTF-8 text: the file is not valid UTF-8 (binary files are not supported).`,
+    );
+  }
+}
+
+/** 读文件；不存在时返回 undefined（新建文件免已读），其余错误照常抛出。 */
+async function readIfExists(path: string, signal?: AbortSignal): Promise<Buffer | undefined> {
+  try {
+    return await readFile(path, { signal });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export function createCodemodeFs(options: CodemodeFsOptions): CodemodeFs {
+  const { policy, reads } = options;
+
+  async function read(args: unknown, call: FsCallContext): Promise<FsCallResult> {
+    const { path } = parseWithSchema(readArgsSchema, args);
+    const absolutePath = resolve(call.ctx.cwd, path);
+    // 不设大小上限：内容不进模型上下文，放不下时（VM 堆不够）会以错误回到脚本里
+    const buffer = await readFile(absolutePath, { signal: call.signal });
+    const text = decodeUtf8(buffer, absolutePath);
+    // 指纹按磁盘字节算：与文件工具共用记账，两侧的 digest 必须能互相对上
+    const recorded = await recordRead(reads, absolutePath, snapshotOf(buffer));
+    return { value: text, reads: recorded };
+  }
+
+  async function write(args: unknown, call: FsCallContext): Promise<FsCallResult> {
+    const { path, content } = parseWithSchema(writeArgsSchema, args);
+    const absolutePath = resolve(call.ctx.cwd, path);
+    const existing = await readIfExists(absolutePath, call.signal);
+    if (existing !== undefined) {
+      await requireCurrentRead(reads, absolutePath, existing);
+    }
+    await guardWriteAccess(call.ctx, {
+      toolName: FS_WRITE,
+      absolutePath,
+      mutation: {
+        contentOld: existing === undefined ? "" : decodeUtf8(existing, absolutePath),
+        contentNew: content,
+      },
+      policy,
+      signal: call.signal,
+    });
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, { encoding: "utf8", signal: call.signal });
+    const recorded = await recordRead(reads, absolutePath, snapshotOf(content));
+    return { reads: recorded };
+  }
+
+  return {
+    handles(name) {
+      return name === FS_READ || name === FS_WRITE;
+    },
+    async execute(name, args, call) {
+      if (name === FS_READ) {
+        return await read(args, call);
+      }
+      if (name === FS_WRITE) {
+        return await write(args, call);
+      }
+      throw new Error(`Unknown fs operation "${name}".`);
+    },
+  };
+}

package/src/codemode/prelude.ts

@@ -1,16 +1,16 @@
 /**
  * codemode 脚本侧的 prelude：在 QuickJS VM 里先于脚本求值，构建脚本能看到的全部
- * 能力（`call` / `CallFailedError` / `ALL_TOOLS` / `text` / `image` / `exit` /
+ * 能力（`call` / `CallFailedError` / `ALL_TOOLS` / `fs` / `text` / `image` / `exit` /
  * `console` / `store`），并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
  *
  * 值与参数过桥时都是 JSON 文本，本侧负责 parse/stringify；异步调用用一个 pending
- * 表把 id 映射到 promise，由宿主在结果到达时 settle。每次嵌套调用失败都由宿主以
- * `ok: false` 回报，本侧统一 reject 成 `CallFailedError`（脚本可以按 instanceof 区分
- * 「工具失败」与自己的运行期错误）。
+ * 表把 id 映射到 promise，由宿主在结果到达时 settle。每次调用失败（工具或 fs 原语）
+ * 都由宿主以 `ok: false` 回报，本侧统一 reject 成 `CallFailedError`（脚本可以按
+ * instanceof 区分「调用失败」与自己的运行期错误）。
  *
  * 求值结果是一个函数 `(bridge, toolsJson, storeJson) => { settle, run, stalled }`。
  * `bridge(kind, a, b, c)`：
- * - `"call"`（id, name, argsJson）
+ * - `"call"`（id, name, argsJson）：工具，以及名字为 `fs.read` / `fs.write` 的 fs 原语
  * - `"output"`（"text", text）/（"image", data, mimeType）
  * - `"done"`（ok, valueJsonOrErrorJson, writesJson）
  */
@@ -118,6 +118,16 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 	}
 	Object.freeze(call);
 
+	// 脚本的文件原语：与工具走同一条桥，但它们是内建能力而不是工具——不进 ALL_TOOLS，
+	// 也不出现在工具描述的工具重载里（声明单独渲染），写审批与已读记账由宿主负责。
+	// 脚本侧是 Node 风格的位置参数，过桥仍是一个可校验的对象。
+	const readFile = caller("fs.read");
+	const writeFile = caller("fs.write");
+	const fs = Object.freeze({
+		read: (path) => readFile({ path }),
+		write: (path, content) => writeFile({ path, content }),
+	});
+
 	// key -> JSON 文本；容量按 key 与 JSON 的字符数计
 	const stored = new Map();
 	const writes = new Map();
@@ -260,6 +270,7 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 	Object.defineProperty(globalThis, "call", { value: call, enumerable: true });
 	Object.defineProperty(globalThis, "CallFailedError", { value: CallFailedError, enumerable: true });
 	Object.defineProperty(globalThis, "ALL_TOOLS", { value: allTools, enumerable: true });
+	Object.defineProperty(globalThis, "fs", { value: fs, enumerable: true });
 	Object.defineProperty(globalThis, "console", { value: console, enumerable: true });
 	Object.defineProperty(globalThis, "text", { value: text, enumerable: true });
 	Object.defineProperty(globalThis, "image", { value: image, enumerable: true });

package/src/codemode/protocol.ts

@@ -13,6 +13,18 @@
 import { type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 
+// ── 资源上限 ─────────────────────────────────────────────────────────────────
+
+/**
+ * QuickJS VM 的堆上限。它不是预留（创建 VM 只占几 MiB，按脚本实际分配增长），而是
+ * 「超量分配变成脚本里可捕获的 InternalError，而不是拖垮宿主」的那条线。
+ *
+ * 文件读取没有单独的上限：读进来的内容不进模型上下文，所以不需要按上下文预算裁剪；
+ * 真正放不下时（VM 堆不够、或超出宿主字符串/缓冲上限）会以错误回到脚本里，让它自己
+ * 决定怎么办。
+ */
+export const MEMORY_LIMIT_BYTES = 2 * 1024 ** 3;
+
 // ── 消息 schema ──────────────────────────────────────────────────────────────
 
 const outputItemSchema = Type.Union([

package/src/codemode/tool.ts

@@ -1,11 +1,12 @@
 /**
- * codemode 工具：模型写一段 JavaScript，脚本在 QuickJS VM（worker 线程）里执行，脚本唯一
- * 的能力是调用 `call(name, args)`——每个嵌套调用都由主线程经本仓库的工具总线执行，因此工具实现
- * 内部的审批（工作区外写入、Bash 沙箱提权等）照常生效；codemode 不再加自己的确认层。
+ * codemode 工具：模型写一段 JavaScript，脚本在 QuickJS VM（worker 线程）里执行，脚本的
+ * 能力有两条：`call(name, args)` 调用工具（每个嵌套调用都由主线程经本仓库的工具总线执行，
+ * 因此工具实现内部的审批——工作区外写入、Bash 沙箱提权等——照常生效；codemode 不再加
+ * 自己的确认层），以及 `fs.read` / `fs.write` 两个文件原语（同样由主线程执行，与文件工具
+ * 共用写审批与已读记账，见 fs.ts）。
  *
- * 可调用集合：总线上实际注册的工具减去 codemode 自身与 spawn-agent，执行时再与 active
+ * 可调用集合：总线上实际注册的工具减去 `EXCLUDED_TOOL_NAMES`，执行时再与 active
  * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
- * spawn-agent 被排除是因为它启动一个新的隔离会话、成本与运行时长都不适合放进脚本编排。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
  */
@@ -18,27 +19,52 @@ import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import type { FileSnapshot, ReadsState } from "../lib/file-reads.js";
 import type { ToolPendant } from "../lib/pendant.js";
+import type { RequestPolicy } from "../lib/request-policy.js";
 import { type ToolBus, toolResultText } from "../lib/tool-bus.js";
 import { renderDeclarations, toScriptTools } from "./declarations.js";
+import { createCodemodeFs } from "./fs.js";
 import type { CodemodeOutputItem, ScriptError, StoreWrites } from "./protocol.js";
 import { type CodemodeSandbox, createCodemodeSandbox, type ScriptCall } from "./sandbox.js";
 import { CODEMODE_SOURCE_GRAMMAR, DEFAULT_OUTPUT_TOKENS, parseCodemodeSource } from "./source.js";
 
 export const CODEMODE_TOOL_NAME = "codemode";
 
-/** 不暴露给脚本的工具：codemode 自身（防递归）与 spawn-agent（见文件头注释）。 */
-const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([CODEMODE_TOOL_NAME, "spawn-agent"]);
+/**
+ * 不暴露给脚本的工具：
+ * - codemode 自身（防递归）；
+ * - spawn-agent：它启动一个新的隔离会话，成本与运行时长都不适合放进脚本编排；
+ * - 两套文件工具集的读写工具：脚本用 `fs.read` / `fs.write`（原文、不截断、按路径整体
+ *   写入），不重复给一套为 LLM 上下文设计的行号/锚点语义。
+ */
+const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([
+  CODEMODE_TOOL_NAME,
+  "spawn-agent",
+  "Read",
+  "Edit",
+  "Write",
+  "read",
+  "edit",
+  "write",
+]);
 
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
 
+export interface CodemodeToolDeps {
+  /** 与写类工具共享的非沙盒请求策略（写审批要用）。 */
+  policy: RequestPolicy;
+  /** 与文件工具共享的已读记账：脚本的 fs 原语据此做 stale 保护（两边互通）。 */
+  reads: ReadsState;
+}
+
 export interface CodemodeTools {
   /**
    * 注册 codemode 工具。注册时编译 quickjs.wasm（编译失败则注册失败，由入口记成
    * 警告），之后每次执行复用同一份编译结果。
    */
-  register(bus: ToolBus): Promise<void>;
+  register(bus: ToolBus, deps: CodemodeToolDeps): Promise<void>;
 }
 
 interface CallableTool {
@@ -126,6 +152,11 @@ function readStore(ctx: ExtensionContext): Record<string, unknown> {
   return Object.fromEntries(store);
 }
 
+/** 本次脚本有没有通过 fs 读写过文件（决定 details 里要不要带 reads 记账）。 */
+function hasReads(reads: Record<string, FileSnapshot>): boolean {
+  return Object.keys(reads).length > 0;
+}
+
 function errorText(error: ScriptError): string {
   const head = error.name ? `${error.name}: ${error.message}` : error.message;
   return `${head}${error.stack && error.stack !== head ? `\n${error.stack}` : ""}`;
@@ -224,8 +255,9 @@ function formatCallSummary(calls: readonly ScriptCall[]): string {
 
 export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
   return {
-    async register(bus) {
+    async register(bus, deps) {
       const sandbox: CodemodeSandbox = await createCodemodeSandbox();
+      const fs = createCodemodeFs(deps);
       const tools = collectTools(bus, allowedToolNames(pi));
       const callable = new Set(tools.map((tool) => tool.name));
       const scriptTools = toScriptTools(tools);
@@ -269,6 +301,9 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
             };
           }
 
+          // 脚本的 fs 原语读到的文件也进同一份记账，随结果持久化（与 details.store 同一处）
+          const recordedReads: Record<string, FileSnapshot> = {};
+
           const outcome = await sandbox.run({
             code,
             tools: scriptTools,
@@ -295,6 +330,20 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
               });
             },
             onCall: async ({ name, args }) => {
+              if (fs.handles(name)) {
+                try {
+                  const result = await fs.execute(name, args, { ctx, signal });
+                  if (result.reads !== undefined) {
+                    Object.assign(recordedReads, result.reads);
+                  }
+                  return { ok: true, value: result.value };
+                } catch (error) {
+                  return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                  };
+                }
+              }
               if (!callable.has(name)) {
                 return { ok: false, error: `Tool "${name}" is not available in codemode.` };
               }
@@ -336,6 +385,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
                 calls: outcome.calls,
                 // store 的写入随工具结果持久化，下一次调用从这里重放恢复
                 ...(hasWrites && { store: writes }),
+                ...(hasReads(recordedReads) && { reads: recordedReads }),
                 pendant: scriptPendant(code, `${outcome.calls.length} tool call(s)`),
                 ...(truncated.fullOutputPath && { fullOutputPath: truncated.fullOutputPath }),
               },
@@ -356,6 +406,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
             details: {
               calls: outcome.calls,
               error: outcome.error.kind,
+              ...(hasReads(recordedReads) && { reads: recordedReads }),
               pendant: scriptPendant(code, `failed (${outcome.error.kind})`),
             },
           };