feat(tools): better approvals (olimorris#2569)

Author: olimorris

doc/codecompanion.txt

@@ -1,4 +1,4 @@
-*codecompanion.txt*        For NVIM v0.11        Last change: 2025 December 19
+*codecompanion.txt*        For NVIM v0.11        Last change: 2025 December 22
 
 ==============================================================================
 Table of Contents                            *codecompanion-table-of-contents*
@@ -997,10 +997,9 @@ The configuration for both types of adapters is exactly the same, however they
 sit within their own tables (`adapters.http.*` and `adapters.acp.*`) and have
 different options available. HTTP adapters use `models` to allow users to
 select the specific LLM they’d like to interact with. ACP adapters use
-`commands` to allow users to customize their interaction with agents
-(e.g. enabling `yolo` mode). As there is a lot of shared functionality between
-the two adapters, it is recommend that you read this page alongside the ACP
-one.
+`commands` to allow users to customize their interaction with agents (e.g.�
+enabling `yolo` mode). As there is a lot of shared functionality between the
+two adapters, it is recommend that you read this page alongside the ACP one.
 
 
 CHANGING AN ADAPTER ~
@@ -1054,7 +1053,7 @@ the adapter’s URL, headers, parameters and other fields at runtime.
   <https://github.com/olimorris/codecompanion.nvim/discussions/601>
 Supported `env` value types: - **Plain environment variable name (string)**: if
 the value is the name of an environment variable that has already been set
-(e.g. `"HOME"` or `"GEMINI_API_KEY"`), the plugin will read the value. -
+(e.g.� `"HOME"` or `"GEMINI_API_KEY"`), the plugin will read the value. -
 **Command (string prefixed with cmd:)**: any value that starts with `cmd:` will
 be executed via the shell. Example: `"cmd:op read
 op://personal/Gemini/credential --no-newline"`. - **Function**: you can provide
@@ -1540,72 +1539,29 @@ dependency and want to refresh the tool availability in the chat buffer.
 
 APPROVALS
 
-Some tools, such as |codecompanion-usage-chat-buffer-tools.html-cmd-runner|,
-require the user to approve any commands before they’re executed. This can be
-changed by altering the config for each tool:
+CodeCompanion allows you to apply safety mechanisms to its built-in tools prior
+to execution.
 
->lua
-    require("codecompanion").setup({
-      interactions = {
-        chat = {
-          tools = {
-            ["cmd_runner"] = {
-              opts = {
-                require_approval_before = false,
-              },
-            },
-          }
-        }
-      }
-    })
-<
-
-You can also force any tool to require your approval by adding in
-`opts.require_approval_before = true`.
 
 
 AUTO SUBMIT (RECURSION)
 
 When a tool executes, it can be useful to automatically send its output back to
 the LLM. This can be achieved by the following options in your configuration:
 
->lua
-    require("codecompanion").setup({
-      interactions = {
-        chat = {
-          tools = {
-            opts = {
-              auto_submit_errors = true, -- Send any errors to the LLM automatically?
-              auto_submit_success = true, -- Send any successful output to the LLM automatically?
-            },
-          }
-        }
-      }
-    })
-<
+`lua {6-7} require("codecompanion").setup({ interactions = { chat = { tools = {
+opts = { auto_submit_errors = true, -- Send any errors to the LLM
+automatically? auto_submit_success = true, -- Send any successful output to the
+LLM automatically? }, } } } })`
 
 
 DEFAULT TOOLS
 
 You can configure the plugin to automatically add tools and tool groups to new
 chat buffers:
 
->lua
-    require("codecompanion").setup({
-      interactions = {
-        chat = {
-          tools = {
-            opts = {
-              default_tools = {
-                "my_tool",
-                "my_tool_group"
-              }
-            },
-          }
-        }
-      }
-    })
-<
+`lua {6-9} require("codecompanion").setup({ interactions = { chat = { tools = {
+opts = { default_tools = { "my_tool", "my_tool_group" } }, } } } })`
 
 This also works for |codecompanion-configuration-extensions|.
 
@@ -2751,7 +2707,7 @@ The fastest way to copy an LLM’s code output is with `gy`. This will yank the
 nearest codeblock.
 
 
-APPLYING AN LLM’S EDITS TO A BUFFER OR FILE ~
+APPLYING AN LLM€�S EDITS TO A BUFFER OR FILE ~
 
 The |codecompanion-usage-chat-buffer-tools-files| tool, combined with the
 |codecompanion-usage-chat-buffer-variables.html-buffer| variable or
@@ -2856,19 +2812,8 @@ CodeCompanion provides comprehensive support for the ACP specification:
 
 SUPPORTED ADAPTERS
 
-  -----------------------------------------------------------------------
-  Adapter         Description             Special Features
-  --------------- ----------------------- -------------------------------
-  Claude Code     Anthropic’s Claude Code OAuth authentication, tool
-                  CLI                     output trimming
-
-  Gemini CLI      Google’s Gemini CLI     Multiple auth methods (OAuth,
-                                          API key, Vertex AI), YOLO mode
-
-  Auggie CLI      Augment Code CLI        Standard ACP support
+Please see the |codecompanion-configuration-adapters-acp| page.
 
-  Codex           OpenAI Codex            Full ACP implementation
-  -----------------------------------------------------------------------
 
 CLIENT CAPABILITIES
 
@@ -3893,20 +3838,7 @@ In the `openai_responses` adapter, the following tools are available:
 - `web_search` - Allow models to search the web for the latest information before generating a response.
 
 
-USEFUL TIPS ~
-
-
-YOLO MODE
-
-The plugin allows you to run tools on autopilot, with YOLO mode. This
-automatically approves any tool use instead of prompting the user, disables any
-diffs, submits errors and success messages and automatically saves any buffers
-that tools may have edited. In the chat buffer, the keymap `gty` will toggle
-YOLO mode on/off. Alternatively, set the global variable
-`vim.g.codecompanion_yolo_mode` to enable this or set it to `nil` to undo this.
-
-
-SECURITY AND APPROVALS ~
+SECURITY ~
 
 CodeCompanion takes security very seriously, especially in a world of agentic
 code development. To that end, every effort is made to ensure that LLMs are
@@ -3917,17 +3849,42 @@ is that the LLM can only work within the cwd when executing tools but will
 minimize actions that are hard to recover from
 <https://www.businessinsider.com/replit-ceo-apologizes-ai-coding-tool-delete-company-database-2025-7>.
 
-The plugin also puts approvals at the heart of its workflow. Some tools, such
-as the |codecompanion--cmd-runner|, require the user to approve any actions
-before they can be executed. If the tool requires this a `vim.fn.confirm`
-dialog will prompt you for a response. You may also
-|codecompanion-configuration-chat-buffer-approvals| an approval for `any` tool.
 
-When using CodeCompanion’s in-built tools, there are three choices:
+APPROVALS
+
+
+  [!NOTE] This applies to CodeCompanion’s built-in tools only. ACP agents have
+  their own tools and approval systems.
+In order to give developers the confidence to use tools, CodeCompanion has
+implemented a comprehensive approval system for it’s built-in tools.
+
+CodeCompanion segregates tool approvals by chat buffer and by tool. This means
+that if you approve a tool in one chat buffer, it is `not` approved for use
+anywhere else. Similarly, if you approve a tool once, you’ll be prompted to
+approve it again next time it’s executed.
+
+When prompted, the user has four options available to them:
+
+- **Allow always** - Always allow this tool/cmd to be executed without further prompts
+- **Allow once** - Allow this tool/cmd to be executed this one time
+- **Reject** - Reject the execution of this tool/cmd and provide a reason
+- **Cancel** - Cancel this tool execution and all other pending tool executions
+
+Certain tools with potentially destructive capabilities have an additional
+layer of protection. Instead of being approved at a tool level, these are
+approved at a command level. Taking the `cmd_runner` tool as an example. If you
+approve an agent to always run `make format`, if it tries to run `make test`,
+you’ll be prompted to approve that command specifically.
+
+Approvals can be reset for the given chat buffer by using the `gtx` keymap.
+
+
+YOLO MODE
 
-1. **Approve** - The tool will be executed
-2. **Reject** - The tool will **NOT** be executed
-3. **Cancel** - All tools in the queue will **NOT** be executed
+To bypass the approval system, you can use `gty` in the chat buffer to enable
+YOLO mode. This will automatically approve all tool executions without
+prompting the user. However, note that some tools such as `cmd_runner` and
+`delete_file` are excluded from this.
 
 
 COMPATIBILITY ~
@@ -4670,7 +4627,7 @@ These handlers manage tool/function calling:
   as a great reference to understand how they’re working with the output of the
   API
 
-OPENAI’S API OUTPUT
+OPENAI€�S API OUTPUT
 
 If we reference the OpenAI documentation
 <https://platform.openai.com/docs/guides/text-generation/chat-completions-api>
@@ -5324,7 +5281,8 @@ Let’s breakdown the prompts in that workflow:
           opts = { auto_submit = false },
           content = function()
             -- Leverage YOLO mode which disables the requirement of approvals and automatically saves any edited buffer
-            vim.g.codecompanion_yolo_mode = true
+            local approvals = require("codecompanion.interactions.chat.tools.approvals")
+            approvals:toggle_yolo_mode()
 
             -- Some clear instructions for the LLM to follow
             return [[### Instructions
@@ -6400,7 +6358,7 @@ tool to function. In the case of Anthropic, we insert additional headers.
 <
 
 Some adapter tools can be a `hybrid` in terms of their implementation. That is,
-they’re an adapter tool that requires a client-side component (i.e. a
+they’re an adapter tool that requires a client-side component (i.e.� a
 built-in tool). This is the case for the
 |codecompanion-usage-chat-buffer-tools-memory| tool from Anthropic. To allow
 for this, ensure that the tool definition in `available_tools` has

lua/codecompanion/interactions/chat/tools/init.lua

@@ -1,6 +1,5 @@
 ---@class CodeCompanion.Tools
 ---@field adapter CodeCompanion.HTTPAdapter The adapter in use for the chat
----@field tools_config table The available tools for the tool system
 ---@field aug number The augroup for the tool
 ---@field bufnr number The buffer of the chat buffer
 ---@field constants table<string, string> The constants for the tool
@@ -11,10 +10,12 @@
 ---@field stdout table The stdout of the tool
 ---@field stderr table The stderr of the tool
 ---@field tool CodeCompanion.Tools.Tool The current tool that's being run
+---@field tools_config table The available tools for the tool system
 ---@field tools_ns number The namespace for the virtual text that appears in the header
 
 local EditTracker = require("codecompanion.interactions.chat.edit_tracker")
 local Orchestrator = require("codecompanion.interactions.chat.tools.orchestrator")
+local approvals = require("codecompanion.interactions.chat.tools.approvals")
 local tool_filter = require("codecompanion.interactions.chat.tools.filter")
 
 local config = require("codecompanion.config")
@@ -258,7 +259,7 @@ function Tools:set_autocmds()
             })
           end
 
-          if vim.g.codecompanion_yolo_mode then
+          if approvals:is_approved(self.bufnr) then
             return auto_submit()
           end
           if self.status == CONSTANTS.STATUS_ERROR and self.tools_config.opts.auto_submit_errors then

lua/codecompanion/interactions/chat/tools/orchestrator.lua

@@ -1,3 +1,4 @@
+local Approvals = require("codecompanion.interactions.chat.tools.approvals")
 local Queue = require("codecompanion.interactions.chat.tools.runtime.queue")
 local Runner = require("codecompanion.interactions.chat.tools.runtime.runner")
 local log = require("codecompanion.utils.log")
@@ -153,11 +154,20 @@ function Orchestrator:_setup_handlers()
   }
 
   self.output = {
-    prompt = function()
+    cmd_string = function()
       if not self.tool then
         return
       end
+      if self.tool.output and self.tool.output.cmd_string then
+        return self.tool.output.cmd_string(self.tool, { tools = self.tools })
+      end
+      return nil
+    end,
 
+    prompt = function()
+      if not self.tool then
+        return
+      end
       if self.tool.output and self.tool.output.prompt then
         return self.tool.output.prompt(self.tool, self.tools)
       end
@@ -250,7 +260,10 @@ function Orchestrator:setup_next_tool(input)
   log:debug("[Orchestrator::setup_next_tool] `%s` tool", self.tool.name)
 
   -- Check if the tool requires approval
-  if self.tool.opts and not vim.g.codecompanion_yolo_mode then
+  if
+    self.tool.opts
+    and not Approvals:is_approved(self.tools.bufnr, { cmd = self.output.cmd_string(), tool_name = self.tool.name })
+  then
     local require_approval_before = self.tool.opts.require_approval_before
 
     if require_approval_before and type(require_approval_before) == "function" then
@@ -282,7 +295,7 @@ function Orchestrator:setup_next_tool(input)
 
         if choice == 1 or choice == 2 then
           if choice == 1 then
-            vim.g.codecompanion_yolo_mode = true
+            Approvals:always(self.tools.bufnr, { cmd = self.output.cmd_string(), tool_name = self.tool.name })
           end
           return self:execute_tool({ cmd = cmd, input = input })
         elseif choice == 3 then