@oh-my-pi/pi-coding-agent 15.9.3 → 15.9.67

package/src/modes/components/tool-execution.ts

@@ -33,7 +33,7 @@ import {
 import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } from "../../tools/render-utils";
 import { toolRenderers } from "../../tools/renderers";
 import { TODO_STRIKE_TOTAL_FRAMES } from "../../tools/todo";
-import { renderStatusLine } from "../../tui";
+import { isFramedBlockComponent, renderStatusLine } from "../../tui";
 import { sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
 import { renderDiff } from "./diff";
 
@@ -45,6 +45,12 @@ function ensureInvalidate(component: unknown): Component {
 	return c as Component;
 }
 
+function addBoxChild(box: Box, component: unknown): boolean {
+	const child = ensureInvalidate(component);
+	box.addChild(child);
+	return isFramedBlockComponent(child);
+}
+
 /**
  * Drop trailing removal/hunk-header lines that appear in a streaming diff
  * before the matching `+added` lines have arrived. Without this, a partial
@@ -107,7 +113,7 @@ function rawTextInputFromPartialJson(partialJson: unknown): string | undefined {
 	// Function-tool arguments stream as JSON. Custom/free-form tools stream raw
 	// text in the same transport field; only the raw form is a valid fallback for
 	// the conventional `input` parameter.
-	if (first === "{" || first === "[" || first === '"') return undefined;
+	if (first === "{" || first === '"') return undefined;
 	return partialJson;
 }
 
@@ -197,6 +203,11 @@ export class ToolExecutionComponent extends Container {
 	#todoStrikeInterval?: NodeJS.Timeout;
 	// Track if args are still being streamed (for edit/write spinner)
 	#argsComplete = false;
+	// Sealed once the tool reaches a terminal state (result delivered, or the
+	// turn abandoned it without one). Drives `isTranscriptBlockFinalized`: until
+	// sealed the block stays in the transcript's repaintable live region so a
+	// late result still repaints instead of stranding the streaming preview.
+	#sealed = false;
 	#renderState: {
 		spinnerFrame?: number;
 		expanded: boolean;
@@ -448,6 +459,13 @@ export class ToolExecutionComponent extends Container {
 		} else if (!needsSpinner && this.#spinnerInterval) {
 			clearInterval(this.#spinnerInterval);
 			this.#spinnerInterval = undefined;
+			// Clear the last drawn frame so a non-live renderCall (e.g. a write whose
+			// args just completed) stops showing a frozen spinner glyph. Skip when a
+			// todo strike owns the frame — it sets its own value right after this.
+			if (!this.#todoStrikeInterval) {
+				this.#spinnerFrame = undefined;
+				this.#renderState.spinnerFrame = undefined;
+			}
 		}
 	}
 
@@ -488,6 +506,37 @@ export class ToolExecutionComponent extends Container {
 		}
 	}
 
+	/**
+	 * Whether this block has reached a terminal state for transcript freezing.
+	 * Reports `false` while it can still visually change so the
+	 * {@link TranscriptContainer} keeps it inside the repaintable live region:
+	 * a foreground tool awaiting its result, or one streaming partial output.
+	 * A final (non-partial) result, a background-async tool the agent has moved
+	 * past, or an explicit {@link seal} flips it to `true`.
+	 */
+	isTranscriptBlockFinalized(): boolean {
+		if (this.#sealed) return true;
+		if (this.#result === undefined) return false;
+		if (!this.#isPartial) return true;
+		// Partial result: a background async tool is accepted to freeze (the agent
+		// continues while it runs and would otherwise pin an unbounded live region);
+		// a foreground tool streaming partial output stays live until it finishes.
+		return (this.#result.details as { async?: { state?: string } } | undefined)?.async?.state === "running";
+	}
+
+	/**
+	 * Mark the tool terminal even though no result arrived (the turn aborted or
+	 * abandoned it) and stop animating, so it can freeze and stops pinning the
+	 * transcript live region.
+	 */
+	seal(): void {
+		if (this.#sealed) return;
+		this.#sealed = true;
+		this.stopAnimation();
+		this.#updateDisplay();
+		this.#ui.requestRender();
+	}
+
 	/**
 	 * Stop spinner animation and cleanup resources.
 	 */
@@ -496,6 +545,7 @@ export class ToolExecutionComponent extends Container {
 			clearInterval(this.#spinnerInterval);
 			this.#spinnerInterval = undefined;
 			this.#spinnerFrame = undefined;
+			this.#renderState.spinnerFrame = undefined;
 		}
 		this.#stopTodoStrikeAnimation();
 		this.#editDiffAbort?.abort();
@@ -538,6 +588,7 @@ export class ToolExecutionComponent extends Container {
 			const inline = Boolean((tool as { inline?: boolean }).inline);
 			this.#contentBox.setBgFn(inline ? undefined : bgFn);
 			this.#contentBox.clear();
+			let contentBoxHasFramedBlock = false;
 			// Mirror the built-in renderer branch so custom renderers (notably the
 			// task tool, whose live instance routes through here) receive the same
 			// render context — e.g. the `hasResult` flag that suppresses the task
@@ -550,16 +601,16 @@ export class ToolExecutionComponent extends Container {
 				try {
 					const callComponent = tool.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
 					if (callComponent) {
-						this.#contentBox.addChild(ensureInvalidate(callComponent));
+						contentBoxHasFramedBlock = addBoxChild(this.#contentBox, callComponent) || contentBoxHasFramedBlock;
 					}
 				} catch (err) {
 					logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 					// Fall back to default on error
-					this.#contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
+					addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 				}
 			} else {
 				// No custom renderCall, show tool name
-				this.#contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
+				addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 			}
 
 			// Render result component if we have a result
@@ -582,23 +633,24 @@ export class ToolExecutionComponent extends Container {
 						this.#args,
 					);
 					if (resultComponent) {
-						this.#contentBox.addChild(ensureInvalidate(resultComponent));
+						contentBoxHasFramedBlock = addBoxChild(this.#contentBox, resultComponent) || contentBoxHasFramedBlock;
 					}
 				} catch (err) {
 					logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 					// Fall back to showing raw output on error
 					const output = this.#getTextOutput();
 					if (output) {
-						this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
+						addBoxChild(this.#contentBox, new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 					}
 				}
 			} else if (this.#result) {
 				// Has result but no custom renderResult
 				const output = this.#getTextOutput();
 				if (output) {
-					this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
+					addBoxChild(this.#contentBox, new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 				}
 			}
+			this.#contentBox.setPaddingX(contentBoxHasFramedBlock ? 0 : 1);
 		} else if (this.#toolName in toolRenderers) {
 			// Built-in tools with renderers
 			const renderer = toolRenderers[this.#toolName];
@@ -617,6 +669,7 @@ export class ToolExecutionComponent extends Container {
 				// Multi-file: render each file as its own Box (identical to separate tool calls)
 				this.#contentBox.setBgFn(undefined);
 				this.#contentBox.clear();
+				this.#contentBox.setPaddingX(1);
 
 				const renderContext = this.#buildRenderContext();
 				this.#renderState.renderContext = renderContext;
@@ -639,7 +692,8 @@ export class ToolExecutionComponent extends Container {
 							theme,
 						);
 						if (resultComponent) {
-							fileBox.addChild(ensureInvalidate(resultComponent));
+							const fileBoxHasFramedBlock = addBoxChild(fileBox, resultComponent);
+							fileBox.setPaddingX(fileBoxHasFramedBlock ? 0 : 1);
 						}
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
@@ -675,6 +729,7 @@ export class ToolExecutionComponent extends Container {
 				// Inline renderers skip background styling
 				this.#contentBox.setBgFn(renderer.inline ? undefined : bgFn);
 				this.#contentBox.clear();
+				let contentBoxHasFramedBlock = false;
 
 				const renderContext = this.#buildRenderContext();
 				this.#renderState.renderContext = renderContext;
@@ -685,12 +740,13 @@ export class ToolExecutionComponent extends Container {
 					try {
 						const callComponent = renderer.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
 						if (callComponent) {
-							this.#contentBox.addChild(ensureInvalidate(callComponent));
+							contentBoxHasFramedBlock =
+								addBoxChild(this.#contentBox, callComponent) || contentBoxHasFramedBlock;
 						}
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 						// Fall back to default on error
-						this.#contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
+						addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 					}
 				}
 
@@ -708,17 +764,19 @@ export class ToolExecutionComponent extends Container {
 							this.#getCallArgsForRender(),
 						);
 						if (resultComponent) {
-							this.#contentBox.addChild(ensureInvalidate(resultComponent));
+							contentBoxHasFramedBlock =
+								addBoxChild(this.#contentBox, resultComponent) || contentBoxHasFramedBlock;
 						}
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 						// Fall back to showing raw output on error
 						const output = this.#getTextOutput();
 						if (output) {
-							this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
+							addBoxChild(this.#contentBox, new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 						}
 					}
 				}
+				this.#contentBox.setPaddingX(contentBoxHasFramedBlock ? 0 : 1);
 			}
 		} else {
 			// Other built-in tools: use Text directly with caching

package/src/modes/components/transcript-container.ts

@@ -12,6 +12,33 @@ interface SnapshotCarrier {
 	[kSnapshot]?: FrozenRender;
 }
 
+/**
+ * A transcript block that is still mutating (a foreground tool awaiting its
+ * result, an assistant message mid-stream) reports `false` so the container
+ * keeps it inside the live (repaintable) region instead of freezing it. Blocks
+ * without the method are treated as finalized — the default, stable behavior.
+ *
+ * `isTranscriptBlockAppendOnly` marks a still-live block whose rendered rows
+ * only grow at the bottom and never re-layout (a streaming assistant reply).
+ * Such a block's scrolled-off head is safe to commit to native scrollback even
+ * while live; blocks that omit it (tool previews that collapse to a compact
+ * result) keep their mutable rows deferred. Default is `false`.
+ */
+interface FinalizableBlock {
+	isTranscriptBlockFinalized?(): boolean;
+	isTranscriptBlockAppendOnly?(): boolean;
+}
+
+function isBlockFinalized(child: Component): boolean {
+	const fn = (child as Component & FinalizableBlock).isTranscriptBlockFinalized;
+	return fn ? fn.call(child) : true;
+}
+
+function isBlockAppendOnly(child: Component): boolean {
+	const fn = (child as Component & FinalizableBlock).isTranscriptBlockAppendOnly;
+	return fn ? fn.call(child) : false;
+}
+
 /**
  * Transcript container that freezes the rendered output of every block except
  * the bottom-most (live) one on terminals where committed native scrollback is
@@ -38,15 +65,24 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 	// Bumped to invalidate every block's snapshot at once; a snapshot is only
 	// honored when its stored generation still matches.
 	#generation = 0;
-	// The block that was bottom-most (live) on the previous render. When the live
-	// position moves past it, its snapshot was last refreshed mid-stream and may
-	// predate content that finalized in the same coalesced frame that appended the
-	// block now below it — so it must recompute once on the live→frozen transition.
-	#prevLiveChild: Component | undefined;
-	// Local line index where the current bottom-most block begins in the most
-	// recent render. TUI extends the native-scrollback pinned region from this
-	// point through the live block and the root chrome rendered below it.
+	// Line index where the live (repaintable) region began on the previous
+	// render — the start of the earliest still-mutating block, or the bottom
+	// block when everything is finalized. A block leaves the live region only
+	// once it has finalized AND a finalized block sits below it; the frame it
+	// crosses out is recomputed so it freezes at its true final content, not the
+	// mid-stream snapshot it last rendered while live (TUI render coalescing can
+	// advance a block's content in the very frame it stops being live).
+	#prevLiveStartIndex = 0;
+	// Local line index where the current live region begins in the most recent
+	// render. TUI extends the native-scrollback pinned region from this point
+	// through the live blocks and the root chrome rendered below them.
 	#nativeScrollbackLiveRegionStart: number | undefined;
+	// Local line index up to which the leading run of live blocks is append-only
+	// (a streaming assistant reply): everything in [liveRegionStart,
+	// commitSafeEnd) only grows at the bottom and never re-layouts, so its
+	// scrolled-off head is safe to commit to native scrollback. `undefined` when
+	// the first live block is volatile (a tool preview).
+	#nativeScrollbackCommitSafeEnd: number | undefined;
 
 	override invalidate(): void {
 		// A theme/global invalidation forces a full recompute on the rebuild that
@@ -64,6 +100,10 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 		return this.#nativeScrollbackLiveRegionStart;
 	}
 
+	getNativeScrollbackCommitSafeEnd(): number | undefined {
+		return this.#nativeScrollbackCommitSafeEnd;
+	}
+
 	/**
 	 * Retire all frozen snapshots so the next render reflects each block's current
 	 * state. Call at reconciliation checkpoints (prompt submit) where the whole
@@ -77,41 +117,62 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 	override render(width: number): string[] {
 		width = Math.max(1, width);
 		this.#nativeScrollbackLiveRegionStart = undefined;
+		this.#nativeScrollbackCommitSafeEnd = undefined;
 		if (!TERMINAL.eagerEraseScrollbackRisk) return super.render(width);
 
+		const count = this.children.length;
+		// The live region spans from the earliest still-mutating block through the
+		// bottom. A block that has not finalized must stay repaintable: out-of-band
+		// inserts (TTSR/todo cards) can append a finalized block *below* a tool that
+		// is still awaiting its result, and freezing the tool there would strand its
+		// committed rows on the mid-stream preview the late result never reaches.
+		let liveStartIndex = count - 1;
+		for (let i = 0; i < count; i++) {
+			if (!isBlockFinalized(this.children[i]!)) {
+				liveStartIndex = i;
+				break;
+			}
+		}
+		// Blocks at [prevLiveStart, liveStart) just crossed out of the live region;
+		// recompute them so they freeze at their final content. Everything below
+		// the lower of the two cutoffs was already frozen last frame and replays.
+		const replayCutoff = Math.min(liveStartIndex, this.#prevLiveStartIndex);
+		this.#prevLiveStartIndex = liveStartIndex;
+
 		const lines: string[] = [];
-		const liveIndex = this.children.length - 1;
-		const liveChild = this.children[liveIndex];
-		const prevLiveChild = this.#prevLiveChild;
-		this.#prevLiveChild = liveChild;
-		for (let i = 0; i < this.children.length; i++) {
+		// Tracks whether we are still inside the leading run of append-only live
+		// blocks. The first non-append-only live block (or a finalized block below
+		// the live region's start, which cannot happen for a leading run) closes it.
+		let commitSafeOpen = true;
+		for (let i = 0; i < count; i++) {
 			const child = this.children[i]! as Component & SnapshotCarrier;
-			if (child === liveChild) {
-				this.#nativeScrollbackLiveRegionStart = lines.length;
+			if (i >= liveStartIndex) {
+				if (i === liveStartIndex) this.#nativeScrollbackLiveRegionStart = lines.length;
 			} else {
 				const snapshot = child[kSnapshot];
-				// Replay the block's last render from while it was live. A stale
-				// generation (post-thaw) or width mismatch (resize in flight, an
-				// explicit rebuild that reconciles history anyway) recomputes instead.
-				// The block that was live on the previous render is also recomputed
-				// here: TUI render coalescing can advance its content (final streamed
-				// tokens) in the very frame that appends the block now below it, so its
-				// cached snapshot predates that final content. Recomputing on the
-				// transition seals the block at its true final state, not a mid-stream one.
-				if (
-					child !== prevLiveChild &&
-					snapshot &&
-					snapshot.generation === this.#generation &&
-					snapshot.width === width
-				) {
+				// Replay a frozen block's last live render. A stale generation
+				// (post-thaw) or width mismatch (resize, explicit rebuild) recomputes
+				// instead, as does a block that was still live last frame (i >= cutoff).
+				if (i < replayCutoff && snapshot && snapshot.generation === this.#generation && snapshot.width === width) {
 					lines.push(...snapshot.lines);
 					continue;
 				}
 			}
 			const rendered = child.render(width);
-			// Cache every block's latest render. While a block is live this keeps its
-			// snapshot current; on the frame it stops being live the recompute above
-			// refreshes it to the final state before it freezes.
+			// Extend the commit-safe boundary through each leading append-only live
+			// block. `lines.length` here is this block's start offset; the boundary
+			// runs to the end of its rendered rows. The first volatile live block
+			// closes the run so its mutable rows stay deferred.
+			if (i >= liveStartIndex && commitSafeOpen) {
+				if (isBlockAppendOnly(child)) {
+					this.#nativeScrollbackCommitSafeEnd = lines.length + rendered.length;
+				} else {
+					commitSafeOpen = false;
+				}
+			}
+			// Cache every block's latest render. While a block is in the live region
+			// this keeps its snapshot current; on the frame it crosses out, the
+			// recompute above refreshes it to the final state before it freezes.
 			child[kSnapshot] = { width, lines: rendered, generation: this.#generation };
 			lines.push(...rendered);
 		}

package/src/modes/components/tree-selector.ts

@@ -6,6 +6,7 @@ import {
 	fuzzyMatch,
 	Input,
 	matchesKey,
+	ScrollView,
 	Spacer,
 	Text,
 	TruncatedText,
@@ -492,6 +493,10 @@ class TreeList implements Component {
 		const contentReserve = Math.max(MIN_CONTENT_COLS, Math.floor(width / 2));
 		const maxIndentLevels = Math.max(1, Math.floor((width - contentReserve - OVERHEAD_COLS) / 3));
 
+		const overflow = this.#filteredNodes.length > this.maxVisibleLines;
+		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+		const rows: string[] = [];
+
 		for (let i = startIndex; i < endIndex; i++) {
 			const flatNode = this.#filteredNodes[i];
 			const entry = flatNode.node.entry;
@@ -560,15 +565,22 @@ class TreeList implements Component {
 			if (isSelected) {
 				line = theme.bg("selectedBg", line);
 			}
-			lines.push(truncateToWidth(line, width));
+			rows.push(truncateToWidth(line, rowWidth));
 		}
 
-		lines.push(
-			truncateToWidth(
-				theme.fg("muted", `  (${this.#selectedIndex + 1}/${this.#filteredNodes.length})${this.#getFilterLabel()}`),
-				width,
-			),
-		);
+		const sv = new ScrollView(rows, {
+			height: rows.length,
+			scrollbar: "auto",
+			totalRows: this.#filteredNodes.length,
+			theme: { track: t => theme.fg("muted", t), thumb: t => theme.fg("accent", t) },
+		});
+		sv.setScrollOffset(startIndex);
+		lines.push(...sv.render(width));
+
+		const filterLabel = this.#getFilterLabel();
+		if (filterLabel) {
+			lines.push(truncateToWidth(theme.fg("muted", `  ${filterLabel.trim()}`), width));
+		}
 
 		return lines;
 	}

package/src/modes/components/user-message-selector.ts

@@ -4,6 +4,7 @@ import {
 	extractPrintableText,
 	fuzzyFilter,
 	matchesKey,
+	ScrollView,
 	Spacer,
 	Text,
 	truncateToWidth,
@@ -48,14 +49,10 @@ class UserMessageList implements Component {
 		return this.#isSearchEnabled() || this.#searchQuery.length > 0;
 	}
 
-	#renderStatusLine(total: number): string {
-		const selectedCount = total === 0 ? 0 : this.#selectedIndex + 1;
-		const count =
-			this.#searchQuery.trim() && total !== this.messages.length
-				? `${selectedCount}/${total} of ${this.messages.length}`
-				: `${selectedCount}/${total}`;
-		const suffix = this.#searchQuery.trim() ? `  Search: ${this.#searchQuery}` : "  Type to search";
-		return theme.fg("muted", `  (${count})${suffix}`);
+	#renderStatusLine(_total: number): string {
+		const query = this.#searchQuery.trim();
+		const suffix = query ? `Search: ${this.#searchQuery}` : "Type to search";
+		return theme.fg("muted", `  ${suffix}`);
 	}
 
 	#setSearchQuery(query: string): void {
@@ -103,6 +100,9 @@ class UserMessageList implements Component {
 		const endIndex = Math.min(startIndex + this.#maxVisible, total);
 
 		// Render visible messages (2 lines per message + blank line)
+		const overflow = total > this.#maxVisible;
+		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+		const messageLines: string[] = [];
 		for (let i = startIndex; i < endIndex; i++) {
 			const message = this.#filteredMessages[i];
 			if (!message) continue;
@@ -113,26 +113,37 @@ class UserMessageList implements Component {
 
 			// First line: cursor + message
 			const cursor = isSelected ? theme.fg("accent", "› ") : "  ";
-			const maxMsgWidth = width - 2; // Account for cursor (2 chars)
+			const maxMsgWidth = rowWidth - 2; // Account for cursor (2 chars)
 			const truncatedMsg = truncateToWidth(normalizedMessage, maxMsgWidth);
 			const messageLine = cursor + (isSelected ? theme.bold(truncatedMsg) : truncatedMsg);
 
-			lines.push(messageLine);
+			messageLines.push(messageLine);
 
 			// Second line: metadata (position in history)
 			const position = this.messages.indexOf(message) + 1;
 			const metadata = `  Message ${position} of ${this.messages.length}`;
 			const metadataLine = theme.fg("muted", metadata);
-			lines.push(metadataLine);
-			lines.push(""); // Blank line between messages
+			messageLines.push(metadataLine);
+			messageLines.push(""); // Blank line between messages
 		}
 
 		if (total === 0) {
 			lines.push(theme.fg("muted", "  No matching messages"));
+		} else {
+			const visibleCount = endIndex - startIndex;
+			const linesPerItem = visibleCount > 0 ? messageLines.length / visibleCount : 1;
+			const sv = new ScrollView(messageLines, {
+				height: messageLines.length,
+				scrollbar: "auto",
+				totalRows: Math.round(total * linesPerItem),
+				theme: { track: t => theme.fg("muted", t), thumb: t => theme.fg("accent", t) },
+			});
+			sv.setScrollOffset(Math.round(startIndex * linesPerItem));
+			lines.push(...sv.render(width));
 		}
 
-		// Add scroll/search indicator if needed
-		if (startIndex > 0 || endIndex < total || this.#shouldRenderSearchStatus()) {
+		// Add search indicator if needed
+		if (this.#shouldRenderSearchStatus()) {
 			lines.push(this.#renderStatusLine(total));
 		}
 

package/src/modes/components/user-message.ts

@@ -1,5 +1,6 @@
 import { Container, Markdown, Spacer } from "@oh-my-pi/pi-tui";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
+import { imageReferenceHyperlink, renderImageReferences } from "../image-references";
 import { highlightMagicKeywords } from "../magic-keywords";
 
 // OSC 133 shell integration: marks prompt zones for terminal multiplexers
@@ -11,7 +12,7 @@ const OSC133_ZONE_FINAL = "\x1b]133;C\x07";
  * Component that renders a user message
  */
 export class UserMessageComponent extends Container {
-	constructor(text: string, synthetic = false) {
+	constructor(text: string, synthetic = false, imageLinks?: readonly (string | undefined)[]) {
 		super();
 		const bgColor = (value: string) => theme.bg("userMessageBg", value);
 		// Paint the magic keywords ("ultrathink"/"orchestrate"/"workflow") inside the rendered
@@ -20,9 +21,15 @@ export class UserMessageComponent extends Container {
 		// `highlightMagicKeywords` additionally restores the bubble's own foreground after each
 		// painted keyword so the gradient never bleeds into the rest of the line.
 		const keywordReset = theme.getFgAnsi("userMessageText") || "\x1b[39m";
-		const color = synthetic
+		const baseText = synthetic
 			? (value: string) => theme.fg("dim", value)
 			: (value: string) => theme.fg("userMessageText", highlightMagicKeywords(value, keywordReset));
+		const imageLabel = (value: string) => theme.fg("accent", `\x1b[1m\x1b[4m${value}\x1b[24m\x1b[22m`);
+		const color = (value: string) =>
+			renderImageReferences(value, {
+				renderText: baseText,
+				renderReference: (label, index) => imageReferenceHyperlink(label, index, imageLinks, imageLabel),
+			});
 		this.addChild(new Spacer(1));
 		this.addChild(
 			new Markdown(text, 1, 1, getMarkdownTheme(), {