skip to content

Security & Governance

Containing a coding agent: OS-level sandboxing for shell commands, workspace trust against repository-supplied config, and organization policy over settings and data. Asked because it runs as you.

part ofClaude Coderead it →
on this pageshow

explore

questions

17

In Claude Code, what is the workspace trust dialog, and what does accepting it switch on for a folder?

level: juniorimportance: must knowfreq 24%

answer

  1. interactive start in an unfamiliar folder
  2. capability-granting config waits
  3. restrictions apply at once
  4. keyed on the git repository root
  5. home directory: session only

basics

~20 s

The workspace trust dialog is Claude Code's interactive prompt in a folder you haven't trusted. Accepting it lets the repository's own config act: settings-file hooks, permissions.allow rules, additional directories and most env values. Deny and ask rules apply regardless.

solid answer

~40 s

When you start `claude` interactively in a folder you haven't trusted, it shows the workspace trust dialog before the repository's own configuration can act. Until you accept, it holds back hooks from every settings file, the `permissions.allow` rules and `permissions.additionalDirectories` in `.claude/settings.json` (the dialog lists them for review), most `env` values, and any approval the repository commits for its own `.mcp.json` servers. `deny` and `ask` rules apply straight away, because they only restrict. Trust is keyed on the git repository root, so it covers the whole repository except a nested repository such as a submodule, and it is saved per project in `~/.claude.json`. Started in your home directory, the acceptance lasts for that session only. The dialog is interactive-only: `claude -p` and SDK sessions never show it.

go deeper

for a junior

Recall that the dialog appears in interactive sessions in an untrusted folder, and that it gates repository config which grants permissions or runs commands.

for a middle

Explain the asymmetry: allow rules, additional directories, hooks and most env values wait, while deny and ask rules apply immediately. Know trust is keyed on the repository root.

for a senior

Treat acceptance as a review step: inspect .claude/settings.json, .mcp.json, skills and agents first, and know which sessions never show the dialog at all.

for a principal

Weigh how a team onboards clones: trust is per developer and per root, so a policy of reviewing committed Claude Code config belongs in code review, not in each person's click.

## What the dialog is Claude Code runs as **you**: its tools read and write your files and its shell commands run with your account's rights. A repository can ship configuration for Claude Code inside it, in `.claude/settings.json`, `.mcp.json`, `.claude/skills/` and `.claude/agents/`. Some of that configuration only shapes behaviour, but some of it **grants capability** (skipping permission prompts, widening file access) or **runs code** (hooks and helper commands are shell commands). The **workspace trust dialog** is the checkpoint between cloning a repository and letting that configuration act. When you start an **interactive** session in a folder you have not trusted, Claude Code shows the dialog first. It names the repository root the grant would cover and lists the allow rules and additional directories the folder's settings would add, so you can read them before you accept. The dialog is about **configuration**, not instructions. A CLAUDE.md or a README in the repository is context that shapes what Claude tends to do; settings, hooks, helper commands and server definitions change what Claude Code is able to do, and those are what the trust step gates. That is also why it matters for prompt injection: an allow rule committed by a repository removes the very prompt that would have stopped Claude acting on an instruction hidden in a file or a fetched page. ## What waits for trust | Repository content | Before you accept | After you accept | |---|---|---| | Hooks in settings files | Held back, including the hooks in your own `~/.claude/settings.json` | Run on their events | | `permissions.allow` and `permissions.additionalDirectories` in `.claude/settings.json` | Not applied; listed in the dialog | Applied | | Most `env` values in project settings | Not applied | Applied | | `enableAllProjectMcpServers` or `enabledMcpjsonServers` committed to `.claude/settings.json` | Ignored; the servers stay pending | Honored like any settings file | | `extraKnownMarketplaces` declared by the repository | Not offered | Applied | | `permissions.deny` and `permissions.ask` | **Apply immediately** | Apply | The asymmetry is deliberate: a rule that only restricts cannot hurt you, so Claude Code applies it at once; a rule that grants or a command that runs waits for your decision. Servers in `.mcp.json` also have their **own per-server approval prompt**, separate from the trust dialog. ## How trust is keyed and stored - **Inside a git repository**, trust is keyed on the **repository root** and covers the whole checkout, except a git repository nested inside it, such as a **submodule**, which gets its own dialog in an interactive session. - **In a worktree**, Claude Code uses the main checkout's root. - **Outside any repository**, trust is keyed on the directory you started in and covers its subdirectories, again except nested repositories such as a clone. - **In your home directory**, acceptance is held for the **current session only** and never written to disk, so the dialog returns on every launch; no setting persists it. Start from a project subdirectory instead. - The decision is stored in `~/.claude.json` as `projects["<path>"].hasTrustDialogAccepted`, where `<path>` is the repository root (or the folder itself outside a repository). Setting it to `true` by hand trusts a folder without the dialog. ## Where the dialog does not appear - **`claude -p` and SDK sessions never show it.** They treat the folder as trusted for some content and withhold other content, which is its own topic and a common source of surprise in automation. - **Moving a session with `/cd`** into an untrusted directory prompts for trust and lists the allow rules, additional directories, hooks and helper commands the new directory would activate. ## Using it well 1. Treat the dialog as a code review moment, not a click-through: open `.claude/settings.json`, `.mcp.json`, `.claude/skills/` and `.claude/agents/` before accepting. 2. Read the listed allow rules; a broad one such as `Bash(curl *)` deserves a question to whoever committed it. 3. Remember the dialog is a **gate on configuration**, not a sandbox: once accepted, hooks run with your full user rights and nothing in the dialog limits what they do. 4. Remember that before you decide, the state is not "nothing from the repository applies": its deny and ask rules are already in force.

  • Why does the trust dialog reappear every time you start Claude Code in your home directory?
    In the home directory Claude Code holds trust acceptance for the current session only and doesn't write it to disk, and there is no setting to persist it. Start Claude Code from a project subdirectory instead, where acceptance is saved per directory in `~/.claude.json`.
  • You trusted a monorepo's root. Does a git submodule inside it share that trust?
    No. Trust keyed on the repository root covers the checkout except a nested git repository such as a submodule, and an interactive session shows the trust dialog again for it. A worktree is different: it uses the main checkout's root, so it shares the trust.
  • Where is the trust decision stored, and can you set it without the dialog?
    In `~/.claude.json`, as `projects["<path>"].hasTrustDialogAccepted`, with `<path>` the repository root or, outside a repository, the folder itself. Setting it to `true` by hand trusts the folder; Claude Code prints the exact key in its warnings for content it skipped.

  • Trust only matters for MCP servers; hooks run as soon as you start Claude.
  • A cloned repository's deny rules also wait for the trust dialog.
  • Accepting the trust dialog sandboxes what the repository's hooks can do.
  • Trusting a repository once also covers every submodule nested inside it.
  • claude -p asks for workspace trust just like an interactive session.
open as a page

Where does an administrator place Claude Code's managed-settings.json on macOS, Linux and Windows, and how do you confirm a session enforces it?

level: middleimportance: must knowfreq 12%

basics

~10 s

In the system directory: /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, C:\Program Files\ClaudeCode\ on Windows. Then run /status and look for Enterprise managed settings (file) on the Setting sources line.

open as a page

Once you trust a cloned repository in Claude Code, which committed files can run commands or widen permissions on your machine?

level: middleimportance: must knowfreq 16%

basics

~20 s

Once trusted, a repository's .claude/settings.json hooks, env block, apiKeyHelper and permissions.allow rules take effect, its .mcp.json servers can connect, and its subagents' frontmatter hooks run. Project skills' allowed-tools grants never waited for trust at all.

open as a page

By default, what can a command inside Claude Code's Bash sandbox write, read and reach on the network?

level: middleimportance: must knowfreq 20%

basics

~10 s

Writes: the working directory, a per-user temp directory and added directories, minus protected config paths. Reads: most of the machine, credential files included. Network: only through a local proxy whose allowedDomains list starts empty.

open as a page

Claude Code's managed settings already deny some reads, yet developers still pre-approve tools and run their own hooks — which managed-only keys close that gap?

level: seniorimportance: must knowfreq 9%

basics

~10 s

Managed settings win conflicts, but lists such as permission rules and hooks still merge in from lower files. Locks close that: allowManagedPermissionRulesOnly, allowManagedHooksOnly, allowManagedMcpServersOnly and strictKnownMarketplaces make Claude Code honour only managed values.

open as a page

What does Claude Code's Bash sandbox leave uncovered, and when should the whole process run in a dev container or VM instead?

level: seniorimportance: must knowfreq 16%

basics

~20 s

The Bash sandbox wraps only shell commands. Read, Edit, WebFetch, hooks, local MCP servers and helper commands run outside it. For unattended runs or untrusted code, put the whole Claude Code process in the sandbox runtime, a container or a VM.

open as a page

Does Anthropic train on the code you send through Claude Code, and how long is that data kept, on its servers and on your machine?

level: juniorimportance: should knowfreq 14%

basics

~20 s

Training and retention follow the account type: commercial accounts (Team, Enterprise, API) aren't trained on and are kept 30 days; consumer accounts are trained on only with the improvement setting on (5-year retention, else 30 days). Local transcripts persist 30 days.

open as a page

Why can Claude Code's Bash sandbox let commands run without a prompt, and how do you turn it on on each platform?

level: juniorimportance: should knowfreq 22%

basics

~20 s

The operating system confines each command's files and network, so the boundary can stand in for a prompt. It is off by default: run /sandbox or set sandbox.enabled. macOS uses built-in Seatbelt; Linux and WSL2 need bubblewrap and socat.

open as a page

What does Claude Code do by default when a fetched web page, a file or an MCP result carries injected instructions?

level: middleimportance: should knowfreq 17%

basics

~20 s

Claude Code gates what injected text can lead to: WebFetch returns a separate model call's extraction, not the raw page; Manual mode prompts for curl, wget and unparseable commands; auto mode's classifier judges actions with tool results stripped.

open as a page

How do Claude Code's managed-mcp.json file and a managed allowedMcpServers allowlist differ in controlling which MCP servers developers can use?

level: seniorimportance: should knowfreq 7%

basics

~20 s

managed-mcp.json takes exclusive control: only its servers, plus organization-provided ones, load and users can't add others. A managed allowedMcpServers list, locked with allowManagedMcpServersOnly, is a catalog: users add their own servers and only matching ones load.

open as a page

With Zero Data Retention enabled for Claude Code on Claude for Enterprise, what is and isn't covered, and how do you keep developers' sessions inside it?

level: seniorimportance: should knowfreq 6%

basics

~20 s

ZDR covers Claude Code inference for one enabled Enterprise organization: prompts and responses aren't stored after the response. Claude.ai chat, Cowork, MCP servers and admin data aren't covered; pin logins to that organization with managed forceLoginMethod and forceLoginOrgUUID.

open as a page

Why is `claude -p` in a repository you didn't write riskier than an interactive Claude Code session, and how do you lock it down?

level: seniorimportance: should knowfreq 9%

basics

~20 s

claude -p never shows the trust dialog: it runs a repository's settings-file hooks, env block and apiKeyHelper, and connects its .mcp.json servers unasked. Lock it down with --bare and --setting-sources user, or pass disableAllHooks through --settings.

open as a page

In Claude Code's sandbox auto-allow mode, which Bash commands still prompt, and how does regular permissions mode differ?

level: seniorimportance: should knowfreq 11%

basics

~20 s

Auto-allow (autoAllowBashIfSandboxed, default true) runs sandboxed commands without a prompt, but deny rules, content-scoped ask rules, critical-path rm and anything running outside the sandbox still go through the normal flow. Regular mode prompts as usual inside the same boundary.

open as a page

When a build fails inside Claude Code's Bash sandbox, how do dangerouslyDisableSandbox, allowUnsandboxedCommands and excludedCommands differ?

level: seniorimportance: should knowfreq 9%

basics

~10 s

dangerouslyDisableSandbox is a Bash parameter Claude sets to retry a failed command unsandboxed. allowUnsandboxedCommands: false makes Claude Code ignore it. excludedCommands is a settings list of patterns that always run outside the sandbox.

open as a page

How would you require Claude Code's Bash sandbox across a mixed macOS, Linux and Windows fleet without stranding developers on blocked tools?

level: principalimportance: should knowfreq 5%

basics

~20 s

Deliver sandbox.enabled, failIfUnavailable and allowUnsandboxedCommands: false through managed settings, add domain and read locks, ship approved tool exclusions centrally, and deliver it per operating system, because native Windows cannot sandbox and would refuse to start.

open as a page

When a Claude Code subagent reads untrusted pages or files, what does the scan of its report do, and what doesn't it do?

level: seniorimportance: nice to knowfreq 5%

basics

~20 s

Claude Code scans each subagent's final report: it escapes text imitating its own output, such as a <system-reminder> tag, and marks instruction-shaped patterns. It never removes text or judges malice; permission checks and the sandbox decide actions.

open as a page

For a Claude Code fleet of MDM-managed laptops, unmanaged contractor machines and cloud sessions, how do you split policy between server-managed and endpoint-managed settings?

level: principalimportance: nice to knowfreq 3%

basics

~20 s

Enforce on managed laptops with endpoint-managed settings (MDM or the system file), use server-managed settings for cloud sessions and unmanaged machines, treat the latter as a client-side control, and remember Claude Code applies one managed source by default.

open as a page