[DOCS] CLAUDE_CODE_SHELL_PREFIX documentation should clarify interaction with permission rules

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

Environment variables table, specifically the CLAUDE_CODE_SHELL_PREFIX row

Current Documentation

CLAUDE_CODE_SHELL_PREFIX: Command prefix to wrap all bash commands (for example, for logging or auditing). Example: /path/to/logger.sh will execute /path/to/logger.sh <command>

What's Wrong or Missing?

The documentation doesn't clarify how CLAUDE_CODE_SHELL_PREFIX interacts with the permission system. Specifically:

1. Permission matching ambiguity: When a user configures a permission rule like Bash(git commit:*), does Claude Code match against:

• The original command (git commit -m "message"), or
• The wrapped command (/path/to/logger.sh git commit -m "message")?

1. Permission prompt display: What command does the user see in permission prompts—the original command or the prefixed version?

This matters because users setting up logging/auditing wrappers need to know whether their existing permission rules will continue to work, or if they need to reconfigure them to match the prefixed command.

Suggested Improvement

Add a sentence clarifying the permission behavior. For example:

CLAUDE_CODE_SHELL_PREFIX: Command prefix to wrap all bash commands (for example, for logging or auditing). Example: /path/to/logger.sh will execute /path/to/logger.sh <command>. Permission rules are evaluated against the original command, not the prefixed version.

(Adjust wording based on actual behavior if permissions evaluate against the wrapped command instead.)

Impact

High - Prevents users from using a feature

Additional Context

• Mirror location: code.claude.com/docs/en/settings.md
• Related: The permission rule syntax documentation and IAM documentation describe command matching in detail, but neither mentions how CLAUDE_CODE_SHELL_PREFIX affects matching
• Use case: Enterprise users setting up centralized command logging/auditing may configure this prefix alongside strict permission policies