@oh-my-pi/pi-coding-agent 13.18.0 → 14.0.2

package/src/tools/read.ts

@@ -5,15 +5,22 @@ import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import { glob } 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, untilAborted } from "@oh-my-pi/pi-utils";
+import { getRemoteDir, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { renderPromptTemplate } from "../config/prompt-templates";
+import { computeLineHash } from "../edit/line-hash";
+import {
+	type ChunkReadTarget,
+	formatChunkedRead,
+	parseChunkReadPath,
+	parseChunkSelector,
+	resolveAnchorStyle,
+} from "../edit/modes/chunk";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { parseInternalUrl } from "../internal-urls/parse";
 import type { InternalUrl } from "../internal-urls/types";
 import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
-import { computeLineHash } from "../patch/hashline";
 import readDescription from "../prompts/tools/read.md" with { type: "text" };
+import readChunkDescription from "../prompts/tools/read-chunk.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
 import {
 	DEFAULT_MAX_BYTES,
@@ -25,20 +32,17 @@ import {
 } from "../session/streaming-output";
 import { renderCodeCell, renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
+import { resolveEditMode } from "../utils/edit-mode";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
-import {
-	ImageInputTooLargeError,
-	loadImageInput,
-	MAX_IMAGE_INPUT_BYTES,
-	readImageMetadata,
-} from "../utils/image-input";
+import { ImageInputTooLargeError, loadImageInput, MAX_IMAGE_INPUT_BYTES } from "../utils/image-loading";
 import { convertFileWithMarkit } from "../utils/markit";
-import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 import { type ArchiveReader, openArchive, parseArchivePathCandidates } from "./archive-reader";
+
 import {
 	executeReadUrl,
 	isReadableUrlPath,
 	loadReadUrlCacheEntry,
+	parseReadUrlTarget,
 	type ReadUrlToolDetails,
 	renderReadUrlCall,
 	renderReadUrlResult,
@@ -50,19 +54,14 @@ import { formatAge, formatBytes, shortenPath, wrapBrackets } from "./render-util
 import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
+const PROSE_LANGUAGES = new Set(["markdown", "text", "log", "asciidoc", "restructuredtext"]);
+
+function isProseLanguage(language: string | undefined): boolean {
+	return language !== undefined && PROSE_LANGUAGES.has(language);
+}
+
 // Document types converted to markdown via markit.
-const CONVERTIBLE_EXTENSIONS = new Set([
-	".pdf",
-	".doc",
-	".docx",
-	".ppt",
-	".pptx",
-	".xls",
-	".xlsx",
-	".rtf",
-	".epub",
-	".ipynb",
-]);
+const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".rtf", ".epub"]);
 
 // Remote mount path prefix (sshfs mounts) - skip fuzzy matching to avoid hangs
 const REMOTE_MOUNT_PREFIX = getRemoteDir() + path.sep;
@@ -354,10 +353,8 @@ function prependSuffixResolutionNotice(text: string, suffixResolution?: { from:
 
 const readSchema = Type.Object({
 	path: Type.String({ description: "Path or URL to read" }),
-	offset: Type.Optional(Type.Number({ description: "Line number to start from (1-indexed)" })),
-	limit: Type.Optional(Type.Number({ description: "Maximum number of lines" })),
+	sel: Type.Optional(Type.String({ description: "Selector: chunk path, L10-L50, or raw" })),
 	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 20)" })),
-	raw: Type.Optional(Type.Boolean({ description: "If set, returns raw content without transformations" })),
 });
 
 export type ReadToolInput = Static<typeof readSchema>;
@@ -368,6 +365,7 @@ export interface ReadToolDetails {
 	isDirectory?: boolean;
 	resolvedPath?: string;
 	suffixResolution?: { from: string; to: string };
+	chunk?: ChunkReadTarget;
 	url?: string;
 	finalUrl?: string;
 	contentType?: string;
@@ -378,6 +376,43 @@ export interface ReadToolDetails {
 
 type ReadParams = ReadToolInput;
 
+/** Parsed representation of the `sel` parameter. */
+type ParsedSelector =
+	| { kind: "none" }
+	| { kind: "raw" }
+	| { kind: "lines"; startLine: number; endLine: number | undefined }
+	| { kind: "chunk"; selector: string };
+
+const LINE_RANGE_RE = /^L(\d+)(?:-L?(\d+))?$/i;
+
+function parseSel(sel: string | undefined): ParsedSelector {
+	if (!sel || sel.length === 0) return { kind: "none" };
+	const normalizedSelector = parseChunkSelector(sel).selector ?? sel;
+	if (normalizedSelector === "raw") return { kind: "raw" };
+	const lineMatch = LINE_RANGE_RE.exec(normalizedSelector);
+	if (lineMatch) {
+		const rawStart = Number.parseInt(lineMatch[1]!, 10);
+		if (rawStart < 1) {
+			throw new ToolError("L0 is invalid; lines are 1-indexed. Use sel=L1.");
+		}
+		const rawEnd = lineMatch[2] ? Number.parseInt(lineMatch[2], 10) : undefined;
+		if (rawEnd !== undefined && rawEnd < rawStart) {
+			throw new ToolError(`Invalid range L${rawStart}-L${rawEnd}: end must be >= start.`);
+		}
+		return { kind: "lines", startLine: rawStart, endLine: rawEnd };
+	}
+	return { kind: "chunk", selector: normalizedSelector };
+}
+
+/** Convert a line-range selector to the offset/limit pair used by internal pagination. */
+function selToOffsetLimit(parsed: ParsedSelector): { offset?: number; limit?: number } {
+	if (parsed.kind === "lines") {
+		const limit = parsed.endLine !== undefined ? parsed.endLine - parsed.startLine + 1 : undefined;
+		return { offset: parsed.startLine, limit };
+	}
+	return {};
+}
+
 interface ResolvedArchiveReadPath {
 	absolutePath: string;
 	archiveSubPath: string;
@@ -410,12 +445,17 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			Math.min(session.settings.get("read.defaultLimit") ?? DEFAULT_MAX_LINES, DEFAULT_MAX_LINES),
 		);
 		this.#inspectImageEnabled = session.settings.get("inspect_image.enabled");
-		this.description = renderPromptTemplate(readDescription, {
-			DEFAULT_LIMIT: String(this.#defaultLimit),
-			DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
-			IS_HASHLINE_MODE: displayMode.hashLines,
-			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
-		});
+		this.description =
+			resolveEditMode(session) === "chunk"
+				? prompt.render(readChunkDescription, {
+						anchorStyle: resolveAnchorStyle(session.settings),
+					})
+				: prompt.render(readDescription, {
+						DEFAULT_LIMIT: String(this.#defaultLimit),
+						DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
+						IS_HASHLINE_MODE: displayMode.hashLines,
+						IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
+					});
 	}
 
 	async #resolveArchiveReadPath(readPath: string, signal?: AbortSignal): Promise<ResolvedArchiveReadPath | null> {
@@ -470,6 +510,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			sourceUrl?: string;
 			sourceInternal?: string;
 			entityLabel: string;
+			ignoreResultLimits?: boolean;
 		},
 	): AgentToolResult<ReadToolDetails> {
 		const displayMode = resolveFileDisplayMode(this.session);
@@ -478,6 +519,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const totalLines = allLines.length;
 		const startLine = offset ? Math.max(0, offset - 1) : 0;
 		const startLineDisplay = startLine + 1;
+		const ignoreResultLimits = options.ignoreResultLimits ?? false;
 
 		const resultBuilder = toolResult(details);
 		if (options.sourcePath) {
@@ -494,18 +536,19 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			const suggestion =
 				allLines.length === 0
 					? `The ${options.entityLabel} is empty.`
-					: `Use offset=1 to read from the start, or offset=${allLines.length} to read the last line.`;
+					: `Use sel=L1 to read from the start, or sel=L${allLines.length} to read the last line.`;
 			return resultBuilder
 				.text(
-					`Offset ${offset} is beyond end of ${options.entityLabel} (${allLines.length} lines total). ${suggestion}`,
+					`Line ${startLineDisplay} is beyond end of ${options.entityLabel} (${allLines.length} lines total). ${suggestion}`,
 				)
 				.done();
 		}
 
-		const endLine = limit !== undefined ? Math.min(startLine + limit, allLines.length) : allLines.length;
+		const endLine =
+			limit !== undefined && !ignoreResultLimits ? Math.min(startLine + limit, allLines.length) : allLines.length;
 		const selectedContent = allLines.slice(startLine, endLine).join("\n");
-		const userLimitedLines = limit !== undefined ? endLine - startLine : undefined;
-		const truncation = truncateHead(selectedContent);
+		const userLimitedLines = limit !== undefined && !ignoreResultLimits ? endLine - startLine : undefined;
+		const truncation = ignoreResultLimits ? noTruncResult(selectedContent) : truncateHead(selectedContent);
 
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
@@ -553,7 +596,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			const nextOffset = startLine + userLimitedLines + 1;
 
 			outputText = formatText(selectedContent, startLineDisplay);
-			outputText += `\n\n[${remaining} more lines in ${options.entityLabel}. Use offset=${nextOffset} to continue]`;
+			outputText += `\n\n[${remaining} more lines in ${options.entityLabel}. Use sel=L${nextOffset} to continue]`;
 		} else {
 			outputText = formatText(truncation.content, startLineDisplay);
 		}
@@ -671,42 +714,60 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		_onUpdate?: AgentToolUpdateCallback<ReadToolDetails>,
 		_toolContext?: AgentToolContext,
 	): Promise<AgentToolResult<ReadToolDetails>> {
-		let { path: readPath, offset, limit, timeout, raw } = params;
-		const displayMode = resolveFileDisplayMode(this.session);
+		let { path: readPath, sel, timeout } = params;
 		if (readPath.startsWith("file://")) {
 			readPath = expandPath(readPath);
 		}
+		const displayMode = resolveFileDisplayMode(this.session);
+		const chunkMode = resolveEditMode(this.session) === "chunk";
 
 		// Handle internal URLs (agent://, artifact://, memory://, skill://, rule://, local://, mcp://)
 		const internalRouter = this.session.internalRouter;
 		if (internalRouter?.canHandle(readPath)) {
+			const parsed = parseSel(sel);
+			const { offset, limit } = selToOffsetLimit(parsed);
 			return this.#handleInternalUrl(readPath, offset, limit);
 		}
 
-		if (isReadableUrlPath(readPath)) {
+		const parsedUrlTarget = parseReadUrlTarget(readPath, sel);
+		if (parsedUrlTarget) {
 			if (!this.session.settings.get("fetch.enabled")) {
 				throw new ToolError("URL reads are disabled by settings.");
 			}
-			if (offset !== undefined || limit !== undefined) {
-				const cached = await loadReadUrlCacheEntry(this.session, { path: readPath, timeout, raw }, signal, {
-					ensureArtifact: true,
-					preferCached: true,
-				});
-				return this.#buildInMemoryTextResult(cached.output, offset, limit, {
+			if (parsedUrlTarget.offset !== undefined || parsedUrlTarget.limit !== undefined) {
+				const cached = await loadReadUrlCacheEntry(
+					this.session,
+					{ path: parsedUrlTarget.path, timeout, raw: parsedUrlTarget.raw },
+					signal,
+					{
+						ensureArtifact: true,
+						preferCached: true,
+					},
+				);
+				return this.#buildInMemoryTextResult(cached.output, parsedUrlTarget.offset, parsedUrlTarget.limit, {
 					details: { ...cached.details },
 					sourceUrl: cached.details.finalUrl,
 					entityLabel: "URL output",
 				});
 			}
-			return executeReadUrl(this.session, { path: readPath, timeout, raw }, signal);
+			return executeReadUrl(this.session, { path: parsedUrlTarget.path, timeout, raw: parsedUrlTarget.raw }, signal);
 		}
 
-		const archivePath = await this.#resolveArchiveReadPath(readPath, signal);
+		const parsedReadPath = chunkMode ? parseChunkReadPath(readPath) : { filePath: readPath };
+		const localReadPath = parsedReadPath.filePath;
+		const pathSelectorParsed = chunkMode ? parseSel(parsedReadPath.selector) : { kind: "none" as const };
+		const pathChunkSelector = pathSelectorParsed.kind === "chunk" ? pathSelectorParsed.selector : undefined;
+		const selectorInput = sel ?? parsedReadPath.selector;
+		const rawSelectorInput = sel ?? parsedReadPath.selector;
+		const parsed = parseSel(selectorInput);
+
+		const archivePath = await this.#resolveArchiveReadPath(localReadPath, signal);
 		if (archivePath) {
+			const { offset, limit } = selToOffsetLimit(parsed);
 			return this.#readArchive(readPath, offset, limit, archivePath, signal);
 		}
 
-		let absolutePath = resolveReadPath(readPath, this.session.cwd);
+		let absolutePath = resolveReadPath(localReadPath, this.session.cwd);
 		let suffixResolution: { from: string; to: string } | undefined;
 
 		let isDirectory = false;
@@ -719,14 +780,14 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (isNotFoundError(error)) {
 				// Attempt unique suffix resolution before falling back to fuzzy suggestions
 				if (!isRemoteMountPath(absolutePath)) {
-					const suffixMatch = await findUniqueSuffixMatch(readPath, this.session.cwd, signal);
+					const suffixMatch = await findUniqueSuffixMatch(localReadPath, this.session.cwd, signal);
 					if (suffixMatch) {
 						try {
 							const retryStat = await Bun.file(suffixMatch.absolutePath).stat();
 							absolutePath = suffixMatch.absolutePath;
 							fileSize = retryStat.size;
 							isDirectory = retryStat.isDirectory();
-							suffixResolution = { from: readPath, to: suffixMatch.displayPath };
+							suffixResolution = { from: localReadPath, to: suffixMatch.displayPath };
 						} catch {
 							// Suffix match candidate no longer stats — fall through to error path
 						}
@@ -734,7 +795,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				}
 
 				if (!suffixResolution) {
-					throw new ToolError(`Path '${readPath}' not found`);
+					throw new ToolError(`Path '${localReadPath}' not found`);
 				}
 			} else {
 				throw error;
@@ -742,7 +803,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 
 		if (isDirectory) {
-			const dirResult = await this.#readDirectory(absolutePath, limit, signal);
+			const dirResult = await this.#readDirectory(absolutePath, selToOffsetLimit(parsed).limit, signal);
 			if (suffixResolution) {
 				dirResult.details ??= {};
 				dirResult.details.suffixResolution = suffixResolution;
@@ -750,11 +811,59 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			return dirResult;
 		}
 
-		const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
+		const imageMetadata = await readImageMetadata(absolutePath);
+		const mimeType = imageMetadata?.mimeType;
 		const ext = path.extname(absolutePath).toLowerCase();
+		const hasEditTool = this.session.hasEditTool ?? true;
+		const language = getLanguageFromPath(absolutePath);
+		const skipChunksForExplore = !hasEditTool && !this.session.settings.get("read.explorechunks");
+		const skipChunksForProse = isProseLanguage(language) && !this.session.settings.get("read.prosechunks");
+		const shouldConvertWithMarkit =
+			CONVERTIBLE_EXTENSIONS.has(ext) || (ext === ".ipynb" && (parsed.kind === "raw" || !chunkMode));
+
+		if (chunkMode && parsed.kind !== "raw" && !skipChunksForExplore && !skipChunksForProse) {
+			const absoluteLineRange =
+				pathChunkSelector && parsed.kind === "lines"
+					? { startLine: parsed.startLine, endLine: parsed.endLine }
+					: undefined;
+			// sel= wins over path:chunk when both are provided (explicit param > embedded path).
+			const effectiveSelector = sel ? selectorInput : (pathChunkSelector ?? selectorInput);
+			const rawEffectiveSelector = sel ? selectorInput : (rawSelectorInput ?? effectiveSelector);
+			const chunkReadPath =
+				parsed.kind === "chunk" || (pathChunkSelector && !sel)
+					? rawEffectiveSelector
+						? `${localReadPath}:${rawEffectiveSelector}`
+						: localReadPath
+					: parsed.kind === "lines"
+						? parsed.endLine !== undefined
+							? `${localReadPath}:L${parsed.startLine}-L${parsed.endLine}`
+							: `${localReadPath}:L${parsed.startLine}`
+						: localReadPath;
+			const chunkResult = await formatChunkedRead({
+				filePath: absolutePath,
+				readPath: chunkReadPath,
+				cwd: this.session.cwd,
+				language,
+				omitChecksum: !hasEditTool,
+				anchorStyle: resolveAnchorStyle(this.session.settings),
+				absoluteLineRange,
+			});
+			let text = chunkResult.text;
+			if (suffixResolution) {
+				text = prependSuffixResolutionNotice(text, suffixResolution);
+			}
+			return toolResult<ReadToolDetails>({
+				resolvedPath: absolutePath,
+				suffixResolution,
+				chunk: chunkResult.chunk,
+			})
+				.text(text)
+				.sourcePath(absolutePath)
+				.done();
+		}
 
 		// Read the file based on type
-		let content: (TextContent | ImageContent)[];
+		let content: Array<TextContent | ImageContent>;
 		let details: ReadToolDetails = {};
 		let sourcePath: string | undefined;
 		let truncationInfo:
@@ -763,14 +872,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		if (mimeType) {
 			if (this.#inspectImageEnabled) {
-				const metadata = await readImageMetadata({
-					path: readPath,
-					cwd: this.session.cwd,
-					resolvedPath: absolutePath,
-					detectedMimeType: mimeType,
-				});
+				const metadata = imageMetadata;
 				const outputMime = metadata?.mimeType ?? mimeType;
-				const outputBytes = metadata?.bytes ?? fileSize;
+				const outputBytes = fileSize;
 				const metadataLines = [
 					"Image metadata:",
 					`- MIME: ${outputMime}`,
@@ -821,7 +925,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					throw error;
 				}
 			}
-		} else if (CONVERTIBLE_EXTENSIONS.has(ext)) {
+		} else if (shouldConvertWithMarkit) {
 			// Convert document or notebook via markit.
 			const result = await convertFileWithMarkit(absolutePath, signal);
 			if (result.ok) {
@@ -840,13 +944,41 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				content = [{ type: "text", text: `[Cannot read ${ext} file: conversion failed]` }];
 			}
 		} else {
-			// Read as text using streaming to avoid loading huge files into memory
+			// Chunk mode: dispatch to chunk tree unless raw or line range requested
+			if (chunkMode && parsed.kind !== "raw" && parsed.kind !== "lines") {
+				const chunkSel = parsed.kind === "chunk" ? parsed.selector : undefined;
+				const chunkResult = await formatChunkedRead({
+					filePath: absolutePath,
+					readPath: chunkSel ? `${localReadPath}:${chunkSel}` : localReadPath,
+					cwd: this.session.cwd,
+					language: getLanguageFromPath(absolutePath),
+					omitChecksum: !(this.session.hasEditTool ?? true),
+					anchorStyle: resolveAnchorStyle(this.session.settings),
+				});
+				let text = chunkResult.text;
+				if (suffixResolution) {
+					text = prependSuffixResolutionNotice(text, suffixResolution);
+				}
+				return toolResult<ReadToolDetails>({
+					resolvedPath: absolutePath,
+					suffixResolution,
+					chunk: chunkResult.chunk,
+				})
+					.text(text)
+					.sourcePath(absolutePath)
+					.done();
+			}
+
+			// Raw text or line-range mode
+			const { offset, limit } = selToOffsetLimit(parsed);
 			const startLine = offset ? Math.max(0, offset - 1) : 0;
-			const startLineDisplay = startLine + 1; // For display (1-indexed)
+			const startLineDisplay = startLine + 1;
 
-			const effectiveLimit = limit ?? this.#defaultLimit;
+			const DEFAULT_LIMIT = this.#defaultLimit;
+			const effectiveLimit = limit ?? DEFAULT_LIMIT;
 			const maxLinesToCollect = Math.min(effectiveLimit, DEFAULT_MAX_LINES);
 			const selectedLineLimit = effectiveLimit;
+
 			const streamResult = await streamLinesFromFile(
 				absolutePath,
 				startLine,
@@ -870,9 +1002,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				const suggestion =
 					totalFileLines === 0
 						? "The file is empty."
-						: `Use offset=1 to read from the start, or offset=${totalFileLines} to read the last line.`;
+						: `Use sel=L1 to read from the start, or sel=L${totalFileLines} to read the last line.`;
 				return toolResult<ReadToolDetails>({ resolvedPath: absolutePath, suffixResolution })
-					.text(`Offset ${offset} is beyond end of file (${totalFileLines} lines total). ${suggestion}`)
+					.text(`Line ${startLineDisplay} is beyond end of file (${totalFileLines} lines total). ${suggestion}`)
 					.done();
 			}
 
@@ -939,7 +1071,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				const nextOffset = startLine + userLimitedLines + 1;
 
 				outputText = formatText(truncation.content, startLineDisplay);
-				outputText += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue]`;
+				outputText += `\n\n[${remaining} more lines in file. Use sel=L${nextOffset} to continue]`;
 				details = {};
 				sourcePath = absolutePath;
 			} else {
@@ -1011,82 +1143,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			return toolResult(details).text(resource.content).sourceInternal(url).done();
 		}
 
-		// Apply pagination similar to file reading.
-		const allLines = resource.content.split("\n");
-		const totalLines = allLines.length;
-
-		const startLine = offset ? Math.max(0, offset - 1) : 0;
-		const startLineDisplay = startLine + 1;
-
-		if (startLine >= allLines.length) {
-			const suggestion =
-				allLines.length === 0
-					? "The resource is empty."
-					: `Use offset=1 to read from the start, or offset=${allLines.length} to read the last line.`;
-			return toolResult<ReadToolDetails>(details)
-				.text(`Offset ${offset} is beyond end of resource (${allLines.length} lines total). ${suggestion}`)
-				.done();
-		}
-
-		const ignoreLimits = scheme === "skill";
-		let selectedContent: string;
-		let userLimitedLines: number | undefined;
-		if (limit !== undefined && !ignoreLimits) {
-			const endLine = Math.min(startLine + limit, allLines.length);
-			selectedContent = allLines.slice(startLine, endLine).join("\n");
-			userLimitedLines = endLine - startLine;
-		} else {
-			selectedContent = allLines.slice(startLine).join("\n");
-		}
-
-		const truncation: TruncationResult = ignoreLimits
-			? noTruncResult(selectedContent)
-			: truncateHead(selectedContent);
-
-		let outputText: string;
-		let truncationInfo:
-			| { result: TruncationResult; options: { direction: "head"; startLine?: number; totalFileLines?: number } }
-			| undefined;
-
-		if (truncation.firstLineExceedsLimit) {
-			const firstLine = allLines[startLine] ?? "";
-			const firstLineBytes = Buffer.byteLength(firstLine, "utf-8");
-			const snippet = truncateHeadBytes(firstLine, DEFAULT_MAX_BYTES);
-
-			outputText = snippet.text;
-			if (snippet.text.length === 0) {
-				outputText = `[Line ${startLineDisplay} is ${formatBytes(
-					firstLineBytes,
-				)}, exceeds ${formatBytes(DEFAULT_MAX_BYTES)} limit. Unable to display a valid UTF-8 snippet.]`;
-			}
-			details.truncation = truncation;
-			truncationInfo = {
-				result: truncation,
-				options: { direction: "head", startLine: startLineDisplay, totalFileLines: totalLines },
-			};
-		} else if (truncation.truncated) {
-			outputText = truncation.content;
-			details.truncation = truncation;
-			truncationInfo = {
-				result: truncation,
-				options: { direction: "head", startLine: startLineDisplay, totalFileLines: totalLines },
-			};
-		} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
-			const remaining = allLines.length - (startLine + userLimitedLines);
-			const nextOffset = startLine + userLimitedLines + 1;
-
-			outputText = truncation.content;
-			outputText += `\n\n[${remaining} more lines in resource. Use offset=${nextOffset} to continue]`;
-			details.truncation = truncation;
-		} else {
-			outputText = truncation.content;
-		}
-
-		const resultBuilder = toolResult(details).text(outputText).sourceInternal(url);
-		if (truncationInfo) {
-			resultBuilder.truncation(truncationInfo.result, truncationInfo.options);
-		}
-		return resultBuilder.done();
+		return this.#buildInMemoryTextResult(resource.content, offset, limit, {
+			details,
+			sourcePath: resource.sourcePath,
+			sourceInternal: url,
+			entityLabel: "resource",
+			ignoreResultLimits: scheme === "skill",
+		});
 	}
 
 	/** Read directory contents as a formatted listing */
@@ -1166,9 +1229,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 interface ReadRenderArgs {
 	path?: string;
 	file_path?: string;
+	sel?: string;
+	timeout?: number;
+	// Legacy fields from old schema — tolerated for in-flight tool calls during transition
 	offset?: number;
 	limit?: number;
-	timeout?: number;
 	raw?: boolean;
 }
 

package/src/tools/render-mermaid.ts

@@ -1,7 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import { type MermaidAsciiRenderOptions, renderMermaidAscii } from "@oh-my-pi/pi-utils";
+import { type MermaidAsciiRenderOptions, prompt, renderMermaidAscii } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { renderPromptTemplate } from "../config/prompt-templates";
 import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with { type: "text" };
 import type { ToolSession } from "./index";
 
@@ -41,7 +40,7 @@ export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema,
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {
-		this.description = renderPromptTemplate(renderMermaidDescription);
+		this.description = prompt.render(renderMermaidDescription);
 	}
 
 	async execute(

package/src/tools/render-utils.ts

@@ -5,17 +5,17 @@
  * tool renderers to ensure a unified TUI experience.
  */
 import * as os from "node:os";
-import { type Ellipsis, truncateToWidth } from "@oh-my-pi/pi-tui";
-import { getIndentation, pluralize } from "@oh-my-pi/pi-utils";
+import * as path from "node:path";
+import type { Ellipsis } from "@oh-my-pi/pi-natives";
+import { replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+import { pluralize } from "@oh-my-pi/pi-utils";
 import { settings } from "../config/settings";
 import type { Theme } from "../modes/theme/theme";
 import { formatDimensionNote, type ResizedImage } from "../utils/image-resize";
 
-export { Ellipsis, truncateToWidth } from "@oh-my-pi/pi-tui";
+export { Ellipsis } from "@oh-my-pi/pi-natives";
+export { replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
 
-export function replaceTabs(text: string, file?: string): string {
-	return text.replaceAll("\t", getIndentation(file));
-}
 // =============================================================================
 // Standardized Display Constants
 // =============================================================================
@@ -548,6 +548,20 @@ export function shortenPath(filePath: string, homeDir?: string): string {
 	return filePath;
 }
 
+export function formatToolWorkingDirectory(workdir: string | undefined, projectDir: string): string | undefined {
+	if (!workdir) return undefined;
+	const resolvedProjectDir = path.resolve(projectDir);
+	const resolvedWorkdir = path.resolve(projectDir, workdir);
+	if (resolvedWorkdir === resolvedProjectDir) {
+		return undefined;
+	}
+	const relativePath = path.relative(resolvedProjectDir, resolvedWorkdir);
+	const isWithinProject =
+		relativePath.length > 0 && !relativePath.startsWith("..") && !relativePath.startsWith(`..${path.sep}`);
+	const displayWorkdir = isWithinProject ? relativePath : shortenPath(resolvedWorkdir);
+	return replaceTabs(displayWorkdir);
+}
+
 export function formatScreenshot(opts: {
 	saveFullRes: boolean;
 	savedMimeType: string;

package/src/tools/renderers.ts

@@ -4,10 +4,10 @@
  * These provide rich visualization for tool calls and results in the TUI.
  */
 import type { Component } from "@oh-my-pi/pi-tui";
+import { editToolRenderer } from "../edit/renderer";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { lspToolRenderer } from "../lsp/render";
 import type { Theme } from "../modes/theme/theme";
-import { editToolRenderer } from "../patch";
 import { taskToolRenderer } from "../task/render";
 import { webSearchToolRenderer } from "../web/search/render";
 import { askToolRenderer } from "./ask";
@@ -15,6 +15,7 @@ import { astEditToolRenderer } from "./ast-edit";
 import { astGrepToolRenderer } from "./ast-grep";
 import { bashToolRenderer } from "./bash";
 import { calculatorToolRenderer } from "./calculator";
+import { debugToolRenderer } from "./debug";
 import { findToolRenderer } from "./find";
 import { ghRunWatchToolRenderer } from "./gh-renderer";
 import { grepToolRenderer } from "./grep";
@@ -46,6 +47,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	ast_grep: astGrepToolRenderer as ToolRenderer,
 	ast_edit: astEditToolRenderer as ToolRenderer,
 	bash: bashToolRenderer as ToolRenderer,
+	debug: debugToolRenderer as ToolRenderer,
 	python: pythonToolRenderer as ToolRenderer,
 	calc: calculatorToolRenderer as ToolRenderer,
 	edit: editToolRenderer as ToolRenderer,