Approval for reads outside working directories
CHANGELOG · original
Added a one-time prompt in auto mode before the first file read outside the working directories, with the option to block such reads (permissions.blockReadsOutsideWorkingDirectories) Open official changelog ↗ Documentation
Documentation excerpt
permissions.blockReadsOutsideWorkingDirectories
Make Claude's file tools refuse reads outside your working directories in every permission mode, including bypassPermissions. Claude Code denies Read, Grep, Glob, and LSP calls on those paths and tells Claude to ask you to add the directory with /add-dir. Files Claude Code itself needs stay readable, such as your skills, plugins, rules, agents, commands, and the CLAUDE.md memory file under ~/.claude/. Requires Claude Code v2.1.257 or later.
Claude Code doesn't refuse shell commands the same way:
- Actions no mode auto-approves covers when a shell command that reads such a path prompts you
- Sandboxed commands under the block covers what a sandboxed command can read
A Bash command the shell parser can't trace, such as one that changes directory more than once or runs a subshell, prompts you even in auto mode and bypassPermissions mode. The prompt appears even when the command names no path outside the working directories. This prompt doesn't apply when the command runs in the sandbox and the sandbox enforces the block.
Claude Code also writes true here when you choose to block such reads on auto mode's prompt before the first read outside the working directories.
- Scope:
Any file. Atruein any file applies, so a repository can turn the block on for itself but can't lift yours. - Type: Boolean
true: Claude's file tools refuse reads outside the working directoriesfalse: the same as unset; the block still applies if another file setstrue
- Default: unset, so reads outside the working directories follow your permission mode
{
"permissions": {
"blockReadsOutsideWorkingDirectories": true
}
}
To lift the block, remove the key from every settings file that sets it, then restart each running session.
Directories you add with --add-dir, /add-dir, or additionalDirectories in your user or managed settings count as working directories for the block. Directories added only in repository settings don't count: those in .claude/settings.json, and those in .claude/settings.local.json unless git reports that file as untracked. In a directory that isn't a git repository, or when git tracks the file, Claude Code treats .claude/settings.local.json as repository settings, so put directories you want to keep readable in your user settings instead.
When autoMemoryDirectory comes from the project's .claude/settings.json, or from a .claude/settings.local.json treated as repository-supplied, Claude Code loads no auto memory from that directory and saves none to it.
Sandboxed commands under the block
When sandboxing is on, the block also covers sandboxed commands. Claude Code denies them read access to your home directory and to the other roots that hold user files: /Users, /home, /root, /Volumes, /mnt, /media, /run/media, and /srv. It then re-opens the working directories, worktrees Claude Code creates in the session, the session temp directory, and the parts of ~/.claude that commands need, such as skills and plugins. While the block is in force, allowRead and allowWrite entries from repository settings don't count.
When the session's working directory is a linked git worktree, including one Claude Code entered mid-session, the repository's common .git directory stays readable and writable to sandboxed commands, so git keeps working there.
In these cases the block doesn't reach sandboxed commands, while Claude's file tools keep enforcing it:
- Filesystem isolation is off through
sandbox.filesystem.disabled allowManagedReadPathsOnlyis set- The path of the directory you started Claude Code in contains a glob character such as
*,?, or[
Under the block, Claude Code re-opens your global git configuration files to sandboxed commands so git keeps your identity and settings:
~/.gitconfig- The
config,ignore, andattributesfiles under$XDG_CONFIG_HOME/git, which defaults to~/.config/git - Files your global git configuration names through
[include],[includeIf],core.excludesFile, orcore.attributesFile
Claude Code judges each file separately. When a file lies where a sandboxed command can write, directly or through a symlink, Claude Code doesn't re-open the files it names.
On Linux and WSL2, a configuration file that is a symlink can stay unreadable at its own path, and git then runs without it. ~/.git-credentials and $XDG_CONFIG_HOME/git/credentials stay blocked.
If a re-opened file holds a secret, such as an http.extraHeader token, add its path to sandbox.filesystem.denyRead. A denyRead entry that covers a file always takes precedence over this re-open.
Documentation snapshot · 2026-11-20
Documentation excerpt
The first read outside the working directories
While permissions.blockReadsOutsideWorkingDirectories is off, file reads other than reads from network paths run without a prompt in auto mode, including reads outside the working directories. The first time Claude uses the Read, Grep, or Glob tool on a path outside them, Claude Code asks whether to allow that read.
The prompt doesn't appear in -p runs, Agent SDK sessions, background sessions, the VS Code chat panel, or the desktop app. There, the read runs.
Whatever you answer, Claude keeps working:
- Yes, and keep allowing any reads outside the working directories: the read runs, later reads outside the working directories run as before, and Claude Code records your answer so the prompt doesn't appear again
- No, and block reads outside the working directories from now on: the read is refused, and Claude Code sets
permissions.blockReadsOutsideWorkingDirectoriestotruein your user settings, which makes the file tools refuse such reads in this and every later session and every permission mode. To lift the block, remove the setting from every settings file that sets it, then restart each running session. For one directory this session, use/add-dir. - No, and ask again next time: the read is refused, and the next read outside the working directories prompts again
- Yes, but ask again next time: the read runs, nothing is saved, and the next read outside the working directories prompts again
Documentation snapshot · 2026-11-20