claude-code - 💡(How to fix) Fix [DOCS] Bash timeout limit missing from tool and SDK references [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Bash tool behavior and the Bash input schema references in the SDK and hooks docs

Current Documentation

The current Bash tool reference says:

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

• When Claude runs cd in the main session, the new working directory carries over to later Bash commands...
• Environment variables do not persist. An export in one command will not be available in the next.

The env vars page separately says:

BASH_DEFAULT_TIMEOUT_MS | Default timeout for long-running bash commands (default: 120000, or 2 minutes)

BASH_MAX_TIMEOUT_MS | Maximum timeout the model can set for long-running bash commands (default: 600000, or 10 minutes)

The Python SDK Bash input documents the limit explicitly:

"timeout": int | None, # Optional timeout in milliseconds (max 600000)

But the TypeScript SDK Bash input omits that limit:

type BashInput = { command: string; timeout?: number; description?: string; run_in_background?: boolean; };

And the hooks docs omit it too:

| timeout | number | 120000 | Optional timeout in milliseconds |

What's Wrong or Missing?

Claude Code v2.1.110 changed Bash timeout handling so the tool now enforces the documented maximum timeout instead of accepting arbitrarily large values.

The problem is that this maximum is not documented in the places where users actually look up Bash tool inputs. The main Bash tool reference does not explain the timeout limit at all, and the TypeScript SDK and hooks Bash schemas show a timeout field without telling users that Bash timeouts are capped.

That leaves the limit documented only indirectly on the env vars page and in the Python SDK, which is easy to miss and creates inconsistent expectations across Claude Code interfaces.

Suggested Improvement

Add one canonical explanation of Bash timeout behavior to the Bash tool docs, then cross-reference it from the SDK and hooks pages.

Suggested minimum content:

• Document that Bash timeout values are in milliseconds.
• Document the default timeout (BASH_DEFAULT_TIMEOUT_MS, 120000 by default).
• Document the maximum timeout (BASH_MAX_TIMEOUT_MS, 600000 by default).
• Document what Claude Code does when a caller supplies a value above the maximum, since v2.1.110 now enforces that limit.

Then update the Bash input tables/snippets in the TypeScript SDK, hooks, and related input-schema docs so they mention the cap instead of showing an unconstrained timeout field.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 6 pages affected

Source: Changelog v2.1.110

Exact changelog entry:

Bash tool now enforces the documented maximum timeout instead of accepting arbitrarily large values