AX-Copilot/docs/claude-code-docs-main/en/concepts/permissions.md

Documentation Index

Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt Use this file to discover all available pages before exploring further.

Permissions

How Claude Code controls which operations Claude can perform automatically versus which require your explicit approval.

Claude Code runs tools on your local machine — executing shell commands, editing files, fetching URLs. The permission system gives you precise control over which operations Claude performs automatically and which require your explicit approval.

What permissions control

Permissions apply to three categories of operations:

Reading, editing, and writing files on your local filesystem via the `Read`, `Edit`, and `Write` tools. Any shell command executed through the `Bash` tool, including installs, builds, git operations, and arbitrary scripts. Tools exposed by connected MCP servers, which may include database queries, API calls, or browser automation.

Permission modes

The permission mode determines the default behaviour when no specific allow/deny rule matches a tool call. Set the mode once and it applies for the entire session.

The standard mode. Claude Code evaluates each tool call and prompts you for confirmation on operations that could have side effects: running shell commands, editing files, making network requests. Read-only operations (file reads, searches) are auto-approved.

This is the recommended mode for everyday use.

File edit and write operations (`Edit`, `Write`) are automatically approved without prompting. Bash commands still require confirmation.

Useful when you trust Claude to make file changes freely but still want to review shell commands.

Claude can read files, search the codebase, and discuss changes, but cannot execute any write or bash operations. All mutating tool calls are blocked.

Use this mode when you want Claude to analyse a problem and produce a plan before you authorise any changes. The model can exit plan mode and request permission to proceed via the `ExitPlanMode` tool.

All permission checks are disabled. Every tool call is executed immediately without any confirmation prompts.

<Warning>
  This mode is intended for automated, fully-scripted workflows where you have audited what Claude will do in advance. Never use `bypassPermissions` in an interactive session where Claude might take unexpected actions.
</Warning>

Similar to `bypassPermissions` but uses a slightly different internal path. Tool calls that would normally prompt are auto-approved. Intended for scripted/non-interactive scenarios. An experimental mode that uses a secondary AI classifier to evaluate each proposed tool call against the conversation transcript. The classifier decides whether the operation is within the scope of what was requested, and either auto-approves or escalates to a human prompt.

This mode is only available when the `TRANSCRIPT_CLASSIFIER` feature flag is enabled.

Setting the permission mode

Pass `--permission-mode` when starting Claude Code:

```bash  theme={null}
claude --permission-mode acceptEdits
claude --permission-mode bypassPermissions
claude --permission-mode plan
```

Change the mode mid-session without restarting:

```
/permissions
```

An interactive menu lets you select the new mode. The change takes effect for the remainder of the session.

Set a persistent default in your user or project settings:

```json  theme={null}
{
  "defaultMode": "acceptEdits"
}
```

Valid values: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`, `"dontAsk"`.

Permission rules (allow/deny lists)

Beyond the global mode, you can create fine-grained rules that always allow or always deny specific tool calls — regardless of the active mode.

Rules have three components:

Field	Description
toolName	The name of the tool the rule applies to (e.g., "Bash", "Edit", "mcp__myserver")
ruleContent	An optional pattern that must match the tool's input (e.g., a command prefix for Bash)
behavior	"allow", "deny", or "ask"

Rules are evaluated before the permission mode. If a matching rule exists, its behavior is applied immediately.

Rule sources and persistence

Rules can originate from different sources and are stored accordingly:

Source	Where stored	Scope
userSettings	~/.claude/settings.json	All projects for the current user
projectSettings	.claude/settings.json	All users of this project
localSettings	.claude/settings.local.json	Current user, this project only
session	In-memory	Current session only
cliArg	CLI flags	Current invocation only

Example: always allow specific git commands

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

How bash permissions work

Bash command permission checking deserves special attention because shell commands can be complex and ambiguous.

Pattern matching

A Bash permission rule with a ruleContent string is matched against the command using wildcard pattern matching:

• git status — exact match only
• git * — matches any git subcommand
• npm run * — matches any npm run script
• * — matches any bash command (use with extreme caution)

Compound commands

When a bash command contains multiple sub-commands joined by &&, ||, ;, or pipes (|), each sub-command is checked independently. The overall permission is the most restrictive result: if any sub-command is denied, the entire compound command is blocked.

Operator restrictions

Certain shell constructs are flagged for extra scrutiny regardless of rules:

• Output redirections (>, >>) to paths outside the project directory
• Commands that change the current directory (cd) to outside the working tree
• sed -i edit-in-place commands (handled specially to track file modifications)

Safety checks

Regardless of the active permission mode, certain operations are always blocked or escalated:

• Commands targeting .claude/ or .git/ configuration directories
• Modifications to shell config files (.bashrc, .zshrc, etc.)
• Attempts to bypass path restrictions using cross-platform path tricks

In `auto` mode (feature-gated), safety checks marked `classifierApprovable: true` are sent to the transcript classifier rather than forcing a prompt. The classifier has visibility into the full conversation context and can decide whether the operation is appropriate.

MCP tool permissions

MCP tools follow the same rule system as built-in tools. You can allow or deny an entire MCP server or individual tools within a server:

{
  "permissions": {
    "deny": [
      "mcp__myserver"
    ],
    "allow": [
      "mcp__myserver__read_database"
    ]
  }
}

Using mcp__servername as the rule (without a specific tool name) blanket-denies all tools from that server — they are filtered out of the tool list before the model even sees them.

Safety recommendations

`bypassPermissions` and `dontAsk` modes remove all safeguards. Only use them in isolated environments (containers, CI sandboxes) where Claude's actions are constrained by the environment itself, not by permission prompts.

• Start with default mode for any interactive session.
• Use plan mode when exploring an unfamiliar codebase or designing a large change — review the plan before enabling writes.
• Use acceptEdits for coding sessions where you trust Claude to edit files freely but want to review shell commands.
• Prefer granular allow rules over broad mode escalation. Allowing Bash(git *) is safer than switching to bypassPermissions.
• Scope deny rules tightly. A blanket Bash(*) deny prevents Claude from running any shell command, including safe read-only operations.
• Review project settings files (.claude/settings.json) when cloning unfamiliar repositories — they may pre-configure permission rules.

Built with Mintlify.