Feature Request: Granular Shell Environment Policy for Agent-Executed Commands

Title: Feature Request: Granular Shell Environment Policy for Agent-Executed Commands

Labels: feature-request, enhancement, security, configuration, bash-tool

Is your feature request related to a problem? Please describe.

Claude Code's powerful capabilities, such as the Bash tool, hooks, and local mcp servers, rely on executing shell commands. Currently, these commands inherit the user's full shell environment. This poses a significant security risk and reproducibility concern, as a developer's environment often contains sensitive credentials and configuration, such as:

• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• GITHUB_TOKEN, ANTHROPIC_API_KEY
• Other proprietary *_API_KEY or *_SECRET variables

Exposing the entire environment to the agent's execution context creates two primary problems:

1. Accidental Credential Leakage: The output of a command (e.g., from env or a debug script) could inadvertently expose these secrets. This sensitive data would then become part of the conversation context, potentially being logged or sent to third-party services.
2. Unintended Side Effects: The agent could unintentionally use these inherited credentials to perform actions on cloud services or other platforms, which is especially risky in fully agentic or automated workflows (--dangerously-skip-permissions).

While Claude Code has a robust permission system for which tools and commands can run, it lacks a mechanism to control the environment in which they run. The existing env setting in settings.json only allows for adding variables, not for restricting or sanitizing the inherited environment.

Describe the solution you'd like

We propose introducing a new configuration section in settings.json called shellEnvironmentPolicy. This would allow users and administrators to define a clear, enforceable policy for the environment variables passed to any shell process spawned by Claude Code. This feature should be respected across all settings levels (user, project, and especially enterprise-managed).

The policy should include the following controls, applied in order:

1. inheritance: A strategy for inheriting from the parent shell.

• all: (Default for backward compatibility) Inherit all environment variables.
• core: Inherit only a minimal set of essential, safe variables (e.g., PATH, HOME, USER, LANG, TMPDIR, SHELL).
• none: Start with a completely empty environment, requiring all variables to be explicitly defined.

1. exclude: An array of glob/wildcard patterns for variables to explicitly remove from the environment after inheritance. This acts as a denylist.

1. include: An array of variable names to explicitly keep. If this key is present, it acts as an allowlist, and only variables matching this list (plus those in set) will be passed to the subprocess.

1. set: A key-value map of variables to define or override for the agent's shell session. This ensures consistency, provides a way to pass safe, static values, and overrides any inherited values.

Example settings.json Configuration

This example demonstrates a secure and reproducible policy that could be enforced at an enterprise level via managed-settings.json.

{
  "shellEnvironmentPolicy": {
    // 1. Start with a minimal, safe set of core system variables.
    "inheritance": "core",

    // 2. As a safeguard, explicitly deny any variable that looks like a secret.
    "exclude": [
      "AWS_*",
      "*_TOKEN",
      "*_API_KEY",
      "*_SECRET"
    ],

    // 3. Explicitly allow-list specific, safe variables needed for the build process.
    "include": [
      "NPM_CONFIG_REGISTRY",
      "HTTP_PROXY",
      "HTTPS_PROXY",
      "NO_PROXY"
    ],

    // 4. Set static, agent-specific variables to ensure consistency.
    "set": {
      "CI": "false",
      "NODE_ENV": "development",
      "CLAUDE_CODE_CONTEXT": "true",
      "GIT_AUTHOR_NAME": "Claude Code Agent",
      "GIT_COMMITTER_NAME": "Claude Code Agent"
    }
  }
}

Describe alternatives you've considered

• Manual unset or Wrapper Scripts: A user could manually unset sensitive variables before launching claude or use a wrapper script to sanitize the environment. These approaches are cumbersome, error-prone, easy to forget, and cannot be enforced across a team.
• Using PreToolUse hooks: Hooks can inspect a command before it runs, but they cannot prevent the user's environment from being passed to the subprocess if the command is ultimately allowed.
• Devcontainers: The documentation mentions [devcontainers](/en/docs/claude-code/devcontainer) for isolation. While effective, this is a much heavier solution. A built-in environment policy is a more lightweight, universally applicable feature that complements containerization and provides essential security for all users, not just those using devcontainers.

Additional context

Implementing this feature would provide several critical benefits:

• Enhanced Security: Directly mitigates the risk of accidental credential leakage, providing a foundational security layer for agentic actions.
• Improved Reproducibility: Ensures that agent-executed commands run in a consistent, predictable environment, reducing "works on my machine" issues in automated workflows.
• Better Isolation: Creates a clear, configurable boundary between the user's host environment and the agent's execution environment.
• Enterprise-Ready Control: Gives administrators a powerful mechanism to enforce security policies across their organization using the managed-settings.json file, making Claude Code safer for enterprise adoption.