# Permission Modes Reference

Complete reference for Claude Code agent permission modes.

Source: https://code.claude.com/docs/en/sub-agents

## Overview

Permission modes control how an agent handles permission prompts (e.g., "Allow Edit to file?"). Choosing the right mode balances automation with safety.

## Modes

### `default`
- **Behavior:** Standard permission prompts for sensitive operations
- **User sees:** Permission dialogs for Write, Edit, Bash, etc.
- **Best for:** Interactive agents where user oversight is desired
- **Risk level:** Low
- **Example use cases:**
  - General-purpose development agents
  - Agents that might make unexpected changes
  - First-time or untrusted agents

### `acceptEdits`
- **Behavior:** Auto-accept file edit permissions (Write, Edit)
- **User sees:** No prompts for file modifications; prompts still appear for Bash
- **Best for:** Code generation and modification agents
- **Risk level:** Medium
- **Example use cases:**
  - Code scaffolding agents
  - Refactoring agents
  - File generation agents

### `dontAsk`
- **Behavior:** Auto-deny all permission prompts
- **User sees:** No prompts; sensitive operations silently fail
- **Best for:** Background tasks that should not interrupt the user
- **Risk level:** Medium (operations may fail silently)
- **Example use cases:**
  - Background monitoring agents
  - Read-only agents that might accidentally try to write
  - Agents where failure is acceptable

### `bypassPermissions`
- **Behavior:** Skip ALL permission checks entirely
- **User sees:** Nothing; all operations proceed without any checks
- **Best for:** Fully trusted automation pipelines
- **Risk level:** **HIGH** - Use with extreme caution
- **Example use cases:**
  - CI/CD pipeline agents
  - Fully automated batch processing
  - Testing harnesses
- **Warning:** This mode can execute ANY command without confirmation. Only use for agents you fully trust in controlled environments.

### `plan`
- **Behavior:** Read-only exploration mode; no modifications allowed
- **User sees:** No prompts; modification attempts are blocked
- **Best for:** Research and analysis agents
- **Risk level:** None
- **Example use cases:**
  - Codebase exploration agents
  - Documentation analysis agents
  - Code review agents (read-only)
  - Architecture analysis agents

## Decision Matrix

| Need | Mode |
|------|------|
| User should approve all changes | `default` |
| Agent modifies files autonomously | `acceptEdits` |
| Agent only reads, never writes | `plan` |
| Agent runs in background, no prompts | `dontAsk` |
| Full automation, no checks | `bypassPermissions` |

## Combining with Tools

Permission modes interact with the `tools` field:

| Scenario | Configuration |
|----------|---------------|
| Read-only agent | `permissionMode: plan` + `tools: "Read, Grep, Glob"` |
| File editor | `permissionMode: acceptEdits` + `tools: "Read, Write, Edit, Glob, Grep"` |
| Shell executor | `permissionMode: default` + `tools: "Bash, Read, Glob"` |
| Full automation | `permissionMode: bypassPermissions` + all tools |

## Best Practices

1. **Start with `default`** and escalate only if needed
2. **Use `plan` for research** - prevents accidental modifications
3. **Prefer `acceptEdits` over `bypassPermissions`** - still blocks dangerous Bash commands
4. **Never use `bypassPermissions` in production** without careful review
5. **Document why** a specific mode was chosen in the agent description
6. **Combine with tool restrictions** for defense in depth:
   ```yaml
   # Safe: read-only mode + read-only tools
   permissionMode: plan
   tools: "Read, Grep, Glob"

   # Dangerous: bypass + all tools (avoid)
   permissionMode: bypassPermissions
   # (no tools restriction = everything allowed)
   ```
