|
| 1 | +# Permission Modes & Rules Reference |
| 2 | + |
| 3 | +This reference covers the complete permission system for Claude Code agents, including all permission modes and the permission rule syntax for fine-grained access control. |
| 4 | + |
| 5 | +## Permission Modes |
| 6 | + |
| 7 | +Agents can specify a `permissionMode` in frontmatter to control how permission requests are handled: |
| 8 | + |
| 9 | +```yaml |
| 10 | +permissionMode: acceptEdits |
| 11 | +``` |
| 12 | +
|
| 13 | +### All Permission Modes |
| 14 | +
|
| 15 | +| Mode | Behavior | Use Case | |
| 16 | +| ------------------- | ------------------------------------------------------------ | --------------------------------------------------- | |
| 17 | +| `default` | Standard permission model — prompts user for each action | General-purpose agents, untrusted contexts | |
| 18 | +| `acceptEdits` | Auto-accept file edit operations (Write, Edit, NotebookEdit) | Code generation agents that need to write files | |
| 19 | +| `dontAsk` | Skip all permission dialogs | Trusted automation agents, CI/CD agents | |
| 20 | +| `bypassPermissions` | Full bypass of all permission checks | Fully trusted agents only | |
| 21 | +| `plan` | Planning mode — propose changes without executing | Architecture/design agents, review agents | |
| 22 | +| `delegate` | Coordination-only — restricted to team management tools | Team lead agents that should not implement directly | |
| 23 | + |
| 24 | +### Mode Details |
| 25 | + |
| 26 | +#### default |
| 27 | + |
| 28 | +The standard interactive permission model. Claude asks the user before performing actions that require permission. This is the implicit mode when `permissionMode` is not specified. |
| 29 | + |
| 30 | +**When to use:** General-purpose agents, agents handling sensitive operations, agents in untrusted contexts. |
| 31 | + |
| 32 | +#### acceptEdits |
| 33 | + |
| 34 | +Auto-accepts file writing operations (Write, Edit, NotebookEdit) without prompting. Other operations (Bash, etc.) still require user permission. |
| 35 | + |
| 36 | +**When to use:** Code generation agents, refactoring agents, documentation generators. |
| 37 | + |
| 38 | +#### dontAsk |
| 39 | + |
| 40 | +Skips all permission dialogs. The agent proceeds without user confirmation for any action. |
| 41 | + |
| 42 | +**When to use:** Trusted automation, background agents, CI/CD pipelines where no user is present. |
| 43 | + |
| 44 | +#### bypassPermissions |
| 45 | + |
| 46 | +Full permission bypass with no restrictions. More permissive than `dontAsk` as it bypasses even system-level restrictions. |
| 47 | + |
| 48 | +**When to use:** Only for fully trusted agents in controlled environments. Never for plugins distributed to unknown users. |
| 49 | + |
| 50 | +#### plan |
| 51 | + |
| 52 | +Planning mode restricts the agent to read-only operations. The agent can explore the codebase and propose changes but cannot execute them. Requires user approval before any modifications. |
| 53 | + |
| 54 | +**When to use:** Architecture planning, design review, impact analysis agents. |
| 55 | + |
| 56 | +#### delegate |
| 57 | + |
| 58 | +Restricts the agent to team coordination tools only: spawning teammates, sending messages, managing tasks, and shutting down teammates. The agent cannot use implementation tools (Edit, Write, Bash, etc.) directly. |
| 59 | + |
| 60 | +**When to use:** Team lead agents that should coordinate work across teammates without implementing tasks themselves. |
| 61 | + |
| 62 | +```yaml |
| 63 | +# Team lead agent that only coordinates |
| 64 | +permissionMode: delegate |
| 65 | +``` |
| 66 | + |
| 67 | +## Permission Rules |
| 68 | + |
| 69 | +Permission rules provide fine-grained control over specific tool access. They are configured in settings files (not agent frontmatter) and apply based on precedence. |
| 70 | + |
| 71 | +### Rule Syntax |
| 72 | + |
| 73 | +Rules are specified in `settings.json` under `permissions`: |
| 74 | + |
| 75 | +```json |
| 76 | +{ |
| 77 | + "permissions": { |
| 78 | + "allow": ["Read", "Bash(npm test)", "Edit(src/**)"], |
| 79 | + "deny": ["Bash(rm *)", "Bash(git push --force*)"] |
| 80 | + } |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +### Tool Specifiers |
| 85 | + |
| 86 | +| Pattern | Matches | Example | |
| 87 | +| -------------------- | ------------------------------- | ------------------------------------ | |
| 88 | +| `ToolName` | Any use of that tool | `Read` — all file reads | |
| 89 | +| `ToolName(argument)` | Tool with specific argument | `Bash(npm test)` — only this command | |
| 90 | +| `ToolName(pattern*)` | Tool with wildcard argument | `Bash(npm *)` — any npm command | |
| 91 | +| `Edit(path)` | Edit with gitignore-style path | `Edit(src/**)` — edits in src/ | |
| 92 | +| `Write(path)` | Write with gitignore-style path | `Write(tests/**)` — writes in tests/ | |
| 93 | + |
| 94 | +### MCP Tool Patterns |
| 95 | + |
| 96 | +```json |
| 97 | +{ |
| 98 | + "permissions": { |
| 99 | + "allow": ["mcp__servername__toolname", "mcp__servername__*"] |
| 100 | + } |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +- `mcp__server__tool` — specific MCP tool |
| 105 | +- `mcp__server__*` — all tools from a server |
| 106 | +- `mcp__*` — all MCP tools (use sparingly) |
| 107 | + |
| 108 | +### Task (Agent) Patterns |
| 109 | + |
| 110 | +Control which agent types can be spawned: |
| 111 | + |
| 112 | +```json |
| 113 | +{ |
| 114 | + "permissions": { |
| 115 | + "allow": ["Task(code-reviewer, test-runner)"] |
| 116 | + } |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +- `Task(type1, type2)` — only listed agent types |
| 121 | +- `Task` — allow any subagent |
| 122 | +- Omitting `Task` — no subagent spawning |
| 123 | + |
| 124 | +### Rule Precedence |
| 125 | + |
| 126 | +When multiple rules match: |
| 127 | + |
| 128 | +1. **deny** rules always take precedence over **allow** rules |
| 129 | +2. More specific rules take precedence over general ones |
| 130 | +3. Explicit rules override `permissionMode` settings |
| 131 | + |
| 132 | +### Plugin Developer Guidance |
| 133 | + |
| 134 | +**Document required permissions:** If your plugin's agents need specific tool access, document the minimum required permissions in your README: |
| 135 | + |
| 136 | +```markdown |
| 137 | +## Required Permissions |
| 138 | +
|
| 139 | +This plugin's agents need: |
| 140 | +
|
| 141 | +- `Edit(src/**)` — to modify source files |
| 142 | +- `Bash(npm test)` — to run tests |
| 143 | +- `mcp__plugin_myserver__*` — for MCP tool access |
| 144 | +``` |
| 145 | +
|
| 146 | +**Configure agent permissions:** Use `permissionMode` in agent frontmatter for broad access control. For fine-grained restrictions, document the settings users should configure. |
| 147 | + |
| 148 | +**Principle of least privilege:** Request only the permissions your agent actually needs. Use `acceptEdits` over `dontAsk` when only file writes are needed. |
0 commit comments