Add plan mode command action

nikita-ashihmin · nikita-ashihmin · commit 303bca986ce8 · 2026-07-13T18:35:04.000+04:00
diff --git a/src/CodexAcpClient.ts b/src/CodexAcpClient.ts
@@ -40,6 +40,8 @@ import type {
 } from "./app-server/v2";
 import packageJson from "../package.json";
 import type {AuthenticationStatusResponse} from "./AcpExtensions";
+import {createCodexCollaborationMode} from "./CollaborationModeConfig";
+import type {ModeKind} from "./app-server/ModeKind";
 
 /**
  * Well-known provider id for the client-configurable custom LLM gateway.
@@ -84,7 +86,10 @@ export class CodexAcpClient {
 
     async initialize(request: acp.InitializeRequest): Promise<void> {
         await this.codexClient.initialize({
-            capabilities: null,
+            capabilities: {
+                experimentalApi: true,
+                requestAttestation: false,
+            },
             clientInfo: {
                 name: request.clientInfo?.name ?? this.defaultClientInfo.name,
                 version: request.clientInfo?.version ?? this.defaultClientInfo.version,
@@ -675,6 +680,13 @@ export class CodexAcpClient {
         }, onTurnStarted);
     }
 
+    async setCollaborationMode(sessionId: string, mode: ModeKind, currentModelId: string): Promise<void> {
+        await this.codexClient.threadSettingsUpdate({
+            threadId: sessionId,
+            collaborationMode: createCodexCollaborationMode(mode, currentModelId),
+        });
+    }
+
     resolveTurnInterrupted(params: { threadId: string, turnId: string }): void {
         this.codexClient.resolveTurnInterrupted(params.threadId, params.turnId);
     }
diff --git a/src/CodexAcpServer.ts b/src/CodexAcpServer.ts
@@ -20,6 +20,13 @@ import type {
 import type {RateLimitsMap} from "./RateLimitsMap";
 import {ModelId} from "./ModelId";
 import {AgentMode, MODE_CONFIG_ID} from "./AgentMode";
+import {
+    COLLABORATION_MODE_CONFIG_ID,
+    createCollaborationModeConfigOption,
+    DEFAULT_COLLABORATION_MODE,
+    parseCollaborationMode,
+} from "./CollaborationModeConfig";
+import type {ModeKind} from "./app-server/ModeKind";
 import {
     createModelConfigOption,
     createReasoningEffortConfigOption,
@@ -87,6 +94,7 @@ export interface SessionState {
     supportedReasoningEfforts: Array<ReasoningEffortOption>,
     supportedInputModalities: Array<InputModality>,
     agentMode: AgentMode,
+    collaborationMode: ModeKind,
     currentTurnId: string | null;
     lastTokenUsage: TokenCount | null;
     totalTokenUsage: TokenCount | null;
@@ -402,6 +410,7 @@ export class CodexAcpServer {
             supportedReasoningEfforts: currentModel?.supportedReasoningEfforts ?? [],
             supportedInputModalities: currentModel?.inputModalities ?? ["text", "image"],
             agentMode: AgentMode.getInitialAgentMode(),
+            collaborationMode: DEFAULT_COLLABORATION_MODE,
             currentTurnId: null,
             lastTokenUsage: null,
             totalTokenUsage: null,
@@ -685,13 +694,24 @@ export class CodexAcpServer {
         const sessionState = this.sessions.get(params.sessionId);
         if (!sessionState) throw new Error(`Session ${params.sessionId} not found`);
 
+        await this.applySessionConfigOption(sessionState, params);
+
+        return {
+            configOptions: this.createSessionConfigOptions(sessionState),
+        };
+    }
+
+    private async applySessionConfigOption(sessionState: SessionState, params: acp.SetSessionConfigOptionRequest): Promise<void> {
         switch (params.configId) {
             case FAST_MODE_CONFIG_ID:
                 this.applyFastModeChange(sessionState, params);
                 break;
             case MODE_CONFIG_ID:
                 this.applyModeChange(sessionState, this.stringConfigValue(params));
                 break;
+            case COLLABORATION_MODE_CONFIG_ID:
+                await this.applyCollaborationModeChange(sessionState, this.stringConfigValue(params));
+                break;
             case MODEL_CONFIG_ID:
                 this.applyModelChange(sessionState, this.stringConfigValue(params));
                 break;
@@ -701,10 +721,6 @@ export class CodexAcpServer {
             default:
                 throw RequestError.invalidParams();
         }
-
-        return {
-            configOptions: this.createSessionConfigOptions(sessionState),
-        };
     }
 
     private applyFastModeChange(sessionState: SessionState, params: acp.SetSessionConfigOptionRequest): void {
@@ -734,6 +750,15 @@ export class CodexAcpServer {
         sessionState.agentMode = newMode;
     }
 
+    private async applyCollaborationModeChange(sessionState: SessionState, value: string): Promise<void> {
+        const mode = parseCollaborationMode(value);
+        if (mode === null) {
+            throw RequestError.invalidParams();
+        }
+        await this.codexAcpClient.setCollaborationMode(sessionState.sessionId, mode, sessionState.currentModelId);
+        sessionState.collaborationMode = mode;
+    }
+
     private applyModelChange(sessionState: SessionState, value: string): void {
         const model = sessionState.availableModels.find(m => m.id === value);
         if (!model) {
@@ -812,6 +837,7 @@ export class CodexAcpServer {
         const currentModelId = ModelId.fromString(sessionState.currentModelId);
         const configOptions = [
             sessionState.agentMode.toConfigOption(),
+            createCollaborationModeConfigOption(sessionState.collaborationMode),
             createModelConfigOption(sessionState.availableModels, currentModelId.model),
         ];
         if (sessionState.supportedReasoningEfforts.length > 0) {
@@ -931,6 +957,7 @@ export class CodexAcpServer {
             supportedReasoningEfforts: currentModel?.supportedReasoningEfforts ?? [],
             supportedInputModalities: currentModel?.inputModalities ?? ["text", "image"],
             agentMode: AgentMode.getInitialAgentMode(),
+            collaborationMode: DEFAULT_COLLABORATION_MODE,
             currentTurnId: null,
             lastTokenUsage: null,
             totalTokenUsage: null,
@@ -1490,6 +1517,18 @@ export class CodexAcpServer {
                     sessionState.currentTurnId = turnId;
                     pendingTurnStart?.resolve(turnId);
                 },
+                setConfigOption: async (configId, value) => {
+                    await this.applySessionConfigOption(sessionState, {
+                        sessionId: sessionState.sessionId,
+                        configId,
+                        value,
+                    });
+                    const session = new ACPSessionConnection(this.connection, sessionState.sessionId);
+                    await session.update({
+                        sessionUpdate: "config_option_update",
+                        configOptions: this.createSessionConfigOptions(sessionState),
+                    });
+                },
             });
             void commandPromise.catch((err) => {
                 if (this.activePrompts.get(params.sessionId) !== activePrompt) {
diff --git a/src/CodexAppServerClient.ts b/src/CodexAppServerClient.ts
@@ -493,6 +493,10 @@ export class CodexAppServerClient {
         return await this.sendRequest({ method: "thread/resume", params: params });
     }
 
+    async threadSettingsUpdate(params: ExperimentalThreadSettingsUpdateParams): Promise<void> {
+        await this.connection.sendRequest("thread/settings/update", params);
+    }
+
     async threadList(params: ThreadListParams): Promise<ThreadListResponse> {
         return await this.sendRequest({ method: "thread/list", params: params });
     }
@@ -927,6 +931,18 @@ type DistributiveOmit<T, K extends keyof any> = T extends any
     ? Omit<T, K>
     : never;
 
+export interface ExperimentalThreadSettingsUpdateParams {
+    threadId: string;
+    collaborationMode: {
+        mode: "default" | "plan";
+        settings: {
+            model: string;
+            reasoning_effort: string | null;
+            developer_instructions: string | null;
+        };
+    };
+}
+
 type McpServerStartupSnapshot = {
     status: McpServerStartupState;
     error: string | null;
diff --git a/src/CodexCommands.ts b/src/CodexCommands.ts
@@ -8,6 +8,11 @@ import type {RateLimitsMap} from "./RateLimitsMap";
 import type {TokenCount} from "./TokenCount";
 import {logger} from "./Logger";
 import {createAgentTextMessageChunk} from "./ContentChunks";
+import {
+    COLLABORATION_MODE_CONFIG_ID,
+    DEFAULT_COLLABORATION_MODE,
+    PLAN_COLLABORATION_MODE,
+} from "./CollaborationModeConfig";
 
 type ParsedSlashCommand = {
     name: string;
@@ -21,6 +26,7 @@ export type CommandHandleResult =
 export type CommandHandleOptions = {
     onTurnStartPending?: () => void;
     onTurnStarted?: (turnId: string, threadId: string) => void;
+    setConfigOption?: (configId: string, value: string) => Promise<void>;
 };
 
 export type LogoutHandler = () => void | Promise<void>;
@@ -94,6 +100,20 @@ export class CodexCommands {
      */
     private getBuiltinCommands(): AvailableCommand[] {
         return [
+            {
+                name: "plan",
+                description: "Turn plan mode on.",
+                input: null,
+                _meta: {
+                    commandAction: {
+                        kind: "setConfigOption",
+                        configId: COLLABORATION_MODE_CONFIG_ID,
+                        value: PLAN_COLLABORATION_MODE,
+                        resetValue: DEFAULT_COLLABORATION_MODE,
+                        presentation: "state",
+                    },
+                },
+            },
             {
                 name: "mcp",
                 description: "List configured Model Context Protocol (MCP) tools.",
@@ -173,6 +193,14 @@ export class CodexCommands {
 
         const sessionId = sessionState.sessionId;
         switch (commandName) {
+            case "plan": {
+                if (command.rest.length > 0) {
+                    await this.sendCommandUsageMessage(commandName, "no arguments", sessionId);
+                    return { handled: true };
+                }
+                await options.setConfigOption?.(COLLABORATION_MODE_CONFIG_ID, PLAN_COLLABORATION_MODE);
+                return { handled: options.setConfigOption !== undefined };
+            }
             case "compact": {
                 await this.runWithProcessCheck(() => this.codexAcpClient.runCompact(sessionId));
                 return { handled: true };
diff --git a/src/CollaborationModeConfig.ts b/src/CollaborationModeConfig.ts
@@ -0,0 +1,41 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type {ReasoningEffort} from "./app-server";
+import type {ModeKind} from "./app-server/ModeKind";
+import {ModelId} from "./ModelId";
+
+export const COLLABORATION_MODE_CONFIG_ID = "collaboration_mode";
+export const DEFAULT_COLLABORATION_MODE: ModeKind = "default";
+export const PLAN_COLLABORATION_MODE: ModeKind = "plan";
+
+export function createCollaborationModeConfigOption(currentValue: ModeKind): acp.SessionConfigOption {
+    return {
+        id: COLLABORATION_MODE_CONFIG_ID,
+        name: "Collaboration mode",
+        description: "How Codex collaborates for subsequent turns",
+        category: "collaboration_mode",
+        type: "select",
+        currentValue,
+        options: [
+            {value: DEFAULT_COLLABORATION_MODE, name: "Default"},
+            {value: PLAN_COLLABORATION_MODE, name: "Plan", description: "Plan before making changes"},
+        ],
+    };
+}
+
+export function parseCollaborationMode(value: unknown): ModeKind | null {
+    if (value === DEFAULT_COLLABORATION_MODE) return DEFAULT_COLLABORATION_MODE;
+    if (value === PLAN_COLLABORATION_MODE) return PLAN_COLLABORATION_MODE;
+    return null;
+}
+
+export function createCodexCollaborationMode(mode: ModeKind, currentModelId: string) {
+    const modelId = ModelId.fromString(currentModelId);
+    return {
+        mode,
+        settings: {
+            model: modelId.model,
+            reasoning_effort: modelId.effort as ReasoningEffort | null,
+            developer_instructions: null,
+        },
+    };
+}
diff --git a/src/__tests__/CodexACPAgent/data/available-commands-build-in.json b/src/__tests__/CodexACPAgent/data/available-commands-build-in.json
@@ -6,6 +6,20 @@
       "update": {
         "sessionUpdate": "available_commands_update",
         "availableCommands": [
+          {
+            "name": "plan",
+            "description": "Turn plan mode on.",
+            "input": null,
+            "_meta": {
+              "commandAction": {
+                "kind": "setConfigOption",
+                "configId": "collaboration_mode",
+                "value": "plan",
+                "resetValue": "default",
+                "presentation": "state"
+              }
+            }
+          },
           {
             "name": "mcp",
             "description": "List configured Model Context Protocol (MCP) tools.",
diff --git a/src/__tests__/CodexACPAgent/data/available-commands-skills.json b/src/__tests__/CodexACPAgent/data/available-commands-skills.json
@@ -6,6 +6,20 @@
       "update": {
         "sessionUpdate": "available_commands_update",
         "availableCommands": [
+          {
+            "name": "plan",
+            "description": "Turn plan mode on.",
+            "input": null,
+            "_meta": {
+              "commandAction": {
+                "kind": "setConfigOption",
+                "configId": "collaboration_mode",
+                "value": "plan",
+                "resetValue": "default",
+                "presentation": "state"
+              }
+            }
+          },
           {
             "name": "mcp",
             "description": "List configured Model Context Protocol (MCP) tools.",
diff --git a/src/__tests__/CodexACPAgent/data/load-session-history.json b/src/__tests__/CodexACPAgent/data/load-session-history.json
@@ -6,6 +6,20 @@
       "update": {
         "sessionUpdate": "available_commands_update",
         "availableCommands": [
+          {
+            "name": "plan",
+            "description": "Turn plan mode on.",
+            "input": null,
+            "_meta": {
+              "commandAction": {
+                "kind": "setConfigOption",
+                "configId": "collaboration_mode",
+                "value": "plan",
+                "resetValue": "default",
+                "presentation": "state"
+              }
+            }
+          },
           {
             "name": "mcp",
             "description": "List configured Model Context Protocol (MCP) tools.",
diff --git a/src/__tests__/CodexACPAgent/data/load-session-response-item-history-fallback.json b/src/__tests__/CodexACPAgent/data/load-session-response-item-history-fallback.json
@@ -6,6 +6,20 @@
       "update": {
         "sessionUpdate": "available_commands_update",
         "availableCommands": [
+          {
+            "name": "plan",
+            "description": "Turn plan mode on.",
+            "input": null,
+            "_meta": {
+              "commandAction": {
+                "kind": "setConfigOption",
+                "configId": "collaboration_mode",
+                "value": "plan",
+                "resetValue": "default",
+                "presentation": "state"
+              }
+            }
+          },
           {
             "name": "mcp",
             "description": "List configured Model Context Protocol (MCP) tools.",
diff --git a/src/__tests__/CodexACPAgent/initialize.test.ts b/src/__tests__/CodexACPAgent/initialize.test.ts
@@ -85,7 +85,7 @@ describe('CodexACPAgent - initialize', () => {
         ]));
     });
 
-    it('should not opt into experimental app-server capabilities for ACP elicitation support', async () => {
+    it('enables experimental thread settings without requesting attestation', async () => {
         await agent.initialize({
             protocolVersion: acp.PROTOCOL_VERSION,
             clientCapabilities: {
@@ -94,7 +94,10 @@ describe('CodexACPAgent - initialize', () => {
         });
 
         expect(mockCodexConnection.sendRequest).toHaveBeenCalledWith("initialize", expect.objectContaining({
-            capabilities: null,
+            capabilities: {
+                experimentalApi: true,
+                requestAttestation: false,
+            },
         }));
     });
 
diff --git a/src/__tests__/CodexACPAgent/session-config-options.test.ts b/src/__tests__/CodexACPAgent/session-config-options.test.ts
diff --git a/src/__tests__/acp-test-utils.ts b/src/__tests__/acp-test-utils.ts
