bash-tool changedagents-and-tools/tool-use/bash-tool
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+11added
Lines−11removed
From line
8
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 8, old and new numbered
/
from line 8
88 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
99</Note>
1010
11The bash tool is a [client tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works): Claude doesn't run commands itself. When you include the tool in a request, Claude replies with a `tool_use` block that names the command to run. Your application runs that command in a bash session it owns and returns the output in a `tool_result` block.
11The bash tool is a [client tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works): Claude doesn’t run commands itself. When you include the tool in a request, Claude replies with a `tool_use` block that names the command to run. Your application runs that command in a bash session it owns and returns the output in a `tool_result` block.
1212
1313Your application keeps one bash process alive across tool calls, so state persists between commands. The working directory, environment variables, and any files a command creates are still there for the next command.
1414
from line 212
212212
2132131. Claude returns a `tool_use` block containing the `command` to run.
2142142. Your application runs the command in its bash session.
2153. Your application returns the command's output, stdout and stderr together, to Claude in a `tool_result` block.
2153. Your application returns the command’s output, stdout and stderr together, to Claude in a `tool_result` block.
2162164. Claude either requests another command in the same session or responds with text.
217217
218218Claude can also return several `tool_use` blocks in one response. Run them in order in the same session and return all of the results in one `user` message. See [Parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use).
from line 221
221221
222222## Parameters
223223
224A bash tool definition has two required fields, `type` and `name`, and the `name` must be `bash`. The tool is schema-less: you don't provide an `input_schema`, because the schema is built into Claude's model and can't be modified. The following table lists the input fields Claude sets when it calls the tool.
224A bash tool definition has two required fields, `type` and `name`, and the `name` must be `bash`. The tool is schema-less: you don’t provide an `input_schema`, because the schema is built into Claude’s model and can’t be modified. The following table lists the input fields Claude sets when it calls the tool.
225225
226226| Parameter | Required | Description |
227227| --------- | -------- | ----------------------------------------- |
from line 284
284284
285285<Steps>
286286 <Step title="Create a persistent bash session">
287 Start one long-lived bash process and run every command inside it. Because a pipe to a live process never reports end-of-file, the session prints a unique sentinel line after each command to mark where that command's output ends:
287 Start one long-lived bash process and run every command inside it. Because a pipe to a live process never reports end-of-file, the session prints a unique sentinel line after each command to mark where that command’s output ends:
288288
289289 <CodeGroup exclude="shell">
290290 ```python Python
from line 683
683683 The session interleaves stderr with stdout, so error messages land where they occurred. The example leaves out what a complete implementation also needs: a timeout that kills the shell and every process it started when a command hangs, then restarts the session. The [Use command timeouts](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool#follow-implementation-best-practices) best practice shows one way to add it.
684684 </Step>
685685
686 <Step title="Process Claude's tool calls">
687 Extract and run commands from Claude's responses:
686 <Step title="Process Claude’s tool calls">
687 Extract and run commands from Claude’s responses:
688688
689689 <CodeGroup exclude="shell">
690690 ```python Python
from line 1186
11861186 </Step>
11871187
11881188 <Step title="Implement safety measures">
1189 Add validation and restrictions. Use an allowlist rather than a blocklist: a blocklist misses any command it didn't anticipate. The example also rejects shell operators that appear as separate words:
1189 Add validation and restrictions. Use an allowlist rather than a blocklist: a blocklist misses any command it didn’t anticipate. The example also rejects shell operators that appear as separate words:
11901190
11911191 <CodeGroup exclude="shell">
11921192 ```python Python
from line 1456
14561456 </Accordion>
14571457
14581458 <Accordion title="Command not found">
1459 If a command doesn't exist:
1459 If a command doesn’t exist:
14601460
14611461 ```json
14621462 {
from line 1949
19491949
19501950## Limitations
19511951
1952* **No interactive commands:** The session can't run `vim`, `less`, password prompts, or any command that waits for input on stdin.
1952* **No interactive commands:** The session can’t run `vim`, `less`, password prompts, or any command that waits for input on stdin.
19531953* **No GUI applications:** The session is command-line only.
19541954* **Session scope:** Bash session state is client-side. Your application is responsible for maintaining the shell session between turns.
1955* **Output limits:** The API doesn't truncate tool results (an oversized request is rejected). Truncate large outputs in your application before returning them to Claude.
1955* **Output limits:** The API doesn’t truncate tool results (an oversized request is rejected). Truncate large outputs in your application before returning them to Claude.
19561956* **No streaming:** Output reaches Claude only when your application returns the `tool_result` in the next request.
19571957
19581958## Combining with other tools
from line 1960
19601960The bash tool pairs well with the [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool): Claude edits a file with one tool and requests the command that runs it with the other.
19611961
19621962<Note>
1963 If you're also using the [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool), Claude has access to two separate execution environments: your local bash session and Anthropic's sandboxed container. State is not shared between them. See [Using code execution with other execution tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#using-code-execution-with-other-execution-tools) for guidance on prompting Claude to distinguish between environments.
1963 If you’re also using the [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool), Claude has access to two separate execution environments: your local bash session and Anthropic’s sandboxed container. State is not shared between them. See [Using code execution with other execution tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#using-code-execution-with-other-execution-tools) for guidance on prompting Claude to distinguish between environments.
19641964</Note>
19651965
19661966## Next steps
No line in this hunk matches that.