@trim21/personal-pi-extensions 0.1.678 → 0.1.680

package/src/gh/tools/read-pr-status.ts

@@ -1,16 +1,18 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   mergeChecks,
   resolveRepo,
   splitRepo,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   toPositiveId,
+  withStructuredResult,
 } from "../base.js";
+import { prStatusSchema } from "../schemas.js";
 
 interface PrStatusParams {
   number: number | string;
@@ -22,7 +24,10 @@ interface PrStatusParams {
  * path as the wait tools (octokit), but it never polls — pending checks come
  * back as-is.
  */
-export async function prStatus(gh: GhClient, call: ToolCall<PrStatusParams>): Promise<ToolResult> {
+export async function prStatus(
+  gh: GhClient,
+  call: ToolCall<PrStatusParams>,
+): Promise<StructuredResultOf<typeof prStatusSchema>> {
   const { params, ctx, signal } = call;
   const { number, repo } = params;
   const pullNumber = toPositiveId(number, "number");
@@ -46,25 +51,31 @@ export async function prStatus(gh: GhClient, call: ToolCall<PrStatusParams>): Pr
   }));
 
   const payload = { pr: pullNumber, repo: effectiveRepo, head_sha: headSha, checks };
-  return {
-    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-    details: { ...payload, input: params, ...(pendant && { pendant }) },
-  };
+  return withStructuredResult(
+    {
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      details: { ...payload, input: params, ...(pendant && { pendant }) },
+    },
+    payload,
+  );
 }
 
 export function addReadPrStatusTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr-status",
-    label: "GitHub PR Status",
-    description:
-      "Get the current checks of a pull request's head commit as JSON {pr, repo, head_sha, checks:[{name, bucket, event, run_id, job_id, url}]}. `bucket` is pass / fail / pending / skipped; Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
-    promptSnippet: "Read GitHub PR status checks",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr-status",
+      label: "GitHub PR Status",
+      description:
+        "Get the current checks of a pull request's head commit as JSON {pr, repo, head_sha, checks:[{name, bucket, event, run_id, job_id, url}]}. `bucket` is pass / fail / pending / skipped; Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
+      promptSnippet: "Read GitHub PR status checks",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      }),
+      structuredSchema: prStatusSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return prStatus(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return prStatus(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

package/src/gh/tools/read-pr.ts

@@ -1,22 +1,30 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResultJson } from "../base.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  repoArgs,
+  subtitlePendant,
+  toStructuredJsonResult,
+} from "../base.js";
+import { prViewSchema } from "../schemas.js";
 
 export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr",
-    label: "GitHub PR",
-    description: "Get details of a GitHub pull request by number.",
-    promptSnippet: "Read a GitHub PR",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-    }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const result = toToolResultJson(
-        await ghExec(
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr",
+      label: "GitHub PR",
+      description: "Get details of a GitHub pull request by number.",
+      promptSnippet: "Read a GitHub PR",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: prViewSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { number, repo } = params;
+        const out = await ghExec(
           [
             "pr",
             "view",
@@ -26,11 +34,11 @@ export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
             "title,state,body,author,createdAt,updatedAt,mergedAt,mergedBy,headRefName,baseRefName,url,additions,deletions,changedFiles,labels,assignees,reviewRequests,reviews,comments,number",
           ],
           { cwd: ctx.cwd, signal, input: params },
-        ),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+        );
+        const result = toStructuredJsonResult(out, params, prViewSchema);
+        result.details.pendant = subtitlePendant(params, "number");
+        return result;
+      },
+    }),
+  );
 }

package/src/gh/tools/wait-commit-checks.ts

@@ -1,15 +1,16 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   resolveRepo,
   splitRepo,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   waitChecksReport,
 } from "../base.js";
+import { checksVerdictSchema } from "../schemas.js";
 
 interface CommitChecksWaitParams {
   commit: number | string;
@@ -22,7 +23,7 @@ interface CommitChecksWaitParams {
 async function waitCommitChecks(
   gh: GhClient,
   call: ToolCall<CommitChecksWaitParams>,
-): Promise<ToolResult> {
+): Promise<StructuredResultOf<typeof checksVerdictSchema>> {
   const { params, ctx, signal, onUpdate } = call;
   const { commit, repo, event, fail_fast } = params;
 
@@ -54,35 +55,38 @@ async function waitCommitChecks(
 }
 
 export function addWaitCommitChecksTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "wait-github-commit-checks",
-    label: "Watch GitHub Commit Checks",
-    description:
-      "Watch CI status checks for a commit until they complete — no pull request required. " +
-      "Same semantics as wait-github-pr-checks: returns when any check fails (immediately under fail_fast) " +
-      "or all checks pass/skip; on timeout the still-in-flight snapshot is returned. " +
-      "With `event`, only check runs triggered by that workflow event (e.g. push) are judged; " +
-      "commit statuses have an unknown trigger event and are excluded under a filter. " +
-      "Use this to wait for the runs a commit's push triggered, or for checks on an arbitrary ref.",
-    promptSnippet: "Watch and wait for GitHub commit CI checks to complete",
-    parameters: Type.Object({
-      commit: Type.Union([Type.Number(), Type.String()], {
-        description:
-          "Commit to wait for: full or partial SHA, branch name, or tag name (resolved to the commit's SHA)",
-      }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      event: Type.Optional(
-        Type.String({
+  bus.register(
+    defineStructuredTool({
+      name: "wait-github-commit-checks",
+      label: "Watch GitHub Commit Checks",
+      description:
+        "Watch CI status checks for a commit until they complete — no pull request required. " +
+        "Same semantics as wait-github-pr-checks: returns when any check fails (immediately under fail_fast) " +
+        "or all checks pass/skip; on timeout the still-in-flight snapshot is returned. " +
+        "With `event`, only check runs triggered by that workflow event (e.g. push) are judged; " +
+        "commit statuses have an unknown trigger event and are excluded under a filter. " +
+        "Use this to wait for the runs a commit's push triggered, or for checks on an arbitrary ref.",
+      promptSnippet: "Watch and wait for GitHub commit CI checks to complete",
+      parameters: Type.Object({
+        commit: Type.Union([Type.Number(), Type.String()], {
           description:
-            "Only judge check runs triggered by this workflow event (e.g. push, pull_request)",
+            "Commit to wait for: full or partial SHA, branch name, or tag name (resolved to the commit's SHA)",
         }),
-      ),
-      fail_fast: Type.Optional(
-        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
-      ),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        event: Type.Optional(
+          Type.String({
+            description:
+              "Only judge check runs triggered by this workflow event (e.g. push, pull_request)",
+          }),
+        ),
+        fail_fast: Type.Optional(
+          Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+        ),
+      }),
+      structuredSchema: checksVerdictSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return waitCommitChecks(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return waitCommitChecks(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

package/src/gh/tools/wait-pr-checks.ts

@@ -1,17 +1,18 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   ghExec,
   resolveRepo,
   splitRepo,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   waitChecksReport,
 } from "../base.js";
+import { checksVerdictSchema } from "../schemas.js";
 
 interface PrChecksWaitParams {
   number: number | string;
@@ -22,7 +23,10 @@ interface PrChecksWaitParams {
 const prHeadSchema = Type.Object({ headRefOid: Type.String() });
 
 /** The toolcall handler behind `wait-github-pr-checks`. */
-async function waitPrChecks(gh: GhClient, call: ToolCall<PrChecksWaitParams>): Promise<ToolResult> {
+async function waitPrChecks(
+  gh: GhClient,
+  call: ToolCall<PrChecksWaitParams>,
+): Promise<StructuredResultOf<typeof checksVerdictSchema>> {
   const { params, ctx, signal, onUpdate } = call;
   const { number, repo, fail_fast } = params;
 
@@ -56,25 +60,28 @@ async function waitPrChecks(gh: GhClient, call: ToolCall<PrChecksWaitParams>): P
 }
 
 export function addWaitPrChecksTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "wait-github-pr-checks",
-    label: "Watch GitHub PR Checks",
-    description:
-      "Watch CI status checks for a PR until they complete. Blocks until all checks pass (or are skipped) or one fails. " +
-      "Covers both commit statuses (Azure DevOps, Jenkins, ...) and GitHub Actions check runs. " +
-      "Each polling round streams a compact bullet list of the checks still in flight via onUpdate; " +
-      "on timeout the still-in-flight snapshot is returned instead of a verdict. " +
-      "Use this when you need to wait for CI to complete and see the final result.",
-    promptSnippet: "Watch and wait for GitHub PR CI checks to complete",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      fail_fast: Type.Optional(
-        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
-      ),
+  bus.register(
+    defineStructuredTool({
+      name: "wait-github-pr-checks",
+      label: "Watch GitHub PR Checks",
+      description:
+        "Watch CI status checks for a PR until they complete. Blocks until all checks pass (or are skipped) or one fails. " +
+        "Covers both commit statuses (Azure DevOps, Jenkins, ...) and GitHub Actions check runs. " +
+        "Each polling round streams a compact bullet list of the checks still in flight via onUpdate; " +
+        "on timeout the still-in-flight snapshot is returned instead of a verdict. " +
+        "Use this when you need to wait for CI to complete and see the final result.",
+      promptSnippet: "Watch and wait for GitHub PR CI checks to complete",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        fail_fast: Type.Optional(
+          Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+        ),
+      }),
+      structuredSchema: checksVerdictSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return waitPrChecks(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return waitPrChecks(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

package/src/index.ts

@@ -120,8 +120,11 @@ export default function personalExtensions(pi: ExtensionAPI): void {
     for (const { name, module } of modules) {
       runModule(name, () => module.register(bus));
     }
-    // codemode 最后注册：它把总线上已有的工具写进自己的描述，并在注册时编译 wasm
-    await runModuleAsync("codemode", () => codemode.register(bus));
+    // codemode 最后注册：它把总线上已有的工具写进自己的描述，并在注册时编译 wasm。
+    // 脚本的 fs 原语与文件工具共用请求策略与已读记账，所以这里把工具集那两份注入过去。
+    await runModuleAsync("codemode", () =>
+      codemode.register(bus, { policy: services.policy, reads: fileToolset.reads }),
+    );
 
     for (const warning of warnings) {
       ctx.ui.notify(warning, "warning");

package/src/lib/tool-bus.ts

@@ -7,6 +7,15 @@
  * - `executeTool`：先用工具自身的参数 schema 校验参数，再调用定义的 `execute`；
  *   参数校验失败与工具抛出的异常都归一化成错误结果返回，不向调用方抛异常。
  *
+ * 结构化结果：工具可以在定义上声明 `structuredSchema`（TypeBox），并在结果里带
+ * `structuredResult: StructuredResult<Static<typeof structuredSchema>>`。成功支的载荷类型
+ * 由 schema 在编译期约束，执行时再由总线 `Value.Parse` 复核；`ok: false` 让工具不必抛异常
+ * 也能结构化地报告失败（它不改变结果的 `isError`）。
+ *
+ * 这两个名字是本仓库自己的约定，刻意不占用宿主字段：pi-agent-core >= 0.99 自带
+ * `outputSchema` / `structuredContent`，语义是「裸载荷 + 用 `isError` 表失败」，与本仓库的
+ * Result 信封不同，将来接宿主原生管线时需要显式换算。
+ *
  * 状态由闭包持有（工厂 + 闭包），不使用模块级可变状态。
  */
 
@@ -20,8 +29,52 @@ import type { Static, TSchema } from "typebox";
 
 import { parseWithSchema } from "./parse-with-schema.js";
 
+/**
+ * 结构化结果：成功带 `value`，失败带可直接展示的错误说明。它只嵌在工具结果的
+ * `structuredResult` 一个属性里，结果对象本身保持单一类型（两个互斥字段会让整个
+ * 结果类型分配成对象联合）。
+ */
+export type StructuredResult<T> = { ok: true; value: T } | { ok: false; error: string };
+
+/**
+ * 声明了输出结构的工具定义：`structuredResult` 成功支的载荷类型由 `structuredSchema` 在编译
+ * 期绑定，因此工具无法返回与声明不符的结果。
+ */
+export interface StructuredToolDefinition<
+  TParams extends TSchema = TSchema,
+  TOutput extends TSchema = TSchema,
+  TDetails = unknown,
+> extends Omit<ToolDefinition<TParams, TDetails, unknown>, "execute"> {
+  structuredSchema: TOutput;
+  execute(
+    toolCallId: string,
+    params: Static<TParams>,
+    signal: AbortSignal | undefined,
+    onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
+    ctx: ExtensionContext,
+  ): Promise<AgentToolResult<TDetails> & { structuredResult: StructuredResult<Static<TOutput>> }>;
+}
+
+/**
+ * 结构化工具必须经它定义：`structuredSchema` 与 `execute` 返回类型之间的绑定只有在
+ * generic 函数的参数位置才建立得起来（与 pi 的 `defineTool` 同理）。
+ */
+export function defineStructuredTool<
+  TParams extends TSchema,
+  TOutput extends TSchema,
+  TDetails = unknown,
+>(
+  definition: StructuredToolDefinition<TParams, TOutput, TDetails>,
+): StructuredToolDefinition<TParams, TOutput, TDetails> {
+  return definition;
+}
+
 /** 一次工具执行的结果：`isError` 标出失败（工具不存在、参数不合法、工具抛错）。 */
-export type ToolExecutionResult = AgentToolResult<unknown> & { isError: boolean };
+export type ToolExecutionResult = AgentToolResult<unknown> & {
+  isError: boolean;
+  /** 工具声明的结构化结果，原样交给 codemode 脚本。 */
+  structuredResult?: StructuredResult<unknown>;
+};
 
 export interface ExecuteToolOptions {
   /** 工具 `execute` 需要的宿主上下文：调用方把自己拿到的那个 ctx 传进来。 */
@@ -32,16 +85,21 @@ export interface ExecuteToolOptions {
   toolCallId?: string;
 }
 
+/** 注册后的定义：多出的 `structuredSchema` 供 codemode 渲染脚本侧返回类型。 */
+export type RegisteredToolDefinition = ToolDefinition<TSchema, unknown, unknown> & {
+  structuredSchema?: TSchema;
+};
+
 export interface ToolBus {
   /** 注册一个工具；被配置禁用时跳过并返回 false。 */
   register<TParams extends TSchema, TDetails>(
     definition: ToolDefinition<TParams, TDetails, unknown>,
   ): boolean;
   /** 本次实际注册的工具定义。 */
-  list(): readonly ToolDefinition[];
+  list(): readonly RegisteredToolDefinition[];
   /** 所有尝试注册过的工具名（含被禁用而跳过的），用于校验配置里的模式是否有效。 */
   declaredNames(): readonly string[];
-  get(name: string): ToolDefinition | undefined;
+  get(name: string): RegisteredToolDefinition | undefined;
   /** 按名执行一个已注册工具；任何失败都以 `isError` 结果返回，不抛异常。 */
   executeTool(
     name: string,
@@ -55,8 +113,6 @@ export interface ToolBusOptions {
   isDisabled?: (name: string) => boolean;
 }
 
-type AnyToolDefinition = ToolDefinition<TSchema, unknown, unknown>;
-
 function errorResult(text: string): ToolExecutionResult {
   return { content: [{ type: "text", text }], details: { error: text }, isError: true };
 }
@@ -65,8 +121,64 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+type StructuredCheck =
+  { ok: true; result?: StructuredResult<unknown> } | { ok: false; error: string };
+
+/**
+ * 复核工具返回的 `structuredResult`：声明了 `structuredSchema` 的工具必须返回它，成功支的
+ * 载荷必须过 schema（外部数据用 typebox 校验是本仓库约定），失败支的错误必须是字符串。
+ */
+function checkStructuredResult(
+  name: string,
+  structuredSchema: TSchema | undefined,
+  result: AgentToolResult<unknown>,
+): StructuredCheck {
+  const structured = (result as { structuredResult?: unknown }).structuredResult;
+  if (structured === undefined) {
+    return structuredSchema === undefined
+      ? { ok: true }
+      : {
+          ok: false,
+          error: `Tool "${name}" declared a structuredSchema but returned no structuredResult.`,
+        };
+  }
+  if (structuredSchema === undefined) {
+    return {
+      ok: false,
+      error: `Tool "${name}" returned a structuredResult without declaring a structuredSchema.`,
+    };
+  }
+  if (typeof structured !== "object" || structured === null) {
+    return { ok: false, error: `Tool "${name}" returned a malformed structuredResult.` };
+  }
+  const candidate = structured as { ok?: unknown; value?: unknown; error?: unknown };
+  if (candidate.ok === false) {
+    if (typeof candidate.error !== "string") {
+      return {
+        ok: false,
+        error: `Tool "${name}" returned a structuredResult whose error is not a string.`,
+      };
+    }
+    return { ok: true, result: { ok: false, error: candidate.error } };
+  }
+  if (candidate.ok !== true) {
+    return { ok: false, error: `Tool "${name}" returned a malformed structuredResult.` };
+  }
+  try {
+    return {
+      ok: true,
+      result: { ok: true, value: parseWithSchema(structuredSchema, candidate.value) },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Tool "${name}" returned a structuredResult value that does not match its structuredSchema: ${errorMessage(error)}`,
+    };
+  }
+}
+
 export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): ToolBus {
-  const registered = new Map<string, AnyToolDefinition>();
+  const registered = new Map<string, RegisteredToolDefinition>();
   const declared = new Set<string>();
   let callCounter = 0;
 
@@ -76,7 +188,7 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
       if (options.isDisabled?.(definition.name) === true) {
         return false;
       }
-      const stored = definition as unknown as AnyToolDefinition;
+      const stored = definition as unknown as RegisteredToolDefinition;
       pi.registerTool(stored);
       registered.set(stored.name, stored);
       return true;
@@ -117,7 +229,15 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
           options.onUpdate,
           options.ctx,
         );
-        return { ...result, isError: false };
+        const checked = checkStructuredResult(name, definition.structuredSchema, result);
+        if (!checked.ok) {
+          return errorResult(checked.error);
+        }
+        return {
+          ...result,
+          isError: false,
+          ...(checked.result !== undefined && { structuredResult: checked.result }),
+        };
       } catch (error) {
         return errorResult(`Tool "${name}" failed: ${errorMessage(error)}`);
       }

package/src/opencode/files.ts

@@ -407,8 +407,14 @@ async function formatDirectoryEntries(dirPath: string): Promise<string[]> {
 
 // ── read-before-edit 记账 ────────────────────────────────────────────────────
 
-/** 会更新 reads 记账（src/lib/file-reads.ts）并随 details 持久化快照的工具名。 */
-const READS_TOOL_NAMES = new Set(["read", "edit", "write", "lsp-rename"]);
+/**
+ * 会更新 reads 记账（src/lib/file-reads.ts）并随 details 持久化快照的工具名。
+ *
+ * 含 `codemode`：脚本的 `fs.read` / `fs.write`（src/codemode/fs.ts）与本工具集共用
+ * 同一个 ReadsState，脚本记下的已读落在 codemode 自己的工具结果里，重放分支时要一起
+ * 收回来（见 `restoreReads`）。
+ */
+const READS_TOOL_NAMES = new Set(["read", "edit", "write", "lsp-rename", "codemode"]);
 
 function registerReadTool(bus: ToolBus, getService: () => LspService, state: ReadsState): void {
   bus.register({
@@ -897,6 +903,8 @@ export interface OpencodeFileToolset {
   register(bus: ToolBus): void;
   onLspEnabled(bus: ToolBus, service: LspService): void;
   restoreReads(ctx: ExtensionContext): void;
+  /** 与工具共用的已读记账：codemode 的 fs 原语拿它做 stale 保护（两边互通）。 */
+  readonly reads: ReadsState;
 }
 
 /**
@@ -939,6 +947,8 @@ export function createOpencodeFileTools(
     restoreReads(ctx) {
       restoreReads(state, ctx.sessionManager, READS_TOOL_NAMES);
     },
+
+    reads: state,
   };
 
   const manager =