@khanhicetea/pi-better-tool 0.1.0 → 0.2.2

package/src/diagnostics.ts

@@ -8,7 +8,7 @@
  *   prefix/suffix context expansion that makes that occurrence unique,
  *   rendered as a ready-to-use oldText snippet
  * - not-found oldText  → the closest matching region (fuzzy line similarity),
- *   a per-line comparison, and the exact file bytes to retry with
+ *   an original-text comparison, and exact LF-normalized retry text when safe
  */
 
 import type { EditFailure, EditOp, LineRange } from "./apply.ts";
@@ -16,9 +16,11 @@ import { normalizeEdits } from "./apply.ts";
 import { findClosestRegion, lineSimilarity, probeMatchCauses } from "./similarity.ts";
 import {
 	countFuzzyOccurrences,
+	findAllOccurrences,
 	getLineSpans,
 	lineAt,
 	normalizeForFuzzyMatch,
+	normalizeToLF,
 	type LineSpan,
 } from "./text.ts";
 
@@ -30,8 +32,16 @@ const MAX_TOTAL_CONTEXT_LINES = 12;
 const MAX_LISTED_OCCURRENCES = 8;
 /** Occurrences that get a ready-to-use disambiguation snippet. */
 const MAX_SNIPPET_OCCURRENCES = 3;
-/** Max lines shown inside a snippet. */
+/** Max lines/bytes shown inside a copyable snippet. */
 const MAX_SNIPPET_LINES = 60;
+const MAX_SNIPPET_BYTES = 12 * 1024;
+/** Hard model-context bound for the complete tool error. */
+const MAX_OUTPUT_LINES = 1_500;
+const MAX_OUTPUT_BYTES = 48 * 1024;
+/** Minimum score at which a unique closest region may be suggested directly. */
+const MIN_DIRECT_RETRY_SCORE = 0.75;
+/** Required separation from a distinct runner-up before direct-retry wording. */
+const MIN_DIRECT_RETRY_GAP = 0.1;
 /** Max non-equal alignment ops rendered. */
 const MAX_DIFF_OPS_SHOWN = 12;
 
@@ -46,6 +56,13 @@ export interface Expansion {
 	endLine: number;
 }
 
+export interface AutoDisambiguation {
+	editIndex: number;
+	oldText: string;
+	chosenRange: LineRange;
+	readRange: LineRange;
+}
+
 export interface FormatFailureOptions {
 	path: string;
 	/** LF-normalized, BOM-stripped file content. */
@@ -55,7 +72,72 @@ export interface FormatFailureOptions {
 	failure: EditFailure;
 }
 
+const MAX_SUCCESS_RESOLUTIONS = 4;
+const MAX_REMAINING_OCCURRENCES = 4;
+const MAX_SUCCESS_SNIPPET_BYTES = 2_500;
+
+/** Add verified read-based selections and retryable remaining candidates to a successful edit result. */
+export function formatAutoDisambiguationSuccess(
+	baseMessage: string,
+	newContent: string,
+	resolutions: AutoDisambiguation[],
+): string {
+	if (resolutions.length === 0) return boundCompleteOutput(baseMessage);
+	const lines = [baseMessage, ""];
+	const shownResolutions = resolutions.slice(0, MAX_SUCCESS_RESOLUTIONS);
+	if (newContent.length > MAX_CONTENT_FOR_DIAGNOSTICS) {
+		for (const resolution of shownResolutions) {
+			lines.push(
+				`Auto-disambiguated edits[${resolution.editIndex}] to ${describeLines(resolution.chosenRange.start, resolution.chosenRange.end)} because it was the only occurrence fully contained in the latest verified read of ${describeLines(resolution.readRange.start, resolution.readRange.end)}.`,
+			);
+		}
+		lines.push("Remaining-occurrence snippets were omitted because the edited file exceeds the diagnostic analysis limit.");
+		return boundCompleteOutput(lines.join("\n"));
+	}
+
+	for (const resolution of shownResolutions) {
+		lines.push(
+			`Auto-disambiguated edits[${resolution.editIndex}] to ${describeLines(resolution.chosenRange.start, resolution.chosenRange.end)} because it was the only occurrence fully contained in the latest verified read of ${describeLines(resolution.readRange.start, resolution.readRange.end)}.`,
+		);
+		const oldText = normalizeToLF(resolution.oldText);
+		const remainingCount = countLiteralOccurrences(newContent, oldText);
+		const offsets = findAllOccurrences(newContent, oldText, MAX_REMAINING_OCCURRENCES);
+		if (remainingCount === 0) {
+			lines.push("No exact occurrences of the original oldText remain after this edit.", "");
+			continue;
+		}
+
+		lines.push(`Remaining exact occurrences of the original oldText (${offsets.length} shown${remainingCount > offsets.length ? `, ${remainingCount - offsets.length} more omitted` : ""}):`);
+		const fuzzyContent = normalizeForFuzzyMatch(newContent);
+		const spans = getLineSpans(newContent);
+		for (const [index, offset] of offsets.slice(0, MAX_REMAINING_OCCURRENCES).entries()) {
+			const range = rangeFromOffset(spans, offset, oldText.length);
+			const expansion = findMinimalUniqueExpansion(newContent, fuzzyContent, spans, range);
+			if (!expansion) {
+				lines.push(`  ${index + 1}. ${describeLines(range.start, range.end)} — no unique prefix/suffix found within ${MAX_TOTAL_CONTEXT_LINES} context lines.`);
+				continue;
+			}
+			const where = `effective context: ${plural(expansion.prefixLines, "line")} before, ${plural(expansion.suffixLines, "line")} after`;
+			if (!isSnippetRenderable(expansion.text) || Buffer.byteLength(expansion.text, "utf8") > MAX_SUCCESS_SNIPPET_BYTES) {
+				lines.push(`  ${index + 1}. ${describeLines(range.start, range.end)} — ${where}; snippet omitted, read lines ${expansion.startLine}-${expansion.endLine}.`);
+				continue;
+			}
+			lines.push(`  ${index + 1}. ${describeLines(range.start, range.end)} — ${where}:`);
+			lines.push(...renderSnippet(expansion.text));
+		}
+		lines.push("Use one fenced snippet byte-for-byte as oldText if you want to edit another occurrence.", "");
+	}
+	if (resolutions.length > shownResolutions.length) {
+		lines.push(`${resolutions.length - shownResolutions.length} more auto-disambiguated edits were applied; details omitted.`);
+	}
+	return boundCompleteOutput(lines.join("\n").trimEnd());
+}
+
 export function formatEditFailure(opts: FormatFailureOptions): string {
+	return boundCompleteOutput(formatEditFailureUnbounded(opts));
+}
+
+function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
 	const { path, normalizedContent, edits, failure } = opts;
 	const total = edits.length;
 
@@ -82,8 +164,8 @@ export function formatEditFailure(opts: FormatFailureOptions): string {
 		case "ambiguous": {
 			const head =
 				total === 1
-					? `Found ${failure.occurrenceOffsets.length} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
-					: `Found ${failure.occurrenceOffsets.length} occurrences of edits[${failure.editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`;
+					? `Found ${failure.occurrenceCount} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
+					: `Found ${failure.occurrenceCount} occurrences of edits[${failure.editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`;
 			const body =
 				normalizedContent.length <= MAX_CONTENT_FOR_DIAGNOSTICS
 					? formatAmbiguous(opts, failure)
@@ -123,17 +205,18 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
 		lines.push(`  ${i + 1}. ${describeLines(range.start, range.end)}`);
 	});
-	if (failure.occurrenceOffsets.length > listed.length) {
-		lines.push(`  … and ${failure.occurrenceOffsets.length - listed.length} more`);
+	if (failure.occurrenceCount > listed.length) {
+		lines.push(`  … and ${failure.occurrenceCount - listed.length} more`);
 	}
 	lines.push("");
 
 	lines.push(
-		"Retry with a disambiguated oldText: pick ONE occurrence below and reuse its snippet exactly. Each snippet already includes the minimum surrounding context that makes it unique:",
+		"Disambiguated oldText candidates are shown below when they fit safely. A fenced snippet can be reused exactly; an omitted snippet must be read from its referenced range first:",
 	);
 
 	let shown = 0;
 	let missingExpansionNote = false;
+	let omittedSnippet = false;
 	for (let i = 0; i < listed.length && shown < MAX_SNIPPET_OCCURRENCES; i++) {
 		const offset = listed[i];
 		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
@@ -142,11 +225,18 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 			missingExpansionNote = true;
 			continue;
 		}
-		shown++;
 		const where = `minimum context: ${plural(expansion.prefixLines, "line")} before, ${plural(expansion.suffixLines, "line")} after`;
 		lines.push("");
+		if (!isSnippetRenderable(expansion.text)) {
+			omittedSnippet = true;
+			lines.push(
+				`Occurrence ${i + 1} (${describeLines(range.start, range.end)}) — ${where}. Exact unique snippet omitted because it exceeds the safe output limit; read lines ${expansion.startLine}-${expansion.endLine}.`,
+			);
+			continue;
+		}
+		shown++;
 		lines.push(`Occurrence ${i + 1} (${describeLines(range.start, range.end)}) — ${where}:`);
-		lines.push(...renderSnippet(expansion.text, `lines ${expansion.startLine}-${expansion.endLine}`));
+		lines.push(...renderSnippet(expansion.text));
 	}
 
 	if (missingExpansionNote) {
@@ -155,12 +245,12 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 			`Some occurrences could not be auto-disambiguated within ${MAX_TOTAL_CONTEXT_LINES} context lines (likely near-identical repeated blocks). Extend oldText manually with distinguishing lines from the occurrences listed above.`,
 		);
 	}
-	if (shown === 0 && !missingExpansionNote) {
+	if (shown === 0 && !missingExpansionNote && !omittedSnippet) {
 		lines.push("", "Extend oldText with more surrounding lines until it matches exactly one location.");
 	}
 	lines.push("");
 	lines.push(
-		"Tip: use the snippet byte-for-byte as the new oldText, and make newText the snippet with your change applied (the snippet may span whole lines).",
+		"Tip: only fenced snippets above are byte-for-byte retryable. Make newText from the chosen snippet with your intended change applied.",
 	);
 	return lines.join("\n");
 }
@@ -177,6 +267,17 @@ function plural(n: number, noun: string): string {
 	return `${n} ${noun}${n === 1 ? "" : "s"}`;
 }
 
+function countLiteralOccurrences(haystack: string, needle: string): number {
+	if (!needle) return 0;
+	let count = 0;
+	let index = haystack.indexOf(needle);
+	while (index !== -1) {
+		count++;
+		index = haystack.indexOf(needle, index + needle.length);
+	}
+	return count;
+}
+
 /**
  * Find the smallest whole-line context expansion of the occurrence at `range`
  * whose text occurs exactly once in the file (checked in fuzzy space, exactly
@@ -271,9 +372,9 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 				);
 			}
 		} else {
-			lines.push(`Differences vs your oldText (${closest.equalCount} of ${closest.totalOldLines} compared lines match):`);
+			lines.push(`Differences vs your oldText (${closest.equalCount} of ${closest.totalOldLines} compared lines match exactly):`);
 			for (const op of diffOps.slice(0, MAX_DIFF_OPS_SHOWN)) {
-				if (op.type === "changed") {
+				if (op.type === "changed" || op.type === "similar") {
 					lines.push(`  file line ${op.fileLine} differs from your oldText line ${op.oldLine}:`);
 					lines.push(`    file:     ${truncateLine(op.fileText ?? "")}`);
 					lines.push(`    oldText:  ${truncateLine(op.oldText ?? "")}`);
@@ -290,12 +391,41 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 			}
 		}
 		lines.push("");
-		lines.push(
-			`Exact file content at ${describeLines(closest.startLine, closest.endLine)} — retry using this text as oldText (then apply your change to newText):`,
-		);
-		lines.push(...snippetFromLines(normalizedContent, closest.startLine, closest.endLine));
+		const candidate = textFromLines(normalizedContent, closest.startLine, closest.endLine);
+		const uniqueCandidate = verifyUniqueSnippet(normalizeForFuzzyMatch(normalizedContent), candidate);
+		const safelyRenderable = isSnippetRenderable(uniqueCandidate ?? candidate);
+		const competitorGap = closest.competitor ? closest.score - closest.competitor.score : Number.POSITIVE_INFINITY;
+		const directRetry =
+			!closest.truncated &&
+			closest.score >= MIN_DIRECT_RETRY_SCORE &&
+			!closest.competitionIncomplete &&
+			competitorGap >= MIN_DIRECT_RETRY_GAP &&
+			uniqueCandidate !== null &&
+			safelyRenderable;
+		if (directRetry) {
+			lines.push(
+				`Exact file content at ${describeLines(closest.startLine, closest.endLine)} (unique under edit matching) — retry using this text as oldText (then apply your change to newText):`,
+			);
+			lines.push(...renderSnippet(uniqueCandidate));
+		} else {
+			const reasons = [
+				closest.truncated ? "only part of oldText was compared" : undefined,
+				closest.score < MIN_DIRECT_RETRY_SCORE ? "similarity confidence is too low" : undefined,
+				closest.competitionIncomplete ? "the bounded search discarded another competitively scored window" : undefined,
+				competitorGap < MIN_DIRECT_RETRY_GAP && closest.competitor
+					? `a distinct candidate at ${describeLines(closest.competitor.startLine, closest.competitor.endLine)} has a similar heuristic score (~${Math.round(closest.competitor.score * 100)}%)`
+					: undefined,
+				uniqueCandidate === null ? "the candidate is not unique under edit matching" : undefined,
+				!safelyRenderable ? "the exact candidate exceeds the safe output limit" : undefined,
+			].filter((reason): reason is string => reason !== undefined);
+			lines.push(
+				`Candidate file content at ${describeLines(closest.startLine, closest.endLine)} is not safe for a direct retry (${reasons.join("; ")}). Read and verify this range before editing.`,
+			);
+			if (safelyRenderable) lines.push(...renderSnippet(uniqueCandidate ?? candidate));
+		}
+
 	} else {
-		lines.push("No similar region was found in the file (best similarity below threshold).");
+		lines.push("No reliable similar region was found within the bounded diagnostic search.");
 		lines.push("If you expected this text to exist, read the file around the expected location and retry.");
 	}
 
@@ -308,37 +438,107 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 }
 
 function truncateLine(line: string): string {
-	const collapsed = line.replace(/\t/g, "→tab→");
-	return collapsed.length > 120 ? `${collapsed.slice(0, 117)}…` : collapsed;
+	const visibleTrailing = line.replace(/[ \t]+$/, (suffix) =>
+		[...suffix].map((char) => (char === "\t" ? "→tab→" : "·")).join(""),
+	);
+	const visible = visibleTrailing.replace(/\t/g, "→tab→");
+	return visible.length > 120 ? `${visible.slice(0, 117)}…` : visible;
+}
+
+/**
+ * Enforce the complete output budget without ever cutting a generated fenced
+ * snippet. Oversized snippets are omitted atomically and clearly marked.
+ */
+function boundCompleteOutput(message: string): string {
+	const source = message.split("\n");
+	const output: string[] = [];
+	let bytes = 0;
+	let omitted = false;
+	const reservedBytes = 512;
+	const maxBodyBytes = MAX_OUTPUT_BYTES - reservedBytes;
+	const maxBodyLines = MAX_OUTPUT_LINES - 3;
+
+	const canAdd = (block: string[]) => {
+		const text = block.join("\n");
+		const addedBytes = Buffer.byteLength(text, "utf8") + (output.length > 0 ? 1 : 0);
+		return output.length + block.length <= maxBodyLines && bytes + addedBytes <= maxBodyBytes;
+	};
+	const add = (block: string[]) => {
+		const text = block.join("\n");
+		bytes += Buffer.byteLength(text, "utf8") + (output.length > 0 ? 1 : 0);
+		output.push(...block);
+	};
+
+	for (let index = 0; index < source.length; index++) {
+		const opener = source[index];
+		if (/^`{3,}$/.test(opener)) {
+			let closing = index + 1;
+			while (closing < source.length && source[closing] !== opener) closing++;
+			if (closing < source.length) {
+				const block = source.slice(index, closing + 1);
+				if (canAdd(block)) add(block);
+				else {
+					omitted = true;
+					const notice = ["[Exact fenced snippet omitted to keep the complete tool output within its byte/line budget.]" ];
+					if (canAdd(notice)) add(notice);
+				}
+				index = closing;
+				continue;
+			}
+		}
+
+		if (canAdd([opener])) {
+			add([opener]);
+			continue;
+		}
+		omitted = true;
+		const available = Math.max(0, maxBodyBytes - bytes - (output.length > 0 ? 1 : 0));
+		if (available > 4 && output.length < maxBodyLines) add([truncateUtf8(opener, available)]);
+		break;
+	}
+
+	if (omitted) {
+		const notice = "[Diagnostic output was bounded. Omitted fenced snippets are not retryable; read the referenced range first.]";
+		if (output.length > 0) output.push("");
+		output.push(notice);
+	}
+	return output.join("\n").trimEnd();
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+	const suffix = "…";
+	const target = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (Buffer.byteLength(text.slice(0, middle), "utf8") <= target) low = middle;
+		else high = middle - 1;
+	}
+	return `${text.slice(0, low)}${suffix}`;
 }
 
 // ---------------------------------------------------------------------------
 // Snippet rendering
 // ---------------------------------------------------------------------------
 
-function snippetFromLines(content: string, startLine: number, endLine: number): string[] {
+function textFromLines(content: string, startLine: number, endLine: number): string {
 	const spans = getLineSpans(content);
-	const raw = content.slice(spans[startLine - 1].start, spans[endLine - 1].end);
-	const text = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
-	return renderSnippet(text, `lines ${startLine}-${endLine}`);
+	return content.slice(spans[startLine - 1].start, spans[endLine - 1].end);
 }
 
-function renderSnippet(text: string, where: string): string[] {
-	const fence = fenceFor(text);
-	const allLines = text.split("\n");
-	if (allLines.length <= MAX_SNIPPET_LINES) {
-		return [fence, text, fence];
+function isSnippetRenderable(text: string): boolean {
+	return text.split("\n").length <= MAX_SNIPPET_LINES && Buffer.byteLength(text, "utf8") <= MAX_SNIPPET_BYTES;
+}
+
+/** Render only complete snippets. Callers must check isSnippetRenderable first. */
+function renderSnippet(text: string): string[] {
+	if (!isSnippetRenderable(text)) {
+		return ["[Exact snippet omitted because it exceeds the safe output limit; read the referenced range first.]" ];
 	}
-	const head = allLines.slice(0, MAX_SNIPPET_LINES - 10);
-	const tail = allLines.slice(-10);
-	const skipped = allLines.length - head.length - tail.length;
-	return [
-		fence,
-		...head,
-		`… (${skipped} middle lines snipped — see ${where}; re-read that range if you need the full text)`,
-		...tail,
-		fence,
-	];
+	const fence = fenceFor(text);
+	return [fence, text, fence];
 }
 
 /** Choose a fence longer than any backtick run inside the snippet. */

package/src/index.ts

@@ -2,20 +2,30 @@
  * pi-better-tool — better built-in tools for the pi coding agent.
  *
  * Currently ships one override:
- * - `edit` — identical matching semantics to the built-in edit tool, but
- *   failures return recovery context (closest matching region, per-occurrence
- *   minimal disambiguation snippets) so the agent can retry immediately
- *   without re-reading the file.
+ * - `edit` — built-in-compatible exact replacement with richer recovery
+ *   context and conservative read-based resolution when a recent verified
+ *   read contains exactly one of several literal occurrences.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerBetterEditTool } from "./tool.ts";
 
 export { registerBetterEditTool, executeBetterEdit, prepareEditArguments, betterEditSchema } from "./tool.ts";
-export type { BetterEditInput } from "./tool.ts";
-export { formatEditFailure, findMinimalUniqueExpansion, fenceFor } from "./diagnostics.ts";
+export type {
+	BetterEditExecutionOptions,
+	BetterEditInput,
+	BetterEditOperations,
+	BetterEditSuccess,
+} from "./tool.ts";
+export {
+	formatAutoDisambiguationSuccess,
+	formatEditFailure,
+	findMinimalUniqueExpansion,
+	fenceFor,
+} from "./diagnostics.ts";
+export type { AutoDisambiguation } from "./diagnostics.ts";
 export { analyzeEdits, applyAnalysis } from "./apply.ts";
-export type { EditFailure, EditOp, EditAnalysis } from "./apply.ts";
+export type { AnalyzeOptions, EditFailure, EditOp, EditAnalysis } from "./apply.ts";
 
 export default function (pi: ExtensionAPI) {
 	registerBetterEditTool(pi);

package/src/read-evidence.ts

@@ -0,0 +1,174 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { normalizeToLF } from "./text.ts";
+
+export interface ReadEvidence {
+	/** 0-based, end-exclusive offsets in LF-normalized, BOM-stripped content. */
+	startOffset: number;
+	endOffset: number;
+	/** 1-based inclusive range represented by the verified read output. */
+	startLine: number;
+	endLine: number;
+}
+
+interface ReadCall {
+	id: string;
+	path: string;
+	offset?: number;
+	limit?: number;
+}
+
+interface StoredToolResult {
+	role: "toolResult";
+	toolCallId: string;
+	toolName: string;
+	isError: boolean;
+	content: Array<{ type: string; text?: string }>;
+}
+
+interface StoredAssistant {
+	role: "assistant";
+	content: Array<{ type: string; id?: string; name?: string; arguments?: unknown }>;
+}
+
+interface ContextEntryLike {
+	type: string;
+	message?: StoredAssistant | StoredToolResult | { role: string };
+	retainedTail?: Array<StoredAssistant | StoredToolResult | { role: string }>;
+}
+
+/**
+ * Find the newest read call for targetPath in Pi's compaction-aware stored
+ * context. The call is accepted only when its successful result exactly
+ * matches the built-in read formatting for the current LF-normalized content.
+ *
+ * This establishes stored-context evidence, not proof of the final provider
+ * payload after other extensions' context/provider hooks.
+ */
+export async function findLatestReadEvidence(
+	sessionManager: Pick<ExtensionContext["sessionManager"], "buildContextEntries"> | undefined,
+	targetPath: string,
+	normalizedContent: string,
+	resolvePath: (path: string) => Promise<string>,
+): Promise<ReadEvidence | null> {
+	if (!sessionManager) return null;
+	const entries = sessionManager.buildContextEntries() as ContextEntryLike[];
+	const messages = entries.flatMap((entry) => {
+		if (entry.type === "message" && entry.message) return [entry.message];
+		if (entry.type === "compaction" && Array.isArray(entry.retainedTail)) return entry.retainedTail;
+		return [];
+	});
+	const calls: ReadCall[] = [];
+	const results = new Map<string, StoredToolResult>();
+
+	for (const message of messages) {
+		if (message.role === "assistant") {
+			for (const item of (message as StoredAssistant).content) {
+				if (item.type !== "toolCall" || item.name !== "read" || typeof item.id !== "string") continue;
+				const args = item.arguments as Record<string, unknown> | undefined;
+				if (!args || typeof args.path !== "string") continue;
+				calls.push({
+					id: item.id,
+					path: args.path,
+					offset: typeof args.offset === "number" ? args.offset : undefined,
+					limit: typeof args.limit === "number" ? args.limit : undefined,
+				});
+			}
+		} else if (message.role === "toolResult") {
+			const result = message as StoredToolResult;
+			if (result.toolName === "read") results.set(result.toolCallId, result);
+		}
+	}
+
+	for (let index = calls.length - 1; index >= 0; index--) {
+		const call = calls[index];
+		let readPath: string;
+		try {
+			readPath = await resolvePath(call.path);
+		} catch {
+			// Without a canonical identity we cannot prove that this newer read is
+			// unrelated, so fail closed instead of falling back to older intent.
+			return null;
+		}
+		if (readPath !== targetPath) continue;
+
+		// Never fall back to older intent when the newest same-file read is
+		// missing, failed, malformed, or stale.
+		const result = results.get(call.id);
+		if (!result || result.isError) return null;
+		return evidenceFromBuiltinRead(normalizedContent, call, result.content);
+	}
+	return null;
+}
+
+export function evidenceFromBuiltinRead(
+	content: string,
+	call: Pick<ReadCall, "path" | "offset" | "limit">,
+	blocks: Array<{ type: string; text?: string }>,
+): ReadEvidence | null {
+	if (blocks.length !== 1 || blocks[0].type !== "text" || typeof blocks[0].text !== "string") return null;
+	if (call.offset !== undefined && (!Number.isInteger(call.offset) || call.offset < 1)) return null;
+	if (call.limit !== undefined && (!Number.isInteger(call.limit) || call.limit < 1)) return null;
+	const actualOutput = normalizeToLF(blocks[0].text);
+	const allLines = content.split("\n");
+	const startIndex = call.offset ? Math.max(0, call.offset - 1) : 0;
+	if (startIndex >= allLines.length) return null;
+
+	let selectedContent: string;
+	let userLimitedLines: number | undefined;
+	if (call.limit !== undefined) {
+		const endIndex = Math.min(startIndex + call.limit, allLines.length);
+		selectedContent = allLines.slice(startIndex, endIndex).join("\n");
+		userLimitedLines = endIndex - startIndex;
+	} else {
+		selectedContent = allLines.slice(startIndex).join("\n");
+	}
+
+	const truncation = truncateHead(selectedContent);
+	if (truncation.firstLineExceedsLimit) return null;
+
+	let expectedOutput = truncation.content;
+	let visibleLines = truncation.outputLines;
+	if (truncation.truncated) {
+		const startLine = startIndex + 1;
+		const endLine = startLine + truncation.outputLines - 1;
+		const nextOffset = endLine + 1;
+		if (truncation.truncatedBy === "lines") {
+			expectedOutput += `\n\n[Showing lines ${startLine}-${endLine} of ${allLines.length}. Use offset=${nextOffset} to continue.]`;
+		} else {
+			expectedOutput += `\n\n[Showing lines ${startLine}-${endLine} of ${allLines.length} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+		}
+	} else if (userLimitedLines !== undefined && startIndex + userLimitedLines < allLines.length) {
+		const remaining = allLines.length - (startIndex + userLimitedLines);
+		const nextOffset = startIndex + userLimitedLines + 1;
+		expectedOutput += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+		visibleLines = userLimitedLines;
+	}
+
+	if (actualOutput !== expectedOutput || visibleLines <= 0 || visibleLines > DEFAULT_MAX_LINES) return null;
+
+	const startLine = startIndex + 1;
+	const endLine = startLine + visibleLines - 1;
+	const startOffset = offsetAtLine(content, startLine);
+	const endOffset = offsetAtLine(content, endLine + 1);
+	return { startOffset, endOffset, startLine, endLine };
+}
+
+/** Offset of a 1-based line; the line after EOF maps to content.length. */
+function offsetAtLine(content: string, line: number): number {
+	if (line <= 1) return 0;
+	let currentLine = 1;
+	let offset = 0;
+	while (currentLine < line) {
+		const newline = content.indexOf("\n", offset);
+		if (newline === -1) return content.length;
+		offset = newline + 1;
+		currentLine++;
+	}
+	return offset;
+}