hyperhive/docs/tools/bash.md

Bash execution tools

For the operator: this page covers the daemon as deployed and what the tools do around the edges. How an agent calls them is in the tools' own MCP descriptions.

Background shell execution via hive-bash-daemon. Tools land as mcp__bash__<tool> (the MCP server name is bash, not hyperhive). nix/agent-modules/mcp.nix registers bash into services.hyperhive.agent.extraMcpServers by default (lib.mkDefault, with allowedTools = ["*"]) — an agent.nix can override or drop the entry, so this is a default, not an unconditional grant. Even where the entry is present, the server is only actually rendered into an agent's claude config when the agent also holds the execution permission: extra_server_required_permission in hive-agent/src/mcp_config.rs suppresses it entirely without that permission, so an agent lacking execution gets no mcp__bash__* tools at all, not just an unused grant. The harness rewrites the config each turn, so a change applies at the next one. See "Relationship to the execution permission" below.

Tools

Each tool's parameters and return values are in its own MCP description, which is what an agent reads at call time. This section says what the tools do around the edges.

• run submits a shell command (through bash) as a background task. Its stdout and stderr stream to harness/bash-tasks/<id>.{out,err}. When the task finishes, times out or its process errors, it surfaces as a todo in the agent's loose-ends, with the exit code and a pointer to the captured output. run waits up to 3 seconds (30 at most) for a result before it returns; a result delivered that way makes no todo. A caller-chosen name replaces the generated id. The daemon accepts the name again once its task has finished, and rejects it while the task is still pending or running.
• status polls a task: its state (pending, running, done, timed_out, interrupted or killed), the exit code, the run time and the last 4 KiB of each stream. A call that sees a finished task clears its completion todo, since the agent already has the result; in a narrow race both can still appear. A task marked interrupted had its process killed by a harness restart, and a best-effort todo is still made so the agent isn't blocked silently.
• kill stops a running or pending task and returns without waiting. The completion surfaces as a todo like any other. It signals the task's whole process group, so children the shell started stop too: SIGINT by default, SIGKILL with force. The daemon cancels a task still pending before it starts, and the task ends as killed.

Namespace note

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

Architecture

hive-bash-daemon is a single long-running process (one per agent container, systemd service in nix/agent-modules/mcp.nix) — no stdio bridge. It owns subprocess management, output file writing, todo delivery on the harness's in-agent socket, and serves the run/status/kill MCP tools directly over streamable-http on services.hyperhive.agent.mcp.bashHttpPort (declared in services.hyperhive.agent.extraMcpServers.bash as { type = "http"; url = ...; }). Same shape as the built-in hyperhive surface (hive-mcp-http) — claude reconnects to the stable URL every turn instead of respawning a stdio child, so there's no per-turn MCP re-registration race and no round-trip socket hop for tool calls.

Completion as a todo (loose-ends v2)

When a bash task changes state, hive-bash-daemon upserts a single keyed todo (key = task id) on the harness's in-agent socket (HIVE_AGENT_SOCKET) — "running" at start, then the completion summary when it finishes. The summary change signals the harness turn loop directly (in-process, no broker round-trip), so the harness drives a turn for the agent to handle it via get_loose_ends, then clears the todo with cancel_loose_end(kind: "todo", id: N) (dials the in-container socket directly — no bash task involved, so clearing doesn't spawn another todo). Same mechanism the matrix daemon uses for unread rooms. An inline wait_seconds / status observation that already delivered the result instead clears the keyed todo, so no redundant loose-end follows.

Relationship to the execution permission

Permission::Execution (in Permission::DEFAULT) is the real gate on bash: extra_server_required_permission (in hive-agent/src/mcp_config.rs) controls whether the bash MCP server reaches the agent's claude config at all, suppressing every mcp__bash__* tool when absent — not just leaving them unused. Its own tools() returns &[]: mcp__bash__run/status/kill live on the separate bash MCP server that extra_server_required_permission gates, not on the mcp__hyperhive__* allowlist tools() builds. Removing execution from an agent's permissions does remove bash availability.