feat(tools): better approvals (#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

doc/configuration/chat-buffer.md

@@ -372,31 +372,65 @@ require("codecompanion").setup({
 
 ### Approvals
 
-Some tools, such as [cmd_runner](/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
+::: code-group
+
+```lua [Require Approval] {7}
 require("codecompanion").setup({
   interactions = {
     chat = {
       tools = {
         ["cmd_runner"] = {
           opts = {
-            require_approval_before = false,
+            require_approval_before = true,
           },
         },
-      }
-    }
-  }
+      },
+    },
+  },
+})
+```
+
+```lua [Require Cmd Approval] {7}
+require("codecompanion").setup({
+  interactions = {
+    chat = {
+      tools = {
+        ["cmd_runner"] = {
+          opts = {
+            require_cmd_approval = true,
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+```lua [No YOLO'ing] {7}
+require("codecompanion").setup({
+  interactions = {
+    chat = {
+      tools = {
+        ["cmd_runner"] = {
+          opts = {
+            allowed_in_yolo_mode = 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
+```lua {6-7}
 require("codecompanion").setup({
   interactions = {
     chat = {
@@ -415,7 +449,7 @@ require("codecompanion").setup({
 
 You can configure the plugin to automatically add tools and tool groups to new chat buffers:
 
-```lua
+```lua {6-9}
 require("codecompanion").setup({
   interactions = {
     chat = {

doc/extending/agentic-workflows.md

@@ -31,7 +31,8 @@ prompts = {
       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

doc/usage/chat-buffer/tools.md

@@ -334,23 +334,33 @@ 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
+## Security
 
-### YOLO mode
+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 only given the information that they need to execute a tool successfully. CodeCompanion will endeavour to make sure that the full disk path to your current working directory (cwd) in Neovim is never shared. The impact of this 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 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.
+### Approvals
 
-## Security and Approvals
+> [!NOTE]
+> This applies to CodeCompanion's built-in tools only. ACP agents have their own tools and approval systems.
 
-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 only given the information that they need to execute a tool successfully. CodeCompanion will endeavour to make sure that the full disk path to your current working directory (cwd) in Neovim is never shared. The impact of this 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).
+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.
 
-The plugin also puts approvals at the heart of its workflow. Some tools, such as the [@cmd_runner](#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 [enforce](/configuration/chat-buffer#approvals) an approval for _any_ tool.
+When prompted, the user has four options available to them:
 
-When using CodeCompanion's in-built tools, there are three choices:
+- **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