# Agent roster and privileges

Agents are a **flat set**: no agent manages another by position. The
`manage_root_agent` permission is the one grant that reaches another agent.

## Who is on the roster

The swarm decides. An agent exists in the swarm if and only if it has an identity
in the swarm's authelia identity store, which `swarmctl agent create` or the
swarm UI writes once. `GET /api/agents` on the swarm controller lists them.

Each hive also keeps a small file of its own, `topology.json`, with the agents
this hive has state or config for. You never edit it: the hive rebuilds it from
what it sees locally, so a hand edit is overwritten, and one that doesn't parse
stops the rebuild until you fix it. It matters for one thing, covered next.

## Who may reach whose state

An agent holding no permission sees its own directories and nothing else. An
agent holding `manage_root_agent` gets every other agent's `state` directory on
this hive mounted read-write at `/agents/<name>/state`, never `config` or
`harness`. It's the only grant that reaches another agent's state. Ruth, the
root agent, holds it, and the swarm UI's setup assistant creates her with it. The
mounts follow the roster: an empty file means no mounts until the next rebuild.

## The manager is a normal agent

`ruth` differs from other agents in her name and in that grant. You create her
like any other agent, from the swarm UI or `swarmctl agent create`; the hive
creates nothing at boot. Her permissions, prompt and tools work as for every
agent, and destroying her is as final as for any other.

How the hive reads and rebuilds the file, the wire protocol and the prompt blocks:
[`roster.md`](../../4-implementation/agent-state/roster.md). The operator/agent
trust boundary is a separate axis: [`boundary.md`](../hives/boundary.md).