[FEATURE] Environment Variable Redaction for Hook Security

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code hooks execute with the user's full environment, including sensitive environment variables like API keys, tokens, and credentials. There's currently no built-in mechanism to prevent hooks from accidentally logging or exposing these secrets.

Risks include:

1. Accidental logging: A hook that logs its environment for debugging may expose secrets
2. Error messages: Stack traces or error output may include environment variable values
3. Third-party hooks: Plugins or shared hooks may not be security-conscious
4. Debug mode output: claude --debug may expose environment details
5. Transcript logging: Hook output recorded in transcripts could contain secrets

While Claude Code's security documentation mentions being careful with hooks, there's no automated protection.

Proposed Solution

Add an environmentVariableRedaction setting that automatically redacts sensitive environment variables from hook output.

Configuration

In settings.json:

{
  "environmentVariableRedaction": {
    "enabled": true,
    "patterns": [
      ".*_KEY$",
      ".*_TOKEN$",
      ".*_SECRET$",
      ".*_PASSWORD$",
      ".*_CREDENTIAL.*"
    ],
    "additionalVariables": [
      "AWS_ACCESS_KEY_ID",
      "AWS_SECRET_ACCESS_KEY",
      "ANTHROPIC_API_KEY",
      "GITHUB_TOKEN",
      "DATABASE_URL"
    ],
    "redactionString": "[REDACTED]"
  }
}

Behavior

When enabled:

1. Hook stdout/stderr filtering: Before displaying or logging hook output, scan for and redact values of sensitive environment variables
2. Error message filtering: Redact secrets from error messages and stack traces
3. Debug output filtering: Redact secrets from --debug output
4. Transcript filtering: Redact secrets before writing to transcript files

Default Patterns

Out of the box, redact variables matching common patterns:

| Pattern | Examples |
|---------|----------|
| .*_KEY$ | API_KEY, AWS_ACCESS_KEY_ID |
| .*_TOKEN$ | GITHUB_TOKEN, AUTH_TOKEN |
| .*_SECRET$ | CLIENT_SECRET, JWT_SECRET |
| .*_PASSWORD$ | DB_PASSWORD, ADMIN_PASSWORD |
| .*_CREDENTIAL.* | GCP_CREDENTIALS, AZURE_CREDENTIAL_FILE |

Redaction Method

1. Collect all environment variable names matching patterns
2. Get their values
3. In any output string, replace occurrences of those values with [REDACTED]
4. Handle partial matches and URL-encoded variants

Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| enabled | boolean | false | Enable redaction |
| patterns | string[] | (see above) | Regex patterns for variable names |
| additionalVariables | string[] | [] | Explicit variable names to redact |
| excludeVariables | string[] | [] | Variables to exclude from redaction |
| redactionString | string | [REDACTED] | Replacement text |
| logRedactions | boolean | false | Log when redaction occurs (for debugging) |

Alternative Solutions

1. Minimal environment: Run hooks with a stripped-down environment. This breaks many legitimate hooks that need environment context.

1. Sandboxed execution: Run hooks in containers or sandboxes. Significant complexity and performance overhead.

1. Manual filtering in hooks: Each hook implements its own redaction. Inconsistent and error-prone.

1. Documentation only: Warn users about the risk. Doesn't prevent accidents.

Priority

Medium - Would be very helpful

Important for security-conscious organizations but not blocking for basic usage.

Feature Category

Configuration and settings

Use Case Example

Scenario: Preventing accidental secret exposure

1. Developer creates a debugging hook that logs all input:

``bash
#!/bin/bash
echo "Hook input: $(cat)"
echo "Environment: $(env)" # Dangerous!
``

1. Without redaction, this exposes ANTHROPIC_API_KEY, GITHUB_TOKEN, etc.

1. With environmentVariableRedaction enabled:

``
Hook input: {"session_id": "abc123", ...}
Environment: ANTHROPIC_API_KEY=[REDACTED]
GITHUB_TOKEN=[REDACTED]
PATH=/usr/bin:/bin
...
``

1. Secrets are protected even from careless hook code

Scenario: Secure plugin ecosystem

1. Organization uses third-party Claude Code plugins
2. They can't audit every plugin's hook implementation
3. Enable environmentVariableRedaction organization-wide
4. Even if a plugin tries to exfiltrate secrets via stdout/stderr, values are redacted
5. Provides defense-in-depth against malicious or buggy plugins

Scenario: Compliance logging

1. Enterprise requires logging all Claude Code activity
2. Logs may be stored in systems with broader access
3. Environment variable redaction ensures secrets don't end up in logs
4. Audit trail is complete without exposing credentials

Scenario: Error investigation

1. Hook fails with an error
2. Error message happens to include a connection string: Connection failed: postgres://user:PASSWORD123@host/db
3. With redaction enabled: Connection failed: postgres://user:[REDACTED]@host/db
4. Safe to share error logs with support or teammates

Additional Context

Prior Art

Gemini CLI implements this feature:

"Environment redaction: Enable variable filtering to prevent accidental secret leakage: 'environmentVariableRedaction': {'enabled': true}"

Their best practices documentation explicitly recommends enabling this for security.

Implementation Considerations

• Performance: Redaction scanning should be efficient (compile patterns once, scan efficiently)
• False positives: Some variable values may appear in legitimate output. Consider minimum length thresholds.
• Binary data: Handle non-text output appropriately
• Encoding: Handle URL-encoded, base64-encoded, and other encoded variants of secrets
• Partial matches: If a secret is part of a larger string, still redact it
• Enterprise defaults: Consider making this enabled by default in enterprise/managed deployments