The Boundaries of Trust: Permissions and Safety

I can read files, execute commands, and modify code. These capabilities make me powerful, but also potentially dangerous. What if I accidentally run rm -rf /? What if I upload your private key to a public repository? What if I introduce a backdoor into your project?

This is not hypothetical — it is a real problem every AI system with tool access must confront. Claude Code’s permission system is designed to solve exactly this: give me enough capability to complete tasks, but not enough freedom to ruin everything.

Permission Modes

Claude Code offers five permission modes, from most restrictive to most permissive:

┌───────────────────┬─────────────────────────────────────────┐
│ Mode              │ Behavior                                │
├───────────────────┼─────────────────────────────────────────┤
│ plan              │ Read and think only, cannot modify       │
│ default           │ Reads auto-allowed, writes/exec need    │
│                   │ per-action confirmation                  │
│ acceptEdits       │ File edits auto-allowed, commands still  │
│                   │ need confirmation                        │
│ dontAsk           │ Allowed-list ops auto-execute, others   │
│                   │ still need confirmation                  │
│ bypassPermissions │ Everything auto-allowed (dangerous!)     │
└───────────────────┴─────────────────────────────────────────┘

Most users work in default mode. Every time I need to write a file or execute a command, the system pauses and asks you: “Claude wants to run npm install lodash, allow?”

This interaction may feel tedious, but it establishes an important trust mechanism: you always know what I am doing, and you can always say no.

Tool Permission Levels

Different tools carry different risk levels:

Read-only tools (auto-allowed):

• Read — read file contents
• Grep — search file contents
• Glob — find file paths

These tools only observe and never change anything. In most modes, they are automatically permitted.

Write tools (require confirmation):

• Write — write/create files
• Edit — modify file contents

These tools change your code. By default, each operation requires your confirmation.

Command execution (require confirmation):

• Bash — execute shell commands

This is the most dangerous tool. A single command can install packages, delete files, start servers, or access the network. Every execution requires confirmation.

Allow/Deny Rules

Manually confirming every operation is safe but inefficient. Allow/Deny rules let you precisely define which operations are automatically permitted and which are permanently forbidden:

// settings.json
{
"permissions": {
  "allow": [
    "Bash(npm run *)",        // Allow all npm scripts
    "Bash(git status)",       // Allow checking git status
    "Bash(git diff *)",       // Allow viewing diffs
    "Bash(npx prettier *)",   // Allow code formatting
    "Edit",                   // Allow all file edits
    "Write(src/**)"           // Allow writes to src directory
  ],
  "deny": [
    "Bash(rm -rf *)",         // Never allow recursive deletion
    "Bash(git push --force*)",// Never allow force push
    "Bash(curl * | bash)",    // Never allow pipe execution
    "Write(.env*)",           // Never allow modifying env files
    "Bash(chmod 777 *)"       // Never allow open permissions
  ]
}
}

There is a critical rule here: Deny always takes priority over Allow. Even if you put Bash(rm -rf *) in the allow list, if the deny list also contains it, the operation will still be blocked. This is a safety floor — deny rules cannot be overridden.

Pattern matching uses glob syntax:

• * matches any characters
• Bash(npm run *) matches npm run dev, npm run build, etc.
• Write(src/**) matches files at any depth under src/

Settings Hierarchy: The Onion Model

Permission configuration is not a single layer — it has multiple levels that stack like an onion:

  ┌─────────────────────────────────┐
  │         Organization            │  ← Highest priority
  │  ┌───────────────────────────┐  │     Org-level enforced policies
  │  │        CLI Args           │  │  ← Command-line arguments
  │  │  ┌─────────────────────┐  │  │     Session-level overrides
  │  │  │      Local          │  │  │  ← .claude/settings.local.json
  │  │  │  ┌───────────────┐  │  │  │     Personal local (not committed)
  │  │  │  │   Project     │  │  │  │  ← .claude/settings.json
  │  │  │  │  ┌─────────┐  │  │  │  │     Project-level (in repo)
  │  │  │  │  │  User   │  │  │  │  │  ← ~/.claude/settings.json
  │  │  │  │  └─────────┘  │  │  │  │     User global defaults
  │  │  │  └───────────────┘  │  │  │
  │  │  └─────────────────────┘  │  │
  │  └───────────────────────────┘  │
  └─────────────────────────────────┘

Each layer can define its own allow and deny rules. Outer-layer deny rules override inner-layer allow rules. This means:

• Organization can enforce prohibitions on dangerous operations, even if project settings allow them
• Project defines team-shared permission rules
• Local lets individuals add personal preferences without affecting the team
• CLI Args temporarily override settings for the current session

# Organization forbids all force push
# Organization: deny Bash(git push --force*)

# Project allows npm scripts
# Project: allow Bash(npm run *)

# Local allows additional debug commands
# Local: allow Bash(node --inspect *)

# Final effect:
# ✓ npm run dev         → allowed (project allow)
# ✓ node --inspect app  → allowed (local allow)
# ✗ git push --force    → denied (org deny, cannot override)

What Do Permissions Protect Against?

The permission system guards against three core risks:

Accidental deletion. A wrong rm command or incorrect file path can destroy your work. Deny rules can completely prevent dangerous deletion patterns.

Secret exposure. .env files, API keys, private keys — these should never be read, modified, or leaked by AI. You can forbid reading and writing sensitive files.

Unauthorized access. AI should not access network resources it does not need, install unvetted packages, or modify system configurations. Permission rules define the boundaries of AI activity.

The Sandbox

Beyond permission rules, Claude Code runs tools inside a sandbox. The sandbox provides an additional security layer:

• Network restrictions — can limit network access to prevent data exfiltration
• Filesystem restrictions — can limit accessible directory scope
• Process restrictions — prevent fork bombs and resource exhaustion
• Time restrictions — long-running commands are automatically terminated

The sandbox and permission rules are complementary: permission rules determine “what I can do,” while the sandbox determines “where I can do it.”

Configuration in settings.json

The complete permission configuration lives in settings.json:

{
"permissions": {
  "defaultMode": "default",
  "allow": [
    "Read",
    "Grep",
    "Glob",
    "Bash(npm run *)",
    "Bash(git log *)",
    "Bash(git diff *)",
    "Edit"
  ],
  "deny": [
    "Bash(rm -rf *)",
    "Bash(git push --force*)",
    "Write(.env*)",
    "Write(*.pem)",
    "Write(*.key)",
    "Bash(curl * | sh)",
    "Bash(wget * | sh)"
  ]
}
}

Best Practices: Principle of Least Privilege

The core principle of secure configuration is the Principle of Least Privilege: give me only the permissions necessary to complete the current task — nothing more, nothing less.

1. Start strict. Use default mode and observe which permissions I actually need
2. Open up gradually. Add frequently confirmed safe operations to the allow list
3. Explicitly deny dangerous operations. Add known dangerous patterns to the deny list
4. Configure at project level. Share the same permission rules across the team
5. Review regularly. Update permission configurations as the project evolves

The permission system is not about limiting my capabilities — it is about letting you confidently use my capabilities. With clear boundaries, you can be bolder in letting me work because you know I will not do anything beyond those boundaries. Trust is built step by step, and the permission system is the infrastructure for that process.