[DOCS] Bash and PowerShell tool docs omit timeout-triggered auto-backgrounding messages

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Bash tool behavior" section's timeout and background-task paragraphs, plus the corresponding "PowerShell tool" behavior reference.

Current Documentation

The Bash reference currently says:

Timeout: two minutes by default. Claude can request up to 10 minutes per command with the timeout parameter. Override the default and ceiling with BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS.

It then describes only explicit backgrounding:

For long-running processes such as dev servers or watch builds, Claude can set run_in_background: true to start the command as a background task and continue working while it runs. List and stop background tasks with /tasks.

The PowerShell section explains that PowerShell is a native shell tool and that its working-directory behavior matches Bash, but it does not describe timeout-triggered backgrounding or the resulting tool message.

What's Wrong or Missing?

Claude Code v2.1.210 changed the Bash/PowerShell tool message shown when a command reaches its timeout and is automatically moved to the background. The message now lets the model distinguish a command that timed out and was auto-backgrounded from a command that was explicitly requested with run_in_background.

The current reference documents the timeout limit and the explicit run_in_background: true path, but does not explain that a timed-out command can become a background task or how the tool result identifies that transition. A reader using the documented timeout controls cannot tell whether a command is still running after the timeout, whether it was intentionally backgrounded, or how that state differs from an explicit background request. The same omission affects users of the PowerShell tool.

Suggested Improvement

Add a short note to the Bash tool behavior section and cross-reference it from the PowerShell section that explains:

1. A command that reaches its timeout may be automatically moved to the background rather than being treated as an ordinary completed command failure.
2. The tool result explicitly identifies timeout-triggered auto-backgrounding, distinguishing it from an explicit run_in_background request.
3. The returned task can be monitored and stopped through the normal background-task workflow, including /tasks.
4. The same timeout and message semantics apply to Bash and PowerShell commands, subject to the shell's availability and configuration.

Please include the stable user/model-facing wording of the message if it is part of the supported tool contract, or describe the semantic distinction without promising an exact string if the wording may change.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference | "Bash tool behavior" documents timeout limits and explicit run_in_background, but not timeout-triggered auto-backgrounding or its message semantics |
| https://code.claude.com/docs/en/tools-reference#powershell-tool | PowerShell tool reference does not explain the corresponding timeout/background message behavior |
| https://code.claude.com/docs/en/env-vars | BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS are listed, but their relationship to timeout-triggered auto-backgrounding is not explained |

Total scope: 1 documentation page affected across Bash, PowerShell, and timeout configuration topics.

The behavior change was released in Claude Code v2.1.210.