# Bash execution tools

Background shell execution via `hive-bash-mcp`. Tools land as
`mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
Available on every agent unconditionally — `harness-base.nix` always
injects bash into `hyperhive.extraMcpServers` (with `allowedTools =
["*"]`), so `mcp__bash__*` is in `--allowedTools` for every claude
invocation regardless of tool groups.

## Tools

### `run(cmd, timeout_secs?)`

Submit a shell command for background execution (`sh -c <cmd>`).
Returns a task ID immediately; the command runs asynchronously in a
harness-managed tokio task. Stdout and stderr stream to
`harness/bash-tasks/<id>.{out,err}`. When the task completes (or
times out, or the process errors), the harness wakes the agent with a
summary body — handle on a future turn. Optional `timeout_secs`: pass
a value for a deadline, or omit for no timeout (runs until natural exit).

Exposed as `mcp__bash__run`.

### `status(id)`

Poll the status of a task submitted with `run`. Returns:

- `status` — `pending` / `running` / `done` / `timed_out` / `interrupted`
- `exit_code` — set when done
- run duration
- last 4 KiB of stdout and stderr (full output in the `.out` / `.err` files)

Tasks marked `interrupted` had their process killed by a harness
restart; a best-effort wake was still sent so the agent is not
silently blocked.

Exposed as `mcp__bash__status`.

## Namespace note

`run` and `status` live in the `bash` MCP server, not `hyperhive`. So
the tool names in claude are `mcp__bash__run` and `mcp__bash__status`.
The `Bash` built-in tool is blocked — all shell execution goes through
this structured path so tasks get task-id tracking and structured output.

## Relationship to the `execution` tool group

`ToolGroup::Execution` exists and appears in `AGENT_DEFAULT`, but its
`tools()` returns `["run", "status"]` which the harness expands to
`mcp__hyperhive__run` / `mcp__hyperhive__status` — tools that don't
exist in the hyperhive MCP server (dead entries). Removing `execution`
from an agent's groups has no effect on bash availability. Bash is
registered separately via the `extraMcpServers` path described above.