@gajae-code/coding-agent 0.11.11 → 0.12.1

package/src/tools/output-meta.ts

@@ -16,7 +16,15 @@ import { getDefault, type Settings } from "../config/settings";
 import { formatGroupedDiagnosticMessages } from "../lsp/utils";
 import type { Theme } from "../modes/theme/theme";
 import { sessionArtifactCapability } from "../session/session-manager";
-import { type OutputSummary, type TruncationResult, truncateMiddle, truncateTail } from "../session/streaming-output";
+import {
+	formatMiddleElisionMarker,
+	type OutputSummary,
+	type ReadWindow,
+	type TruncationResult,
+	truncateMiddle,
+	truncateTail,
+} from "../session/streaming-output";
+
 import { formatBytes, wrapBrackets } from "./render-utils";
 import { renderError } from "./tool-errors";
 
@@ -25,6 +33,9 @@ import { renderError } from "./tool-errors";
  */
 export interface TruncationMeta {
 	direction: "head" | "tail" | "middle";
+	/** Coordinate basis for shown/head/tail ranges. Omitted means file coordinates; "window" is the selected-range coordinate system. */
+	rangeBase?: "file" | "window";
+	noticeOwner?: "body";
 	truncatedBy: "lines" | "bytes" | "middle";
 	totalLines: number;
 	totalBytes: number;
@@ -36,12 +47,18 @@ export interface TruncationMeta {
 	/** Head/tail line ranges shown when direction === "middle". */
 	headRange?: { start: number; end: number };
 	tailRange?: { start: number; end: number };
+	/** Partial source-line preview retained by a directional window. */
+	partialLine?: { line: number; bytes: number; sourceBytes: number };
 	/** Bytes elided from the middle. */
 	elidedBytes?: number;
 	/** Lines elided from the middle. */
 	elidedLines?: number;
-	/** Artifact ID if full output was saved */
+	/** Artifact ID when output was persisted; completeness is tracked separately below. */
 	artifactId?: string;
+	/** Bytes omitted from an artifact after its hard storage cap was reached. */
+	artifactTruncatedBytes?: number;
+	/** Bounded diagnostic when artifact writer creation, write, or finalization failed. */
+	artifactFailureDiagnostic?: string;
 	/** Next offset for pagination (head truncation only) */
 	nextOffset?: number;
 }
@@ -91,12 +108,15 @@ export interface TruncationOptions {
 	startLine?: number;
 	totalFileLines?: number;
 	artifactId?: string;
+	maxBytes?: number;
+	noticeOwner?: "body";
 }
 
 export interface TruncationSummaryOptions {
 	direction: "head" | "tail" | "middle";
 	startLine?: number;
 	totalFileLines?: number;
+	noticeOwner?: "body";
 }
 
 export interface TruncationTextOptions {
@@ -105,6 +125,7 @@ export interface TruncationTextOptions {
 	totalBytes?: number;
 	maxBytes?: number;
 	artifactId?: string;
+	noticeOwner?: "body";
 }
 
 /**
@@ -126,7 +147,7 @@ export class OutputMetaBuilder {
 	truncation(result: TruncationResult, options: TruncationOptions): this {
 		if (!result.truncated) return this;
 
-		const { direction, startLine = 1, totalFileLines, artifactId } = options;
+		const { direction, startLine = 1, totalFileLines, artifactId, noticeOwner, maxBytes } = options;
 		const outputLines = result.outputLines ?? result.totalLines;
 		const outputBytes = result.outputBytes ?? result.totalBytes;
 		const isMiddle = direction === "middle" || result.truncatedBy === "middle";
@@ -137,6 +158,7 @@ export class OutputMetaBuilder {
 				: "bytes";
 
 		const effectiveTotalLines = totalFileLines ?? result.totalLines;
+		const owner = noticeOwner !== undefined ? { noticeOwner } : {};
 
 		if (isMiddle) {
 			const elidedLines = result.elidedLines ?? Math.max(0, effectiveTotalLines - outputLines);
@@ -150,10 +172,12 @@ export class OutputMetaBuilder {
 			this.#meta.truncation = {
 				direction: "middle",
 				truncatedBy: "middle",
+				...owner,
 				totalLines: effectiveTotalLines,
 				totalBytes: result.totalBytes,
 				outputLines,
 				outputBytes,
+				...(maxBytes !== undefined ? { maxBytes } : {}),
 				headRange: headLines > 0 ? { start: 1, end: headLines } : undefined,
 				tailRange:
 					tailLines > 0 ? { start: effectiveTotalLines - tailLines + 1, end: effectiveTotalLines } : undefined,
@@ -178,10 +202,12 @@ export class OutputMetaBuilder {
 		this.#meta.truncation = {
 			direction,
 			truncatedBy,
+			...owner,
 			totalLines: effectiveTotalLines,
 			totalBytes: result.totalBytes,
 			outputLines,
 			outputBytes,
+			...(maxBytes !== undefined ? { maxBytes } : {}),
 			shownRange: { start: shownStart, end: shownEnd },
 			artifactId,
 			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
@@ -190,12 +216,141 @@ export class OutputMetaBuilder {
 		return this;
 	}
 
-	/** Add truncation info from OutputSummary. No-op if not truncated. */
-	truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this {
-		if (!summary.truncated) return this;
+	/** Add metadata from the actual head/tail windows retained by middle truncation. */
+	truncationWindows(
+		windows: ReadWindow,
+		options: {
+			artifactId?: string;
+			noticeOwner?: "body";
+			maxBytes?: number;
+			rangeBase?: "file" | "window";
+		} = {},
+	): this {
+		if (windows.kind === "full") return this;
+
+		const { artifactId, noticeOwner, rangeBase } = options;
+		const maxBytes = options.maxBytes ?? (windows as ReadWindow & { maxBytes?: number }).maxBytes;
+		const outputLinesOverride = (windows as ReadWindow & { outputLinesOverride?: number }).outputLinesOverride;
+		const outputBytesOverride = (windows as ReadWindow & { outputBytesOverride?: number }).outputBytesOverride;
+		const owner = noticeOwner !== undefined ? { noticeOwner } : {};
+		const rangeBaseMeta = rangeBase !== undefined ? { rangeBase } : {};
+		const hiddenReason = (windows as ReadWindow & { truncatedBy?: "lines" | "bytes" | "middle" }).truncatedBy;
+		const fallbackTruncatedBy: "lines" | "bytes" = hiddenReason === "bytes" ? "bytes" : "lines";
+		const partialTail = windows.tail?.kind === "partial-line" ? windows.tail : undefined;
+		if (partialTail) {
+			const headBytes = windows.head?.bytes ?? 0;
+			const separatorBytes = windows.head ? 1 : 0;
+			const markerBytes =
+				windows.elidedLines > 0
+					? Buffer.byteLength(formatMiddleElisionMarker(windows.elidedLines, windows.elidedBytes), "utf-8") + 1
+					: 0;
+			this.#meta.truncation = {
+				direction: windows.kind === "tail-only" ? "tail" : "middle",
+				truncatedBy: "bytes",
+				...owner,
+				...rangeBaseMeta,
+				totalLines: windows.totalLines,
+				totalBytes: windows.totalBytes,
+				outputLines:
+					outputLinesOverride ??
+					(windows.head
+						? windows.head.lines + partialTail.lines + (windows.elidedLines > 0 ? 1 : 0)
+						: partialTail.lines),
+				outputBytes: outputBytesOverride ?? headBytes + partialTail.bytes + separatorBytes + markerBytes,
+				...(maxBytes !== undefined ? { maxBytes } : {}),
+				partialLine: {
+					line: partialTail.origin.startLine,
+					bytes: partialTail.bytes,
+					sourceBytes: partialTail.sourceLineBytes,
+				},
+				artifactId,
+			};
+			return this;
+		}
 
-		const { direction, startLine = 1, totalFileLines } = options;
+		if (windows.kind === "head-only" && windows.head) {
+			const { head } = windows;
+			this.#meta.truncation = {
+				direction: "head",
+				truncatedBy: fallbackTruncatedBy,
+				...owner,
+				...rangeBaseMeta,
+				totalLines: windows.totalLines,
+				totalBytes: windows.totalBytes,
+				outputLines: outputLinesOverride ?? head.lines,
+				outputBytes: outputBytesOverride ?? head.bytes,
+				...(maxBytes !== undefined ? { maxBytes } : {}),
+				shownRange: { start: head.origin.startLine, end: head.origin.endLine },
+				artifactId,
+				nextOffset: head.origin.endLine + 1,
+			};
+			return this;
+		}
+
+		if (windows.kind === "tail-only" && windows.tail) {
+			const { tail } = windows;
+			this.#meta.truncation = {
+				direction: "tail",
+				truncatedBy: fallbackTruncatedBy,
+				...owner,
+				...rangeBaseMeta,
+				totalLines: windows.totalLines,
+				totalBytes: windows.totalBytes,
+				outputLines: outputLinesOverride ?? tail.lines,
+				outputBytes: outputBytesOverride ?? tail.bytes,
+				...(maxBytes !== undefined ? { maxBytes } : {}),
+				shownRange: { start: tail.origin.startLine, end: tail.origin.endLine },
+				artifactId,
+			};
+			return this;
+		}
+
+		const { head, tail } = windows;
+		if (!head || !tail) return this;
+		const marker = formatMiddleElisionMarker(windows.elidedLines, windows.elidedBytes);
+		this.#meta.truncation = {
+			direction: "middle",
+			truncatedBy: "middle",
+			...owner,
+			...rangeBaseMeta,
+			totalLines: windows.totalLines,
+			totalBytes: windows.totalBytes,
+			outputLines: head.lines + tail.lines + 1,
+			outputBytes: head.bytes + tail.bytes + Buffer.byteLength(marker, "utf-8") + 2,
+			...(maxBytes !== undefined ? { maxBytes } : {}),
+			headRange: { start: head.origin.startLine, end: head.origin.endLine },
+			tailRange: { start: tail.origin.startLine, end: tail.origin.endLine },
+			elidedLines: windows.elidedLines,
+			elidedBytes: windows.elidedBytes,
+			artifactId,
+		};
+		return this;
+	}
+
+	/** Add truncation info from OutputSummary. No-op if not truncated or artifact evidence is absent. */
+	truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this {
+		const artifactFailureDiagnostic = summary.artifactFailureDiagnostic;
+		const artifactTruncatedBytes =
+			summary.artifactTruncatedBytes != null && summary.artifactTruncatedBytes > 0
+				? summary.artifactTruncatedBytes
+				: undefined;
+		const hasArtifactEvidence =
+			summary.artifactId !== undefined ||
+			artifactFailureDiagnostic !== undefined ||
+			artifactTruncatedBytes !== undefined;
+		if (!summary.truncated && !hasArtifactEvidence) return this;
+
+		const { direction, startLine = 1, totalFileLines, noticeOwner } = options;
 		const totalLines = totalFileLines ?? summary.totalLines;
+		const bodyHasArtifact =
+			summary.artifactId !== undefined && summary.output.includes(`artifact://${summary.artifactId}`);
+		const bodyOwnsArtifact =
+			bodyHasArtifact &&
+			(artifactTruncatedBytes === undefined ||
+				(summary.artifactId !== undefined &&
+					summary.output.includes(formatArtifactReference(summary.artifactId, artifactTruncatedBytes))));
+		const owner =
+			noticeOwner !== undefined ? { noticeOwner } : bodyOwnsArtifact ? { noticeOwner: "body" as const } : {};
 
 		// Middle elision: the sink retained head + tail with an elision marker.
 		if (summary.elidedBytes != null && summary.elidedBytes > 0) {
@@ -206,6 +361,7 @@ export class OutputMetaBuilder {
 			this.#meta.truncation = {
 				direction: "middle",
 				truncatedBy: "middle",
+				...owner,
 				totalLines,
 				totalBytes: summary.totalBytes,
 				outputLines: summary.outputLines,
@@ -215,6 +371,8 @@ export class OutputMetaBuilder {
 				elidedBytes: summary.elidedBytes,
 				elidedLines,
 				artifactId: summary.artifactId,
+				artifactTruncatedBytes,
+				artifactFailureDiagnostic,
 			};
 			return this;
 		}
@@ -240,12 +398,15 @@ export class OutputMetaBuilder {
 		this.#meta.truncation = {
 			direction,
 			truncatedBy,
+			...owner,
 			totalLines,
 			totalBytes: summary.totalBytes,
 			outputLines: summary.outputLines,
 			outputBytes: summary.outputBytes,
 			shownRange: { start: shownStart, end: shownEnd },
 			artifactId: summary.artifactId,
+			artifactTruncatedBytes,
+			artifactFailureDiagnostic,
 			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
 		};
 
@@ -285,6 +446,7 @@ export class OutputMetaBuilder {
 		this.#meta.truncation = {
 			direction: options.direction,
 			truncatedBy,
+			...(options.noticeOwner !== undefined ? { noticeOwner: options.noticeOwner } : {}),
 			totalLines,
 			totalBytes,
 			outputLines,
@@ -387,7 +549,56 @@ export function formatFullOutputReference(artifactId: string): string {
 	return `Read artifact://${artifactId} for full output`;
 }
 
+/**
+ * Format an artifact reference without claiming completeness when storage was hard-capped.
+ */
+export function formatArtifactReference(artifactId: string, artifactTruncatedBytes?: number): string {
+	if (artifactTruncatedBytes != null && artifactTruncatedBytes > 0) {
+		return `Read artifact://${artifactId} for retained output (at least ${formatBytes(artifactTruncatedBytes)} omitted by the artifact storage cap)`;
+	}
+	return formatFullOutputReference(artifactId);
+}
+
+function formatTruncationArtifactNotice(truncation: TruncationMeta): string {
+	const reference = truncation.artifactId
+		? formatArtifactReference(truncation.artifactId, truncation.artifactTruncatedBytes)
+		: undefined;
+	if (truncation.artifactFailureDiagnostic) {
+		const failure = `Artifact storage failed: ${truncation.artifactFailureDiagnostic}`;
+		if (reference) return `${reference}; ${failure}`;
+		return failure;
+	}
+	if (reference) return reference;
+	return `Artifact storage omitted at least ${formatBytes(truncation.artifactTruncatedBytes ?? 0)}; no artifact reference is available`;
+}
+
+function hasArtifactNotice(truncation: TruncationMeta): boolean {
+	return (
+		truncation.artifactId != null ||
+		(truncation.artifactTruncatedBytes ?? 0) > 0 ||
+		truncation.artifactFailureDiagnostic != null
+	);
+}
+
+function formatTruncationRangeTotal(truncation: TruncationMeta): string {
+	return truncation.rangeBase === "window"
+		? `the selected ${truncation.totalLines}-line range`
+		: `${truncation.totalLines}`;
+}
+
 export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
+	const rangeTotal = formatTruncationRangeTotal(truncation);
+	if (truncation.partialLine) {
+		let notice = `Showing last ${formatBytes(truncation.partialLine.bytes)} of line ${truncation.partialLine.line} of ${rangeTotal}`;
+		if (truncation.partialLine.sourceBytes > truncation.partialLine.bytes) {
+			notice += ` (line is ${formatBytes(truncation.partialLine.sourceBytes)})`;
+		}
+		if (hasArtifactNotice(truncation)) {
+			notice += `. ${formatTruncationArtifactNotice(truncation)}`;
+		}
+		return notice;
+	}
+
 	let notice: string;
 
 	if (truncation.direction === "middle") {
@@ -398,22 +609,24 @@ export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 		const elidedLines = truncation.elidedLines ?? Math.max(0, totalLines - truncation.outputLines);
 		const headPart = head ? `lines ${head.start}-${head.end}` : "";
 		const tailPart = tail ? `${tail.start}-${tail.end}` : "";
-		if (headPart && tailPart) {
-			notice = `Showing ${headPart} and ${tailPart} of ${totalLines}; ${elidedLines.toLocaleString()} middle line${elidedLines === 1 ? "" : "s"} (${formatBytes(elidedBytes)}) elided`;
+		if (head && tail && elidedLines === 0 && head.start === tail.start && head.end === tail.end) {
+			notice = `Showing head and tail of line ${head.start} of ${rangeTotal}; ${formatBytes(elidedBytes)} middle bytes elided`;
+		} else if (headPart && tailPart) {
+			notice = `Showing ${headPart} and ${tailPart} of ${rangeTotal}; ${elidedLines.toLocaleString()} middle line${elidedLines === 1 ? "" : "s"} (${formatBytes(elidedBytes)}) elided`;
 		} else {
-			notice = `Showing ${truncation.outputLines} of ${totalLines} lines; middle elided`;
+			notice = `Showing ${truncation.outputLines} of ${rangeTotal}${truncation.rangeBase === "window" ? "" : " lines"}; ${formatBytes(elidedBytes)} middle bytes elided`;
 		}
-		if (truncation.artifactId != null) {
-			notice += `. ${formatFullOutputReference(truncation.artifactId)}`;
+		if (hasArtifactNotice(truncation)) {
+			notice += `. ${formatTruncationArtifactNotice(truncation)}`;
 		}
 		return notice;
 	}
 
 	const range = truncation.shownRange;
 	if (range && range.end >= range.start) {
-		notice = `Showing lines ${range.start}-${range.end} of ${truncation.totalLines}`;
+		notice = `Showing lines ${range.start}-${range.end} of ${rangeTotal}`;
 	} else {
-		notice = `Showing ${truncation.outputLines} of ${truncation.totalLines} lines`;
+		notice = `Showing ${truncation.outputLines} of ${rangeTotal}${truncation.rangeBase === "window" ? "" : " lines"}`;
 	}
 
 	if (truncation.truncatedBy === "bytes") {
@@ -425,8 +638,8 @@ export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 		notice += `. Use :${truncation.nextOffset} to continue`;
 	}
 
-	if (truncation.artifactId != null) {
-		notice += `. ${formatFullOutputReference(truncation.artifactId)}`;
+	if (hasArtifactNotice(truncation)) {
+		notice += `. ${formatTruncationArtifactNotice(truncation)}`;
 	}
 
 	return notice;
@@ -450,7 +663,7 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
 	const parts: string[] = [];
 
 	// Truncation notice
-	if (meta.truncation) {
+	if (meta.truncation && meta.truncation.noticeOwner !== "body") {
 		parts.push(formatTruncationMetaNotice(meta.truncation));
 	}
 
@@ -487,8 +700,25 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
  * Returns null if no truncation metadata present.
  */
 export function formatStyledTruncationWarning(meta: OutputMeta | undefined, theme: Theme): string | null {
-	if (!meta?.truncation) return null;
-	const message = formatTruncationMetaNotice(meta.truncation);
+	const truncation = meta?.truncation;
+	if (!truncation) return null;
+	if (
+		truncation.noticeOwner === "body" &&
+		truncation.totalBytes === truncation.outputBytes &&
+		truncation.totalLines === truncation.outputLines
+	) {
+		return null;
+	}
+	const warningMeta =
+		truncation.noticeOwner === "body"
+			? {
+					...truncation,
+					artifactId: undefined,
+					artifactTruncatedBytes: undefined,
+					artifactFailureDiagnostic: undefined,
+				}
+			: truncation;
+	const message = formatTruncationMetaNotice(warningMeta);
 	return theme.fg("warning", wrapBrackets(message, theme));
 }
 
@@ -580,6 +810,25 @@ export function resolveOutputSinkHeadBytes(s: Settings | undefined): number {
 	return getSpillConfig(s).headBytes;
 }
 
+export const BASH_DEFAULT_OUTPUT_TAIL_BYTES = 1024;
+
+/**
+ * Bash uses a deliberately small tail window to nudge callers toward focused
+ * commands and dedicated search tools. An explicitly configured shared tail
+ * budget still wins.
+ */
+export function resolveBashOutputSinkTailBytes(s: Settings): number {
+	return s.has("tools.artifactTailBytes") ? s.get("tools.artifactTailBytes") * 1024 : BASH_DEFAULT_OUTPUT_TAIL_BYTES;
+}
+/**
+ * Bash keeps only the tail unless the user explicitly opts into the shared
+ * head-retention setting. Schema defaults still apply to other streaming
+ * tools without silently turning Bash back into middle-elision mode.
+ */
+export function resolveBashOutputSinkHeadBytes(s: Settings): number {
+	return s.has("tools.artifactHeadBytes") ? resolveOutputSinkHeadBytes(s) : 0;
+}
+
 /**
  * Resolve the per-line column cap from session settings. Shared by streaming
  * executors (bash/python/ssh/eval via OutputSink) and the `read` tool's
@@ -710,6 +959,17 @@ async function spillLargeResultToArtifact(
 	return { ...result, content: newContent, details: newDetails };
 }
 
+const BODY_TRUNCATION_FOOTER_KEY = "__bodyTruncationFooter";
+
+function stripBodyOwnedTruncationFooter(text: string, details: unknown): string {
+	const footer = (details as { [BODY_TRUNCATION_FOOTER_KEY]?: unknown } | undefined)?.[BODY_TRUNCATION_FOOTER_KEY];
+	if (typeof footer !== "string" || footer.length === 0) return text;
+	const trimmedText = text.trimEnd();
+	const trimmedFooter = footer.trim();
+	if (!trimmedText.endsWith(trimmedFooter)) return text;
+	return trimmedText.slice(0, -trimmedFooter.length).trimEnd();
+}
+
 /**
  * Absolute inline-size backstop enforced after {@link spillLargeResultToArtifact}.
  *
@@ -738,7 +998,8 @@ async function enforceInlineResultBackstop(
 	}
 	if (textParts.length === 0) return result;
 
-	const fullText = textParts.length === 1 ? textParts[0] : textParts.join("\n");
+	const renderedText = textParts.length === 1 ? textParts[0] : textParts.join("\n");
+	const fullText = stripBodyOwnedTruncationFooter(renderedText, result.details);
 	const totalBytes = Buffer.byteLength(fullText, "utf-8");
 	if (totalBytes <= maxInlineBytes) return result;
 

package/src/tools/path-utils.ts

@@ -33,7 +33,11 @@ function normalizeUnicodeSpaces(str: string): string {
 }
 
 function tryMacOSScreenshotPath(filePath: string): string {
-	return filePath.replace(/ (AM|PM)\./g, `${NARROW_NO_BREAK_SPACE}$1.`);
+	// macOS writes a narrow no-break space before AM/PM, but the model normalizes it
+	// to a plain space. The original name is not always `…PM.png`: attachment paths
+	// append a timestamp (`…PM-1785075812409.png`), so match any non-alphanumeric
+	// separator or end of segment rather than a literal dot.
+	return filePath.replace(/ (AM|PM)(?=[^A-Za-z0-9/]|$)/g, `${NARROW_NO_BREAK_SPACE}$1`);
 }
 
 function tryNFDVariant(filePath: string): string {
@@ -633,6 +637,7 @@ export interface ToolScopeOptions {
 	rawPaths: string[];
 	cwd: string;
 	getArtifactsDir?: () => string | null;
+	getAuthorizedArtifactsDirs?: () => readonly string[];
 	/** Verb used in the "Cannot {action} internal URL without a backing file: …" message. */
 	internalUrlAction: string;
 	/** Collect absolute paths flagged immutable by their internal-URL handler. */
@@ -663,7 +668,7 @@ export interface ToolScopeResolution {
  *  5. stat the resolved base path so callers can branch on directory vs file scope.
  */
 export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<ToolScopeResolution> {
-	const { rawPaths: inputs, cwd, internalUrlAction, getArtifactsDir } = opts;
+	const { rawPaths: inputs, cwd, internalUrlAction, getArtifactsDir, getAuthorizedArtifactsDirs } = opts;
 	const rawPaths = inputs.map(normalizePathLikeInput);
 	if (rawPaths.some(rawPath => rawPath.length === 0)) {
 		throw new ToolError("`paths` must contain non-empty paths or globs");
@@ -679,7 +684,7 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 		if (hasGlobPathChars(rawPath)) {
 			throw new ToolError(`Glob patterns are not supported for internal URLs: ${rawPath}`);
 		}
-		const resource = await internalRouter.resolve(rawPath, { cwd, getArtifactsDir });
+		const resource = await internalRouter.resolve(rawPath, { cwd, getArtifactsDir, getAuthorizedArtifactsDirs });
 		if (!resource.sourcePath) {
 			throw new ToolError(`Cannot ${internalUrlAction} internal URL without a backing file: ${rawPath}`);
 		}

package/src/tools/read-internals.ts

@@ -0,0 +1,44 @@
+import type { Settings } from "../config/settings";
+import type { TruncationDirection } from "../session/streaming-output";
+
+/**
+ * Read execution routes that have distinct truncation-default contracts.
+ * Routes that share the same default are grouped only when their truncation
+ * policy is identical; selection and rendering remain owned by read.ts.
+ */
+export type ReadRoute =
+	| "local-bare-stream"
+	| "local-bare-acp"
+	| "archive-member-bare"
+	| "local-range"
+	| "local-multi-range"
+	| "local-raw"
+	| "local-summary"
+	| "url-reader"
+	| "url-cache-page"
+	| "dir-local"
+	| "dir-archive"
+	| "sqlite-list"
+	| "sqlite-rows"
+	| "converted";
+
+/** Resolve the configured default for a route; explicit parameters bypass it. */
+export function pathDefault(route: ReadRoute, settings: Settings): TruncationDirection {
+	switch (route) {
+		case "local-bare-stream":
+		case "local-bare-acp":
+		case "archive-member-bare":
+			return settings.get("read.truncation") ?? "last";
+		default:
+			return "head";
+	}
+}
+
+/** Resolve the effective caller-facing direction with explicit precedence. */
+export function resolveEffectiveDirection(
+	explicitParam: TruncationDirection | undefined,
+	route: ReadRoute,
+	settings: Settings,
+): TruncationDirection {
+	return explicitParam !== undefined ? explicitParam : pathDefault(route, settings);
+}