@linxiraos/pi-tui 1.2.1 → 1.3.1

package/src/tools/lsp.ts

@@ -28,6 +28,8 @@ import {
 } from "../render/render-utils";
 import { renderStatusLine } from "../render";
 import { framedToolCard } from "../render/tool-card";
+import { wrapGuidedLine, wrapPrefixedLine } from "../render/hanging-wrap";
+import { visibleWidth } from "../utils";
 import { ansi, code, col, compact, keyed, md, node, row, span, text } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { OwnerMemo } from "../native/memo";
@@ -245,7 +247,7 @@ export function renderResult(
 		return { label: "Response", state: "success", bodyLines: renderGeneric(text, lines, expanded, theme) };
 	};
 
-	return framedToolCard(theme, () => {
+	return framedToolCard(theme, ({ contentWidth }) => {
 		// Read mutable state at render time
 		const { expanded, isPartial, spinnerFrame } = options;
 		const slot = expanded ? 1 : 0;
@@ -263,12 +265,22 @@ export function renderResult(
 			: formatStatusIcon(isPartial ? "running" : "error", theme, spinnerFrame);
 		const header = `${icon} LSP ${actionLabel}`;
 
+		// Hover code hangs under its rail; expanded rows hang under their tree
+		// connector or guide rails so Ctrl+O reveals full text instead of clipping.
+		const rail = ` ${theme.fg("mdCodeBlockBorder", theme.boxRound.vertical)} `;
+		const contentLines = codeBlockMatch
+			? bodyLines.flatMap(line =>
+					line.startsWith(rail) ? wrapPrefixedLine(rail, rail, line.slice(rail.length), contentWidth) : [line],
+				)
+			: expanded
+				? bodyLines.flatMap(line => wrapGuidedLine(line, contentWidth, theme))
+				: bodyLines;
 		return {
 			header,
 			phase: isPartial ? "partial" : state,
 			sections: [
 				...(requestLines.length > 0 ? [{ content: requestLines }] : []),
-				{ label: theme.fg("toolTitle", "Response"), content: bodyLines },
+				{ label: theme.fg("toolTitle", "Response"), content: contentLines },
 			],
 			applyBg: false,
 		};
@@ -413,10 +425,7 @@ function renderDiagnostics(
 			)}`;
 			const message = formatDiagnosticMessage(item);
 			if (message) {
-				output += `\n ${theme.fg("dim", detailPrefix)}${theme.fg(
-					"muted",
-					truncateToWidth(message, TRUNCATE_LENGTHS.LINE),
-				)}`;
+				output += `\n ${theme.fg("dim", detailPrefix)}${theme.fg("muted", message)}`;
 			}
 		}
 		return output.split("\n");
@@ -427,7 +436,10 @@ function renderDiagnostics(
 		parsedDiagnostics.length > 0 ? parsedDiagnostics.slice(0, 3) : fallbackDiagnostics.slice(0, 3);
 	const remaining =
 		(parsedDiagnostics.length > 0 ? parsedDiagnostics.length : fallbackDiagnostics.length) - previewItems.length;
-	const expandHint = formatExpandHint(theme, expanded, remaining > 0);
+	const clipped = previewItems.some(
+		item => !("raw" in item) && visibleWidth(formatDiagnosticMessage(item)) > TRUNCATE_LENGTHS.CONTENT,
+	);
+	const expandHint = formatExpandHint(theme, expanded, remaining > 0 || clipped);
 	let output = `${icon} ${theme.fg("dim", meta.join(theme.sep.dot))}${expandHint}`;
 	for (let i = 0; i < previewItems.length; i++) {
 		const item = previewItems[i];
@@ -479,8 +491,9 @@ function renderReferences(refMatch: RegExpMatchArray, lines: string[], expanded:
 
 	const files = Array.from(byFile.keys());
 
-	const renderGrouped = (maxFiles: number, maxLocsPerFile: number, showHint: boolean): string => {
-		const expandHint = formatExpandHint(theme, undefined, showHint);
+	const renderGrouped = (maxFiles: number, maxLocsPerFile: number): string => {
+		const hidden = files.length > maxFiles || files.some(file => byFile.get(file)!.length > maxLocsPerFile);
+		const expandHint = formatExpandHint(theme, expanded, hidden);
 		let output = `${icon} ${theme.fg("dim", `${refCount} found`)}${expandHint}`;
 
 		const filesToShow = files.slice(0, maxFiles);
@@ -506,10 +519,9 @@ function renderReferences(refMatch: RegExpMatchArray, lines: string[], expanded:
 						`line ${line}, col ${col}`,
 					)}`;
 					if (expanded) {
-						const context = `at ${file}:${line}:${col}`;
 						output += `\n ${theme.fg("dim", fileCont)}${theme.fg("dim", locCont)}${theme.fg(
 							"muted",
-							truncateToWidth(context, TRUNCATE_LENGTHS.LINE),
+							`at ${file}:${line}:${col}`,
 						)}`;
 					}
 				}
@@ -532,11 +544,7 @@ function renderReferences(refMatch: RegExpMatchArray, lines: string[], expanded:
 		return output;
 	};
 
-	if (expanded) {
-		return renderGrouped(files.length, 3, false).split("\n");
-	}
-
-	return renderGrouped(3, 1, true).split("\n");
+	return (expanded ? renderGrouped(files.length, Number.POSITIVE_INFINITY) : renderGrouped(3, 1)).split("\n");
 }
 
 // =============================================================================
@@ -658,13 +666,17 @@ function renderGeneric(text: string, lines: string[], expanded: boolean, theme:
 		for (let i = 0; i < lines.length; i++) {
 			const isLast = i === lines.length - 1;
 			const branch = isLast ? theme.tree.last : theme.tree.branch;
-			output += `\n ${theme.fg("dim", branch)} ${truncateToWidth(replaceTabs(lines[i]), TRUNCATE_LENGTHS.CONTENT)}`;
+			output += `\n ${theme.fg("dim", branch)} ${replaceTabs(lines[i])}`;
 		}
 		return output.split("\n");
 	}
 
 	const firstLine = lines[0] || "No output";
-	const expandHint = formatExpandHint(theme, expanded, lines.length > 1);
+	const expandHint = formatExpandHint(
+		theme,
+		expanded,
+		lines.length > 1 || visibleWidth(firstLine) > TRUNCATE_LENGTHS.TITLE,
+	);
 	let output = `${icon} ${theme.fg("dim", truncateToWidth(firstLine, TRUNCATE_LENGTHS.TITLE))}${expandHint}`;
 
 	if (lines.length > 1) {

package/src/tools/mcp.ts

@@ -26,7 +26,7 @@ import {
 	renderJsonTreeLines,
 } from "./json-tree";
 import { formatStyledTruncationWarning, stripOutputNotice } from "./output-meta";
-import { formatExpandHint, truncateToWidth } from "../render/render-utils";
+import { clipCollapsed, formatExpandHint } from "../render/render-utils";
 import { formatOutputPaneLines, styleToolOutputLine } from "../render/output-pane";
 import type { StatusLineOptions } from "../render/status-line";
 import { plainToolCard, type ToolCardPhase } from "../render/tool-card";
@@ -267,7 +267,7 @@ export function renderMCPResult(
 					expanded,
 					collapsedMaxLines: 4,
 					expandedMaxLines: 12,
-					styleLine: line => truncateToWidth(styleToolOutputLine(line, theme), contentWidth),
+					styleLine: line => clipCollapsed(styleToolOutputLine(line, theme), contentWidth, expanded),
 					showExpandHintWhenUncapped: true,
 				},
 				theme,

package/src/tools/native-view.d.ts

@@ -85,7 +85,7 @@ export interface RunFootInput {
     readonly state: RunState;
     /** Exit code of a `failed` run; a non-zero code names the state `exit N`. */
     readonly exitCode?: number;
-    /** Milliseconds run so far (`running`) or in total; the time is omitted when undefined. */
+    /** Milliseconds run so far (`running`, a live `background` job) or in total; omitted when undefined. */
     readonly elapsedMs?: number;
     /** Quiet facts (job id, service state, artifact), muted and ` · `-joined. */
     readonly facts?: readonly string[];

package/src/tools/native-view.ts

@@ -216,7 +216,7 @@ export interface RunFootInput {
 	readonly state: RunState;
 	/** Exit code of a `failed` run; a non-zero code names the state `exit N`. */
 	readonly exitCode?: number;
-	/** Milliseconds run so far (`running`) or in total; the time is omitted when undefined. */
+	/** Milliseconds run so far (`running`, a live `background` job) or in total; omitted when undefined. */
 	readonly elapsedMs?: number;
 	/** Quiet facts (job id, service state, artifact), muted and ` · `-joined. */
 	readonly facts?: readonly string[];
@@ -250,7 +250,7 @@ export function runFoot(input: RunFootInput): NativeNode {
 			? undefined
 			: node(
 					"elapsed",
-					input.state === "running"
+					input.state === "running" || input.state === "background"
 						? { role: "zeta.run.time", age: ms, format: "short" }
 						: { role: "zeta.run.time", age: ms, stopped: ms, format: "short" },
 					undefined,

package/src/tools/read.d.ts

@@ -1,6 +1,6 @@
 import type { SummaryResult } from "@linxiraos/pi-natives";
 import type { Component } from "../tui";
-import type { NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer";
+import type { RenderResultContextOptions, NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer";
 import type { NativeNode } from "../native/node";
 import type { Theme } from "../theme/theme";
 import type { OutputMeta } from "./output-meta";
@@ -20,6 +20,12 @@ export interface ReadToolDetails {
     truncation?: ReadTruncationStats;
     isDirectory?: boolean;
     resolvedPath?: string;
+    /**
+     * Absolute path of the disk file whose image this read returned. A native TSP host that
+     * supports `media` shows the file by path instead of the uploaded image bytes. Unset for
+     * screenshots, URL reads and other images not backed by a file. Display-only.
+     */
+    mediaPath?: string;
     suffixResolution?: {
         from: string;
         to: string;
@@ -34,6 +40,11 @@ export interface ReadToolDetails {
     fileSize?: number;
     /** Full source line count when the read reached EOF and the count is exact. */
     totalLines?: number;
+    /**
+     * Whether the text's rows carry line-number prefixes (`N:` hashline, `N|` line numbers). Set where a
+     * file read is formatted; a raw read sets `false`. Snapcompact reads it to tell a `12:` prefix from content.
+     */
+    rowPrefixes?: 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. */
@@ -49,7 +60,10 @@ export interface ReadToolDetails {
     };
     /** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
     conflictCount?: number;
-    /** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
+    /**
+     * Paths recovered from a delimited read argument. The TUI renders one call as multiple read rows; snapcompact
+     * keeps such a composite result as text.
+     */
     displayReadTargets?: string[];
     /**
      * Resolved filesystem link target for each {@link displayReadTargets} entry, aligned by index; `null` when a
@@ -107,14 +121,22 @@ export declare function pendingFileLinkPath(inputPath: string): string;
  * target when the structured `resolvedPath` isn't set (the common plain-file and
  * image reads only record the path in `meta.source`). URL/internal sources are
  * not fs paths, so only `type: "path"` qualifies. */
-export declare function readSourceFsPath(details: ReadToolDetails | undefined): string | undefined;
+export declare function readSourceFsPath(details: unknown): string | undefined;
+/**
+ * Whether a read result renders as a Markdown preview rather than numbered source:
+ * the read tool tagged it `text/markdown` (`read.renderMarkdown`, or a protocol
+ * resource) and the call did not ask for `:raw` source. Shared by the standalone
+ * read card and the read group's content previews so both honor the setting.
+ */
+export declare function readResultIsMarkdown(details: ReadToolDetails | undefined, args: ReadRenderArgs | undefined): boolean;
 /**
- * Read content as numbered `code` (no path header: the head names the file).
- * Numbers come from `lineNumbers` (`displayContent`'s per-line numbers,
- * `null` for an elided block; runs split with `…` between) when they cover
- * every line, else count up from `start`.
+ * Read content as numbered, wrapped `code` (no path header: the head names
+ * the file), matching the ANSI preview's hanging wrap. Numbers come from
+ * `lineNumbers` (`displayContent`'s per-line numbers, `null` for an elided
+ * block; runs split with `…` between) when they cover every line, else count
+ * up from `start`.
  */
-export declare function readContentCode(content: string, start: number, numbers: readonly (number | null)[] | undefined, lang: string | undefined): NativeNode[];
+export declare function readContentCode(content: string, start: number, numbers: readonly (number | null)[] | undefined, path: string | undefined): NativeNode[];
 /** Render file, image, and URL reads in the transcript. */
 export declare const readToolRenderer: {
     activitySummary(args: unknown, _context: ToolActivityContext): ToolActivitySummary;
@@ -126,7 +148,7 @@ export declare const readToolRenderer: {
         }>;
         details?: ReadToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: ReadRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: ReadRenderArgs): Component;
     describeCall(args: ReadRenderArgs): NativeToolView;
     /**
      * Inline (§7.3 read): the head names the file and range; the content
@@ -140,7 +162,7 @@ export declare const readToolRenderer: {
         }>;
         details?: ReadToolDetails;
         isError?: boolean;
-    }, _options: RenderResultOptions, args?: ReadRenderArgs): NativeToolView;
+    }, options: RenderResultContextOptions, args?: ReadRenderArgs): NativeToolView;
     mergeCallAndResult: true;
 };
 /** Inclusive line range describing one elided span in a structural summary. */

package/src/tools/read.ts

@@ -4,10 +4,12 @@ import { LINE_RANGE_CHUNK_SOURCE, parseLineRanges } from "./line-ranges";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseArchivePathCandidates } from "@linxiraos/pi-utils/ar";
+import { isRecord, sanitizeText } from "@linxiraos/pi-utils";
 import type { Component } from "../tui";
 import { Text } from "../components/text";
 import type {
 	NativeToolHead,
+	RenderResultContextOptions,
 	NativeToolView,
 	RenderResultOptions,
 	ToolActivityContext,
@@ -15,7 +17,7 @@ import type {
 	ToolRenderer,
 } from "./renderer";
 import { ansi, compact, md } from "../native/describe";
-import { base64ImageNode } from "../native/blobs";
+import { base64ImageNode, nativeMediaNode, readMediaPath } from "../native/blobs";
 import type { NativeChild, NativeNode } from "../native/node";
 import { fileHref, footnoteText, inlineErrorView, resultText } from "./native-view";
 import { numberedCode } from "./grouped-file-output";
@@ -54,6 +56,12 @@ export interface ReadToolDetails {
 	truncation?: ReadTruncationStats;
 	isDirectory?: boolean;
 	resolvedPath?: string;
+	/**
+	 * Absolute path of the disk file whose image this read returned. A native TSP host that
+	 * supports `media` shows the file by path instead of the uploaded image bytes. Unset for
+	 * screenshots, URL reads and other images not backed by a file. Display-only.
+	 */
+	mediaPath?: string;
 	suffixResolution?: { from: string; to: string };
 	url?: string;
 	finalUrl?: string;
@@ -65,6 +73,11 @@ export interface ReadToolDetails {
 	fileSize?: number;
 	/** Full source line count when the read reached EOF and the count is exact. */
 	totalLines?: number;
+	/**
+	 * Whether the text's rows carry line-number prefixes (`N:` hashline, `N|` line numbers). Set where a
+	 * file read is formatted; a raw read sets `false`. Snapcompact reads it to tell a `12:` prefix from content.
+	 */
+	rowPrefixes?: 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. */
@@ -76,7 +89,10 @@ export interface ReadToolDetails {
 	summary?: { lines: number; elidedSpans: number; elidedLines: number };
 	/** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
 	conflictCount?: number;
-	/** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
+	/**
+	 * Paths recovered from a delimited read argument. The TUI renders one call as multiple read rows; snapcompact
+	 * keeps such a composite result as text.
+	 */
 	displayReadTargets?: string[];
 	/**
 	 * Resolved filesystem link target for each {@link displayReadTargets} entry, aligned by index; `null` when a
@@ -296,9 +312,17 @@ function firstReadSelectorLine(sel: string | undefined): number | undefined {
  * target when the structured `resolvedPath` isn't set (the common plain-file and
  * image reads only record the path in `meta.source`). URL/internal sources are
  * not fs paths, so only `type: "path"` qualifies. */
-export function readSourceFsPath(details: ReadToolDetails | undefined): string | undefined {
-	const source = details?.meta?.source;
-	return source?.type === "path" && typeof source.value === "string" ? source.value : undefined;
+export function readSourceFsPath(details: unknown): string | undefined {
+	if (!isRecord(details) || !isRecord(details.meta) || !isRecord(details.meta.source)) return undefined;
+	const source = details.meta.source;
+	return source.type === "path" && typeof source.value === "string" ? source.value : undefined;
+}
+
+function readLinkTarget(details: unknown): string | undefined {
+	if (!isRecord(details)) return undefined;
+	if (typeof details.resolvedPath === "string") return details.resolvedPath;
+	if (typeof details.displayTarget === "string") return details.displayTarget;
+	return readSourceFsPath(details);
 }
 
 function formatReadPathLink(
@@ -314,9 +338,11 @@ function formatReadPathLink(
 	const split = splitReadRenderPath(rawPath);
 	const basePath = split.path || rawPath;
 	const selectorSuffix = split.sel ? `:${split.sel}` : "";
-	const plainDisplayPath = options.suffixResolution
-		? shortenPath(options.suffixResolution.to)
-		: shortenPath(basePath || options.resolvedPath || options.fallbackLabel || rawPath);
+	const plainDisplayPath = sanitizeText(
+		options.suffixResolution
+			? shortenPath(options.suffixResolution.to)
+			: shortenPath(basePath || options.resolvedPath || options.fallbackLabel || rawPath),
+	);
 	// Calls render before the tool has resolved a filesystem target. Preserve
 	// protocol resources as plain text, but resolve direct relative file paths
 	// so terminals receive an explicit file: link rather than guessing HTTPS.
@@ -335,12 +361,29 @@ function readRawPath(args: ReadRenderArgs | undefined): string {
 	return typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
 }
 
+/**
+ * Whether a read result renders as a Markdown preview rather than numbered source:
+ * the read tool tagged it `text/markdown` (`read.renderMarkdown`, or a protocol
+ * resource) and the call did not ask for `:raw` source. Shared by the standalone
+ * read card and the read group's content previews so both honor the setting.
+ */
+export function readResultIsMarkdown(details: ReadToolDetails | undefined, args: ReadRenderArgs | undefined): boolean {
+	if (details?.contentType !== "text/markdown" || args?.raw === true) return false;
+	const sel = splitReadRenderPath(readRawPath(args)).sel;
+	return sel?.split(":").some(chunk => chunk.toLowerCase() === "raw") !== true;
+}
+
 /**
  * Native read head (§7.3 read): `Read path:13-36` with the path as the
  * target (shortened, plus the selector / legacy offset range), a `file://`
  * link when the fs path is known, and a suffix correction as meta.
  */
-function readNativeHead(rawPath: string, args: ReadRenderArgs | undefined, details?: ReadToolDetails): NativeToolHead {
+function readNativeHead(
+	rawPath: string,
+	args: ReadRenderArgs | undefined,
+	details?: ReadToolDetails,
+	linkPath?: string,
+): NativeToolHead {
 	const split = splitReadRenderPath(rawPath);
 	const suffix = details?.suffixResolution;
 	let target = suffix ? shortenPath(suffix.to) : shortenPath(split.path || rawPath);
@@ -359,9 +402,9 @@ function readNativeHead(rawPath: string, args: ReadRenderArgs | undefined, detai
 	const conflicts = details?.conflictCount ?? 0;
 	return {
 		title: "Read",
-		target: target || "…",
+		target: sanitizeText(target) || "…",
 		targetKind: "path",
-		href: fileHref(details?.resolvedPath ?? details?.displayTarget ?? readSourceFsPath(details)),
+		href: fileHref(linkPath ?? details?.resolvedPath ?? details?.displayTarget ?? readSourceFsPath(details)),
 		meta,
 		badges:
 			conflicts > 0 ? [{ text: `${conflicts} conflict${conflicts === 1 ? "" : "s"}`, tone: "warning" }] : undefined,
@@ -378,21 +421,22 @@ function readRangeStart(rawPath: string, args: ReadRenderArgs | undefined): numb
 }
 
 /**
- * Read content as numbered `code` (no path header: the head names the file).
- * Numbers come from `lineNumbers` (`displayContent`'s per-line numbers,
- * `null` for an elided block; runs split with `…` between) when they cover
- * every line, else count up from `start`.
+ * Read content as numbered, wrapped `code` (no path header: the head names
+ * the file), matching the ANSI preview's hanging wrap. Numbers come from
+ * `lineNumbers` (`displayContent`'s per-line numbers, `null` for an elided
+ * block; runs split with `…` between) when they cover every line, else count
+ * up from `start`.
  */
 export function readContentCode(
 	content: string,
 	start: number,
 	numbers: readonly (number | null)[] | undefined,
-	lang: string | undefined,
+	path: string | undefined,
 ): NativeNode[] {
 	const lines = content.split("\n");
 	return numberedCode(
 		lines.map((text, i) => ({ n: numbers && numbers.length === lines.length ? numbers[i]! : start + i, text })),
-		{ lang },
+		{ path, wrap: true },
 	);
 }
 
@@ -435,7 +479,7 @@ export const readToolRenderer = {
 			typeof input?.file_path === "string" ? input.file_path : typeof input?.path === "string" ? input.path : "";
 		const routed = readUrlCard(rawPath);
 		if (routed) return { label: routed.card.label, detail: routed.target || routed.card.rootDetail };
-		return { label: "Read", detail: shortenPath(rawPath) };
+		return { label: "Read", detail: sanitizeText(shortenPath(rawPath)) };
 	},
 	renderCall(args: ReadRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const rawPath =
@@ -462,10 +506,11 @@ export const readToolRenderer = {
 
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: ReadToolDetails; isError?: boolean },
-		options: RenderResultOptions,
+		options: RenderResultContextOptions,
 		uiTheme: Theme,
 		args?: ReadRenderArgs,
 	): Component {
+		const linkPath = readLinkTarget(options.renderContext?.rawDetails);
 		const urlDetails = result.details as ReadUrlToolDetails | undefined;
 		const baseRawPathForKind =
 			typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
@@ -492,8 +537,8 @@ export const readToolRenderer = {
 			const filePath =
 				formatReadPathLink(rawPath, {
 					offset: args?.offset,
-					sourcePath: result.details?.displayTarget ?? readSourceFsPath(result.details),
-				}) || shortenPath(rawPath);
+					sourcePath: linkPath ?? result.details?.displayTarget ?? readSourceFsPath(result.details),
+				}) || sanitizeText(shortenPath(rawPath));
 			let title = filePath ? `Read ${filePath}` : "Read";
 			if (args?.offset !== undefined || args?.limit !== undefined) {
 				const startLine = args.offset ?? 1;
@@ -525,7 +570,9 @@ export const readToolRenderer = {
 		const truncation = details?.meta?.truncation;
 		const fallback = details?.truncation;
 		if (details?.resolvedPath) {
-			warningLines.push(uiTheme.fg("dim", wrapBrackets(`Resolved path: ${details.resolvedPath}`, uiTheme)));
+			warningLines.push(
+				uiTheme.fg("dim", wrapBrackets(`Resolved path: ${shortenPath(details.resolvedPath)}`, uiTheme)),
+			);
 		}
 		if (truncation) {
 			if (fallback?.firstLineExceedsLimit) {
@@ -543,7 +590,7 @@ export const readToolRenderer = {
 		if (imageContent) {
 			const suffix = details?.suffixResolution;
 			const displayPath = formatReadPathLink(rawPath, {
-				resolvedPath: details?.resolvedPath,
+				resolvedPath: linkPath ?? details?.resolvedPath,
 				sourcePath: details?.displayTarget ?? readSourceFsPath(details),
 				suffixResolution: suffix,
 				fallbackLabel: "image",
@@ -575,7 +622,7 @@ export const readToolRenderer = {
 		// reads only record the absolute path in meta.source, so fall back to that
 		// to keep the title clickable.
 		const displayPath = formatReadPathLink(rawPath, {
-			resolvedPath: details?.resolvedPath,
+			resolvedPath: linkPath ?? details?.resolvedPath,
 			sourcePath: details?.displayTarget ?? readSourceFsPath(details),
 			suffixResolution: suffix,
 			offset: args?.offset,
@@ -594,9 +641,7 @@ export const readToolRenderer = {
 			const n = details.conflictCount;
 			title += ` ${uiTheme.fg("warning", `(⚠ ${n} conflict${n === 1 ? "" : "s"})`)}`;
 		}
-		const rawRequested =
-			args?.raw === true || renderPath.sel?.split(":").some(chunk => chunk.toLowerCase() === "raw") === true;
-		const isMarkdown = details?.contentType === "text/markdown" && !rawRequested;
+		const isMarkdown = readResultIsMarkdown(details, args);
 		let cachedWidth: number | undefined;
 		let cachedExpanded: boolean | undefined;
 		let cachedLines: string[] | undefined;
@@ -659,9 +704,10 @@ export const readToolRenderer = {
 	 */
 	describeResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: ReadToolDetails; isError?: boolean },
-		_options: RenderResultOptions,
+		options: RenderResultContextOptions,
 		args?: ReadRenderArgs,
 	): NativeToolView {
+		const linkPath = readLinkTarget(options.renderContext?.rawDetails);
 		const details = result.details;
 		const rawPath = readRawPath(args);
 		const routed = readUrlCard(rawPath, details);
@@ -677,11 +723,11 @@ export const readToolRenderer = {
 
 		if (result.isError) {
 			const message = (resultText(result) || "Unknown error").replace(/^Error:\s*/, "");
-			return inlineErrorView(readNativeHead(rawPath, args, details), message);
+			return inlineErrorView(readNativeHead(rawPath, args, details, linkPath), message);
 		}
 
 		const suffix = details?.suffixResolution;
-		const head = readNativeHead(rawPath, args, details);
+		const head = readNativeHead(rawPath, args, details, linkPath);
 		const truncation = details?.meta?.truncation;
 		const fallback = details?.truncation;
 		const firstLineTooLong = truncation !== undefined && fallback?.firstLineExceedsLimit === true;
@@ -695,6 +741,9 @@ export const readToolRenderer = {
 		);
 
 		const contentText = details?.displayContent?.text ?? stripOutputNotice(resultText(result), details?.meta);
+		// A file Tern's media viewer shows (image, model, PDF, video, audio): the host loads it by path.
+		const mediaPath = readMediaPath(options.renderContext?.rawDetails) ?? details?.mediaPath;
+		const media = options.media && mediaPath ? nativeMediaNode(mediaPath, "media") : undefined;
 		const imageBlock = result.content?.find(isImageBlock);
 		if (imageBlock) {
 			const detailText = contentText.trim();
@@ -703,7 +752,7 @@ export const readToolRenderer = {
 				tone: suffix ? "warning" : undefined,
 				inline: true,
 				body: compact<NativeChild>([
-					describeReadImage(imageBlock, shortenPath(suffix?.to ?? splitReadRenderPath(rawPath).path)),
+					media ?? describeReadImage(imageBlock, shortenPath(suffix?.to ?? splitReadRenderPath(rawPath).path)),
 					detailText.length > 0 && ansi(detailText),
 					foot,
 				]),
@@ -711,18 +760,15 @@ export const readToolRenderer = {
 		}
 
 		const renderPath = splitReadRenderPath(rawPath);
-		const rawRequested =
-			args?.raw === true || renderPath.sel?.split(":").some(chunk => chunk.toLowerCase() === "raw") === true;
-		const content: NativeChild[] =
-			details?.contentType === "text/markdown" && !rawRequested
-				? [md(contentText)]
-				: readContentCode(
-						contentText,
-						details?.displayContent?.startLine ?? readRangeStart(rawPath, args),
-						details?.displayContent?.lineNumbers,
-						getLanguageFromPath(renderPath.path),
-					);
-		return { tool: head, inline: true, body: compact<NativeChild>([...content, foot]) };
+		const content: NativeChild[] = readResultIsMarkdown(details, args)
+			? [md(contentText)]
+			: readContentCode(
+					contentText,
+					details?.displayContent?.startLine ?? readRangeStart(rawPath, args),
+					details?.displayContent?.lineNumbers,
+					renderPath.path,
+				);
+		return { tool: head, inline: true, body: compact<NativeChild>([media, ...content, foot]) };
 	},
 	mergeCallAndResult: true,
 } satisfies ToolRenderer<ReadRenderArgs, ReadToolDetails>;

package/src/tools/renderer.d.ts

@@ -33,6 +33,8 @@ export interface RenderResultOptions {
     elapsedMs?: number;
     /** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
     cancelled?: boolean;
+    /** The native host shows files by path (`cx.supports("media")`). Native describe hooks only. */
+    media?: boolean;
 }
 /** Render options for a result, plus the tool-specific context the transcript threads through. */
 export type RenderResultContextOptions = RenderResultOptions & {

package/src/tools/renderer.ts

@@ -34,6 +34,8 @@ export interface RenderResultOptions {
 	elapsedMs?: number;
 	/** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
 	cancelled?: boolean;
+	/** The native host shows files by path (`cx.supports("media")`). Native describe hooks only. */
+	media?: boolean;
 }
 
 /** Render options for a result, plus the tool-specific context the transcript threads through. */

package/src/tools/task.d.ts

@@ -101,6 +101,10 @@ export interface TaskItem {
     name?: string;
     /** Agent type to run this item (e.g. "scout"). Defaults to the spawn policy's default agent. */
     agent?: string;
+    /** Historical source session selected by the bundled consult agent. */
+    sourceSession?: string;
+    /** Optional model selector override for the historical source session. */
+    model?: string | string[];
     /** The work; required by the schema. */
     task?: string;
     /** How open-ended the work is; required by the schema and the child's sole `auto` thinking classification input. */
@@ -127,6 +131,10 @@ export interface TaskParams {
     name?: string;
     /** Agent type to spawn (flat form); omitted values resolve from the session spawn policy. */
     agent?: string;
+    /** Historical source session selected by the bundled consult agent. */
+    sourceSession?: string;
+    /** Optional model selector override for the historical source session. */
+    model?: string | string[];
     /** The work (flat form). */
     task?: string;
     /** How open-ended the work is (flat form); see {@link TaskItem.solutionSpace}. */
@@ -383,6 +391,29 @@ export interface SingleResult {
         attempt: number;
         errorMessage: string;
     };
+    /**
+     * Coarse category of a non-zero exit — `usage-limit`, `auth`,
+     * `account-policy`, `context-overflow`, `transient`, `aborted`, or
+     * `unknown`. A parent agent reads this to tell "swap the model" (the first
+     * three) from "fix the request" instead of parsing provider prose.
+     */
+    failureClass?: "usage-limit" | "auth" | "account-policy" | "context-overflow" | "transient" | "aborted" | "unknown";
+    /**
+     * Other models this session could run instead (selectors accepted by the
+     * task `model` parameter, including `@role` aliases). Empty when nothing
+     * else is configured or every alternative is already in cooldown.
+     */
+    fallbackCandidates?: string[];
+    /**
+     * Set when a caller-supplied `model` replaced the model this run would
+     * otherwise have used — the audit trail of an agent-driven switch.
+     */
+    modelChange?: {
+        source: "spawn-param" | "wake-param";
+        /** The model the run would have used without the override, when resolvable. */
+        from?: string;
+        to: string;
+    };
     /** Output metadata for agent:// URL integration */
     outputMeta?: {
         lineCount: number;