@oh-my-pi/pi-coding-agent 15.3.2 → 15.4.2

package/src/tools/read.ts

@@ -9,9 +9,10 @@ import { Text } from "@oh-my-pi/pi-tui";
 import { getRemoteDir, logger, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import { getFileReadCache } from "../edit/file-read-cache";
+import { normalizeToLF } from "../edit/normalize";
 import { isNotebookPath, readEditableNotebookText } from "../edit/notebook";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
-import { formatHashLine, formatHashLines, formatLineHash, HL_BODY_SEP } from "../hashline/hash";
+import { computeFileHash, formatHashlineHeader, formatNumberedLine, formatNumberedLines } from "../hashline/hash";
 import { InternalUrlRouter } from "../internal-urls";
 import { parseInternalUrl } from "../internal-urls/parse";
 import type { InternalUrl } from "../internal-urls/types";
@@ -113,13 +114,50 @@ function prependLineNumbers(text: string, startNum: number): string {
 	return textLines.map((line, i) => `${startNum + i}|${line}`).join("\n");
 }
 
+interface HashlineHeaderContext {
+	header: string;
+	fileHash: string;
+	fullText: string;
+}
+
+function buildHashlineHeaderContext(displayPath: string, fullText: string): HashlineHeaderContext {
+	const normalized = normalizeToLF(fullText);
+	const fileHash = computeFileHash(normalized);
+	return {
+		header: formatHashlineHeader(displayPath, fileHash),
+		fileHash,
+		fullText: normalized,
+	};
+}
+
+async function readHashlineHeaderContext(absolutePath: string, cwd: string): Promise<HashlineHeaderContext> {
+	const fullText = await Bun.file(absolutePath).text();
+	return buildHashlineHeaderContext(formatPathRelativeToCwd(absolutePath, cwd), fullText);
+}
+
+function prependHashlineHeader(text: string, context: HashlineHeaderContext | undefined): string {
+	return context ? `${context.header}\n${text}` : text;
+}
+
+function recordHashlineSnapshot(
+	session: ToolSession,
+	absolutePath: string | undefined,
+	context: HashlineHeaderContext | undefined,
+): void {
+	if (!context || !absolutePath || !path.isAbsolute(absolutePath)) return;
+	getFileReadCache(session).recordContiguous(absolutePath, 1, context.fullText.split("\n"), {
+		fullText: context.fullText,
+		fileHash: context.fileHash,
+	});
+}
+
 function formatTextWithMode(
 	text: string,
 	startNum: number,
 	shouldAddHashLines: boolean,
 	shouldAddLineNumbers: boolean,
 ): string {
-	if (shouldAddHashLines) return formatHashLines(text, startNum);
+	if (shouldAddHashLines) return formatNumberedLines(text, startNum);
 	if (shouldAddLineNumbers) return prependLineNumbers(text, startNum);
 	return text;
 }
@@ -150,7 +188,7 @@ function formatSingleLine(
 	shouldAddHashLines: boolean,
 	shouldAddLineNumbers: boolean,
 ): string {
-	if (shouldAddHashLines) return formatHashLine(line, text);
+	if (shouldAddHashLines) return formatNumberedLine(line, text);
 	if (shouldAddLineNumbers) return `${line}|${text}`;
 	return text;
 }
@@ -165,9 +203,7 @@ function formatMergedBraceLine(
 ): { model: string; display: string } {
 	const merged = `${headText.trimEnd()} .. ${tailText.trim()}`;
 	if (shouldAddHashLines) {
-		const start = formatLineHash(startLine, headText);
-		const end = formatLineHash(endLine, tailText);
-		return { model: `${start}-${end}${HL_BODY_SEP}${merged}`, display: merged };
+		return { model: `${startLine}-${endLine}:${merged}`, display: merged };
 	}
 	if (shouldAddLineNumbers) {
 		return { model: `${startLine}-${endLine}|${merged}`, display: merged };
@@ -180,17 +216,38 @@ function countTextLines(text: string): number {
 	return text.split("\n").length;
 }
 
+/** Inclusive line range describing one elided span in a structural summary. */
+interface ElidedRange {
+	start: number;
+	end: number;
+}
+
+/** Sample ranges shown in the footer to demonstrate the multi-range syntax. */
+const FOOTER_RANGE_SAMPLES = 2;
+
 /**
  * Footer appended to summarized reads telling the model how to recover the
  * elided body. Without this hint, agents either ignore the `...`/`{ .. }`
- * markers or burn a turn guessing the right selector (see issue #1046).
+ * markers or burn a turn guessing the right selector (see issue #1046). The
+ * footer demonstrates the multi-range selector syntax with concrete sample
+ * ranges drawn from the actual elision so the model re-reads only what it
+ * needs instead of falling back to `:raw` or whole-file reads.
  */
-function formatSummaryElisionFooter(readPath: string, elidedSpans: number, elidedLines: number): string {
-	if (elidedSpans <= 0) return "";
-	const spanWord = elidedSpans === 1 ? "region" : "regions";
+function formatSummaryElisionFooter(
+	readPath: string,
+	elidedRanges: ReadonlyArray<ElidedRange>,
+	elidedLines: number,
+): string {
+	if (elidedRanges.length === 0) return "";
 	const lineWord = elidedLines === 1 ? "line" : "lines";
-	const linePart = elidedLines > 0 ? `${elidedLines} ${lineWord} across ` : "";
-	return `[${linePart}${elidedSpans} elided ${spanWord}; read ${readPath}:raw or a line range like ${readPath}:1-9999 for verbatim content]`;
+	const sampleCount = Math.min(elidedRanges.length, FOOTER_RANGE_SAMPLES);
+	const selector = elidedRanges
+		.slice(0, sampleCount)
+		.map(r => `${r.start}-${r.end}`)
+		.join(",");
+	const example = `${readPath}:${selector}`;
+	const tail = elidedRanges.length > sampleCount ? `, e.g. ${example}` : ` with ${example}`;
+	return `[${elidedLines} ${lineWord} elided; re-read needed ranges${tail}]`;
 }
 const READ_CHUNK_SIZE = 8 * 1024;
 
@@ -844,9 +901,18 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
+		const hashContext =
+			shouldAddHashLines && options.sourcePath
+				? buildHashlineHeaderContext(formatPathRelativeToCwd(options.sourcePath, this.session.cwd), text)
+				: undefined;
+		recordHashlineSnapshot(this.session, options.sourcePath, hashContext);
+		let emittedHashlineHeader = false;
 		const formatText = (content: string, startNum: number): string => {
 			details.displayContent = { text: content, startLine: startNum };
-			return formatTextWithMode(content, startNum, shouldAddHashLines, shouldAddLineNumbers);
+			const formatted = formatTextWithMode(content, startNum, shouldAddHashLines, shouldAddLineNumbers);
+			if (!hashContext || emittedHashlineHeader) return formatted;
+			emittedHashlineHeader = true;
+			return prependHashlineHeader(formatted, hashContext);
 		};
 
 		let outputText: string;
@@ -862,7 +928,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (shouldAddHashLines) {
 				outputText = `[Line ${startLineDisplay} is ${formatBytes(
 					firstLineBytes,
-				)}, exceeds ${formatBytes(DEFAULT_MAX_BYTES)} limit. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`;
+				)}, exceeds ${formatBytes(DEFAULT_MAX_BYTES)} limit. Hashline output requires full lines; cannot emit an editable numbered preview for a truncated line.]`;
 			} else {
 				outputText = formatText(snippet.text, startLineDisplay);
 			}
@@ -928,6 +994,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const totalLines = allLines.length;
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
+		const hashContext =
+			shouldAddHashLines && options.sourcePath
+				? buildHashlineHeaderContext(formatPathRelativeToCwd(options.sourcePath, this.session.cwd), text)
+				: undefined;
+		recordHashlineSnapshot(this.session, options.sourcePath, hashContext);
+		let emittedHashlineHeader = false;
 
 		const resultBuilder = toolResult(details);
 		if (options.sourcePath) resultBuilder.sourcePath(options.sourcePath);
@@ -943,7 +1015,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 			const effectiveEnd = Math.min(range.endLine ?? totalLines, totalLines);
 			const sliced = allLines.slice(range.startLine - 1, effectiveEnd).join("\n");
-			parts.push(formatTextWithMode(sliced, range.startLine, shouldAddHashLines, shouldAddLineNumbers));
+			const formatted = formatTextWithMode(sliced, range.startLine, shouldAddHashLines, shouldAddLineNumbers);
+			parts.push(hashContext && !emittedHashlineHeader ? prependHashlineHeader(formatted, hashContext) : formatted);
+			if (hashContext) emittedHashlineHeader = true;
 		}
 
 		const outputText = parts.length > 0 ? parts.join("\n\n…\n\n") : "";
@@ -1002,6 +1076,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const shouldAddHashLines = !rawSelector && displayMode.hashLines;
 		const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
+		const hashContext = shouldAddHashLines
+			? await readHashlineHeaderContext(absolutePath, this.session.cwd)
+			: undefined;
+		recordHashlineSnapshot(this.session, absolutePath, hashContext);
+		let emittedHashlineHeader = false;
 		const maxColumns = resolveOutputMaxColumns(this.session.settings);
 
 		const blocks: string[] = [];
@@ -1042,11 +1121,18 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 
 			if (collectedLines.length > 0) {
-				getFileReadCache(this.session).recordContiguous(absolutePath, range.startLine, collectedLines);
+				getFileReadCache(this.session).recordContiguous(
+					absolutePath,
+					range.startLine,
+					collectedLines,
+					hashContext ? { fullText: hashContext.fullText, fileHash: hashContext.fileHash } : {},
+				);
 			}
 
 			const blockText = collectedLines.join("\n");
-			blocks.push(formatTextWithMode(blockText, range.startLine, shouldAddHashLines, shouldAddLineNumbers));
+			const formatted = formatTextWithMode(blockText, range.startLine, shouldAddHashLines, shouldAddLineNumbers);
+			blocks.push(hashContext && !emittedHashlineHeader ? prependHashlineHeader(formatted, hashContext) : formatted);
+			if (hashContext) emittedHashlineHeader = true;
 		}
 
 		let outputText = blocks.join("\n\n…\n\n");
@@ -1335,7 +1421,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	#renderSummary(summary: SummaryResult): {
 		text: string;
 		displayText: string;
-		elidedSpans: number;
+		elidedRanges: ElidedRange[];
 		elidedLines: number;
 	} {
 		const displayMode = resolveFileDisplayMode(this.session);
@@ -1396,13 +1482,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const modelParts: string[] = [];
 		const displayParts: string[] = [];
-		let elidedSpans = 0;
+		const elidedRanges: ElidedRange[] = [];
 		let elidedLines = 0;
 		for (const unit of units) {
 			if (unit.kind === "elided") {
 				modelParts.push("...");
 				displayParts.push("...");
-				elidedSpans++;
+				elidedRanges.push({ start: unit.startLine, end: unit.endLine });
 				elidedLines += unit.endLine - unit.startLine + 1;
 				continue;
 			}
@@ -1417,7 +1503,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				);
 				modelParts.push(formatted.model);
 				displayParts.push(formatted.display);
-				elidedSpans++;
+				// Suggest the full brace range so re-reading shows both braces
+				// plus the elided body in one shot.
+				elidedRanges.push({ start: unit.startLine, end: unit.endLine });
 				// Merged brace pair encloses (start+1)..(end-1) as elided.
 				elidedLines += Math.max(0, unit.endLine - unit.startLine - 1);
 				continue;
@@ -1426,7 +1514,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			displayParts.push(unit.text);
 		}
 
-		return { text: modelParts.join("\n"), displayText: displayParts.join("\n"), elidedSpans, elidedLines };
+		return { text: modelParts.join("\n"), displayText: displayParts.join("\n"), elidedRanges, elidedLines };
 	}
 
 	async execute(
@@ -1674,15 +1762,20 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					const renderedSummary = this.#renderSummary(summary);
 					const footer = formatSummaryElisionFooter(
 						localReadPath,
-						renderedSummary.elidedSpans,
+						renderedSummary.elidedRanges,
 						renderedSummary.elidedLines,
 					);
-					const modelText = footer ? `${renderedSummary.text}\n\n${footer}` : renderedSummary.text;
+					const summaryHashContext = displayMode.hashLines
+						? await readHashlineHeaderContext(absolutePath, this.session.cwd)
+						: undefined;
+					recordHashlineSnapshot(this.session, absolutePath, summaryHashContext);
+					const bodyText = footer ? `${renderedSummary.text}\n\n${footer}` : renderedSummary.text;
+					const modelText = prependHashlineHeader(bodyText, summaryHashContext);
 					details = {
 						displayContent: { text: renderedSummary.displayText, startLine: 1 },
 						summary: {
 							lines: countTextLines(renderedSummary.text),
-							elidedSpans: renderedSummary.elidedSpans,
+							elidedSpans: renderedSummary.elidedRanges.length,
 							elidedLines: renderedSummary.elidedLines,
 						},
 					};
@@ -1820,16 +1913,29 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						firstLineExceedsLimit,
 					};
 
+					const shouldAddHashLines = !rawSelector && displayMode.hashLines;
+					const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
+					const hashContext = shouldAddHashLines
+						? await readHashlineHeaderContext(absolutePath, this.session.cwd)
+						: undefined;
+
 					if (collectedLines.length > 0 && !firstLineExceedsLimit) {
-						getFileReadCache(this.session).recordContiguous(absolutePath, startLineDisplay, collectedLines);
+						getFileReadCache(this.session).recordContiguous(
+							absolutePath,
+							startLineDisplay,
+							collectedLines,
+							hashContext ? { fullText: hashContext.fullText, fileHash: hashContext.fileHash } : {},
+						);
 					}
 
-					const shouldAddHashLines = !rawSelector && displayMode.hashLines;
-					const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
 					let capturedDisplayContent: { text: string; startLine: number } | undefined;
+					let emittedHashlineHeader = false;
 					const formatText = (text: string, startNum: number): string => {
 						capturedDisplayContent = { text, startLine: startNum };
-						return formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
+						const formatted = formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
+						if (!hashContext || emittedHashlineHeader) return formatted;
+						emittedHashlineHeader = true;
+						return prependHashlineHeader(formatted, hashContext);
 					};
 
 					let outputText: string;
@@ -1841,7 +1947,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						if (shouldAddHashLines) {
 							outputText = `[Line ${startLineDisplay} is ${formatBytes(
 								firstLineBytes,
-							)}, exceeds ${formatBytes(maxBytesForRead)} limit. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`;
+							)}, exceeds ${formatBytes(maxBytesForRead)} limit. Hashline output requires full lines; cannot emit an editable numbered preview for a truncated line.]`;
 						} else {
 							outputText = formatText(snippet.text, startLineDisplay);
 						}
@@ -1964,7 +2070,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
 
 		const rawText = region.lines.join("\n");
-		const formattedText = formatTextWithMode(rawText, region.startLine, shouldAddHashLines, shouldAddLineNumbers);
+		const hashContext = shouldAddHashLines
+			? await readHashlineHeaderContext(entry.absolutePath, this.session.cwd)
+			: undefined;
+		recordHashlineSnapshot(this.session, entry.absolutePath, hashContext);
+		const formattedBody = formatTextWithMode(rawText, region.startLine, shouldAddHashLines, shouldAddLineNumbers);
+		const formattedText = prependHashlineHeader(formattedBody, hashContext);
 
 		const details: ReadToolDetails = {
 			resolvedPath: entry.absolutePath,

package/src/tools/review.ts

@@ -15,6 +15,7 @@ import { isRecord } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import type { Theme, ThemeColor } from "../modes/theme/theme";
 import { subprocessToolRegistry } from "../task/subprocess-tool-registry";
+import type { ReviewFinding } from "../task/types";
 export type FindingPriority = "P0" | "P1" | "P2" | "P3";
 
 export interface FindingPriorityInfo {
@@ -186,6 +187,28 @@ export interface SubmitReviewDetails {
 
 // Re-export types for external use
 export type { ReportFindingDetails };
+/**
+ * Coerce a tool-side `ReportFindingDetails` into the cross-boundary
+ * `ReviewFinding` shape consumed by the reviewer agent's JTD output schema.
+ *
+ * The `report_finding` tool exposes `priority` as a string enum (`"P0".."P3"`)
+ * for ergonomics, but the bundled reviewer schema (and every custom review
+ * agent that mirrors it) declares `priority: number`. Without this coercion
+ * the auto-populated `findings[]` fails JTD validation and every review run
+ * that surfaces a finding is rejected with `findings.0.priority: expected
+ * number, received string`.
+ */
+export function toReviewFinding(details: ReportFindingDetails): ReviewFinding {
+	return {
+		title: details.title,
+		body: details.body,
+		priority: getPriorityInfo(details.priority).ord,
+		confidence: details.confidence,
+		file_path: details.file_path,
+		line_start: details.line_start,
+		line_end: details.line_end,
+	};
+}
 
 // Register report_finding handler
 subprocessToolRegistry.register<ReportFindingDetails>("report_finding", {

package/src/tools/search-tool-bm25.ts

@@ -19,12 +19,6 @@ import type { ToolSession } from ".";
 import { formatCount, replaceTabs, TRUNCATE_LENGTHS } from "./render-utils";
 import { ToolError } from "./tool-errors";
 
-// Re-export legacy MCP types for back-compat (tests and external callers may reference them)
-export type {
-	DiscoverableMCPSearchIndex,
-	DiscoverableMCPTool,
-} from "../mcp/discoverable-tool-metadata";
-
 const DEFAULT_LIMIT = 8;
 const TOOL_DISCOVERY_TITLE = "Tool Discovery";
 const COLLAPSED_MATCH_LIMIT = 5;
@@ -81,21 +75,7 @@ function buildSearchToolBm25Content(details: SearchToolBm25Details): string {
 /** Get discoverable tools for description rendering. Falls back to empty array on error. */
 function getDiscoverableToolsForDescription(session: ToolSession): DiscoverableTool[] {
 	try {
-		// Prefer generic method; fall back to legacy MCP-only
-		if (session.getDiscoverableTools) {
-			return session.getDiscoverableTools();
-		}
-		// Legacy MCP path — adapt DiscoverableMCPTool (with `description`) → DiscoverableTool.
-		const legacy = session.getDiscoverableMCPTools?.() ?? [];
-		return legacy.map(t => ({
-			name: t.name,
-			label: t.label,
-			summary: t.description,
-			source: "mcp" as const,
-			serverName: t.serverName,
-			mcpToolName: t.mcpToolName,
-			schemaKeys: t.schemaKeys,
-		}));
+		return session.getDiscoverableTools?.() ?? [];
 	} catch {
 		return [];
 	}
@@ -103,15 +83,8 @@ function getDiscoverableToolsForDescription(session: ToolSession): DiscoverableT
 
 function getDiscoverableToolSearchIndexForExecution(session: ToolSession): DiscoverableToolSearchIndex {
 	try {
-		// Prefer generic cached index
-		if (session.getDiscoverableToolSearchIndex) {
-			const cached = session.getDiscoverableToolSearchIndex();
-			if (cached) return cached;
-		}
-		// Legacy MCP: use cached MCP index. Its documents expose `tool.description` as well as
-		// `tool.summary`, so it is structurally compatible with DiscoverableToolSearchIndex.
-		const mcpCached = session.getDiscoverableMCPSearchIndex?.();
-		if (mcpCached) return mcpCached as unknown as DiscoverableToolSearchIndex;
+		const cached = session.getDiscoverableToolSearchIndex?.();
+		if (cached) return cached;
 	} catch {}
 	return buildDiscoverableToolSearchIndex(getDiscoverableToolsForDescription(session));
 }

package/src/tools/search.ts

@@ -9,6 +9,7 @@ import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import { getFileReadCache } from "../edit/file-read-cache";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { computeFileHash, formatHashlineHeader } from "../hashline/hash";
 import type { Theme } from "../modes/theme/theme";
 import searchDescription from "../prompts/tools/search.md" with { type: "text" };
 import { DEFAULT_MAX_COLUMN, type TruncationResult, truncateHead } from "../session/streaming-output";
@@ -38,13 +39,13 @@ import {
 import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
+const searchPathEntrySchema = z.string().describe("file, directory, glob, or internal URL to search");
 const searchSchema = z
 	.object({
 		pattern: z.string().describe("regex pattern"),
 		paths: z
-			.array(z.string().describe("file, directory, glob, or internal URL to search"))
-			.min(1)
-			.describe("files, directories, globs, or internal URLs to search"),
+			.union([searchPathEntrySchema, z.array(searchPathEntrySchema).min(1)])
+			.describe("file, directory, glob, internal URL, or array of those to search"),
 		i: z.boolean().optional().describe("case-insensitive search"),
 		gitignore: z.boolean().optional().describe("respect gitignore"),
 		skip: z
@@ -55,6 +56,9 @@ const searchSchema = z
 	.strict();
 
 export type SearchToolInput = z.infer<typeof searchSchema>;
+export function toPathList(input: string | string[] | undefined): string[] {
+	return typeof input === "string" ? [input] : (input ?? []);
+}
 
 /** Maximum number of distinct files surfaced in a single response. The
  * agent paginates further pages via `skip`. */
@@ -236,7 +240,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 		_onUpdate?: AgentToolUpdateCallback<SearchToolDetails>,
 		_toolContext?: AgentToolContext,
 	): Promise<AgentToolResult<SearchToolDetails>> {
-		const { pattern, paths, i, gitignore, skip } = params;
+		const { pattern, paths: rawPaths, i, gitignore, skip } = params;
 
 		return untilAborted(signal, async () => {
 			const normalizedPattern = pattern.trim();
@@ -248,6 +252,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 			if (normalizedSkip < 0 || !Number.isFinite(normalizedSkip)) {
 				throw new ToolError("Skip must be a non-negative number");
 			}
+			const paths = toPathList(rawPaths);
 			for (const entry of paths) {
 				if (containsTopLevelComma(entry)) {
 					throw new ToolError('paths is an array — pass ["a", "b"] not ["a,b"]');
@@ -303,7 +308,6 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				}
 				const { globFilter } = scope;
 				const baseDisplayMode = resolveFileDisplayMode(this.session);
-				const immutableDisplayMode = resolveFileDisplayMode(this.session, { immutable: true });
 
 				const effectiveOutputMode = GrepOutputMode.Content;
 				// Multi-scope = more than one file may match. We fetch up to
@@ -485,14 +489,27 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 					matchesByFile.get(relativePath)!.push(match);
 				}
 				const displayLines: string[] = [];
+				const hashContexts = new Map<string, { absolutePath: string; fileHash: string }>();
+				if (baseDisplayMode.hashLines) {
+					for (const relativePath of fileList) {
+						if (archiveDisplaySet.has(relativePath)) continue;
+						const absoluteFilePath = path.resolve(this.session.cwd, relativePath);
+						if (immutableSourcePaths.has(absoluteFilePath)) continue;
+						try {
+							const fullText = await Bun.file(absoluteFilePath).text();
+							const fileHash = computeFileHash(fullText);
+							hashContexts.set(relativePath, { absolutePath: absoluteFilePath, fileHash });
+						} catch {
+							// Best-effort: if the file disappeared between grep and render, fall back to plain line output.
+						}
+					}
+				}
 				const renderMatchesForFile = (relativePath: string): { model: string[]; display: string[] } => {
 					const modelOut: string[] = [];
 					const displayOut: string[] = [];
 					const fileMatches = matchesByFile.get(relativePath) ?? [];
-					const absoluteFilePath = path.resolve(this.session.cwd, relativePath);
-					const useHashLines = immutableSourcePaths.has(absoluteFilePath)
-						? immutableDisplayMode.hashLines
-						: baseDisplayMode.hashLines;
+					const hashContext = hashContexts.get(relativePath);
+					const useHashLines = hashContext !== undefined;
 					const lineNumberWidth = fileMatches.reduce((width, match) => {
 						let nextWidth = Math.max(width, String(match.lineNumber).length);
 						for (const ctx of match.contextBefore ?? []) {
@@ -533,17 +550,21 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 						}
 						fileMatchCounts.set(relativePath, (fileMatchCounts.get(relativePath) ?? 0) + 1);
 					}
-					if (cacheEntries.length > 0 && !archiveDisplaySet.has(relativePath)) {
-						getFileReadCache(this.session).recordSparse(path.resolve(searchPath, relativePath), cacheEntries);
+					if (cacheEntries.length > 0 && hashContext) {
+						getFileReadCache(this.session).recordSparse(hashContext.absolutePath, cacheEntries, {
+							fileHash: hashContext.fileHash,
+						});
 					}
 					return { model: modelOut, display: displayOut };
 				};
 				if (isDirectory) {
 					const grouped = formatGroupedFiles(fileList, relativePath => {
 						const rendered = renderMatchesForFile(relativePath);
+						const hashContext = hashContexts.get(relativePath);
 						return {
 							modelLines: rendered.model,
 							displayLines: rendered.display,
+							headerSuffix: hashContext ? `#${hashContext.fileHash}` : "",
 							skip: rendered.model.length === 0,
 						};
 					});
@@ -552,6 +573,15 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				} else {
 					for (const relativePath of fileList) {
 						const rendered = renderMatchesForFile(relativePath);
+						if (rendered.model.length === 0) continue;
+						if (outputLines.length > 0) {
+							outputLines.push("");
+							displayLines.push("");
+						}
+						const hashContext = hashContexts.get(relativePath);
+						if (hashContext) {
+							outputLines.push(formatHashlineHeader(relativePath, hashContext.fileHash));
+						}
 						outputLines.push(...rendered.model);
 						displayLines.push(...rendered.display);
 					}
@@ -607,7 +637,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 
 interface SearchRenderArgs {
 	pattern: string;
-	paths?: string[];
+	paths?: string | string[];
 	i?: boolean;
 	gitignore?: boolean;
 	skip?: number;
@@ -618,8 +648,9 @@ const COLLAPSED_TEXT_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
 export const searchToolRenderer = {
 	inline: true,
 	renderCall(args: SearchRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const paths = toPathList(args.paths);
 		const meta: string[] = [];
-		if (args.paths?.length) meta.push(`in ${args.paths.join(", ")}`);
+		if (paths.length) meta.push(`in ${paths.join(", ")}`);
 		if (args.i) meta.push("case:insensitive");
 		if (args.gitignore === false) meta.push("gitignore:false");
 		if (args.skip !== undefined && args.skip > 0) meta.push(`skip:${args.skip}`);
@@ -745,11 +776,12 @@ export const searchToolRenderer = {
 							let contextDir = searchBase ?? "";
 							return group.map(line => {
 								if (line.startsWith("## ")) {
-									// Strip optional ` (suffix)` like ` (3 replacements)` before resolving.
+									// Strip optional ` (suffix)` and `#hash` before resolving.
 									const fileName = line
 										.slice(3)
 										.trimEnd()
-										.replace(/\s+\([^)]*\)\s*$/, "");
+										.replace(/\s+\([^)]*\)\s*$/, "")
+										.replace(/#[0-9a-f]+$/, "");
 									const absPath = contextDir && fileName ? path.join(contextDir, fileName) : undefined;
 									const styled = uiTheme.fg("dim", line);
 									return absPath ? fileHyperlink(absPath, styled) : styled;
@@ -760,7 +792,7 @@ export const searchToolRenderer = {
 										.trimEnd()
 										.replace(/\s+\([^)]*\)\s*$/, "");
 									const isDirectory = raw.endsWith("/");
-									const name = raw.replace(/\/$/, "");
+									const name = isDirectory ? raw.replace(/\/$/, "") : raw.replace(/#[0-9a-f]+$/, "");
 									if (isDirectory) {
 										if (searchBase) {
 											contextDir = name === "." ? searchBase : path.join(searchBase, name);

package/src/tools/write.ts

@@ -74,8 +74,8 @@ export interface WriteToolDetails {
 /**
  * Strip hashline display prefixes from write content.
  *
- * Only active when hashline edit mode is enabled — the model sees `LINE+ID|`
- * prefixes in read output and sometimes copies them into write content.
+ * Only active when hashline edit mode is enabled — the model sees `¶PATH#HASH`
+ * headers plus `LINE:` prefixes in read output and sometimes copies them into write content.
  */
 function stripWriteContent(session: ToolSession, content: string): { text: string; stripped: boolean } {
 	if (!resolveFileDisplayMode(session).hashLines) {
@@ -658,7 +658,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		context?: AgentToolContext,
 	): Promise<AgentToolResult<WriteToolDetails>> {
 		return untilAborted(signal, async () => {
-			// Strip hashline display prefixes (LINE+ID|) if the model copied them from read output
+			// Strip hashline display prefixes (¶PATH#HASH + LINE:) if the model copied them from read output
 			const { text: cleanContent, stripped } = stripWriteContent(this.session, content);
 			const internalRouter = InternalUrlRouter.instance();
 			if (internalRouter.canHandle(path)) {