AnthropicClaude Certified Architect – Professional2026-107.1 Configure Claude tools and environments for teams (e.g., Claude Code)
Set team permission modes and sandbox limits
Completed by the knowledge check
Learning objective
Configure permission modes, allowed and denied tools, secrets handling, and sandboxing for safe autonomy.
Core idea
Tool availability, pre-approval, and denial answer different questions; a skill’s allowed-tools is a grant rather than an exclusive tool list. An architect builds on that distinction by deciding which work can proceed unattended, which effects require a person, and which credentials the development environment should never possess.
Choose autonomy from the workflow’s effects and recovery cost. A local refactor, a database query, and a release to production can all use Bash, yet they deserve different privileges. Removing prompts does not reduce those privileges. Give developers a useful default, preserve explicit approval paths for consequential actions, and test the chosen execution boundary instead of treating a mode name as a security assessment.
How it works
Select a mode for the work and the approval path
Set the starting mode with permissions.defaultMode; --permission-mode selects a mode for a session. The choices carry different operational consequences:
| Mode value | Team decision it supports | Cost or limitation |
|---|---|---|
default | Keep a developer in the approval path | Permission prompts interrupt work; the interface labels it Manual. |
acceptEdits | Let repository edits and supported filesystem operations proceed | This also auto-approves filesystem commands such as mkdir, mv, cp, rm, rmdir, and sed for paths inside the working directory or additionalDirectories; critical-path removals and protected-path writes still prompt. |
plan | Explore and plan before changing source | It permits reads and read-only shell commands; where auto mode is available, classifier-approved commands can also run. |
auto | Remove routine prompts with background classifier review | The classifier evaluates relevant actions against the request; this is a different approval mechanism from deterministic denial. |
dontAsk | Run unattended and refuse unresolved calls | Calls that would prompt are denied rather than silently authorized. |
bypassPermissions | Skip permission prompts in an isolated environment | Anthropic limits its recommended use to environments such as containers or VMs where damage is contained. |
Auto mode requires a supported model and can be disabled by organization policy; when it is unavailable, a session that selects it starts in Manual instead. Do not solve missing unattended permissions by switching to bypass mode. First identify whether the workflow should possess the action at all. If a bounded action is appropriate, pre-approve its documented tool pattern; if the action needs a human, move it to a stage with an approval path.
Explicit denials still apply across modes. Set permissions.disableBypassPermissionsMode: "disable" in managed policy when developers must not enter bypass mode. If classifier-driven autonomy is also disallowed, use the separate permissions.disableAutoMode: "disable". The two settings prohibit different modes.
Keep approvals narrow and test the rejected path
A team can start ordinary refactoring in acceptEdits, approve a bounded test command with permissions.allow, and require confirmation for a publication command with permissions.ask. For example, Bash(npm test *) and Bash(git push *) identify different effects even though both use Bash. Match the actual package manager and commands used by the repository.
Review the actual tool set alongside the approvals: use --tools for the built-in set and decide MCP exposure separately because that flag does not restrict it. Before adopting a bare Bash deny, check whether removing the shell also removes the test path the team needs. Prefer a narrow approval only when the corresponding execution privilege is appropriate.
Bash matching is not a complete authorization boundary. A command-name pattern can miss equivalent invocations through paths, flags, or an interpreter. A Read deny blocks file tools and recognized shell file operations, but not arbitrary programs that open the file indirectly. Review a denied-path test and an indirect-process test rather than demonstrating only that one Read call was blocked.
Keep secret delivery separate from secret accessibility
A shared .mcp.json should contain an integration-specific credential reference, not a token value. That avoids committing the secret; it does not prevent a process from obtaining a credential already available in its environment. Make successful authentication with the intended integration identity part of rollout acceptance, not merely a JSON syntax check.
The Bash sandbox inherits environment variables by default, including secrets. Its default read access also includes much of the machine. Enabling sandbox.enabled: true alone therefore does not establish a secret-free environment. Pair restrictions on file-tool access with the sandbox’s filesystem restrictions where required, and launch development sessions without production credentials that the workflow does not need.
For sandboxed Bash commands, set sandbox.credentials.envVars to entries such as {"name": "GITHUB_TOKEN", "mode": "deny"} to unset the named variable before each command; hooks and MCP servers remain outside that protection. For environment-variable masking, "mode": "mask" supplies a placeholder that the proxy replaces on allowed outbound requests, but Claude Code honors masking only from user settings, managed settings, and --settings; it also requires sandbox.network.tlsTerminate and an allowed destination in sandbox.network.allowedDomains.
A deny entry unsets the named variable before each sandboxed Bash command; hooks and MCP servers remain outside that protection.
Keep production authorization at the service or credential boundary. An ask rule is useful when a legitimate developer can approve an action, but it cannot turn an overprivileged production token into a least-privilege credential. The integration owner supplies development-only credentials; the platform owner verifies where those credentials can be read or forwarded.
Verify what the sandbox actually contains
The built-in sandbox constrains shell commands and their descendants on macOS, Linux, and WSL2. Native Windows commands run unsandboxed; use a supported environment when containment is required. File and web tools, command hooks, and MCP servers are outside that shell boundary.
Lesson 5.1.5 owns the detailed managed containment design, including sandbox.failIfUnavailable, sandbox.allowUnsandboxedCommands, and network restrictions. For a team rollout, carry its decision into the developer environment and test it there. A missing dependency can otherwise cause execution without sandboxing unless startup is configured to fail; an excludedCommands exception deliberately runs matching commands outside containment.
Ask Claude to perform a harmless outside-directory write probe rather than typing the command at the ! prompt, which ordinarily runs unsandboxed. Verify that the command is rejected, then exercise the legitimate test command. If containment prevents required work, review the narrow missing access before adding an unsandboxed exception.
Key distinctions and trade-offs
Autonomy versus privilege: A mode changes approval behavior. Credentials and accessible services determine the effects an approved operation can cause.
Secret reference versus secret isolation: Keeping tokens out of Git solves distribution hygiene. Removing unnecessary credentials and constraining process access solves a different problem.
Shell containment versus whole-session containment: The Bash sandbox does not contain hooks or MCP server processes. An environment-level container or VM is the relevant boundary when the entire Claude Code process and its helpers require isolation.
Architecture / decision scenario
A healthcare software team wants an overnight refactor of a synthetic-data service, with a 30-minute per-task budget. In a pilot, narrow test approvals finish 18 of 20 tasks; two require a publication action that must have release-owner approval. A proposal to enable bypass mode for all tasks would also expose a production token inherited from the runner.
The platform owner removes that token, supplies development-only integration credentials, and runs the refactor in dontAsk with the required tools and test approvals. Publication has no production credential and is also denied through permissions.deny in this unattended stage; it moves to the release owner’s stage. The team verifies sandbox startup, a rejected outside-directory write, and successful tests on its Linux runner. It reviews helper processes separately rather than assuming the shell sandbox contains them. The two incomplete jobs remain visible as workflow design issues instead of being completed through excessive privilege.
Common exam traps
- Treating
acceptEditsas approval for edits only. - Assuming
sandbox.enabled: truealone keeps inherited secrets from sandboxed commands. - Testing the sandbox by typing a probe at the
!prompt. - Assuming environment-variable credential references hide secrets from subprocesses.
- Assuming the Bash sandbox contains MCP servers and hooks.
- Replacing a failed-path investigation with bypass mode.
What to remember
Select approval behavior, tool exposure, credentials, and containment separately. Safe autonomy gives a workflow the access it needs, denies unresolved effects where no reviewer exists, and verifies both useful execution and prohibited access.
Knowledge check
A team runs refactoring sessions in acceptEdits so that file edits proceed without prompts. Its policy requires a person to confirm every deletion. A review finds that Claude ran rm -r src/legacy inside the working directory without a prompt. The sessions run without the Bash sandbox, and no allow rule covers rm. What explains it?
acceptEdits also auto-approves rm inside the working directoryacceptEdits approves every Bash command once the session has edited a filerm belongs to the built-in set of read-only commandsask rules wait for workspace trust before they applyacceptEdits auto-approves common filesystem commands — mkdir , touch , rm , rmdir , mv , cp and sed — for paths inside the working directory or additionalDirectories . Other Bash commands still prompt, as do removals that target a critical path. A deletion policy therefore cannot rest on the mode’s name.A developer’s shell exports GITHUB_TOKEN, which the team’s GitHub MCP server reads. Bash sandboxing is on with sandbox.enabled: true, yet a sandboxed env command printed the token. The token must stay available to the MCP server but must not reach sandboxed commands. What should the team configure?
Read deny rule for the files that hold the tokenallowedDomains list that leaves out GitHub’s API hostGITHUB_TOKEN deny entry in sandbox.credentials.envVarsdontAsk default mode for the team’s development sessionssandbox.credentials.envVars entry with "mode": "deny" unsets the named variable before each command. MCP servers run outside the sandbox, so the server keeps the variable. The token is not read from a file, a network allowlist does not stop a command from printing it, and a permission mode decides approvals rather than what an approved process can see.An overnight refactor runs on a Linux runner with no one watching. Its edit and test commands are pre-approved. Any other call must be refused rather than authorized, and the decision must not depend on a classifier’s judgment. Which permission mode should the job use?
acceptEditsdontAskautobypassPermissionsdontAsk runs pre-approved tools and denies anything that would prompt, which suits unattended work with no reviewer. auto removes prompts through background classifier review, which the requirement rules out. bypassPermissions skips prompts instead of refusing calls, and acceptEdits still prompts for other commands with nobody there to answer.To verify a new sandbox configuration in an interactive macOS terminal session, a developer types ! touch ~/outside-probe at the Claude Code prompt, and the file is created. The sandbox is running, its filesystem policy disallows that path, and no excludedCommands entry matches the probe. The developer concludes that the sandbox does not restrict writes outside the project. What should the team do next?
sandbox.failIfUnavailable and type the same probe againbypassPermissions and type the same probe againtouch to excludedCommands and type the same probe again! prompt ordinarily runs unsandboxed, so this probe says nothing about the sandbox. The test has to be a command Claude runs inside the sandbox; decline any offer to retry it unsandboxed. failIfUnavailable addresses a sandbox that cannot start, and an excludedCommands entry deliberately runs matching commands outside containment.References
- Anthropic, CLI reference
- Anthropic, Permission modes
- Anthropic, Configure permissions
- Anthropic, Configure the sandboxed Bash tool
- Anthropic, Connect Claude Code to tools via MCP
- Anthropic, Settings reference