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?, wait_seconds?)

Submit a shell command for background execution (sh -c <cmd>). Stdout and stderr stream to harness/bash-tasks/<id>.{out,err}. When the task completes (or times out, or the process errors), the harness fires a wake with from: "bash-task-<id>" and the exit code

• last stdout lines in the body; handle it on a future turn.

• timeout_secs — kill the task after N seconds and mark it timed_out. Omit for no timeout (runs until natural exit).
• wait_seconds — inline poll before returning (capped at 30). When the task finishes within the window the full status is returned immediately and no wake is fired; when the window expires the task keeps running and the normal task started: id=<id> response is returned. Defaults to 3 — pass wait_seconds: 0 to disable inline waiting and always get the immediate response.

Exposed as mcp__bash__run.

status(id, wait_seconds?)

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)

wait_seconds — optional inline poll (capped at 30): when the task finishes within the window the full status is returned immediately. Useful to avoid a separate round-trip when the task is expected to finish soon.

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.

Architecture

The bash tooling follows the same daemon + stdio-bridge pattern as the matrix MCP:

• hive-bash-daemon — long-running process (one per agent container, systemd service in harness-base.nix). Owns subprocess management, output file writing, mcp-loose-ends/ state, and wake signal delivery. Listens on /run/hive-bash/socket inside the container.

• hive-bash-mcp — stdio bridge spawned by claude per turn (declared in hyperhive.extraMcpServers.bash). Connects to the daemon socket and forwards run / status tool calls. Has no subprocess management logic of its own.

This split keeps claude's turn-local MCP bridge lightweight while the daemon tracks long-running tasks that outlive a single turn.

Transient wake (bypass broker sqlite)

When a bash task finishes, hive-bash-daemon sends the wake signal via the agent's per-agent socket as a transient wake (AgentRequest::Wake with transient: true). This bypasses broker sqlite for lower latency — the same mechanism used by matrix events. The message is delivered directly to the harness without touching the persistent message store.

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.