Permission System

The permission system is critical for safety. It controls what the agent can do, when it needs approval, and how to sandbox dangerous operations.

Design Goals

• Safety by default - Require approval for potentially harmful actions
• User control - Let users decide what to allow
• Granular - Control per-tool, per-command, per-path
• Transparent - Show what will happen before execution
• Flexible - Support different modes (interactive, auto-approve safe, etc.)
• Auditable - Log all permission decisions

Permission Models

Risk Classification

Permission Flow

graph TD
    A[Tool Call Requested] --> B{Check Allowlist}
    B -->|Allowed| C[Execute]
    B -->|Not Allowed| D{Check Risk Level}
    D -->|Low| E{Check Mode}
    D -->|Medium/High| F[Ask User]
    E -->|Auto-approve Low| C
    E -->|Interactive| F
    F -->|Approve Once| C
    F -->|Approve Always| G[Add to Allowlist]
    F -->|Deny| H[Reject with Message]
    G --> C

    style C fill:#e8f5e9
    style H fill:#ffcdd2
    style F fill:#fff3e0

Permission Rules

Rules can be defined at multiple levels:

interface PermissionRule {
  type: 'allow' | 'deny' | 'ask';
  tool?: string;      // Specific tool or wildcard
  command?: string;   // For shell, regex pattern
  path?: string;      // For filesystem, glob pattern
  description?: string;
}

Example Rules

permissions:
  rules:
    - type: allow
      tool: read_file
    - type: allow
      tool: grep
    - type: allow
      tool: glob
    - type: ask
      tool: write_file
    - type: ask
      tool: edit
    - type: ask
      tool: bash
    - type: deny
      tool: bash
      command: "rm -rf /"
    - type: ask
      tool: bash
      command: "git push*"

Shell Command Analysis

For bash/shell commands, parse and analyze for safety:

DANGEROUS_PATTERNS = [
    r"rm\s+-rf\s+/",      # Delete everything
    r"curl.*\|\s*sh",     # Pipe curl to shell
    r"wget.*\|\s*sh",     # Pipe wget to shell
    r"sudo",              # Privilege escalation
    r"chmod\s+777",       # Overly permissive
    r"mkfs",              # Format disk
    r"dd\s+if=",          # Disk operations
]

def analyze_command(cmd: str) -> RiskLevel:
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, cmd):
            return RiskLevel.CRITICAL
    # Check for other risky operations
    ...
    return RiskLevel.HIGH

Filesystem Path Restrictions

Prevent escaping the project directory:

def validate_path(path: str, working_dir: str) -> bool:
    resolved = os.path.realpath(os.path.join(working_dir, path))
    wd_resolved = os.path.realpath(working_dir)
    # Must be within working directory
    if not resolved.startswith(wd_resolved + os.sep) and resolved != wd_resolved:
        raise PermissionError("Path outside working directory")
    # Check for sensitive paths
    if is_sensitive_path(resolved):
        raise PermissionError("Access to sensitive path denied")
    return True

User Approval UI

When asking for permission, show clear information:

Permission required

Tool: bash
Command: npm install express
Risk: Medium
Working directory: /home/user/project

This command will:
- Download and install packages from npm registry
- Modify node_modules/ and package-lock.json

[Allow once] [Allow for this session] [Allow always] [Deny]

Session-Based Permissions

Track approvals within a session:

interface SessionPermissions {
  allowedTools: Set<string>;
  allowedCommands: Array<{pattern: RegExp, count: number}>;
  allowedPaths: Set<string>;
  autoApproveLowRisk: boolean;
  planMode: boolean;
}

Sub-Agent Permissions

Sub-agents can have different permission profiles:

Sandboxing Strategies

Audit Logging

Log all permission decisions:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "sessionId": "ses_123",
  "tool": "bash",
  "args": {"command": "git commit -m 'fix'"},
  "riskLevel": "medium",
  "decision": "approved",
  "approvedBy": "user",
  "duration": 150
}

Best Practices

1. Default deny for high-risk - Better to ask than regret
2. Be specific in prompts - Show exactly what will happen
3. Allow session-level approval - Reduce friction for repeated safe actions
4. Support plan mode - Let users review before executing
5. Clear deny messages - Explain why something was blocked
6. Respect .gitignore patterns - Don't modify ignored files carelessly
7. Handle secrets carefully - Never log sensitive values
8. Provide escape hatch - Allow advanced users to configure

Configuration

Users can configure permissions in settings:

{
  "permissions": {
    "mode": "interactive",
    "autoApprove": ["read_file", "glob", "grep"],
    "deny": ["rm -rf /*"],
    "requireApproval": ["bash", "write_file"],
    "workingDirectoryOnly": true
  }
}

Related Notes

• Tool Registry — Tool system integration
• Shell Integration — Shell safety
• Filesystem Integration — Filesystem restrictions
• Security — Broader security
• Minimal Harness — Implementation

Sources

• Claude Code permissions documentation
• OpenCode security model
• Principle of Least Privilege (NIST)
• OWASP Secure Coding Practices
• Container security best practices