Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: correct how approval lists combine and proxy behavior
A toolkit's own require_approval rules replace the session-wide tag list for that toolkit, and proxy execution is disabled for toolkits where approval could apply rather than asking. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 14:50 UTC
e1c1667f50e5f5af570e522c753216bc85d7bbc6
1 file changed
+19
-2
docs/content/docs/approval-mode.mdx
+19
-2
@@ -88,7 +88,24 @@ const session = await composio.create('user_123', {
88
</Tab>
89
</Tabs>
90
91
-A tool needs approval if any `require_approval` list matches it, whether it's set on the tool's toolkit, the tool itself or one of its [tags](/docs/configuring-sessions#filtering-tools-by-tags). `require_approval` doesn't hide any tools from the agent. It can still find and call them, and the call waits for the user's approval.
91
+A tool needs approval if:
92
+
93
+- its toolkit is in `toolkits.require_approval`,
94
+- its slug is in `tools.<toolkit>.require_approval`, or
95
+- one of its [tags](/docs/configuring-sessions#filtering-tools-by-tags) is in the tag list that applies to its toolkit.
96
+
97
+The session-wide `tags.require_approval` list applies to every toolkit that doesn't set approval rules of its own. Once a toolkit has its own `require_approval` under `tools.<toolkit>`, its own tag list (`tools.<toolkit>.tags.require_approval`) replaces the session-wide one, the same way its tag filter replaces the session-wide filter. If it has no tag list of its own, no tags apply to it. For example:
98
+
99
+```json
100
+{
101
+ "tags": { "require_approval": ["destructiveHint"] },
102
+ "tools": { "gmail": { "require_approval": ["GMAIL_SEND_EMAIL"] } }
103
+}
104
+```
105
+
106
+Here, Gmail only asks before `GMAIL_SEND_EMAIL`, and its destructive tools run without asking. Every other toolkit asks before its destructive tools. To keep asking before Gmail's destructive tools too, add `"tags": { "require_approval": ["destructiveHint"] }` to the `gmail` entry.
107
+
108
+`require_approval` doesn't hide any tools from the agent. It can still find and call them, and the call waits for the user's approval.
109
110
This also applies to each tool call inside `COMPOSIO_MULTI_EXECUTE_TOOL`, the meta tool agents use to run app tools. A batch with two calls that need approval comes back with two questions.
111
@@ -443,7 +460,7 @@ While approval mode is experimental, only `session.execute()` and `session.execu
460
461
- **Providers.** `handle_tool_calls` (`handleToolCalls` in TypeScript) and the tools that framework providers wrap don't ask the user. Depending on the provider, a call that needs approval either raises the error or returns it to the agent as a tool error. Run tool calls with `session.execute()`, as in the example above.
462
- **Custom tools.** If a [custom tool](/docs/extending-sessions/custom-tools-and-toolkits) runs a tool that needs approval through `ctx.execute()`, it raises the error, and there's no way to pass the answer back through the custom tool yet.
446
-- **Proxy execute.** `session.proxy_execute()` (`proxyExecute()` in TypeScript) raises the error when a call needs approval, but can't send an answer.
463
+- **Proxy execute.** A proxy request can't be matched to a tool, so it can't be approved. `session.proxy_execute()` (`proxyExecute()` in TypeScript) is disabled for any toolkit where approval could apply to one of its tools.
464
465
## Next
466