pi-readseek 0.4.16 → 0.4.18

package/index.ts

@@ -2,10 +2,11 @@ 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, isSgAvailable } from "./src/sg.js";
+import { registerSgTool } from "./src/sg.js";
 import { registerRefsTool } from "./src/refs.js";
 import { registerWriteTool } from "./src/write.js";
 import { SessionAnchors } from "./src/session-anchors.js";
+import { isReadSeekAvailable } from "./src/readseek-client.js";
 
 export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	const sessionAnchors = new SessionAnchors();
@@ -14,10 +15,10 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 
 	registerReadTool(pi, { onSuccessfulRead: markAnchored });
 	registerEditTool(pi, { wasReadInSession: hasFreshAnchors });
-	const sgAvailable = isSgAvailable();
-	const searchGuideline = sgAvailable
+	const searchAvailable = isReadSeekAvailable();
+	const searchGuideline = searchAvailable
 		? "Use grep summary for counts; use search for structural code patterns."
-		: "Use grep summary for counts; install @jarkkojs/readseek to enable search.";
+		: "Use grep summary for counts; search is unavailable (readseek native backend not loaded).";
 
 	registerGrepTool(pi, { searchGuideline, onFileAnchored: markAnchored });
 	registerSgTool(pi, { onFileAnchored: markAnchored });

package/package.json

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

package/src/edit.ts

@@ -12,6 +12,7 @@ import { HashlineMismatchError, applyHashlineEdits, computeLineHash, ensureHashI
 import { resolveToCwd } from "./path-utils.js";
 import { looksLikeBinary } from "./binary-detect.js";
 import { throwIfAborted } from "./runtime.js";
+import { classifyFsError } from "./fs-error.js";
 import { buildEditOutput } from "./edit-output.js";
 import { classifyEdit, isDifftAvailable, runDifftastic } from "./edit-classify.js";
 import type { SemanticSummary } from "./readseek-value.js";
@@ -26,7 +27,7 @@ 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 { registerReadSeekTool } from "./register-tool.js";
+import { filePathParam, registerReadSeekTool } from "./register-tool.js";
 
 import { resolveEditDiffDisplay } from "./readseek-settings.js";
 
@@ -46,7 +47,7 @@ const hashlineEditItemSchema = Type.Union([
 		{ replace_lines: Type.Object({ start_anchor: Type.String(), end_anchor: Type.String(), new_text: Type.String() }) },
 		{ additionalProperties: true },
 	),
-	Type.Object({ insert_after: Type.Object({ anchor: Type.String(), new_text: Type.String(), text: Type.Optional(Type.String()) }) }, { additionalProperties: true }),
+	Type.Object({ insert_after: Type.Object({ anchor: Type.String(), new_text: Type.String() }) }, { additionalProperties: true }),
 	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 },
@@ -55,18 +56,11 @@ const hashlineEditItemSchema = Type.Union([
 		{ replace_symbol: Type.Object({ symbol: Type.String(), new_body: Type.String() }) },
 		{ additionalProperties: true },
 	),
-	Type.Object(
-		{ old_text: Type.String(), new_text: Type.String() },
-		{
-			additionalProperties: true,
-			description: "Do not use — Wrap as { replace: {old_text, new_text} }.",
-		},
-	),
 ]);
 
 const hashlineEditSchema = Type.Object(
 	{
-		path: Type.String({ description: "File path" }),
+		path: filePathParam(),
 		edits: Type.Optional(Type.Array(hashlineEditItemSchema, { description: "Edit operations" })),
 		postEditVerify: Type.Optional(Type.Boolean({
 			description: "Verify persisted content after write",
@@ -112,17 +106,12 @@ function buildEditError(
 
 function mapEditFileError(err: any, filePath: string, displayPath: string, phase: "read" | "write"): ReturnType<typeof buildEditError> {
 	const code = err?.code;
-	if (code === "EISDIR") {
-		return buildEditError(filePath, "path-is-directory",
-			`Path is a directory: ${displayPath}`,
-			`Use ls(${JSON.stringify(displayPath)}) to inspect directories.`);
-	}
-	if (code === "ENOENT") {
-		return buildEditError(filePath, "file-not-found",
-			`${phase === "write" ? "Failed to write file" : "File not found"}: ${displayPath}`);
+	if (code === "ENOENT" && phase === "write") {
+		return buildEditError(filePath, "file-not-found", `Failed to write file: ${displayPath}`);
 	}
-	if (code === "EACCES" || code === "EPERM") {
-		return buildEditError(filePath, "permission-denied", `Permission denied: ${displayPath}`);
+	const fsError = classifyFsError(err, displayPath);
+	if (fsError) {
+		return buildEditError(filePath, fsError.code, fsError.message, fsError.hint);
 	}
 	const prefix = phase === "write" ? "Failed to write file" : "File not readable";
 	const message = `${prefix}: ${displayPath}${err?.message ? ` — ${err.message}` : ""}`;

package/src/fs-error.ts

@@ -0,0 +1,30 @@
+export type FsErrorCode = "path-is-directory" | "permission-denied" | "file-not-found";
+
+export interface FsErrorInfo {
+  code: FsErrorCode;
+  message: string;
+  hint?: string;
+}
+
+/**
+ * Translate a Node `fs` errno into the shared readseek error taxonomy with a
+ * canonical message. Returns null for errno values without a dedicated code so
+ * callers fall back to their own `fs-error` handling.
+ */
+export function classifyFsError(err: { code?: unknown }, path: string): FsErrorInfo | null {
+  switch (err?.code) {
+    case "EISDIR":
+      return {
+        code: "path-is-directory",
+        message: `Path is a directory: ${path}`,
+        hint: `Use ls(${JSON.stringify(path)}) to inspect directories.`,
+      };
+    case "EACCES":
+    case "EPERM":
+      return { code: "permission-denied", message: `Permission denied: ${path}` };
+    case "ENOENT":
+      return { code: "file-not-found", message: `File not found: ${path}` };
+    default:
+      return null;
+  }
+}

package/src/grep-render-helpers.ts

@@ -22,7 +22,7 @@ export function formatGrepCallText(
   };
 }
 
-const GREP_TRUNCATION_THRESHOLD = 50;
+export const GREP_TRUNCATION_THRESHOLD = 50;
 
 interface GrepResultTextInput {
   totalMatches: number;
@@ -56,7 +56,7 @@ export function formatGrepResultText(input: GrepResultTextInput): GrepResultText
 
   const { totalMatches, summary, fileCount } = input;
   const noMatches = totalMatches === 0;
-  const truncated = totalMatches >= GREP_TRUNCATION_THRESHOLD;
+  const truncated = totalMatches > GREP_TRUNCATION_THRESHOLD;
 
   const matchWord = totalMatches === 1 ? "match" : "matches";
   const fileWord = fileCount === 1 ? "file" : "files";

package/src/grep-symbol-scope.ts

@@ -1,38 +1,25 @@
 import { buildReadSeekLine } from "./readseek-value.js";
 import type { GrepOutputEntry, GrepOutputGroup, GrepOutputScopeSymbol, GrepScopeWarning } from "./grep-output.js";
-import type { FileMap, FileSymbol } from "./readseek/types.js";
-
-interface FlatSymbol extends GrepOutputScopeSymbol {
-  rangeSize: number;
-}
-
-function flattenSymbols(symbols: FileSymbol[], parentName?: string): FlatSymbol[] {
-  const flattened: FlatSymbol[] = [];
-  for (const symbol of symbols) {
-    flattened.push({
-      name: symbol.name,
-      kind: symbol.kind,
-      startLine: symbol.startLine,
-      endLine: symbol.endLine,
-      parentName,
-      rangeSize: symbol.endLine - symbol.startLine,
-    });
-    if (symbol.children?.length) flattened.push(...flattenSymbols(symbol.children, symbol.name));
-  }
-  return flattened;
-}
+import type { FileMap } from "./readseek/types.js";
+import { traverseSymbolTree } from "./readseek/symbol-tree.js";
 
 function findEnclosingSymbol(map: FileMap, lineNumber: number): GrepOutputScopeSymbol | null {
-  const candidates = flattenSymbols(map.symbols)
+  const candidates = traverseSymbolTree(map.symbols, (symbol, parentName): GrepOutputScopeSymbol => ({
+    name: symbol.name,
+    kind: symbol.kind,
+    startLine: symbol.startLine,
+    endLine: symbol.endLine,
+    parentName,
+  }))
     .filter((s) => lineNumber >= s.startLine && lineNumber <= s.endLine)
     .sort((a, b) => {
-      if (a.rangeSize !== b.rangeSize) return a.rangeSize - b.rangeSize;
+      const rangeA = a.endLine - a.startLine;
+      const rangeB = b.endLine - b.startLine;
+      if (rangeA !== rangeB) return rangeA - rangeB;
       if (a.startLine !== b.startLine) return a.startLine - b.startLine;
       return a.name.localeCompare(b.name);
     });
-  if (!candidates.length) return null;
-  const { rangeSize: _rangeSize, ...symbol } = candidates[0];
-  return symbol;
+  return candidates.length ? candidates[0] : null;
 }
 
 function firstLineNumber(group: GrepOutputGroup): number {

package/src/grep.ts

@@ -17,7 +17,7 @@ import { getOrGenerateMap } from "./file-map.js";
 import { scopeGrepGroupsToSymbols } from "./grep-symbol-scope.js";
 import { resolveToCwd } from "./path-utils.js";
 import { throwIfAborted } from "./runtime.js";
-import { formatGrepCallText, formatGrepResultText } from "./grep-render-helpers.js";
+import { formatGrepCallText, formatGrepResultText, GREP_TRUNCATION_THRESHOLD } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
@@ -89,7 +89,6 @@ function parseGrepOutputLine(line: string):
 	return null;
 }
 
-const GREP_TRUNCATION_THRESHOLD = 50;
 const GREP_MAX_MATCHES_PER_FILE = 10;
 
 type GrepAnchoredEntry = Extract<GrepOutputEntry, { kind: "match" | "context" }>;

package/src/hashline.ts

@@ -14,7 +14,7 @@ import { CONFUSABLE_HYPHENS_RE } from "./confusable-hyphens.js";
 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; text?: string } }
+	| { insert_after: { anchor: string; new_text: string } }
 	| { replace: { old_text: string; new_text: string; all?: boolean } };
 
 interface HashMismatch {
@@ -382,7 +382,7 @@ function parseHashlineEditItem(edit: HashlineEditItem): ParsedEdit {
 	if ("insert_after" in edit) {
 		return {
 			spec: { kind: "insertAfter", after: parseLineRef(edit.insert_after.anchor) },
-			dstLines: stripNewLinePrefixes(splitDst(edit.insert_after.new_text ?? edit.insert_after.text ?? "")),
+			dstLines: stripNewLinePrefixes(splitDst(edit.insert_after.new_text ?? "")),
 		};
 	}
 	throw new Error("replace edits are applied separately");

package/src/pending-diff-preview.ts

@@ -94,7 +94,7 @@ function isReplaceEdit(edit: unknown): edit is ReplaceEdit {
 type AnchorEdit =
 	| { 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; text?: string } };
+	| { insert_after: { anchor: string; new_text: string } };
 
 function isAnchorEdit(edit: unknown): edit is AnchorEdit {
 	return !!edit && typeof edit === "object" && ("set_line" in edit || "replace_lines" in edit || "insert_after" in edit);

package/src/read-local-bundle.ts

@@ -1,6 +1,7 @@
 import { SymbolKind } from "./readseek/enums.js";
 import type { SymbolMatch } from "./readseek/symbol-lookup.js";
 import type { FileMap, FileSymbol } from "./readseek/types.js";
+import { traverseSymbolTree } from "./readseek/symbol-tree.js";
 
 export interface LocalBundleSupport {
   symbol: SymbolMatch;
@@ -23,19 +24,6 @@ const CONTAINER_KINDS = new Set<SymbolKind>([
   SymbolKind.Namespace,
 ]);
 
-function flattenSymbols(symbols: FileSymbol[], parentName?: string): FlatSymbol[] {
-  const flattened: FlatSymbol[] = [];
-
-  for (const symbol of symbols) {
-    flattened.push({ symbol, parentName });
-    if (symbol.children?.length) {
-      flattened.push(...flattenSymbols(symbol.children, symbol.name));
-    }
-  }
-
-  return flattened;
-}
-
 export function buildLocalBundle(
   fileMap: FileMap,
   requested: SymbolMatch,
@@ -44,7 +32,7 @@ export function buildLocalBundle(
   const requestedText = allLines.slice(requested.startLine - 1, requested.endLine).join("\n");
   const identifiers = new Set(requestedText.match(/\b[A-Za-z_][A-Za-z0-9_]*\b/g) ?? []);
 
-  const candidates = flattenSymbols(fileMap.symbols).filter(({ symbol }) => {
+  const candidates = traverseSymbolTree(fileMap.symbols, (symbol, parentName): FlatSymbol => ({ symbol, parentName })).filter(({ symbol }) => {
     if (CONTAINER_KINDS.has(symbol.kind as SymbolKind)) return false;
     return !(symbol.name === requested.name && symbol.startLine === requested.startLine && symbol.endLine === requested.endLine);
   });

package/src/read.ts

@@ -17,6 +17,7 @@ import { buildReadSeekWarning, buildToolErrorResult, renderReadSeekLines, type R
 import { looksLikeBinary } from "./binary-detect.js";
 import { resolveToCwd } from "./path-utils.js";
 import { throwIfAborted } from "./runtime.js";
+import { classifyFsError } from "./fs-error.js";
 import { getOrGenerateMap } from "./file-map.js";
 import { formatFileMapWithBudget } from "./readseek/formatter.js";
 import { findSymbol, type SymbolMatch } from "./readseek/symbol-lookup.js";
@@ -29,7 +30,7 @@ import { readseekRead, readseekDetect, type ReadSeekDetection } from "./readseek
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
-import { optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
+import { filePathParam, mapParam, optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
 
 const READ_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/read.md", import.meta.url),
@@ -144,17 +145,12 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		rawBuffer = await fsReadFile(absolutePath);
 	} catch (err: any) {
 		const code = err?.code;
-		if (code === "EISDIR") {
-			const message = `Path is a directory: ${rawPath}`;
-			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 buildToolErrorResult("read", "permission-denied", message, { path: rawParams.path });
-		}
-		if (code === "ENOENT") {
-			const message = `File not found: ${rawPath}`;
-			return buildToolErrorResult("read", "file-not-found", message, { path: rawParams.path });
+		const fsError = classifyFsError(err, rawPath);
+		if (fsError) {
+			return buildToolErrorResult("read", fsError.code, fsError.message, {
+				path: rawParams.path,
+				...(fsError.hint ? { hint: fsError.hint } : {}),
+			});
 		}
 		const message = `File not readable: ${rawPath}${err?.message ? ` — ${err.message}` : ""}`;
 		return buildToolErrorResult("read", "fs-error", message, { path: rawParams.path, details: { fsCode: code, fsMessage: err?.message } });
@@ -162,23 +158,23 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 
 	const hasBinaryContent = looksLikeBinary(rawBuffer);
 	if (hasBinaryContent) {
-		// Images are always binary; classify and OCR in a single readseek detect call.
+		// Images are always binary; classify and transcribe in a single readseek detect call.
 		let detection: ReadSeekDetection | undefined;
 		try {
-			detection = await readseekDetect(absolutePath, { ocr: true, signal });
+			detection = await readseekDetect(absolutePath, { transcribe: true, signal });
 		} catch {
 			// detect unavailable — fall through to binary-as-text handling below
 		}
 		if (detection?.type === "image") {
 			const builtinRead = createReadTool(cwd);
 			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
-			const ocrText = detection.ocr?.text?.trim();
-			if (ocrText) {
+			const transcript = detection.transcribe?.text?.trim();
+			if (transcript) {
 				return succeed({
 					...builtinResult,
 					content: [
 						...(builtinResult.content ?? []),
-						{ type: "text" as const, text: `OCR text extracted from image:\n${ocrText}` },
+						{ type: "text" as const, text: `Transcribed text from image:\n${transcript}` },
 					],
 				});
 			}
@@ -450,11 +446,11 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		promptSnippet: READ_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: READ_PROMPT_METADATA.promptGuidelines,
 		parameters: Type.Object({
-			path: Type.String({ description: "File path" }),
+			path: filePathParam(),
 			offset: optionalIntOrString("Start line (1-indexed)"),
 			limit: optionalIntOrString("Max lines"),
 			symbol: Type.Optional(Type.String({ description: "Symbol name to read" })),
-			map: Type.Optional(Type.Boolean({ description: "Append structural map" })),
+			map: mapParam(),
 			bundle: Type.Optional(
 				Type.Literal("local", {
 					description: "Include same-file local support",

package/src/readseek/symbol-lookup.ts

@@ -1,5 +1,6 @@
 import type { FileMap, FileSymbol } from "./types.js";
 import type { SymbolKind } from "./enums.js";
+import { traverseSymbolTree } from "./symbol-tree.js";
 
 export interface SymbolMatch {
   name: string;
@@ -40,20 +41,7 @@ function toMatches(candidates: SymbolCandidate[]): SymbolMatch[] {
 }
 
 function flattenSymbols(symbols: FileSymbol[]): SymbolCandidate[] {
-  const flattened: SymbolCandidate[] = [];
-
-  const visit = (symbol: FileSymbol, parentName?: string): void => {
-    flattened.push({ symbol, parentName });
-    for (const child of symbol.children ?? []) {
-      visit(child, symbol.name);
-    }
-  };
-
-  for (const symbol of symbols) {
-    visit(symbol);
-  }
-
-  return flattened;
+  return traverseSymbolTree(symbols, (symbol, parentName) => ({ symbol, parentName }));
 }
 
 function resolveDotPath(symbols: FileSymbol[], parts: string[]): SymbolCandidate[] {

package/src/readseek/symbol-tree.ts

@@ -0,0 +1,21 @@
+import type { FileSymbol } from "./types.js";
+
+/**
+ * Depth-first walk over a readseek symbol tree. {@link visit} is called for
+ * every symbol with the enclosing symbol's name as `parentName` (undefined at
+ * the top level); its results are returned flattened in pre-order.
+ */
+export function traverseSymbolTree<T>(
+  symbols: FileSymbol[],
+  visit: (symbol: FileSymbol, parentName?: string) => T,
+): T[] {
+  const result: T[] = [];
+  const walk = (nodes: FileSymbol[], parentName?: string) => {
+    for (const symbol of nodes) {
+      result.push(visit(symbol, parentName));
+      if (symbol.children?.length) walk(symbol.children, symbol.name);
+    }
+  };
+  walk(symbols);
+  return result;
+}

package/src/readseek-client.ts

@@ -108,14 +108,14 @@ export interface ReadSeekCheckOutput {
 	diagnostics: ReadSeekDiagnostic[];
 }
 
-export interface ReadSeekOcrLine {
+export interface ReadSeekTranscriptRegion {
 	text: string;
-	bbox: [number, number, number, number];
+	quad: [number, number, number, number, number, number, number, number];
 }
 
-export interface ReadSeekOcrText {
+export interface ReadSeekTranscript {
 	text: string;
-	lines: ReadSeekOcrLine[];
+	regions: ReadSeekTranscriptRegion[];
 }
 
 export type ReadSeekDetection =
@@ -136,7 +136,7 @@ export type ReadSeekDetection =
 			width: number;
 			height: number;
 			animated: boolean;
-			ocr?: ReadSeekOcrText;
+			transcribe?: ReadSeekTranscript;
 		}
 	| {
 			type: "binary";
@@ -641,21 +641,21 @@ export async function readseekCheck(
 	);
 }
 
-function parseOcrText(value: unknown): ReadSeekOcrText | undefined {
+function parseTranscript(value: unknown): ReadSeekTranscript | undefined {
 	if (value === undefined || value === null) return undefined;
-	if (typeof value !== "object") throw new Error("invalid readseek detect ocr");
-	const ocr = value as Record<string, unknown>;
-	if (!Array.isArray(ocr.lines)) throw new Error("invalid readseek detect ocr.lines");
+	if (typeof value !== "object") throw new Error("invalid readseek detect transcribe");
+	const transcribe = value as Record<string, unknown>;
+	if (!Array.isArray(transcribe.regions)) throw new Error("invalid readseek detect transcribe.regions");
 	return {
-		text: requireString(ocr.text, "ocr.text"),
-		lines: ocr.lines.map((line) => {
-			if (!line || typeof line !== "object") throw new Error("invalid readseek detect ocr line");
-			const item = line as Record<string, unknown>;
-			const bbox = item.bbox;
-			if (!Array.isArray(bbox) || bbox.length !== 4) throw new Error("invalid readseek detect ocr bbox");
+		text: requireString(transcribe.text, "transcribe.text"),
+		regions: transcribe.regions.map((region) => {
+			if (!region || typeof region !== "object") throw new Error("invalid readseek detect transcribe region");
+			const item = region as Record<string, unknown>;
+			const quad = item.quad;
+			if (!Array.isArray(quad) || quad.length !== 8) throw new Error("invalid readseek detect transcribe quad");
 			return {
-				text: requireString(item.text, "ocr.line.text"),
-				bbox: bbox.map((n, i) => requireNumber(n, `ocr.line.bbox[${i}]`)) as [number, number, number, number],
+				text: requireString(item.text, "transcribe.region.text"),
+				quad: quad.map((n, i) => requireNumber(n, `transcribe.region.quad[${i}]`)) as ReadSeekTranscriptRegion["quad"],
 			};
 		}),
 	};
@@ -687,7 +687,7 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 				width: requireNumber(output.width, "width"),
 				height: requireNumber(output.height, "height"),
 				animated: requireBoolean(output.animated, "animated"),
-				ocr: parseOcrText(output.ocr),
+				transcribe: parseTranscript(output.transcribe),
 			};
 		case "binary":
 		case "text":
@@ -699,10 +699,10 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 
 export async function readseekDetect(
 	filePath: string,
-	options: { ocr?: boolean; signal?: AbortSignal } = {},
+	options: { transcribe?: boolean; signal?: AbortSignal } = {},
 ): Promise<ReadSeekDetection> {
 	const args = ["detect"];
-	if (options.ocr) args.push("--ocr");
+	if (options.transcribe) args.push("--transcribe");
 	args.push(filePath);
 	return parseDetectOutput(await runReadSeek(args, { signal: options.signal }));
 }

package/src/readseek-params.ts

@@ -33,7 +33,7 @@ export function validateIgnoredRequiresOthers(
   params: { others?: boolean; ignored?: boolean },
 ): ToolErrorResult | null {
   if (params.ignored && !params.others) {
-    return buildToolErrorResult(tool, "invalid-parameter", `Error: ${tool} parameter 'ignored' requires 'others'`);
+    return buildToolErrorResult(tool, "invalid-parameter", `${tool} parameter 'ignored' requires 'others'`);
   }
   return null;
 }

package/src/readseek-value.ts

@@ -86,6 +86,26 @@ export function renderReadSeekLines(lines: ReadSeekLine[]): string {
   return lines.map(renderReadSeekLine).join("\n");
 }
 
+/**
+ * Render the anchored-file block format shared by the `search` and `refs`
+ * tools: a `--- <displayPath> ---` header per file followed by one
+ * `>><anchor>|<display>` line per match. {@link lineSuffix} appends tool
+ * specific trailers (e.g. refs' enclosing-symbol annotation).
+ */
+export function formatAnchoredFileBlocks<T extends ReadSeekLine>(
+  files: Array<{ displayPath: string; lines: T[] }>,
+  lineSuffix?: (line: T) => string,
+): string {
+  const blocks: string[] = [];
+  for (const file of files) {
+    blocks.push(`--- ${file.displayPath} ---`);
+    for (const line of file.lines) {
+      blocks.push(`>>${line.anchor}|${line.display}${lineSuffix?.(line) ?? ""}`);
+    }
+  }
+  return blocks.join("\n");
+}
+
 export function buildReadSeekWarning(
   code: string,
   message: string,

package/src/refs-output.ts

@@ -1,4 +1,4 @@
-import type { ReadSeekLine } from "./readseek-value.js";
+import { formatAnchoredFileBlocks, type ReadSeekLine } from "./readseek-value.js";
 
 export interface RefsOutputLine extends ReadSeekLine {
   enclosingSymbol?: string;
@@ -34,17 +34,8 @@ export function buildRefsOutput(input: BuildRefsOutputInput): RefsOutputResult {
     };
   }
 
-  const blocks: string[] = [];
-  for (const file of input.files) {
-    blocks.push(`--- ${file.displayPath} ---`);
-    for (const line of file.lines) {
-      const suffix = line.enclosingSymbol ? ` (in ${line.enclosingSymbol})` : "";
-      blocks.push(`>>${line.anchor}|${line.display}${suffix}`);
-    }
-  }
-
   return {
-    text: blocks.join("\n"),
+    text: formatAnchoredFileBlocks(input.files, (line) => (line.enclosingSymbol ? ` (in ${line.enclosingSymbol})` : "")),
     readseekValue: {
       tool: "refs",
       files: input.files.map((file) => ({

package/src/refs.ts

@@ -86,7 +86,7 @@ export async function executeRefs(opts: ExecuteRefsOptions): Promise<any> {
   const ignoredError = validateIgnoredRequiresOthers("refs", p);
   if (ignoredError) return ignoredError;
   if (p.scope && p.line === undefined) {
-    return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'scope' requires 'line'");
+    return buildToolErrorResult("refs", "invalid-parameter", "refs parameter 'scope' requires 'line'");
   }
   const searchPath = resolveToCwd(p.path ?? ".", cwd);
 

package/src/register-tool.ts

@@ -10,6 +10,16 @@ export function optionalIntOrString(description: string) {
   return Type.Optional(Type.Union([Type.Number({ description }), Type.String({ description })]));
 }
 
+/** Required file-path parameter shared by the read, edit, and write tools. */
+export function filePathParam() {
+  return Type.String({ description: "File path" });
+}
+
+/** Optional structural-map toggle shared by the read and write tools. */
+export function mapParam() {
+  return Type.Optional(Type.Boolean({ description: "Append structural map" }));
+}
+
 export type ReadSeekToolPolicy = "read-only" | "mutating";
 
 export type ReadSeekToolExposure = "safe-by-default" | "opt-in" | "not-safe-by-default";

package/src/sg-output.ts

@@ -1,4 +1,4 @@
-import type { ReadSeekLine, ReadSeekRange } from "./readseek-value.js";
+import { formatAnchoredFileBlocks, type ReadSeekLine, type ReadSeekRange } from "./readseek-value.js";
 
 export interface SgOutputFile {
   displayPath: string;
@@ -36,16 +36,8 @@ export function buildSgOutput(input: BuildSgOutputInput): SgOutputResult {
     };
   }
 
-  const blocks: string[] = [];
-  for (const file of input.files) {
-    blocks.push(`--- ${file.displayPath} ---`);
-    for (const line of file.lines) {
-      blocks.push(`>>${line.anchor}|${line.display}`);
-    }
-  }
-
   return {
-    text: blocks.join("\n"),
+    text: formatAnchoredFileBlocks(input.files),
     readseekValue: {
       tool: "search",
       files: input.files.map((file) => ({

package/src/sg.ts

@@ -7,7 +7,7 @@ import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadSeekLineWithHash, buildToolErrorResult, type ReadSeekLine } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
 import { statSearchPathOrError } from "./stat-search-path.js";
-import { classifyReadSeekFailure, isReadSeekAvailable, readseekSearch, type ReadSeekHashline, type ReadSeekSearchFileOutput } from "./readseek-client.js";
+import { classifyReadSeekFailure, readseekSearch, type ReadSeekHashline, type ReadSeekSearchFileOutput } from "./readseek-client.js";
 import { buildSgOutput } from "./sg-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { langParam, readseekGitSearchParams, searchPathParam, validateIgnoredRequiresOthers } from "./readseek-params.js";
@@ -52,10 +52,6 @@ const SG_PROMPT_METADATA = defineToolPromptMetadata({
   promptSnippet: "Search code structurally with readseek and return edit-ready anchors",
 });
 
-export function isSgAvailable(): boolean {
-  return isReadSeekAvailable();
-}
-
 interface SgToolOptions {
   onFileAnchored?: FileAnchoredCallback;
 }

package/src/stat-search-path.ts

@@ -23,12 +23,12 @@ export async function statSearchPathOrError(
     const display = rawPath ?? ".";
     const path = rawPath ?? searchPath;
     if (err?.code === "ENOENT") {
-      return { ok: false, error: buildToolErrorResult(tool, "path-not-found", `Error: path '${display}' does not exist`, { path }) };
+      return { ok: false, error: buildToolErrorResult(tool, "path-not-found", `Path '${display}' does not exist`, { path }) };
     }
     if (err?.code === "EACCES" || err?.code === "EPERM") {
-      return { ok: false, error: buildToolErrorResult(tool, "permission-denied", `Error: permission denied for path '${display}'`, { path }) };
+      return { ok: false, error: buildToolErrorResult(tool, "permission-denied", `Permission denied for path '${display}'`, { path }) };
     }
-    const message = `Error: could not access path '${display}': ${err?.message ?? String(err)}`;
+    const message = `Could not access path '${display}': ${err?.message ?? String(err)}`;
     return { ok: false, error: buildToolErrorResult(tool, "fs-error", message, { path, details: { fsCode: err?.code, fsMessage: err?.message } }) };
   }
 }

package/src/write.ts

@@ -9,6 +9,7 @@ import { resolveToCwd } from "./path-utils.js";
 import { ensureHashInit, formatHashlineDisplay } from "./hashline.js";
 import { buildReadSeekError, buildReadSeekLine, buildReadSeekWarning, buildToolErrorResult, type ReadSeekLine, type ReadSeekWarning } from "./readseek-value.js";
 import { looksLikeBinary } from "./binary-detect.js";
+import { classifyFsError, type FsErrorCode } from "./fs-error.js";
 import { getOrGenerateMap } from "./file-map.js";
 import { formatFileMapWithBudget } from "./readseek/formatter.js";
 
@@ -19,7 +20,7 @@ import { buildDiffData, type DiffData } from "./diff-data.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { upsertDiffComponent, upsertTextComponent } from "./tui-diff-component.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
-import { registerReadSeekTool } from "./register-tool.js";
+import { filePathParam, mapParam, registerReadSeekTool } from "./register-tool.js";
 
 const WRITE_PENDING_PREVIEW_STATE_KEY = "hashline-write-pending-preview";
 
@@ -120,8 +121,9 @@ export interface WriteToolOptions {
 }
 
 type MappedFsError = {
-  code: "permission-denied" | "path-is-directory" | "fs-error";
+  code: FsErrorCode | "fs-error";
   message: string;
+  hint?: string;
   includeMeta: boolean;
 };
 
@@ -129,20 +131,6 @@ function mapFsWriteError(err: any, path: string): MappedFsError {
   const phase: "mkdir" | "write" | undefined = err?.__phase;
   const fsCode = err?.code as string | undefined;
 
-  if (fsCode === "EACCES" || fsCode === "EPERM") {
-    return {
-      code: "permission-denied",
-      message: `Permission denied — cannot write: ${path}`,
-      includeMeta: false,
-    };
-  }
-  if (fsCode === "EISDIR") {
-    return {
-      code: "path-is-directory",
-      message: `Path is a directory — cannot overwrite: ${path}`,
-      includeMeta: false,
-    };
-  }
   if (fsCode === "ENOENT" && phase === "mkdir") {
     return {
       code: "fs-error",
@@ -164,6 +152,10 @@ function mapFsWriteError(err: any, path: string): MappedFsError {
       includeMeta: true,
     };
   }
+  const fsError = classifyFsError(err, path);
+  if (fsError) {
+    return { code: fsError.code, message: fsError.message, hint: fsError.hint, includeMeta: false };
+  }
   return {
     code: "fs-error",
     message: `Error writing ${path}: ${err?.message ?? String(err)}`,
@@ -175,6 +167,7 @@ function buildWriteFsErrorResult(err: any, absolutePath: string) {
   const mapped = mapFsWriteError(err, absolutePath);
   return buildToolErrorResult("write", mapped.code, mapped.message, {
     path: absolutePath,
+    hint: mapped.hint,
     extra: { lines: [], warnings: [] },
     details: mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
   });
@@ -321,9 +314,9 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
     promptSnippet: WRITE_PROMPT_METADATA.promptSnippet,
     promptGuidelines: WRITE_PROMPT_METADATA.promptGuidelines,
     parameters: Type.Object({
-      path: Type.String({ description: "File path" }),
+      path: filePathParam(),
       content: Type.String({ description: "File content" }),
-      map: Type.Optional(Type.Boolean({ description: "Append structural map" })),
+      map: mapParam(),
     }),
     async execute(_toolCallId: string, params: { path: string; content: string; map?: boolean }, _signal: AbortSignal | undefined, _onUpdate: any, ctx: any): Promise<any> {
       const cwd = ctx?.cwd ?? process.cwd();