Claude Code 2.1.314 can refuse every file write outside your project. What blockWritesOutsideWorkingDirectories covers, and what still writes

You start Claude Code in a project folder and expect it to stay there. In Manual mode it mostly does, because it asks before its file tools touch anything outside that folder. In auto mode a classifier answers for you, and with --dangerously-skip-permissions nothing does. If the agent decides that the fix belongs in ~/.zshrc, or a prompt in a cloned README tells it to edit ~/.ssh/config, the Edit tool may simply do it.

Claude Code 2.1.314, released on October 30, adds a setting for this. The changelog puts it in one line:

Added permissions.blockWritesOutsideWorkingDirectories: Write, Edit and NotebookEdit refuse paths outside the working directories in every permission mode

This post explains what that line means, how to turn it on, and which writes it does not stop. It is based on the 2.1.314 release and Anthropic's docs as they read on October 30, 2026. We have not run the setting ourselves yet. We make Sessionboxer, which runs the agent in a container; that part is near the end.

What the setting does

Claude Code has three tools that write files: Write creates or replaces a file, Edit changes part of one, and NotebookEdit changes a Jupyter notebook cell. With the new setting on, all three refuse a path outside the working directories. The changelog says this holds "in every permission mode". So it applies in auto mode and in bypassPermissions, the mode that --dangerously-skip-permissions turns on, where normally nothing is refused.

The permissions docs define the working directories. They are the folder you started Claude Code in, plus any folder you add with --add-dir at start, /add-dir during a session, or additionalDirectories in a settings file.

Before this release, the boundary was a prompt. Anthropic's security page says so directly: in Manual mode, Claude Code asks before its file tools read or write outside the folder where it was started, and "the boundary is a permission prompt, so a Bash command you approve can still write anywhere your user account can". A prompt only helps when someone reads it, and the other two modes do not ask you. The new setting turns the prompt into a refusal that the mode cannot lift.

Turning it on looks like this, in ~/.claude/settings.json:

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  }
}

The setting needs 2.1.314 or later; check with claude --version.

Its older sibling, and what the docs say about it

The write block is new enough that the settings reference has no entry for it yet. It does have one for permissions.blockReadsOutsideWorkingDirectories, which arrived in 2.1.257 and does the same job for reading. The reference says that with the read block on, Read, Grep, Glob and LSP calls outside the working directories are denied in every permission mode, and Claude is told to ask you to add the directory with /add-dir. Files Claude Code needs for itself, such as your skills, plugins and CLAUDE.md under ~/.claude/, stay readable.

Three rules in that entry matter if you use the two together:

• A true in any settings file applies. The reference says this means "a repository can turn the block on for itself but can't lift yours."
• Directories added only in a repository's .claude/settings.json do not count as working directories for the block. Ones you add on the command line or in your user settings do.
• To lift it, remove the key from every settings file that sets it and start a new session.

We do not know yet whether the write block follows the same rules. The changelog does not say, and the reference has no entry. If you depend on one of these details, test it on your machine before you rely on it.

To turn both on:

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true,
    "blockWritesOutsideWorkingDirectories": true
  }
}

What still writes outside the project

The changelog names three tools. The shell is not one of them. If the agent runs echo 'alias ls=rm' >> ~/.zshrc or sed -i on a file in your home folder, the Bash tool does it, and nothing in the changelog line says the new setting stops that.

The read block is documented as working the same way. The reference says plainly that "Claude Code doesn't refuse shell commands the same way". Instead, recognized file-reading commands that reach outside the working directories ask you first, even in auto mode and bypassPermissions, and a command the parser cannot follow, such as one that runs a subshell, asks too. Whether the write block adds a similar prompt for shell commands is not documented today.

The thing that does confine the shell is the Bash sandbox. The sandboxing docs describe how it limits what commands can write at the operating system level. They also say what it leaves out: Read, Edit and Write "follow permission rules instead", and hooks, local MCP servers and helper commands "run with your full access". The sandbox covers shell commands and the new setting covers the file tools, so you want both on if you want the agent's writes to stay in the project on your own machine.

Two more limits:

• Other processes that Claude Code starts, such as an MCP server you configured, write with your account's rights. The setting is about Claude's file tools.
• The refusal depends on a path check. This week's advisory, GHSA-5xjx-9qx6-jcrv, was about exactly such a check being raced with a symlink on macOS, and the fix was an update. We wrote about it in Claude Code's Edit tool symlink race. Keep Claude Code updated; the setting does not replace that.

Other fixes in 2.1.314 worth a look

Three other changes in the same release are close to this one:

• Sandbox protections now apply to a worktree that claude -p --resume or --continue enters.
• Auto mode's prompt before the first read outside the working directories now says when blocking those reads makes shell commands ask for permission.
• claude -p no longer exits with code 0 and no output when startup fails. It prints the error and exits 1.

A quick test before you trust it

The docs are thin, so spend five minutes watching the setting work:

1. Update with claude update (or your package manager), then check claude --version shows 2.1.314 or later.
2. Add the key to ~/.claude/settings.json and start a new session in a scratch folder.
3. Ask Claude to create /tmp/blocktest.txt with its Write tool. It should refuse.
4. Ask it to create notes.txt in the project. It should work.
5. Ask it to run echo hi > /tmp/blocktest.txt in the shell. Note what happens. This tells you how much the shell is still allowed on your setup.

Step 3 also shows a cost. Agents use /tmp for scratch files, and /tmp is outside your project. If the agent starts failing on its own scratch files, add a folder for them with --add-dir, or tell it in CLAUDE.md to use a folder inside the project.

Where Sessionboxer fits

Sessionboxer runs each session in its own Docker container. The repositories are cloned into /workspace in the box, which is the agent's working directory, and Claude Code runs there with every permission granted: the image sets bypassPermissions. Your home folder is not mounted in the box. A folder from your machine is copied in, and the Start a session chapter explains how the agent's work comes back.

In that setup, a write outside /workspace lands in the container's own filesystem. It can still break the session, but it does not reach your laptop. Each turn ends with a snapshot, so you can go back to the state before a bad turn; the snapshots and forks chapter shows how.

What Sessionboxer does not do here:

• The image pins Claude Code 2.1.272, which is older than 2.1.314. The new setting does not exist in the box until we ship an image with a newer version, so putting the key in a repository's .claude/settings.json has no effect in a Sessionboxer session today.
• We do not turn on the read block, the write block or the Bash sandbox in the box, because the container is the boundary.
• A container shares the host kernel, so it is a weaker wall than a VM. Network egress from the box is not restricted, and the agent's login token is in the box, so code that runs there can read it.

If you run Claude Code directly on your own machine in auto mode or with prompts off, the new setting is a cheap thing to add today, next to the Bash sandbox. For unattended runs on code you have not read, Anthropic's docs still say to use a container or VM, and our guide to running Claude Code with --dangerously-skip-permissions safely compares the ways to get one.