Security

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

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 .claude directory 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:

  1. Start a test session with the intended managed, user, project, and local files.
  2. Run /status and record the reported configuration and sandbox state.
  3. Run /permissions and inspect the effective permission result.
  4. Run /doctor and resolve configuration warnings.
  5. Compare the observed result with the policy file stored outside the project.
  6. 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

Can Claude Code change its own settings.json file?+
Yes, if the file is inside a directory that the active Claude Code session can write to. A project-level settings file can therefore be changed by an Edit, Write, or Bash action unless the effective permissions deny that path. A high-priority setting controls precedence; it does not automatically make the file immutable.
How can a project block writes to its .claude directory?+
Use the effective filesystem deny rules to cover the complete .claude path, then verify the result with /status, /permissions, and /doctor. Also inspect hooks, skills, and related project-controlled files. A rule that protects only one JSON file can leave another behavior-changing path writable.
Are managed settings safer than project settings?+
For policy protection, yes. Managed settings are delivered outside the project’s normal writable boundary and have the highest documented configuration priority. They are better for mandatory rules such as denyWrite and failIfUnavailable. Project settings remain useful for repository-specific behavior, but they should not hold the final security boundary.
Can SBPL restrict the entire Claude Code process?+
A hand-written SBPL profile can apply restrictions from outside the Claude Code process, so the profile can cover Claude Code itself and child processes rather than only Bash commands. It can protect selected paths with default-deny rules. However, sandbox-exec is deprecated, so this is a controlled compatibility measure, not a permanent platform guarantee.

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.