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/turn-loop/README.md

@@ -177,7 +177,7 @@ harness between turns.
 One harness serve binary (`hive-agent`, with its `hive-agent-mcp`
 sibling), one shared `nix/agent-modules/` tree, one service unit
 (`systemd.services.hive-agent`) for all agents. Privilege
-differences live server-side in the broker socket (which tool groups
+differences live in the agent's swarm permissions and the broker socket (which tools
 and manager-surface calls each agent receives).
 
 `agent.nix` and `ruth.nix` both import the shared `nix/agent-modules/`.
@@ -250,7 +250,7 @@ The rest lives alongside this page, in three topic files:
   custom static files, connectivity overrides, claude plugins, cargo message
   filtering).
 - **[mcp.md](mcp.md)** — the MCP tool surface claude sees: core tools,
-  privileged tool groups, self-wake, authoritative state, the tool envelope,
+  permission-gated tools, self-wake, authoritative state, the tool envelope,
   and the built-in tool allowlist.
 
 Per-subsystem impl detail lives in each module's `//!` doc-comment; these pages

docs/turn-loop/mcp.md

@@ -22,10 +22,11 @@ toggle (default `false`) — see
 [`docs/tools/subagent.md`](../tools/subagent.md#mcp-servers-available-to-a-subagent)
 for what reaches a subagent's own `--mcp-config` and what doesn't.
 
-Tool groups (`HIVE_TOOL_GROUPS`) gate tool access. The default
-preset (`AGENT_DEFAULT`) includes `messaging`, `meta`, `inbox`, and
-`execution`. The privileged `lifecycle` group
-is opt-in via the P3RM1SS10NS tab.
+The agent's permissions gate tool access
+([`docs/process/conventions.md#permissions`](../process/conventions.md)).
+The default (`Permission::DEFAULT`) is `messaging`, `meta`, `inbox` and
+`execution`; `swarmctl agent permissions set` changes it, and the next turn
+runs on the change.
 
 ## Core tools (always available)
 
@@ -106,7 +107,7 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
   `homeserver`); omitted for agents with no matrix provisioning. Omit
   `name` to query self.
 
-**Always-on, no tool group**: `set_status(text)`, `compact()`,
+**Always-on, no permission needed**: `set_status(text)`, `compact()`,
 `mark_todos_done(ids)`.
 
 - `set_status` — set a free-text status string visible on the
@@ -130,26 +131,23 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
   unknown or already-done ids are silently skipped. Dials the same
   in-agent todo socket as `cancel_loose_end`'s `todo` kind.
 
-## Privileged tools (by tool group)
+## Privileged tools (by permission)
 
 - **Bash execution** (`execution`) — background shell tasks. See
   [`docs/tools/bash.md`](../tools/bash.md).
 - **Subagent spawning** — nested sessions on the agent's own runtime
   (claude or ACP, via `hive-runtime`) as background tasks, shipped
-  default-on like bash execution; no tool group gates it. See
+  default-on like bash execution; no permission gates it. See
   [`docs/tools/subagent.md`](../tools/subagent.md).
-- **Lifecycle + config** (`lifecycle`) — gates nothing.
-  Config changes go through a forge PR on `agent-configs/<name>` — see
+- **Config changes** — no permission: they go through a forge PR on
+  `agent-configs/<name>` — see
   [`docs/agent-lifecycle/config-changes.md`](../agent-lifecycle/config-changes.md).
-- **Forge repos** (`forge`) — gates nothing.
 - **Web egress** (`web_tools`) — enables Claude's built-in `WebFetch`
   and `WebSearch` tools (not MCP tools; added directly to the
-  `--allowedTools` list). Off by default; add the group in the
-  P3RM1SS10NS tab and rebuild to enable.
-- **Capabilities** — orthogonal to tool groups, set via the P3RM1SS10NS
-  tab. No capability registers an MCP tool today; the full list and their
-  effects are in
-  [`docs/process/conventions.md#capabilities`](../process/conventions.md).
+  `--allowedTools` list). Off by default.
+- **Recovery mounts** (`manage_root_agent`) — no tool: every agent's state
+  and config mounted into this agent's container. See
+  [`docs/process/conventions.md#permissions`](../process/conventions.md).
 - **Matrix MCP + extra servers** — `mcp__matrix__*` tools and
   per-agent extra MCP config. See
   [`docs/tools/matrix.md`](../tools/matrix.md).
@@ -199,7 +197,7 @@ status hint lives in the wake prompt + UI header, not here.
 ## Tool allowlist (`hive_sh4re::permissions::ALLOWED_BUILTIN_TOOLS`)
 
 The built-in list and the `--tools` value it resolves to live in
-`hive-sh4re` alongside `ToolGroup`, not in the harness, because the
+`hive-sh4re` alongside `Permission`, not in the harness, because the
 subagent daemon spawns its own `claude` and must resolve the same set —
 see [`docs/tools/subagent.md`](../tools/subagent.md).
 
@@ -207,15 +205,15 @@ see [`docs/tools/subagent.md`](../tools/subagent.md).
   `Skill` is what makes an installed plugin's `SKILL.md` invokable —
   without it, a skill's `description` frontmatter never gets seen by
   the model no matter how well it matches the task.
-- Tool-group-gated built-ins: `WebFetch`, `WebSearch` (added once the
-  operator enables the `web_tools` tool group — see P3RM1SS10NS tab).
+- Permission-gated built-ins: `WebFetch`, `WebSearch` (added once the
+  agent holds `web_tools`).
 - Denied by omission (absent from the harness `--tools` /
   `--allowedTools`, so they "literally don't exist" in a harness turn):
   `Bash`, `Task`, `NotebookEdit`, `TodoWrite`.
 - Additionally in the managed-settings deny list
   (`/etc/claude-code/managed-settings.json`, un-overridable): `Task`,
   `TodoWrite`. `Bash` **isn't** in the managed deny — see below.
-- Allowed MCP tools: as listed above (by tool group).
+- Allowed MCP tools: as listed above (by permission).
 
 The autonomous harness disallows `Bash` — shell execution goes
 through `mcp__bash__run` (background tasks with structured output +
@@ -230,7 +228,7 @@ completion wake landing in the wrong session (the harness inbox) for a
 choom-started task; `choom` is an operator action (root or `hive-admin`),
 so built-in shell there stays within the existing trust boundary. The bash MCP server
 (`run` / `status` / `kill`) uses `allowedTools = ["*"]` so all
-`mcp__bash__*` tools are always available regardless of tool groups.
+`mcp__bash__*` tools are available whenever the agent holds `execution`.
 
-`WebFetch` / `WebSearch` are off by default; enable the `web_tools`
-tool group in the P3RM1SS10NS tab and rebuild the agent to enable them.
+`WebFetch` / `WebSearch` are off by default; grant `web_tools`
+(`swarmctl agent permissions set`) to enable them from the next turn.