pi-subagents-j0k3r 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -2,9 +2,18 @@
 
 ## Unreleased
 
+### Added
+- Added opt-in render diagnostics with bounded JSONL logging for subagent UI and completion rendering.
+- Added structured, versioned subagent execution errors covering provider failures, context limits, timeouts, stalls, cancellations, fallback attempts, persistence, tool responses, and history UI.
+
 ### Fixed
 - Fixed manual task-mode background handoff so it frees the chat only when the user explicitly sends the running subagent to background.
 - Fixed background completion delivery so notifications arrive while the main agent continues working without triggering an extra follow-up turn.
+- Increased the default task timeout to 20 minutes and inactivity timeout to 4 minutes.
+- Preserved machine-readable failure details while retaining backward-compatible human-readable error messages.
+
+### Documentation
+- Added rendering investigation and solution notes covering terminal synchronization, viewport stability, and renderer trade-offs.
 
 ## 1.1.0 - 2026-06-27
 

package/README.md

@@ -139,8 +139,8 @@ Example:
 {
   "default_model": "anthropic/claude-sonnet-4-5",
   "default_effort": "medium",
-  "timeout_ms": 600000,
-  "stall_timeout_ms": 120000,
+  "timeout_ms": 1200000,
+  "stall_timeout_ms": 240000,
   "max_concurrency": 5,
   "session_resources": "lean",
   "history_panel_shortcut": "ctrl+,",
@@ -173,8 +173,8 @@ Example:
 | `default_model` | current orchestrator model | Fallback model for all subagents. Format: `provider/model-id`. |
 | `default_effort` | current orchestrator effort | Fallback thinking effort. Also accepts `default_thinking_level` or `thinkingLevel`. |
 | `model_profiles` | `{}` | Per-agent model/effort overrides scoped to matching definitions. Project-local profiles apply to project-local definitions; global profiles apply to global definitions. |
-| `timeout_ms` | `600000` | Total timeout per subagent task. |
-| `stall_timeout_ms` | `120000` | Inactivity timeout for a subagent session. |
+| `timeout_ms` | `1200000` | Total timeout per subagent task (20 minutes). |
+| `stall_timeout_ms` | `240000` | Inactivity timeout for a subagent session (4 minutes). |
 | `max_concurrency` | `5` | Max concurrent subagent tasks per cwd/config pair. |
 | `session_resources` | `lean` | SDK resource loading mode. `lean` uses the subagent markdown body as the nested session system prompt, skips skills, prompt templates, themes, and context files, and loads extensions in tools-only/safety-hook mode so allowlisted extension tools remain available without startup context injection. Use explicit `full` only when a subagent intentionally needs the full Pi resource set. Also accepts camelCase `sessionResources`. |
 | `history_panel_shortcut` | `ctrl+,` | OpenCode-mode shortcut used to open the subagents history/detail panel. Accepts `ctrl+<letter>` or `ctrl+,` and also accepts camelCase `historyPanelShortcut`. |

package/index.ts

@@ -3,6 +3,8 @@ import { readSubagentsConfig, subagentSourceWarnings } from './src/config.js';
 import { registerSubagentTools, triggerClaudeBackgroundHandoff } from './src/tools.js';
 import { runSubagentModelsCommand } from './src/model-profiles-ui.js';
 import { SubagentsHistoryPanel } from './src/ui.js';
+import { createSubagentsRenderLogger } from './src/render-debug.js';
+import { safeErrorMetadataDetails } from './src/error-metadata.js';
 import type { SubagentTask } from './src/types.js';
 
 type ClaudeBackgroundWidgetEntry = {
@@ -119,6 +121,32 @@ function setMouseTracking(tui: any, enabled: boolean): void {
   write(enabled ? '\u001b[?1000h\u001b[?1006h' : '\u001b[?1006l\u001b[?1000l');
 }
 
+function subagentsPanelMouseWheelDelta(data: string): -1 | 1 | undefined {
+  const sgr = data.match(/^\u001b\[<(\d+);\d+;\d+M$/);
+  const urxvt = data.match(/^\u001b\[(\d+);\d+;\d+M$/);
+  const button = sgr || urxvt ? Number((sgr ?? urxvt)![1]) : data.startsWith('\u001b[M') && data.length >= 6 ? data.charCodeAt(3) - 32 : undefined;
+  if (button === undefined || !Number.isFinite(button) || (button & 64) === 0) return undefined;
+  return (button & 1) === 0 ? -1 : 1;
+}
+
+function classifySubagentsPanelInput(data: string, matchesPanelKey: (data: string, key: string) => boolean): { category: string; action: string } {
+  if (matchesPanelKey(data, 'escape') || matchesPanelKey(data, 'ctrl+c') || matchesPanelKey(data, 'q')) return { category: 'lifecycle', action: 'close' };
+  if (matchesPanelKey(data, 'ctrl+o') || data === '\u000f') return { category: 'display', action: 'toggle_expand' };
+  if (matchesPanelKey(data, 'detailCancel')) return { category: 'task', action: 'cancel_selected' };
+  const wheel = subagentsPanelMouseWheelDelta(data);
+  if (wheel === -1) return { category: 'scroll', action: 'up' };
+  if (wheel === 1) return { category: 'scroll', action: 'down' };
+  if (matchesPanelKey(data, 'right')) return { category: 'navigation', action: 'right' };
+  if (matchesPanelKey(data, 'left')) return { category: 'navigation', action: 'left' };
+  if (matchesPanelKey(data, 'down')) return { category: 'navigation', action: 'down' };
+  if (matchesPanelKey(data, 'up')) return { category: 'navigation', action: 'up' };
+  if (matchesPanelKey(data, 'pageDown')) return { category: 'scroll', action: 'page_down' };
+  if (matchesPanelKey(data, 'pageUp')) return { category: 'scroll', action: 'page_up' };
+  if (matchesPanelKey(data, 'home')) return { category: 'scroll', action: 'home' };
+  if (matchesPanelKey(data, 'end')) return { category: 'scroll', action: 'end' };
+  return { category: 'other', action: 'unmatched' };
+}
+
 function toolFromRegistry(registry: any, name: string): unknown {
   if (!registry) return undefined;
   if (typeof registry.get === 'function') return registry.get(name);
@@ -290,6 +318,11 @@ export function completionMessage(task: any): string {
   ].join('\n');
 }
 
+function safeCompletionErrorMetadata(task: any): Record<string, unknown> | undefined {
+  if (!task?.error_metadata) return undefined;
+  return safeErrorMetadataDetails(task.error_metadata as any);
+}
+
 export function sendSubagentCompletionMessage(pi: any, task: any): void {
   pi.sendMessage?.({
     customType: 'subagent-completion',
@@ -307,6 +340,7 @@ export function sendSubagentCompletionMessage(pi: any, task: any): void {
         usage: task.usage,
         result: task.result,
         error: task.error,
+        error_metadata: safeCompletionErrorMetadata(task),
       },
     },
   }, {
@@ -438,12 +472,16 @@ export default function subagentsExtension(pi: any): void {
       await ctx.ui.custom(
       (tui: any, theme: any, _keybindings: any, done: () => void) => {
         setMouseTracking(tui, true);
+        const config = readSubagentsConfig(cwd);
+        const renderLogger = createSubagentsRenderLogger({ cwd, sessionId, config: config.render_debug });
+        let nextRenderReason = 'initial';
+        let renderCycle = 0;
         const close = () => {
           if (refresh) clearInterval(refresh);
+          renderLogger.log({ event: 'panel_disposed' });
           setMouseTracking(tui, false);
           done();
         };
-        const config = readSubagentsConfig(cwd);
         const baseMatchesKey = createSubagentsPanelKeyMatcher(_keybindings);
         const panel = new SubagentsHistoryPanel(
           () => manager.listSessionTasks(cwd, sessionId).slice(0, 100),
@@ -475,13 +513,59 @@ export default function subagentsExtension(pi: any): void {
           (id: string) => manager.cancel(id, 'cancelled from subagents detail view'),
           config.detail_cancel_shortcut ?? 'x',
         );
+        renderLogger.log({ event: 'panel_created' });
+        renderLogger.log({ event: 'render_requested', reason: nextRenderReason });
         activePanelCancelSelected = () => panel.cancelSelectedActiveTask();
-        activePanelRequestRender = () => tui.requestRender?.();
-        refresh = setInterval(() => tui.requestRender?.(), 1000);
+        activePanelRequestRender = () => {
+          nextRenderReason = 'external';
+          renderLogger.log({ event: 'render_requested', reason: nextRenderReason });
+          tui.requestRender?.();
+        };
+        refresh = setInterval(() => {
+          nextRenderReason = 'interval';
+          renderLogger.log({ event: 'render_requested', reason: nextRenderReason });
+          tui.requestRender?.();
+        }, 1000);
         return {
-          render: (width: number) => panel.render(width),
+          render: (width: number) => {
+            const reason = nextRenderReason;
+            const currentRenderCycle = ++renderCycle;
+            renderLogger.log({
+              event: 'render_started',
+              reason,
+              renderCycle: currentRenderCycle,
+              dimensions: {
+                stdoutColumns: process.stdout.columns,
+                stdoutRows: process.stdout.rows,
+                renderWidth: width,
+              },
+            });
+            const startedAt = process.hrtime.bigint();
+            const lines = panel.render(width);
+            const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+            renderLogger.log({
+              event: 'render_completed',
+              reason,
+              renderCycle: currentRenderCycle,
+              durationMs,
+              dimensions: {
+                stdoutColumns: process.stdout.columns,
+                stdoutRows: process.stdout.rows,
+                renderWidth: width,
+              },
+              state: panel.getRenderDebugState(),
+            });
+            nextRenderReason = 'external';
+            return lines;
+          },
           invalidate: () => panel.invalidate(),
-          handleInput: (data: string) => { panel.handleInput(data); tui.requestRender?.(); },
+          handleInput: (data: string) => {
+            renderLogger.log({ event: 'input_received', input: classifySubagentsPanelInput(data, baseMatchesKey) });
+            nextRenderReason = 'input';
+            renderLogger.log({ event: 'render_requested', reason: nextRenderReason });
+            panel.handleInput(data);
+            tui.requestRender?.();
+          },
         };
       },
       undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-j0k3r",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Installable Pi package that adds markdown-defined subagents, delegated task tools, history, and model profiles.",
   "type": "module",
   "license": "MIT",

package/skills/subagents-configuration/SKILL.md

@@ -120,8 +120,8 @@ Recommended `subagents.json` starter:
 ```json
 {
   "mode": "opencode",
-  "timeout_ms": 600000,
-  "stall_timeout_ms": 120000,
+  "timeout_ms": 1200000,
+  "stall_timeout_ms": 240000,
   "max_concurrency": 5,
   "debug": false,
   "session_resources": "lean",

package/src/config.ts

@@ -5,11 +5,12 @@ import type { ModelRef, SubagentDefinition, SubagentDefinitionScope, SubagentMod
 
 const DEFAULT_TOOLS = ['read', 'memory_context', 'memory_search', 'memory_recall', 'memory_get'];
 const DEFAULT_MAX_CONCURRENCY = 5;
-const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
-const DEFAULT_STALL_TIMEOUT_MS = 2 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 20 * 60 * 1000;
+const DEFAULT_STALL_TIMEOUT_MS = 4 * 60 * 1000;
 const DEFAULT_BACKGROUND_HANDOFF_SHORTCUT = 'ctrl+h';
 const DEFAULT_HISTORY_PANEL_SHORTCUT = 'ctrl+,';
 const DEFAULT_DETAIL_CANCEL_SHORTCUT = 'x';
+const DEFAULT_RENDER_DEBUG_LOG_PATH = path.join(os.tmpdir(), 'pi-subagents-render.jsonl');
 const BLOCKED_SUBAGENT_TOOLS = new Set([
   'subagent_run',
   'subagent_list_agents',
@@ -141,6 +142,23 @@ function parseBoolean(value: any, fallback = false): boolean {
   return fallback;
 }
 
+function parseRenderDebugPartial(value: unknown): { enabled?: boolean; path?: string } {
+  if (!isPlainObject(value)) return {};
+  const partial: { enabled?: boolean; path?: string } = {};
+  if (value.enabled === true) partial.enabled = true;
+  else if (value.enabled === false) partial.enabled = false;
+  if (typeof value.path === 'string' && value.path.trim()) partial.path = value.path.trim();
+  return partial;
+}
+
+function parseRenderDebugConfig(globalRaw: Record<string, unknown>, projectRaw: Record<string, unknown>): SubagentsConfig['render_debug'] {
+  const globalPartial = parseRenderDebugPartial(globalRaw.render_debug ?? globalRaw.renderDebug);
+  const projectPartial = parseRenderDebugPartial(projectRaw.render_debug ?? projectRaw.renderDebug);
+  const merged = { ...globalPartial, ...projectPartial };
+  if (merged.enabled !== true) return undefined;
+  return { enabled: true, path: merged.path ?? DEFAULT_RENDER_DEBUG_LOG_PATH };
+}
+
 function parseModelProfile(value: unknown): SubagentModelProfile | undefined {
   if (!isPlainObject(value)) return undefined;
   const profile: SubagentModelProfile = {};
@@ -196,6 +214,7 @@ export function readSubagentsConfig(cwd: string): SubagentsConfig {
     history_panel_shortcut: parseCtrlShortcut(raw.history_panel_shortcut ?? raw.historyPanelShortcut, DEFAULT_HISTORY_PANEL_SHORTCUT),
     detail_cancel_shortcut: parseDetailShortcut(raw.detail_cancel_shortcut ?? raw.detailCancelShortcut),
     debug: parseBoolean(raw.debug, false),
+    render_debug: parseRenderDebugConfig(globalRaw, projectRaw),
   };
 }
 

package/src/error-metadata.ts

@@ -0,0 +1,336 @@
+import { sanitizeInteractionTransportText } from './interaction-channel.js';
+import type { SubagentErrorAttemptRole, SubagentErrorCategory, SubagentErrorMetadata, SubagentErrorPhase, UsageStats } from './types.js';
+
+const MESSAGE_LIMIT = 1024;
+const CODE_LIMIT = 128;
+const SOURCE_LIMIT = 256;
+const LAST_ACTIVITY_LIMIT = 512;
+const DETAILS_KEY_LIMIT = 64;
+const DETAILS_VALUE_LIMIT = 512;
+const DETAILS_LIMIT = 16;
+const ATTEMPTS_LIMIT = 2;
+const CAUSE_DEPTH_LIMIT = 2;
+
+const RETRYABLE_DEFAULTS: Record<SubagentErrorCategory, boolean> = {
+  total_timeout: false,
+  stall_timeout: false,
+  cancelled: false,
+  empty_response_no_tools: false,
+  empty_response_after_tools: false,
+  context_overflow: false,
+  provider_api_error: true,
+  provider_auth_error: false,
+  provider_rate_limit: true,
+  provider_network_error: true,
+  tool_failure: false,
+  fallback_failed: false,
+  unknown_fallback: false,
+  malformed_thrown_value: false,
+  serialization_failure: false,
+  unknown: false,
+};
+
+const CATEGORY_SET = new Set<SubagentErrorCategory>(Object.keys(RETRYABLE_DEFAULTS) as SubagentErrorCategory[]);
+const PHASE_SET = new Set<SubagentErrorPhase>(['runner_invoke', 'runner_session', 'assistant_final', 'tool_execution', 'manager', 'user', 'serializer']);
+const ROLE_SET = new Set<SubagentErrorAttemptRole>(['primary', 'fallback']);
+
+function limitCodePoints(value: string | undefined, limit: number): string | undefined {
+  if (value === undefined) return undefined;
+  const chars = Array.from(value);
+  return chars.length > limit ? `${chars.slice(0, Math.max(0, limit - 1)).join('')}…` : value;
+}
+
+function asciiSafe(value: string | undefined, limit: number): string | undefined {
+  if (!value) return undefined;
+  const bounded = limitCodePoints(value.replace(/[^\x20-\x7E]+/g, '_'), limit);
+  return bounded || undefined;
+}
+
+function redactText(value: string | undefined, limit: number): string | undefined {
+  if (!value) return undefined;
+  let text = sanitizeInteractionTransportText(String(value));
+  text = text
+    .replace(/authorization\s*:\s*bearer\s+[A-Za-z0-9._\-]+/gi, 'Authorization: [redacted]')
+    .replace(/bearer\s+[A-Za-z0-9._\-]+/gi, 'Bearer [redacted]')
+    .replace(/\b(sk|pk|rk)-[A-Za-z0-9._\-]+\b/g, '[redacted]')
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[redacted]')
+    .replace(/(?:^|\s)(?:\/[A-Za-z0-9._-]+)+/g, (match) => match.replace(/\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*/g, '[redacted]'))
+    .replace(/\b(?:prompt|system prompt|user prompt|prompt text)\s*:[^|\n\r]*/gi, '[redacted]')
+    .replace(/\b(?:system|user|assistant)\s*:[^|\n\r]*/gi, '[redacted]')
+    .replace(/SECRET_FILE_BODY[\w-]*/g, '[redacted]')
+    .replace(/file contents?[^|\n\r]*/gi, '[redacted]')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return limitCodePoints(text, limit);
+}
+
+function normalizeCategory(value: unknown): SubagentErrorCategory {
+  return typeof value === 'string' && CATEGORY_SET.has(value as SubagentErrorCategory)
+    ? value as SubagentErrorCategory
+    : 'unknown';
+}
+
+function normalizePhase(value: unknown): SubagentErrorPhase | undefined {
+  return typeof value === 'string' && PHASE_SET.has(value as SubagentErrorPhase)
+    ? value as SubagentErrorPhase
+    : undefined;
+}
+
+function normalizeRole(value: unknown): SubagentErrorAttemptRole | undefined {
+  return typeof value === 'string' && ROLE_SET.has(value as SubagentErrorAttemptRole)
+    ? value as SubagentErrorAttemptRole
+    : undefined;
+}
+
+function normalizeUsage(value: unknown): UsageStats | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const usage = value as Partial<UsageStats>;
+  return {
+    input: Number(usage.input ?? 0),
+    output: Number(usage.output ?? 0),
+    cacheRead: Number(usage.cacheRead ?? 0),
+    cacheWrite: Number(usage.cacheWrite ?? 0),
+    cost: Number(usage.cost ?? 0),
+    contextTokens: Number(usage.contextTokens ?? 0),
+    turns: Number(usage.turns ?? 0),
+  };
+}
+
+function normalizeDetails(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const details: Record<string, string> = {};
+  for (const [rawKey, rawValue] of Object.entries(value).slice(0, DETAILS_LIMIT)) {
+    const key = asciiSafe(rawKey, DETAILS_KEY_LIMIT);
+    const text = redactText(typeof rawValue === 'string' ? rawValue : JSON.stringify(rawValue), DETAILS_VALUE_LIMIT);
+    if (!key || !text) continue;
+    details[key] = text;
+  }
+  return Object.keys(details).length ? details : undefined;
+}
+
+function safeMessage(category: SubagentErrorCategory, details?: Record<string, string>): string {
+  switch (category) {
+    case 'total_timeout':
+      return details?.timeout_ms ? `timed out after ${details.timeout_ms}ms` : 'timed out';
+    case 'stall_timeout':
+      return details?.stall_timeout_ms ? `Subagent stalled for ${details.stall_timeout_ms}ms without final response.` : 'Subagent stalled without final response.';
+    case 'cancelled':
+      return `Subagent cancelled: ${details?.cancel_reason ?? 'cancelled'}`;
+    case 'empty_response_no_tools':
+      return 'Subagent finished without a final response.';
+    case 'empty_response_after_tools':
+      return 'Subagent completed tool execution but did not produce a final response.';
+    case 'fallback_failed':
+      return 'Subagent fallback failed.';
+    case 'unknown_fallback':
+      return 'Subagent fallback unavailable after model failure.';
+    case 'serialization_failure':
+      return 'Subagent error metadata could not be serialized safely.';
+    default:
+      return category.replace(/_/g, ' ');
+  }
+}
+
+export function normalizeErrorMetadata(input: Partial<SubagentErrorMetadata> & { category: SubagentErrorCategory } | Partial<SubagentErrorMetadata>): SubagentErrorMetadata {
+  try {
+    return normalizeErrorMetadataInternal(input, 0);
+  } catch {
+    return {
+      version: 1,
+      category: 'serialization_failure',
+      message: 'Subagent error metadata could not be serialized safely.',
+      retryable: false,
+      phase: 'serializer',
+      partial_result_available: false,
+    };
+  }
+}
+
+function normalizeErrorMetadataInternal(input: Partial<SubagentErrorMetadata> | undefined, depth: number): SubagentErrorMetadata {
+  const category = normalizeCategory(input?.category);
+  const details = normalizeDetails(input?.details);
+  const message = redactText(typeof input?.message === 'string' ? input.message : safeMessage(category, details), MESSAGE_LIMIT)
+    ?? safeMessage(category, details);
+  const attempts = Array.isArray(input?.attempts)
+    ? input.attempts
+        .slice(0, ATTEMPTS_LIMIT)
+        .map((attempt, index) => {
+          const normalized = normalizeErrorMetadataInternal(attempt, depth + 1);
+          const role = normalizeRole(attempt?.role) ?? (index === 0 ? 'primary' : 'fallback');
+          return { ...normalized, role };
+        })
+    : undefined;
+  const cause = depth < CAUSE_DEPTH_LIMIT && input?.cause
+    ? normalizeErrorMetadataInternal(input.cause, depth + 1)
+    : undefined;
+  return {
+    version: 1,
+    category,
+    message,
+    retryable: typeof input?.retryable === 'boolean' ? input.retryable : RETRYABLE_DEFAULTS[category],
+    phase: normalizePhase(input?.phase),
+    code: asciiSafe(typeof input?.code === 'string' ? input.code : category, CODE_LIMIT),
+    role: normalizeRole(input?.role),
+    source: input?.source ? {
+      provider: redactText(input.source.provider, SOURCE_LIMIT),
+      model: redactText(input.source.model, SOURCE_LIMIT),
+      tool: redactText(input.source.tool, SOURCE_LIMIT),
+      operation: redactText(input.source.operation, SOURCE_LIMIT),
+    } : undefined,
+    cause,
+    attempts: attempts?.length ? attempts : undefined,
+    usage_at_failure: normalizeUsage(input?.usage_at_failure),
+    last_activity: redactText(input?.last_activity, LAST_ACTIVITY_LIMIT),
+    partial_result_available: Boolean(input?.partial_result_available),
+    task_id: redactText(input?.task_id, SOURCE_LIMIT),
+    parent_session_id: redactText(input?.parent_session_id, SOURCE_LIMIT),
+    details,
+  };
+}
+
+export function deriveErrorString(metadata: SubagentErrorMetadata): string {
+  const normalized = normalizeErrorMetadata(metadata);
+  return safeMessage(normalized.category, normalized.details) === 'unknown'
+    ? normalized.message
+    : safeMessage(normalized.category, normalized.details);
+}
+
+export function classifyThrownError(error: unknown, context: { phase?: SubagentErrorPhase; provider?: string; model?: string; operation?: string; retryable?: boolean } = {}): SubagentErrorMetadata {
+  const rawMessage = error instanceof Error
+    ? error.message
+    : typeof error === 'string'
+      ? error
+      : error && typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string'
+        ? String((error as { message: unknown }).message)
+        : String(error);
+  const message = rawMessage || 'Unknown subagent failure';
+  const lower = message.toLowerCase();
+  const errorClass = error instanceof Error ? error.constructor.name : typeof error;
+  let category: SubagentErrorCategory = 'unknown';
+  if (!(error instanceof Error) && typeof error !== 'string') category = 'malformed_thrown_value';
+  else if (/auth|api key|invalid key|unauthori[sz]ed|forbidden|401|403|credential/.test(lower)) category = 'provider_auth_error';
+  else if (/context|token|maximum|length/.test(lower)) category = 'context_overflow';
+  else if (/rate.?limit|quota|429|too many requests/.test(lower)) category = 'provider_rate_limit';
+  else if (/econnreset|enotfound|network|socket|timeout|timed out|connection/.test(lower)) category = 'provider_network_error';
+  else if (error instanceof Error) category = 'provider_api_error';
+  return normalizeErrorMetadata({
+    category,
+    message,
+    retryable: context.retryable,
+    phase: context.phase,
+    source: {
+      provider: context.provider,
+      model: context.model,
+      operation: context.operation,
+    },
+    partial_result_available: false,
+    details: { error_class: errorClass },
+  });
+}
+
+export function classifyAssistantFailure(input: {
+  stopReason?: string;
+  errorMessage?: string;
+  sawToolActivity?: boolean;
+  provider?: string;
+  model?: string;
+}): SubagentErrorMetadata | undefined {
+  if (input.stopReason === 'error' || input.errorMessage) {
+    return classifyThrownError(new Error(input.errorMessage ?? 'Assistant error'), {
+      phase: 'assistant_final',
+      provider: input.provider,
+      model: input.model,
+      operation: 'session.prompt',
+    });
+  }
+  if (input.sawToolActivity) {
+    return normalizeErrorMetadata({
+      category: 'empty_response_after_tools',
+      message: 'Subagent completed tool execution but did not produce a final response.',
+      phase: 'assistant_final',
+      partial_result_available: false,
+    });
+  }
+  return normalizeErrorMetadata({
+    category: 'empty_response_no_tools',
+    message: 'Subagent finished without a final response.',
+    phase: 'assistant_final',
+    partial_result_available: false,
+  });
+}
+
+export function classifyFallbackFailure(primary: SubagentErrorMetadata, fallback?: SubagentErrorMetadata): SubagentErrorMetadata {
+  return normalizeErrorMetadata({
+    category: fallback ? 'fallback_failed' : 'unknown_fallback',
+    message: fallback ? 'Subagent fallback failed.' : 'Subagent fallback unavailable after model failure.',
+    retryable: false,
+    partial_result_available: false,
+    attempts: fallback
+      ? [{ ...normalizeErrorMetadata(primary), role: 'primary' }, { ...normalizeErrorMetadata(fallback), role: 'fallback' }]
+      : [{ ...normalizeErrorMetadata(primary), role: 'primary' }],
+  });
+}
+
+export function enrichErrorMetadata(metadata: SubagentErrorMetadata, snapshot: {
+  usage_at_failure?: UsageStats;
+  last_activity?: string;
+  partial_result_available?: boolean;
+  task_id?: string;
+  parent_session_id?: string;
+}): SubagentErrorMetadata {
+  return normalizeErrorMetadata({
+    ...metadata,
+    usage_at_failure: snapshot.usage_at_failure ?? metadata.usage_at_failure,
+    last_activity: snapshot.last_activity ?? metadata.last_activity,
+    partial_result_available: snapshot.partial_result_available ?? metadata.partial_result_available,
+    task_id: snapshot.task_id ?? metadata.task_id,
+    parent_session_id: snapshot.parent_session_id ?? metadata.parent_session_id,
+  });
+}
+
+export function serializeErrorMetadata(metadata: unknown): string | null {
+  try {
+    return JSON.stringify(normalizeErrorMetadata(metadata as Partial<SubagentErrorMetadata>));
+  } catch {
+    return JSON.stringify(normalizeErrorMetadata({
+      category: 'serialization_failure',
+      message: 'Subagent error metadata could not be serialized safely.',
+      phase: 'serializer',
+      partial_result_available: false,
+    }));
+  }
+}
+
+export function parseErrorMetadata(json: unknown): SubagentErrorMetadata | undefined {
+  try {
+    if (typeof json !== 'string' || !json.trim()) return undefined;
+    return normalizeErrorMetadata(JSON.parse(json) as Partial<SubagentErrorMetadata>);
+  } catch {
+    return undefined;
+  }
+}
+
+export function safeErrorMetadataDetails(metadata: SubagentErrorMetadata): Record<string, unknown> {
+  const normalized = normalizeErrorMetadata(metadata);
+  return {
+    version: normalized.version,
+    category: normalized.category,
+    retryable: normalized.retryable,
+    phase: normalized.phase,
+    code: normalized.code,
+    source: normalized.source,
+    partial_result_available: normalized.partial_result_available,
+    details: normalized.details,
+  };
+}
+
+export class SubagentStructuredError extends Error {
+  readonly error_metadata: SubagentErrorMetadata;
+
+  constructor(metadata: SubagentErrorMetadata) {
+    const normalized = normalizeErrorMetadata(metadata);
+    super(deriveErrorString(normalized));
+    this.name = 'SubagentStructuredError';
+    this.error_metadata = normalized;
+  }
+}

package/src/history.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { parseErrorMetadata, serializeErrorMetadata } from './error-metadata.js';
 import { boundThreadSnapshot } from './thread-view.js';
 import type { SubagentTask, SubagentThreadSnapshot } from './types.js';
 
@@ -97,6 +98,8 @@ export class SubagentHistoryStore {
         effort_source TEXT,
         fallback_used INTEGER,
         error TEXT,
+        error_metadata_json TEXT,
+        error_category TEXT,
         result TEXT,
         thread_snapshot_json TEXT
       );
@@ -114,18 +117,32 @@ export class SubagentHistoryStore {
       CREATE INDEX IF NOT EXISTS idx_subagent_events_task ON subagent_events(task_id, created_at);
     `);
     ensureColumn(db, 'subagent_tasks', 'system_prompt', 'TEXT');
+    ensureColumn(db, 'subagent_tasks', 'error_metadata_json', 'TEXT');
+    ensureColumn(db, 'subagent_tasks', 'error_category', 'TEXT');
     this.dbs.set(file, db);
     return db;
   }
 
   upsertTask(cwd: string, task: SubagentTask): void {
+    let errorMetadataJson: string | null = null;
+    let errorCategory: string | null = null;
+    if (task.error_metadata !== undefined) {
+      try {
+        errorMetadataJson = serializeErrorMetadata(task.error_metadata);
+        errorCategory = parseErrorMetadata(errorMetadataJson)?.category ?? null;
+      } catch {
+        errorMetadataJson = null;
+        errorCategory = null;
+      }
+    }
+
     this.db(cwd).prepare(`
       INSERT INTO subagent_tasks (
         id, cwd, agent, mode, status, task, context, created_at, session_id, started_at, ended_at,
         last_activity_at, last_activity, output_preview, prompt, system_prompt, transcript,
         usage_input, usage_output, usage_cache_read, usage_cache_write, usage_cost, usage_context_tokens, usage_turns,
-        model, effort, model_source, effort_source, fallback_used, error, result, thread_snapshot_json
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        model, effort, model_source, effort_source, fallback_used, error, error_metadata_json, error_category, result, thread_snapshot_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         status=excluded.status,
         session_id=excluded.session_id,
@@ -150,6 +167,8 @@ export class SubagentHistoryStore {
         effort_source=excluded.effort_source,
         fallback_used=excluded.fallback_used,
         error=excluded.error,
+        error_metadata_json=excluded.error_metadata_json,
+        error_category=excluded.error_category,
         result=excluded.result,
         thread_snapshot_json=excluded.thread_snapshot_json
     `).run(
@@ -183,6 +202,8 @@ export class SubagentHistoryStore {
       value(task.effort_source),
       task.fallback_used === undefined ? null : task.fallback_used ? 1 : 0,
       value(task.error),
+      errorMetadataJson,
+      errorCategory,
       value(task.result),
       snapshotJson(task.thread_snapshot),
     );
@@ -248,6 +269,7 @@ function rowToTask(row: any, options: HistoryReadOptions = {}): SubagentTask {
     effort_source: row.effort_source ?? undefined,
     fallback_used: row.fallback_used === null || row.fallback_used === undefined ? undefined : Boolean(row.fallback_used),
     error: row.error ?? undefined,
+    error_metadata: parseErrorMetadata(row.error_metadata_json),
     result: row.result ?? undefined,
     thread_snapshot: options.includeSnapshots === false ? undefined : parseSnapshotJson(row.thread_snapshot_json),
   };