@trim21/personal-pi-extensions 0.1.488 → 0.1.490

package/package.json

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

package/src/claude-code/files.ts

@@ -14,11 +14,11 @@ 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 { registerLspInspectTools } from "../lib/lsp/inspect-tool.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 +60,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,197 +675,23 @@ 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;
     },
   });
+  // 只读符号查询工具（find-definition / find-reference / inspect）与 opencode 共享。
+  registerLspInspectTools(pi, service);
 }
 
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */

package/src/lib/lsp/client.ts

@@ -20,7 +20,13 @@ import {
   StreamMessageReader,
   StreamMessageWriter,
 } from "vscode-jsonrpc/node";
-import type { Diagnostic as VSCodeDiagnostic, WorkspaceEdit } from "vscode-languageserver-types";
+import type {
+  Diagnostic as VSCodeDiagnostic,
+  Hover,
+  Location as LspLocation,
+  LocationLink,
+  WorkspaceEdit,
+} from "vscode-languageserver-types";
 
 import type { LspServerHandle } from "./adapter.js";
 import { LANGUAGE_EXTENSIONS } from "./language.js";
@@ -72,6 +78,20 @@ const LSP_CONTENT_MODIFIED = -32801;
  */
 export class RenameNotPossibleError extends Error {}
 
+/**
+ * 服务器不支持某 LSP 方法（MethodNotFound）。与传输失败区分，供服务层跳过
+ * 该服务器尝试下一个，而不是把整个操作当作失败。
+ */
+export class LspMethodNotSupportedError extends Error {
+  readonly serverID: string;
+  readonly method: string;
+  constructor(serverID: string, method: string) {
+    super(`LSP server "${serverID}" does not support ${method}`);
+    this.serverID = serverID;
+    this.method = method;
+  }
+}
+
 /**
  * rename edit 未覆盖 references 看到的全部文件：服务器索引可能仍在后台加载。
  * 抛出时发生在写盘之前，整个 rename 无副作用，可稍后重试。
@@ -148,6 +168,48 @@ export interface RenameSymbolResult {
   placeholder?: string;
 }
 
+/** definition / references / hover 请求的输入（line / character 为 0-based LSP position）。 */
+export interface InspectPositionRequest {
+  path: string;
+  line: number;
+  character: number;
+}
+
+/** definition / references 归一化后的位置（0-based；1-based 格式化由工具层负责）。 */
+export interface InspectLocation {
+  path: string;
+  line: number;
+  character: number;
+}
+
+type DefinitionResult = LspLocation | LspLocation[] | LocationLink | LocationLink[] | null;
+
+/** Location / LocationLink → path + 0-based 坐标；非 file: URI 是服务器的意外行为，跳过。 */
+function toInspectLocations(result: DefinitionResult): InspectLocation[] {
+  if (result === null) return [];
+  const items = Array.isArray(result) ? result : [result];
+  const locations: InspectLocation[] = [];
+  for (const item of items) {
+    if ("targetUri" in item) {
+      if (!item.targetUri.startsWith("file:")) continue;
+      const range = item.targetSelectionRange ?? item.targetRange;
+      locations.push({
+        path: normalize(fileURLToPath(item.targetUri)),
+        line: range.start.line,
+        character: range.start.character,
+      });
+    } else {
+      if (!item.uri.startsWith("file:")) continue;
+      locations.push({
+        path: normalize(fileURLToPath(item.uri)),
+        line: item.range.start.line,
+        character: item.range.start.character,
+      });
+    }
+  }
+  return locations;
+}
+
 export class InitializeError extends Error {
   readonly serverID: string;
   constructor(serverID: string, cause: unknown) {
@@ -241,6 +303,21 @@ export interface LspClient {
    * 位置不在符号上 / 服务器不支持 rename 时抛 RenameNotPossibleError。
    */
   renameSymbol(request: RenameSymbolRequest): Promise<RenameSymbolResult>;
+  /**
+   * textDocument/definition：归一化后的定义位置列表（Location / LocationLink
+   * 统一转 path + 0-based 坐标；无结果返回空数组）。
+   */
+  definition(request: InspectPositionRequest): Promise<InspectLocation[]>;
+  /**
+   * textDocument/references：归一化后的引用位置列表（是否含声明处由服务器
+   * 按 includeDeclaration 决定，此处固定包含，对齐 rename 覆盖校验口径）。
+   */
+  references(request: InspectPositionRequest): Promise<InspectLocation[]>;
+  /**
+   * textDocument/hover：服务器返回的 contents 原样透传，不做内容归一化；
+   * 服务器无信息时返回 null（合法应答，非错误）。
+   */
+  hover(request: InspectPositionRequest): Promise<Hover | null>;
   shutdown(): Promise<void>;
 }
 
@@ -922,6 +999,31 @@ export async function create(input: CreateInput): Promise<LspClient> {
     return 0;
   };
 
+  // ── 只读符号查询（definition / references / hover）──────────────────────────
+
+  /** 请求前先同步磁盘内容（didOpen/didChange），保证服务器基于最新文本应答。 */
+  const preparePositionRequest = async (request: InspectPositionRequest) => {
+    const resolvedPath = normalize(
+      isAbsolute(request.path) ? request.path : resolve(input.directory, request.path),
+    );
+    await openDocument({ path: resolvedPath });
+    return {
+      uri: pathToFileURL(resolvedPath).href,
+      position: { line: request.line, character: request.character },
+    };
+  };
+
+  const sendInspectRequest = async <T>(method: string, message: object): Promise<T> => {
+    try {
+      return await retryOnContentModified(() => connection.sendRequest<T>(method, message));
+    } catch (error) {
+      if (error instanceof ResponseError && error.code === LSP_METHOD_NOT_FOUND) {
+        throw new LspMethodNotSupportedError(input.serverID, method);
+      }
+      throw error;
+    }
+  };
+
   return {
     root: input.root,
     get serverID() {
@@ -1101,6 +1203,31 @@ export async function create(input: CreateInput): Promise<LspClient> {
         current = toPaths(await referencesRequest());
       }
     },
+    async definition(request: InspectPositionRequest): Promise<InspectLocation[]> {
+      const { uri, position } = await preparePositionRequest(request);
+      return toInspectLocations(
+        await sendInspectRequest<DefinitionResult>("textDocument/definition", {
+          textDocument: { uri },
+          position,
+        }),
+      );
+    },
+    async references(request: InspectPositionRequest): Promise<InspectLocation[]> {
+      const { uri, position } = await preparePositionRequest(request);
+      const locations = await sendInspectRequest<LspLocation[] | null>("textDocument/references", {
+        textDocument: { uri },
+        position,
+        context: { includeDeclaration: true },
+      });
+      return toInspectLocations(locations);
+    },
+    async hover(request: InspectPositionRequest): Promise<Hover | null> {
+      const { uri, position } = await preparePositionRequest(request);
+      return await sendInspectRequest<Hover | null>("textDocument/hover", {
+        textDocument: { uri },
+        position,
+      });
+    },
     get diagnostics() {
       const result = new Map<string, Diagnostic[]>();
       for (const key of new Set([...pushDiagnostics.keys(), ...pullDiagnostics.keys()])) {

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

@@ -0,0 +1,376 @@
+/**
+ * 只读 LSP 符号查询工具，由 claude-code / opencode 两个工具集共享注册：
+ *
+ * - lsp-find-definition：textDocument/definition → 定义位置列表
+ * - lsp-find-reference：textDocument/references（含声明处）→ 按文件分组
+ * - lsp-inspect：textDocument/hover → hover 内容原样透传
+ *
+ * 三个工具共用 lsp-rename 的定位与消歧语义（file_path + line + symbol，
+ * character 消歧）：按词边界枚举行内候选逐个探测，格式化输出一致即视为
+ * 同一符号的多次出现，不一致报歧义并列出候选列号。
+ */
+
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Hover } from "vscode-languageserver-types";
+
+import { resolvePathArg } from "../path.js";
+import type { InspectLocation } from "./client.js";
+import type { LspService } from "./lsp.js";
+import { type LspPosition, symbolCandidates } from "./rename.js";
+
+/** references 输出上限：每文件最多列出的行片段数。 */
+const MAX_ENTRIES_PER_FILE = 10;
+/** references 输出上限：最多列出片段的文件数，超出部分按计数汇总。 */
+const MAX_FILES_LISTED = 30;
+const MAX_SNIPPET_LENGTH = 200;
+
+/** 一次探测的产出：text 是消歧分组键，subtitle 供 pendant 摘要。 */
+interface InspectOutput {
+  text: string;
+  subtitle: string;
+}
+
+function loadPrompt(fileName: string): string {
+  return readFileSync(fileURLToPath(new URL(fileName, import.meta.url)), "utf8").trim();
+}
+
+const FIND_DEFINITION_PROMPT = loadPrompt("lsp-find-definition.md");
+const FIND_REFERENCE_PROMPT = loadPrompt("lsp-find-reference.md");
+const INSPECT_PROMPT = loadPrompt("lsp-inspect.md");
+
+const POSITION_SCHEMA = 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",
+    }),
+    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 function readSymbolFile(
+  cwd: string,
+  filePathArg: string,
+): Promise<{ path: string; content: string }> {
+  const filePath = resolvePathArg(cwd, filePathArg);
+  try {
+    await stat(filePath);
+    const content = await readFile(filePath, "utf8");
+    return { path: filePath, content };
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error(`File does not exist: ${filePath}`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+/** 目标行内容片段（跨文件缓存；读取失败静默跳过片段，坐标仍然输出）。 */
+async function lineSnippet(
+  path: string,
+  line: number,
+  cache: Map<string, string[]>,
+): Promise<string> {
+  let lines = cache.get(path);
+  if (lines === undefined) {
+    try {
+      const content = await readFile(path, "utf8");
+      lines = content.split("\n");
+    } catch {
+      return "";
+    }
+    cache.set(path, lines);
+  }
+  const text = (lines[line] ?? "").replace(/\r$/, "");
+  return text.length > MAX_SNIPPET_LENGTH ? `${text.slice(0, MAX_SNIPPET_LENGTH)}…` : text;
+}
+
+function toCoordinates(location: InspectLocation): string {
+  return `${location.path}:${location.line + 1}:${location.character + 1}`;
+}
+
+async function formatDefinitionLocations(
+  locations: InspectLocation[],
+  cache: Map<string, string[]>,
+): Promise<InspectOutput> {
+  if (locations.length === 0) {
+    return { text: "No definition found for this symbol.", subtitle: "0 definition(s)" };
+  }
+  const lines = [`Found ${locations.length} definition(s):`];
+  for (const location of locations) {
+    const snippet = await lineSnippet(location.path, location.line, cache);
+    lines.push(`- ${toCoordinates(location)}${snippet === "" ? "" : `\n  ${snippet}`}`);
+  }
+  return {
+    text: lines.join("\n"),
+    subtitle: `${locations.length} definition(s)`,
+  };
+}
+
+async function formatReferenceLocations(
+  locations: InspectLocation[],
+  cache: Map<string, string[]>,
+): Promise<InspectOutput> {
+  if (locations.length === 0) {
+    return { text: "No references found for this symbol.", subtitle: "0 reference(s)" };
+  }
+  const byPath = new Map<string, InspectLocation[]>();
+  for (const location of locations) {
+    const existing = byPath.get(location.path);
+    if (existing) existing.push(location);
+    else byPath.set(location.path, [location]);
+  }
+  const paths = [...byPath.keys()];
+  const sections = [`Found ${locations.length} reference(s) in ${paths.length} file(s):`];
+  for (const path of paths.slice(0, MAX_FILES_LISTED)) {
+    const entries = byPath.get(path);
+    if (!entries) continue;
+    const shown = entries.slice(0, MAX_ENTRIES_PER_FILE);
+    sections.push(`### ${path} (${entries.length})`);
+    for (const entry of shown) {
+      const snippet = await lineSnippet(path, entry.line, cache);
+      sections.push(
+        `- ${entry.line + 1}:${entry.character + 1}${snippet === "" ? "" : `: ${snippet}`}`,
+      );
+    }
+    if (entries.length > shown.length) {
+      sections.push(`(+${entries.length - shown.length} more in this file)`);
+    }
+  }
+  const omitted = paths.slice(MAX_FILES_LISTED);
+  if (omitted.length > 0) {
+    const omittedCount = omitted.reduce((sum, path) => sum + (byPath.get(path)?.length ?? 0), 0);
+    sections.push(`(+${omittedCount} reference(s) in ${omitted.length} more file(s) not shown)`);
+  }
+  return {
+    text: sections.join("\n"),
+    subtitle: `${locations.length} reference(s) in ${paths.length} file(s)`,
+  };
+}
+
+type MarkedString = string | { language: string; value: string };
+
+function formatMarkedString(marked: MarkedString): string {
+  return typeof marked === "string" ? marked : `\`\`\`${marked.language}\n${marked.value}\n\`\`\``;
+}
+
+/** hover contents 原样透传：仅做结构格式化（MarkedString → code fence），不改写内容。 */
+function formatHoverContents(contents: Hover["contents"]): string {
+  if (typeof contents === "string") return contents;
+  if (Array.isArray(contents)) {
+    return contents.map((marked) => formatMarkedString(marked)).join("\n\n");
+  }
+  if ("language" in contents) return formatMarkedString(contents);
+  return contents.value;
+}
+
+/**
+ * 行内同名候选逐个探测：输出一致即同一符号的多次出现；不一致报歧义并列出
+ * 各候选的 1-based 列号（与 lsp-rename 的消歧行为一致）。
+ */
+async function probeSymbolCandidates(options: {
+  content: string;
+  filePath: string;
+  line: number;
+  symbol: string;
+  character?: number;
+  signal?: AbortSignal;
+  probe: (position: LspPosition) => Promise<InspectOutput>;
+}): Promise<InspectOutput> {
+  const candidates = symbolCandidates(
+    options.content,
+    options.line - 1,
+    options.symbol,
+    options.character === undefined ? undefined : options.character - 1,
+  );
+  if (candidates.length === 0) {
+    throw new Error(
+      `Symbol "${options.symbol}" not found on line ${options.line} of ${options.filePath}. Read the file again and locate the symbol.`,
+    );
+  }
+  const outputs: InspectOutput[] = [];
+  for (const candidate of candidates) {
+    options.signal?.throwIfAborted();
+    outputs.push(await options.probe(candidate));
+  }
+  const groups = new Map<string, { output: InspectOutput; candidates: LspPosition[] }>();
+  for (const [index, candidate] of candidates.entries()) {
+    const output = outputs[index];
+    if (!output) continue;
+    const group = groups.get(output.text);
+    if (group) group.candidates.push(candidate);
+    else groups.set(output.text, { output, candidates: [candidate] });
+  }
+  if (groups.size > 1) {
+    const listing = [...groups.values()]
+      .map((group) =>
+        group.candidates
+          .map((candidate) => `- line ${candidate.line + 1}, column ${candidate.character + 1}`)
+          .join("\n"),
+      )
+      .join("\n");
+    throw new Error(
+      `Ambiguous symbol on line ${options.line} of ${options.filePath}: several distinct symbols share the name "${options.symbol}". Retry with 'character' (1-based) to pick one:\n${listing}`,
+    );
+  }
+  const first = [...groups.values()][0];
+  if (!first) throw new Error("LSP inspect returned no result");
+  return first.output;
+}
+
+export function registerLspInspectTools(pi: ExtensionAPI, service: LspService): void {
+  pi.registerTool({
+    name: "lsp-find-definition",
+    label: "Lsp Find Definition",
+    description:
+      "Find where a code symbol is defined via LSP. Returns 1-based path:line:col locations with source line snippets.",
+    promptSnippet: "Find symbol definitions via LSP",
+    promptGuidelines: [FIND_DEFINITION_PROMPT],
+    parameters: POSITION_SCHEMA,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
+      const cache = new Map<string, string[]>();
+      const output = await probeSymbolCandidates({
+        content,
+        filePath,
+        line: params.line,
+        symbol: params.symbol,
+        character: params.character,
+        signal,
+        probe: async (position) => {
+          const result = await service.inspect({
+            file: filePath,
+            cwd: ctx.cwd,
+            line: position.line,
+            character: position.character,
+            query: "definition",
+            options: { signal },
+          });
+          return formatDefinitionLocations(result.locations, cache);
+        },
+      });
+      return {
+        content: [{ type: "text" as const, text: output.text }],
+        details: {
+          pendant: {
+            title: "lsp-find-definition",
+            subtitle: `${params.symbol} · ${output.subtitle}`,
+          },
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "lsp-find-reference",
+    label: "Lsp Find Reference",
+    description:
+      "Find all references to a code symbol across the workspace via LSP (includes the declaration). Grouped by file with 1-based line:col and source snippets.",
+    promptSnippet: "Find symbol references via LSP",
+    promptGuidelines: [FIND_REFERENCE_PROMPT],
+    parameters: POSITION_SCHEMA,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
+      const cache = new Map<string, string[]>();
+      const output = await probeSymbolCandidates({
+        content,
+        filePath,
+        line: params.line,
+        symbol: params.symbol,
+        character: params.character,
+        signal,
+        probe: async (position) => {
+          const result = await service.inspect({
+            file: filePath,
+            cwd: ctx.cwd,
+            line: position.line,
+            character: position.character,
+            query: "references",
+            options: { signal },
+          });
+          return formatReferenceLocations(result.locations, cache);
+        },
+      });
+      return {
+        content: [{ type: "text" as const, text: output.text }],
+        details: {
+          pendant: {
+            title: "lsp-find-reference",
+            subtitle: `${params.symbol} · ${output.subtitle}`,
+          },
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "lsp-inspect",
+    label: "Lsp Inspect",
+    description:
+      "Get hover information (type signature, documentation) for a code symbol via LSP. Content is passed through from the language server.",
+    promptSnippet: "Get hover info for a symbol via LSP",
+    promptGuidelines: [INSPECT_PROMPT],
+    parameters: POSITION_SCHEMA,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
+      const output = await probeSymbolCandidates({
+        content,
+        filePath,
+        line: params.line,
+        symbol: params.symbol,
+        character: params.character,
+        signal,
+        probe: async (position) => {
+          const result = await service.inspect({
+            file: filePath,
+            cwd: ctx.cwd,
+            line: position.line,
+            character: position.character,
+            query: "hover",
+            options: { signal },
+          });
+          if (result.hover === null) {
+            return {
+              text: `No hover information for '${params.symbol}' at line ${params.line} of ${filePath}.`,
+              subtitle: "no hover info",
+            };
+          }
+          return {
+            text: formatHoverContents(result.hover.contents),
+            subtitle: "hover",
+          };
+        },
+      });
+      return {
+        content: [{ type: "text" as const, text: output.text }],
+        details: {
+          pendant: { title: "lsp-inspect", subtitle: `${params.symbol} · ${output.subtitle}` },
+        },
+      };
+    },
+  });
+}

package/src/lib/lsp/lsp-find-definition.md

@@ -0,0 +1,8 @@
+## LSP Find Definition
+
+Find where a code symbol is defined and update nothing — read-only lookup via LSP.
+
+- 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.
+- Returns every definition site as `path:line:col` (1-based) with a source line snippet — imports, re-exports and overloads are resolved by the language server, unlike text search.

package/src/lib/lsp/lsp-find-reference.md

@@ -0,0 +1,8 @@
+## LSP Find Reference
+
+Find every reference to a code symbol across the workspace — read-only lookup via LSP.
+
+- 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.
+- Results are grouped by file with 1-based `line:col` and source snippets; the declaration site is included. Run it before `lsp-rename` to preview the blast radius.

package/src/lib/lsp/lsp-inspect.md

@@ -0,0 +1,8 @@
+## LSP Inspect
+
+Read a code symbol's hover information (type signature, documentation) without opening the file — read-only via LSP.
+
+- 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.
+- The hover content is passed through from the language server as-is.

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/lsp.ts

@@ -25,7 +25,7 @@ import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding
 import { minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
-import type { WorkspaceEdit } from "vscode-languageserver-types";
+import type { Hover, WorkspaceEdit } from "vscode-languageserver-types";
 
 import { type LspServerAdapter } from "./adapter.js";
 import {
@@ -33,6 +33,8 @@ import {
   type CreateInput,
   type Diagnostic,
   type Info as LspClient,
+  type InspectLocation,
+  LspMethodNotSupportedError,
   RenameNotPossibleError,
   WATCH_KIND_CHANGE,
   WATCH_KIND_CREATE,
@@ -242,6 +244,16 @@ interface LspState {
 /** 渲染 LSP status 文本的回调（传入 undefined 表示清除）。 */
 export type StatusRenderer = (text: string | undefined) => void;
 
+export type LspInspectQuery = "definition" | "references" | "hover";
+
+/**
+ * 返回类型与 query 泛型关联：query 为 "hover" 时返回 hover 内容，否则返回
+ * 位置列表。实现内部用 cast 建立关联（TS 无法验证分支与泛型的对应关系）。
+ */
+export type LspInspectResult<Q extends LspInspectQuery = LspInspectQuery> = Q extends "hover"
+  ? { serverID: string; query: "hover"; hover: Hover | null }
+  : { serverID: string; query: "definition" | "references"; locations: InspectLocation[] };
+
 export interface LspRequestOptions {
   notify?: ExtensionUIContext["notify"];
   /** 中止时提前结束诊断等待（已中止时直接跳过诊断）。 */
@@ -288,6 +300,19 @@ export interface LspService {
     newName: string;
     options?: LspRequestOptions;
   }): Promise<{ serverID: string; edit: WorkspaceEdit; placeholder?: string }>;
+  /**
+   * 只读符号查询（definition / references / hover）：只面向 kind 为 "language"
+   * 的服务器，按配置顺序取第一个成功结果；服务器不支持该方法（MethodNotFound）
+   * 时跳过并尝试下一个，全部不支持时抛聚合错误。line / character 为 0-based。
+   */
+  inspect<Q extends LspInspectQuery>(request: {
+    file: string;
+    cwd: string;
+    line: number;
+    character: number;
+    query: Q;
+    options?: LspRequestOptions;
+  }): Promise<LspInspectResult<Q>>;
   shutdownAll(): Promise<void>;
   /** 停止全部服务器并禁用 LSP：之后工具调用不再 spawn，直到 start/reload。 */
   stop(): Promise<void>;
@@ -690,6 +715,56 @@ export function createLspService(
       : new Error(`LSP rename failed on all servers — ${detail}`);
   }
 
+  /** 只读符号查询：与 rename 同款多服务器策略，但 MethodNotFound 是"跳过"而非失败。 */
+  async function inspect<Q extends LspInspectQuery>(request: {
+    file: string;
+    cwd: string;
+    line: number;
+    character: number;
+    query: Q;
+    options?: LspRequestOptions;
+  }): Promise<LspInspectResult<Q>> {
+    const clients = await getClients(
+      request.file,
+      request.cwd,
+      request.options?.notify,
+      (adapter) => adapter.kind !== "linter",
+    );
+    if (clients.length === 0) {
+      throw new Error(
+        `no LSP language server available for ${request.file} (check lsp.json servers and kind)`,
+      );
+    }
+    const failures: { serverID: string; error: unknown }[] = [];
+    for (const client of clients) {
+      const position = { path: request.file, line: request.line, character: request.character };
+      try {
+        if (request.query === "hover") {
+          const hover = await client.hover(position);
+          return { serverID: client.serverID, query: "hover", hover } as LspInspectResult<Q>;
+        }
+        const locations =
+          request.query === "definition"
+            ? await client.definition(position)
+            : await client.references(position);
+        return {
+          serverID: client.serverID,
+          query: request.query,
+          locations,
+        } as LspInspectResult<Q>;
+      } catch (error) {
+        failures.push({ serverID: client.serverID, error });
+      }
+    }
+    const allNotSupported = failures.every((f) => f.error instanceof LspMethodNotSupportedError);
+    const detail = failures
+      .map((f) => `${f.serverID}: ${f.error instanceof Error ? f.error.message : String(f.error)}`)
+      .join("; ");
+    throw allNotSupported
+      ? new LspMethodNotSupportedError("all configured servers", `textDocument/${request.query}`)
+      : new Error(`LSP inspect failed on all servers — ${detail}`);
+  }
+
   /** 关闭全部 client 并清空缓存；closing 置 true 让 in-flight spawn 自行退出。 */
   async function closeAll(): Promise<void> {
     state.closing = true;
@@ -752,6 +827,7 @@ export function createLspService(
     diagnostics,
     lspDiagnosticsForFile,
     rename,
+    inspect,
     shutdownAll,
     stop,
     start,

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
@@ -30,7 +30,9 @@ import {
 import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
+import { registerLspInspectTools } from "../lib/lsp/inspect-tool.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 +698,11 @@ 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);
+  // 只读符号查询工具（find-definition / find-reference / inspect）与 claude-code 共享。
+  registerLspInspectTools(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` and
+ * LSP inspect tools, which stay hidden unless a subagent declares them.
  */
 const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   read: "opencode/files.ts",