@ryan_nookpi/pi-extension-subagent 0.4.4 → 0.4.7

package/claude-stream-parser.ts

@@ -1,5 +1,6 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: Claude stream events are dynamic runtime data. */
 import type { Message } from "@earendil-works/pi-ai";
+import { classifySubagentFailure, countTextChars } from "./failure-telemetry.js";
 import { extractActivityPreviewFromTextDelta, extractThoughtText } from "./live-preview.js";
 import type { SingleResult } from "./types.js";
 
@@ -32,6 +33,7 @@ export interface ClaudeStreamState {
 	completedUsage?: ClaudeUsageTotals;
 	currentMessageUsage?: ClaudeUsageTotals;
 	lastTurnContextTokens?: number;
+	peakContextTokens?: number;
 	resultReceived: boolean;
 	resultEvent: any | undefined;
 	isError: boolean;
@@ -39,6 +41,8 @@ export interface ClaudeStreamState {
 	liveActivityPreview: string | undefined;
 	currentToolName: string | undefined;
 	currentToolInput: string;
+	lastToolName?: string;
+	lastToolOutputChars?: number;
 }
 
 export function createStreamState(): ClaudeStreamState {
@@ -56,6 +60,7 @@ export function createStreamState(): ClaudeStreamState {
 		completedUsage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 		currentMessageUsage: undefined,
 		lastTurnContextTokens: 0,
+		peakContextTokens: 0,
 		resultReceived: false,
 		resultEvent: undefined,
 		isError: false,
@@ -63,6 +68,8 @@ export function createStreamState(): ClaudeStreamState {
 		liveActivityPreview: undefined,
 		currentToolName: undefined,
 		currentToolInput: "",
+		lastToolName: undefined,
+		lastToolOutputChars: undefined,
 	};
 }
 
@@ -99,6 +106,7 @@ function syncUsageTotals(state: ClaudeStreamState): void {
 	state.usage.cacheRead = completed.cacheRead + (current?.cacheRead || 0);
 	state.usage.cacheWrite = completed.cacheWrite + (current?.cacheWrite || 0);
 	state.usage.contextTokens = current ? getContextTokensFromUsage(current) : (state.lastTurnContextTokens ?? 0);
+	state.peakContextTokens = Math.max(state.peakContextTokens ?? 0, state.usage.contextTokens);
 }
 
 function finalizeCurrentMessageUsage(state: ClaudeStreamState): void {
@@ -173,6 +181,7 @@ function processStreamEvent(state: ClaudeStreamState, ev: any): boolean {
 		} else if (block?.type === "tool_use") {
 			state.liveToolCalls++;
 			state.currentToolName = block.name;
+			state.lastToolName = block.name;
 			state.currentToolInput = "";
 			state.liveActivityPreview = `\u2192 ${block.name}`;
 		} else if (block?.type === "thinking") {
@@ -279,6 +288,10 @@ function processUserEvent(state: ClaudeStreamState, event: any): void {
 		}
 	}
 
+	if (contentBlocks.length > 0) {
+		state.lastToolOutputChars = countTextChars(contentBlocks);
+	}
+
 	const piMessage = {
 		role: "user" as const,
 		content: contentBlocks.length > 0 ? contentBlocks : [{ type: "text" as const, text: "" }],
@@ -315,6 +328,7 @@ function processResultEvent(state: ClaudeStreamState, event: any): void {
 				(state.lastTurnContextTokens ?? 0) > 0 ? (state.lastTurnContextTokens ?? 0) : getContextTokensFromUsage(totals),
 			turns: event.num_turns || state.usage.turns,
 		};
+		state.peakContextTokens = Math.max(state.peakContextTokens ?? 0, state.usage.contextTokens);
 	}
 }
 
@@ -372,6 +386,9 @@ export function stateToSingleResult(
 		model: state.model,
 		stopReason: state.stopReason,
 		errorMessage: state.errorMessage,
+		peakContextTokens: (state.peakContextTokens ?? 0) > 0 ? state.peakContextTokens : undefined,
+		lastToolName: state.lastToolName,
+		lastToolOutputChars: state.lastToolOutputChars,
 		step,
 		runtime: "claude",
 		claudeSessionId: state.sessionId,
@@ -396,5 +413,13 @@ export function stateToSingleResult(
 		result.errorMessage = `Permission denied for tools: ${names}`;
 	}
 
+	result.errorClass = classifySubagentFailure({
+		failed: exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted" || state.isError,
+		stopReason: result.stopReason,
+		exitCode,
+		errorMessage: result.errorMessage,
+		stderr,
+	});
+
 	return result;
 }

package/cli.ts

@@ -15,7 +15,7 @@ export type SubagentCliParseResult =
 	| { type: "help" }
 	| { type: "agents" }
 	| { type: "params"; params: Record<string, unknown> }
-	| { type: "error"; message: string };
+	| { type: "error"; message: string; showHelp?: boolean };
 
 export const SUBAGENT_CLI_HELP_TEXT = [
 	"Subagent CLI (LLM interface)",
@@ -451,7 +451,8 @@ export function parseSubagentToolCommand(
 	if ("error" in tokenized) {
 		return {
 			type: "error",
-			message: `❌ Syntax error: ${tokenized.error}\n\nCheck that quotes are balanced and the command is well-formed.\n\n✓ Correct: subagent run worker -- "task with spaces"`,
+			message: `❌ Syntax error: ${tokenized.error}\nClose the quote or wrap the task after \`--\` in matching quotes.`,
+			showHelp: false,
 		};
 	}
 

package/commands.ts

@@ -640,6 +640,10 @@ function restoreRunsFromSession(store: SubagentStore, ctx: any, pi?: ExtensionAP
 					contextMode: d.contextMode ?? existing?.contextMode,
 					usage: d.usage ?? existing?.usage,
 					model: d.model ?? existing?.model,
+					errorClass: d.errorClass ?? existing?.errorClass,
+					peakContextTokens: d.peakContextTokens ?? existing?.peakContextTokens,
+					lastToolName: d.lastToolName ?? existing?.lastToolName,
+					lastToolOutputChars: d.lastToolOutputChars ?? existing?.lastToolOutputChars,
 					thoughtText: d.thoughtText ?? d.progressText ?? existing?.thoughtText,
 					source: restoredSource,
 					runtime: d.runtime ?? existing?.runtime,
@@ -697,6 +701,10 @@ function restoreRunsFromSession(store: SubagentStore, ctx: any, pi?: ExtensionAP
 					contextMode: d.contextMode ?? existing?.contextMode,
 					usage: existing?.usage,
 					model: existing?.model,
+					errorClass: existing?.errorClass ?? "unknown",
+					peakContextTokens: existing?.peakContextTokens,
+					lastToolName: existing?.lastToolName,
+					lastToolOutputChars: existing?.lastToolOutputChars,
 					thoughtText: d.thoughtText ?? d.progressText ?? existing?.thoughtText,
 					source: restoredSource,
 					runtime: d.runtime ?? existing?.runtime,
@@ -1514,6 +1522,10 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 							usage: result.usage,
 							model: result.model,
 							source: result.agentSource,
+							errorClass: runState.errorClass,
+							peakContextTokens: runState.peakContextTokens,
+							lastToolName: runState.lastToolName,
+							lastToolOutputChars: runState.lastToolOutputChars,
 							thoughtText: runState.thoughtText,
 							retryCount: runState.retryCount,
 							status: runState.status,
@@ -1546,6 +1558,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 				} catch (error: any) {
 					if (runState.removed || store.disposed) return;
 					runState.status = "error";
+					runState.errorClass = "process_error";
 					runState.elapsedMs = Date.now() - runState.startedAt;
 					runState.lastLine =
 						runState.autoAbortReason ?? (error?.message ? String(error.message) : "Subagent execution failed");
@@ -1572,6 +1585,10 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 							elapsedMs: runState.elapsedMs,
 							lastActivityAt: runState.lastActivityAt,
 							error: runState.lastLine,
+							errorClass: runState.errorClass,
+							peakContextTokens: runState.peakContextTokens,
+							lastToolName: runState.lastToolName,
+							lastToolOutputChars: runState.lastToolOutputChars,
 							thoughtText: runState.thoughtText,
 							status: runState.status,
 							runtime: runState.runtime,

package/context-limits.ts

@@ -8,12 +8,12 @@
  *    partial findings instead of surfacing a raw provider error.
  *
  * 2. Proactive guard (④): some providers register a context window that is
- *    larger than the backend's actually-enforced limit. Notably `openai-codex`
- *    models report climbing usage.totalTokens every turn but hard-error around
- *    ~264k with "Your input exceeds the context window of this model" — and
- *    pi's native threshold-compaction never fires because the registry window
- *    sits above that ceiling. We watch reported tokens live and stop the run
- *    gracefully just below the real cliff, preserving findings.
+ *    unsafe for long internal tool loops. Some `openai-codex` models expose a
+ *    larger registry window than the backend actually enforces; Spark correctly
+ *    reports 128k but can still cross the threshold between tool turns because
+ *    pi checks native compaction only after the whole agent run. We watch
+ *    reported tokens live and stop just below each known cliff, preserving
+ *    findings.
  *
  * Overflow patterns are aligned with `@earendil-works/pi-ai`'s OVERFLOW_PATTERNS.
  */
@@ -73,6 +73,11 @@ export function isContextOverflowText(text: string | undefined | null): boolean
  * Only applied to the pi runtime; the claude runtime handles its own limits.
  */
 const GUARD_CEILINGS: Array<{ prefix: string; tokens: number }> = [
+	// GPT-5.3 Codex Spark has a hard 128k text-only window. Pi checks native
+	// threshold compaction only after the full agent run, not between internal
+	// tool-use turns, so stop at 115k before one large read/reasoning turn can
+	// cross the provider cliff.
+	{ prefix: "openai-codex/gpt-5.3-codex-spark", tokens: 115_000 },
 	// GPT-5.6 Codex models expose a 372k input window in pi. Keep the same 37k
 	// safety margin used by the older 272k-window models so long tool turns stop
 	// at 335k while partial findings can still be preserved. The family prefix
@@ -80,7 +85,7 @@ const GUARD_CEILINGS: Array<{ prefix: string; tokens: number }> = [
 	{ prefix: "openai-codex/gpt-5.6", tokens: 335_000 },
 	// Observed 272k-window codex models hard-error around ~264k with a raw
 	// provider error and no compaction. Cut at 235k to preserve the exploration
-	// so far. Unlisted codex models fall back to overflow detection/recovery (②).
+	// so far. Other unlisted models fall back to overflow detection/recovery (②).
 	{ prefix: "openai-codex/gpt-5.5", tokens: 235_000 },
 	// gpt-5.4 and gpt-5.4-mini both use a 272k window and are covered via startsWith.
 	{ prefix: "openai-codex/gpt-5.4", tokens: 235_000 },

package/failure-telemetry.ts

@@ -0,0 +1,66 @@
+import { isContextOverflowText } from "./context-limits.js";
+
+export type SubagentErrorClass =
+	| "context_overflow"
+	| "overloaded"
+	| "rate_limit"
+	| "tool_error"
+	| "aborted"
+	| "process_error"
+	| "unknown";
+
+export interface FailureTelemetryInput {
+	failed: boolean;
+	stopReason?: string;
+	exitCode?: number;
+	errorMessage?: string;
+	stderr?: string;
+	output?: string;
+}
+
+const OVERLOADED_PATTERNS = [
+	/servers? (?:are|is) currently overloaded/i,
+	/server overloaded/i,
+	/service unavailable/i,
+	/\b(?:http\s*)?5(?:03|29)\b/i,
+];
+
+const RATE_LIMIT_PATTERNS = [/rate limit/i, /too many requests/i, /\bhttp\s*429\b/i, /\b429\b.*request/i];
+
+const TOOL_ERROR_PATTERNS = [
+	/tool(?: execution| call)? (?:failed|error)/i,
+	/tool_execution_error/i,
+	/permission denied for tools?/i,
+	/invalid tool/i,
+];
+
+export function classifySubagentFailure(input: FailureTelemetryInput): SubagentErrorClass | undefined {
+	if (!input.failed) return undefined;
+	const text = [input.errorMessage, input.stderr, input.output].filter(Boolean).join("\n");
+
+	if (isContextOverflowText(text)) return "context_overflow";
+	if (OVERLOADED_PATTERNS.some((pattern) => pattern.test(text))) return "overloaded";
+	if (RATE_LIMIT_PATTERNS.some((pattern) => pattern.test(text))) return "rate_limit";
+	if (input.stopReason === "aborted") return "aborted";
+	if (TOOL_ERROR_PATTERNS.some((pattern) => pattern.test(text))) return "tool_error";
+	if ((input.exitCode ?? 0) !== 0) return "process_error";
+	return "unknown";
+}
+
+export function countTextChars(content: unknown): number {
+	if (typeof content === "string") return content.length;
+	if (!Array.isArray(content)) return 0;
+	let chars = 0;
+	for (const part of content) {
+		if (typeof part === "string") {
+			chars += part.length;
+			continue;
+		}
+		if (!part || typeof part !== "object") continue;
+		const record = part as Record<string, unknown>;
+		if (typeof record.text === "string") chars += record.text.length;
+		else if (typeof record.content === "string") chars += record.content.length;
+		else if (Array.isArray(record.content)) chars += countTextChars(record.content);
+	}
+	return chars;
+}

package/lifecycle.ts

@@ -74,6 +74,7 @@ export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, rea
 		if (run.status !== "running") continue;
 		const message = `Aborted because the parent pi session ${reason} is shutting down.`;
 		run.status = "error";
+		run.errorClass = "aborted";
 		run.elapsedMs = Date.now() - run.startedAt;
 		run.lastActivityAt = Date.now();
 		run.lastLine = message;
@@ -98,6 +99,10 @@ export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, rea
 						displayTask: run.displayTask,
 						status: "error",
 						error: message,
+						errorClass: run.errorClass,
+						peakContextTokens: run.peakContextTokens,
+						lastToolName: run.lastToolName,
+						lastToolOutputChars: run.lastToolOutputChars,
 						startedAt: run.startedAt,
 						elapsedMs: run.elapsedMs,
 						lastActivityAt: run.lastActivityAt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.4.4",
+  "version": "0.4.7",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,7 @@
     "diagnostics.ts",
     "display-task.ts",
     "escalation.ts",
+    "failure-telemetry.ts",
     "format.ts",
     "group-pending.ts",
     "index.ts",

package/runner.ts

@@ -24,6 +24,7 @@ import {
 	serializeDiagnosticValue,
 	toDiagnosticError,
 } from "./diagnostics.js";
+import { classifySubagentFailure, countTextChars } from "./failure-telemetry.js";
 import { formatToolCallPlain } from "./format.js";
 import {
 	extractActivityPreviewFromTextDelta,
@@ -871,6 +872,7 @@ async function runPiAgent(
 				if (event.type === "tool_execution_start") {
 					currentResult.liveToolCalls = (currentResult.liveToolCalls ?? 0) + 1;
 					if (typeof event.toolName === "string") {
+						currentResult.lastToolName = event.toolName;
 						currentResult.liveActivityPreview = formatPiToolExecutionPreview(event.toolName, event.args);
 					}
 					emitUpdate();
@@ -894,6 +896,7 @@ async function runPiAgent(
 							currentResult.usage.contextTokens = usage.totalTokens || 0;
 						}
 						peakContextTokens = Math.max(peakContextTokens, currentResult.usage.contextTokens);
+						currentResult.peakContextTokens = peakContextTokens;
 						// ④ Proactive context guard: stop just below the provider's real
 						// ceiling so heavy runs surface partial findings instead of a raw
 						// context-overflow error one turn later.
@@ -944,7 +947,10 @@ async function runPiAgent(
 				}
 
 				if (event.type === "tool_result_end" && event.message) {
-					currentResult.messages.push(event.message as Message);
+					const toolResultMessage = event.message as Message & { toolName?: string };
+					currentResult.messages.push(toolResultMessage);
+					if (typeof toolResultMessage.toolName === "string") currentResult.lastToolName = toolResultMessage.toolName;
+					currentResult.lastToolOutputChars = countTextChars(toolResultMessage.content);
 					emitUpdate();
 					if (sawAgentEnd) scheduleAgentEndForceResolve();
 					return;
@@ -1112,6 +1118,17 @@ async function runPiAgent(
 		});
 
 		currentResult.exitCode = exitCode;
+		if (peakContextTokens > 0) {
+			currentResult.peakContextTokens = Math.max(currentResult.peakContextTokens ?? 0, peakContextTokens);
+		}
+		currentResult.errorClass = classifySubagentFailure({
+			failed: exitCode !== 0 || currentResult.stopReason === "error" || currentResult.stopReason === "aborted",
+			stopReason: wasAborted ? "aborted" : currentResult.stopReason,
+			exitCode,
+			errorMessage: currentResult.errorMessage,
+			stderr: currentResult.stderr,
+			output: getFinalOutput(currentResult.messages),
+		});
 		if (wasAborted) throw new Error("Subagent was aborted");
 		return currentResult;
 	} finally {

package/store.ts

@@ -127,6 +127,10 @@ export function updateRunFromResult(state: CommandRunState, result: SingleResult
 	state.toolCalls = Math.max(collectToolCallCount(result.messages), result.liveToolCalls ?? 0);
 	state.usage = result.usage;
 	state.model = result.model ?? state.model;
+	state.errorClass = result.errorClass;
+	state.peakContextTokens = Math.max(state.peakContextTokens ?? 0, result.peakContextTokens ?? 0);
+	if (result.lastToolName) state.lastToolName = result.lastToolName;
+	if (result.lastToolOutputChars != null) state.lastToolOutputChars = result.lastToolOutputChars;
 	if (result.usage?.turns != null) state.turnCount = result.usage.turns;
 	if (result.thoughtText) state.thoughtText = result.thoughtText;
 

package/tool-execute.ts

@@ -31,6 +31,7 @@ import {
 	summarizeSubagentDisplayTask,
 } from "./display-task.js";
 import { ESCALATION_EXIT_CODE, readAndConsumeEscalation } from "./escalation.js";
+import { classifySubagentFailure, type SubagentErrorClass } from "./failure-telemetry.js";
 import {
 	formatContextUsageBar,
 	formatUsageStats,
@@ -97,6 +98,7 @@ type SessionDetailSummary = {
 type ResultFailureDiagnosis = {
 	failed: boolean;
 	reason?: string;
+	errorClass?: SubagentErrorClass;
 	/** Set when the failure was caused by exceeding the model context window. */
 	contextOverflow?: boolean;
 };
@@ -283,12 +285,26 @@ function parseSessionDetailSummary(sessionFile?: string): SessionDetailSummary {
 }
 
 export function diagnoseResultFailure(result: SingleResult): ResultFailureDiagnosis {
+	const finalOutput = getFinalOutput(result.messages).trim();
+	const failedByStatus = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+	const errorClass =
+		result.errorClass ??
+		classifySubagentFailure({
+			failed: failedByStatus,
+			stopReason: result.stopReason,
+			exitCode: result.exitCode,
+			errorMessage: result.errorMessage,
+			stderr: result.stderr,
+			output: finalOutput,
+		});
+
 	if (result.exitCode !== 0 || result.stopReason === "error") {
-		const overflowText = result.errorMessage || result.stderr || getFinalOutput(result.messages);
+		const overflowText = result.errorMessage || result.stderr || finalOutput;
 		if (isContextOverflowText(overflowText)) {
 			const turns = result.usage?.turns ?? 0;
 			return {
 				failed: true,
+				errorClass: "context_overflow",
 				contextOverflow: true,
 				reason:
 					`Subagent stopped after exceeding the model context window (${turns} turn(s) completed). ` +
@@ -296,12 +312,13 @@ export function diagnoseResultFailure(result: SingleResult): ResultFailureDiagno
 			};
 		}
 	}
-	if (result.exitCode !== 0) return { failed: true, reason: `Subagent process exited with code ${result.exitCode}.` };
+	if (result.exitCode !== 0)
+		return { failed: true, errorClass, reason: `Subagent process exited with code ${result.exitCode}.` };
 	if (result.stopReason === "error")
-		return { failed: true, reason: result.errorMessage || "Subagent reported stopReason=error." };
-	if (result.stopReason === "aborted") return { failed: true, reason: "Subagent execution was aborted." };
+		return { failed: true, errorClass, reason: result.errorMessage || "Subagent reported stopReason=error." };
+	if (result.stopReason === "aborted")
+		return { failed: true, errorClass: errorClass ?? "aborted", reason: "Subagent execution was aborted." };
 
-	const finalOutput = getFinalOutput(result.messages).trim();
 	const hasAssistantText = finalOutput.length > 0;
 	if (hasAssistantText) return { failed: false };
 
@@ -309,6 +326,7 @@ export function diagnoseResultFailure(result: SingleResult): ResultFailureDiagno
 	if (result.messages.length === 0) {
 		return {
 			failed: true,
+			errorClass: errorClass ?? "unknown",
 			reason:
 				"Subagent returned no messages (turn=0). " +
 				(stderr ? `stderr: ${stderr}` : "No stderr captured. Child process may have exited before producing output."),
@@ -317,6 +335,7 @@ export function diagnoseResultFailure(result: SingleResult): ResultFailureDiagno
 
 	return {
 		failed: true,
+		errorClass: errorClass ?? "unknown",
 		reason: `Subagent finished without assistant text output. ${stderr ? `stderr: ${stderr}` : "No stderr captured."}`,
 	};
 }
@@ -471,6 +490,10 @@ function buildRunCompletionMessage(finalized: FinalizedRun, options?: { display?
 			usage: result?.usage,
 			model: result?.model,
 			source: result?.agentSource,
+			errorClass: runState.errorClass,
+			peakContextTokens: runState.peakContextTokens,
+			lastToolName: runState.lastToolName,
+			lastToolOutputChars: runState.lastToolOutputChars,
 			thoughtText: runState.thoughtText,
 			status: runState.status,
 			batchId: runState.batchId,
@@ -506,6 +529,10 @@ function buildEscalationMessage(runState: CommandRunState, escalationMessage: st
 			exitCode: result.exitCode,
 			usage: result.usage,
 			model: result.model,
+			errorClass: runState.errorClass,
+			peakContextTokens: runState.peakContextTokens,
+			lastToolName: runState.lastToolName,
+			lastToolOutputChars: runState.lastToolOutputChars,
 			batchId: runState.batchId,
 			pipelineId: runState.pipelineId,
 			pipelineStepIndex: runState.pipelineStepIndex,
@@ -549,6 +576,7 @@ function finalizeRunState(runState: CommandRunState, result: SingleResult): Fina
 	const failure = diagnoseResultFailure(result);
 	const isError = failure.failed;
 	runState.status = isError ? "error" : "done";
+	runState.errorClass = failure.errorClass;
 	runState.elapsedMs = Date.now() - runState.startedAt;
 	let rawOutput: string;
 	if (isError && failure.contextOverflow) {
@@ -653,7 +681,19 @@ function toLaunchSummary(
 function buildRunAnalyticsSummary(
 	runState: Pick<
 		CommandRunState,
-		"id" | "agent" | "status" | "elapsedMs" | "model" | "batchId" | "pipelineId" | "pipelineStepIndex" | "runtime"
+		| "id"
+		| "agent"
+		| "status"
+		| "elapsedMs"
+		| "model"
+		| "batchId"
+		| "pipelineId"
+		| "pipelineStepIndex"
+		| "runtime"
+		| "errorClass"
+		| "peakContextTokens"
+		| "lastToolName"
+		| "lastToolOutputChars"
 	>,
 ): Record<string, unknown> {
 	return {
@@ -662,6 +702,10 @@ function buildRunAnalyticsSummary(
 		status: runState.status,
 		elapsedMs: runState.elapsedMs,
 		model: runState.model,
+		errorClass: runState.errorClass,
+		peakContextTokens: runState.peakContextTokens,
+		lastToolName: runState.lastToolName,
+		lastToolOutputChars: runState.lastToolOutputChars,
 		batchId: runState.batchId,
 		pipelineId: runState.pipelineId,
 		stepIndex: runState.pipelineStepIndex,
@@ -683,6 +727,7 @@ function isInteractiveTuiContext(ctx: SubagentToolExecuteContext): boolean {
 
 function finalizeRunError(runState: CommandRunState, error: unknown): FinalizedRun {
 	runState.status = "error";
+	runState.errorClass = "process_error";
 	runState.elapsedMs = Date.now() - runState.startedAt;
 	runState.lastLine =
 		runState.autoAbortReason ?? (error instanceof Error ? error.message : "Subagent execution failed");
@@ -729,8 +774,13 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 		}
 
 		if (parsedCommand.type === "error") {
+			const errorText =
+				parsedCommand.showHelp === false
+					? parsedCommand.message
+					: `${parsedCommand.message}\n\n${SUBAGENT_CLI_HELP_TEXT}`;
+
 			return {
-				content: [{ type: "text", text: `${parsedCommand.message}\n\n${SUBAGENT_CLI_HELP_TEXT}` }],
+				content: [{ type: "text", text: errorText }],
 				details: createEmptyDetails("single", false, null),
 				isError: true,
 			};

package/types.ts

@@ -6,6 +6,7 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import type { AgentConfig, AgentRuntime } from "./agents.js";
+import type { SubagentErrorClass } from "./failure-telemetry.js";
 
 // ─── Interfaces ──────────────────────────────────────────────────────────────
 
@@ -30,6 +31,10 @@ export interface SingleResult {
 	model?: string;
 	stopReason?: string;
 	errorMessage?: string;
+	errorClass?: SubagentErrorClass;
+	peakContextTokens?: number;
+	lastToolName?: string;
+	lastToolOutputChars?: number;
 	step?: number;
 	liveText?: string;
 	liveThinking?: string;
@@ -91,6 +96,14 @@ export interface CommandRunState {
 	retryCount?: number;
 	/** Last transient failure reason that triggered an auto-retry. */
 	lastRetryReason?: string;
+	/** Normalized terminal failure category for analytics. */
+	errorClass?: SubagentErrorClass;
+	/** Highest reported context usage observed during the run. */
+	peakContextTokens?: number;
+	/** Most recently completed/started tool name. */
+	lastToolName?: string;
+	/** Text character count of the most recent tool result. */
+	lastToolOutputChars?: number;
 	/** Hang detector reason preserved until the normal finalizer emits the sole completion. */
 	autoAbortReason?: string;
 	runtime?: AgentRuntime;

package/widget.ts

@@ -119,9 +119,10 @@ function getContextShort(run: CommandRunState, ctx: WidgetRenderCtx, theme: Widg
 	if (usedContextPercent === undefined) return "";
 	const contextBar = formatCompactContextBar(usedContextPercent);
 	if (!contextBar) return "";
+	const contextLabel = `${contextBar} ${usedContextPercent}%`;
 	const contextBarColor =
 		remainingContextPercent !== undefined ? getContextBarColorByRemaining(remainingContextPercent) : undefined;
-	return contextBarColor ? theme.fg(contextBarColor, contextBar) : theme.fg("dim", contextBar);
+	return contextBarColor ? theme.fg(contextBarColor, contextLabel) : theme.fg("dim", contextLabel);
 }
 
 function buildPrimaryLabelText(run: CommandRunState): string {