Bash tool (bash_20250124)
Status: DOCUMENTED · LIVE_VERIFIED 2026-09-18 (h7 on haiku 4.5 → tool_use{name:"bash", input:{"command":"echo OK"}}; j4 count_tokens 751). Nothing was executed.
Sources: Bash tool · Tool reference · Release notes 2025-02-24.
Last verified: 2026-09-18.
Definition and versions
{"type": "bash_20250124", "name": "bash"}Schema-less client tool; name must be bash. Generic properties allowed: cache_control, defer_loading, strict, input_examples, allowed_callers.
| Version | Header | Models |
|---|---|---|
bash_20250124 |
none | every model since Claude Sonnet 3.7, incl. all current models (live haiku 4.5) |
bash_20241022 |
computer-use-2024-10-22 |
Claude Sonnet 3.5 (Oct 2024) only — retired; SDK beta namespace only |
Input Claude sends
| Field | Required | Meaning |
|---|---|---|
command |
yes unless restart |
the bash command to run |
restart |
no | true → kill and restart the session (state lost); answer with a confirmation |
Your application owns a persistent bash process (cwd, env vars, files persist across calls), runs command, returns stdout+stderr as the tool_result content, is_error:true on failure/timeout. Several tool_use blocks in one turn → run in order in the same session, return all results in one user message. The API does not truncate tool results (oversized request rejected) — truncate yourself.
Limits and security
No interactive commands (vim, less, prompts), no GUI, no output streaming. Run in an isolated container/VM as least-privileged user, allowlist commands (a tokenizer-based allowlist is a tripwire, not a boundary), ulimit, audit log, redact secrets. When the server-side code execution tool is also present, tell Claude the two environments do not share state.
Pricing
Definition adds ≈325 input tokens (Opus 5 / 4.8 / 4.7) or ≈244 (Opus 4.6, Sonnet 4.6 and earlier) on top of the tool-use system prompt. Live count_tokens haiku 4.5: 751 tokens for a one-line prompt + bash tool (11 without tools).
Examples: examples/anthropic/tools/bash/basic.{sh,py,ts}; test test_anthropic_schema_client_tools_emit_tool_use[bash].