shell-exec

name	shell-exec
description	Run shell commands in the workspace. Use when: the user asks to invoke a CLI, run tests, install dependencies, or chain Unix tools. NOT for: file reads (use file-ops), HTTP calls (web_fetch), or anything where a built-in tool already exists. NEVER use this to bypass other safety checks.
metadata	{"all_agents":{"emoji":"💻","requires":{"bins":["bash"]}}}

Shell Execution

The run_command tool runs one shell command and returns its stdout, stderr, and exit code.

Contract

{
  "cmd": "ls -la",
  "cwd": "subdir",         // optional, defaults to workspace root
  "timeout_s": 30          // optional, defaults to 30
}

Returns:

{ "ok": true, "stdout": "...", "stderr": "...", "returncode": 0 }

Approval policy

run_command honours the runtime's ExecApprovalPolicy. Commands that match deny-listed patterns (e.g. rm -rf /, sudo, curl | sh) are refused without execution. The agent is expected to read the policy and not retry refused commands with shell tricks.

When to chain vs. when to script

• One short command: pass it inline (grep -r foo src/).
• Multiple commands: prefer chaining with && / | over multiple tool calls — one approval, less round-trip.
• Anything multi-line or with quoting traps: write a script via write_file and bash script.sh.

What this tool is NOT

• Not a long-running daemon (use processes start <agent>).
• Not a way to install global packages (ask the user to run installers).
• Not a workaround for missing tools — if you wish you had a glob_files primitive, use the existing one rather than find . -name.