Protected Paths and Workspace Trust
- Identify which directories and files Claude Code protects in every mode and why allow rules cannot override that protection
- Understand how workspace trust controls whether project allow rules and additional directories activate in a session
- Avoid the home-directory trust trap that silently prevents workspace trust from persisting across sessions
A Safety Layer Below Rules
Permission rules let you configure what Claude Code can access. Protected paths are a safety layer that sits below rules — a hardcoded list of directories and files that are never auto-approved regardless of what your rules say. Even if you write allow: ["Edit(.claude/**)"] in your settings, Claude Code does not honor that allow rule for protected-path writes. The protected-path check runs before allow rules are evaluated.
This design prevents two failure modes: accidentally allowing Claude to corrupt its own configuration, and allowing an attacker-controlled allow rule (injected through a repository's settings file) to grant write access to shell configuration files.
The Protected Directories
The following directories are protected in every mode except bypassPermissions:
.gitand.config/git.claude(except.claude/worktreeswhere Claude manages its own git worktrees).vscode,.idea.husky,.cargo,.devcontainer,.yarn,.mvn
The following files are also protected:
- Shell configuration:
.bashrc,.bash_profile,.bash_aliases,.zshrc,.zprofile,.zshenv,.profile,.envrc, and their login/logout variants - Git configuration:
.gitconfig,.gitmodules - Package manager:
.npmrc,.yarnrc,.yarnrc.yml,bunfig.toml,.pnpmfile.cjs - Build tools:
.bazelrc,.bazelversion - Hook managers:
.pre-commit-config.yaml,lefthook.yml,lefthook.yaml - Claude configuration:
.mcp.json,.claude.json
What Protected Means in Each Mode
The handling of protected-path writes varies by permission mode:
Protected-path writes prompt for manual approval. You decide each time.
Protected-path writes are routed to the auto-mode classifier. The classifier applies its own judgment rather than auto-approving.
Protected-path writes are auto-denied. They cannot execute regardless of any allow rule.
Protected-path writes are allowed. This is one of the core reasons bypassPermissions requires a container.
When Claude Code prompts for a write to the .claude/ directory, the dialog offers Yes, and allow Claude to edit its own settings for this session. Choosing this option approves all future .claude/ writes in the current session without prompting again — useful when Claude is legitimately updating hooks or settings as part of a setup task.
Workspace Trust and Project Allow Rules
Project allow rules and additionalDirectories entries in .claude/settings.json grant capability — they expand what Claude can access. Claude Code does not apply them until you accept the workspace trust dialog for that project. Until trust is accepted, Claude reads the rules but ignores them.
When you open a project for the first time, the trust dialog shows you the allow rules and additional directories the project would grant so you can review them before accepting. This prevents a malicious repository from silently expanding Claude's permissions the moment you open it. Deny rules are not affected — they restrict rather than grant, so they apply without trust acceptance.
Claude Code saves trust per workspace, keyed on the git repository root. Trusting a parent directory does not apply a nested project's allow rules.
The Home-Directory Trap
When you start Claude Code directly from your home directory (~), workspace trust acceptance is held for the current session only and is not written to disk. The dialog reappears on every launch. This is intentional: the home directory contains everything, and saving permanent trust for it would mean Claude Code silently applies any project's allow rules the next time you happen to open a terminal there.
The practical consequence: if your terminal defaults to opening in ~, project allow rules will never activate. Always start Claude Code from a project subdirectory where trust acceptance is persisted. Add cd ~/projects/myproject before your Claude Code launch alias if needed.
The same caveat applies to .claude/settings.local.json allow rules when you are outside a git repository or in your home directory. In those contexts, Claude Code treats the file as potentially repository-supplied and may not apply its allow rules without the trust dialog. Starting from a project subdirectory with a proper git root resolves this.
Working Directory Scope
Claude Code writes only to the working directory where you launched it and its subdirectories. Reads can reach anywhere the filesystem allows, but writes outside the working directory require explicit permission in every mode except bypassPermissions.
Use /add-dir <path> to grant file access to an additional directory during a session, or --add-dir <path> at startup. Unlike adding a path to permissions.additionalDirectories in settings, the --add-dir flag also loads skills, subagents, and (with the right environment variable) CLAUDE.md from that directory. Use /cd to relocate the session's primary working directory entirely, which loads the new directory's CLAUDE.md and changes the trust context.
- Protected paths (.git, .claude, shell rc files, and others) are never auto-approved regardless of allow rules — the safety check runs before rule evaluation in every mode except bypassPermissions.
- permissions.allow rules cannot pre-approve protected-path writes — the only way to get session-wide .claude/ write approval is to explicitly accept the "Yes, and allow Claude to edit its own settings" prompt.
- Workspace trust controls whether project allow rules and additionalDirectories entries activate — until trust is accepted for a workspace, Claude reads those rules but does not apply them.
- Starting Claude Code from your home directory means trust is never saved to disk — the trust dialog reappears on every launch; always start from a project subdirectory to persist trust correctly.
- The --add-dir flag grants file access and also loads skills, subagents, and CLAUDE.md from the added directory; additionalDirectories in settings.json grants only file access without the configuration loading.