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..29f2793a 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -274,6 +274,47 @@ 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)* | + +**Config storage** — per-agent tool groups live in +`/var/lib/hyperhive/meta/tool-groups.json` (hive-c0re-owned, committed to the +meta repo alongside `topology.json`). Format: `{ "alice": ["messaging", "meta", +"inbox", "lifecycle"], "bob": ["messaging", "meta", "inbox"] }`. An absent entry +means "use role default". Tool permissions are intentionally NOT configurable +from `agent.nix` — that file goes through the manager's approval flow, so +letting it declare its own groups would let the manager grant itself any tool by +submitting a config commit, bypassing the operator gate. + +**Setting groups** — the operator sets groups via the dashboard or +`hive-c0re::tool_groups::set_groups(name, groups)`. After a change +`meta::sync_agents` commits the updated file; the next agent rebuild picks up +the new `HIVE_TOOL_GROUPS` env var. Agents with no entry get no var. + +**Runtime resolution** — at session start the harness reads `HIVE_TOOL_GROUPS` +(a comma-separated list of snake_case group names injected by the meta renderer +from `tool-groups.json`). 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-c0re/src/lib.rs b/hive-c0re/src/lib.rs index b95dd58f..2c1f808e 100644 --- a/hive-c0re/src/lib.rs +++ b/hive-c0re/src/lib.rs @@ -45,4 +45,5 @@ pub mod scheduled_prompts; pub mod scheduled_prompts_worker; pub mod server; pub mod stats_vacuum; +pub mod tool_groups; pub mod topology; diff --git a/hive-c0re/src/meta.rs b/hive-c0re/src/meta.rs index 9b602407..17fb79dc 100644 --- a/hive-c0re/src/meta.rs +++ b/hive-c0re/src/meta.rs @@ -141,6 +141,13 @@ pub async fn sync_agents( if crate::topology::topology_path().exists() { git(&dir, &["add", "topology.json"]).await?; } + // Stage tool-groups.json when it exists. Created on first + // `set_groups` call (operator-driven); absent = all agents on + // their role defaults, no file needed. git add is a no-op when + // the file is unchanged. + if crate::tool_groups::tool_groups_path().exists() { + git(&dir, &["add", "tool-groups.json"]).await?; + } nix(&dir, &["flake", "lock"]).await?; if std::path::Path::new(&dir).join("flake.lock").exists() { git(&dir, &["add", "flake.lock"]).await?; @@ -436,7 +443,7 @@ where let pronouns_escaped = operator_pronouns.replace('\\', "\\\\").replace('"', "\\\""); let _ = writeln!( out, - " dashboardPort = {dashboard_port};\n operatorPronouns = \"{pronouns_escaped}\";\n mkAgent = {{ name, isManager, port, parent ? null }}:" + " dashboardPort = {dashboard_port};\n operatorPronouns = \"{pronouns_escaped}\";\n mkAgent = {{ name, isManager, port, parent ? null, toolGroups ? null }}:" ); out.push_str( r#" let @@ -446,6 +453,7 @@ where input = inputs."agent-${name}"; service = if isManager then "hive-m1nd" else "hive-ag3nt"; parentEnv = if parent == null then {} else { HIVE_PARENT = parent; }; + toolGroupsEnv = if toolGroups == null then {} else { HIVE_TOOL_GROUPS = toolGroups; }; in base.extendModules { modules = [ @@ -477,7 +485,7 @@ where HIVE_LABEL = name; HYPERHIVE_STATE_DIR = "/agents/${name}/state"; }; - systemd.services.${service}.environment = parentEnv // { + systemd.services.${service}.environment = parentEnv // toolGroupsEnv // { HIVE_PORT = toString port; HIVE_LABEL = name; HIVE_DASHBOARD_PORT = toString dashboardPort; @@ -527,19 +535,32 @@ where // (every container at root). `meta::sync_agents` seeds the file // on first run with manager as root + everyone else under manager. let topology = crate::topology::read(); + let tool_groups_map = crate::tool_groups::read(); for spec in agents { let parent_attr = topology .get(&spec.name) .and_then(|p| p.as_ref()) .map_or_else(|| "null".to_owned(), |p| format!("\"{p}\"")); + // Emit `toolGroups = "group1,group2"` when the operator has + // explicitly configured groups for this agent. Absent entry = null + // = harness falls back to its role default (no env var emitted, + // no rebuild cascade for agents whose groups haven't changed). + let groups = tool_groups_map.get(&spec.name).cloned().unwrap_or_default(); + let tool_groups_attr = if groups.is_empty() { + "null".to_owned() + } else { + let joined = groups.join(","); + format!("\"{joined}\"") + }; let _ = writeln!( out, - " {} = mkAgent {{ name = \"{}\"; isManager = {}; port = {}; parent = {}; }};", + " {} = mkAgent {{ name = \"{}\"; isManager = {}; port = {}; parent = {}; toolGroups = {}; }};", spec.name, spec.name, if spec.is_manager { "true" } else { "false" }, spec.port, parent_attr, + tool_groups_attr, ); } out.push_str(" };\n };\n}\n"); diff --git a/hive-c0re/src/tool_groups.rs b/hive-c0re/src/tool_groups.rs new file mode 100644 index 00000000..c9341709 --- /dev/null +++ b/hive-c0re/src/tool_groups.rs @@ -0,0 +1,88 @@ +//! Per-agent tool-group configuration. Stored at +//! `/var/lib/hyperhive/meta/tool-groups.json` alongside `topology.json` +//! and the meta `flake.nix`. +//! +//! Format: a JSON object mapping agent name to an array of +//! `hive_sh4re::ToolGroup` snake_case strings: +//! +//! ```json +//! { +//! "alice": ["messaging", "meta", "inbox", "lifecycle"], +//! "bob": ["messaging", "meta", "inbox"] +//! } +//! ``` +//! +//! An absent entry (or an absent file) means "use the harness role +//! default" — agents get `messaging + meta + inbox`, the manager gets +//! all groups. `render_flake` in `meta.rs` reads this file and +//! injects `HIVE_TOOL_GROUPS` into each agent's systemd service env; +//! agents with no entry get no env var and the harness falls back. +//! +//! Write path: `set_groups` is called from the dashboard action handler +//! that the operator uses to grant/revoke tool groups per agent. +//! The manager may also request group changes via an approval; hive-c0re +//! applies the change on approval, commits the file, and cascades a rebuild. + +use std::collections::BTreeMap; +use std::path::PathBuf; + +const TOOL_GROUPS_FILE: &str = "tool-groups.json"; + +#[must_use] +pub fn tool_groups_path() -> PathBuf { + crate::meta::meta_dir().join(TOOL_GROUPS_FILE) +} + +/// Read the per-agent tool-group map. Returns an empty map when the +/// file is absent or unparsable — callers treat a missing entry as +/// "use role default". +#[must_use] +pub fn read() -> BTreeMap> { + let path = tool_groups_path(); + let Ok(raw) = std::fs::read_to_string(&path) else { + return BTreeMap::new(); + }; + serde_json::from_str(&raw).unwrap_or_default() +} + +/// Look up the configured tool groups for one agent. Returns an empty +/// vec when the agent has no entry — callers should treat this as +/// "use the harness role default." +#[must_use] +pub fn groups_for(name: &str) -> Vec { + read().get(name).cloned().unwrap_or_default() +} + +/// Persist the full tool-groups map. Sorted JSON output keeps diffs +/// minimal. Best-effort — returns `io::Error` so callers decide +/// whether to abort or log. +pub fn write(map: &BTreeMap>) -> std::io::Result<()> { + let path = tool_groups_path(); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + let text = serde_json::to_string_pretty(map) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + std::fs::write(&path, format!("{text}\n")) +} + +/// Set the tool groups for one agent and persist the map. An empty +/// `groups` vec removes the entry (agent reverts to role default). +pub fn set_groups(name: &str, groups: &[String]) -> std::io::Result<()> { + let mut current = read(); + if groups.is_empty() { + current.remove(name); + } else { + current.insert(name.to_owned(), groups.to_vec()); + } + write(¤t) +} + +/// Drop the entry for an agent that is being destroyed. Idempotent. +pub fn remove_agent(name: &str) -> std::io::Result<()> { + let mut current = read(); + if current.remove(name).is_some() { + write(¤t)?; + } + Ok(()) +} 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