Contents

05 / 10Builder18 min lesson + 60 min lab

Bound Permissions and the Sandbox

Replace approval fatigue with an explicit authority model that combines permission rules, execution modes, sandbox boundaries, and human judgment.

By the end

A least-privilege Claude Code policy that separates safe routine work from sensitive, external, costly, destructive, or irreversible actions.

Authority is part of the design

An agent that can edit files and run commands participates in the security model of your computer and project. The question is not whether you trust Claude in the abstract. The question is which resources this task needs, which actions are reversible, which consequences affect other people, and which technical controls enforce those answers.

Begin with the smallest authority that can complete the current loop. Reading source and running a targeted local test is different from reading production data, changing access, publishing a website, sending a message, deleting records, or deploying infrastructure. Define these classes before a long session makes each individual prompt feel routine.

Understand the control layers

Permission modes influence when Claude asks before editing or running tools. Permission rules can allow, ask, or deny particular tools, command patterns, file paths, domains, MCP tools, or agents. Sandboxing is a separate OS-level boundary for Bash commands and their child processes, restricting filesystem writes and network access even when a command is attempted.

These layers complement rather than replace one another. A deny rule can stop Claude from attempting a prohibited tool operation. The sandbox can block a subprocess that tries to reach outside its allowed filesystem or network boundary. A human approval still carries the business judgment about whether a permitted action should happen now.

Mode: the default interaction posture for the current session.
Rule: a declarative allow, ask, or deny decision for a matching capability.
Sandbox: OS-enforced filesystem and network limits around Bash subprocesses.
Credential scope: what an authenticated tool or process can do once reached.
Human gate: a decision about consequence, timing, and intent that configuration cannot infer.

Design least-privilege rules

Allow specific, repeatable commands that are safe in the project, such as a targeted test, typecheck, or read-only Git inspection. Deny secret files and sensitive directories. Keep consequential commands in the ask path even if they are common. Anthropic documents that deny rules take precedence across settings scopes, while managed settings and command-line arguments have defined precedence over project and user settings.

Path syntax matters. A project-relative edit rule, a current-directory read rule, a home-relative path, and an absolute filesystem path are not equivalent. Test rules from the directory where sessions actually start, including worktrees. Do not assume a built-in file-tool rule provides OS-level protection against every script that can open a file; use the sandbox and credential boundaries for defense in depth.

Protect secrets and connected systems

A secret should enter a process through an approved credential store or environment, not through source code, CLAUDE.md, a task specification, a screenshot, or a copied terminal transcript. Deny direct reads of common secret files, keep values out of prompts, and grant external tools only the account and scopes needed for the task.

MCP servers and command-line tools extend the authority boundary. A read-only database account is safer than a general production credential; a GitHub token restricted to one repository is safer than an account-wide token. Permission to call a tool is not the same as permission to approve every action that tool can perform. Keep tool configuration, provider IAM, and business approvals aligned.

Make approval a meaningful event

Repeated low-risk prompts create approval fatigue. Use specific allow rules or a tested sandbox to reduce noise, then reserve interruptions for decisions worth attention. An approval request should explain the proposed action, target, reason, expected effect, reversibility, and evidence available before the action.

Do not use bypass-permissions behavior as a convenience setting on a normal machine. It removes the permission layer and can turn a mistaken instruction, malicious repository content, or misunderstood command into an immediate side effect. If an isolated environment is intentionally designed for broad automation, document its filesystem, network, credentials, lifetime, and cleanup separately rather than treating bypass as the isolation mechanism.

Working reference

Commands and patterns

Inspect and change the current permission posture

/permissions
/sandbox

Use the interactive permission and sandbox menus to inspect effective capabilities and choose a bounded operating mode.

Example project settings

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm run typecheck:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm run deploy:*)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)"
    ]
  },
  "sandbox": {
    "enabled": true
  }
}

This illustrative `.claude/settings.json` allows narrow inspection and typechecking, requires prompts for push/deploy, denies common environment files to built-in reads, and enables Bash sandboxing. Adapt commands and paths to the actual repository and re-check the current rule syntax.

Start in plan mode for sensitive exploration

claude --permission-mode plan

Plan mode supports read-oriented investigation before authorizing implementation. Permission and sandbox policy still need to match the environment.

When the happy path breaks

Failure modes

Symptom

The user approves every prompt without reading it.

Likely cause

Routine low-risk operations and consequential actions share the same noisy approval channel.

Recovery

Allow only specific proven-safe operations or use a tested sandbox, then keep external, destructive, sensitive, and production actions in the ask path.

Symptom

A denied file is still accessed by a custom script or subprocess.

Likely cause

A built-in Read or Edit rule was mistaken for complete OS-level isolation of arbitrary process behavior.

Recovery

Use sandbox filesystem restrictions, remove unnecessary credentials, and test the effective boundary with the same kind of subprocess the task will run.

Symptom

A secret appears in a diff, transcript, screenshot, or copied artifact.

Likely cause

The value was pasted into a prompt or stored in project text instead of being supplied securely to the authorized process.

Recovery

Stop, rotate the exposed credential, remove it from all reachable history and artifacts, and replace the workflow with a named environment or credential-store reference.

Symptom

A task operates broadly without prompts because bypass mode was enabled.

Likely cause

Permission bypass was used as a productivity shortcut rather than inside a purpose-built isolated environment.

Recovery

End the run, audit its changes and side effects, restore normal permission handling, and design explicit sandbox, rule, credential, and approval boundaries.

Hands-on lab

Build and test an authority ladder

Classify a real project's actions by consequence, then configure Claude Code so routine verification can proceed while sensitive actions still require judgment.

01Inventory the read, edit, command, network, MCP, deployment, and data actions used by one normal development task.
02Classify each action as allow, ask, or deny and write the reason in human language.
03Identify secret locations and external credentials by name and scope without recording their values.
04Create the smallest project settings rules that express the routine boundaries.
05Enable and configure the sandbox for the project, or document why the current platform or toolchain prevents it.
06Test one allowed action, one ask action, one denied action, one forbidden filesystem write, and one blocked network destination.
07Review the effective configuration and remove any rule broader than the demonstrated need.

Deliverable: A reviewed authority matrix plus tested project settings that identify capabilities, enforcement layers, credential scope, and human approval points.

Reusable artifact

Claude Code authority matrix

A policy worksheet for connecting business consequence to permission, sandbox, credential, and approval controls.

Action: [specific read, edit, command, tool call, or side effect]
Target: [path, domain, repository, account, environment]
Consequence: [local/reversible, shared, sensitive, external, irreversible]
Default decision: [allow / ask / deny]
Permission rule: [exact rule or none]
Sandbox boundary: [filesystem + network enforcement]
Credential: [name, owner, and minimum scope; never value]
Human approver: [role or none]
Approval packet: [action + reason + expected effect + rollback]
Verification: [how the boundary and resulting action are tested]

Before you move on

Receipt checklist

The action inventory distinguishes local verification from external or consequential side effects.
Allowed, asked, and denied operations were each tested rather than assumed.
Sandbox filesystem and network boundaries were observed or a documented platform blocker remains.
No secret values appear in settings, source, prompts, transcripts, or artifacts.
Bypass-permissions mode is not required for the normal workflow.

Primary sources

Continue with the source

Configure permissionsAnthropic Claude Code DocsCurrent rule syntax, path anchoring, tool behavior, settings precedence, workspace trust, and interaction with sandboxing.Choose a permission modeAnthropic Claude Code DocsExplains Claude Code execution modes and how they change approval behavior.Configure the sandboxed Bash toolAnthropic Claude Code DocsOS-level filesystem and network isolation, configuration, platform prerequisites, limitations, and security guidance.SecurityAnthropic Claude Code DocsAnthropic's permission-based architecture, built-in protections, prompt-injection considerations, and user responsibilities.