Module shell 

Shell command execution tool (Bash). Shell command execution tool (Bash).

Runs commands as child processes with timeout protection. Output line cap is set by OutputCaps (context-scaled).

Parameters

• command (required) — The shell command to execute
• timeout (optional, default 60) — Timeout in seconds
• background (optional, default false) — Run in background, return PID

Background mode

When background: true the command is spawned detached and control returns immediately with the PID. Use for dev servers, file watchers, and other long-running processes. Background processes are tracked in BgRegistry.

Safety

• Commands are classified by bash_safety::classify_bash_command
• Destructive commands (rm -rf, git push --force) always need confirmation
• Path escapes outside the project root are flagged by bash_path_lint
• Output is capped to prevent context overflow (verbose output is truncated)

Best practices (sent to the model)

• Use Bash only for builds, tests, git, and commands without a dedicated tool
• Never use Bash for file ops — use Read/Write/Edit/Grep/List instead
• Suppress verbose output: pipe to tail, use --quiet, avoid -v flags

Structs

ShellOutput

Result of a shell command with both a model-facing summary and full output.

Functions

definitions

Return tool definitions for the LLM.

run_shell_command

Execute a shell command with timeout, output capping, and optional streaming.