pi-subagents-j0k3r 1.1.3 → 1.2.1

package/CHANGELOG.md

@@ -1,10 +1,24 @@
 # Changelog
 
-## Unreleased
+## 1.2.1 - 2026-07-12
+
+### Fixed
+- Stabilized `/subagents` rendering with a full-screen overlay that prevents parent-chat flicker and reserves space for the panel border.
+
+## 1.2.0 - 2026-07-12
+
+### 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),
@@ -469,22 +507,68 @@ export default function subagentsExtension(pi: any): void {
             showImages: ctx?.showImages,
             imageWidthCells: ctx?.imageWidthCells,
           },
-          () => Math.max(12, process.stdout.rows || 42),
+          () => Math.max(12, (process.stdout.rows || 42) - 2),
           (id: string) => manager.getTask(id, cwd),
           selectedTaskId,
           (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,
+      { overlay: true, overlayOptions: { anchor: 'top-left', width: '100%', maxHeight: '100%', margin: 0 } },
     );
     } finally {
       activePanelCancelSelected = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-j0k3r",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "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;
+  }
+}