Permissions & Sandbox

The security layer that controls what the AI agent can do — permission modes, rule engine, filesystem sandbox, and network restrictions.

Permission Modes

Five modes control the default behavior when the agent tries to use a tool:

Mode	Identifier	Behavior
Default	default	Prompt user on first use of each tool
Accept Edits	acceptEdits	Auto-approve file edits, ask for shell commands
Plan	plan	Read-only mode — blocks write, exec, and delete tools
Don't Ask	dontAsk	Deny all unless explicitly allowed by rules
Bypass	bypassPermissions	Auto-approve everything (unsafe, for trusted environments)

Rule Engine

The rule engine provides fine-grained control over tool permissions using a 3-tier evaluation system:

Rule Priority (Highest to Lowest)

Deny Rules

Always win. Cannot be overridden by any other rule. Use these to block dangerous operations permanently.

Ask Rules

Override allow rules. Forces the agent to prompt the user for permission even if an allow rule would match.

Allow Rules

Auto-approve when no deny or ask rule matches. Use these for trusted operations.

Rule Syntax

Pattern	Description	Example
Tool	All uses of a tool	Read
Tool(*)	Same as above (explicit wildcard)	Edit(*)
Bash(cmd *)	Shell commands (wildcard with word boundaries)	Bash(npm *)
Read(path)	Read a specific file or directory	Read(src/**)
Edit(path)	Edit a specific file or directory	Edit(src/**.ts)
Delete(path)	Delete a specific file	Delete(tmp/**)
WebFetch(domain:x)	Fetch from a domain (wildcards allowed)	WebFetch(domain:*.github.com)
Agent(name)	Sub-agent names	Agent(researcher)

Settings Hierarchy

Permission rules can be defined at three levels. Higher-priority settings override lower-priority ones:

Local Project Highest Priority

.claude/settings.local.json — Personal overrides for this project (gitignored).

Shared Project

.claude/settings.json — Shared project settings (committed to git, shared with team).

User Global Lowest Priority

~/.claude/settings.json — User-wide defaults that apply to all projects.

Settings File Format

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(src/**)",
      "Bash(npm test)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Delete(*.env)"
    ],
    "ask": [
      "Bash(git push *)",
      "WebFetch(domain:*)"
    ]
  }
}

Filesystem Sandbox

The filesystem sandbox restricts which paths the agent can read from and write to.

Sandbox Modes

Mode	Behavior
regular	No sandbox — all filesystem access allowed
auto-allow	Auto-approve if path passes sandbox checks (no prompt)
strict	Deny by default, must explicitly allow paths

Sandbox Configuration

{
  "sandbox": {
    "enabled": true,
    "mode": "auto-allow",
    "filesystem": {
      "allowWrite": ["~/Downloads", "/tmp"],
      "denyWrite": ["/etc", "/usr"],
      "denyRead": ["~/.ssh", "~/.aws", "~/.env"]
    },
    "network": {
      "allowedDomains": [
        "api.github.com",
        "*.npmjs.org"
      ],
      "allowManagedDomainsOnly": false
    }
  }
}

Network Sandbox

The network sandbox controls which domains the agent can access via the web_fetch tool:

Domain allowlisting — Only specified domains are accessible (wildcards supported)
Session approvals — Domains can be approved for the current session when prompted
Managed domains only — Optional strict mode that blocks all non-allowlisted domains without prompting

Runtime Permission Storage

Permissions granted at runtime are stored in:

Scope	Location	Persistence
Global	~/.cdoing/permissions.json	Persistent across all projects
Project	.cdoing/permissions.json	Persistent for this project
File edits	In-memory	Session only (cleared on restart)
Shell commands	.cdoing/permissions.json	Persistent per-project

Shell Path Checking

When the agent runs a shell command, the permission system:

Extracts file paths from the command string
Checks extracted paths against Read/Edit/Delete rules
Blocks compound commands with operators (&&, ||, |, ;) when using wildcard rules to prevent rule bypassing

Security Note

The permission system is designed as a safety net, not a security boundary. A determined user can always bypass it. It's meant to prevent the AI from accidentally performing destructive operations.