@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/theme/defaults/onyx.json

@@ -16,76 +16,76 @@
 		"emerald": "#6fb37f"
 	},
 	"colors": {
-		"accent": "$vein",
-		"border": "$band2",
-		"borderAccent": "$vein",
-		"borderMuted": "$band1",
-		"success": "$emerald",
-		"error": "$ruby",
-		"warning": "$bronze",
-		"muted": "$warmGray",
+		"accent": "vein",
+		"border": "band2",
+		"borderAccent": "vein",
+		"borderMuted": "band1",
+		"success": "emerald",
+		"error": "ruby",
+		"warning": "bronze",
+		"muted": "warmGray",
 		"dim": "#6a6760",
 		"text": "",
-		"thinkingText": "$warmGray",
-		"selectedBg": "$band2",
-		"userMessageBg": "$band1",
+		"thinkingText": "warmGray",
+		"selectedBg": "band2",
+		"userMessageBg": "band1",
 		"userMessageText": "",
-		"customMessageBg": "$band2",
+		"customMessageBg": "band2",
 		"customMessageText": "",
-		"customMessageLabel": "$vein",
-		"toolPendingBg": "$band1",
-		"toolSuccessBg": "$band1",
-		"toolErrorBg": "$band1",
+		"customMessageLabel": "vein",
+		"toolPendingBg": "band1",
+		"toolSuccessBg": "band1",
+		"toolErrorBg": "band1",
 		"toolTitle": "",
-		"toolOutput": "$warmGray",
-		"mdHeading": "$vein",
-		"mdLink": "$bronze",
-		"mdLinkUrl": "$copper",
-		"mdCode": "$vein",
-		"mdCodeBlock": "$cream",
-		"mdCodeBlockBorder": "$band3",
-		"mdQuote": "$warmGray",
-		"mdQuoteBorder": "$veinDim",
-		"mdHr": "$band2",
-		"mdListBullet": "$vein",
-		"toolDiffAdded": "$emerald",
-		"toolDiffRemoved": "$ruby",
-		"toolDiffContext": "$warmGray",
+		"toolOutput": "warmGray",
+		"mdHeading": "vein",
+		"mdLink": "bronze",
+		"mdLinkUrl": "copper",
+		"mdCode": "vein",
+		"mdCodeBlock": "cream",
+		"mdCodeBlockBorder": "band3",
+		"mdQuote": "warmGray",
+		"mdQuoteBorder": "veinDim",
+		"mdHr": "band2",
+		"mdListBullet": "vein",
+		"toolDiffAdded": "emerald",
+		"toolDiffRemoved": "ruby",
+		"toolDiffContext": "warmGray",
 		"syntaxComment": "#6a6760",
-		"syntaxKeyword": "$vein",
-		"syntaxFunction": "$bronze",
-		"syntaxVariable": "$cream",
-		"syntaxString": "$copper",
-		"syntaxNumber": "$veinDim",
-		"syntaxType": "$vein",
-		"syntaxOperator": "$warmGray",
-		"syntaxPunctuation": "$warmGray",
-		"thinkingOff": "$warmGray",
-		"thinkingMinimal": "$warmGray",
-		"thinkingLow": "$warmGray",
-		"thinkingMedium": "$veinDim",
-		"thinkingHigh": "$vein",
-		"thinkingXhigh": "$bronze",
-		"bashMode": "$vein",
-		"statusLineBg": "$band1",
-		"statusLineSep": "$band3",
-		"statusLineModel": "$vein",
-		"statusLinePath": "$cream",
-		"statusLineGitClean": "$emerald",
-		"statusLineGitDirty": "$bronze",
-		"statusLineContext": "$warmGray",
-		"statusLineSpend": "$copper",
-		"statusLineStaged": "$emerald",
-		"statusLineDirty": "$bronze",
-		"statusLineUntracked": "$warmGray",
-		"statusLineOutput": "$cream",
-		"statusLineCost": "$copper",
-		"statusLineSubagents": "$vein",
+		"syntaxKeyword": "vein",
+		"syntaxFunction": "bronze",
+		"syntaxVariable": "cream",
+		"syntaxString": "copper",
+		"syntaxNumber": "veinDim",
+		"syntaxType": "vein",
+		"syntaxOperator": "warmGray",
+		"syntaxPunctuation": "warmGray",
+		"thinkingOff": "warmGray",
+		"thinkingMinimal": "warmGray",
+		"thinkingLow": "warmGray",
+		"thinkingMedium": "veinDim",
+		"thinkingHigh": "vein",
+		"thinkingXhigh": "bronze",
+		"bashMode": "vein",
+		"statusLineBg": "band1",
+		"statusLineSep": "band3",
+		"statusLineModel": "vein",
+		"statusLinePath": "cream",
+		"statusLineGitClean": "emerald",
+		"statusLineGitDirty": "bronze",
+		"statusLineContext": "warmGray",
+		"statusLineSpend": "copper",
+		"statusLineStaged": "emerald",
+		"statusLineDirty": "bronze",
+		"statusLineUntracked": "warmGray",
+		"statusLineOutput": "cream",
+		"statusLineCost": "copper",
+		"statusLineSubagents": "vein",
 		"pythonMode": "#f0c040"
 	},
 	"export": {
-		"pageBg": "$stone",
-		"cardBg": "$band1",
-		"infoBg": "$band2"
+		"pageBg": "stone",
+		"cardBg": "band1",
+		"infoBg": "band2"
 	}
 }

package/src/theme/mermaid-cache.ts

@@ -1,4 +1,5 @@
 import type { MermaidRenderOptions } from "@oh-my-pi/pi-natives";
+import { LRUCache } from "@oh-my-pi/pi-utils/lru";
 import * as mermaidAscii from "@oh-my-pi/pi-utils/mermaid-ascii";
 
 /**
@@ -19,7 +20,15 @@ export interface MermaidResolveOptions extends MermaidRenderOptions {
 // Memoizes rendered ASCII (and failures) keyed on the render options + the
 // layout-direction variant + source. Width selection happens per call against
 // the cached renders, so a terminal resize re-decides without re-rendering.
-const cache = new Map<string, string | null>();
+// Bounded by entry count and by UTF-16 length of key (which embeds the whole
+// source) plus rendered ASCII, so long sessions cannot pin every diagram.
+const MERMAID_CACHE_MAX = 256;
+const MERMAID_CACHE_MAX_SIZE = 4 * 1024 * 1024;
+const cache = new LRUCache<string, string | null>({
+	max: MERMAID_CACHE_MAX,
+	maxSize: MERMAID_CACHE_MAX_SIZE,
+	sizeCalculation: (ascii, key) => key.length + (ascii?.length ?? 0),
+});
 
 /** Display columns, ignoring ANSI so themed diagrams are measured as drawn. */
 const DISPLAY_WIDTH = { countAnsiEscapeCodes: false } as const;

package/src/theme/schema.ts

@@ -165,4 +165,19 @@ export type ThemeBg =
 	| "toolErrorBg"
 	| "statusLineBg";
 
+const VALID_THEME_BGS: ReadonlySet<string> = new Set([
+	"selectedBg",
+	"userMessageBg",
+	"customMessageBg",
+	"toolPendingBg",
+	"toolSuccessBg",
+	"toolErrorBg",
+	"statusLineBg",
+] satisfies ThemeBg[]);
+
+/** Check if a string is a valid ThemeBg value */
+export function isValidThemeBg(color: string): color is ThemeBg {
+	return VALID_THEME_BGS.has(color);
+}
+
 export type ColorMode = "truecolor" | "256color";

package/src/theme/shimmer.ts

@@ -1,3 +1,7 @@
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import { node } from "../native/describe";
+import type { NativeNode } from "../native/node";
+import { isNativeRendering } from "../native/state";
 import type { Theme, ThemeColor } from "./theme";
 import { FG_RESET } from "./color";
 
@@ -151,6 +155,28 @@ export function shimmerEnabled(): boolean {
 	return activeMode !== "disabled";
 }
 
+/**
+ * Describe shimmering segments for a TSP terminal, which clocks the sweep
+ * itself: a `shimmer` node in the active mode, or plain spans in the mid tier
+ * color when shimmer is disabled. Palette tiers given as theme colors travel as
+ * token names; raw-ANSI tiers are dropped (the terminal's theme decides).
+ */
+export function describeShimmer(segments: readonly ShimmerSegment[], key?: string): NativeNode {
+	const spans: TspSpan[] = [];
+	for (const { text: value, palette } of segments) {
+		if (value.length === 0) continue;
+		const mid = (palette ?? DEFAULT_SHIMMER_PALETTE).mid;
+		spans.push(typeof mid === "string" ? { t: value, s: mid } : { t: value });
+	}
+	if (activeMode === "disabled") return node("text", { spans }, undefined, key);
+	const palette = segments[0]?.palette ?? DEFAULT_SHIMMER_PALETTE;
+	const tokens: { low?: string; mid?: string; high?: string } = {};
+	if (typeof palette.low === "string") tokens.low = palette.low;
+	if (typeof palette.mid === "string") tokens.mid = palette.mid;
+	if (typeof palette.high === "string") tokens.high = palette.high;
+	return node("shimmer", { spans, mode: activeMode, palette: tokens }, undefined, key);
+}
+
 /**
  * Apply a shimmer sweep across one or more segments, treating them as a
  * single continuous string for band positioning. Each segment can supply
@@ -165,6 +191,13 @@ export function shimmerEnabled(): boolean {
  *   - No per-char allocations beyond the run buffer.
  */
 export function shimmerSegments(segments: readonly ShimmerSegment[], theme: ShimmerTheme): string {
+	// A TSP terminal animates shimmer from described nodes; a frame painted
+	// here would freeze mid-sweep, so the text goes out unstyled.
+	if (isNativeRendering()) {
+		let out = "";
+		for (const { text: value } of segments) out += value;
+		return out;
+	}
 	const mode = activeMode;
 
 	// Disabled: no animation or code-point scan. Preserve the all-empty result,

package/src/theme/theme-class.ts

@@ -140,6 +140,26 @@ const underlineStyler = chalk.underline;
 const strikethroughStyler = chalk.strikethrough;
 const inverseStyler = chalk.inverse;
 
+/** Theme token of a thinking/effort level name (`off`…`max`); unknown levels (`auto`) map to `thinkingOff`. */
+export function thinkingLevelToken(level: string): ThemeColor {
+	switch (level) {
+		case "minimal":
+			return "thinkingMinimal";
+		case "low":
+			return "thinkingLow";
+		case "medium":
+			return "thinkingMedium";
+		case "high":
+			return "thinkingHigh";
+		case "xhigh":
+			return "thinkingXhigh";
+		case "max":
+			return "thinkingMax";
+		default:
+			return "thinkingOff";
+	}
+}
+
 export class Theme {
 	#fgColors: Record<ThemeColor, string>;
 	#bgColors: Record<ThemeBg, string>;
@@ -419,25 +439,10 @@ export class Theme {
 
 	/** Border color for a thinking/effort level name (`off`…`max`); unknown levels fall back to `thinkingOff`. */
 	getThinkingBorderColor(level: string): (str: string) => string {
-		switch (level) {
-			case "off":
-				return (str: string) => this.fg("thinkingOff", str);
-			case "minimal":
-				return (str: string) => this.fg("thinkingMinimal", str);
-			case "low":
-				return (str: string) => this.fg("thinkingLow", str);
-			case "medium":
-				return (str: string) => this.fg("thinkingMedium", str);
-			case "high":
-				return (str: string) => this.fg("thinkingHigh", str);
-			case "xhigh":
-				return (str: string) => this.fg("thinkingXhigh", str);
-			case "max":
-				// thinkingMax is optional; themes without it resolve to the xhigh color.
-				return (str: string) => this.fg(this.#fgColors.thinkingMax ? "thinkingMax" : "thinkingXhigh", str);
-			default:
-				return (str: string) => this.fg("thinkingOff", str);
-		}
+		const token = thinkingLevelToken(level);
+		// thinkingMax is optional; themes without it resolve to the xhigh color.
+		const color = token === "thinkingMax" && !this.#fgColors.thinkingMax ? "thinkingXhigh" : token;
+		return (str: string) => this.fg(color, str);
 	}
 
 	getBashModeBorderColor(): (str: string) => string {

package/src/theme/theme.ts

@@ -7,8 +7,16 @@ import { getCustomThemesDir } from "@oh-my-pi/pi-utils/dirs";
 import * as logger from "@oh-my-pi/pi-utils/logger";
 import { setActiveSymbolTheme } from "./active-symbols";
 import { ansi256ToHex, resolveThemeColors, resolveVarRefs } from "./color";
-import { type CreateThemeOptions, getBuiltinThemes, loadTheme, loadThemeJson, loadThemeSync } from "./loader";
-import type { ThemeColor, ThemeJson } from "./schema";
+import {
+	type CreateThemeOptions,
+	createTheme,
+	getBuiltinThemes,
+	loadTheme,
+	loadThemeJson,
+	loadThemeJsonSync,
+	loadThemeSync,
+} from "./loader";
+import { isValidThemeBg, isValidThemeColor, type ThemeColor, type ThemeJson } from "./schema";
 import type { SymbolPreset } from "./symbols";
 import type { Theme } from "./theme-class";
 
@@ -84,6 +92,8 @@ function getDefaultTheme(): string {
 /** Active theme; imports remain live across initialization, previews, and theme switches. */
 export var theme: Theme;
 var currentThemeName: string | undefined;
+/** Theme shown by `previewTheme` until the next non-preview assignment. */
+var previewThemeName: string | undefined;
 
 type ThemeBinding = (value: Theme) => void;
 var themeBindings: Set<ThemeBinding> | undefined;
@@ -98,8 +108,10 @@ export function bindTheme(binding: ThemeBinding): () => void {
 	};
 }
 
-function assignTheme(value: Theme): void {
+/** `previewName` marks a theme-selector preview; any other assignment ends it. */
+function assignTheme(value: Theme, previewName?: string): void {
 	theme = value;
+	previewThemeName = previewName;
 	setActiveSymbolTheme(value);
 	if (themeBindings) {
 		for (const binding of themeBindings) binding(value);
@@ -121,6 +133,9 @@ export interface ThemeChangeEvent {
 }
 
 var currentSymbolPresetOverride: SymbolPreset | undefined;
+// Process-local preset forced while a Tern Surface Protocol surface is live;
+// wins over the user's preset and is never persisted.
+var nativeSymbolPreset: SymbolPreset | undefined;
 var currentColorBlindMode: boolean = false;
 var themeWatcher: fs.FSWatcher | undefined;
 var themeReloadTimer: NodeJS.Timeout | undefined;
@@ -134,7 +149,7 @@ let themeEpoch = 0;
 
 function getCurrentThemeOptions(): CreateThemeOptions {
 	return {
-		symbolPresetOverride: currentSymbolPresetOverride,
+		symbolPresetOverride: nativeSymbolPreset ?? currentSymbolPresetOverride,
 		colorBlindMode: currentColorBlindMode,
 	};
 }
@@ -162,10 +177,7 @@ export function initThemeSync(
 	lightTheme?: string,
 ): void {
 	const name = configureTheme(symbolPreset, colorBlindMode, darkTheme, lightTheme);
-	const options: CreateThemeOptions = {
-		symbolPresetOverride: currentSymbolPresetOverride,
-		colorBlindMode: currentColorBlindMode,
-	};
+	const options = getCurrentThemeOptions();
 	try {
 		assignTheme(loadThemeSync(name, options));
 	} catch (error) {
@@ -255,7 +267,8 @@ export async function previewTheme(
 		if (requestId !== themeLoadRequestId) {
 			return { success: false, error: "Theme preview superseded by a newer request" };
 		}
-		assignTheme(loadedTheme);
+		// Previewing the active theme again (selector cancel) ends the preview.
+		assignTheme(loadedTheme, name === currentThemeName ? undefined : name);
 		notifyThemeChange(event);
 		return { success: true };
 	} catch (error) {
@@ -337,6 +350,30 @@ export function getSymbolPresetOverride(): SymbolPreset | undefined {
 	return currentSymbolPresetOverride;
 }
 
+/**
+ * Force `preset` while a Tern Surface Protocol surface is live (the terminal's
+ * font carries every Nerd Font glyph, so icons need no Glyph Protocol
+ * registration); `undefined` restores the user's preset. Process-local and
+ * never persisted. Rebuilds the active theme synchronously so the next frame
+ * already uses it, and notifies theme listeners like a preset change. Returns
+ * whether the active theme was rebuilt (callers invalidate render caches).
+ */
+export function setNativeSymbolPreset(preset: SymbolPreset | undefined): boolean {
+	if (nativeSymbolPreset === preset) return false;
+	nativeSymbolPreset = preset;
+	if (!currentThemeName || typeof theme === "undefined") return false;
+	++themeLoadRequestId;
+	try {
+		assignTheme(loadThemeSync(currentThemeName, getCurrentThemeOptions()));
+	} catch (error) {
+		// In-memory themes can't be rebuilt by name; they keep their symbols.
+		logger.debug("Native symbol preset: theme rebuild skipped", { theme: currentThemeName, error: String(error) });
+		return false;
+	}
+	notifyThemeChange({ ephemeral: true });
+	return true;
+}
+
 /**
  * Set color blind mode, recreating the theme with the new setting.
  * When enabled, uses blue instead of green for diff additions.
@@ -770,6 +807,71 @@ export async function getResolvedThemeColors(themeName?: string): Promise<Record
 	return cssColors;
 }
 
+/** One appearance variant of {@link NativeThemePalette}: token name → `#rrggbb`. */
+export type NativeThemeVariant = Record<string, string>;
+
+/** omp's resolved theme for a Tern Surface Protocol terminal (the `t` verb body minus `sf`). */
+export interface NativeThemePalette {
+	dark?: NativeThemeVariant;
+	light?: NativeThemeVariant;
+	name: { dark?: string; light?: string };
+}
+
+/**
+ * Cheap identity of everything {@link getNativeThemePalette} depends on;
+ * recompute the palette only when it changes.
+ */
+export function getNativeThemePaletteKey(): string {
+	return `${themeEpoch}|${autoDetectedTheme}|${autoDarkTheme}|${autoLightTheme}|${currentThemeName}|${previewThemeName}|${currentColorBlindMode}`;
+}
+
+/** Every token of theme `name` as hex (terminal-default tokens omitted), plus its export colours. */
+function nativeThemeVariant(name: string): { light: boolean; colors: NativeThemeVariant } {
+	const themeJson = loadThemeJsonSync(name);
+	const built = createTheme(themeJson, getCurrentThemeOptions());
+	const raw = resolveThemeColors(themeJson.colors, themeJson.vars);
+	const colors: NativeThemeVariant = {};
+	for (const key in raw) {
+		// Terminal-default tokens stay unset; keys outside the schema are ignored like the theme does.
+		if (raw[key as keyof typeof raw] === "") continue;
+		if (isValidThemeColor(key)) colors[key] = built.getColorHex(key);
+		else if (isValidThemeBg(key)) colors[key] = built.getBgHex(key);
+	}
+	const exported = resolveThemeExportColors(themeJson);
+	for (const key of ["pageBg", "cardBg", "infoBg"] as const) {
+		const value = exported[key];
+		if (value) colors[key] = value;
+	}
+	return { light: isLightThemeJson(themeJson), colors };
+}
+
+/**
+ * omp's theme for a native surface: with auto theme, the configured dark and
+ * light themes; otherwise (or while the theme selector previews one) the
+ * active theme under its own appearance only. Themes without a loadable
+ * definition (in-memory instances) contribute nothing.
+ */
+export function getNativeThemePalette(): NativeThemePalette {
+	const palette: NativeThemePalette = { name: {} };
+	const add = (name: string, as?: "dark" | "light"): void => {
+		try {
+			const variant = nativeThemeVariant(name);
+			const slot = as ?? (variant.light ? "light" : "dark");
+			palette[slot] = variant.colors;
+			palette.name[slot] = name;
+		} catch (error) {
+			logger.debug("Native theme palette: theme not loadable", { name, error: String(error) });
+		}
+	};
+	const single = previewThemeName ?? (autoDetectedTheme ? undefined : currentThemeName);
+	if (single !== undefined) add(single);
+	else {
+		add(autoDarkTheme, "dark");
+		add(autoLightTheme, "light");
+	}
+	return palette;
+}
+
 /**
  * Check if a theme is a "light" theme by analyzing its status-line background
  * luminance. Loads theme JSON synchronously (built-in or custom file on disk)

package/src/theme/tui-adapters.ts

@@ -59,7 +59,20 @@ function getHighlightColors(t: Theme): NativeHighlightColors {
  * the 33ms frame budget and starving the spinner/render timers (the "TUI freeze").
  */
 const HIGHLIGHT_CACHE_MAX = 256;
-const highlightCache = new LRUCache<string, string>({ max: HIGHLIGHT_CACHE_MAX });
+// Size-bound like markdown's render cache: a streaming block (bash command,
+// eval cell) inserts one full `code + highlighted` pair per growth frame, so a
+// count cap alone would retain 256 near-copies of a large payload. Sizes are
+// UTF-16 code units of key + value (ANSI output runs several times the source
+// length). The per-entry cap stays generous so a large but settled code body
+// repainting every frame still hits; only payloads past it re-highlight.
+const HIGHLIGHT_CACHE_MAX_SIZE = 8 * 1024 * 1024;
+const HIGHLIGHT_CACHE_MAX_ENTRY_SIZE = 1024 * 1024;
+const highlightCache = new LRUCache<string, string>({
+	max: HIGHLIGHT_CACHE_MAX,
+	maxSize: HIGHLIGHT_CACHE_MAX_SIZE,
+	maxEntrySize: HIGHLIGHT_CACHE_MAX_ENTRY_SIZE,
+	sizeCalculation: (value, key) => Math.max(1, key.length + value.length),
+});
 let highlightCacheTheme: Theme | undefined;
 
 function highlightCached(code: string, validLang: string | undefined, highlightTheme: Theme): string | null {

package/src/tools/ask.ts

@@ -1,4 +1,10 @@
-import type { ToolRenderer } from "./renderer";
+import type { NativeToolHead, NativeToolView, ToolRenderer, ToolRenderResult } from "./renderer";
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import { compact, md, node, row, span, text } from "../native/describe";
+import type { NativeChild, NativeNode } from "../native/node";
+import { OwnerMemo } from "../native/memo";
+import { plainText } from "../native/spans";
+import { noteText, resultText } from "./native-view";
 
 import {
 	type Component,
@@ -281,8 +287,158 @@ function renderAnswerOptionLines(
 	return out;
 }
 
+function askHead(question: string | undefined, meta?: string): NativeToolHead {
+	const first = question ? plainText(sanitizeCarriageReturns(question)).trim().split("\n")[0] : "";
+	return { title: "Ask", target: first || undefined, targetKind: "text", meta: meta ? [meta] : undefined };
+}
+
+/** One question of a multi-question result: the question as markdown over its answers. */
+function describeQuestionSection(id: string, question: string, rest: readonly NativeChild[]): NativeNode {
+	return node("section", {}, [md(plainText(question)), ...rest], id);
+}
+
+/** An answer row: a success check before the chosen label, or a quiet unchosen label. */
+function answerRow(key: string, label: TspSpan[], chosen: boolean): NativeNode {
+	return row(
+		compact([chosen ? node("icon", { name: "check", tone: "success" }) : undefined, text(label, { wrap: "word" })]),
+		{ gap: "sm", align: "baseline", role: chosen ? "omp.tool.answer" : "omp.tool.answer.off", key },
+	);
+}
+
+/**
+ * Answered option list: every offered option marked chosen or not, plus any
+ * quoted custom answer and a muted note. A lone "Cancelled" line when nothing was chosen.
+ */
+function describeAnswers(
+	options: string[] | undefined,
+	selectedOptions: string[] | undefined,
+	customInput: string | undefined,
+	note: string | undefined,
+	selectedIndices: ReadonlySet<number> | undefined,
+): NativeChild[] {
+	const selected = new Set(selectedOptions ?? []);
+	if (selected.size === 0 && customInput === undefined && note === undefined) {
+		return [text([span("Cancelled", "warning")], { tone: "warning" })];
+	}
+	const labels = options && options.length > 0 ? options : (selectedOptions ?? []);
+	const rows = labels.map((label, index) => {
+		const isSelected = selectedIndices !== undefined ? selectedIndices.has(index) : selected.has(label);
+		return answerRow(`${index}`, [span(plainText(label), isSelected ? "toolOutput" : "muted")], isSelected);
+	});
+	if (customInput !== undefined) {
+		rows.push(answerRow("custom", [span(`\u201c${plainText(customInput)}\u201d`, "toolOutput")], true));
+	}
+	return compact([
+		...rows,
+		note !== undefined
+			? text([span(plainText(note), "muted")], { wrap: "word", role: "omp.tool.context" })
+			: undefined,
+	]);
+}
+
+/** Pending ask: an inline head naming the question; the ask dialog owns the form. */
+function describeAskCall(args: AskRenderArgs): NativeToolView {
+	const questions = normalizeRenderQuestions(args.questions);
+	const first = questions?.[0]?.question ?? (typeof args.question === "string" ? args.question : undefined);
+	const more = questions && questions.length > 1 ? `${questions.length} questions` : undefined;
+	return {
+		tool: askHead(first, more),
+		inline: true,
+		body: [text([span("Waiting for your answer…", "muted")])],
+	};
+}
+
+function describeAskResult(result: ToolRenderResult<AskToolDetails>, args: AskRenderArgs | undefined): NativeToolView {
+	const rawDetails = result.details;
+	const fallback = plainText(sanitizeCarriageReturns(resultText(result)));
+	const argQuestion =
+		normalizeRenderQuestions(args?.questions)?.[0]?.question ??
+		(typeof args?.question === "string" ? args.question : undefined);
+	if (!rawDetails) {
+		return { tool: askHead(argQuestion), tone: "warning", body: fallback ? [noteText(fallback)] : undefined };
+	}
+	const details = sanitizeAskResultDetails(rawDetails);
+
+	if (details.chatRedirect) {
+		return {
+			tool: askHead(details.questions?.[0] ?? argQuestion, "chat redirect"),
+			tone: "info",
+			body: (details.questions ?? []).map(q => md(plainText(q))),
+		};
+	}
+
+	if (details.results && details.results.length > 0) {
+		const results = details.results;
+		const rawResults = rawDetails.results ?? [];
+		const answered = results.some(
+			r =>
+				r.customInput !== undefined || r.note !== undefined || (r.selectedOptions && r.selectedOptions.length > 0),
+		);
+		return {
+			tool: askHead(results[0]?.question, results.length > 1 ? `${results.length} questions` : undefined),
+			tone: answered ? undefined : "warning",
+			// Sanitizing preserves order and length, so raw indices align with `r`.
+			body: results.map((r, index) =>
+				describeQuestionSection(
+					r.id,
+					r.question,
+					describeAnswers(
+						r.options,
+						r.selectedOptions,
+						r.customInput,
+						r.note,
+						selectedIndicesFor(rawResults[index]?.options, rawResults[index]?.selectedOptions),
+					),
+				),
+			),
+		};
+	}
+
+	if (!details.question) {
+		return { tool: askHead(argQuestion), body: fallback ? [text(fallback, { wrap: "word" })] : undefined };
+	}
+
+	const answered =
+		details.customInput !== undefined ||
+		details.note !== undefined ||
+		(details.selectedOptions && details.selectedOptions.length > 0);
+	return {
+		tool: askHead(details.question),
+		tone: answered ? undefined : "warning",
+		body: compact([
+			md(plainText(details.question)),
+			...describeAnswers(
+				details.options,
+				details.selectedOptions,
+				details.customInput,
+				details.note,
+				selectedIndicesFor(rawDetails.options, rawDetails.selectedOptions),
+			),
+			details.timedOut
+				? text([span("auto-selected after timeout — not a user choice", "muted")], {
+						wrap: "word",
+						role: "omp.tool.notice",
+					})
+				: undefined,
+		]),
+	};
+}
+
+const askCallMemo = new OwnerMemo<NativeToolView | undefined>();
+const askResultMemo = new OwnerMemo<NativeToolView | undefined>();
+
 /** Render question forms and their recorded answers. */
 export const askToolRenderer = {
+	describeCall(args: AskRenderArgs): NativeToolView | undefined {
+		return askCallMemo.get(args, [JSON.stringify(args)], () => describeAskCall(args));
+	},
+	describeResult(
+		result: ToolRenderResult<AskToolDetails>,
+		_options?: RenderResultOptions,
+		args?: AskRenderArgs,
+	): NativeToolView | undefined {
+		return askResultMemo.get(result, [], () => describeAskResult(result, args));
+	},
 	mergeCallAndResult: true,
 	renderCall(args: AskRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const label = formatTitle("Ask", uiTheme);