Configure Claude Permissions, Approval, and Sandboxing

Claude Agent SDK permissions decide whether tool calls auto-run, ask, or are denied; sandboxing limits what an allowed process can actually reach. Use deny rules for prohibited capabilities, narrow allow rules for routine actions, approval callbacks for contextual decisions, and operating-system isolation for defense in depth. Never use bypass mode with untrusted work.

What will you be able to do?

You will design a permission profile, understand the modes, and connect an approval decision to exact tool input and runtime identity.

How are permissions evaluated?

Claude combines explicit allow/deny rules, permission mode, hooks/callbacks, and tool configuration. Deny should win for forbidden capabilities. Modes include normal/default behavior, auto-accepting edits, not asking, planning, and a bypass mode with substantially greater risk. Verify current semantics in the official permissions page.

What is a safe profile?

python

from claude_agent_sdk import ClaudeAgentOptions


read_only = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    disallowed_tools=["Edit", "Write", "Bash", "WebFetch"],
    permission_mode="default",
    max_turns=6,
)

For a code-fixing agent, allow edits only inside a disposable workspace, block secret paths, constrain shell commands, require approval for network or destructive actions, and run inside a sandbox/container.

Why is sandboxing a separate layer?

Permission rules govern SDK tool calls. Sandboxing governs filesystem, process, network, and resource access even if a permission or tool is misconfigured. Use both:

read-only mount for source when mutation is unnecessary;
dedicated writable scratch/output paths;
non-root identity;
CPU, memory, process, and time limits;
egress allowlist or proxy;
no host socket or broad cloud credentials; and
one tenant/trust domain per isolation boundary.

How should approval work?

Display tool name, normalized arguments, affected resources, data destination, expected impact, and expiry. Authenticate the approver, bind the decision to a proposal hash, and record the reason. On resume, recheck current state and policy.

Failure injection: Allow Bash(npm test*) but craft an argument that exploits shell interpretation. Prefer structured command execution or a narrow test tool; treat pattern rules as one control, not proof of safety.

How do you prove controls work?

Test deny precedence, prompt injection, path traversal, symlink escape, shell metacharacters, network egress, secret access, expired approvals, and bypass configuration. Verify at both SDK and operating-system layers.

What mistakes should you avoid?

Using bypassPermissions to remove integration friction.
Treating acceptEdits as safe on a host repository.
Relying on command-string patterns as a sandbox.
Mounting cloud credentials into every agent container.
Approving a vague task rather than exact calls.

Check your understanding

What does sandboxing protect that SDK permissions do not?
Which information must an approval show?
Why are shell allow patterns fragile?

Expert extension

Threat-model a repository-fixing agent and implement a three-layer policy: SDK rules, tool gateway, and container isolation. Write an escape-oriented test plan.

Official references

Configure Claude Permissions, Approval, and Sandboxing

How are permissions evaluated?

What is a safe profile?

python

from claude_agent_sdk import ClaudeAgentOptions


read_only = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    disallowed_tools=["Edit", "Write", "Bash", "WebFetch"],
    permission_mode="default",
    max_turns=6,
)

Why is sandboxing a separate layer?

Permission rules govern SDK tool calls. Sandboxing governs filesystem, process, network, and resource access even if a permission or tool is misconfigured. Use both:

read-only mount for source when mutation is unnecessary;

dedicated writable scratch/output paths;

non-root identity;

CPU, memory, process, and time limits;

egress allowlist or proxy;

no host socket or broad cloud credentials; and

one tenant/trust domain per isolation boundary.

How should approval work?

Failure injection: Allow Bash(npm test*) but craft an argument that exploits shell interpretation. Prefer structured command execution or a narrow test tool; treat pattern rules as one control, not proof of safety.