Can Claude Code Configuration Be Rewritten by an Agent in 2026? SBPL Tamper Protection

The symptom is simple: Claude Code can edit the file that defines what Claude Code is allowed to do.
The fastest fix is to keep project settings out of the final trust boundary: use denyWrite and fail-closed controls for supervised work, move mandatory policy into managed settings for team work, and place the whole process inside SBPL or an isolated Mac for unattended tasks.
Who should read this: developers who keep .claude/settings.json in a real repository and allow Claude Code to edit project files. DevSecOps engineers protecting team policy from project-level overrides. Platform owners preparing a remote Mac for long-running or unattended terminal agents.
Last updated September 15, 2026. Configuration fields and behavior were checked against the Claude Code configuration documentation, permissions documentation, sandboxing documentation, and the current sandbox-exec manual page.
The real failure is a shared writable boundary
A project-level file can describe permissions, hooks, skills, or other behavior that affects later Claude Code sessions. If the agent can write to the project directory, it may also be able to write to the configuration directory inside that project.
That does not prove that the current Claude Code release will always perform such a modification. Developer issue reports can identify a threat scenario, but they are version-specific signals, not proof of a universal vulnerability. The security question is narrower and more useful:
Can the running process write to a file that later defines its permissions?
If the answer is yes, the file is not a hard security boundary.
Claude Code has several permission surfaces that should not be treated as one control:
- Edit changes files through the agent’s file-editing capability.
- Write creates or replaces files through the agent’s file-writing capability.
- Bash launches shell commands and child processes.
- The official Bash Sandbox primarily constrains Bash and its subprocesses. It does not automatically mean that the entire Claude Code process, every tool, or every configuration path is protected.
- Sandbox Runtime provides the implementation used by the official sandbox path on macOS. Its scope and behavior must be checked against the current release rather than assumed from an older setup.
- A hand-written SBPL profile applies an operating-system sandbox boundary around the launched process and its children.
This distinction explains why a successful Bash restriction does not automatically protect .claude/settings.json. The file may still be reachable through another tool or through a process outside the restricted command path.
Project settings are convenient, not self-protecting
Project settings are good for repository-specific preferences. They can travel with the codebase, support collaboration, and make experiments reproducible. They are poor candidates for mandatory security policy when the same agent can modify the repository.
The weak pattern looks like this:
repository/
├── .claude/
│ ├── settings.json
│ ├── hooks/
│ └── skills/
├── source/
└── build/
If the allowed write area includes the repository root, the visible target is not only settings.json. A hook can change what happens after a tool call. A skill can alter the instructions presented in a later session. Another project-controlled file can influence behavior without changing the main settings file.
The Claude Code permissions reference should be used to verify the current names and semantics of permission controls. The operational rule is more important than the filename:
- Keep ordinary project behavior in the repository when collaboration requires it.
- Keep mandatory deny rules outside the agent-controlled tree.
- Protect the full
.claudedirectory when it influences later sessions. - Review hooks and skills as policy-bearing files, not as harmless project metadata.
- Treat a writable configuration file as mutable input, even when it has a high precedence.
A project setting can tell the agent how to behave. It cannot independently guarantee that the agent cannot rewrite the setting.
Higher priority does not mean immutable
Claude Code configuration is assembled from several scopes. The documented hierarchy includes managed settings, user settings, project settings, and local settings. Managed settings have the highest documented priority, but priority answers a different question from write protection.
Priority asks:
If several values exist, which value is used?
Tamper protection asks:
Can the process change the value that will be used next time?
A project file can lose a merge conflict and still remain writable. A managed rule can win precedence and still require operational verification. The two properties should be reviewed separately.
Arrays create another trap. A permission list such as allowWrite may be combined across scopes rather than behaving like a simple replacement. A single JSON file therefore cannot always reveal the final effective boundary. The configuration result may include entries inherited from another layer.
Use the built-in diagnostic paths before approving a deployment:
- Start a test session with the intended managed, user, project, and local files.
- Run
/statusand record the reported configuration and sandbox state. - Run
/permissionsand inspect the effective permission result. - Run
/doctorand resolve configuration warnings. - Compare the observed result with the policy file stored outside the project.
- Repeat the check after a clean session starts.
The official configuration debugging guide is the authoritative reference for these diagnostic commands. This process catches a common mistake: reviewing a policy file as if it were the final policy engine.
Benefits and limits of project settings
Advantages
- Easy to review in a pull request.
- Portable with the repository.
- Useful for controlled experiments.
- Convenient for repository-specific tools and workflows.
Limitations
- The agent may be able to edit the policy-bearing directory.
- Hooks and skills can expand the effective behavior surface.
- Merge behavior can differ from simple JSON replacement.
- A project file cannot guarantee fail-closed execution if the process can select another route.
- A local developer may accidentally run with a different effective configuration.
The practical boundary is clear: project settings can express business configuration, but they should not be the final authority for protecting the agent from itself.
A failed sandbox can invalidate the protection assumption
A sandbox policy can be correct on paper and still fail as an operational control if the process continues without it. Three cases must be separated.
Case one: sandbox initialization fails
The runtime cannot create the intended sandbox. This may result from an unsupported environment, a policy syntax error, a missing capability, or a platform change. The correct response for unattended work is to stop rather than silently continue.
Case two: execution falls back to an ordinary permission path
The command still runs, but the operating-system restriction is no longer active. Permission prompts or Claude Code rules may remain, yet the process is not operating under the same filesystem boundary.
Case three: an explicit unsandboxed route is allowed
A configuration may permit commands to run outside the sandbox. That can be useful for compatibility, but it directly weakens the assumption that every command is constrained. The current documentation must be checked for the exact field names and behavior before deployment.
The relevant controls confirmed in the task’s documented fact boundary include filesystem.denyWrite, failIfUnavailable, and allowUnsandboxedCommands. Their meaning should not be inferred from a similarly named field or an older example. Use the current Claude Code sandboxing documentation to verify the active release.
For a security-sensitive unattended job, the desired decision is usually:
- If the sandbox cannot start, stop.
- Do not expose an unsandboxed escape route unless the task explicitly requires it.
- Document every excluded command or path.
- Test the failure path, not only the successful path.
- Record whether the restriction covers Bash only or the complete Claude Code process.
A protected settings file is not enough if the agent can continue after the protection disappears.
SBPL protects a wider process boundary
The key difference between Claude Code’s official Bash Sandbox and a hand-written SBPL profile is scope.
The official Bash Sandbox is designed around Bash execution and its child processes. A hand-written profile launched from outside Claude Code can restrict the Claude Code process itself, its child processes, and access to selected filesystem paths. This makes SBPL useful when the main concern is protecting policy files outside the project’s normal trust boundary.
The macOS sandbox language supports default-deny profiles and explicit path rules. A small test profile should protect only invented paths and temporary files. It should not be tested against production repositories, real API keys, system configuration, or shared credentials.
Example profile:
(version 1)
(deny default)
(allow process*)
(allow signal (target self))
(allow file-read*
(subpath "/usr")
(subpath "/System")
(subpath "/private/tmp/claude-sbpl-demo"))
(allow file-write*
(subpath "/private/tmp/claude-sbpl-demo"))
(allow file-read*
(literal "/private/tmp/claude-sbpl-demo/fake-policy.json"))
(deny file-write*
(literal "/private/tmp/claude-sbpl-demo/fake-policy.json"))
This is a demonstration profile, not a production-ready Claude Code policy. It may require additional rules for a real runtime, and a profile that is too restrictive can prevent normal operation. The profile intentionally uses a fictional policy file and a temporary directory.
A reversible launch alias can make the protected path explicit:
alias claude-sbpl='sandbox-exec -f "$HOME/.config/claude/demo.sb" claude'
The alias should point to a test profile first. Remove it when the test ends. Keep the ordinary launch command available so that a failed profile does not become an undocumented operational dependency.
The important warning is that sandbox-exec is marked deprecated. Deprecated does not mean unavailable today. It means the current ability to call it should not be treated as a permanent support commitment. The macOS sandbox reference describes the underlying sandbox model, but it does not turn a deprecated command-line entry point into a long-term product guarantee.
Anthropic’s Sandbox Runtime repository is a separate implementation reference. It confirms that macOS sandboxing can use sandbox-exec with custom policies, but it should not be conflated with a hand-written outer profile. One is the runtime path used by the tool; the other is an external process boundary.
Five steps to test configuration tamper protection
Step one: map every policy-bearing path
List the project settings file, user settings, managed settings location, hooks, skills, wrapper scripts, and environment files that affect Claude Code behavior. Do not stop at .claude/settings.json.
Mark each path as:
- Writable by the agent.
- Writable only by the developer.
- Delivered by platform automation.
- Read-only inside the execution environment.
The first map usually exposes a hidden writable policy path.
Step two: define the allowed write surface
Write down the directories the task truly needs. Separate source changes, build output, temporary files, and policy files. A code agent may need to write source files without needing to write .claude, home-directory policy files, or deployment credentials.
Use filesystem.denyWrite for paths that must remain unchanged. Confirm the exact syntax in the current permissions documentation instead of copying a rule from an older project.
Step three: move mandatory policy out of the project
Put non-negotiable controls in managed settings or another administrator-controlled delivery path. The mandatory set normally includes write denies, sandbox availability requirements, and the decision about unsandboxed commands.
The project can still contain ordinary workflow preferences. It should not be able to remove the rule that prevents the agent from bypassing its own boundary.
Step four: verify the effective configuration
Start a clean session. Run /status, /permissions, and /doctor. Save the output with the deployment record. Then change a harmless test file in the temporary demonstration directory and confirm that the protected fictional policy file remains unchanged.
Do not use a real secret to prove that a secret is protected. A fake policy file tests the control without creating a new exposure.
Step five: test failure and recovery
Disable the expected sandbox capability in a disposable environment. Confirm that the task stops when failIfUnavailable requires a fail-closed result. Test the behavior when an unsandboxed command would otherwise be available.
Finally, restore the policy and start a new session. A control that works only until the process restarts is not sufficient for unattended execution.
Compare the policy locations before choosing a boundary
The following table separates convenience from protection. It does not claim that one layer solves every task.
| Policy location or control | Protects against project self-editing? | Best use | Main weakness |
|---|---|---|---|
| Project settings | No, if the agent can write the project | Repository-specific preferences | Same writable boundary as the agent |
| User settings | Sometimes | Personal defaults and experiments | Local user or process access may still alter behavior |
| Managed settings | Stronger | Mandatory team policy and centrally delivered controls | Requires reliable delivery and verification |
| Official Bash Sandbox | Partial | Restricting Bash and child processes | Does not automatically cover the whole Claude Code process |
| Outer SBPL profile | Broader | Protecting selected paths and the launched process | sandbox-exec is deprecated and profiles need maintenance |
| Independent Mac environment | Strongest operational separation | High-risk, long-running, or unattended work | Requires separate delivery, recovery, and administration |
A managed policy is usually the first upgrade for a team. An outer SBPL profile is useful when the remaining concern is process-wide filesystem access. An independent Mac environment becomes more attractive when the task is unattended, the repository contains sensitive material, or recovery must not depend on the same agent that caused the failure.
Choose the environment by failure impact
The final decision should follow the consequence of a policy edit, not the convenience of the setup.
| Situation | Keep project settings | Add managed settings | Add outer SBPL | Use an independent Mac |
|---|---|---|---|---|
| Developer supervises every change | Yes, for workflow behavior | Optional | Usually unnecessary | Usually unnecessary |
| Team shares a repository and policy | Only for non-critical preferences | Yes | Consider for sensitive paths | Consider for shared long-running jobs |
| Agent runs without supervision | No for mandatory controls | Yes | Strongly consider | Preferred for high-risk tasks |
| Policy must survive project changes | No | Yes | Yes, if compatible | Yes |
| Recovery must be isolated from the agent | Limited | Moderate | Moderate | Strong |
| Physical or local-only interfaces are required | Local setup may be better | Depends | Depends | Verify hardware access first |
An independent Mac is not automatically the best answer. A developer who needs direct physical interfaces, stable local device access, or sustained heavy workloads may prefer a self-managed machine. A remote Mac is more suitable when the priority is a disposable, separately administered execution boundary, remote access, and controlled recovery.
For teams evaluating that route, the ProxyMac console can be used as the place to inspect an available remote environment before testing the policy. The ProxyMac help center is the better starting point for checking delivery and access details rather than assuming that every remote Mac has the same sandbox capabilities.
The practical choice for Claude Code configuration tamper protection
For supervised personal work, project settings can remain in the repository if the developer accepts that they are editable and adds a documented deny rule for the sensitive paths. That is a workflow decision, not a hard security guarantee.
For team work, managed settings should hold the controls that cannot be weakened by a pull request or an agent action. The project file can describe local conventions, but it should not decide whether the sandbox is mandatory.
For unattended work, a fail-closed managed policy plus a broader process boundary is more defensible. Where sandbox-exec compatibility is acceptable, a carefully tested SBPL profile can protect the policy files and directories outside the project. Where the risk or recovery requirement is higher, moving the job to an independent Mac is the cleaner boundary.
The current setup often fails in three ways: its project policy is writable by the same agent it is meant to constrain, its Bash sandbox is mistaken for whole-process isolation, and its recovery path silently continues after sandbox initialization fails. A separate ProxyMac Mac environment can provide a more controlled place to validate managed settings, SBPL behavior, and recovery procedures without placing the test boundary inside the production workstation.
Before choosing a rental environment, record the policy location, whether the task is unattended, the directories that must remain writable, and the recovery action after a failed sandbox. That produces a defensible isolation plan instead of treating a remote Mac as a generic replacement for local execution. For teams that need to check access and environment options first, the ProxyMac service page is the appropriate next step.
FAQ
Further Reading
Run Claude Code on an Isolated Mac
Use ProxyMac to run agent-driven workflows on a separate Mac without exposing your primary computer.
Deploy a remote Mac for testing configuration changes, sandbox rules, and SBPL protection in a controlled environment.