Permission Modes in the Claude Agent SDK
Five modes that control how the agent handles tool calls: default, acceptEdits, bypassPermissions, plan, and dontAsk. When to use each and how tool lists interact with permission modes.
Five modes, five behaviors
The Agent SDK gives you five permission modes. Each controls how the agent handles tool calls that are not already approved by your tool list or hooks. Understanding the difference matters — the wrong mode in a production agent either blocks the work you need or lets the agent do things you did not intend.
| Mode | Behavior |
|---|---|
default | Every tool call goes through the canUseTool callback. Nothing runs automatically. |
acceptEdits | File operation tools (write, edit) are auto-approved. Other tools go to the callback. |
bypassPermissions | Every tool runs without asking. Requires the dangerouslyAllowBypassPermissions flag. |
plan | No tools execute. The agent thinks and produces a plan, but takes no action. |
dontAsk | Tools that need approval are silently denied, not queued. No human required in the loop. |
Default mode
When you run in default mode, every tool call routes through the canUseTool callback. If you have not implemented the callback yet, tools that need approval will get blocked — the agent will report that it cannot use them and try to work around the limitation.
This mode is where you end up when you are building interactive agents with human-in-the-loop approval. The canUseTool callback is covered in its own guide.
Accept edits mode
One level up from default. File writes and edits get auto-approved. Everything else still needs the callback.
This is the mode many production agents use when the primary job is document work — reading research, writing summaries, editing deliverables. The agent can do its file-based work without interruption while you still have control over things like web access or bash commands.
Bypass permissions mode
Every tool runs. No approval needed. This is what most examples in this series use during development because it removes friction while you are building.
Two requirements: 1. permissionMode: "bypassPermissions" 2. dangerouslyAllowBypassPermissions: true
Both must be present. The double opt-in is intentional — Anthropic wants you to be explicit about choosing this mode.
for await (const message of query(prompt, {
model: "claude-sonnet-4-5",
permissionMode: "bypassPermissions",
dangerouslyAllowBypassPermissions: true,
})) {
// handle messages
}
> The safety lever you still have: bypassPermissions does not override your tools array. If you have scoped the tool list to only ["read", "write"], the agent cannot run bash even in bypass mode. Tools are checked before permission mode. This is what makes bypass mode safe to use in production when combined with a tight tool list.
Plan mode
The agent produces a structured plan but executes nothing. No files are created. No web searches run. No commands execute.
This maps directly to plan mode in Claude Code. The agent will say something like "Here is what I would do" and outline the steps, but takes no action until you approve.
Useful for:
- Building approval workflows where a human reviews the plan before execution
- Debugging agents that are doing unexpected things — see the plan first
- Demos and client-facing tools where you want to show reasoning without risk
Don't ask mode
Silently denies tool calls that would normally trigger approval. No message to the user. No callback invoked. The tool just does not run.
The primary use case is automated pipelines and CI/CD workflows where there is no human in the loop. In those contexts, you do not want an agent waiting indefinitely for an approval that will never come. dontAsk mode lets the agent proceed with what it can do and skip what it cannot, without blocking.
How the evaluation order works
When the agent wants to use a tool, the SDK evaluates in this order:
1. Tool list check — Is the tool in the tools array? If not, the agent cannot use it. 2. Disallowed tools check — Is the tool in disallowedTools? If yes, block it. 3. Hooks — Do any hooks fire for this tool? Hooks can allow or deny before the mode applies. 4. Permission rules — Are there settings.json rules that auto-approve this tool? 5. Permission mode — Apply the current mode's behavior. 6. canUseTool callback — For tools that still need a decision.
Understanding this order prevents a common confusion: why is bypass mode not letting my agent use a tool? Because the tool was not in the tools array to begin with.
> For operators building production agents: Start with acceptEdits mode as your default for document-heavy workflows. Use bypassPermissions only when you have scoped the tool list tightly and know exactly what the agent can and cannot access. For any agent running without supervision overnight, bypassPermissions with a constrained tools array plus maxBudgetUsd and maxTurns limits is a reasonable production pattern.
---
Author: FractionalSkill