Understanding Claude Code Subagent Permission Modes: default, acceptEdits, dontAsk, bypassPermissions, and plan

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, 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. As specified in 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 (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 at line 26, with concrete implementation examples in implementation/claude-subagents-implementation.md (line 34).

Autonomous editing agent:

# .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:

# .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:

# .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:

# .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 by defining the defaultMode property. This value applies to all subagents using permissionMode: default.

{
  "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 at line 68. This is useful for testing agents with different privilege levels without modifying YAML files.

# 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 configuration, typically set to acceptEdits.
• Configuration sources include agent YAML files, global settings in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}