@straiffi/archon 1.4.12 → 1.6.0

package/dist/server/lib/agent.js

@@ -6,13 +6,64 @@ import Database from 'better-sqlite3';
 import db from '../db.js';
 import { getChatSession, updateChatSessionUsageSnapshot } from './chats.js';
 import { normalizeClaudeModelId, normalizeModelId } from './models.js';
+import { createOpencodeTaskSessionReader, parseOpencodeTaskEnvelope } from './opencodeTaskSessions.js';
 import { PLAN_MODE_QUESTION_TOOL_NAME } from './planModeQuestions.js';
+import { formatGenericToolCall } from './genericToolCall.js';
 import { getSpecSession, updateSpecSessionResumeId, updateSpecSessionStatus, updateSpecSessionTitle, updateSpecSessionUsageSnapshot } from './specs.js';
 import { updateSpecReviewRunStatus, updateSpecReviewRunStreaming, updateSpecReviewRunUsage } from './specReviews.js';
-import { emitAgentRunsUpdated, finalizeAgentRun, updateAgentRunSessionId, updateAgentRunStatus } from './agentRuns.js';
+import { createAgentRun, emitAgentRunsUpdated, finalizeAgentRun, getNextAgentRunIndex, listAgentRunsForParent, updateAgentRunLabel, updateAgentRunSessionId, updateAgentRunStatus } from './agentRuns.js';
 import { resolveOpencodeDbPath } from './runtimePaths.js';
 import { markTicketDescriptionVisibleInBundle } from './ticketMessages.js';
 import { getTicket } from './tickets.js';
+import { createTranscriptRunSnapshots } from './transcriptRuns.js';
+const withTranscriptRuns = (value, transcriptRuns) => {
+    return transcriptRuns ? { ...value, transcriptRuns } : value;
+};
+const createOpencodeRecoveryTracker = () => {
+    let sawError = false;
+    let latestEvent = null;
+    let recoveredFinalAnswerFragments = [];
+    return {
+        consume: events => {
+            let shouldResetResponse = false;
+            for (const event of events ?? []) {
+                latestEvent = event.type;
+                if (event.type === 'error') {
+                    sawError = true;
+                    recoveredFinalAnswerFragments = [];
+                    shouldResetResponse = true;
+                    continue;
+                }
+                if (sawError) {
+                    recoveredFinalAnswerFragments.push(event.text);
+                }
+            }
+            return shouldResetResponse;
+        },
+        hasRecoveredFinalAnswer: () => (sawError
+            && latestEvent === 'final_answer'
+            && recoveredFinalAnswerFragments.length > 0),
+        hasUnrecoveredError: () => latestEvent === 'error',
+        getRecoveredResponse: () => recoveredFinalAnswerFragments.join('\n\n'),
+    };
+};
+const isSuccessfulOpencodeExit = (code, modelError, recoveryTracker) => (!modelError
+    && !recoveryTracker.hasUnrecoveredError()
+    && (code === 0 || recoveryTracker.hasRecoveredFinalAnswer()));
+const attachTranscriptRunsToError = (error, transcriptRuns) => {
+    const resolvedError = (error instanceof Error ? error : new Error(String(error)));
+    if (transcriptRuns) {
+        resolvedError.transcriptRuns = transcriptRuns;
+    }
+    return resolvedError;
+};
+export const getAgentErrorTranscriptRuns = (error) => {
+    if (!error || typeof error !== 'object' || !('transcriptRuns' in error)) {
+        return null;
+    }
+    const transcriptRuns = error.transcriptRuns;
+    return Array.isArray(transcriptRuns) && transcriptRuns.length > 0 ? transcriptRuns : null;
+};
 const OPENCODE_PLACEHOLDER_TITLE_PATTERN = /^New session\b/i;
 const OPENCODE_SESSION_METADATA_LOOKUP_DELAY_MS = 1500;
 const AGENT_PROGRESS_UPDATE_INTERVAL_MS = 100;
@@ -702,7 +753,6 @@ const createSpecOpencodeMetadataRefresher = ({ specSessionId, io, spawnTimestamp
         },
     };
 };
-const TOOL_CALL_PREVIEW_MAX_LENGTH = 100;
 const APPLY_PATCH_START_MARKER = '[[archon-apply-patch]]';
 const APPLY_PATCH_END_MARKER = '[[/archon-apply-patch]]';
 const normalizeToolName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
@@ -836,22 +886,6 @@ const formatWriteToolCall = (input, cwd) => {
     displayLines.push(APPLY_PATCH_END_MARKER);
     return displayLines.join('\n');
 };
-const pickGenericToolVal = (name, input) => {
-    const explicitVal = {
-        Read: input?.filePath ?? input?.file_path,
-        Bash: input?.command,
-        Glob: input?.pattern,
-        Grep: input?.pattern,
-        WebFetch: input?.url,
-        WebSearch: input?.query,
-        Task: input?.description,
-        NotebookEdit: input?.notebook_path,
-    }[name];
-    if (typeof explicitVal === 'string' && explicitVal.length > 0) {
-        return explicitVal;
-    }
-    return Object.values(input ?? {}).find(v => typeof v === 'string') ?? null;
-};
 const formatToolCall = (name, input, cwd) => {
     if (isTodoWriteTool(name)) {
         return formatTodoWriteToolCall(input);
@@ -865,40 +899,87 @@ const formatToolCall = (name, input, cwd) => {
         if (formatted !== null) {
             return formatted;
         }
-        return genericToolCallLabel(name, input);
+        return formatGenericToolCall(name, input);
     }
     if (normalized === 'write') {
         const formatted = formatWriteToolCall(input, cwd);
         if (formatted !== null) {
             return formatted;
         }
-        return genericToolCallLabel(name, input);
+        return formatGenericToolCall(name, input);
     }
-    return genericToolCallLabel(name, input);
+    return formatGenericToolCall(name, input);
 };
-const genericToolCallLabel = (name, input) => {
-    const val = pickGenericToolVal(name, input);
-    if (typeof val !== 'string' || val.length === 0) {
-        return `_${name}_`;
+const isSubagentTool = (name) => {
+    const normalized = normalizeToolName(name);
+    return normalized === 'task' || normalized === 'subagent' || normalized === 'agent';
+};
+const getSubagentDescription = (input, fallback) => {
+    if (input) {
+        for (const key of ['description', 'title', 'task', 'subagent_type', 'prompt']) {
+            const value = input[key];
+            if (typeof value === 'string' && value.trim()) {
+                const firstLine = value.trim().split('\n')[0] ?? '';
+                return firstLine.length > 120 ? `${firstLine.slice(0, 117)}...` : firstLine;
+            }
+        }
     }
-    const display = val.length > TOOL_CALL_PREVIEW_MAX_LENGTH ? val.slice(0, TOOL_CALL_PREVIEW_MAX_LENGTH) + '…' : val;
-    return `_${name}_ \`${display}\``;
+    return fallback;
 };
+const stringifyToolResult = (content) => {
+    if (typeof content === 'string') {
+        return content.trim() || null;
+    }
+    if (Array.isArray(content)) {
+        const text = content
+            .map(item => item && typeof item === 'object' && typeof item.text === 'string'
+            ? item.text.trim()
+            : '')
+            .filter(Boolean)
+            .join('\n\n');
+        return text || null;
+    }
+    return content === null || content === undefined ? null : JSON.stringify(content);
+};
+const getSubagentCompletionStatus = (state, isError = false) => {
+    const normalizedState = state?.toLowerCase();
+    return isError || normalizedState === 'failed' || normalizedState === 'error' ? 'error' : 'done';
+};
+const emptyParsedStreamLine = () => ({
+    logFragment: null,
+    responseFragment: null,
+    subagentEvents: [],
+    providerSessionId: null,
+});
 const parseClaudeStreamJsonLine = (line, cwd) => {
     const trimmed = line.trim();
     if (!trimmed) {
-        return { logFragment: null, responseFragment: null };
+        return emptyParsedStreamLine();
     }
     let event;
     try {
         event = JSON.parse(trimmed);
     }
     catch {
-        return { logFragment: trimmed, responseFragment: trimmed };
+        const envelope = parseOpencodeTaskEnvelope(trimmed);
+        if (envelope) {
+            return {
+                ...emptyParsedStreamLine(),
+                subagentEvents: [{
+                        kind: 'complete',
+                        callId: null,
+                        sessionId: envelope.childSessionId,
+                        status: getSubagentCompletionStatus(envelope.state),
+                        ...(envelope.result ? { text: envelope.result } : {}),
+                    }],
+            };
+        }
+        return { logFragment: trimmed, responseFragment: trimmed, subagentEvents: [], providerSessionId: null };
     }
     if (event.type === 'assistant' && Array.isArray(event.message?.content)) {
         const logParts = [];
         const responseParts = [];
+        const subagentEvents = [];
         for (const block of event.message.content) {
             if (block.type === 'text' && block.text) {
                 const text = block.text.trim();
@@ -908,6 +989,16 @@ const parseClaudeStreamJsonLine = (line, cwd) => {
                 }
             }
             else if (block.type === 'tool_use' && block.name) {
+                if (isSubagentTool(block.name)) {
+                    const description = getSubagentDescription(block.input, block.name);
+                    logParts.push(`Subagent: ${description}`);
+                    subagentEvents.push({
+                        kind: 'start',
+                        callId: block.id ?? null,
+                        label: `Subagent: ${description}`,
+                    });
+                    continue;
+                }
                 const toolFragment = formatToolCall(block.name, block.input, cwd);
                 if (toolFragment) {
                     logParts.push(toolFragment);
@@ -917,9 +1008,44 @@ const parseClaudeStreamJsonLine = (line, cwd) => {
         return {
             logFragment: logParts.length > 0 ? logParts.join('\n\n') : null,
             responseFragment: responseParts.length > 0 ? responseParts.join('\n\n') : null,
+            subagentEvents,
+            providerSessionId: null,
         };
     }
-    return { logFragment: null, responseFragment: null };
+    if (event.type === 'stream_event' && event.event?.type === 'content_block_start') {
+        const block = event.event.content_block;
+        if (block?.type === 'tool_use' && block.name && isSubagentTool(block.name)) {
+            const description = getSubagentDescription(block.input, block.name);
+            return {
+                ...emptyParsedStreamLine(),
+                logFragment: `Subagent: ${description}`,
+                subagentEvents: [{
+                        kind: 'start',
+                        callId: block.id ?? null,
+                        label: `Subagent: ${description}`,
+                    }],
+            };
+        }
+    }
+    if (event.type === 'user' && Array.isArray(event.message?.content)) {
+        const subagentEvents = event.message.content.flatMap(block => {
+            if (block.type !== 'tool_result' || !block.tool_use_id) {
+                return [];
+            }
+            const rawText = stringifyToolResult(block.content);
+            const envelope = parseOpencodeTaskEnvelope(rawText);
+            const text = envelope?.result ?? rawText;
+            return [{
+                    kind: 'complete',
+                    callId: block.tool_use_id,
+                    status: getSubagentCompletionStatus(envelope?.state, block.is_error),
+                    ...(text ? { text } : {}),
+                    ...(envelope ? { sessionId: envelope.childSessionId } : {}),
+                }];
+        });
+        return { ...emptyParsedStreamLine(), subagentEvents };
+    }
+    return emptyParsedStreamLine();
 };
 const formatOpencodeToolUse = (event, cwd) => {
     const toolName = event.part?.tool;
@@ -989,12 +1115,22 @@ const extractLeadingJsonObjects = (line) => {
     };
 };
 const parseOpencodeJsonEvent = (event, cwd) => {
+    const providerSessionId = event.sessionID?.trim()
+        || event.sessionId?.trim()
+        || event.part?.sessionID?.trim()
+        || event.part?.sessionId?.trim()
+        || null;
     if (event.type === 'text' && event.part?.type === 'text' && event.part.text) {
         const text = event.part.text.trim();
         const phase = event.part.metadata?.openai?.phase;
         return {
             logFragment: text || null,
             responseFragment: text && (!phase || phase === 'final_answer') ? text : null,
+            subagentEvents: [],
+            providerSessionId,
+            recoveryEvents: text && phase === 'final_answer'
+                ? [{ type: 'final_answer', text }]
+                : [],
         };
     }
     if (event.type === 'reasoning' && event.part?.type === 'reasoning') {
@@ -1002,25 +1138,74 @@ const parseOpencodeJsonEvent = (event, cwd) => {
         return {
             logFragment: text || null,
             responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
         };
     }
-    if (event.type === 'tool_use') {
+    if (event.type === 'tool' || event.type === 'tool_use' || event.type === 'tool_result') {
+        const isToolInvocation = event.type === 'tool' || event.type === 'tool_use';
+        const toolName = event.part?.tool;
+        if (toolName && isSubagentTool(toolName)) {
+            const description = getSubagentDescription(event.part?.state?.input, toolName);
+            const rawOutput = event.part?.state?.output?.trim();
+            const envelope = parseOpencodeTaskEnvelope(rawOutput);
+            const output = envelope ? envelope.result : rawOutput;
+            const taskStatus = event.part?.state?.status?.toLowerCase() ?? envelope?.state?.toLowerCase();
+            const outputKind = taskStatus === 'running' || taskStatus === 'pending' ? 'fragment' : 'complete';
+            const completionStatus = taskStatus === 'error' || taskStatus === 'failed' ? 'error' : 'done';
+            const childSessionId = envelope?.childSessionId
+                ?? (typeof event.part?.state?.metadata?.sessionID === 'string' ? event.part.state.metadata.sessionID : null)
+                ?? (typeof event.part?.state?.metadata?.sessionId === 'string' ? event.part.state.metadata.sessionId : null);
+            return {
+                logFragment: isToolInvocation ? `Subagent: ${description}` : null,
+                responseFragment: null,
+                subagentEvents: [
+                    ...(isToolInvocation
+                        ? [{
+                                kind: 'start',
+                                callId: event.part?.callID ?? null,
+                                label: `Subagent: ${description}`,
+                                sessionId: childSessionId,
+                            }]
+                        : []),
+                    ...(output
+                        ? [{
+                                kind: outputKind,
+                                callId: event.part?.callID ?? null,
+                                text: output,
+                                sessionId: childSessionId,
+                                status: completionStatus,
+                            }]
+                        : []),
+                ],
+                providerSessionId,
+            };
+        }
+        if (!isToolInvocation) {
+            return { ...emptyParsedStreamLine(), providerSessionId };
+        }
         const toolFragment = formatOpencodeToolUse(event, cwd);
         return {
             logFragment: toolFragment,
             responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
         };
     }
     if (event.type === 'step_start') {
         return {
             logFragment: formatOpencodeStepTitle(event),
             responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
         };
     }
     if (event.type === 'step_finish') {
         return {
             logFragment: null,
             responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
         };
     }
     if (event.type === 'error') {
@@ -1032,29 +1217,46 @@ const parseOpencodeJsonEvent = (event, cwd) => {
                     || JSON.stringify(event.error))
                 : '';
         const text = event.part?.text?.trim() || errorText || '';
-        if (text) {
-            return {
-                logFragment: `**Error:** ${text}`,
-                responseFragment: text,
-            };
-        }
+        return {
+            logFragment: text ? `**Error:** ${text}` : null,
+            responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
+            recoveryEvents: [{ type: 'error' }],
+        };
     }
-    return { logFragment: null, responseFragment: null };
+    return emptyParsedStreamLine();
 };
 const parseOpencodeJsonLine = (line, cwd) => {
     const trimmed = line.trim();
     if (!trimmed) {
-        return { logFragment: null, responseFragment: null };
+        return emptyParsedStreamLine();
     }
     const { jsonObjects, remainder } = extractLeadingJsonObjects(trimmed);
     if (jsonObjects.length === 0) {
         if (trimmed.startsWith('{')) {
-            return { logFragment: null, responseFragment: null };
+            return emptyParsedStreamLine();
         }
-        return { logFragment: trimmed, responseFragment: trimmed };
+        const envelope = parseOpencodeTaskEnvelope(trimmed);
+        if (envelope) {
+            return {
+                ...emptyParsedStreamLine(),
+                subagentEvents: [{
+                        kind: 'complete',
+                        callId: null,
+                        sessionId: envelope.childSessionId,
+                        status: getSubagentCompletionStatus(envelope.state),
+                        ...(envelope.result ? { text: envelope.result } : {}),
+                    }],
+            };
+        }
+        return { logFragment: trimmed, responseFragment: trimmed, subagentEvents: [], providerSessionId: null };
     }
     const logFragments = [];
     const responseFragments = [];
+    const subagentEvents = [];
+    const recoveryEvents = [];
+    let providerSessionId = null;
     for (const jsonObject of jsonObjects) {
         let event;
         try {
@@ -1063,7 +1265,11 @@ const parseOpencodeJsonLine = (line, cwd) => {
         catch {
             continue;
         }
-        const { logFragment, responseFragment } = parseOpencodeJsonEvent(event, cwd);
+        const parsedEvent = parseOpencodeJsonEvent(event, cwd);
+        const { logFragment, responseFragment } = parsedEvent;
+        subagentEvents.push(...parsedEvent.subagentEvents);
+        recoveryEvents.push(...(parsedEvent.recoveryEvents ?? []));
+        providerSessionId = providerSessionId ?? parsedEvent.providerSessionId;
         if (logFragment !== null) {
             logFragments.push(logFragment);
         }
@@ -1071,16 +1277,386 @@ const parseOpencodeJsonLine = (line, cwd) => {
             responseFragments.push(responseFragment);
         }
     }
-    if (logFragments.length > 0 || responseFragments.length > 0) {
+    if (remainder) {
+        const envelope = parseOpencodeTaskEnvelope(remainder);
+        if (envelope) {
+            subagentEvents.push({
+                kind: 'complete',
+                callId: null,
+                sessionId: envelope.childSessionId,
+                status: getSubagentCompletionStatus(envelope.state),
+                ...(envelope.result ? { text: envelope.result } : {}),
+            });
+        }
+        else if (logFragments.length === 0 && responseFragments.length === 0 && subagentEvents.length === 0) {
+            logFragments.push(remainder);
+            responseFragments.push(remainder);
+        }
+    }
+    if (logFragments.length > 0 || responseFragments.length > 0 || subagentEvents.length > 0) {
         return {
             logFragment: logFragments.length > 0 ? logFragments.join('\n\n') : null,
             responseFragment: responseFragments.length > 0 ? responseFragments.join('\n\n') : null,
+            subagentEvents,
+            providerSessionId,
+            recoveryEvents,
         };
     }
-    if (remainder) {
-        return { logFragment: remainder, responseFragment: remainder };
+    return emptyParsedStreamLine();
+};
+const appendTranscriptText = (current, fragment) => {
+    const trimmed = fragment.trim();
+    if (!trimmed) {
+        return current;
+    }
+    return current ? `${current}\n\n${trimmed}` : trimmed;
+};
+const appendOpencodeTranscriptLine = ({ parsed, logLines, responseLines, recoveryTracker, }) => {
+    const shouldResetResponse = recoveryTracker.consume(parsed.recoveryEvents);
+    if (shouldResetResponse) {
+        responseLines.length = 0;
+    }
+    if (parsed.logFragment !== null) {
+        logLines.push(parsed.logFragment);
+    }
+    if (parsed.responseFragment !== null) {
+        responseLines.push(parsed.responseFragment);
+    }
+    return shouldResetResponse;
+};
+export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, }) => {
+    const trackedRuns = [];
+    let nextRunIndex = Math.max(getNextAgentRunIndex(parentType, parentId), mainRun ? mainRun.runIndex + 1 : 1);
+    const emitUpdate = () => {
+        emitAgentRunsUpdated(io, parentType, parentId);
+    };
+    const findRun = (callId, sessionId) => {
+        if (callId) {
+            const callRun = trackedRuns.find(run => run.callId === callId);
+            if (callRun) {
+                return callRun;
+            }
+            return sessionId ? trackedRuns.find(run => run.sessionId === sessionId) ?? null : null;
+        }
+        if (sessionId) {
+            const sessionRun = trackedRuns.find(run => run.sessionId === sessionId);
+            if (sessionRun) {
+                return sessionRun;
+            }
+        }
+        return [...trackedRuns].reverse().find(run => run.status === 'running') ?? null;
+    };
+    const bindSessionId = (run, sessionId) => {
+        const normalized = sessionId?.trim() || null;
+        if (!normalized || normalized === run.sessionId) {
+            return;
+        }
+        run.sessionId = normalized;
+        updateAgentRunSessionId(run.id, normalized);
+    };
+    const updateLabel = (run, label) => {
+        const normalized = label?.trim() || null;
+        if (!normalized || normalized === run.label) {
+            return;
+        }
+        run.label = normalized;
+        updateAgentRunLabel(run.id, normalized);
+    };
+    const handle = (events) => {
+        for (const event of events) {
+            if (event.kind === 'start') {
+                const existingRun = event.callId || event.sessionId ? findRun(event.callId, event.sessionId) : null;
+                if (existingRun) {
+                    bindSessionId(existingRun, event.sessionId);
+                    updateLabel(existingRun, event.label);
+                    emitUpdate();
+                    continue;
+                }
+                const runIndex = Math.max(getNextAgentRunIndex(parentType, parentId), nextRunIndex);
+                const id = createAgentRun({
+                    parentType,
+                    parentId,
+                    runIndex,
+                    label: event.label?.trim() || 'Subagent',
+                    role: 'subagent',
+                });
+                nextRunIndex = runIndex + 1;
+                const run = {
+                    id,
+                    callId: event.callId,
+                    runIndex,
+                    log: '',
+                    response: '',
+                    status: 'running',
+                    sessionId: null,
+                    label: event.label?.trim() || 'Subagent',
+                    createdAt: new Date().toISOString(),
+                };
+                trackedRuns.push(run);
+                bindSessionId(run, event.sessionId);
+                emitUpdate();
+                continue;
+            }
+            let run = findRun(event.callId, event.sessionId);
+            if (!run && event.kind === 'complete' && !event.callId) {
+                handle([{
+                        kind: 'start',
+                        callId: event.callId,
+                        label: 'Subagent',
+                        sessionId: event.sessionId,
+                    }]);
+                run = findRun(event.callId, event.sessionId);
+            }
+            if (!run || run.status !== 'running') {
+                continue;
+            }
+            bindSessionId(run, event.sessionId);
+            if (event.text) {
+                if (event.kind === 'fragment') {
+                    run.log = appendTranscriptText(run.log, event.text);
+                }
+                else {
+                    run.response = appendTranscriptText(run.response, event.text);
+                }
+            }
+            if (event.kind === 'complete') {
+                const completionStatus = event.status ?? 'done';
+                run.status = completionStatus;
+                updateAgentRunStatus(run.id, 'running', run.log || null, run.response || null);
+                finalizeAgentRun(run.id, completionStatus, run.response || null);
+            }
+            else {
+                updateAgentRunStatus(run.id, 'running', run.log || null, run.response || null);
+            }
+            emitUpdate();
+        }
+    };
+    const applySnapshot = ({ callId, label, status, log, response, sessionId, }) => {
+        let run = findRun(callId);
+        if (!run) {
+            handle([{ kind: 'start', callId, label, sessionId }]);
+            run = findRun(callId);
+        }
+        if (!run) {
+            return;
+        }
+        bindSessionId(run, sessionId);
+        updateLabel(run, label);
+        const nextLog = log?.trim() ?? '';
+        const nextResponse = response?.trim() ?? '';
+        const nextStatus = run.status !== 'running' && status === 'running' ? run.status : status;
+        const hasChanged = run.log !== nextLog || run.response !== nextResponse || run.status !== nextStatus;
+        if (!hasChanged) {
+            return;
+        }
+        run.log = nextLog;
+        run.response = nextResponse;
+        run.status = nextStatus;
+        if (nextStatus === 'running') {
+            updateAgentRunStatus(run.id, 'running', run.log || null, run.response || null);
+        }
+        else {
+            updateAgentRunStatus(run.id, 'running', run.log || null, run.response || null);
+            finalizeAgentRun(run.id, nextStatus, run.response || null);
+        }
+        emitUpdate();
+    };
+    const finalize = (status, parentLog, parentResponse) => {
+        if (trackedRuns.length === 0 && !mainRun) {
+            return null;
+        }
+        for (const run of trackedRuns) {
+            if (run.status !== 'running') {
+                continue;
+            }
+            run.status = status;
+            finalizeAgentRun(run.id, status, run.response || null);
+        }
+        emitUpdate();
+        const trackedIds = new Set(trackedRuns.map(run => run.id));
+        const persistedRuns = listAgentRunsForParent(parentType, parentId)
+            .filter(run => trackedIds.has(run.id) || run.id === mainRun?.id);
+        const persistedIds = new Set(persistedRuns.map(run => run.id));
+        const timestamp = new Date().toISOString();
+        for (const run of trackedRuns) {
+            if (persistedIds.has(run.id)) {
+                continue;
+            }
+            persistedRuns.push({
+                id: run.id,
+                parent_type: parentType,
+                parent_id: parentId,
+                run_index: run.runIndex,
+                label: run.label,
+                role: 'subagent',
+                agent_status: run.status,
+                agent_log: run.log || null,
+                streaming_response: null,
+                response_text: run.response || null,
+                session_id: run.sessionId,
+                created_at: run.createdAt,
+                updated_at: timestamp,
+            });
+        }
+        if (mainRun) {
+            const persistedMainRun = persistedRuns.find(run => run.id === mainRun.id);
+            const mainSnapshotRun = {
+                id: mainRun.id,
+                parent_type: parentType,
+                parent_id: parentId,
+                run_index: mainRun.runIndex,
+                label: mainRun.label,
+                role: mainRun.role,
+                agent_status: status,
+                agent_log: parentLog,
+                streaming_response: null,
+                response_text: parentResponse,
+                session_id: persistedMainRun?.session_id ?? null,
+                created_at: persistedMainRun?.created_at ?? timestamp,
+                updated_at: persistedMainRun?.updated_at ?? timestamp,
+            };
+            const mainRunIndex = persistedRuns.findIndex(run => run.id === mainRun.id);
+            if (mainRunIndex >= 0) {
+                persistedRuns[mainRunIndex] = mainSnapshotRun;
+            }
+            else {
+                persistedRuns.push(mainSnapshotRun);
+            }
+        }
+        else {
+            persistedRuns.push({
+                id: `${parentType}:${parentId}:main`,
+                parent_type: parentType,
+                parent_id: parentId,
+                run_index: 0,
+                label: 'Main agent',
+                role: 'main',
+                agent_status: status,
+                agent_log: parentLog,
+                streaming_response: null,
+                response_text: parentResponse,
+                session_id: null,
+                created_at: timestamp,
+                updated_at: timestamp,
+            });
+        }
+        return createTranscriptRunSnapshots(persistedRuns.sort((left, right) => left.run_index - right.run_index));
+    };
+    return { applySnapshot, handle, finalize };
+};
+export const reconstructOpencodeSubagentTranscript = (parts, cwd) => {
+    let log = '';
+    let response = '';
+    for (const persistedPart of parts) {
+        if (persistedPart.role && persistedPart.role !== 'assistant') {
+            continue;
+        }
+        const part = persistedPart.data;
+        const partType = part?.type;
+        const eventType = partType === 'tool'
+            ? 'tool_use'
+            : partType === 'step-start'
+                ? 'step_start'
+                : partType === 'step-finish'
+                    ? 'step_finish'
+                    : partType;
+        const parsed = parseOpencodeJsonEvent({ type: eventType, part }, cwd);
+        if (parsed.logFragment && parsed.logFragment !== parsed.responseFragment) {
+            log = appendTranscriptText(log, parsed.logFragment);
+        }
+        if (parsed.responseFragment) {
+            response = appendTranscriptText(response, parsed.responseFragment);
+        }
     }
-    return { logFragment: null, responseFragment: null };
+    return { log: log || null, response: response || null };
+};
+export const createOpencodeSubagentMonitor = ({ initialParentSessionId, spawnTimestamp, cwd, tracker, onParentSessionId, taskSessionReader, discoverParentSession = true, }) => {
+    const reader = taskSessionReader === undefined ? createOpencodeTaskSessionReader() : taskSessionReader;
+    let parentSessionId = initialParentSessionId;
+    let timer = null;
+    const childSessionByCallId = new Map();
+    const setParentSessionId = (sessionId) => {
+        const normalized = sessionId?.trim() || null;
+        if (!normalized || normalized === parentSessionId) {
+            return;
+        }
+        parentSessionId = normalized;
+        onParentSessionId?.(normalized);
+    };
+    const resolveChildSessions = (invocations, children) => {
+        const claimedSessionIds = new Set(childSessionByCallId.values());
+        for (const invocation of invocations) {
+            if (invocation.childSessionId) {
+                childSessionByCallId.set(invocation.callId, invocation.childSessionId);
+                claimedSessionIds.add(invocation.childSessionId);
+            }
+        }
+        const unmatchedInvocations = invocations.filter(invocation => !childSessionByCallId.has(invocation.callId));
+        const unmatchedChildren = children.filter(child => !claimedSessionIds.has(child.id));
+        for (const invocation of unmatchedInvocations) {
+            const description = invocation.label.replace(/^Subagent:\s*/i, '').toLowerCase();
+            const titleMatch = unmatchedChildren.find(child => child.title?.toLowerCase().includes(description));
+            if (!titleMatch) {
+                continue;
+            }
+            childSessionByCallId.set(invocation.callId, titleMatch.id);
+            claimedSessionIds.add(titleMatch.id);
+        }
+        const stillUnmatchedInvocations = unmatchedInvocations.filter(invocation => !childSessionByCallId.has(invocation.callId));
+        const stillUnmatchedChildren = unmatchedChildren.filter(child => !claimedSessionIds.has(child.id));
+        if (stillUnmatchedInvocations.length === 1 && stillUnmatchedChildren.length === 1) {
+            childSessionByCallId.set(stillUnmatchedInvocations[0].callId, stillUnmatchedChildren[0].id);
+        }
+    };
+    const refresh = () => {
+        if (!reader) {
+            return;
+        }
+        try {
+            if (!parentSessionId && discoverParentSession) {
+                setParentSessionId(reader.findParentSessionSince(spawnTimestamp));
+            }
+            if (!parentSessionId) {
+                return;
+            }
+            const invocations = reader.listTaskInvocations(parentSessionId, spawnTimestamp);
+            const children = reader.listChildSessions(parentSessionId, spawnTimestamp);
+            resolveChildSessions(invocations, children);
+            for (const invocation of invocations) {
+                const childSessionId = childSessionByCallId.get(invocation.callId) ?? invocation.childSessionId;
+                const transcript = childSessionId
+                    ? reconstructOpencodeSubagentTranscript(reader.listSessionParts(childSessionId), cwd)
+                    : { log: null, response: null };
+                tracker.applySnapshot({
+                    callId: invocation.callId,
+                    label: invocation.label,
+                    status: invocation.status,
+                    log: transcript.log,
+                    response: transcript.response ?? invocation.output,
+                    sessionId: childSessionId ?? null,
+                });
+            }
+        }
+        catch {
+            // OpenCode persistence is a progressive enhancement; stdout remains the fallback.
+        }
+    };
+    const start = () => {
+        if (!reader || timer) {
+            return;
+        }
+        refresh();
+        timer = setInterval(refresh, 150);
+        timer.unref?.();
+    };
+    const stop = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+        reader?.close();
+    };
+    return { refresh, setParentSessionId, start, stop };
 };
 const buildResponseTiming = ({ startTime, firstFinalAnswerTime, isStopped, }) => {
     if (!startTime) {
@@ -1265,6 +1841,21 @@ export const stopSpecReviewAgent = async (specReviewRunId) => {
 };
 export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = null, resumeSessionId = null, sessionField = 'session_id', trackBuildProcess = false, emitSuccessUpdate = true, opencodeAgentMode, runStream, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
+    const subagentTracker = createSubagentRunTracker({
+        parentType: 'ticket',
+        parentId: ticketId,
+        io: io,
+        ...(runStream
+            ? {
+                mainRun: {
+                    id: runStream.runId,
+                    label: runStream.label,
+                    role: runStream.role,
+                    runIndex: runStream.runIndex,
+                },
+            }
+            : {}),
+    });
     const writeRunStatus = (status, log, streamingResponse = null, options = {}) => {
         if (runStream) {
             updateAgentRunStatus(runStream.runId, status, log, streamingResponse);
@@ -1285,15 +1876,17 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
         if (runStream) {
             finalizeAgentRun(runStream.runId, status, responseText);
             emitAgentRunsUpdated(io, 'ticket', ticketId);
-            return;
+            return subagentTracker.finalize(status, log, responseText);
         }
         updateStatus(ticketId, status, log, io, responseText, options);
+        return subagentTracker.finalize(status, log, responseText);
     };
     return new Promise((resolve, reject) => {
         let sessionId = null;
         let spawnTimestamp = null;
         let sessionLookupTimer = null;
         let hasResolvedOpencodeSessionId = Boolean(resumeSessionId);
+        let opencodeSubagentMonitor = null;
         let settled = false;
         let startTime = null;
         let firstFinalAnswerTime = null;
@@ -1305,6 +1898,7 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 return;
             }
             settled = true;
+            opencodeSubagentMonitor?.stop();
             if (sessionLookupTimer) {
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
@@ -1362,6 +1956,23 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
             activeBuildProcesses.set(ticketId, buildState);
         }
         startTime = Date.now();
+        if (tool === 'opencode' && spawnTimestamp !== null) {
+            opencodeSubagentMonitor = createOpencodeSubagentMonitor({
+                initialParentSessionId: resumeSessionId,
+                spawnTimestamp,
+                cwd,
+                tracker: subagentTracker,
+                discoverParentSession: false,
+                onParentSessionId: discoveredSessionId => {
+                    if (hasResolvedOpencodeSessionId) {
+                        return;
+                    }
+                    hasResolvedOpencodeSessionId = true;
+                    writeRunSessionId(discoveredSessionId);
+                },
+            });
+            opencodeSubagentMonitor.start();
+        }
         if (tool === 'claude') {
             const logLines = [];
             const responseLines = [];
@@ -1377,7 +1988,8 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 remainder = lines.pop() ?? '';
                 for (const line of lines) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, line);
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(line, cwd);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(line, cwd);
+                    subagentTracker.handle(subagentEvents);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
                     }
@@ -1394,7 +2006,8 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 progressUpdater.cancel();
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(remainder, cwd);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(remainder, cwd);
+                    subagentTracker.handle(subagentEvents);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
                     }
@@ -1408,32 +2021,33 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 const modelError = isModelResolutionError(finalLog);
                 const timing = startTime ? { totalMs: Date.now() - startTime } : null;
                 if (buildState?.stopRequested) {
-                    finalizeRun('stopped', finalLog, finalResponse);
-                    resolveOnce({ response: finalResponse, responseTiming: timing, usageSnapshot });
+                    const transcriptRuns = finalizeRun('stopped', finalLog, finalResponse);
+                    resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing, usageSnapshot }, transcriptRuns));
                     return;
                 }
                 if (code === 0 && !modelError) {
-                    finalizeRun('done', finalLog, finalResponse, { emit: emitSuccessUpdate });
-                    resolveOnce({ response: finalResponse, responseTiming: timing, usageSnapshot });
+                    const transcriptRuns = finalizeRun('done', finalLog, finalResponse, { emit: emitSuccessUpdate });
+                    resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing, usageSnapshot }, transcriptRuns));
                     return;
                 }
-                finalizeRun('error', finalLog + (errOutput ? '\n\n' + errOutput : ''), finalResponse);
-                rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`));
+                const transcriptRuns = finalizeRun('error', finalLog + (errOutput ? '\n\n' + errOutput : ''), finalResponse);
+                rejectOnce(attachTranscriptRunsToError(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`), transcriptRuns));
             });
             child.on('error', err => {
                 progressUpdater.cancel();
                 if (buildState?.stopRequested) {
-                    finalizeRun('stopped', null, null);
-                    resolveOnce({ response: null, responseTiming: null, usageSnapshot });
+                    const transcriptRuns = finalizeRun('stopped', null, null);
+                    resolveOnce(withTranscriptRuns({ response: null, responseTiming: null, usageSnapshot }, transcriptRuns));
                     return;
                 }
-                finalizeRun('error', getErrorMessage(err), null);
-                rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+                const transcriptRuns = finalizeRun('error', getErrorMessage(err), null);
+                rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
             });
             return;
         }
         const logLines = [];
         const responseLines = [];
+        const recoveryTracker = createOpencodeRecoveryTracker();
         let remainder = '';
         const stderrChunks = [];
         const progressUpdater = createThrottledProgressUpdater(() => {
@@ -1459,12 +2073,12 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                         catch { /* best-effort timing */ }
                     }
                 }
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(line);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(line);
+                const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
                 if (logFragment !== null || responseFragment !== null) {
                     progressUpdater.schedule();
@@ -1489,31 +2103,35 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 sessionLookupTimer = null;
             }
             if (remainder.trim()) {
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(remainder);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(remainder);
+                const { subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
             }
             const stderrOutput = Buffer.concat(stderrChunks).toString();
+            opencodeSubagentMonitor?.refresh();
             const log = logLines.join('\n\n') || stderrOutput;
-            const finalResponse = responseLines.join('\n\n') || stderrOutput;
+            const recoveredResponse = recoveryTracker.getRecoveredResponse();
+            const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
+                ? recoveredResponse
+                : responseLines.join('\n\n') || stderrOutput;
             const modelError = isModelResolutionError(log);
             const timing = buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: Boolean(buildState?.stopRequested) });
             if (buildState?.stopRequested) {
-                finalizeRun('stopped', log, finalResponse);
-                resolveOnce({ response: finalResponse, responseTiming: timing });
+                const transcriptRuns = finalizeRun('stopped', log, finalResponse);
+                resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing }, transcriptRuns));
                 return;
             }
-            if (code === 0 && !modelError) {
-                finalizeRun('done', log, finalResponse, { emit: emitSuccessUpdate });
-                resolveOnce({ response: finalResponse, responseTiming: timing });
+            if (isSuccessfulOpencodeExit(code, modelError, recoveryTracker)) {
+                const transcriptRuns = finalizeRun('done', log, finalResponse, { emit: emitSuccessUpdate });
+                resolveOnce(withTranscriptRuns({ response: finalResponse, responseTiming: timing }, transcriptRuns));
                 return;
             }
-            finalizeRun('error', log, finalResponse);
-            rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`));
+            const transcriptRuns = finalizeRun('error', log, finalResponse);
+            rejectOnce(attachTranscriptRunsToError(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`), transcriptRuns));
         });
         child.on('error', err => {
             progressUpdater.cancel();
@@ -1522,21 +2140,27 @@ export const runAgent = ({ ticketId, tool, prompt, cwd, io, model, variant = nul
                 sessionLookupTimer = null;
             }
             if (buildState?.stopRequested) {
-                finalizeRun('stopped', null, null);
-                resolveOnce({ response: null, responseTiming: null });
+                const transcriptRuns = finalizeRun('stopped', null, null);
+                resolveOnce(withTranscriptRuns({ response: null, responseTiming: null }, transcriptRuns));
                 return;
             }
-            finalizeRun('error', getErrorMessage(err), null);
-            rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+            const transcriptRuns = finalizeRun('error', getErrorMessage(err), null);
+            rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
         });
     });
 };
 export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', }) => {
     const resolvedModel = resolveAgentModel(tool, model);
+    const subagentTracker = createSubagentRunTracker({
+        parentType: 'chat',
+        parentId: chatSessionId,
+        io,
+    });
     return new Promise((resolve, reject) => {
         let sessionId = null;
         let spawnTimestamp = null;
         let opencodeMetadataRefresher = null;
+        let opencodeSubagentMonitor = null;
         let settled = false;
         let startTime = null;
         let firstFinalAnswerTime = null;
@@ -1552,6 +2176,7 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
             }
             settled = true;
             opencodeMetadataRefresher?.stop();
+            opencodeSubagentMonitor?.stop();
             untrackChatProcess(chatSessionId, chatState);
             handler(value);
         };
@@ -1598,6 +2223,19 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
             writeClaudeStdin(child, buildClaudeStdinMessage(prompt, files, cwd));
         }
         startTime = Date.now();
+        if (tool === 'opencode' && spawnTimestamp !== null) {
+            opencodeSubagentMonitor = createOpencodeSubagentMonitor({
+                initialParentSessionId: resumeSessionId,
+                spawnTimestamp,
+                cwd,
+                tracker: subagentTracker,
+                discoverParentSession: false,
+                onParentSessionId: discoveredSessionId => {
+                    updateChatSessionId(chatSessionId, 'opencode', discoveredSessionId, io);
+                },
+            });
+            opencodeSubagentMonitor.start();
+        }
         if (tool === 'claude') {
             const logLines = [];
             const responseLines = [];
@@ -1611,7 +2249,8 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                 const lines = text.split('\n');
                 remainder = lines.pop() ?? '';
                 for (const line of lines) {
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(line);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(line);
+                    subagentTracker.handle(subagentEvents);
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, line);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
@@ -1629,7 +2268,8 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                 progressUpdater.cancel();
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(remainder);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(remainder);
+                    subagentTracker.handle(subagentEvents);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
                     }
@@ -1647,12 +2287,13 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                         response: finalResponse,
                     });
                     updateChatSessionStatus(chatSessionId, 'running', preservedOutput.log, io, preservedOutput.response);
-                    resolveOnce({
+                    const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput.log, preservedOutput.response);
+                    resolveOnce(withTranscriptRuns({
                         completionStatus: 'stopped',
                         finalResponse: preservedOutput.response,
                         usageSnapshot,
                         responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                    });
+                    }, transcriptRuns));
                     return;
                 }
                 const modelError = isModelResolutionError(finalLog);
@@ -1663,16 +2304,18 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                         response: finalResponse,
                     });
                     updateChatSessionStatus(chatSessionId, 'running', finalOutput.log, io, finalOutput.response);
-                    resolveOnce({
+                    const transcriptRuns = subagentTracker.finalize('done', finalOutput.log, finalOutput.response);
+                    resolveOnce(withTranscriptRuns({
                         completionStatus: 'done',
                         finalResponse: finalOutput.response,
                         usageSnapshot,
                         responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: false }),
-                    });
+                    }, transcriptRuns));
                     return;
                 }
                 updateChatSessionStatus(chatSessionId, 'error', finalLog + (errOutput ? '\n\n' + errOutput : ''), io, finalResponse);
-                rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`));
+                const transcriptRuns = subagentTracker.finalize('error', finalLog, finalResponse);
+                rejectOnce(attachTranscriptRunsToError(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`), transcriptRuns));
             });
             child.on('error', err => {
                 progressUpdater.cancel();
@@ -1685,21 +2328,24 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                         response,
                     });
                     updateChatSessionStatus(chatSessionId, 'running', preservedOutput.log, io, preservedOutput.response);
-                    resolveOnce({
+                    const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput.log, preservedOutput.response);
+                    resolveOnce(withTranscriptRuns({
                         completionStatus: 'stopped',
                         finalResponse: preservedOutput.response,
                         usageSnapshot,
                         responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                    });
+                    }, transcriptRuns));
                     return;
                 }
                 updateChatSessionStatus(chatSessionId, 'error', getErrorMessage(err), io);
-                rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+                const transcriptRuns = subagentTracker.finalize('error', getErrorMessage(err), null);
+                rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
             });
             return;
         }
         const logLines = [];
         const responseLines = [];
+        const recoveryTracker = createOpencodeRecoveryTracker();
         let remainder = '';
         const stderrChunks = [];
         const progressUpdater = createThrottledProgressUpdater(() => {
@@ -1726,12 +2372,12 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                         catch { /* best-effort timing */ }
                     }
                 }
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(line, cwd);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(line, cwd);
+                const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
                 if (logFragment !== null || responseFragment !== null) {
                     progressUpdater.schedule();
@@ -1746,17 +2392,20 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
             progressUpdater.cancel();
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(remainder, cwd);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(remainder, cwd);
+                const { subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
             }
             const stderrOutput = Buffer.concat(stderrChunks).toString();
             const log = logLines.join('\n\n') || stderrOutput;
-            const finalResponse = responseLines.join('\n\n') || stderrOutput;
+            const recoveredResponse = recoveryTracker.getRecoveredResponse();
+            const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
+                ? recoveredResponse
+                : responseLines.join('\n\n') || stderrOutput;
             const preservedOutput = chatState.stopRequested
                 ? getPreservedChatOutput({
                     chatSessionId,
@@ -1769,6 +2418,7 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                 ?? preservedOutput?.opencodeSessionId
                 ?? getChatSession(chatSessionId)?.opencode_session_id
                 ?? resumeSessionId;
+            opencodeSubagentMonitor?.refresh();
             if (chatState.stopRequested) {
                 if (resolvedOpencodeSessionId) {
                     usageSnapshot = resolveOpencodeUsageSnapshot({
@@ -1778,16 +2428,17 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                     });
                 }
                 updateChatSessionStatus(chatSessionId, 'running', preservedOutput?.log ?? null, io, preservedOutput?.response ?? null);
-                resolveOnce({
+                const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput?.log ?? null, preservedOutput?.response ?? null);
+                resolveOnce(withTranscriptRuns({
                     completionStatus: 'stopped',
                     finalResponse: preservedOutput?.response ?? null,
                     usageSnapshot,
                     responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                });
+                }, transcriptRuns));
                 return;
             }
             const modelError = isModelResolutionError(log);
-            if (code === 0 && !modelError) {
+            if (isSuccessfulOpencodeExit(code, modelError, recoveryTracker)) {
                 const finalOutput = getPreservedChatOutput({
                     chatSessionId,
                     log,
@@ -1801,16 +2452,18 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                     });
                 }
                 updateChatSessionStatus(chatSessionId, 'running', finalOutput.log, io, finalOutput.response);
-                resolveOnce({
+                const transcriptRuns = subagentTracker.finalize('done', finalOutput.log, finalOutput.response);
+                resolveOnce(withTranscriptRuns({
                     completionStatus: 'done',
                     finalResponse: finalOutput.response,
                     usageSnapshot,
                     responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: false }),
-                });
+                }, transcriptRuns));
                 return;
             }
             updateChatSessionStatus(chatSessionId, 'error', log, io, finalResponse);
-            rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`));
+            const transcriptRuns = subagentTracker.finalize('error', log, finalResponse);
+            rejectOnce(attachTranscriptRunsToError(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`), transcriptRuns));
         });
         child.on('error', err => {
             progressUpdater.cancel();
@@ -1823,25 +2476,33 @@ export const runChatAgent = ({ chatSessionId, tool, prompt, files = [], cwd, io,
                     response,
                 });
                 updateChatSessionStatus(chatSessionId, 'running', preservedOutput.log, io, preservedOutput.response);
-                resolveOnce({
+                const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput.log, preservedOutput.response);
+                resolveOnce(withTranscriptRuns({
                     completionStatus: 'stopped',
                     finalResponse: preservedOutput.response,
                     usageSnapshot,
                     responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                });
+                }, transcriptRuns));
                 return;
             }
             updateChatSessionStatus(chatSessionId, 'error', getErrorMessage(err), io);
-            rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+            const transcriptRuns = subagentTracker.finalize('error', getErrorMessage(err), null);
+            rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
         });
     });
 };
 export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, }) => {
     const resolvedModel = resolveAgentModel(tool, model);
+    const subagentTracker = createSubagentRunTracker({
+        parentType: 'spec',
+        parentId: specSessionId,
+        io,
+    });
     return new Promise((resolve, reject) => {
         let sessionId = null;
         let spawnTimestamp = null;
         let opencodeMetadataRefresher = null;
+        let opencodeSubagentMonitor = null;
         let settled = false;
         let startTime = null;
         let firstFinalAnswerTime = null;
@@ -1857,6 +2518,7 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
             }
             settled = true;
             opencodeMetadataRefresher?.stop();
+            opencodeSubagentMonitor?.stop();
             untrackSpecProcess(specSessionId, specState);
             handler(value);
         };
@@ -1903,6 +2565,19 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
             writeClaudeStdin(child, buildClaudeStdinMessage(prompt, files, cwd));
         }
         startTime = Date.now();
+        if (tool === 'opencode' && spawnTimestamp !== null) {
+            opencodeSubagentMonitor = createOpencodeSubagentMonitor({
+                initialParentSessionId: resumeSessionId,
+                spawnTimestamp,
+                cwd,
+                tracker: subagentTracker,
+                discoverParentSession: false,
+                onParentSessionId: discoveredSessionId => {
+                    updateSpecSessionIdLocal(specSessionId, 'opencode', discoveredSessionId, io);
+                },
+            });
+            opencodeSubagentMonitor.start();
+        }
         if (tool === 'claude') {
             const logLines = [];
             const responseLines = [];
@@ -1916,7 +2591,8 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                 const lines = text.split('\n');
                 remainder = lines.pop() ?? '';
                 for (const line of lines) {
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(line);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(line);
+                    subagentTracker.handle(subagentEvents);
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, line);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
@@ -1934,7 +2610,8 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                 progressUpdater.cancel();
                 if (remainder.trim()) {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                    const { logFragment, responseFragment } = parseClaudeStreamJsonLine(remainder);
+                    const { logFragment, responseFragment, subagentEvents } = parseClaudeStreamJsonLine(remainder);
+                    subagentTracker.handle(subagentEvents);
                     if (logFragment !== null) {
                         logLines.push(logFragment);
                     }
@@ -1952,12 +2629,13 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                         response: finalResponse,
                     });
                     updateSpecSessionStatusLocal(specSessionId, 'running', preservedOutput.log, io, preservedOutput.response);
-                    resolveOnce({
+                    const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput.log, preservedOutput.response);
+                    resolveOnce(withTranscriptRuns({
                         completionStatus: 'stopped',
                         finalResponse: preservedOutput.response,
                         usageSnapshot,
                         responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                    });
+                    }, transcriptRuns));
                     return;
                 }
                 const modelError = isModelResolutionError(finalLog);
@@ -1968,16 +2646,18 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                         response: finalResponse,
                     });
                     updateSpecSessionStatusLocal(specSessionId, 'running', finalOutput.log, io, finalOutput.response);
-                    resolveOnce({
+                    const transcriptRuns = subagentTracker.finalize('done', finalOutput.log, finalOutput.response);
+                    resolveOnce(withTranscriptRuns({
                         completionStatus: 'done',
                         finalResponse: finalOutput.response,
                         usageSnapshot,
                         responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: false }),
-                    });
+                    }, transcriptRuns));
                     return;
                 }
                 updateSpecSessionStatusLocal(specSessionId, 'error', finalLog + (errOutput ? '\n\n' + errOutput : ''), io, finalResponse);
-                rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`));
+                const transcriptRuns = subagentTracker.finalize('error', finalLog, finalResponse);
+                rejectOnce(attachTranscriptRunsToError(new Error(`Agent exited with code ${code ?? 'null'}\n${finalLog}${errOutput !== finalLog && errOutput ? '\n\n' + errOutput : ''}`), transcriptRuns));
             });
             child.on('error', err => {
                 progressUpdater.cancel();
@@ -1990,21 +2670,24 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                         response,
                     });
                     updateSpecSessionStatusLocal(specSessionId, 'running', preservedOutput.log, io, preservedOutput.response);
-                    resolveOnce({
+                    const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput.log, preservedOutput.response);
+                    resolveOnce(withTranscriptRuns({
                         completionStatus: 'stopped',
                         finalResponse: preservedOutput.response,
                         usageSnapshot,
                         responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                    });
+                    }, transcriptRuns));
                     return;
                 }
                 updateSpecSessionStatusLocal(specSessionId, 'error', getErrorMessage(err), io);
-                rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+                const transcriptRuns = subagentTracker.finalize('error', getErrorMessage(err), null);
+                rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
             });
             return;
         }
         const logLines = [];
         const responseLines = [];
+        const recoveryTracker = createOpencodeRecoveryTracker();
         let remainder = '';
         const stderrChunks = [];
         const progressUpdater = createThrottledProgressUpdater(() => {
@@ -2031,12 +2714,12 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                         catch { /* best-effort timing */ }
                     }
                 }
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(line, cwd);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(line, cwd);
+                const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
                 if (logFragment !== null || responseFragment !== null) {
                     progressUpdater.schedule();
@@ -2049,19 +2732,23 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
         }
         child.on('close', code => {
             progressUpdater.cancel();
+            opencodeSubagentMonitor?.refresh();
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(remainder, cwd);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(remainder, cwd);
+                const { subagentEvents, providerSessionId } = parsed;
+                opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                subagentTracker.handle(subagentEvents);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
             }
             const stderrOutput = Buffer.concat(stderrChunks).toString();
             const log = logLines.join('\n\n') || stderrOutput;
-            const finalResponse = responseLines.join('\n\n') || stderrOutput;
+            const recoveredResponse = recoveryTracker.getRecoveredResponse();
+            const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
+                ? recoveredResponse
+                : responseLines.join('\n\n') || stderrOutput;
             const preservedOutput = specState.stopRequested
                 ? getPreservedSpecOutput({
                     specSessionId,
@@ -2074,6 +2761,7 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                 ?? preservedOutput?.opencodeSessionId
                 ?? getSpecSession(specSessionId)?.opencode_session_id
                 ?? resumeSessionId;
+            opencodeSubagentMonitor?.refresh();
             if (specState.stopRequested) {
                 if (resolvedOpencodeSessionId) {
                     usageSnapshot = resolveOpencodeUsageSnapshot({
@@ -2083,16 +2771,17 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                     });
                 }
                 updateSpecSessionStatusLocal(specSessionId, 'running', preservedOutput?.log ?? null, io, preservedOutput?.response ?? null);
-                resolveOnce({
+                const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput?.log ?? null, preservedOutput?.response ?? null);
+                resolveOnce(withTranscriptRuns({
                     completionStatus: 'stopped',
                     finalResponse: preservedOutput?.response ?? null,
                     usageSnapshot,
                     responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                });
+                }, transcriptRuns));
                 return;
             }
             const modelError = isModelResolutionError(log);
-            if (code === 0 && !modelError) {
+            if (isSuccessfulOpencodeExit(code, modelError, recoveryTracker)) {
                 const finalOutput = getPreservedSpecOutput({
                     specSessionId,
                     log,
@@ -2106,16 +2795,18 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                     });
                 }
                 updateSpecSessionStatusLocal(specSessionId, 'running', finalOutput.log, io, finalOutput.response);
-                resolveOnce({
+                const transcriptRuns = subagentTracker.finalize('done', finalOutput.log, finalOutput.response);
+                resolveOnce(withTranscriptRuns({
                     completionStatus: 'done',
                     finalResponse: finalOutput.response,
                     usageSnapshot,
                     responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: false }),
-                });
+                }, transcriptRuns));
                 return;
             }
             updateSpecSessionStatusLocal(specSessionId, 'error', log, io, finalResponse);
-            rejectOnce(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`));
+            const transcriptRuns = subagentTracker.finalize('error', log, finalResponse);
+            rejectOnce(attachTranscriptRunsToError(new Error(`Agent exited with code ${code ?? 'null'}\n${log}${stderrOutput !== log && stderrOutput ? '\n\n' + stderrOutput : ''}`), transcriptRuns));
         });
         child.on('error', err => {
             progressUpdater.cancel();
@@ -2128,16 +2819,18 @@ export const runSpecAgent = ({ specSessionId, tool, prompt, files = [], cwd, io,
                     response,
                 });
                 updateSpecSessionStatusLocal(specSessionId, 'running', preservedOutput.log, io, preservedOutput.response);
-                resolveOnce({
+                const transcriptRuns = subagentTracker.finalize('stopped', preservedOutput.log, preservedOutput.response);
+                resolveOnce(withTranscriptRuns({
                     completionStatus: 'stopped',
                     finalResponse: preservedOutput.response,
                     usageSnapshot,
                     responseTiming: buildResponseTiming({ startTime, firstFinalAnswerTime, isStopped: true }),
-                });
+                }, transcriptRuns));
                 return;
             }
             updateSpecSessionStatusLocal(specSessionId, 'error', getErrorMessage(err), io);
-            rejectOnce(err instanceof Error ? err : new Error(getErrorMessage(err)));
+            const transcriptRuns = subagentTracker.finalize('error', getErrorMessage(err), null);
+            rejectOnce(attachTranscriptRunsToError(err, transcriptRuns));
         });
     });
 };
@@ -2269,6 +2962,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
         }
         const logLines = [];
         const responseLines = [];
+        const recoveryTracker = createOpencodeRecoveryTracker();
         let remainder = '';
         const stderrChunks = [];
         const progressUpdater = createThrottledProgressUpdater(() => {
@@ -2295,12 +2989,10 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                         catch { /* best-effort timing */ }
                     }
                 }
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(line, cwd);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(line, cwd);
+                const { logFragment, responseFragment } = parsed;
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
                 if (logFragment !== null || responseFragment !== null) {
                     progressUpdater.schedule();
@@ -2312,17 +3004,17 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
             progressUpdater.cancel();
             if (remainder.trim()) {
                 usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
-                const { logFragment, responseFragment } = parseOpencodeJsonLine(remainder, cwd);
-                if (logFragment !== null) {
-                    logLines.push(logFragment);
-                }
-                if (responseFragment !== null) {
-                    responseLines.push(responseFragment);
+                const parsed = parseOpencodeJsonLine(remainder, cwd);
+                if (appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker })) {
+                    firstFinalAnswerTime = null;
                 }
             }
             const stderrOutput = Buffer.concat(stderrChunks).toString();
             const log = logLines.join('\n\n') || stderrOutput;
-            const finalResponse = responseLines.join('\n\n') || stderrOutput;
+            const recoveredResponse = recoveryTracker.getRecoveredResponse();
+            const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
+                ? recoveredResponse
+                : responseLines.join('\n\n') || stderrOutput;
             if (reviewState.stopRequested) {
                 updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
                 resolveOnce({
@@ -2334,7 +3026,7 @@ export const runSpecReviewAgent = ({ specReviewRunId, tool, prompt, files = [],
                 return;
             }
             const modelError = isModelResolutionError(log);
-            if (code === 0 && !modelError) {
+            if (isSuccessfulOpencodeExit(code, modelError, recoveryTracker)) {
                 updateSpecReviewRunStreaming(specReviewRunId, finalResponse || null);
                 resolveOnce({
                     completionStatus: 'done',