pi-readseek 0.4.24 → 0.4.26

package/index.ts

@@ -4,7 +4,10 @@ import { registerEditTool } from "./src/edit.js";
 import { registerGrepTool } from "./src/grep.js";
 import { registerSgTool } from "./src/sg.js";
 import { registerRefsTool } from "./src/refs.js";
+import { registerRenameTool } from "./src/rename.js";
+import { registerHoverTool } from "./src/hover.js";
 import { registerWriteTool } from "./src/write.js";
+import { registerDefTool } from "./src/def.js";
 import { SessionAnchors } from "./src/session-anchors.js";
 import { isReadSeekAvailable } from "./src/readseek-client.js";
 
@@ -23,5 +26,8 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	registerGrepTool(pi, { searchGuideline, onFileAnchored: markAnchored });
 	registerSgTool(pi, { onFileAnchored: markAnchored });
 	registerRefsTool(pi, { onFileAnchored: markAnchored });
+	registerRenameTool(pi);
+	registerHoverTool(pi);
+	registerDefTool(pi, { onFileAnchored: markAnchored });
 	registerWriteTool(pi, { onFileAnchored: markAnchored });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.4.24",
+  "version": "0.4.26",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.4.31",
+    "@jarkkojs/readseek": "^0.4.32",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/def.md

@@ -0,0 +1,24 @@
+---
+tools: def
+---
+
+Find structural symbol definitions. Calls `readseek def` which searches
+for the definition of a named symbol across a file or directory.
+
+## Parameters
+
+- `path` (optional): File or directory to search (default: ".").
+- `name` (optional): Qualified or unqualified symbol name. Required unless
+  `fromIdentify` is true.
+- `lang` (optional): Language override.
+- `fromIdentify` (optional): When true, reads identify output from a
+  previous identify call to extract the symbol name automatically.
+- `cached` (optional): Search tracked/indexed files in a Git repository.
+- `others` (optional): Search untracked files.
+- `ignored` (optional): Include ignored untracked files.
+
+## When to use
+
+- After a hover call, to jump to where a symbol is defined.
+- When the user asks "where is X defined?".
+- To find a function/class/type definition by its qualified name.

package/prompts/hover.md

@@ -0,0 +1,19 @@
+---
+tools: hover
+---
+
+Use hover to identify the identifier and enclosing symbol at a cursor
+position. Calls `readseek identify` with the file content sent via stdin
+so unsaved editor content is included.
+
+## Parameters
+
+- `path` (required): File path.
+- `line` (required): One-based cursor line.
+- `column` (optional): One-based cursor byte column.
+
+## When to use
+
+- Before a rename, to confirm the identifier under the cursor.
+- Before a go-to-definition, to get the qualified symbol name.
+- To inspect what symbol a specific line belongs to.

package/prompts/rename.md

@@ -0,0 +1,31 @@
+---
+tools: rename
+---
+
+Use rename to rename an identifier (variable, function, type, etc.) with
+binding accuracy. The tool calls `readseek rename` which resolves the
+lexical binding under the cursor and renames every occurrence that binds
+to the same declaration.
+
+## Parameters
+
+- `path` (required): File holding the binding to rename (a single regular file).
+- `line` (required): One-based cursor line of the binding to rename.
+- `column` (optional): One-based cursor byte column of the binding.
+- `to` (required): New name for the binding. Must be a plain identifier.
+- `workspace` (optional): When true, expands the rename across the project
+  root. The cursor file remains binding-accurate; other files are matched
+  by name (free uses only, local shadows excluded).
+- `apply` (optional, default true): When true, writes the edits to disk
+  after verifying line hashes. When false, returns the plan only.
+
+## When to use
+
+- The user asks to rename a symbol (function, variable, class, etc.).
+- The cursor position (line, optionally column) is known from an identify
+  call or from the user's editor context.
+
+## When not to use
+
+- For search-and-replace across files, use grep or sg.
+- For refactoring that requires adding/removing parameters, use edit.

package/src/def.ts

@@ -0,0 +1,148 @@
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import path from "node:path";
+
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { buildReadSeekLineWithHash, buildToolErrorResult } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { statSearchPathOrError } from "./stat-search-path.js";
+import { classifyReadSeekFailure, readseekDef } from "./readseek-client.js";
+import { searchPathParam, langParam, readseekGitSearchParams } from "./readseek-params.js";
+import { registerReadSeekTool } from "./register-tool.js";
+
+import { renderAnchoredFilesResult, renderReadSeekSearchCall } from "./tui-render-utils.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
+
+const DEF_PROMPT_METADATA = defineToolPromptMetadata({
+	promptUrl: new URL("../prompts/def.md", import.meta.url),
+	promptSnippet: "Find structural symbol definitions with readseek",
+});
+
+type DefParams = {
+	name?: string;
+	path?: string;
+	lang?: string;
+	fromIdentify?: boolean;
+	cached?: boolean;
+	others?: boolean;
+	ignored?: boolean;
+};
+
+interface DefToolOptions {
+	onFileAnchored?: FileAnchoredCallback;
+}
+
+export interface ExecuteDefOptions {
+	params: unknown;
+	signal: AbortSignal | undefined;
+	cwd: string;
+	onFileAnchored?: FileAnchoredCallback;
+}
+
+export async function executeDef(opts: ExecuteDefOptions): Promise<any> {
+	const { params, signal, cwd, onFileAnchored } = opts;
+	const p = params as DefParams;
+
+	if (!p.fromIdentify && (!p.name || !p.name.trim())) {
+		return buildToolErrorResult("def", "invalid-parameter", "def requires 'name' or 'fromIdentify'");
+	}
+
+	const searchPath = resolveToCwd(p.path ?? ".", cwd);
+
+	const statResult = await statSearchPathOrError("def", p.path, searchPath);
+	if (!statResult.ok) return statResult.error;
+
+	try {
+		const definitions = await readseekDef(searchPath, {
+			name: p.name,
+			fromIdentify: p.fromIdentify,
+			language: p.lang,
+			cached: p.cached,
+			others: p.others,
+			ignored: p.ignored,
+			signal,
+		});
+
+		if (definitions.length === 0) {
+			return {
+				content: [{ type: "text", text: "no definitions found" }],
+				details: {
+					readseekValue: { tool: "def", ok: true, path: searchPath, definitions: [] },
+				},
+			};
+		}
+
+		const files = new Map<string, { displayPath: string; path: string; lines: ReturnType<typeof buildReadSeekLineWithHash>[] }>();
+		for (const def of definitions) {
+			const abs = path.isAbsolute(def.file) ? def.file : path.resolve(cwd, def.file);
+			let file = files.get(abs);
+			if (!file) {
+				file = { displayPath: path.relative(cwd, abs) || abs, path: abs, lines: [] };
+				files.set(abs, file);
+			}
+			file.lines.push(buildReadSeekLineWithHash(def.line, def.line_hash, def.text));
+		}
+
+		const fileList = [...files.values()];
+		for (const file of fileList) {
+			onFileAnchored?.(file.path);
+		}
+
+		const textParts: string[] = [];
+		for (const file of fileList) {
+			textParts.push(file.displayPath);
+			for (const line of file.lines) {
+			textParts.push(`  ${line.line}:${line.hash} ${line.display}`);
+			}
+		}
+
+		return {
+			content: [{ type: "text", text: textParts.join("\n") }],
+			details: {
+				readseekValue: { tool: "def", ok: true, path: searchPath, definitions },
+			},
+		};
+	} catch (err: any) {
+		const failure = classifyReadSeekFailure(err);
+		return buildToolErrorResult("def", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+	}
+}
+
+export function registerDefTool(pi: ExtensionAPI, options: DefToolOptions = {}) {
+	registerReadSeekTool(pi, {
+		policy: "read-only",
+		pythonName: "def",
+		defaultExposure: "opt-in",
+	}, {
+		name: "def",
+		label: "Definition",
+		description: DEF_PROMPT_METADATA.description,
+		promptSnippet: DEF_PROMPT_METADATA.promptSnippet,
+		promptGuidelines: DEF_PROMPT_METADATA.promptGuidelines,
+		parameters: Type.Object({
+			name: Type.Optional(Type.String({ description: "Qualified or unqualified symbol name" })),
+			path: searchPathParam(),
+			lang: langParam(),
+			fromIdentify: Type.Optional(Type.Boolean({ description: "Read identify output from stdin to choose the symbol name" })),
+			...readseekGitSearchParams(),
+		}),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeDef({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
+		},
+		renderCall(args: any, theme: any, ...rest: any[]) {
+			return renderReadSeekSearchCall(args, theme, rest, {
+				label: "def",
+				accent: args.name,
+				flags: [args.fromIdentify && "from-identify", args.cached && "cached", args.others && "others", args.ignored && "ignored"],
+			});
+		},
+		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+			return renderAnchoredFilesResult(result, options, theme, rest, {
+				pendingLabel: "pending def",
+				emptyLabel: "no definitions",
+				unitSingular: "definition",
+				unitPlural: "definitions",
+			});
+		},
+	});
+}

package/src/hover.ts

@@ -0,0 +1,131 @@
+import { readFile } from "node:fs/promises";
+
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Text } from "@earendil-works/pi-tui";
+
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { buildToolErrorResult } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { classifyReadSeekFailure, readseekIdentify } from "./readseek-client.js";
+import { filePathParam, registerReadSeekTool } from "./register-tool.js";
+
+import { clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+
+const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
+	promptUrl: new URL("../prompts/hover.md", import.meta.url),
+	promptSnippet: "Identify the identifier and enclosing symbol at a cursor position",
+});
+
+const hoverSchema = Type.Object({
+	path: filePathParam(),
+	line: Type.Number({ description: "One-based cursor line" }),
+	column: Type.Optional(Type.Number({ description: "One-based cursor byte column" })),
+});
+
+interface HoverParams {
+	path: string;
+	line: number;
+	column?: number;
+}
+
+export interface ExecuteHoverOptions {
+	params: unknown;
+	signal: AbortSignal | undefined;
+	cwd: string;
+}
+
+export async function executeHover(opts: ExecuteHoverOptions): Promise<any> {
+	const { params, signal, cwd } = opts;
+	const p = params as HoverParams;
+
+	if (!Number.isSafeInteger(p.line) || p.line < 1) {
+		return buildToolErrorResult("hover", "invalid-parameter", "hover parameter 'line' must be a positive integer");
+	}
+
+	const filePath = resolveToCwd(p.path, cwd);
+
+	let content: string;
+	try {
+		content = await readFile(filePath, "utf-8");
+	} catch {
+		return buildToolErrorResult("hover", "file-not-found", `hover could not read ${p.path}`);
+	}
+
+	try {
+		const output = await readseekIdentify(filePath, content, {
+			line: p.line,
+			column: p.column,
+			signal,
+		});
+
+		const lines: string[] = [];
+		if (output.identifier) {
+			lines.push(`identifier: ${output.identifier.text}`);
+		}
+		if (output.symbol) {
+			lines.push(`symbol: ${output.symbol.name}`);
+			lines.push(`kind: ${output.symbol.kind}`);
+			lines.push(`qualified: ${output.symbol.qualified_name}`);
+		}
+		lines.push(`file: ${output.file}`);
+		lines.push(`language: ${output.language}`);
+		lines.push(`location: ${output.line}:${output.column}`);
+
+		return {
+			content: [{ type: "text", text: lines.join("\n") }],
+			details: {
+				readseekValue: {
+					tool: "hover",
+					ok: true,
+					path: filePath,
+					output,
+				},
+			},
+		};
+	} catch (err: any) {
+		const failure = classifyReadSeekFailure(err);
+		return buildToolErrorResult("hover", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+	}
+}
+
+export function registerHoverTool(pi: ExtensionAPI) {
+	registerReadSeekTool(pi, {
+		policy: "read-only",
+		pythonName: "hover",
+		defaultExposure: "opt-in",
+	}, {
+		name: "hover",
+		label: "Hover",
+		description: HOVER_PROMPT_METADATA.description,
+		promptSnippet: HOVER_PROMPT_METADATA.promptSnippet,
+		promptGuidelines: HOVER_PROMPT_METADATA.promptGuidelines,
+		parameters: hoverSchema,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeHover({ params, signal, cwd: ctx.cwd });
+		},
+		renderCall(args: any, theme: any, ...rest: any[]) {
+			const context = rest[0] ?? {};
+			const cwd = context.cwd ?? process.cwd();
+			const displayPath = typeof args?.path === "string" ? args.path : "?";
+			let text = theme.fg("toolTitle", theme.bold("hover"));
+			text += ` ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
+			if (args?.line) text += theme.fg("dim", `:${args.line}`);
+			return text;
+		},
+		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+			const { isPartial, isError, width } = resolveRenderResultContext(options, rest);
+
+			if (isPartial) return renderPendingResult("pending hover", width);
+
+			const content = result.content?.[0];
+			const textContent = content?.type === "text" ? content.text : "";
+
+			if (isError || result.isError) {
+			return new Text(textContent || "hover failed", 0, 0);
+			}
+
+		return new Text(textContent.split("\n")[0] || "", 0, 0);
+		},
+	});
+}

package/src/readseek-client.ts

@@ -708,3 +708,270 @@ export async function readseekDetect(
 	args.push(filePath);
 	return parseDetectOutput(await runReadSeek(args, { signal: options.signal }));
 }
+
+// --- Rename ---
+
+export interface RenameConflict {
+	line: number;
+	column: number;
+	reason: string;
+}
+
+export interface RenameEdit {
+	line: number;
+	start_column: number;
+	end_column: number;
+	start_byte: number;
+	end_byte: number;
+	occurrence: string;
+	line_hash: string;
+	text: string;
+}
+
+export interface RenameFileOutput {
+	file: string;
+	language: string;
+	engine?: string;
+	file_hash: string;
+	conflicts: RenameConflict[];
+	edits: RenameEdit[];
+}
+
+export interface RenameOutput {
+	file: string;
+	language: string;
+	engine?: string;
+	file_hash: string;
+	old_name: string;
+	new_name: string;
+	applied: boolean;
+	conflicts: RenameConflict[];
+	edits: RenameEdit[];
+	others: RenameFileOutput[];
+}
+
+interface RenameOptions {
+	to: string;
+	line: number;
+	column?: number;
+	workspace?: string;
+	apply?: boolean;
+	language?: string;
+	cached?: boolean;
+	others?: boolean;
+	ignored?: boolean;
+	signal?: AbortSignal;
+}
+
+function parseRenameOutput(value: unknown): RenameOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek rename output");
+	const output = value as Record<string, unknown>;
+	return {
+		file: requireString(output.file, "file"),
+		language: requireString(output.language, "language"),
+		engine: optionalString(output.engine, "engine"),
+		file_hash: requireString(output.file_hash, "file_hash"),
+		old_name: requireString(output.old_name, "old_name"),
+		new_name: requireString(output.new_name, "new_name"),
+		applied: requireBoolean(output.applied, "applied"),
+		conflicts: (output.conflicts as any[] | undefined)?.map((c: Record<string, unknown>) => ({
+			line: requireNumber(c.line, "conflict.line"),
+			column: requireNumber(c.column, "conflict.column"),
+			reason: requireString(c.reason, "conflict.reason"),
+		})) ?? [],
+		edits: (output.edits as any[] | undefined)?.map((e: Record<string, unknown>) => ({
+			line: requireNumber(e.line, "edit.line"),
+			start_column: requireNumber(e.start_column, "edit.start_column"),
+			end_column: requireNumber(e.end_column, "edit.end_column"),
+			start_byte: requireNumber(e.start_byte, "edit.start_byte"),
+			end_byte: requireNumber(e.end_byte, "edit.end_byte"),
+			occurrence: requireString(e.occurrence, "edit.occurrence"),
+			line_hash: requireString(e.line_hash, "edit.line_hash"),
+			text: requireString(e.text, "edit.text"),
+		})) ?? [],
+		others: (output.others as any[] | undefined)?.map((o: Record<string, unknown>) => ({
+			file: requireString(o.file, "other.file"),
+			language: requireString(o.language, "other.language"),
+			engine: optionalString(o.engine, "other.engine"),
+			file_hash: requireString(o.file_hash, "other.file_hash"),
+			conflicts: (o.conflicts as any[] | undefined)?.map((c: Record<string, unknown>) => ({
+				line: requireNumber(c.line, "conflict.line"),
+				column: requireNumber(c.column, "conflict.column"),
+				reason: requireString(c.reason, "conflict.reason"),
+			})) ?? [],
+			edits: (o.edits as any[] | undefined)?.map((e: Record<string, unknown>) => ({
+				line: requireNumber(e.line, "edit.line"),
+				start_column: requireNumber(e.start_column, "edit.start_column"),
+				end_column: requireNumber(e.end_column, "edit.end_column"),
+				start_byte: requireNumber(e.start_byte, "edit.start_byte"),
+				end_byte: requireNumber(e.end_byte, "edit.end_byte"),
+				occurrence: requireString(e.occurrence, "edit.occurrence"),
+				line_hash: requireString(e.line_hash, "edit.line_hash"),
+				text: requireString(e.text, "edit.text"),
+			})) ?? [],
+		})) ?? [],
+	};
+}
+
+export async function readseekRename(
+	filePath: string,
+	options: RenameOptions,
+): Promise<RenameOutput> {
+	const args = ["rename", filePath, "--line", String(options.line)];
+	if (options.column !== undefined) args.push("--column", String(options.column));
+	args.push("--to", options.to);
+	if (options.apply) args.push("--apply");
+	if (options.workspace) args.push("--workspace", options.workspace);
+	if (options.language) args.push("--language", options.language);
+	if (options.cached) args.push("--cached");
+	if (options.others) args.push("--others");
+	if (options.ignored) args.push("--ignored");
+	return parseRenameOutput(await runReadSeek(args, { signal: options.signal }));
+}
+
+// --- Identify ---
+
+export interface IdentifierOutput {
+	text: string;
+	start_column: number;
+	end_column: number;
+	start_byte: number;
+	end_byte: number;
+}
+
+export interface IdentifyOutput {
+	file: string;
+	language: string;
+	engine?: string;
+	line_count: number;
+	file_hash: string;
+	line: number;
+	column: number;
+	line_hash: string;
+	identifier?: IdentifierOutput;
+	symbol?: {
+		name: string;
+		kind: string;
+		qualified_name: string;
+		start_line: number;
+		end_line: number;
+	};
+}
+
+interface IdentifyOptions {
+	line?: number;
+	column?: number;
+	language?: string;
+	signal?: AbortSignal;
+}
+
+function parseIdentifyOutput(value: unknown): IdentifyOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek identify output");
+	const output = value as Record<string, unknown>;
+	const identifier = output.identifier;
+	const symbol = output.symbol;
+	return {
+		file: requireString(output.file, "file"),
+		language: requireString(output.language, "language"),
+		engine: optionalString(output.engine, "engine"),
+		line_count: requireNumber(output.line_count, "line_count"),
+		file_hash: requireString(output.file_hash, "file_hash"),
+		line: requireNumber(output.line, "line"),
+		column: requireNumber(output.column, "column"),
+		line_hash: requireString(output.line_hash, "line_hash"),
+		identifier: identifier && typeof identifier === "object"
+			? {
+				text: requireString((identifier as Record<string, unknown>).text, "identifier.text"),
+				start_column: requireNumber((identifier as Record<string, unknown>).start_column, "identifier.start_column"),
+				end_column: requireNumber((identifier as Record<string, unknown>).end_column, "identifier.end_column"),
+				start_byte: requireNumber((identifier as Record<string, unknown>).start_byte, "identifier.start_byte"),
+				end_byte: requireNumber((identifier as Record<string, unknown>).end_byte, "identifier.end_byte"),
+			}
+			: undefined,
+		symbol: symbol && typeof symbol === "object"
+			? {
+				name: requireString((symbol as Record<string, unknown>).name, "symbol.name"),
+				kind: requireString((symbol as Record<string, unknown>).kind, "symbol.kind"),
+				qualified_name: requireString((symbol as Record<string, unknown>).qualified_name, "symbol.qualified_name"),
+				start_line: requireNumber((symbol as Record<string, unknown>).start_line, "symbol.start_line"),
+				end_line: requireNumber((symbol as Record<string, unknown>).end_line, "symbol.end_line"),
+			}
+			: undefined,
+	};
+}
+
+export async function readseekIdentify(
+	filePath: string,
+	content: string,
+	options: IdentifyOptions = {},
+): Promise<IdentifyOutput> {
+	const args = ["identify", "--stdin", filePath];
+	if (options.line !== undefined) args.push("--line", String(options.line));
+	if (options.column !== undefined) args.push("--column", String(options.column));
+	if (options.language) args.push("--language", options.language);
+	return parseIdentifyOutput(await runReadSeek(args, { signal: options.signal, stdin: content }));
+}
+
+// --- Def ---
+
+export interface DefLocation {
+	file: string;
+	line: number;
+	column: number;
+	line_hash: string;
+	text: string;
+	kind?: string;
+	name?: string;
+	qualified_name?: string;
+}
+
+interface DefOptions {
+	name?: string;
+	fromIdentify?: boolean;
+	identifyInput?: string;
+	language?: string;
+	cached?: boolean;
+	others?: boolean;
+	ignored?: boolean;
+	signal?: AbortSignal;
+}
+
+function parseDefCompact(value: unknown): DefLocation[] {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek def output");
+	const output = value as Record<string, unknown>;
+	const locations = output.locations;
+	if (!Array.isArray(locations)) throw new Error("invalid readseek def locations");
+	return locations.map((loc) => {
+		if (!loc || typeof loc !== "object") throw new Error("invalid readseek def location");
+		const item = loc as Record<string, unknown>;
+		return {
+			file: requireString(item.file, "location.file"),
+			line: requireNumber(item.line, "location.line"),
+			column: requireNumber(item.column, "location.column"),
+			line_hash: requireString(item.line_hash, "location.line_hash"),
+			text: requireString(item.text, "location.text"),
+			kind: optionalString(item.kind, "location.kind"),
+			name: optionalString(item.name, "location.name"),
+			qualified_name: optionalString(item.qualified_name, "location.qualified_name"),
+		};
+	});
+}
+
+export async function readseekDef(
+	target: string,
+	options: DefOptions = {},
+): Promise<DefLocation[]> {
+	const args = ["def", target, "--format", "plain"];
+	if (options.fromIdentify) {
+		args.push("--from-identify");
+	}
+	if (options.name) {
+		args.push(options.name);
+	}
+	if (options.language) args.push("--language", options.language);
+	if (options.cached) args.push("--cached");
+	if (options.others) args.push("--others");
+	if (options.ignored) args.push("--ignored");
+	const stdin = options.fromIdentify && options.identifyInput ? options.identifyInput : undefined;
+	return parseDefCompact(await runReadSeek(args, { signal: options.signal, stdin }));
+}

package/src/rename.ts

@@ -0,0 +1,167 @@
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import path from "node:path";
+import { Text } from "@earendil-works/pi-tui";
+
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { buildToolErrorResult } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { classifyReadSeekFailure, readseekRename, type RenameOutput } from "./readseek-client.js";
+import { filePathParam, registerReadSeekTool } from "./register-tool.js";
+
+import { clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+
+const RENAME_PROMPT_METADATA = defineToolPromptMetadata({
+	promptUrl: new URL("../prompts/rename.md", import.meta.url),
+	promptSnippet: "Rename an identifier with binding-accurate readseek rename",
+});
+
+const renameSchema = Type.Object({
+	path: filePathParam(),
+	line: Type.Number({ description: "One-based cursor line of the binding to rename" }),
+	column: Type.Optional(Type.Number({ description: "One-based cursor byte column of the binding to rename" })),
+	to: Type.String({ description: "New name for the binding" }),
+	workspace: Type.Optional(Type.Boolean({ description: "Expand rename across project root (name-based outside cursor file)" })),
+	apply: Type.Optional(Type.Boolean({ description: "Write the planned edits to disk after verifying line hashes" })),
+});
+
+interface RenameParams {
+	path: string;
+	line: number;
+	column?: number;
+	to: string;
+	workspace?: boolean;
+	apply?: boolean;
+}
+
+export interface ExecuteRenameOptions {
+	params: unknown;
+	signal: AbortSignal | undefined;
+	cwd: string;
+}
+
+export async function executeRename(opts: ExecuteRenameOptions): Promise<any> {
+	const { params, signal, cwd } = opts;
+	const p = params as RenameParams;
+
+	if (!p.to.trim()) {
+		return buildToolErrorResult("rename", "invalid-parameter", "rename parameter 'to' must not be empty");
+	}
+	if (!Number.isSafeInteger(p.line) || p.line < 1) {
+		return buildToolErrorResult("rename", "invalid-parameter", "rename parameter 'line' must be a positive integer");
+	}
+
+	const filePath = resolveToCwd(p.path, cwd);
+
+	try {
+		const output = await readseekRename(filePath, {
+			to: p.to,
+			line: p.line,
+			column: p.column,
+			workspace: p.workspace ? cwd : undefined,
+			apply: p.apply ?? true,
+			signal,
+		});
+
+		const files: string[] = [output.file];
+		for (const other of output.others) {
+			const abs = path.isAbsolute(other.file) ? other.file : path.resolve(cwd, other.file);
+			if (!files.includes(abs)) files.push(abs);
+		}
+
+		const totalEdits = output.edits.length + output.others.reduce((sum, o) => sum + o.edits.length, 0);
+		const totalConflicts = output.conflicts.length + output.others.reduce((sum, o) => sum + o.conflicts.length, 0);
+
+		const parts: string[] = [];
+		if (totalConflicts > 0) {
+			parts.push(`${totalConflicts} naming conflict(s)`);
+		}
+		parts.push(`renamed ${output.old_name} to ${output.new_name} in ${totalEdits} location(s) across ${files.length} file(s)`);
+
+		let text = parts.join("; ");
+		if (output.applied) text += " (applied)";
+		else text += " (dry-run)";
+
+		// Surface first conflict reason for visibility
+		const firstConflict = output.conflicts[0]
+			?? output.others.find((o) => o.conflicts.length > 0)?.conflicts[0];
+		if (firstConflict) {
+			text += `\nFirst conflict at ${firstConflict.line}:${firstConflict.column}: ${firstConflict.reason}`;
+		}
+
+		return {
+			content: [{ type: "text", text }],
+			details: {
+				readseekValue: {
+					tool: "rename",
+					ok: true,
+					path: filePath,
+					output,
+				},
+			},
+		};
+	} catch (err: any) {
+		const failure = classifyReadSeekFailure(err);
+		return buildToolErrorResult("rename", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+	}
+}
+
+export function registerRenameTool(pi: ExtensionAPI) {
+	registerReadSeekTool(pi, {
+		policy: "mutating",
+		pythonName: "rename",
+		defaultExposure: "not-safe-by-default",
+	}, {
+		name: "rename",
+		label: "Rename",
+		description: RENAME_PROMPT_METADATA.description,
+		promptSnippet: RENAME_PROMPT_METADATA.promptSnippet,
+		promptGuidelines: RENAME_PROMPT_METADATA.promptGuidelines,
+		parameters: renameSchema,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeRename({ params, signal, cwd: ctx.cwd });
+		},
+		renderCall(args: any, theme: any, ...rest: any[]) {
+			const context = rest[0] ?? {};
+			const cwd = context.cwd ?? process.cwd();
+			const displayPath = typeof args?.path === "string" ? args.path : "?";
+			const oldName = typeof args?.to === "string" ? "" : "";
+			let text = theme.fg("toolTitle", theme.bold("rename"));
+			text += ` ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
+			if (args?.to) text += theme.fg("dim", ` → ${args.to}`);
+			return text;
+		},
+		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
+
+			if (isPartial) return renderPendingResult("pending rename", width);
+
+			const content = result.content?.[0];
+			const textContent = content?.type === "text" ? content.text : "";
+			const readseekValue = (result.details as any)?.readseekValue;
+			const output = readseekValue?.output as RenameOutput | undefined;
+
+			if (isError || result.isError) {
+			return new Text(textContent || "rename failed", 0, 0);
+			}
+
+		let text = summaryLine(
+			output?.applied
+				? `renamed ${output.old_name} → ${output.new_name}`
+				: `rename plan for ${output?.old_name ?? "?"} → ${output?.new_name ?? "?"} (dry-run)`,
+		);
+
+			if (expanded && output) {
+				const files = new Set<string>();
+				files.add(output.file);
+				for (const o of output.others) files.add(o.file);
+				for (const f of files) {
+					text += `\n  ${f}`;
+				}
+			}
+
+			const lines = clampLinesToWidth(text.split("\n"), width);
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+}