← Back to BlogSecurity

Claude Code Adds a Write Block That Shell Commands Skip

Claude Code 2.1.314 can refuse Write and Edit calls outside your project in every mode, but not shell commands. Setup, gaps and a sandbox pairing.

Claude Code 2.1.314, dated October 30, 2026 in the changelog, added a setting that makes the file tools refuse paths outside your working directories, in every permission mode, including bypassPermissions. Turn on permissions.blockWritesOutsideWorkingDirectories and Write, Edit and NotebookEdit stop at the project edge, apart from a few files Claude Code itself keeps writable. Shell commands are not covered, so a script or a test run that gets approved can still write wherever your account can, unless the Bash sandbox is on too.

Sources: Claude Code changelog, 2.1.314 (October 30, 2026), Claude Code docs: Block file-tool reads and writes outside the working directories

This post covers what the key changes in each permission mode, which routes it leaves open, the sandbox settings that cover those routes, and the rollout details that catch people out. Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section accordingly. Everything before that section is about Claude Code itself and applies with or without us.

What shipped in 2.1.314

The changelog entry reads: "Added permissions.blockWritesOutsideWorkingDirectories: Write, Edit and NotebookEdit refuse paths outside the working directories in every permission mode". The GitHub release page for v2.1.314 carries the same line. The key is unset by default, so writes outside the working directories keep following your permission mode.

Sources: Claude Code changelog, 2.1.314 (October 30, 2026), GitHub release v2.1.314, Claude Code docs: permissions.blockWritesOutsideWorkingDirectories

A working directory, in the docs' terms, is the directory you launched Claude Code in (or moved the session to with /cd) plus any you add with --add-dir, /add-dir or additionalDirectories in settings. With the key unset, a write to a path outside those follows your permission mode. With it on, the file tools refuse instead. The docs say a few Claude Code files stay writable, such as plan files and the session scratchpad, and that the key has a read-side twin, permissions.blockReadsOutsideWorkingDirectories, which needs 2.1.257 or later. We covered that release in What Is Containment Escape in Claude Code?

Sources: Claude Code docs: Working directories, Claude Code docs: Block file-tool reads and writes outside the working directories, Claude Code docs: permissions.blockWritesOutsideWorkingDirectories, Claude Code docs: permissions.blockReadsOutsideWorkingDirectories

Turn it on and test it

Check the version first with claude --version, because the key needs 2.1.314 or later. Then add it to ~/.claude/settings.json. A true in any settings file the session loads applies, so putting it in your user file means every project gets the block and no repository can lift it.

Sources: Claude Code docs: CLI reference, Claude Code docs: permissions.blockWritesOutsideWorkingDirectories

Pro Tip

Merge into ~/.claude/settings.json, or create the file with this content: { "permissions": { "blockWritesOutsideWorkingDirectories": true } }

The docs give a test. Ask Claude to use the Write tool to create a file outside your working directories, such as ~/block-test.txt. The call should fail with a message that begins with the path. One documented wording says "the permissions.blockWritesOutsideWorkingDirectories setting blocks writes outside the working directories". The docs list a second wording that names the setting in parentheses. If you launched Claude Code from your home directory, your home directory is a working directory and the block will not refuse the test file. That is the first lesson about this key: the fence sits wherever you launch from. A Planted AGENTS.md in Downloads Can Steer Your Coding Agent makes the same point about launch folders.

Sources: Claude Code docs: permissions.blockWritesOutsideWorkingDirectories, Claude Code docs: Setting blocks writes outside the working directories

The refusal text is written for the model and points to /add-dir or to removing the setting. One documented wording tells Claude to ask the user to add the directory. Expect Claude to come back and ask you to widen the fence, and treat that as a question for you. Claude's file tools cannot lift the block by editing a settings file, because the docs say Write, Edit and NotebookEdit writes to settings files are refused too while the key is on. If the block does not seem to apply, claude doctor reports invalid settings files and /status shows which settings sources are active.

Sources: Claude Code docs: Setting blocks writes outside the working directories, Claude Code docs: permissions.blockWritesOutsideWorkingDirectories, Claude Code docs: Check resolved settings

What changes in each permission mode

With the key unset, what happens to a write outside the project depends on the mode. This table follows the permission-modes documentation, covers four of the modes and assumes no allow or deny rule matches the path.

Sources: Claude Code docs: Choose a permission mode

Permission modeWrite or Edit outside the working directories, key unsetKey on
Manual (default)Prompts youRefused
acceptEditsPrompts you; auto-approval covers only paths inside the working directoriesRefused
autoGoes to the classifier model to review; only edits inside the working directories are auto-approvedRefused
bypassPermissionsRuns with no promptRefused

The change matters most in the last two rows. In auto mode a classifier model decides whether a write outside the project is fine. In bypassPermissions mode nobody decides: the docs describe it as disabling permission prompts and safety checks, and list it for isolated containers and VMs only. With the key on, both modes refuse, and per the docs no allow rule lets the file tools through the block.

Sources: Claude Code docs: Choose a permission mode, Claude Code docs: Block file-tool reads and writes outside the working directories

The auto row is not an edge case. With Claude Code 2.1.283 or later, the built-in starting mode for interactive terminal and VS Code sessions is auto, whenever auto mode is available to the session. A session you start without choosing a mode, with no defaultMode in your settings, therefore begins in the mode where a classifier, not you, reviews a write outside the project. If you want a hard rule in that path rather than a model judgment, this key is the file-tool version of one.

Sources: Claude Code docs: Choose a permission mode

For ordinary project files inside the working directories nothing changes, apart from the settings-file and worktree cases covered below. The key is a fence around the project, not a scope control for the files within it, which is the problem Why Claude Code Edits Files You Never Named works through.

What the key does not cover

The docs say it in one sentence: "The key doesn't limit shell commands, MCP tools, or the programs hooks run". The table puts each route next to what does limit it.

Sources: Claude Code docs: Block file-tool reads and writes outside the working directories, Claude Code docs: What runs outside the sandbox

Route to a write outside the projectCovered by the new keyWhat limits it
Write, Edit and NotebookEdit toolsYes, in every permission modeThe key itself
Shell commands Claude runs (Bash, PowerShell, Monitor)NoThe Bash sandbox. Edit deny rules also match some recognized file commands and redirect targets, but not scripts
Programs a shell command starts, such as test runners and build scriptsNoThe sandbox, which covers the processes a sandboxed command starts
MCP tools and local MCP serversNoNot the sandbox, since local MCP servers run with your full access. A container or VM around Claude Code covers them
Programs that hooks runNoNot the sandbox either. A container, VM or sandbox runtime around the whole Claude Code process covers them

Two older controls fill part of the gap. The first is a per-path Edit deny rule, such as Edit(~/.ssh/**), which still works for named locations. It matches the file tools plus some shell commands Claude Code recognizes, such as tee and output redirects, but not a script that opens files itself, which is the limit we walked through in Claude Code Permissions: What Deny Rules Miss. The second is the sandbox, which the docs point to for limiting where shell commands write.

Sources: Claude Code docs: What Read and Edit rules cover, Claude Code docs: Block file-tool reads and writes outside the working directories

A GitHub issue opened on October 27, 2026 (UTC) shows what the gap looks like in practice. The reporter says a subagent using worktree isolation wrote a test whose fixture ran its arguments through sh -c, that the test passed a payload containing rm -rf ~, and that the command ran against the real home directory when the suite ran. They list Claude Code 2.1.311, permission mode auto and Bash sandboxing disabled, and say unpushed work was lost. That is one user's account and we have not reproduced it. What it shows is where the deletion happened: inside a test process, not in a Write or Edit call. By the docs' description, a key that limits only those tools would not have applied.

Sources: anthropics/claude-code issue 105342

Claude Code does check rm and rmdir commands for critical paths such as your home directory, including inside sh -c scripts. The docs add that the check can miss some commands, so it does not replace an operating-system control such as sandboxing. A destructive command inside a program the shell started, as in that report, is the case an OS boundary is for.

Sources: Claude Code docs: Critical paths

A user of the desktop app's Code tab on Windows, in an issue filed October 18, 2026 (UTC), made this request: "By default, restrict file access (read, search and shell commands) to the project folder." One request is not a trend. The controls that map to it are split by tool: write and read blocks for the file tools, and the sandbox for shell commands. Mods are one more route outside the sandbox, covered in Claude Code Mods Ship Unsandboxed, On by Default.

Sources: anthropics/claude-code issue 103269, Claude Code docs: Block file-tool reads and writes outside the working directories, Claude Code docs: What runs outside the sandbox

The sandbox half of the setup

The docs describe the Bash sandbox as a boundary the operating system enforces around the shell commands Claude runs. Its limits cover Bash, PowerShell and Monitor commands and the processes they start. By default sandboxed commands can write to the working directory, a per-user temp directory and directories you added. Six things decide whether it holds:

Sources: Claude Code docs: Configure the sandboxed Bash tool

  • It is off by default. Turn it on with /sandbox, or set sandbox.enabled to true.
  • Native Windows runs commands unsandboxed, and the docs say to run Claude Code inside WSL2 there. On Linux and WSL2 the sandbox needs bubblewrap and socat.
  • If the sandbox cannot start, because the platform is unsupported or the dependency check at startup fails, Claude Code runs commands unsandboxed unless sandbox.failIfUnavailable is true. With that key on, Claude Code exits at startup instead.
  • Claude can retry a command that fails in the sandbox outside it. In bypassPermissions mode the retry runs with no prompt, and a matching allow rule approves it too. Set sandbox.allowUnsandboxedCommands to false to turn the retry off.
  • Commands that match excludedCommands run unsandboxed, and so do commands you type at the ! prompt in most sessions.
  • The working directory is writable inside the sandbox, and the docs warn that sandboxed commands can still delete it. Commit or push work you care about before a long unattended run.

A starting point for ~/.claude/settings.json on macOS, Linux or WSL2 pairs the two layers. A false for allowUnsandboxedCommands in your user settings holds even when a project sets it to true, which the docs say needs 2.1.285 or later. On Linux and WSL2, install bubblewrap and socat first, because the sandbox relies on them and failIfUnavailable makes Claude Code exit at startup when the dependency check fails. On native Windows, leave out failIfUnavailable, or Claude Code will not start.

Sources: Claude Code docs: sandbox.allowUnsandboxedCommands, Claude Code docs: sandbox.failIfUnavailable

Pro Tip

Merge into ~/.claude/settings.json, or create the file with this content: { "permissions": { "blockWritesOutsideWorkingDirectories": true }, "sandbox": { "enabled": true, "allowUnsandboxedCommands": false, "failIfUnavailable": true } }

Rollout details that catch people out

  • Claude's file tools cannot edit Claude Code settings files while the key is on, even inside the project, because a settings file could lift the block. Edit .claude/settings.json yourself.
  • To let one outside directory through, run /add-dir <directory>, pass --add-dir, or list it under additionalDirectories in your user or managed settings. A directory that only repository settings add does not count. The same directories are also writable inside the sandbox, so one /add-dir widens both fences.
  • Worktrees are affected. The docs say Claude Code removes the EnterWorktree and ExitWorktree tools or refuses calls to them, and refuses edits from an isolation: worktree subagent whose worktree sits outside the working directories. For subagent worktrees the documented fix is to add the .claude/worktrees directory at the repository root.
  • The docs list the key among those where a true from any scope is honored even when a managed source sets false. A cloned repository can turn the block on for itself but cannot lift yours.
  • Some of Claude Code's own files stay writable: plan files, the scratchpad, a background session's tmp directory, and .md files in the project's auto memory.
  • In a cloud session the key might not apply, because the container is the boundary. The block is also on while Claude Code cannot read the permissions object in your managed settings.

A five-minute checklist

  • Run claude --version and confirm 2.1.314 or later.
  • Add the copy-paste block above to ~/.claude/settings.json, minus failIfUnavailable on native Windows.
  • Start Claude Code from the project root, not your home directory.
  • Run the Write test and confirm the refusal message.
  • On macOS, Linux or WSL2, ask Claude to run touch ~/sandbox-probe. Inside the sandbox it should fail with Operation not permitted on macOS or Read-only file system on Linux and WSL2. Decline any retry outside the sandbox.
  • If the command succeeds, delete the file and run /sandbox to check that the sandbox is on and its dependencies are installed.
  • Add outside directories deliberately with /add-dir, and commit or push before unattended runs.

Where TLM Forge fits

This is a containment problem, and TLM Forge is not a containment layer: its commit hook matches the command text of git commit, git push and gh pr merge, not file paths. Set the write block and the sandbox first.

What a process layer adds sits around the task. Medium and Deep tasks show you a design for your OK before building, and the final review wave includes a phase-auditor that checks the spec's out-of-scope items were respected. That is scope in the spec sense, not the filesystem sense. The auditor is an LLM agent, so it can miss things, and it is not a boundary around your home directory.

Frequently asked questions

01How do I stop Claude Code from writing outside my project folder?

Set permissions.blockWritesOutsideWorkingDirectories to true in a settings file, on Claude Code 2.1.314 or later. The Write, Edit and NotebookEdit tools then refuse paths outside your working directories in every permission mode. Shell commands are separate, so turn on the Bash sandbox as well.

02Does the write block work in bypassPermissions mode?

Yes. The docs say the file tools refuse writes outside the working directories in every permission mode, including bypassPermissions. A few Claude Code files, such as plan files and the session scratchpad, stay writable. Allow rules cannot lift the block, and the file tools cannot edit settings files while it is on.

03Does the write block stop rm -rf or scripts that delete files?

No. The setting limits only the Write, Edit and NotebookEdit tools. Shell commands, and any script or test runner they start, are outside it. The Bash sandbox, which is off by default, is the documented way to limit where shell commands write.

04How do I let Claude Code write to one extra directory?

Add it as a working directory. Run /add-dir with the directory in the session, pass --add-dir at startup, or list it under additionalDirectories in your user or managed settings. A directory added only in repository settings does not count, and no allow rule lifts the block.

05Is the Claude Code sandbox on by default?

No. Turn it on with /sandbox or by setting sandbox.enabled to true. On native Windows, commands run unsandboxed, so the docs say to use WSL2. On Linux and WSL2 you need bubblewrap and socat. Without failIfUnavailable, a sandbox that cannot start falls back to unsandboxed commands.

Ship AI-written code you can trust

TLM Forge is the missing process layer for Claude Code: a spec audit, independent multi-agent review, enforced TDD, and an adversarial red-team gate.

Get TLM Forge