@gajae-code/coding-agent 0.11.11 → 0.12.0

package/src/tools/read.ts

@@ -19,14 +19,16 @@ import type { InternalUrl } from "../internal-urls/types";
 import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
 import readDescription from "../prompts/tools/read.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
+import type { ReadSegment, ReadWindow, TruncationDirection, TruncationResult } from "../session/streaming-output";
 import {
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,
-	noTruncResult,
-	type TruncationResult,
+	formatMiddleElisionMarker,
 	truncateHead,
 	truncateHeadBytes,
 	truncateLine,
+	truncateMiddleWindows,
+	truncateTailBytes,
 } from "../session/streaming-output";
 import { fileHyperlink, renderCodeCell, renderMarkdownCell, renderStatusLine, tryResolveInternalUrlSync } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
@@ -51,6 +53,7 @@ import {
 	isReadableUrlPath,
 	loadReadUrlCacheEntry,
 	parseReadUrlTarget,
+	prepareReadUrlSelectorInput,
 	type ReadUrlToolDetails,
 	renderReadUrlCall,
 	renderReadUrlResult,
@@ -71,6 +74,7 @@ import {
 	splitInternalUrlSel,
 	splitPathAndSel,
 } from "./path-utils";
+import { type ReadRoute, resolveEffectiveDirection } from "./read-internals";
 import { formatBytes, replaceTabs, shortenPath, wrapBrackets } from "./render-utils";
 import {
 	enforceSqliteQueryOnly,
@@ -99,6 +103,12 @@ const MAX_SUMMARY_BYTES = 2 * 1024 * 1024;
 const MAX_SUMMARY_LINES = 20_000;
 const RAW_COLLECTOR_MAX_BYTES = MAX_SUMMARY_BYTES;
 
+const BODY_TRUNCATION_FOOTER_KEY = "__bodyTruncationFooter";
+
+function rememberBodyTruncationFooter(details: ReadToolDetails, footer: string): void {
+	Object.defineProperty(details, BODY_TRUNCATION_FOOTER_KEY, { value: footer, configurable: true, enumerable: false });
+}
+
 /**
  * Per-line column cap for file reads. Lines wider than the value of
  * `tools.outputMaxColumns` are ellipsis-truncated at display time; the file
@@ -185,6 +195,259 @@ function countTextLines(text: string): number {
 	return text.split("\n").length;
 }
 
+function windowSegments(window: ReadWindow): ReadSegment[] {
+	return [window.head, window.tail].filter((segment): segment is ReadSegment => segment !== undefined);
+}
+
+function windowHasPartialSegment(window: ReadWindow): boolean {
+	return windowSegments(window).some(segment => segment.kind === "partial-line");
+}
+
+function partialTailOf(window: ReadWindow): Extract<ReadSegment, { kind: "partial-line" }> | undefined {
+	const tail = window.tail;
+	return tail?.kind === "partial-line" ? tail : undefined;
+}
+
+function linesOfSegment(segment: ReadSegment): string[] {
+	return segment.content.split("\n");
+}
+
+function rebaseWindow(window: ReadWindow, offset: number): ReadWindow {
+	const rebaseSegment = (segment: ReadSegment | undefined): ReadSegment | undefined => {
+		if (!segment) return undefined;
+		return {
+			...segment,
+			origin: {
+				startLine: segment.origin.startLine + offset,
+				endLine: segment.origin.endLine + offset,
+			},
+		};
+	};
+	const rebased: ReadWindow = {
+		...window,
+		head: rebaseSegment(window.head),
+		tail: rebaseSegment(window.tail),
+	};
+	for (const key of ["maxBytes", "truncatedBy", "outputLinesOverride", "outputBytesOverride"] as const) {
+		const descriptor = Object.getOwnPropertyDescriptor(window, key);
+		if (descriptor) Object.defineProperty(rebased, key, descriptor);
+	}
+	return rebased;
+}
+
+function renderReadWindow(
+	window: ReadWindow,
+	shouldAddHashLines: boolean,
+	shouldAddLineNumbers: boolean,
+	maxColumns = 0,
+): string {
+	const renderSegment = (segment: ReadSegment): string => {
+		const hash = shouldAddHashLines && segment.kind === "lines";
+		const numbers = !hash && shouldAddLineNumbers;
+		const renderContent =
+			!hash && maxColumns > 0
+				? segment.content
+						.split("\n")
+						.map(line => truncateLine(line, maxColumns).text)
+						.join("\n")
+				: segment.content;
+		return formatTextWithMode(renderContent, segment.origin.startLine, hash, numbers);
+	};
+	const marker = formatMiddleElisionMarker(window.elidedLines, window.elidedBytes);
+	if (window.kind === "full") return window.head ? renderSegment(window.head) : "";
+	if (window.kind === "head-only") return window.head ? renderSegment(window.head) : "";
+	if (window.kind === "tail-only") return window.tail ? renderSegment(window.tail) : "";
+	if (!window.head || !window.tail) return "";
+	if (window.elidedLines <= 0) return `${renderSegment(window.head)}\n${renderSegment(window.tail)}`;
+	return `${renderSegment(window.head)}\n${marker}\n${renderSegment(window.tail)}`;
+}
+
+function windowOutputLines(window: ReadWindow): number {
+	if (window.kind === "full") return window.head?.lines ?? 0;
+	if (window.kind === "head-only") return window.head?.lines ?? 0;
+	if (window.kind === "tail-only") return window.tail?.lines ?? 0;
+	return (window.head?.lines ?? 0) + (window.tail?.lines ?? 0) + (window.elidedLines > 0 ? 1 : 0);
+}
+
+function windowOutputBytes(window: ReadWindow): number {
+	if (window.kind === "full") return window.head?.bytes ?? 0;
+	if (window.kind === "head-only") return window.head?.bytes ?? 0;
+	if (window.kind === "tail-only") return window.tail?.bytes ?? 0;
+	if (window.elidedLines <= 0) return (window.head?.bytes ?? 0) + (window.tail?.bytes ?? 0) + 1;
+	const marker = formatMiddleElisionMarker(window.elidedLines, window.elidedBytes);
+	return (window.head?.bytes ?? 0) + (window.tail?.bytes ?? 0) + Buffer.byteLength(marker, "utf-8") + 2;
+}
+
+function windowTruncatedBy(window: ReadWindow): "lines" | "bytes" | "middle" | undefined {
+	return (window as ReadWindow & { truncatedBy?: "lines" | "bytes" | "middle" }).truncatedBy;
+}
+
+function makeWindowResult(window: ReadWindow, content: string): TruncationResult {
+	const truncatedBy = windowTruncatedBy(window);
+	const lastLineExceedsLimit = window.tail?.kind === "partial-line";
+	return {
+		content,
+		truncated: window.kind !== "full",
+		truncatedBy: truncatedBy ?? (window.kind === "middle" ? "middle" : "lines"),
+		totalLines: window.totalLines,
+		totalBytes: window.totalBytes,
+		outputLines: windowOutputLines(window),
+		outputBytes: windowOutputBytes(window),
+		// `elidedLines`/`elidedBytes` are documented as middle-only on the legacy
+		// `TruncationResult`; head/tail windows leave them absent so one-sided
+		// results stay byte-identical to the pre-change shape.
+		...(window.kind === "middle" ? { elidedLines: window.elidedLines, elidedBytes: window.elidedBytes } : {}),
+		lastLinePartial: windowHasPartialSegment(window),
+		firstLineExceedsLimit: false,
+		...(lastLineExceedsLimit ? { lastLineExceedsLimit: true } : {}),
+	};
+}
+
+function fullReadWindow(content: string, totalLines: number, totalBytes: number): ReadWindow {
+	return {
+		kind: "full",
+		head: {
+			kind: "lines",
+			content,
+			lines: totalLines,
+			bytes: totalBytes,
+			origin: { startLine: 1, endLine: totalLines },
+			lastLinePartial: false,
+		},
+		overlap: "disjoint",
+		elidedLines: 0,
+		elidedBytes: 0,
+		totalLines,
+		totalBytes,
+	};
+}
+
+function selectReceiptWindow(
+	allLines: readonly string[],
+	direction: "head" | "tail",
+	budgetLines: number,
+	budgetBytes: number,
+): ReadWindow {
+	const totalLines = allLines.length;
+	const fullContent = allLines.join("\n");
+	const totalBytes = Buffer.byteLength(fullContent, "utf-8");
+	const take = (from: number, step: 1 | -1): { picked: string[]; bytes: number; truncatedBy?: "lines" | "bytes" } => {
+		const picked: string[] = [];
+		let bytes = 0;
+		let truncatedBy: "lines" | "bytes" | undefined;
+		for (let i = from; i >= 0 && i < allLines.length; i += step) {
+			if (picked.length >= budgetLines) {
+				truncatedBy = "lines";
+				break;
+			}
+			const lineBytes = Buffer.byteLength(allLines[i] ?? "", "utf-8") + (picked.length > 0 ? 1 : 0);
+			if (bytes + lineBytes > budgetBytes) {
+				// Report the constraint that actually bound the window. When the
+				// line budget was already full, the byte overflow is incidental and
+				// the materialized oracle calls it "lines"; matching keeps A26
+				// parity honest.
+				truncatedBy = picked.length >= budgetLines ? "lines" : "bytes";
+				break;
+			}
+			picked.push(allLines[i] ?? "");
+			bytes += lineBytes;
+		}
+		return { picked, bytes, truncatedBy };
+	};
+	const taken = direction === "head" ? take(0, 1) : take(allLines.length - 1, -1);
+	if (direction === "tail") taken.picked.reverse();
+	const startLine = direction === "head" ? 1 : totalLines - taken.picked.length + 1;
+	const selected = taken.picked.join("\n");
+	if (taken.picked.length === totalLines) return fullReadWindow(fullContent, totalLines, totalBytes);
+	const segment: ReadSegment | undefined =
+		taken.picked.length > 0
+			? {
+					kind: "lines",
+					content: selected,
+					lines: taken.picked.length,
+					bytes: taken.bytes,
+					origin: { startLine, endLine: startLine + taken.picked.length - 1 },
+					lastLinePartial: false,
+				}
+			: undefined;
+	const window: ReadWindow = {
+		kind: direction === "head" ? "head-only" : "tail-only",
+		...(direction === "head" ? (segment ? { head: segment } : {}) : segment ? { tail: segment } : {}),
+		overlap: "disjoint",
+		elidedLines: Math.max(0, totalLines - taken.picked.length),
+		elidedBytes: Math.max(0, totalBytes - taken.bytes),
+		totalLines,
+		totalBytes,
+	};
+	if (taken.truncatedBy) Object.defineProperty(window, "truncatedBy", { value: taken.truncatedBy, enumerable: false });
+	return window;
+}
+
+function selectReadWindow(
+	text: string,
+	allLines: readonly string[],
+	direction: TruncationDirection,
+	budgetLines: number,
+	budgetBytes: number,
+): ReadWindow {
+	if (direction === "both") {
+		return truncateMiddleWindows(text, { maxLines: budgetLines, maxBytes: budgetBytes });
+	}
+	return selectReceiptWindow(allLines, direction === "head" ? "head" : "tail", budgetLines, budgetBytes);
+}
+
+function formatDirectionalFooter(readPath: string, window: ReadWindow): string {
+	if (window.kind === "full") return "";
+	const total = window.totalLines;
+	const shownSegments = windowSegments(window);
+	const shownBytes =
+		shownSegments.reduce((sum, segment) => sum + segment.bytes, 0) + Math.max(0, shownSegments.length - 1);
+	const head = window.head;
+	const tail = window.tail;
+	const partialTail = partialTailOf(window);
+	if (partialTail) {
+		return `[Showing last ${formatBytes(partialTail.bytes)} of line ${partialTail.origin.startLine} (line is ${formatBytes(partialTail.sourceLineBytes)}); re-read ${readPath}:1-${total} or ${readPath}:raw for the full file]`;
+	}
+	if (window.kind === "tail-only" && tail) {
+		const start = tail.origin.startLine;
+		return `[Showing last ${tail.lines} of ${total} lines (lines ${start}-${tail.origin.endLine}, ~${Math.ceil(shownBytes / 1024)} KiB); omitted lines 1-${start - 1}; re-read ${readPath}:1-${total} or ${readPath}:raw for the full file]`;
+	}
+	if (window.kind === "middle" && head && tail) {
+		const omittedStart = head.origin.endLine + 1;
+		const omittedEnd = tail.origin.startLine - 1;
+		return `[Showing lines 1-${head.origin.endLine} and ${tail.origin.startLine}-${tail.origin.endLine} of ${total} (~${Math.ceil(shownBytes / 1024)} KiB); omitted lines ${omittedStart}-${omittedEnd}; re-read ${readPath}:1-${total} or ${readPath}:raw for the full file]`;
+	}
+	const shown = head?.lines ?? 0;
+	return `[Showing first ${shown} of ${total} lines (~${Math.ceil(shownBytes / 1024)} KiB); re-read ${readPath}:1-${total} or ${readPath}:raw for the full file]`;
+}
+
+function formatOversizedLineWarning(
+	readPath: string,
+	lineNumber: number,
+	lineBytes: number,
+	maxBytes: number,
+	fullFileLines: number,
+): string {
+	return `[Line ${lineNumber} is ${formatBytes(lineBytes)}, exceeds ${formatBytes(maxBytes)} limit. Hashline output requires full lines; cannot compute hashes for a truncated preview. Re-read ${readPath}:1-${fullFileLines} or ${readPath}:raw for the full file]`;
+}
+
+function formatListingTruncationNotice(
+	shownLines: number,
+	shownBytes: number,
+	absolutePath: string,
+	direction: TruncationDirection,
+): string {
+	const retained = direction === "last" ? "last" : direction === "both" ? "first and last" : "first";
+	const directionPart = direction === "head" ? "" : `; retained ${retained} lines`;
+	return `[Listing truncated at ${shownLines} lines / ${Math.ceil(shownBytes / 1024)} KiB${directionPart}; read a deeper subpath (e.g. ${absolutePath}/<subdir>) to narrow the view]`;
+}
+
+function formatRawReadCapNotice(maxBytes: number, fileSize: number, direction: TruncationDirection): string {
+	const retained = direction === "last" ? "last" : direction === "both" ? "first and last" : "first";
+	const directionPart = direction === "head" ? "" : `; retained ${retained} bytes`;
+	return `[Raw read capped at ${formatBytes(maxBytes)} of ${formatBytes(fileSize)}${directionPart}; re-read a line range to narrow the view]`;
+}
+
 /**
  * Footer appended to summarized reads telling the model how to recover the
  * elided body. Without this hint, agents either ignore the `...`/`{ .. }`
@@ -202,8 +465,15 @@ function formatReceiptFooter(readPath: string, shownLines: number, totalLines: n
 	return `[Showing first ${shownLines} of ${totalLines} lines (~${Math.ceil(shownBytes / 1024)} KiB); re-read ${readPath}:1-${totalLines} or ${readPath}:raw for the full file]`;
 }
 
-function formatSummaryCapFooter(readPath: string, maxBytes: number, totalLines: number): string {
-	return `[Summary truncated at ${Math.ceil(maxBytes / 1024)} KiB; re-read ${readPath}:raw or ${readPath}:1-${totalLines} for the full source]`;
+function formatSummaryCapFooter(
+	readPath: string,
+	maxBytes: number,
+	totalLines: number,
+	direction: TruncationDirection = "head",
+): string {
+	const retained = direction === "last" ? "last" : direction === "both" ? "first and last" : "first";
+	const directionPart = direction === "head" ? "" : `; retained ${retained} summary units`;
+	return `[Summary truncated at ${Math.ceil(maxBytes / 1024)} KiB${directionPart}; re-read ${readPath}:1-${totalLines} or ${readPath}:raw for the full source]`;
 }
 const READ_CHUNK_SIZE = 8 * 1024;
 
@@ -241,13 +511,15 @@ function expandRangeWithContext(
 	};
 }
 
-async function streamLinesFromFile(
+export async function streamLinesFromFile(
 	filePath: string,
 	startLine: number,
 	maxLinesToCollect: number,
 	maxBytes: number,
 	selectedLineLimit: number | null,
 	signal?: AbortSignal,
+	collect: "head" | "tail" | "both" = "head",
+	collectEndExclusive: number | null = null,
 ): Promise<{
 	lines: string[];
 	totalFileLines: number;
@@ -256,6 +528,22 @@ async function streamLinesFromFile(
 	firstLinePreview?: { text: string; bytes: number };
 	firstLineByteLength?: number;
 	selectedBytesTotal: number;
+	windowBytesTotal: number;
+	windowLinesTotal: number;
+	windowStartIndex: number;
+	tailPartial?: { text: string; bytes: number; sourceIndex: number; sourceLineBytes: number };
+	maxBytes: number;
+	headLines?: string[];
+	headBytes?: number;
+	headStartIndex?: number;
+	degenerateTailBudget: boolean;
+	degenerateHeadBudget: boolean;
+	headStoppedByBytes: boolean;
+	headStoppedByLines: boolean;
+	ringBudgetLines: number;
+	ringEvictedForBytes: boolean;
+	ringEvictedForLines: boolean;
+	tailDroppedForBytes: boolean;
 }> {
 	const bufferChunk = Buffer.allocUnsafe(READ_CHUNK_SIZE);
 	const collectedLines: string[] = [];
@@ -273,30 +561,72 @@ async function streamLinesFromFile(
 	let firstLineByteLength: number | undefined;
 	let selectedBytesTotal = 0;
 	let selectedLinesSeen = 0;
+	let windowBytesTotal = 0;
+	let windowLinesTotal = 0;
 	let captureLine = false;
 	let discardLineChunks = false;
 	let lineCaptureLimit = 0;
 
+	// A middle read uses the same split as truncateMiddleWindows. The candidate
+	// state below is deliberately full-fit first: a file that fits the unsplit
+	// budget must not lose bytes merely because the eventual mode is "both".
+	const headBudgetBytes = collect === "both" ? Math.floor(maxBytes / 2) : 0;
+	const ringBudgetBytes = collect === "both" ? Math.max(0, maxBytes - headBudgetBytes) : maxBytes;
+	const headBudgetLines = collect === "both" ? Math.max(1, Math.floor(maxLinesToCollect / 2)) : 0;
+	const ringBudgetLines = collect === "both" ? Math.max(0, maxLinesToCollect - headBudgetLines) : maxLinesToCollect;
+	// Keep the full-fit candidate ahead of this classification. Once a split is
+	// required, these predicates dispatch the effective one-sided window kind.
+	const degenerateHeadBudget = collect === "both" && (headBudgetBytes <= 0 || headBudgetLines <= 0);
+	const degenerateTailBudget = collect === "both" && (ringBudgetBytes <= 0 || ringBudgetLines <= 0);
+	type BothState = "full-fit" | "split";
+	let oneSidedDispatch: "head" | "tail" | undefined;
+	let state: BothState = collect === "both" ? "full-fit" : "split";
+	let fitLines: string[] = [];
+	let fitByteLens: number[] = [];
+	let fitBytes = 0;
+	let fitStartIndex = -1;
+
+	const ring: string[] = [];
+	const ringLineBytes: number[] = [];
+	let ringHead = 0;
+	let ringBytes = 0;
+	let ringStartIndex = 0;
+	let ringOriginPending = true;
+	let ringEvictedForBytes = false;
+	let ringEvictedForLines = false;
+	let tailDroppedForBytes = false;
+
+	const headLines: string[] = [];
+	let headBytes = 0;
+	let headSealed = false;
+	let headStoppedByBytes = false;
+	let headStoppedByLines = false;
+
+	let currentLineKept = 0;
+	let currentLineDropped = false;
+	let oversizedPending: { index: number; byteLength: number; preview: { text: string; bytes: number } } | undefined;
+
+	const windowEndExclusive = collectEndExclusive === null ? Number.POSITIVE_INFINITY : collectEndExclusive;
+	const inWindow = () => lineIndex >= startLine && lineIndex < windowEndExclusive;
+
 	const setupLineState = () => {
-		captureLine = !doneCollecting && lineIndex >= startLine;
+		captureLine = collect === "head" && !doneCollecting && lineIndex >= startLine;
 		discardLineChunks = !captureLine;
 		if (captureLine) {
 			const separatorBytes = collectedLines.length > 0 ? 1 : 0;
 			lineCaptureLimit = maxBytes - collectedBytes - separatorBytes;
-			if (lineCaptureLimit <= 0) {
-				discardLineChunks = true;
-			}
+			if (lineCaptureLimit <= 0) discardLineChunks = true;
 		} else {
 			lineCaptureLimit = 0;
 		}
 	};
 
 	const decodeLine = (): string => {
-		if (currentLineLength === 0) return "";
-		if (currentLineChunks.length === 1 && currentLineChunks[0]?.length === currentLineLength) {
+		if (currentLineKept === 0) return "";
+		if (currentLineChunks.length === 1 && currentLineChunks[0]?.length === currentLineKept) {
 			return currentLineChunks[0].toString("utf-8");
 		}
-		return Buffer.concat(currentLineChunks, currentLineLength).toString("utf-8");
+		return Buffer.concat(currentLineChunks, currentLineKept).toString("utf-8");
 	};
 
 	const maybeCapturePreview = (segment: Uint8Array) => {
@@ -309,15 +639,123 @@ async function streamLinesFromFile(
 		firstLinePreviewBytes += slice.length;
 	};
 
+	const trimCurrentLineBuffer = (cap: number) => {
+		while (currentLineKept > cap && currentLineChunks.length > 0) {
+			const front = currentLineChunks[0];
+			const excess = currentLineKept - cap;
+			if (front.length <= excess) {
+				currentLineChunks.shift();
+				currentLineKept -= front.length;
+			} else {
+				currentLineChunks[0] = Buffer.from(front.subarray(excess));
+				currentLineKept -= excess;
+			}
+			currentLineDropped = true;
+		}
+	};
+
 	const appendSegment = (segment: Uint8Array) => {
 		currentLineLength += segment.length;
-		maybeCapturePreview(segment);
-		if (!captureLine || discardLineChunks || segment.length === 0) return;
-		if (currentLineLength <= lineCaptureLimit) {
-			currentLineChunks.push(Buffer.from(segment));
-		} else {
-			discardLineChunks = true;
+		if (collect === "head") {
+			maybeCapturePreview(segment);
+			if (!captureLine || discardLineChunks || segment.length === 0) return;
+			if (currentLineLength <= lineCaptureLimit) {
+				currentLineChunks.push(Buffer.from(segment));
+				currentLineKept += segment.length;
+			} else {
+				discardLineChunks = true;
+			}
+			return;
 		}
+		if (!inWindow() || segment.length === 0) return;
+		currentLineChunks.push(Buffer.from(segment));
+		currentLineKept += segment.length;
+		trimCurrentLineBuffer(collect === "both" && state === "full-fit" ? maxBytes : ringBudgetBytes);
+	};
+
+	const capturePartialPreview = (): { text: string; bytes: number } => {
+		const raw = Buffer.concat(currentLineChunks, currentLineKept);
+		let start = 0;
+		while (start < raw.length && (raw[start]! & 0xc0) === 0x80) start++;
+		const aligned = raw.subarray(start);
+		return { text: aligned.toString("utf-8"), bytes: aligned.length };
+	};
+
+	const pushSplit = (
+		index: number,
+		text: string,
+		bytes: number,
+		dropped: boolean,
+		previewOverride?: { text: string; bytes: number },
+	) => {
+		if (collect === "both" && oneSidedDispatch !== "tail" && !headSealed) {
+			if (dropped || bytes > headBudgetBytes) {
+				headSealed = true;
+				headStoppedByBytes = true;
+			} else {
+				const separatorBytes = headLines.length > 0 ? 1 : 0;
+				if (headLines.length < headBudgetLines && headBytes + separatorBytes + bytes <= headBudgetBytes) {
+					headLines.push(text);
+					headBytes += separatorBytes + bytes;
+				} else {
+					headSealed = true;
+					if (headLines.length >= headBudgetLines) headStoppedByLines = true;
+					else headStoppedByBytes = true;
+				}
+			}
+		}
+		if (collect === "both" && oneSidedDispatch === "head") return;
+
+		if (dropped || bytes > ringBudgetBytes) {
+			const preview = previewOverride ?? truncateTailBytes(text, ringBudgetBytes);
+			oversizedPending = { index, byteLength: bytes, preview };
+			ring.length = 0;
+			ringHead = 0;
+			ringLineBytes.length = 0;
+			ringBytes = 0;
+			ringOriginPending = true;
+			tailDroppedForBytes = true;
+			return;
+		}
+
+		if (ringOriginPending) {
+			ringStartIndex = index;
+			ringOriginPending = false;
+		}
+		ring.push(text);
+		ringLineBytes.push(bytes);
+		ringBytes += (ring.length - ringHead > 1 ? 1 : 0) + bytes;
+		oversizedPending = undefined;
+
+		while (ring.length - ringHead > ringBudgetLines || (ringBytes > ringBudgetBytes && ring.length - ringHead > 1)) {
+			if (ring.length - ringHead > ringBudgetLines) ringEvictedForLines = true;
+			if (ringBytes > ringBudgetBytes) ringEvictedForBytes = true;
+			const evictedBytes = ringLineBytes[ringHead] ?? 0;
+			const evictedSep = ring.length - ringHead > 1 ? 1 : 0;
+			ringBytes -= evictedBytes + evictedSep;
+			ring[ringHead] = undefined as unknown as string;
+			ringHead++;
+			ringStartIndex++;
+		}
+		if (ring.length - ringHead === 0) ringOriginPending = true;
+		if (ringHead > 4096) {
+			ring.splice(0, ringHead);
+			ringLineBytes.splice(0, ringHead);
+			ringHead = 0;
+		}
+	};
+
+	const transitionToSplit = () => {
+		state = "split";
+		oneSidedDispatch = degenerateHeadBudget ? "tail" : degenerateTailBudget ? "head" : undefined;
+		for (let i = 0; i < fitLines.length; i++) {
+			pushSplit(fitStartIndex + i, fitLines[i] ?? "", fitByteLens[i] ?? 0, false);
+		}
+		fitLines = [];
+		fitByteLens = [];
+		fitBytes = 0;
+		fitStartIndex = -1;
+		trimCurrentLineBuffer(ringBudgetBytes);
 	};
 
 	const finalizeLine = () => {
@@ -325,41 +763,65 @@ async function streamLinesFromFile(
 			selectedBytesTotal += currentLineLength + (selectedLinesSeen > 0 ? 1 : 0);
 			selectedLinesSeen++;
 		}
+		if (inWindow()) {
+			windowBytesTotal += currentLineLength + (windowLinesTotal > 0 ? 1 : 0);
+			windowLinesTotal++;
+		}
 
-		if (!doneCollecting && lineIndex >= startLine) {
-			const separatorBytes = collectedLines.length > 0 ? 1 : 0;
-			if (collectedLines.length >= maxLinesToCollect) {
-				doneCollecting = true;
-			} else if (collectedLines.length === 0 && currentLineLength > maxBytes) {
-				stoppedByByteLimit = true;
-				doneCollecting = true;
-				if (firstLineByteLength === undefined) {
-					firstLineByteLength = currentLineLength;
-				}
-			} else if (collectedLines.length > 0 && collectedBytes + separatorBytes + currentLineLength > maxBytes) {
-				stoppedByByteLimit = true;
-				doneCollecting = true;
-			} else {
-				const lineText = decodeLine();
-				collectedLines.push(lineText);
-				collectedBytes += separatorBytes + currentLineLength;
-				if (firstLineByteLength === undefined) {
-					firstLineByteLength = currentLineLength;
-				}
-				if (collectedBytes > maxBytes) {
+		if (collect === "head") {
+			if (!doneCollecting && lineIndex >= startLine) {
+				const separatorBytes = collectedLines.length > 0 ? 1 : 0;
+				if (collectedLines.length >= maxLinesToCollect) {
+					doneCollecting = true;
+				} else if (collectedLines.length === 0 && currentLineLength > maxBytes) {
 					stoppedByByteLimit = true;
 					doneCollecting = true;
-				} else if (collectedLines.length >= maxLinesToCollect) {
+					if (firstLineByteLength === undefined) firstLineByteLength = currentLineLength;
+				} else if (collectedLines.length > 0 && collectedBytes + separatorBytes + currentLineLength > maxBytes) {
+					stoppedByByteLimit = true;
 					doneCollecting = true;
+				} else {
+					const lineText = decodeLine();
+					collectedLines.push(lineText);
+					collectedBytes += separatorBytes + currentLineLength;
+					if (firstLineByteLength === undefined) firstLineByteLength = currentLineLength;
+					if (collectedBytes > maxBytes) {
+						stoppedByByteLimit = true;
+						doneCollecting = true;
+					} else if (collectedLines.length >= maxLinesToCollect) {
+						doneCollecting = true;
+					}
 				}
+			} else if (lineIndex >= startLine && firstLineByteLength === undefined) {
+				firstLineByteLength = currentLineLength;
+			}
+		} else if (inWindow()) {
+			const lineText = decodeLine();
+			if (collect === "both" && state === "full-fit") {
+				const separatorBytes = fitLines.length > 0 ? 1 : 0;
+				const stillFits =
+					!currentLineDropped &&
+					fitLines.length + 1 <= maxLinesToCollect &&
+					fitBytes + separatorBytes + currentLineLength <= maxBytes;
+				if (stillFits) {
+					if (fitStartIndex < 0) fitStartIndex = lineIndex;
+					fitLines.push(lineText);
+					fitByteLens.push(currentLineLength);
+					fitBytes += separatorBytes + currentLineLength;
+				} else {
+					transitionToSplit();
+					pushSplit(lineIndex, lineText, currentLineLength, currentLineDropped, capturePartialPreview());
+				}
+			} else {
+				pushSplit(lineIndex, lineText, currentLineLength, currentLineDropped, capturePartialPreview());
 			}
-		} else if (lineIndex >= startLine && firstLineByteLength === undefined) {
-			firstLineByteLength = currentLineLength;
 		}
 
 		lineIndex++;
 		currentLineLength = 0;
+		currentLineKept = 0;
 		currentLineChunks = [];
+		currentLineDropped = false;
 		setupLineState();
 	};
 
@@ -367,7 +829,6 @@ async function streamLinesFromFile(
 
 	try {
 		fileHandle = await fs.open(filePath, "r");
-
 		while (true) {
 			throwIfAborted(signal);
 			const { bytesRead } = await fileHandle.read(bufferChunk, 0, bufferChunk.length, null);
@@ -381,27 +842,18 @@ async function streamLinesFromFile(
 			for (let i = 0; i < chunk.length; i++) {
 				if (chunk[i] === 0x0a) {
 					const segment = chunk.subarray(start, i);
-					if (segment.length > 0) {
-						appendSegment(segment);
-					}
+					if (segment.length > 0) appendSegment(segment);
 					finalizeLine();
 					start = i + 1;
 				}
 			}
-
-			if (start < chunk.length) {
-				appendSegment(chunk.subarray(start));
-			}
+			if (start < chunk.length) appendSegment(chunk.subarray(start));
 		}
 	} finally {
-		if (fileHandle) {
-			await fileHandle.close();
-		}
+		if (fileHandle) await fileHandle.close();
 	}
 
-	if (endedWithNewline || currentLineLength > 0 || !sawAnyByte) {
-		finalizeLine();
-	}
+	if (endedWithNewline || currentLineLength > 0 || !sawAnyByte) finalizeLine();
 
 	let firstLinePreview: { text: string; bytes: number } | undefined;
 	if (firstLinePreviewBytes > 0) {
@@ -409,17 +861,271 @@ async function streamLinesFromFile(
 		firstLinePreview = { text, bytes };
 	}
 
+	const tailPartial =
+		collect !== "head" && oversizedPending
+			? {
+					text: oversizedPending.preview.text,
+					bytes: oversizedPending.preview.bytes,
+					sourceIndex: oversizedPending.index,
+					sourceLineBytes: oversizedPending.byteLength,
+				}
+			: undefined;
+	// I8: selected-window line totals are defined on the valid domain only;
+	// out-of-bounds starts clamp the mathematical count at zero.
+	// `inWindow()` above enforces the same predicate while collecting.
+	// I8 is therefore `windowLinesTotal === Math.max(0, windowEnd - startLine)`.
+	const ringSize = ring.length - ringHead;
+	const ringLines = ring.slice(ringHead);
+	const windowEnd = Math.min(collectEndExclusive ?? lineIndex, lineIndex);
+	const windowStartIndex =
+		collect === "head"
+			? startLine
+			: ringSize > 0
+				? ringStartIndex
+				: tailPartial
+					? tailPartial.sourceIndex
+					: windowEnd;
+
+	if (collect !== "head") collectedBytes = ringBytes;
+
+	const resolvedHeadLines = collect === "both" && state === "full-fit" ? fitLines : headLines;
+	const resolvedHeadBytes = collect === "both" && state === "full-fit" ? fitBytes : headBytes;
 	return {
-		lines: collectedLines,
+		lines: collect === "head" ? collectedLines : ringLines,
 		totalFileLines: lineIndex,
 		collectedBytes,
-		stoppedByByteLimit,
+		stoppedByByteLimit: collect === "head" ? stoppedByByteLimit : ringEvictedForBytes,
 		firstLinePreview,
 		firstLineByteLength,
 		selectedBytesTotal,
+		windowBytesTotal,
+		windowLinesTotal,
+		windowStartIndex,
+		tailPartial,
+		maxBytes,
+		headLines: collect === "both" ? resolvedHeadLines : undefined,
+		headBytes: collect === "both" ? resolvedHeadBytes : undefined,
+		headStartIndex: collect === "both" ? startLine : undefined,
+		degenerateTailBudget,
+		degenerateHeadBudget,
+		headStoppedByBytes,
+		headStoppedByLines,
+		ringBudgetLines,
+		ringEvictedForBytes,
+		ringEvictedForLines,
+		tailDroppedForBytes,
 	};
 }
 
+export function streamResultWindow(
+	result: Awaited<ReturnType<typeof streamLinesFromFile>>,
+	collect: "tail" | "both",
+	startLine: number,
+	collectEndExclusive: number | null,
+): ReadWindow {
+	const windowEnd = Math.min(collectEndExclusive ?? result.totalFileLines, result.totalFileLines);
+	const totalLines = result.windowLinesTotal;
+	const totalBytes = result.windowBytesTotal;
+	const ringLines = result.lines;
+	const partial = result.tailPartial;
+	const attachReason = (window: ReadWindow, reason: "lines" | "bytes" | "middle" | undefined): ReadWindow => {
+		Object.defineProperty(window, "maxBytes", { value: result.maxBytes, enumerable: false });
+		if (reason !== undefined) Object.defineProperty(window, "truncatedBy", { value: reason, enumerable: false });
+		return window;
+	};
+	const linesSegment = (lines: readonly string[], bytes: number, sourceStart: number): ReadSegment | undefined => {
+		if (lines.length === 0) return undefined;
+		return {
+			kind: "lines",
+			content: lines.join("\n"),
+			lines: lines.length,
+			bytes,
+			origin: { startLine: sourceStart + 1, endLine: sourceStart + lines.length },
+			lastLinePartial: false,
+		};
+	};
+	const partialSegment = (): ReadSegment | undefined => {
+		if (!partial) return undefined;
+		return {
+			kind: "partial-line",
+			content: partial.text,
+			lines: 1,
+			bytes: partial.bytes,
+			origin: { startLine: partial.sourceIndex + 1, endLine: partial.sourceIndex + 1 },
+			sourceLineBytes: partial.sourceLineBytes,
+			lastLinePartial: true,
+		};
+	};
+	const sourceBytes = (lines: readonly string[]): number => Buffer.byteLength(lines.join("\n"), "utf-8");
+	const tail = partialSegment() ?? linesSegment(ringLines, result.collectedBytes, result.windowStartIndex);
+	const tailStartIndex = partial?.sourceIndex ?? (ringLines.length > 0 ? result.windowStartIndex : windowEnd);
+	const tailCount = partial ? 1 : ringLines.length;
+	const lineBudgetWon = !partial && result.ringEvictedForLines && tailCount >= result.ringBudgetLines;
+	const tailReason: "lines" | "bytes" | undefined =
+		partial || result.tailDroppedForBytes || (result.ringEvictedForBytes && !lineBudgetWon)
+			? "bytes"
+			: lineBudgetWon || tailCount < totalLines
+				? "lines"
+				: undefined;
+
+	if (collect === "tail") {
+		if (
+			tailCount === totalLines &&
+			!partial &&
+			!result.ringEvictedForBytes &&
+			!result.ringEvictedForLines &&
+			!result.tailDroppedForBytes
+		) {
+			return {
+				kind: "full",
+				head: linesSegment(ringLines, totalBytes, startLine),
+				overlap: "disjoint",
+				elidedLines: 0,
+				elidedBytes: 0,
+				totalLines,
+				totalBytes,
+			};
+		}
+		return attachReason(
+			{
+				kind: "tail-only",
+				...(tail ? { tail } : {}),
+				overlap: "disjoint",
+				elidedLines: Math.max(0, totalLines - tailCount),
+				elidedBytes: partial
+					? Math.max(0, totalBytes - partial.bytes)
+					: Math.max(0, totalBytes - result.collectedBytes),
+				totalLines,
+				totalBytes,
+			},
+			tailReason,
+		);
+	}
+
+	const headLines = result.headLines ?? [];
+	const headCount = headLines.length;
+	const headBytes = result.headBytes ?? sourceBytes(headLines);
+	const head = linesSegment(headLines, headBytes, result.headStartIndex ?? startLine);
+	const headEndExclusive = startLine + headCount;
+	const windowLineCount = totalLines;
+	const headReason: "lines" | "bytes" | undefined = result.degenerateTailBudget
+		? result.headStoppedByBytes
+			? "bytes"
+			: result.headStoppedByLines || headCount < windowLineCount
+				? "lines"
+				: undefined
+		: result.ringEvictedForBytes || result.tailDroppedForBytes
+			? "bytes"
+			: result.ringEvictedForLines || headCount < windowLineCount
+				? "lines"
+				: undefined;
+	const makeHeadOnly = (): ReadWindow =>
+		attachReason(
+			{
+				kind: "head-only",
+				...(head ? { head } : {}),
+				overlap: "disjoint",
+				elidedLines: Math.max(0, windowLineCount - headCount),
+				elidedBytes: Math.max(0, totalBytes - headBytes),
+				totalLines: windowLineCount,
+				totalBytes,
+			},
+			headReason,
+		);
+	const makeTailOnly = (): ReadWindow =>
+		attachReason(
+			{
+				kind: "tail-only",
+				...(tail ? { tail } : {}),
+				overlap: "disjoint",
+				elidedLines: Math.max(0, windowLineCount - tailCount),
+				elidedBytes: partial
+					? Math.max(0, totalBytes - partial.bytes)
+					: Math.max(0, totalBytes - result.collectedBytes),
+				totalLines: windowLineCount,
+				totalBytes,
+			},
+			tailReason,
+		);
+	if (
+		collect === "both" &&
+		headCount === windowLineCount &&
+		!partial &&
+		!result.ringEvictedForBytes &&
+		!result.ringEvictedForLines &&
+		!result.tailDroppedForBytes
+	) {
+		return {
+			kind: "full",
+			head: linesSegment(headLines, totalBytes, startLine),
+			overlap: "disjoint",
+			elidedLines: 0,
+			elidedBytes: 0,
+			totalLines: windowLineCount,
+			totalBytes,
+		};
+	}
+
+	if (collect === "both" && result.degenerateHeadBudget) return makeTailOnly();
+	if (collect === "both" && result.degenerateTailBudget) return makeHeadOnly();
+	if (headCount === 0) return makeTailOnly();
+	if (ringLines.length === 0 && !partial) return makeHeadOnly();
+	if (!tail) return makeHeadOnly();
+
+	const headTailGap = tailStartIndex - headEndExclusive;
+	const overlap: ReadWindow["overlap"] = headTailGap > 0 ? "disjoint" : headTailGap === 0 ? "adjacent" : "overlapping";
+	if (headTailGap <= 0) {
+		const headKeep = Math.max(0, tailStartIndex - startLine);
+		if (headKeep === 0) return makeTailOnly();
+		if (!partial && headKeep + ringLines.length >= windowLineCount) {
+			const fullLines = headLines.slice(0, headKeep).concat(ringLines);
+			return {
+				kind: "full",
+				head: linesSegment(fullLines, totalBytes, startLine),
+				overlap,
+				elidedLines: 0,
+				elidedBytes: 0,
+				totalLines: windowLineCount,
+				totalBytes,
+			};
+		}
+		const keptHeadLines = headLines.slice(0, headKeep);
+		const keptHead = linesSegment(keptHeadLines, sourceBytes(keptHeadLines), startLine);
+		if (!keptHead) return makeTailOnly();
+		return attachReason(
+			{
+				kind: "middle",
+				head: keptHead,
+				tail,
+				overlap,
+				elidedLines: partial ? Math.max(0, tailStartIndex - (startLine + headKeep)) : 0,
+				elidedBytes: partial
+					? Math.max(0, totalBytes - keptHead.bytes - partial.sourceLineBytes)
+					: Math.max(0, totalBytes - keptHead.bytes - tail.bytes),
+				totalLines: windowLineCount,
+				totalBytes,
+			},
+			"middle",
+		);
+	}
+
+	const elidedLines = partial ? Math.max(0, tailStartIndex - headEndExclusive) : headTailGap;
+	const partialSourceBytes = partial ? partial.sourceLineBytes : tail.bytes;
+	return attachReason(
+		{
+			kind: "middle",
+			...(head ? { head } : {}),
+			tail,
+			overlap,
+			elidedLines,
+			elidedBytes: Math.max(0, totalBytes - headBytes - partialSourceBytes),
+			totalLines: windowLineCount,
+			totalBytes,
+		},
+		"middle",
+	);
+}
+
 // Maximum image file size (20MB) - larger images will be rejected to prevent OOM during serialization
 const MAX_IMAGE_SIZE = MAX_IMAGE_INPUT_BYTES;
 const GLOB_TIMEOUT_MS = 5000;
@@ -495,6 +1201,12 @@ function prependSuffixResolutionNotice(text: string, suffixResolution?: { from:
 const readSchema = z
 	.object({
 		path: z.string().describe('path or url; append :<sel> for line ranges or raw mode (e.g. "src/foo.ts:50-100")'),
+		truncation: z
+			.enum(["head", "last", "both"])
+			.optional()
+			.describe(
+				"which end of an over-budget result to keep: head | last | both. Route defaults are route-aware: read.truncation is consulted for bare local and archive-member routes (factory default: last), while URL, converted, directory, range, internal, and other routes default to head. SQLite row, schema, and query reads ignore this parameter; raw reads honor explicit directions.",
+			),
 	})
 	.strict();
 
@@ -730,6 +1442,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		this.description = prompt.render(readDescription, {
 			DEFAULT_LIMIT: String(this.#defaultLimit),
 			DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
+			TRUNCATION_DEFAULT: String(this.session.settings.get("read.truncation") ?? "last"),
+			RECEIPT_LINES: String(this.session.settings.get("read.receiptBudgetLines")),
+			RECEIPT_KIB: String(this.session.settings.get("read.receiptBudgetBytes")),
 			IS_HL_MODE: displayMode.hashLines,
 			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
 		});
@@ -833,6 +1548,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			sourcePath?: string;
 			spillEligible?: boolean;
 			receiptPath?: string;
+			bodyFooterPath?: string;
 			sourceUrl?: string;
 			sourceInternal?: string;
 			entityLabel: string;
@@ -841,19 +1557,21 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			raw?: boolean;
 			immutable?: boolean;
 			wrapUntrusted?: boolean;
+			truncationDirection?: TruncationDirection;
+			/** Truncation metadata stays relative to the selected body, not a protected prefix. */
+			truncationMetadataBodyRelative?: boolean;
+			/** Preserve this leading URL preamble while truncating only the selected body. */
+			protectedPrefixChars?: number;
+			cacheLinesFor?: string;
 		},
 	): AgentToolResult<ReadToolDetails> {
 		const displayMode = resolveFileDisplayMode(this.session, { raw: options.raw, immutable: options.immutable });
 		const details = options.details ?? {};
 		const allLines = text.split("\n");
 		const totalLines = allLines.length;
-		// User-requested 0-indexed range start. Lines BEFORE this are leading
-		// context (added below if offset is explicit).
 		const requestedStart = offset ? Math.max(0, offset - 1) : 0;
 		const ignoreResultLimits = options.ignoreResultLimits ?? false;
 		const requestedEnd = limit !== undefined ? Math.min(requestedStart + limit, allLines.length) : allLines.length;
-		// Expand only on sides the user actually constrained: leading context
-		// when offset>1, trailing context when a finite limit was set.
 		const expanded = expandRangeWithContext(
 			requestedStart,
 			requestedEnd,
@@ -862,19 +1580,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			limit !== undefined,
 		);
 		const startLine = expanded.startLine;
-		const endLineExpanded = expanded.endLine;
+		const endLine = expanded.endLine;
 		const startLineDisplay = startLine + 1;
 
 		const resultBuilder = toolResult(details);
-		if (options.sourcePath) {
-			resultBuilder.sourcePath(options.sourcePath);
-		}
-		if (options.sourceUrl) {
-			resultBuilder.sourceUrl(options.sourceUrl);
-		}
-		if (options.sourceInternal) {
-			resultBuilder.sourceInternal(options.sourceInternal);
-		}
+		if (options.sourcePath) resultBuilder.sourcePath(options.sourcePath);
+		if (options.sourceUrl) resultBuilder.sourceUrl(options.sourceUrl);
+		if (options.sourceInternal) resultBuilder.sourceInternal(options.sourceInternal);
 
 		if (requestedStart >= allLines.length) {
 			const suggestion =
@@ -888,92 +1600,217 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				.done();
 		}
 
-		const endLine = endLineExpanded;
-		let selectedContent = allLines.slice(startLine, endLine).join("\n");
-
-		if (options.receiptPath) {
-			const budgetLines = this.session.settings.get("read.receiptBudgetLines");
-			const budgetBytes = this.session.settings.get("read.receiptBudgetBytes") * 1024;
-			const receiptLines: string[] = [];
-			let bytes = 0;
-			for (const line of allLines) {
-				const lineBytes = Buffer.byteLength(line, "utf-8") + (receiptLines.length > 0 ? 1 : 0);
-				if (receiptLines.length >= budgetLines || bytes + lineBytes > budgetBytes) break;
-				receiptLines.push(line);
-				bytes += lineBytes;
-			}
-			selectedContent = receiptLines.join("\n");
-		}
-		const userLimitedLines = limit !== undefined ? endLine - startLine : undefined;
-		const truncation = ignoreResultLimits
-			? noTruncResult(selectedContent)
-			: truncateHead(
-					selectedContent,
-					options.resultByteCeiling === undefined
-						? undefined
-						: { maxBytes: options.resultByteCeiling, maxLines: Number.MAX_SAFE_INTEGER },
+		const direction = options.truncationDirection ?? "head";
+		const receipt = options.receiptPath !== undefined;
+		const exposeReceiptHeadMeta = receipt && options.cacheLinesFor !== undefined;
+		const bodyFooterPath = options.receiptPath ?? options.bodyFooterPath;
+		const preservePrefix =
+			direction !== "head" && options.protectedPrefixChars !== undefined && options.protectedPrefixChars > 0;
+		const protectedPrefix = preservePrefix ? text.slice(0, options.protectedPrefixChars) : "";
+		const protectedPrefixLines = preservePrefix ? protectedPrefix.split("\n").length - 1 : 0;
+		const rangeStart = preservePrefix ? Math.max(startLine, protectedPrefixLines) : startLine;
+
+		const rangeLines = allLines.slice(rangeStart, endLine);
+		const rangeText = rangeLines.join("\n");
+		const budgetLines = receipt
+			? this.session.settings.get("read.receiptBudgetLines")
+			: options.resultByteCeiling === undefined
+				? DEFAULT_MAX_LINES
+				: Number.MAX_SAFE_INTEGER;
+		const budgetBytes = receipt
+			? this.session.settings.get("read.receiptBudgetBytes") * 1024
+			: (options.resultByteCeiling ?? DEFAULT_MAX_BYTES);
+		const relativeWindow = ignoreResultLimits
+			? fullReadWindow(rangeText, rangeLines.length, Buffer.byteLength(rangeText, "utf-8"))
+			: selectReadWindow(
+					receipt ? text : rangeText,
+					receipt ? allLines : rangeLines,
+					direction,
+					budgetLines,
+					budgetBytes,
 				);
-
+		// A directional head window cannot render anything when its first source line
+		// exceeds the byte budget. Fall back to the historical head truncator so ACP
+		// still emits the same UTF-8 preview and metadata as the pre-direction code.
+		const oversizedHeadWindow =
+			!receipt &&
+			direction === "head" &&
+			options.resultByteCeiling === undefined &&
+			relativeWindow.kind === "head-only" &&
+			relativeWindow.head === undefined;
+		const legacyHeadByteCeiling = options.resultByteCeiling ?? (oversizedHeadWindow ? budgetBytes : undefined);
+		const window = rebaseWindow(relativeWindow, receipt ? 0 : rangeStart);
+		// Keep explicit ranges in the selected-window coordinate system for truncation metadata.
+		// Rendered output still uses `window`, whose anchors retain absolute file line numbers.
+		const metadataWindow =
+			options.truncationMetadataBodyRelative || (offset !== undefined && direction !== "head")
+				? relativeWindow
+				: window;
+		const metadataRangeBase =
+			options.truncationMetadataBodyRelative || (offset !== undefined && direction !== "head")
+				? "window"
+				: undefined;
 		const shouldAddHashLines = displayMode.hashLines;
-		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
-		const formatText = (content: string, startNum: number): string => {
-			details.displayContent = { text: content, startLine: startNum };
-			return formatTextWithMode(content, startNum, shouldAddHashLines, shouldAddLineNumbers);
+		const shouldAddLineNumbers = !shouldAddHashLines && displayMode.lineNumbers;
+		const maxColumns = options.raw ? 0 : resolveOutputMaxColumns(this.session.settings);
+		const bodyRawWindow = renderReadWindow(window, false, false, maxColumns);
+		const bodyRenderedWindow = renderReadWindow(window, shouldAddHashLines, shouldAddLineNumbers, maxColumns);
+		const rawWindow = preservePrefix ? `${protectedPrefix}${bodyRawWindow}` : bodyRawWindow;
+		const renderedWindow = preservePrefix ? `${protectedPrefix}${bodyRenderedWindow}` : bodyRenderedWindow;
+		const partialTail = partialTailOf(window);
+		const partialTailWarning = partialTail !== undefined && shouldAddHashLines && bodyFooterPath !== undefined;
+		if (partialTailWarning) {
+			Object.defineProperty(metadataWindow, "outputLinesOverride", { value: 0, enumerable: false });
+			Object.defineProperty(metadataWindow, "outputBytesOverride", { value: 0, enumerable: false });
+		}
+		const selectedContent = windowSegments(window)
+			.map(segment => segment.content)
+			.join("\n");
+		details.displayContent = {
+			text: rawWindow,
+			startLine: preservePrefix
+				? 1
+				: (window.head?.origin.startLine ?? window.tail?.origin.startLine ?? startLineDisplay),
 		};
 
-		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);
-
-			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.]`;
+		let usedLegacyHeadTruncation = false;
+		let outputText = partialTailWarning
+			? formatOversizedLineWarning(
+					bodyFooterPath!,
+					partialTail!.origin.startLine,
+					partialTail!.sourceLineBytes,
+					budgetBytes,
+					totalLines,
+				)
+			: renderedWindow;
+		let truncationResult: TruncationResult | undefined;
+		if (window.kind !== "full" && (!receipt || direction !== "head" || exposeReceiptHeadMeta)) {
+			const windowResult = makeWindowResult(metadataWindow, selectedContent);
+			const baseTruncation =
+				!receipt && direction === "head"
+					? {
+							...windowResult,
+							truncated: true,
+						}
+					: windowResult;
+			truncationResult = partialTailWarning
+				? { ...baseTruncation, outputLines: 0, outputBytes: 0, lastLineExceedsLimit: true }
+				: baseTruncation;
+			details.truncation = truncationResult;
+		}
+
+		// Preserve the historical head byte-cap oversized-line behavior. The
+		// directional window model is used for tail/both; head remains the old
+		// oracle so existing hashline and snippet contracts stay byte-identical.
+		if (!receipt && direction === "head" && legacyHeadByteCeiling !== undefined) {
+			const legacy = truncateHead(rangeText, {
+				maxBytes: legacyHeadByteCeiling,
+				maxLines: Number.MAX_SAFE_INTEGER,
+			});
+			truncationResult = legacy;
+			usedLegacyHeadTruncation = legacy.truncated === true;
+			details.truncation = legacy.truncated ? legacy : undefined;
+			if (legacy.firstLineExceedsLimit) {
+				const firstLine = allLines[startLine] ?? "";
+				const firstLineBytes = Buffer.byteLength(firstLine, "utf-8");
+				const snippet = truncateHeadBytes(firstLine, legacyHeadByteCeiling);
+				if (shouldAddHashLines) {
+					outputText = `[Line ${startLineDisplay} is ${formatBytes(firstLineBytes)}, exceeds ${formatBytes(legacyHeadByteCeiling)} limit. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`;
+				} else {
+					outputText = formatTextWithMode(snippet.text, startLineDisplay, false, shouldAddLineNumbers);
+				}
+				if (snippet.text.length === 0) {
+					outputText = `[Line ${startLineDisplay} is ${formatBytes(firstLineBytes)}, exceeds ${formatBytes(legacyHeadByteCeiling)} limit. Unable to display a valid UTF-8 snippet.]`;
+				}
+				details.displayContent = { text: snippet.text, startLine: startLineDisplay };
+			} else if (legacy.truncated) {
+				outputText = formatTextWithMode(legacy.content, startLineDisplay, shouldAddHashLines, shouldAddLineNumbers);
 			} else {
-				outputText = formatText(snippet.text, startLineDisplay);
+				outputText = formatTextWithMode(rangeText, startLineDisplay, shouldAddHashLines, shouldAddLineNumbers);
 			}
+		}
 
-			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.]`;
+		const userLimitedLines = limit !== undefined ? endLine - startLine : undefined;
+		if (bodyFooterPath !== undefined && window.kind !== "full" && !partialTailWarning) {
+			// A head window only owns a body footer on the historical receipt paths.
+			// Archive members and internal URLs reach here through `bodyFooterPath`
+			// alone; adding a head footer there would emit a second notice beside the
+			// wrapper's, changing output that must stay byte-identical when the
+			// direction is rolled back to head.
+			const footer =
+				direction === "head"
+					? receipt
+						? formatReceiptFooter(
+								bodyFooterPath,
+								metadataWindow.head?.lines ?? 0,
+								metadataWindow.totalLines,
+								windowSegments(metadataWindow).reduce((sum, segment) => sum + segment.bytes, 0),
+							)
+						: undefined
+					: formatDirectionalFooter(bodyFooterPath, metadataWindow);
+			if (footer) {
+				outputText += `\n\n${footer}`;
+				if (direction !== "head") rememberBodyTruncationFooter(details, footer);
 			}
-
-			details.truncation = truncation;
-			truncationInfo = {
-				result: truncation,
-				options: { direction: "head", startLine: startLineDisplay, totalFileLines: totalLines },
-			};
-		} else if (truncation.truncated) {
-			outputText = formatText(truncation.content, startLineDisplay);
-			details.truncation = truncation;
-			truncationInfo = {
-				result: truncation,
-				options: { direction: "head", startLine: startLineDisplay, totalFileLines: totalLines },
-			};
-		} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
+		} else if (
+			!receipt &&
+			window.kind === "full" &&
+			userLimitedLines !== undefined &&
+			startLine + userLimitedLines < allLines.length
+		) {
 			const remaining = allLines.length - (startLine + userLimitedLines);
 			const nextOffset = startLine + userLimitedLines + 1;
-
-			outputText = formatText(selectedContent, startLineDisplay);
 			outputText += `\n\n[${remaining} more lines in ${options.entityLabel}. Use :${nextOffset} to continue]`;
-		} else {
-			outputText = formatText(truncation.content, startLineDisplay);
-		}
-		if (options.receiptPath && (truncation.truncated || countTextLines(selectedContent) < totalLines)) {
-			outputText += `\n\n${formatReceiptFooter(options.receiptPath, countTextLines(selectedContent), totalLines, Buffer.byteLength(selectedContent, "utf-8"))}`;
 		}
 
-		details.spillEligible = options.spillEligible === true && selectedContent.length > 0;
+		details.spillEligible =
+			options.spillEligible === true && selectedContent.length > 0 && !windowHasPartialSegment(window);
+		if (options.cacheLinesFor && !windowHasPartialSegment(window)) {
+			for (const segment of windowSegments(window)) {
+				if (segment.kind === "lines" && segment.lines > 0) {
+					getFileReadCache(this.session).recordContiguous(
+						options.cacheLinesFor,
+						segment.origin.startLine,
+						linesOfSegment(segment),
+					);
+				}
+			}
+		}
 		resultBuilder.text(options.wrapUntrusted ? wrapUntrustedContent(outputText) : outputText);
-		if (truncationInfo) {
-			resultBuilder.truncation(truncationInfo.result, truncationInfo.options);
+		if (window.kind !== "full" && (!receipt || direction !== "head" || exposeReceiptHeadMeta)) {
+			const receiptHead = receipt && direction === "head";
+			if (receiptHead && truncationResult?.truncated) {
+				const diskLike = {
+					...truncationResult,
+					totalBytes: Buffer.byteLength(selectedContent, "utf-8"),
+				};
+				resultBuilder.truncation(diskLike, {
+					direction: "head",
+					startLine: startLineDisplay,
+					totalFileLines: totalLines,
+				});
+			} else if (usedLegacyHeadTruncation && truncationResult?.truncated) {
+				resultBuilder.truncation(truncationResult, {
+					direction: "head",
+					startLine: startLineDisplay,
+					totalFileLines: totalLines,
+				});
+			} else {
+				// Only a directional window moves notice ownership into the body: its
+				// footer names the kept range and the re-read path. A head window keeps
+				// the wrapper notice, which carries the `:N to continue` hint instead.
+				resultBuilder.truncationWindows(metadataWindow, {
+					noticeOwner: bodyFooterPath !== undefined && direction !== "head" ? "body" : undefined,
+					maxBytes: direction === "head" ? undefined : budgetBytes,
+					rangeBase: metadataRangeBase,
+				});
+			}
+		} else if (truncationResult?.truncated) {
+			resultBuilder.truncation(truncationResult, {
+				direction: "head",
+				startLine: startLineDisplay,
+				totalFileLines: totalLines,
+			});
 		}
 		return resultBuilder.done();
 	}
@@ -996,6 +1833,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			entityLabel: string;
 			raw?: boolean;
 			immutable?: boolean;
+			truncationDirection?: TruncationDirection;
+			cacheLinesFor?: string;
 		},
 	): AgentToolResult<ReadToolDetails> {
 		const displayMode = resolveFileDisplayMode(this.session, { raw: options.raw, immutable: options.immutable });
@@ -1004,13 +1843,54 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const totalLines = allLines.length;
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
+		const maxColumns = resolveOutputMaxColumns(this.session.settings);
+		const direction = options.truncationDirection ?? "head";
+		let columnTruncated = 0;
 
 		const resultBuilder = toolResult(details);
 		if (options.sourcePath) resultBuilder.sourcePath(options.sourcePath);
 		if (options.sourceUrl) resultBuilder.sourceUrl(options.sourceUrl);
 		if (options.sourceInternal) resultBuilder.sourceInternal(options.sourceInternal);
 
+		const renderBlockWindow = (
+			window: ReadWindow,
+		): { text: string; partialTail?: Extract<ReadSegment, { kind: "partial-line" }> } => {
+			const renderSegment = (segment: ReadSegment): string => {
+				const hash = shouldAddHashLines && segment.kind === "lines";
+				// A partial line is a byte suffix, not a complete source line. Never
+				// give it an anchor that could make the preview look fully readable.
+				const numbers = !hash && shouldAddLineNumbers && segment.kind === "lines";
+				const renderContent =
+					!options.raw && !hash && maxColumns > 0
+						? segment.content
+								.split("\n")
+								.map(line => {
+									const result = truncateLine(line, maxColumns);
+									if (result.wasTruncated) columnTruncated = maxColumns;
+									return result.text;
+								})
+								.join("\n")
+						: segment.content;
+				return formatTextWithMode(renderContent, segment.origin.startLine, hash, numbers);
+			};
+			let text = "";
+			if (window.kind === "full") text = window.head ? renderSegment(window.head) : "";
+			else if (window.kind === "head-only") text = window.head ? renderSegment(window.head) : "";
+			else if (window.kind === "tail-only") text = window.tail ? renderSegment(window.tail) : "";
+			else {
+				const marker = formatMiddleElisionMarker(window.elidedLines, window.elidedBytes);
+				if (window.head && window.tail) {
+					text =
+						window.elidedLines <= 0
+							? `${renderSegment(window.head)}\n${renderSegment(window.tail)}`
+							: `${renderSegment(window.head)}\n${marker}\n${renderSegment(window.tail)}`;
+				}
+			}
+			return { text, partialTail: partialTailOf(window) };
+		};
+
 		const parts: string[] = [];
+		let hasPartialSegment = false;
 		const outOfBounds: LineRange[] = [];
 		for (const range of ranges) {
 			if (range.startLine > totalLines) {
@@ -1018,8 +1898,41 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				continue;
 			}
 			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 blockLines = allLines.slice(range.startLine - 1, effectiveEnd);
+			const blockText = blockLines.join("\n");
+			const requestedLength = range.endLine !== undefined ? range.endLine - range.startLine + 1 : this.#defaultLimit;
+			const blockMaxLines = Math.min(requestedLength, DEFAULT_MAX_LINES);
+			const blockMaxBytes = Math.max(DEFAULT_MAX_BYTES, blockMaxLines * 512);
+			const relative = selectReadWindow(blockText, blockLines, direction, blockMaxLines, blockMaxBytes);
+			const window = rebaseWindow(relative, range.startLine - 1);
+			hasPartialSegment ||= windowHasPartialSegment(window);
+			const rendered = renderBlockWindow(window);
+			let blockOutput = rendered.text;
+			if (rendered.partialTail) {
+				const disclosurePath =
+					options.sourceInternal ?? options.sourceUrl ?? options.sourcePath ?? options.entityLabel;
+				blockOutput = shouldAddHashLines
+					? formatOversizedLineWarning(
+							disclosurePath,
+							rendered.partialTail.origin.startLine,
+							rendered.partialTail.sourceLineBytes,
+							blockMaxBytes,
+							totalLines,
+						)
+					: `${blockOutput}\n\n${formatDirectionalFooter(disclosurePath, window)}`;
+			}
+			parts.push(blockOutput);
+			if (options.cacheLinesFor && !windowHasPartialSegment(window)) {
+				for (const segment of windowSegments(window)) {
+					if (segment.kind === "lines" && segment.lines > 0) {
+						getFileReadCache(this.session).recordContiguous(
+							options.cacheLinesFor,
+							segment.origin.startLine,
+							linesOfSegment(segment),
+						);
+					}
+				}
+			}
 		}
 
 		const outputText = parts.length > 0 ? parts.join("\n\n…\n\n") : "";
@@ -1030,9 +1943,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 		const finalText =
 			notices.length > 0 ? (outputText ? `${outputText}\n${notices.join("\n")}` : notices.join("\n")) : outputText;
-		details.spillEligible = parts.length > 0;
-
+		details.spillEligible = parts.length > 0 && !hasPartialSegment;
 		resultBuilder.text(finalText);
+		if (columnTruncated > 0) resultBuilder.limits({ columnMax: columnTruncated });
 		return resultBuilder.done();
 	}
 
@@ -1049,6 +1962,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		displayMode: { hashLines: boolean; lineNumbers: boolean },
 		suffixResolution: { from: string; to: string } | undefined,
 		signal: AbortSignal | undefined,
+		direction: TruncationDirection,
 	): Promise<{
 		outputText: string;
 		contentLineCount: number;
@@ -1067,6 +1981,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					sourcePath: absolutePath,
 					entityLabel: "file",
 					raw: rawSelector,
+					truncationDirection: direction,
+					cacheLinesFor: absolutePath,
 				});
 				if (suffixResolution) {
 					const notice = `[Path '${suffixResolution.from}' not found; resolved to '${suffixResolution.to}' via suffix match]`;
@@ -1079,6 +1995,27 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 		}
 
+		// The legacy stream collector remains the head/default implementation.
+		// Directional multi-range reads use the same materialized window oracle as
+		// ACP so each block has identical bytes, anchors, and cache entries.
+		if (direction !== "head") {
+			const diskText = await Bun.file(absolutePath).text();
+			const result = this.#buildInMemoryMultiRangeResult(diskText, ranges, {
+				details: { resolvedPath: absolutePath, suffixResolution },
+				sourcePath: absolutePath,
+				entityLabel: "file",
+				raw: rawSelector,
+				truncationDirection: direction,
+				cacheLinesFor: absolutePath,
+			});
+			const firstText = result.content.find((content): content is TextContent => content.type === "text");
+			if (suffixResolution && firstText) {
+				const notice = `[Path '${suffixResolution.from}' not found; resolved to '${suffixResolution.to}' via suffix match]`;
+				firstText.text = `${notice}\n${firstText.text}`;
+			}
+			return { outputText: "", contentLineCount: 0, columnTruncated: 0, bridgeResult: result };
+		}
+
 		const shouldAddHashLines = !rawSelector && displayMode.hashLines;
 		const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
 		const maxColumns = resolveOutputMaxColumns(this.session.settings);
@@ -1111,6 +2048,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 
 			const collectedLines = streamResult.lines;
+			const cacheLines = collectedLines.slice();
 			if (!rawSelector && !shouldAddHashLines && maxColumns > 0) {
 				for (let i = 0; i < collectedLines.length; i++) {
 					const { text, wasTruncated } = truncateLine(collectedLines[i], maxColumns);
@@ -1122,8 +2060,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 
 			contentLineCount += collectedLines.length;
-			if (collectedLines.length > 0) {
-				getFileReadCache(this.session).recordContiguous(absolutePath, range.startLine, collectedLines);
+			if (cacheLines.length > 0) {
+				getFileReadCache(this.session).recordContiguous(absolutePath, range.startLine, cacheLines);
 			}
 
 			const blockText = collectedLines.join("\n");
@@ -1143,6 +2081,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		subPath: string,
 		limit: number | undefined,
 		details: ReadToolDetails,
+		direction: TruncationDirection,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		const DEFAULT_LIMIT = 500;
@@ -1166,14 +2105,21 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 
 		const output = results.length > 0 ? results.join("\n") : "(empty archive directory)";
-		const text = prependSuffixResolutionNotice(output, details.suffixResolution);
-		const truncation = truncateHead(text, { maxLines: Number.MAX_SAFE_INTEGER });
-		const directoryDetails: ReadToolDetails = { ...details, isDirectory: true };
-		const resultBuilder = toolResult<ReadToolDetails>(directoryDetails).text(truncation.content);
+		const window = selectReadWindow(output, results, direction, Number.MAX_SAFE_INTEGER, DEFAULT_MAX_BYTES);
+		const rendered = prependSuffixResolutionNotice(renderReadWindow(window, false, false), details.suffixResolution);
+		const directoryDetails: ReadToolDetails = {
+			...details,
+			isDirectory: true,
+			...(window.kind !== "full" ? { truncation: makeWindowResult(window, output) } : {}),
+		};
+		const resultBuilder = toolResult<ReadToolDetails>(directoryDetails).text(rendered);
 		resultBuilder.sourcePath(archivePath).limits({ resultLimit: limitMeta.resultLimit?.reached });
-		if (truncation.truncated) {
-			directoryDetails.truncation = truncation;
-			resultBuilder.truncation(truncation, { direction: "head" });
+		if (window.kind !== "full") {
+			if (direction === "head") {
+				resultBuilder.truncation(makeWindowResult(window, output), { direction: "head" });
+			} else {
+				resultBuilder.truncationWindows(window, { maxBytes: DEFAULT_MAX_BYTES });
+			}
 		}
 		return resultBuilder.done();
 	}
@@ -1183,6 +2129,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		parsedSel: ParsedSelector,
 		resolvedArchivePath: ResolvedArchiveReadPath,
 		signal?: AbortSignal,
+		truncationParam?: TruncationDirection,
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		throwIfAborted(signal);
 		const archive = await openArchive(resolvedArchivePath.absolutePath);
@@ -1197,6 +2144,14 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		if (!node) {
 			throw new ToolError(`Path '${readPath}' not found inside archive`);
 		}
+		const route: ReadRoute = node.isDirectory
+			? "dir-archive"
+			: isMultiRange(parsedSel)
+				? "local-multi-range"
+				: parsedSel.kind === "none"
+					? "archive-member-bare"
+					: "local-range";
+		const direction = resolveEffectiveDirection(truncationParam, route, this.session.settings);
 
 		if (node.isDirectory) {
 			if (isMultiRange(parsedSel)) {
@@ -1209,12 +2164,16 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				resolvedArchivePath.archiveSubPath,
 				limit,
 				details,
+				direction,
 				signal,
 			);
 		}
 
 		const entry = await archive.readFile(resolvedArchivePath.archiveSubPath);
 		const text = decodeUtf8Text(entry.bytes);
+		if (text === null && truncationParam !== undefined && truncationParam !== "head") {
+			throw new ToolError("Explicit truncation for binary archive entries is not yet supported.");
+		}
 		if (text === null) {
 			return toolResult<ReadToolDetails>(details)
 				.text(
@@ -1235,6 +2194,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						sourcePath: resolvedArchivePath.absolutePath,
 						entityLabel: "archive entry",
 						raw,
+						truncationDirection: direction,
 					})
 				: this.#buildInMemoryTextResult(
 						text,
@@ -1245,6 +2205,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 							sourcePath: resolvedArchivePath.absolutePath,
 							entityLabel: "archive entry",
 							raw,
+							truncationDirection: direction,
+							bodyFooterPath: parsedSel.kind === "none" ? readPath : undefined,
 						},
 					);
 		const firstText = result.content.find((content): content is TextContent => content.type === "text");
@@ -1257,6 +2219,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	async #readSqlite(
 		resolvedSqlitePath: ResolvedSqliteReadPath,
 		signal?: AbortSignal,
+		truncationParam?: TruncationDirection,
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		throwIfAborted(signal);
 
@@ -1269,6 +2232,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			resolvedPath: resolvedSqlitePath.absolutePath,
 			suffixResolution: resolvedSqlitePath.suffixResolution,
 		};
+		const sqliteRoute: ReadRoute = selector.kind === "list" ? "sqlite-list" : "sqlite-rows";
+		const direction = resolveEffectiveDirection(truncationParam, sqliteRoute, this.session.settings);
+		// SQLite row/schema/query/raw selectors are row-selection routes: queryRows and
+		// executeReadQuery apply their SQL row limits, while renderRow/renderTable only
+		// cap individual cell width. No rendered-output truncator runs on these paths.
+		// Keep explicit direction as a deliberate no-op there; sqlite-list below
+		// truncates only its rendered table listing.
 
 		let db: Database | null = null;
 		try {
@@ -1280,18 +2250,29 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			switch (selector.kind) {
 				case "list": {
 					const listLimit = applyListLimit(listTables(db), { limit: 500 });
-					const output = prependSuffixResolutionNotice(
-						renderTableList(listLimit.items),
+					const body = renderTableList(listLimit.items);
+					const window = selectReadWindow(
+						body,
+						body.split("\n"),
+						direction,
+						Number.MAX_SAFE_INTEGER,
+						DEFAULT_MAX_BYTES,
+					);
+					const rendered = prependSuffixResolutionNotice(
+						renderReadWindow(window, false, false),
 						resolvedSqlitePath.suffixResolution,
 					);
-					const truncation = truncateHead(output, { maxLines: Number.MAX_SAFE_INTEGER });
-					details.truncation = truncation.truncated ? truncation : undefined;
+					details.truncation = window.kind !== "full" ? makeWindowResult(window, body) : undefined;
 					const resultBuilder = toolResult<ReadToolDetails>(details)
-						.text(truncation.content)
+						.text(rendered)
 						.sourcePath(resolvedSqlitePath.absolutePath)
 						.limits({ resultLimit: listLimit.meta.resultLimit?.reached });
-					if (truncation.truncated) {
-						resultBuilder.truncation(truncation, { direction: "head" });
+					if (window.kind !== "full") {
+						if (direction === "head") {
+							resultBuilder.truncation(makeWindowResult(window, body), { direction: "head" });
+						} else {
+							resultBuilder.truncationWindows(window, { maxBytes: DEFAULT_MAX_BYTES });
+						}
 					}
 					return resultBuilder.done();
 				}
@@ -1553,6 +2534,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					"Reading `conflict://*` is not supported — wildcards are write-only. Use the `<path>:conflicts` read selector for the full list of conflicts in a file, or read `conflict://<N>` to inspect a single block.",
 				);
 			}
+			if (params.truncation !== undefined && params.truncation !== "head") {
+				throw new ToolError("Explicit truncation for conflict:// regions is not yet supported.");
+			}
 			return this.#readConflictRegion(conflictUri.id, conflictUri.scope);
 		}
 		const displayMode = resolveFileDisplayMode(this.session);
@@ -1572,15 +2556,36 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						preferCached: true,
 					},
 				);
-				return this.#buildInMemoryTextResult(cached.output, parsedUrlTarget.offset, parsedUrlTarget.limit, {
+				const requestedDirection = resolveEffectiveDirection(
+					params.truncation,
+					"url-cache-page",
+					this.session.settings,
+				);
+				const direction =
+					requestedDirection !== "head" && cached.wrappedPreambleChars === undefined ? "head" : requestedDirection;
+				const selectorInput = prepareReadUrlSelectorInput(
+					cached.output,
+					cached.preambleChars,
+					cached.wrappedPreambleChars,
+				);
+
+				return this.#buildInMemoryTextResult(selectorInput.text, parsedUrlTarget.offset, parsedUrlTarget.limit, {
 					details: { ...cached.details },
 					sourceUrl: cached.details.finalUrl,
 					entityLabel: "URL output",
 					immutable: true,
 					wrapUntrusted: true,
+					truncationDirection: direction,
+					protectedPrefixChars: selectorInput.preambleChars,
+					truncationMetadataBodyRelative: true,
 				});
 			}
-			return executeReadUrl(this.session, { path: parsedUrlTarget.path, raw: parsedUrlTarget.raw }, signal);
+			return executeReadUrl(
+				this.session,
+				{ path: parsedUrlTarget.path, raw: parsedUrlTarget.raw },
+				signal,
+				resolveEffectiveDirection(params.truncation, "url-reader", this.session.settings),
+			);
 		}
 
 		// Handle internal URLs (agent://, artifact://, memory://, rule://, local://, gjc://, issue://, pr://).
@@ -1595,7 +2600,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (internalTarget.sel !== undefined && parsed.kind === "none") {
 				throw new ToolError(`Invalid internal URL selector "${internalTarget.sel}".`);
 			}
-			return this.#handleInternalUrl(internalTarget.path, parsed, signal);
+			return this.#handleInternalUrl(internalTarget.path, parsed, signal, params.truncation);
 		}
 
 		const archivePath = await this.#resolveArchiveReadPath(readPath, signal);
@@ -1607,12 +2612,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				archiveParsed,
 				{ ...archivePath, archiveSubPath: archiveSubPath.path },
 				signal,
+				params.truncation,
 			);
 		}
 
 		const sqlitePath = await this.#resolveSqliteReadPath(readPath, signal);
 		if (sqlitePath) {
-			return this.#readSqlite(sqlitePath, signal);
+			return this.#readSqlite(sqlitePath, signal, params.truncation);
 		}
 
 		const localTarget = splitPathAndSel(readPath);
@@ -1658,7 +2664,14 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (isMultiRange(parsed)) {
 				throw new ToolError("Multi-range line selectors are not supported for directory listings.");
 			}
-			const dirResult = await this.#readDirectory(absolutePath, selToOffsetLimit(parsed).limit, signal);
+			const dirDirection = resolveEffectiveDirection(params.truncation, "dir-local", this.session.settings);
+			const dirResult = await this.#readDirectory(
+				absolutePath,
+				selToOffsetLimit(parsed).limit,
+				dirDirection,
+				signal,
+			);
+
 			if (suffixResolution) {
 				dirResult.details ??= {};
 				dirResult.details.suffixResolution = suffixResolution;
@@ -1667,7 +2680,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 
 		if (parsed.kind === "conflicts") {
-			return this.#readFileConflicts(absolutePath, suffixResolution, signal);
+			return this.#readFileConflicts(absolutePath, suffixResolution, signal, params.truncation);
 		}
 
 		const imageMetadata = await readImageMetadata(absolutePath);
@@ -1680,10 +2693,25 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		let sourcePath: string | undefined;
 		let columnTruncated = 0;
 		let truncationInfo:
-			| { result: TruncationResult; options: { direction: "head"; startLine?: number; totalFileLines?: number } }
+			| {
+					result: TruncationResult;
+					options: {
+						direction: "head";
+						startLine?: number;
+						totalFileLines?: number;
+						noticeOwner?: "body";
+						maxBytes?: number;
+					};
+			  }
 			| undefined;
+		let directionalWindow: ReadWindow | undefined;
+		let directionalNoticeOwner: "body" | undefined;
+		let directionalRangeBase: "file" | "window" | undefined;
 
 		if (mimeType) {
+			if (params.truncation !== undefined && params.truncation !== "head") {
+				throw new ToolError("Explicit truncation for image reads is not yet supported.");
+			}
 			if (fileSize > MAX_IMAGE_SIZE) {
 				const sizeStr = formatBytes(fileSize);
 				const maxStr = formatBytes(MAX_IMAGE_SIZE);
@@ -1715,11 +2743,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 		} else if (isNotebookPath(absolutePath) && !isRawSelector(parsed)) {
 			const notebookText = await readEditableNotebookText(absolutePath, localReadPath);
+			const direction = resolveEffectiveDirection(params.truncation, "converted", this.session.settings);
 			if (isMultiRange(parsed) && parsed.kind === "lines") {
 				return this.#buildInMemoryMultiRangeResult(notebookText, parsed.ranges, {
 					details: { resolvedPath: absolutePath },
 					sourcePath: absolutePath,
 					entityLabel: "notebook",
+					truncationDirection: direction,
 				});
 			}
 			const { offset, limit } = selToOffsetLimit(parsed);
@@ -1736,10 +2766,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 							)
 						: undefined,
 				receiptPath: parsed.kind === "none" ? localReadPath : undefined,
+				truncationDirection: direction,
 			});
 		} else if (shouldConvertWithMarkit) {
 			const result = await convertFileWithMarkit(absolutePath, signal);
 			if (result.ok) {
+				const direction = resolveEffectiveDirection(params.truncation, "converted", this.session.settings);
 				const { offset, limit } = selToOffsetLimit(parsed);
 				return this.#buildInMemoryTextResult(result.content, offset, limit, {
 					details: { resolvedPath: absolutePath },
@@ -1755,6 +2787,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 								)
 							: undefined,
 					receiptPath: parsed.kind === "none" ? localReadPath : undefined,
+					truncationDirection: direction,
 				});
 			}
 			content = [{ type: "text", text: `[Cannot read ${ext} file: ${result.error || "conversion failed"}]` }];
@@ -1766,6 +2799,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				(this.session.settings.get("read.summarize.prose") || !PROSE_SUMMARY_EXTENSIONS.has(ext))
 			) {
 				const summary = await this.#trySummarize(absolutePath, fileSize, signal);
+				if (params.truncation !== undefined && params.truncation !== "head" && summary?.parsed) {
+					throw new ToolError(
+						"Explicit truncation for structural summaries is not yet supported; summary direction will be applied after summary units become directional.",
+					);
+				}
 				if (summary?.parsed && summary.elided) {
 					const renderedSummary = this.#renderSummary(summary);
 					const footer = formatSummaryElisionFooter(
@@ -1804,6 +2842,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 			if (!content) {
 				if (isMultiRange(parsed) && parsed.kind === "lines") {
+					const multiDirection = resolveEffectiveDirection(
+						params.truncation,
+						"local-multi-range",
+						this.session.settings,
+					);
 					const multiResult = await this.#readLocalFileMultiRange(
 						absolutePath,
 						parsed.ranges,
@@ -1811,6 +2854,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						displayMode,
 						suffixResolution,
 						signal,
+						multiDirection,
 					);
 					if (multiResult.bridgeResult) return multiResult.bridgeResult;
 					content = [{ type: "text", text: multiResult.outputText }];
@@ -1822,6 +2866,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				} else {
 					// Raw text or line-range mode
 					const { offset, limit } = selToOffsetLimit(parsed);
+					const bareEligible = parsed.kind === "none";
+					const localDirection = resolveEffectiveDirection(
+						params.truncation,
+						bareEligible ? "local-bare-stream" : isRawSelector(parsed) ? "local-raw" : "local-range",
+						this.session.settings,
+					);
 					// Try ACP bridge first — editor's in-memory buffer is source of truth.
 					// Request full text so local range rendering keeps normal context and line numbers.
 					const bridgePromise = this.#routeReadThroughBridge(absolutePath);
@@ -1833,6 +2883,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 								sourcePath: absolutePath,
 								entityLabel: "file",
 								raw: isRawSelector(parsed),
+								cacheLinesFor: absolutePath,
+								truncationDirection: localDirection,
 							});
 							if (suffixResolution) {
 								const notice = `[Path '${suffixResolution.from}' not found; resolved to '${suffixResolution.to}' via suffix match]`;
@@ -1874,6 +2926,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						: isBareReceipt
 							? receiptBudgetBytes
 							: Math.max(DEFAULT_MAX_BYTES, maxLinesToCollect * 512);
+					const collectMode = localDirection === "head" ? "head" : localDirection === "last" ? "tail" : "both";
+					const collectEndExclusive =
+						rawSelector || isBareReceipt ? null : startLine + effectiveLimit + leadingContext + trailingContext;
 
 					const streamResult = await streamLinesFromFile(
 						absolutePath,
@@ -1882,6 +2937,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						maxBytesForRead,
 						selectedLineLimit,
 						signal,
+						collectMode,
+						collectEndExclusive,
 					);
 
 					const {
@@ -1906,148 +2963,295 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 							.done();
 					}
 
-					// Per-line column cap. Skipped in raw mode so `:raw` always returns
-					// verbatim bytes for paste-back-into-tool workflows. Total byte/line
-					// counts in `truncation` keep reflecting the source, not the trimmed
-					// view — column truncation surfaces separately via `.limits()`.
-
-					const shouldAddHashLines = !rawSelector && displayMode.hashLines;
-					const maxColumns = resolveOutputMaxColumns(this.session.settings);
-					if (!rawSelector && !shouldAddHashLines && maxColumns > 0) {
-						for (let i = 0; i < collectedLines.length; i++) {
-							const { text, wasTruncated } = truncateLine(collectedLines[i], maxColumns);
-							if (wasTruncated) {
-								collectedLines[i] = text;
-								columnTruncated = maxColumns;
+					if (collectMode !== "head") {
+						const window = streamResultWindow(streamResult, collectMode, startLine, collectEndExclusive);
+						const metadataWindow = rebaseWindow(window, -startLine);
+						directionalWindow = metadataWindow;
+						directionalNoticeOwner = isBareReceipt ? "body" : undefined;
+						directionalRangeBase = offset !== undefined && localDirection !== "head" ? "window" : undefined;
+						const directionalPartial = windowHasPartialSegment(window);
+						const shouldAddDirectionalHashLines = !rawSelector && displayMode.hashLines;
+						const shouldAddDirectionalLineNumbers = rawSelector
+							? false
+							: !shouldAddDirectionalHashLines && displayMode.lineNumbers;
+						const directionalMaxColumns = rawSelector ? 0 : resolveOutputMaxColumns(this.session.settings);
+						if (!rawSelector && !shouldAddDirectionalHashLines && directionalMaxColumns > 0) {
+							for (const segment of windowSegments(window)) {
+								if (
+									segment.content
+										.split("\n")
+										.some(line => truncateLine(line, directionalMaxColumns).wasTruncated)
+								) {
+									columnTruncated = directionalMaxColumns;
+									break;
+								}
 							}
 						}
-					}
-
-					const selectedContent = collectedLines.join("\n");
-					const userLimitedLines = collectedLines.length;
-
-					const totalSelectedLines = totalFileLines - startLine;
-					const totalSelectedBytes = collectedBytes;
-					const wasTruncated = collectedLines.length < totalSelectedLines || stoppedByByteLimit;
-					const firstLineExceedsLimit = firstLineByteLength !== undefined && firstLineByteLength > maxBytesForRead;
-
-					const truncation: TruncationResult = {
-						content: selectedContent,
-						truncated: wasTruncated,
-						truncatedBy: stoppedByByteLimit ? "bytes" : wasTruncated ? "lines" : undefined,
-						totalLines: totalSelectedLines,
-						totalBytes: totalSelectedBytes,
-						outputLines: collectedLines.length,
-						outputBytes: collectedBytes,
-						lastLinePartial: false,
-						firstLineExceedsLimit,
-					};
-
-					if (collectedLines.length > 0 && !firstLineExceedsLimit) {
-						getFileReadCache(this.session).recordContiguous(absolutePath, startLineDisplay, collectedLines);
-					}
-
-					const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
-					let capturedDisplayContent: { text: string; startLine: number } | undefined;
-					const formatText = (text: string, startNum: number): string => {
-						capturedDisplayContent = { text, startLine: startNum };
-						return formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
-					};
-
-					let outputText: string;
-
-					if (truncation.firstLineExceedsLimit) {
-						const firstLineBytes = firstLineByteLength ?? 0;
-						const snippet = firstLinePreview ?? { text: "", bytes: 0 };
-
-						if (shouldAddHashLines) {
-							outputText = `[Line ${startLineDisplay} is ${formatBytes(
-								firstLineBytes,
-							)}, exceeds ${formatBytes(maxBytesForRead)} limit. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`;
-						} else {
-							outputText = formatText(snippet.text, startLineDisplay);
+						const selectedContent = windowSegments(window)
+							.map(segment => segment.content)
+							.join("\n");
+						const partialTail = partialTailOf(window);
+						const partialTailWarning = partialTail !== undefined && shouldAddDirectionalHashLines;
+						if (partialTailWarning) {
+							Object.defineProperty(window, "outputLinesOverride", { value: 0, enumerable: false });
+							Object.defineProperty(window, "outputBytesOverride", { value: 0, enumerable: false });
+							Object.defineProperty(metadataWindow, "outputLinesOverride", { value: 0, enumerable: false });
+							Object.defineProperty(metadataWindow, "outputBytesOverride", { value: 0, enumerable: false });
+						}
+						const baseWindowResult =
+							window.kind === "full" ? undefined : makeWindowResult(metadataWindow, selectedContent);
+						const windowResult =
+							baseWindowResult && partialTailWarning
+								? { ...baseWindowResult, outputLines: 0, outputBytes: 0, lastLineExceedsLimit: true }
+								: baseWindowResult;
+						const rawWindow = renderReadWindow(window, false, false, directionalMaxColumns);
+						let outputText = partialTailWarning
+							? formatOversizedLineWarning(
+									localReadPath,
+									partialTail.origin.startLine,
+									partialTail.sourceLineBytes,
+									maxBytesForRead,
+									totalFileLines,
+								)
+							: renderReadWindow(
+									window,
+									shouldAddDirectionalHashLines,
+									shouldAddDirectionalLineNumbers,
+									directionalMaxColumns,
+								);
+						const windowEnd = Math.min(collectEndExclusive ?? totalFileLines, totalFileLines);
+						let bodyFooter: string | undefined;
+						if (isBareReceipt && window.kind !== "full" && !partialTailWarning) {
+							const footer = formatDirectionalFooter(localReadPath, metadataWindow);
+							if (footer) {
+								outputText += `\n\n${footer}`;
+								bodyFooter = footer;
+							}
 						}
-						if (snippet.text.length === 0) {
-							outputText = `[Line ${startLineDisplay} is ${formatBytes(
-								firstLineBytes,
-							)}, exceeds ${formatBytes(maxBytesForRead)} limit. Unable to display a valid UTF-8 snippet.]`;
+						if (rawSelector && window.kind !== "full") {
+							outputText += `\n\n${formatRawReadCapNotice(maxBytesForRead, fileSize, localDirection)}`;
+						}
+						if (
+							!isBareReceipt &&
+							window.kind === "full" &&
+							limit !== undefined &&
+							startLine < windowEnd &&
+							windowEnd < totalFileLines
+						) {
+							const remaining = totalFileLines - windowEnd;
+							outputText += `\n\n[${remaining} more lines in file. Use :${windowEnd + 1} to continue]`;
+						}
+						details = {
+							resolvedPath: absolutePath,
+							suffixResolution,
+							displayContent: {
+								text: rawWindow,
+								startLine: window.head?.origin.startLine ?? window.tail?.origin.startLine ?? startLineDisplay,
+							},
+							...(windowResult ? { truncation: windowResult } : {}),
+							spillEligible: !isBareReceipt && selectedContent.length > 0 && !directionalPartial,
+						};
+						if (bodyFooter) rememberBodyTruncationFooter(details, bodyFooter);
+						if (!directionalPartial) {
+							for (const segment of windowSegments(window)) {
+								if (segment.kind === "lines" && segment.lines > 0) {
+									getFileReadCache(this.session).recordContiguous(
+										absolutePath,
+										segment.origin.startLine,
+										linesOfSegment(segment),
+									);
+								}
+							}
+						}
+						if (!partialTailWarning) {
+							const conflictBlocks = windowSegments(window).flatMap(segment =>
+								segment.kind === "lines"
+									? scanConflictLines(linesOfSegment(segment), segment.origin.startLine)
+									: [],
+							);
+							if (conflictBlocks.length > 0) {
+								const history = getConflictHistory(this.session);
+								const displayPathForWarning = formatPathRelativeToCwd(absolutePath, this.session.cwd);
+								const entries = conflictBlocks.map(block =>
+									history.register({
+										absolutePath,
+										displayPath: displayPathForWarning,
+										...block,
+									}),
+								);
+								// Cheap full-file scan only when the window already showed
+								// at least one conflict — otherwise pay nothing on clean files.
+								let totalInFile = entries.length;
+								let scanTruncated = false;
+								try {
+									const fileScan = await scanFileForConflicts(absolutePath);
+									totalInFile = Math.max(entries.length, fileScan.blocks.length);
+									scanTruncated = fileScan.scanTruncated;
+								} catch {
+									// Best-effort enrichment; fall back to window-only count.
+								}
+								outputText += formatConflictWarning(entries, {
+									totalInFile,
+									displayPath: displayPathForWarning,
+									scanTruncated,
+								});
+								details.conflictCount = entries.length;
+							}
 						}
-						details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
-
 						sourcePath = absolutePath;
-						truncationInfo = {
-							result: truncation,
-							options: { direction: "head", startLine: startLineDisplay, totalFileLines },
+						content = [{ type: "text", text: outputText }];
+					} else {
+						// Per-line column cap. Skipped in raw mode so `:raw` always returns
+						// verbatim bytes for paste-back-into-tool workflows. Total byte/line
+						// counts in `truncation` keep reflecting the source, not the trimmed
+						// view — column truncation surfaces separately via `.limits()`.
+
+						const shouldAddHashLines = !rawSelector && displayMode.hashLines;
+						const maxColumns = resolveOutputMaxColumns(this.session.settings);
+						if (!rawSelector && !shouldAddHashLines && maxColumns > 0) {
+							for (let i = 0; i < collectedLines.length; i++) {
+								const { text, wasTruncated } = truncateLine(collectedLines[i], maxColumns);
+								if (wasTruncated) {
+									collectedLines[i] = text;
+									columnTruncated = maxColumns;
+								}
+							}
+						}
+
+						const selectedContent = collectedLines.join("\n");
+						const userLimitedLines = collectedLines.length;
+
+						const totalSelectedLines = totalFileLines - startLine;
+						const totalSelectedBytes = collectedBytes;
+						const wasTruncated = collectedLines.length < totalSelectedLines || stoppedByByteLimit;
+						const firstLineExceedsLimit =
+							firstLineByteLength !== undefined && firstLineByteLength > maxBytesForRead;
+
+						const truncation: TruncationResult = {
+							content: selectedContent,
+							truncated: wasTruncated,
+							truncatedBy: stoppedByByteLimit ? "bytes" : wasTruncated ? "lines" : undefined,
+							totalLines: totalSelectedLines,
+							totalBytes: totalSelectedBytes,
+							outputLines: collectedLines.length,
+							outputBytes: collectedBytes,
+							lastLinePartial: false,
+							firstLineExceedsLimit,
 						};
-					} else if (truncation.truncated) {
-						outputText = formatText(truncation.content, startLineDisplay);
-						details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
 
-						sourcePath = absolutePath;
-						truncationInfo = {
-							result: truncation,
-							options: { direction: "head", startLine: startLineDisplay, totalFileLines },
+						if (collectedLines.length > 0 && !firstLineExceedsLimit) {
+							getFileReadCache(this.session).recordContiguous(absolutePath, startLineDisplay, collectedLines);
+						}
+
+						const shouldAddLineNumbers = rawSelector
+							? false
+							: shouldAddHashLines
+								? false
+								: displayMode.lineNumbers;
+						let capturedDisplayContent: { text: string; startLine: number } | undefined;
+						const formatText = (text: string, startNum: number): string => {
+							capturedDisplayContent = { text, startLine: startNum };
+							return formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
 						};
-					} else if (startLine + userLimitedLines < totalFileLines) {
-						const remaining = totalFileLines - (startLine + userLimitedLines);
-						const nextOffset = startLine + userLimitedLines + 1;
 
-						outputText = formatText(truncation.content, startLineDisplay);
-						outputText += `\n\n[${remaining} more lines in file. Use :${nextOffset} to continue]`;
-						details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
+						let outputText: string;
 
-						sourcePath = absolutePath;
-					} else {
-						// No truncation, no user limit exceeded
-						outputText = formatText(truncation.content, startLineDisplay);
-						details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
+						if (truncation.firstLineExceedsLimit) {
+							const firstLineBytes = firstLineByteLength ?? 0;
+							const snippet = firstLinePreview ?? { text: "", bytes: 0 };
 
-						sourcePath = absolutePath;
-					}
-					if (isBareReceipt && (truncation.truncated || collectedLines.length < totalFileLines)) {
-						outputText += `\n\n${formatReceiptFooter(localReadPath, collectedLines.length, totalFileLines, collectedBytes)}`;
-					}
-					if (rawSelector && truncation.truncated) {
-						outputText += `\n\n[Raw read capped at ${formatBytes(maxBytesForRead)} of ${formatBytes(fileSize)}; re-read a line range to narrow the view]`;
-					}
+							if (shouldAddHashLines) {
+								outputText = `[Line ${startLineDisplay} is ${formatBytes(
+									firstLineBytes,
+								)}, exceeds ${formatBytes(maxBytesForRead)} limit. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`;
+							} else {
+								outputText = formatText(snippet.text, startLineDisplay);
+							}
+							if (snippet.text.length === 0) {
+								outputText = `[Line ${startLineDisplay} is ${formatBytes(
+									firstLineBytes,
+								)}, exceeds ${formatBytes(maxBytesForRead)} limit. Unable to display a valid UTF-8 snippet.]`;
+							}
+							details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
+							sourcePath = absolutePath;
+							truncationInfo = {
+								result: truncation,
+								// Head receipts keep the wrapper notice: it carries the `:N to
+								// continue` hint, which the body footer does not duplicate.
+								// Only directional windows transfer notice ownership to the body.
+								options: { direction: "head", startLine: startLineDisplay, totalFileLines },
+							};
+						} else if (truncation.truncated) {
+							outputText = formatText(truncation.content, startLineDisplay);
+							details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
+							sourcePath = absolutePath;
+							truncationInfo = {
+								result: truncation,
+								options: { direction: "head", startLine: startLineDisplay, totalFileLines },
+							};
+						} else if (startLine + userLimitedLines < totalFileLines) {
+							const remaining = totalFileLines - (startLine + userLimitedLines);
+							const nextOffset = startLine + userLimitedLines + 1;
+
+							outputText = formatText(truncation.content, startLineDisplay);
+							outputText += `\n\n[${remaining} more lines in file. Use :${nextOffset} to continue]`;
+							details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
+							sourcePath = absolutePath;
+						} else {
+							// No truncation, no user limit exceeded
+							outputText = formatText(truncation.content, startLineDisplay);
+							details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
 
-					if (capturedDisplayContent) {
-						details.displayContent = capturedDisplayContent;
-					}
+							sourcePath = absolutePath;
+						}
+						if (isBareReceipt && (truncation.truncated || collectedLines.length < totalFileLines)) {
+							outputText += `\n\n${formatReceiptFooter(localReadPath, collectedLines.length, totalFileLines, collectedBytes)}`;
+						}
+						if (rawSelector && truncation.truncated) {
+							outputText += `\n\n${formatRawReadCapNotice(maxBytesForRead, fileSize, localDirection)}`;
+						}
 
-					if (!firstLineExceedsLimit && collectedLines.length > 0) {
-						const blocks = scanConflictLines(collectedLines, startLineDisplay);
-						if (blocks.length > 0) {
-							const history = getConflictHistory(this.session);
-							const displayPathForWarning = formatPathRelativeToCwd(absolutePath, this.session.cwd);
-							const entries = blocks.map(block =>
-								history.register({
-									absolutePath,
+						if (capturedDisplayContent) {
+							details.displayContent = capturedDisplayContent;
+						}
+
+						if (!firstLineExceedsLimit && collectedLines.length > 0) {
+							const blocks = scanConflictLines(collectedLines, startLineDisplay);
+							if (blocks.length > 0) {
+								const history = getConflictHistory(this.session);
+								const displayPathForWarning = formatPathRelativeToCwd(absolutePath, this.session.cwd);
+								const entries = blocks.map(block =>
+									history.register({
+										absolutePath,
+										displayPath: displayPathForWarning,
+										...block,
+									}),
+								);
+								// Cheap full-file scan only when the window already showed
+								// at least one conflict — otherwise pay nothing on clean files.
+								let totalInFile = entries.length;
+								let scanTruncated = false;
+								try {
+									const fileScan = await scanFileForConflicts(absolutePath);
+									totalInFile = Math.max(entries.length, fileScan.blocks.length);
+									scanTruncated = fileScan.scanTruncated;
+								} catch {
+									// Best-effort enrichment; fall back to window-only count.
+								}
+								outputText += formatConflictWarning(entries, {
+									totalInFile,
 									displayPath: displayPathForWarning,
-									...block,
-								}),
-							);
-							// Cheap full-file scan only when the window already showed
-							// at least one conflict — otherwise pay nothing on clean files.
-							let totalInFile = entries.length;
-							let scanTruncated = false;
-							try {
-								const fileScan = await scanFileForConflicts(absolutePath);
-								totalInFile = Math.max(entries.length, fileScan.blocks.length);
-								scanTruncated = fileScan.scanTruncated;
-							} catch {
-								// Best-effort enrichment; fall back to window-only count.
+									scanTruncated,
+								});
+								details.conflictCount = entries.length;
 							}
-							outputText += formatConflictWarning(entries, {
-								totalInFile,
-								displayPath: displayPathForWarning,
-								scanTruncated,
-							});
-							details.conflictCount = entries.length;
 						}
-					}
 
-					content = [{ type: "text", text: outputText }];
+						content = [{ type: "text", text: outputText }];
+					}
 				}
 			}
 		}
@@ -2070,6 +3274,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		if (truncationInfo) {
 			resultBuilder.truncation(truncationInfo.result, truncationInfo.options);
 		}
+		if (directionalWindow) {
+			resultBuilder.truncationWindows(directionalWindow, {
+				noticeOwner: directionalNoticeOwner,
+				rangeBase: directionalRangeBase,
+			});
+		}
 		if (columnTruncated > 0) {
 			resultBuilder.limits({ columnMax: columnTruncated });
 		}
@@ -2115,8 +3325,15 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		absolutePath: string,
 		suffixResolution: { from: string; to: string } | undefined,
 		signal: AbortSignal | undefined,
+		truncationParam?: TruncationDirection,
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		throwIfAborted(signal);
+		if (truncationParam !== undefined && truncationParam !== "head") {
+			throw new ToolError(
+				"Explicit truncation for :conflicts indexes is not yet supported; the conflict preamble and bulk-resolve notice will be preserved when a structural index window is added.",
+			);
+		}
+
 		const scan = await scanFileForConflicts(absolutePath);
 		const displayPath = formatPathRelativeToCwd(absolutePath, this.session.cwd);
 		const history = getConflictHistory(this.session);
@@ -2149,6 +3366,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		url: string,
 		parsedSel: ParsedSelector,
 		signal?: AbortSignal,
+		truncationParam?: TruncationDirection,
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		const internalRouter = InternalUrlRouter.instance();
 
@@ -2185,8 +3403,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		// If extraction was used, return directly (no pagination)
 		if (hasExtraction) {
+			if (truncationParam !== undefined && truncationParam !== "head") {
+				throw new ToolError("Explicit truncation for internal URL query extraction is not yet supported.");
+			}
 			return toolResult(details).text(resource.content).sourceInternal(url).done();
 		}
+		const direction = resolveEffectiveDirection(truncationParam, "converted", this.session.settings);
 
 		const raw = isRawSelector(parsedSel);
 		if (isMultiRange(parsedSel) && parsedSel.kind === "lines") {
@@ -2197,6 +3419,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				entityLabel: "resource",
 				immutable: resource.immutable,
 				raw,
+				truncationDirection: direction,
 			});
 		}
 
@@ -2209,6 +3432,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			ignoreResultLimits: scheme === "skill",
 			immutable: resource.immutable,
 			raw,
+			truncationDirection: direction,
+			bodyFooterPath: parsedSel.kind === "none" && !raw ? url : undefined,
 		});
 	}
 
@@ -2216,6 +3441,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	async #readDirectory(
 		absolutePath: string,
 		limit: number | undefined,
+		direction: TruncationDirection,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<ReadToolDetails>> {
 		const READ_DIRECTORY_MAX_DEPTH = 2;
@@ -2239,20 +3465,26 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const receiptLines = this.session.settings.get("read.receiptBudgetLines");
 		const receiptBytes = this.session.settings.get("read.receiptBudgetBytes") * 1024;
 		const sourceLines = tree.totalLines <= 1 ? ["(empty directory)"] : tree.rendered.split("\n");
-		const bodyLines: string[] = [];
-		let bodyBytes = 0;
-		for (const line of sourceLines) {
-			const bytes = Buffer.byteLength(line, "utf-8") + (bodyLines.length > 0 ? 1 : 0);
-			if (bodyLines.length >= receiptLines || bodyBytes + bytes > receiptBytes) break;
-			bodyLines.push(line);
-			bodyBytes += bytes;
-		}
-		let output = bodyLines.join("\n");
-		if (bodyLines.length < sourceLines.length || tree.truncated) {
-			output += `\n\n[Listing truncated at ${bodyLines.length} lines / ${Math.ceil(bodyBytes / 1024)} KiB; read a deeper subpath (e.g. ${absolutePath}/<subdir>) to narrow the view]`;
-		}
-		const details: ReadToolDetails = { isDirectory: true, spillEligible: false, resolvedPath: tree.rootPath };
-		return toolResult(details).text(output).sourcePath(tree.rootPath).done();
+		const source = sourceLines.join("\n");
+		const window = selectReadWindow(source, sourceLines, direction, receiptLines, receiptBytes);
+		const shownLines = windowOutputLines(window);
+		const shownSegments = windowSegments(window);
+		const shownBytes =
+			shownSegments.reduce((sum, segment) => sum + segment.bytes, 0) + Math.max(0, shownSegments.length - 1);
+		let output = renderReadWindow(window, false, false);
+		if (window.kind !== "full" || tree.truncated) {
+			output += `\n\n${formatListingTruncationNotice(shownLines, shownBytes, absolutePath, direction)}`;
+		}
+		const details: ReadToolDetails = {
+			isDirectory: true,
+			spillEligible: false,
+			resolvedPath: tree.rootPath,
+			...(window.kind !== "full" && direction !== "head" ? { truncation: makeWindowResult(window, source) } : {}),
+		};
+		const resultBuilder = toolResult(details).text(output).sourcePath(tree.rootPath);
+		if (window.kind !== "full" && direction !== "head")
+			resultBuilder.truncationWindows(window, { noticeOwner: "body", maxBytes: receiptBytes });
+		return resultBuilder.done();
 	}
 }