RunShellTool

Escape hatch — run an arbitrary shell command via the backend.

Default-deny: the tool refuses unless the host registers an explicit allowlist of command prefixes via ShellAllowlist. The host's choice is the security boundary; the LLM cannot bypass it through prompting.

Two parameter forms:

• Argv form (preferred): pass command (the bin name) plus args (an array of argv strings). No tokenisation, quoting just works.

• String form (legacy / convenience): pass only command containing the full command line. The tool whitespace-splits — quotes are NOT honoured, so this form is unsuitable for arguments containing spaces. Allowlist matching is against the split tokens.

Allowlist enforcement: the request's argv — the whitespace-split command line in string form, or [command] + args verbatim in argv form — is checked against ShellAllowlist.isAllowed, a token-by-token prefix match against the host-registered entries (see ShellAllowlist). If it doesn't match (including the default empty allowlist, which disables the tool entirely), execute short-circuits with a run_shell_not_enabled ToolResult.error whose detail lists the current allowlist snapshot — the command is never spawned.

Privilege: requires a working ShellBackend AND a host-configured ShellAllowlist.

Params: command (required), args (optional argv array), max_stdout_bytes (optional, clamped 1024–65536, default 8192; the same byte cap is applied to stderr).

On success the result map carries exit_code, stdout, stderr, stdout_truncated, and stderr_truncated. The *_truncated flags are also set when the backend itself killed the process for exceeding its capture cap (then exit_code is -1). Note the raw process exit_code is reported as data: a non-zero exit is still a successful tool call.