@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

package/src/modes/components/settings-defs.ts

@@ -90,6 +90,13 @@ const CONDITIONS: Record<string, () => boolean> = {
 			return false;
 		}
 	},
+	autolearnActive: () => {
+		try {
+			return Settings.instance.get("autolearn.enabled") === true;
+		} catch {
+			return false;
+		}
+	},
 	autoThinkingActive: () => {
 		try {
 			return Settings.instance.get("defaultThinkingLevel") === "auto";

package/src/modes/components/status-line/component.ts

@@ -1,7 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import { estimateTokens } from "@oh-my-pi/pi-agent-core/compaction";
 import { type Component, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
 import { getProjectDir } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
@@ -11,7 +10,6 @@ import * as git from "../../../utils/git";
 import { getSessionAccentAnsi, getSessionAccentHex } from "../../../utils/session-color";
 import { sanitizeStatusText } from "../../shared";
 import { theme } from "../../theme/theme";
-import { computeNonMessageTokens } from "../../utils/context-usage";
 import { canReuseCachedPr, createPrCacheContext, isSamePrCacheContext, type PrCacheContext } from "./git-utils";
 import { getPreset } from "./presets";
 import { renderSegment, type SegmentContext } from "./segments";
@@ -26,30 +24,15 @@ import type {
 } from "./types";
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Per-message token cache
+// Context-usage memo
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Symbol-keyed sidecar tagged onto each `AgentMessage` to memoize its
- * `estimateTokens` result. Keyed by message identity (the object itself);
- * a cheap content fingerprint detects in-place mutations (post-hoc error
- * attachment, retry-truncated branch rebuild, etc.) and forces recompute.
- *
- * Cache lives on the message — multiple `StatusLineComponent` instances
- * share it for free, and entries collect with the message itself when the
- * conversation is replaced or compacted.
- */
-const kTokenCache = Symbol("statusLine.tokenCache");
-interface TaggedMessage {
-	[kTokenCache]?: { fingerprint: string; tokens: number };
-}
-
-/**
- * Cheap structural fingerprint mirroring `estimateTokens`'s content walk.
- * O(blocks) — only reads string `.length` and primitives, never copies or
- * serializes content. Any in-place mutation that alters total tokenized
- * content also alters one of the byte-length sums or block counts captured
- * here, forcing the cached `estimateTokens` value to be recomputed.
+ * Cheap structural fingerprint of a message's tokenizable content. O(blocks) —
+ * only reads string `.length` and primitives, never copies or serializes.
+ * Detects in-place growth of the streaming tail (and other in-place mutations)
+ * so the cached `getContextUsage()` result is recomputed when — and only when —
+ * the numbers it depends on change.
  */
 function messageFingerprint(msg: AgentMessage): string {
 	const role = (msg as { role?: string }).role ?? "";
@@ -107,29 +90,17 @@ function messageFingerprint(msg: AgentMessage): string {
 	return `${role}:${ts}:${textLen}:${blocks}:${images}`;
 }
 
-/**
- * Token count for a single message, using the per-message sidecar cache.
- * The caller MUST skip caching for the last message during streaming —
- * it may still be growing and its tokens belong recomputed each refresh.
- */
-function tokensForMessage(msg: AgentMessage): number {
-	const fp = messageFingerprint(msg);
-	const tagged = msg as TaggedMessage;
-	const cached = tagged[kTokenCache];
-	if (cached && cached.fingerprint === fp) return cached.tokens;
-	const tokens = estimateTokens(msg);
-	tagged[kTokenCache] = { fingerprint: fp, tokens };
-	return tokens;
-}
-
-interface MessageTokenTotalsCache {
+interface ContextUsageMemo {
 	messagesRef: readonly AgentMessage[];
-	stableCount: number;
-	stableTokens: number;
-	lastStableMessage: AgentMessage | undefined;
-	lastStableFingerprint: string | undefined;
+	length: number;
+	lastFingerprint: string | undefined;
+	modelContextWindow: number;
+	usedTokens: number | null;
+	contextWindow: number;
 }
 
+const EMPTY_MESSAGES: readonly AgentMessage[] = [];
+
 function hasContextSegment(segments: readonly StatusLineSegmentId[]): boolean {
 	return segments.includes("context_pct") || segments.includes("context_total");
 }
@@ -176,19 +147,12 @@ export class StatusLineComponent implements Component {
 	} | null = null;
 	#usageFetchedAt = 0;
 	#usageInFlight = false;
-	// Context breakdown — incremental rolling cache. The status line refreshes
-	// on every agent event, so the hot path must not re-tokenize the full
-	// message list. Stable messages are accumulated once; normal streaming
-	// refreshes only recompute the current tail message and newly appended
-	// entries. History rewrites/compaction replace or shrink the message array
-	// and rebuild this cache. Stable messages are treated as immutable after
-	// promotion, matching the normal append-only session flow.
-	// Cached non-message total (system prompt + tools + skills). Invalidated
-	// when the inputs-identity fingerprint changes (model swap, skill toggle,
-	// tool registration).
-	#nonMessageTokensCache: number | undefined;
-	#nonMessageInputsKey: string | undefined;
-	#messageTokenTotalsCache: MessageTokenTotalsCache | undefined;
+	// Context-usage memo. The status line redraws on every agent event, so the
+	// hot path must not recompute context tokens unless an input changed.
+	// `getContextUsage()` anchors on the last assistant's real prompt-token
+	// count (matching the provider and the `/context` panel), so a stable
+	// message list + model window yields a stable result we can return verbatim.
+	#contextUsageCache: ContextUsageMemo | undefined;
 
 	constructor(private session: AgentSession) {
 		this.#settings = {
@@ -310,9 +274,7 @@ export class StatusLineComponent implements Component {
 		this.#cachedUsage = null;
 		this.#usageFetchedAt = 0;
 		this.#usageInFlight = false;
-		this.#nonMessageTokensCache = undefined;
-		this.#nonMessageInputsKey = undefined;
-		this.#messageTokenTotalsCache = undefined;
+		this.#contextUsageCache = undefined;
 		this.#lastTokensPerSecond = null;
 		this.#lastTokensPerSecondTimestamp = null;
 	}
@@ -544,109 +506,44 @@ export class StatusLineComponent implements Component {
 	}
 
 	/**
-	 * Compute the (cached) used-tokens / context-window totals for the
-	 * status-line context% segment. Exposed (non-private) so unit tests can
-	 * verify the incremental-cache invariants; not part of any external
-	 * API.
+	 * Used-tokens / context-window totals for the status-line context% segment,
+	 * memoized so the per-event redraw stays O(1) when nothing changed.
+	 *
+	 * The numerator comes from `session.getContextUsage()`, which anchors on the
+	 * last assistant's real prompt-token count — so the bar matches the provider
+	 * and the `/context` panel — and reports `null` while that count is unknown
+	 * (right after compaction, before the next response). Exposed (non-private)
+	 * for unit tests and the collab host's state broadcast.
 	 */
-	getCachedContextBreakdown(): { usedTokens: number; contextWindow: number } {
-		const messages = this.session.messages ?? [];
-		const contextWindow = this.session.model?.contextWindow ?? 0;
-
-		// 1) Non-message tokens (system prompt + tools + skills). Refresh only
-		//    when the inputs identity fingerprint changes — usually never
-		//    during a streaming turn. ~10-30 ms when it does refresh.
-		const inputsKey = this.#computeNonMessageInputsKey();
-		if (this.#nonMessageTokensCache === undefined || this.#nonMessageInputsKey !== inputsKey) {
-			this.#nonMessageTokensCache = computeNonMessageTokens(this.session);
-			this.#nonMessageInputsKey = inputsKey;
-		}
-
-		// 2) Message tokens — incremental rolling total. The sidecar cache lives
-		//    on each stable message object (all but the current tail). Normal
-		//    streaming turns only recompute the last message and newly appended
-		//    entries. Full rebuild only when the message array is replaced,
-		//    shrinks, or the recently-promoted stable tail mutates in place.
-		const messagesTokens = this.#getCachedMessageTokens(messages);
-
-		const usedTokens = this.#nonMessageTokensCache + messagesTokens;
-		return { usedTokens, contextWindow };
-	}
-
-	#getCachedMessageTokens(messages: readonly AgentMessage[]): number {
-		const cache = this.#messageTokenTotalsCache;
-		if (!cache || cache.messagesRef !== messages || messages.length <= cache.stableCount) {
-			return this.#rebuildMessageTokenTotals(messages);
-		}
-
-		let stableTokens = cache.stableTokens;
-		let stableCount = cache.stableCount;
-		const stableLimit = Math.max(0, messages.length - 1);
+	getCachedContextBreakdown(): { usedTokens: number | null; contextWindow: number } {
+		const messages = this.session.messages ?? EMPTY_MESSAGES;
+		const modelContextWindow = this.session.model?.contextWindow ?? 0;
+		const length = messages.length;
+		const lastFingerprint = length > 0 ? messageFingerprint(messages[length - 1]!) : undefined;
 
+		const cache = this.#contextUsageCache;
 		if (
-			cache.lastStableMessage &&
-			stableCount > 0 &&
-			messages[stableCount - 1] === cache.lastStableMessage &&
-			cache.lastStableFingerprint !== undefined &&
-			cache.lastStableFingerprint !== messageFingerprint(cache.lastStableMessage)
+			cache &&
+			cache.messagesRef === messages &&
+			cache.length === length &&
+			cache.lastFingerprint === lastFingerprint &&
+			cache.modelContextWindow === modelContextWindow
 		) {
-			return this.#rebuildMessageTokenTotals(messages);
-		}
-
-		while (stableCount < stableLimit) {
-			const promoted = messages[stableCount]!;
-			stableTokens += tokensForMessage(promoted);
-			stableCount++;
-		}
-
-		const lastStableMessage = stableCount > 0 ? messages[stableCount - 1] : undefined;
-		const lastStableFingerprint = lastStableMessage ? messageFingerprint(lastStableMessage) : undefined;
-		const lastMessage = messages.at(-1);
-		const lastTokens = lastMessage ? estimateTokens(lastMessage) : 0;
-		this.#messageTokenTotalsCache = {
-			messagesRef: messages,
-			stableCount,
-			stableTokens,
-			lastStableMessage,
-			lastStableFingerprint,
-		};
-		return stableTokens + lastTokens;
-	}
-
-	#rebuildMessageTokenTotals(messages: readonly AgentMessage[]): number {
-		let stableTokens = 0;
-		const stableLimit = Math.max(0, messages.length - 1);
-		for (let i = 0; i < stableLimit; i++) {
-			stableTokens += tokensForMessage(messages[i]!);
+			return { usedTokens: cache.usedTokens, contextWindow: cache.contextWindow };
 		}
 
-		const lastStableMessage = stableLimit > 0 ? messages[stableLimit - 1] : undefined;
-		const lastStableFingerprint = lastStableMessage ? messageFingerprint(lastStableMessage) : undefined;
-		const lastMessage = messages.at(-1);
-		const lastTokens = lastMessage ? estimateTokens(lastMessage) : 0;
-
-		this.#messageTokenTotalsCache = {
+		const usage = this.session.getContextUsage();
+		const usedTokens = usage?.tokens ?? null;
+		const contextWindow = usage?.contextWindow ?? modelContextWindow;
+		this.#contextUsageCache = {
 			messagesRef: messages,
-			stableCount: stableLimit,
-			stableTokens,
-			lastStableMessage,
-			lastStableFingerprint,
+			length,
+			lastFingerprint,
+			modelContextWindow,
+			usedTokens,
+			contextWindow,
 		};
-		return stableTokens + lastTokens;
-	}
-
-	/**
-	 * Build an identity fingerprint for the non-message inputs (system prompt,
-	 * tools, skills). When this changes, the non-message token cache must be
-	 * recomputed. Cheap: just lengths + first-string-length. Doesn't need to
-	 * be cryptographically unique — only stable for the same inputs.
-	 */
-	#computeNonMessageInputsKey(): string {
-		const sp = this.session.systemPrompt ?? [];
-		const tools = this.session.agent?.state?.tools ?? [];
-		const skills = this.session.skills ?? [];
-		const modelId = this.session.model?.id ?? "";
-		return `${modelId}|${sp.length}:${sp[0]?.length ?? 0}|${tools.length}|${skills.length}`;
+		return { usedTokens, contextWindow };
 	}
 
 	#buildSegmentContext(
@@ -673,14 +570,14 @@ export class StatusLineComponent implements Component {
 			tokensPerSecond: this.#getTokensPerSecond(),
 		};
 
-		let contextTokens = 0;
 		let contextWindow = state.model?.contextWindow ?? this.session.model?.contextWindow ?? 0;
+		let contextPercent: number | null = 0;
 		if (includeContext) {
 			const breakdown = this.getCachedContextBreakdown();
-			contextTokens = breakdown.usedTokens;
 			contextWindow = breakdown.contextWindow || contextWindow;
+			contextPercent =
+				breakdown.usedTokens === null ? null : contextWindow > 0 ? (breakdown.usedTokens / contextWindow) * 100 : 0;
 		}
-		let contextPercent = contextWindow > 0 ? (contextTokens / contextWindow) * 100 : 0;
 
 		// Collab guest: context comes from the host's state frames — the local
 		// replica does no accounting of its own.

package/src/modes/components/status-line/segments.ts

@@ -364,7 +364,7 @@ const contextPctSegment: StatusLineSegment = {
 		const autoIcon = ctx.autoCompactEnabled && theme.icon.auto ? ` ${theme.icon.auto}` : "";
 		const text = `${formatContextUsage(pct, window)}${autoIcon}`;
 
-		const color = getContextUsageThemeColor(getContextUsageLevel(pct, window));
+		const color = getContextUsageThemeColor(getContextUsageLevel(pct ?? 0, window));
 		const content = withIcon(theme.icon.context, theme.fg(color, text));
 
 		return { content, visible: true };

package/src/modes/components/status-line/types.ts

@@ -71,7 +71,8 @@ export interface SegmentContext {
 		cost: number;
 		tokensPerSecond: number | null;
 	};
-	contextPercent: number;
+	/** Context usage percent, or null when unknown (e.g. right after compaction). */
+	contextPercent: number | null;
 	contextWindow: number;
 	autoCompactEnabled: boolean;
 	subagentCount: number;

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

@@ -8,6 +8,7 @@ import {
 	Image,
 	ImageProtocol,
 	imageFallback,
+	type NativeScrollbackLiveRegion,
 	Spacer,
 	TERMINAL,
 	Text,
@@ -16,7 +17,7 @@ import {
 import { getProjectDir, logger, sanitizeText } from "@oh-my-pi/pi-utils";
 import { EDIT_MODE_STRATEGIES, type EditMode, type PerFileDiffPreview } from "../../edit";
 import type { Theme } from "../../modes/theme/theme";
-import { theme } from "../../modes/theme/theme";
+import { getThemeEpoch, theme } from "../../modes/theme/theme";
 import { BASH_DEFAULT_PREVIEW_LINES } from "../../tools/bash";
 import { EVAL_DEFAULT_PREVIEW_LINES } from "../../tools/eval";
 import { isWaitingPollDetails } from "../../tools/job";
@@ -148,10 +149,16 @@ export interface ToolExecutionHandle {
 /** Drive pending-tool redraws at 30fps for live tool headers and displaceable
  * poll blocks. The TUI throttles at the same cadence, and static frames diff to
  * a no-op redraw at ~zero cost. */
-const SPINNER_RENDER_INTERVAL_MS = 1000 / 30;
+export const SPINNER_RENDER_INTERVAL_MS = 1000 / 30;
 /** Advance the spinner glyph at its classic ~12.5fps step, decoupled from the
  * render cadence (mirrors `Loader`). */
-const SPINNER_GLYPH_ADVANCE_MS = 80;
+export const SPINNER_GLYPH_ADVANCE_MS = 80;
+
+/** Phase-locked spinner glyph index shared by every live tool block so parallel
+ * spinners advance in lockstep instead of each tracking its own start time. */
+export function sharedSpinnerFrame(frameCount: number, now: number = performance.now()): number {
+	return frameCount > 0 ? Math.floor(now / SPINNER_GLYPH_ADVANCE_MS) % frameCount : 0;
+}
 
 // Stable per-instance counter so each tool execution's inline images get a
 // graphics id that survives child re-creation (the image budget keys off it).
@@ -160,7 +167,7 @@ let toolExecutionInstanceSeq = 0;
 /**
  * Component that renders a tool call with its result (updateable)
  */
-export class ToolExecutionComponent extends Container {
+export class ToolExecutionComponent extends Container implements NativeScrollbackLiveRegion {
 	#contentBox: Box; // Used for custom tools and bash visual truncation
 	#contentText: Text; // For built-in tools (with its own padding/bg)
 	#multiFileBoxes: (Box | Spacer)[] = []; // Extra boxes for multi-file edit results
@@ -176,6 +183,22 @@ export class ToolExecutionComponent extends Container {
 	#editAllowFuzzy: boolean | undefined;
 	#snapshots?: SnapshotStore;
 	#isPartial = true;
+	#resultVersion = 0;
+	#lastDisplayKey: string | undefined;
+	// Bumped whenever a render input that #rebuildDisplay consumes but the memo
+	// key cannot cheaply hash changes: streamed call args, the async edit-diff
+	// preview, and Kitty PNG conversions. Folded into the dirty key so those
+	// updates are not swallowed by the memo (see #updateDisplay).
+	#displayInputVersion = 0;
+	// Set once #rebuildDisplay has populated the display. Replaces a
+	// #contentBox.children.length probe so the memo fast-path also covers the
+	// #contentText fallback path (which leaves #contentBox empty).
+	#displayBuilt = false;
+	// Number of Image children the last rebuild emitted. Only when this is > 0 does
+	// the memo key fold in viewport-dependent image sizing (resolveImageOptions),
+	// so a terminal resize re-shapes image-bearing results to rescale them without
+	// forcing the common image-free result to re-shape on every resize tick.
+	#renderedImageCount = 0;
 	#tool?: AgentTool;
 	#ui: TUI;
 	#cwd: string;
@@ -196,7 +219,6 @@ export class ToolExecutionComponent extends Container {
 	// Spinner animation for partial task results
 	#spinnerFrame?: number;
 	#spinnerInterval?: NodeJS.Timeout;
-	#lastSpinnerAdvanceAt = 0;
 	// Todo write completion strikethrough reveal animation
 	#todoStrikeInterval?: NodeJS.Timeout;
 	// Track if args are still being streamed (for edit/write spinner)
@@ -281,6 +303,7 @@ export class ToolExecutionComponent extends Container {
 		// signals "nothing meaningful changed" and the renderer can skip.
 		if (args === this.#args) return;
 		this.#args = args;
+		this.#displayInputVersion++;
 		this.#updateSpinnerAnimation();
 		this.#editDiffInFlight = this.#runPreviewDiff();
 		this.#updateDisplay();
@@ -365,6 +388,7 @@ export class ToolExecutionComponent extends Container {
 			if (controller.signal.aborted) return;
 			if (previews) {
 				this.#editDiffPreview = isStreaming ? stabilizeStreamingPreviews(previews) : previews;
+				this.#displayInputVersion++;
 				this.#updateDisplay();
 				this.#ui.requestRender();
 			}
@@ -393,6 +417,7 @@ export class ToolExecutionComponent extends Container {
 			return;
 		}
 		this.#result = result;
+		this.#resultVersion++;
 		this.#isPartial = isPartial;
 		// A `job` poll that found every watched job still running is transient
 		// "still waiting" chrome; keep the block displaceable so the next `job`
@@ -446,6 +471,7 @@ export class ToolExecutionComponent extends Container {
 				.toBase64()
 				.then(data => {
 					this.#convertedImages.set(index, { data, mimeType: "image/png" });
+					this.#displayInputVersion++;
 					this.#updateDisplay();
 					this.#ui.requestRender();
 				})
@@ -470,32 +496,18 @@ export class ToolExecutionComponent extends Container {
 		// once the block leaves the live region.
 		const needsSpinner = isStreamingArgs || isPartialTask || this.isDisplaceableBlock();
 		if (needsSpinner && !this.#spinnerInterval) {
-			const now = performance.now();
 			const frameCount = theme.spinnerFrames.length;
-			this.#lastSpinnerAdvanceAt = now;
-			if (frameCount > 0 && this.#spinnerFrame === undefined) {
-				this.#spinnerFrame = 0;
-				this.#renderState.spinnerFrame = 0;
-			}
+			const frame = sharedSpinnerFrame(frameCount);
+			this.#spinnerFrame = frame;
+			this.#renderState.spinnerFrame = frame;
 			this.#spinnerInterval = setInterval(() => {
 				// If a detached task interval from an older render path is still live,
 				// stop it the instant the block leaves the repaintable region.
 				if (this.#maybeFreezeBackgroundTask()) return;
 				const now = performance.now();
 				const frameCount = theme.spinnerFrames.length;
-				// Redraw at 30fps, but keep the spinner glyph phase-locked to its
-				// classic ~12.5fps cadence. Advancing the anchor by elapsed frames
-				// instead of resetting to `now` avoids the 30fps timer quantizing the
-				// glyph down to one step every three ticks.
-				if (frameCount > 0) {
-					const elapsed = now - this.#lastSpinnerAdvanceAt;
-					if (elapsed >= SPINNER_GLYPH_ADVANCE_MS) {
-						const steps = Math.floor(elapsed / SPINNER_GLYPH_ADVANCE_MS);
-						this.#spinnerFrame = ((this.#spinnerFrame ?? 0) + steps) % frameCount;
-						this.#renderState.spinnerFrame = this.#spinnerFrame;
-						this.#lastSpinnerAdvanceAt += steps * SPINNER_GLYPH_ADVANCE_MS;
-					}
-				}
+				this.#spinnerFrame = sharedSpinnerFrame(frameCount, now);
+				this.#renderState.spinnerFrame = this.#spinnerFrame;
 				this.#ui.requestRender();
 			}, SPINNER_RENDER_INTERVAL_MS);
 		} else if (!needsSpinner && this.#spinnerInterval) {
@@ -568,6 +580,17 @@ export class ToolExecutionComponent extends Container {
 		}
 	}
 
+	/**
+	 * Standalone harnesses may mount a tool component directly under `TUI`
+	 * instead of inside `TranscriptContainer`. In that shape the component must
+	 * report its own live-region seam for provisional previews, or the core
+	 * renderer treats it like shell output and commits tail-window edit/eval/bash
+	 * previews to immutable native scrollback before the result replaces them.
+	 */
+	getNativeScrollbackLiveRegionStart(): number | undefined {
+		return !this.isTranscriptBlockFinalized() && !this.isTranscriptBlockCommitStable() ? 0 : undefined;
+	}
+
 	/**
 	 * Whether this block has reached a terminal state for transcript freezing.
 	 * Reports `false` while it can still visually change so the
@@ -591,28 +614,20 @@ export class ToolExecutionComponent extends Container {
 
 	/**
 	 * Whether this still-live block's settled rows may enter native scrollback
-	 * (see `FinalizableBlock.isTranscriptBlockCommitStable`). Classification is
-	 * per renderer (`ToolRenderer.provisionalPendingPreview`): tail-window
-	 * streaming views (edit's streamed-diff tail, bash/ssh command caps, eval
-	 * cells) are re-anchored top-first by the result render, so promoting
-	 * their visually static head — e.g. an edit preview idling on its last
-	 * frame while the apply + LSP pass runs — would strand a stale copy of
-	 * the call box above the final block the moment the result lands. Every
-	 * other pending preview streams top-anchored append-shaped rows the
-	 * result render preserves (a task call's context/assignment markdown, a
-	 * write's content), so it stays commit-eligible — a call taller than the
-	 * viewport scrolls into native history mid-stream instead of reading as
-	 * cut off until the result. Expanded blocks always stream top-anchored
-	 * (the over-tall write/eval scrollback contract). Displaceable waiting
-	 * polls are removed wholesale by the next poll and must never commit.
+	 * (see `FinalizableBlock.isTranscriptBlockCommitStable`). Renderers classify
+	 * pending views by durability instead of by tool name: a provisional view is
+	 * allowed to be useful on screen, but finalization may replace or re-anchor
+	 * it wholesale, so committing any of its rows would strand stale preview
+	 * bytes in immutable scrollback. Non-provisional views stream rows whose
+	 * committed prefix survives the remaining transitions.
 	 */
 	isTranscriptBlockCommitStable(): boolean {
 		if (this.#displaceable) return false;
-		if (this.#expanded || this.isTranscriptBlockFinalized()) return true;
-		if ((this.#tool as { provisionalPendingPreview?: boolean } | undefined)?.provisionalPendingPreview) {
-			return false;
-		}
-		return !toolRenderers[this.#toolName]?.provisionalPendingPreview;
+		if (this.isTranscriptBlockFinalized()) return true;
+		const tool = this.#tool as { provisionalPendingPreview?: boolean | "collapsed" } | undefined;
+		const provisionalPendingPreview =
+			tool?.provisionalPendingPreview ?? toolRenderers[this.#toolName]?.provisionalPendingPreview;
+		return provisionalPendingPreview !== true && (provisionalPendingPreview !== "collapsed" || this.#expanded);
 	}
 
 	/**
@@ -674,6 +689,29 @@ export class ToolExecutionComponent extends Container {
 	}
 
 	#updateDisplay(): void {
+		// `TERMINAL.imageProtocol` is resolved by an async capability probe during
+		// TUI startup, so a result rendered before it lands must re-shape once it
+		// does (it gates Image children vs text fallback in #rebuildDisplay); keyed
+		// here for the same reason markdown.ts keys its render cache on it.
+		const key = `${this.#resultVersion}|${this.#expanded}|${this.#isPartial}|${this.#spinnerFrame ?? "-"}|${this.#showImages}|${getThemeEpoch()}|${this.#displayInputVersion}|${this.#backgroundTaskFrozen}|${TERMINAL.imageProtocol ?? "-"}|${this.#imageSizeKey()}`;
+		if (key === this.#lastDisplayKey && this.#displayBuilt) return;
+		this.#lastDisplayKey = key;
+
+		this.#rebuildDisplay();
+		this.#displayBuilt = true;
+	}
+
+	// Viewport-/settings-dependent image sizing folded into the memo key only when
+	// the last rebuild actually emitted images, so a terminal resize re-shapes an
+	// image-bearing result (to rescale it) without re-shaping every image-free
+	// result on each resize tick.
+	#imageSizeKey(): string {
+		if (this.#renderedImageCount === 0) return "-";
+		const o = resolveImageOptions();
+		return `${o.maxWidthCells}:${o.maxHeightCells ?? "-"}`;
+	}
+
+	#rebuildDisplay(): void {
 		// Sync shared mutable render state for component closures
 		this.#renderState.expanded = this.#expanded;
 		this.#renderState.isPartial = this.#isPartial;
@@ -917,6 +955,7 @@ export class ToolExecutionComponent extends Container {
 				}
 			}
 		}
+		this.#renderedImageCount = this.#imageComponents.length;
 	}
 
 	#getCallArgsForRender(): any {