@devries-cameron20 / composio-1 / commits / 7a1b73018
Fork 0

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: describe allowing, blocking and asking first for tools consistently

Configuring Sessions, Approval mode and Tool tags now use the same allow / ask first / block model for tools, with per-toolkit overrides. Bumps the docs @composio/core to 0.24.0, whose tag types include createHint and updateHint. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Mukund committed Oct 15, 2026 at 15:27 UTC 7a1b73018ad61b171ea40804e9c0c5e30a8d842d
3 files changed +44 -58
docs/content/docs/approval-mode.mdx
+17 -17
@@ -9,12 +9,12 @@ By default, your agent can run any tool in a session as soon as it decides to. F
9 When your agent calls a tool that requires approval, Composio doesn't run it. It returns a question for the user instead, and runs the tool once your app sends back their approval.
10
11 <Callout type="warn" title="Experimental">
12 -Approval mode is experimental, and its SDK options may change. Answering questions needs `composio` newer than 0.26.0 (Python) or `@composio/core` newer than 0.23.0 (TypeScript).
12 +Approval mode is experimental, and its SDK options may change. Answering questions needs `composio` newer than 0.27.0 (Python) or `@composio/core` newer than 0.24.0 (TypeScript).
13 </Callout>
14
15 -## Configuring approvals
15 +## Configuring the session
16
17 -You set approvals when you create or update a session, in three steps. They're the same steps as building a [Session config](/docs/configuring-sessions#using-a-saved-session-config) in the Composio Dashboard, and produce the same configuration. The snippets in each step are Python. In TypeScript, `require_approval` is `requireApproval`.
17 +You choose which tools the agent can use, and which ones ask first, when you create or update a session. It takes three steps. They're the same steps as building a [Session config](/docs/configuring-sessions#using-a-saved-session-config) in the Composio Dashboard, and produce the same configuration. The snippets in each step are Python. In TypeScript, `require_approval` is `requireApproval`.
18
19 ### 1. Enable toolkits
20
@@ -24,7 +24,7 @@ List the toolkits the agent can use in `toolkits.enable`:
24 toolkits={"enable": ["gmail", "github"]}
25 ```
26
27 -### 2. Choose what each tag does
27 +### 2. Allow, ask first or block tools by type
28
29 Every tool has a [tag](/docs/tool-tags) for the type of action it takes:
30
@@ -35,13 +35,13 @@ Every tool has a [tag](/docs/tool-tags) for the type of action it takes:
35 | `updateHint` | Update |
36 | `destructiveHint` | Destructive |
37
38 -For each tag, choose one of:
38 +Use the tags to set what happens to each type of tool:
39
40 -- **Allow:** leave the tag out.
41 -- **Ask first:** add the tag to `tags.require_approval`.
40 +- **Allow:** leave the tag out. These tools run without asking.
41 +- **Ask first:** add the tag to `tags.require_approval`. These tools wait for the user's approval.
42 - **Block:** add the tag to `tags.disable`. The agent can't see or call these tools.
43
44 -For example, to allow reads, ask before creates and updates, and block destructive actions:
44 +For example, to allow tools that read, ask before tools that create or update, and block tools that delete:
45
46 ```python
47 tags={
@@ -50,13 +50,13 @@ tags={
50 }
51 ```
52
53 -### 3. Override the tags for a toolkit
53 +### 3. Override for specific toolkits
54
55 -The global `tags` from step 2 apply to every toolkit. To treat a toolkit differently, add an override for it under `tools.<toolkit>`.
55 +Step 2 applies to the tools of every toolkit. To handle a toolkit's tools differently, add an override for it under `tools.<toolkit>`.
56
57 -An override replaces the global `tags` for that toolkit. The global `tags` no longer apply to it at all, so the override has to say everything about the toolkit. An override is either by tag or by tool.
57 +The override replaces step 2 for that toolkit. Step 2 no longer applies to its tools at all, so the override has to cover all of them. You can override by type or tool by tool.
58
59 -**By tag.** Set `tools.<toolkit>.tags` the same way as step 2. Repeat any global settings you still want for the toolkit. For example, this override makes GitHub's destructive actions ask first instead of being blocked. Creates and updates are listed again so they still ask first:
59 +**By type.** Set `tools.<toolkit>.tags` the same way as step 2. Repeat anything from step 2 you still want for the toolkit. For example, this override makes GitHub's tools that delete ask first instead of being blocked. Tools that create or update are listed again so they still ask first:
60
61 ```python
62 tools={
@@ -66,7 +66,7 @@ tools={
66 }
67 ```
68
69 -**By tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones that ask first in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. For example, this override lets the agent fetch and send Gmail, and asks before sending:
69 +**Tool by tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones that ask first in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. For example, this override lets the agent fetch and send Gmail, and asks before sending:
70
71 ```python
72 tools={
@@ -77,7 +77,7 @@ tools={
77 }
78 ```
79
80 -Always set `require_approval` in a by-tool override, even to `[]`. Without it, the global `tags.require_approval` isn't overridden and still applies to the listed tools.
80 +Always set `require_approval` in a tool-by-tool override, even to `[]`. Without it, the tools you list still ask first if step 2 says so.
81
82 Use one or the other for a toolkit, not both.
83
@@ -133,9 +133,9 @@ const session = await composio.create('user_123', {
133
134 With this session:
135
136 -- **GitHub** has a by-tag override. Reads run freely, and creates, updates and deletes ask first.
137 -- **Gmail** has a by-tool override. Fetching emails runs freely, sending asks first, and no other Gmail tools are available.
138 -- **Any other toolkit** isn't enabled. If you enabled one without an override, the global `tags` would apply to it: reads run freely, creates and updates ask first, and destructive actions are blocked.
136 +- **GitHub** is overridden by type. Tools that read run freely, and tools that create, update or delete ask first.
137 +- **Gmail** is overridden tool by tool. Fetching emails runs freely, sending asks first, and no other Gmail tools are available.
138 +- **Any other toolkit** isn't enabled. If you enabled one without an override, step 2 would apply to its tools: tools that read run freely, tools that create or update ask first, and tools that delete are blocked.
139
140 Asking first doesn't hide a tool from the agent. It can still find and call it, and the call waits for the user's approval. 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.
141
docs/content/docs/configuring-sessions.mdx
+22 -37
@@ -403,26 +403,20 @@ const session = await composio.create("user_123", {
403
404 ## Filtering tools by tags
405
406 -Every tool has a tag for the type of action it takes: `readOnlyHint`, `createHint`, `updateHint` or `destructiveHint`. See [Tool tags](/docs/tool-tags) for what each one means and how tools get them.
406 +Every tool has a [tag](/docs/tool-tags) for the type of action it takes: `readOnlyHint`, `createHint`, `updateHint` or `destructiveHint`. Use the tags to set what happens to each type of tool:
407
408 -To apply tag filters across all toolkits, pass `tags` at the session level:
408 +- **Allow:** leave the tag out. This is the default.
409 +- **Block:** add the tag to `tags.disable`. The agent can't see or call these tools.
410 +- **Ask first:** add the tag to `tags.require_approval`. The agent can call these tools, but the session asks the user before they run. See [Approval mode](/docs/approval-mode).
411 +
412 +For example, to block every tool that can delete something:
413
414 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
415 <Tab value="Python">
416 ```python
413 -# Only include tools that read or create; no updates or deletes
414 -session = composio.sessions.create(
415 - user_id="user_123",
416 - tags=["readOnlyHint", "createHint"]
417 -)
418 -
419 -# Enable some tags, disable others
417 session = composio.sessions.create(
418 user_id="user_123",
422 - tags={
423 - "enable": ["readOnlyHint"],
424 - "disable": ["destructiveHint"]
425 - }
419 + tags={"disable": ["destructiveHint"]}
420 )
421 ```
422 </Tab>
@@ -431,36 +425,29 @@ session = composio.sessions.create(
425 import { Composio } from '@composio/core';
426 const composio = new Composio({ apiKey: 'your_api_key' });
427 // ---cut---
434 -// Only include read-only tools
428 const session = await composio.create("user_123", {
436 - tags: ["readOnlyHint"]
437 -});
438 -
439 -// Enable some tags, disable others
440 -const sessionWithTagConfig = await composio.create("user_123", {
441 - tags: {
442 - enable: ["readOnlyHint"],
443 - disable: ["destructiveHint"]
444 - }
429 + tags: { disable: ["destructiveHint"] }
430 });
431 ```
432 </Tab>
433 </Tabs>
434
450 -To override the global tags for a specific toolkit, set `tags` inside that toolkit's `tools` config:
435 +### Overriding for a toolkit
436 +
437 +The session-wide `tags` apply to the tools of every toolkit. To handle a toolkit's tools differently, override them in `tools.<toolkit>.tags`. The override replaces the session-wide `tags` for that toolkit, so list everything you still want to block for it.
438 +
439 +For example, this session blocks tools that update or delete everywhere, but overrides GitHub so only its tools that delete are blocked:
440
441 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
442 <Tab value="Python">
443 ```python
444 session = composio.sessions.create(
445 user_id="user_123",
457 - # Global: only read-only tools
458 - tags=["readOnlyHint"],
446 + # Everywhere: block tools that update or delete
447 + tags={"disable": ["updateHint", "destructiveHint"]},
448 tools={
460 - # Override for GitHub: allow all tools except destructive
461 - "github": {"tags": {"disable": ["destructiveHint"]}},
462 - # Override for Gmail: only read-only tools (explicit)
463 - "gmail": {"tags": ["readOnlyHint"]}
449 + # GitHub: block only tools that delete
450 + "github": {"tags": {"disable": ["destructiveHint"]}}
451 }
452 )
453 ```
@@ -471,20 +458,18 @@ import { Composio } from '@composio/core';
458 const composio = new Composio({ apiKey: 'your_api_key' });
459 // ---cut---
460 const session = await composio.create("user_123", {
474 - // Global: only read-only tools
475 - tags: ["readOnlyHint"],
461 + // Everywhere: block tools that update or delete
462 + tags: { disable: ["updateHint", "destructiveHint"] },
463 tools: {
477 - // Override for GitHub: allow all tools except destructive
478 - github: { tags: { disable: ["destructiveHint"] } },
479 - // Override for Gmail: only read-only tools (explicit)
480 - gmail: { tags: ["readOnlyHint"] }
464 + // GitHub: block only tools that delete
465 + github: { tags: { disable: ["destructiveHint"] } }
466 }
467 });
468 ```
469 </Tab>
470 </Tabs>
471
487 -To keep a tool available but have the session ask the user before it runs, see [Approval mode](/docs/approval-mode).
472 +Listing a toolkit's tools with `enable` or `disable`, as in [Enabling or disabling specific tools](#enabling-or-disabling-specific-tools), also overrides the session-wide `tags` for that toolkit.
473
474 ## Preloading tools
475
docs/content/docs/tool-tags.mdx
+5 -4
@@ -45,12 +45,13 @@ To see a tool's tags, read its `tags` field with [Get a tool](/reference/api-ref
45
46 ## Using tags in a session
47
48 -Use the four tags to:
48 +A session uses the tags to decide what happens to each type of tool:
49
50 -- **Filter tools.** Hide tools by tag across the session or per toolkit. See [Filtering tools by tags](/docs/configuring-sessions#filtering-tools-by-tags).
51 -- **Ask first.** Have the session ask the user before tools with a tag run. See [Approval mode](/docs/approval-mode).
50 +- **Allow:** the tools run without asking. This is the default.
51 +- **Block:** the agent can't see or call the tools. See [Filtering tools by tags](/docs/configuring-sessions#filtering-tools-by-tags).
52 +- **Ask first:** the tools wait for the user's approval. See [Approval mode](/docs/approval-mode).
53
53 -Sessions also accept the MCP hints `idempotentHint` and `openWorldHint`, but only some tools set them, so don't use them for access control. Session configs in the Composio Dashboard only accept the four tags above.
54 +You set this for the whole session, then override it for specific toolkits.
55
56 ## Next
57