1# Tool Permissions
2
3Configure which [Agent Panel](./agent-panel.md) tools run automatically and which require your approval.
4For a list of available tools, [see the Tools page](./tools.md).
5
6> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
7> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`).
8
9## Quick Start
10
11Use Zed's Settings Editor to [configure tool permissions](zed://settings/agent.tool_permissions), or add rules directly to your settings file:
12
13```json [settings]
14{
15 "agent": {
16 "tool_permissions": {
17 "default": "allow",
18 "tools": {
19 "terminal": {
20 "default": "confirm",
21 "always_allow": [
22 { "pattern": "^cargo\\s+(build|test|check)" },
23 { "pattern": "^npm\\s+(install|test|run)" }
24 ],
25 "always_confirm": [{ "pattern": "sudo\\s+/" }]
26 }
27 }
28 }
29 }
30}
31```
32
33This example auto-approves `cargo` and `npm` commands in the terminal tool, while requiring manual confirmation on a case-by-case basis for `sudo` commands.
34Non-terminal commands follow the global `"default": "allow"` setting, but tool-specific defaults and `always_confirm` rules can still prompt.
35
36## How It Works
37
38The `tool_permissions` setting lets you customize tool permissions by specifying regex patterns that:
39
40- **Auto-approve** actions you trust
41- **Auto-deny** dangerous actions (blocked even when `tool_permissions.default` is set to `"allow"`)
42- **Always confirm** sensitive actions regardless of other settings
43
44## Supported Tools
45
46| Tool | Input Matched Against |
47| ------------------------ | ---------------------------- |
48| `terminal` | The shell command string |
49| `edit_file` | The file path |
50| `delete_path` | The path being deleted |
51| `move_path` | Source and destination paths |
52| `copy_path` | Source and destination paths |
53| `create_directory` | The directory path |
54| `restore_file_from_disk` | The file paths |
55| `save_file` | The file paths |
56| `fetch` | The URL |
57| `web_search` | The search query |
58
59For MCP tools, use the format `mcp:<server>:<tool_name>`.
60For example, a tool called `create_issue` on a server called `github` would be `mcp:github:create_issue`.
61
62## Configuration
63
64```json [settings]
65{
66 "agent": {
67 "tool_permissions": {
68 "default": "confirm",
69 "tools": {
70 "<tool_name>": {
71 "default": "confirm",
72 "always_allow": [{ "pattern": "...", "case_sensitive": false }],
73 "always_deny": [{ "pattern": "...", "case_sensitive": false }],
74 "always_confirm": [{ "pattern": "...", "case_sensitive": false }]
75 }
76 }
77 }
78 }
79}
80```
81
82### Options
83
84| Option | Description |
85| ---------------- | ------------------------------------------------------------------------------ |
86| `default` | Fallback when no patterns match: `"confirm"` (default), `"allow"`, or `"deny"` |
87| `always_allow` | Patterns that auto-approve (unless deny or confirm also matches) |
88| `always_deny` | Patterns that block immediately—highest priority, cannot be overridden |
89| `always_confirm` | Patterns that always prompt, even when `tool_permissions.default` is `"allow"` |
90
91### Pattern Syntax
92
93```json [settings]
94{
95 "pattern": "your-regex-here",
96 "case_sensitive": false
97}
98```
99
100Patterns use Rust regex syntax.
101Matching is case-insensitive by default.
102
103## Rule Precedence
104
105From highest to lowest priority:
106
1071. **Built-in security rules**: Hardcoded protections (e.g., `rm -rf /`). Cannot be overridden.
1082. **`always_deny`**: Blocks matching actions
1093. **`always_confirm`**: Requires confirmation for matching actions
1104. **`always_allow`**: Auto-approves matching actions
1115. **Tool-specific `default`**: Per-tool fallback when no patterns match (e.g., `tools.terminal.default`)
1126. **Global `default`**: Falls back to `tool_permissions.default` when no tool-specific default is set
113
114## Global Auto-Approve
115
116To auto-approve all tool actions:
117
118```json [settings]
119{
120 "agent": {
121 "tool_permissions": {
122 "default": "allow"
123 }
124 }
125}
126```
127
128This bypasses confirmation prompts for most tools, but `always_deny`, `always_confirm`, built-in security rules, and paths inside Zed settings directories still prompt or block.
129
130## Shell Compatibility
131
132For the `terminal` tool, Zed parses chained commands (e.g., `echo hello && rm file`) to check each sub-command against your patterns.
133
134All supported shells work with tool permission patterns, including sh, bash, zsh, dash, fish, PowerShell 7+, pwsh, cmd, xonsh, csh, tcsh, Nushell, Elvish, and rc (Plan 9).
135
136## Writing Patterns
137
138- Use `\b` for word boundaries: `\brm\b` matches "rm" but not "storm"
139- Use `^` and `$` to anchor patterns to start/end of input
140- Escape special characters: `\.` for literal dot, `\\` for backslash
141
142<div class="warning">
143
144Test carefully—a typo in a deny pattern blocks legitimate actions.
145You can use the "Test Your Rules" checker, available in each individual tool page, to confirm whether a pattern is correctly falling in the desired condition.
146
147</div>
148
149## Built-in Security Rules
150
151Zed includes a small set of hardcoded security rules that **cannot be overridden** by any setting.
152These only apply to the **terminal** tool and block recursive deletion of critical directories:
153
154- `rm -rf /` and `rm -rf /*` — filesystem root
155- `rm -rf ~` and `rm -rf ~/*` — home directory
156- `rm -rf $HOME` / `rm -rf ${HOME}` (and `$HOME/*`) — home directory via environment variable
157- `rm -rf .` and `rm -rf ./*` — current directory
158- `rm -rf ..` and `rm -rf ../*` — parent directory
159
160These patterns catch any flag combination (e.g., `-fr`, `-rfv`, `-r -f`, `--recursive --force`) and are case-insensitive.
161They are checked against both the raw command and each parsed sub-command in chained commands (e.g., `ls && rm -rf /`).
162
163There are no other built-in rules.
164The default settings file ({#action zed::OpenDefaultSettings}) includes commented-out examples for protecting `.env` files, secrets directories, and private keys — you can uncomment or adapt these to suit your needs.
165
166## Permission Request in the UI
167
168When the agent requests permission, you'll see in the thread view a tool card with a menu that includes:
169
170- **Allow once** / **Deny once** — One-time decision
171- **Always for <tool>** — Sets a tool-level default to allow or deny
172- **Always for <pattern>** — Adds an `always_allow` or `always_deny` pattern (when a safe pattern can be extracted)
173
174Selecting "Always for <tool>" sets `tools.<tool>.default` to allow or deny.
175When a pattern can be safely extracted, selecting "Always for <pattern>" adds an `always_allow` or `always_deny` rule for that input.
176MCP tools only support the tool-level option.
177
178## Examples
179
180### Terminal: Auto-Approve Build Commands
181
182```json [settings]
183{
184 "agent": {
185 "tool_permissions": {
186 "tools": {
187 "terminal": {
188 "default": "confirm",
189 "always_allow": [
190 { "pattern": "^cargo\\s+(build|test|check|clippy|fmt)" },
191 { "pattern": "^npm\\s+(install|test|run|build)" },
192 { "pattern": "^git\\s+(status|log|diff|branch)" },
193 { "pattern": "^ls\\b" },
194 { "pattern": "^cat\\s" }
195 ],
196 "always_deny": [
197 { "pattern": "rm\\s+-rf\\s+(/|~)" },
198 { "pattern": "sudo\\s+rm" }
199 ],
200 "always_confirm": [
201 { "pattern": "sudo\\s" },
202 { "pattern": "git\\s+push" }
203 ]
204 }
205 }
206 }
207 }
208}
209```
210
211### File Editing: Protect Sensitive Files
212
213```json [settings]
214{
215 "agent": {
216 "tool_permissions": {
217 "tools": {
218 "edit_file": {
219 "default": "confirm",
220 "always_allow": [
221 { "pattern": "\\.(md|txt|json)$" },
222 { "pattern": "^src/" }
223 ],
224 "always_deny": [
225 { "pattern": "\\.env" },
226 { "pattern": "secrets?/" },
227 { "pattern": "\\.(pem|key)$" }
228 ]
229 }
230 }
231 }
232 }
233}
234```
235
236### Path Deletion: Block Critical Directories
237
238```json [settings]
239{
240 "agent": {
241 "tool_permissions": {
242 "tools": {
243 "delete_path": {
244 "default": "confirm",
245 "always_deny": [
246 { "pattern": "^/etc" },
247 { "pattern": "^/usr" },
248 { "pattern": "\\.git/?$" },
249 { "pattern": "node_modules/?$" }
250 ]
251 }
252 }
253 }
254 }
255}
256```
257
258### URL Fetching: Control External Access
259
260```json [settings]
261{
262 "agent": {
263 "tool_permissions": {
264 "tools": {
265 "fetch": {
266 "default": "confirm",
267 "always_allow": [
268 { "pattern": "docs\\.rs" },
269 { "pattern": "github\\.com" }
270 ],
271 "always_deny": [{ "pattern": "internal\\.company\\.com" }]
272 }
273 }
274 }
275 }
276}
277```
278
279### MCP Tools
280
281```json [settings]
282{
283 "agent": {
284 "tool_permissions": {
285 "tools": {
286 "mcp:github:create_issue": {
287 "default": "confirm"
288 },
289 "mcp:github:create_pull_request": {
290 "default": "confirm"
291 }
292 }
293 }
294 }
295}
296```