feat(acp): can specify default mode (#2901)

Author: mrjones2014

doc/codecompanion.txt

@@ -1033,6 +1033,17 @@ Using a `function` is useful for working around the limitations
 Code SDK (which enables ACP support).
 
 
+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.
+
+
+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.
+
+
 ADAPTER SETTINGS ~
 
 To change any of the default settings for an ACP adapter, you can extend it in

doc/configuration/adapters-acp.md

@@ -79,6 +79,52 @@ 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).
 
+## 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,
+    }
+  },
+}),
+```
+
+```lua [Adapters: Function] {6-12}
+require("codecompanion").setup({
+  adapters = {
+    acp = {
+      claude_code = function()
+        return require("codecompanion.adapters").extend("claude_code", {
+          defaults = {
+            ---@param self CodeCompanion.ACPAdapter
+            ---@return string
+            mode = function(self)
+              return "plan"
+            end,
+          },
+        })
+      end,
+    }
+  },
+}),
+```
+
+:::
+
+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/codecompanion/acp/init.lua

@@ -151,6 +151,7 @@ function Connection:connect_and_initialize()
   end
 
   self:apply_default_model()
+  self:apply_default_mode()
 
   return self
 end
@@ -299,6 +300,53 @@ function Connection:apply_default_model()
   return self:set_model(model_id)
 end
 
+---Apply the default mode from the adapter config
+---@return boolean
+function Connection:apply_default_mode()
+  if not self._modes then
+    return false
+  end
+
+  local default_mode = self.adapter_modified and self.adapter_modified.defaults and self.adapter_modified.defaults.mode
+  if not default_mode then
+    return false
+  end
+
+  -- Support function values for default mode
+  if type(default_mode) == "function" then
+    default_mode = default_mode(self.adapter_modified)
+  end
+
+  if type(default_mode) ~= "string" or default_mode == "" then
+    return false
+  end
+
+  -- Check if the requested mode is available
+  local mode_id = nil
+  for _, mode in ipairs(self._modes.availableModes or {}) do
+    -- Match by id first, then by partial name match (e.g., "plan" matches mode with name containing "plan")
+    if mode.id == default_mode then
+      mode_id = mode.id
+      break
+    elseif mode.name and mode.name:lower():find(default_mode:lower(), 1, true) then
+      mode_id = mode.id
+      break
+    end
+  end
+
+  if not mode_id then
+    log:warn("[acp::apply_default_mode] Mode `%s` not found in available modes", default_mode)
+    return false
+  end
+
+  if mode_id == self._modes.currentModeId then
+    log:debug("[acp::apply_default_mode] Mode `%s` is already selected", mode_id)
+    return true
+  end
+
+  return self:set_mode(mode_id)
+end
+
 ---Create the ACP process
 ---@return boolean success
 function Connection:start_agent_process()

lua/codecompanion/adapters/acp/claude_code.lua

@@ -24,6 +24,7 @@ return {
   defaults = {
     mcpServers = {},
     timeout = 20000, -- 20 seconds
+    -- mode = "plan", -- Optional: Set default agent mode (e.g., "plan")
   },
   env = {
     CLAUDE_CODE_OAUTH_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN",

lua/codecompanion/adapters/acp/init.lua

@@ -95,6 +95,12 @@ function Adapter.resolve(adapter, opts)
       })
     end
 
+    if opts.mode then
+      adapter = vim.tbl_deep_extend("force", vim.deepcopy(adapter), {
+        defaults = { mode = opts.mode },
+      })
+    end
+
     adapter = Adapter.new(adapter)
   elseif type(adapter) == "string" then
     if not config.adapters.acp or not config.adapters.acp[adapter] then