# Understanding Claude Code Subagent Permission Modes: default, acceptEdits, dontAsk, bypassPermissions, and plan > Master Claude Code subagent permission modes default acceptEdits dontAsk bypassPermissions and plan Learn how these five modes control file system edits from manual review to full autonomy. - Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) - Tags: deep-dive - Published: 2026-03-12 --- **Claude Code subagent permission modes control how autonomous agents handle file system edits through five distinct behaviors ranging from interactive prompts to fully autonomous execution.** The `shanraisshan/claude-code-best-practice` repository defines a comprehensive framework for configuring Claude Code subagents using YAML front-matter. Understanding these **subagent permission modes** is essential for safely deploying autonomous agents that range from read-only explorers to fully privileged automation tools. ## How Permission Modes Govern Agent Behavior In Claude Code, subagents are defined by YAML front-matter blocks that declare their capabilities and constraints. The **`permissionMode`** field determines how the runtime handles file modifications, tool invocations, and user interactions. According to the specification in [`best-practice/claude-subagents.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-subagents.md), this field accepts one of five values that control whether an agent asks for confirmation, applies changes automatically, or operates in a sandboxed planning state. ## The Five Subagent Permission Modes ### default The **`default`** mode defers to the global project configuration defined in [`claude-settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/claude-settings.json). As specified in [`best-practice/claude-settings.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-settings.md) at line 176, the typical global default is `"defaultMode": "acceptEdits"`, meaning subagents without explicit mode declarations inherit autonomous editing privileges. Use this mode when you want project-wide consistency without hardcoding behavior into individual agent files. ### acceptEdits The **`acceptEdits`** mode grants full autonomy by automatically accepting any file edits or tool-generated changes without prompting the user. This mode is implemented in the Weather Agent example at [`.claude/agents/weather-agent.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/weather-agent.md) (line 8), where the configuration enables fast, autonomous operation. Deploy this mode only for trusted agents that require write access to code or data. ### dontAsk The **`dontAsk`** mode creates a read-only, non-interactive agent that runs without prompts and silently skips any write-type actions. When configured with this mode, the agent cannot invoke `Write` or `Edit` tools, making it ideal for code exploration agents that must analyze repositories without risk of modification. ### bypassPermissions The **`bypassPermissions`** mode overrides all permission checks, allowing the agent to read, write, edit, and execute any allowed tool regardless of global safety settings. This privileged mode is reserved for debugging scenarios or automation workflows where you explicitly need to override security constraints. ### plan The **`plan`** mode executes in a sandboxed, planning-only state where the agent can read files and reason about solutions but cannot invoke any tool that mutates state. Instead of applying changes, the agent outputs a structured plan description, making this mode suitable for design review workflows or PR generation preparation where human approval is required before execution. ## Configuring Permission Modes ### Front-Matter Declaration Define the mode directly in the agent's YAML front-matter file. The field is documented in [`best-practice/claude-subagents.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-subagents.md) at line 26, with concrete implementation examples in [`implementation/claude-subagents-implementation.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/implementation/claude-subagents-implementation.md) (line 34). **Autonomous editing agent:** ```yaml # .claude/agents/example-auto.md --- name: example-auto description: Fully autonomous agent that can modify code. tools: Read, Write, Edit, Bash permissionMode: acceptEdits # changes are applied automatically --- ``` **Read-only explorer:** ```yaml # .claude/agents/code-explorer.md --- name: code-explorer description: Fast code exploration without any writes. tools: Read, Glob, Grep permissionMode: dontAsk # no prompts, no write tools allowed --- ``` **Privileged automation:** ```yaml # .claude/agents/privileged-task.md --- name: privileged-task description: Runs with full access, ignoring global safety settings. tools: Read, Write, Edit, Bash, WebFetch permissionMode: bypassPermissions --- ``` **Plan-only workflow:** ```yaml # .claude/agents/planner.md --- name: planner description: Generates a step-by-step plan without touching files. tools: Read, Grep permissionMode: plan --- ``` ### Global Default Configuration Set the project-wide default in [`best-practice/claude-settings.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-settings.md) by defining the `defaultMode` property. This value applies to all subagents using `permissionMode: default`. ```json { "defaultMode": "acceptEdits" } ``` ### CLI Session Overrides Override permission modes for individual sessions using the `--permission-mode` flag documented in [`best-practice/claude-cli-startup-flags.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-cli-startup-flags.md) at line 68. This is useful for testing agents with different privilege levels without modifying YAML files. ```bash # Start a session that will never ask for confirmation claude --permission-mode acceptEdits # Start a read-only planning session claude --permission-mode plan ``` ## Summary - **Subagent permission modes** in Claude Code are declared via the `permissionMode` field in YAML front-matter. - **`acceptEdits`** provides full autonomy for trusted agents, while **`dontAsk`** creates silent, read-only explorers. - **`bypassPermissions`** removes all safety constraints for privileged debugging scenarios. - **`plan`** enables safe architecture design by preventing state mutation while allowing analysis. - **`default`** inherits from the global [`claude-settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/claude-settings.json) configuration, typically set to `acceptEdits`. - Configuration sources include agent YAML files, global settings in [`best-practice/claude-settings.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-settings.md), and CLI flags. ## Frequently Asked Questions ### What happens if I don't specify a permissionMode in my subagent? If you omit the `permissionMode` field or set it to `default`, the agent inherits the global default defined in your project's [`claude-settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/claude-settings.json) file. According to the best practice guide, this typically resolves to `acceptEdits`, meaning the agent will automatically apply edits unless you explicitly configure otherwise. ### Can I switch between permission modes without editing the agent file? Yes. You can override any agent's configured mode by starting your Claude Code session with the `--permission-mode` CLI flag. For example, running `claude --permission-mode plan` forces all agents into plan-only mode for that session, regardless of their YAML front-matter declarations. ### Is bypassPermissions safe to use in production workflows? No. The **`bypassPermissions`** mode should be reserved for debugging or highly controlled automation scenarios. This mode ignores all permission checks defined in your global settings, allowing the agent to execute any available tool without constraints, which introduces significant risk if the agent encounters unexpected states or malicious instructions. ### How does plan mode differ from dontAsk mode? While both modes restrict file modifications, they serve different purposes. **`plan`** mode allows the agent to reason about changes and output a detailed implementation strategy, but it cannot execute tools that mutate state. **`dontAsk`** mode allows the agent to execute read tools silently without user prompts, but it actively skips write operations rather than just planning them.