@oh-my-pi/pi-coding-agent 17.2.10 → 17.2.12

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

@@ -23,7 +23,7 @@ import { formatDefaultToolExecution } from "../../tools/default-renderer";
 import { EVAL_DEFAULT_PREVIEW_LINES } from "../../tools/eval";
 import { isWaitingPollDetails } from "../../tools/hub";
 import { formatStatusIcon, replaceTabs, resolveImageOptions } from "../../tools/render-utils";
-import { type FirstResultViewportRepaint, toolRenderers } from "../../tools/renderers";
+import { type FirstResultViewportRepaint, type ToolRenderer, toolRenderers } from "../../tools/renderers";
 import { TODO_STRIKE_TOTAL_FRAMES, type TodoToolDetails } from "../../tools/todo";
 import type { XdevState } from "../../tools/xdev";
 import { isFramedBlockComponent, markFramedBlockComponent, renderStatusLine, WidthAwareText } from "../../tui";
@@ -226,6 +226,8 @@ export interface ToolExecutionOptions {
 	/** Session-persistent edit clipboard register, forked per preview frame. */
 	clipboard?: Clipboard;
 	showImages?: boolean; // default: true (only used if terminal supports images)
+	/** Allow the name-keyed renderer registry only when the active tool is the built-in implementation. */
+	useBuiltInRenderer?: boolean;
 	editFuzzyThreshold?: number;
 	editAllowFuzzy?: boolean;
 	/** Live-region probe used to settle detached task progress once the block
@@ -312,6 +314,7 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 	// forcing the common image-free result to re-shape on every resize tick.
 	#renderedImageCount = 0;
 	#tool?: AgentTool;
+	#renderer?: ToolRenderer;
 	#ui: ToolExecutionUi;
 	#cwd: string;
 	#result?: {
@@ -398,6 +401,7 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		super();
 		this.#toolName = toolName;
 		this.#toolLabel = tool?.label ?? toolName;
+		this.#renderer = options.useBuiltInRenderer === false ? undefined : toolRenderers[toolName];
 		this.#showImages = options.showImages ?? true;
 		this.#editFuzzyThreshold = options.editFuzzyThreshold;
 		this.#editAllowFuzzy = options.editAllowFuzzy;
@@ -418,10 +422,9 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		this.#contentBox = new Box(0, 1);
 		this.#contentText = new WidthAwareText(contentWidth => this.#renderDefaultCard(contentWidth), 1, 1);
 
-		// Use Box for custom tools or built-in tools that have renderers
-		const hasRenderer = toolName in toolRenderers;
+		// Use Box for custom tools or built-in tools with rich renderers.
 		const hasCustomRenderer = !!(tool?.renderCall || tool?.renderResult);
-		this.#usesContentBox = hasCustomRenderer || hasRenderer;
+		this.#usesContentBox = hasCustomRenderer || this.#renderer !== undefined;
 		if (this.#usesContentBox) {
 			this.addChild(this.#contentBox);
 		} else {
@@ -668,12 +671,7 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		const isStreamingArgs = !this.#argsComplete && (isEditLikeToolName(this.#toolName) || this.#toolName === "write");
 		const isBackgroundAsyncRunning =
 			(this.#result?.details as { async?: { state?: string } } | undefined)?.async?.state === "running";
-		const renderer = toolRenderers[this.#toolName] as
-			| {
-					animatedPendingPreview?: boolean | ((args: unknown) => boolean);
-					animatedPartialResult?: boolean | ((args: unknown) => boolean);
-			  }
-			| undefined;
+		const renderer = this.#renderer;
 		const pendingAnimation = renderer?.animatedPendingPreview;
 		const partialAnimation = renderer?.animatedPartialResult;
 		const pendingCallConsumesSpinner =
@@ -933,7 +931,7 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 
 	#rendererFlag(name: "forceResultViewportRepaintOnSettle"): boolean {
 		const toolValue = (this.#tool as Record<string, unknown> | undefined)?.[name];
-		const rendererValue = toolRenderers[this.#toolName]?.[name];
+		const rendererValue = this.#renderer?.[name];
 		return toolValue === true || (toolValue === undefined && rendererValue === true);
 	}
 
@@ -948,8 +946,7 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		if (this.#result !== undefined) return false;
 		const toolValue = (this.#tool as { forceFirstResultViewportRepaint?: FirstResultViewportRepaint } | undefined)
 			?.forceFirstResultViewportRepaint;
-		const value =
-			toolValue !== undefined ? toolValue : toolRenderers[this.#toolName]?.forceFirstResultViewportRepaint;
+		const value = toolValue !== undefined ? toolValue : this.#renderer?.forceFirstResultViewportRepaint;
 		if (typeof value === "function") return value(this.#args, this.#renderState);
 		return value === true;
 	}
@@ -1101,9 +1098,9 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 			const customFramed = this.#contentBox.children.some(isFramedBlockComponent);
 			this.#contentBox.setPaddingX(customFramed ? 0 : 1);
 			this.#contentBox.setBgFn(customFramed ? undefined : stateBgFn);
-		} else if (this.#toolName in toolRenderers) {
-			// Built-in tools with renderers
-			const renderer = toolRenderers[this.#toolName];
+		} else if (this.#renderer) {
+			// The active registry entry is a built-in tool with a rich renderer.
+			const renderer = this.#renderer;
 
 			// Clean up previous multi-file boxes
 			for (const box of this.#multiFileBoxes) {

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

@@ -286,12 +286,20 @@ class TreeList implements Component {
 
 			// Apply filter mode
 			let passesFilter = true;
-			// Entry types hidden in default view (settings/bookkeeping)
+			// Entry types hidden in default view (settings/bookkeeping). These carry
+			// no conversation content, so the tree only shows them in "all" mode.
 			const isSettingsEntry =
 				entry.type === "label" ||
 				entry.type === "custom" ||
 				entry.type === "model_change" ||
-				entry.type === "thinking_level_change";
+				entry.type === "thinking_level_change" ||
+				entry.type === "service_tier_change" ||
+				entry.type === "title_change" ||
+				entry.type === "credential_pin" ||
+				entry.type === "session_init" ||
+				entry.type === "ttsr_injection" ||
+				entry.type === "mode_change" ||
+				entry.type === "reset_boundary";
 
 			switch (this.#filterMode) {
 				case "user-only":
@@ -390,6 +398,34 @@ class TreeList implements Component {
 			case "label":
 				parts.push("label", entry.label ?? "");
 				break;
+			case "service_tier_change":
+				parts.push("service tier");
+				if (entry.serviceTier) {
+					const serviceTier = entry.serviceTier;
+					for (const family in serviceTier) {
+						const tier = serviceTier[family as keyof typeof serviceTier];
+						if (tier) parts.push(family, tier);
+					}
+				}
+				break;
+			case "title_change":
+				parts.push("title", entry.title);
+				break;
+			case "mode_change":
+				parts.push("mode", entry.mode);
+				break;
+			case "credential_pin":
+				parts.push("credential pin", entry.provider);
+				break;
+			case "ttsr_injection":
+				parts.push("ttsr injection", ...entry.injectedRules);
+				break;
+			case "reset_boundary":
+				parts.push("reset boundary");
+				break;
+			case "session_init":
+				parts.push("session init");
+				break;
 		}
 
 		return parts.join(" ");
@@ -658,8 +694,31 @@ class TreeList implements Component {
 			case "label":
 				result = theme.fg("dim", `[label: ${entry.label ?? "(cleared)"}]`);
 				break;
+			case "service_tier_change": {
+				// Per-family map, or null when the session went back to the default.
+				const tiers = entry.serviceTier
+					? Object.entries(entry.serviceTier)
+							.map(([family, tier]) => `${family}:${tier}`)
+							.join(" ")
+					: "(default)";
+				result = theme.fg("dim", `[service tier: ${tiers}]`);
+				break;
+			}
+			case "title_change":
+				result = theme.fg("dim", `[title: ${normalize(entry.title)}]`);
+				break;
+			case "mode_change":
+				result = theme.fg("dim", `[mode: ${entry.mode}]`);
+				break;
+			case "credential_pin":
+				result = theme.fg("dim", `[credential pin: ${entry.provider}]`);
+				break;
 			default:
-				result = "";
+				// Bookkeeping entries with nothing worth spelling out still get their
+				// type. A row that renders to the empty string is worse than a
+				// useless one: it draws as a bare bullet with no way to tell what it
+				// is or why the tree has a gap in it.
+				result = theme.fg("dim", `[${entry.type.replaceAll("_", " ")}]`);
 		}
 
 		return isSelected ? theme.bold(result) : result;

package/src/modes/controllers/command-controller.ts

@@ -11,7 +11,7 @@ import {
 	type UsageReport,
 } from "@oh-my-pi/pi-ai";
 import { Loader, Markdown, padding, Spacer, Text, visibleWidth } from "@oh-my-pi/pi-tui";
-import { formatDuration, Snowflake, sanitizeText } from "@oh-my-pi/pi-utils";
+import { formatDuration, logger, Snowflake, sanitizeText } from "@oh-my-pi/pi-utils";
 import { shouldEnableAppendOnlyContext } from "../../config/append-only-context-mode";
 import { type BashResult, isPersistentShellCdCommand } from "../../exec/bash-executor";
 import { type LoadedCustomShare, loadCustomShare } from "../../export/custom-share";
@@ -1436,9 +1436,15 @@ export class CommandController {
 			}
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			if (message === "Handoff cancelled" || (error instanceof Error && error.name === "AbortError")) {
+			// `session.handoff()` normalizes genuine cancellations to this exact message; a
+			// provider error (even one named AbortError) is re-thrown verbatim so it surfaces
+			// as a real failure instead of a false "cancelled".
+			if (message === "Handoff cancelled") {
 				this.ctx.showError("Handoff cancelled");
 			} else {
+				// Persist the real failure so it is debuggable after the transient
+				// TUI error clears (#7993).
+				logger.error("Handoff failed", { error: message });
 				this.ctx.showError(`Handoff failed: ${message}`);
 			}
 		} finally {

package/src/modes/controllers/event-controller.ts

@@ -1073,6 +1073,7 @@ export class EventController {
 						content.name,
 						renderArgs,
 						{
+							useBuiltInRenderer: this.ctx.viewSession.hasBuiltInTool(content.name),
 							snapshots: getFileSnapshotStore(this.ctx.viewSession),
 							clipboard: getEditClipboard(this.ctx.viewSession),
 							showImages: settings.get("terminal.showImages"),
@@ -1322,6 +1323,7 @@ export class EventController {
 				event.toolName,
 				event.args,
 				{
+					useBuiltInRenderer: this.ctx.viewSession.hasBuiltInTool(event.toolName),
 					snapshots: getFileSnapshotStore(this.ctx.viewSession),
 					clipboard: getEditClipboard(this.ctx.viewSession),
 					showImages: settings.get("terminal.showImages"),
@@ -1920,21 +1922,19 @@ export class EventController {
 			this.ctx.retryLoader = undefined;
 			this.ctx.statusContainer.disposeChildren();
 		}
-		if (event.success) {
-			let appliedRecovered = false;
-			for (const recovered of event.recoveredErrors ?? []) {
-				const component = this.#takeRetrySupersededAssistantComponent(recovered.persistenceKey);
-				if (!component) continue;
-				component.applyRetryRecovery(recovered.retryRecovery);
-				if (this.#pinnedErrorComponent === component) this.#pinnedErrorComponent = undefined;
-				appliedRecovered = true;
-			}
-			if (appliedRecovered || (event.recoveredErrors?.length ?? 0) > 0) {
-				this.ctx.clearPinnedError();
-			}
-			this.#clearRetrySupersededAssistantComponents();
-		} else {
-			this.#clearRetrySupersededAssistantComponents();
+		let appliedRetryUpdate = false;
+		for (const retryError of event.retryErrors ?? []) {
+			const component = this.#takeRetrySupersededAssistantComponent(retryError.persistenceKey);
+			if (!component) continue;
+			component.applyRetryRecovery(retryError.retryRecovery);
+			if (this.#pinnedErrorComponent === component) this.#pinnedErrorComponent = undefined;
+			appliedRetryUpdate = true;
+		}
+		if (appliedRetryUpdate || (event.retryErrors?.length ?? 0) > 0) {
+			this.ctx.clearPinnedError();
+		}
+		this.#clearRetrySupersededAssistantComponents();
+		if (!event.success) {
 			this.ctx.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError || "Unknown error"}`);
 		}
 		this.#ensureWorkingLoaderWhileStreaming();

package/src/modes/controllers/input-controller.ts

@@ -13,6 +13,7 @@ import { renderSegmentTrack } from "../../modes/components/segment-track";
 import { StrippedToolCallsPlaceholder } from "../../modes/components/stripped-tool-calls-placeholder";
 import { TinyTitleDownloadProgressComponent } from "../../modes/components/tiny-title-download-progress";
 import { ToolExecutionComponent } from "../../modes/components/tool-execution";
+import { TreeSelectorComponent } from "../../modes/components/tree-selector";
 import { expandEmoticons } from "../../modes/emoji-autocomplete";
 import { materializeImageReferenceLinks, shiftImageMarkers } from "../../modes/image-references";
 import { createPromptActionAutocompleteProvider } from "../../modes/prompt-action-autocomplete";
@@ -177,6 +178,7 @@ export class InputController {
 	#focusedPasteListenerInstalled = false;
 	#btwBranchListenerInstalled = false;
 	#btwCopyListenerInstalled = false;
+	#expandToolsListenerInstalled = false;
 	// Tap counter for the double-← gesture; reset whenever a quiet gap
 	// (>= LEFT_DOUBLE_TAP_MAX_GAP_MS) starts a fresh sequence. See
 	// #detectLeftDoubleTap.
@@ -278,6 +280,24 @@ export class InputController {
 				return { consume: true };
 			});
 		}
+		if (!this.#expandToolsListenerInstalled) {
+			this.#expandToolsListenerInstalled = true;
+			// `app.tools.expand` (Ctrl+O) toggles the transcript's tool-output
+			// preview. It must fire regardless of focus so a truncated edit stays
+			// expandable while an approval prompt / select dialog holds keyboard
+			// focus (#7837). Defers when the main transcript is not the active
+			// surface (a fullscreen/anchored overlay — agent hub, transcript
+			// viewer, log viewer, model picker) or when the focused component
+			// rebinds Ctrl+O for its own use (the tree selector's filter cycle).
+			this.ctx.ui.addInputListener(data => {
+				if (!this.ctx.keybindings.matches(data, "app.tools.expand")) return undefined;
+				if (this.ctx.ui.hasOverlay()) return undefined;
+				if (this.ctx.ui.getFocused() instanceof TreeSelectorComponent && matchesKey(data, "ctrl+o"))
+					return undefined;
+				this.toggleToolOutputExpansion();
+				return { consume: true };
+			});
+		}
 		this.ctx.editor.onEscape = () => {
 			// Side-channel panels are the topmost view. Esc dismisses them before
 			// touching loop mode, maintenance, or the underlying main turn.
@@ -456,8 +476,6 @@ export class InputController {
 			this.ctx.keybindings.getKeys("app.clipboard.copyPrompt"),
 		);
 		this.ctx.editor.onCopyPrompt = () => this.handleCopyPrompt();
-		this.ctx.editor.setActionKeys("app.tools.expand", this.ctx.keybindings.getKeys("app.tools.expand"));
-		this.ctx.editor.onExpandTools = () => this.toggleToolOutputExpansion();
 		this.ctx.editor.setActionKeys(
 			"app.tools.toggleVisibility",
 			this.ctx.keybindings.getKeys("app.tools.toggleVisibility"),

package/src/modes/controllers/selector-controller.ts

@@ -2026,6 +2026,7 @@ export class SelectorController {
 			remote: this.ctx.collabGuest?.hubRemote,
 			ui: this.ctx.ui,
 			getTool: name => this.ctx.session.getToolByName(name),
+			isBuiltInTool: name => this.ctx.session.hasBuiltInTool(name),
 			getMessageRenderer: type => this.ctx.session.extensionRunner?.getMessageRenderer(type),
 			cwd: this.ctx.sessionManager.getCwd(),
 			hideThinkingBlock: () => this.ctx.effectiveHideThinkingBlock,

package/src/modes/theme/color.ts

@@ -0,0 +1,133 @@
+import type { ColorMode, ColorValue } from "./schema";
+
+// ============================================================================
+// Color Utilities
+// ============================================================================
+
+export function detectColorMode(): ColorMode {
+	const colorterm = Bun.env.COLORTERM;
+	if (colorterm === "truecolor" || colorterm === "24bit") {
+		return "truecolor";
+	}
+	// Windows Terminal supports truecolor
+	if (Bun.env.WT_SESSION) {
+		return "truecolor";
+	}
+	const term = Bun.env.TERM || "";
+	// Only fall back to 256color for truly limited terminals
+	if (term === "dumb" || term === "" || term === "linux") {
+		return "256color";
+	}
+	// Assume truecolor for everything else - virtually all modern terminals support it
+	return "truecolor";
+}
+
+export function colorToAnsi(color: string, mode: ColorMode): string {
+	const format = mode === "truecolor" ? "ansi-16m" : "ansi-256";
+	const ansi = Bun.color(color, format);
+	if (ansi === null) {
+		throw new Error(`Invalid color value: ${color}`);
+	}
+	return ansi;
+}
+
+export function fgAnsi(color: string | number, mode: ColorMode): string {
+	if (color === "") return "\x1b[39m";
+	if (typeof color === "number") return `\x1b[38;5;${color}m`;
+	if (typeof color === "string") {
+		return colorToAnsi(color, mode);
+	}
+	throw new Error(`Invalid color value: ${color}`);
+}
+
+export function bgAnsi(color: string | number, mode: ColorMode): string {
+	if (color === "") return "\x1b[49m";
+	if (typeof color === "number") return `\x1b[48;5;${color}m`;
+	const ansi = colorToAnsi(color, mode);
+	return ansi.replace("\x1b[38;", "\x1b[48;");
+}
+
+export function resolveVarRefs(
+	value: ColorValue,
+	vars: Record<string, ColorValue>,
+	visited = new Set<string>(),
+): string | number {
+	if (typeof value === "number" || value === "" || value.startsWith("#")) {
+		return value;
+	}
+	if (visited.has(value)) {
+		throw new Error(`Circular variable reference detected: ${value}`);
+	}
+	if (!(value in vars)) {
+		throw new Error(`Variable reference not found: ${value}`);
+	}
+	visited.add(value);
+	return resolveVarRefs(vars[value], vars, visited);
+}
+
+export function resolveThemeColors<T extends Record<string, ColorValue>>(
+	colors: T,
+	vars: Record<string, ColorValue> = {},
+): Record<keyof T, string | number> {
+	const resolved: Record<string, string | number> = {};
+	for (const [key, value] of Object.entries(colors)) {
+		resolved[key] = resolveVarRefs(value, vars);
+	}
+	return resolved as Record<keyof T, string | number>;
+}
+
+/**
+ * Resolve a theme color value (hex string or 256-color index) to a CSS hex string.
+ * Empty string represents the default terminal color.
+ */
+export function resolveToHex(value: string | number, isLight: boolean): string {
+	if (typeof value === "number") return ansi256ToHex(value);
+	if (value === "") return isLight ? "#000000" : "#e5e5e7";
+	return value;
+}
+
+/**
+ * Convert a 256-color index to hex string.
+ * Indices 0-15: basic colors (approximate)
+ * Indices 16-231: 6x6x6 color cube
+ * Indices 232-255: grayscale ramp
+ */
+export function ansi256ToHex(index: number): string {
+	// Basic colors (0-15) - approximate common terminal values
+	const basicColors = [
+		"#000000",
+		"#800000",
+		"#008000",
+		"#808000",
+		"#000080",
+		"#800080",
+		"#008080",
+		"#c0c0c0",
+		"#808080",
+		"#ff0000",
+		"#00ff00",
+		"#ffff00",
+		"#0000ff",
+		"#ff00ff",
+		"#00ffff",
+		"#ffffff",
+	];
+	if (index < 16) {
+		return basicColors[index];
+	}
+
+	// Color cube (16-231): 6x6x6 = 216 colors
+	if (index < 232) {
+		const cubeIndex = index - 16;
+		const r = Math.floor(cubeIndex / 36);
+		const g = Math.floor((cubeIndex % 36) / 6);
+		const b = cubeIndex % 6;
+		const toHex = (n: number) => (n === 0 ? 0 : 55 + n * 40).toString(16).padStart(2, "0");
+		return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+	}
+
+	// Grayscale (232-255): 24 shades
+	const gray = 8 + (index - 232) * 10;
+	const grayHex = gray.toString(16).padStart(2, "0");
+	return `#${grayHex}${grayHex}${grayHex}`;
+}

package/src/modes/theme/loader.ts

@@ -0,0 +1,178 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type } from "@oh-my-pi/omptype";
+import { adjustHsv, getCustomThemesDir, isEnoent } from "@oh-my-pi/pi-utils";
+import { detectColorMode, resolveThemeColors } from "./color";
+import darkThemeJson from "./dark.json" with { type: "json" };
+import { defaultThemes } from "./defaults";
+import lightThemeJson from "./light.json" with { type: "json" };
+import { type ColorMode, type ThemeBg, type ThemeColor, type ThemeJson, themeJsonSchema } from "./schema";
+import { normalizeSpinnerFramesOverride, type SymbolPreset } from "./symbols";
+import { Theme } from "./theme-class";
+
+// ============================================================================
+// Theme Loading
+// ============================================================================
+
+const BUILTIN_THEMES: Record<string, ThemeJson> = {
+	dark: darkThemeJson as ThemeJson,
+	light: lightThemeJson as ThemeJson,
+	...(defaultThemes as Record<string, ThemeJson>),
+};
+
+export function getBuiltinThemes(): Record<string, ThemeJson> {
+	return BUILTIN_THEMES;
+}
+
+export async function getAvailableThemes(): Promise<string[]> {
+	const themes = new Set<string>(Object.keys(getBuiltinThemes()));
+	const customThemesDir = getCustomThemesDir();
+	try {
+		const files = await fs.promises.readdir(customThemesDir);
+		for (const file of files) {
+			if (file.endsWith(".json")) {
+				themes.add(file.slice(0, -5));
+			}
+		}
+	} catch {
+		// Directory doesn't exist or isn't readable
+	}
+	return Array.from(themes).sort();
+}
+
+export interface ThemeInfo {
+	name: string;
+	path: string | undefined;
+}
+
+export async function getAvailableThemesWithPaths(): Promise<ThemeInfo[]> {
+	const result: ThemeInfo[] = [];
+
+	// Built-in themes (embedded, no file path)
+	for (const name of Object.keys(getBuiltinThemes())) {
+		result.push({ name, path: undefined });
+	}
+
+	// Custom themes
+	const customThemesDir = getCustomThemesDir();
+	try {
+		const files = await fs.promises.readdir(customThemesDir);
+		for (const file of files) {
+			if (file.endsWith(".json")) {
+				const name = file.slice(0, -5);
+				if (!result.some(themeInfo => themeInfo.name === name)) {
+					result.push({ name, path: path.join(customThemesDir, file) });
+				}
+			}
+		}
+	} catch {
+		// Directory doesn't exist or isn't readable
+	}
+
+	return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function loadThemeJson(name: string): Promise<ThemeJson> {
+	const builtinThemes = getBuiltinThemes();
+	if (name in builtinThemes) {
+		return builtinThemes[name];
+	}
+	const customThemesDir = getCustomThemesDir();
+	const themePath = path.join(customThemesDir, `${name}.json`);
+	let content: string;
+	try {
+		content = await Bun.file(themePath).text();
+	} catch (err) {
+		if (isEnoent(err)) throw new Error(`Theme not found: ${name}`);
+		throw err;
+	}
+	let json: unknown;
+	try {
+		json = JSON.parse(content);
+	} catch (error) {
+		throw new Error(`Failed to parse theme ${name}: ${error}`);
+	}
+	let parsed: ThemeJson;
+	try {
+		parsed = themeJsonSchema(json) as ThemeJson;
+		if (parsed instanceof type.errors) {
+			throw new Error(parsed.summary);
+		}
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		// Extract color key information if available
+		const missingColorMatch = errorMessage.match(/missing keys: (.+)/i);
+		const missingColors: string[] = missingColorMatch ? missingColorMatch[1].split(",").map(s => s.trim()) : [];
+
+		let fullErrorMessage = `Invalid theme "${name}":\n`;
+		if (missingColors.length > 0) {
+			fullErrorMessage += `\nMissing required color tokens:\n`;
+			fullErrorMessage += missingColors.map(c => `  - ${c}`).join("\n");
+			fullErrorMessage += `\n\nPlease add these colors to your theme's "colors" object.`;
+			fullErrorMessage += `\nSee the built-in themes (dark.json, light.json) for reference values.`;
+		}
+		fullErrorMessage += `\n\nValidation error:\n  - ${errorMessage}`;
+
+		throw new Error(fullErrorMessage);
+	}
+	return parsed;
+}
+
+export interface CreateThemeOptions {
+	mode?: ColorMode;
+	symbolPresetOverride?: SymbolPreset;
+	colorBlindMode?: boolean;
+}
+
+/** HSV adjustment to shift green toward blue for colorblind mode (red-green colorblindness) */
+const COLORBLIND_ADJUSTMENT = { h: 60, s: 0.71 };
+
+export function createTheme(themeJson: ThemeJson, options: CreateThemeOptions = {}): Theme {
+	const { mode, symbolPresetOverride, colorBlindMode } = options;
+	const colorMode = mode ?? detectColorMode();
+	const resolvedColors = resolveThemeColors(themeJson.colors, themeJson.vars);
+
+	if (colorBlindMode) {
+		const added = resolvedColors.toolDiffAdded;
+		if (typeof added === "string" && added.startsWith("#")) {
+			resolvedColors.toolDiffAdded = adjustHsv(added, COLORBLIND_ADJUSTMENT);
+		}
+	}
+
+	const fgColors: Record<ThemeColor, string | number> = {} as Record<ThemeColor, string | number>;
+	const bgColors: Record<ThemeBg, string | number> = {} as Record<ThemeBg, string | number>;
+	const bgColorKeys: Set<string> = new Set([
+		"selectedBg",
+		"userMessageBg",
+		"customMessageBg",
+		"toolPendingBg",
+		"toolSuccessBg",
+		"toolErrorBg",
+		"statusLineBg",
+	]);
+	for (const [key, value] of Object.entries(resolvedColors)) {
+		if (bgColorKeys.has(key)) {
+			bgColors[key as ThemeBg] = value;
+		} else {
+			fgColors[key as ThemeColor] = value;
+		}
+	}
+	// Extract symbol configuration - settings override takes precedence over theme
+	const symbolPreset: SymbolPreset = symbolPresetOverride ?? themeJson.symbols?.preset ?? "unicode";
+	const symbolOverrides = themeJson.symbols?.overrides ?? {};
+	const spinnerFramesOverrides = normalizeSpinnerFramesOverride(themeJson.symbols?.spinnerFrames);
+	return new Theme(fgColors, bgColors, colorMode, symbolPreset, symbolOverrides, spinnerFramesOverrides);
+}
+
+export async function loadTheme(name: string, options: CreateThemeOptions = {}): Promise<Theme> {
+	const themeJson = await loadThemeJson(name);
+	return createTheme(themeJson, options);
+}
+
+export async function getThemeByName(name: string): Promise<Theme | undefined> {
+	try {
+		return await loadTheme(name);
+	} catch {
+		return undefined;
+	}
+}