[DOCS] Missing documentation on Bash tool output limits (30k characters) and truncation behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/settings#bash-tool-behavior

Section/Topic

Settings > Tools available to Claude > Bash tool behavior

Current Documentation

Currently, the Bash tool behavior section focuses entirely on directory and environment variable persistence:

Bash tool behavior The Bash tool executes shell commands with the following persistence behavior: Working directory persists: When Claude changes the working directory... Environment variables do NOT persist: Environment variables set in one Bash command...

The only reference to output limits is buried in the Environment variables reference table under the key BASH_MAX_OUTPUT_LENGTH.

What's Wrong or Missing?

The documentation fails to explicitly state that the Bash tool has a hard limit of 30,000 characters for command outputs. It also fails to explain how that data is handled (middle-truncation) when the limit is exceeded.

This information is critical for developers running commands with verbose outputs (like npm test, cat logfile, or build processes). Without this information in the primary tool documentation:

1. Users do not know why Claude might be "hallucinating" or missing parts of a log file.
2. Users do not know that the middle of the log is removed (head + tail retention) rather than a simple cutoff.
3. Users do not know they can adjust this specific behavior via BASH_MAX_OUTPUT_LENGTH.

Suggested Improvement

Please add a subsection to Bash tool behavior that explicitly defines the output constraints.

Suggested text:

Output Limits and Truncation By default, the Bash tool captures a maximum of 30,000 characters of output. If a command produces more output than this limit, Claude Code applies middle-truncation—preserving the beginning and end of the output while removing the middle. If you need to process larger logs or outputs, you can increase this limit by setting the BASH_MAX_OUTPUT_LENGTH environment variable (e.g., export BASH_MAX_OUTPUT_LENGTH=100000).

Impact

High - Prevents users from using a feature

Additional Context

This behavior is confirmed by the BASH_MAX_OUTPUT_LENGTH description in the environment variables table:

"Maximum number of characters in bash outputs before they are middle-truncated"

However, because this variable is listed alphabetically in a massive table at the bottom of the Settings page, it is not discoverable for users reading the actual Bash tool documentation.