vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(bash): document wait_seconds param on run + status

Browse source
This commit is contained in:
damocles 2026-06-04 13:14:45 +02:00 • committed by mara
commit be8d8e48bf
1 changed files with 20 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/tools/bash.md
View file

@ -9,19 +9,26 @@ invocation regardless of tool groups.
## Tools
### `run(cmd, timeout_secs?)`
### `run(cmd, timeout_secs?, wait_seconds?)`
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).
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)`
### `status(id, wait_seconds?)`
Poll the status of a task submitted with `run`. Returns:
@ -30,6 +37,11 @@ Poll the status of a task submitted with `run`. Returns:
- 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.