Feature request: opt out of the bundled CLI (slim install + force external `claude`)

[timqi]

Summary

Provide a supported way to not use the bundled CLI — both at install time (a packaging extra that skips shipping _bundled/) and at runtime (an env var / option that forces resolution to an external claude). Today the bundled binary is mandatory: it's baked into the wheel and it takes priority over a system claude, so users who already have a CLI on PATH pay for a copy they never run.

Motivation

1. Size. On SDK 0.2.123 the _bundled/ directory is ~253 MB — the single largest thing most installs pull in. For anyone who already manages claude separately (npm global, mise/asdf, distro package, container base image), that 253 MB is pure dead weight: downloaded on every pip install / uv tool upgrade, never executed. This is a regression in spirit from #349, which was closed by switching to a native binary — the "ink bloat" went away but the on-disk footprint went up.

2. Correctness / control. Several open issues stem specifically from the bundled binary, and an opt-out would give affected users a clean workaround:

• Bundled claude binary hangs when stdout is not a TTY (pipe / file / launchd / cron / Docker) #926 — bundled claude hangs when stdout isn't a TTY (pipe / cron / launchd / Docker)
• _bundled/claude v2.1.121 protocol-incompatible in container env (silent timeout on control_request:initialize) #922 — _bundled/claude protocol-incompatible in container env (silent initialize timeout)
• Bundled CLI silently drops inbound TRACEPARENT on 2nd+ query() call when ~/.claude/ has state from a prior run #952 / OTel log events from bundled CLI have empty trace_id/span_id (upstream: claude-code#63074) #1034 / Vertex/Bedrock: empty ThinkingBlock.thinking on Opus 4.8/4.7 — bundled CLI drops thinking.display (post-#831, root cause anthropics/claude-code#71599) #1068 — bundled CLI drops inbound TRACEPARENT / OTel trace_id / thinking blocks

Users who pin a known-good external CLI can't reliably do so today, because…

3. Surprising precedence. In _internal/transport/subprocess_cli.py, _find_cli() checks _find_bundled_cli() before shutil.which("claude"). So a system claude on PATH is silently shadowed by the bundled copy unless the caller passes ClaudeAgentOptions(cli_path=...) explicitly. "I installed my own claude on PATH" does not do what most users expect.

Proposed solution

Any one of these would solve it; ideally the first two together:

1. Packaging extra to skip the bundle. Publish the CLI as an optional component so pip install claude-agent-sdk (or an explicit claude-agent-sdk[no-cli] / a claude-agent-sdk[bundled] opt-in) can install without _bundled/. When absent, resolution simply falls through to PATH.
2. Runtime opt-out env var, e.g. CLAUDE_AGENT_SDK_NO_BUNDLE=1 (mirroring the existing CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK), that makes _find_cli() skip _find_bundled_cli() and go straight to PATH / known locations.
3. Optional precedence flip / documentation: let callers prefer a PATH claude over the bundled one (an env or option), and document the current order explicitly.

Workaround today

ClaudeAgentOptions(cli_path=...) bypasses the bundled binary at runtime, and deleting _bundled/ reclaims the 253 MB — but the delete is undone by the next pip install / uv tool upgrade, so there's no durable slim install.

Environment

• claude-agent-sdk 0.2.123 (Python), Linux x86_64
• _bundled/ measured at ~253 MB