Repository navigation
[DOCS] CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 environment variable is missing from the docs #38559
Description
Documentation Type
other
Documentation Location
https://code.claude.com/docs/en/env-vars
Section/Topic
| Page | URL | Why affected |
|---|---|---|
| Environment variables | https://code.claude.com/docs/en/env-vars | Primary reference for all CLAUDE_CODE_* vars; CLAUDE_CODE_SUBPROCESS_ENV_SCRUB is absent from the table |
| Security | https://code.claude.com/docs/en/security | Documents built-in protections; credential scrubbing from subprocesses is a security control |
| Hooks | https://code.claude.com/docs/en/hooks | Hook commands run as subprocesses; users configuring hooks need to know this option exists |
| MCP | https://code.claude.com/docs/en/mcp | MCP stdio servers are explicitly called out as affected; no mention of the scrub flag |
Current Documentation
The environment variables reference page (env-vars) lists all supported CLAUDE_CODE_* variables in a table. CLAUDE_CODE_SUBPROCESS_ENV_SCRUB is not listed anywhere in the table or in any prose on that page. The security, hooks, and MCP pages likewise make no mention of this flag or the credential-stripping behavior it enables.
What's Wrong or Missing?
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB should be documented in the environment variables reference with a clear description of:
- What setting it to
1does (strips Anthropic API keys and cloud provider credentials from the environment inherited by subprocesses) - Which subprocess types are affected (Bash tool executions, hook commands, MCP stdio servers)
- Which credential families are scrubbed (Anthropic keys such as
ANTHROPIC_API_KEY, and cloud provider credentials such as AWS, GCP, and Azure env vars)
The security page should cross-reference this variable as part of the built-in protections for credential isolation in agentic contexts.
Suggested Improvement
- Open https://code.claude.com/docs/en/env-vars
- Search the page (Ctrl+F / Cmd+F) for
SUBPROCESS_ENV_SCRUB - Observe: no results
- Open https://code.claude.com/docs/en/security and repeat
- Observe: no results
Impact
Medium - Makes feature difficult to understand
Additional Context
- Type: Missing documentation
- Severity: High — a security-relevant feature added in v2.1.83 is entirely undiscoverable through the official docs
Activity
coygeek commentedon Apr 1, 2026
Issue #38559 Verification
Title: [DOCS]
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1environment variable is missing from the docsIssue Date: 2026-03-25
Verification Date: 2026-04-01
Status: PARTIALLY RESOLVED
Issue Summary
This issue reports that Claude Code's docs did not document the
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBenvironment variable in the environment-variables reference and did not cross-reference its subprocess credential-scrubbing behavior from the security, hooks, and MCP pages.Verification Results
Claim 1: The
env-varspage does not documentCLAUDE_CODE_SUBPROCESS_ENV_SCRUBStatus: RESOLVED
At https://code.claude.com/docs/en/env-vars, line 123: "
|CLAUDE_CODE_SUBPROCESS_ENV_SCRUB| Set to1to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). The parent Claude process keeps these credentials for API calls, but child processes cannot read them, reducing exposure to prompt injection attacks that attempt to exfiltrate secrets via shell expansion.claude-code-actionsets this automatically whenallowed_non_write_usersis configured".At https://code.claude.com/docs/en/changelog, line 182: "
* AddedCLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers)".Verdict: The environment-variables reference now documents the variable, what setting it to
1does, and which subprocess types it affects.Claim 2: The
securitypage does not cross-reference this credential-scrubbing protectionStatus: UNRESOLVED
At https://code.claude.com/docs/en/security, lines 23-30: "
### Built-in protections", "* **Sandboxed bash tool**: [Sandbox](https://code.claude.com/docs/en/sandboxing) bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with/sandboxto define boundaries where Claude Code can work autonomously", and the rest of the built-in protections list other security controls.At https://code.claude.com/docs/en/security, lines 42-44: "
* **Permission system**: Sensitive operations require explicit approval", "* **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request", and "* **Input sanitization**: Prevents command injection by processing user inputs".At https://code.claude.com/docs/en/security, line 66: "
* **Secure credential storage**: API keys and tokens are encrypted. See [Credential Management](https://code.claude.com/docs/en/authentication)".Verdict: The security page documents several built-in protections, but it still does not mention
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBor describe subprocess credential stripping as one of those protections.Claim 3: The
hookspage does not mention the flag for hook subprocessesStatus: UNRESOLVED
At https://code.claude.com/docs/en/hooks, lines 13-17: "
Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle." and "For command hooks, input arrives on stdin."At https://code.claude.com/docs/en/hooks, lines 267-270: "
* **[Command hooks](#command-hook-fields)** (type: "command"): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout."At https://code.claude.com/docs/en/hooks, line 344: "
Handlers run in the current directory with Claude Code's environment."Verdict: The hooks reference explains that command hooks are subprocesses and run with Claude Code's environment, but it still does not mention
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBor explain that this variable can strip sensitive credentials from those hook environments.Claim 4: The
mcppage does not mention the flag for MCP stdio serversStatus: UNRESOLVED
At https://code.claude.com/docs/en/mcp, lines 284-286: "
### Option 3: Add a local stdio server" and "Stdio servers run as local processes on your machine."At https://code.claude.com/docs/en/mcp, lines 293-305: "
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable" and "claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080→ runspython server.py --port 8080withKEY=valuein environment`".At https://code.claude.com/docs/en/mcp, lines 503-505: "
Claude Code supports environment variable expansion in.mcp.jsonfiles, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys."Verdict: The MCP page documents stdio servers as local subprocesses and discusses passing environment variables to them, but it still does not mention
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBor explain that stdio subprocesses are part of this credential-scrubbing feature.Current State
env-varspage does not documentCLAUDE_CODE_SUBPROCESS_ENV_SCRUBsecuritypage does not cross-reference this credential-scrubbing protectionhookspage does not mention the flag for hook subprocessesmcppage does not mention the flag for MCP stdio serversSuggested Fix
Keep the current
env-varsentry, and add short cross-references on the affected evergreen pages.security, addCLAUDE_CODE_SUBPROCESS_ENV_SCRUBto the built-in protections or prompt-injection section as an opt-in control that strips Anthropic and cloud-provider credentials from subprocess environments.hooks, note that command hooks run as subprocesses and thatCLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1prevents those hook processes from inheriting Anthropic and cloud-provider credentials.mcp, note in the stdio-server section that the same variable applies to MCP stdio subprocesses.References
URL: https://code.claude.com/docs/en/env-vars
Lines 123-123: The environment-variables reference now includes
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBand describes its behavior.URL: https://code.claude.com/docs/en/changelog
Lines 182-182: The changelog records that the feature applies to the Bash tool, hooks, and MCP stdio servers.
URL: https://code.claude.com/docs/en/security
Lines 23-30: The built-in protections list covers other security controls but not subprocess environment scrubbing.
URL: https://code.claude.com/docs/en/security
Lines 42-44: The prompt-injection protections list omits
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.URL: https://code.claude.com/docs/en/security
Lines 66-66: The page mentions secure credential storage, but not subprocess credential isolation.
URL: https://code.claude.com/docs/en/hooks
Lines 13-17: The page explains that hooks execute automatically and that command-hook input arrives on stdin.
URL: https://code.claude.com/docs/en/hooks
Lines 267-270: The reference states that command hooks run shell commands.
URL: https://code.claude.com/docs/en/hooks
Lines 344-344: The page says handlers run with Claude Code's environment.
URL: https://code.claude.com/docs/en/mcp
Lines 284-305: The stdio-server section describes local processes and passing environment variables.
URL: https://code.claude.com/docs/en/mcp
Lines 503-505: The
.mcp.jsonsection discusses environment-variable expansion for sensitive values like API keys.Conclusion & Recommendation
Primary Concern: Users still cannot find this subprocess credential-scrubbing protection from the related security, hooks, and MCP documentation pages.
Resolution Status: UNRESOLVED
Recommendation: KEEP OPEN
The main environment-variables reference now documents
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB, so the issue is no longer fully current. However, the cross-references requested for the security, hooks, and MCP pages are still missing, so the broader documentation gap remains open.coygeek commentedon Apr 28, 2026
Issue #38559 Verification
Title: [DOCS]
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1environment variable is missing from the docsIssue Date: (opened prior to verification)
Verification Date: 2026-04-27
Status: RESOLVED
Issue Summary
The reporter identified that
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB— a security-relevant environment variable introduced in v2.1.83 that strips Anthropic and cloud provider credentials from subprocess environments — was entirely absent from the official documentation pages (env-vars, security, hooks, MCP).Verification Results
Claim 1:
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBis missing from the env-vars pageenv-vars.mdline 140 with a full description: "Set to1to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). The parent Claude process keeps these credentials for API calls, but child processes cannot read them, reducing exposure to prompt injection attacks that attempt to exfiltrate secrets via shell expansion. On Linux, this also runs Bash subprocesses in an isolated PID namespace so they cannot read host process environments via/proc; as a side effect,ps,pgrep, andkillcannot see or signal host processes.claude-code-actionsets this automatically whenallowed_non_write_usersis configured"Claim 2: The security page should cross-reference this variable
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBby name. However, the env-vars page provides the authoritative reference with security context built into the description.Claim 3: The hooks and MCP pages should mention this option
Current State
claude-code-actionSuggested Fix
N/A — the primary documentation gap has been resolved. The env-vars page now contains a thorough entry for
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.References
Conclusion & Recommendation
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBis now fully documented in the env-vars reference page with comprehensive details covering behavior, affected subprocess types, platform-specific behavior (Linux PID namespace), and auto-configuration byclaude-code-action.github-actions commentedon Jun 19, 2026
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.