Agent Permissions
Explicit permission model controlling which agents can communicate with which. Restrictive by default — no agent can call another without explicit permission.
Reach is drawn, not inherited
1:406 chapters
Staffing an Entire Agency — wiring permissions so four agents can talk
Oct 2026
Trinity Platform Demo
May 2026
How It Works

Open the detail page of the agent that will make the calls and click its Permissions tab (next to Channels). The tab is shown to the agent's owner and admins, and never on the system agent.
You will see a list of the other agents in the system.
Toggle each agent to allow or deny the current agent calling it. You can only grant access to agents you can access yourself. Allow All and Allow None set every row at once. Click Save Permissions to apply.
Permissions are directional: allowing Agent A to call Agent B does not allow Agent B to call Agent A. Each direction must be granted separately.
System agents (e.g., trinity-system) bypass permission checks entirely.
Default Behavior
trinity-system) can call any agent without requiring permission.Enforcement
chat_with_agent("agent-b", ...), the MCP server checks whether Agent A has permission to communicate with Agent B.Access denied result and the call is blocked. An agent can always reach itself, and the agents it spawned./api/tags counts, the event-subscription list, container telemetry, the operator queue, the agents named on each row of GET /api/subscriptions, the onboarding roster and the /ws/events stream all answer an agent key with its reach: itself, the agents it may call, and the agents it spawned with its current key — never its owner's whole fleet, even when the owner is an admin. The stream's roster is re-read when an agent is created, deleted, shared, unshared or renamed, so a newly spawned child appears without a reconnect. Two fleet sweeps that carry no task text or emails keep the owner's view: GET /api/fleet/sync-audit and GET /api/monitoring/status (get_fleet_health). GET /api/mcp/keys/{id} answers an agent key for its own key only. System views, the /ws ticket and the proactive-share switch are for people only, so an agent key gets 403 there. Deploying a version over an agent name the key cannot manage is refused (403, NAME_OWNED_BY_ANOTHER_USER) before anything is stopped.run_agent_loop) and reading or stopping that loop (get_loop_status, stop_loop). See Agent Loops.get_metrics with agent set to the target). These cross-agent reads count against the reader's own rate budget and are recorded in the audit log.Which Skills a Permission Lets the Caller Run
A peer may run what an agent declares; what an admin assigned needs a grant.
skill_not_granted and nothing runs. The refusal is recorded in the audit log. A message that only mentions such a skill with a leading slash (/skill-name) is refused too; writing the name without the slash delivers it.get_agent_skills marks each library skill with peer_needs_grant.When a Withdrawn Permission Takes Effect
Each control re-reads the permission at a different moment, so removing one (or replacing the set with Save Permissions) reaches each at a different time:
| Control | Checked | A withdrawn permission stops it |
|---|---|---|
Calling the agent (chat_with_agent, loops, reading its work) | on every call | at the next call |
| Event subscriptions | when the subscription is created, and again on every delivery | at the next event. The subscription itself is kept, so granting the permission again resumes it |
| Shared folders the agent reads from the other agent | when the container is built | at the agent's next start, which rebuilds it without that folder. Restart the agent to apply it immediately; until then a running agent keeps the folder mounted |
Turning Mount Shared Folders off on the consuming agent works the same way: the next start removes every shared-in folder it still has.
For Agents
get_agent_permissions. The list is observed within the caller's view (observed_within): an edge whose target has no container, or that you cannot reach, is not listed, so a missing edge is not a removed edge. Granting stays in the UI.Access denied result and ask the owner for a grant.API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/agents/{name}/permissions | GET | The agents this agent may call (any user with access to the agent) |
/api/agents/{name}/permissions | PUT | Replace the whole set (owner or admin; human only) |
/api/agents/{name}/permissions/{target} | POST | Grant one target (owner or admin; human only) |
/api/agents/{name}/permissions/{target} | DELETE | Withdraw one target (owner or admin; human only) |
/api/agents/permissions-edges | GET | Every permission edge between agents you can access, in one call |
/api/agents/{name}/peer-skills | GET | For each agent name may call: the library skills on it, and whether name may run each |
/api/agents/{name}/peer-skills/{target}/{skill} | PUT | Let name run the library skill skill on target (admin; human only) |
/api/agents/{name}/peer-skills/{target}/{skill} | DELETE | Take that grant back (admin; human only) |
/api/skills/peer-grants/drift | GET | Calls between agents that used a library skill in the last 30 days and are now refused (admin) |
/api/agents/{name}/reach/{target} | GET | Whether name may call target — {source_agent, target_agent, reachable}, decided from the permission or the spawn record, never from which containers are running. The MCP server's agent-to-agent check reads it |
Every grant, replacement and withdrawal is written to the audit log.