[DOCS] Bash tool documentation contradicts Claude Code settings on environment variable persistence

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/bash-tool - https://code.claude.com/en/settings

Section/Topic

• Bash tool page: "How it works" section - Claude Code settings page: "Bash tool behavior" section

Current Documentation

bash-tool page (How it works section):

The bash tool maintains a persistent session: ... 4. Session state persists between commands (environment variables, working directory)

Claude Code settings page (Bash tool behavior section):

* Environment variables do NOT persist: Environment variables set in one Bash command (for example, export MY_VAR=value) are not available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.

What's Wrong or Missing?

These two documentation pages directly contradict each other:

1. The Bash tool documentation claims environment variables persist between commands
2. The Claude Code settings documentation explicitly states they do NOT persist

This creates confusion for users who expect standard shell behavior based on the Bash tool docs, then find their environment variables disappear when using Claude Code.

The likely explanation is that the Bash tool docs describe the ideal API contract for implementing the tool, while Claude Code CLI has a specific implementation that does not persist environment variables (for isolation/security reasons).

Suggested Improvement

Update the Bash tool page to clarify that persistence behavior depends on the client implementation:

4. Session state may persist between commands depending on the client implementation. Working directory typically persists; environment variable persistence varies by client. Note for Claude Code CLI users: The Claude Code CLI does not persist environment variables between Bash commands. Each command runs in a fresh shell environment. See the Claude Code Settings documentation for workarounds.

Alternatively, add a callout box to the Bash tool page linking to client-specific documentation for actual behavior.

Impact

High - Prevents users from using a feature

Additional Context

• The Claude Code settings page includes workarounds (~/.zshrc, ~/.bashrc, or CLAUDE_ENV_FILE) that work for some cases
• Users implementing their own clients may expect different behavior than what Claude Code provides
• Mirror locations: platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md, code.claude.com/docs/en/settings.md