pi-readseek 0.4.25 → 0.4.27

package/README.md

@@ -24,8 +24,9 @@ npm install --save-dev @jarkkojs/readseek
 ## Tools
 
 - **read** — reads text files with `LINE:HASH` anchors for later `edit` calls;
-  images are returned as attachments. Supports `symbol`, `map`, and `bundle`
-  options powered by `@jarkkojs/readseek`.
+  images are returned as attachments and may include local OCR, caption, and
+  object text. Supports `symbol`, `map`, and `bundle` options powered by
+  `@jarkkojs/readseek`.
 - **edit** — changes existing text files using fresh anchors from `read`,
   `grep`, `search`, or `write`. Variants: `set_line`, `replace_lines`,
   `insert_after`, `replace_symbol`, `replace`. Set `new_text` to `""` to
@@ -40,6 +41,38 @@ npm install --save-dev @jarkkojs/readseek
 - **write** — creates or overwrites whole files and returns anchors for
   immediate follow-up edits.
 
+## Settings
+
+`pi-readseek` reads optional JSON settings from:
+
+| Location | Scope |
+| --- | --- |
+| `~/.pi/agent/readseek/settings.json` | Global |
+| `.pi/readseek/settings.json` | Project |
+
+Project settings override global settings. Image OCR behavior is controlled by
+`read.ocrMode`:
+
+```json
+{
+  "read": {
+    "ocrMode": "on"
+  }
+}
+```
+
+Modes:
+
+- `"on"` — always run local image OCR/caption/object analysis. This is the
+  default.
+- `"off"` — return only the image attachment. Use this as a workaround if the
+  local readseek image-analysis path crashes.
+- `"auto"` — run local image analysis only when the active model does not
+  support native image input.
+
+`READSEEK_READ_OCR_MODE=on|off|auto` overrides the JSON setting for one
+process.
+
 ## Related
 
 - [readseek.vim](https://github.com/jarkkojs/readseek.vim) — Vim 9 plugin

package/index.ts

@@ -4,7 +4,10 @@ import { registerEditTool } from "./src/edit.js";
 import { registerGrepTool } from "./src/grep.js";
 import { registerSgTool } from "./src/sg.js";
 import { registerRefsTool } from "./src/refs.js";
+import { registerRenameTool } from "./src/rename.js";
+import { registerHoverTool } from "./src/hover.js";
 import { registerWriteTool } from "./src/write.js";
+import { registerDefTool } from "./src/def.js";
 import { SessionAnchors } from "./src/session-anchors.js";
 import { isReadSeekAvailable } from "./src/readseek-client.js";
 
@@ -23,5 +26,8 @@ export default function piReadSeekExtension(pi: ExtensionAPI): void {
 	registerGrepTool(pi, { searchGuideline, onFileAnchored: markAnchored });
 	registerSgTool(pi, { onFileAnchored: markAnchored });
 	registerRefsTool(pi, { onFileAnchored: markAnchored });
+	registerRenameTool(pi);
+	registerHoverTool(pi);
+	registerDefTool(pi, { onFileAnchored: markAnchored });
 	registerWriteTool(pi, { onFileAnchored: markAnchored });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {

package/prompts/def.md

@@ -0,0 +1,24 @@
+---
+tools: def
+---
+
+Find structural symbol definitions. Calls `readseek def` which searches
+for the definition of a named symbol across a file or directory.
+
+## Parameters
+
+- `path` (optional): File or directory to search (default: ".").
+- `name` (optional): Qualified or unqualified symbol name. Required unless
+  `fromIdentify` is true.
+- `lang` (optional): Language override.
+- `fromIdentify` (optional): When true, reads identify output from a
+  previous identify call to extract the symbol name automatically.
+- `cached` (optional): Search tracked/indexed files in a Git repository.
+- `others` (optional): Search untracked files.
+- `ignored` (optional): Include ignored untracked files.
+
+## When to use
+
+- After a hover call, to jump to where a symbol is defined.
+- When the user asks "where is X defined?".
+- To find a function/class/type definition by its qualified name.

package/prompts/hover.md

@@ -0,0 +1,19 @@
+---
+tools: hover
+---
+
+Use hover to identify the identifier and enclosing symbol at a cursor
+position. Calls `readseek identify` with the file content sent via stdin
+so unsaved editor content is included.
+
+## Parameters
+
+- `path` (required): File path.
+- `line` (required): One-based cursor line.
+- `column` (optional): One-based cursor byte column.
+
+## When to use
+
+- Before a rename, to confirm the identifier under the cursor.
+- Before a go-to-definition, to get the qualified symbol name.
+- To inspect what symbol a specific line belongs to.

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `edit`; supported images return attachments instead of anchors. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `edit`; supported images return attachments and may append OCR/caption/object text depending on `read.ocrMode`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
 
 ## Choose the right read
 

package/prompts/rename.md

@@ -0,0 +1,31 @@
+---
+tools: rename
+---
+
+Use rename to rename an identifier (variable, function, type, etc.) with
+binding accuracy. The tool calls `readseek rename` which resolves the
+lexical binding under the cursor and renames every occurrence that binds
+to the same declaration.
+
+## Parameters
+
+- `path` (required): File holding the binding to rename (a single regular file).
+- `line` (required): One-based cursor line of the binding to rename.
+- `column` (optional): One-based cursor byte column of the binding.
+- `to` (required): New name for the binding. Must be a plain identifier.
+- `workspace` (optional): When true, expands the rename across the project
+  root. The cursor file remains binding-accurate; other files are matched
+  by name (free uses only, local shadows excluded).
+- `apply` (optional, default true): When true, writes the edits to disk
+  after verifying line hashes. When false, returns the plan only.
+
+## When to use
+
+- The user asks to rename a symbol (function, variable, class, etc.).
+- The cursor position (line, optionally column) is known from an identify
+  call or from the user's editor context.
+
+## When not to use
+
+- For search-and-replace across files, use grep or sg.
+- For refactoring that requires adding/removing parameters, use edit.

package/src/def.ts

@@ -0,0 +1,148 @@
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import path from "node:path";
+
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { buildReadSeekLineWithHash, buildToolErrorResult } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { statSearchPathOrError } from "./stat-search-path.js";
+import { classifyReadSeekFailure, readseekDef } from "./readseek-client.js";
+import { searchPathParam, langParam, readseekGitSearchParams } from "./readseek-params.js";
+import { registerReadSeekTool } from "./register-tool.js";
+
+import { renderAnchoredFilesResult, renderReadSeekSearchCall } from "./tui-render-utils.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
+
+const DEF_PROMPT_METADATA = defineToolPromptMetadata({
+	promptUrl: new URL("../prompts/def.md", import.meta.url),
+	promptSnippet: "Find structural symbol definitions with readseek",
+});
+
+type DefParams = {
+	name?: string;
+	path?: string;
+	lang?: string;
+	fromIdentify?: boolean;
+	cached?: boolean;
+	others?: boolean;
+	ignored?: boolean;
+};
+
+interface DefToolOptions {
+	onFileAnchored?: FileAnchoredCallback;
+}
+
+export interface ExecuteDefOptions {
+	params: unknown;
+	signal: AbortSignal | undefined;
+	cwd: string;
+	onFileAnchored?: FileAnchoredCallback;
+}
+
+export async function executeDef(opts: ExecuteDefOptions): Promise<any> {
+	const { params, signal, cwd, onFileAnchored } = opts;
+	const p = params as DefParams;
+
+	if (!p.fromIdentify && (!p.name || !p.name.trim())) {
+		return buildToolErrorResult("def", "invalid-parameter", "def requires 'name' or 'fromIdentify'");
+	}
+
+	const searchPath = resolveToCwd(p.path ?? ".", cwd);
+
+	const statResult = await statSearchPathOrError("def", p.path, searchPath);
+	if (!statResult.ok) return statResult.error;
+
+	try {
+		const definitions = await readseekDef(searchPath, {
+			name: p.name,
+			fromIdentify: p.fromIdentify,
+			language: p.lang,
+			cached: p.cached,
+			others: p.others,
+			ignored: p.ignored,
+			signal,
+		});
+
+		if (definitions.length === 0) {
+			return {
+				content: [{ type: "text", text: "no definitions found" }],
+				details: {
+					readseekValue: { tool: "def", ok: true, path: searchPath, definitions: [] },
+				},
+			};
+		}
+
+		const files = new Map<string, { displayPath: string; path: string; lines: ReturnType<typeof buildReadSeekLineWithHash>[] }>();
+		for (const def of definitions) {
+			const abs = path.isAbsolute(def.file) ? def.file : path.resolve(cwd, def.file);
+			let file = files.get(abs);
+			if (!file) {
+				file = { displayPath: path.relative(cwd, abs) || abs, path: abs, lines: [] };
+				files.set(abs, file);
+			}
+			file.lines.push(buildReadSeekLineWithHash(def.line, def.line_hash, def.text));
+		}
+
+		const fileList = [...files.values()];
+		for (const file of fileList) {
+			onFileAnchored?.(file.path);
+		}
+
+		const textParts: string[] = [];
+		for (const file of fileList) {
+			textParts.push(file.displayPath);
+			for (const line of file.lines) {
+			textParts.push(`  ${line.line}:${line.hash} ${line.display}`);
+			}
+		}
+
+		return {
+			content: [{ type: "text", text: textParts.join("\n") }],
+			details: {
+				readseekValue: { tool: "def", ok: true, path: searchPath, definitions },
+			},
+		};
+	} catch (err: any) {
+		const failure = classifyReadSeekFailure(err);
+		return buildToolErrorResult("def", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+	}
+}
+
+export function registerDefTool(pi: ExtensionAPI, options: DefToolOptions = {}) {
+	registerReadSeekTool(pi, {
+		policy: "read-only",
+		pythonName: "def",
+		defaultExposure: "opt-in",
+	}, {
+		name: "def",
+		label: "Definition",
+		description: DEF_PROMPT_METADATA.description,
+		promptSnippet: DEF_PROMPT_METADATA.promptSnippet,
+		promptGuidelines: DEF_PROMPT_METADATA.promptGuidelines,
+		parameters: Type.Object({
+			name: Type.Optional(Type.String({ description: "Qualified or unqualified symbol name" })),
+			path: searchPathParam(),
+			lang: langParam(),
+			fromIdentify: Type.Optional(Type.Boolean({ description: "Read identify output from stdin to choose the symbol name" })),
+			...readseekGitSearchParams(),
+		}),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeDef({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
+		},
+		renderCall(args: any, theme: any, ...rest: any[]) {
+			return renderReadSeekSearchCall(args, theme, rest, {
+				label: "def",
+				accent: args.name,
+				flags: [args.fromIdentify && "from-identify", args.cached && "cached", args.others && "others", args.ignored && "ignored"],
+			});
+		},
+		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+			return renderAnchoredFilesResult(result, options, theme, rest, {
+				pendingLabel: "pending def",
+				emptyLabel: "no definitions",
+				unitSingular: "definition",
+				unitPlural: "definitions",
+			});
+		},
+	});
+}

package/src/edit.ts

@@ -12,7 +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 { formatFsError } 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";
@@ -104,19 +104,9 @@ function buildEditError(
 	};
 }
 
-function mapEditFileError(err: any, filePath: string, displayPath: string, phase: "read" | "write"): ReturnType<typeof buildEditError> {
-	const code = err?.code;
-	if (code === "ENOENT" && phase === "write") {
-		return buildEditError(filePath, "file-not-found", `Failed to write file: ${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}` : ""}`;
-	return buildEditError(filePath, "fs-error", message, undefined,
-		{ fsCode: code, fsMessage: err?.message });
+function mapEditFileError(err: any, filePath: string, _displayPath: string, _phase: "read" | "write"): ReturnType<typeof buildEditError> {
+	const { code, message } = formatFsError(err, "edit-error");
+	return buildEditError(filePath, code, message);
 }
 
 export interface EditToolOptions {

package/src/fs-error.ts

@@ -1,30 +1,33 @@
-export type FsErrorCode = "path-is-directory" | "permission-denied" | "file-not-found";
+const SYSLOG_PATH_SUFFIX = /,\s+[a-z]+(\s+'.*')?$/;
 
-export interface FsErrorInfo {
-  code: FsErrorCode;
-  message: string;
-  hint?: string;
+/**
+ * Derive the canonical OS strerror from a Node {@link err.message} by
+ * stripping the trailing syscall and optional path suffix so the result
+ * is portable and never duplicates information already carried in the
+ * error-envelope `path` field.
+ */
+function strerror(err: { message?: unknown }): string {
+	const raw = String(err?.message ?? String(err));
+	return raw.replace(SYSLOG_PATH_SUFFIX, "");
 }
 
 /**
- * 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.
+ * Build a readseek error from a Node `fs` errno exception.
+ *
+ * Every errno maps to its own canonical code automatically — no
+ * hand-curated switch, no `"fs-error"` catch-all.
+ *
+ * @param err  The caught exception (carries `err.code` and `err.message`).
+ * @param domain  Tool-level prefix for the message: `"read-error"`,
+ *                `"edit-error"`, `"write-error"`, `"stat-error"`.
  */
-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;
-  }
+export function formatFsError(
+	err: { code?: unknown; message?: string },
+	domain: string,
+): { code: string; message: string } {
+	const errno = typeof err.code === "string" ? err.code : "EIO";
+	return {
+		code: errno,
+		message: `${domain}: ${errno}: ${strerror(err)}`,
+	};
 }

package/src/hover.ts

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Text } from "@earendil-works/pi-tui";
+
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { buildToolErrorResult } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { formatFsError } from "./fs-error.js";
+import { classifyReadSeekFailure, readseekIdentify } from "./readseek-client.js";
+import { filePathParam, registerReadSeekTool } from "./register-tool.js";
+
+import { clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+
+const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
+	promptUrl: new URL("../prompts/hover.md", import.meta.url),
+	promptSnippet: "Identify the identifier and enclosing symbol at a cursor position",
+});
+
+const hoverSchema = Type.Object({
+	path: filePathParam(),
+	line: Type.Number({ description: "One-based cursor line" }),
+	column: Type.Optional(Type.Number({ description: "One-based cursor byte column" })),
+});
+
+interface HoverParams {
+	path: string;
+	line: number;
+	column?: number;
+}
+
+export interface ExecuteHoverOptions {
+	params: unknown;
+	signal: AbortSignal | undefined;
+	cwd: string;
+}
+
+export async function executeHover(opts: ExecuteHoverOptions): Promise<any> {
+	const { params, signal, cwd } = opts;
+	const p = params as HoverParams;
+
+	if (!Number.isSafeInteger(p.line) || p.line < 1) {
+		return buildToolErrorResult("hover", "invalid-parameter", "hover parameter 'line' must be a positive integer");
+	}
+
+	const filePath = resolveToCwd(p.path, cwd);
+
+	let content: string;
+	try {
+		content = await readFile(filePath, "utf-8");
+	} catch (err: any) {
+		const { code, message } = formatFsError(err, "hover-error");
+		return buildToolErrorResult("hover", code, message, { path: p.path });
+	}
+
+	try {
+		const output = await readseekIdentify(filePath, content, {
+			line: p.line,
+			column: p.column,
+			signal,
+		});
+
+		const lines: string[] = [];
+		if (output.identifier) {
+			lines.push(`identifier: ${output.identifier.text}`);
+		}
+		if (output.symbol) {
+			lines.push(`symbol: ${output.symbol.name}`);
+			lines.push(`kind: ${output.symbol.kind}`);
+			lines.push(`qualified: ${output.symbol.qualified_name}`);
+		}
+		lines.push(`file: ${output.file}`);
+		lines.push(`language: ${output.language}`);
+		lines.push(`location: ${output.line}:${output.column}`);
+
+		return {
+			content: [{ type: "text", text: lines.join("\n") }],
+			details: {
+				readseekValue: {
+					tool: "hover",
+					ok: true,
+					path: filePath,
+					output,
+				},
+			},
+		};
+	} catch (err: any) {
+		const failure = classifyReadSeekFailure(err);
+		return buildToolErrorResult("hover", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
+	}
+}
+
+export function registerHoverTool(pi: ExtensionAPI) {
+	registerReadSeekTool(pi, {
+		policy: "read-only",
+		pythonName: "hover",
+		defaultExposure: "opt-in",
+	}, {
+		name: "hover",
+		label: "Hover",
+		description: HOVER_PROMPT_METADATA.description,
+		promptSnippet: HOVER_PROMPT_METADATA.promptSnippet,
+		promptGuidelines: HOVER_PROMPT_METADATA.promptGuidelines,
+		parameters: hoverSchema,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeHover({ params, signal, cwd: ctx.cwd });
+		},
+		renderCall(args: any, theme: any, ...rest: any[]) {
+			const context = rest[0] ?? {};
+			const cwd = context.cwd ?? process.cwd();
+			const displayPath = typeof args?.path === "string" ? args.path : "?";
+			let text = theme.fg("toolTitle", theme.bold("hover"));
+			text += ` ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
+			if (args?.line) text += theme.fg("dim", `:${args.line}`);
+			return text;
+		},
+		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+			const { isPartial, isError, width } = resolveRenderResultContext(options, rest);
+
+			if (isPartial) return renderPendingResult("pending hover", width);
+
+			const content = result.content?.[0];
+			const textContent = content?.type === "text" ? content.text : "";
+
+			if (isError || result.isError) {
+			return new Text(textContent || "hover failed", 0, 0);
+			}
+
+		return new Text(textContent.split("\n")[0] || "", 0, 0);
+		},
+	});
+}

package/src/read.ts

@@ -17,7 +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 { formatFsError } 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";
@@ -28,6 +28,7 @@ import { buildLocalBundle } from "./read-local-bundle.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { readseekRead, readseekDetect, type ReadSeekDetection } from "./readseek-client.js";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
+import { resolveReadSeekOcrMode } from "./readseek-settings.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { filePathParam, mapParam, optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
@@ -57,6 +58,8 @@ export interface ExecuteReadOptions {
 	onUpdate: any;
 	cwd: string;
 	onSuccessfulRead?: FileAnchoredCallback;
+	/** Whether the active model accepts image input natively. Used when OCR mode is auto. */
+	modelSupportsImages?: boolean;
 }
 
 function hasReadAnchors(result: AgentToolResult<any>): boolean {
@@ -68,6 +71,20 @@ function hasReadAnchors(result: AgentToolResult<any>): boolean {
 	return Array.isArray(lines) && lines.length > 0;
 }
 
+function formatImageAnalysis(detection: ReadSeekDetection): string | undefined {
+	if (detection.kind !== "image") return undefined;
+	const sections: string[] = [];
+	const transcript = detection.transcribe?.text?.trim();
+	if (transcript) sections.push(`Transcribed text from image:\n${transcript}`);
+	const caption = detection.caption?.trim();
+	if (caption) sections.push(`Image caption:\n${caption}`);
+	if (detection.objects?.length) {
+		const lines = detection.objects.map((object) => `- ${object.label} [${object.bbox.join(", ")}]`);
+		sections.push(`Detected objects:\n${lines.join("\n")}`);
+	}
+	return sections.length > 0 ? sections.join("\n\n") : undefined;
+}
+
 export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolResult<any>> {
 	const { toolCallId, params, signal, onUpdate, cwd, onSuccessfulRead } = opts;
 	await ensureHashInit();
@@ -144,37 +161,53 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 	try {
 		rawBuffer = await fsReadFile(absolutePath);
 	} catch (err: any) {
-		const code = err?.code;
-		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 } });
+		const { code, message } = formatFsError(err, "read-error");
+		return buildToolErrorResult("read", code, message, {
+			path: rawParams.path,
+		});
 	}
 
 	const hasBinaryContent = looksLikeBinary(rawBuffer);
 	if (hasBinaryContent) {
-		// Images are always binary; classify and transcribe in a single readseek detect call.
 		let detection: ReadSeekDetection | undefined;
 		try {
-			detection = await readseekDetect(absolutePath, { transcribe: true, signal });
+			detection = await readseekDetect(absolutePath, { signal });
 		} catch {
-			// detect unavailable — fall through to binary-as-text handling below
 		}
 		if (detection?.kind === "image") {
 			const builtinRead = createReadTool(cwd);
 			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
-			const transcript = detection.transcribe?.text?.trim();
-			if (transcript) {
+			const ocrMode = resolveReadSeekOcrMode();
+			const shouldTranscribe = ocrMode === "on" || (ocrMode === "auto" && !opts.modelSupportsImages);
+			if (!shouldTranscribe) return succeed(builtinResult);
+
+			let ocrFailed = false;
+			try {
+				const ocrDetection = await readseekDetect(absolutePath, {
+					transcribe: true,
+					caption: true,
+					objects: true,
+					signal,
+				});
+				const imageAnalysis = formatImageAnalysis(ocrDetection);
+				if (imageAnalysis) {
+					return succeed({
+						...builtinResult,
+						content: [
+							...(builtinResult.content ?? []),
+							{ type: "text" as const, text: imageAnalysis },
+						],
+					});
+				}
+			} catch {
+				ocrFailed = true;
+			}
+			if (ocrFailed) {
 				return succeed({
 					...builtinResult,
 					content: [
 						...(builtinResult.content ?? []),
-						{ type: "text" as const, text: `Transcribed text from image:\n${transcript}` },
+						{ type: "text" as const, text: "[Warning: local image analysis (OCR) unavailable — showing image attachment only]" },
 					],
 				});
 			}
@@ -465,6 +498,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				onUpdate,
 				cwd: ctx.cwd,
 				onSuccessfulRead: options.onSuccessfulRead,
+				modelSupportsImages: ctx.model?.input.includes("image") ?? false,
 			});
 		},
 		renderCall(args: any, theme: any, ...rest: any[]) {