@trim21/personal-pi-extensions 0.1.487 → 0.1.489

package/package.json

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

package/src/aft/tools.ts

@@ -7,6 +7,7 @@
 
 import { readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -18,7 +19,7 @@ import {
   PLAIN_CALLGRAPH_THEME,
   type StatusSnapshot,
 } from "@cortexkit/aft-bridge";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
@@ -290,6 +291,42 @@ const CallgraphParams = Type.Object(
 /** 只读导航的合法"否定答案"：符号未定义或索引仍在构建——返回文本而非报错。 */
 const CALLGRAPH_SOFT_CODES = new Set(["symbol_not_found", "callgraph_building"]);
 
+/**
+ * callgraph 查询的 building 重试总预算与间隔。Rust 侧内联等待窗口
+ * （AFT_CALLGRAPH_BUILD_WAIT_MS）覆盖不到的场景会秒回 callgraph_building：
+ * 语义索引冷种子 gate 激活期间 callgraph 冷构建被 defer（大仓库可持续数分钟），
+ * 以及冷构建本身超过内联窗口。这里在扩展侧重试，预算耗尽才把 building
+ * 文本交给模型。
+ */
+export const CALLGRAPH_BUILD_RETRY_BUDGET_MS = 90_000;
+const CALLGRAPH_BUILD_RETRY_INTERVAL_MS = 3_000;
+
+export async function callCallgraphWithBuildRetry(
+  bridge: AftProjectTransport,
+  rawArgs: Record<string, unknown>,
+  extCtx: ExtensionContext,
+  timing?: { budgetMs: number; intervalMs: number },
+): Promise<{ text: string; response: Record<string, unknown> }> {
+  const budgetMs = timing?.budgetMs ?? CALLGRAPH_BUILD_RETRY_BUDGET_MS;
+  const intervalMs = timing?.intervalMs ?? CALLGRAPH_BUILD_RETRY_INTERVAL_MS;
+  const deadline = Date.now() + budgetMs;
+  for (;;) {
+    const { text, response } = await callAftTool(
+      bridge,
+      "callgraph",
+      rawArgs,
+      extCtx,
+      undefined,
+      CALLGRAPH_SOFT_CODES,
+    );
+    const code = typeof response.code === "string" ? response.code : "";
+    if (code !== "callgraph_building" || Date.now() >= deadline) {
+      return { text, response };
+    }
+    await sleep(intervalMs);
+  }
+}
+
 export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): void {
   pi.registerTool({
     name: "aft_callgraph",
@@ -317,14 +354,7 @@ export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): vo
         includeUnresolved: params.includeUnresolved,
       });
 
-      const { text, response } = await callAftTool(
-        bridgeFor(ctx),
-        "callgraph",
-        rawArgs,
-        extCtx,
-        undefined,
-        CALLGRAPH_SOFT_CODES,
-      );
+      const { text, response } = await callCallgraphWithBuildRetry(bridgeFor(ctx), rawArgs, extCtx);
       const out =
         text ||
         formatCallgraphSections(params.op, response, PLAIN_CALLGRAPH_THEME, {

package/src/claude-code/files.ts

@@ -14,11 +14,10 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { RenameNotPossibleError } from "../lib/lsp/client.js";
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
 import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
-import { canonicalizeEdit, expandWorkspaceEdit, symbolCandidates } from "../lib/lsp/rename.js";
-import { formatSubtitlePath, resolvePathArg } from "../lib/path.js";
+import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
+import { formatSubtitlePath } from "../lib/path.js";
 import type { ToolPendant } from "../lib/pendant.ts";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import {
@@ -60,10 +59,6 @@ const WRITE_PROMPT = readFileSync(
   fileURLToPath(new URL("write.md", import.meta.url)),
   "utf8",
 ).trim();
-const LSP_RENAME_PROMPT = readFileSync(
-  fileURLToPath(new URL("lsp-rename.md", import.meta.url)),
-  "utf8",
-).trim();
 const IMAGE_MIMES = new Map<string, string>([
   [".gif", "image/gif"],
   [".jpeg", "image/jpeg"],
@@ -679,195 +674,19 @@ export function registerFileTools(
     },
   });
 
-  pi.registerTool({
-    name: "lsp-rename",
-    label: "Lsp Rename",
-    description: "Rename a code symbol and update all references across the workspace via LSP",
-    promptSnippet: "Workspace-wide symbol rename via LSP",
-    promptGuidelines: [LSP_RENAME_PROMPT],
-    parameters: Type.Object(
-      {
-        file_path: Type.String({
-          description:
-            "A file containing the symbol (absolute path, or relative / ~/ path resolved against the session cwd)",
-        }),
-        line: Type.Integer({
-          minimum: 1,
-          description:
-            "1-based line number where the symbol appears (any occurrence works, not only the definition)",
-        }),
-        symbol: Type.String({
-          minLength: 1,
-          description: "The symbol's name exactly as it appears on that line",
-        }),
-        new_name: Type.String({ minLength: 1, description: "The new name for the symbol" }),
-        character: Type.Optional(
-          Type.Integer({
-            minimum: 1,
-            description:
-              "1-based character offset of the symbol on that line. Only needed when the tool reports an ambiguity error on this line",
-          }),
-        ),
-      },
-      { additionalProperties: false },
-    ),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      signal?.throwIfAborted();
-
-      const filePath = resolvePathArg(ctx.cwd, params.file_path);
-      let content: string;
-      try {
-        await stat(filePath);
-        content = await readFile(filePath, "utf8");
-      } catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-          throw new Error(`File does not exist: ${filePath}`, { cause: error });
-        }
-        throw error;
-      }
-
-      const notify = (message: string, level: "info" | "warning" | "error") =>
-        ctx.ui.notify(message, level);
-      const options = { notify, signal };
-
-      // ── 按 symbol 名枚举行内候选，逐候选探测与消歧 ────────────────────────
-      const candidates = symbolCandidates(
-        content,
-        params.line - 1,
-        params.symbol,
-        params.character === undefined ? undefined : params.character - 1,
-      );
-      if (candidates.length === 0) {
-        throw new Error(
-          `Symbol "${params.symbol}" not found on line ${params.line} of ${filePath}. Read the file again and locate the symbol.`,
-        );
-      }
-      const successes: { result: Awaited<ReturnType<typeof service.rename>> }[] = [];
-      const notPossibleErrors: string[] = [];
-      for (const candidate of candidates) {
-        signal?.throwIfAborted();
-        try {
-          const result = await service.rename({
-            file: filePath,
-            cwd: ctx.cwd,
-            line: candidate.line,
-            character: candidate.character,
-            newName: params.new_name,
-            options,
-          });
-          successes.push({ result });
-        } catch (error) {
-          if (error instanceof RenameNotPossibleError) {
-            notPossibleErrors.push(error.message);
-            continue;
-          }
-          throw error;
-        }
-      }
-      if (successes.length === 0) {
-        throw new RenameNotPossibleError(
-          notPossibleErrors.length > 0
-            ? notPossibleErrors.join("; ")
-            : `no renameable symbol "${params.symbol}" on line ${params.line} of ${filePath}`,
-        );
-      }
-
-      // 同一符号的多次出现编辑集合一致；不一致即为不同符号 → 要求补 character
-      const groups = new Map<
-        string,
-        { result: (typeof successes)[number]["result"]; candidates: typeof candidates }
-      >();
-      for (const [index, candidate] of candidates.entries()) {
-        const entry = successes[index];
-        if (!entry) continue;
-        const key = canonicalizeEdit(entry.result.edit);
-        const group = groups.get(key);
-        if (group) group.candidates.push(candidate);
-        else groups.set(key, { result: entry.result, candidates: [candidate] });
-      }
-      if (groups.size > 1) {
-        const listing = [...groups.values()]
-          .map((group) =>
-            group.candidates
-              .map(
-                (candidate) =>
-                  `- line ${candidate.line + 1}, column ${candidate.character + 1} (rename target: ${group.result.placeholder ?? "unknown"})`,
-              )
-              .join("\n"),
-          )
-          .join("\n");
-        throw new Error(
-          `Ambiguous rename target on line ${params.line} of ${filePath}: several distinct symbols share the name "${params.symbol}". Retry with 'character' (1-based) to pick one:\n${listing}`,
-        );
-      }
-      const firstGroup = [...groups.values()][0];
-      if (!firstGroup) throw new Error("LSP rename returned no target");
-      const { result } = firstGroup;
-
-      // ── 内存展开 → 审批 → 写盘 → 诊断 ────────────────────────────────────
-      signal?.throwIfAborted();
-      const applied = await expandWorkspaceEdit(result.edit, (path) => readFile(path, "utf8"));
-      if (applied.length === 0) {
-        throw new Error("LSP rename returned no edits");
-      }
-      for (const fileEdit of applied) {
-        await guardWriteAccess(ctx, {
-          toolName: "lsp-rename",
-          absolutePath: fileEdit.path,
-          change: { oldText: fileEdit.oldText, newText: fileEdit.newText },
-        });
-      }
-
-      const diffs: string[] = [];
-      const pendingReads: { key: string; snapshot: FileSnapshot }[] = [];
-      for (const fileEdit of applied) {
-        await withFileMutationQueue(fileEdit.path, async () => {
-          await writeFile(fileEdit.path, fileEdit.newText, "utf8");
-          const key = await readStateKey(fileEdit.path);
-          pendingReads.push({ key, snapshot: snapshotOf(fileEdit.newText) });
-        });
-        diffs.push(
-          `### ${fileEdit.path} (${fileEdit.changeCount} edit(s))\n\n\`\`\`diff\n${generateDiffString(fileEdit.oldText, fileEdit.newText).diff}\n\`\`\``,
-        );
-      }
-
-      let diagnosticText = "";
-      for (const fileEdit of applied) {
-        signal?.throwIfAborted();
-        const diagnostics = await service.lspDiagnosticsForFile(fileEdit.path, ctx.cwd, {
-          notify,
-          signal,
-        });
-        if (diagnostics.text !== "") diagnosticText += `${diagnostics.text}\n`;
-      }
-
+  // lsp-rename 工具壳与 opencode 共享（lib/lsp/rename-tool.ts）；本工具集
+  // 跟踪 read-before-write 状态，rename 落盘的文件要标记为已读并随 details
+  // 持久化（FILE_TOOL_NAMES 的 restoreFileReads 依赖 details.reads）。
+  registerLspRenameTool(pi, service, {
+    recordReads: async (applied) => {
       const reads: Record<string, FileSnapshot> = {};
-      for (const { key, snapshot } of pendingReads) {
-        reads[key] = snapshot;
+      for (const fileEdit of applied) {
+        const key = await readStateKey(fileEdit.path);
+        const snapshot = snapshotOf(fileEdit.newText);
         state.reads.set(key, snapshot);
+        reads[key] = snapshot;
       }
-
-      const renamed =
-        result.placeholder !== undefined && result.placeholder !== params.new_name
-          ? `'${result.placeholder}' -> '${params.new_name}'`
-          : `to '${params.new_name}'`;
-      const summary = `Renamed ${renamed} across ${applied.length} file(s).`;
-      const text =
-        diagnosticText === ""
-          ? summary
-          : `${summary}\n\nLSP diagnostics detected in renamed files:\n${diagnosticText.trimEnd()}`;
-
-      return {
-        content: [{ type: "text" as const, text }],
-        details: {
-          reads,
-          pendant: {
-            title: "lsp-rename",
-            subtitle: `${renamed} · ${applied.length} file(s)`,
-            markdown: diffs.join("\n\n"),
-          } satisfies ToolPendant,
-        },
-      };
+      return reads;
     },
   });
 }

package/src/{claude-code → lib/lsp}/lsp-rename.md

@@ -5,5 +5,3 @@ Rename a code symbol (function, class, variable, ...) and update every reference
 - Locate the symbol with `file_path` + `line` (1-based) + `symbol` (the symbol's name exactly as it appears on that line). Any occurrence works — it does not have to be the definition.
 - The tool computes the column itself; do not pass `character` unless asked to disambiguate.
 - When several distinct symbols share the same name on that line, the tool refuses to guess: it reports an ambiguity error listing the candidate columns. Re-run with `character` (1-based) to pick one.
-- Requires an LSP server of kind `language` (per lsp.json) for the file; linter-only servers cannot rename.
-- After the rename, affected files are reported with their edit counts and LSP diagnostics. Renamed files are marked as read — no re-Read needed before further edits.

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

@@ -0,0 +1,237 @@
+/**
+ * lsp-rename 工具壳，由 claude-code / opencode 两个工具集共享注册。
+ *
+ * rename 的纯逻辑（候选枚举、同名消歧、WorkspaceEdit 展开）在 ./rename.ts，
+ * 这里只负责工具注册与执行编排：按行内候选逐个探测 → canonicalizeEdit 分组
+ * 消歧 → expandWorkspaceEdit 内存展开 → 审批 → 写盘 → 诊断。
+ *
+ * 两个工具集行为一致，唯一差异是 reads 记账：跟踪 read-before-write 状态的
+ * 工具集通过 hooks.recordReads 把重命名文件标记为已读并随 details 持久化；
+ * 不跟踪该状态的工具集不传 hook。
+ */
+
+import { readFileSync } from "node:fs";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import {
+  type ExtensionAPI,
+  generateDiffString,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { resolvePathArg } from "../path.js";
+import type { ToolPendant } from "../pendant.ts";
+import { guardWriteAccess } from "../write-guard.js";
+import { RenameNotPossibleError } from "./client.js";
+import type { LspService } from "./lsp.js";
+import {
+  type AppliedFileEdit,
+  canonicalizeEdit,
+  expandWorkspaceEdit,
+  symbolCandidates,
+} from "./rename.js";
+
+export interface LspRenameHooks {
+  /**
+   * rename 落盘后对每个被修改文件做已读记账；返回的 map 随 details.reads
+   * 持久化，供 session 恢复时重放。不跟踪已读状态的工具集不提供该 hook。
+   */
+  recordReads?: (applied: readonly AppliedFileEdit[]) => Promise<Record<string, unknown>>;
+}
+
+const LSP_RENAME_PROMPT = readFileSync(
+  fileURLToPath(new URL("lsp-rename.md", import.meta.url)),
+  "utf8",
+).trim();
+
+export function registerLspRenameTool(
+  pi: ExtensionAPI,
+  service: LspService,
+  hooks: LspRenameHooks = {},
+): void {
+  pi.registerTool({
+    name: "lsp-rename",
+    label: "Lsp Rename",
+    description: "Rename a code symbol and update all references across the workspace via LSP",
+    promptSnippet: "Workspace-wide symbol rename via LSP",
+    promptGuidelines: [LSP_RENAME_PROMPT],
+    parameters: Type.Object(
+      {
+        file_path: Type.String({
+          description:
+            "A file containing the symbol (absolute path, or relative / ~/ path resolved against the session cwd)",
+        }),
+        line: Type.Integer({
+          minimum: 1,
+          description:
+            "1-based line number where the symbol appears (any occurrence works, not only the definition)",
+        }),
+        symbol: Type.String({
+          minLength: 1,
+          description: "The symbol's name exactly as it appears on that line",
+        }),
+        new_name: Type.String({ minLength: 1, description: "The new name for the symbol" }),
+        character: Type.Optional(
+          Type.Integer({
+            minimum: 1,
+            description:
+              "1-based character offset of the symbol on that line. Only needed when the tool reports an ambiguity error on this line",
+          }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+
+      const filePath = resolvePathArg(ctx.cwd, params.file_path);
+      let content: string;
+      try {
+        await stat(filePath);
+        content = await readFile(filePath, "utf8");
+      } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+          throw new Error(`File does not exist: ${filePath}`, { cause: error });
+        }
+        throw error;
+      }
+
+      const notify = (message: string, level: "info" | "warning" | "error") =>
+        ctx.ui.notify(message, level);
+      const options = { notify, signal };
+
+      // ── 按 symbol 名枚举行内候选，逐候选探测与消歧 ────────────────────────
+      const candidates = symbolCandidates(
+        content,
+        params.line - 1,
+        params.symbol,
+        params.character === undefined ? undefined : params.character - 1,
+      );
+      if (candidates.length === 0) {
+        throw new Error(
+          `Symbol "${params.symbol}" not found on line ${params.line} of ${filePath}. Read the file again and locate the symbol.`,
+        );
+      }
+      const successes: { result: Awaited<ReturnType<typeof service.rename>> }[] = [];
+      const notPossibleErrors: string[] = [];
+      for (const candidate of candidates) {
+        signal?.throwIfAborted();
+        try {
+          const result = await service.rename({
+            file: filePath,
+            cwd: ctx.cwd,
+            line: candidate.line,
+            character: candidate.character,
+            newName: params.new_name,
+            options,
+          });
+          successes.push({ result });
+        } catch (error) {
+          if (error instanceof RenameNotPossibleError) {
+            notPossibleErrors.push(error.message);
+            continue;
+          }
+          throw error;
+        }
+      }
+      if (successes.length === 0) {
+        throw new RenameNotPossibleError(
+          notPossibleErrors.length > 0
+            ? notPossibleErrors.join("; ")
+            : `no renameable symbol "${params.symbol}" on line ${params.line} of ${filePath}`,
+        );
+      }
+
+      // 同一符号的多次出现编辑集合一致；不一致即为不同符号 → 要求补 character
+      const groups = new Map<
+        string,
+        { result: (typeof successes)[number]["result"]; candidates: typeof candidates }
+      >();
+      for (const [index, candidate] of candidates.entries()) {
+        const entry = successes[index];
+        if (!entry) continue;
+        const key = canonicalizeEdit(entry.result.edit);
+        const group = groups.get(key);
+        if (group) group.candidates.push(candidate);
+        else groups.set(key, { result: entry.result, candidates: [candidate] });
+      }
+      if (groups.size > 1) {
+        const listing = [...groups.values()]
+          .map((group) =>
+            group.candidates
+              .map(
+                (candidate) =>
+                  `- line ${candidate.line + 1}, column ${candidate.character + 1} (rename target: ${group.result.placeholder ?? "unknown"})`,
+              )
+              .join("\n"),
+          )
+          .join("\n");
+        throw new Error(
+          `Ambiguous rename target on line ${params.line} of ${filePath}: several distinct symbols share the name "${params.symbol}". Retry with 'character' (1-based) to pick one:\n${listing}`,
+        );
+      }
+      const firstGroup = [...groups.values()][0];
+      if (!firstGroup) throw new Error("LSP rename returned no target");
+      const { result } = firstGroup;
+
+      // ── 内存展开 → 审批 → 写盘 → 诊断 ────────────────────────────────────
+      signal?.throwIfAborted();
+      const applied = await expandWorkspaceEdit(result.edit, (path) => readFile(path, "utf8"));
+      if (applied.length === 0) {
+        throw new Error("LSP rename returned no edits");
+      }
+      for (const fileEdit of applied) {
+        await guardWriteAccess(ctx, {
+          toolName: "lsp-rename",
+          absolutePath: fileEdit.path,
+          change: { oldText: fileEdit.oldText, newText: fileEdit.newText },
+        });
+      }
+
+      const diffs: string[] = [];
+      for (const fileEdit of applied) {
+        await withFileMutationQueue(fileEdit.path, async () => {
+          await writeFile(fileEdit.path, fileEdit.newText, "utf8");
+        });
+        diffs.push(
+          `### ${fileEdit.path} (${fileEdit.changeCount} edit(s))\n\n\`\`\`diff\n${generateDiffString(fileEdit.oldText, fileEdit.newText).diff}\n\`\`\``,
+        );
+      }
+      const reads = hooks.recordReads === undefined ? undefined : await hooks.recordReads(applied);
+
+      let diagnosticText = "";
+      for (const fileEdit of applied) {
+        signal?.throwIfAborted();
+        const diagnostics = await service.lspDiagnosticsForFile(fileEdit.path, ctx.cwd, {
+          notify,
+          signal,
+        });
+        if (diagnostics.text !== "") diagnosticText += `${diagnostics.text}\n`;
+      }
+
+      const renamed =
+        result.placeholder !== undefined && result.placeholder !== params.new_name
+          ? `'${result.placeholder}' -> '${params.new_name}'`
+          : `to '${params.new_name}'`;
+      const summary = `Renamed ${renamed} across ${applied.length} file(s).`;
+      const text =
+        diagnosticText === ""
+          ? summary
+          : `${summary}\n\nLSP diagnostics detected in renamed files:\n${diagnosticText.trimEnd()}`;
+
+      return {
+        content: [{ type: "text" as const, text }],
+        details: {
+          ...(reads !== undefined && { reads }),
+          pendant: {
+            title: "lsp-rename",
+            subtitle: `${renamed} · ${applied.length} file(s)`,
+            markdown: diffs.join("\n\n"),
+          } satisfies ToolPendant,
+        },
+      };
+    },
+  });
+}

package/src/opencode/files.ts

@@ -1,9 +1,9 @@
 /**
  * Opencode File Tools —— read / edit / write 统一构建点。
  *
- * 三个工具在同一个 registerFileTools(pi, service) 里注册，共享同一个 LSP
- * service 实例（registerLsp 创建的闭包变量），与 claude-code/files.ts 共享
- * read-snapshot state 的方式一致；不再用模块级全局缓存。
+ * read / edit / write 三个工具在同一个 registerFileTools(pi, service) 里注册，
+ * 共享同一个 LSP service 实例（registerLsp 创建的闭包变量）；lsp-rename 的
+ * 工具壳与 claude-code 共享，同样挂进 registerFileTools。
  *
  * 对齐官方 v1（packages/opencode/src/tool/{read,edit,write}.ts）：
  * - read：流式分行（LF / CRLF / CR）、每行 `N: ` 行号前缀、单行 2000
@@ -31,6 +31,7 @@ import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
 import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
+import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import { applyEdit, normalizeToLF, stripBom } from "./edit-engine.js";
@@ -696,6 +697,9 @@ export function registerFileTools(pi: ExtensionAPI, service: LspService): void {
   registerReadTool(pi, service);
   registerEditTool(pi, service);
   registerWriteTool(pi, service);
+  // 工具壳与 claude-code 共享（lib/lsp/rename-tool.ts）；opencode 不跟踪
+  // read-before-write 状态，不传 recordReads hook。
+  registerLspRenameTool(pi, service);
 }
 
 /** 独立入口：创建 LSP service（闭包共享给三个工具）并注册。 */

package/src/spawn-agent.ts

@@ -89,7 +89,8 @@ const SETTINGS_PATH = join(getAgentDir(), "settings.json");
  * implementation file (they share a read-snapshot state); the `tools`
  * allowlist still exposes only the declared subset. The opencode file tools
  * (read/edit/write) likewise share opencode/files.ts (they share the LSP
- * service instance).
+ * service instance); that file also registers the shared `lsp-rename` tool,
+ * which stays hidden unless a subagent declares it.
  */
 const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   read: "opencode/files.ts",