pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/src/async-subagents/core/routing.ts

@@ -29,10 +29,23 @@ export interface RoutedSubagentTasks {
 	warnings: string[];
 }
 
+/** A recoverable selection error: the parent must correct the batch before spawn. */
+export class SubagentRoutingError extends Error {
+	constructor(reason: string, readonly taskIds: string[], readonly allowedTypes: string[]) {
+		super([
+			reason,
+			`Tasks requiring a valid role: ${taskIds.join(", ")}.`,
+			"Set an explicit valid subagentType for these tasks and retry; defaultType is not an error fallback.",
+			`Available types: ${allowedTypes.join(", ") || "(none configured)"}.`,
+		].join("\n"));
+		this.name = "SubagentRoutingError";
+	}
+}
+
 const ROUTER_SYSTEM_PROMPT = [
 	"You route Pi async sub-agent tasks to the best configured subagentType.",
 	"Choose exactly one allowed type for each task. Use the allowed type descriptions as the source of truth.",
-	"Prefer the most specific matching type over generic quick/deep. Use frontend for UI/UX implementation or visual frontend polish. For pure image inspection, use the lookup tool rather than subagents.",
+	"Prefer a matching project specialist. Otherwise use research for reading/review and evidence, implement for code/docs/tests/UI changes, verify for running checks, browser-qa for real-browser testing. Oracle is a deliberate strong second opinion, not the default for difficult work.",
 	"Return only strict JSON with this shape: {\"routes\":[{\"id\":\"task-id\",\"subagentType\":\"type\"}]}",
 	"Do not include markdown, comments, explanations, or unknown types.",
 ].join("\n");
@@ -43,31 +56,37 @@ export async function routeSubagentTasks(
 	ctx: SubagentRoutingContext,
 	signal?: AbortSignal,
 ): Promise<RoutedSubagentTasks> {
-	const fallbackTasks = () => tasks.map((task) => withFallbackType(task, config));
+	if (signal?.aborted) throw new Error("Aborted");
+	// Validate even the fast path: an explicit typo must not bypass profiles.
+	tasks = tasks.map((task) => hasText(task.subagentType) && task.subagentType !== task.subagentType.trim()
+		? { ...task, subagentType: task.subagentType.trim() }
+		: task);
+	const invalidTasks = tasks.filter((task) => hasText(task.subagentType)
+		&& !Object.prototype.hasOwnProperty.call(config.types, task.subagentType));
+	if (invalidTasks.length > 0) {
+		throw routingError(`Unknown subagentType: ${invalidTasks.map((task) => `${task.id}=${JSON.stringify(task.subagentType)}`).join(", ")}.`, invalidTasks, config);
+	}
 	const autoTasks = tasks.filter((task) => !hasText(task.subagentType));
 	if (autoTasks.length === 0) return { tasks, usedLlm: false, routes: {}, warnings: [] };
 
 	const routing = resolveSubagentRoutingConfig(config);
 	if (!routing.enabled) {
-		return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: ["LLM sub-agent routing is disabled; used defaultType fallback."] };
+		throw routingError("LLM sub-agent routing is disabled.", autoTasks, config);
 	}
-	if (signal?.aborted) throw new Error("Aborted");
+	if (Object.keys(config.types).length === 0) throw routingError("No sub-agent types are configured.", autoTasks, config);
 
 	try {
 		const candidates = await resolveRoutingModels(ctx, routing);
 		if (candidates.length === 0) {
-			const warning = `LLM sub-agent routing model unavailable (${routing.model}); used defaultType fallback.`;
-			notifyRoutingWarning(ctx, routing, warning);
-			return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
+			throw routingError(`LLM sub-agent routing model unavailable (${routing.model}).`, autoTasks, config);
 		}
 
 		const prompt = buildRoutingPrompt(autoTasks, config, routing);
 		const failures: string[] = [];
-		let response: RoutingResponse | undefined;
 		for (const candidate of candidates) {
 			if (signal?.aborted) throw new Error("Aborted");
 			try {
-				response = await completeWithModelRegistry(
+				const response = await completeWithModelRegistry(
 					ctx.modelRegistry,
 					candidate.model,
 					{
@@ -91,48 +110,38 @@ export async function routeSubagentTasks(
 						timeoutMs: routing.timeoutMs,
 					},
 				);
-				break;
+				if (signal?.aborted || response.stopReason === "aborted") throw new Error("Aborted");
+				if (response.stopReason === "error") throw new Error(response.errorMessage || "Router provider returned an error.");
+				const routes = parseRoutingResponse(responseText(response), config, autoTasks);
+				const missingTasks = autoTasks.filter((task) => !Object.prototype.hasOwnProperty.call(routes, task.id));
+				if (missingTasks.length > 0) {
+					throw new Error(`Returned ${Object.keys(routes).length}/${autoTasks.length} valid route(s); missing: ${missingTasks.map((task) => task.id).join(", ")}.`);
+				}
+				return {
+					usedLlm: true,
+					routes,
+					warnings: [],
+					tasks: tasks.map((task) => hasText(task.subagentType) ? task : { ...task, subagentType: routes[task.id] }),
+				};
 			} catch (error) {
 				if (signal?.aborted || isAbortError(error)) throw error;
 				failures.push(`${currentModelRef(candidate.model) ?? "(unknown)"}: ${errorMessage(error)}`);
 			}
 		}
 
-		if (!response) {
-			const warning = `LLM sub-agent routing failed (${failures.join("; ")}); used defaultType fallback.`;
-			notifyRoutingWarning(ctx, routing, warning);
-			return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
-		}
-
-		const routes = parseRoutingResponse(responseText(response), config, autoTasks);
-		const warnings = Object.keys(routes).length === autoTasks.length
-			? []
-			: [`LLM sub-agent routing returned ${Object.keys(routes).length}/${autoTasks.length} valid route(s); missing tasks used defaultType fallback.`];
-		for (const warning of warnings) notifyRoutingWarning(ctx, routing, warning);
-		return {
-			usedLlm: true,
-			routes,
-			warnings,
-			tasks: tasks.map((task) => applyRoute(task, config, routes)),
-		};
+		throw routingError(`LLM sub-agent routing failed (${failures.join("; ")}).`, autoTasks, config);
 	} catch (error) {
 		if (signal?.aborted || isAbortError(error)) throw error;
-		const warning = `LLM sub-agent routing failed (${errorMessage(error)}); used defaultType fallback.`;
-		notifyRoutingWarning(ctx, routing, warning);
-		return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
+		const failure = error instanceof SubagentRoutingError
+			? error
+			: routingError(`LLM sub-agent routing failed (${errorMessage(error)}).`, autoTasks, config);
+		notifyRoutingWarning(ctx, routing, failure.message);
+		throw failure;
 	}
 }
 
-function applyRoute(task: AgentTask, config: SubagentConfig, routes: Record<string, string>): AgentTask {
-	if (hasText(task.subagentType)) return task;
-	const fallback = withFallbackType(task, config);
-	return routes[task.id] ? { ...fallback, subagentType: routes[task.id] } : fallback;
-}
-
-function withFallbackType(task: AgentTask, config: SubagentConfig): AgentTask {
-	if (hasText(task.subagentType)) return task;
-	const fallback = defaultSubagentType(config);
-	return fallback ? { ...task, subagentType: fallback } : task;
+function routingError(reason: string, tasks: AgentTask[], config: SubagentConfig): SubagentRoutingError {
+	return new SubagentRoutingError(reason, tasks.map((task) => task.id), Object.keys(config.types).sort());
 }
 
 function buildRoutingPrompt(tasks: AgentTask[], config: SubagentConfig, routing: ResolvedSubagentRoutingConfig): string {
@@ -144,7 +153,7 @@ function buildRoutingPrompt(tasks: AgentTask[], config: SubagentConfig, routing:
 			return `- ${name}: ${profile.description ?? "No description; use only when the task explicitly names this type."}`;
 		}),
 		"",
-		`Default fallback if genuinely ambiguous: ${defaultSubagentType(config) ?? "none"}`,
+		`Preferred type only for genuinely ambiguous tasks: ${defaultSubagentType(config) ?? "none"}`,
 		"",
 		"Tasks:",
 		JSON.stringify(tasks.map((task) => ({
@@ -184,8 +193,6 @@ interface RoutingCandidate {
 	env?: Record<string, string>;
 }
 
-type RoutingResponse = Awaited<ReturnType<typeof completeWithModelRegistry>>;
-
 async function resolveModelRef(ctx: SubagentRoutingContext, modelRef: string): Promise<{
 	model: Model<Api>;
 	apiKey?: string;
@@ -212,7 +219,7 @@ function parseRoutingResponse(raw: string, config: SubagentConfig, tasks: AgentT
 	const parsed = parseJsonObject(raw);
 	const allowedTypes = new Map(Object.keys(config.types).map((name) => [name.toLowerCase(), name]));
 	const taskIds = new Set(tasks.map((task) => task.id));
-	const routes: Record<string, string> = {};
+	const routes: Record<string, string> = Object.create(null);
 	if (Array.isArray(parsed)) collectRouteArray(parsed, taskIds, allowedTypes, routes);
 	else if (typeof parsed === "string" && tasks.length === 1) addRoute(routes, taskIds, allowedTypes, tasks[0]!.id, parsed);
 	else if (isRecord(parsed)) {
@@ -289,7 +296,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function isAbortError(error: unknown): boolean {
-	return error instanceof Error && /abort/i.test(error.name || error.message);
+	return error instanceof Error && (/abort/i.test(error.name) || /^aborted$/i.test(error.message));
 }
 
 function errorMessage(error: unknown): string {

package/external/pi-tools-suite/src/async-subagents/core/spawn.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { selectSuitableToolsForModel } from "../../lib/tool-args.js";
+import { BROWSER_QA_RUNNER_ENV, getBrowserQaRunnerPath } from "./browser-qa.js";
 import { validateBasename } from "./paths.js";
 import { getPiInvocation } from "./pi-invocation.js";
 import { writePromptFile } from "./prompt.js";
@@ -88,7 +89,10 @@ export function spawnAgent(
 	// detached subprocesses do not depend on persisted local pi settings.
 	const persistSessions = shouldPersistSubagentSessions();
 	const sessionDir = persistSessions ? getAgentSessionDir(agentDir) : undefined;
-	const forwardedExtraArgs = options.isolatedSkills?.length ? withoutSkillArgs(extraArgs) : extraArgs;
+	// QA instructions now live in the agent prompt, but normal skill discovery
+	// must stay disabled even when no additional skill is configured.
+	const isolateSkills = task.subagentType === "browser-qa" || Boolean(options.isolatedSkills?.length);
+	const forwardedExtraArgs = isolateSkills ? withoutSkillArgs(extraArgs) : extraArgs;
 	if (sessionDir) fs.mkdirSync(sessionDir, { recursive: true });
 	const piArgs: string[] = ["--mode", "rpc"];
 	if (sessionDir) piArgs.push("--session-dir", sessionDir);
@@ -100,9 +104,9 @@ export function spawnAgent(
 	if (usesAntigravityModel(task.model, forwardedExtraArgs)) {
 		piArgs.push("--extension", getAntigravityAuthExtensionPath());
 	}
-	if (options.isolatedSkills && options.isolatedSkills.length > 0) {
+	if (isolateSkills) {
 		piArgs.push("--no-skills");
-		for (const skillPath of options.isolatedSkills) piArgs.push("--skill", skillPath);
+		for (const skillPath of options.isolatedSkills ?? []) piArgs.push("--skill", skillPath);
 	}
 	const envModel = task.model || getEnvModel();
 	if (envModel) piArgs.push("--model", envModel);
@@ -812,7 +816,11 @@ function subagentEnvironment(env: NodeJS.ProcessEnv, agentDir?: string): NodeJS.
 		]),
 	};
 	delete result[SUBAGENT_AGENT_DIR_ENV];
-	if (agentDir) result[SUBAGENT_AGENT_DIR_ENV] = fs.realpathSync(agentDir);
+	delete result[BROWSER_QA_RUNNER_ENV];
+	if (agentDir) {
+		result[SUBAGENT_AGENT_DIR_ENV] = fs.realpathSync(agentDir);
+		result[BROWSER_QA_RUNNER_ENV] = getBrowserQaRunnerPath();
+	}
 	return result;
 }
 

package/external/pi-tools-suite/src/async-subagents/index.ts

@@ -19,6 +19,7 @@ import {
 } from "./lib.js";
 import { buildUltraworkPrompt, isUltraworkEnvEnabled, registerCommands } from "./commands.js";
 import { agentStrategyPrompt, appendAgentStrategyPrompt } from "./core/agent-strategy.js";
+import { buildSubagentCatalogPrompt } from "./core/agent-catalog.js";
 import {
 	bridgeImageAttachments,
 	removeImageAttachmentBridgeState,
@@ -190,9 +191,13 @@ export default function (pi: ExtensionAPI) {
 			customPrompt: Boolean(event?.systemPromptOptions?.customPrompt),
 		});
 		const visionPrompt = visionCapabilityPrompt(event, ctx);
-		if (!strategyPrompt && !visionPrompt) return undefined;
+		const catalogPrompt = selectedToolsInclude(event, "subagents")
+			? subagentCatalogPrompt((ctx as { cwd?: string } | undefined)?.cwd ?? process.cwd())
+			: undefined;
+		if (!strategyPrompt && !visionPrompt && !catalogPrompt) return undefined;
 		let systemPrompt = event.systemPrompt ?? "";
 		if (strategyPrompt) systemPrompt = appendAgentStrategyPrompt(systemPrompt, strategyPrompt);
+		if (catalogPrompt) systemPrompt = appendAgentStrategyPrompt(systemPrompt, catalogPrompt);
 		if (visionPrompt) systemPrompt = appendAgentStrategyPrompt(systemPrompt, visionPrompt);
 		return { systemPrompt };
 	});
@@ -281,6 +286,11 @@ function safeLoadSubagentConfig(cwd: string) {
 	}
 }
 
+function subagentCatalogPrompt(cwd: string): string | undefined {
+	const config = safeLoadSubagentConfig(cwd);
+	return config ? buildSubagentCatalogPrompt(config) : undefined;
+}
+
 function startupSubagentPresetList(cwd = process.cwd()): string {
 	try {
 		const config = loadSubagentConfig(cwd);

package/external/pi-tools-suite/src/async-subagents/lib.ts

@@ -23,7 +23,7 @@ export {
 	DEFAULT_ROUTING_CONFIG,
 	existingSubagentConfigFiles,
 	getDefaultSubagentConfigPath,
-	getBrowserQaSkillPath,
+	getBuiltinSubagentDefinitionsDir,
 	getSubagentConfigInitTargetPath,
 	getSubagentConfigSamplePath,
 	isBlindModelRef,
@@ -34,8 +34,12 @@ export {
 	selectSubagentType,
 	shouldForceCurrentSubagentModel,
 } from "./core/config.js";
-export { routeSubagentTasks } from "./core/routing.js";
+export { routeSubagentTasks, SubagentRoutingError } from "./core/routing.js";
+export { BROWSER_QA_RUNNER_ENV, getBrowserQaRunnerPath } from "./core/browser-qa.js";
 export type { RoutedSubagentTasks, SubagentRoutingContext } from "./core/routing.js";
+export { agentDefinitionFiles, agentNameFromFilename, parseAgentMarkdown, projectAgentDefinitionFiles, readAgentDefinitionsFromDir, readProjectAgentDefinitions } from "./core/agents-dir.js";
+export type { AgentDefinition, ProjectAgentDefinition } from "./core/agents-dir.js";
+export { buildSubagentCatalogPrompt } from "./core/agent-catalog.js";
 export type { SubagentPresetSelectionState } from "./core/presets.js";
 export { getActiveSubagentPresetName, getSessionSubagentPresetOverride, getSubagentPresetSelectionPath, loadSubagentPresetSelection, saveSubagentPresetSelection, setActiveSubagentPreset, setSessionSubagentPresetOverride } from "./core/presets.js";
 export { isQuotaLimitCompletion, nextFallbackModel, rememberSessionModelFallback, resetSessionModelFallbacks, selectSessionModelWithFallback } from "./core/model-fallback.js";

package/external/pi-tools-suite/src/async-subagents/tools/spawn.ts

@@ -4,6 +4,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
 import { ASYNC_SUBAGENT_TOOL_DESCRIPTIONS } from "../../tool-descriptions.js";
+import { SUBAGENT_TYPE_SELECTION_GUIDANCE } from "../core/agent-catalog.js";
+import { selectAvailableAgentModels } from "../core/model-selection.js";
+import { SubagentModelSelectionError } from "../core/config.js";
 import type { AgentCompletionHandler, AgentTask, ResolvedAgentTaskConfig, Semaphore, SpawnedAgent } from "../lib.js";
 import {
 	createRunDir,
@@ -19,6 +22,7 @@ import {
 	resolveAgentTaskConfig,
 	resolveRunDir,
 	routeSubagentTasks,
+	SubagentRoutingError,
 	selectSessionModelWithFallback,
 	shouldForceCurrentSubagentModel,
 	spawnAgent,
@@ -172,7 +176,7 @@ const AgentTaskSchema = Type.Object({
 	id: Type.Optional(Type.String({ description: "Short identifier for this agent (used as directory name). If omitted, the spawn action assigns agent-1, agent-2, etc." })),
 	task: Type.String({ description: "Focused task description for the sub-agent" }),
 	scope: Type.Optional(Type.String({ description: "Relevant files/areas for this task" })),
-	subagentType: Type.Optional(Type.String({ description: "Logical sub-agent type/profile from config. Usually omit this so the router selects from the current config; set only for an explicit user-requested role, deterministic tests, or another concrete override." })),
+	subagentType: Type.Optional(Type.String({ description: SUBAGENT_TYPE_SELECTION_GUIDANCE })),
 	model: Type.Optional(Type.String({ description: "Explicit model override for this sub-agent. Prefer subagentType for reusable routing." })),
 	thinking: Type.Optional(Type.String({ description: "Per-agent thinking level override (off, minimal, low, medium, high, xhigh, max)." })),
 	promptAppend: Type.Optional(Type.String({ description: "Extra prompt instructions appended after the generated/type prompt." })),
@@ -209,10 +213,6 @@ export function registerSpawnTool(
 			const parentSession = typeof ctx.sessionManager?.getSessionFile === "function"
 				? ctx.sessionManager.getSessionFile()
 				: undefined;
-			const runDir = params.runDir
-				? resolveRunDir(ctx.cwd, params.runDir)
-				: createRunDir(ctx.cwd, params.slug);
-
 			const normalized = normalizeAgentTasks(params.tasks);
 			if (normalized.error) {
 				return {
@@ -240,21 +240,49 @@ export function registerSpawnTool(
 					isError: true,
 				};
 			}
-			const routed = await routeSubagentTasks(normalized.tasks ?? [], config, ctx as any, signal ?? undefined);
+			let routed: Awaited<ReturnType<typeof routeSubagentTasks>>;
+			try {
+				routed = await routeSubagentTasks(normalized.tasks ?? [], config, ctx as any, signal ?? undefined);
+			} catch (error) {
+				if (!(error instanceof SubagentRoutingError)) throw error;
+				return {
+					content: [{ type: "text", text: `No agents were launched. Correct the roles and resubmit the whole batch.\n${error.message}` }],
+					details: { error: "subagent_routing", taskIds: error.taskIds, allowedTypes: error.allowedTypes },
+					isError: true,
+				};
+			}
 			const timeoutMs = timeoutMsFromSeconds(params.timeoutSeconds);
 			const parentModel = currentModelRef((ctx as { model?: unknown }).model);
-			const resolvedTasks = routed.tasks.map((task) => applySessionModelFallback(
-				resolveAgentTaskConfig(task, config, {
-					preset: activePreset,
-					thinking: params.thinking,
-					extraArgs: Array.isArray(params.extraArgs) ? params.extraArgs : [],
-					forcedModel,
-					parentModel,
-					timeoutMs,
-				}),
-			));
+			let resolvedTasks: ResolvedAgentTaskConfig[];
+			try {
+				resolvedTasks = await Promise.all(routed.tasks.map(async (task) => applySessionModelFallback(await selectAvailableAgentModels(
+					resolveAgentTaskConfig(task, config, {
+						preset: activePreset,
+						thinking: params.thinking,
+						extraArgs: Array.isArray(params.extraArgs) ? params.extraArgs : [],
+						forcedModel,
+						parentModel,
+						timeoutMs,
+					}), config, ctx.modelRegistry, signal,
+				))));
+			} catch (error) {
+				if (!(error instanceof SubagentModelSelectionError)) throw error;
+				return { content: [{ type: "text", text: error.message }], details: { error: "subagent_model_selection" }, isError: true };
+			}
 			const tasks: AgentTask[] = resolvedTasks.map((resolved) => resolved.task);
-			const taskPreviews = toTaskPreviews(tasks);
+			if (signal?.aborted) throw new Error("Aborted");
+			if (signal?.aborted) throw new Error("Aborted");
+			// Resolve the entire batch before creating run state or launching children.
+			const runDir = params.runDir
+				? resolveRunDir(ctx.cwd, params.runDir)
+				: createRunDir(ctx.cwd, params.slug);
+			const taskPreviews = toTaskPreviews(tasks).map((preview, index) => {
+				// tasks[i] === resolvedTasks[i].task (positional), so the resolved
+				// profile's icon rides along into every preview consumer (tool render
+				// details, live-state events, and the desktop subagents panel).
+				const icon = resolvedTasks[index]?.profile?.icon;
+				return icon ? { ...preview, icon } : preview;
+			});
 			const results: { id: string; pid: number; agentDir: string }[] = [];
 			const maxConcurrent = config.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
 			const semaphore = getProjectSemaphore(ctx.cwd, maxConcurrent);
@@ -365,7 +393,7 @@ export function registerSpawnTool(
 
 		renderResult(result, opts, theme) {
 			const details = result.details as SubagentRunRenderDetails | undefined;
-			if (!details) {
+			if (!details || ("isError" in result && result.isError === true)) {
 				const fallback = result.content[0] && result.content[0].type === "text" ? result.content[0].text : "(no output)";
 				return new Text(fallback, 0, 0);
 			}

package/external/pi-tools-suite/src/async-subagents/tools/subagents.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
 import { asyncSubagentToolDescriptions } from "../../tool-descriptions.js";
+import { SUBAGENT_TYPE_SELECTION_GUIDANCE } from "../core/agent-catalog.js";
 import { hasIndexedProjectRoot } from "../../lib/project.js";
 import type { AgentCompletionHandler } from "../lib.js";
 import { DEFAULT_SPAWN_WATCH_SECONDS, INLINE_RENDERING } from "../constants.js";
@@ -19,7 +20,7 @@ const AgentTaskSchema = Type.Object({
 	id: Type.Optional(Type.String({ description: "Short identifier for this agent (used as directory name). If omitted, assigns agent-1, agent-2, etc." })),
 	task: Type.String({ description: "Focused task description for the sub-agent" }),
 	scope: Type.Optional(Type.String({ description: "Relevant files/areas for this task" })),
-	subagentType: Type.Optional(Type.String({ description: "Logical sub-agent type/profile from config. Usually omit this so the router selects from the current config; set only for an explicit user-requested role, deterministic tests, or another concrete override." })),
+	subagentType: Type.Optional(Type.String({ description: SUBAGENT_TYPE_SELECTION_GUIDANCE })),
 	model: Type.Optional(Type.String({ description: "Explicit model override for this sub-agent. Prefer subagentType for reusable routing." })),
 	thinking: Type.Optional(Type.String({ description: "Per-agent thinking level override (off, minimal, low, medium, high, xhigh, max)." })),
 	promptAppend: Type.Optional(Type.String({ description: "Extra prompt instructions appended after the generated/type prompt." })),
@@ -141,7 +142,7 @@ export function registerSubagentsTool(
 
 		renderResult(result, _opts, theme) {
 			const details = result.details as SubagentRunRenderDetails | undefined;
-			if (!details) return new Text(firstText(result), 0, 0);
+			if (!details || ("isError" in result && result.isError === true)) return new Text(firstText(result), 0, 0);
 			if (details.mode === "spawn" && Array.isArray(details.agents) && theme) {
 				return renderSubagentSpawnPrompts(details, _opts, theme);
 			}

package/external/pi-tools-suite/src/async-subagents/types.ts

@@ -14,6 +14,8 @@ export interface AgentTaskPreview {
 	task?: string;
 	scope?: string;
 	model?: string;
+	/** Agent icon name from the resolved subagentType profile; rendered by UIs. */
+	icon?: string;
 }
 
 export interface SubagentRunRenderDetails {