feat(#513): add ToolGroup enum, derive allowed_mcp_tools from groups + HIVE_TOOL_GROUPS env

hive-sh4re/src/lib.rs

@@ -711,6 +711,81 @@ pub struct SchedulePromptPayload {
     pub description: Option<String>,
 }
 
+/// Named group of MCP tools an agent may be granted. The harness reads
+/// `HIVE_TOOL_GROUPS` from the environment (a comma-separated list of
+/// snake_case group names written by the meta renderer from per-agent
+/// config) and expands it to the matching tool names for `--allowedTools`.
+/// When the env var is absent the harness falls back to the flavor default
+/// (`AGENT_DEFAULT` or `MANAGER_DEFAULT`). See `docs/conventions.md::Tool groups`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolGroup {
+    /// `send`, `recv`, `ask`, `answer`
+    Messaging,
+    /// `set_status`, `get_agent_meta`
+    Meta,
+    /// `get_loose_ends`, `cancel_loose_end`, `remind`, `request_next_turn`
+    Inbox,
+    /// `kill`, `start`, `restart`, `update` - *(privileged)*
+    Lifecycle,
+    /// `request_init_config`, `request_apply_commit`,
+    /// `request_update_meta_inputs` - *(privileged)*
+    Approvals,
+    /// `request_schedule_prompt`, `fire_schedule_now`, `cancel_schedule`,
+    /// `edit_schedule`, `list_schedules` - *(privileged)*
+    Scheduling,
+    /// `get_logs` - *(privileged)*
+    Diagnostics,
+}
+
+impl ToolGroup {
+    /// The MCP tool names (without the `mcp__hyperhive__` prefix) in this group.
+    #[must_use]
+    pub fn tools(self) -> &'static [&'static str] {
+        match self {
+            Self::Messaging => &["send", "recv", "ask", "answer"],
+            Self::Meta => &["set_status", "get_agent_meta"],
+            Self::Inbox => &[
+                "get_loose_ends",
+                "cancel_loose_end",
+                "remind",
+                "request_next_turn",
+            ],
+            Self::Lifecycle => &["kill", "start", "restart", "update"],
+            Self::Approvals => &[
+                "request_init_config",
+                "request_apply_commit",
+                "request_update_meta_inputs",
+            ],
+            Self::Scheduling => &[
+                "request_schedule_prompt",
+                "fire_schedule_now",
+                "cancel_schedule",
+                "edit_schedule",
+                "list_schedules",
+            ],
+            Self::Diagnostics => &["get_logs"],
+        }
+    }
+
+    /// Default tool groups for a plain agent harness — equivalent to the
+    /// old `Flavor::Agent` allow-list. Used when `HIVE_TOOL_GROUPS` is unset.
+    pub const AGENT_DEFAULT: &'static [Self] =
+        &[Self::Messaging, Self::Meta, Self::Inbox];
+
+    /// Default tool groups for the manager harness — equivalent to the
+    /// old `Flavor::Manager` allow-list. Used when `HIVE_TOOL_GROUPS` is unset.
+    pub const MANAGER_DEFAULT: &'static [Self] = &[
+        Self::Messaging,
+        Self::Meta,
+        Self::Inbox,
+        Self::Lifecycle,
+        Self::Approvals,
+        Self::Scheduling,
+        Self::Diagnostics,
+    ];
+}
+
 /// Schedule row shape on the wire — mirror of
 /// `scheduled_prompts::Schedule` but in the public crate so the
 /// dashboard and agent surfaces can deserialize without depending