BashTool

• Entity ID: ent-20260410-9cb9a269b007
• Type: tool
• Scope: shared
• Status: active
• Aliases: bash tool, shell execution, command execution

Description

The shell command execution tool — the most complex and security-critical tool in Claude Code. Executes arbitrary bash commands with full system access, subject to a multi-layer security pipeline: permission rules, dangerous pattern detection (23 checks), read-only validation, path constraints, optional ML classification, and sandbox wrapping. Supports streaming output, background execution, auto-backgrounding, and platform-specific shell selection.

Implementation: src/tools/BashTool/ (12,429 lines across all files)

Execution pipeline

Input (command string)
  → validateInput (sleep pattern detection)
  → checkPermissions (compound command parsing, 23 security checks, path validation)
  → shouldUseSandbox (exclusion check)
  → findSuitableShell (bash/zsh detection)
  → buildExecCommand (snapshot + init chain + eval)
  → [if sandbox] wrapWithSandbox (bubblewrap/macOS sandbox)
  → spawn(shell, ['-c', command])
  → streaming output + progress reporting
  → output processing (truncation, image detection, exit code interpretation)
  → result

Security model

23 dangerous pattern checks (bashSecurity.ts)

Compound command parsing

Uses Tree-sitter for AST analysis. Splits &&, ||, ;, | into subcommands. Each subcommand validated independently against permission rules via preparePermissionMatcher. Extracts argv (strips leading VAR=val assignments).

Read-only validation (readOnlyValidation.ts)

Dynamic per-command evaluation determines isConcurrencySafe:

isConcurrencySafe(input) {
  return this.isReadOnly?.(input) ?? false
}

Allowlisted read-only commands with flag whitelisting: git log/show/diff/status, find, grep, rg, fd, cat, head, tail, jq, wc, stat, file, docker ps/inspect, gh (read-only subcommands). Dangerous flags are explicitly blocked (e.g., fd -x/--exec).

Sandbox integration

shouldUseSandbox() checks if sandboxing is enabled, then wraps the command via SandboxManager.wrapWithSandbox() (bubblewrap on Linux, macOS sandbox). Excluded commands configurable via GrowthBook dynamic config and user settings. Sandbox config includes: allowWrite (cwd, temp), denyWrite (settings files, .claude/skills, bare git repo files), network domain restrictions.

Shell selection

Priority: CLAUDE_CODE_SHELL env → $SHELL (if bash/zsh) → which bash/zsh → standard paths. On Windows, uses Git Bash with POSIX path conversion. Shell init chain: source snapshot → source session env (from hooks) → disable extended globs → eval command → capture cwd.

Output handling

• Streaming: stdout/stderr directed to a file fd. Progress extracted by polling file tail. Progress-driven yielding (not interval-based).
• Truncation: >30K chars inline → persist to disk (up to 64MB), model receives 5KB preview + filepath.
• Timeout: Default 30 minutes. In assistant mode, auto-backgrounds after 15s instead of killing.
• Exit code interpretation: Command-specific semantics (grep: 1=no matches, diff: 1=differences found).

Background execution

run_in_background: true spawns as LocalShellTask. Auto-backgrounding for long-running commands (npm, yarn, node, python, docker, cargo, webpack). Background tasks have a size watchdog (5s polling, kills if output exceeds limit).

Platform differences

What depends on it

• StreamingToolExecutor — BashTool's isConcurrencySafe drives the concurrency model
• Permission pipeline — BashTool is the most heavily permission-checked tool
• Hooks system — PreToolUse/PostToolUse hooks fire around every Bash execution
• Task system — background Bash commands become LocalShellTasks
• Agent lifecycle — agents execute Bash commands for code operations

Design trade-offs

Key claims

• Most complex tool: 12,429 lines across security, validation, execution, and platform handling
• 23 dangerous pattern checks provide defense-in-depth security
• Dynamic per-command read-only evaluation enables concurrent execution for safe commands
• Sandbox integration wraps commands in bubblewrap (Linux) or macOS sandbox
• Platform-specific handling for Windows (Git Bash, path conversion, null redirect rewriting)

Relations

• rel-bash-executor: StreamingToolExecutor --[evaluates]--> BashTool.isConcurrencySafe
• rel-bash-permissions: permission-pipeline --[validates]--> BashTool commands
• rel-bash-sandbox: BashTool --[wraps-via]--> SandboxManager
• rel-bash-tasks: BashTool --[creates]--> LocalShellTask (background)

Sources

Source code at src/tools/BashTool/, src/utils/Shell.ts, src/utils/sandbox/sandbox-adapter.ts