Claude Code blockWritesOutsideWorkingDirectories: Keep Edits Inside the Project

Last updated: November 2, 2026

Claude Code 2.1.314 added permissions.blockWritesOutsideWorkingDirectories. Set it to true and the Write, Edit and NotebookEdit tools refuse any path outside your working directories, in every permission mode, bypassPermissions included. It does not limit shell commands, MCP tools or hooks, so pair it with sandboxing if you need a hard boundary. One line in ~/.claude/settings.json turns it on, and a repository cannot turn it back off.

It is the write-side twin of permissions.blockReadsOutsideWorkingDirectories, which arrived in v2.1.257. Everything below is from the settings reference and the permissions docs, read November 2, 2026.

Official Sources#

Why it matters#

Permission modes decide whether Claude asks before an edit. They do not decide where an edit can land. In acceptEdits, auto mode or bypassPermissions, a file tool could write to ~/.zshrc or a sibling repository as easily as to your project. This key draws the line by location instead, and it holds in every mode. If you run long unattended sessions, it is the cheapest guardrail you can add. Pair it with the allow and deny rules in our Claude Code permissions guide.

%% title: How Claude Code 2.1.314 decides whether a file-tool write goes through
flowchart TD
  A["Write, Edit or NotebookEdit on a path"] --> B{"Is it a Claude Code settings file?"}
  B -->|"Yes"| X["Refused, even inside the project"]
  B -->|"No"| C{"Inside a working directory?"}
  C -->|"Yes"| D["Normal permission mode applies"]
  C -->|"No"| E{"One of Claude Code's own files, like a plan file or the scratchpad?"}
  E -->|"Yes"| D
  E -->|"No"| F["Refused: blocks writes outside the working directories"]

Turn it on#

You need Claude Code v2.1.314 or later. Add the key to the permissions object of your user settings at ~/.claude/settings.json:

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

The facts that matter, from the settings reference:

• Type: Boolean. true turns the block on. false is the same as unset, and the block still applies if another settings file sets true.
• Default: unset, so writes outside the working directories follow your permission mode. The block is also on while Claude Code cannot read the permissions object in your managed settings, so a broken managed file fails closed.
• Scope: any settings file. A true in any file the session loads applies, and the key is honored even when a managed source sets false. A repository can turn the block on for itself, but it cannot lift yours.
• Cloud sessions: Claude Code might not apply the key, because the file tools already run in a container that is itself the boundary.

Test that it works#

The docs give a direct test. Ask Claude to use the Write tool to create ~/block-test.txt, assuming your home directory is not a working directory. The call is refused with an error of this form:

<path> is outside <dirs>; the permissions.blockWritesOutsideWorkingDirectories setting blocks writes outside the working directories. Ask the user to add the directory with /add-dir, or to remove that setting.

To lift the block, remove the key from every settings file that sets it, then restart Claude Code.

What stays writable, and what is refused#

Some of Claude Code's own files stay writable outside the project:

• plan files
• the session scratchpad
• a background session's tmp directory
• .md files in this project's auto memory

Along with your own files outside the working directories, the block also refuses writes to:

• Claude Code settings files, even inside the working directories, because a settings file could lift the block. The error reads "Writes to Claude Code settings files are blocked while permissions.blockWritesOutsideWorkingDirectories is on". Edit settings files yourself.
• A directory that only repository settings add, through additionalDirectories in .claude/settings.json, or in .claude/settings.local.json unless git reports that file as untracked.
• A subagent's worktree outside the working directories, for subagents that use isolation: worktree.
• An auto memory directory the repository chose through autoMemoryDirectory in repository settings.

One more side effect: with the key on, Claude Code removes the EnterWorktree and ExitWorktree tools or refuses calls to them. If you rely on Claude Code worktrees, follow the docs' no EnterWorktree tool steps.

Let one directory through#

No allow rule lets the file tools through the block. The only way is to make the directory a working directory:

• run /add-dir <directory> in the session
• pass --add-dir <directory> when you start Claude Code
• list it under additionalDirectories in your user or managed settings

A directory listed only in the project's .claude/settings.json does not count, so a cloned repository cannot widen the boundary for itself. /add-dir needs a directory that exists. For subagent worktrees, add the .claude/worktrees directory at the repository root.

Gotchas#

It does not cover the shell. This is the big one. The key covers Claude's file tools only. A bash command such as echo x > ~/file, an MCP tool, or a program a hook runs is not limited. To limit where shell commands write, turn on sandboxing. Our local sandbox comparison shows how Claude Code's sandbox compares with Codex and Copilot CLI.

It is not a substitute for auto mode's classifier. Auto mode decides whether an action is risky. This key decides where file edits can land. They stack. See Claude Code auto mode explained for what the classifier checks.

Restart after removing it. The docs say to remove the key from every settings file that sets it and then restart Claude Code. A false in one file does nothing while another file still sets true.

The read-side twin#

permissions.blockReadsOutsideWorkingDirectories (v2.1.257 and later) makes the file tools refuse reads outside the working directories, apart from files Claude Code itself needs. Unlike the write key, it reaches further when sandboxing is on. Sandboxed commands then lose read access to your home directory and roots like /Users, /home and /root, while the working directories, the session temp directory and your global git configuration are re-opened. In auto mode, Claude Code offers to turn it on the first time Claude reads outside the working directories.

For a tight local setup, set both:

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

The same /add-dir, --add-dir and user-level additionalDirectories route lets one directory through either block.

What people are actually saying#

• 2.1.314 was published to npm on October 30, 2026. The settings reference documented the key by November 2. We found no Hacker News or Reddit thread about it yet.
• The likely confusion is the shell gap. Anyone who reads "refuses writes outside the working directories" as a sandbox will be surprised by a bash redirect, so test with the Write tool, as the docs do, and enable sandboxing separately.

FAQ#

What does permissions.blockWritesOutsideWorkingDirectories do?#

It makes Write, Edit and NotebookEdit refuse paths outside your working directories in every permission mode, bypassPermissions included. It requires v2.1.314 or later.

Does it stop shell commands from writing outside the project?#

No. It does not limit shell commands, MCP tools or hook programs. Use sandboxing for those.

How do I let Claude write to one directory outside the project?#

Add it as a working directory with /add-dir, --add-dir, or additionalDirectories in user or managed settings. Allow rules do not work, and repository-only additionalDirectories does not count.

Can a repository turn the block off?#

No. A true in any loaded settings file wins, even over a managed false.

Is there a matching setting for reads?#

Yes: permissions.blockReadsOutsideWorkingDirectories, since v2.1.257. With sandboxing on, it also covers sandboxed commands.

Continue Reading#

• Claude Code Permissions: settings.json Allow, Deny, Ask - the rule system this key sits next to
• Claude Code Auto Mode Explained: Permissions Without Prompts - the other half of unattended safety
• Claude Code Worktrees: Parallel Development Without the Chaos - affected by the block's worktree rules

Sources#

• Claude Code settings reference: permissions.blockWritesOutsideWorkingDirectories
• Claude Code settings reference: permissions.blockReadsOutsideWorkingDirectories
• Claude Code docs: Permissions, working directories
• Claude Code docs: Settings, keys honored from any scope
• Claude Code docs: Error reference
• Claude Code docs: Sandboxing
• Claude Code changelog (2.1.314)
• @anthropic-ai/claude-code on npm