Claude Code Permission Modes

Overview

Claude Code permission management provides fine-grained control over tool access, command execution, and system operations through comprehensive permission policies. Enables secure, controlled automation in enterprise environments.

Permission Architecture

Two-Layer Permission System

Layer 1: allowedTools (Whitelist)
  ├─ Read patterns: Read(**/*.{js,ts})
  ├─ Edit patterns: Edit(src/**)
  └─ Bash patterns: Bash(git:*), Bash(npm:*)

Layer 2: deniedTools (Blacklist Override)
  ├─ Secrets files: .env*, .aws/**, .vercel/**
  ├─ Destructive: rm -rf:*, sudo:*
  └─ Dangerous: chmod 777:*

Permission Modes

Whitelist Approach (Recommended)

Define explicitly allowed tool patterns:

json
1{
2  "permissions": {
3    "allowedTools": [
4      "Read(**/*.{js,ts,json,md})",
5      "Edit(**/*.{js,ts})",
6      "Bash(git:*)",
7      "Bash(npm:*)",
8      "Bash(uv:*)",
9      "Bash(pytest:*)",
10      "Bash(mypy:*)"
11    ]
12  }
13}

Benefits:

• Secure by default (deny unless explicitly allowed)
• Clear audit trail
• Easy to review
• Enterprise-ready

Blacklist Approach (Not Recommended)

Explicitly block dangerous operations:

json
1{
2  "permissions": {
3    "deniedTools": [
4      "Edit(/config/secrets.json)",
5      "Edit(.env*)",
6      "Edit(.aws/**)",
7      "Bash(rm -rf:*)",
8      "Bash(sudo:*)",
9      "Bash(chmod 777:*)"
10    ]
11  }
12}

Issues:

• Requires knowing all dangerous patterns
• New vulnerabilities not covered
• Hard to maintain
• Not enterprise-recommended

Tool Pattern Syntax

Read Operations

Read(glob_pattern)

Examples:
- Read(**/*.{js,ts})          # All JS/TS files recursively
- Read(.claude/**)            # All Claude files
- Read(docs/api/**/*.md)      # API documentation
- Read(config/production.json) # Specific file

Edit Operations

Edit(glob_pattern)

Examples:
- Edit(src/**/*.py)           # Source code only
- Edit(src/services/*.ts)     # Specific directory

Never Edit:

• .env* files
• .aws/ credentials
• .vercel/ project config
• secrets.json, credentials.json

Bash Commands

Bash(command:*)

Examples:
- Bash(git:*)                 # All git operations
- Bash(npm:*)                 # NPM package management
- Bash(uv:*)                  # UV (Python) operations
- Bash(pytest:*)              # Testing
- Bash(mypy:*)                # Type checking
- Bash(ruff:*)                # Python linting

Dangerous (Block):
- Bash(rm -rf:*)              # Recursive delete
- Bash(sudo:*)                # Superuser access
- Bash(chmod 777:*)           # Permission changes
- Bash(find.*-delete:*)       # File deletion

Security Patterns

Production-Grade Configuration

json
1{
2  "permissions": {
3    "allowedTools": [
4      "Read(**)",
5      "Edit(src/**)",
6      "Edit(tests/**)",
7      "Bash(git:*)",
8      "Bash(uv:*)",
9      "Bash(pytest:*)",
10      "Bash(mypy:*)",
11      "Bash(ruff:*)"
12    ],
13    "deniedTools": [
14      "Edit(.*)",
15      "Edit(.env*)",
16      "Edit(.aws/**)",
17      "Edit(.vercel/**)",
18      "Bash(rm:*)",
19      "Bash(sudo:*)",
20      "Bash(chmod:*)"
21    ]
22  },
23  "sandbox": {
24    "allowUnsandboxedCommands": false
25  }
26}

Sensitive Data Protection

Critical patterns to block:

json
1{
2  "deniedTools": [
3    "Edit(.env*)",
4    "Edit(.env.local)",
5    "Edit(.env.production)",
6    "Edit(.aws/**)",
7    "Edit(.aws/credentials)",
8    "Edit(.aws/config)",
9    "Edit(.vercel/**)",
10    "Edit(config/**/secrets.json)",
11    "Edit(**/*credentials*.json)",
12    "Edit(**/*password*.json)",
13    "Edit(**/*token*.json)"
14  ]
15}

Permission Validation

Always validate permission configurations:

bash
1# Check current settings
2cat .claude/settings.json | jq '.permissions'
3
4# Verify allowedTools patterns
5cat .claude/settings.json | jq '.permissions.allowedTools[]'
6
7# Verify deniedTools patterns
8cat .claude/settings.json | jq '.permissions.deniedTools[]'
9
10# Test specific operation
11# Try Read(test_file.md) → allowed?
12# Try Edit(.env) → denied?
13# Try Bash(git status) → allowed?

Best Practices

Security-First Approach

• ✅ Use whitelist (allowedTools) instead of blacklist
• ✅ Protect secrets files (.env*, .aws/, .vercel/)
• ✅ Block destructive commands (rm -rf, sudo, chmod)
• ✅ Enable sandbox mode
• ✅ Regularly review permissions
• ✅ Audit permission violations
• ✅ Document permission decisions

Team Collaboration

• ✅ Document permission changes in commit
• ✅ Explain security rationale
• ✅ Test with different roles
• ✅ Keep audit log of changes

Common Patterns by Use Case

Development Environment

json
1{
2  "allowedTools": [
3    "Read(**)",
4    "Edit(src/**)",
5    "Edit(tests/**)",
6    "Edit(.claude/**)",
7    "Bash(git:*)",
8    "Bash(uv:*)",
9    "Bash(pytest:*)",
10    "Bash(mypy:*)",
11    "Bash(ruff:*)"
12  ],
13  "deniedTools": [
14    "Edit(.env*)",
15    "Edit(.aws/**)",
16    "Bash(rm -rf:*)",
17    "Bash(sudo:*)"
18  ]
19}

CI/CD Pipeline

json
1{
2  "allowedTools": [
3    "Read(src/**)",
4    "Read(tests/**)",
5    "Read(.github/workflows/**)",
6    "Bash(git:*)",
7    "Bash(uv:*)",
8    "Bash(pytest:*)",
9    "Bash(mypy:*)"
10  ],
11  "deniedTools": [
12    "Edit(**)",
13    "Bash(sudo:*)",
14    "Bash(rm:*)"
15  ]
16}

Read-Only Analysis

json
1{
2  "allowedTools": [
3    "Read(**)",
4    "Bash(git:log)",
5    "Bash(git:show)"
6  ],
7  "deniedTools": [
8    "Edit(**)",
9    "Bash(git:push)",
10    "Bash(git:pull)"
11  ]
12}

TRUST 5 Compliance

• Test-First: Permission patterns tested with actual Claude Code usage scenarios
• Readable: Clear permission naming and organization, documented rationale
• Unified: Consistent permission approach across all environments
• Secured: Whitelist-based, blocking all dangerous operations
• Trackable: Audit trail of permission modifications and changes

Related Skills

• moai-cc-hooks - Hook execution for pre/post-tool validation
• moai-core-env-security - Environment variable security
• moai-cc-sandbox-isolation - Sandbox mode configuration

Last Updated: 2025-11-19 Version: 4.0.0 Enterprise Production Ready: Yes ✅ Maturity: Stable