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: add Firewall page and a Governance section
Adds docs/firewall for session hooks: condition_check and prompt_injection_check, with Python and TypeScript examples. Groups it with Approvals under a new Governance section in the sidebar. Page URLs don't change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 22, 2026 at 14:06 UTC
0838819fae1e9bd2415fe72e4c295a64028afe43
4 files changed
+285
-2
docs/content/docs/firewall.mdx
new
+275
@@ -0,0 +1,275 @@
1
+---
2
+title: Firewall
3
+description: Block tool calls and tool results you don't want your agent to act on
4
+keywords: [firewall, hooks, guardrails, condition_check, prompt_injection_check, prompt injection, before_execute, after_execute]
5
+---
6
+
7
+Firewall lets you block actions you don't want your agent to take, or tool results you don't want it to receive. For example, you can stop your agent from:
8
+
9
+- sharing internal pricing with customers
10
+- posting about unreleased products in public Slack channels
11
+- receiving emails that contain a password or API key
12
+- receiving Salesforce or HubSpot records that contain customers' personal details
13
+
14
+You can describe each check in natural language, and Firewall blocks any tool call or result that matches it. Your agent can still use the same tools for everything else.
15
+
16
+Firewall also comes with a built-in check that blocks prompt injection in tool results before it reaches your agent.
17
+
18
+<Callout type="warn" title="Beta">
19
+Firewall is in beta.
20
+</Callout>
21
+
22
+## Custom prompt checks
23
+
24
+You can build custom prompt checks with **hooks**. A hook is attached to a session and runs when your agent calls a tool. It can run before the tool call (`before_execute`) or after it (`after_execute`).
25
+
26
+To write a custom prompt check, use the `condition_check` hook. It lets you block a tool call or its result if it matches a condition you write in natural language.
27
+
28
+Use a `before_execute` hook to block something your agent is about to do, like emailing internal pricing to a customer. Use an `after_execute` hook to block something a tool returns before your agent reads it, like an email that contains a password or API key. Note that an `after_execute` hook can't undo the tool call, since the tool has already run.
29
+
30
+Here's a `before_execute` hook that stops your agent from sharing internal pricing with customers:
31
+
32
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
33
+<Tab value="Python">
34
+```python
35
+session = composio.create(
36
+ user_id="user_123",
37
+ hooks=[
38
+ {
39
+ "id": "no_pricing_to_customers",
40
+ "type": "before_execute",
41
+ "applies_to": {"toolkits": ["gmail"]},
42
+ "handler": {
43
+ "type": "condition_check",
44
+ "condition": "Sharing internal pricing with anyone outside acme.com",
45
+ "action": "block",
46
+ },
47
+ },
48
+ ],
49
+)
50
+```
51
+</Tab>
52
+<Tab value="TypeScript">
53
+```typescript
54
+// @noErrors
55
+import { Composio } from '@composio/core';
56
+const composio = new Composio({ apiKey: 'your_api_key' });
57
+// ---cut---
58
+const session = await composio.create('user_123', {
59
+ hooks: [
60
+ {
61
+ id: 'no_pricing_to_customers',
62
+ type: 'before_execute',
63
+ appliesTo: { toolkits: ['gmail'] },
64
+ handler: {
65
+ type: 'condition_check',
66
+ condition: 'Sharing internal pricing with anyone outside acme.com',
67
+ action: 'block',
68
+ },
69
+ },
70
+ ],
71
+});
72
+```
73
+</Tab>
74
+</Tabs>
75
+
76
+When your agent tries to email internal pricing to someone outside your company, the email isn't sent, and the following is returned when the tool is executed:
77
+
78
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
79
+<Tab value="Python">
80
+```python
81
+result = session.execute(
82
+ "GMAIL_SEND_EMAIL",
83
+ arguments={
84
+ "recipient_email": "jane@customer.com",
85
+ "subject": "Pricing",
86
+ "body": "Our internal floor price is $40 per seat.",
87
+ },
88
+)
89
+
90
+print(result.result_type) # 'blocked'
91
+print(result.error) # 'Blocked by session policy'
92
+print(result.block_reason) # {'type': 'request_blocked', 'hook_id': 'no_pricing_to_customers'}
93
+print(result.hook_results) # [{'id': 'no_pricing_to_customers', 'status': 'evaluated', 'outcome': 'block'}]
94
+```
95
+</Tab>
96
+<Tab value="TypeScript">
97
+```typescript
98
+// @noErrors
99
+import { Composio } from '@composio/core';
100
+const composio = new Composio({ apiKey: 'your_api_key' });
101
+const session = await composio.create('user_123');
102
+// ---cut---
103
+const result = await session.execute('GMAIL_SEND_EMAIL', {
104
+ recipient_email: 'jane@customer.com',
105
+ subject: 'Pricing',
106
+ body: 'Our internal floor price is $40 per seat.',
107
+});
108
+
109
+console.log(result);
110
+// {
111
+// resultType: 'blocked',
112
+// data: {},
113
+// error: 'Blocked by session policy',
114
+// blockReason: { type: 'request_blocked', hookId: 'no_pricing_to_customers' },
115
+// hookResults: [
116
+// { id: 'no_pricing_to_customers', status: 'evaluated', outcome: 'block' },
117
+// ],
118
+// }
119
+```
120
+</Tab>
121
+</Tabs>
122
+
123
+If you use the SDK with an agent framework, your agent sees the message in `error`.
124
+
125
+If more than one hook applies to a call, `hookResults` has an entry for each one, and the call is blocked if any of them blocks it.
126
+
127
+Here's an `after_execute` hook that keeps emails with passwords or API keys away from your agent:
128
+
129
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
130
+<Tab value="Python">
131
+```python
132
+session = composio.create(
133
+ user_id="user_123",
134
+ hooks=[
135
+ {
136
+ "id": "no_secrets_in_results",
137
+ "type": "after_execute",
138
+ "name": "Hide emails that contain passwords or API keys",
139
+ "applies_to": {"toolkits": ["gmail"]},
140
+ "handler": {
141
+ "type": "condition_check",
142
+ "condition": "An email that contains a password, API key or access token",
143
+ "action": "block",
144
+ },
145
+ },
146
+ ],
147
+)
148
+```
149
+</Tab>
150
+<Tab value="TypeScript">
151
+```typescript
152
+// @noErrors
153
+import { Composio } from '@composio/core';
154
+const composio = new Composio({ apiKey: 'your_api_key' });
155
+// ---cut---
156
+const session = await composio.create('user_123', {
157
+ hooks: [
158
+ {
159
+ id: 'no_secrets_in_results',
160
+ type: 'after_execute',
161
+ name: 'Hide emails that contain passwords or API keys',
162
+ appliesTo: { toolkits: ['gmail'] },
163
+ handler: {
164
+ type: 'condition_check',
165
+ condition: 'An email that contains a password, API key or access token',
166
+ action: 'block',
167
+ },
168
+ },
169
+ ],
170
+});
171
+```
172
+</Tab>
173
+</Tabs>
174
+
175
+When Gmail returns an email with a password in it, your agent doesn't receive the email.
176
+
177
+### Writing a condition
178
+
179
+It's important to write a condition as a description of the tool call or result you want blocked, not as an instruction for your agent to follow. A hook blocks a tool call or result when it matches the condition, and an instruction like "Don't share internal pricing with anyone outside acme.com" doesn't describe anything to match. Here are some good and bad ways to write a condition:
180
+
181
+**Good:**
182
+
183
+- "Sharing internal pricing with anyone outside acme.com"
184
+- "An email that contains a password, API key or access token"
185
+
186
+**Bad:**
187
+
188
+- "Don't share internal pricing with anyone outside acme.com"
189
+- "Hide emails that contain a password, API key or access token"
190
+
191
+### How we evaluate a condition
192
+
193
+We use a classifier to compare each tool call to your condition. It sees which tool your agent is calling and the arguments it passes. In an `after_execute` hook, it also sees the data the tool returned.
194
+
195
+The classifier also takes your agent's earlier activity in the session into account. This is important because a single tool call might seem harmless on its own, but when chained together with earlier tool calls, your agent might be doing something it's not allowed to do. For example, an email to a customer with a few numbers in it looks fine, unless your agent just copied those numbers from your internal pricing sheet.
196
+
197
+<Callout type="info">
198
+For projects with ZDR enabled, we don't have context about your agent's historical activity, so our classifier can only judge a tool call in isolation. This may not work for certain kinds of checks.
199
+</Callout>
200
+
201
+## Prompt injection detection
202
+
203
+To block prompt injection, use the `prompt_injection_check` hook. It screens each tool result and blocks it if it contains a prompt injection.
204
+
205
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
206
+<Tab value="Python">
207
+```python
208
+session = composio.create(
209
+ user_id="user_123",
210
+ hooks=[
211
+ {
212
+ "id": "block_injection",
213
+ "type": "after_execute",
214
+ "applies_to": "all",
215
+ "handler": {"type": "prompt_injection_check", "action": "block"},
216
+ },
217
+ ],
218
+)
219
+```
220
+</Tab>
221
+<Tab value="TypeScript">
222
+```typescript
223
+// @noErrors
224
+import { Composio } from '@composio/core';
225
+const composio = new Composio({ apiKey: 'your_api_key' });
226
+// ---cut---
227
+const session = await composio.create('user_123', {
228
+ hooks: [
229
+ {
230
+ id: 'block_injection',
231
+ type: 'after_execute',
232
+ appliesTo: 'all',
233
+ handler: { type: 'prompt_injection_check', action: 'block' },
234
+ },
235
+ ],
236
+});
237
+```
238
+</Tab>
239
+</Tabs>
240
+
241
+`prompt_injection_check` only works in `after_execute` hooks, since tool results are where outside content reaches your agent.
242
+
243
+## Other details
244
+
245
+### Hook IDs and names
246
+
247
+You're required to assign a unique `id` to each hook in a session. You can also set an optional `name`. When the hook blocks a call, the name is included in the `error` message your agent sees.
248
+
249
+### Which tool calls are checked
250
+
251
+A hook runs on calls to the toolkits listed in its `appliesTo`, or on calls to every toolkit if `appliesTo` is `'all'`. That includes proxy calls to a toolkit's API, and tool calls your agent makes from a Workbench script or with multi-execute.
252
+
253
+Keep in mind that hooks don't currently run on Composio meta tools themselves, so a condition like "Running a Workbench script" won't block anything.
254
+
255
+### Updating checks
256
+
257
+To change a session's checks, pass a new `hooks` list to `session.update()`. The new list replaces the old one, so include every hook you want to keep. To remove them all, pass `null` (`None` in Python).
258
+
259
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
260
+<Tab value="Python">
261
+```python
262
+session.update(hooks=[...]) # every hook you want to keep
263
+```
264
+</Tab>
265
+<Tab value="TypeScript">
266
+```typescript
267
+// @noErrors
268
+import { Composio } from '@composio/core';
269
+const composio = new Composio({ apiKey: 'your_api_key' });
270
+const session = await composio.create('user_123');
271
+// ---cut---
272
+await session.update({ hooks: [/* every hook you want to keep */] });
273
+```
274
+</Tab>
275
+</Tabs>
docs/content/docs/meta.json
+3
-1
@@ -13,13 +13,15 @@
13
"how-composio-works",
14
"configuring-sessions",
15
"session-configs",
16
- "approvals",
16
"instant-tools",
17
"toolkits",
18
"tool-tags",
19
"authentication",
20
"triggers",
21
"skills",
22
+ "---Governance---",
23
+ "approvals",
24
+ "firewall",
25
"---Guides---",
26
"consumer-agents",
27
"b2b-agents",
docs/lib/home-navigation.ts
+6
-1
@@ -131,6 +131,7 @@ export const DOCS_PRODUCTS = {
131
'/docs/configuring-sessions',
132
'/docs/session-configs',
133
'/docs/approvals',
134
+ '/docs/firewall',
135
'/docs/instant-tools',
136
'/docs/toolkits',
137
'/docs/tool-tags',
@@ -169,7 +170,6 @@ export const DOCS_PRODUCTS = {
170
{ url: '/docs/configuring-sessions' },
171
{ url: '/docs/session-configs' },
172
{ url: '/docs/sessions-via-mcp' },
172
- { url: '/docs/approvals' },
173
],
174
},
175
{
@@ -177,6 +177,11 @@ export const DOCS_PRODUCTS = {
177
label: 'Toolkits & Tools',
178
links: [{ url: '/docs/toolkits' }, { url: '/docs/tool-tags' }, { url: '/docs/instant-tools' }],
179
},
180
+ {
181
+ type: 'group',
182
+ label: 'Governance',
183
+ links: [{ url: '/docs/approvals' }, { url: '/docs/firewall' }],
184
+ },
185
{
186
type: 'group',
187
label: 'Authentication',
docs/tests/static/navigation.test.ts
+1
@@ -58,6 +58,7 @@ describe("Navigation - meta.json validity", () => {
58
expect(separators).toEqual([
59
"---Get Started---",
60
"---Core concepts---",
61
+ "---Governance---",
62
"---Guides---",
63
"---Direct execution (legacy)---",
64
"---Migration and security---",