Misleading warning: '--allowed-tools' CLI flag and shell env do not satisfy CLAUDE_CODE_SUBPROCESS_ENV_SCRUB auto-mode gate

Summary

When CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 is set in ~/.claude/settings.json, --permission-mode auto is silently downgraded to default with the following warning:

⚠ Permission mode forced to default — CLAUDE_CODE_SUBPROCESS_ENV_SCRUB is set (allowed_non_write_users hardening). Declare allowedTools explicitly, or set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0 to opt out.

Two of the warning's suggested remediations do not work as worded.

1. --allowed-tools CLI flag does NOT satisfy the gate

claude --permission-mode auto --allowed-tools "Bash Edit Read Write Grep Glob" --name test

Still produces the warning. Auto mode is still downgraded to default. The user has to declare allowedTools via settings.json (or via --settings '{"allowedTools":[...]}') to actually satisfy the gate — the equivalent CLI flag does not.

2. Shell-exported CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0 does NOT override settings.json

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0 claude --permission-mode auto --name test

Still produces the warning. The env value in ~/.claude/settings.json takes precedence over the shell-exported variable. The warning's second suggestion (set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0 to opt out) reads as "export it in your shell," which doesn't work.

What does work

Only the --settings JSON override succeeds in unlocking auto mode without editing settings.json directly:

claude --permission-mode auto --settings '{"env":{"CLAUDE_CODE_SUBPROCESS_ENV_SCRUB":"0"}}' --name test

Version

• claude --version: 2.1.145 (Claude Code)
• Platform: darwin-arm64
• Install: package manager (homebrew)

Relevant settings.json (minimal)

{
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  }
}

(No allowedTools set at the user / managed-settings level.)

Expected

Either:

• The warning text clarifies that "Declare allowedTools explicitly" means the settings.json key (not the --allowed-tools CLI flag), and that the env-var opt-out must be set in settings.json (not the shell)
• OR the CLI flag and shell-exported env actually satisfy the gate, matching the warning's wording

Actual

The warning suggests two remediations, neither works as the user would naturally read them. Users end up having to discover the --settings '{"env":{...}}' override path or edit settings.json directly.

Impact

For configs that set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 as a hardening measure, --permission-mode auto is effectively unreachable from the CLI. This is particularly relevant for users who set env-scrub deliberately and want per-invocation control over auto mode (e.g., testing, scripting, ephemeral sessions).