Run shell command (agent-native)
sh_runRun shell commands with structured output including exit code, duration, and file changes. Supports post-condition verification and sandboxing.
Instructions
Execute a shell command and return a QUIET, STRUCTURED result: exit code, duration, files changed (git diff), and a token-aware view of stdout/stderr (full on small/failure, head+tail otherwise). Full output is stored and addressable via sh_detail — it is NOT re-emitted into context. Prefer this over a raw Bash call when you care about effects or output is likely verbose.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The shell command to execute. | |
| cwd | No | Working directory. Defaults to the server's cwd. | |
| full | No | If true, return full stdout/stderr inline (skip condensing). | |
| timeout_ms | No | Override per-command timeout in ms (0-config default applies otherwise). | |
| expect | No | Post-conditions verified after the command, so you need no second command to confirm it worked. | |
| retries | No | Retry up to N times on failure (default 0). | |
| retry_on_exit | No | Only retry when exit code is in this set; omit = retry on any nonzero. | |
| backoff_ms | No | Fixed delay between retries in ms. | |
| sandbox | No | Run under a real OS sandbox (macOS sandbox-exec): file writes confined to cwd + temp. Pass {network:false} to also deny network, {writable:[...]} for extra writable paths. REFUSES to run (does not execute unconfined) if a sandbox is unavailable. | |
| trace | No | Capture a structured FS/syscall trace (feature A; Linux strace). Surfaces a read/write summary; full trace via sh_detail selector=trace. Best-effort: if no tracer is available the command still runs and trace_unavailable is set. |