bash-tool changedagents-and-tools/tool-use/bash-tool
Nearest release: v2.1.307, published an hour after 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+14added
Lines−14removed
From line
17
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits10to this page, all time
The whole hunk
from line 17, old and new numbered
/
from line 17
1717## Use cases
1818
1919* **Development workflows:** Run build commands, tests, and development tools
20* **System automation:** Execute scripts, manage files, automate tasks
20* **System automation:** Run scripts, manage files, automate tasks
2121* **Data processing:** Process files, run analysis scripts, manage datasets
2222* **Environment setup:** Install packages, configure environments
2323
from line 216
216216
217217Claude 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).
218218
219The API is stateless. Nothing about your shell session travels between requests, so your application decides when the session starts, how long it lives, and when to restart it. For the full request and response cycle, see [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
219The API is stateless. Nothing about your shell session travels between requests, so your application determines when the session starts, how long it lives, and when to restart it. For the full request and response cycle, see [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
220220
221221## Parameters
222222
from line 679
679679 ```
680680 </CodeGroup>
681681
682 The session interleaves stderr with stdout, so error messages land where they happened. 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.
682 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.
683683 </Step>
684684
685685 <Step title="Process Claude's tool calls">
from line 828
828828 </Step>
829829
830830 <Step title="Return the result to Claude">
831 Send the `tool_result` back in a `user` message that continues the same conversation. Claude either requests another command in the same session or finishes its answer:
831 Send the `tool_result` back in a `user` message that continues the same conversation. Claude either requests another command in the same session or completes its answer:
832832
833833 <CodeGroup>
834834 ```bash cURL
from line 1432
14321432
14331433### Handle errors
14341434
1435When a command fails or the session breaks, tell Claude what happened. Return the message as the `tool_result` content and set `is_error` to `true`, which marks the tool call as failed. See [Handling errors with is\_error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-errors-with-is-error).
1435When a command fails or the session breaks, tell Claude what occurred. Return the message as the `tool_result` content and set `is_error` to `true`, which marks the tool call as failed. See [Handling errors with is\_error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-errors-with-is-error).
14361436
14371437<AccordionGroup>
14381438 <Accordion title="Command execution timeout">
1439 If a command takes too long to execute:
1439 If a command takes too long to run:
14401440
14411441 ```json
14421442 {
from line 1494
14941494
14951495<AccordionGroup>
14961496 <Accordion title="Use command timeouts">
1497 A command that never finishes, such as one that waits for input, blocks the session forever because its sentinel line never arrives. Give every command a deadline. When the deadline passes, stop the shell and everything the command started, then restart the session:
1497 A command that never completes, such as one that waits for input, blocks the session forever because its sentinel line never arrives. Give every command a deadline. When the deadline passes, stop the shell and everything the command started, then restart the session:
14981498
14991499 <CodeGroup exclude="shell">
15001500 ```python Python
from line 1803
18031803 </Accordion>
18041804
18051805 <Accordion title="Log all commands">
1806 Keep an audit trail. Route every command through one wrapper that records the command before it runs and the output after it finishes. A command that hangs or breaks the session still leaves a record:
1806 Keep an audit trail. Route every command through one wrapper that records the command before it runs and the output after it completes. A command that hangs or breaks the session still leaves a record:
18071807
18081808 <CodeGroup exclude="shell">
18091809 ```python Python
from line 1929
19291929
19301930* Running tests: `pytest && coverage report`
19311931* Building projects: `npm install && npm run build`
1932* Git operations: `git status && git add . && git commit -m "message"`
1932* Running Git operations: `git status && git add . && git commit -m "message"`
19331933
1934For guidance on using git as a checkpoint-and-recovery mechanism in long-running agent workflows, see [state management best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#state-management-best-practices).
1934For guidance on using Git as a checkpoint-and-recovery mechanism in long-running agent workflows, see [state management best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#state-management-best-practices).
19351935
19361936### File operations
19371937
from line 1942
19421942### System tasks
19431943
19441944* Checking resources: `df -h && free -m`
1945* Process management: `ps aux | grep python`
1946* Environment setup: `export PATH=$PATH:/new/path && echo $PATH`
1945* Managing processes: `ps aux | grep python`
1946* Setting up the environment: `export PATH=$PATH:/new/path && echo $PATH`
19471947
19481948## Limitations
19491949
from line 1969
19691969 </Card>
19701970
19711971 <Card title="Tool use with Claude" icon="tool" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview">
1972 Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
1972 Connect Claude to external tools and APIs. See where tools run, when Claude calls them, and which tool fits your task.
19731973 </Card>
19741974</CardGroup>
19751975
No line in this hunk matches that.