Claude Code 2.1.314: Block Writes Outside Working Directories with New Boundary Switch

Restrict Working Directory

Claude Code defaults to the launch directory as the primary working directory. If you launch from work/order-service, only that directory is in scope; launching from the parent work includes billing-service and shared-tools even if they have separate Git repositories.

After confirming version 2.1.314 or newer with claude --version, add the following to the project's .claude/settings.local.json (or .claude/settings.json for team sharing):

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

Once enabled, Write, Edit, and NotebookEdit refuse to modify files outside the working directories . This restriction applies to all permission modes, including bypassPermissions.

To let Claude reference another directory (e.g., ../billing-service) without granting write access to it, start with: claude --add-dir ../billing-service or use /add-dir in-session. Adding a directory for reference also grants write permission ; the new switch only governs writes, while reads follow separate permission rules.

Contain Script Writes

The file-tool switch does not stop writes performed by shell commands (e.g., test scripts). A July 2026 GitHub issue (#75859) reported an agent deleting user files because HOME was temporarily redirected during a test run and later restored, causing cleanup commands to hit the real home directory.

To confine Bash commands and their child processes, enable the sandbox in the same settings file:

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "failIfUnavailable": true
  }
}

With this configuration, Claude will not retry failed sandboxed commands outside the sandbox, and will exit on startup if the platform or dependencies do not support sandboxing.

macOS : built-in sandbox works out of the box.

Linux / WSL2 : require extra dependencies; run /sandbox to list missing packages, install them, then restart Claude Code.

Native Windows : not supported; the above config will cause startup refusal.

Verify Write Boundaries

Create a test layout outside any default-allow temporary directory:

claude-write-lab/
├── project/
└── outside/

Place the combined config in project/.claude/settings.local.json, start a new session from project without adding outside, and prepare a plain text file in outside. Then test:

Attempt 1 : Write a marker file inside project — Expected: New switch does not block; other permissions apply normally.

Attempt 2 : Write a file in ../outside with Write, then Edit the external test file — Expected: Both writes rejected by the new switch.

Attempt 3 : Use Bash to write a marker into ../outside — Expected: Command runs in sandbox; write rejected.

For the Bash test, have Claude execute via the Bash tool:

python3 -c 'from pathlib import Path; Path("../outside/bash-probe.txt").write_text("probe
")'

Confirm Claude actually invoked the tool ; a verbal refusal does not prove the write was blocked. Manual ! shell commands run outside the sandbox in most sessions and are not a valid substitute. After the tool call, check outside for new or changed files; git diff in the project repo will not show additions in adjacent directories.

Troubleshoot Out-of-Bounds Writes

File-tool writes (Write/Edit) : Verify whether the target directory was added via --add-dir, /add-dir, or /cd (which changes the working directory and reloads project config).

Configuration precedence : Use /status → Setting sources to see loaded config files; higher-priority sources may override the project setting.

Script writes after npm test : If a test script writes to ../shared-tools/build-info.json, inspect sandbox allow-lists. Adding the cache path via sandbox.filesystem.allowWrite keeps the test inside the sandbox with an extra writable directory. Conversely, adding the test command to sandbox.excludedCommands runs it entirely outside the sandbox — the failIfUnavailable setting only blocks unsandboxed retries, it does not cancel exclusions .

Git worktree .git directory : Sandbox defaults allow writes to the shared .git directory for index/ref updates, but hooks/ and config remain write-protected.

MCP services or Hooks : These operate outside both the file-tool switch and the Bash sandbox; investigate the corresponding service or script.

References: [1] Anthropic: Claude Code changelog 2.1.314 [2] Anthropic: Settings files and precedence [3] Anthropic: Configure permissions – Working directories / Symlinks [4] Anthropic: Configure the sandboxed Bash tool [5] Anthropic: All settings – Sandbox settings [6] calstfrancis: GitHub issue #75859 (2026-07-08)