@straiffi/archon 1.10.10 → 1.11.0

package/dist/server/lib/agent.js

@@ -3,15 +3,17 @@ import { randomUUID } from 'crypto';
 import { isAbsolute, relative, resolve, sep } from 'path';
 import db from '../db.js';
 import { getChatSession, updateChatSessionUsageSnapshot } from './chats.js';
-import { normalizeClaudeModelId, normalizeModelId } from './models.js';
+import { normalizeAgentModelId, requireExecutableAgent } from './agentCatalog.js';
 import { createOpencodeTaskSessionReader, parseOpencodeTaskEnvelope } from './opencodeTaskSessions.js';
 import { hostOpencodeSessionOperations } from './opencodeSessionOperations.js';
 import { hostExecutionEnvironment } from './hostExecutionEnvironment.js';
 import { markRetryableOpenCodeDatabaseLock, RetryableOpenCodeDatabaseLockError, retryOpenCodeDatabaseLocks } from './opencodeExecutionReliability.js';
 import { claudeAgentProvider } from './claudeAgentProvider.js';
+import { codexAgentProvider } from './codexAgentProvider.js';
+import { redactCodexDiagnostic } from './codexAppServer.js';
 import { buildOpencodeSpecReviewInvocation, createOpencodeExitError, createOpencodeRecoveryTracker, interpretOpencodeRecoveryEvent, isSuccessfulOpencodeExit, opencodeAgentProvider, } from './opencodeAgentProvider.js';
 import { appendClaudeHeadlessPlanPrompt, buildClaudeHeadlessPlanArgs } from './planModeQuestions.js';
-import { formatGenericToolCall } from './genericToolCall.js';
+import { formatCodexFileChange, formatCodexWebSearch, formatGenericToolCall } from './genericToolCall.js';
 import { getSpecSession, updateSpecSessionResumeId, updateSpecSessionStatus, updateSpecSessionTitle, updateSpecSessionUsageSnapshot } from './specs.js';
 import { updateSpecReviewRunStatus, updateSpecReviewRunStreaming, updateSpecReviewRunUsage } from './specReviews.js';
 import { createAgentRun, emitAgentRunsUpdated, emitExecutionAgentRunsUpdated, finalizeAgentRun, getNextAgentRunIndex, listAgentRunsForExecutionRun, listAgentRunsForParent, updateAgentRunLabel, updateAgentRunSessionId, updateAgentRunStatus } from './agentRuns.js';
@@ -34,7 +36,7 @@ export class AgentContinuationRejectedError extends Error {
     }
 }
 export const isAgentContinuationRejectedError = (error) => (error instanceof AgentContinuationRejectedError);
-const isTypedPreExecutionContinuationRejection = (message) => (/(?:session|conversation).*(?:not found|does not exist|invalid|expired)|(?:invalid|unknown).*(?:session|conversation)/i.test(message));
+export const isTypedPreExecutionContinuationRejection = (message) => (/(?:session|conversation|thread).*(?:not found|does not exist|invalid|expired)|(?:invalid|unknown).*(?:session|conversation|thread)|no rollout found for thread id/i.test(message));
 const attachTranscriptRunsToError = (error, transcriptRuns) => {
     const resolvedError = (error instanceof Error ? error : new Error(String(error)));
     if (transcriptRuns) {
@@ -53,10 +55,20 @@ const OPENCODE_SESSION_METADATA_LOOKUP_DELAY_MS = 1500;
 const AGENT_PROGRESS_UPDATE_INTERVAL_MS = 100;
 const OPENCODE_SUBAGENT_POLL_INTERVAL_MS = 750;
 const resolveAgentModel = (tool, model) => {
+    return normalizeAgentModelId(tool, model) || null;
+};
+const getStreamingAgentProvider = (tool) => {
     if (tool === 'claude') {
-        return normalizeClaudeModelId(model) || null;
+        return claudeAgentProvider;
+    }
+    if (tool === 'codex') {
+        return codexAgentProvider;
     }
-    return normalizeModelId(model) || null;
+    return opencodeAgentProvider;
+};
+const getAgentStderr = (tool, chunks) => {
+    const stderr = Buffer.concat(chunks).toString();
+    return tool === 'codex' ? redactCodexDiagnostic(stderr) : stderr;
 };
 const writeClaudeStdin = (child, message) => {
     const stdin = child.stdin;
@@ -358,7 +370,11 @@ const updateChatSessionStatus = (chatSessionId, status, log, io, streamingRespon
     }
 };
 const updateChatSessionId = (chatSessionId, tool, sessionId, io) => {
-    const sessionField = tool === 'claude' ? 'claude_session_id' : 'opencode_session_id';
+    const sessionField = tool === 'claude'
+        ? 'claude_session_id'
+        : tool === 'codex'
+            ? 'codex_session_id'
+            : 'opencode_session_id';
     db.prepare(`UPDATE chat_sessions SET ${sessionField} = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?`).run(sessionId, chatSessionId);
     const chatSession = getChatSession(chatSessionId, { includeMessages: true });
     if (chatSession) {
@@ -787,6 +803,16 @@ const formatToolCall = (name, input, cwd) => {
         return formatApplyPatchToolCall(input, cwd);
     }
     const normalized = normalizeToolName(name);
+    if (normalized === 'filechange') {
+        const formatted = formatCodexFileChange(input, cwd);
+        if (formatted !== null) {
+            return formatted;
+        }
+        return formatGenericToolCall(name, input);
+    }
+    if (normalized === 'websearch') {
+        return formatCodexWebSearch(input);
+    }
     if (normalized === 'edit') {
         const formatted = formatEditToolCall(input, cwd);
         if (formatted !== null) {
@@ -836,7 +862,10 @@ const stringifyToolResult = (content) => {
 };
 const getSubagentCompletionStatus = (state, isError = false) => {
     const normalizedState = state?.toLowerCase();
-    return isError || normalizedState === 'failed' || normalizedState === 'error' ? 'error' : 'done';
+    if (isError || normalizedState === 'failed' || normalizedState === 'error') {
+        return 'error';
+    }
+    return normalizedState === 'stopped' ? 'stopped' : 'done';
 };
 const emptyParsedStreamLine = () => ({
     logFragment: null,
@@ -961,8 +990,23 @@ const parseOpencodeJsonEvent = (event, cwd) => {
         || event.part?.sessionID?.trim()
         || event.part?.sessionId?.trim()
         || null;
+    if (event.type === 'plan' && event.part?.type === 'text' && event.part.text) {
+        return {
+            logFragment: event.part.text,
+            responseFragment: null,
+            subagentEvents: [],
+            providerSessionId,
+            modelResolutionError: false,
+            concatenateFragments: event.part.metadata?.codex?.delta === true,
+            replaceFragment: event.part.metadata?.codex?.snapshot === true,
+            fragmentGroup: event.part.metadata?.codex?.fragmentGroup
+                ?? event.part.metadata?.codex?.itemId
+                ?? null,
+        };
+    }
     if (event.type === 'text' && event.part?.type === 'text' && event.part.text) {
-        const text = event.part.text.trim();
+        const concatenateFragments = event.part.metadata?.codex?.delta === true;
+        const text = concatenateFragments ? event.part.text : event.part.text.trim();
         const phase = event.part.metadata?.openai?.phase;
         const recoveryEvent = interpretOpencodeRecoveryEvent(event.type, event.error, text, phase);
         return {
@@ -972,16 +1016,25 @@ const parseOpencodeJsonEvent = (event, cwd) => {
             providerSessionId,
             modelResolutionError: false,
             recoveryEvents: recoveryEvent ? [recoveryEvent] : [],
+            concatenateFragments,
+            fragmentGroup: event.part.metadata?.codex?.fragmentGroup
+                ?? event.part.metadata?.codex?.itemId
+                ?? null,
         };
     }
     if (event.type === 'reasoning' && event.part?.type === 'reasoning') {
-        const text = event.part.text?.trim() ?? '';
+        const concatenateFragments = event.part.metadata?.codex?.delta === true;
+        const text = concatenateFragments ? event.part.text ?? '' : event.part.text?.trim() ?? '';
         return {
             logFragment: text || null,
             responseFragment: null,
             subagentEvents: [],
             providerSessionId,
             modelResolutionError: false,
+            concatenateFragments,
+            fragmentGroup: event.part.metadata?.codex?.fragmentGroup
+                ?? event.part.metadata?.codex?.itemId
+                ?? null,
         };
     }
     if (event.type === 'tool' || event.type === 'tool_use' || event.type === 'tool_result') {
@@ -993,8 +1046,9 @@ const parseOpencodeJsonEvent = (event, cwd) => {
             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 isTerminal = Boolean(taskStatus && taskStatus !== 'running' && taskStatus !== 'pending');
+            const outputKind = isTerminal ? 'complete' : 'fragment';
+            const completionStatus = getSubagentCompletionStatus(taskStatus);
             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);
@@ -1010,11 +1064,11 @@ const parseOpencodeJsonEvent = (event, cwd) => {
                                 sessionId: childSessionId,
                             }]
                         : []),
-                    ...(output
+                    ...(output || isTerminal
                         ? [{
                                 kind: outputKind,
                                 callId: event.part?.callID ?? null,
-                                text: output,
+                                ...(output ? { text: output } : {}),
                                 sessionId: childSessionId,
                                 status: completionStatus,
                             }]
@@ -1099,6 +1153,9 @@ const parseOpencodeJsonLine = (line, cwd) => {
     const recoveryEvents = [];
     let providerSessionId = null;
     let modelResolutionError = false;
+    let concatenateFragments;
+    let replaceFragment;
+    let fragmentGroup;
     for (const jsonObject of jsonObjects) {
         let event;
         try {
@@ -1113,6 +1170,11 @@ const parseOpencodeJsonLine = (line, cwd) => {
         recoveryEvents.push(...(parsedEvent.recoveryEvents ?? []));
         modelResolutionError ||= Boolean(parsedEvent.modelResolutionError);
         providerSessionId = providerSessionId ?? parsedEvent.providerSessionId;
+        if (jsonObjects.length === 1) {
+            concatenateFragments = parsedEvent.concatenateFragments;
+            replaceFragment = parsedEvent.replaceFragment;
+            fragmentGroup = parsedEvent.fragmentGroup;
+        }
         if (logFragment !== null) {
             logFragments.push(logFragment);
         }
@@ -1144,6 +1206,9 @@ const parseOpencodeJsonLine = (line, cwd) => {
             providerSessionId,
             modelResolutionError,
             recoveryEvents,
+            concatenateFragments,
+            replaceFragment,
+            fragmentGroup,
         };
     }
     return emptyParsedStreamLine();
@@ -1155,16 +1220,49 @@ const appendTranscriptText = (current, fragment) => {
     }
     return current ? `${current}\n\n${trimmed}` : trimmed;
 };
+const concatenatingLogLines = new WeakMap();
+const concatenatingResponseLines = new WeakMap();
+const groupedLogLineIndexes = new WeakMap();
+const groupedResponseLineIndexes = new WeakMap();
+const appendGroupedFragment = (lines, fragment, group, concatenate, replace, activeGroups, indexesByGroup) => {
+    const groupKey = group ?? null;
+    const indexes = indexesByGroup.get(lines) ?? new Map();
+    if (replace && group) {
+        const index = indexes.get(group);
+        if (index !== undefined) {
+            lines[index] = fragment;
+        }
+        else {
+            indexes.set(group, lines.push(fragment) - 1);
+        }
+    }
+    else if (concatenate && activeGroups.get(lines) === groupKey && lines.length > 0) {
+        lines[lines.length - 1] += fragment;
+    }
+    else {
+        const index = lines.push(fragment) - 1;
+        if (group) {
+            indexes.set(group, index);
+        }
+    }
+    indexesByGroup.set(lines, indexes);
+    if (concatenate) {
+        activeGroups.set(lines, groupKey);
+    }
+    else {
+        activeGroups.delete(lines);
+    }
+};
 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);
+        appendGroupedFragment(logLines, parsed.logFragment, parsed.fragmentGroup, parsed.concatenateFragments, parsed.replaceFragment, concatenatingLogLines, groupedLogLineIndexes);
     }
     if (parsed.responseFragment !== null) {
-        responseLines.push(parsed.responseFragment);
+        appendGroupedFragment(responseLines, parsed.responseFragment, parsed.fragmentGroup, parsed.concatenateFragments, parsed.replaceFragment, concatenatingResponseLines, groupedResponseLineIndexes);
     }
     return shouldResetResponse;
 };
@@ -1360,6 +1458,9 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, ex
                 run_index: run.runIndex,
                 label: run.label,
                 role: 'subagent',
+                tool: persistedRun?.tool,
+                model: persistedRun?.model,
+                variant: persistedRun?.variant,
                 agent_status: run.status,
                 agent_log: run.log || null,
                 streaming_response: null,
@@ -1388,6 +1489,9 @@ export const createSubagentRunTracker = ({ parentType, parentId, io, mainRun, ex
                 run_index: mainRun.runIndex,
                 label: mainRun.label,
                 role: mainRun.role,
+                tool: persistedMainRun?.tool,
+                model: persistedMainRun?.model,
+                variant: persistedMainRun?.variant,
                 agent_status: status,
                 agent_log: parentLog,
                 streaming_response: null,
@@ -1935,7 +2039,7 @@ export const stopSpecReviewAgent = async (specReviewRunId) => {
     }
     return true;
 };
-const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null, resumeSessionId = null, sessionField = 'session_id', trackBuildProcess = false, reviewProcessState, emitSuccessUpdate = true, opencodeAgentMode, runStream, executionContext, persistSessionIdToTicket = false, spawnPermitId, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
+const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null, skills = [], resumeSessionId = null, sessionField = 'session_id', trackBuildProcess = false, reviewProcessState, emitSuccessUpdate = true, opencodeAgentMode, runStream, executionContext, persistSessionIdToTicket = false, spawnPermitId, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const opencodeSessionOperations = executionProvider.sessionOperations?.opencode ?? null;
     const subagentTracker = createSubagentRunTracker({
@@ -2067,18 +2171,18 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
             }
             return hasResolvedOpencodeSessionId;
         };
-        const agentProvider = tool === 'claude'
-            ? claudeAgentProvider
-            : opencodeAgentProvider;
-        const invocation = agentProvider.buildStreamingInvocation({
+        const agentProvider = getStreamingAgentProvider(tool);
+        const streamingRequest = {
             cwd,
+            skills,
             prompt,
             model: resolvedModel,
             variant,
             mode: opencodeAgentMode,
             resumeSessionId,
             sessionId: randomUUID(),
-        });
+        };
+        const invocation = agentProvider.buildStreamingInvocation(streamingRequest);
         sessionId = invocation.sessionId;
         writeRunStatus('running', null);
         if (tool === 'claude' && sessionId) {
@@ -2088,6 +2192,7 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
             spawnTimestamp = Date.now();
         }
         let child;
+        let providerStdout = null;
         let interrupt;
         let placementFailure;
         let placementCompletion = Promise.resolve(null);
@@ -2115,6 +2220,31 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
             if (handle.placementIdentity) {
                 placementCompletion = placementFailure;
             }
+            const connection = agentProvider.connectStreamingInvocation?.(child, streamingRequest, {
+                runtimeEnvironmentKind: executionRuntimeEnvironment.kind,
+            });
+            if (connection) {
+                providerStdout = connection.stdout;
+                const placementInterrupt = interrupt;
+                interrupt = async (signal) => {
+                    if (signal === 'SIGKILL') {
+                        await placementInterrupt(signal);
+                        return;
+                    }
+                    try {
+                        await connection.interrupt();
+                    }
+                    catch {
+                        await placementInterrupt(signal);
+                    }
+                };
+                void connection.sessionReady.then(providerThreadId => {
+                    if (!settled && providerThreadId) {
+                        sessionId = providerThreadId;
+                        writeRunSessionId(providerThreadId);
+                    }
+                }).catch(() => { });
+            }
         }
         catch (error) {
             const resolvedError = agentProvider.classifyExecutionFailure(error);
@@ -2219,7 +2349,7 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                         responseLines.push(responseFragment);
                     }
                 }
-                const errOutput = Buffer.concat(stderrChunks).toString();
+                const errOutput = getAgentStderr(tool, stderrChunks);
                 const finalLog = logLines.join('\n\n') || errOutput;
                 const finalResponse = responseLines.join('\n\n') || errOutput;
                 const modelError = isLegacyModelResolutionError(errOutput);
@@ -2285,7 +2415,8 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 },
             });
         }
-        child.stdout?.on('data', (chunk) => {
+        const output = providerStdout ?? child.stdout;
+        output?.on('data', (chunk) => {
             lastOutputAt = Date.now();
             const text = remainder + chunk.toString();
             const lines = text.split('\n');
@@ -2395,7 +2526,7 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 clearTimeout(sessionLookupTimer);
                 sessionLookupTimer = null;
             }
-            const stderrOutput = Buffer.concat(stderrChunks).toString();
+            const stderrOutput = getAgentStderr(tool, stderrChunks);
             const log = logLines.join('\n\n') || persistedTranscript?.log || stderrOutput;
             const recoveredResponse = recoveryTracker.getRecoveredResponse();
             const streamedResponse = recoveryTracker.hasRecoveredFinalAnswer()
@@ -2463,7 +2594,7 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
                 subagentTracker.handle(parsed.subagentEvents);
                 appendOpencodeTranscriptLine({ parsed, logLines, responseLines, recoveryTracker });
             }
-            const stderrOutput = Buffer.concat(stderrChunks).toString();
+            const stderrOutput = getAgentStderr(tool, stderrChunks);
             const log = logLines.join('\n\n') || stderrOutput;
             const response = recoveryTracker.hasRecoveredFinalAnswer()
                 ? recoveryTracker.getRecoveredResponse()
@@ -2490,10 +2621,11 @@ const runAgentOnce = ({ ticketId, tool, prompt, cwd, io, model, variant = null,
     });
 };
 export const runAgent = (options) => {
+    requireExecutableAgent(options.tool);
     const run = () => runAgentOnce(options);
     return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
 };
-const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, opencodeAgentMode = 'build', executionContext, mainRun, spawnPermitId, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
+const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, model, variant = null, skills = [], resumeSessionId = null, opencodeAgentMode = 'build', executionContext, mainRun, spawnPermitId, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const opencodeSessionOperations = executionProvider.sessionOperations?.opencode ?? null;
     const subagentTracker = createSubagentRunTracker({
@@ -2537,19 +2669,19 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             }, transcriptRuns));
             return;
         }
-        const agentProvider = tool === 'claude'
-            ? claudeAgentProvider
-            : opencodeAgentProvider;
-        const invocation = agentProvider.buildStreamingInvocation({
+        const agentProvider = getStreamingAgentProvider(tool);
+        const streamingRequest = {
             cwd,
             files,
+            skills,
             prompt,
             model: resolvedModel,
             variant,
             mode: opencodeAgentMode,
             resumeSessionId,
             sessionId: randomUUID(),
-        });
+        };
+        const invocation = agentProvider.buildStreamingInvocation(streamingRequest);
         sessionId = invocation.sessionId;
         updateChatSessionStatus(chatSessionId, 'running', null, io);
         subagentTracker.updateMain(null, null);
@@ -2580,6 +2712,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             }
         }
         let child;
+        let providerStdout = null;
         let placementCompletion;
         try {
             if (chatState.stopRequested) {
@@ -2602,6 +2735,32 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             child = handle.child;
             chatState.interrupt = handle.interrupt;
             placementCompletion = handle.placementFailure;
+            const connection = agentProvider.connectStreamingInvocation?.(child, streamingRequest, {
+                runtimeEnvironmentKind: executionRuntimeEnvironment.kind,
+            });
+            if (connection) {
+                providerStdout = connection.stdout;
+                const placementInterrupt = handle.interrupt;
+                chatState.interrupt = async (signal) => {
+                    if (signal === 'SIGKILL') {
+                        await placementInterrupt(signal);
+                        return;
+                    }
+                    try {
+                        await connection.interrupt();
+                    }
+                    catch {
+                        await placementInterrupt(signal);
+                    }
+                };
+                void connection.sessionReady.then(providerThreadId => {
+                    if (!settled && providerThreadId) {
+                        sessionId = providerThreadId;
+                        updateChatSessionId(chatSessionId, 'codex', providerThreadId, io);
+                        subagentTracker.setMainSessionId(providerThreadId);
+                    }
+                }).catch(() => { });
+            }
         }
         catch (error) {
             const resolvedError = agentProvider.classifyExecutionFailure(error);
@@ -2696,7 +2855,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                         responseLines.push(responseFragment);
                     }
                 }
-                const errOutput = Buffer.concat(stderrChunks).toString();
+                const errOutput = getAgentStderr(tool, stderrChunks);
                 const finalLog = logLines.join('\n\n') || errOutput;
                 const finalResponse = responseLines.join('\n\n') || errOutput;
                 if (chatState.stopRequested) {
@@ -2777,7 +2936,8 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
             updateChatSessionStatus(chatSessionId, 'running', log, io, response);
             subagentTracker.updateMain(log, response);
         });
-        child.stdout?.on('data', (chunk) => {
+        const output = providerStdout ?? child.stdout;
+        output?.on('data', (chunk) => {
             const text = remainder + chunk.toString();
             const lines = text.split('\n');
             remainder = lines.pop() ?? '';
@@ -2836,7 +2996,7 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
                     firstFinalAnswerTime = null;
                 }
             }
-            const stderrOutput = Buffer.concat(stderrChunks).toString();
+            const stderrOutput = getAgentStderr(tool, stderrChunks);
             const log = logLines.join('\n\n') || stderrOutput;
             const recoveredResponse = recoveryTracker.getRecoveredResponse();
             const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
@@ -2941,10 +3101,11 @@ const runChatAgentOnce = ({ chatSessionId, tool, prompt, files = [], cwd, io, mo
     });
 };
 export const runChatAgent = (options) => {
+    requireExecutableAgent(options.tool);
     const run = () => runChatAgentOnce(options);
     return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
 };
-const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, resumeSessionId = null, executionContext, mainRun, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
+const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, skills = [], resumeSessionId = null, executionContext, mainRun, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const resolvedModel = resolveAgentModel(tool, model);
     const subagentTracker = createSubagentRunTracker({
         parentType: 'spec',
@@ -2987,15 +3148,20 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
             }, transcriptRuns));
             return;
         }
-        const [cmd, args] = tool === 'claude'
-            ? (() => {
-                sessionId = resumeSessionId || randomUUID();
-                return [
-                    'claude',
-                    buildClaudeArgs('plan', resolvedModel, resumeSessionId, sessionId),
-                ];
-            })()
-            : ['opencode', ['run', '--agent', 'plan', '--format', 'json', '--thinking', ...(resumeSessionId ? ['--session', resumeSessionId] : []), ...(resolvedModel ? ['--model', resolvedModel] : []), ...(variant ? ['--variant', variant] : []), ...files.flatMap(filePath => ['--file', filePath]), ...(files.length > 0 ? ['--'] : []), prompt]];
+        const agentProvider = getStreamingAgentProvider(tool);
+        const streamingRequest = {
+            cwd,
+            files,
+            skills,
+            prompt,
+            model: resolvedModel,
+            variant,
+            mode: 'plan',
+            resumeSessionId,
+            sessionId: randomUUID(),
+        };
+        const invocation = agentProvider.buildStreamingInvocation(streamingRequest);
+        sessionId = invocation.sessionId;
         updateSpecSessionStatusLocal(specSessionId, 'running', null, io);
         subagentTracker.updateMain(null, null);
         if (tool === 'claude' && sessionId) {
@@ -3024,15 +3190,16 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
             }
         }
         let child;
+        let providerStdout = null;
         let placementFailure = Promise.resolve(null);
         try {
             const handle = executionProvider.execute({
                 phase: 'agent',
                 target: executionTarget ?? null,
-                command: cmd,
-                args,
+                command: invocation.command,
+                args: invocation.args,
                 cwd,
-                stdio: tool === 'claude' ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+                stdio: invocation.stdio,
                 launcherEnvironment: executionLauncherEnvironment,
                 runtimeEnvironment: executionRuntimeEnvironment,
                 detached: process.platform !== 'win32',
@@ -3040,6 +3207,32 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
             child = handle.child;
             specState.interrupt = handle.interrupt;
             placementFailure = handle.placementFailure;
+            const connection = agentProvider.connectStreamingInvocation?.(child, streamingRequest, {
+                runtimeEnvironmentKind: executionRuntimeEnvironment.kind,
+            });
+            if (connection) {
+                providerStdout = connection.stdout;
+                const placementInterrupt = handle.interrupt;
+                specState.interrupt = async (signal) => {
+                    if (signal === 'SIGKILL') {
+                        await placementInterrupt(signal);
+                        return;
+                    }
+                    try {
+                        await connection.interrupt();
+                    }
+                    catch {
+                        await placementInterrupt(signal);
+                    }
+                };
+                void connection.sessionReady.then(providerThreadId => {
+                    if (!settled && providerThreadId) {
+                        sessionId = providerThreadId;
+                        updateSpecSessionIdLocal(specSessionId, 'codex', providerThreadId, io);
+                        subagentTracker.setMainSessionId(providerThreadId);
+                    }
+                }).catch(() => { });
+            }
             void placementFailure.then(failure => {
                 if (failure) {
                     rejectOnce(failure);
@@ -3129,7 +3322,7 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
                         responseLines.push(responseFragment);
                     }
                 }
-                const errOutput = Buffer.concat(stderrChunks).toString();
+                const errOutput = getAgentStderr(tool, stderrChunks);
                 const finalLog = logLines.join('\n\n') || errOutput;
                 const finalResponse = responseLines.join('\n\n') || errOutput;
                 if (specState.stopRequested) {
@@ -3210,7 +3403,8 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
             updateSpecSessionStatusLocal(specSessionId, 'running', log, io, response);
             subagentTracker.updateMain(log, response);
         });
-        child.stdout?.on('data', (chunk) => {
+        const output = providerStdout ?? child.stdout;
+        output?.on('data', (chunk) => {
             const text = remainder + chunk.toString();
             const lines = text.split('\n');
             remainder = lines.pop() ?? '';
@@ -3271,7 +3465,7 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
                     firstFinalAnswerTime = null;
                 }
             }
-            const stderrOutput = Buffer.concat(stderrChunks).toString();
+            const stderrOutput = getAgentStderr(tool, stderrChunks);
             const log = logLines.join('\n\n') || stderrOutput;
             const recoveredResponse = recoveryTracker.getRecoveredResponse();
             const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
@@ -3374,6 +3568,7 @@ const runSpecAgentOnce = ({ specSessionId, tool, prompt, files = [], cwd, io, mo
     });
 };
 export const runSpecAgent = (options) => {
+    requireExecutableAgent(options.tool);
     const run = () => runSpecAgentOnce(options);
     return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
 };
@@ -3387,7 +3582,7 @@ export const runSpecAgent = (options) => {
  * updateSpecReviewRunStatus / updateSpecReviewRunStreaming / updateSpecReviewRunUsage —
  * the spec_sessions row is never touched by this path.
  */
-const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, executionContext, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
+const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt, files = [], cwd, io, model, variant = null, skills = [], executionContext, executionProvider = hostExecutionEnvironment, executionTarget, executionLauncherEnvironment = createHostLauncherEnvironment(), executionRuntimeEnvironment = createLegacyHostRuntimeEnvironment(cwd, { PWD: cwd }), }) => {
     const registeredState = activeSpecReviewProcesses.get(specReviewRunId);
     if (registeredState?.stopRequested) {
         return Promise.resolve({
@@ -3431,20 +3626,25 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
         };
         const resolveOnce = settle(resolve);
         const rejectOnce = settle(reject);
-        const [cmd, args] = [
-            'claude',
-            buildClaudeArgs('plan', resolvedModel, null, randomUUID()),
-        ];
         updateSpecReviewRunStreaming(specReviewRunId, null);
         let child;
+        let providerStdout = null;
         let placementFailure = Promise.resolve(null);
+        const agentProvider = getStreamingAgentProvider(tool);
+        const streamingRequest = {
+            cwd,
+            files,
+            skills,
+            prompt,
+            model: resolvedModel,
+            variant,
+            mode: 'plan',
+            resumeSessionId: null,
+            sessionId: randomUUID(),
+        };
         const invocation = tool === 'opencode'
             ? buildOpencodeSpecReviewInvocation({ prompt, files, model: resolvedModel, variant })
-            : {
-                command: cmd,
-                args,
-                stdio: ['pipe', 'pipe', 'pipe'],
-            };
+            : agentProvider.buildStreamingInvocation(streamingRequest);
         try {
             const handle = executionProvider.execute({
                 phase: 'agent',
@@ -3460,14 +3660,36 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
             child = handle.child;
             reviewState.interrupt = handle.interrupt;
             placementFailure = handle.placementFailure;
+            const connection = agentProvider.connectStreamingInvocation?.(child, streamingRequest, {
+                runtimeEnvironmentKind: executionRuntimeEnvironment.kind,
+            });
+            if (connection) {
+                providerStdout = connection.stdout;
+                const placementInterrupt = handle.interrupt;
+                reviewState.interrupt = async (signal) => {
+                    if (signal === 'SIGKILL') {
+                        await placementInterrupt(signal);
+                        return;
+                    }
+                    try {
+                        await connection.interrupt();
+                    }
+                    catch {
+                        await placementInterrupt(signal);
+                    }
+                };
+                void connection.ready.catch(error => {
+                    rejectOnce(agentProvider.classifyExecutionFailure(error));
+                });
+            }
             void placementFailure.then(failure => {
                 if (failure) {
-                    rejectOnce(tool === 'opencode' ? opencodeAgentProvider.classifyExecutionFailure(failure) : failure);
+                    rejectOnce(agentProvider.classifyExecutionFailure(failure));
                 }
             });
         }
         catch (error) {
-            rejectOnce(tool === 'opencode' ? opencodeAgentProvider.classifyExecutionFailure(error) : error);
+            rejectOnce(agentProvider.classifyExecutionFailure(error));
             return;
         }
         reviewState.child = child;
@@ -3536,7 +3758,7 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
                         responseLines.push(responseFragment);
                     }
                 }
-                const errOutput = Buffer.concat(stderrChunks).toString();
+                const errOutput = getAgentStderr(tool, stderrChunks);
                 const finalLog = logLines.join('\n\n') || errOutput;
                 const finalResponse = responseLines.join('\n\n') || errOutput;
                 if (reviewState.stopRequested) {
@@ -3580,7 +3802,8 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
         const progressUpdater = createThrottledProgressUpdater(() => {
             updateSpecReviewRunStreaming(specReviewRunId, responseLines.join('\n\n') || null);
         });
-        child.stdout?.on('data', (chunk) => {
+        const output = providerStdout ?? child.stdout;
+        output?.on('data', (chunk) => {
             const text = remainder + chunk.toString();
             const lines = text.split('\n');
             remainder = lines.pop() ?? '';
@@ -3619,7 +3842,7 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
             progressUpdater.cancel();
             const placementError = await placementFailure;
             if (placementError) {
-                rejectOnce(tool === 'opencode' ? opencodeAgentProvider.classifyExecutionFailure(placementError) : placementError);
+                rejectOnce(agentProvider.classifyExecutionFailure(placementError));
                 return;
             }
             await opencodeSubagentMonitor?.refresh();
@@ -3633,7 +3856,7 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
                     firstFinalAnswerTime = null;
                 }
             }
-            const stderrOutput = Buffer.concat(stderrChunks).toString();
+            const stderrOutput = getAgentStderr(tool, stderrChunks);
             const log = logLines.join('\n\n') || stderrOutput;
             const recoveredResponse = recoveryTracker.getRecoveredResponse();
             const finalResponse = recoveryTracker.hasRecoveredFinalAnswer()
@@ -3699,13 +3922,14 @@ const runSpecReviewAgentOnce = ({ specReviewRunId, specSessionId, tool, prompt,
                 });
                 return;
             }
-            const failure = opencodeAgentProvider.classifyExecutionFailure(err);
+            const failure = agentProvider.classifyExecutionFailure(err);
             subagentTracker.finalize('error', failure.message, null);
             rejectOnce(failure);
         });
     });
 };
 export const runSpecReviewAgent = (options) => {
+    requireExecutableAgent(options.tool);
     const run = () => runSpecReviewAgentOnce(options);
     return options.tool === 'opencode' ? retryOpenCodeDatabaseLocks(run) : run();
 };