Roles
A role is a spawn-time profile that decides whether a spawned
agent may itself delegate — spawn or drive further children — and,
if so, which roles it's allowed to spawn. It's set once, at
agent_start, and enforced by the daemon for the life of the
session.
Roles are an MCP/HTTP surface today — there is no agentproto sessions start --role flag. Set role on the agent_start MCP tool
or the POST /sessions/agent HTTP body; see below.
The 3-layer profile
A role bundles three things:
disposition— a system-prompt fragment prepended to the child's first turn. Soft: it sets the mindset ("you are the leaf, do the work yourself" vs. "decompose, delegate, verify"), but nothing stops a capable model from ignoring it if the tools to disobey are still in its hands.toolPolicy.delegation("allow"|"deny") — the delegation gate. When"deny", the daemon tries to keepagent_start/agent_promptout of the child's toolset at spawn time — but this is spawn-path-specific and, on the default gateway, not airtight. It's a real gate on the orchestrator sub-gateway path and a best-effort default elsewhere; see below for which paths it covers and where it leaks.skills[]— declared but currently inert. The field is typed onRoleProfile(role.ts:33) and parsed from a role pack'sROLE.md(role-pack.ts:84), but nothing in the spawn path readsrole.skills—session-spawn.tsonly consults theagent_startcall's ownskillsand the configdefaults.skills(session-spawn.ts:580,652).role.ts:12-13flags it as intended for "a future pack-carried role"; treat it as unimplemented, not a working per-role skill set.
Plus two fields that place the role in the spawn lattice:
level(number) — privilege level; higher is more privileged.spawnableRoles(optional string array) — a closed allowlist of role names this role may spawn, by name. When set, it replaces the level comparison below for this role.
How the delegation gate works
toolPolicy.delegation is resolved at the agent_start injection
point (session-spawn.ts:510), before the child runs — but it is not
one universal, airtight gate. It acts through two separate spawn-time
mechanisms, and a third path escapes it entirely:
- Orchestrator sub-gateway — genuinely gated. A role that denies
delegation has its
orchestratorrequest dropped outright, whatever the caller asked for (session-spawn.ts:547, guarded on!delegationDenied). The scoped sub-gateway (/mcp/orchestrator) is the only path that mountsagent_start/agent_promptfor an orchestrating child, and it demands a scope token — it deliberately does not inherit the loopback bypass (http-server.ts:668-675). A denied role never receives the sub-gateway, so it has nothing to spawn with. - hermes default gateway — best-effort, loopback-open. Only when
the adapter is
hermesand the caller passed no explicitmcpServers, the daemon defaults the child to its own/mcpURL, and for a denied role appends?denyTools=agent_start,agent_prompt(session-spawn.ts:538-542;DELEGATION_TOOL_NAMES,role.ts:64). The daemon reads that deny-list back from the requesting URL's own query string (parseDenyToolsQuery→handleMcp,http-server.ts:652-666), not from a trusted per-session registry. And the bare/mcpendpoint is loopback-open: any request from127.0.0.1/::1without anX-Forwarded-Forheader skips the token check (authorize/isLoopback,http-server.ts:479-491). A co-located child handed the gated URL can therefore reconnect to the plain/mcpand getagent_start/agent_promptback — on this path the strip is a default, not a wall. - Caller-supplied
mcpServers/ non-hermes adapters — not touched. If the caller passes explicitmcpServers, or the adapter isn'thermes, thedenyToolsdefault never fires (session-spawn.ts:525,538). Whatever delegation tools such a child ends up with are whatever the caller wired;toolPolicy.delegationdoes not reach in and remove them.
The part that toolPolicy locks down hard is the orchestrator sub-gateway:
promptAppend can't re-open it (it's never consulted at the drop,
session-spawn.ts:547) and a child can't mint its own scope token.
promptAppend layers text on top of the resolved role's disposition —
it can specialize it, never replace it. Beyond that path,
delegation-deny is a spawn-time default the child's own wiring can
route around, not a universal sandbox — and the daemon still cannot
strip a native CLI subagent/Task tool it never routed in the first
place (see the built-ins below).
The two built-ins
| Role | level | toolPolicy.delegation | Disposition |
|---|---|---|---|
executor | 0 | deny | Leaf — execute the task directly, never spawn or delegate. |
supervisor | 100 | allow | Decompose, delegate the parts that benefit from a separate agent, verify their output. |
Both built-in dispositions explicitly tell the agent not to use its own
CLI's native subagent/Task tool: the daemon cannot strip tools that are
not routed through its MCP gateway, so the rule must be followed in the
prompt. executor is told never to spawn or delegate; supervisor is
told to delegate via agent_start so the caller gets an observable
session.
executor is the floor of the lattice — canSpawn short-circuits to
false for any role whose own delegation is "deny"
(role.ts:192-194), before the level comparison, so an executor may
spawn nothing, not even a peer at its own level. Whether the child even
holds agent_start to attempt it is the separate, weaker toolset
question covered above.
Role-level default for deferred tool loading
A role can also carry a deferredTools default (role.ts's
RoleProfile.deferredTools, optional boolean). executor defaults it
on — an executor never delegates anyway (the tool gate above already
strips agent_start/agent_prompt for it), so the daemon's own
~190-tool /mcp surface is mostly dead weight in its context; hiding it
behind tool_search (see deferred-tools.ts) saves real turn-0 tokens
without losing any capability (every tool stays fully callable, just
absent from tools/list until searched). Two harness checks gate when
that role default can take effect: a harness with native tool search
(capabilities.nativeToolSearch, claude-code) is always eager, and a
harness that cannot drive deferred discovery
(capabilities.deferredToolDiscovery absent/false — every adapter today,
including opencode, which validates tool calls against its last
tools/list and rejects a hidden tool client-side with "Model tried to
call unavailable tool ...") is eager too. The role default therefore only
reaches a harness that declares capabilities.deferredToolDiscovery: true.
supervisor has no opinion (undefined) and falls through to
whatever the daemon's own boot-time default is (subject to the same
capability gate).
This composes with the same ?denyTools=-carrying self-mount URL
described above: when the spawn resolves a value — an explicit
agent_start.deferredTools override (which always wins), or any spawn
whose harness checks rule deferral out — session-spawn.ts appends
&deferred=1 or &deferred=0 to the injected mcpServers ref — e.g.
today an executor's hermes self-mount (executor defaults it on, but
hermes declares no deferredToolDiscovery) ends up
...?denyTools=agent_start,agent_prompt&deferred=0&callerSessionId=....
Precedence, highest first: explicit agent_start.deferredTools → a
caller-supplied mount's own ?deferred= → a harness whose manifest declares
capabilities.nativeToolSearch (claude-code ⇒ eager, since it already
defers MCP tools behind its own ToolSearch — see
MCP in coding CLIs)
→ a harness that cannot drive deferred discovery (manifest
capabilities.deferredToolDiscovery absent/false ⇒ eager: it validates
tool calls against its last tools/list, so a tool the daemon hid is
rejected client-side before the call reaches the gateway)
→ the resolved role's deferredTools → (no override at all) the gateway's
own defaults.mcp.deferredTools config.json default, which is off
globally unless an operator opts in.
The same ?deferred=1|0 query works standalone on any /mcp connection
(not just the daemon's own self-mount), and composes with ?denyTools=
exactly like the delegation gate above — denyTools is applied as the
outermost wrap either way, so an excluded tool name never reaches
registration regardless of deferred status.
canSpawn: the non-escalation rule
Every spawn made through an orchestrator sub-gateway (a session
started with orchestrator: true/{...}) is gated by canSpawn(parentRole, childRole), checked before the child's tools are ever injected:
- If the parent's own
toolPolicy.delegationis"deny", it can spawn nothing — full stop. The lattice below is moot. - Else, if the parent has
spawnableRolesset, the child must be named in that allowlist. - Else (the default, open mode): non-escalation —
child.level <= parent.level. A role may spawn a peer or a subordinate, never something more privileged than itself.
Unbounded same-level recursion (a supervisor spawning a supervisor
spawning a supervisor) is allowed by this rule — it's a separate,
deliberate pattern bounded by the orchestrator's maxDepth /
maxChildren caps, not by the role lattice.
Worked example with the built-ins:
supervisor(level 100) may spawnexecutororsupervisor.executor(level 0, delegation denied) may spawn nothing.
A denied spawn returns role_spawn_denied with the parent/child role
names and levels, plus (in allowlist mode) the allowed set.
Delegation gate
AIP-46 makes the spawn authority the calling session's bound agent
delegatesTo, a closed allowlist: a caller may spawn only the agents its
list names. The daemon evaluates it on every nested spawn it can attribute
to a trusted caller, on both the scoped orchestrator sub-gateway and the
unscoped /mcp path. The calling agent is the owner session's recorded
agentSlug. When there is none (the owner is not bound to the scope yet, or
the session predates agentSlug) the scope's role names it, and on the
unscoped path the owner's recorded role does. AIP-46 also says an agent
with no list may spawn nothing; this release does not apply that part, an
agent without a list stays on the level lattice (undeclared, below).
Each spawn gets one of five verdicts:
allowed- the caller's agent declaresdelegatesToand the child is in it.would_deny- the caller's agent declaresdelegatesToand the child is not in it.undeclared- the caller's agent declares nodelegatesTo(a pack role, or a manifest agent whose list is absent, empty or unresolvable); the legacy lattice decides.unbound- a trusted caller session exists but names no agent the daemon can resolve.no_caller- no trusted caller, so this is a root spawn authorized by the host's own auth, not gated here.
defaults.spawn.delegationGate selects the mode:
observe(default) counts every verdict and logs one warning for eachwould_denypair, changing no decision.enforcerefuses awould_denychild withdelegation_denied(details.gate: "agent",details.legacyCode: "role_spawn_denied"). Anallowedchild skips onlycanSpawn's open-mode level comparison: the declared list decides which child, but the parent's own hard gates still apply. A parent whosetoolPolicy.delegationis"deny"can spawn nothing, and a parent withspawnableRolesset must still name the child there —delegatesTocannot widen a closed allowlist.offskips evaluation entirely.
undeclared, unbound and no_caller always fall through to the unchanged
level lattice, so a pack role without a list and every root spawn behave
exactly as before. The counters are in memory (a daemon restart resets them);
GET /permissions/grants exposes them under delegation.
A manifest agent's delegates_to is read once, at spawn: the runtime
resolves each entry to an agent identity (an agent id, optionally
@owner/-prefixed, or a role name) and records the list on the session
(meta.agentDelegatesTo). The gate evaluates that frozen list for a
manifest-bound caller and never re-reads the file, so editing the manifest
and respawning is what applies a change (a restart carries the recorded
list). An absent or empty list is undeclared (the manifest schema
defaults the field to [], so the runtime cannot tell "declares none"
apart; AIP-46's deny-by-default for such agents is not applied yet). An
entry given as a path, file or inline cannot be resolved yet: the spawn
carries a warning and the agent is undeclared. session_continue_fresh
carries the agent binding to its successor, like a restart: the recorded
role, manifest id and delegation list, never a fresh read of the file. An
explicit agent or role in the continuation request wins instead and
nothing is carried.
A manifest-bound child is matched by its manifest id, the same value the
session records as meta.agentSlug, not by the role its manifest resolves
to. A caller whose delegatesTo names only roles ("executor") will
therefore see would_deny for a child spawned via agent/agentId; the
caller must name the manifest id to declare that child.
Profile gate
AIP-46's "no self-widening" rule also covers billing: a spawn may name an
auth profile it is allowed to use, not any profile on the machine. The
daemon evaluates access.profileRef and every access.profileRefs entry
on a nested spawn against the CALLING session's set. That set is the
caller's own recorded accessProfile.profileRef plus
defaults.spawn.sharedProfiles, the operator's grant to every session.
Only the profiles the REQUEST names are evaluated. A profile supplied by a
harness default preset, a session preset, an AGENT.md manifest or a config
layer is operator or author configuration, not a request, and is not gated.
The caller is the same trusted identity the delegation gate uses (the
scope's owner session, else the daemon-derived auto-parent); the
caller-supplied parentSessionId hint is never used. A root spawn and
every continuation path with no trusted caller (continue-fresh, restart,
migrate, cron, retries) is no_caller and is never gated: the host's own
auth authorises it. A trusted caller id the registry does not hold is
caller_unknown and is counted but not gated. A caller that is an
external row (a client the daemon did not spawn, such as Claude Desktop or
a bare CLI) is a label evaluated as anonymous under AIP-46 rule 7: it is
external, counted and never gated.
defaults.spawn.profileGate selects the mode:
observe(default) counts every verdict and logs one warning per would-deny caller/requested-profile pair, changing no decision.enforcerefuses awould_denyspawn withauth_profile_denied(details.gate: "profile",details.denied,details.callerProfiles) before any credential is resolved. A session with no recorded profile has an empty set of its own, so underenforceit may name only the shared profiles.offskips evaluation entirely.
The counters are in memory (a daemon restart resets them);
GET /permissions/grants exposes them under profileUse.
Stdio mount gate
A stdio MCP entry in agent_start.mcpServers names an arbitrary command
the agent CLI launches, which is command execution outside
.agentproto/allowed-commands.json unless it is evaluated. The daemon
evaluates only the stdio entries the REQUEST names: a session may mount
only a command the workspace command allowlist admits, through the same
evaluator command_execute uses (a basename match, plus an argv-prefix
match when the entry constrains args). An http or sse entry is never a
stdio mount. Mounts supplied by a preset, an AGENT.md manifest, a bundle, a
config layer or the daemon's own injected servers are not a request and are
not evaluated.
The caller is the same trusted identity the other gates use (the scope's
owner session, else the daemon-derived auto-parent); the caller-supplied
parentSessionId hint is never used. A root spawn and every continuation
path with no trusted caller (continue-fresh, restart, migrate, cron,
retries) is no_caller and is never gated: the host's own auth authorises
it. A trusted caller id the registry does not hold is caller_unknown, an
external row (Claude Desktop, a bare CLI) is a label evaluated as
anonymous under AIP-46 rule 7, and a sandboxed spawn launches the server
inside the box rather than on the host: all three are counted and never
gated.
defaults.spawn.stdioMountGate selects the mode:
observe(default) counts every verdict and logs one warning per would-deny command basename, changing no decision.enforcerefuses awould_denyspawn withstdio_mount_denied(details.gate: "mount",details.deniedas{ name, command }) before any tool injection or credential resolution.offskips evaluation entirely.
The counters are in memory (a daemon restart resets them);
GET /permissions/grants exposes them under stdioMounts. The limits are
the same as command_execute's: the allowlist is the daemon boot
workspace's, not a per-session one, and env is not evaluated, so a mount
can still set PATH or NODE_OPTIONS for an allowlisted command. An
interpreter allowlisted without an argv constraint (node, python3)
admits node -e ... exactly as it does for command_execute.
Requiring proof to spawn
AIP-46 §Session principals has three proof levels. A caller is proven when
it presents a credential: a scoped orchestrator's scope token, or a session
token the daemon minted for the session it names. It is claimed when it
only names a session, and none when it names none. On loopback, none is
the operator the daemon trusts (CLI, hooks, desktop), and it is never
refused. A kind: "external" identifier (a bare Claude Desktop or CLI
label) is evaluated as anonymous, and an id the registry does not hold is
caller_unknown; neither is refused.
defaults.identity.requireProof lists the actions that require proven. It
is empty by default and today only "session:spawn" is evaluated
(session:control and auth-profile:use follow later). A claimed caller
of a listed action is refused identity_unverified; a caller whose session
token was minted for another session than its claim is refused
identity_mismatch. Both happen before any other spawn gate or side effect.
A scoped orchestrator child is proven by its scope token, so nothing
changes for it.
The list is opt-in because enforcement never outruns delivery (AIP-46 rule
8): a session whose adapter or placement cannot carry a token (codex,
opencode, a sandboxed session, one spawned while sessionTokens was off)
can never be proven, and would stop being able to spawn the moment the action
was listed. The gate is also ignored while
defaults.identity.sessionTokens is "off": no token is minted, so nobody
could be proven, and the reading is counted as requireProofIgnored with one
warning.
Before listing anything, read GET /identity. Its spawnProof block counts
every verdict, splits claimed by whether a token was ever deliverable
(claimedByClass.delivered / undelivered), and reports wouldRefuse
(claimed plus mismatch), refused, and requireProofIgnored since the
process started. The counters are in memory and reset on a restart; the
warning line for a new verdict/class pair is the durable record. A claimed
caller on an undelivered adapter cannot spawn while the action is listed,
so check that split before turning it on.
The same proof gate and the same trusted caller id are used by the
delegation, auth-profile and stdio mount gates. A session spawning over the
HTTP routes (POST /sessions/agent, POST /sessions/chat) now carries its
trusted caller id into all of them too, so those spawns are judged by the
three gates instead of reading no_caller.
The limits: only session:spawn is evaluated today; a session that omits
both its token and its claim is indistinguishable from the operator under the
loopback trust model; and the counters live in memory, so a restart starts a
new reading window.
Depth-derived default
Omitting role (and agent) on agent_start doesn't leave the child
roleless; it binds the agent named by defaults.spawn.defaultAgent.root
below the depth cutoff and by defaults.spawn.defaultAgent.nested at or
above it. Today's values are supervisor (root) and executor (nested):
depth < cutoff → supervisor, depth >= cutoff → executor. The
cutoff still defaults to 1 and is overridable via
defaults.defaultRoleDepthCutoff in ~/.agentproto/config.json; that key
is deprecated and removed with role in @agentproto/runtime 6.0.0, while
it stays the depth boundary between the two defaults. The session records
the bound agent as meta.agentSlug, which a message envelope exposes as
from.agentSlug.
Introspection
role_list
The role_list MCP tool enumerates every role the daemon currently
knows — the two built-ins plus any installed role pack — read-only,
pure visibility into the same registry agent_start's role field
and the spawn gate use:
{
"roles": [
{ "name": "executor", "level": 0, "delegation": "deny", "spawnable": [], "delegatesTo": [] },
{ "name": "supervisor", "level": 100, "delegation": "allow", "spawnable": ["executor", "supervisor"], "delegatesTo": ["supervisor", "executor"] }
]
}spawnable is precomputed with the same canSpawn check the daemon
uses at spawn time, so a caller can discover what it may spawn before
attempting agent_start with orchestrator. Each row also carries
delegatesTo, the agents the role declares it may spawn, which the
delegation gate evaluates; the key is omitted when the role declares
none, while an explicit empty array is kept. Manifest agents are not
listed: role_list shows roles, a manifest agent's list lives on its
session.
The "Roles you may spawn" context line
When a delegating role's disposition is composed into the child's first turn, a line is appended automatically if its spawnable set is non-empty:
Roles you may spawn: executor, supervisor.This lets a delegating agent know its options at runtime instead of
guessing. It's omitted entirely for a role with an empty spawnable
set (an executor sees nothing extra).
Pack-carried custom roles
Beyond the two built-ins, a role can be installed as a role pack
— discovered the same way skill packs are (packages/cli/src/commands /skill-install):
- Standalone:
<dir>/roles/<slug>/ROLE.md, one folder per custom role —~/.agentproto/roles/<slug>/ROLE.mdin production. - Adapter-carried: any installed
@agentproto/adapter-*package may declaremetadata.roles: string[], each entry rawROLE.mdmarkdown embedded directly in the package.
ROLE.md format
Frontmatter (flat key: value, dotted keys, comma-separated lists —
no YAML dependency) plus a body that becomes the disposition
verbatim:
---
role: reviewer
level: 50
toolPolicy.delegation: deny
skills: code-review, security-review
---
You review code for correctness and security issues. You do not
edit files or spawn sub-agents — flag problems, suggest fixes, and
let the calling agent decide what to do with your findings.Required fields: role (the name), level (a finite number),
toolPolicy.delegation (allow or deny). Optional: skills,
spawnableRoles (both comma-separated) — but skills is parsed and
then ignored (see the 3-layer profile); only
spawnableRoles currently affects behavior. A malformed ROLE.md throws
when parsed directly, but registry loading treats a broken pack as
partial-discovery-safe — it's skipped, not fatal to the whole
registry.
contextFiles (optional, comma-separated tag=path entries) names files
whose content the daemon injects into the spawn prompt, fenced by
<tag>...</tag>, right after the role disposition. ~, $VAR and ${VAR}
are expanded in the path (an entry whose variable is unset is skipped). A
missing or unreadable file is announced as <tag absent="path"/> instead of
failing the spawn, and a file over 64 KiB is truncated with a marker. Example:
templates/roles/recherche/ROLE.md,
which puts the repo map in front of an agent asked to search "globally".
Only effective when the spawn carries a plain-string prompt, like the
disposition itself.
Spec status: contextFiles is a host extension of the pack-carried role
surface, which no AIP defines. AIP-46 (§"There is no role on this surface")
treats the spawn-time role as a deprecated private alias for a built-in
AGENT, and AIP-47's ROLE.md (role/v1, an organizational role) is a different
document. The spec-aligned home for "context injected at spawn" is an AIP-42
AGENT field; until the spec gains one, this stays a documented host extension.
Paths must be absolute, ~/... or start with $VAR (a relative path is
rejected at parse time). Trust: the daemon reads these files on the host
with its own rights and the bytes go to the model provider, outside any
session read grant or command sandbox, so only install role packs you trust.
The files are skipped for device sandbox spawns (like AGENTS.md and RULES.md)
and when the role falls back to the executor disposition. Reads are bounded
(at most 64 KiB, regular files only), truncated on a UTF-8 boundary, and a
</tag> inside the file cannot close the fence.
Built-ins always win a name collision — a pack cannot shadow or
widen executor/supervisor, regardless of where the merged
registry is consumed (resolveRole, listRoles, spawnableRolesFor
all merge through the same function).
Trust boundary
Installing a role pack is an operator decision, same as installing an
adapter or a skill pack — a ROLE.md can declare
toolPolicy.delegation: allow at any level. The optional
maxGrantableDelegation knob (defaults.maxGrantableDelegation in
config.json) caps this: a pack that self-grants allow at a level
above the configured cap is forced to deny at load time — the pack
still declares its intent, but the daemon refuses to grant it. No cap
configured means no restriction.
Relationship to --orchestrator
These answer different questions:
- Role — may this child delegate at all, and if so, to whom?
The gate. Set via
roleonagent_start. --orchestrator— mount the scoped sub-gateway so it actually can. Set viaorchestratoronagent_start(CLI:--orchestrator/--orchestrator-json, seeverbs/sessions.md).
A role that denies delegation drops orchestrator outright, no
matter what the caller requested. A role that allows delegation still
needs orchestrator (or caller-supplied mcpServers) mounted before
it has anything to spawn with.
CLI surface
agentproto sessions start does not currently expose a --role or
--prompt-append flag — role assignment is MCP/HTTP-only:
- MCP:
agent_start'srole(string) andpromptAppend(string) fields. - HTTP: the same fields on the
POST /sessions/agentbody.
role_list is likewise MCP-only today; there is no agentproto role-list verb.
Plugins
A plugin extends agentproto run-swarm's runtime registry with new substrates, dispatchers, participant executors, or state stores — the four port kinds the MultiAgentRuntime kernel composes per swarm.
Runtime profiles
A runtime profile is a bundle of file scaffolding the CLI can drop into a user's repo to make a workflow work out of the box.