Permissions System

Permission Modes

Cycle through modes with Shift+Tab in a session, or set defaultMode in settings.

Mode	Behavior
default	Ask before edits and shell commands
acceptEdits	Auto-accept file edits, ask for shell
plan	Read-only — no edits or shell commands
auto	Auto-approve safe actions
dontAsk	Require pre-approval, no runtime prompts
bypassPermissions	Skip all prompts — use only in containers!

Rule Syntax

Bash Patterns

{
  "permissions": {
    "allow": [
      "Bash",                  // allow all bash
      "Bash(npm run *)",       // npm run <anything>
      "Bash(npm test)",        // exact command
      "Bash(git *)",           // all git subcommands
      "Bash(* --version)"      // any command with --version
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | bash)"
    ]
  }
}

File Path Patterns

{
  "permissions": {
    "allow": [
      "Read",                  // read all files
      "Edit",                  // edit all files
      "Edit(/src/**)",         // edit only under src/
      "Write(/tmp/**)"         // write only in /tmp
    ],
    "deny": [
      "Edit(/secrets/**)",
      "Edit(/.env)",
      "Read(~/.ssh/**)",
      "Edit(//etc/**)"         // absolute path: double slash
    ]
  }
}

WebFetch Domain Rules

{
  "permissions": {
    "allow": [
      "WebFetch(domain:github.com)",
      "WebFetch(domain:*.anthropic.com)"
    ],
    "deny": [
      "WebFetch(domain:internal.corp)"
    ]
  }
}

MCP Tool Rules

{
  "permissions": {
    "allow": [
      "mcp__github__*",        // all GitHub MCP tools
      "mcp__slack__send_message"
    ],
    "deny": [
      "mcp__*"                 // block all MCP tools
    ]
  }
}

Agent Rules

{
  "permissions": {
    "deny": [
      "Agent(Explore)"         // disable a specific subagent
    ]
  }
}

Manage at Runtime

/permissions               # view current rules
Shift+Tab                  # cycle through modes

Pattern Matching Rules

• * matches any single path segment or command token
• ** matches any number of path segments
• For absolute paths use // prefix: Edit(//etc/**)
• For home dir use ~: Read(~/.ssh/**)
• Deny rules take precedence over allow rules at the same scope

🧠 Quick Recall

• Trick: “deny > ask > allow — deny always wins.”
• Rule shape: Tool(filter) — e.g. Bash(npm test:*).

👨‍🏫 Teach It

• Show: add one allow rule, re-run the command, watch the prompt vanish.
• They’ll trip on: Bash(npm *) not covering chained commands — each part of a && b needs allowing.

---

Learning path: ⬅ 13-model-config-env-vars.md · Index · ➡ 15-permissions-real-examples.md