Named environment masks for child processes

[in4mer]

Summary

Add the ability to define named environment variable masks that are overlaid on child process environments before exec. Masks are data (key-value maps), not shell scripts — no sourcing, no subshell expansion, no mutation of the Claude Code parent process. This applies to all child processes Claude Code spawns (Bash tool, MCP servers, hooks, any forked process), not just shell invocations.

Problem

Claude Code spawns child processes for tool calls, MCP servers, and hooks. Environment variables set in one child don't persist to the next. The existing CLAUDE_ENV_FILE mechanism (#15840, #27987) relies on file sourcing with shell evaluation semantics, which is fragile and currently broken.

Certain workflows require consistent environment setup across many child processes (JDK paths, timezone overrides, ulimits, registry URLs). Today, every invocation must redundantly inline these values, or wrap commands in subshells with dynamic evaluation like $(ulimit -Hn) — which triggers command approval prompts and adds noise.

Proposal

Define named masks

A mask is a named key-value map, defined once per session or persisted in config:

EnvMask("gradle", {
  "ULIMIT_HN": "1048576",
  "JAVA_HOME": "/usr/lib/jvm/java-17-openjdk-amd64",
  "TZ": "America/Los_Angeles"
})

EnvMask("node", {
  "NODE_OPTIONS": "--max-old-space-size=4096",
  "NPM_CONFIG_REGISTRY": "https://registry.internal/npm"
})

EnvMask("base", {
  "TZ": "America/Los_Angeles"
})

Apply by reference

Child processes specify which mask(s) to apply. The mask is overlaid on the inherited environment in the fork-before-exec path — before the child process starts. No tool interface changes are required; this happens at the process spawning layer inside Claude Code.

Ordered composition

Multiple masks can be applied as a named series with clear left-to-right precedence. Later masks override earlier ones on key collision:

env_mask: ["base", "gradle"]

This allows a common base (timezone, locale) to be shared without duplicating values in each mask. Specialized masks override only what they need to.

Persistence

Masks defined in session are ephemeral. Masks defined in config (e.g., settings.json or a dedicated masks file) persist across sessions and are available by identifier without re-declaration.

Implementation notes

• Masks are applied at the process spawning layer, after fork and before exec. The parent Claude Code process environment is never modified.
• Masks are pure data — no shell expansion, no eval, no sourcing. Values are literal strings.
• Because this operates at the fork/exec boundary, it applies uniformly to all child processes regardless of type (shell, MCP server, hook, etc.). No per-tool integration is needed.
• This replaces the need for CLAUDE_ENV_FILE sourcing and avoids the class of bugs around shell evaluation in env setup.

Related issues

• [FEATURE] Persistent shell context (CWD, env vars) across Bash tool calls #28228 — Persistent shell context across Bash tool calls (closed/stale)
• CLAUDE_ENV_FILE not provided to SessionStart hooks #15840 — CLAUDE_ENV_FILE not provided to SessionStart hooks (open, broken)
• CLAUDE_ENV_FILE written but not sourced for Bash tool calls on Windows #27987 — CLAUDE_ENV_FILE not sourced on Windows (open)
• [BUG] ~/.claude/settings.local.json env vars not applied to Bash tool subprocesses #35703 — settings.local.json env vars not applied to Bash subprocesses (open)
• [BUG] Bash Tool Silently Empties Environment Variables in Pipelines #29298, [BUG] Environment Variables Cleared When Using Pipe Operator in Bash Tool #8318 — Env vars silently emptied in pipelines (open)

[github-actions]

Found 3 possible duplicate issues:

1. Support persistent environment variables across Bash calls #13735
2. [FEATURE] Persistent shell context (CWD, env vars) across Bash tool calls #28228
3. [DOCS] Environment variables don't persist between bash commands - documentation inconsistency #2508

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[in4mer]

The three flagged issues are not duplicates of this request:

• Support persistent environment variables across Bash calls #13735 — closed via autoclose label, no resolution
• [FEATURE] Persistent shell context (CWD, env vars) across Bash tool calls #28228 — closed as stale, no resolution
• [DOCS] Environment variables don't persist between bash commands - documentation inconsistency #2508 — closed as a documentation issue about env var persistence between Bash calls

Those issues ask for persistent shell state (env vars surviving across Bash tool invocations). This issue requests named environment masks — a declarative mechanism for controlling which env vars are inherited by child processes, which is a different feature. The overlap is superficial (both mention "environment variables") but the problem space and proposed solution are distinct.

All three flagged issues are closed without resolution, so auto-closing this as a duplicate would just bury the request.