@gajae-code/coding-agent 0.11.2 → 0.11.4

package/src/tools/path-utils.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
-import { isEnoent } from "@gajae-code/utils";
+import { isEnoent } from "@gajae-code/utils/fs-error";
 import { InternalUrlRouter } from "../internal-urls";
 import { ToolError } from "./tool-errors";
 
@@ -10,13 +10,9 @@ const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 const FILE_LINE_RANGE_RE = /^(?:L?\d+(?:[-+]L?\d+|-)?(?:,L?\d+(?:[-+]L?\d+|-)?)*|raw|conflicts)$/i;
 const FILE_LINE_RANGE_ONLY_RE = /^L?\d+(?:[-+]L?\d+|-)?(?:,L?\d+(?:[-+]L?\d+|-)?)*$/i;
 const FILE_RAW_ONLY_RE = /^raw$/i;
-// Permissive selector chunk for internal URLs — accepts well-formed selectors
-// plus common malformed shapes (e.g. `:-N`) so the read tool peels the entire
-// selector chain off before dispatching to a protocol handler.
-const INTERNAL_URL_SELECTOR_PART_RE =
-	/^(?:raw|conflicts|L?\d+(?:[-+]L?\d+|-)?(?:,L?\d+(?:[-+]L?\d+|-)?)*|-\d+(?:[-+]\d+)?)$/i;
-// Schemes whose host grammar is identifier-shaped, so any trailing
-// `:<selector-chunk>` is unambiguously a read-tool selector.
+// Schemes whose authority grammar is identifier-shaped and may therefore carry
+// a read selector immediately after the authority. Colons in a path, query, or
+// fragment remain part of the URL and are never considered selectors.
 const INTERNAL_SCHEMES_WITH_SELECTORS: Record<string, true> = {
 	agent: true,
 	artifact: true,
@@ -148,39 +144,50 @@ export function splitPathAndSel(rawPath: string): { path: string; sel?: string }
 /**
  * Variant of {@link splitPathAndSel} for internal URLs (`scheme://...`).
  *
- * The filesystem-path splitter is intentionally conservative: it refuses to
- * peel a trailing `:<chunk>` unless that chunk matches the strict selector
- * grammar. That rule is right for filesystem paths (a file named `a:1-50` is
- * legal) but wrong for internal URLs, where any trailing `:<chunk>` after the
- * scheme is unambiguously a read-tool selector — even if malformed (e.g.
- * `artifact://3:raw:-100`).
- *
- * This function iteratively peels selector-shaped chunks (well-formed plus
- * common malformed shapes like `:-N`) so the rest of the read tool can pass a
- * clean URL to the protocol handler and surface selector errors via parseSel
- * instead of as misleading "host invalid" errors from the handler.
- *
- * Falls back to the input unchanged when nothing matches.
+ * Artifact authorities are generated identifiers, so their complete tail is
+ * unambiguously a selector and malformed selectors can be rejected before
+ * resolving the artifact. Other resources may legitimately use colons in
+ * their identities, so they only lose strict, recognized selector suffixes.
+ * Skill authorities additionally use the active registry to distinguish a
+ * skill name from its selector without making path-utils depend on skills.
  */
-export function splitInternalUrlSel(rawPath: string): { path: string; sel?: string } {
+export function splitInternalUrlSel(
+	rawPath: string,
+	options: { activeSkillNames?: readonly string[] } = {},
+): { path: string; sel?: string } {
 	const schemeMatch = rawPath.match(INTERNAL_URL_SCHEME_RE);
 	if (!schemeMatch) return { path: rawPath };
-	if (!INTERNAL_SCHEMES_WITH_SELECTORS[schemeMatch[1].toLowerCase()]) return { path: rawPath };
+	const scheme = schemeMatch[1].toLowerCase();
+	if (!INTERNAL_SCHEMES_WITH_SELECTORS[scheme]) return { path: rawPath };
 
 	const schemeEnd = schemeMatch[0].length;
-	let path = rawPath;
-	const chunks: string[] = [];
-	while (true) {
-		const colon = path.lastIndexOf(":");
-		// Stop before crossing into the scheme separator `://`.
-		if (colon < schemeEnd) break;
-		const tail = path.slice(colon + 1);
-		if (!INTERNAL_URL_SELECTOR_PART_RE.test(tail)) break;
-		chunks.unshift(tail);
-		path = path.slice(0, colon);
+	const authorityTerminator = rawPath.slice(schemeEnd).search(/[/?#]/);
+	if (authorityTerminator !== -1) return { path: rawPath };
+	const authority = rawPath.slice(schemeEnd);
+	const firstColon = authority.indexOf(":");
+	if (firstColon === -1) return { path: rawPath };
+
+	if (scheme === "artifact") {
+		return { path: rawPath.slice(0, schemeEnd + firstColon), sel: authority.slice(firstColon + 1) };
+	}
+
+	if (scheme === "skill") {
+		const activeSkillNames = options.activeSkillNames ?? [];
+		if (activeSkillNames.includes(authority)) return { path: rawPath };
+		const skillName = activeSkillNames
+			.filter(name => authority.startsWith(`${name}:`))
+			.sort((a, b) => b.length - a.length)[0];
+		if (skillName) {
+			return {
+				path: `${rawPath.slice(0, schemeEnd)}${skillName}`,
+				sel: authority.slice(skillName.length + 1),
+			};
+		}
 	}
-	if (chunks.length === 0) return { path: rawPath };
-	return { path, sel: chunks.join(":") };
+
+	const strict = splitPathAndSel(authority);
+	if (strict.sel === undefined) return { path: rawPath };
+	return { path: `${rawPath.slice(0, schemeEnd)}${strict.path}`, sel: strict.sel };
 }
 
 function assertNotInternalUrl(expanded: string, original: string): void {

package/src/tools/read.ts

@@ -11,6 +11,7 @@ import * as z from "zod/v4";
 import { getFileReadCache } from "../edit/file-read-cache";
 import { isNotebookPath, readEditableNotebookText } from "../edit/notebook";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { getActiveSkills } from "../extensibility/skills";
 import { formatHashLine, formatHashLines, formatLineHash, HL_BODY_SEP } from "../hashline/hash";
 import { InternalUrlRouter } from "../internal-urls";
 import { parseInternalUrl } from "../internal-urls/parse";
@@ -95,6 +96,8 @@ const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx"
 
 const MAX_SUMMARY_BYTES = 2 * 1024 * 1024;
 const MAX_SUMMARY_LINES = 20_000;
+const RAW_COLLECTOR_MAX_BYTES = MAX_SUMMARY_BYTES;
+
 /**
  * Per-line column cap for file reads. Lines wider than the value of
  * `tools.outputMaxColumns` are ellipsis-truncated at display time; the file
@@ -193,6 +196,14 @@ function formatSummaryElisionFooter(readPath: string, elidedSpans: number, elide
 	const linePart = elidedLines > 0 ? `${elidedLines} ${lineWord} across ` : "";
 	return `[${linePart}${elidedSpans} elided ${spanWord}; read ${readPath}:raw or a line range like ${readPath}:1-9999 for verbatim content]`;
 }
+
+function formatReceiptFooter(readPath: string, shownLines: number, totalLines: number, shownBytes: number): string {
+	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]`;
+}
 const READ_CHUNK_SIZE = 8 * 1024;
 
 /**
@@ -532,6 +543,9 @@ export interface ReadToolDetails {
 	method?: string;
 	notes?: string[];
 	meta?: OutputMeta;
+	/** Whether this explicit content read may be spilled by output metadata. */
+	spillEligible?: boolean;
+
 	/** Raw text + start line for user-visible TUI rendering, set when content is text-like.
 	 * Mirrors the same lines the model receives but without hashline/line-number prefixes,
 	 * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
@@ -816,10 +830,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		options: {
 			details?: ReadToolDetails;
 			sourcePath?: string;
+			spillEligible?: boolean;
+			receiptPath?: string;
 			sourceUrl?: string;
 			sourceInternal?: string;
 			entityLabel: string;
 			ignoreResultLimits?: boolean;
+			resultByteCeiling?: number;
 			raw?: boolean;
 			immutable?: boolean;
 			wrapUntrusted?: boolean;
@@ -871,9 +888,30 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 
 		const endLine = endLineExpanded;
-		const selectedContent = allLines.slice(startLine, endLine).join("\n");
+		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);
+		const truncation = ignoreResultLimits
+			? noTruncResult(selectedContent)
+			: truncateHead(
+					selectedContent,
+					options.resultByteCeiling === undefined
+						? undefined
+						: { maxBytes: options.resultByteCeiling, maxLines: Number.MAX_SAFE_INTEGER },
+				);
 
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
@@ -927,7 +965,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		} 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;
 		resultBuilder.text(options.wrapUntrusted ? wrapUntrustedContent(outputText) : outputText);
 		if (truncationInfo) {
 			resultBuilder.truncation(truncationInfo.result, truncationInfo.options);
@@ -987,6 +1029,8 @@ 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;
+
 		resultBuilder.text(finalText);
 		return resultBuilder.done();
 	}
@@ -1006,6 +1050,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		signal: AbortSignal | undefined,
 	): Promise<{
 		outputText: string;
+		contentLineCount: number;
 		columnTruncated: number;
 		bridgeResult?: AgentToolResult<ReadToolDetails>;
 	}> {
@@ -1027,7 +1072,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					const firstText = bridgeResult.content.find((c): c is TextContent => c.type === "text");
 					if (firstText) firstText.text = `${notice}\n${firstText.text}`;
 				}
-				return { outputText: "", columnTruncated: 0, bridgeResult };
+				return { outputText: "", contentLineCount: 0, columnTruncated: 0, bridgeResult };
 			} catch (error) {
 				logger.warn("ACP fs readTextFile failed; falling back to disk", { path: absolutePath, error });
 			}
@@ -1040,6 +1085,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const blocks: string[] = [];
 		const notices: string[] = [];
 		let columnTruncated = 0;
+		let contentLineCount = 0;
 
 		for (const range of ranges) {
 			const rangeStart = range.startLine - 1; // 0-indexed
@@ -1074,6 +1120,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				}
 			}
 
+			contentLineCount += collectedLines.length;
 			if (collectedLines.length > 0) {
 				getFileReadCache(this.session).recordContiguous(absolutePath, range.startLine, collectedLines);
 			}
@@ -1086,7 +1133,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		if (notices.length > 0) {
 			outputText = outputText ? `${outputText}\n${notices.join("\n")}` : notices.join("\n");
 		}
-		return { outputText, columnTruncated };
+		return { outputText, contentLineCount, columnTruncated };
 	}
 
 	async #readArchiveDirectory(
@@ -1369,6 +1416,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		displayText: string;
 		elidedSpans: number;
 		elidedLines: number;
+		capped: boolean;
 	} {
 		const displayMode = resolveFileDisplayMode(this.session);
 		const shouldAddHashLines = displayMode.hashLines;
@@ -1428,17 +1476,19 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const modelParts: string[] = [];
 		const displayParts: string[] = [];
+		const capBytes = this.session.settings.get("read.summaryMaxBytes") * 1024;
+		let usedBytes = 0;
 		let elidedSpans = 0;
 		let elidedLines = 0;
+		let capDropped = false;
 		for (const unit of units) {
+			let model: string;
+			let display: string;
+			let implicitElidedLines = 0;
 			if (unit.kind === "elided") {
-				modelParts.push("...");
-				displayParts.push("...");
-				elidedSpans++;
-				elidedLines += unit.endLine - unit.startLine + 1;
-				continue;
-			}
-			if (unit.kind === "merged") {
+				model = display = "...";
+				implicitElidedLines = unit.endLine - unit.startLine + 1;
+			} else if (unit.kind === "merged") {
 				const formatted = formatMergedBraceLine(
 					unit.startLine,
 					unit.endLine,
@@ -1447,18 +1497,39 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					shouldAddHashLines,
 					shouldAddLineNumbers,
 				);
-				modelParts.push(formatted.model);
-				displayParts.push(formatted.display);
+				model = formatted.model;
+				display = formatted.display;
+				implicitElidedLines = Math.max(0, unit.endLine - unit.startLine - 1);
+			} else {
+				model = formatSingleLine(unit.line, unit.text, shouldAddHashLines, shouldAddLineNumbers);
+				display = unit.text;
+			}
+			const separatorBytes = modelParts.length > 0 ? 1 : 0;
+			if (usedBytes + separatorBytes + Buffer.byteLength(model, "utf-8") > capBytes) {
+				capDropped = true;
 				elidedSpans++;
-				// Merged brace pair encloses (start+1)..(end-1) as elided.
-				elidedLines += Math.max(0, unit.endLine - unit.startLine - 1);
+				elidedLines += unit.kind === "line" ? 1 : unit.endLine - unit.startLine + 1;
 				continue;
 			}
-			modelParts.push(formatSingleLine(unit.line, unit.text, shouldAddHashLines, shouldAddLineNumbers));
-			displayParts.push(unit.text);
+			usedBytes += separatorBytes + Buffer.byteLength(model, "utf-8");
+			modelParts.push(model);
+			displayParts.push(display);
+			if (unit.kind === "elided" || unit.kind === "merged") {
+				elidedSpans++;
+				elidedLines += implicitElidedLines;
+			}
 		}
-
-		return { text: modelParts.join("\n"), displayText: displayParts.join("\n"), elidedSpans, elidedLines };
+		if (capDropped) {
+			modelParts.push("…");
+			displayParts.push("…");
+		}
+		return {
+			text: modelParts.join("\n"),
+			displayText: displayParts.join("\n"),
+			elidedSpans,
+			elidedLines,
+			capped: capDropped,
+		};
 	}
 
 	async execute(
@@ -1515,8 +1586,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		// off the URL and surfaced via parseSel rather than confusing handlers.
 		const internalRouter = InternalUrlRouter.instance();
 		if (internalRouter.canHandle(readPath)) {
-			const internalTarget = splitInternalUrlSel(readPath);
+			const internalTarget = splitInternalUrlSel(readPath, {
+				activeSkillNames: getActiveSkills().map(skill => skill.name),
+			});
 			const parsed = parseSel(internalTarget.sel);
+			if (internalTarget.sel !== undefined && parsed.kind === "none") {
+				throw new ToolError(`Invalid internal URL selector "${internalTarget.sel}".`);
+			}
 			return this.#handleInternalUrl(internalTarget.path, parsed, signal);
 		}
 
@@ -1649,25 +1725,38 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				details: { resolvedPath: absolutePath },
 				sourcePath: absolutePath,
 				entityLabel: "notebook",
+				spillEligible: parsed.kind !== "none",
+				resultByteCeiling:
+					parsed.kind !== "none"
+						? Math.max(
+								RAW_COLLECTOR_MAX_BYTES,
+								this.session.settings.get("tools.readArtifactSpillThreshold") * 1024,
+							)
+						: undefined,
+				receiptPath: parsed.kind === "none" ? localReadPath : undefined,
 			});
 		} else if (shouldConvertWithMarkit) {
-			// Convert document via markit.
 			const result = await convertFileWithMarkit(absolutePath, signal);
 			if (result.ok) {
-				// Apply truncation to converted content
-				const truncation = truncateHead(result.content);
-				const outputText = truncation.content;
-
-				details = { truncation };
-				sourcePath = absolutePath;
-				truncationInfo = { result: truncation, options: { direction: "head", startLine: 1 } };
-
-				content = [{ type: "text", text: outputText }];
-			} else if (result.error) {
-				content = [{ type: "text", text: `[Cannot read ${ext} file: ${result.error || "conversion failed"}]` }];
-			} else {
-				content = [{ type: "text", text: `[Cannot read ${ext} file: conversion failed]` }];
+				const { offset, limit } = selToOffsetLimit(parsed);
+				return this.#buildInMemoryTextResult(result.content, offset, limit, {
+					details: { resolvedPath: absolutePath },
+					sourcePath: absolutePath,
+					entityLabel: "converted document",
+					raw: isRawSelector(parsed),
+					spillEligible: parsed.kind !== "none",
+					resultByteCeiling:
+						parsed.kind !== "none"
+							? Math.max(
+									RAW_COLLECTOR_MAX_BYTES,
+									this.session.settings.get("tools.readArtifactSpillThreshold") * 1024,
+								)
+							: undefined,
+					receiptPath: parsed.kind === "none" ? localReadPath : undefined,
+				});
 			}
+			content = [{ type: "text", text: `[Cannot read ${ext} file: ${result.error || "conversion failed"}]` }];
+			details = { spillEligible: false };
 		} else {
 			if (
 				parsed.kind === "none" &&
@@ -1682,8 +1771,22 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						renderedSummary.elidedSpans,
 						renderedSummary.elidedLines,
 					);
-					const modelText = footer ? `${renderedSummary.text}\n\n${footer}` : renderedSummary.text;
+					const summaryTotalLines = Math.max(...summary.segments.map(segment => segment.endLine));
+					const modelText = [
+						renderedSummary.text,
+						footer,
+						renderedSummary.capped
+							? formatSummaryCapFooter(
+									localReadPath,
+									this.session.settings.get("read.summaryMaxBytes") * 1024,
+									summaryTotalLines,
+								)
+							: "",
+					]
+						.filter(Boolean)
+						.join("\n\n");
 					details = {
+						spillEligible: false,
 						displayContent: { text: renderedSummary.displayText, startLine: 1 },
 						summary: {
 							lines: countTextLines(renderedSummary.text),
@@ -1710,7 +1813,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					if (multiResult.bridgeResult) return multiResult.bridgeResult;
 					content = [{ type: "text", text: multiResult.outputText }];
 					sourcePath = absolutePath;
-					details = {};
+					details = { spillEligible: multiResult.contentLineCount > 0 };
 					if (multiResult.columnTruncated > 0) {
 						columnTruncated = multiResult.columnTruncated;
 					}
@@ -1750,13 +1853,25 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					const startLine = requestedStart - leadingContext;
 					const startLineDisplay = startLine + 1;
 
+					const isBareReceipt = parsed.kind === "none" && !content;
+					const rawSelector = isRawSelector(parsed);
 					const DEFAULT_LIMIT = this.#defaultLimit;
-					const effectiveLimit = limit ?? DEFAULT_LIMIT;
-					const maxLinesToCollect = Math.min(effectiveLimit + leadingContext + trailingContext, DEFAULT_MAX_LINES);
-					const selectedLineLimit = effectiveLimit + leadingContext + trailingContext;
-					// Scale byte budget with line limit so the configured line count actually fits.
-					// Assume ~512 bytes/line average; never go below the shared default.
-					const maxBytesForRead = Math.max(DEFAULT_MAX_BYTES, maxLinesToCollect * 512);
+					const effectiveLimit = rawSelector ? Number.MAX_SAFE_INTEGER : (limit ?? DEFAULT_LIMIT);
+					const receiptBudgetBytes = this.session.settings.get("read.receiptBudgetBytes") * 1024;
+					const maxLinesToCollect = rawSelector
+						? Number.MAX_SAFE_INTEGER
+						: isBareReceipt
+							? this.session.settings.get("read.receiptBudgetLines")
+							: Math.min(effectiveLimit + leadingContext + trailingContext, DEFAULT_MAX_LINES);
+					const selectedLineLimit = rawSelector ? null : effectiveLimit + leadingContext + trailingContext;
+					const maxBytesForRead = rawSelector
+						? Math.max(
+								RAW_COLLECTOR_MAX_BYTES,
+								this.session.settings.get("tools.readArtifactSpillThreshold") * 1024,
+							)
+						: isBareReceipt
+							? receiptBudgetBytes
+							: Math.max(DEFAULT_MAX_BYTES, maxLinesToCollect * 512);
 
 					const streamResult = await streamLinesFromFile(
 						absolutePath,
@@ -1793,7 +1908,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					// 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 rawSelector = isRawSelector(parsed);
+
 					const shouldAddHashLines = !rawSelector && displayMode.hashLines;
 					const maxColumns = resolveOutputMaxColumns(this.session.settings);
 					if (!rawSelector && !shouldAddHashLines && maxColumns > 0) {
@@ -1855,7 +1970,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 								firstLineBytes,
 							)}, exceeds ${formatBytes(maxBytesForRead)} limit. Unable to display a valid UTF-8 snippet.]`;
 						}
-						details = { truncation };
+						details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 						truncationInfo = {
 							result: truncation,
@@ -1863,7 +1979,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						};
 					} else if (truncation.truncated) {
 						outputText = formatText(truncation.content, startLineDisplay);
-						details = { truncation };
+						details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 						truncationInfo = {
 							result: truncation,
@@ -1875,14 +1992,22 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 						outputText = formatText(truncation.content, startLineDisplay);
 						outputText += `\n\n[${remaining} more lines in file. Use :${nextOffset} to continue]`;
-						details = {};
+						details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 					} else {
 						// No truncation, no user limit exceeded
 						outputText = formatText(truncation.content, startLineDisplay);
-						details = {};
+						details = { spillEligible: !isBareReceipt && collectedLines.length > 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 (capturedDisplayContent) {
 						details.displayContent = capturedDisplayContent;
@@ -2109,23 +2234,23 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 		throwIfAborted(signal);
 
-		const output = tree.totalLines <= 1 ? "(empty directory)" : tree.rendered;
-		const truncation = truncateHead(output, { maxLines: Number.MAX_SAFE_INTEGER });
-		const details: ReadToolDetails = {
-			isDirectory: true,
-			resolvedPath: tree.rootPath,
-		};
-
-		const resultBuilder = toolResult(details).text(truncation.content).sourcePath(tree.rootPath);
-		if (tree.truncated) {
-			resultBuilder.limits({ resultLimit: 1 });
-		}
-		if (truncation.truncated) {
-			resultBuilder.truncation(truncation, { direction: "head" });
-			details.truncation = truncation;
-		}
-
-		return resultBuilder.done();
+		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();
 	}
 }
 

package/src/tools/render-utils.ts

@@ -15,10 +15,10 @@ import { pluralize } from "@gajae-code/utils";
 import { settings } from "../config/settings";
 import type { Theme } from "../modes/theme/theme";
 import { Hasher } from "../tui/utils";
-import { formatDimensionNote, type ResizedImage } from "../utils/image-resize";
 
 export { Ellipsis } from "@gajae-code/natives";
 export { replaceTabs, truncateToWidth, wrapTextWithAnsi } from "@gajae-code/tui";
+export { formatScreenshot } from "./browser/screenshot-format";
 
 // =============================================================================
 // Standardized Display Constants
@@ -591,32 +591,6 @@ export function formatToolWorkingDirectory(workdir: string | undefined, projectD
 	return replaceTabs(displayWorkdir);
 }
 
-export function formatScreenshot(opts: {
-	saveFullRes: boolean;
-	savedMimeType: string;
-	savedByteLength: number;
-	dest: string;
-	resized: ResizedImage;
-}): string[] {
-	const lines = ["Screenshot captured"];
-	if (opts.saveFullRes) {
-		lines.push(
-			`Saved: ${opts.savedMimeType} (${(opts.savedByteLength / 1024).toFixed(2)} KB) to ${shortenPath(opts.dest)}`,
-		);
-		lines.push(
-			`Model: ${opts.resized.mimeType} (${(opts.resized.buffer.length / 1024).toFixed(2)} KB, ${opts.resized.width}x${opts.resized.height})`,
-		);
-	} else {
-		lines.push(`Format: ${opts.resized.mimeType} (${(opts.resized.buffer.length / 1024).toFixed(2)} KB)`);
-		lines.push(`Dimensions: ${opts.resized.width}x${opts.resized.height}`);
-	}
-	const dimensionNote = formatDimensionNote(opts.resized);
-	if (dimensionNote) {
-		lines.push(dimensionNote);
-	}
-	return lines;
-}
-
 export function wrapBrackets(text: string, theme: Theme): string {
 	return `${theme.format.bracketLeft}${text}${theme.format.bracketRight}`;
 }