pi-readseek 0.3.23 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.3.23",
+  "version": "0.4.0",
   "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.3.20",
+    "@jarkkojs/readseek": "^0.4.3",
     "diff": "^8.0.3",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.4",

package/src/edit.ts

@@ -20,9 +20,10 @@ import { resolveSyntaxValidateMode, type SyntaxValidateOptions } from "./syntax-
 import { replaceSymbol } from "./replace-symbol.js";
 import { buildEditPreviewKey, buildPendingEditPreviewData, resolvePendingDiffPreview, type PendingDiffPreviewResult } from "./pending-diff-preview.js";
 import { buildDiffData, type DiffBlockRange } from "./diff-data.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 import type { FreshAnchorsPredicate } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { resolveEditDiffDisplay } from "./readseek-settings.js";
 
@@ -35,14 +36,6 @@ function pendingPreviewLines(summary: string, preview: PendingDiffPreviewResult
 	return { lines: [summary, headerLine], diffData: expanded ? diffData : undefined, headerLabel: preview.data.headerLabel };
 }
 
-export function wrapWriteError(err: any, path: string): Error {
-	const code = err?.code;
-	if (code === "EACCES" || code === "EPERM") {
-		return new Error(`Permission denied: ${path}`);
-	}
-	return new Error(`Failed to write file: ${path}`);
-}
-
 
 const hashlineEditItemSchema = Type.Union([
 	Type.Object({ set_line: Type.Object({ anchor: Type.String(), new_text: Type.String() }) }, { additionalProperties: true }),
@@ -268,16 +261,16 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 		}
 	}
 	let preAnchorContent = originalNormalized;
-	// AC 26: reject anchored edits that target a line inside any replace_symbol
+	// reject anchored edits that target a line inside any replace_symbol
 	// pre-replace range. Resolve each target against the ORIGINAL content so the
 	// user-provided anchor line numbers (which reference the file as read) are
 	// compared against the pre-replace coordinates.
 	//
-	// F2: surface replace_symbol symbol-resolution errors (not-found, ambiguous)
-	// BEFORE the AC 26 overlap check and before any write (C1 preserved).
+	// surface replace_symbol symbol-resolution errors (not-found, ambiguous)
+	// before the overlap check and before any write.
 	// Error-precedence order: replace_symbol resolution > anchor-overlap > anchored-edit.
 	//
-	// AC 4: store successful probe results and reuse them in the apply loop so
+	// store successful probe results and reuse them in the apply loop so
 	// readseekMapContent is invoked at most once per replace_symbol edit.
 	const replaceSymbolRanges: { start: number; end: number }[] = [];
 	const rsProbeResults: { type: "ok"; content: string; replacement: string; warnings: string[]; range: { start: number; end: number } }[] = [];
@@ -289,7 +282,7 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 			newBody: rs.replace_symbol.new_body,
 		});
 		if (probe.type !== "ok") {
-			// F2: symbol-resolution errors surface before AC 26 overlap check.
+			// symbol-resolution errors surface before the overlap check.
 			return buildEditError(absolutePath, "invalid-edit-variant", probe.message);
 		}
 		rsProbeResults.push(probe);
@@ -348,7 +341,7 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 			}
 		}
 	}
-	// Apply pass: reuse all probe results (AC 4). The probe pass resolved every
+	// Apply pass: reuse all probe results. The probe pass resolved every
 	// replace_symbol against originalNormalized; apply those replacements in
 	// reverse source order so original line ranges stay valid and no second
 	// replaceSymbol/readseekMapContent call is needed.
@@ -444,7 +437,7 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 		if (regression) {
 			const lines = regression.errorLines.join(", ");
 			const message = `syntax-regression: lines ${lines}`;
-			// Task 7 (AC 12): block mode aborts with syntax-regression code; file is left untouched.
+			// block mode aborts with syntax-regression code; file is left untouched.
 			if (syntaxMode === "block") {
 				return buildEditError(absolutePath, "syntax-regression", message);
 			}
@@ -566,22 +559,17 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 
 
 export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "mutating" as const,
-		readOnly: false,
+	const tool = registerReadseekTool(pi, {
+		policy: "mutating",
 		pythonName: "edit",
-		defaultExposure: "not-safe-by-default" as const,
-	};
-	const tool = {
+		defaultExposure: "not-safe-by-default",
+	}, {
 		name: "edit",
 		label: "Edit",
 		description: EDIT_PROMPT_METADATA.description,
 		promptSnippet: EDIT_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: EDIT_PROMPT_METADATA.promptGuidelines,
 		parameters: hashlineEditSchema,
-		ptc: toolConfig,
 		renderShell: "default" as const,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			return executeEdit({
@@ -645,7 +633,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			const { isPartial, isError, expanded: baseExpanded, width, context } = resolveRenderResultContext(options, rest);
 
 			if (isPartial) {
-				return new Text(clampLinesToWidth([summaryLine("pending edit")], width).join("\n"), 0, 0);
+				return renderPendingResult("pending edit", width);
 			}
 
 			// Extract data from result
@@ -698,8 +686,6 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			}
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/grep.ts

@@ -17,8 +17,9 @@ import { throwIfAborted } from "./runtime.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatGrepCallText, formatGrepResultText } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const GREP_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/grep.md", import.meta.url),
@@ -508,21 +509,15 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 }
 
 export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
+	const tool = registerReadseekTool(pi, {
+		policy: "read-only",
 		pythonName: "grep",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
+		defaultExposure: "safe-by-default",
+	}, {
 		name: "grep",
 		label: "grep",
 		description: GREP_PROMPT_METADATA.description,
 		parameters: grepSchema,
-		ptc: toolConfig,
 		promptSnippet: GREP_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: options.searchGuideline
 			? [GREP_PROMPT_METADATA.promptGuidelines[0], options.searchGuideline]
@@ -558,16 +553,12 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], width).join("\n"), 0, 0);
+			if (isPartial) return renderPendingResult("pending search", width);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
 
-			if (isError || result.isError) {
-				const firstLine = textContent.split("\n")[0] || "Error";
-				const body = expanded && textContent ? textContent : firstLine;
-				return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-			}
+			if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
 
 			const readseekValue = (result.details as any)?.readseekValue as {
 				tool: "grep";
@@ -607,8 +598,6 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 			}
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/read.ts

@@ -26,8 +26,9 @@ import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { readseekRead } from "./readseek-client.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const READ_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/read.md", import.meta.url),
@@ -423,16 +424,11 @@ function splitReadseekLines(text: string): string[] {
 }
 
 export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
+	const tool = registerReadseekTool(pi, {
+		policy: "read-only",
 		pythonName: "read",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
+		defaultExposure: "safe-by-default",
+	}, {
 		name: "read",
 		label: "Read",
 		description: READ_PROMPT_METADATA.description,
@@ -460,7 +456,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				}),
 			),
 		}),
-		ptc: toolConfig,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			return executeRead({
 				toolCallId,
@@ -489,7 +484,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
-			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending read")], width).join("\n"), 0, 0);
+			if (isPartial) return renderPendingResult("pending read", width);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
@@ -516,8 +511,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			if (expanded && textContent) text += "\n" + wrapReadHashlinesForWidth(textContent, width);
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/readseek/formatter.ts

@@ -233,22 +233,6 @@ export function formatFileMap(map: FileMap, level?: DetailLevel): string {
   return lines.join("\n");
 }
 
-/**
- * Get the appropriate detail level for a map based on size.
- */
-export function getDetailLevelForSize(currentSize: number): DetailLevel {
-  if (currentSize <= THRESHOLDS.FULL_TARGET_BYTES) {
-    return DetailLevel.Full;
-  }
-  if (currentSize <= THRESHOLDS.COMPACT_TARGET_BYTES) {
-    return DetailLevel.Compact;
-  }
-  if (currentSize <= THRESHOLDS.MAX_MAP_BYTES) {
-    return DetailLevel.Minimal;
-  }
-  return DetailLevel.Outline;
-}
-
 /**
  * Reduce detail level of a file map.
  */

package/src/readseek/symbol-lookup.ts

@@ -136,7 +136,7 @@ export function findSymbol(map: FileMap, query: string): SymbolLookupResult {
     } else {
       pool = allSymbols.filter((c) => c.symbol.name === namePart);
     }
-    // AC 16 + AC 17: drop candidates without usable startLine. If that empties
+    // drop candidates without usable startLine. If that empties
     // the pool entirely, surface any same-leaf-name decls elsewhere in the file
     // so the user can see real candidate lines.
     pool = pool.filter((c) => Number.isFinite(c.symbol.startLine) && c.symbol.startLine > 0);

package/src/readseek-client.ts

@@ -203,6 +203,28 @@ export function isReadseekAvailable(): boolean {
 	}
 }
 
+export interface ReadseekFailure {
+	code: "readseek-not-installed" | "readseek-execution-error";
+	message: string;
+	hint?: string;
+}
+
+/**
+ * Classify an error thrown while invoking readseek into the shared failure
+ * taxonomy: a missing binary or package (`readseek-not-installed`, with an
+ * install hint) versus any other execution error.
+ */
+export function classifyReadseekFailure(err: unknown): ReadseekFailure {
+	const message = String((err as { message?: unknown } | null)?.message || err);
+	const missing =
+		(err as { code?: unknown } | null)?.code === "ENOENT" ||
+		/Cannot find package|Cannot find module|no such file/i.test(message);
+	if (missing) {
+		return { code: "readseek-not-installed", message, hint: "Run npm install to install @jarkkojs/readseek." };
+	}
+	return { code: "readseek-execution-error", message };
+}
+
 function directoryExists(dirPath: string): boolean {
 	try {
 		return statSync(dirPath).isDirectory();
@@ -353,15 +375,7 @@ function parseReadOutput(value: unknown): ReadseekReadOutput {
 		file_hash: requireString(output.file_hash, "file_hash"),
 		start_line: requireNumber(output.start_line, "start_line"),
 		end_line: requireNumber(output.end_line, "end_line"),
-		hashlines: hashlines.map((line) => {
-			if (!line || typeof line !== "object") throw new Error("invalid readseek hashline");
-			const item = line as Record<string, unknown>;
-			return {
-				line: requireNumber(item.line, "hashline.line"),
-				hash: requireString(item.hash, "hashline.hash"),
-				text: requireString(item.text, "hashline.text"),
-			};
-		}),
+		hashlines: hashlines.map((line) => parseHashline(line, "hashline")),
 	};
 }
 
@@ -391,17 +405,19 @@ function parseMapOutput(value: unknown): ReadseekMapOutput {
 	};
 }
 
+function parseHashline(value: unknown, field: string): ReadseekHashline {
+	if (!value || typeof value !== "object") throw new Error(`invalid readseek ${field}`);
+	const item = value as Record<string, unknown>;
+	return {
+		line: requireNumber(item.line, `${field}.line`),
+		hash: requireString(item.hash, `${field}.hash`),
+		text: requireString(item.text, `${field}.text`),
+	};
+}
+
 function parseSearchHashlines(value: unknown, field: string): ReadseekHashline[] {
 	if (!Array.isArray(value)) throw new Error(`invalid readseek ${field}`);
-	return value.map((line) => {
-		if (!line || typeof line !== "object") throw new Error(`invalid readseek ${field}`);
-		const item = line as Record<string, unknown>;
-		return {
-			line: requireNumber(item.line, `${field}.line`),
-			hash: requireString(item.hash, `${field}.hash`),
-			text: requireString(item.text, `${field}.text`),
-		};
-	});
+	return value.map((line) => parseHashline(line, field));
 }
 
 function parseSearchOutput(value: unknown): ReadseekSearchOutput {
@@ -422,7 +438,7 @@ function parseSearchOutput(value: unknown): ReadseekSearchOutput {
 					const item = match as Record<string, unknown>;
 					if (!Array.isArray(item.captures)) throw new Error("invalid readseek search captures");
 					return {
-						pattern_index: requireNumber(item.pattern_index, "search.match.pattern_index"),
+						pattern_index: item.pattern_index === undefined ? 0 : requireNumber(item.pattern_index, "search.match.pattern_index"),
 						start_line: requireNumber(item.start_line, "search.match.start_line"),
 						end_line: requireNumber(item.end_line, "search.match.end_line"),
 						start_hash: requireString(item.start_hash, "search.match.start_hash"),
@@ -449,7 +465,7 @@ function parseSearchOutput(value: unknown): ReadseekSearchOutput {
 
 export async function readseekRead(filePath: string, startLine?: number, endLine?: number): Promise<ReadseekReadOutput> {
 	const args = ["read", filePath];
-	if (startLine !== undefined) args.push("--offset", String(startLine));
+	if (startLine !== undefined) args.push("--start", String(startLine));
 	if (endLine !== undefined) args.push("--end", String(endLine));
 	return parseReadOutput(await runReadseek(args));
 }

package/src/refs.ts

@@ -6,9 +6,10 @@ import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadseekLineWithHash, buildToolErrorResult } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
-import { isReadseekAvailable, readseekRefs, type ReadseekReference } from "./readseek-client.js";
+import { classifyReadseekFailure, readseekRefs, type ReadseekReference } from "./readseek-client.js";
 import { buildRefsOutput, type RefsOutputFile, type RefsOutputLine } from "./refs-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -29,10 +30,6 @@ const REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptSnippet: "Find references to an identifier with readseek and return edit-ready anchors",
 });
 
-export function isRefsAvailable(): boolean {
-  return isReadseekAvailable();
-}
-
 interface RefsToolOptions {
   onFileAnchored?: FileAnchoredCallback;
 }
@@ -72,6 +69,14 @@ function groupReferences(references: ReadseekReference[], cwd: string): RefsOutp
   return [...files.values()];
 }
 
+function isReadseekCursorValidationFailure(message: string): boolean {
+  return (
+    /line and column must be greater than zero/i.test(message) ||
+    /line \d+ not found/i.test(message) ||
+    /column \d+ exceeds maximum column \d+ for line \d+/i.test(message)
+  );
+}
+
 /**
  * Executes identifier reference lookup and returns readseek-anchored matches.
  */
@@ -127,28 +132,20 @@ export async function executeRefs(opts: ExecuteRefsOptions): Promise<any> {
       details: { readseekValue: builtOutput.readseekValue },
     };
   } catch (err: any) {
-    const message = String(err?.message || err);
-    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-    return buildToolErrorResult(
-      "refs",
-      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-      message,
-      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-    );
+    const failure = classifyReadseekFailure(err);
+    if (p.scope && isReadseekCursorValidationFailure(failure.message)) {
+      return buildToolErrorResult("refs", "invalid-parameter", failure.message);
+    }
+    return buildToolErrorResult("refs", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
   }
 }
 
 export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "read-only" as const,
-    readOnly: true,
+  const tool = registerReadseekTool(pi, {
+    policy: "read-only",
     pythonName: "refs",
-    defaultExposure: "opt-in" as const,
-  };
-
-  const tool = {
+    defaultExposure: "opt-in",
+  }, {
     name: "refs",
     label: "References",
     description: REFS_PROMPT_METADATA.description,
@@ -165,7 +162,6 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
       others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
       ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
     }),
-    ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return executeRefs({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
@@ -186,8 +182,6 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
         unitPlural: "references",
       });
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-  pi.registerTool(tool);
+  });
   return tool;
 }

package/src/register-tool.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type ReadseekToolPolicy = "read-only" | "mutating";
+
+export type ReadseekToolExposure = "safe-by-default" | "opt-in" | "not-safe-by-default";
+
+/**
+ * Per-tool fields of the pi tool config (`ptc`) that genuinely differ between
+ * readseek tools. The remaining fields are constant or derived.
+ */
+export interface ReadseekToolConfig {
+  policy: ReadseekToolPolicy;
+  pythonName: string;
+  defaultExposure: ReadseekToolExposure;
+}
+
+export interface ReadseekToolPtc extends ReadseekToolConfig {
+  callable: true;
+  enabled: true;
+  readOnly: boolean;
+}
+
+type ToolSpec = Parameters<ExtensionAPI["registerTool"]>[0];
+
+/**
+ * Attach the standard `ptc` envelope to a tool definition and register it.
+ *
+ * `callable` and `enabled` are always true and `readOnly` is derived from
+ * `policy`, so callers supply only the fields that vary between tools.
+ */
+export function registerReadseekTool<T extends ToolSpec>(
+  pi: ExtensionAPI,
+  config: ReadseekToolConfig,
+  tool: T,
+): T & { ptc: ReadseekToolPtc } {
+  const ptc: ReadseekToolPtc = {
+    callable: true,
+    enabled: true,
+    policy: config.policy,
+    readOnly: config.policy === "read-only",
+    pythonName: config.pythonName,
+    defaultExposure: config.defaultExposure,
+  };
+  const registered = { ...tool, ptc };
+  pi.registerTool(registered);
+  return registered;
+}

package/src/sg.ts

@@ -6,9 +6,10 @@ import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadseekLineWithHash, buildToolErrorResult, type ReadseekLine } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
-import { isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
+import { classifyReadseekFailure, isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
 import { buildSgOutput } from "./sg-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -193,28 +194,17 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
       },
     };
   } catch (err: any) {
-    const message = String(err?.message || err);
-    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-    return buildToolErrorResult(
-      "search",
-      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-      message,
-      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-    );
+    const failure = classifyReadseekFailure(err);
+    return buildToolErrorResult("search", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
   }
 }
 
 export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "read-only" as const,
-    readOnly: true,
+  const tool = registerReadseekTool(pi, {
+    policy: "read-only",
     pythonName: "search",
-    defaultExposure: "opt-in" as const,
-  };
-
-  const tool = {
+    defaultExposure: "opt-in",
+  }, {
     name: "search",
     label: "Structural Search",
     description: SG_PROMPT_METADATA.description,
@@ -228,7 +218,6 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
       ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
     }),
-    ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return executeSg({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
@@ -249,8 +238,6 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
         unitPlural: "matches",
       });
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-  pi.registerTool(tool);
+  });
   return tool;
 }

package/src/tui-render-utils.ts

@@ -80,15 +80,6 @@ export function clampLinesToWidth(lines: string[], width: number | undefined): s
   return lines.map((line) => clampLineToWidth(line, width));
 }
 
-export function wrapLinesToWidth(lines: string[], width: number | undefined): string[] {
-  if (width === undefined || width === null) return lines;
-  const normalized = normalizeWidth(width);
-  return lines.flatMap((line) => {
-    if (visibleWidth(line) <= normalized) return [line];
-    return wrapTextWithAnsi(line, normalized).map((wrapped) => clampLineToWidth(wrapped, normalized));
-  });
-}
-
 export interface WrapWithHangingIndentOptions {
   /** Optional transform applied to each produced line (e.g. theme tinting). */
   tint?: (text: string) => string;
@@ -156,6 +147,27 @@ export function wrapReadHashlinesForWidth(text: string, width: number | undefine
   return output.join("\n");
 }
 
+/**
+ * Render the `isPartial` placeholder line shared by every tool's `renderResult`.
+ */
+export function renderPendingResult(pendingLabel: string, width: number | undefined): Text {
+  return new Text(clampLinesToWidth([summaryLine(pendingLabel)], width).join("\n"), 0, 0);
+}
+
+/**
+ * Render a tool result error: the first line of `textContent`, or its full body
+ * when expanded, prefixed and clamped to width. Tools pass their own `fallback`
+ * for the empty-content case.
+ */
+export function renderErrorResult(
+  textContent: string,
+  options: { expanded: boolean; width: number | undefined; fallback?: string },
+): Text {
+  const firstLine = textContent.split("\n")[0] || (options.fallback ?? "Error");
+  const body = options.expanded && textContent ? textContent : firstLine;
+  return new Text(clampLinesToWidth(summaryLine(body).split("\n"), options.width).join("\n"), 0, 0);
+}
+
 export interface AnchoredFilesLabels {
   pendingLabel: string;
   emptyLabel: string;
@@ -178,15 +190,11 @@ export function renderAnchoredFilesResult(
 ): Text {
   const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-  if (isPartial) return new Text(clampLinesToWidth([summaryLine(labels.pendingLabel)], width).join("\n"), 0, 0);
+  if (isPartial) return renderPendingResult(labels.pendingLabel, width);
 
   const content = result.content?.[0];
   const textContent = content?.type === "text" ? content.text : "";
-  if (isError || result.isError) {
-    const firstLine = textContent.split("\n")[0] || "Error";
-    const body = expanded && textContent ? textContent : firstLine;
-    return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-  }
+  if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
 
   const readseekValue = (result.details as any)?.readseekValue as
     | { files: Array<{ path: string; lines: any[] }> }

package/src/write.ts

@@ -14,9 +14,10 @@ import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildPendingWritePreviewData, buildWritePreviewKey, resolvePendingDiffPreview, type PendingDiffPreviewResult } from "./pending-diff-preview.js";
 import { generateCompactOrFullDiff, normalizeToLF, hasBareCarriageReturn } from "./edit-diff.js";
 import { buildDiffData, type DiffData } from "./diff-data.js";
-import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderErrorResult, renderToolLabel, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const WRITE_PENDING_PREVIEW_STATE_KEY = "hashline-write-pending-preview";
 
@@ -169,6 +170,30 @@ function mapFsWriteError(err: any, path: string): MappedFsError {
   };
 }
 
+function buildWriteFsErrorResult(err: any, absolutePath: string) {
+  const mapped = mapFsWriteError(err, absolutePath);
+  return {
+    content: [{ type: "text" as const, text: mapped.message }],
+    isError: true,
+    details: {
+      readseekValue: {
+        tool: "write" as const,
+        path: absolutePath,
+        lines: [] as ReadseekLine[],
+        warnings: [] as ReadseekWarning[],
+        ok: false,
+        error: buildReadseekError(
+          mapped.code,
+          mapped.message,
+          undefined,
+          mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
+        ),
+      },
+      warnings: [] as string[],
+    },
+  };
+}
+
 export async function executeWrite(opts: {
   path: string;
   content: string;
@@ -301,21 +326,16 @@ export async function executeWrite(opts: {
 }
 
 export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "mutating" as const,
-    readOnly: false,
+  const tool = registerReadseekTool(pi, {
+    policy: "mutating",
     pythonName: "write",
-    defaultExposure: "not-safe-by-default" as const,
-  };
-  const tool = {
+    defaultExposure: "not-safe-by-default",
+  }, {
     name: "write",
     label: "write",
     description: WRITE_PROMPT_METADATA.description,
     promptSnippet: WRITE_PROMPT_METADATA.promptSnippet,
     promptGuidelines: WRITE_PROMPT_METADATA.promptGuidelines,
-    ptc: toolConfig,
     parameters: Type.Object({
       path: Type.String({ description: "File path" }),
       content: Type.String({ description: "File content" }),
@@ -325,112 +345,58 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const cwd = ctx?.cwd ?? process.cwd();
       const absolutePath = resolveToCwd(params.path, cwd);
       try {
-      return await withFileMutationQueue(absolutePath, async () => {
-      let result: WriteResult;
-      try {
-        result = await executeWrite({
-          path: absolutePath,
-          content: params.content,
-          map: params.map,
-          cwd,
-        });
-      } catch (err: any) {
-        const mapped = mapFsWriteError(err, absolutePath);
-        return {
-          content: [{ type: "text" as const, text: mapped.message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "write" as const,
+        return await withFileMutationQueue(absolutePath, async () => {
+          let result: WriteResult;
+          try {
+            result = await executeWrite({
               path: absolutePath,
-              lines: [] as ReadseekLine[],
-              warnings: [] as ReadseekWarning[],
-              ok: false,
-              error: buildReadseekError(
-                mapped.code,
-                mapped.message,
-                undefined,
-                mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-              ),
-            },
-            warnings: [] as string[],
-          },
-        };
-      }
+              content: params.content,
+              map: params.map,
+              cwd,
+            });
+          } catch (err: any) {
+            return buildWriteFsErrorResult(err, absolutePath);
+          }
 
-      if (result.readseekValue.lines.length > 0) {
-        options.onFileAnchored?.(absolutePath);
-      }
+          if (result.readseekValue.lines.length > 0) {
+            options.onFileAnchored?.(absolutePath);
+          }
 
-      // Lift binary-content signal into a fatal readseekValue.error envelope so
-      // downstream consumers get the same taxonomy shape as every other tool.
-      // The existing ReadseekWarning entry is preserved on readseekValue.warnings for
-      // backward compatibility (see AC 12 — warnings namespace alignment).
-      const binaryWarning = result.readseekValue.warnings.find((w) => w.code === "binary-content");
-      if (binaryWarning) {
-        return {
-          content: [{ type: "text" as const, text: result.text }],
-          isError: true,
-          details: {
-            readseekValue: {
-              ...result.readseekValue,
-              ok: false,
-              error: buildReadseekError("binary-content", binaryWarning.message),
-            },
-            warnings: result.warnings,
-          },
-        };
-      }
+          // Lift binary-content signal into a fatal readseekValue.error envelope so
+          // downstream consumers get the same taxonomy shape as every other tool.
+          // The existing ReadseekWarning entry is preserved on readseekValue.warnings for
+          // backward compatibility.
+          for (const code of ["binary-content", "bare-cr"] as const) {
+            const warning = result.readseekValue.warnings.find((w) => w.code === code);
+            if (warning) {
+              return {
+                content: [{ type: "text" as const, text: result.text }],
+                isError: true,
+                details: {
+                  readseekValue: {
+                    ...result.readseekValue,
+                    ok: false,
+                    error: buildReadseekError(code, warning.message),
+                  },
+                  warnings: result.warnings,
+                },
+              };
+            }
+          }
 
-      const bareCrWarning = result.readseekValue.warnings.find((w) => w.code === "bare-cr");
-      if (bareCrWarning) {
-        return {
-          content: [{ type: "text" as const, text: result.text }],
-          isError: true,
-          details: {
-            readseekValue: {
-              ...result.readseekValue,
-              ok: false,
-              error: buildReadseekError("bare-cr", bareCrWarning.message),
+          return {
+            content: [{ type: "text" as const, text: result.text }],
+            details: {
+              ...(result.diff !== undefined ? { diff: result.diff } : {}),
+              ...(result.diffData !== undefined ? { diffData: result.diffData } : {}),
+              ...(result.writeState ? { writeState: result.writeState } : {}),
+              readseekValue: result.readseekValue,
+              warnings: result.warnings,
             },
-            warnings: result.warnings,
-          },
-        };
-      }
-
-      return {
-        content: [{ type: "text" as const, text: result.text }],
-        details: {
-          ...(result.diff !== undefined ? { diff: result.diff } : {}),
-          ...(result.diffData !== undefined ? { diffData: result.diffData } : {}),
-          ...(result.writeState ? { writeState: result.writeState } : {}),
-          readseekValue: result.readseekValue,
-          warnings: result.warnings,
-        },
-      };
-      });
+          };
+        });
       } catch (err: any) {
-        const mapped = mapFsWriteError(err, absolutePath);
-        return {
-          content: [{ type: "text" as const, text: mapped.message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "write" as const,
-              path: absolutePath,
-              lines: [] as ReadseekLine[],
-              warnings: [] as ReadseekWarning[],
-              ok: false,
-              error: buildReadseekError(
-                mapped.code,
-                mapped.message,
-                undefined,
-                mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-              ),
-            },
-            warnings: [] as string[],
-          },
-        };
+        return buildWriteFsErrorResult(err, absolutePath);
       }
     },
     renderCall(args: any, theme: any, context: any = {}) {
@@ -478,9 +444,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const details = result.details ?? {};
       const output = result.content?.[0]?.type === "text" ? result.content[0].text : "";
       if (result.isError || details.readseekValue?.ok === false) {
-        const firstLine = output.split("\n")[0] || "write failed";
-        const body = expanded && output ? output : firstLine;
-        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
+        return renderErrorResult(output, { expanded, width, fallback: "write failed" });
       }
       const diffData = details.diffData;
       const state = details.writeState === "overwritten" ? "overwritten" : "created";
@@ -510,7 +474,6 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       }
       return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-  pi.registerTool(tool);
+  });
   return tool;
 }