How it works

Each tool call is one round trip between Claude and your application:

1. Claude returns a tool_use block containing the command to run.
2. Your application runs the command in its bash session.
3. Your application returns the command's output, stdout and stderr together, to Claude in a tool_result block.
4. Claude either requests another command in the same session or responds with text.

Claude 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.

The 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.