docs(#1251): split MCP tool docs into docs/tools/ sub-mds by feature

docs/tools/bash.md

@@ -0,0 +1,49 @@
+# Bash execution tools (`execution` tool group)
+
+Background shell execution via `hive-bash-mcp`. Tools land as
+`mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
+Enabled for any agent whose tool groups include `execution` — the
+default preset (`AGENT_DEFAULT`) includes it.
+
+## Tools
+
+### `run(cmd, timeout_secs?)`
+
+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).
+
+Exposed as `mcp__bash__run`.
+
+### `status(id)`
+
+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)
+
+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.
+
+## Tool whitelist cross-reference
+
+`mcp__bash__run` and `mcp__bash__status` are unconditionally in
+`--allowedTools` whenever the harness spawns claude (they are not
+gated by the `execution` group at the `--allowedTools` level — the
+group only gates whether the MCP server registers the tools at all).