pi-readseek 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "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.0",
+    "@jarkkojs/readseek": "^0.3.8",
     "diff": "^8.0.3",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.4",

package/src/edit.ts

@@ -19,7 +19,7 @@ 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, isRendererExpanded, linkToolPath, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 
 import { resolveEditDiffDisplay } from "./readseek-settings.js";
@@ -86,11 +86,6 @@ type HashlineParams = Static<typeof hashlineEditSchema>;
 const EDIT_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/edit.md", import.meta.url),
 	promptSnippet: "Edit files using hash-verified anchors from read/grep/search/write",
-	promptGuidelines: [
-		"Use edit for changes to existing files; read or search first and copy fresh LINE:HASH anchors.",
-		"Prefer edit anchored set_line, replace_lines, and insert_after over shell rewrites.",
-		"Use edit replace only when anchored edits are impractical.",
-	],
 });
 
 function buildEditError(
@@ -644,13 +639,9 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			return textComponent;
 		},
 			renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-			const context: { isPartial?: boolean; isError?: boolean; expanded?: boolean; lastComponent?: any; width?: number } =
-				rest[0] ?? options ?? {};
-			const isPartial = context.isPartial ?? (options as any)?.isPartial ?? false;
-			const isError = context.isError ?? false;
+			const { isPartial, isError, expanded: baseExpanded, width, context } = resolveRenderResultContext(options, rest);
 
 			if (isPartial) {
-				const width = (context as any).width ?? (options as any)?.width;
 				return new Text(clampLinesToWidth([summaryLine("pending edit")], width).join("\n"), 0, 0);
 			}
 
@@ -678,8 +669,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 				semanticClassification: semanticClassification as any,
 			});
 
-			const expanded = isRendererExpanded(options as any, context as any) || resolveEditDiffDisplay() === "expanded";
-			const width = (context as any).width ?? (options as any)?.width;
+			const expanded = baseExpanded || resolveEditDiffDisplay() === "expanded";
 			const diffData = (details as any).diffData;
 			const stats = diffData?.stats ?? { added: 0, removed: 0 };
 			let text = "";

package/src/grep.ts

@@ -7,7 +7,7 @@ import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { normalizeToLF, stripBom, hasBareCarriageReturn } from "./edit-diff.js";
 import { looksLikeBinary } from "./binary-detect.js";
 import { ensureHashInit, formatHashlineDisplay, escapeControlCharsForDisplay } from "./hashline.js";
-import { buildReadseekError, buildReadseekLine } from "./readseek-value.js";
+import { buildReadseekLine, buildToolErrorResult } from "./readseek-value.js";
 import { buildGrepOutput } from "./grep-output.js";
 
 import { getOrGenerateMap } from "./map-cache.js";
@@ -17,16 +17,11 @@ 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, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 
 const GREP_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/grep.md", import.meta.url),
 	promptSnippet: "Search file contents and return edit-ready hashline anchors",
-	promptGuidelines: [
-		"Use grep for text search across files instead of bash grep or rg.",
-		"Use grep summary mode when you only need matching files or counts.",
-		"Use search instead of grep when the query depends on code structure.",
-	],
 });
 
 const grepSchema = Type.Object({
@@ -314,76 +309,23 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 			const rawParams = params as GrepParams;
 			const context = coerceObviousBase10Int(rawParams.context, "context");
 			if (!context.ok) {
-				return {
-					content: [{ type: "text", text: context.message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "grep",
-							ok: false,
-							error: buildReadseekError("invalid-params-combo", context.message),
-						},
-					},
-				};
+				return buildToolErrorResult("grep", "invalid-params-combo", context.message);
 			}
 			const limit = coerceObviousBase10Int(rawParams.limit, "limit");
 			if (!limit.ok) {
-				return {
-					content: [{ type: "text", text: limit.message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "grep",
-							ok: false,
-							error: buildReadseekError("invalid-limit", limit.message),
-						},
-					},
-				};
+				return buildToolErrorResult("grep", "invalid-limit", limit.message);
 			}
 			const scopeContext = coerceObviousBase10Int(rawParams.scopeContext, "scopeContext");
 			if (!scopeContext.ok) {
-				return {
-					content: [{ type: "text", text: scopeContext.message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "grep",
-							ok: false,
-							error: buildReadseekError("invalid-params-combo", scopeContext.message),
-						},
-					},
-				};
+				return buildToolErrorResult("grep", "invalid-params-combo", scopeContext.message);
 			}
 			if (scopeContext.value !== undefined && rawParams.scope !== "symbol") {
 				const message = 'Invalid scopeContext: requires scope: "symbol". For normal surrounding-line context outside symbol scope, use the `context` parameter.';
-				return {
-					content: [{
-						type: "text",
-						text: message,
-					}],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "grep",
-							ok: false,
-							error: buildReadseekError("invalid-params-combo", message),
-						},
-					},
-				};
+				return buildToolErrorResult("grep", "invalid-params-combo", message);
 			}
 			if (scopeContext.value !== undefined && scopeContext.value < 0) {
 				const message = `Invalid scopeContext: expected a non-negative integer, received ${scopeContext.value}.`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "grep",
-							ok: false,
-							error: buildReadseekError("invalid-params-combo", message),
-						},
-					},
-				};
+				return buildToolErrorResult("grep", "invalid-params-combo", message);
 			}
 			const p: GrepParams = {
 				...rawParams,
@@ -716,13 +658,7 @@ if (p.scope === "symbol" && !summary) {
 			return new Text(clampLineToWidth(text, context.width), 0, 0);
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-			const context: { isPartial?: boolean; isError?: boolean; expanded?: boolean; cwd?: string; width?: number } =
-				rest[0] ?? options ?? {};
-			const isPartial = context.isPartial ?? (options as any)?.isPartial ?? false;
-			const isError = context.isError ?? false;
-			const expanded = isRendererExpanded(options as any, context as any);
-			const cwd = context.cwd ?? process.cwd();
-			const width = (context as any).width ?? (options as any)?.width;
+			const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
 			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], width).join("\n"), 0, 0);
 

package/src/image-detect.ts

@@ -0,0 +1,47 @@
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+function startsWithBytes(buffer: Buffer, bytes: number[]): boolean {
+	return buffer.length >= bytes.length && bytes.every((byte, index) => buffer[index] === byte);
+}
+
+function startsWithAscii(buffer: Buffer, offset: number, text: string): boolean {
+	if (buffer.length < offset + text.length) return false;
+	for (let index = 0; index < text.length; index++) {
+		if (buffer[offset + index] !== text.charCodeAt(index)) return false;
+	}
+	return true;
+}
+
+function readUint32BE(buffer: Buffer, offset: number): number {
+	return (
+		((buffer[offset] ?? 0) * 0x1000000) +
+		((buffer[offset + 1] ?? 0) << 16) +
+		((buffer[offset + 2] ?? 0) << 8) +
+		(buffer[offset + 3] ?? 0)
+	);
+}
+
+function isPng(buffer: Buffer): boolean {
+	return buffer.length >= 16 && readUint32BE(buffer, PNG_SIGNATURE.length) === 13 && startsWithAscii(buffer, 12, "IHDR");
+}
+
+function isAnimatedPng(buffer: Buffer): boolean {
+	let offset = PNG_SIGNATURE.length;
+	while (offset + 8 <= buffer.length) {
+		const chunkLength = readUint32BE(buffer, offset);
+		const chunkTypeOffset = offset + 4;
+		if (startsWithAscii(buffer, chunkTypeOffset, "acTL")) return true;
+		if (startsWithAscii(buffer, chunkTypeOffset, "IDAT")) return false;
+		const nextOffset = offset + 8 + chunkLength + 4;
+		if (nextOffset <= offset || nextOffset > buffer.length) return false;
+		offset = nextOffset;
+	}
+	return false;
+}
+
+export function isSupportedImageBuffer(buffer: Buffer): boolean {
+	if (startsWithBytes(buffer, [0xff, 0xd8, 0xff])) return buffer[3] !== 0xf7;
+	if (startsWithBytes(buffer, PNG_SIGNATURE)) return isPng(buffer) && !isAnimatedPng(buffer);
+	if (startsWithAscii(buffer, 0, "GIF")) return true;
+	return startsWithAscii(buffer, 0, "RIFF") && startsWithAscii(buffer, 8, "WEBP");
+}

package/src/read.ts

@@ -11,8 +11,9 @@ import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { readFile as fsReadFile } from "fs/promises";
 import { normalizeToLF, stripBom, hasBareCarriageReturn } from "./edit-diff.js";
 import { ensureHashInit, escapeControlCharsForDisplay } from "./hashline.js";
-import { buildReadseekError, buildReadseekWarning, renderReadseekLines, type ReadseekLine, type ReadseekWarning } from "./readseek-value.js";
+import { buildReadseekWarning, buildToolErrorResult, renderReadseekLines, type ReadseekLine, type ReadseekWarning } from "./readseek-value.js";
 import { looksLikeBinary } from "./binary-detect.js";
+import { isSupportedImageBuffer } from "./image-detect.js";
 import { resolveToCwd } from "./path-utils.js";
 import { throwIfAborted } from "./runtime.js";
 import { getOrGenerateMap } from "./map-cache.js";
@@ -26,17 +27,11 @@ 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, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 
 const READ_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/read.md", import.meta.url),
 	promptSnippet: "Read text files or images; text reads include hashline anchors and optional maps/symbol lookup",
-	promptGuidelines: [
-		"Use read instead of bash cat/head/tail/sed for file inspection.",
-		"Use read for images/screenshots; supported images return attachments like stock pi read.",
-		"Use read offset/limit, symbol, or map to keep large files focused.",
-		"Use read anchors as fresh inputs for edit.",
-	],
 });
 
 interface ReadParams {
@@ -58,55 +53,6 @@ function splitReadseekLines(text: string): string[] {
 	return withoutTrailingTerminator.split("\n");
 }
 
-const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-
-function startsWithBytes(buffer: Buffer, bytes: number[]): boolean {
-	return buffer.length >= bytes.length && bytes.every((byte, index) => buffer[index] === byte);
-}
-
-function startsWithAscii(buffer: Buffer, offset: number, text: string): boolean {
-	if (buffer.length < offset + text.length) return false;
-	for (let index = 0; index < text.length; index++) {
-		if (buffer[offset + index] !== text.charCodeAt(index)) return false;
-	}
-	return true;
-}
-
-function readUint32BE(buffer: Buffer, offset: number): number {
-	return (
-		((buffer[offset] ?? 0) * 0x1000000) +
-		((buffer[offset + 1] ?? 0) << 16) +
-		((buffer[offset + 2] ?? 0) << 8) +
-		(buffer[offset + 3] ?? 0)
-	);
-}
-
-function isPng(buffer: Buffer): boolean {
-	return buffer.length >= 16 && readUint32BE(buffer, PNG_SIGNATURE.length) === 13 && startsWithAscii(buffer, 12, "IHDR");
-}
-
-function isAnimatedPng(buffer: Buffer): boolean {
-	let offset = PNG_SIGNATURE.length;
-	while (offset + 8 <= buffer.length) {
-		const chunkLength = readUint32BE(buffer, offset);
-		const chunkTypeOffset = offset + 4;
-		if (startsWithAscii(buffer, chunkTypeOffset, "acTL")) return true;
-		if (startsWithAscii(buffer, chunkTypeOffset, "IDAT")) return false;
-		const nextOffset = offset + 8 + chunkLength + 4;
-		if (nextOffset <= offset || nextOffset > buffer.length) return false;
-		offset = nextOffset;
-	}
-	return false;
-}
-
-function isSupportedImageBuffer(buffer: Buffer): boolean {
-	if (startsWithBytes(buffer, [0xff, 0xd8, 0xff])) return buffer[3] !== 0xf7;
-	if (startsWithBytes(buffer, PNG_SIGNATURE)) return isPng(buffer) && !isAnimatedPng(buffer);
-	if (startsWithAscii(buffer, 0, "GIF")) return true;
-	return startsWithAscii(buffer, 0, "RIFF") && startsWithAscii(buffer, 8, "WEBP");
-}
-
-
 export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}) {
 	const toolConfig = {
 		callable: true,
@@ -151,63 +97,19 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			const rawParams = params as ReadParams;
 			const offset = coerceObviousBase10Int(rawParams.offset, "offset");
 			if (!offset.ok) {
-				return {
-					content: [{ type: "text", text: offset.message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-offset", offset.message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-offset", offset.message, { path: rawParams.path });
 			}
 			const limit = coerceObviousBase10Int(rawParams.limit, "limit");
 			if (!limit.ok) {
-				return {
-					content: [{ type: "text", text: limit.message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-limit", limit.message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-limit", limit.message, { path: rawParams.path });
 			}
 			if (limit.value !== undefined && limit.value < 1) {
 				const message = `Invalid limit: expected a positive integer, received ${limit.value}.`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-limit", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-limit", message, { path: rawParams.path });
 			}
 			if (offset.value !== undefined && offset.value < 1) {
 				const message = `Invalid offset: expected a positive integer, received ${offset.value}.`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-offset", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-offset", message, { path: rawParams.path });
 			}
 			const p = {
 				...rawParams,
@@ -218,18 +120,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				const trimmedSymbol = typeof rawParams.symbol === "string" ? rawParams.symbol.trim() : "";
 				if (trimmedSymbol.length === 0) {
 					const message = "Invalid symbol: expected a non-empty string.";
-					return {
-						content: [{ type: "text", text: message }],
-						isError: true,
-						details: {
-							readseekValue: {
-								tool: "read",
-								ok: false,
-								path: rawParams.path,
-								error: buildReadseekError("invalid-params-combo", message),
-							},
-						},
-					};
+					return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
 				}
 				p.symbol = trimmedSymbol;
 			}
@@ -246,63 +137,19 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			throwIfAborted(signal);
 			if (p.symbol && (p.offset !== undefined || p.limit !== undefined)) {
 				const message = "Cannot combine symbol with offset/limit. Use one or the other.";
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-params-combo", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
 			}
 			if (p.bundle && !p.symbol) {
 				const message = 'Cannot use bundle without symbol. Use read({ path, symbol, bundle: "local" }).';
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-params-combo", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
 			}
 			if (p.bundle && p.map) {
 				const message = "Cannot combine bundle with map. Use one or the other.";
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-params-combo", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
 			}
 			if (p.map && p.symbol) {
 				const message = "Cannot combine map with symbol. Use one or the other.";
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("invalid-params-combo", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
 			}
 			// Delegate images to the built-in read tool
 			throwIfAborted(signal);
@@ -320,69 +167,18 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				const code = err?.code;
 				if (code === "EISDIR") {
 					const message = `Path is a directory: ${rawPath}. Use ls to inspect directories.`;
-					return {
-						content: [{ type: "text", text: message }],
-						isError: true,
-						details: {
-							readseekValue: {
-								tool: "read",
-								ok: false,
-								path: rawParams.path,
-								error: buildReadseekError(
-									"path-is-directory",
-									message,
-									`Use ls(${JSON.stringify(rawPath)}) to inspect directories.`,
-								),
-							},
-						},
-					};
+					return buildToolErrorResult("read", "path-is-directory", message, { path: rawParams.path, hint: `Use ls(${JSON.stringify(rawPath)}) to inspect directories.` });
 				}
 				if (code === "EACCES" || code === "EPERM") {
 					const message = `Permission denied — cannot access: ${rawPath}`;
-					return {
-						content: [{ type: "text", text: message }],
-						isError: true,
-						details: {
-							readseekValue: {
-								tool: "read",
-								ok: false,
-								path: rawParams.path,
-								error: buildReadseekError("permission-denied", message),
-							},
-						},
-					};
+					return buildToolErrorResult("read", "permission-denied", message, { path: rawParams.path });
 				}
 				if (code === "ENOENT") {
 					const message = `File not found: ${rawPath}`;
-					return {
-						content: [{ type: "text", text: message }],
-						isError: true,
-						details: {
-							readseekValue: {
-								tool: "read",
-								ok: false,
-								path: rawParams.path,
-								error: buildReadseekError("file-not-found", message),
-							},
-						},
-					};
+					return buildToolErrorResult("read", "file-not-found", message, { path: rawParams.path });
 				}
 				const message = `File not readable: ${rawPath}${err?.message ? ` — ${err.message}` : ""}`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("fs-error", message, undefined, {
-								fsCode: code,
-								fsMessage: err?.message,
-							}),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "fs-error", message, { path: rawParams.path, details: { fsCode: code, fsMessage: err?.message } });
 			}
 
 			if (isSupportedImageBuffer(rawBuffer)) {
@@ -399,18 +195,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			let endIdx = p.limit !== undefined ? Math.min(startLine - 1 + p.limit, total) : total;
 			if (p.offset !== undefined && startLine > total) {
 				const message = `[offset ${p.offset} is past end of file (${total} lines)]`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("offset-past-end", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "offset-past-end", message, { path: rawParams.path });
 			}
 			let symbolMatch: SymbolMatch | undefined;
 			let symbolFileMap: Awaited<ReturnType<typeof getOrGenerateMap>> | null = null;
@@ -550,23 +335,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			} catch (err: any) {
 				const detail = err?.message ? ` — ${err.message}` : "";
 				const message = `readseek failed while reading ${rawPath}${detail}`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError(
-								"readseek-error",
-								message,
-								"Ensure @jarkkojs/readseek and its npm platform package are installed.",
-								{ message: err?.message },
-							),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "readseek-error", message, { path: rawParams.path, hint: "Ensure @jarkkojs/readseek and its npm platform package are installed.", details: { message: err?.message } });
 			}
 			const expectedLineCount = Math.max(0, endIdx - startLine + 1);
 			const invalidLine = readseekOutput.hashlines.find((line, index) => line.line !== startLine + index);
@@ -574,18 +343,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				const message = invalidLine
 					? `readseek returned non-sequential line ${invalidLine.line} for requested range ${startLine}-${endIdx}`
 					: `readseek returned ${readseekOutput.hashlines.length} lines for requested range ${startLine}-${endIdx} (${expectedLineCount} expected)`;
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: {
-						readseekValue: {
-							tool: "read",
-							ok: false,
-							path: rawParams.path,
-							error: buildReadseekError("readseek-output-mismatch", message),
-						},
-					},
-				};
+				return buildToolErrorResult("read", "readseek-output-mismatch", message, { path: rawParams.path });
 			}
 			const readseekLines: ReadseekLine[] = readseekOutput.hashlines.map((line) => ({
 				line: line.line,
@@ -708,11 +466,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			return new Text(clampLineToWidth(text, context.width), 0, 0);
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-			const context: { isPartial?: boolean; isError?: boolean; expanded?: boolean; cwd?: string; width?: number } = rest[0] ?? options ?? {};
-			const isPartial = context.isPartial ?? (options as any)?.isPartial ?? false;
-			const isError = context.isError ?? false;
-			const expanded = isRendererExpanded(options as any, context as any);
-			const width = context.width ?? (options as any)?.width;
+			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
 			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending read")], width).join("\n"), 0, 0);
 
 			const content = result.content?.[0];

package/src/readseek-value.ts

@@ -100,6 +100,42 @@ export function buildReadseekError(
   };
 }
 
+export interface ToolErrorResult {
+  content: [{ type: "text"; text: string }];
+  isError: true;
+  details: { readseekValue: Record<string, unknown> };
+}
+
+/**
+ * Build the standard failure envelope shared by every read-family tool: a text
+ * content block plus a `readseekValue` carrying `ok: false` and a
+ * {@link buildReadseekError} payload.
+ *
+ * `path` is included only when provided, and `extra` is merged into
+ * `readseekValue` so callers can attach tool-specific fields (e.g. write's
+ * `lines`/`warnings`).
+ */
+export function buildToolErrorResult(
+  tool: string,
+  code: string,
+  message: string,
+  opts: { path?: string; hint?: string; details?: unknown; extra?: Record<string, unknown> } = {},
+): ToolErrorResult {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+    details: {
+      readseekValue: {
+        tool,
+        ...(opts.extra ?? {}),
+        ok: false,
+        ...(opts.path !== undefined ? { path: opts.path } : {}),
+        error: buildReadseekError(code, message, opts.hint, opts.details),
+      },
+    },
+  };
+}
+
 export function buildReadseekEditResult(input: {
   ok?: boolean;
   path: string;

package/src/sg.ts

@@ -5,12 +5,12 @@ import path from "node:path";
 import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { escapeControlCharsForDisplay } from "./hashline.js";
-import { buildReadseekError, type ReadseekLine } from "./readseek-value.js";
+import { 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 { buildSgOutput } from "./sg-output.js";
 
-import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 
 type SgParams = { pattern: string; lang?: string; path?: string; cached?: boolean; others?: boolean; ignored?: boolean };
 
@@ -47,11 +47,6 @@ export function mergeRanges(ranges: SgRange[]): SgRange[] {
 const SG_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/sg.md", import.meta.url),
   promptSnippet: "Search code structurally with readseek and return edit-ready anchors",
-  promptGuidelines: [
-    "Use search when text search is too broad or brittle and the query depends on code shape.",
-    "Use search for calls, imports, declarations, JSX, and similar syntax patterns.",
-    "Use grep instead of search for plain text search.",
-  ],
 });
 
 export function isSgAvailable(): boolean {
@@ -128,17 +123,7 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       const p = params as SgParams;
       if (p.ignored && !p.others) {
         const message = "Error: search parameter 'ignored' requires 'others'";
-        return {
-          content: [{ type: "text", text: message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "search",
-              ok: false,
-              error: buildReadseekError("invalid-parameter", message),
-            },
-          },
-        };
+        return buildToolErrorResult("search", "invalid-parameter", message);
       }
       const searchPath = resolveToCwd(p.path ?? ".", ctx.cwd);
       let searchPathIsFile = false;
@@ -149,47 +134,14 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       } catch (err: any) {
         if (err?.code === "ENOENT") {
           const message = `Error: path '${p.path ?? "."}' does not exist`;
-          return {
-            content: [{ type: "text", text: message }],
-            isError: true,
-            details: {
-              readseekValue: {
-                tool: "search",
-                ok: false,
-                path: p.path ?? searchPath,
-                error: buildReadseekError("path-not-found", message),
-              },
-            },
-          };
+          return buildToolErrorResult("search", "path-not-found", message, { path: p.path ?? searchPath });
         }
         if (err?.code === "EACCES" || err?.code === "EPERM") {
           const message = `Error: permission denied for path '${p.path ?? "."}'`;
-          return {
-            content: [{ type: "text", text: message }],
-            isError: true,
-            details: {
-              readseekValue: {
-                tool: "search",
-                ok: false,
-                path: p.path ?? searchPath,
-                error: buildReadseekError("permission-denied", message),
-              },
-            },
-          };
+          return buildToolErrorResult("search", "permission-denied", message, { path: p.path ?? searchPath });
         }
         const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "search",
-              ok: false,
-              path: p.path ?? searchPath,
-              error: buildReadseekError("fs-error", message, undefined, { fsCode: err?.code, fsMessage: err?.message }),
-            },
-          },
-        };
+        return buildToolErrorResult("search", "fs-error", message, { path: p.path ?? searchPath, details: { fsCode: err?.code, fsMessage: err?.message } });
       }
 
       try {
@@ -260,19 +212,12 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       } 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 {
-          content: [{ type: "text", text: message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "search",
-              ok: false,
-              error: missingReadseek
-                ? buildReadseekError("readseek-not-installed", message, "Run npm install to install @jarkkojs/readseek.")
-                : buildReadseekError("readseek-execution-error", message),
-            },
-          },
-        };
+        return buildToolErrorResult(
+          "search",
+          missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
+          message,
+          missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
+        );
       }
     },
     renderCall(args: any, theme: any, ...rest: any[]) {
@@ -285,13 +230,7 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       return new Text(clampLineToWidth(text, context.width), 0, 0);
     },
     renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-      const context: { isPartial?: boolean; isError?: boolean; expanded?: boolean; cwd?: string; width?: number } =
-        rest[0] ?? options ?? {};
-      const isPartial = context.isPartial ?? (options as any)?.isPartial ?? false;
-      const isError = context.isError ?? false;
-      const expanded = isRendererExpanded(options as any, context as any);
-      const cwd = context.cwd ?? process.cwd();
-      const width = (context as any).width ?? (options as any)?.width;
+      const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
       if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], width).join("\n"), 0, 0);
 

package/src/tool-prompt-metadata.ts

@@ -59,7 +59,6 @@ function promptFileName(promptUrl: URL): string {
 export function defineToolPromptMetadata(options: {
   promptUrl: URL;
   promptSnippet: string;
-  promptGuidelines: string[];
 }): ToolPromptMetadata {
   const prompt = loadPrompt(options.promptUrl);
   const fileName = promptFileName(options.promptUrl);
@@ -67,6 +66,6 @@ export function defineToolPromptMetadata(options: {
   return {
     description: compactDescription ?? firstPromptParagraph(prompt),
     promptSnippet: options.promptSnippet,
-    promptGuidelines: COMPACT_GUIDELINES[fileName] ?? options.promptGuidelines,
+    promptGuidelines: COMPACT_GUIDELINES[fileName] ?? [],
   };
 }

package/src/tui-render-utils.ts

@@ -37,6 +37,33 @@ export function isRendererExpanded(options?: { expanded?: boolean }, context?: {
   return context?.expanded ?? options?.expanded ?? false;
 }
 
+export interface RenderResultContext {
+  isPartial: boolean;
+  isError: boolean;
+  expanded: boolean;
+  width: number | undefined;
+  cwd: string;
+  context: Record<string, any>;
+}
+
+/**
+ * Resolve the shared render context for a tool's `renderResult`, which may
+ * receive its context either as a trailing `rest[0]` argument or folded into
+ * `options`. Returns the common flags plus the raw context object for callers
+ * that need fields beyond the common set (e.g. `lastComponent`).
+ */
+export function resolveRenderResultContext(options: any, rest: any[]): RenderResultContext {
+  const context = rest[0] ?? options ?? {};
+  return {
+    isPartial: context.isPartial ?? options?.isPartial ?? false,
+    isError: context.isError ?? false,
+    expanded: isRendererExpanded(options, context),
+    width: context.width ?? options?.width,
+    cwd: context.cwd ?? process.cwd(),
+    context,
+  };
+}
+
 export function normalizeWidth(width: unknown, fallback = 80): number {
   return typeof width === "number" && Number.isFinite(width) && width > 0 ? Math.floor(width) : fallback;
 }

package/src/write.ts

@@ -66,11 +66,6 @@ const MAX_BYTES = 50 * 1024;
 const WRITE_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/write.md", import.meta.url),
   promptSnippet: "Create or overwrite a complete file and return edit anchors",
-  promptGuidelines: [
-    "Use write to create new files or intentionally replace whole files.",
-    "Use edit instead of write for small changes or appends to existing files.",
-    "Remember write overwrites existing files without confirmation.",
-  ],
 });
 
 type WriteDiffFields = {