Interface: RunShellCommandOptions
Defined in: src/batteries/sandbox/tool.ts:105
Configuration for the streaming shell-command tool.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
allowedCommands? | readonly | readonly string[] | Optional command-name allow-list; restricts the line to a single plain command. Operators, pipes, redirection, grouping, backticks, all $ expansion, and backslashes are refused even inside quotes. The first word must be unquoted; argument quotes are allowed. This is a name check, not a security boundary: the sandbox policy remains the boundary. | src/batteries/sandbox/tool.ts:128 |
description? | readonly | string | Optional tool description override. | src/batteries/sandbox/tool.ts:143 |
env? | readonly | Readonly<Record<string, string>> | Environment variables to add to every command this tool spawns. Remarks ADDITIVE, and applied LAST — over both the host variables the enforcer allow-listed and SRT's own proxy/CA plumbing. It is not the host-inheritance control: the enforcer decides what the child inherits (envAllowList / inheritHostEnv on the Node adapter), and this cannot re-admit a variable the enforcer withheld except by supplying the value literally here. Anything put here is readable by the model — run_shell_command runs commands the model chose, and env is one of them — so pass configuration, not credentials. | src/batteries/sandbox/tool.ts:141 |
gate? | readonly | ToolGateFn | Required human/policy approval gate. | src/batteries/sandbox/tool.ts:121 |
narrate? | readonly | SandboxNarrator | Injectable model-facing outcome renderer. | src/batteries/sandbox/tool.ts:155 |
onCompletion? | readonly | RunShellCommandCompletionFn | Called exactly once per invocation with the structured completion, on EVERY terminal outcome. Remarks Success, non-zero exit, timeout, kill/signal, gate/approval denial, and an enforcer throw all settle this once — see RunShellCommandCompletion for the field rules. A callback that throws is logged and swallowed: it must never break the tool call or surface as an unhandled rejection (the issue-#39 bug class). | src/batteries/sandbox/tool.ts:153 |
policy | readonly | | SandboxPolicy | RunShellCommandPolicyFn | Policy applied to the spawned command: a static object for every call, or a per-call function. Remarks A function is evaluated once per invocation, AFTER the gate has approved and after cwd has passed the path gauntlet, and receives the call context (the validated tool args and the resolved workspace-relative cwd). Its return is the policy for that ONE child — see RunShellCommandPolicyFn for the fresh-object rule under concurrency. | src/batteries/sandbox/tool.ts:117 |
sandbox | readonly | SandboxPolicyEnforcer | Streaming policy enforcer; unlike BinaryExecutor this exposes live stdout/stderr. | src/batteries/sandbox/tool.ts:107 |
translator | readonly | PathTranslator | Model-path translator for the working directory. | src/batteries/sandbox/tool.ts:119 |