hyperhive/docs/tools/bash.md

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).