[BUG] The setting excludedCommands doesn't seem to be respected.

[klillywhite]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Summary

The sandbox.excludedCommands setting in .claude/settings.json is being ignored. Commands listed in this array are still being executed with sandboxing enabled, contrary to the documented behavior.

Expected Behavior

According to the settings documentation, excludedCommands should specify "Commands that should run outside of the sandbox." When a command is listed in this array, Claude Code should execute it outside the sandbox from the first attempt.

Actual Behavior

Commands listed in excludedCommands are still executed in the sandbox. Claude Code only attempts to run them outside the sandbox after the sandboxed execution fails and encounters errors indicating sandbox restrictions.

Steps to Reproduce

1. Create .claude/settings.json with the following configuration:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["uv"]
  }
}

2. Run a command that would trigger the excluded command:

> run uv sync

3. Observe that Claude Code first attempts to run uv sync inside the sandbox, which fails with:

error: failed to open file `~/.cache/uv/sdists-v9/.git`: Read-only file system (os error 30)

4. Claude Code then attempts to retry outside the sandbox

Configuration Used

Note: The settings file was copied directly from the official settings documentation to avoid any syntax errors or misspellings. The only modification made was replacing "docker" with "uv" in the excludedCommands array to demonstrate this issue.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["uv"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

Environment

• Claude Code version: v2.0.28
• Model: Sonnet 4.5 (Claude Max)
• Platform: Linux 6.12.48-1-MANJARO

Impact

This bug defeats the purpose of the excludedCommands setting. Tools like uv, docker, and watchman that are incompatible with sandboxing (as noted in the sandboxing documentation) will always fail on the first attempt, requiring:

• Extra retries and API calls
• User intervention to approve the unsandboxed execution
• Unnecessary error messages and friction in the workflow

What Should Happen?

According to the settings documentation, excludedCommands should specify "Commands that should run outside of the sandbox." When a command is listed in this array, Claude Code should execute it outside the sandbox from the first attempt.

Error Messages/Logs

Steps to Reproduce

1. Create .claude/settings.json with the following configuration:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["uv"]
  }
}

2. Run a command that would trigger the excluded command:

> run uv sync

3. Observe that Claude Code first attempts to run uv sync inside the sandbox, which fails with:

error: failed to open file `~/.cache/uv/sdists-v9/.git`: Read-only file system (os error 30)

4. Claude Code then attempts to retry outside the sandbox

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.0.28

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

No response

[herskinduk]

If this is not resolved, I fail to see how anyone will be able to use sandboxing.

[kfrance]

The problem appears to persist in v2.0.36.

[czottmann]

Same problem on macOS 26.1 w/ Claude Code 2.0.37.

[egalanos]

Still present in v2.0.50.

/sandbox shows the commands listed so it's not a configuration error.

A work around is instructing Claude to use the dangerouslyDisableSandbox: true parameter for the Bash tool for the commands in question.

[Ninja3047]

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["uv:*"]
  }
}

the documentation is incorrect, you must append :* otherwise it only does an exact match

[danielorbach]

Also something that helps (unrelated to uv), if all you need is access to some file paths: use the Edit permissions. Like so:

{
  "permissions": {
    "allow": [
      "Edit(/tmp)"
    ]
  }
}

In my case Claude chooses to use a heredoc for multiline commit messages, which requires access to /tmp. Paths with Edit permissions reflect in the output of /sandbox in the Filesystem Write Restrictions: Allowed: section.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.