@oh-my-pi/pi-coding-agent 16.1.15 → 16.1.17

package/src/tools/eval.ts

@@ -38,8 +38,6 @@ const EVAL_LANGUAGE_NAME: Record<EvalLanguageToken, string> = {
 	rb: "Ruby",
 	jl: "Julia",
 };
-const EVAL_CELLS_DESCRIPTION =
-	"cells executed in order. State persists within each language across cells and tool calls.";
 
 /** Join names as an English "or" list: ["A"]→"A", ["A","B"]→"A or B", 3+→"A, B, or C". */
 function joinWithOr(items: readonly string[]): string {
@@ -56,12 +54,12 @@ function describeCodeField(langs: readonly EvalLanguageToken[]): string {
 	const replLangs = langs.filter(lang => lang === "rb" || lang === "jl");
 	// No persistent REPL backends → keep the original py/js phrasing verbatim so the
 	// default (rb/jl off) wire schema stays byte-identical to the pre-feature one.
-	if (replLangs.length === 0) return "cell body, verbatim. Use top-level await freely.";
+	if (replLangs.length === 0) return "code to run in this eval call, verbatim. Use top-level await freely.";
 	const awaitLangs = langs.filter(lang => lang === "py" || lang === "js");
 	const clauses: string[] = [];
 	if (awaitLangs.length > 0) clauses.push(`Top-level \`await\` is available in ${awaitLangs.join("/")}`);
 	clauses.push(`${replLangs.join("/")} auto-display the last expression like a REPL`);
-	return `cell body, verbatim. ${clauses.join("; ")}.`;
+	return `code to run in this eval call, verbatim. ${clauses.join("; ")}.`;
 }
 
 /** One-line discovery summary listing the runtimes available this session. */
@@ -86,29 +84,24 @@ function enabledEvalLanguages(backends: EvalBackendsAllowance): EvalLanguageToke
 
 const evalCellCommonFields = {
 	"title?": type("string").describe('short label shown in transcript (e.g. "imports", "load config")'),
-	"timeout?": type("number").describe("per-cell timeout in seconds"),
-	"reset?": type("boolean").describe(
-		"wipe this cell's language kernel before running. Other languages are untouched.",
-	),
+	"timeout?": type("number").describe("timeout for this eval call in seconds"),
+	"reset?": type("boolean").describe("wipe this language's kernel before running. Other languages are untouched."),
 };
 
 /**
- * Per-cell input. Each cell runs in order; state persists within a language
- * across cells and across tool calls. This static schema carries the full
- * language union for typing; {@link buildEvalSchema} narrows the wire copy per
- * session so disabled backends are never advertised to the model.
+ * Per-call input: a single cell. State persists within a language across
+ * separate eval calls and across tool calls, so each call is one logical step
+ * and later calls reuse what earlier ones defined. This static schema carries
+ * the full language union for typing; {@link buildEvalSchema} narrows the wire
+ * copy per session so disabled backends are never advertised to the model.
  */
-const evalCellSchema = type({
+export const evalSchema = type({
 	language: type("'py' | 'js' | 'rb' | 'jl'").describe(describeLanguageField(EVAL_LANGUAGE_ORDER)),
-	code: type("string").describe(describeCodeField(EVAL_LANGUAGE_ORDER)),
 	...evalCellCommonFields,
-});
-export type EvalCellInput = typeof evalCellSchema.infer;
-
-export const evalSchema = type({
-	cells: evalCellSchema.array().atLeastLength(1).describe(EVAL_CELLS_DESCRIPTION),
+	code: type("string").describe(describeCodeField(EVAL_LANGUAGE_ORDER)),
 });
 export type EvalToolParams = typeof evalSchema.infer;
+export type EvalCellInput = EvalToolParams;
 
 /**
  * Build a session-scoped copy of the eval schema whose `language` enum and field
@@ -118,14 +111,11 @@ export type EvalToolParams = typeof evalSchema.infer;
  * {@link evalSchema} (full union) remains the type-level source of truth.
  */
 function buildEvalSchema(langs: readonly EvalLanguageToken[]): typeof evalSchema {
-	const cellSchema = type({
+	const schema = type({
 		language: type.enumerated(...langs).describe(describeLanguageField(langs)),
 		code: type("string").describe(describeCodeField(langs)),
 		...evalCellCommonFields,
 	});
-	const schema = type({
-		cells: cellSchema.array().atLeastLength(1).describe(EVAL_CELLS_DESCRIPTION),
-	});
 	return schema as unknown as typeof evalSchema;
 }
 
@@ -290,22 +280,15 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 	readonly approval = "exec" as const;
 	readonly formatApprovalDetails = (args: unknown): string[] => {
 		const params = args as Partial<EvalToolParams>;
-		const cells = Array.isArray(params.cells) ? params.cells : [];
-		const firstCell = cells[0] as Partial<EvalCellInput> | undefined;
-		if (!firstCell) return [];
 		const language =
-			typeof firstCell.language === "string" ? formatEvalInputLanguage(firstCell.language) : "javascript (default)";
-		const code = typeof firstCell.code === "string" ? firstCell.code : "";
-		const lines = [`Language: ${language}`, `Code:\n${truncateForPrompt(code)}`];
-		if (cells.length > 1) {
-			lines.push(`+${cells.length - 1} more cell${cells.length === 2 ? "" : "s"}`);
-		}
-		return lines;
+			typeof params.language === "string" ? formatEvalInputLanguage(params.language) : "javascript (default)";
+		const code = typeof params.code === "string" ? params.code : "";
+		return [`Language: ${language}`, `Code:\n${truncateForPrompt(code)}`];
 	};
 	get summary(): string {
 		return summarizeEvalLanguages(this.#enabledLanguages());
 	}
-	readonly loadMode = "discoverable";
+	readonly loadMode = "essential";
 	readonly label = "Eval";
 	get description(): string {
 		if (!this.session) return getEvalToolDescription();
@@ -320,25 +303,53 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 			spawns: spawnsAllowed,
 		});
 	}
-	readonly examples: readonly ToolExample<typeof evalSchema.infer>[] = [
+	/** All reuse-chain examples; the `examples` getter filters by enabled languages. */
+	private static readonly ALL_EXAMPLES: readonly ToolExample<typeof evalSchema.infer>[] = [
 		{
+			caption: "First call — set up once",
 			call: {
-				cells: [
-					{
-						language: "py",
-						title: "imports",
-						timeout: 10,
-						code: "import json\nfrom pathlib import Path",
-					},
-					{
-						language: "py",
-						title: "load config",
-						code: "data = json.loads(read('package.json'))\ndisplay(data)",
-					},
-				],
+				language: "py",
+				title: "imports",
+				code: "import json\nfrom pathlib import Path",
+			},
+		},
+		{
+			caption: "Second call — reuse, do NOT re-import",
+			call: {
+				language: "py",
+				title: "load config",
+				code: "data = json.loads(read('package.json'))\ndisplay(data)",
+			},
+		},
+		{
+			caption: "Third call — reuse the loaded config",
+			call: {
+				language: "py",
+				title: "scan deps",
+				code: "display(sorted(data['dependencies']))",
+			},
+		},
+		{
+			caption: "Ruby first call — set up once",
+			call: {
+				language: "rb",
+				title: "setup",
+				code: "require 'json'\npkg_path = 'package.json'",
+			},
+		},
+		{
+			caption: "Ruby second call — reuse, do NOT re-require",
+			call: {
+				language: "rb",
+				title: "load config",
+				code: "pkg = JSON.parse(read(pkg_path))\ndisplay(pkg.keys.sort)",
 			},
 		},
 	];
+	get examples(): readonly ToolExample<typeof evalSchema.infer>[] {
+		const langs = new Set(this.#enabledLanguages());
+		return EvalTool.ALL_EXAMPLES.filter(ex => "call" in ex && langs.has(ex.call.language as EvalLanguageToken));
+	}
 	get parameters(): typeof evalSchema {
 		const langs = this.#enabledLanguages();
 		if (langs.length === 0 || langs.length === EVAL_LANGUAGE_ORDER.length) return evalSchema;
@@ -352,13 +363,9 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 	readonly concurrency = "exclusive";
 	readonly strict = true;
 	readonly intent = (args: Partial<typeof evalSchema.infer>): string | undefined => {
-		const cells = Array.isArray(args.cells) ? args.cells : [];
-		const first = cells.find(c => c && typeof c === "object");
-		if (!first) return "evaluating";
-		const title = typeof first.title === "string" ? first.title : undefined;
-		const language = typeof first.language === "string" ? formatEvalInputLanguage(first.language) : "javascript";
-		const label = title || `running ${language}`;
-		return cells.length > 1 ? `${label} (+${cells.length - 1})` : label;
+		const title = typeof args.title === "string" ? args.title : undefined;
+		const language = typeof args.language === "string" ? formatEvalInputLanguage(args.language) : "javascript";
+		return title || `running ${language}`;
 	};
 
 	readonly #proxyExecutor?: EvalProxyExecutor;
@@ -398,27 +405,25 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 		const session = this.session;
 		const excludeWebP = webpExclusionForModel(session.getActiveModel?.());
 
-		const cells: ResolvedEvalCell[] = [];
-		for (let i = 0; i < params.cells.length; i++) {
-			const cell = params.cells[i];
-			const language: EvalLanguage =
-				cell.language === "py"
-					? "python"
-					: cell.language === "rb"
-						? "ruby"
-						: cell.language === "jl"
-							? "julia"
-							: "js";
-			const resolved = await resolveBackend(session, language);
-			cells.push({
-				index: i,
-				title: cell.title,
-				code: cell.code,
-				timeoutMs: (cell.timeout ?? 30) * 1000,
-				reset: cell.reset ?? false,
+		const cellLanguage: EvalLanguage =
+			params.language === "py"
+				? "python"
+				: params.language === "rb"
+					? "ruby"
+					: params.language === "jl"
+						? "julia"
+						: "js";
+		const resolved = await resolveBackend(session, cellLanguage);
+		const cells: ResolvedEvalCell[] = [
+			{
+				index: 0,
+				title: params.title,
+				code: params.code,
+				timeoutMs: (params.timeout ?? 30) * 1000,
+				reset: params.reset ?? false,
 				resolved,
-			});
-		}
+			},
+		];
 		const languages = uniqueEvalLanguages(cells);
 		const notice = detailsNotice(cells);
 		const sessionAbortController = new AbortController();
@@ -453,6 +458,13 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 					status: "pending",
 				}));
 				const cellOutputs: string[] = [];
+				// The cell currently inside backend.execute(). Streamed stdout is
+				// appended to its rendered `output` live so a long-running cell (e.g. a
+				// sleep loop) shows progress instead of nothing until it returns. A
+				// dedicated per-cell tail buffer keeps attribution correct and avoids
+				// double-counting against the aggregate `tailBuffer`; on completion the
+				// authoritative `cellResult.output` (below) overwrites this live tail.
+				let activeLiveCell: { result: EvalCellResult; buf: TailBuffer } | undefined;
 
 				const appendTail = (text: string) => {
 					tailBuffer.append(text);
@@ -502,6 +514,10 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 					maxColumns: resolveOutputMaxColumns(session.settings),
 					onChunk: chunk => {
 						appendTail(chunk);
+						if (activeLiveCell) {
+							activeLiveCell.buf.append(chunk);
+							activeLiveCell.result.output = activeLiveCell.buf.text();
+						}
 						pushUpdate();
 					},
 				});
@@ -529,6 +545,7 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 					cellResult.statusEvents = undefined;
 					cellResult.exitCode = undefined;
 					cellResult.durationMs = undefined;
+					activeLiveCell = { result: cellResult, buf: new TailBuffer(DEFAULT_MAX_BYTES * 2) };
 					pushUpdate();
 
 					const startTime = Date.now();
@@ -562,6 +579,7 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 						});
 					} finally {
 						idle.dispose();
+						activeLiveCell = undefined;
 					}
 					const durationMs = Date.now() - startTime;
 
@@ -623,24 +641,9 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 					cellResult.statusEvents = cellStatusEvents.length > 0 ? cellStatusEvents : undefined;
 					cellResult.hasMarkdown = cellHasMarkdown || undefined;
 
-					let combinedCellOutput = "";
-					if (cells.length > 1) {
-						const cellHeader = `[${i + 1}/${cells.length}]`;
-						const cellTitle = cell.title ? ` ${cell.title}` : "";
-						if (cellOutput) {
-							combinedCellOutput = `${cellHeader}${cellTitle}\n${cellOutput}`;
-						} else {
-							combinedCellOutput = `${cellHeader}${cellTitle} (ok)`;
-						}
-						cellOutputs.push(combinedCellOutput);
-					} else if (cellOutput) {
-						combinedCellOutput = cellOutput;
-						cellOutputs.push(combinedCellOutput);
-					}
-
-					if (combinedCellOutput) {
-						const prefix = cellOutputs.length > 1 ? "\n\n" : "";
-						appendTail(`${prefix}${combinedCellOutput}`);
+					if (cellOutput) {
+						cellOutputs.push(cellOutput);
+						appendTail(cellOutput);
 					}
 
 					if (result.cancelled) {
@@ -648,10 +651,7 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 						pushUpdate();
 						const errorMsg = result.output || "Command aborted";
 						const combinedOutput = cellOutputs.join("\n\n");
-						const outputText =
-							cells.length > 1
-								? `${combinedOutput}\n\nCell ${i + 1} aborted: ${errorMsg}`
-								: combinedOutput || errorMsg;
+						const outputText = combinedOutput || errorMsg;
 
 						const summaryForMeta = await summarizeFinal(combinedOutput, finalizeOutput);
 						const details: EvalToolDetails = {
@@ -674,12 +674,9 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 						cellResult.status = "error";
 						pushUpdate();
 						const combinedOutput = cellOutputs.join("\n\n");
-						const outputText =
-							cells.length > 1
-								? `${combinedOutput}\n\nCell ${i + 1} failed (exit code ${result.exitCode}). Earlier cells succeeded—their state persists. Fix only cell ${i + 1}.`
-								: combinedOutput
-									? `${combinedOutput}\n\nCommand exited with code ${result.exitCode}`
-									: `Command exited with code ${result.exitCode}`;
+						const outputText = combinedOutput
+							? `${combinedOutput}\n\nCommand exited with code ${result.exitCode}`
+							: `Command exited with code ${result.exitCode}`;
 
 						const summaryForMeta = await summarizeFinal(combinedOutput, finalizeOutput);
 						const details: EvalToolDetails = {

package/src/tools/index.ts

@@ -377,7 +377,14 @@ export type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool |
 export type BuiltinToolLoadMode = "essential" | "discoverable";
 
 /** Default essential tool names when tools.essentialOverride is empty. */
-export const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[] = ["read", "bash", "edit", "write", "find"] as const;
+export const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[] = [
+	"read",
+	"bash",
+	"edit",
+	"write",
+	"find",
+	"eval",
+] as const;
 
 /**
  * Resolve the active essential built-in tool names from settings.

package/src/tools/read.ts

@@ -8,7 +8,7 @@ import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import { glob, type SummaryResult, summarizeCode } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
-import { getRemoteDir, logger, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
+import { getRemoteDir, type ImageMetadata, logger, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import { LRUCache } from "lru-cache/raw";
 import {
@@ -22,7 +22,7 @@ import {
 import { normalizeToLF } from "../edit/normalize";
 import { isNotebookPath, readEditableNotebookText } from "../edit/notebook";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
-import { InternalUrlRouter } from "../internal-urls";
+import { InternalUrlRouter, resolveLocalUrlToFile } from "../internal-urls";
 import { parseInternalUrl } from "../internal-urls/parse";
 import type { InternalUrl } from "../internal-urls/types";
 import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
@@ -1112,6 +1112,79 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			.done();
 	}
 
+	/**
+	 * Build content blocks for an on-disk image file: an `inspect_image`
+	 * metadata note when inspection is enabled, otherwise the decoded image
+	 * block. Shared by the plain-file read path and the `local://` image fast
+	 * path so both honor `inspect_image.enabled`, the size cap, and auto-resize
+	 * identically. Too-large / unsupported images surface as {@link ToolError}.
+	 */
+	async #loadImageContent(options: {
+		readPath: string;
+		absolutePath: string;
+		mimeType: string;
+		imageMetadata: ImageMetadata | null;
+		fileSize: number;
+	}): Promise<{ content: Array<TextContent | ImageContent>; details: ReadToolDetails; sourcePath: string }> {
+		const { readPath, absolutePath, mimeType, imageMetadata, fileSize } = options;
+		if (this.#inspectImageEnabled) {
+			const outputMime = imageMetadata?.mimeType ?? mimeType;
+			const metadataLines = [
+				"Image metadata:",
+				`- MIME: ${outputMime}`,
+				`- Bytes: ${fileSize} (${formatBytes(fileSize)})`,
+				imageMetadata?.width !== undefined && imageMetadata.height !== undefined
+					? `- Dimensions: ${imageMetadata.width}x${imageMetadata.height}`
+					: "- Dimensions: unknown",
+				imageMetadata?.channels !== undefined ? `- Channels: ${imageMetadata.channels}` : "- Channels: unknown",
+				imageMetadata?.hasAlpha === true
+					? "- Alpha: yes"
+					: imageMetadata?.hasAlpha === false
+						? "- Alpha: no"
+						: "- Alpha: unknown",
+				"",
+				`If you want to analyze the image, call inspect_image with path="${formatPathRelativeToCwd(
+					absolutePath,
+					this.session.cwd,
+				)}" and a question describing what to inspect and the desired output format.`,
+			];
+			return { content: [{ type: "text", text: metadataLines.join("\n") }], details: {}, sourcePath: absolutePath };
+		}
+
+		if (fileSize > MAX_IMAGE_SIZE) {
+			const sizeStr = formatBytes(fileSize);
+			const maxStr = formatBytes(MAX_IMAGE_SIZE);
+			throw new ToolError(`Image file too large: ${sizeStr} exceeds ${maxStr} limit.`);
+		}
+		try {
+			const imageInput = await loadImageInput({
+				path: readPath,
+				cwd: this.session.cwd,
+				autoResize: this.#autoResizeImages,
+				maxBytes: MAX_IMAGE_SIZE,
+				resolvedPath: absolutePath,
+				detectedMimeType: mimeType,
+				excludeWebP: webpExclusionForModel(this.session.getActiveModel?.()),
+			});
+			if (!imageInput) {
+				throw new ToolError(`Read image file [${mimeType}] failed: unsupported image format.`);
+			}
+			return {
+				content: [
+					{ type: "text", text: imageInput.textNote },
+					{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
+				],
+				details: {},
+				sourcePath: imageInput.resolvedPath,
+			};
+		} catch (error) {
+			if (error instanceof ImageInputTooLargeError) {
+				throw new ToolError(error.message);
+			}
+			throw error;
+		}
+	}
+
 	#buildInMemoryTextResult(
 		text: string,
 		offset: number | undefined,
@@ -2132,64 +2205,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			| undefined;
 
 		if (mimeType) {
-			if (this.#inspectImageEnabled) {
-				const metadata = imageMetadata;
-				const outputMime = metadata?.mimeType ?? mimeType;
-				const outputBytes = fileSize;
-				const metadataLines = [
-					"Image metadata:",
-					`- MIME: ${outputMime}`,
-					`- Bytes: ${outputBytes} (${formatBytes(outputBytes)})`,
-					metadata?.width !== undefined && metadata.height !== undefined
-						? `- Dimensions: ${metadata.width}x${metadata.height}`
-						: "- Dimensions: unknown",
-					metadata?.channels !== undefined ? `- Channels: ${metadata.channels}` : "- Channels: unknown",
-					metadata?.hasAlpha === true
-						? "- Alpha: yes"
-						: metadata?.hasAlpha === false
-							? "- Alpha: no"
-							: "- Alpha: unknown",
-					"",
-					`If you want to analyze the image, call inspect_image with path="${formatPathRelativeToCwd(
-						absolutePath,
-						this.session.cwd,
-					)}" and a question describing what to inspect and the desired output format.`,
-				];
-				content = [{ type: "text", text: metadataLines.join("\n") }];
-				details = {};
-				sourcePath = absolutePath;
-			} else {
-				if (fileSize > MAX_IMAGE_SIZE) {
-					const sizeStr = formatBytes(fileSize);
-					const maxStr = formatBytes(MAX_IMAGE_SIZE);
-					throw new ToolError(`Image file too large: ${sizeStr} exceeds ${maxStr} limit.`);
-				}
-				try {
-					const imageInput = await loadImageInput({
-						path: readPath,
-						cwd: this.session.cwd,
-						autoResize: this.#autoResizeImages,
-						maxBytes: MAX_IMAGE_SIZE,
-						resolvedPath: absolutePath,
-						detectedMimeType: mimeType,
-						excludeWebP: webpExclusionForModel(this.session.getActiveModel?.()),
-					});
-					if (!imageInput) {
-						throw new ToolError(`Read image file [${mimeType}] failed: unsupported image format.`);
-					}
-					content = [
-						{ type: "text", text: imageInput.textNote },
-						{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
-					];
-					details = {};
-					sourcePath = imageInput.resolvedPath;
-				} catch (error) {
-					if (error instanceof ImageInputTooLargeError) {
-						throw new ToolError(error.message);
-					}
-					throw error;
-				}
-			}
+			({ content, details, sourcePath } = await this.#loadImageContent({
+				readPath,
+				absolutePath,
+				mimeType,
+				imageMetadata,
+				fileSize,
+			}));
 		} else if (isNotebookPath(absolutePath) && !isRawSelector(parsed)) {
 			const notebookText = await readEditableNotebookText(absolutePath, localReadPath);
 			if (isMultiRange(parsed) && parsed.kind === "lines") {
@@ -2727,6 +2749,17 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			hasExtraction = hasPathExtraction || hasQueryExtraction;
 		}
 
+		// local:// files are real on-disk paths. Detect image files and emit a
+		// decoded image block before the text-only resource contract UTF-8
+		// decodes the binary into mojibake. The fast path returns null for
+		// non-images, directories, listings, or any resolution failure, so the
+		// text path below reproduces the router's not-found / symlink-escape
+		// behavior unchanged.
+		if (scheme === "local") {
+			const imageResult = await this.#tryReadLocalImage(urlMeta, signal);
+			if (imageResult) return imageResult;
+		}
+
 		// Reject line selectors when query extraction is used
 		if (hasExtraction && parsedSel.kind !== "none" && parsedSel.kind !== "raw") {
 			throw new ToolError("Cannot combine query extraction with line selectors");
@@ -2770,6 +2803,49 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		});
 	}
 
+	/**
+	 * Fast path for `local://` image files. Resolves the URL to its real
+	 * on-disk path with the same realpath + containment checks as
+	 * {@link LocalProtocolHandler.resolve} (via {@link resolveLocalUrlToFile}),
+	 * and — only when the target is a genuine image — emits a decoded image
+	 * block. Returns null for non-images, directories, listings, or any
+	 * resolution failure (not-found, symlink escape) so the caller falls back to
+	 * normal text resolution, which reproduces the router's errors. Errors from
+	 * a confirmed image (too large / unsupported) propagate rather than
+	 * degrading into a corrupted text read.
+	 */
+	async #tryReadLocalImage(url: InternalUrl, signal?: AbortSignal): Promise<AgentToolResult<ReadToolDetails> | null> {
+		let file: { path: string; size: number } | null;
+		try {
+			file = await resolveLocalUrlToFile(url, {
+				cwd: this.session.cwd,
+				settings: this.session.settings,
+				signal,
+				localProtocolOptions: this.session.localProtocolOptions,
+			});
+		} catch {
+			// Not found / containment escape / no session — let the text path
+			// surface the router's canonical error.
+			return null;
+		}
+		if (!file) return null;
+
+		const imageMetadata = await readImageMetadata(file.path);
+		const mimeType = imageMetadata?.mimeType;
+		if (!mimeType) return null;
+
+		const { content, details, sourcePath } = await this.#loadImageContent({
+			readPath: url.href,
+			absolutePath: file.path,
+			mimeType,
+			imageMetadata,
+			fileSize: file.size,
+		});
+		const resultBuilder = toolResult(details).content(content).sourceInternal(url.href);
+		if (sourcePath) resultBuilder.sourcePath(sourcePath);
+		return resultBuilder.done();
+	}
+
 	/** Read directory contents as a formatted listing */
 	async #readDirectory(
 		absolutePath: string,