---
url: >-
  https://adk.nht.io/api/@nhtio/adk/batteries/sandbox/functions/createRunShellCommandTool.md
---

# Function: createRunShellCommandTool()

```ts
function createRunShellCommandTool(options: RunShellCommandOptions): Tool;
```

Defined in: [src/batteries/sandbox/tool.ts:60](https://github.com/NHTIO/ADK/blob/v1.20260824.1/src/src/batteries/sandbox/tool.ts#L60)

Assemble the factory-style `run_shell_command` tool. It is intentionally not a bulk-registered
battery value. `cwd` is a model-supplied workspace-relative path and receives the complete
PathTranslator gauntlet, including symlink refusal; the default is the workspace root.

The command spawns first, then stdout and stderr are drained concurrently and merged in arrival
order into one stream and one `storeRetrievableBytes` call. Diagnostics are polled while drains
run and written as `[sandbox] denied: …` at their observation point ("observed after", not
"caused by"). The command is never accumulated here. `timeout_seconds` defaults to 300 and is
a tool argument. Non-zero exits, violations, timeouts, and post-spawn I/O failures return the
singular artifact; failures meaning the command never ran throw instead.

## Parameters

| Parameter | Type                                                                |
| --------- | ------------------------------------------------------------------- |
| `options` | [`RunShellCommandOptions`](../interfaces/RunShellCommandOptions.md) |

## Returns

[`Tool`](../../../forge/classes/Tool.md)