Run shell command (agent-native)
sh_runExecute shell commands with structured output: exit code, duration, git diff, and condensed stdout/stderr. Full output stored for on-demand retrieval, reducing token usage.
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. Pass scrub_env:true to strip credential-shaped env vars from the child (auto-on with sandbox protect_secrets/deny_read); no_store:true keeps a sensitive run memory-only.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory. Defaults to the server's cwd. | |
| full | No | If true, return full stdout/stderr inline (skip condensing). | |
| trace | No | Capture a structured FS/syscall trace (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. | |
| expect | No | Post-conditions verified after the command, so you need no second command to confirm it worked. | |
| command | Yes | The shell command to execute. | |
| preview | No | Dry-run in a disposable CoW clone of cwd: the command runs INSIDE the clone, you get the cwd-relative file diff, and the real cwd is never touched (nothing is promoted). Honest scope: absolute-path / parent-dir / network effects are NOT captured and may happen for real — this is NOT a sandbox (combine with sandbox:true for containment). Refuses if cwd can't be cloned. | |
| retries | No | Retry up to N times on failure (default 0). | |
| sandbox | No | Run under a real OS sandbox (macOS sandbox-exec / Linux bubblewrap): file writes confined to cwd + temp. Pass {network:false} to deny network, {writable:[...]} for extra writable paths, {protect_secrets:true} or {deny_read:[...]} to BLOCK READS of configured secret dirs (scoped — blocks the listed paths, NOT a proof against all exfiltration). REFUSES to run (does not execute unconfined) if a sandbox is unavailable. | |
| no_store | No | Keep this run MEMORY-ONLY: the record is cached for sh_detail this session but is NOT written to disk. Use for a sensitive run whose output should not persist. Result carries stored:"memory-only" so you know sh_detail works now but nothing was persisted. | |
| scrub_env | No | Strip credential-shaped vars (SECRET/TOKEN/PASSWORD/KEY/… see SECRET_ENV_PATTERNS) from the command's environment so a child can't read them. Auto-enabled whenever the sandbox requests protect_secrets or deny_read — masking ~/.ssh while leaving tokens in $env would be inconsistent. Surfaces secrets_env_scrubbed (a COUNT; values are never echoed). | |
| background | No | Run as a LONG-RUNNING background process (dev server, --watch build): returns IMMEDIATELY with { id, pid, status:"running" } instead of blocking until exit. Poll its output with sh_logs id=<id> (pass the returned cursor to tail only new lines); stop it with sh_kill id=<id>. No stdin/TTY. Incompatible with options that require completion (expect, preview, trace, retries, full, timeout_ms) — those are refused. Keeps cwd, sandbox, scrub_env, no_store. | |
| backoff_ms | No | Fixed delay between retries in ms. | |
| timeout_ms | No | Override per-command timeout in ms (0-config default applies otherwise). | |
| retry_on_exit | No | Only retry when exit code is in this set; omit = retry on any nonzero. |