tools/BashTool/ — Shell Command Execution Tool

Contents

Architecture

flowchart TD
  A["AgentLoop / Model"] -->|"tool_use: Bash"| B["BashTool.call()"]
  B --> C{"validateInput()"}
  C -->|"invalid"| D["Return error + errorCode"]
  C -->|"valid"| E{"checkPermissions()"}
  E -->|"deny"| F["Permission denied"]
  E -->|"ask"| G["User confirmation dialog"]
  E -->|"allow"| H["runShellCommand()"]
  G -->|"approved"| H
  H --> I["Streaming output via async generator"]
  I --> J{"Timeout / background?"}
  J -->|"background"| K["Register background task"]
  J -->|"complete"| L["interpretCommandResult()"]
  L --> M["Format + return stdout/stderr"]

Security Validation Stack

flowchart LR
  CMD["Command string"] --> MV["modeValidation"]
  MV --> PV["pathValidation"]
  PV --> SV["sedValidation"]
  SV --> RO["readOnlyValidation"]
  RO --> CS["commandSemantics"]
  CS --> OP["operatorPermissions"]
  OP --> SB{"shouldUseSandbox?"}
  SB -->|"yes"| SX["Sandbox execution"]
  SB -->|"no"| DX["Direct execution"]

Key Classes & Functions

Data Structures

Interactions

Permission Resolution Flow

The permission system uses a fail-closed strategy where commands must be explicitly allowed. The resolution order is:

1. Mode auto-approval — In acceptEdits mode, safe filesystem commands (mkdir, touch, rm, rmdir, mv, cp, sed) are auto-approved
2. Classifier evaluation — Async risk assessment classifier evaluates command semantics
3. Exact rule matching — User-defined rules checked for exact command string match
4. Wildcard/prefix matching — Glob-style pattern rules evaluated against normalized command
5. Operator decomposition — Compound commands (&&, ||, pipes) split and each segment validated
6. Subcommand analysis — Up to 50 subcommands analyzed with suggested rules for compounds
7. User confirmation — If no rule matches, prompt user for explicit approval

Configuration

Command-Specific Exit Code Semantics

BashTool interprets exit codes differently depending on the command, preventing false “error” reports for commands where non-zero codes are normal:

Directory Map

BashTool/
├── BashTool.tsx                  ← Main tool definition: call(), validateInput(), checkPermissions()
├── BashToolResultMessage.tsx     ← React component for rendering command output in UI
├── UI.tsx                        ← Tool use message rendering, user-facing name logic
├── bashCommandHelpers.ts         ← Operator permission checking for pipes, &&, ||
├── bashPermissions.ts            ← Primary permission layer (2621 LOC): rule matching, classifier
├── bashSecurity.ts               ← Injection detection (2592 LOC): 23+ async safety checks
├── commandSemantics.ts           ← Exit code interpretation per command type (grep, diff, test)
├── commentLabel.ts               ← UI label generation for command display
├── destructiveCommandWarning.ts  ← Warning messages for destructive operations
├── modeValidation.ts             ← Permission mode auto-approval for safe filesystem commands
├── pathValidation.ts             ← File path validation for 35+ commands (1303 LOC)
├── prompt.ts                     ← System prompt: background tasks, git, sandbox instructions
├── readOnlyValidation.ts         ← Flag whitelisting for read-only mode (1990 LOC)
├── sedEditParser.ts              ← Sed command parsing, BRE→ERE regex conversion
├── sedValidation.ts              ← Sed pattern allowlisting (print + substitution only)
├── shouldUseSandbox.ts           ← Multi-level sandboxing decision logic
├── toolName.ts                   ← Tool name constant and aliases
└── utils.ts                      ← Output formatting, image handling, CWD reset

Deep-Dive Highlights

Core mechanisms from BashTool have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Permission Flow Entry Point

// bashPermissions.ts — Main permission entry point
export async function bashToolHasPermission(
  input: { command: string; timeout?: number },
  context: ToolPermissionContext,
): Promise<PermissionResult> {
  // 1. Mode-based auto-approval (acceptEdits allows mkdir, touch, rm, etc.)
  const modeResult = checkPermissionMode(input.command, context);
  if (modeResult) return modeResult;

  // 2. Async classifier evaluation for risk assessment
  const classifierResult = await evaluateClassifier(input, context);
  if (classifierResult.behavior === 'deny') return classifierResult;

  // 3. Exact command matching against user-defined rules
  const exactMatch = matchExactRule(input.command, context.rules);
  if (exactMatch) return exactMatch;

  // 4. Operator permission checking (pipes, &&, ||)
  const operatorResult = checkCommandOperatorPermissions(input.command, context);
  if (operatorResult.behavior !== 'allow') return operatorResult;

  // 5. Subcommand analysis for compound commands
  return checkCommandAndSuggestRules(input.command, context);
}

Example: Command Exit Code Interpretation

// commandSemantics.ts — Semantic exit code mapping
export function interpretCommandResult(
  command: string,
  exitCode: number,
): string | undefined {
  const baseCmd = command.split(/\s+/)[0];
  switch (baseCmd) {
    case 'grep': case 'rg':
      // 0 = matches found, 1 = no matches (not an error), ≥2 = real error
      if (exitCode === 1) return 'No matches found (not an error)';
      if (exitCode >= 2) return 'Error occurred during search';
      break;
    case 'diff':
      // 0 = identical, 1 = differences found, ≥2 = error
      if (exitCode === 1) return 'Files differ (expected behavior)';
      break;
    case 'test': case '[':
      // 0 = condition true, 1 = condition false, ≥2 = error
      if (exitCode === 1) return 'Condition evaluated to false';
      break;
  }
  return undefined;
}