agent permissions: one set, tool groups included, set at agent creation

mara on #5170: "dont split caps and perms. its all perms. / dont include
the now empty tool groups / nothing set -> default / also add perms to
agent creation screen".

- hive-sh4re: one `Permission` enum (messaging, meta, inbox, execution,
  web_tools, manage_root_agent) replaces `ToolGroup` and `Capability`;
  `lifecycle`/`forge` are gone. `Permission::default_for` is the default
  for an agent the swarm sets nothing for.
- The record is `{ "permissions": [...] }`. Missing key, unset field or
  no successful read yet = default; `[]` = none; a failed read after a
  good one keeps the last value.
- hive-agent reads its own key every 10s and builds each turn's --tools,
  --allowedTools and MCP config (rewritten before every turn) from it;
  the subagent daemon reads it on each start/continue. Agents get a
  read-only grant on their own key.
- hive-c0re restarts an agent only when its manage_root_agent changes.
  The import now merges meta/capabilities.json and meta/tool-groups.json
  into one list per agent and deletes both; the "import pending, don't
  read" decision is `ImportOutcome::read_allowed`, table-tested.
- swarm-controller: `GET /api/permissions` (names + default) and an
  optional `permissions` on `POST /api/agents`, stored before the job is
  queued. swarm-ui's create-agent form gets a permissions field.
- Deleted: HIVE_TOOL_GROUPS and its forward to the subagent daemon,
  tool_groups.rs, ruth's tool-group seed, the permissions rebuild job
  (PermPayload/WritePermFile/perm_change), the dashboard permissions tab
  and its stale-entries panel.

Part of #5170.

docs/tools/bash.md

@@ -7,11 +7,12 @@ 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
+holds the **`execution`** permission: `extra_server_required_permission` 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.
+permission, so an agent lacking `execution` gets no `mcp__bash__*` tools at
+all, not just an unused grant. The harness rewrites the config each turn,
+so a change applies at the next one. See "Relationship to the
+`execution` permission" below.
 
 ## Tools
 
@@ -122,14 +123,14 @@ unread rooms. An inline `wait_seconds` / `status` observation that already
 delivered the result instead clears the keyed todo, so no redundant
 loose-end follows.
 
-## Relationship to the `execution` tool group
+## Relationship to the `execution` permission
 
-`ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash:
-`extra_server_required_group` (in `hive-agent/src/mcp_config.rs`)
+`Permission::Execution` (in `Permission::DEFAULT`) is the real gate on bash:
+`extra_server_required_permission` (in `hive-agent/src/mcp_config.rs`)
 controls whether the `bash` MCP server reaches the agent's claude
 config at all, suppressing every `mcp__bash__*` tool
 when absent — not just leaving them unused. Its own `tools()` returns
 `&[]`: `mcp__bash__run`/`status`/`kill` live on the separate `bash` MCP
-server that `extra_server_required_group` gates, not on the
+server that `extra_server_required_permission` gates, not on the
 `mcp__hyperhive__*` allowlist `tools()` builds. Removing `execution`
-from an agent's groups **does** remove bash availability.
+from an agent's permissions **does** remove bash availability.

docs/tools/subagent.md

@@ -399,23 +399,24 @@ particular `--tools` does **not** filter `mcp__*` tools.
 
 **A subagent gets exactly the built-ins its parent agent has, plus one
 deliberate exception** — the base resolution
-(`hive_sh4re::permissions::subagent_builtin_tools_arg`, wrapping the
-harness's own `builtin_tools_for`) from the same `HIVE_TOOL_GROUPS`:
+(`hive_sh4re::permissions::subagent_builtin_tools_for`, wrapping the
+harness's own `builtin_tools_for`) over the agent's permissions, which the
+daemon reads from the swarm on each `start`/`continue`:
 `Edit`, `Glob`, `Grep`, `Read`, `Skill`, `Write`, plus `WebFetch`/
-`WebSearch` for an agent granted the `web_tools` tool group and not
-otherwise. See
+`WebSearch` for an agent granted `web_tools` and not otherwise. A running
+subagent keeps the tools it started with. See
 [the harness's own allowlist](../turn-loop/mcp.md#tool-allowlist-hive_sh4repermissionsallowed_builtin_tools)
 for what that list contains and why.
 
 The exception: **a subagent gets Claude's built-in `Bash` iff its parent
-holds the `execution` tool group** — the group that already grants the
+holds the `execution` permission** — the permission that already grants the
 parent shell execution, via the out-of-process `bash` MCP server
 (`mcp__bash__run`/`status`/`kill`). A subagent has no MCP server of its
 own by default (see [MCP servers](#mcp-servers---strict-mcp-config)
 below), so there is no `mcp__bash__*` for it to inherit that capability
 through; it gets Claude's own tool instead. The rule is the capability
 transfers, not the mechanism — the parent itself never gains built-in
-`Bash` no matter which groups it holds, only a subagent spawned by an
+`Bash` no matter which permissions it holds, only a subagent spawned by an
 `execution`-holding parent does.
 
 Inheriting rather than listing is the point: a hardcoded subagent list

docs/tools/swarmctl-cli.md

@@ -70,7 +70,7 @@ Manage agents across the swarm
 * `create` — Queue creation of a new agent on a hive in this swarm
 * `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale
 * `inference` — Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models
-* `permissions` — Show or change the capabilities the swarm grants an agent
+* `permissions` — Show or change the permissions the swarm grants an agent
 
 
 
@@ -205,23 +205,23 @@ Clear every field for an agent, so it goes back to its own values
 
 ## `swarmctl agent permissions`
 
-Show or change the capabilities the swarm grants an agent.
+Show or change the permissions the swarm grants an agent.
 
-The hive running the agent reads them every 30 seconds and, when they change, restarts the agent after its current turn. Unset leaves the agent on its hive's default: none, except `ruth`, who gets `manage_root_agent`.
+The agent applies its tool permissions at its next turn; the hive running it restarts it, after its current turn, when `manage_root_agent` changes. Unset leaves the agent on the default: `messaging`, `meta`, `inbox`, `execution`, plus `manage_root_agent` for `ruth`.
 
 **Usage:** `swarmctl agent permissions <COMMAND>`
 
 ###### **Subcommands:**
 
-* `get` — Show the capabilities the swarm grants an agent, or that it sets none
-* `set` — Replace the capabilities the swarm grants an agent
-* `clear` — Clear the agent's permissions, so its hive's default applies again
+* `get` — Show the permissions the swarm grants an agent, or that it sets none
+* `set` — Replace the permissions the swarm grants an agent
+* `clear` — Clear the agent's permissions, so the default applies again
 
 
 
 ## `swarmctl agent permissions get`
 
-Show the capabilities the swarm grants an agent, or that it sets none
+Show the permissions the swarm grants an agent, or that it sets none
 
 **Usage:** `swarmctl agent permissions get [OPTIONS] <AGENT>`
 
@@ -239,9 +239,9 @@ Show the capabilities the swarm grants an agent, or that it sets none
 
 ## `swarmctl agent permissions set`
 
-Replace the capabilities the swarm grants an agent
+Replace the permissions the swarm grants an agent
 
-**Usage:** `swarmctl agent permissions set [OPTIONS] --capabilities <CAPABILITIES> <AGENT>`
+**Usage:** `swarmctl agent permissions set [OPTIONS] --permissions <PERMISSIONS> <AGENT>`
 
 ###### **Arguments:**
 
@@ -249,7 +249,7 @@ Replace the capabilities the swarm grants an agent
 
 ###### **Options:**
 
-* `--capabilities <CAPABILITIES>` — The capabilities to grant, comma-separated (`manage_root_agent`). `--capabilities ''` grants none
+* `--permissions <PERMISSIONS>` — The permissions to grant, comma-separated: any of `messaging`, `meta`, `inbox`, `execution`, `web_tools`, `manage_root_agent`. `--permissions ''` grants none
 * `--controller-socket <PATH>` — swarm-controller's unix socket.
 
    Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
@@ -258,7 +258,7 @@ Replace the capabilities the swarm grants an agent
 
 ## `swarmctl agent permissions clear`
 
-Clear the agent's permissions, so its hive's default applies again
+Clear the agent's permissions, so the default applies again
 
 **Usage:** `swarmctl agent permissions clear [OPTIONS] <AGENT>`