pi-readseek 0.6.4 → 0.6.5

package/README.md

@@ -23,8 +23,8 @@ npm install --save-dev @jarkkojs/readseek
 
 ## Tools
 
-- **readSeek_read:** reads text with `LINE:HASH` anchors; images and PDFs can
-  be returned as base64 or analyzed locally.
+- **readSeek_read:** reads text with `LINE:HASH` anchors; when image modes are
+  enabled, images and PDFs can be returned as base64 or analyzed locally.
 - **readSeek_edit:** edits existing text files using fresh `LINE:HASH` anchors.
 - **readSeek_grep:** searches text and returns edit-ready anchors.
 - **readSeek_search:** searches code by structural AST pattern.
@@ -32,6 +32,7 @@ npm install --save-dev @jarkkojs/readseek
 - **readSeek_rename:** plans or applies binding-aware renames.
 - **readSeek_hover:** identifies the cursor token and enclosing symbol.
 - **readSeek_def:** finds structural symbol definitions.
+- **readSeek_check:** checks a source file for parser errors and missing syntax.
 - **readSeek_write:** creates or overwrites whole files and returns anchors.
 
 ## Settings
@@ -64,8 +65,8 @@ optional (defaults shown):
   Valid values are `"read"`, `"edit"`, `"write"`, and `"grep"`. For a
   readseek-only file surface, use `["read", "edit", "write", "grep"]`.
 - **imageMode:** `"auto"` exposes `none`, `ocr`, `caption`, and `objects`;
-  `"on"` omits `none`; `"off"` skips image/PDF files. Omitting `image` also
-  skips visual files.
+  `"on"` omits `none`; `"off"` removes the `image` parameter and always skips
+  image/PDF files. Omitting `image` also skips visual files.
 - **syntaxValidation:** pre-write syntax-regression check in `readSeek_edit`:
   `"warn"` writes with a warning, `"block"` aborts without writing, `"off"`
   skips the check.

package/index.ts

@@ -2,12 +2,13 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerReadTool } from "./src/read.js";
 import { registerEditTool } from "./src/edit.js";
 import { registerGrepTool } from "./src/grep.js";
-import { registerSgTool } from "./src/sg.js";
+import { registerSearchTool } from "./src/search.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 { registerCheckTool } from "./src/check.js";
 import { SessionAnchors } from "./src/session-anchors.js";
 import { readSeekBinaryAvailability } from "./src/readseek-client.js";
 import { resolveReadSeekJsonSettings, type ReadSeekSettingsWarning } from "./src/readseek-settings.js";
@@ -37,6 +38,7 @@ const READSEEK_TOOL_ENTRIES: ReadonlyArray<{ builtIn: ReplacedBuiltIn | null; re
 	{ builtIn: null, readSeekName: "readSeek_hover" },
 	{ builtIn: "write", readSeekName: "readSeek_write" },
 	{ builtIn: null, readSeekName: "readSeek_def" },
+	{ builtIn: null, readSeekName: "readSeek_check" },
 ];
 
 function formatSettingsWarning(warning: ReadSeekSettingsWarning): string {
@@ -47,6 +49,7 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	const sessionAnchors = new SessionAnchors();
 	const markAnchored = (absolutePath: string) => sessionAnchors.markAnchored(absolutePath);
 	const hasFreshAnchors = (absolutePath: string) => sessionAnchors.hasFreshAnchors(absolutePath);
+	const forgetAnchors = (absolutePath: string) => sessionAnchors.forget(absolutePath);
 
 	// Resolve replacedTools at load time so the readSeek implementation is
 	// registered under the built-in name (e.g. "edit") when replaced. Extension
@@ -76,16 +79,18 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	};
 
 	registerReadTool(pi, { onSuccessfulRead: markAnchored, name: readName });
-	registerEditTool(pi, { wasReadInSession: hasFreshAnchors, name: editName, toolAliases });
+	registerEditTool(pi, { wasReadInSession: hasFreshAnchors, onFileMutated: forgetAnchors, name: editName, toolAliases });
 	registerGrepTool(pi, { onFileAnchored: markAnchored, name: grepName });
-	registerSgTool(pi, { onFileAnchored: markAnchored });
+	registerSearchTool(pi, { onFileAnchored: markAnchored });
 	registerRefsTool(pi, { onFileAnchored: markAnchored });
-	registerRenameTool(pi);
+	registerRenameTool(pi, { onFileMutated: forgetAnchors });
 	registerHoverTool(pi);
 	registerDefTool(pi, { onFileAnchored: markAnchored });
+	registerCheckTool(pi);
 	registerWriteTool(pi, { onFileAnchored: markAnchored, name: writeName });
 
 	pi.on("session_start", (_event, ctx) => {
+		sessionAnchors.clear();
 		const { warnings } = resolveReadSeekJsonSettings();
 		const problems = warnings.map(formatSettingsWarning);
 
@@ -121,4 +126,4 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 		pi.setActiveTools([...new Set(activeTools)]);
 	});
 
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "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.6.4",
+    "@jarkkojs/readseek": "^0.6.5",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/check.md

@@ -0,0 +1,9 @@
+Check a source file for parser errors and missing syntax. Use after edits for quick syntax validation, not as a compiler or linter.
+
+## Parameters
+
+- `path` - source file to check.
+
+## Output
+
+Returns parser error and missing-node counts with affected line ranges.

package/prompts/hover.md

@@ -1,4 +1,4 @@
-Identify the token and enclosing symbol at a cursor. Use before rename or definition lookup, or to identify a line's enclosing symbol; unsaved editor content is included.
+Identify the token and enclosing symbol at a cursor. Use before rename or definition lookup, or to identify a line's enclosing symbol. The file is read from disk.
 
 ## Parameters
 

package/prompts/read.md

@@ -14,9 +14,9 @@ Read anchored text by range, map, or symbol, and process images or PDFs with an
 - `map` — full-file map; incompatible with `symbol` or `bundle`.
 - `symbol` — `Name`, `Class.method`, or `Name@<line>`; incompatible with `offset` / `limit`.
 - `bundle` — only `"local"`; requires `symbol` and excludes `map`.
-- `image` — an exposed image/PDF mode.
+- `image` — an exposed image/PDF mode; unavailable when `imageMode` is `"off"`.
 
-Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. Omitting `image` skips images and PDFs.
+Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. Omitting `image` skips images and PDFs; when `imageMode` is `"off"`, visual files are always skipped.
 
 Truncated full-file reads append a map when available. Use its ranges for follow-up reads.
 

package/prompts/write.md

@@ -2,8 +2,8 @@ Create or replace a complete file and return `LINE:HASH` anchors. Use for new or
 
 ## Use / avoid
 
-Existing files are overwritten without confirmation. Binary-looking content gets
-no anchors.
+Existing files are overwritten without confirmation. Binary-looking content is
+rejected without writing.
 
 ## Parameters
 
@@ -13,6 +13,7 @@ no anchors.
 
 ## Output
 
-Text writes return `LINE:HASH|content`. Visible output is capped at 2000 lines or
-50 KB; full anchors remain in `readSeekValue`. Results also include a compact
+Text writes return `LINE:HASH|content`. Visible output is capped at
+{{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}; full anchors remain in
+`readSeekValue`. Results also include a compact
 diff, unified patch, and structured `details.diffData`.

package/src/check.ts

@@ -0,0 +1,92 @@
+import { readFile } from "node:fs/promises";
+
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+
+import { classifyReadSeekFailure, readSeekCheck, type ReadSeekCheckOutput } from "./readseek-client.js";
+import { buildToolErrorResult } from "./readseek-value.js";
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { formatFsError } from "./fs-error.js";
+import { resolveToCwd } from "./path-utils.js";
+import { filePathParam, registerReadSeekTool } from "./register-tool.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+
+const CHECK_PROMPT_METADATA = defineToolPromptMetadata({
+  promptUrl: new URL("../prompts/check.md", import.meta.url),
+  promptSnippet: "Check a source file for parser errors and missing syntax",
+});
+
+export async function executeCheck(opts: {
+  params: unknown;
+  signal: AbortSignal | undefined;
+  cwd: string;
+}): Promise<any> {
+  const { params, signal, cwd } = opts;
+  const p = params as { path: string };
+  const filePath = resolveToCwd(p.path, cwd);
+
+  let content: string;
+  try {
+    content = await readFile(filePath, "utf-8");
+  } catch (err: any) {
+    const { code, message } = formatFsError(err, "check-error");
+    return buildToolErrorResult("check", code, message, { path: p.path });
+  }
+
+  try {
+    const output = await readSeekCheck(filePath, content, { signal });
+    const lines = output.diagnostics.map((diagnostic) =>
+      `${diagnostic.kind}: lines ${diagnostic.start_line}-${diagnostic.end_line}`,
+    );
+    const summary = output.errorCount === 0 && output.missingCount === 0
+      ? "No syntax errors found."
+      : `${output.errorCount} error(s), ${output.missingCount} missing syntax node(s)`;
+    return {
+      content: [{ type: "text", text: [summary, ...lines].join("\n") }],
+      details: {
+        readSeekValue: { tool: "check", ok: true, path: filePath, output },
+      },
+    };
+  } catch (err: any) {
+    const failure = classifyReadSeekFailure(err);
+    return buildToolErrorResult("check", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+  }
+}
+
+export function registerCheckTool(pi: ExtensionAPI) {
+  return registerReadSeekTool(pi, {
+    name: "readSeek_check",
+    label: "Check",
+    description: CHECK_PROMPT_METADATA.description,
+    promptSnippet: CHECK_PROMPT_METADATA.promptSnippet,
+    promptGuidelines: CHECK_PROMPT_METADATA.promptGuidelines,
+    parameters: Type.Object({ path: filePathParam() }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return executeCheck({ 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 text = `${theme.fg("toolTitle", theme.bold("check"))} ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
+      return new Text(clampLineToWidth(text, context.width), 0, 0);
+    },
+    renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+      const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
+      if (isPartial) return renderPendingResult("pending check", width, theme);
+      const textContent = result.content?.[0]?.type === "text" ? result.content[0].text : "";
+      if (isError || result.isError) {
+        return renderErrorResult(textContent, { expanded, width, fallback: "check failed", theme });
+      }
+      const output = (result.details as any)?.readSeekValue?.output as ReadSeekCheckOutput | undefined;
+      const issueCount = (output?.errorCount ?? 0) + (output?.missingCount ?? 0);
+      let text = summaryLine(issueCount === 0 ? "syntax valid" : `${issueCount} syntax issue(s)`, {
+        theme,
+        style: issueCount === 0 ? "success" : "warning",
+      });
+      if (expanded && textContent) text += `\n${textContent}`;
+      return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+    },
+  });
+}

package/src/def.ts

@@ -7,7 +7,7 @@ import { buildReadSeekLineWithHash, buildToolErrorResult } from "./readseek-valu
 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 { searchPathParam, langParam, readSeekGitSearchParams, validateIgnoredRequiresOthers } from "./readseek-params.js";
 import { registerReadSeekTool } from "./register-tool.js";
 
 import { renderAnchoredFilesResult, renderReadSeekSearchCall } from "./tui-render-utils.js";
@@ -41,6 +41,8 @@ export interface ExecuteDefOptions {
 export async function executeDef(opts: ExecuteDefOptions): Promise<any> {
 	const { params, signal, cwd, onFileAnchored } = opts;
 	const p = params as DefParams;
+	const ignoredError = validateIgnoredRequiresOthers("def", p);
+	if (ignoredError) return ignoredError;
 
 	if (!p.name || !p.name.trim()) {
 		return buildToolErrorResult("def", "invalid-parameter", "readSeek_def requires 'name'");

package/src/edit.ts

@@ -26,7 +26,7 @@ import { buildEditPreviewKey, buildPendingEditPreviewData, resolvePendingDiffPre
 import { buildDiffData, type DiffBlockRange } from "./diff-data.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { upsertDiffComponent, upsertTextComponent } from "./tui-diff-component.js";
-import type { FreshAnchorsPredicate } from "./tool-types.js";
+import type { FileMutatedCallback, FreshAnchorsPredicate } from "./tool-types.js";
 import { filePathParam, registerReadSeekTool } from "./register-tool.js";
 
 const EDIT_PENDING_PREVIEW_STATE_KEY = "hashline-edit-pending-preview";
@@ -40,19 +40,19 @@ function pendingPreviewLines(summary: string, preview: PendingDiffPreviewResult
 
 
 const hashlineEditItemSchema = Type.Union([
-	Type.Object({ set_line: Type.Object({ anchor: Type.String(), new_text: Type.String() }) }, { additionalProperties: true }),
+	Type.Object({ set_line: Type.Object({ anchor: Type.String(), new_text: Type.String() }) }, { additionalProperties: false }),
 	Type.Object(
 		{ replace_lines: Type.Object({ start_anchor: Type.String(), end_anchor: Type.String(), new_text: Type.String() }) },
-		{ additionalProperties: true },
+		{ additionalProperties: false },
 	),
-	Type.Object({ insert_after: Type.Object({ anchor: Type.String(), new_text: Type.String() }) }, { additionalProperties: true }),
+	Type.Object({ insert_after: Type.Object({ anchor: Type.String(), new_text: Type.String() }) }, { additionalProperties: false }),
 	Type.Object(
 		{ replace: Type.Object({ old_text: Type.String(), new_text: Type.String(), all: Type.Optional(Type.Boolean()), fuzzy: Type.Optional(Type.Boolean()) }) },
-		{ additionalProperties: true },
+		{ additionalProperties: false },
 	),
 	Type.Object(
 		{ replace_symbol: Type.Object({ symbol: Type.String(), new_body: Type.String() }) },
-		{ additionalProperties: true },
+		{ additionalProperties: false },
 	),
 ]);
 
@@ -107,6 +107,7 @@ function mapEditFileError(err: any, filePath: string, _displayPath: string, _pha
 
 export interface EditToolOptions {
 	wasReadInSession?: FreshAnchorsPredicate;
+	onFileMutated?: FileMutatedCallback;
 	syntaxValidate?: SyntaxValidateOptions["syntaxValidate"];
 	name?: string;
 	toolAliases?: Readonly<Record<string, string>>;
@@ -117,11 +118,12 @@ export interface ExecuteEditOptions {
 	signal: AbortSignal | undefined;
 	cwd: string;
 	wasReadInSession?: FreshAnchorsPredicate;
+	onFileMutated?: FileMutatedCallback;
 	syntaxValidate?: SyntaxValidateOptions["syntaxValidate"];
 }
 
 export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
-	const { params, signal, cwd, wasReadInSession, syntaxValidate } = opts;
+	const { params, signal, cwd, wasReadInSession, onFileMutated, syntaxValidate } = opts;
 	await ensureHashInit();
 	const parsed = params as HashlineParams;
 	const input = params as Record<string, unknown>;
@@ -469,6 +471,7 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 	} catch (err: any) {
 		return mapEditFileError(err, absolutePath, path, "write");
 	}
+	onFileMutated?.(absolutePath);
 
 	if (input.postEditVerify === true) {
 		let verifiedContent: string;
@@ -585,6 +588,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 				signal,
 				cwd: ctx.cwd,
 				wasReadInSession: options.wasReadInSession,
+				onFileMutated: options.onFileMutated,
 				syntaxValidate: options.syntaxValidate,
 			});
 		},

package/src/hashline.ts

@@ -15,7 +15,8 @@ export type HashlineEditItem =
 	| { set_line: { anchor: string; new_text: string } }
 	| { replace_lines: { start_anchor: string; end_anchor: string; new_text: string } }
 	| { insert_after: { anchor: string; new_text: string } }
-	| { replace: { old_text: string; new_text: string; all?: boolean } };
+	| { replace: { old_text: string; new_text: string; all?: boolean; fuzzy?: boolean } }
+	| { replace_symbol: { symbol: string; new_body: string } };
 
 interface HashMismatch {
 	line: number;

package/src/hover.ts

@@ -20,8 +20,8 @@ const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
 
 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" })),
+	line: Type.Integer({ minimum: 1, description: "One-based cursor line" }),
+	column: Type.Optional(Type.Integer({ minimum: 1, description: "One-based cursor byte column" })),
 });
 
 interface HoverParams {
@@ -43,6 +43,9 @@ export async function executeHover(opts: ExecuteHoverOptions): Promise<any> {
 	if (!Number.isSafeInteger(p.line) || p.line < 1) {
 		return buildToolErrorResult("hover", "invalid-parameter", "hover parameter 'line' must be a positive integer");
 	}
+	if (p.column !== undefined && (!Number.isSafeInteger(p.column) || p.column < 1)) {
+		return buildToolErrorResult("hover", "invalid-parameter", "hover parameter 'column' must be a positive integer");
+	}
 
 	const filePath = resolveToCwd(p.path, cwd);
 

package/src/read.ts

@@ -530,12 +530,14 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 	const tool = registerReadSeekTool(pi, {
 		name,
 		label: "Read",
-		description: promptMetadata.description,
+		description: imageMode === "off"
+			? 'Read anchored text by range, map, or symbol; image and PDF files are skipped because imageMode is "off".'
+			: promptMetadata.description,
 		promptSnippet: promptMetadata.promptSnippet,
 		promptGuidelines: [
 			...promptMetadata.promptGuidelines,
 			imageMode === "off"
-				? "Image and PDF reads are disabled."
+				? "The image parameter is unavailable; image and PDF files are always skipped."
 				: `For an image or PDF, explicitly choose image: ${imageModes.join(", ")}; omitting image skips the file.`,
 		],
 		parameters: Type.Object({

package/src/rename.ts

@@ -8,6 +8,7 @@ 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 type { FileMutatedCallback } from "./tool-types.js";
 
 import { clampLineToWidth, clampLinesToWidth, linkedPathLine, linkToolPath, renderErrorResult, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 
@@ -18,8 +19,8 @@ const RENAME_PROMPT_METADATA = defineToolPromptMetadata({
 
 const renameSchema = Type.Object({
 	path: filePathParam(),
-	line: Type.Number({ description: "One-based line of the symbol to rename" }),
-	column: Type.Optional(Type.Number({ description: "One-based byte column for disambiguation" })),
+	line: Type.Integer({ minimum: 1, description: "One-based line of the symbol to rename" }),
+	column: Type.Optional(Type.Integer({ minimum: 1, description: "One-based byte column for disambiguation" })),
 	to: Type.String({ description: "New symbol name" }),
 	workspace: Type.Optional(Type.Boolean({ description: "Rename across the project" })),
 	apply: Type.Optional(Type.Boolean({ description: "Apply the verified edits; default true" })),
@@ -38,10 +39,11 @@ export interface ExecuteRenameOptions {
 	params: unknown;
 	signal: AbortSignal | undefined;
 	cwd: string;
+	onFileMutated?: FileMutatedCallback;
 }
 
 export async function executeRename(opts: ExecuteRenameOptions): Promise<any> {
-	const { params, signal, cwd } = opts;
+	const { params, signal, cwd, onFileMutated } = opts;
 	const p = params as RenameParams;
 
 	if (!p.to.trim()) {
@@ -50,6 +52,9 @@ export async function executeRename(opts: ExecuteRenameOptions): Promise<any> {
 	if (!Number.isSafeInteger(p.line) || p.line < 1) {
 		return buildToolErrorResult("rename", "invalid-parameter", "rename parameter 'line' must be a positive integer");
 	}
+	if (p.column !== undefined && (!Number.isSafeInteger(p.column) || p.column < 1)) {
+		return buildToolErrorResult("rename", "invalid-parameter", "rename parameter 'column' must be a positive integer");
+	}
 
 	const filePath = resolveToCwd(p.path, cwd);
 
@@ -62,6 +67,13 @@ export async function executeRename(opts: ExecuteRenameOptions): Promise<any> {
 			apply: p.apply ?? true,
 			signal,
 		});
+		if (output.applied) {
+			for (const file of [output, ...output.others]) {
+				if (file.edits.length === 0) continue;
+				const absoluteFile = path.isAbsolute(file.file) ? file.file : path.resolve(cwd, file.file);
+				onFileMutated?.(absoluteFile);
+			}
+		}
 
 		const files: string[] = [output.file];
 		for (const other of output.others) {
@@ -106,7 +118,7 @@ export async function executeRename(opts: ExecuteRenameOptions): Promise<any> {
 	}
 }
 
-export function registerRenameTool(pi: ExtensionAPI) {
+export function registerRenameTool(pi: ExtensionAPI, options: { onFileMutated?: FileMutatedCallback } = {}) {
 	registerReadSeekTool(pi, {
 		name: "readSeek_rename",
 		label: "Rename",
@@ -115,7 +127,7 @@ export function registerRenameTool(pi: ExtensionAPI) {
 		promptGuidelines: RENAME_PROMPT_METADATA.promptGuidelines,
 		parameters: renameSchema,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			return executeRename({ params, signal, cwd: ctx.cwd });
+			return executeRename({ params, signal, cwd: ctx.cwd, onFileMutated: options.onFileMutated });
 		},
 		renderCall(args: any, theme: any, ...rest: any[]) {
 			const context = rest[0] ?? {};

package/src/{sg-output.ts → search-output.ts}

@@ -1,6 +1,6 @@
 import { formatAnchoredFileBlocks, type ReadSeekLine, type ReadSeekRange } from "./readseek-value.js";
 
-export interface SgOutputFile {
+export interface SearchOutputFile {
   displayPath: string;
   path: string;
   ranges: ReadSeekRange[];
@@ -8,12 +8,12 @@ export interface SgOutputFile {
   symbols?: Array<{ name: string; kind?: string }>;
 }
 
-export interface BuildSgOutputInput {
+export interface BuildSearchOutputInput {
   pattern: string;
-  files: SgOutputFile[];
+  files: SearchOutputFile[];
 }
 
-export interface SgOutputResult {
+export interface SearchOutputResult {
   text: string;
   readSeekValue: {
     tool: "search";
@@ -25,7 +25,7 @@ export interface SgOutputResult {
   };
 }
 
-export function buildSgOutput(input: BuildSgOutputInput): SgOutputResult {
+export function buildSearchOutput(input: BuildSearchOutputInput): SearchOutputResult {
   if (input.files.length === 0) {
     return {
       text: `No matches found for pattern: ${input.pattern}`,

package/src/{sg.ts → search.ts}

@@ -8,31 +8,31 @@ import { buildReadSeekLineWithHash, buildToolErrorResult, type ReadSeekLine } fr
 import { resolveToCwd } from "./path-utils.js";
 import { statSearchPathOrError } from "./stat-search-path.js";
 import { classifyReadSeekFailure, readSeekSearch, type ReadSeekHashline, type ReadSeekSearchFileOutput } from "./readseek-client.js";
-import { buildSgOutput } from "./sg-output.js";
+import { buildSearchOutput } from "./search-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { langParam, readSeekGitSearchParams, searchPathParam, validateIgnoredRequiresOthers } from "./readseek-params.js";
 import { registerReadSeekTool } from "./register-tool.js";
 
 import { renderAnchoredFilesResult, renderReadSeekSearchCall } from "./tui-render-utils.js";
 
-type SgParams = { pattern: string; lang?: string; path?: string; cached?: boolean; others?: boolean; ignored?: boolean };
+type SearchParams = { pattern: string; lang?: string; path?: string; cached?: boolean; others?: boolean; ignored?: boolean };
 
-export interface SgRange {
+export interface SearchRange {
   startLine: number;
   endLine: number;
 }
 
-export interface SgEnclosingSymbol {
+export interface SearchEnclosingSymbol {
   name: string;
   kind: string;
 }
 
-export function mergeRanges(ranges: SgRange[]): SgRange[] {
+export function mergeRanges(ranges: SearchRange[]): SearchRange[] {
   if (ranges.length === 0) return [];
   if (ranges.length === 1) return [{ ...ranges[0] }];
 
   const sorted = [...ranges].sort((a, b) => a.startLine - b.startLine);
-  const merged: SgRange[] = [{ ...sorted[0] }];
+  const merged: SearchRange[] = [{ ...sorted[0] }];
 
   for (let i = 1; i < sorted.length; i++) {
     const current = sorted[i];
@@ -47,19 +47,19 @@ export function mergeRanges(ranges: SgRange[]): SgRange[] {
   return merged;
 }
 
-const SG_PROMPT_METADATA = defineToolPromptMetadata({
-  promptUrl: new URL("../prompts/sg.md", import.meta.url),
+const SEARCH_PROMPT_METADATA = defineToolPromptMetadata({
+  promptUrl: new URL("../prompts/search.md", import.meta.url),
   promptSnippet: "Search syntax-aware code shapes with AST patterns",
 });
 
-interface SgToolOptions {
+interface SearchToolOptions {
   onFileAnchored?: FileAnchoredCallback;
 }
 
 /**
  * Inputs for executing the structural search tool without registering it.
  */
-export interface ExecuteSgOptions {
+export interface ExecuteSearchOptions {
   params: unknown;
   signal: AbortSignal | undefined;
   cwd: string;
@@ -70,7 +70,7 @@ function readSeekLineFromSearch(line: ReadSeekHashline): ReadSeekLine {
   return buildReadSeekLineWithHash(line.line, line.hash, line.text);
 }
 
-function linesFromSearchResult(result: ReadSeekSearchFileOutput, ranges: SgRange[]): ReadSeekLine[] {
+function linesFromSearchResult(result: ReadSeekSearchFileOutput, ranges: SearchRange[]): ReadSeekLine[] {
   const lineMap = new Map<number, ReadSeekLine>();
   for (const match of result.matches) {
     for (const line of match.hashlines) {
@@ -100,9 +100,9 @@ function readSeekLanguageForPath(language: string | undefined, searchPath: strin
 /**
  * Executes structural search and returns readseek-anchored matches.
  */
-export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
+export async function executeSearch(opts: ExecuteSearchOptions): Promise<any> {
   const { params, signal, cwd, onFileAnchored } = opts;
-  const p = params as SgParams;
+  const p = params as SearchParams;
   const ignoredError = validateIgnoredRequiresOthers("search", p);
   if (ignoredError) return ignoredError;
   const searchPath = resolveToCwd(p.path ?? ".", cwd);
@@ -121,7 +121,7 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
       signal,
     });
     if (results.length === 0) {
-      const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [] });
+      const emptyOutput = buildSearchOutput({ pattern: p.pattern, files: [] });
       return {
         content: [{ type: "text", text: emptyOutput.text }],
         details: {
@@ -133,9 +133,9 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
     const readSeekFiles: Array<{
       displayPath: string;
       path: string;
-      ranges: SgRange[];
+      ranges: SearchRange[];
       lines: ReadSeekLine[];
-      symbols?: SgEnclosingSymbol[];
+      symbols?: SearchEnclosingSymbol[];
     }> = [];
 
     for (const result of results) {
@@ -154,7 +154,7 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
     }
 
     if (readSeekFiles.length === 0) {
-      const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [] });
+      const emptyOutput = buildSearchOutput({ pattern: p.pattern, files: [] });
       return {
         content: [{ type: "text", text: emptyOutput.text }],
         details: {
@@ -163,7 +163,7 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
       };
     }
 
-    const builtOutput = buildSgOutput({
+    const builtOutput = buildSearchOutput({
       pattern: p.pattern,
       files: readSeekFiles,
     });
@@ -182,13 +182,13 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
   }
 }
 
-export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
+export function registerSearchTool(pi: ExtensionAPI, options: SearchToolOptions = {}) {
   const tool = registerReadSeekTool(pi, {
     name: "readSeek_search",
     label: "Structural Search",
-    description: SG_PROMPT_METADATA.description,
-    promptSnippet: SG_PROMPT_METADATA.promptSnippet,
-    promptGuidelines: SG_PROMPT_METADATA.promptGuidelines,
+    description: SEARCH_PROMPT_METADATA.description,
+    promptSnippet: SEARCH_PROMPT_METADATA.promptSnippet,
+    promptGuidelines: SEARCH_PROMPT_METADATA.promptGuidelines,
     parameters: Type.Object({
       pattern: Type.String({ description: "ast-grep pattern, such as console.log($$$ARGS)" }),
       lang: langParam(),
@@ -196,7 +196,7 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       ...readSeekGitSearchParams(),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      return executeSg({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
+      return executeSearch({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
     renderCall(args: any, theme: any, ...rest: any[]) {
       return renderReadSeekSearchCall(args, theme, rest, {

package/src/session-anchors.ts

@@ -11,6 +11,20 @@ export class SessionAnchors {
     this.#paths.add(absolutePath);
   }
 
+  /**
+   * Forgets anchors after a file mutation that did not return current anchors.
+   */
+  forget(absolutePath: string): void {
+    this.#paths.delete(absolutePath);
+  }
+
+  /**
+   * Forgets every anchor, such as when resetting extension session state.
+   */
+  clear(): void {
+    this.#paths.clear();
+  }
+
   /**
    * Returns whether a file has fresh anchors in the current session.
    */

package/src/tool-prompt-metadata.ts

@@ -38,7 +38,7 @@ const COMPACT_GUIDELINES: Record<string, string[]> = {
   "write.md": [
     "Use anchored edits rather than readSeek_write for small changes or appends to existing files.",
   ],
-  "sg.md": [
+  "search.md": [
     "Use readSeek_search for syntax-aware code shapes; use readSeek_grep for plain text.",
   ],
   "refs.md": [

package/src/tool-types.ts

@@ -7,3 +7,6 @@ export type FileAnchoredCallback = (absolutePath: string) => void;
  * Predicate used by mutating tools to check whether a file has session-fresh anchors.
  */
 export type FreshAnchorsPredicate = (absolutePath: string) => boolean;
+
+/** Callback used after a tool persists a file mutation. */
+export type FileMutatedCallback = (absolutePath: string) => void;