pi-readseek 0.6.3 → 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.3",
+  "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.3",
+    "@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/def.md

@@ -1,5 +1,4 @@
-Find structural definitions by qualified or unqualified name across a file or
-directory.
+Find symbol declarations by qualified or unqualified name. Use instead of text search when locating where a function, class, type, or other symbol is defined.
 
 ## Parameters
 
@@ -8,7 +7,4 @@ directory.
 - `lang` — language override.
 - `cached`, `others`, `ignored` — Git file selection; `ignored` requires `others`.
 
-## When to use
-
-- After `readSeek_hover`, use its qualified symbol name.
-- When asked where a function, class, or type is defined.
+After `readSeek_hover`, use its qualified symbol name.

package/prompts/edit.md

@@ -1,6 +1,6 @@
-Edit existing text files with fresh `LINE:HASH` anchors from `readSeek_read`,
-`readSeek_grep`, `readSeek_search`, or `readSeek_write`. The file must have
-been anchored in this session; on `file-not-read`, read or search it first.
+Edit existing text files safely with fresh `LINE:HASH` anchors; on `file-not-read`, read or search the file first.
+
+Anchors come from `readSeek_read`, `readSeek_grep`, `readSeek_search`, or `readSeek_write`.
 
 ## Variants
 

package/prompts/grep.md

@@ -1,4 +1,4 @@
-Search file contents. Non-summary results include edit-ready `LINE:HASH` anchors, so you usually do not need a follow-up `readSeek_read` before `readSeek_edit`.
+Search plain text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, or documentation.
 
 ## Modes
 
@@ -19,10 +19,4 @@ Search file contents. Non-summary results include edit-ready `LINE:HASH` anchors
 - `scope` — only `"symbol"` is supported.
 - `scopeContext` — non-negative context within symbol scope; requires `scope: "symbol"`.
 
-## Use well
-
-Use `readSeek_grep` for text: identifiers, strings, config keys, error messages, comments, or docs. Use `literal: true` unless you want regex behavior.
-
-For code shape — calls, imports, declarations, JSX, object literals, control flow — prefer `readSeek_search`, which parses AST patterns.
-
 If output says results were truncated at `limit` or by display budget, narrow before editing. Good narrowing order: `summary` → `path`/`glob` → stricter pattern → `scope: "symbol"` or `context`.

package/prompts/hover.md

@@ -1,11 +1,6 @@
-Identify the identifier and enclosing symbol at a cursor. 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
 
 - `path`, `line` — required file path and one-based cursor line.
 - `column` — optional one-based cursor byte column.
-
-## When to use
-
-- Before rename or go-to-definition, or to identify a line's enclosing symbol.

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read files through readseek. Text results use `LINE:HASH|content` anchors for `readSeek_edit`. Images and PDFs require an explicit available `image` mode; omitting it skips them. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+Read anchored text by range, map, or symbol, and process images or PDFs with an explicit mode.
 
 ## Choose the right read
 
@@ -14,7 +14,9 @@ Read files through readseek. Text results use `LINE:HASH|content` anchors for `r
 - `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; 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/refs.md

@@ -1,5 +1,4 @@
-Find identifier references before renaming, deleting, or changing a symbol when
-text search is too broad. Results include edit-ready anchors and enclosing symbols.
+Find identifier usages with enclosing symbols and edit-ready anchors. Use before renaming, deleting, or changing a symbol; add a cursor scope to exclude same-named bindings.
 
 ## Parameters
 
@@ -23,5 +22,3 @@ shadows.
 
 In Git repositories, directory search includes tracked/indexed and untracked
 non-ignored files. `ignored` requires `others`.
-
-Use `readSeek_grep` for plain text, `readSeek_search` for code shape, and `readSeek_refs` for identifier usage.

package/prompts/rename.md

@@ -1,5 +1,4 @@
-Rename an identifier with binding accuracy. The cursor binding is resolved and
-only occurrences of that declaration are changed.
+Rename the symbol at a cursor without changing same-named bindings. Use for symbol renames; use search and edit for broader refactors.
 
 ## Parameters
 
@@ -7,12 +6,3 @@ only occurrences of that declaration are changed.
 - `column` — optional one-based cursor byte column.
 - `workspace` — expand across the project; local shadows in other files are excluded.
 - `apply` — default `true`; set `false` to return only the verified plan.
-
-## When to use
-
-- Use when the user requests a symbol rename and the cursor is known.
-
-## When not to use
-
-- Use `readSeek_grep`/`readSeek_search` for broad replacement and
-  `readSeek_edit` for other refactors.

package/prompts/{sg.md → search.md}

@@ -1,6 +1,4 @@
-Search code with AST patterns when text search is too broad. Use it for calls,
-imports, declarations, JSX, object fields, and control flow. Results include
-edit-ready anchors.
+Search syntax-aware code shapes with AST patterns and return edit-ready anchors. Use for calls, imports, declarations, JSX, object fields, or control flow; use `readSeek_grep` for plain text.
 
 ## Parameters
 
@@ -35,5 +33,3 @@ punctuation must be valid for the selected language.
 In Git repositories, directory search includes tracked/indexed and untracked
 non-ignored files. Use `cached`, `others`, and `ignored` to choose; `ignored`
 requires `others`.
-
-Use `readSeek_grep` for plain text and `readSeek_search` for structure.

package/prompts/write.md

@@ -1,12 +1,9 @@
-Create or replace a whole file and return `LINE:HASH` anchors for follow-up edits.
+Create or replace a complete file and return `LINE:HASH` anchors. Use for new or fully generated files; use anchored edits for small changes.
 
 ## Use / avoid
 
-Use it for new, generated, or intentionally replaced files. For small changes or
-appends, read/search first and use `readSeek_edit`.
-
-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
 
@@ -16,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";
@@ -15,7 +15,7 @@ import type { FileAnchoredCallback } from "./tool-types.js";
 
 const DEF_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/def.md", import.meta.url),
-	promptSnippet: "Find structural definitions for a symbol",
+	promptSnippet: "Find where a symbol is defined",
 });
 
 type DefParams = {
@@ -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,26 +40,28 @@ 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 },
 	),
 ]);
 
 const hashlineEditSchema = Type.Object(
 	{
 		path: filePathParam(),
-		edits: Type.Optional(Type.Array(hashlineEditItemSchema, { description: "Edit operations" })),
+		edits: Type.Optional(Type.Array(hashlineEditItemSchema, {
+			description: "Edits: set_line, replace_lines, insert_after, replace_symbol, or replace",
+		})),
 		postEditVerify: Type.Optional(Type.Boolean({
 			description: "Verify persisted content after write",
 		})),
@@ -105,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>>;
@@ -115,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>;
@@ -467,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;
@@ -565,7 +570,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 	const name = options.name ?? "readSeek_edit";
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/edit.md", import.meta.url),
-		promptSnippet: "Edit with fresh hash-verified anchors",
+		promptSnippet: "Safely edit with fresh LINE:HASH anchors",
 		registeredName: name,
 		toolAliases: options.toolAliases,
 	});
@@ -583,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/grep.ts

@@ -26,20 +26,20 @@ import { searchPathParam } from "./readseek-params.js";
 
 
 const grepSchema = Type.Object({
-	pattern: Type.String({ description: "Pattern to search" }),
+	pattern: Type.String({ description: "Regex pattern; use literal for exact text" }),
 	path: searchPathParam(),
-	glob: Type.Optional(Type.String({ description: "Glob filter" })),
+	glob: Type.Optional(Type.String({ description: "File-name glob, such as *.ts" })),
 	ignoreCase: Type.Optional(Type.Boolean({ description: "Ignore case" })),
 	literal: Type.Optional(Type.Boolean({ description: "Treat pattern literally" })),
-	context: optionalIntOrString("Context lines"),
-	limit: optionalIntOrString("Max matches"),
+	context: optionalIntOrString("Surrounding lines for each match"),
+	limit: optionalIntOrString("Maximum matches to return"),
 	summary: Type.Optional(Type.Boolean({ description: "Return per-file counts" })),
 	scope: Type.Optional(
 		Type.Literal("symbol", {
-			description: "Scope matches to symbols",
+			description: "Group matches by enclosing symbol",
 		}),
 	),
-	scopeContext: optionalIntOrString("Symbol context lines"),
+	scopeContext: optionalIntOrString("Context lines within each symbol"),
 });
 
 interface GrepParams {
@@ -513,7 +513,7 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 	const name = options.name ?? "readSeek_grep";
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/grep.md", import.meta.url),
-		promptSnippet: "Search file text with edit-ready anchors",
+		promptSnippet: "Search plain text or regex with edit-ready anchors",
 		registeredName: name,
 	});
 	const tool = registerReadSeekTool(pi, {

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

@@ -15,13 +15,13 @@ import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, r
 
 const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/hover.md", import.meta.url),
-	promptSnippet: "Identify a cursor token and enclosing symbol",
+	promptSnippet: "Identify the token and enclosing symbol at a cursor",
 });
 
 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

@@ -524,29 +524,31 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 	const imageModes = imageMode === "auto" ? ["none", "ocr", "caption", "objects"] as const : ["ocr", "caption", "objects"] as const;
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/read.md", import.meta.url),
-		promptSnippet: "Read files or images with anchors, maps, symbols, and OCR",
+		promptSnippet: "Read anchored text, symbols, maps, images, or PDFs",
 		registeredName: name,
 	});
 	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({
 			path: filePathParam(),
 			offset: optionalIntOrString("Start line (1-indexed)"),
-			limit: optionalIntOrString("Max lines"),
+			limit: optionalIntOrString("Maximum lines to return"),
 			symbol: Type.Optional(Type.String({ description: "Symbol name to read" })),
 			map: mapParam(),
 			bundle: Type.Optional(
 				Type.Literal("local", {
-					description: "Include same-file local support",
+					description: "Include related symbols from the same file; requires symbol",
 				}),
 			),
 			...(imageMode === "off"

package/src/readseek-params.ts

@@ -4,12 +4,12 @@ import { buildToolErrorResult, type ToolErrorResult } from "./readseek-value.js"
 
 /** Optional search path shared by the readseek search tools. */
 export function searchPathParam() {
-  return Type.Optional(Type.String({ description: "Search path" }));
+  return Type.Optional(Type.String({ description: "File or directory to search" }));
 }
 
 /** Optional language hint shared by the readseek search tools. */
 export function langParam() {
-  return Type.Optional(Type.String({ description: "Language hint" }));
+  return Type.Optional(Type.String({ description: "Language override when auto-detection is ambiguous" }));
 }
 
 /**

package/src/refs.ts

@@ -27,7 +27,7 @@ type RefsParams = {
 
 const REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/refs.md", import.meta.url),
-  promptSnippet: "Find identifier references with enclosing symbols",
+  promptSnippet: "Find usages of an identifier or cursor binding",
 });
 
 interface RefsToolOptions {
@@ -133,9 +133,9 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
       name: Type.String({ description: "Identifier to find references for" }),
       path: searchPathParam(),
       lang: langParam(),
-      scope: Type.Optional(Type.Boolean({ description: "Restrict to the binding under line/column (single file)" })),
-      line: Type.Optional(Type.Number({ description: "One-based cursor line, used with scope" })),
-      column: Type.Optional(Type.Number({ description: "One-based cursor byte column, used with scope" })),
+      scope: Type.Optional(Type.Boolean({ description: "Restrict results to the binding at the cursor" })),
+      line: Type.Optional(Type.Number({ description: "Cursor line (1-indexed), required with scope" })),
+      column: Type.Optional(Type.Number({ description: "Cursor byte column (1-indexed) for disambiguation" })),
       ...readSeekGitSearchParams(),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/src/register-tool.ts

@@ -12,7 +12,7 @@ export function optionalIntOrString(description: string) {
 
 /** Required file-path parameter shared by the read, edit, and write tools. */
 export function filePathParam() {
-  return Type.String({ description: "File path" });
+  return Type.String({ description: "Absolute or relative file path" });
 }
 
 /** Optional structural-map toggle shared by the read and write tools. */

package/src/rename.ts

@@ -8,21 +8,22 @@ 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";
 
 const RENAME_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/rename.md", import.meta.url),
-	promptSnippet: "Rename a binding accurately from its cursor",
+	promptSnippet: "Rename the symbol at a cursor without touching shadows",
 });
 
 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" })),
+	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" })),
 });
 
 interface RenameParams {
@@ -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),
-  promptSnippet: "Search code by AST pattern with edit-ready anchors",
+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,21 +182,21 @@ 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 pattern" }),
+      pattern: Type.String({ description: "ast-grep pattern, such as console.log($$$ARGS)" }),
       lang: langParam(),
       path: searchPathParam(),
       ...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

@@ -2,16 +2,6 @@ import { readFileSync } from "node:fs";
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
-const COMPACT_DESCRIPTIONS: Record<string, string> = {
-  "read.md": "Read text files, images, or PDFs by path; text has LINE:HASH anchors and visual files require an explicit image mode.",
-  "edit.md": "Edit existing text files using fresh LINE:HASH anchors from readSeek_read, readSeek_grep, readSeek_search, or readSeek_write.",
-  "grep.md": "Search file contents; non-summary results include LINE:HASH anchors for edits.",
-
-  "write.md": "Create or overwrite a complete file and return anchors.",
-  "sg.md": "Search code by AST pattern and return anchored matches.",
-  "refs.md": "Find references to an identifier and return anchored usages with enclosing symbols.",
-};
-
 const REPLACEABLE_TOOL_GUIDELINES: Record<string, { readSeekName: string; builtInName: string; benefit: string }> = {
   "read.md": {
     readSeekName: "readSeek_read",
@@ -37,8 +27,7 @@ const REPLACEABLE_TOOL_GUIDELINES: Record<string, { readSeekName: string; builtI
 
 const COMPACT_GUIDELINES: Record<string, string[]> = {
   "read.md": [
-    "Use readSeek_read map or symbol mode before pulling large code files into context.",
-    "For images and PDFs, explicitly choose one of the image modes exposed by readSeek_read.",
+    "Use readSeek_read map or symbol mode to inspect large code files without reading them in full.",
   ],
   "edit.md": [
     "With readSeek_edit, prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical.",
@@ -49,9 +38,8 @@ 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": [
-    "Use readSeek_search for AST-shaped code patterns.",
-    "Use readSeek_grep instead of readSeek_search for plain text.",
+  "search.md": [
+    "Use readSeek_search for syntax-aware code shapes; use readSeek_grep for plain text.",
   ],
   "refs.md": [
     "Use readSeek_refs to find every usage of an identifier before renaming or deleting it.",
@@ -96,7 +84,6 @@ export function defineToolPromptMetadata(options: {
 }): ToolPromptMetadata {
   const prompt = loadPrompt(options.promptUrl);
   const fileName = promptFileName(options.promptUrl);
-  const compactDescription = COMPACT_DESCRIPTIONS[fileName];
   const replaceable = REPLACEABLE_TOOL_GUIDELINES[fileName];
   const registeredName = options.registeredName ?? replaceable?.readSeekName;
   const preferenceGuideline = replaceable && registeredName
@@ -105,7 +92,7 @@ export function defineToolPromptMetadata(options: {
       : `Use ${registeredName}; ${replaceable.benefit}`
     : undefined;
   return {
-    description: rewriteToolAliases(compactDescription ?? firstPromptParagraph(prompt), options.toolAliases),
+    description: rewriteToolAliases(firstPromptParagraph(prompt), options.toolAliases),
     promptSnippet: rewriteToolAliases(options.promptSnippet, options.toolAliases),
     promptGuidelines: [
       ...(preferenceGuideline ? [preferenceGuideline] : []),

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;

package/src/write.ts

@@ -241,7 +241,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
   const name = options.name ?? "readSeek_write";
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/write.md", import.meta.url),
-    promptSnippet: "Create or overwrite a file with edit anchors",
+    promptSnippet: "Create or replace a complete file with edit anchors",
     registeredName: name,
   });
   const tool = registerReadSeekTool(pi, {
@@ -252,7 +252,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
     promptGuidelines: promptMetadata.promptGuidelines,
     parameters: Type.Object({
       path: filePathParam(),
-      content: Type.String({ description: "File content" }),
+      content: Type.String({ description: "Complete file content" }),
       map: mapParam(),
     }),
     async execute(_toolCallId: string, params: { path: string; content: string; map?: boolean }, _signal: AbortSignal | undefined, _onUpdate: any, ctx: any): Promise<any> {