feat(acp): add session/set_config_option support (#3002)

Author: olimorris

doc/codecompanion.txt

@@ -6,7 +6,37 @@ description: Learn how to configure ACP adapters like Claude Code, Gemini CLI an
 
 This section contains configuration which is specific to Agent Client Protocol (ACP) adapters only. There is a lot of shared functionality between ACP and [http](/configuration/adapters-http) adapters. Therefore it's recommended you read the two pages together.
 
-## Configuring Default Adapter
+## Configuring Adapter Settings
+
+To change any of the default settings for an ACP adapter, you can extend it in your CodeCompanion setup. For example, to change the timeout and authentication method for the Gemini CLI adapter, you can do the following:
+
+```lua
+require("codecompanion").setup({
+  adapters = {
+    acp = {
+      gemini_cli = function()
+        return require("codecompanion.adapters").extend("gemini_cli", {
+          commands = {
+            default = {
+              "some-other-gemini"
+              "--experimental-acp",
+            },
+          },
+          defaults = {
+            auth_method = "gemini-api-key",
+            timeout = 20000, -- 20 seconds
+          },
+          env = {
+            GEMINI_API_KEY = "GEMINI_API_KEY",
+          },
+        })
+      end,
+    },
+  },
+})
+```
+
+## Setting a Default Adapter
 
 You can select an ACP adapter to be the default for all chat interactions:
 
@@ -20,33 +50,39 @@ require("codecompanion").setup({
 }),
 ```
 
-## Configuring Default Model
+## Setting Default Session Config Options
 
-You can change the default model used by an ACP adapter. For example, to change the default model for the Claude Code adapter:
+The ACP specification has recently added support for [session config options](https://agentclientprotocol.com/protocol/session-config-options). These are lists of configuration options that agents can share with CodeCompanion at the start of a session such as models, reasoning levels, and more.
+
+### Models
+
+There are numerous was you can set a model in your config and it differs significantly from other session config options because of how CodeCompanion integrates adapters and models into the chat interaction.
 
 ::: code-group
 
-```lua [For Interactions] {4-7}
+```lua [Interactions] {4-7}
 require("codecompanion").setup({
   interactions = {
     chat = {
       adapter = {
-        name = "claude_code",
-        model = "opus",
+        name = "codex",
+        model = "gpt-5.4",
       },
     },
   },
 }),
 ```
 
-```lua [Adapters: Text] {6-8}
+```lua [Adapter String] {6-10}
 require("codecompanion").setup({
   adapters = {
     acp = {
-      claude_code = function()
-        return require("codecompanion.adapters").extend("claude_code", {
+      codex = function()
+        return require("codecompanion.adapters").extend("codex", {
           defaults = {
-            model = "opus"
+            session_config_options = {
+              model = "gpt-5.4"
+            },
           },
         })
       end,
@@ -55,18 +91,20 @@ require("codecompanion").setup({
 }),
 ```
 
-```lua [Adapters: Function] {6-12}
+```lua [Adapter Function] {6-14}
 require("codecompanion").setup({
   adapters = {
     acp = {
-      claude_code = function()
-        return require("codecompanion.adapters").extend("claude_code", {
+      codex = function()
+        return require("codecompanion.adapters").extend("codex", {
           defaults = {
-            ---@param self CodeCompanion.ACPAdapter
-            ---@return string
-            model = function(self)
-              return "opus"
-            end,
+            session_config_options = {
+              ---@param self CodeCompanion.ACPAdapter
+              ---@return string
+              model = function(self)
+                return "gpt-5.4"
+              end,
+            },
           },
         })
       end,
@@ -77,42 +115,21 @@ require("codecompanion").setup({
 
 :::
 
-Using a _function_ is useful for working around the [limitations](https://github.com/zed-industries/claude-code-acp/issues/225) in the Claude Code SDK (which enables ACP support).
+### Others
 
-## Configuring Default Mode
-
-You can configure an ACP adapter to start in a specific agent mode (e.g., plan mode) by setting the `defaults.mode` option. This is useful if you want to always start sessions in plan mode or another specific mode.
-
-::: code-group
-
-```lua [Adapters: Text] {6-8}
-require("codecompanion").setup({
-  adapters = {
-    acp = {
-      claude_code = function()
-        return require("codecompanion.adapters").extend("claude_code", {
-          defaults = {
-            mode = "plan"
-          },
-        })
-      end,
-    }
-  },
-}),
-```
+To set any other session config option, you can pass them in the `defaults.session_config_options` table:
 
-```lua [Adapters: Function] {6-12}
+```lua {6-11}
 require("codecompanion").setup({
   adapters = {
     acp = {
-      claude_code = function()
-        return require("codecompanion.adapters").extend("claude_code", {
+      codex = function()
+        return require("codecompanion.adapters").extend("codex", {
           defaults = {
-            ---@param self CodeCompanion.ACPAdapter
-            ---@return string
-            mode = function(self)
-              return "plan"
-            end,
+            session_config_options = {
+              mode = "Full Access",
+              thought_level = "Xhigh",
+            },
           },
         })
       end,
@@ -121,39 +138,7 @@ require("codecompanion").setup({
 }),
 ```
 
-:::
-
-The mode is applied automatically after the session is established. Available mode IDs can be viewed using the `/mode` slash command in the chat buffer.
-
-## Configuring Adapter Settings
-
-To change any of the default settings for an ACP adapter, you can extend it in your CodeCompanion setup. For example, to change the timeout and authentication method for the Gemini CLI adapter, you can do the following:
-
-```lua
-require("codecompanion").setup({
-  adapters = {
-    acp = {
-      gemini_cli = function()
-        return require("codecompanion.adapters").extend("gemini_cli", {
-          commands = {
-            default = {
-              "some-other-gemini"
-              "--experimental-acp",
-            },
-          },
-          defaults = {
-            auth_method = "gemini-api-key",
-            timeout = 20000, -- 20 seconds
-          },
-          env = {
-            GEMINI_API_KEY = "GEMINI_API_KEY",
-          },
-        })
-      end,
-    },
-  },
-})
-```
+To find out what the available session config options are for a specific adapter you can open the [debug window](/usage/chat-buffer/#debug-window) in the chat buffer.
 
 ## Configuring MCP Servers