From 14339319043262d6b63bb769aed645a8e5ba4c90 Mon Sep 17 00:00:00 2001 From: damocles Date: Mon, 1 Jun 2026 13:55:19 +0200 Subject: [PATCH] docs: document bash_run and bash_status tools in turn-loop.md --- docs/turn-loop.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/turn-loop.md b/docs/turn-loop.md index 2e4f24cc..87df5583 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -369,6 +369,20 @@ it as a stdio child via `--mcp-config`. The hyperhive socket name is continue without waiting for an external message. The next turn starts with `from: "self"` and `body: "continue"`. No-op if new inbox messages arrive before this turn ends. No args. +- `bash_run(cmd, timeout_secs?)` — submit a shell command for + background execution (`sh -c `). Returns a task ID immediately; + the command runs asynchronously in a harness-managed tokio task. Stdout + and stderr stream to `harness/bash-tasks/.{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. Default + timeout 180s; pass `timeout_secs` to override. Requires the + `execution` tool group. +- `bash_status(id)` — poll the status of a task submitted with + `bash_run`. Returns status (`pending`/`running`/`done`/`timed_out`/ + `interrupted`), exit code, run duration, and the 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. ### Waking the agent from inside the container