@junctionpanel/server 0.1.29 → 0.1.32

package/dist/server/server/agent/providers/codex-app-server-agent.js

@@ -7,6 +7,7 @@ import { z } from "zod";
 import { loadCodexPersistedTimeline } from "./codex-rollout-timeline.js";
 import { mapCodexRolloutToolCall, mapCodexToolCallFromThreadItem, } from "./codex/tool-call-mapper.js";
 import { applyProviderEnv, isProviderCommandAvailable, resolveProviderCommandPrefix, } from "../provider-launch-config.js";
+import { buildCodexRuntimeExtra, DEFAULT_CODEX_MODE_ID, isCodexPlanModeEnabled, normalizeCodexModeId, setCodexPlanModeEnabled, } from "../codex-config.js";
 import { writeImageAttachment } from "./image-attachments.js";
 const DEFAULT_TIMEOUT_MS = 14 * 24 * 60 * 60 * 1000;
 const TURN_START_TIMEOUT_MS = 90 * 1000;
@@ -21,39 +22,39 @@ const CODEX_APP_SERVER_CAPABILITIES = {
 };
 const CODEX_MODES = [
     {
-        id: "read-only",
-        label: "Read Only",
-        description: "Read files and answer questions. Manual approval required for edits, commands, or network ops.",
+        id: "default",
+        label: "Ask",
+        description: "Trusted commands run automatically; untrusted commands and edits require approval.",
     },
     {
-        id: "auto",
-        label: "Auto",
-        description: "Edit files and run commands but still request approval before escalating scope.",
+        id: "acceptEdits",
+        label: "Auto Edit",
+        description: "Workspace edits and commands run automatically without approval.",
     },
     {
-        id: "full-access",
-        label: "Full Access",
-        description: "Edit files, run commands, and access the network without additional prompts.",
+        id: "bypassPermissions",
+        label: "Bypass",
+        description: "Full disk and network access with no approval prompts.",
     },
 ];
-const DEFAULT_CODEX_MODE_ID = "auto";
 const MODE_PRESETS = {
-    "read-only": {
-        approvalPolicy: "on-request",
-        sandbox: "read-only",
+    default: {
+        approvalPolicy: "untrusted",
+        sandbox: "workspace-write",
     },
-    auto: {
-        approvalPolicy: "on-request",
+    acceptEdits: {
+        approvalPolicy: "never",
         sandbox: "workspace-write",
     },
-    "full-access": {
+    bypassPermissions: {
         approvalPolicy: "never",
         sandbox: "danger-full-access",
         networkAccess: true,
     },
 };
 function validateCodexMode(modeId) {
-    if (!(modeId in MODE_PRESETS)) {
+    const normalizedModeId = normalizeCodexModeId(modeId);
+    if (typeof normalizedModeId !== "string" || !(normalizedModeId in MODE_PRESETS)) {
         const validModes = Object.keys(MODE_PRESETS).join(", ");
         throw new Error(`Invalid Codex mode "${modeId}". Valid modes are: ${validModes}`);
     }
@@ -184,6 +185,13 @@ function toRecord(value) {
     }
     return value;
 }
+function toNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 function parseUpdatedQuestionAnswers(updatedInput) {
     const parsed = {};
     const root = toRecord(updatedInput);
@@ -218,6 +226,98 @@ function parseUpdatedQuestionAnswers(updatedInput) {
     }
     return parsed;
 }
+function normalizeCodexQuestionOption(value) {
+    if (typeof value === "string") {
+        const label = value.trim();
+        return label ? { label, value: label } : null;
+    }
+    const record = toRecord(value);
+    if (!record) {
+        return null;
+    }
+    const label = toNonEmptyString(record.label) ?? toNonEmptyString(record.value);
+    if (!label) {
+        return null;
+    }
+    return {
+        label,
+        value: toNonEmptyString(record.value) ?? label,
+        description: toNonEmptyString(record.description) ?? undefined,
+    };
+}
+function normalizeCodexQuestionDescriptor(value, fallbackIndex) {
+    const record = toRecord(value);
+    if (!record) {
+        return null;
+    }
+    const id = toNonEmptyString(record.id) ??
+        toNonEmptyString(record.key) ??
+        `question_${fallbackIndex + 1}`;
+    const options = Array.isArray(record.options)
+        ? record.options
+            .map((option) => normalizeCodexQuestionOption(option))
+            .filter((option) => option !== null)
+        : [];
+    return {
+        id,
+        header: toNonEmptyString(record.header) ?? undefined,
+        question: toNonEmptyString(record.question) ??
+            toNonEmptyString(record.prompt) ??
+            toNonEmptyString(record.text) ??
+            undefined,
+        isOther: Boolean(record.isOther ?? record.is_other),
+        isSecret: Boolean(record.isSecret ?? record.is_secret),
+        options,
+    };
+}
+function normalizeCodexQuestionDescriptors(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((question, index) => normalizeCodexQuestionDescriptor(question, index))
+        .filter((question) => question !== null);
+}
+function extractExplicitDecision(updatedInput) {
+    const root = toRecord(updatedInput);
+    if (!root || !Object.prototype.hasOwnProperty.call(root, "decision")) {
+        return null;
+    }
+    return root.decision ?? null;
+}
+function buildCodexPermissionsResponse(response, requestedPermissions) {
+    const root = toRecord(response.updatedInput);
+    const permissions = toRecord(root?.permissions);
+    const scope = root?.scope === "session" ? "session" : "turn";
+    if (permissions) {
+        return { permissions, scope };
+    }
+    if (response.behavior === "allow") {
+        return { permissions: toRecord(requestedPermissions) ?? {}, scope };
+    }
+    return { permissions: {}, scope };
+}
+function buildCodexElicitationResponse(response) {
+    const root = toRecord(response.updatedInput);
+    const explicitAction = root?.action === "accept" || root?.action === "decline" || root?.action === "cancel"
+        ? root.action
+        : null;
+    if (response.behavior === "allow") {
+        return {
+            action: explicitAction ?? "accept",
+            content: root?.content ?? null,
+            _meta: root?._meta ?? null,
+        };
+    }
+    return {
+        action: explicitAction ?? (response.interrupt ? "cancel" : "decline"),
+        content: null,
+        _meta: root?._meta ?? null,
+    };
+}
+function toPendingPermissionId(requestId) {
+    return `permission-${String(requestId)}`;
+}
 async function listCodexCustomPrompts() {
     const codexHome = resolveCodexHomeDir();
     const promptsDir = path.join(codexHome, "prompts");
@@ -524,7 +624,7 @@ class CodexAppServerClient {
                 const request = msg;
                 const handler = this.requestHandlers.get(request.method);
                 try {
-                    const result = handler ? await handler(request.params) : {};
+                    const result = handler ? await handler(request.params, request.id) : {};
                     const response = { id: request.id, result };
                     this.child.stdin.write(`${JSON.stringify(response)}\n`);
                 }
@@ -581,12 +681,73 @@ function parsePlanTextToTodoItems(text) {
         completed: false,
     }));
 }
+function formatProposedPlanBlock(text) {
+    return `<proposed_plan>\n${text}\n</proposed_plan>`;
+}
+function formatProposedPlanChunk(text, options) {
+    const parts = [];
+    if (options?.open) {
+        parts.push("<proposed_plan>\n");
+    }
+    parts.push(text);
+    if (options?.close) {
+        parts.push("\n</proposed_plan>");
+    }
+    return parts.join("");
+}
 function planStepsToTodoItems(steps) {
     return steps.map((entry) => ({
         text: entry.step,
         completed: entry.status === "completed",
     }));
 }
+function supportsPlanCollaborationMode(response) {
+    const candidateArrays = [
+        Array.isArray(response) ? response : null,
+        Array.isArray(response?.data)
+            ? (response.data)
+            : null,
+        Array.isArray(response?.modes)
+            ? (response.modes)
+            : null,
+        Array.isArray(response?.collaborationModes)
+            ? (response.collaborationModes)
+            : null,
+        Array.isArray(response?.items)
+            ? (response.items)
+            : null,
+    ];
+    for (const entries of candidateArrays) {
+        if (!entries)
+            continue;
+        for (const entry of entries) {
+            const record = toRecord(entry);
+            const modeName = (typeof record?.mode === "string" ? record.mode : null) ??
+                (typeof record?.name === "string" ? record.name : null) ??
+                (typeof record?.id === "string" ? record.id : null) ??
+                (typeof entry === "string" ? entry : null);
+            if (modeName?.trim().toLowerCase() === "plan") {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function shouldRetryInitializeWithoutExperimentalApi(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return (message.includes("experimentalapi") ||
+        message.includes("experimental api") ||
+        message.includes("capabilities") ||
+        message.includes("unknown field") ||
+        message.includes("invalid params"));
+}
+function shouldRetryTurnStartWithoutCollaborationMode(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return (message.includes("collaborationmode") ||
+        message.includes("collaboration mode") ||
+        message.includes("experimentalapi") ||
+        message.includes("experimental api"));
+}
 function extractPatchLikeText(value) {
     if (!value || typeof value !== "object") {
         return undefined;
@@ -896,8 +1057,11 @@ function threadItemToTimeline(item, options) {
         }
         case "plan": {
             const text = normalizedItem.text ?? "";
+            if (typeof text === "string" && text.trim().length > 0) {
+                return { type: "assistant_message", text: formatProposedPlanBlock(text) };
+            }
             const items = parsePlanTextToTodoItems(text);
-            return { type: "todo", items };
+            return items.length > 0 ? { type: "todo", items } : null;
         }
         case "reasoning": {
             const summary = Array.isArray(normalizedItem.summary)
@@ -958,6 +1122,13 @@ const TurnPlanUpdatedNotificationSchema = z.object({
     })
         .passthrough()),
 }).passthrough();
+const ItemPlanDeltaNotificationSchema = z.object({
+    itemId: z.string(),
+    delta: z.string(),
+}).passthrough();
+const ServerRequestResolvedNotificationSchema = z.object({
+    requestId: z.union([z.string(), z.number()]),
+}).passthrough();
 const TurnDiffUpdatedNotificationSchema = z.object({
     diff: z.string(),
 }).passthrough();
@@ -1097,6 +1268,12 @@ const CodexNotificationSchema = z.union([
         })),
     })),
     z.object({ method: z.literal("turn/plan/updated"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
+    z.object({ method: z.literal("item/plan/delta"), params: ItemPlanDeltaNotificationSchema }).transform(({ params }) => ({
+        kind: "plan_delta",
+        itemId: params.itemId,
+        delta: params.delta,
+    })),
+    z.object({ method: z.literal("item/plan/delta"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
     z.object({ method: z.literal("turn/diff/updated"), params: TurnDiffUpdatedNotificationSchema }).transform(({ params }) => ({ kind: "diff_updated", diff: params.diff })),
     z.object({ method: z.literal("turn/diff/updated"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
     z.object({
@@ -1104,6 +1281,14 @@ const CodexNotificationSchema = z.union([
         params: ThreadTokenUsageUpdatedNotificationSchema,
     }).transform(({ params }) => ({ kind: "token_usage_updated", tokenUsage: params.tokenUsage })),
     z.object({ method: z.literal("thread/tokenUsage/updated"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
+    z.object({
+        method: z.literal("serverRequest/resolved"),
+        params: ServerRequestResolvedNotificationSchema,
+    }).transform(({ params }) => ({
+        kind: "server_request_resolved",
+        requestId: String(params.requestId),
+    })),
+    z.object({ method: z.literal("serverRequest/resolved"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
     z.object({ method: z.literal("item/agentMessage/delta"), params: ItemTextDeltaNotificationSchema }).transform(({ params }) => ({
         kind: "agent_message_delta",
         itemId: params.itemId,
@@ -1303,6 +1488,22 @@ export async function codexAppServerTurnInputFromPrompt(prompt, logger) {
 }
 export const __codexAppServerInternals = {
     mapCodexPatchNotificationToToolCall,
+    supportsPlanCollaborationMode,
+    shouldRetryInitializeWithoutExperimentalApi,
+    shouldRetryTurnStartWithoutCollaborationMode,
+    formatProposedPlanBlock,
+    normalizeCodexQuestionDescriptors,
+    parseUpdatedQuestionAnswers,
+    buildCodexPermissionsResponse,
+    buildCodexElicitationResponse,
+    supportedRequestMethods: [
+        "item/commandExecution/requestApproval",
+        "item/fileChange/requestApproval",
+        "tool/requestUserInput",
+        "item/tool/requestUserInput",
+        "item/permissions/requestApproval",
+        "mcpServer/elicitation/request",
+    ],
 };
 class CodexAppServerAgentSession {
     constructor(config, resumeHandle, logger, spawnAppServer) {
@@ -1332,16 +1533,21 @@ class CodexAppServerAgentSession {
         this.warnedInvalidNotificationPayloads = new Set();
         this.warnedIncompleteEditToolCallIds = new Set();
         this.connected = false;
-        this.collaborationModes = [];
-        this.resolvedCollaborationMode = null;
+        this.nativePlanModeSupported = null;
+        this.pendingPlanTexts = new Map();
         this.cachedSkills = [];
         this.logger = logger.child({ module: "agent", provider: CODEX_PROVIDER });
         if (config.modeId === undefined) {
             throw new Error("Codex agent requires modeId to be specified");
         }
-        validateCodexMode(config.modeId);
-        this.currentMode = config.modeId;
         this.config = config;
+        const normalizedModeId = normalizeCodexModeId(config.modeId);
+        if (typeof normalizedModeId !== "string") {
+            throw new Error("Codex agent requires a valid modeId");
+        }
+        validateCodexMode(normalizedModeId);
+        this.currentMode = normalizedModeId;
+        this.config.modeId = normalizedModeId;
         this.config.thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
         if (this.resumeHandle?.sessionId) {
             this.currentThreadId = this.resumeHandle.sessionId;
@@ -1358,13 +1564,27 @@ class CodexAppServerAgentSession {
         this.client = new CodexAppServerClient(child, this.logger);
         this.client.setNotificationHandler((method, params) => this.handleNotification(method, params));
         this.registerRequestHandlers();
-        await this.client.request("initialize", {
-            clientInfo: {
-                name: "junction",
-                title: "Junction",
-                version: "0.0.0",
-            },
-        });
+        const clientInfo = {
+            name: "junction",
+            title: "Junction",
+            version: "0.0.0",
+        };
+        try {
+            await this.client.request("initialize", {
+                clientInfo,
+                capabilities: {
+                    experimentalApi: true,
+                },
+            });
+        }
+        catch (error) {
+            if (!shouldRetryInitializeWithoutExperimentalApi(error)) {
+                throw error;
+            }
+            await this.client.request("initialize", { clientInfo });
+            this.nativePlanModeSupported = false;
+            setCodexPlanModeEnabled(this.config, false);
+        }
         this.client.notify("initialized", {});
         await this.loadCollaborationModes();
         await this.loadSkills();
@@ -1377,22 +1597,22 @@ class CodexAppServerAgentSession {
     async loadCollaborationModes() {
         if (!this.client)
             return;
+        if (this.nativePlanModeSupported === false) {
+            setCodexPlanModeEnabled(this.config, false);
+            return;
+        }
         try {
-            const response = (await this.client.request("collaborationMode/list", {}));
-            const data = Array.isArray(response?.data) ? response.data : [];
-            this.collaborationModes = data.map((entry) => ({
-                name: String(entry.name ?? ""),
-                mode: entry.mode ?? null,
-                model: entry.model ?? null,
-                reasoning_effort: entry.reasoning_effort ?? null,
-                developer_instructions: entry.developer_instructions ?? null,
-            }));
+            const response = await this.client.request("collaborationMode/list", {});
+            this.nativePlanModeSupported = supportsPlanCollaborationMode(response);
+            if (this.nativePlanModeSupported === false) {
+                setCodexPlanModeEnabled(this.config, false);
+            }
         }
         catch (error) {
             this.logger.trace({ error }, "Failed to load collaboration modes");
-            this.collaborationModes = [];
+            this.nativePlanModeSupported = false;
+            setCodexPlanModeEnabled(this.config, false);
         }
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(this.currentMode);
     }
     async loadSkills() {
         if (!this.client)
@@ -1422,59 +1642,15 @@ class CodexAppServerAgentSession {
             this.cachedSkills = [];
         }
     }
-    resolveCollaborationMode(modeId) {
-        if (this.collaborationModes.length === 0)
-            return null;
-        const normalized = modeId.toLowerCase();
-        const findByName = (predicate) => this.collaborationModes.find((entry) => predicate(entry.name.toLowerCase()));
-        let match;
-        if (normalized === "read-only") {
-            // Prefer explicit plan collaboration modes over generic read-only modes.
-            match =
-                findByName((name) => name.includes("plan")) ??
-                    findByName((name) => name.includes("read"));
-        }
-        else if (normalized === "full-access") {
-            match = findByName((name) => name.includes("full") || name.includes("exec"));
-        }
-        else {
-            match = findByName((name) => name.includes("auto") || name.includes("code"));
-        }
-        if (!match) {
-            match = this.collaborationModes[0] ?? null;
-        }
-        if (!match)
-            return null;
-        const settings = {};
-        if (match.model)
-            settings.model = match.model;
-        if (match.reasoning_effort)
-            settings.reasoning_effort = match.reasoning_effort;
-        const modeSpecificInstruction = normalized === "read-only"
-            ? "Plan mode is enabled. Do not execute commands, edit files, or perform write operations. Provide analysis and a step-by-step plan only."
-            : "";
-        const developerInstructions = [
-            modeSpecificInstruction,
-            match.developer_instructions?.trim(),
-            this.config.systemPrompt?.trim(),
-        ]
-            .filter((entry) => typeof entry === "string" && entry.length > 0)
-            .join("\n\n");
-        if (developerInstructions)
-            settings.developer_instructions = developerInstructions;
-        if (this.config.model)
-            settings.model = this.config.model;
-        const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
-        if (thinkingOptionId)
-            settings.reasoning_effort = thinkingOptionId;
-        return { mode: match.mode ?? "code", settings, name: match.name };
-    }
     registerRequestHandlers() {
         if (!this.client)
             return;
-        this.client.setRequestHandler("item/commandExecution/requestApproval", (params) => this.handleCommandApprovalRequest(params));
-        this.client.setRequestHandler("item/fileChange/requestApproval", (params) => this.handleFileChangeApprovalRequest(params));
-        this.client.setRequestHandler("tool/requestUserInput", (params) => this.handleToolApprovalRequest(params));
+        this.client.setRequestHandler("item/commandExecution/requestApproval", (params, requestId) => this.handleCommandApprovalRequest("item/commandExecution/requestApproval", params, requestId));
+        this.client.setRequestHandler("item/fileChange/requestApproval", (params, requestId) => this.handleFileChangeApprovalRequest("item/fileChange/requestApproval", params, requestId));
+        this.client.setRequestHandler("tool/requestUserInput", (params, requestId) => this.handleToolApprovalRequest("tool/requestUserInput", params, requestId));
+        this.client.setRequestHandler("item/tool/requestUserInput", (params, requestId) => this.handleToolApprovalRequest("item/tool/requestUserInput", params, requestId));
+        this.client.setRequestHandler("item/permissions/requestApproval", (params, requestId) => this.handlePermissionsApprovalRequest("item/permissions/requestApproval", params, requestId));
+        this.client.setRequestHandler("mcpServer/elicitation/request", (params, requestId) => this.handleMcpElicitationRequest("mcpServer/elicitation/request", params, requestId));
     }
     async loadPersistedHistory() {
         if (!this.client || !this.currentThreadId)
@@ -1672,6 +1848,11 @@ class CodexAppServerAgentSession {
             const preset = MODE_PRESETS[this.currentMode] ?? MODE_PRESETS[DEFAULT_CODEX_MODE_ID];
             const approvalPolicy = this.config.approvalPolicy ?? preset.approvalPolicy;
             const sandboxPolicyType = this.config.sandboxMode ?? preset.sandbox;
+            const explicitPlanMode = options?.extra?.codex?.planMode;
+            const planModeRequested = explicitPlanMode === undefined
+                ? isCodexPlanModeEnabled(this.config)
+                : explicitPlanMode === true;
+            const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
             const params = {
                 threadId: this.currentThreadId,
                 input,
@@ -1683,16 +1864,9 @@ class CodexAppServerAgentSession {
             if (this.config.model) {
                 params.model = this.config.model;
             }
-            const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
             if (thinkingOptionId) {
                 params.effort = thinkingOptionId;
             }
-            if (this.resolvedCollaborationMode) {
-                params.collaborationMode = {
-                    mode: this.resolvedCollaborationMode.mode,
-                    settings: this.resolvedCollaborationMode.settings,
-                };
-            }
             if (this.config.cwd) {
                 params.cwd = this.config.cwd;
             }
@@ -1706,7 +1880,39 @@ class CodexAppServerAgentSession {
             if (codexConfig) {
                 params.config = codexConfig;
             }
-            await this.client.request("turn/start", params, TURN_START_TIMEOUT_MS);
+            let downgradedFromPlanMode = false;
+            if (this.nativePlanModeSupported !== false) {
+                const collaborationMode = this.buildCollaborationModePayload(planModeRequested ? "plan" : "default");
+                if (collaborationMode) {
+                    params.collaborationMode = collaborationMode;
+                }
+            }
+            try {
+                await this.client.request("turn/start", params, TURN_START_TIMEOUT_MS);
+            }
+            catch (error) {
+                const canRetryWithoutPlanMode = Object.prototype.hasOwnProperty.call(params, "collaborationMode") &&
+                    shouldRetryTurnStartWithoutCollaborationMode(error);
+                if (!canRetryWithoutPlanMode) {
+                    throw error;
+                }
+                delete params.collaborationMode;
+                this.nativePlanModeSupported = false;
+                setCodexPlanModeEnabled(this.config, false);
+                this.cachedRuntimeInfo = null;
+                downgradedFromPlanMode = planModeRequested;
+                await this.client.request("turn/start", params, TURN_START_TIMEOUT_MS);
+            }
+            if (downgradedFromPlanMode) {
+                this.emitEvent({
+                    type: "timeline",
+                    provider: CODEX_PROVIDER,
+                    item: {
+                        type: "assistant_message",
+                        text: "Plan mode is not supported by this Codex runtime. Sent as a normal turn instead.",
+                    },
+                });
+            }
             let sawTurnStarted = false;
             for await (const event of queue) {
                 // Drop pre-start timeline noise that can leak from the previous turn.
@@ -1763,9 +1969,10 @@ class CodexAppServerAgentSession {
             model: this.config.model ?? null,
             thinkingOptionId: normalizeCodexThinkingOptionId(this.config.thinkingOptionId) ?? null,
             modeId: this.currentMode ?? null,
-            extra: this.resolvedCollaborationMode
-                ? { collaborationMode: this.resolvedCollaborationMode.name }
-                : undefined,
+            extra: buildCodexRuntimeExtra({
+                planModeSupported: this.nativePlanModeSupported,
+                planModeEnabled: isCodexPlanModeEnabled(this.config),
+            }),
         };
         this.cachedRuntimeInfo = info;
         return { ...info };
@@ -1777,19 +1984,21 @@ class CodexAppServerAgentSession {
         return this.currentMode ?? null;
     }
     async setMode(modeId) {
-        validateCodexMode(modeId);
-        this.currentMode = modeId;
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(modeId);
+        const normalizedModeId = normalizeCodexModeId(modeId);
+        if (typeof normalizedModeId !== "string") {
+            throw new Error(`Invalid Codex mode "${modeId}"`);
+        }
+        validateCodexMode(normalizedModeId);
+        this.currentMode = normalizedModeId;
+        this.config.modeId = normalizedModeId;
         this.cachedRuntimeInfo = null;
     }
     async setModel(modelId) {
         this.config.model = modelId ?? undefined;
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(this.currentMode);
         this.cachedRuntimeInfo = null;
     }
     async setThinkingOption(thinkingOptionId) {
         this.config.thinkingOptionId = normalizeCodexThinkingOptionId(thinkingOptionId);
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(this.currentMode);
         this.cachedRuntimeInfo = null;
     }
     getPendingPermissions() {
@@ -1838,23 +2047,33 @@ class CodexAppServerAgentSession {
             resolution: response,
         });
         if (pending.kind === "command") {
-            const decision = response.behavior === "allow"
-                ? "accept"
-                : response.interrupt
-                    ? "cancel"
-                    : "decline";
+            const decision = extractExplicitDecision(response.updatedInput) ??
+                (response.behavior === "allow"
+                    ? "accept"
+                    : response.interrupt
+                        ? "cancel"
+                        : "decline");
             pending.resolve({ decision });
             return;
         }
         if (pending.kind === "file") {
-            const decision = response.behavior === "allow"
-                ? "accept"
-                : response.interrupt
-                    ? "cancel"
-                    : "decline";
+            const decision = extractExplicitDecision(response.updatedInput) ??
+                (response.behavior === "allow"
+                    ? "accept"
+                    : response.interrupt
+                        ? "cancel"
+                        : "decline");
             pending.resolve({ decision });
             return;
         }
+        if (pending.kind === "permissions") {
+            pending.resolve(buildCodexPermissionsResponse(response, pending.permissions));
+            return;
+        }
+        if (pending.kind === "elicitation") {
+            pending.resolve(buildCodexElicitationResponse(response));
+            return;
+        }
         // tool/requestUserInput
         const answers = {};
         const questions = pending.questions ?? [];
@@ -2015,10 +2234,29 @@ class CodexAppServerAgentSession {
             innerConfig.mcp_servers = mcpServers;
         }
         if (this.config.extra?.codex) {
-            Object.assign(innerConfig, this.config.extra.codex);
+            const { planModeEnabled: _planModeEnabled, ...codexExtra } = this.config.extra.codex;
+            Object.assign(innerConfig, codexExtra);
         }
         return Object.keys(innerConfig).length > 0 ? innerConfig : null;
     }
+    buildCollaborationModePayload(mode) {
+        if (this.nativePlanModeSupported !== true) {
+            return null;
+        }
+        const model = normalizeCodexModelId(this.config.model);
+        if (!model) {
+            return null;
+        }
+        const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId) ?? null;
+        return {
+            mode,
+            settings: {
+                model,
+                reasoning_effort: thinkingOptionId,
+                developer_instructions: null,
+            },
+        };
+    }
     async buildUserInput(prompt) {
         if (typeof prompt === "string") {
             return [{ type: "text", text: prompt }];
@@ -2073,6 +2311,7 @@ class CodexAppServerAgentSession {
             this.emittedExecCommandCompletedCallIds.clear();
             this.pendingCommandOutputDeltas.clear();
             this.pendingFileChangeOutputDeltas.clear();
+            this.pendingPlanTexts.clear();
             this.warnedIncompleteEditToolCallIds.clear();
             this.eventQueue?.end();
             return;
@@ -2089,6 +2328,22 @@ class CodexAppServerAgentSession {
             });
             return;
         }
+        if (parsed.kind === "plan_delta") {
+            const previous = this.pendingPlanTexts.get(parsed.itemId) ?? "";
+            const next = previous + parsed.delta;
+            this.pendingPlanTexts.set(parsed.itemId, next);
+            this.emitEvent({
+                type: "timeline",
+                provider: CODEX_PROVIDER,
+                item: {
+                    type: "assistant_message",
+                    text: formatProposedPlanChunk(parsed.delta, {
+                        open: previous.length === 0,
+                    }),
+                },
+            });
+            return;
+        }
         if (parsed.kind === "diff_updated") {
             // NOTE: Codex app-server emits frequent `turn/diff/updated` notifications
             // containing a full accumulated unified diff for the *entire turn*.
@@ -2096,6 +2351,20 @@ class CodexAppServerAgentSession {
             // We intentionally do NOT store every diff update in the timeline.
             return;
         }
+        if (parsed.kind === "server_request_resolved") {
+            const pendingRequestId = toPendingPermissionId(parsed.requestId);
+            if (this.resolvedPermissionRequests.has(pendingRequestId)) {
+                return;
+            }
+            this.pendingPermissions.delete(pendingRequestId);
+            this.emitEvent({
+                type: "permission_resolved",
+                provider: CODEX_PROVIDER,
+                requestId: pendingRequestId,
+                resolution: { behavior: "allow" },
+            });
+            return;
+        }
         if (parsed.kind === "token_usage_updated") {
             this.latestUsage = toAgentUsage(parsed.tokenUsage);
             return;
@@ -2225,6 +2494,24 @@ class CodexAppServerAgentSession {
                         timelineItem.text = buffered;
                     }
                 }
+                if (timelineItem.type === "assistant_message" &&
+                    normalizedItemType === "plan" &&
+                    itemId) {
+                    const bufferedPlanText = this.pendingPlanTexts.get(itemId) ?? "";
+                    const finalPlanText = typeof parsed.item.text === "string" ? parsed.item.text : "";
+                    if (bufferedPlanText.length > 0) {
+                        const trailingText = finalPlanText.startsWith(bufferedPlanText)
+                            ? finalPlanText.slice(bufferedPlanText.length)
+                            : "";
+                        timelineItem.text = formatProposedPlanChunk(trailingText, {
+                            close: true,
+                        });
+                        this.pendingPlanTexts.delete(itemId);
+                    }
+                    else if (finalPlanText.trim().length > 0) {
+                        timelineItem.text = formatProposedPlanBlock(finalPlanText);
+                    }
+                }
                 if (timelineItem.type === "reasoning" && itemId) {
                     const buffered = this.pendingReasoning.get(itemId);
                     if (buffered && buffered.length > 0) {
@@ -2240,6 +2527,7 @@ class CodexAppServerAgentSession {
                     this.emittedItemStartedIds.delete(itemId);
                     this.pendingCommandOutputDeltas.delete(itemId);
                     this.pendingFileChangeOutputDeltas.delete(itemId);
+                    this.pendingPlanTexts.delete(itemId);
                 }
             }
             return;
@@ -2336,7 +2624,7 @@ class CodexAppServerAgentSession {
             payload,
         }, "Codex edit tool call is missing diff/content fields");
     }
-    handleCommandApprovalRequest(params) {
+    handleCommandApprovalRequest(requestMethod, params, rawRequestId) {
         const parsed = params;
         const commandPreview = mapCodexExecNotificationToToolCall({
             callId: parsed.itemId,
@@ -2344,8 +2632,12 @@ class CodexAppServerAgentSession {
             cwd: parsed.cwd ?? this.config.cwd ?? null,
             running: true,
         });
-        const requestId = `permission-${parsed.itemId}`;
-        const title = parsed.command ? `Run command: ${parsed.command}` : "Run command";
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.approvalId ?? parsed.itemId);
+        const title = parsed.command
+            ? `Run command: ${parsed.command}`
+            : parsed.networkApprovalContext
+                ? "Allow network access"
+                : "Run command";
         const request = {
             id: requestId,
             provider: CODEX_PROVIDER,
@@ -2366,9 +2658,18 @@ class CodexAppServerAgentSession {
                 output: null,
             },
             metadata: {
+                requestMethod,
                 itemId: parsed.itemId,
+                approvalId: parsed.approvalId ?? null,
                 threadId: parsed.threadId,
                 turnId: parsed.turnId,
+                commandActions: parsed.commandActions ?? null,
+                availableDecisions: parsed.availableDecisions ?? null,
+                additionalPermissions: parsed.additionalPermissions ?? null,
+                proposedExecpolicyAmendment: parsed.proposedExecpolicyAmendment ?? null,
+                proposedNetworkPolicyAmendments: parsed.proposedNetworkPolicyAmendments ?? null,
+                networkApprovalContext: parsed.networkApprovalContext ?? null,
+                skillMetadata: parsed.skillMetadata ?? null,
             },
         };
         this.pendingPermissions.set(requestId, request);
@@ -2377,9 +2678,9 @@ class CodexAppServerAgentSession {
             this.pendingPermissionHandlers.set(requestId, { resolve, kind: "command" });
         });
     }
-    handleFileChangeApprovalRequest(params) {
+    handleFileChangeApprovalRequest(requestMethod, params, rawRequestId) {
         const parsed = params;
-        const requestId = `permission-${parsed.itemId}`;
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.itemId);
         const request = {
             id: requestId,
             provider: CODEX_PROVIDER,
@@ -2391,13 +2692,16 @@ class CodexAppServerAgentSession {
                 type: "unknown",
                 input: {
                     reason: parsed.reason ?? null,
+                    grantRoot: parsed.grantRoot ?? null,
                 },
                 output: null,
             },
             metadata: {
+                requestMethod,
                 itemId: parsed.itemId,
                 threadId: parsed.threadId,
                 turnId: parsed.turnId,
+                grantRoot: parsed.grantRoot ?? null,
             },
         };
         this.pendingPermissions.set(requestId, request);
@@ -2406,28 +2710,132 @@ class CodexAppServerAgentSession {
             this.pendingPermissionHandlers.set(requestId, { resolve, kind: "file" });
         });
     }
-    handleToolApprovalRequest(params) {
+    handleToolApprovalRequest(requestMethod, params, rawRequestId) {
         const parsed = params;
-        const requestId = `permission-${parsed.itemId}`;
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.itemId);
+        const questions = normalizeCodexQuestionDescriptors(parsed.questions);
         const request = {
             id: requestId,
             provider: CODEX_PROVIDER,
-            name: "CodexTool",
-            kind: "tool",
-            title: "Tool action requires approval",
+            name: "CodexQuestion",
+            kind: "question",
+            title: "Answer question",
             description: undefined,
+            input: {
+                questions,
+            },
             detail: {
                 type: "unknown",
                 input: {
-                    questions: Array.isArray(parsed.questions) ? parsed.questions : [],
+                    questions,
                 },
                 output: null,
             },
             metadata: {
+                requestMethod,
                 itemId: parsed.itemId,
                 threadId: parsed.threadId,
                 turnId: parsed.turnId,
-                questions: parsed.questions,
+                questions,
+            },
+        };
+        this.pendingPermissions.set(requestId, request);
+        this.emitEvent({ type: "permission_requested", provider: CODEX_PROVIDER, request });
+        return new Promise((resolve) => {
+            this.pendingPermissionHandlers.set(requestId, {
+                resolve,
+                kind: "question",
+                questions,
+            });
+        });
+    }
+    handlePermissionsApprovalRequest(requestMethod, params, rawRequestId) {
+        const parsed = params;
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.itemId);
+        const request = {
+            id: requestId,
+            provider: CODEX_PROVIDER,
+            name: "CodexPermissionProfile",
+            kind: "tool",
+            title: "Grant additional permissions",
+            description: parsed.reason ?? undefined,
+            input: {
+                permissions: parsed.permissions ?? null,
+            },
+            detail: {
+                type: "unknown",
+                input: {
+                    reason: parsed.reason ?? null,
+                    permissions: parsed.permissions ?? null,
+                },
+                output: null,
+            },
+            metadata: {
+                requestMethod,
+                itemId: parsed.itemId,
+                threadId: parsed.threadId,
+                turnId: parsed.turnId,
+                permissions: parsed.permissions ?? null,
+            },
+        };
+        this.pendingPermissions.set(requestId, request);
+        this.emitEvent({ type: "permission_requested", provider: CODEX_PROVIDER, request });
+        return new Promise((resolve) => {
+            this.pendingPermissionHandlers.set(requestId, {
+                resolve,
+                kind: "permissions",
+                permissions: parsed.permissions ?? null,
+            });
+        });
+    }
+    handleMcpElicitationRequest(requestMethod, params, rawRequestId) {
+        const parsed = params;
+        const baseRequestId = rawRequestId ??
+            parsed.elicitationId ??
+            `${parsed.threadId}:${parsed.turnId ?? "none"}:${parsed.serverName ?? "mcp"}`;
+        const requestId = toPendingPermissionId(baseRequestId);
+        const title = parsed.mode === "url"
+            ? "Open MCP authorization link"
+            : parsed.serverName
+                ? `Respond to ${parsed.serverName}`
+                : "Respond to MCP server";
+        const request = {
+            id: requestId,
+            provider: CODEX_PROVIDER,
+            name: "CodexMcpElicitation",
+            kind: "other",
+            title,
+            description: parsed.message ?? undefined,
+            input: {
+                mode: parsed.mode ?? null,
+                requestedSchema: parsed.requestedSchema ?? null,
+                url: parsed.url ?? null,
+            },
+            detail: {
+                type: "unknown",
+                input: {
+                    requestMethod,
+                    serverName: parsed.serverName ?? null,
+                    mode: parsed.mode ?? null,
+                    message: parsed.message ?? null,
+                    requestedSchema: parsed.requestedSchema ?? null,
+                    url: parsed.url ?? null,
+                    elicitationId: parsed.elicitationId ?? null,
+                    _meta: parsed._meta ?? null,
+                },
+                output: null,
+            },
+            metadata: {
+                requestMethod,
+                threadId: parsed.threadId,
+                turnId: parsed.turnId ?? null,
+                serverName: parsed.serverName ?? null,
+                mode: parsed.mode ?? null,
+                message: parsed.message ?? null,
+                requestedSchema: parsed.requestedSchema ?? null,
+                url: parsed.url ?? null,
+                elicitationId: parsed.elicitationId ?? null,
+                _meta: parsed._meta ?? null,
             },
         };
         this.pendingPermissions.set(requestId, request);
@@ -2435,8 +2843,7 @@ class CodexAppServerAgentSession {
         return new Promise((resolve) => {
             this.pendingPermissionHandlers.set(requestId, {
                 resolve,
-                kind: "tool",
-                questions: Array.isArray(parsed.questions) ? parsed.questions : [],
+                kind: "elicitation",
             });
         });
     }
@@ -2616,7 +3023,7 @@ export class CodexAppServerAgentClient {
         }
     }
     async isAvailable() {
-        return isProviderCommandAvailable(this.runtimeSettings?.command, resolveCodexBinary);
+        return isProviderCommandAvailable(this.runtimeSettings?.command, resolveCodexBinary, applyProviderEnv(process.env, this.runtimeSettings));
     }
 }
 //# sourceMappingURL=codex-app-server-agent.js.map