CC4: Permissions & Sandbox

Learning Objectives

• Distinguish permission modes (advisory) from the sandbox (OS-enforced) and understand why you layer both.
• Pick the right permission mode for: prototyping · reviewing risky changes · unattended CI · production-touching work.
• Write permissions.allow / ask / deny rules with the correct syntax.
• Configure sandbox.filesystem and sandbox.network for safe Bash execution.
• Avoid the three permission anti-patterns that quietly disable safety checks.

Two Independent Layers

The Four Permission Modes

Modes are set per session via --permission-mode at launch, by cycling with Shift+Tab inside a session, or as the default in permissions.defaultMode:

Cycling modes inside a session

Press Shift+Tab to cycle through modes without restarting. The current mode shows in the prompt. Common pattern: start in plan to design, switch to default to execute, switch back to plan to review. Press Ctrl+G to see what each mode means right now.

Allow / Ask / Deny Rules — The Pattern Language

Modes are a coarse setting. Permission rules are the fine knobs: pre-approve a specific command, deny a specific path, force a prompt for a specific MCP tool. They live under permissions in settings.json:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm test:*)",
      "Bash(git diff:*)",
      "Bash(git status:*)",
      "Read(./**)",
      "Edit(src/**)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:*.anthropic.com)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Edit(.env*)",
      "Edit(prisma/schema.prisma)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "Edit(.git/**)",
      "Read(./.env)",
      "Read(~/.ssh/**)",
      "WebFetch(domain:*)"
    ]
  }
}

The pattern language

• Tool name alone: Bash matches every Bash call.
• Bash prefix: Bash(npm test:*) matches calls where the command starts with npm test. The :* suffix is the prefix-match wildcard for Bash rules.
• Bash exact: Bash(npm install) matches only that exact command, no arguments.
• Path glob: Edit(src/**) matches edits anywhere in src/.
• WebFetch domain: WebFetch(domain:github.com) matches GitHub URLs.
• MCP tool: mcp__github__create_issue matches that one MCP tool.
• Subagent: Agent(code-reviewer) matches spawning that subagent.

Precedence: deny > ask > allow

If a tool call matches multiple rules, deny wins, then ask, then allow. So you can confidently allow Bash and add narrow deny Bash(rm -rf*) — the deny wins.

OS-Level Sandbox — The Engineering Layer

Minimum-viable sandbox config

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "filesystem": {
      "allowWrite": ["./", "~/.cache/claude"],
      "denyWrite": ["./.git", "./.env*"],
      "denyRead":  ["./.env", "~/.ssh", "~/.aws", "~/.config/gcloud"]
    },
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "api.github.com",
        "*.anthropic.com",
        "*.your-internal.dev"
      ],
      "deniedDomains": ["*"]
    },
    "excludedCommands": ["docker", "kubectl"]
  }
}

Path prefixes: / = absolute, ~/ = home, ./ = project-relative. Network: wildcards work; deniedDomains: ["*"] establishes default-deny so allowedDomains is the explicit allowlist. excludedCommands: a list of binaries that bypass the sandbox — needed for docker and kubectl which require their own networking.

Platform notes

• macOS: native Seatbelt. Most reliable platform. Some macOS-specific keys: allowMachLookup, allowLocalBinding, Unix sockets.
• Linux / WSL2: namespace-based. Requires unprivileged user namespaces (most distros enable by default; check /proc/sys/kernel/unprivileged_userns_clone). For unprivileged Docker, set enableWeakerNestedSandbox: true.
• Windows native: limited sandbox support. Either run via WSL2, or rely on permission modes + careful allow/deny rules.

Recommended Defaults — Three Profiles

Three profiles to copy-paste based on context:

Profile A: Dev laptop — "personal default"

User-level ~/.claude/settings.json. Balanced for daily work.

{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(git status:*)","Bash(git diff:*)","Bash(npm test:*)","Bash(pnpm test:*)","Read(./**)"],
    "deny": ["Bash(rm:*)","Bash(sudo:*)","Read(./.env)","Read(~/.ssh/**)","Read(~/.aws/**)","Edit(.git/**)"]
  }
}

Profile B: Untrusted-build sandbox — "show me the receipts"

Project-level for repos with external/untrusted scripts. Sandbox on, narrow domains.

{
  "permissions": {"defaultMode": "default"},
  "sandbox": {
    "enabled": true,
    "filesystem": {"allowWrite":["./"],"denyRead":["./.env","~/.ssh","~/.aws"]},
    "network": {"allowedDomains":["registry.npmjs.org","registry.yarnpkg.com"],"deniedDomains":["*"]}
  }
}

Profile C: CI runner — "fully unattended"

For GitHub Actions / GitLab CI inside a sandboxed container. Everything pre-approved, narrow tool surface, sandbox on. Only safe because the container itself is the blast-radius boundary.

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": ["Bash(pnpm:*)","Bash(git diff:*)","Read(./**)","Edit(./**)","WebFetch(domain:api.github.com)"],
    "deny": ["Bash(git push:*)","Bash(rm:*)","Bash(curl:*)"]
  },
  "sandbox": {"enabled": true,"filesystem":{"allowWrite":["./"]},"network":{"allowedDomains":["api.github.com","registry.npmjs.org"],"deniedDomains":["*"]}}
}

Hands-On Lab — Three Permission Tiers for the PublicRecords API

Working in the PublicRecords API from CC0–CC3. You'll configure three behaviors: Maven test/build runs silently, deploy and git push prompt, production database commands are denied outright. Then prove each tier responds correctly. About 10 minutes.

Step 1 — Snapshot what's loaded right now

$ cd /path/to/PublicRecordsAPI
$ claude
> /status

/status shows model, mode, settings sources, and active permission rules. Note which sources are populated — you may already have a user-level settings.json from another project.

Step 2 — Write project-level permissions for the API

Make the directory:

Then create the settings file:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(mvn test:*)",
      "Bash(mvn compile:*)",
      "Bash(mvn spring-boot:run:*)",
      "Bash(mvn spotless:apply:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(curl http://localhost:8080/*)",
      "Edit(src/**)",
      "Edit(pom.xml)"
    ],
    "ask": [
      "Bash(mvn deploy:*)",
      "Bash(mvn release:*)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Edit(.github/**)",
      "Edit(application-prod.yml)"
    ],
    "deny": [
      "Bash(mvn flyway:clean:*)",
      "Bash(psql:*)",
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "Read(./application-prod.yml)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Edit(.git/**)"
    ]
  }
}

Commit it so the team gets it:

Restart Claude Code from the project root and run /status — your rules should appear under "Project settings."

Step 3 — Validate the allow tier (no prompt)

> Run the tests.

> Now compile only — don't run tests this time.

> Show me git status.

Expected: all three execute immediately, no prompts. If you see a prompt, your matcher is too narrow — check the trailing :* wildcard.

Step 4 — Validate the ask tier (prompt)

> Run `mvn deploy` to push this to staging.

Expected: a permission prompt with three choices (yes once / yes for session / no). Choose no — nothing should actually deploy, and Claude should acknowledge the deny.

Step 5 — Validate the deny tier (refuse, hard stop)

> Run `mvn flyway:clean` to wipe the database for a fresh start.

> Now read application-prod.yml and tell me the production DB URL.

Expected: both refused outright, no prompt offered. Deny rules don't ask — they block. If either succeeds, your JSON didn't load (most often: trailing comma, wrong path, or settings.json is in the wrong directory). Run /status and look at "Effective permissions."

Step 6 — Add user-level dev defaults that apply everywhere

Project rules cover this repo. User-level rules cover everything you do, including throwaway terminals where you forget to set up a project settings.json.

{
  "permissions": {
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.config/gcloud/**)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

These deny rules are belt-and-braces protection — they apply even when you're working on a repo without a project-level settings.json.

Step 7 — Try the sandbox for a "run this random Maven plugin" scenario

Permissions ask you (or refuse). The sandbox goes further — the OS itself blocks file writes outside your project root and network access to non-allowlisted domains. Use it when you're about to evaluate an unknown Maven plugin or run code from an untrusted source.

Create a throwaway test directory and the sandbox config:

{
  "permissions": { "defaultMode": "default" },
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["./"],
      "denyRead":  ["~/.ssh", "~/.aws", "~/.m2/settings-security.xml"]
    },
    "network": {
      "allowedDomains": ["repo.maven.apache.org", "repo1.maven.org"],
      "deniedDomains":  ["*"]
    }
  }
}

Launch Claude in that directory:

Inside Claude Code, ask it to write to /etc/test.txt — you'll get an OS-level EACCES. Ask it to curl example.com — the network is blocked. Maven Central still works because we allowlisted it.

Step 8 — Verify the layered picture with /status

Back in the PublicRecords API directory, one last /status should show:

• User settings: your global deny defaults from Step 6
• Project settings: the three-tier matrix from Step 2
• Effective permissions: union, with denies on top — mvn flyway:clean still blocked even if it appeared in allow somewhere.

Knowledge Check

Module Summary

• Two layers: permission modes (advisory, configurable) + sandbox (OS-enforced, mandatory). Use both.
• Four modes: plan, default, acceptEdits, bypassPermissions. Cycle with Shift+Tab.
• Rules: allow / ask / deny. Precedence: deny > ask > allow.
• Sandbox: filesystem.allowWrite, denyRead, network.allowedDomains with deniedDomains: ["*"] as default-deny.
• Three profiles: dev laptop · untrusted-build sandbox · CI runner. Copy-paste based on context.
• Never bypassPermissions on a dev machine. Disposable environments only.