49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# Bash execution tools (`execution` tool group)
|
|
|
|
Background shell execution via `hive-bash-mcp`. Tools land as
|
|
`mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
|
|
Enabled for any agent whose tool groups include `execution` — the
|
|
default preset (`AGENT_DEFAULT`) includes it.
|
|
|
|
## 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.
|
|
|
|
## Tool whitelist cross-reference
|
|
|
|
`mcp__bash__run` and `mcp__bash__status` are unconditionally in
|
|
`--allowedTools` whenever the harness spawns claude (they are not
|
|
gated by the `execution` group at the `--allowedTools` level — the
|
|
group only gates whether the MCP server registers the tools at all).
|