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.

Retrieve full stored output for a previous sh_run by id WITHOUT re-running it (the addressable output store). Use after a condensed result hid lines you need.

Statically predict what a command WOULD do without running it: blast-radius category (read-only | mutating | destructive | network | complex | unknown), whether it's reversible, and predicted file mutations. Use before destructive or unfamiliar commands. Does NOT execute anything.

Snapshot a working directory under a label so you can restore it later with sh_restore. Excludes .git and node_modules. Take one before a risky or irreversible change.

Mirror a directory back to a previous sh_checkpoint (files created since the checkpoint are removed). This is the rollback for an agent's mistakes.

List existing checkpoint labels for a project directory (checkpoints are namespaced per directory).

Aggregate PAST sh_run records for a command: observed exit/retry/duration/file-churn with explicit sample size (n) and recency window. DESCRIPTIVE only — it restates this local, capped, TTL-pruned store; it is NOT a prediction and makes NO causal claim. Read-only, runs nothing. Use to judge whether a command is historically slow/flaky in THIS project before running it.

Read the output of a background run started with sh_run background:true, by id. Returns a QUIET, condensed view of stdout/stderr plus status (running/exited/killed), exit code, and running_ms. Pass back stdout_cursor/stderr_cursor (the values returned by the previous call) to get ONLY new output since last poll — ideal for tailing a dev server. A live process reads from its in-memory buffer; once it exits the SAME id resolves to the durable record.

Stop a background run started with sh_run background:true, by id. Signals the whole process group (so a dev server's children die too). SIGTERM (the default) escalates to SIGKILL after 2s if the process ignores it. Returns status:"terminating" — the signal was sent but the OS hasn't confirmed the process is dead yet; poll sh_logs to see it settle to exited/killed. Killing an id whose process has ALREADY exited is not an error — it returns already_exited (idempotent).