65 lines
2.7 KiB
Markdown
65 lines
2.7 KiB
Markdown
# 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.
|
|
|
|
## 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.
|