@aitne/daemon 0.1.0

package/dist/core/backends/codex-core.js

@@ -0,0 +1,1693 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, isAutonomousProcessKey, isPlausibleOpenAiApiKey, matchRunAllowedToolPattern, } from "@aitne/shared";
+import { getContextDir } from "../../config.js";
+import { cleanupSessionWorkdir, createSessionWorkdir } from "../workdir.js";
+import { BackendDecisiveFailure, BackendQuotaError, DelegatedProxyTimeoutError, classifyAbortReason, } from "../agent-core.js";
+import { IdleWatchdog } from "./idle-watchdog.js";
+import { DELEGATED_PROXY_DEFAULTS } from "../../services/delegated-proxy-config.js";
+import { buildDelegatedToolPrompt, emptyCost, flattenToolResultContent, tryParseToolResult, withDurationMs, } from "../../services/delegated-tool-runtime.js";
+import { materializeMcpForSession } from "../../services/mcp/session-materializer.js";
+import { parseMcpToolName } from "../../services/mcp/risk.js";
+import { logMcpToolCall } from "../../services/mcp/tool-audit.js";
+import { buildDaemonApiCliEnv } from "../daemon-api-cli.js";
+import { createOutputCapturePath, CliPathCache, parseJsonLine, readFileIfExists, removeFileIfExists, runLineCommand, } from "./cli-utils.js";
+import { probeApiKeyServerSide } from "./api-key-probe.js";
+import { extractSilentApiErrors, logSilentApiErrors, } from "./silent-api-error-detector.js";
+import { estimateTextInputTokens, findRegisteredModel, getModelsForBackend, latestLiteFor, } from "./model-registry.js";
+import { PriceFetcher } from "./price-fetcher.js";
+import { buildExecutionPrompt, buildSummaryPrompt } from "./prompt-utils.js";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("codex-core");
+const EMPTY_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheCreationInputTokens: 0,
+    cacheReadInputTokens: 0,
+};
+// Probe prompt is derived from `INTEGRATION_DESCRIPTORS.backendConnectors.codex`
+// so adding a new delegated integration (Slack, GitHub, …) requires only the
+// registry update. The line-based filter below (`l.startsWith("mcp__")`) is
+// permissive enough to accept any namespace the registry declares; the prompt
+// is what actually drives ToolSearch to enumerate them. See
+// `docs/design/17-delegated-mode-v2.md` §7.1.
+export const CODEX_PROBE_TOOLS_PROMPT = (() => {
+    const meta = [];
+    for (const key of INTEGRATION_KEYS) {
+        const descriptor = INTEGRATION_DESCRIPTORS[key];
+        const connector = descriptor.backendConnectors.codex;
+        if (!connector)
+            continue;
+        const seen = new Set();
+        for (const tools of Object.values(connector.capabilityTools)) {
+            for (const t of tools)
+                seen.add(t);
+        }
+        meta.push({
+            displayName: descriptor.displayName,
+            toolNamespace: connector.toolNamespace,
+            requiredCapabilities: connector.requiredCapabilities,
+            capabilityToolNames: Array.from(seen),
+        });
+    }
+    const prefixes = meta.map((m) => `'${m.toolNamespace}'`).join(", ");
+    const lines = [];
+    const queries = meta.map((m) => {
+        // Same semantic query approach as the Claude probe — display name +
+        // requiredCapabilities expanded to word tokens. Avoids the
+        // bag-of-fragments dilution that all-tool-name splitting causes.
+        const queryWords = [
+            m.displayName,
+            ...m.requiredCapabilities.flatMap((c) => c.split(/[-_]/)),
+            "connector tools",
+        ]
+            .join(" ")
+            .replace(/\s+/g, " ")
+            .trim();
+        return `'${queryWords}'`;
+    });
+    lines.push(`Use \`tool_search\` for each of these queries with the highest result limit available: ${queries.join("; ")}.`);
+    lines.push("Do not call any of the searched tools.");
+    lines.push(`After the searches, print only full tool names from the search results that start with one of: ${prefixes}.`);
+    for (const m of meta) {
+        if (m.capabilityToolNames.length === 0)
+            continue;
+        const fullNames = m.capabilityToolNames
+            .map((n) => m.toolNamespace + n)
+            .join(", ");
+        lines.push(`Include these ${m.displayName} tools if present: ${fullNames}.`);
+    }
+    lines.push("One tool name per line. No markdown fences. No explanation. If no such tools are available, print NONE.");
+    return lines.join(" ");
+})();
+export class CodexCore {
+    config;
+    priceFetcher;
+    backendId = "codex";
+    // Lazily re-resolved with a 60 s TTL — see ClaudeCodeCore for rationale (§9.4).
+    cliPathCache;
+    get cliPath() {
+        return this.cliPathCache.get();
+    }
+    constructor(config, priceFetcher = new PriceFetcher(config.dataDir)) {
+        this.config = config;
+        this.priceFetcher = priceFetcher;
+        this.cliPathCache = new CliPathCache("codex");
+    }
+    mcpContext;
+    setMcpContext(context) {
+        this.mcpContext = context;
+    }
+    async materializeMcp(sessionDir, processKey) {
+        if (!this.mcpContext) {
+            return {
+                servers: [],
+                env: {},
+                configPath: null,
+                claudeMcpServers: null,
+                disallowedTools: [],
+            };
+        }
+        // Allow mode bypasses the approve-tier MCP strip (see claude-code-core
+        // for the rationale — "strong permission mode" enables every MCP tool,
+        // autonomous routines included).
+        const allowMode = this.config.codexExecutionPermissionMode === "allow";
+        const autonomous = !allowMode && (processKey ? isAutonomousProcessKey(processKey) : false);
+        return materializeMcpForSession({
+            db: this.mcpContext.db,
+            blobStore: this.mcpContext.blobStore,
+            sessionDir,
+            backendId: this.backendId,
+            autonomous,
+            contextDir: getContextDir(this.config),
+        });
+    }
+    async execute(params, streamCallbacks) {
+        return await this.runTurn({
+            prompt: buildExecutionPrompt(params.prompt, params.context, params.event, params.conversationHistory),
+            modelId: params.modelId,
+            eventType: params.event.type,
+            processKey: params.processKey,
+            sessionDir: params.sessionDir,
+            maxBudgetUsd: params.maxBudgetUsd,
+            persistSession: params.persistSession ?? false,
+            turnToken: params.turnToken,
+            stagedAttachments: params.stagedAttachments,
+            sessionDbId: params.sessionDbId,
+            eventCorrelationId: params.event.correlationId,
+        }, streamCallbacks);
+    }
+    async executeResume(params, streamCallbacks) {
+        return await this.runTurn({
+            prompt: params.message,
+            modelId: params.modelId,
+            eventType: "message.received",
+            sessionDir: params.sessionDir,
+            resumeSessionId: params.sessionId,
+            maxBudgetUsd: params.maxBudgetUsd,
+            persistSession: true,
+            turnToken: params.turnToken,
+            stagedAttachments: params.stagedAttachments,
+            sessionDbId: params.sessionDbId,
+            eventCorrelationId: params.eventCorrelationId,
+        }, streamCallbacks);
+    }
+    async summarize(conversationText) {
+        const result = await this.runTurn({
+            prompt: buildSummaryPrompt(conversationText),
+            modelId: this.pickSummaryModel(),
+            eventType: "message.received",
+            persistSession: false,
+        });
+        return result.output;
+    }
+    async checkAuth() {
+        if (!this.cliPath) {
+            return { ok: false, reason: "Codex CLI is not installed or not on PATH." };
+        }
+        const rawApiKey = process.env.OPENAI_API_KEY?.trim();
+        if (rawApiKey) {
+            if (!isPlausibleOpenAiApiKey(rawApiKey)) {
+                return {
+                    ok: false,
+                    reason: "OPENAI_API_KEY is set but does not look like an OpenAI key (expected `sk-…`).",
+                };
+            }
+            return { ok: true, method: "api_key" };
+        }
+        if (existsSync(join(homedir(), ".codex", "auth.json"))) {
+            return { ok: true, method: "oauth" };
+        }
+        return {
+            ok: false,
+            reason: "Codex is not authenticated. Run `codex login` or set OPENAI_API_KEY.",
+        };
+    }
+    /**
+     * Detailed auth probe. Two modes:
+     *  - **API key** (`OPENAI_API_KEY`): format check + server-side probe via
+     *    `probeApiKeyServerSide("openai", ...)` (roadmap §9.1). Throws on
+     *    network/timeout so `checkAll()` records `probe_network_error`.
+     *  - **OAuth** (`codex login`): relies on `codex login status` exit code —
+     *    Phase 0 confirmed that `auth.json.last_refresh` age is not a
+     *    trustworthy staleness signal (CLI returns exit 0 even after 10+ days).
+     */
+    async checkAuthDetailed() {
+        if (!this.cliPath) {
+            return {
+                ok: false,
+                status: "missing",
+                method: "cli_login",
+                detail: "Codex CLI not found on PATH",
+                recoveryCommand: "npm install -g @openai/codex",
+            };
+        }
+        const rawApiKey = process.env.OPENAI_API_KEY?.trim();
+        if (rawApiKey) {
+            if (!isPlausibleOpenAiApiKey(rawApiKey)) {
+                return {
+                    ok: false,
+                    status: "expired",
+                    method: "api_key",
+                    detail: "OPENAI_API_KEY does not match OpenAI key format (expected `sk-…`).",
+                    recoveryCommand: "Unset OPENAI_API_KEY or replace it with a valid OpenAI API key",
+                };
+            }
+            // Format is plausible — attempt a server-side probe to detect
+            // revoked keys within 1 hourly cycle (roadmap §9.1).
+            const probe = await probeApiKeyServerSide("openai", rawApiKey);
+            return {
+                ok: probe.ok,
+                status: probe.ok ? "ok" : "expired",
+                method: "api_key",
+                detail: probe.detail,
+                ...(!probe.ok && {
+                    recoveryCommand: "Unset OPENAI_API_KEY or replace it with a valid OpenAI API key",
+                }),
+            };
+        }
+        try {
+            const result = await runLineCommand({
+                command: this.cliPath,
+                args: ["login", "status"],
+                cwd: process.cwd(),
+                timeoutMs: 10_000,
+            });
+            if (result.exitCode === 0) {
+                return { ok: true, status: "ok", method: "oauth" };
+            }
+            return {
+                ok: false,
+                status: "expired",
+                method: "oauth",
+                detail: "Codex login status reported failure",
+                recoveryCommand: "codex login",
+            };
+        }
+        catch (err) {
+            logger.warn({ err }, "codex login status probe failed");
+            return {
+                ok: false,
+                status: "expired",
+                method: "oauth",
+                detail: err instanceof Error ? err.message : "Codex login status failed",
+                recoveryCommand: "codex login",
+            };
+        }
+    }
+    listModels() {
+        return getModelsForBackend(this.backendId);
+    }
+    /**
+     * Phase 5 §4.11 live probe. Codex doesn't expose a zero-turn tool
+     * manifest, so we prompt the agent to discover and print connector tool
+     * names. Codex apps are lazy-loaded behind `tool_search` on current CLI
+     * builds, so the prompt explicitly opens that catalog before printing
+     * `mcp__...` names. The output is plain-text (one per line), one
+     * minimum-tokens turn.
+     *
+     * Tools whose names don't start with `mcp__` (built-ins like `Bash`,
+     * `Read`) are out of scope — probes are only used to evaluate
+     * connector-namespaced tools via `evaluateProbe`.
+     */
+    async probeTools() {
+        if (!this.cliPath) {
+            throw new Error("Codex CLI is not installed or not on PATH");
+        }
+        const sessionDir = createSessionWorkdir(this.config.workspaceDir, "message.received", undefined, { backendId: this.backendId, character: this.config.character });
+        const outputPath = createOutputCapturePath(sessionDir, "probe");
+        const prompt = CODEX_PROBE_TOOLS_PROMPT;
+        const modelId = this.pickSummaryModel();
+        const args = [
+            "exec",
+            "--json",
+            "--color",
+            "never",
+            "--dangerously-bypass-approvals-and-sandbox",
+            "--skip-git-repo-check",
+            "--output-last-message",
+            outputPath,
+            "--model",
+            modelId,
+            "--ephemeral",
+            prompt,
+        ];
+        const lines = [];
+        try {
+            const result = await runLineCommand({
+                command: this.cliPath,
+                args,
+                cwd: sessionDir,
+                env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, { sessionBackend: "codex" }),
+                timeoutMs: 60_000,
+                onStdoutLine: (line) => {
+                    const event = parseJsonLine(line);
+                    if (!event)
+                        return;
+                    const text = extractCodexText(event);
+                    if (text)
+                        lines.push(...text.split(/\r?\n/));
+                },
+            });
+            if (result.exitCode !== 0 && result.exitCode !== null) {
+                throw new Error(`codex exec exited with code ${result.exitCode}: ${result.stderrLines.slice(-3).join(" | ")}`);
+            }
+            const finalMessage = readFileIfExists(outputPath);
+            const combined = [
+                ...lines,
+                ...(finalMessage ? finalMessage.split(/\r?\n/) : []),
+            ];
+            const tools = combined
+                .map((l) => l.trim())
+                .filter((l) => l.startsWith("mcp__"));
+            const deduped = Array.from(new Set(tools));
+            logger.info({ toolCount: deduped.length }, "Live probe collected tool manifest via codex exec");
+            return deduped;
+        }
+        finally {
+            removeFileIfExists(outputPath);
+            cleanupSessionWorkdir(sessionDir);
+        }
+    }
+    async runTurn(params, streamCallbacks) {
+        // Pre-flight auth gate — ClaudeCodeCore does NOT have this because
+        // the Agent SDK's first HTTP round-trip returns a decisive 401 on
+        // its own, so a Claude pre-flight would double-read credentials
+        // for no benefit. For Codex we're about to spawn a CLI subprocess
+        // (costly TTFB), so it is cheaper to read credentials once here
+        // and surface `BackendDecisiveFailure("auth")` before the subprocess
+        // even boots. See the class-level comment on `ClaudeCodeCore` for
+        // the full rationale and `IAgentCore.checkAuth` for the contract.
+        const auth = await this.checkAuth();
+        if (!auth.ok) {
+            logger.warn({ reason: auth.reason }, "Codex auth check failed");
+            throw new BackendDecisiveFailure(this.backendId, "auth", new Error(auth.reason));
+        }
+        this.assertPromptWithinMaxBudget(params.prompt, params.maxBudgetUsd, params.modelId);
+        const startMs = Date.now();
+        const sessionDir = params.sessionDir ?? createSessionWorkdir(this.config.workspaceDir, params.eventType, `${this.config.dataDir}/skills`, {
+            backendId: this.backendId,
+            processKey: params.processKey,
+            character: this.config.character,
+        });
+        const ownsSessionDir = !params.sessionDir;
+        const outputPath = createOutputCapturePath(sessionDir, "codex-last-message");
+        const mcp = await this.materializeMcp(sessionDir, params.processKey);
+        logger.info({ eventType: params.eventType, model: params.modelId, promptLen: params.prompt.length, mcpServers: mcp.servers.map((s) => s.id) }, "Codex execute started");
+        let streamed = false;
+        const deferStreamingUntilBudgetCheck = params.maxBudgetUsd !== undefined;
+        try {
+            let sessionId = params.resumeSessionId ?? null;
+            let actualModelId = params.modelId;
+            let usage = { ...EMPTY_USAGE };
+            let lastError = null;
+            let sawCompletion = false;
+            let numTurns = 0;
+            let stopReason = null;
+            const outputChunks = [];
+            // Accumulate every scrap of subprocess text (tool-output item fields +
+            // raw stderr lines) so we can scan once for `PA_API_ERROR` markers after
+            // the run. Collecting up front — rather than scanning per-line — keeps
+            // each occurrence logged exactly once across multi-line payloads.
+            const apiOutputBuffer = [];
+            const runResult = await runLineCommand({
+                command: "codex",
+                args: this.buildArgs(params, outputPath),
+                cwd: sessionDir,
+                env: {
+                    ...buildDaemonApiCliEnv(sessionDir, this.config.apiPort, {
+                        sessionBackend: "codex",
+                        sessionId: params.sessionDbId,
+                        eventCorrelationId: params.eventCorrelationId,
+                    }),
+                    ...mcp.env,
+                    ...(params.turnToken ? { PA_TURN_TOKEN: params.turnToken } : {}),
+                },
+                timeoutMs: this.config.executeTimeoutMinutes * 60 * 1000,
+                onStdoutLine: (line) => {
+                    const event = parseJsonLine(line);
+                    if (!event?.type) {
+                        return;
+                    }
+                    if (event.type === "thread.started" && typeof event.thread_id === "string") {
+                        sessionId = event.thread_id;
+                        return;
+                    }
+                    if (event.type === "turn.started") {
+                        numTurns += 1;
+                        return;
+                    }
+                    if (event.type === "turn.completed") {
+                        sawCompletion = true;
+                        usage = extractCodexUsage(event) ?? usage;
+                        actualModelId = event.model ?? actualModelId;
+                        stopReason = event.stop_reason ?? event.reason ?? stopReason;
+                        return;
+                    }
+                    if (event.type === "turn.failed") {
+                        lastError = event.error?.message ?? lastError;
+                        return;
+                    }
+                    if (event.type === "error") {
+                        const message = event.message?.trim();
+                        if (message && !message.startsWith("Reconnecting...")) {
+                            lastError = message;
+                        }
+                        return;
+                    }
+                    collectCodexItemText(event, apiOutputBuffer);
+                    // B-003 Phase 4.4 — persist MCP tool call to `mcp_tool_calls`.
+                    const mcpCall = extractMcpToolCall(event);
+                    if (mcpCall) {
+                        logger.debug({
+                            serverId: mcpCall.serverId,
+                            toolName: mcpCall.toolName,
+                            sessionId,
+                            eventType: params.eventType,
+                        }, "mcp.tool_call");
+                        if (this.mcpContext?.db) {
+                            try {
+                                logMcpToolCall(this.mcpContext.db, {
+                                    serverId: mcpCall.serverId,
+                                    toolName: mcpCall.toolName,
+                                    eventType: params.eventType,
+                                    sessionId: sessionId ?? undefined,
+                                });
+                            }
+                            catch (err) {
+                                logger.warn({ err, serverId: mcpCall.serverId }, "mcp.tool_call audit insert failed");
+                            }
+                        }
+                    }
+                    const delta = extractCodexText(event);
+                    if (!delta) {
+                        return;
+                    }
+                    outputChunks.push(delta);
+                    if (!deferStreamingUntilBudgetCheck) {
+                        streamCallbacks?.onText?.(delta);
+                        streamed = true;
+                    }
+                },
+                onStderrLine: (line) => {
+                    apiOutputBuffer.push(line);
+                    if (isLikelyCodexFailure(line)) {
+                        lastError = line.trim();
+                    }
+                },
+            });
+            const apiErrors = extractSilentApiErrors(apiOutputBuffer.join("\n"));
+            if (apiErrors.length > 0) {
+                logSilentApiErrors(logger, apiErrors, {
+                    backendId: this.backendId,
+                    sessionId,
+                    eventType: params.eventType,
+                });
+            }
+            if (runResult.timedOut) {
+                const err = new BackendDecisiveFailure(this.backendId, "timeout", new Error(`Codex execution exceeded timeout of ${this.config.executeTimeoutMinutes} minutes`));
+                logger.error({ err, eventType: params.eventType, model: params.modelId, durationMs: Date.now() - startMs }, "Codex execute timed out");
+                throw err;
+            }
+            const capturedOutput = readFileIfExists(outputPath);
+            const outputSource = capturedOutput && capturedOutput.trim().length > 0
+                ? capturedOutput
+                : outputChunks.join("");
+            const output = outputSource.trim();
+            const combinedFailure = lastError
+                ?? firstFailureLine(runResult.stderrLines)
+                ?? firstFailureLine(runResult.stdoutLines);
+            if (!sawCompletion || runResult.exitCode !== 0) {
+                const failureMsg = combinedFailure ?? "Codex execution did not complete successfully.";
+                const classified = this.classifyFailure(failureMsg);
+                logger.error({ err: classified, eventType: params.eventType, model: params.modelId, exitCode: runResult.exitCode, durationMs: Date.now() - startMs }, "Codex execute failed");
+                throw classified;
+            }
+            const { costUsd, costSource } = this.priceFetcher.estimateUsageCost({
+                backendId: this.backendId,
+                modelId: actualModelId,
+                usage,
+                fallbackModel: findRegisteredModel(this.backendId, actualModelId),
+            });
+            this.assertWithinMaxBudget(costUsd, params.maxBudgetUsd, actualModelId);
+            if (output && !streamed) {
+                streamCallbacks?.onText?.(output);
+            }
+            const durationMs = Date.now() - startMs;
+            logger.info({ eventType: params.eventType, model: actualModelId, durationMs, costUsd, numTurns: numTurns || 1 }, "Codex execute completed");
+            return {
+                output,
+                sessionId,
+                backendId: this.backendId,
+                modelId: actualModelId,
+                costSource,
+                costUsd,
+                usage,
+                modelUsage: usage.inputTokens || usage.outputTokens
+                    ? {
+                        [actualModelId]: {
+                            inputTokens: usage.inputTokens,
+                            outputTokens: usage.outputTokens,
+                            costUsd,
+                        },
+                    }
+                    : {},
+                numTurns: numTurns || 1,
+                durationMs,
+                durationApiMs: durationMs,
+                model: actualModelId,
+                isError: false,
+                stopReason,
+                contextUpdated: false,
+                // advisorCallCount omitted — non-Anthropic backends never populate
+                // this field, consumers treat undefined as 0.
+            };
+        }
+        finally {
+            removeFileIfExists(outputPath);
+            streamCallbacks?.onEnd?.();
+            if (ownsSessionDir) {
+                cleanupSessionWorkdir(sessionDir);
+            }
+        }
+    }
+    buildArgs(params, outputPath) {
+        // ─────────────────────────────────────────────────────────────────────
+        // Sandbox network-access asymmetry (known limitation).
+        //
+        // `-c sandbox_workspace_write.network_access=true` is required for the
+        // agent to reach the daemon API at http://localhost:${apiPort}/... under
+        // the workspace-write sandbox. Without it, Seatbelt/sandbox-exec blocks
+        // ALL network egress and `curl http://localhost:8321/api/health` fails
+        // with a connection-refused sandbox denial (verified 2026-04-11, Codex
+        // v0.118.0).
+        //
+        // HOWEVER: this flag is a binary on/off switch in Codex's sandbox model.
+        // There is no host-scoped allowlist. Once enabled, the agent can reach
+        // ANY external host (verified: curl https://example.com → HTTP 200).
+        //
+        // This is MORE PERMISSIVE than the Claude Code backend, which uses a
+        // PreToolUse hook (`bashCurlHook` in claude-code-core.ts) to restrict
+        // curl targets to localhost:${apiPort}. The Gemini backend achieves the
+        // same localhost restriction via a generated TOML admin policy
+        // (`generateAdminPolicy()` in gemini-cli-core.ts).
+        //
+        // Codex has neither a hook system nor an admin-policy layer for shell
+        // commands, so the localhost-only restriction cannot currently be
+        // enforced on this backend. As long as `message.dm` is routed primarily
+        // to Claude Code (the default), this asymmetry is latent. If the default
+        // binding changes to Codex, revisit by either:
+        //   (a) generating a config.toml with a stricter sandbox profile, or
+        //   (b) wrapping curl with a shim that validates URLs before exec.
+        //
+        // Tracked: BUG-DM-BACKEND-PERMISSIONS.md §5 / §9.
+        //
+        // Allow mode: `--dangerously-bypass-approvals-and-sandbox` skips both
+        // approvals AND sandboxing. No workspace-write network override needed
+        // because the sandbox itself is off.
+        //
+        // `codex exec resume` argv narrowing (verified on 0.121.0):
+        //   `codex exec resume` rejects `--sandbox` and `--color`. Both are
+        //   accepted by the fresh `codex exec` subcommand but not by the
+        //   resume subcommand. We therefore:
+        //     - Use `-c sandbox_mode="workspace-write"` (config-override form)
+        //       for strict mode instead of `--sandbox workspace-write`, since
+        //       `-c` IS accepted by both exec and resume. Functionally
+        //       equivalent; keeps one branch for both code paths.
+        //     - Drop `--color never` from the resume invocation. It remains
+        //       in fresh exec where it is still accepted.
+        // ─────────────────────────────────────────────────────────────────────
+        const allowMode = this.config.codexExecutionPermissionMode === "allow";
+        //
+        // EXECUTION-MODE-DESIGN.md §6 absolute-block layer — Codex gap.
+        //
+        // The absolute-block list (rm -rf, sudo, curl | sh, secret-path reads)
+        // cannot be enforced at the daemon layer on Codex:
+        //
+        //  - Strict mode: the workspace-write sandbox blocks file writes
+        //    outside `cwd`, which contains some of the damage (e.g. a
+        //    `Write(~/.ssh/authorized_keys)` would be denied by the
+        //    sandbox). It does NOT pattern-match shell commands — `rm -rf`
+        //    INSIDE the session workdir, `sudo`, and `curl | sh` are not
+        //    intercepted.
+        //
+        //  - Allow mode: `--dangerously-bypass-approvals-and-sandbox` turns
+        //    off both approvals and the sandbox entirely. There is no hook
+        //    or admin-policy layer we can attach to. The user has
+        //    explicitly opted in.
+        //
+        // Accepted gap per design sign-off. If / when Codex ships a hook
+        // system or admin-policy layer for shell commands, wire
+        // `ALWAYS_DISALLOWED_TOOLS` + the `classifyAbsoluteBlock` helper
+        // from `safety/always-disallowed.ts` here, mirroring the Claude
+        // Code implementation.
+        //
+        // DELEGATED-MODE-V2-DESIGN.md §4.3.4 — same-backend MCP-tool deny
+        // shares the same accepted-gap surface (γ outcome). Codex's built-in
+        // connector apps (`mcp__codex_apps__*`) are not exposed in
+        // `.codex/config.toml` and there is no per-tool disable flag at the
+        // CLI layer. Enforcement is prose-only via the `## Denied tools
+        // (per-integration)` block in AGENTS.md (rendered by
+        // `skills-compiler.buildSameBackendDenyBlock`). Cross-backend
+        // delegation provides hard enforcement at the
+        // `/api/integrations/:key/invoke` chokepoint, so users requiring
+        // strict deny should pick a non-Codex DM backend.
+        //
+        const sandboxArgs = allowMode
+            ? ["--dangerously-bypass-approvals-and-sandbox"]
+            : [
+                "-c",
+                'sandbox_mode="workspace-write"',
+                "-c",
+                "sandbox_workspace_write.network_access=true",
+            ];
+        const imageArgs = buildCodexImageArgs(params.stagedAttachments, CODEX_ARGV_BUDGET_BYTES);
+        if (params.resumeSessionId) {
+            return [
+                "exec",
+                "resume",
+                params.resumeSessionId,
+                "--json",
+                // NOTE: `--color never` omitted — rejected by `codex exec resume`.
+                ...sandboxArgs,
+                "--skip-git-repo-check",
+                "--output-last-message",
+                outputPath,
+                "--model",
+                params.modelId,
+                ...imageArgs,
+                params.prompt,
+            ];
+        }
+        return [
+            "exec",
+            "--json",
+            "--color",
+            "never",
+            ...sandboxArgs,
+            "--skip-git-repo-check",
+            "--output-last-message",
+            outputPath,
+            "--model",
+            params.modelId,
+            ...(params.persistSession ? [] : ["--ephemeral"]),
+            ...imageArgs,
+            params.prompt,
+        ];
+    }
+    pickSummaryModel() {
+        // Registry-derived lite-tier model is the canonical pick (compaction
+        // summaries are short-shape and benefit from the cheapest model).
+        // Falls through to "any registered model" when the registry has no
+        // available lite entry, then throws when the registry is empty for
+        // this backend — preferable to the prior silent literal fallback
+        // that hid registry misconfiguration.
+        const liteFromRegistry = latestLiteFor(this.backendId);
+        if (liteFromRegistry)
+            return liteFromRegistry;
+        const anyFromRegistry = this.listModels()[0]?.modelId;
+        if (anyFromRegistry)
+            return anyFromRegistry;
+        throw new Error(`pickSummaryModel: no models registered for backend ${this.backendId}`);
+    }
+    classifyFailure(message) {
+        if (isMaxBudgetMessage(message)) {
+            return new BackendQuotaError(this.backendId, "max_budget_usd", null, message);
+        }
+        if (/rate limit|usage limit|quota/i.test(message)) {
+            return new BackendQuotaError(this.backendId, "rate_limited", null, message);
+        }
+        if (/unauthorized|forbidden|api key|login/i.test(message)) {
+            return new BackendDecisiveFailure(this.backendId, "auth", new Error(message));
+        }
+        if (/timed out|timeout/i.test(message)) {
+            return new BackendDecisiveFailure(this.backendId, "timeout", new Error(message));
+        }
+        return new BackendDecisiveFailure(this.backendId, "other_non_retryable", new Error(message));
+    }
+    assertWithinMaxBudget(costUsd, maxBudgetUsd, modelId) {
+        if (maxBudgetUsd === undefined || costUsd <= maxBudgetUsd) {
+            return;
+        }
+        throw new BackendQuotaError(this.backendId, "max_budget_usd", null, `Codex estimated cost $${costUsd.toFixed(4)} exceeded the per-turn budget limit $${maxBudgetUsd.toFixed(2)} for ${modelId}.`);
+    }
+    assertPromptWithinMaxBudget(prompt, maxBudgetUsd, modelId) {
+        if (maxBudgetUsd === undefined) {
+            return;
+        }
+        const estimatedUsage = {
+            inputTokens: estimateTextInputTokens(prompt),
+            outputTokens: 0,
+            cacheCreationInputTokens: 0,
+            cacheReadInputTokens: 0,
+        };
+        const { costUsd } = this.priceFetcher.estimateUsageCost({
+            backendId: this.backendId,
+            modelId,
+            usage: estimatedUsage,
+            fallbackModel: findRegisteredModel(this.backendId, modelId),
+        });
+        if (costUsd <= maxBudgetUsd) {
+            return;
+        }
+        throw new BackendQuotaError(this.backendId, "max_budget_usd", null, `Codex estimated prompt cost $${costUsd.toFixed(4)} exceeded the per-turn budget limit $${maxBudgetUsd.toFixed(2)} for ${modelId}.`);
+    }
+    /**
+     * Delegated proxy invocation — Codex CLI path.
+     *
+     * Spawns `codex exec --json --ephemeral --skip-git-repo-check
+     * --output-last-message <path> --model <m> <prompt>` in the
+     * pre-materialized `sessionDir`, parses JSONL events, and matches the
+     * first `mcp__codex_apps__*` tool call whose name equals the requested
+     * tool. The tool result is extracted from item-output fields (`output`,
+     * `aggregated_output`, `stdout`) emitted on the same item or on a
+     * subsequent paired item — the precise pairing semantics differ across
+     * Codex CLI versions, so the implementation is defensive: it captures
+     * the first non-empty output that arrives after the matching call and
+     * within the same turn. The captured-last-message file is the final
+     * fallback (model-text path; less reliable but better than 502 if the
+     * structured pairing changes shape upstream).
+     *
+     * Error classes mirror the Claude path. `auth_error` is detected via
+     * the existing `classifyFailure` regex; `tool_error` arrives as a
+     * `turn.failed` event or as a non-zero subprocess exit code with a
+     * recognisable message.
+     */
+    async runDelegatedTool(params) {
+        const startMs = Date.now();
+        const { toolName, toolArgs, modelId, sessionDir, abortSignal } = params;
+        if (!this.cliPath) {
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: "codex CLI not found on PATH",
+                cost: withDurationMs(emptyCost(), startMs),
+            };
+        }
+        const auth = await this.checkAuth();
+        if (!auth.ok) {
+            return {
+                ok: false,
+                errorClass: "auth_error",
+                message: auth.reason,
+                cost: withDurationMs(emptyCost(), startMs),
+            };
+        }
+        const prompt = buildDelegatedToolPrompt(toolName, toolArgs);
+        const outputPath = createOutputCapturePath(sessionDir, "codex-delegated-last-message");
+        // Mirror the user's execution mode rather than hard-coding strict
+        // sandbox. The proxy session itself runs proxy.md (one tool call,
+        // no Bash / Edit / Write), so the sandbox is purely defensive — but
+        // forcing strict on a user who explicitly opted into allow mode is
+        // an inconsistency that surfaces when delegated.
+        const allowMode = this.config.codexExecutionPermissionMode === "allow";
+        const sandboxArgs = allowMode
+            ? ["--dangerously-bypass-approvals-and-sandbox"]
+            : [
+                "-c",
+                'sandbox_mode="workspace-write"',
+                "-c",
+                "sandbox_workspace_write.network_access=true",
+            ];
+        const args = [
+            "exec",
+            "--json",
+            "--color",
+            "never",
+            ...sandboxArgs,
+            "--skip-git-repo-check",
+            "--output-last-message",
+            outputPath,
+            "--model",
+            modelId,
+            "--ephemeral",
+            prompt,
+        ];
+        let capturedToolItemId = null;
+        let capturedResultRaw = null;
+        let capturedToolError = null;
+        let wrongToolName = null;
+        let usage = { ...EMPTY_USAGE };
+        let actualModelId = modelId;
+        let numTurns = 0;
+        let lastError = null;
+        let sawTurnCompleted = false;
+        const stderrBuffer = [];
+        // Local aborter bridged from the caller's signal so we can also
+        // trigger an early abort on wrong-tool detection. See gemini-cli-core
+        // for the full rationale: this caps wrong_tool failures at ~5s
+        // instead of waiting for the wall-clock or natural completion.
+        const proxyAborter = new AbortController();
+        const callerAbortListener = () => {
+            proxyAborter.abort(abortSignal?.reason);
+        };
+        if (abortSignal) {
+            if (abortSignal.aborted) {
+                proxyAborter.abort(abortSignal.reason);
+            }
+            else {
+                abortSignal.addEventListener("abort", callerAbortListener, {
+                    once: true,
+                });
+            }
+        }
+        // Idle watchdog — same pattern as gemini-cli-core. Catches a hung
+        // codex CLI subprocess (no stream events at all) before the local
+        // safety-net timer or the caller's wall-clock signal fires. Tuned
+        // for codex's typical first-event time (5-15 s); tripping at 60 s
+        // is well outside the healthy distribution.
+        let idleTimedOut = false;
+        const idleTimeoutMs = DELEGATED_PROXY_DEFAULTS.idleTimeoutMsByBackend.codex
+            ?? DELEGATED_PROXY_DEFAULTS.idleTimeoutMs;
+        const idleWatchdog = new IdleWatchdog({
+            idleTimeoutMs,
+            onTimeout: (idleMs) => {
+                idleTimedOut = true;
+                logger.warn({ idleMs, idleTimeoutMs, toolName }, "codex delegated proxy idle watchdog tripped");
+                proxyAborter.abort(new DelegatedProxyTimeoutError(`codex stream idle for ${idleMs}ms (limit ${idleTimeoutMs}ms)`));
+            },
+        });
+        try {
+            idleWatchdog.start();
+            const runResult = await runLineCommand({
+                command: this.cliPath,
+                args,
+                cwd: sessionDir,
+                env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, { sessionBackend: "codex" }),
+                // Wall-clock is enforced by the invoker via abortSignal — we still
+                // pass a generous local timeout as a safety net (callers can
+                // disable it by setting their own abortSignal).
+                timeoutMs: 120_000,
+                abortSignal: proxyAborter.signal,
+                onStdoutLine: (line) => {
+                    idleWatchdog.beat();
+                    const event = parseJsonLine(line);
+                    if (!event?.type)
+                        return;
+                    if (event.type === "turn.started") {
+                        numTurns += 1;
+                        return;
+                    }
+                    if (event.type === "turn.completed") {
+                        sawTurnCompleted = true;
+                        usage = extractCodexUsage(event) ?? usage;
+                        actualModelId = event.model ?? actualModelId;
+                        return;
+                    }
+                    if (event.type === "turn.failed") {
+                        lastError = event.error?.message ?? lastError;
+                        return;
+                    }
+                    if (event.type === "error") {
+                        const message = event.message?.trim();
+                        if (message && !message.startsWith("Reconnecting...")) {
+                            lastError = message;
+                        }
+                        return;
+                    }
+                    // Match MCP tool calls by item.name / item.tool. We accept the
+                    // first item that resolves to the requested tool name; any
+                    // earlier item resolving to a different MCP tool flips the
+                    // wrong_tool flag.
+                    const item = event.item;
+                    if (item && typeof item === "object") {
+                        const bag = item;
+                        const itemId = typeof bag.id === "string"
+                            ? bag.id
+                            : typeof bag.call_id === "string"
+                                ? bag.call_id
+                                : null;
+                        const callMatch = extractMcpToolCall(event);
+                        if (callMatch && itemId !== null && capturedToolItemId === null) {
+                            const fullName = callMatch.toolName.startsWith("mcp__")
+                                ? callMatch.toolName
+                                : `mcp__${callMatch.serverId}__${callMatch.toolName}`;
+                            if (callMatch.toolName === toolName
+                                || fullName === toolName
+                                || itemMatchesToolName(bag, toolName)) {
+                                capturedToolItemId = itemId;
+                            }
+                            else if (wrongToolName === null) {
+                                wrongToolName = fullName;
+                                // Early abort: see gemini-cli-core comment on the same
+                                // pattern. The post-await classifier checks
+                                // `wrongToolName` before `abortSignal?.aborted` so the
+                                // failure is attributed correctly.
+                                proxyAborter.abort(new Error("wrong_tool"));
+                            }
+                        }
+                        // Pair tool result by call_id / parent_id when available;
+                        // otherwise treat the first non-empty output that arrives
+                        // after the matching call as the result. The output may live
+                        // on the call item itself (some Codex versions backfill it)
+                        // or on a separate function_call_output item.
+                        if (capturedToolItemId !== null && capturedResultRaw === null) {
+                            const pairedId = typeof bag.call_id === "string"
+                                ? bag.call_id
+                                : typeof bag.parent_id === "string"
+                                    ? bag.parent_id
+                                    : itemId;
+                            const paired = pairedId === capturedToolItemId;
+                            if (paired || itemId === capturedToolItemId) {
+                                const collected = collectItemOutput(bag);
+                                if (collected !== null) {
+                                    capturedResultRaw = collected;
+                                    // Codex marks tool errors with `is_error` or `error`
+                                    // fields on the output item.
+                                    if (bag.is_error === true
+                                        || (typeof bag.error === "string"
+                                            && bag.error.trim().length > 0)) {
+                                        capturedToolError =
+                                            typeof bag.error === "string"
+                                                ? bag.error
+                                                : capturedResultRaw;
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                onStderrLine: (line) => {
+                    idleWatchdog.beat();
+                    stderrBuffer.push(line);
+                    if (isLikelyCodexFailure(line)) {
+                        lastError = line.trim();
+                    }
+                },
+            });
+            if (capturedResultRaw === null && capturedToolItemId !== null) {
+                // Structured stream pairing did not yield a result block — fall
+                // back to the captured `--output-last-message` content. The
+                // proxy.md prompt instructs the model to return the tool's raw
+                // result, so the assistant's final message should already be the
+                // tool output (less reliable than structured matching, but a
+                // graceful degradation when pairing semantics drift across
+                // Codex versions).
+                const lastMessage = readFileIfExists(outputPath);
+                if (lastMessage && lastMessage.trim().length > 0) {
+                    capturedResultRaw = lastMessage.trim();
+                }
+            }
+            const cost = withDurationMs({
+                tokensInput: usage.inputTokens,
+                tokensOutput: usage.outputTokens,
+                cacheCreationTokens: usage.cacheCreationInputTokens,
+                cacheReadTokens: usage.cacheReadInputTokens,
+                costUsd: this.priceFetcher.estimateUsageCost({
+                    backendId: this.backendId,
+                    modelId: actualModelId,
+                    usage,
+                    fallbackModel: findRegisteredModel(this.backendId, actualModelId),
+                }).costUsd,
+                durationMs: 0,
+                numTurns: numTurns || (sawTurnCompleted ? 1 : 0),
+            }, startMs);
+            // wrong_tool check is hoisted above the abort branch because the
+            // early-abort path (proxyAborter.abort) sets `wrongToolName` and
+            // triggers a kill — without this ordering the failure would
+            // surface as `cancelled` instead of the actual upstream cause.
+            // The idle-watchdog branch sits between wrong_tool and the
+            // caller's abortSignal: an idle hang aborts via proxyAborter and
+            // does not propagate to abortSignal, so without this ordering the
+            // failure would mis-classify as `no_tool_call`.
+            if (wrongToolName !== null) {
+                return {
+                    ok: false,
+                    errorClass: "wrong_tool",
+                    message: `model called '${wrongToolName}' instead of requested '${toolName}'`,
+                    cost,
+                };
+            }
+            if (idleTimedOut) {
+                return {
+                    ok: false,
+                    errorClass: "timeout",
+                    message: `delegated proxy stream went idle (no codex events for ${idleTimeoutMs}ms)`,
+                    cost,
+                };
+            }
+            if (abortSignal?.aborted) {
+                const errorClass = classifyAbortReason(abortSignal.reason);
+                return {
+                    ok: false,
+                    errorClass,
+                    message: errorClass === "timeout"
+                        ? "delegated proxy timed out (wall-clock)"
+                        : "delegated proxy cancelled by caller",
+                    cost,
+                };
+            }
+            if (runResult.timedOut) {
+                return {
+                    ok: false,
+                    errorClass: "timeout",
+                    message: "codex subprocess exceeded local safety-net timeout",
+                    cost,
+                };
+            }
+            if (capturedResultRaw !== null && capturedToolError === null) {
+                return {
+                    ok: true,
+                    toolResult: tryParseToolResult(capturedResultRaw),
+                    cost,
+                };
+            }
+            if (capturedToolError !== null) {
+                return {
+                    ok: false,
+                    errorClass: "tool_error",
+                    message: flattenToolResultContent(capturedToolError),
+                    cost,
+                };
+            }
+            const failure = lastError ?? firstFailureLine(stderrBuffer);
+            if (failure && /unauthorized|forbidden|api key|login|auth/i.test(failure)) {
+                return {
+                    ok: false,
+                    errorClass: "auth_error",
+                    message: failure,
+                    cost,
+                };
+            }
+            if (runResult.exitCode !== 0 && runResult.exitCode !== null) {
+                return {
+                    ok: false,
+                    errorClass: "subprocess_crashed",
+                    message: failure ?? `codex exec exited ${runResult.exitCode}`,
+                    cost,
+                };
+            }
+            if (capturedToolItemId === null) {
+                return {
+                    ok: false,
+                    errorClass: "no_tool_call",
+                    message: failure
+                        ?? `model did not invoke '${toolName}' (sawTurnCompleted=${sawTurnCompleted})`,
+                    cost,
+                };
+            }
+            return {
+                ok: false,
+                errorClass: "parse_error",
+                message: failure
+                    ?? `codex emitted '${toolName}' call but no output payload could be paired`,
+                cost,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const cost = withDurationMs(emptyCost(), startMs);
+            if (abortSignal?.aborted) {
+                return {
+                    ok: false,
+                    errorClass: classifyAbortReason(abortSignal.reason),
+                    message,
+                    cost,
+                };
+            }
+            return { ok: false, errorClass: "subprocess_crashed", message, cost };
+        }
+        finally {
+            idleWatchdog.stop();
+            removeFileIfExists(outputPath);
+            if (abortSignal && !abortSignal.aborted) {
+                abortSignal.removeEventListener("abort", callerAbortListener);
+            }
+        }
+    }
+    /**
+     * DELEGATED-TASK-MODE-DESIGN.md §9 — Codex task mode (Phase 1.5+).
+     *
+     * Codex CLI has no per-spawn allowedTools surface for MCP calls and no
+     * PreToolUse hook, so allowed-tools enforcement lives entirely in
+     * daemon-side stream pre-emption: we observe each `tool_use` item on
+     * stdout, gate it against `allowedTools` and the destructive denylist,
+     * and abort the subprocess (via the local AbortController) when the
+     * model reaches outside the per-task envelope.
+     *
+     * Race window (accepted): a fast tool's side effect can land before our
+     * SIGTERM arrives. The session's materialized `.codex/` config restricts
+     * the MCP surface to the integration's connector (so out-of-scope tools
+     * are unreachable to begin with), and `allowDestructive=false` removes
+     * destructive entries from `allowedTools` upstream — but a destructive
+     * connector tool that the prompt instructs the model NOT to call could
+     * still race a SIGTERM. The prompt's destructive-section + the
+     * `needsConfirmation` envelope are the load-bearing guardrails for that
+     * narrow case; stream pre-emption is the second line.
+     *
+     * Output extraction: Codex CLI does not expose a structured-output API
+     * (Anthropic-style `outputFormat: 'json_schema'`), so we pin
+     * `--output-last-message` to a file and let the runtime helper
+     * (`extractAndValidateResult`) handle fence-stripping + Ajv validation.
+     * The `structuredOutput` field on the result is intentionally omitted
+     * for Codex; the invoker falls back to text-extract automatically.
+     */
+    async runDelegatedTask(params) {
+        const startMs = Date.now();
+        const { systemPrompt, allowedTools, destructiveTools, writeClassTools, modelId, maxToolCalls, timeoutMs, sessionDir, abortSignal, onToolStep, allowDestructive, } = params;
+        const trace = [];
+        let writeClassToolFired = false;
+        const writeClassMatcher = (name) => writeClassTools.some((pattern) => matchRunAllowedToolPattern(pattern, name));
+        if (!this.cliPath) {
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: "codex CLI not found on PATH",
+                cost: withDurationMs(emptyCost(), startMs),
+                trace,
+                writeClassToolFired,
+            };
+        }
+        const auth = await this.checkAuth();
+        if (!auth.ok) {
+            return {
+                ok: false,
+                errorClass: "auth_error",
+                message: auth.reason,
+                cost: withDurationMs(emptyCost(), startMs),
+                trace,
+                writeClassToolFired,
+            };
+        }
+        const outputPath = createOutputCapturePath(sessionDir, "codex-delegated-task-last-message");
+        // Mirror runDelegatedTool's sandbox decision so the proxy session's
+        // posture matches the user's configured execution mode (Allow vs Safe).
+        // In both modes the per-task allowed-tools envelope is enforced by
+        // stream pre-emption below — sandbox bypass only relaxes shell/file
+        // restrictions, which the task subprocess does not exercise anyway.
+        const allowMode = this.config.codexExecutionPermissionMode === "allow";
+        const sandboxArgs = allowMode
+            ? ["--dangerously-bypass-approvals-and-sandbox"]
+            : [
+                "-c",
+                'sandbox_mode="workspace-write"',
+                "-c",
+                "sandbox_workspace_write.network_access=true",
+            ];
+        const args = [
+            "exec",
+            "--json",
+            "--color",
+            "never",
+            ...sandboxArgs,
+            "--skip-git-repo-check",
+            "--output-last-message",
+            outputPath,
+            "--model",
+            modelId,
+            "--ephemeral",
+            systemPrompt,
+        ];
+        // Local aborter bridged from the caller's signal so we can also
+        // trigger an early abort on policy_violation / loop_aborted detection.
+        // Mirrors the pattern in runDelegatedTool and gemini-cli-core's
+        // task-mode implementation.
+        const aborter = new AbortController();
+        const callerListener = () => {
+            aborter.abort(abortSignal?.reason);
+        };
+        if (abortSignal) {
+            if (abortSignal.aborted) {
+                aborter.abort(abortSignal.reason);
+            }
+            else {
+                abortSignal.addEventListener("abort", callerListener, { once: true });
+            }
+        }
+        const isAllowedTool = (name) => allowedTools.some((pattern) => matchRunAllowedToolPattern(pattern, name));
+        const destructiveSet = allowDestructive
+            ? new Set()
+            : new Set(destructiveTools);
+        const pendingByItemId = new Map();
+        let toolCallCount = 0;
+        let loopAborted = false;
+        let policyViolationTool = null;
+        let usage = { ...EMPTY_USAGE };
+        let actualModelId = modelId;
+        let numTurns = 0;
+        let lastError = null;
+        let sawTurnCompleted = false;
+        const stderrBuffer = [];
+        try {
+            const runResult = await runLineCommand({
+                command: this.cliPath,
+                args,
+                cwd: sessionDir,
+                env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, {
+                    sessionBackend: "codex",
+                }),
+                // Wall-clock is enforced by the caller's abortSignal (the route
+                // handler clamps timeoutMs to DELEGATED_TASK_HARD_CAPS.maxTimeoutMs
+                // = 5min). Local timeoutMs is a safety net pegged to the caller
+                // bound + 60s grace so the abort fires first and gives a clean
+                // errorClass=timeout via classifyAbortReason.
+                timeoutMs: timeoutMs + 60_000,
+                abortSignal: aborter.signal,
+                onStdoutLine: (line) => {
+                    const event = parseJsonLine(line);
+                    if (!event?.type)
+                        return;
+                    if (event.type === "turn.started") {
+                        numTurns += 1;
+                        return;
+                    }
+                    if (event.type === "turn.completed") {
+                        sawTurnCompleted = true;
+                        usage = extractCodexUsage(event) ?? usage;
+                        actualModelId = event.model ?? actualModelId;
+                        return;
+                    }
+                    if (event.type === "turn.failed") {
+                        lastError = event.error?.message ?? lastError;
+                        return;
+                    }
+                    if (event.type === "error") {
+                        const message = event.message?.trim();
+                        if (message && !message.startsWith("Reconnecting...")) {
+                            lastError = message;
+                        }
+                        return;
+                    }
+                    const item = event.item;
+                    if (!item || typeof item !== "object")
+                        return;
+                    const bag = item;
+                    const itemId = typeof bag.id === "string"
+                        ? bag.id
+                        : typeof bag.call_id === "string"
+                            ? bag.call_id
+                            : null;
+                    // Stream pre-emption: gate every MCP tool_use against the
+                    // per-task allowed-tools / destructive envelope before the
+                    // subprocess can act on it. The race-window caveat (model side
+                    // effect lands before SIGTERM) is documented at the top of this
+                    // method.
+                    const callMatch = extractMcpToolCall(event);
+                    if (callMatch && itemId !== null) {
+                        // Prefer the verbatim `bag.name` (or `bag.tool_name`) when
+                        // it's already the fully-qualified `mcp__server__tool` form —
+                        // splitting + reconstructing via serverId+toolName loses
+                        // dotted namespace prefixes like `gmail.` (e.g. Codex's gmail
+                        // MCP registers `gmail._search_emails`, but `bag.tool` carries
+                        // only `_search_emails`, dropping the `gmail.` segment).
+                        const verbatim = typeof bag.name === "string" && bag.name.startsWith("mcp__")
+                            ? bag.name
+                            : typeof bag.tool_name === "string"
+                                && bag.tool_name.startsWith("mcp__")
+                                ? bag.tool_name
+                                : null;
+                        const fullName = verbatim
+                            ?? (callMatch.toolName.startsWith("mcp__")
+                                ? callMatch.toolName
+                                : `mcp__${callMatch.serverId}__${callMatch.toolName}`);
+                        if (!pendingByItemId.has(itemId)) {
+                            if (!isAllowedTool(fullName) || destructiveSet.has(fullName)) {
+                                policyViolationTool = fullName;
+                                loopAborted = true;
+                                aborter.abort(new Error("policy_violation"));
+                                return;
+                            }
+                            toolCallCount += 1;
+                            if (toolCallCount > maxToolCalls) {
+                                loopAborted = true;
+                                aborter.abort(new Error("loop_aborted"));
+                                return;
+                            }
+                            if (writeClassMatcher(fullName)) {
+                                writeClassToolFired = true;
+                            }
+                            pendingByItemId.set(itemId, {
+                                name: fullName,
+                                args: extractCodexCallArgs(bag),
+                                startedAt: Date.now(),
+                            });
+                            return;
+                        }
+                    }
+                    // Tool result pairing: bind the first non-empty output that
+                    // arrives for a known pending tool_use. Codex emits the output
+                    // either backfilled on the call item itself (older versions) or
+                    // on a paired function_call_output item.
+                    if (pendingByItemId.size > 0) {
+                        const pairedId = typeof bag.call_id === "string"
+                            ? bag.call_id
+                            : typeof bag.parent_id === "string"
+                                ? bag.parent_id
+                                : itemId;
+                        if (pairedId !== null && pendingByItemId.has(pairedId)) {
+                            const pending = pendingByItemId.get(pairedId);
+                            const collected = collectItemOutput(bag);
+                            if (pending && collected !== null) {
+                                pendingByItemId.delete(pairedId);
+                                const isErrorResult = bag.is_error === true
+                                    || (typeof bag.error === "string"
+                                        && bag.error.trim().length > 0);
+                                // `collected` is the connector response as a string —
+                                // either a JSON-encoded object (the common path:
+                                // `bag.output` was the Codex-side tool_result envelope)
+                                // or a free-form text reply (`stdout` / `stderr`). Try
+                                // JSON-parse for the response-shape walker downstream;
+                                // fall back to the raw string so the field is always
+                                // populated for ok steps.
+                                let parsedToolResult = collected;
+                                try {
+                                    parsedToolResult = JSON.parse(collected);
+                                }
+                                catch {
+                                    /* keep raw string */
+                                }
+                                const step = {
+                                    toolName: pending.name,
+                                    toolArgs: pending.args,
+                                    durationMs: Date.now() - pending.startedAt,
+                                    status: isErrorResult ? "error" : "ok",
+                                    costUsd: null,
+                                    tokensInput: null,
+                                    tokensOutput: null,
+                                    toolResult: parsedToolResult,
+                                };
+                                trace.push(step);
+                                onToolStep?.(step);
+                            }
+                        }
+                    }
+                },
+                onStderrLine: (line) => {
+                    stderrBuffer.push(line);
+                    if (isLikelyCodexFailure(line)) {
+                        lastError = line.trim();
+                    }
+                },
+            });
+            const cost = withDurationMs({
+                tokensInput: usage.inputTokens,
+                tokensOutput: usage.outputTokens,
+                cacheCreationTokens: usage.cacheCreationInputTokens,
+                cacheReadTokens: usage.cacheReadInputTokens,
+                costUsd: this.priceFetcher.estimateUsageCost({
+                    backendId: this.backendId,
+                    modelId: actualModelId,
+                    usage,
+                    fallbackModel: findRegisteredModel(this.backendId, actualModelId),
+                }).costUsd,
+                durationMs: 0,
+                numTurns: numTurns || (sawTurnCompleted ? 1 : 0),
+            }, startMs);
+            if (policyViolationTool) {
+                return {
+                    ok: false,
+                    errorClass: "policy_violation",
+                    message: `subprocess attempted to call '${policyViolationTool}' which is outside the per-task allowlist`,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            if (loopAborted) {
+                return {
+                    ok: false,
+                    errorClass: "loop_aborted",
+                    message: `subprocess exceeded maxToolCalls=${maxToolCalls}`,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            if (abortSignal?.aborted) {
+                const errorClass = classifyAbortReason(abortSignal.reason);
+                return {
+                    ok: false,
+                    errorClass,
+                    message: errorClass === "timeout"
+                        ? "delegated task timed out (wall-clock)"
+                        : "delegated task cancelled by caller",
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            if (runResult.timedOut) {
+                return {
+                    ok: false,
+                    errorClass: "timeout",
+                    message: "codex subprocess exceeded local safety-net timeout",
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            const lastMessage = readFileIfExists(outputPath);
+            const finalText = lastMessage?.trim() ?? "";
+            if (finalText.length === 0) {
+                const failure = lastError ?? firstFailureLine(stderrBuffer);
+                if (failure
+                    && /unauthorized|forbidden|api key|login|auth/i.test(failure)) {
+                    return {
+                        ok: false,
+                        errorClass: "auth_error",
+                        message: failure,
+                        cost,
+                        trace,
+                        writeClassToolFired,
+                    };
+                }
+                return {
+                    ok: false,
+                    errorClass: "parse_error",
+                    message: failure
+                        ?? `codex emitted no final assistant message (sawTurnCompleted=${sawTurnCompleted})`,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            return {
+                ok: true,
+                rawAssistantText: finalText,
+                cost,
+                trace,
+                writeClassToolFired,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const cost = withDurationMs(emptyCost(), startMs);
+            if (abortSignal?.aborted || aborter.signal.aborted) {
+                return {
+                    ok: false,
+                    errorClass: classifyAbortReason(abortSignal?.reason ?? aborter.signal.reason),
+                    message,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message,
+                cost,
+                trace,
+                writeClassToolFired,
+            };
+        }
+        finally {
+            removeFileIfExists(outputPath);
+            if (abortSignal) {
+                abortSignal.removeEventListener("abort", callerListener);
+            }
+        }
+    }
+}
+/**
+ * Best-effort extraction of tool-call arguments from a Codex
+ * `function_call` / `mcp_call` item. Codex serialises args as a JSON
+ * string in `bag.arguments`; older versions may use `bag.input` instead.
+ * Returns `null` when nothing parseable is present so the trace's
+ * `toolArgs` field stays informative.
+ */
+function extractCodexCallArgs(bag) {
+    const candidates = ["arguments", "input", "args"];
+    for (const key of candidates) {
+        const value = bag[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                return JSON.parse(trimmed);
+            }
+            catch {
+                return trimmed;
+            }
+        }
+        if (typeof value === "object")
+            return value;
+    }
+    return null;
+}
+/**
+ * Codex MCP items can carry the tool name on multiple fields depending on
+ * CLI version (`name`, `tool`, `tool_name`). Returns true when any of
+ * them match the requested tool — used as a belt-and-suspenders check
+ * after `extractMcpToolCall` has run, in case the parsing path missed.
+ */
+function itemMatchesToolName(bag, toolName) {
+    const candidates = ["name", "tool", "tool_name"];
+    for (const key of candidates) {
+        const v = bag[key];
+        if (typeof v === "string" && (v === toolName || `mcp__${v}` === toolName)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Pull the first non-empty output payload from a Codex item. Tries the
+ * structured `output` field first (object → JSON); falls back to the
+ * text-shaped fields the existing `collectCodexItemText` helper scans.
+ */
+function collectItemOutput(bag) {
+    const structured = bag.output;
+    if (structured !== undefined && structured !== null) {
+        if (typeof structured === "string" && structured.length > 0) {
+            return structured;
+        }
+        if (typeof structured === "object") {
+            try {
+                return JSON.stringify(structured);
+            }
+            catch {
+                /* fall through to text fields */
+            }
+        }
+    }
+    const fields = ["aggregated_output", "stdout", "stderr"];
+    for (const key of fields) {
+        const v = bag[key];
+        if (typeof v === "string" && v.length > 0) {
+            return v;
+        }
+    }
+    return null;
+}
+function isMaxBudgetMessage(message) {
+    return /max(?:imum)? budget|max_budget_usd|budget limit|per-turn budget/i.test(message);
+}
+/**
+ * Codex argv byte budget. macOS `ARG_MAX` is ~1 MB and the kernel counts
+ * env vars too, so we cap our contribution at 120 KB to leave plenty of
+ * headroom for the prompt body (which can exceed 50 KB on long-context
+ * routines) + env. Matches the chat-file-attachments envelope (see
+ * `docs/design/04-daemon-api.md` §4.3.23).
+ */
+export const CODEX_ARGV_BUDGET_BYTES = 120_000;
+/**
+ * Translate staged image attachments into repeated `--image <absolutePath>`
+ * argv pairs. Non-image attachments stay staged-only (the agent opens them
+ * via shell `cat` / `grep`). If emitting flags for every image would push
+ * argv past the budget, drop the entire list — partial emission would
+ * silently bias the model's attention toward the first N images in an
+ * order that's not visible in the prompt. All-or-nothing is easier to
+ * diagnose and the `[Attached files]` text block still names every file.
+ *
+ * Pure function — unit-testable without a CLI subprocess.
+ */
+export function buildCodexImageArgs(staged, budgetBytes) {
+    if (!staged || staged.length === 0)
+        return [];
+    const images = staged.filter((att) => att.mimeType.toLowerCase().startsWith("image/"));
+    if (images.length === 0)
+        return [];
+    let totalBytes = 0;
+    const args = [];
+    for (const img of images) {
+        // Approximate argv cost: flag name + path + null separators the kernel
+        // adds between args. utf-8 covers macOS paths with non-ASCII chars.
+        totalBytes += Buffer.byteLength("--image", "utf8") + 1;
+        totalBytes += Buffer.byteLength(img.absolutePath, "utf8") + 1;
+        args.push("--image", img.absolutePath);
+    }
+    if (totalBytes > budgetBytes) {
+        logger.warn({ imageCount: images.length, totalBytes, budgetBytes }, "Codex --image argv would exceed budget — dropping to staged-only references");
+        return [];
+    }
+    return args;
+}
+function extractCodexUsage(event) {
+    const usage = event.usage;
+    if (!usage || typeof usage !== "object") {
+        return null;
+    }
+    const totalInputTokens = readNumber(usage.input_tokens);
+    const cacheReadInputTokens = readNumber(usage.cached_input_tokens);
+    return {
+        inputTokens: nonCachedInputTokens(totalInputTokens, cacheReadInputTokens),
+        outputTokens: readNumber(usage.output_tokens),
+        cacheCreationInputTokens: 0,
+        cacheReadInputTokens,
+    };
+}
+function nonCachedInputTokens(totalInputTokens, cacheReadInputTokens, cacheCreationInputTokens = 0) {
+    return Math.max(totalInputTokens - cacheReadInputTokens - cacheCreationInputTokens, 0);
+}
+function extractCodexText(event) {
+    if (typeof event.output_text === "string") {
+        return event.output_text;
+    }
+    if (typeof event.delta === "string") {
+        return event.delta;
+    }
+    if (typeof event.text === "string") {
+        return event.text;
+    }
+    const item = event.item;
+    if (!item || typeof item !== "object") {
+        return "";
+    }
+    if (typeof item.delta === "string") {
+        return item.delta;
+    }
+    if (typeof item.text === "string") {
+        return item.text;
+    }
+    return "";
+}
+function isLikelyCodexFailure(line) {
+    return /error|failed|unauthorized|forbidden|rate limit|quota/i.test(line);
+}
+/**
+ * Copy any string-valued subprocess-output fields from a Codex JSONL event's
+ * `item` into the given sink. Codex emits tool/command output under a small
+ * set of well-known fields; we scan these (not the whole event graph) so that
+ * a command echo like `echo PA_API_ERROR` never false-positives on the
+ * command-text itself.
+ */
+/**
+ * Detect an MCP tool call in a Codex JSONL event. Returns null when the
+ * event does not describe an MCP invocation (plain function calls, text
+ * deltas, turn events, etc.). Two shapes are recognised:
+ *
+ *  1. Items whose `name` matches the cross-runtime `mcp__<server>__<tool>`
+ *     convention. This is the form emitted by Codex's function-call items
+ *     when the underlying tool is an MCP export.
+ *  2. Items that declare `server` + `tool` (or `server_label` + `name`)
+ *     fields directly. Surfaced by newer Codex builds for MCP tools and
+ *     preferred when present because no string parsing is required.
+ *
+ * Logging is fire-and-forget — unparseable inputs silently return null so
+ * benign shape changes upstream don't spam the log.
+ */
+function extractMcpToolCall(event) {
+    const item = event.item;
+    if (!item || typeof item !== "object")
+        return null;
+    const bag = item;
+    const serverField = typeof bag.server === "string"
+        ? bag.server
+        : typeof bag.server_label === "string"
+            ? bag.server_label
+            : null;
+    const toolField = typeof bag.tool === "string"
+        ? bag.tool
+        : typeof bag.tool_name === "string"
+            ? bag.tool_name
+            : null;
+    if (serverField && toolField) {
+        return { serverId: serverField, toolName: toolField };
+    }
+    const name = typeof bag.name === "string"
+        ? bag.name
+        : typeof bag.tool_name === "string"
+            ? bag.tool_name
+            : null;
+    if (name) {
+        const parsed = parseMcpToolName(name);
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function collectCodexItemText(event, sink) {
+    const item = event.item;
+    if (!item || typeof item !== "object")
+        return;
+    const fields = ["output", "stdout", "stderr", "aggregated_output"];
+    for (const key of fields) {
+        const value = item[key];
+        if (typeof value === "string" && value.length > 0) {
+            sink.push(value);
+        }
+    }
+}
+function firstFailureLine(lines) {
+    const line = lines.find((candidate) => isLikelyCodexFailure(candidate));
+    return line?.trim() ?? null;
+}
+function readNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+//# sourceMappingURL=codex-core.js.map