@oh-my-pi/pi-coding-agent 15.3.1 → 15.4.1

package/src/tools/irc.ts

@@ -25,6 +25,7 @@ import ircDescription from "../prompts/tools/irc.md" with { type: "text" };
 import type { AgentRef, AgentRegistry } from "../registry/agent-registry";
 import type { ToolSession } from ".";
 
+const DEFAULT_IRC_TIMEOUT_MS = 120_000;
 const ircSchema = z.object({
 	op: z.enum(["send", "list"]).describe("irc operation"),
 	to: z.string().optional().describe('recipient agent id or "all"'),
@@ -159,6 +160,7 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 
 		const awaitReply = params.awaitReply ?? !isBroadcast;
 
+		const timeoutMs = normalizeIrcTimeoutMs(this.session.settings.get("irc.timeoutMs"));
 		const delivered: string[] = [];
 		const replies: IrcReply[] = [];
 		const failed: Array<{ id: string; error: string }> = [];
@@ -174,12 +176,18 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 				return;
 			}
 			try {
-				const result = await targetSession.respondAsBackground({
-					from: senderId,
-					message,
-					awaitReply,
+				const result = await runIrcDispatchWithTimeout(
+					timeoutMs,
 					signal,
-				});
+					timeoutSignal =>
+						targetSession.respondAsBackground({
+							from: senderId,
+							message,
+							awaitReply,
+							signal: timeoutSignal,
+						}),
+					target.id,
+				);
 				delivered.push(target.id);
 				if (awaitReply && result.replyText) {
 					replies.push({ from: target.id, text: result.replyText });
@@ -237,3 +245,49 @@ function errorResult(text: string, details: IrcDetails): AgentToolResult<IrcDeta
 		details,
 	};
 }
+
+function normalizeIrcTimeoutMs(value: number): number {
+	if (!Number.isFinite(value) || value === 0) return value === 0 ? 0 : DEFAULT_IRC_TIMEOUT_MS;
+	return Math.max(1, Math.trunc(value));
+}
+
+async function runIrcDispatchWithTimeout<T>(
+	timeoutMs: number,
+	parentSignal: AbortSignal | undefined,
+	run: (signal?: AbortSignal) => Promise<T>,
+	targetId: string,
+): Promise<T> {
+	if (timeoutMs <= 0) {
+		return await run(parentSignal);
+	}
+
+	const controller = new AbortController();
+	const timeoutError = new Error(`IRC timed out waiting for ${targetId} after ${timeoutMs} ms`);
+	let timeout: NodeJS.Timeout | undefined;
+	let parentAbortListener: (() => void) | undefined;
+
+	const timeoutDeferred = Promise.withResolvers<never>();
+	if (parentSignal) {
+		if (parentSignal.aborted) {
+			throw parentSignal.reason instanceof Error ? parentSignal.reason : new Error("IRC aborted");
+		}
+		parentAbortListener = () => {
+			controller.abort(parentSignal.reason);
+			timeoutDeferred.reject(parentSignal.reason instanceof Error ? parentSignal.reason : new Error("IRC aborted"));
+		};
+		parentSignal.addEventListener("abort", parentAbortListener, { once: true });
+	}
+
+	timeout = setTimeout(() => {
+		controller.abort(timeoutError);
+		timeoutDeferred.reject(timeoutError);
+	}, timeoutMs);
+	timeout.unref?.();
+
+	try {
+		return await Promise.race([run(controller.signal), timeoutDeferred.promise]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+		if (parentSignal && parentAbortListener) parentSignal.removeEventListener("abort", parentAbortListener);
+	}
+}

package/src/tools/jtd-to-json-schema.ts

@@ -180,7 +180,11 @@ function normalizeMixedSchemaNode(schema: unknown): unknown {
 	}
 
 	if (isJTDSchema(schema)) {
-		return normalizeMixedSchemaNode(convertSchema(schema));
+		// `convertSchema` is itself fully recursive and emits pure JSON Schema, so
+		// re-walking the result with `normalizeMixedSchemaNode` is unnecessary and
+		// unsafe: it would treat user-named properties whose keys happen to be JTD
+		// keywords (e.g. `ref`, `elements`) as nested JTD forms (#1345).
+		return convertSchema(schema);
 	}
 
 	const normalized: Record<string, unknown> = {};

package/src/tools/match-line-format.ts

@@ -1,12 +1,10 @@
-import { computeLineHash } from "../hashline/hash";
-
 /**
  * Format a single line of match output for grep/ast-grep style results.
  *
- * The anchor/content separator is always `|`. Matched lines are prefixed
- * with `*`; context lines are prefixed with a single space so anchors
- * align in column. In hashline mode the anchor is `LINE+ID` (no `#`); in
- * plain mode it is just the line number. Line numbers are never padded.
+ * Matched lines are prefixed with `*`; context lines are prefixed with a single
+ * space so line numbers align in column. In hashline mode the line uses the
+ * editable `LINE:content` shape under a file-hash header; in plain mode it keeps
+ * the legacy `LINE|content` display-only shape. Line numbers are never padded.
  */
 export function formatMatchLine(
 	lineNumber: number,
@@ -16,7 +14,7 @@ export function formatMatchLine(
 ): string {
 	const marker = isMatch ? "*" : " ";
 	if (options.useHashLines) {
-		return `${marker}${lineNumber}${computeLineHash(lineNumber, line)}|${line}`;
+		return `${marker}${lineNumber}:${line}`;
 	}
 	return `${marker}${lineNumber}|${line}`;
 }

package/src/tools/output-schema-validator.ts

@@ -0,0 +1,132 @@
+/**
+ * Shared output-schema validation for subagent yield + executor finalization.
+ *
+ * Both the in-process `yield` tool (subagent side) and the executor's post-mortem
+ * finalize path (parent side) need to validate yield payloads against the agent's
+ * declared output schema. This module is the single source of truth for that
+ * pipeline — keeping the two callsites in lockstep so a schema accepted in-tool
+ * cannot be rejected post-mortem (or vice versa).
+ */
+import {
+	isValidJsonSchema,
+	type JsonSchemaValidationIssue,
+	type JsonSchemaValidationResult,
+	validateJsonSchemaValue,
+} from "@oh-my-pi/pi-ai/utils/schema";
+import { jtdToJsonSchema, normalizeSchema } from "./jtd-to-json-schema";
+
+/** A validator bound to a specific output schema. */
+export interface OutputValidator {
+	/** Run JSON Schema validation; returns the raw `success`/`issues` shape so callers may inspect every failure. */
+	validate(value: unknown): JsonSchemaValidationResult;
+	/** Top-level required property names. Empty if the schema has no `required` array at root. */
+	readonly requiredFields: readonly string[];
+}
+
+export interface BuildOutputValidatorResult {
+	/** Present when the schema produced a usable validator (i.e. constraining schemas). Absent for missing/unconstrained schemas. */
+	validator?: OutputValidator;
+	/** Raw JSON Schema produced by `jtdToJsonSchema`. Available alongside the validator so callers can derive related artifacts (strict-mode probe, dereference, hint text). */
+	jsonSchema?: Record<string, unknown>;
+	/**
+	 * Normalized schema (post-`normalizeSchema`). Surfaced so callers can distinguish
+	 * "no schema provided" (`undefined`) from "intentionally unconstrained" (`true`)
+	 * when both produce no validator.
+	 */
+	normalized?: unknown;
+	/** Set when the schema cannot be used. Callers should treat this as a "no validation" case (loose acceptance) and surface the message in diagnostics. */
+	error?: string;
+}
+
+/**
+ * Build the canonical validator for a JTD-or-JSON-Schema output declaration.
+ *
+ * Returns:
+ * - `{ validator, jsonSchema, normalized }` for constraining schemas — both callers use this path.
+ * - `{ normalized: true }` for an intentionally unconstrained schema (the JSON Schema literal `true`).
+ *   No validator, but distinguishable from "no schema provided".
+ * - `{}` for an absent schema (`undefined`).
+ * - `{ error, normalized? }` when the schema cannot be honored (invalid syntax, `false`, malformed JTD).
+ */
+export function buildOutputValidator(schema: unknown): BuildOutputValidatorResult {
+	const { normalized, error: normalizeError } = normalizeSchema(schema);
+	if (normalizeError) return { error: normalizeError, normalized };
+	if (normalized === undefined) return {};
+	if (normalized === false) return { error: "boolean false schema rejects all outputs", normalized };
+	if (normalized === true) return { normalized };
+
+	const jsonSchema = jtdToJsonSchema(normalized);
+	if (jsonSchema === undefined) return { normalized };
+	if (jsonSchema === false) return { error: "boolean false schema rejects all outputs", normalized };
+	if (jsonSchema === true) return { normalized };
+	if (typeof jsonSchema !== "object" || Array.isArray(jsonSchema)) {
+		return { error: "invalid JSON schema", normalized };
+	}
+	if (!isValidJsonSchema(jsonSchema)) return { error: "invalid JSON schema", normalized };
+
+	const jsonSchemaRecord = jsonSchema as Record<string, unknown>;
+	const required = extractRequiredFields(jsonSchemaRecord);
+	return {
+		normalized,
+		jsonSchema: jsonSchemaRecord,
+		validator: {
+			requiredFields: required,
+			validate: value => validateJsonSchemaValue(jsonSchemaRecord, value),
+		},
+	};
+}
+
+/** Produce the executor's headline+missing-required summary from a failed validation. */
+export function summarizeValidationFailure(
+	result: JsonSchemaValidationResult,
+	value: unknown,
+	requiredFields: readonly string[],
+): { message: string; missingRequired: string[] } {
+	if (result.success) return { message: "", missingRequired: [] };
+	const missing = computeMissingRequired(requiredFields, value);
+	const message = formatValidationIssueHeadline(result.issues[0]) ?? "schema validation failed";
+	return { message, missingRequired: missing };
+}
+
+export function extractRequiredFields(jsonSchema: unknown): string[] {
+	if (!jsonSchema || typeof jsonSchema !== "object") return [];
+	const required = (jsonSchema as { required?: unknown }).required;
+	return Array.isArray(required) ? required.filter((k): k is string => typeof k === "string") : [];
+}
+
+export function computeMissingRequired(required: readonly string[], value: unknown): string[] {
+	if (required.length === 0) return [];
+	if (value === null || value === undefined) return [...required];
+	if (typeof value !== "object" || Array.isArray(value)) return [];
+	const record = value as Record<string, unknown>;
+	return required.filter(key => !(key in record) || record[key] === undefined);
+}
+
+/**
+ * Format a single validation issue as `path.with.dots: message`.
+ *
+ * Used by the executor's post-mortem `schema_violation` headline — one line, dot-separated path,
+ * since the executor's error format already lists missing-required fields separately.
+ */
+export function formatValidationIssueHeadline(issue: JsonSchemaValidationIssue | undefined): string | undefined {
+	if (!issue) return undefined;
+	const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
+	return `${path}: ${issue.message}`;
+}
+
+/**
+ * Format every validation issue as `path/with/slashes: message; ...`.
+ *
+ * Used by the yield tool's model-facing retry feedback — the model gets every problem at once so it
+ * can fix the entire output in one retry instead of iterating issue-by-issue. The slash separator
+ * mirrors JSON Pointer convention and disambiguates against fields whose names contain dots.
+ */
+export function formatAllValidationIssues(issues: ReadonlyArray<JsonSchemaValidationIssue> | undefined): string {
+	if (!issues || issues.length === 0) return "Unknown schema validation error.";
+	return issues
+		.map(issue => {
+			const path = issue.path.length === 0 ? "" : `${issue.path.map(seg => String(seg)).join("/")}: `;
+			return `${path}${issue.message}`;
+		})
+		.join("; ");
+}

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,27 +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,
-	truncatedLines?: ReadonlySet<number>,
 ): string {
-	if (shouldAddHashLines) {
-		if (!truncatedLines || truncatedLines.size === 0) return formatHashLines(text, startNum);
-		// Column-truncated lines hash differently from the on-disk line that the
-		// edit verifier reads back. Drop the anchor (`LINE|TEXT` instead of
-		// `LINE+HASH|TEXT`) so the model treats the line as un-anchorable rather
-		// than copying a hash that will be rejected as stale.
-		const lines = text.split("\n");
-		return lines
-			.map((line, i) => {
-				const ln = startNum + i;
-				return truncatedLines.has(ln) ? `${ln}${HL_BODY_SEP}${line}` : formatHashLine(ln, line);
-			})
-			.join("\n");
-	}
+	if (shouldAddHashLines) return formatNumberedLines(text, startNum);
 	if (shouldAddLineNumbers) return prependLineNumbers(text, startNum);
 	return text;
 }
@@ -164,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;
 }
@@ -179,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 };
@@ -194,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;
 
@@ -858,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;
@@ -876,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);
 			}
@@ -942,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);
@@ -957,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") : "";
@@ -1016,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[] = [];
@@ -1045,32 +1110,29 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 
 			const collectedLines = streamResult.lines;
-			const truncatedLineNumbers = new Set<number>();
 			if (!rawSelector && maxColumns > 0) {
 				for (let i = 0; i < collectedLines.length; i++) {
 					const { text, wasTruncated } = truncateLine(collectedLines[i], maxColumns);
 					if (wasTruncated) {
 						collectedLines[i] = text;
 						columnTruncated = maxColumns;
-						truncatedLineNumbers.add(range.startLine + i);
 					}
 				}
 			}
 
 			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,
-					truncatedLineNumbers,
-				),
-			);
+			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");
@@ -1359,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);
@@ -1420,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;
 			}
@@ -1441,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;
@@ -1450,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(
@@ -1698,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,
 						},
 					};
@@ -1814,14 +1883,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					// view — column truncation surfaces separately via `.limits()`.
 					const rawSelector = isRawSelector(parsed);
 					const maxColumns = resolveOutputMaxColumns(this.session.settings);
-					const truncatedLineNumbers = new Set<number>();
 					if (!rawSelector && maxColumns > 0) {
 						for (let i = 0; i < collectedLines.length; i++) {
 							const { text, wasTruncated } = truncateLine(collectedLines[i], maxColumns);
 							if (wasTruncated) {
 								collectedLines[i] = text;
 								columnTruncated = maxColumns;
-								truncatedLineNumbers.add(startLineDisplay + i);
 							}
 						}
 					}
@@ -1846,22 +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,
-							truncatedLineNumbers,
-						);
+						const formatted = formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
+						if (!hashContext || emittedHashlineHeader) return formatted;
+						emittedHashlineHeader = true;
+						return prependHashlineHeader(formatted, hashContext);
 					};
 
 					let outputText: string;
@@ -1873,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);
 						}
@@ -1996,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,