claude-code - 💡(How to fix) Fix [DOCS] Bash tool docs omit `$TMPDIR` consistency across sandboxed and unsandboxed commands

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Bash tool behavior, especially temporary directory behavior when sandboxing is enabled and a session runs both sandboxed and unsandboxed Bash commands.

Current Documentation

The Bash tool reference currently says:

The Bash tool runs each command in a separate process with the following persistence behavior:

It also says:

Environment variables do not persist. An export in one command will not be available in the next.

The sandboxing guide explains that sandboxed commands may fall back to unsandboxed execution:

Some commands cannot run inside the sandbox at all, such as tools that are incompatible with it or that need a host you have not allowed. Rather than failing the task or requiring you to turn sandboxing off, Claude Code includes an escape hatch: when a command fails because of sandbox restrictions, Claude analyzes the failure and may retry the command with the dangerouslyDisableSandbox parameter. The retried command runs outside the sandbox, so it goes through the regular permission flow and requires your approval.

The environment variables reference documents only Claude Code's internal temp directory override:

CLAUDE_CODE_TMPDIR | Override the temp directory used for internal temp files. Claude Code appends /claude-{uid}/ (Unix) or /claude/ (Windows) to this path. Default: /tmp on macOS, os.tmpdir() on Linux/Windows

What's Wrong or Missing?

Claude Code v2.1.154 fixed $TMPDIR resolving to different directories in sandboxed vs unsandboxed Bash commands within the same session.

That user-visible behavior is not documented in the Bash or sandboxing references:

A. $TMPDIR consistency is not documented for mixed sandbox modes

The sandboxing docs explain that a session can run some Bash commands inside the sandbox and retry or exclude others outside it, but they do not say whether $TMPDIR should resolve to the same directory across those execution modes.

B. The Bash persistence section does not cover session temp-directory expectations

The Bash tool docs explain working-directory carry-over, environment-variable non-persistence, shell snapshots, timeouts, and output storage. They do not explain what temp directory Bash commands receive, or whether users can rely on a stable $TMPDIR across commands in the same Claude Code session.

C. CLAUDE_CODE_TMPDIR is easy to confuse with Bash $TMPDIR

The env-vars page documents CLAUDE_CODE_TMPDIR as an internal Claude Code temp-file override. It does not clarify how that setting relates to the $TMPDIR environment variable visible to Bash commands, including sandboxed Bash subprocesses.

Without that clarification, users writing scripts that pass temp-file paths between Bash commands cannot tell whether a sandbox fallback, excludedCommands, or dangerouslyDisableSandbox retry should preserve the same $TMPDIR location.

Suggested Improvement

Add a short note to Bash tool behavior, and cross-reference it from the sandboxing guide where fallback to unsandboxed execution is described.

Suggested wording:

Bash commands in the same Claude Code session receive a consistent $TMPDIR, even when sandboxing is enabled and the session runs a mix of sandboxed and unsandboxed Bash commands. This lets scripts safely create temporary files in one Bash command and reference them from a later command in the same session, subject to normal filesystem permissions and sandbox write boundaries.

Also expand the CLAUDE_CODE_TMPDIR entry to clarify whether it sets or influences the $TMPDIR value exposed to Bash commands, or whether it is only for Claude Code's internal temp files.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: Claude Code v2.1.154 fixed $TMPDIR resolving to different directories in sandboxed vs unsandboxed Bash commands within the same session.