136 lines
No EOL
7.8 KiB
Markdown
136 lines
No EOL
7.8 KiB
Markdown
---
|
||
title: "Configure permissions"
|
||
source: "https://code.claude.com/docs/en/agent-sdk/permissions"
|
||
author:
|
||
published:
|
||
created: 2026-04-17
|
||
description: "Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules."
|
||
tags:
|
||
- "clippings"
|
||
---
|
||
The Claude Agent SDK provides permission controls to manage how Claude uses tools. Use permission modes and rules to define what’s allowed automatically, and the [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input) to handle everything else at runtime.
|
||
|
||
This page covers permission modes and rules. To build interactive approval flows where users approve or deny tool requests at runtime, see [Handle approvals and user input](https://code.claude.com/docs/en/agent-sdk/user-input).
|
||
|
||
## How permissions are evaluated
|
||
|
||
When Claude requests a tool, the SDK checks permissions in this order:
|
||
|
||
![[00cfae3f277bb4ecd4fe501a516e6d34_MD5.svg]]
|
||
|
||
Permission evaluation flow diagram
|
||
|
||
This page focuses on **allow and deny rules** and **permission modes**. For the other steps:
|
||
|
||
- **Hooks:** run custom code to allow, deny, or modify tool requests. See [Control execution with hooks](https://code.claude.com/docs/en/agent-sdk/hooks).
|
||
- **canUseTool callback:** prompt users for approval at runtime. See [Handle approvals and user input](https://code.claude.com/docs/en/agent-sdk/user-input).
|
||
|
||
## Allow and deny rules
|
||
|
||
`allowed_tools` and `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) add entries to the allow and deny rule lists in the evaluation flow above. They control whether a tool call is approved, not whether the tool is available to Claude.
|
||
|
||
| Option | Effect |
|
||
| --- | --- |
|
||
| `allowed_tools=["Read", "Grep"]` | `Read` and `Grep` are auto-approved. Tools not listed here still exist and fall through to the permission mode and `canUseTool`. |
|
||
| `disallowed_tools=["Bash"]` | `Bash` is always denied. Deny rules are checked first and hold in every permission mode, including `bypassPermissions`. |
|
||
|
||
For a locked-down agent, pair `allowedTools` with `permissionMode: "dontAsk"`. Listed tools are approved; anything else is denied outright instead of prompting:
|
||
|
||
```typescript
|
||
const options = {
|
||
allowedTools: ["Read", "Glob", "Grep"],
|
||
permissionMode: "dontAsk"
|
||
};
|
||
```
|
||
|
||
**`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`.
|
||
|
||
You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. These rules are read when the `project` setting source is enabled, which it is for default `query()` options. If you set `setting_sources` (TypeScript: `settingSources`) explicitly, include `"project"` for them to apply. See [Permission settings](https://code.claude.com/docs/en/settings#permission-settings) for the rule syntax.
|
||
|
||
## Permission modes
|
||
|
||
Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions.
|
||
|
||
### Available modes
|
||
|
||
The SDK supports these permission modes:
|
||
|
||
| Mode | Description | Tool behavior |
|
||
| --- | --- | --- |
|
||
| `default` | Standard permission behavior | No auto-approvals; unmatched tools trigger your `canUseTool` callback |
|
||
| `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; `canUseTool` is never called |
|
||
| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |
|
||
| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) |
|
||
| `plan` | Planning mode | No tool execution; Claude plans without making changes |
|
||
| `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |
|
||
|
||
**Subagent inheritance:** When the parent uses `bypassPermissions`, `acceptEdits`, or `auto`, all subagents inherit that mode and it cannot be overridden per subagent. Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting `bypassPermissions` grants them full, autonomous system access without any approval prompts.
|
||
|
||
### Set permission mode
|
||
|
||
You can set the permission mode once when starting a query, or change it dynamically while the session is active.
|
||
|
||
- At query time
|
||
- During streaming
|
||
|
||
Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically.
|
||
|
||
```python
|
||
import asyncio
|
||
from claude_agent_sdk import query, ClaudeAgentOptions
|
||
|
||
async def main():
|
||
async for message in query(
|
||
prompt="Help me refactor this code",
|
||
options=ClaudeAgentOptions(
|
||
permission_mode="default", # Set the mode here
|
||
),
|
||
):
|
||
if hasattr(message, "result"):
|
||
print(message.result)
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
### Mode details
|
||
|
||
#### Accept edits mode (acceptEdits)
|
||
|
||
Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren’t filesystem operations) still require normal permissions.
|
||
|
||
**Auto-approved operations:**
|
||
|
||
- File edits (Edit, Write tools)
|
||
- Filesystem commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`
|
||
|
||
Both apply only to paths inside the working directory or `additionalDirectories`. Paths outside that scope and writes to protected paths still prompt.
|
||
|
||
**Use when:** you trust Claude’s edits and want faster iteration, such as during prototyping or when working in an isolated directory.
|
||
|
||
#### Don’t ask mode (dontAsk)
|
||
|
||
Converts any permission prompt into a denial. Tools pre-approved by `allowed_tools`, `settings.json` allow rules, or a hook run as normal. Everything else is denied without calling `canUseTool`.
|
||
|
||
**Use when:** you want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on `canUseTool` being absent.
|
||
|
||
#### Bypass permissions mode (bypassPermissions)
|
||
|
||
Auto-approves all tool uses without prompts. Hooks still execute and can block operations if needed.
|
||
|
||
Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations.
|
||
|
||
`allowed_tools` does not constrain this mode. Every tool is approved, not just the ones you listed. Deny rules (`disallowed_tools`), explicit `ask` rules, and hooks are evaluated before the mode check and can still block a tool.
|
||
|
||
#### Plan mode (plan)
|
||
|
||
Prevents tool execution entirely. Claude can analyze code and create plans but cannot make changes. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](https://code.claude.com/docs/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts.
|
||
|
||
**Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they’re made.
|
||
|
||
## Related resources
|
||
|
||
For the other steps in the permission evaluation flow:
|
||
|
||
- [Handle approvals and user input](https://code.claude.com/docs/en/agent-sdk/user-input): interactive approval prompts and clarifying questions
|
||
- [Hooks guide](https://code.claude.com/docs/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle
|
||
- [Permission rules](https://code.claude.com/docs/en/settings#permission-settings): declarative allow/deny rules in `settings.json` |