[DOCS] Bash tool docs omit the "argument list too long" limit and the v2.1.203 worktree-repo fix

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Bash tool behavior (the "Two limits bound each command" subsection in the Bash tool reference) on tools-reference.md, and the Clean up worktrees / Manage worktrees manually sections on worktrees.md.

Current Documentation

From tools-reference.md "Bash tool behavior":

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 as long as it stays inside the project directory or an additional working directory you added with --add-dir, /add-dir, or additionalDirectories in settings. Subagent sessions never carry over working directory changes. If cd lands outside those directories, Claude Code resets to the project directory and appends Shell cwd was reset to <dir> to the tool result. To disable this carry-over so every Bash command starts in the project directory, set CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1. Environment variables don't persist. An export in one command won't be available in the next. Aliases and shell functions defined in your shell startup file are available. At session start, Claude Code sources ~/.zshrc, ~/.bashrc, or ~/.profile depending on your shell, captures the resulting aliases, functions, and shell options, and applies them to every Bash command. Activate your virtualenv or conda environment before launching Claude Code. To make environment variables persist across Bash commands, set CLAUDE_ENV_FILE to a shell script before launching Claude Code, or use a SessionStart hook to populate it dynamically. Two limits bound each command: 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. * Output length: 30,000 characters by default. When a command produces more than that, Claude Code saves the full output to a file in the session directory and gives Claude the file path plus a short preview from the start. Claude reads or searches that file when it needs the rest. Raise the limit with BASH_MAX_OUTPUT_LENGTH, up to a hard ceiling of 150,000 characters.

The page never mentions the OS-enforced argument-list length limit (commonly E2BIG / ARG_MAX) that the shell or execve raises when the combined length of the command's arguments and environment exceeds the kernel's limit. That limit has a real impact on Bash tool calls in repositories with many git worktrees, because paths from git worktree list and similar enumerations can be passed as positional arguments to a single command.

From worktrees.md:

## Clean up worktrees When you exit a worktree session, cleanup depends on whether you made changes: No uncommitted changes, no untracked files, and no new commits: the worktree and its branch are removed automatically. If the session has a name, Claude prompts instead so you can keep the worktree for later Uncommitted changes, untracked files, or new commits exist: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding any uncommitted changes, untracked files, and commits * Non-interactive runs: worktrees created with --worktree alongside -p are not cleaned up automatically since there is no exit prompt. Remove them with git worktree remove Worktrees that Claude created for subagents and background sessions are removed automatically once they are older than your cleanupPeriodDays setting, provided they have no uncommitted changes, no untracked files, and no unpushed commits. Worktrees you create with --worktree are never removed by this sweep. While an agent is running, Claude runs git worktree lock on its worktree so that concurrent cleanup cannot remove it. The lock is released when the agent finishes. To clean up a worktree that the sweep keeps, run git worktree remove, adding --force if the worktree has uncommitted changes or untracked files.

The page never mentions that Bash tool calls constructed from many worktree paths could fail with the OS "argument list too long" error before v2.1.203, and never tells users that this scenario is fixed as of that release.

What's Wrong or Missing?

A. The Bash tool "Two limits" list omits the argument-list length limit

The Bash tool reference says "Two limits bound each command" and then lists only Timeout and Output length. The argument-list length limit is a third, OS-enforced limit that exists on every Unix shell invocation and that the Bash tool calls are not exempt from. When a Bash tool call expands into an execve whose combined argument and environment length exceeds the kernel's limit (typically a few hundred kilobytes on Linux and macOS), the call fails with E2BIG and the shell reports Argument list too long before the command runs. The current documentation gives no indication that this limit exists or that it can affect Bash tool calls.

B. The v2.1.203 fix is documented in the changelog but not reflected in the user-facing docs

The v2.1.203 changelog entry reads:

Fixed Bash failing with "argument list too long" in repos with many git worktrees

That confirms two things the user-facing docs should reflect:

1. The Bash tool call construction in worktree-heavy repositories could hit the OS argument-list length limit before v2.1.203.
2. After v2.1.203, that failure mode no longer occurs.

Neither the Bash tool behavior section nor the worktrees guide mentions this failure mode or the v2.1.203 fix. A user on v2.1.202 or earlier who hits this error has no documentation pointing at the changelog, and a user on v2.1.203 has no documentation explaining what the fix changes.

C. The worktrees guide makes no allowance for repos that accumulate many worktrees

worktrees.md describes the lifecycle of individual worktrees, automatic cleanup of orphaned worktrees, and how to use git worktree list / git worktree remove for manual management. It never warns that running many parallel sessions or accumulating many claude --worktree / EnterWorktree worktrees over time can produce Bash tool calls large enough to trigger the OS argument-list limit. The "Clean up worktrees" section even encourages manual enumeration with git worktree list — the exact command whose output, if forwarded to another shell call, is most likely to blow the limit.

Suggested Improvement

Bash tool behavior — add the third limit

In https://code.claude.com/docs/en/tools-reference "Bash tool behavior", replace:

Two limits bound each command: Timeout: two minutes by default. ... Output length: 30,000 characters by default. ...

with a "Three limits" version that adds an argument-list length bullet. For example:

Three limits bound each command: Timeout: two minutes by default. ... Output length: 30,000 characters by default. ... * Argument list length: the kernel-enforced limit on the total length of the command line and environment (typically ARG_MAX, around 256 KiB on Linux and 1 MiB-class on macOS). Bash tool calls constructed from very long lists — for example many paths from git worktree list — can fail with Argument list too long before v2.1.203 in repositories with many git worktrees. As of v2.1.203, Bash tool calls in those repositories no longer hit this limit; if you still see E2BIG on a Bash invocation, narrow the argument list or pass paths via stdin instead of as positional arguments.

worktrees.md — note the v2.1.203 fix in the cleanup section

In https://code.claude.com/docs/en/worktrees "Clean up worktrees", add a short paragraph after the existing git worktree list / git worktree remove advice. For example:

{/ min-version: 2.1.203 /}Repositories with many worktrees used to fail Bash tool calls that passed worktree paths as arguments with the OS Argument list too long error. That limit no longer triggers as of v2.1.203, so cleanup scripts that pipe the full git worktree list output into git worktree remove or xargs work reliably even in repos that have accumulated dozens of worktrees.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 124-127 | "Two limits bound each command" — missing the argument-list length bullet |
| https://code.claude.com/docs/en/worktrees | 89-99 | "Clean up worktrees" — no mention of v2.1.203 worktree-path Bash fix |

Total scope: 2 pages affected

Cross-reference: The v2.1.203 fix complements an earlier v2.1.202 fix in https://github.com/anthropics/claude-code/issues/73994 style issues where --resume itself slowed down in repositories with many worktrees; that fix is reflected in the v2.1.202 row of changelog.md (line 26). The v2.1.203 Bash entry is the parallel fix for the same family of "many worktrees" pathologies but for the Bash tool surface, and it is not yet reflected in the Bash tool reference.

Version: v2.1.203.