[DOCS] CLAUDE_CODE_SUBPROCESS_ENV_SCRUB requires bubblewrap on Linux and exits at startup without it, but the docs don't say so

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

Current Documentation

The env-vars entry says:

Set to 1 to strip credentials from subprocess environments (Bash tool, hooks, MCP stdio servers) [...] On Linux, this also runs Bash subprocesses in an isolated PID namespace so they cannot read host process environments via /proc [...]

Separately, the sandboxing page says that "a Linux session with CLAUDE_CODE_SUBPROCESS_ENV_SCRUB set" runs every command sandboxed, and lists bubblewrap as a Linux sandbox dependency.

What's Wrong or Missing?

Neither page says that on Linux the variable requires bubblewrap, and Claude Code refuses to start without it. With CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 and no bwrap on the machine, claude -p exits 1 at startup, before any API call:

Error: bubblewrap is required for subprocess env scrubbing and isolation. Install with: sudo apt-get install -y bubblewrap, set sandbox.bwrapPath in managed settings, or set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0 to disable (loses subprocess isolation).

Reproduced on 2.1.263 in a clean node:22-bookworm container. The same flags without the variable start normally.

This is easy to miss in CI:

• macOS doesn't need bubblewrap, so a script tested locally on a Mac passes and then fails on a Linux runner. GitHub-hosted ubuntu-latest runners don't ship bubblewrap.
• With --output-format json or stream-json, nothing is written to stdout. The message goes to stderr and no result event is emitted, so a wrapper that parses the result sees an empty run rather than a clear error. Ours reported it as an API auth failure.
• The docs present the variable as a hardening switch to "set to 1", with no sign that it adds a hard system dependency on Linux.

Suggested Improvement

In the CLAUDE_CODE_SUBPROCESS_ENV_SCRUB row on the env-vars page, add something like:

On Linux, this requires [bubblewrap](/docs/en/sandboxing#prerequisites); Claude Code exits at startup if it isn't installed. On Ubuntu 24.04 and later, bubblewrap also needs the AppArmor profile described in [Sandboxing](/docs/en/sandboxing). To run without it, set the variable to 0, which loses subprocess isolation.

A line in the sandboxing page's Linux prerequisites saying that this variable implies the sandbox dependencies would help too. So would a note in the CI and GitHub Actions docs.

Impact

High - Prevents users from using a feature

Additional Context

Found while hardening an unattended claude -p job on GitHub Actions (Bedrock mode, pinned 2.1.263). Every local test on macOS passed; the first Linux runner failed 0.2s after start.