diff --git a/docs/tools/bash.md b/docs/tools/bash.md
index d49719af..59bbc61b 100644
--- a/docs/tools/bash.md
+++ b/docs/tools/bash.md
@@ -55,6 +55,32 @@ 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.
 
+## Architecture
+
+The bash tooling follows the same daemon + stdio-bridge pattern as the
+matrix MCP:
+
+- **`hive-bash-daemon`** — long-running process (one per agent container,
+  systemd service in `harness-base.nix`). Owns subprocess management,
+  output file writing, `mcp-loose-ends/` state, and wake signal delivery.
+  Listens on `/run/hive-bash/socket` inside the container.
+
+- **`hive-bash-mcp`** — stdio bridge spawned by claude per turn (declared
+  in `hyperhive.extraMcpServers.bash`). Connects to the daemon socket and
+  forwards `run` / `status` tool calls. Has no subprocess management logic
+  of its own.
+
+This split keeps claude's turn-local MCP bridge lightweight while the
+daemon tracks long-running tasks that outlive a single turn.
+
+### Transient wake (bypass broker sqlite)
+
+When a bash task finishes, `hive-bash-daemon` sends the wake signal via
+the agent's per-agent socket as a **transient wake** (`AgentRequest::Wake`
+with `transient: true`). This bypasses broker sqlite for lower latency —
+the same mechanism used by matrix events. The message is delivered
+directly to the harness without touching the persistent message store.
+
 ## Relationship to the `execution` tool group
 
 `ToolGroup::Execution` exists and appears in `AGENT_DEFAULT`, but its