diff --git a/CLAUDE.md b/CLAUDE.md index b60196b1..af5643cd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -296,7 +296,7 @@ nix/ forge-theme/theme-catppuccin-vibec0re.css Catppuccin Mocha forge theme docs/ - conventions.md naming, identity=socket, async forms, commit style + conventions.md naming, identity=socket, tool groups, async forms, commit style gotchas.md NixOS / nspawn quirks and lessons learned web-ui.md index → web-ui/shape.md (shared skeleton, SSE, terminal, listener bind, relative paths, atomic diff --git a/docs/conventions.md b/docs/conventions.md index 806c95b0..07979a69 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -274,6 +274,33 @@ status_text, status_set_at, hive_name, swarm_name }`: `services.hyperhive.hiveName` / `services.hyperhive.swarmName`). Both `None` when the options aren't configured. +## Tool groups + +The MCP tool surface an agent receives is derived from a set of named +`ToolGroup` values (`hive_sh4re::ToolGroup`), not from a hardcoded +binary flavor. + +| Group | Tools | +|---|---| +| `messaging` | `send`, `recv`, `ask`, `answer` | +| `meta` | `set_status`, `get_agent_meta` | +| `inbox` | `get_loose_ends`, `cancel_loose_end`, `remind`, `request_next_turn` | +| `lifecycle` | `kill`, `start`, `restart`, `update` *(privileged)* | +| `approvals` | `request_init_config`, `request_apply_commit`, `request_update_meta_inputs` *(privileged)* | +| `scheduling` | `request_schedule_prompt`, `fire_schedule_now`, `cancel_schedule`, `edit_schedule`, `list_schedules` *(privileged)* | +| `diagnostics` | `get_logs` *(privileged)* | + +**Runtime resolution** — at session start the harness reads `HIVE_TOOL_GROUPS` +(a comma-separated list of snake_case group names written by the meta renderer +from per-agent config). Unrecognised tokens are logged and skipped. Falls back +to `ToolGroup::AGENT_DEFAULT` (`messaging`, `meta`, `inbox`) or +`ToolGroup::MANAGER_DEFAULT` (all groups) when the var is absent or empty. + +**Updating the surface** — when a new `#[tool]` fn is added to `AgentServer` +or `ManagerServer` in `hive-ag3nt/src/mcp.rs`, add its name to the matching +`ToolGroup::tools()` slice in `hive-sh4re/src/lib.rs`. That's the single +source of truth; `allowed_mcp_tools` reads it at session start. + ## Async forms Dashboard + per-agent mutating forms carry `data-async`; a delegated diff --git a/hive-ag3nt/src/mcp.rs b/hive-ag3nt/src/mcp.rs index 614fd79b..e3f4a134 100644 --- a/hive-ag3nt/src/mcp.rs +++ b/hive-ag3nt/src/mcp.rs @@ -468,10 +468,9 @@ impl AgentServer { } // IMPORTANT: when adding a new `#[tool]` fn to this impl, also add -// its name to `allowed_mcp_tools(Flavor::Agent)` below. Claude -// Code's permission gate refuses uninlisted MCP tools in -// non-interactive `--print` mode with "permissions not granted yet" -// — keep the two lists in lockstep. +// its name to the matching `ToolGroup::tools()` slice in hive-sh4re. +// Claude Code's permission gate refuses uninlisted MCP tools in +// non-interactive `--print` mode with "permissions not granted yet". #[tool_router] impl AgentServer { #[tool( @@ -1062,10 +1061,9 @@ impl ManagerServer { } // IMPORTANT: when adding a new `#[tool]` fn to this impl, also add -// its name to `allowed_mcp_tools(Flavor::Manager)` below. Claude -// Code's permission gate refuses uninlisted MCP tools in -// non-interactive `--print` mode with "permissions not granted yet" -// — keep the two lists in lockstep. +// its name to the matching `ToolGroup::tools()` slice in hive-sh4re. +// Claude Code's permission gate refuses uninlisted MCP tools in +// non-interactive `--print` mode with "permissions not granted yet". #[tool_router] impl ManagerServer { #[tool( @@ -1731,56 +1729,70 @@ pub enum Flavor { Manager, } -/// MCP tools claude is allowed to call without prompting. Mirrors the -/// hyperhive surface so a new tool added in the corresponding `#[tool_router]` -/// impl needs to be listed here too. -#[must_use] -pub fn allowed_mcp_tools(flavor: Flavor) -> Vec { - let names: &[&str] = match flavor { - Flavor::Agent => &[ - "send", - "recv", - "ask", - "answer", - "remind", - "get_loose_ends", - "set_status", - "get_agent_meta", - "cancel_loose_end", - ], - Flavor::Manager => &[ - "send", - "recv", - "request_init_config", - "kill", - "start", - "restart", - "update", - "request_apply_commit", - // The remaining manager tools below were added incrementally - // and have historically been missed in the allow-list when - // their `#[tool]` impls landed. Claude Code's permission gate - // refuses uninlisted tools in non-interactive `--print` mode - // with a "permissions not granted yet" error — keep this - // block in lockstep with the `#[tool]` fns in `ManagerServer`. - "request_update_meta_inputs", - "request_schedule_prompt", - "fire_schedule_now", - "cancel_schedule", - "edit_schedule", - "list_schedules", - "ask", - "answer", - "get_logs", - "get_loose_ends", - "remind", - "set_status", - "get_agent_meta", - "cancel_loose_end", - ], +/// Env var written by the meta renderer with a comma-separated list of +/// `hive_sh4re::ToolGroup` snake_case names (e.g. `"messaging,inbox,meta"`). +/// When present, the harness expands the groups into per-tool allow entries +/// instead of using the hardcoded flavor default. See `docs/conventions.md::Tool groups`. +const TOOL_GROUPS_ENV: &str = "HIVE_TOOL_GROUPS"; + +/// Resolve the active tool groups for a harness session. +/// +/// Reads `HIVE_TOOL_GROUPS` from the environment first. Each comma-separated +/// token is matched (case-insensitive) against the `ToolGroup` serde names +/// (`messaging`, `meta`, `inbox`, `lifecycle`, `approvals`, `scheduling`, +/// `diagnostics`). Unrecognised tokens are logged and skipped. Falls back to +/// the flavor default when the env var is absent or empty. +fn effective_tool_groups(flavor: Flavor) -> Vec { + let raw = match std::env::var(TOOL_GROUPS_ENV) { + Ok(v) if !v.trim().is_empty() => v, + _ => { + // No env var — use the flavor default unchanged. + let defaults = match flavor { + Flavor::Agent => hive_sh4re::ToolGroup::AGENT_DEFAULT, + Flavor::Manager => hive_sh4re::ToolGroup::MANAGER_DEFAULT, + }; + return defaults.to_vec(); + } }; - let mut out: Vec = names + let mut groups = Vec::new(); + for token in raw.split(',') { + let t = token.trim().to_ascii_lowercase(); + // Parse via serde_json (the canonical deserialization path). + match serde_json::from_value::( + serde_json::Value::String(t.clone()), + ) { + Ok(g) => groups.push(g), + Err(_) => tracing::warn!( + token = %t, + "{TOOL_GROUPS_ENV}: unknown tool group, skipping" + ), + } + } + if groups.is_empty() { + tracing::warn!( + "{TOOL_GROUPS_ENV} set but contained no recognised groups; \ + falling back to flavor default" + ); + return match flavor { + Flavor::Agent => hive_sh4re::ToolGroup::AGENT_DEFAULT.to_vec(), + Flavor::Manager => hive_sh4re::ToolGroup::MANAGER_DEFAULT.to_vec(), + }; + } + groups +} + +/// MCP tools claude is allowed to call without prompting, derived from +/// the supplied tool groups. Adding a new `#[tool]` fn to a server impl +/// requires updating the matching `ToolGroup::tools()` slice in hive-sh4re +/// (single source of truth). See `docs/conventions.md::Tool groups`. +#[must_use] +pub fn allowed_mcp_tools(groups: &[hive_sh4re::ToolGroup]) -> Vec { + // Collect all tool names, deduplicating while preserving order. + let mut seen = std::collections::HashSet::new(); + let mut out: Vec = groups .iter() + .flat_map(|g| g.tools()) + .filter(|t| seen.insert(*t)) .map(|t| format!("mcp__{SERVER_NAME}__{t}")) .collect(); // Extra MCP servers declared via `hyperhive.extraMcpServers` in @@ -1822,7 +1834,8 @@ pub fn allowed_tools_arg(flavor: Flavor) -> String { } }) .collect(); - all.extend(allowed_mcp_tools(flavor)); + let groups = effective_tool_groups(flavor); + all.extend(allowed_mcp_tools(&groups)); all.join(",") } diff --git a/hive-sh4re/src/lib.rs b/hive-sh4re/src/lib.rs index 45488fcf..f25557b4 100644 --- a/hive-sh4re/src/lib.rs +++ b/hive-sh4re/src/lib.rs @@ -711,6 +711,81 @@ pub struct SchedulePromptPayload { pub description: Option, } +/// 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