@straiffi/archon 1.4.12 → 1.6.0

package/dist/server/workers/plan.js

@@ -5,14 +5,16 @@ import db from '../db.js';
 import config from '../lib/config.js';
 import { JiraApiError } from '../lib/integrations/jira.js';
 import { GitHubApiError } from '../lib/integrations/github.js';
+import { formatGenericToolCall } from '../lib/genericToolCall.js';
 import { PlanningReferenceError, resolveExternalPlanningDescription } from '../lib/integrations/planning.js';
 import { resolveExistingWorktreePath } from '../lib/git.js';
 import { normalizeModelId } from '../lib/models.js';
+import { parseOpencodeTaskEnvelope } from '../lib/opencodeTaskSessions.js';
 import { CLAUDE_NO_PLAN_FILE_DIRECTIVE, PLAN_MODE_QUESTION_TOOL_NAME } from '../lib/planModeQuestions.js';
 import { persistProjectMemorySuggestions } from '../lib/projectMemory.js';
 import { getProjectMemoryPromptBlock } from '../lib/projectMemoryPrompt.js';
 import { normalizeProjectMemorySuggestions, PROJECT_MEMORY_SUGGESTION_COMMON_RULE_LINES } from '../lib/projectMemorySuggestions.js';
-import { prependSkillPromptBlock } from '../lib/promptSkills.js';
+import { buildPlanningSubagentGuidancePromptBlock, prependSkillPromptBlock } from '../lib/promptSkills.js';
 import { registerBundleActivity, unregisterBundleActivity } from '../lib/bundleActivity.js';
 import { enqueue, isRunning } from '../lib/queue.js';
 import { getEffectiveProject, getProjectById, listLinkedProjects } from '../lib/projects.js';
@@ -21,7 +23,59 @@ import { IMPLEMENTATION_BODY_DEDUPLICATION_RULES, IMPLEMENTATION_DETAIL_RULES, I
 import { beginTicketThinkingRun, bindTicketThinkingMessage } from '../lib/thinkingState.js';
 import { createTicketMessage, upsertTicketDescriptionMessage } from '../lib/ticketMessages.js';
 import { getTicket, resolveTicketBranch, resolveTicketTool, resolveTicketWorkerKey } from '../lib/tickets.js';
-import { storeTicketUsageSnapshot, storeTicketUsageSnapshotDirect, mergeUsageFromJsonLine, EMPTY_CHAT_USAGE_SNAPSHOT } from '../lib/agent.js';
+import { createOpencodeSubagentMonitor, createSubagentRunTracker, formatAgentErrorForTranscript, getAgentErrorTranscriptRuns, storeTicketUsageSnapshot, storeTicketUsageSnapshotDirect, mergeUsageFromJsonLine, EMPTY_CHAT_USAGE_SNAPSHOT } from '../lib/agent.js';
+import { clearAndEmitAgentRunsForParent, createAgentRun, finalizeAgentRun, getNextAgentRunIndex } from '../lib/agentRuns.js';
+const createPlanningInvocation = (options, label, role) => {
+    const parentType = options.ticketId ? 'ticket' : options.projectId ? 'planning' : null;
+    const parentId = options.ticketId ?? options.projectId ?? null;
+    if (!parentType || !parentId) {
+        return null;
+    }
+    return {
+        parentType,
+        parentId,
+        runId: createAgentRun({
+            parentType,
+            parentId,
+            runIndex: getNextAgentRunIndex(parentType, parentId),
+            label,
+            role,
+        }),
+    };
+};
+const finalizePlanningInvocation = (invocation, status, response) => {
+    if (invocation) {
+        finalizeAgentRun(invocation.runId, status, response);
+    }
+};
+const createPlannerRecoveryTracker = () => {
+    let sawError = false;
+    let latestEvent = null;
+    let finalAnswerFragments = [];
+    return {
+        consume: (events) => {
+            let shouldResetResponse = false;
+            for (const event of events ?? []) {
+                latestEvent = event.type;
+                if (event.type === 'error') {
+                    sawError = true;
+                    finalAnswerFragments = [];
+                    shouldResetResponse = true;
+                    continue;
+                }
+                if (sawError) {
+                    finalAnswerFragments.push(event.text);
+                }
+            }
+            return shouldResetResponse;
+        },
+        hasRecoveredFinalAnswer: () => (sawError
+            && latestEvent === 'final_answer'
+            && finalAnswerFragments.length > 0),
+        hasUnrecoveredError: () => latestEvent === 'error',
+        getRecoveredResponse: () => finalAnswerFragments.join('\n\n'),
+    };
+};
 const extractLeadingJsonObject = (line) => {
     if (!line.startsWith('{')) {
         return null;
@@ -63,6 +117,43 @@ const extractLeadingJsonObject = (line) => {
     return null;
 };
 const normalizeToolName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+const isPlannerSubagentTool = (name) => {
+    const normalized = normalizeToolName(name);
+    return normalized === 'task' || normalized === 'subagent' || normalized === 'agent';
+};
+const getPlannerSubagentDescription = (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;
+            }
+        }
+    }
+    return fallback;
+};
+const stringifyPlannerToolResult = (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 emptyParsedPlannerStreamLine = () => ({
+    logFragment: null,
+    responseFragment: null,
+    subagentEvents: [],
+    providerSessionId: null,
+});
 const toPlannerInputPath = (input) => {
     if (typeof input?.filePath === 'string') {
         return input.filePath.trim();
@@ -117,26 +208,6 @@ const formatPlannerWriteToolCall = (input) => {
     lines.push('[[/archon-apply-patch]]');
     return lines.join('\n');
 };
-const formatPlannerGenericToolCall = (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];
-    const value = typeof explicitVal === 'string' && explicitVal.length > 0
-        ? explicitVal
-        : Object.values(input ?? {}).find(entry => typeof entry === 'string');
-    if (typeof value !== 'string' || value.length === 0) {
-        return `_${name}_`;
-    }
-    const display = value.length > 100 ? value.slice(0, 100) + '…' : value;
-    return `_${name}_ \`${display}\``;
-};
 const formatPlannerToolCall = (name, input) => {
     const normalized = normalizeToolName(name);
     if (normalized === 'edit') {
@@ -144,32 +215,46 @@ const formatPlannerToolCall = (name, input) => {
         if (formatted !== null) {
             return formatted;
         }
-        return formatPlannerGenericToolCall(name, input);
+        return formatGenericToolCall(name, input);
     }
     if (normalized === 'write') {
         const formatted = formatPlannerWriteToolCall(input);
         if (formatted !== null) {
             return formatted;
         }
-        return formatPlannerGenericToolCall(name, input);
+        return formatGenericToolCall(name, input);
     }
-    return formatPlannerGenericToolCall(name, input);
+    return formatGenericToolCall(name, input);
 };
 const parseClaudePlannerStreamJsonLine = (line) => {
     const trimmedLine = line.trim();
     if (!trimmedLine) {
-        return { logFragment: null, responseFragment: null };
+        return emptyParsedPlannerStreamLine();
     }
     let event;
     try {
         event = JSON.parse(trimmedLine);
     }
     catch {
-        return { logFragment: trimmedLine, responseFragment: trimmedLine };
+        const envelope = parseOpencodeTaskEnvelope(trimmedLine);
+        if (envelope) {
+            return {
+                ...emptyParsedPlannerStreamLine(),
+                subagentEvents: [{
+                        kind: 'complete',
+                        callId: null,
+                        sessionId: envelope.childSessionId,
+                        status: envelope.state?.toLowerCase() === 'error' || envelope.state?.toLowerCase() === 'failed' ? 'error' : 'done',
+                        ...(envelope.result ? { text: envelope.result } : {}),
+                    }],
+            };
+        }
+        return { ...emptyParsedPlannerStreamLine(), logFragment: trimmedLine, responseFragment: trimmedLine };
     }
     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();
@@ -180,15 +265,61 @@ const parseClaudePlannerStreamJsonLine = (line) => {
                 continue;
             }
             if (block.type === 'tool_use' && block.name) {
+                if (isPlannerSubagentTool(block.name)) {
+                    const description = getPlannerSubagentDescription(block.input, block.name);
+                    logParts.push(`Subagent: ${description}`);
+                    subagentEvents.push({
+                        kind: 'start',
+                        callId: block.id ?? null,
+                        label: `Subagent: ${description}`,
+                    });
+                    continue;
+                }
                 logParts.push(formatPlannerToolCall(block.name, block.input));
             }
         }
         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 && isPlannerSubagentTool(block.name)) {
+            const description = getPlannerSubagentDescription(block.input, block.name);
+            return {
+                ...emptyParsedPlannerStreamLine(),
+                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 = stringifyPlannerToolResult(block.content);
+            const envelope = parseOpencodeTaskEnvelope(rawText);
+            const text = envelope?.result ?? rawText;
+            const state = envelope?.state?.toLowerCase();
+            return [{
+                    kind: 'complete',
+                    callId: block.tool_use_id,
+                    status: block.is_error || state === 'error' || state === 'failed' ? 'error' : 'done',
+                    ...(text ? { text } : {}),
+                    ...(envelope ? { sessionId: envelope.childSessionId } : {}),
+                }];
+        });
+        return { ...emptyParsedPlannerStreamLine(), subagentEvents };
+    }
+    return emptyParsedPlannerStreamLine();
 };
 const formatPlannerOpencodeToolUse = (event) => {
     const toolName = event.part?.tool;
@@ -204,25 +335,48 @@ const formatPlannerStepTitle = (event) => {
 const parseOpencodePlannerJsonLine = (line) => {
     const trimmedLine = line.trim();
     if (!trimmedLine) {
-        return { logFragment: null, responseFragment: null };
+        return emptyParsedPlannerStreamLine();
     }
     const jsonLine = extractLeadingJsonObject(trimmedLine);
     if (!jsonLine) {
-        return { logFragment: trimmedLine, responseFragment: trimmedLine };
+        const envelope = parseOpencodeTaskEnvelope(trimmedLine);
+        if (envelope) {
+            return {
+                ...emptyParsedPlannerStreamLine(),
+                subagentEvents: [{
+                        kind: 'complete',
+                        callId: null,
+                        sessionId: envelope.childSessionId,
+                        status: envelope.state?.toLowerCase() === 'error' || envelope.state?.toLowerCase() === 'failed' ? 'error' : 'done',
+                        ...(envelope.result ? { text: envelope.result } : {}),
+                    }],
+            };
+        }
+        return { ...emptyParsedPlannerStreamLine(), logFragment: trimmedLine, responseFragment: trimmedLine };
     }
     let event;
     try {
         event = JSON.parse(jsonLine);
     }
     catch {
-        return { logFragment: trimmedLine, responseFragment: trimmedLine };
+        return { ...emptyParsedPlannerStreamLine(), logFragment: trimmedLine, responseFragment: trimmedLine };
     }
+    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') {
@@ -230,21 +384,88 @@ const parseOpencodePlannerJsonLine = (line) => {
         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 && isPlannerSubagentTool(toolName)) {
+            const description = getPlannerSubagentDescription(event.part?.state?.input, toolName);
+            const rawOutput = event.part?.state?.output?.trim();
+            const envelope = parseOpencodeTaskEnvelope(rawOutput);
+            const output = envelope?.result ?? rawOutput;
+            const taskStatus = event.part?.state?.status?.toLowerCase() ?? envelope?.state?.toLowerCase();
+            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: taskStatus === 'running' || taskStatus === 'pending' ? 'fragment' : 'complete',
+                                callId: event.part?.callID ?? null,
+                                text: output,
+                                sessionId: childSessionId,
+                                status: taskStatus === 'error' || taskStatus === 'failed' ? 'error' : 'done',
+                            }]
+                        : []),
+                ],
+                providerSessionId,
+            };
+        }
+        if (!isToolInvocation) {
+            return { ...emptyParsedPlannerStreamLine(), providerSessionId };
+        }
         return {
             logFragment: formatPlannerOpencodeToolUse(event),
             responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
         };
     }
     if (event.type === 'step_start') {
         return {
             logFragment: formatPlannerStepTitle(event),
             responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
+        };
+    }
+    if (event.type === 'error') {
+        const errorText = typeof event.error === 'string'
+            ? event.error.trim()
+            : event.error?.data?.message?.trim()
+                || event.error?.message?.trim()
+                || (event.error ? JSON.stringify(event.error) : '');
+        const text = event.part?.text?.trim() || errorText;
+        return {
+            logFragment: text ? `**Error:** ${text}` : null,
+            responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
+            recoveryEvents: [{ type: 'error' }],
         };
     }
-    return { logFragment: null, responseFragment: null };
+    return { ...emptyParsedPlannerStreamLine(), providerSessionId };
+};
+const attachPlannerTranscriptRuns = (error, transcriptRuns) => {
+    const resolvedError = (error instanceof Error ? error : new Error(String(error)));
+    if (transcriptRuns) {
+        resolvedError.transcriptRuns = transcriptRuns;
+    }
+    return resolvedError;
 };
 const stripSystemReminderBlocks = (output) => {
     return output.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim();
@@ -268,10 +489,10 @@ const PLANNING_QUESTIONS_RULES = [
     '- Return an empty `open_questions` array when the ticket is already clear enough to implement.',
 ].join('\n');
 const MEMORY_SUGGESTION_RULES = [
+    '- Prioritize explicit durable decisions established by the user.',
     ...PROJECT_MEMORY_SUGGESTION_COMMON_RULE_LINES,
     '- Do not suggest planner assumptions as project memory.',
-    '- Use the exact shape `{ "kind": "decision", "title": "...", "scope": "optional scope", "decision": "...", "rationale": "optional why", "implications": ["optional implication"] }` for decisions.',
-    '- Use the exact shape `{ "kind": "convention", "title": "...", "scope": "relevant area", "instruction": "...", "rationale": "optional why", "stages": ["build"], "priority": "normal" }` for conventions.',
+    '- Include structured applicability, evidence, and a create/update/supersede recommendation using the common suggestion contract.',
 ].join('\n');
 const getPlanningMemorySuggestionRules = (memoryEnabled) => {
     return memoryEnabled ? MEMORY_SUGGESTION_RULES : '';
@@ -439,6 +660,7 @@ const buildSingleTicketPrompt = (title, description, linkedResearchContext = '',
 
 This is a planning-only task.
 - You may inspect the repository and use read-only tools if helpful.
+${buildPlanningSubagentGuidancePromptBlock()}
 - Do not edit files or make changes.
 - Return a short natural-language planning update first, then the final JSON object on the last line.
 
@@ -497,6 +719,7 @@ This is pass 1 of 2. Your job is to decide the best ticket split and dependency
 
 This is a planning-only task.
 - You may inspect the repository and use read-only tools if helpful.
+${buildPlanningSubagentGuidancePromptBlock()}
 - Do not edit files or make changes.
 - Return only the final JSON object.
 
@@ -548,7 +771,7 @@ ${projectMemoryBlock ? `${projectMemoryBlock}
 
 ` : ''}
 ${linkedResearchContext}`;
-const buildPlanningAgentExpansionPrompt = (description, outline, linkedResearchContext = '', projectMemoryBlock = '', memoryEnabled = false) => `You are helping expand a previously decomposed software development initiative into implementation-ready tickets for a kanban board.
+const buildPlanningAgentExpansionPrompt = (description, outline, linkedResearchContext = '', projectMemoryBlock = '') => `You are helping expand a previously decomposed software development initiative into implementation-ready tickets for a kanban board.
 
 Each generated ticket will later be implemented by a separate AI agent, so every ticket description must be self-contained and implementation-ready without needing any further context or clarification.
 
@@ -556,6 +779,7 @@ This is pass 2 of 2. The ticket split and dependency graph are already decided.
 
 This is a planning-only task.
 - You may inspect the repository and use read-only tools if helpful.
+${buildPlanningSubagentGuidancePromptBlock()}
 - Do not edit files or make changes.
 - Return only the final JSON object.
 
@@ -566,7 +790,7 @@ Return ONLY a JSON object with this exact shape:
       "key": "short-kebab-key",
       "title": "Ticket title",
       "description": "Detailed markdown description",
-      "open_questions": ["Optional question"]${memoryEnabled ? ',\n      "memory_suggestions": []' : ''}
+      "open_questions": ["Optional question"]
     }
   ],
   "dependencies": [
@@ -604,8 +828,7 @@ ${IMPLEMENTATION_BODY_DEDUPLICATION_RULES}
 - Include those resources verbatim in the final ticket description instead of replacing them with vague summaries.
 - Clarification handling rules:
 ${PLANNING_QUESTIONS_RULES}
-- Memory suggestion rules:${getPlanningMemorySuggestionRules(memoryEnabled) ? `
-${getPlanningMemorySuggestionRules(memoryEnabled)}` : ' Omit memory suggestions entirely when project memory is disabled.'}
+- Do not return \`memory_suggestions\`. Multi-ticket expansion has no durable source record to own them.
 
 Example of the expected depth and structure for a single expanded ticket:
 ${EXPANDED_TICKET_EXAMPLE}
@@ -740,11 +963,19 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
         let resolvedSessionId = sessionTracking?.resumeSessionId ?? null;
         let lastStdoutAt = Date.now();
         let watchdogTimer = null;
+        const subagentTracker = options.agentRunParent
+            ? createSubagentRunTracker({
+                ...options.agentRunParent,
+                io: options.agentRunParent.io,
+            })
+            : null;
+        let opencodeSubagentMonitor = null;
         const resolveOnce = (value) => {
             if (settled) {
                 return;
             }
             settled = true;
+            opencodeSubagentMonitor?.stop();
             resolve(value);
         };
         const rejectOnce = (error) => {
@@ -752,6 +983,7 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 return;
             }
             settled = true;
+            opencodeSubagentMonitor?.stop();
             reject(error);
         };
         const clearWatchdogTimer = () => {
@@ -779,6 +1011,9 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
             }
             return hasResolvedSessionId;
         };
+        if (tool === 'opencode' && (sessionTracking || subagentTracker)) {
+            spawnTimestamp = Date.now();
+        }
         const child = spawn(cmd, args, {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, ...(cwd ? { PWD: cwd } : {}) },
@@ -789,7 +1024,6 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
             updatePlanningSessionId(sessionTracking.ticketId, sessionId, sessionTracking.io);
         }
         if (sessionTracking && tool === 'opencode') {
-            spawnTimestamp = Date.now();
             if (!sessionTracking.resumeSessionId) {
                 sessionLookupTimer = setTimeout(() => {
                     attemptOpencodeSessionLookup();
@@ -797,10 +1031,25 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 }, 1500);
             }
         }
+        if (subagentTracker && tool === 'opencode') {
+            spawnTimestamp = spawnTimestamp ?? Date.now();
+            opencodeSubagentMonitor = createOpencodeSubagentMonitor({
+                initialParentSessionId: sessionTracking?.resumeSessionId ?? null,
+                spawnTimestamp,
+                cwd: cwd ?? process.cwd(),
+                tracker: subagentTracker,
+                discoverParentSession: false,
+                onParentSessionId: discoveredSessionId => {
+                    resolvedSessionId = resolvedSessionId ?? discoveredSessionId;
+                },
+            });
+            opencodeSubagentMonitor.start();
+        }
         const stdoutChunks = [];
         const stderrChunks = [];
         const logLines = [];
         const responseLines = [];
+        const recoveryTracker = createPlannerRecoveryTracker();
         let usageSnapshot = EMPTY_CHAT_USAGE_SNAPSHOT;
         let remainder = '';
         let insideHiddenBlock = false;
@@ -839,9 +1088,18 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                         catch { /* best-effort timing */ }
                     }
                 }
-                const { logFragment, responseFragment } = tool === 'claude'
+                const parsedLine = tool === 'claude'
                     ? parseClaudePlannerStreamJsonLine(line)
                     : parseOpencodePlannerJsonLine(line);
+                const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsedLine;
+                if (tool === 'opencode' && recoveryTracker.consume(parsedLine.recoveryEvents)) {
+                    responseLines.length = 0;
+                    firstFinalAnswerTime = null;
+                }
+                subagentTracker?.handle(subagentEvents);
+                if (providerSessionId) {
+                    opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                }
                 if (isHiddenOpenTag.test(line)) {
                     insideHiddenBlock = true;
                 }
@@ -863,6 +1121,7 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
         child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
         child.on('close', code => {
             clearWatchdogTimer();
+            opencodeSubagentMonitor?.refresh();
             const resolvedSessionOnClose = attemptOpencodeSessionLookup();
             if (sessionLookupTimer && (resolvedSessionOnClose || hasResolvedSessionId)) {
                 clearTimeout(sessionLookupTimer);
@@ -872,9 +1131,18 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 if (tool === 'claude') {
                     usageSnapshot = mergeUsageFromJsonLine(usageSnapshot, remainder);
                 }
-                const { logFragment, responseFragment } = tool === 'claude'
+                const parsedLine = tool === 'claude'
                     ? parseClaudePlannerStreamJsonLine(remainder)
                     : parseOpencodePlannerJsonLine(remainder);
+                const { logFragment, responseFragment, subagentEvents, providerSessionId } = parsedLine;
+                if (tool === 'opencode' && recoveryTracker.consume(parsedLine.recoveryEvents)) {
+                    responseLines.length = 0;
+                    firstFinalAnswerTime = null;
+                }
+                subagentTracker?.handle(subagentEvents);
+                if (providerSessionId) {
+                    opencodeSubagentMonitor?.setParentSessionId(providerSessionId);
+                }
                 if (logFragment !== null) {
                     logLines.push(logFragment);
                 }
@@ -884,9 +1152,12 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 }
             }
             const rawOutput = Buffer.concat(stdoutChunks).toString().trim();
-            const output = tool === 'claude' && !rawOutput.startsWith('{')
-                ? rawOutput
-                : responseLines.join('\n\n').trim() || rawOutput;
+            const recoveredResponse = recoveryTracker.getRecoveredResponse();
+            const output = tool === 'opencode' && recoveryTracker.hasRecoveredFinalAnswer()
+                ? recoveredResponse
+                : tool === 'claude' && !rawOutput.startsWith('{')
+                    ? rawOutput
+                    : responseLines.join('\n\n').trim() || rawOutput;
             const errorOutput = Buffer.concat(stderrChunks).toString().trim();
             const timing = (() => {
                 const totalMs = Date.now() - startTime;
@@ -898,17 +1169,22 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 return { totalMs };
             })();
             if (hardTimeoutForced) {
-                rejectOnce(new Error(output || errorOutput || `Planner exceeded the ${PLANNER_HARD_TIMEOUT_MS} ms hard timeout.`));
+                const transcriptRuns = subagentTracker?.finalize('error', logLines.join('\n\n') || errorOutput || null, output || null) ?? null;
+                rejectOnce(attachPlannerTranscriptRuns(new Error(output || errorOutput || `Planner exceeded the ${PLANNER_HARD_TIMEOUT_MS} ms hard timeout.`), transcriptRuns));
                 return;
             }
-            if ((code === 0 || completionForced) && output) {
-                resolveOnce({ output, responseTiming: timing, usageSnapshot });
+            if (!recoveryTracker.hasUnrecoveredError()
+                && (code === 0 || completionForced || recoveryTracker.hasRecoveredFinalAnswer())
+                && output) {
+                const transcriptRuns = subagentTracker?.finalize('done', logLines.join('\n\n') || null, output) ?? null;
+                resolveOnce({ output, responseTiming: timing, usageSnapshot, transcriptRuns });
                 return;
             }
             const fallbackError = code === 0
                 ? 'Planner did not return a usable plan.'
                 : `Process exited with code ${code}`;
-            rejectOnce(new Error(output || errorOutput || fallbackError));
+            const transcriptRuns = subagentTracker?.finalize('error', logLines.join('\n\n') || errorOutput || null, output || null) ?? null;
+            rejectOnce(attachPlannerTranscriptRuns(new Error(output || errorOutput || fallbackError), transcriptRuns));
         });
         child.on('error', err => {
             clearWatchdogTimer();
@@ -916,7 +1192,8 @@ export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
             }
-            rejectOnce(err);
+            const transcriptRuns = subagentTracker?.finalize('error', err.message, null) ?? null;
+            rejectOnce(attachPlannerTranscriptRuns(err, transcriptRuns));
         });
         if (tool === 'opencode') {
             const runWatchdog = () => {
@@ -1227,14 +1504,17 @@ export const generatePlanText = (title, description, options = {}) => {
     const tool = options.tool ?? config.tool ?? 'opencode';
     const project = options.projectId ? getProjectById(options.projectId) : null;
     return (async () => {
+        const invocation = createPlanningInvocation(options, 'Ticket Planning', 'planning');
         const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(`${title}\n\n${description}`, options);
         const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
         const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+            flow: 'plan',
             stage: 'plan',
             title,
             description,
+            ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.runId } } : {}),
         });
-        const { output: plannerOutput, responseTiming: plannerTiming, usageSnapshot } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildSingleTicketPrompt(title, description, linkedResearchContext, projectMemoryBlock, Boolean(project?.memory_enabled)), options.skills ?? []), resolvePlannerCwd(project, options.branch), {
+        const { output: plannerOutput, responseTiming: plannerTiming, usageSnapshot, transcriptRuns } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildSingleTicketPrompt(title, description, linkedResearchContext, projectMemoryBlock, Boolean(project?.memory_enabled)), options.skills ?? []), resolvePlannerCwd(project, options.branch), {
             onProgress: options.onProgress,
             ...(options.ticketId && options.io
                 ? {
@@ -1243,51 +1523,87 @@ export const generatePlanText = (title, description, options = {}) => {
                         io: options.io,
                         resumeSessionId: options.planningSessionId,
                     },
+                    agentRunParent: {
+                        parentType: 'ticket',
+                        parentId: options.ticketId,
+                        io: options.io,
+                    },
                 }
                 : {}),
         });
-        const expanded = extractTaggedJsonObjectWithLeadingText(plannerOutput, PLAN_OUTPUT_TAG)
-            ?? extractFirstJsonObjectWithLeadingText(plannerOutput);
-        const expandedTicket = expanded.parsed.tickets.find(ticket => ticket.key === 'main-ticket');
-        if (!expandedTicket?.description?.trim()) {
-            throw new Error('Planner did not return a usable plan.');
+        try {
+            const expanded = extractTaggedJsonObjectWithLeadingText(plannerOutput, PLAN_OUTPUT_TAG)
+                ?? extractFirstJsonObjectWithLeadingText(plannerOutput);
+            const expandedTicket = expanded.parsed.tickets.find(ticket => ticket.key === 'main-ticket');
+            if (!expandedTicket?.description?.trim()) {
+                throw new Error('Planner did not return a usable plan.');
+            }
+            const result = {
+                ...normalizePlanningDraftTicket(expandedTicket),
+                key: 'main-ticket',
+                title: title.trim(),
+                description: expandedTicket.description.trim(),
+                response: expanded.before.trim(),
+                responseTiming: plannerTiming,
+                usageSnapshot,
+                transcriptRuns,
+            };
+            finalizePlanningInvocation(invocation, 'done', plannerOutput);
+            return result;
+        }
+        catch (error) {
+            finalizePlanningInvocation(invocation, 'error', plannerOutput);
+            throw attachPlannerTranscriptRuns(error, transcriptRuns ?? null);
         }
-        return {
-            ...normalizePlanningDraftTicket(expandedTicket),
-            key: 'main-ticket',
-            title: title.trim(),
-            description: expandedTicket.description.trim(),
-            response: expanded.before.trim(),
-            responseTiming: plannerTiming,
-            usageSnapshot,
-        };
     })();
 };
 export const generatePlanningTicketOutline = async (description, options = {}) => {
     const tool = options.tool ?? config.tool ?? 'opencode';
     const project = options.projectId ? getProjectById(options.projectId) : null;
+    const invocation = createPlanningInvocation(options, 'Planning Outline', 'planning-outline');
     const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
     const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
     const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+        flow: 'plan',
         stage: 'plan',
         title: description,
         description,
+        ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.runId } } : {}),
     });
     const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentOutlinePrompt(description, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch));
-    return extractFirstJsonObject(output);
+    try {
+        const result = extractFirstJsonObject(output);
+        finalizePlanningInvocation(invocation, 'done', output);
+        return result;
+    }
+    catch (error) {
+        finalizePlanningInvocation(invocation, 'error', output);
+        throw error;
+    }
 };
 export const expandPlanningTicketOutline = async (description, outline, options = {}) => {
     const tool = options.tool ?? config.tool ?? 'opencode';
     const project = options.projectId ? getProjectById(options.projectId) : null;
+    const invocation = createPlanningInvocation(options, 'Planning Expansion', 'planning-expansion');
     const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
     const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
     const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+        flow: 'plan',
         stage: 'plan',
         title: description,
         description,
+        ...(invocation ? { invocation: { parentType: invocation.parentType, parentId: invocation.parentId, agentRunId: invocation.runId } } : {}),
     });
-    const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentExpansionPrompt(description, outline, linkedResearchContext, projectMemoryBlock, Boolean(project?.memory_enabled)), options.skills ?? []), resolvePlannerCwd(project, options.branch));
-    return extractFirstJsonObject(output);
+    const { output } = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentExpansionPrompt(description, outline, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch));
+    try {
+        const result = extractFirstJsonObject(output);
+        finalizePlanningInvocation(invocation, 'done', output);
+        return result;
+    }
+    catch (error) {
+        finalizePlanningInvocation(invocation, 'error', output);
+        throw error;
+    }
 };
 const emitTicketUpdate = (ticketId, io) => {
     const updated = getTicket(ticketId);
@@ -1308,6 +1624,7 @@ export const startPlan = (ticket, io, options = {}) => {
         registerBundleActivity(ticket, 'plan');
         beginTicketThinkingRun(ticket.id);
         db.prepare('UPDATE tickets SET agent_status = ?, agent_log = NULL, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('running', ticket.id);
+        clearAndEmitAgentRunsForParent(io, 'ticket', ticket.id);
         emitTicketUpdate(ticket.id, io);
         try {
             const project = getEffectiveProject(ticket);
@@ -1356,7 +1673,7 @@ export const startPlan = (ticket, io, options = {}) => {
             const assistantMessage = buildPlanningAssistantMessage({
                 response: planned.response,
                 openQuestions: planned.open_questions,
-            });
+            }) || (planned.transcriptRuns?.length ? planned.description : '');
             if (assistantMessage) {
                 const messageId = createTicketMessage({
                     ticketId: ticket.id,
@@ -1364,14 +1681,19 @@ export const startPlan = (ticket, io, options = {}) => {
                     kind: 'planning_response',
                     content: assistantMessage,
                     responseTiming: planned.responseTiming,
+                    transcriptRuns: planned.transcriptRuns,
                 });
                 if (messageId) {
                     bindTicketThinkingMessage(ticket.id, messageId);
                 }
             }
+            if (planned.transcriptRuns) {
+                clearAndEmitAgentRunsForParent(io, 'ticket', ticket.id);
+            }
             emitTicketUpdate(ticket.id, io);
         }
         catch (err) {
+            const transcriptRuns = getAgentErrorTranscriptRuns(err);
             const message = err instanceof PlanningReferenceError
                 ? err.message
                 : err instanceof JiraApiError
@@ -1381,6 +1703,20 @@ export const startPlan = (ticket, io, options = {}) => {
                         : err instanceof Error
                             ? err.message
                             : String(err);
+            const errorContent = formatAgentErrorForTranscript(err);
+            let errorMessageId = null;
+            if (errorContent) {
+                errorMessageId = createTicketMessage({
+                    ticketId: ticket.id,
+                    role: 'assistant',
+                    kind: 'error',
+                    content: errorContent,
+                    transcriptRuns,
+                });
+            }
+            if (transcriptRuns && errorMessageId) {
+                clearAndEmitAgentRunsForParent(io, 'ticket', ticket.id);
+            }
             db.prepare('UPDATE tickets SET agent_status = ?, agent_log = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('error', message, ticket.id);
             emitTicketUpdate(ticket.id, io);
         }