From f80947f4ccd2350e4ef00b94b2800b01281e8f23 Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Fri, 11 Sep 2026 18:31:15 +0200
Subject: [PATCH] hive-sh4re, docs: fix the two docs argus flagged on
 ToolGroup::Execution

addresses review on #4245
---
 docs/tools/bash.md            | 32 +++++++++++++++++++++-----------
 hive-sh4re/src/permissions.rs |  6 +++++-
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/docs/tools/bash.md b/docs/tools/bash.md
index a5855be0..f0bd5cb6 100644
--- a/docs/tools/bash.md
+++ b/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
-bash into `hyperhive.extraMcpServers` via `lib.mkDefault` (with
-`allowedTools = ["*"]`), so `mcp__bash__*` is in `--allowedTools` for
-every claude invocation regardless of tool groups. Default rather than
-unconditional: an `agent.nix` can override or drop the entry.
+`nix/agent-modules/mcp.nix` registers bash into `hyperhive.extraMcpServers`
+by default (`lib.mkDefault`, with `allowedTools = ["*"]`) — an `agent.nix`
+can override or drop the entry, so this is a default, not an
+unconditional grant. Even where the entry is present, the server is only
+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
-`tools()` returns `["run", "status"]` which the harness expands to
-`mcp__hyperhive__run` / `mcp__hyperhive__status` — tools that don't
-exist in the hyperhive MCP server (dead entries). Removing `execution`
-from an agent's groups has no effect on bash availability.
-`nix/agent-modules/mcp.nix` registers Bash separately via the `extraMcpServers` path described above.
+`ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash: it
+controls whether the `bash` MCP server is rendered into the agent's
+claude config at all (`extra_server_required_group` in
+`hive-agent/src/mcp_config.rs`), suppressing every `mcp__bash__*` tool
+when absent — not just leaving them unused. Its own `tools()` returns
+`&[]` 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.
diff --git a/hive-sh4re/src/permissions.rs b/hive-sh4re/src/permissions.rs
index 2c3b296d..f34496b8 100644
--- a/hive-sh4re/src/permissions.rs
+++ b/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