diff --git a/docs/tools/bash.md b/docs/tools/bash.md
index a99f4de0..d49719af 100644
--- a/docs/tools/bash.md
+++ b/docs/tools/bash.md
@@ -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.