07. Deep Read: BashTool

Why BashTool Is the Most Important Module

If you only study one concrete tool in the tree, study BashTool. It captures the central tension of an agentic terminal product: the model becomes useful only when it can act locally, but that same ability is the main safety hazard.

What BashTool.tsx Handles

• Input schema and execution flow
• Progress reporting and foreground/background task behavior
• Command classification for UI collapsing
• Sandbox routing
• File history tracking and output storage
• Tool result message rendering

One subtle lesson here is that execution logic is mixed with presentation concerns only at the outer layer. The dangerous reasoning itself is delegated to separate files.

What bashSecurity.ts Handles

This file reads like a shell attack taxonomy. It blocks or inspects command substitution, process substitution, zsh-specific tricks, malformed shell quoting, heredoc edge cases, redirection abuse, escaped metacharacters, environment access, and parser desynchronization patterns.

The main lesson is architectural: command safety is not one regex. It is a layered parser-plus-heuristics problem.

What bashPermissions.ts Handles

This layer sits between raw shell text and the user permission experience. It combines shell parsing, AST semantics, rule extraction, classifier decisions, path checks, sandbox checks, and permission modes. It is effectively the policy engine for shell execution.

Layer Breakdown

What You Should Copy Into Your Own Work

• Split shell safety into multiple files with narrow responsibilities.
• Represent permission state as data, not as scattered booleans.
• Keep the UI in the loop for risky actions.
• Use parser-informed checks where possible, and heuristics as defense in depth.