Bug Description

claude --permission-mode auto fails at CLI parse time with error: option '--permission-mode <mode>' argument 'auto' is invalid on certain CC builds, where the advertised choices list is acceptEdits, bypassPermissions, default, delegate, dontAsk, plan — note auto is removed and delegate is added vs. the npm distribution.

This is distinct from the existing batch of "auto mode silently downgraded" reports (#51879, #46616, #49653, #42648, #53694) which all describe the flag being accepted and then silently rejected based on plan/model. Here the flag is rejected by the argument parser itself before any session begins, so there is no graceful fallback, no UI message, no --help consistency between the user's build and the published documentation, and no way to detect at runtime which choices are actually valid without parsing claude --help.

Why this is a real problem (not just cosmetic)

Plugin authors and launcher scripts cannot write a single claude invocation that works across CC distributions:

• npm @anthropic-ai/[email protected] (next): advertises "acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan" — auto valid.
• Anthropic native installer (curl -fsSL https://claude.ai/install.sh | bash): advertises "acceptEdits", "bypassPermissions", "default", "delegate", "dontAsk", "plan" — auto invalid, delegate valid.

Same major version, same --permission-mode flag, different accepted enum. There's no documented compatibility matrix for which build supports which choices. Plugin / agent / framework authors are forced to introspect claude --help at runtime and fall back across an unspecified ordering.

Concrete install path that triggers this

The user followed the install instructions linked from Anthropic's docs and quoted by every plugin marketplace setup guide we know of (including ours):

curl -fsSL https://claude.ai/install.sh | bash

This is the native Claude Code installer. Our marketplace setup guide (SETUP.md prerequisites table) lists it as the recommended path on macOS and Windows because it's the one Anthropic recommends:

| Claude Code | curl -fsSL https://claude.ai/install.sh \| bash | irm https://claude.ai/install.ps1 \| iex |

So this isn't an obscure build — it's the canonical end-user install path, and it ships with a --permission-mode enum that's incompatible with the npm distribution most plugin authors test against. Plugin authors typically develop on the npm package (because that's what claude doctor, automated CI containers, and npm install -g deliver), then ship to users who installed via claude.ai/install.sh, and the divergence surfaces as a hard parse-time failure on first run.

Environment

• Affected build: Anthropic native CC, installed via curl -fsSL https://claude.ai/install.sh | bash on macOS. Exact version unknown — the user hit this on first run, before the launcher could capture claude --version. The advertised choices include delegate (per https://code.claude.com/docs/en/agent-teams#use-delegate-mode), suggesting either a plan-tier-gated build where auto was compiled out at the CLI surface, or a native channel that's drifted ahead/behind npm.
• Comparison build (works): @anthropic-ai/[email protected] from npm registry on macOS — auto is in the choice list.
• Affected workflow: Fulcrum plugin marketplace launcher script, which calls claude --permission-mode auto --model sonnet on first run to drive the persona-setup command non-interactively.

Steps to Reproduce

# 1. Install via the path Anthropic's docs recommend:
curl -fsSL https://claude.ai/install.sh | bash

# 2. Try to launch in auto mode (the canonical pattern for unattended CC):
$ claude --permission-mode auto
error: option '--permission-mode <mode>' argument 'auto' is invalid. Allowed choices are acceptEdits, bypassPermissions, default, delegate, dontAsk, plan.

$ claude --help | grep -A1 'permission-mode'
  --permission-mode <mode>   Permission mode to use for the session
                             (choices: "acceptEdits", "bypassPermissions",
                              "default", "delegate", "dontAsk", "plan")

# vs. on npm 2.1.121, same flag:
$ claude --permission-mode auto
# (session starts normally, auto mode active)

$ claude --help | grep -A1 'permission-mode'
  --permission-mode <mode>   Permission mode to use for the session
                             (choices: "acceptEdits", "auto", "bypassPermissions",
                              "default", "dontAsk", "plan")

Expected

One of:

1. Keep the CLI surface stable across distributions. If auto is unavailable for a user's plan/model/build, accept the flag at parse time and emit a clear runtime message (matches the silent-downgrade behavior tracked in the related issues), or
2. Publish a compatibility matrix — which --permission-mode values are valid for npm vs. native vs. plan-tier-gated builds, by version. Currently there's nothing in the docs to consult, so plugin authors have to hard-fail and patch reactively.
3. At minimum, alias auto to whatever the plan-permitted equivalent is on builds that drop it, even if the alias just resolves to acceptEdits or default. A CLI parse-time hard-fail with a misleading "invalid argument" message is the worst possible behavior because no static check or documentation lookup catches it.

Actual

Hard CLI parse-time rejection. Any script invoking claude --permission-mode auto fails before a session starts, with no way to recover programmatically except by parsing --help output and re-invoking. This breaks the canonical end-user install path (claude.ai/install.sh) for any plugin marketplace, agent framework, or automation that uses the auto mode pattern.

Workaround

We added runtime introspection: parse claude --help, discover which --permission-mode values are actually advertised, and pick the best available (auto first, then acceptEdits — we explicitly skip delegate because its documented semantics are agent-teams orchestration, not an auto-equivalent).

This works but feels wrong: every CC integration on the planet now has to do the same. The tracker has a half-dozen issues describing fragmentation symptoms (#14297, #51879, #46616, #49653, #42648, #53694) — none of them describe the underlying problem that the set of valid CLI choices is not stable across distributions of the same Claude Code version, and the divergence falls along the npm-vs-native split that ordinary users don't choose deliberately.

Related

• #14297 — delegate mode missing docs (open, comments confirm delegate is for agent-teams orchestration, not an auto replacement)
• #51879 — auto mode silently dropped on Sonnet 4.6 even when CLI flag passed
• #46616 — Max plan: "auto mode is not available for your plan"
• #49653 — auto-mode gating inconsistent across entry paths
• #42648 — auto unavailable on Haiku, no clear feedback (stale)
• #53694 — Desktop: auto-mode silently rejected on Sonnet 4.6, no UI feedback