Shell run
shell_runExecutes shell commands in the workspace for builds, tests, git, and package installs, returning a background run ID or blocking for stdout/stderr on short commands.
Instructions
Run a shell command in the workspace (shell, relative_cwd, timeout_s). Default is background: returns run_id, poll shell_status. background=false blocks until exit and returns stdout/stderr. Use when: you build, test, run git or install packages. background=false for short commands you need now. Avoid when: you read or edit files (file tools) or run a tiny JS calculation (execute_js). Output: run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=false) or stdout_tail/stderr_tail. ok=true only means the call ran; status (completed|failed|running|cancelled) and command_status describe the command. shell_path/shell_kind name the binary that ran it (on Windows bash may be the WSL launcher). approval_required: ask the user to approve, then retry once with approval_id. repeated_failure: the identical invocation already failed; read data.previous.stderr_tail, then change the command or pass retry_failed=true.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"command": "<command>"
},
"name": "shell_run"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| shell | No | Default: VENIRA_DEFAULT_SHELL, else the host default. pwsh = PowerShell 7+, powershell = 5.1. | |
| reason | No | Required with override: one-line intent (audit-logged). | |
| command | Yes | Command line to run. | |
| dry_run | No | true = evaluate policy only; nothing runs, no approval is created (default false). | |
| override | No | Named exception; only works when the operator enabled this exact name in VENIRA_SHELL_OVERRIDES. | |
| timeout_s | No | Kill the process tree after this many seconds (0/unset = 10 min; fractional ok; capped by VENIRA_SHELL_MAX_TIMEOUT_MS). | |
| background | No | true = background (default): return immediately with run_id. false = foreground: block until the command exits, then return the final stdout/stderr in this call. | |
| secret_env | No | Stored secret names (secret) injected as env vars, e.g. ["GITHUB_TOKEN"]. Values never appear in the command, audit log or output. | |
| approval_id | No | Id from approval_required, granted by a human (`data.approval.approve_command` or client elicitation). Retry once. | |
| relative_cwd | No | Working directory inside the workspace (default: workspace root). | |
| retry_failed | No | true = rerun an identical invocation that already failed (default false: refused with repeated_failure and the previous stderr tail). | |
| approval_wait_s | No | If approval is needed, wait up to this many seconds (max 45; fractional ok) for the human, then run in the same call. |