hive-sh4re, docs: fix the two docs argus flagged on ToolGroup::Execution

addresses review on #4245

docs/tools/bash.md

@@ -2,11 +2,16 @@
 
 Background shell execution via `hive-bash-daemon`. Tools land as
 `mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
-Available on every agent by default — `nix/agent-modules/mcp.nix` injects
+`nix/agent-modules/mcp.nix` registers bash into `hyperhive.extraMcpServers`
-bash into `hyperhive.extraMcpServers` via `lib.mkDefault` (with
+by default (`lib.mkDefault`, with `allowedTools = ["*"]`) — an `agent.nix`
-`allowedTools = ["*"]`), so `mcp__bash__*` is in `--allowedTools` for
+can override or drop the entry, so this is a default, not an
-every claude invocation regardless of tool groups. Default rather than
+unconditional grant. Even where the entry is present, the server is only
-unconditional: an `agent.nix` can override or drop the entry.
+actually rendered into an agent's claude config when the agent also
+holds the **`execution`** tool group: `extra_server_required_group` in
+`hive-agent/src/mcp_config.rs` suppresses it entirely without that
+group, so an agent lacking `execution` gets no `mcp__bash__*` tools at
+all, not just an unused grant. See "Relationship to the `execution` tool
+group" below.
 
 ## Tools
 
@@ -119,9 +124,14 @@ loose-end follows.
 
 ## Relationship to the `execution` tool group
 
-`ToolGroup::Execution` exists and appears in `AGENT_DEFAULT`, but its
+`ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash: it
-`tools()` returns `["run", "status"]` which the harness expands to
+controls whether the `bash` MCP server is rendered into the agent's
-`mcp__hyperhive__run` / `mcp__hyperhive__status` — tools that don't
+claude config at all (`extra_server_required_group` in
-exist in the hyperhive MCP server (dead entries). Removing `execution`
+`hive-agent/src/mcp_config.rs`), suppressing every `mcp__bash__*` tool
-from an agent's groups has no effect on bash availability.
+when absent — not just leaving them unused. Its own `tools()` returns
-`nix/agent-modules/mcp.nix` registers Bash separately via the `extraMcpServers` path described above.
+`&[]` and stays that way: `mcp__bash__run`/`status`/`kill` belong to a
+different, out-of-process MCP server (`bash`, not `hyperhive`), so they
+were never real entries in the `mcp__hyperhive__*` allowlist `tools()`
+builds — the two dead `["run", "status"]` strings it used to return
+matched nothing and have been removed. Removing `execution` from an
+agent's groups **does** remove bash availability.

hive-sh4re/src/permissions.rs

@@ -34,7 +34,11 @@ pub enum ToolGroup {
     /// now that agents can't create them directly). Opt-in per
     /// agent so the operator controls who can spin up repos.
     Forge,
-    /// `run`, `status` (via `mcp__bash__*`)
+    /// Gates whether the `bash` MCP server (`mcp__bash__run`/`status`/
+    /// `kill`) is rendered into the agent's config at all — see
+    /// `extra_server_required_group` in `hive-agent/src/mcp_config.rs`.
+    /// `tools()` returns `&[]`: this isn't a `mcp__hyperhive__*`
+    /// allowlist entry, the gate lives at config-render time instead.
     Execution,
     /// Claude built-in web egress tools: `WebFetch` (retrieve a URL) and
     /// `WebSearch` (search the web). Both are omitted from `--tools` by
@@ -65,8 +69,16 @@ impl ToolGroup {
             ],
             Self::Diagnostics => &["get_logs"],
             Self::Forge => &["create_repo"],
-            Self::Execution => &["run", "status"],
+            // Both empty, for different reasons — see each variant's own
-            Self::WebTools => &[],
+            // doc comment above. `Execution` grants the out-of-process
+            // `bash` MCP server (`mcp__bash__run`/`status`/`kill`), gated
+            // at config-render time by `extra_server_required_group` in
+            // `hive-agent/src/mcp_config.rs`, not by this list — an
+            // out-of-process server has no later enforcement point, so
+            // that gate is the actual security boundary. `WebTools`
+            // grants Claude built-in tools, not MCP ones; see
+            // `builtin_tools()`.
+            Self::Execution | Self::WebTools => &[],
         }
     }