What is a delegation chain
A delegation chain lets one agent grant a subset of its permissions to another. The delegating agent keeps its own permissions unchanged. The receiving agent gains access only to what was explicitly delegated. This pattern is most useful when an orchestrator spins up sub-agents for specific tasks. Each sub-agent gets only the access it needs, for only as long as it needs it.
A delegation chain is capped by maxDepth, and revoking a link also revokes the links created downstream of it.
The delegating agent must currently hold every permission it is trying to delegate. Attempting to delegate a permission not in the agent’s own set throws an
Error (“Delegated permissions must be a subset of the parent agent’s permissions…”). The check runs against the agent’s own permissions only, not against permissions it received through other delegations.Working with delegations
Creating a delegation
Agent ID granting the permissions. Must hold every permission being delegated, either as its own permission or through a delegation it received.
Subset of permissions to delegate. Must not exceed what the fromAgent holds (its own permissions plus the active, unexpired delegations it received).
Highest chain depth this link and any later link below it may reach. The new link’s depth (1 for a first hop, parent depth plus 1 for a re-delegation) must be less than or equal to the effective limit, otherwise the call throws. Default is 3. The limit is inherited: a re-delegation is checked against the smaller of its own
maxDepth and the maxDepth of every active delegation the parent received.Permission subset enforcement
The permissions you delegate must be a subset of what thefromAgent holds. Narrower resources and fewer actions are allowed. Wider resources or new actions are rejected.
Given an orchestrator with:
mcp:github does not allow delegating mcp:github:read, because authorize() would not let the parent use it either. With path matching, a parent ros2:/fleet/* can delegate ros2:/fleet/r1.
Constraints carry over
Constraints on the permissions you delegate are stored on the chain and enforced byauthorize(), authorizeByToken() and policy.evaluate(). They are narrowed against the permission the parent holds, so a child can only be tighter:
Depth limiting
Each link has a depth: 1 for a delegation from an agent that did not itself receive one, otherwise the deepest active chain into the delegating agent plus 1. On everydelegate() call the code computes an effective limit, the smallest of the maxDepth passed on that call (default 3) and the maxDepth stored on every active, unexpired delegation into the delegating agent, and throws if the new link’s depth is larger. The effective limit is stored on the new link, so a limit set at the top of a chain holds for every hop below it. A later call can lower it, never raise it.
maxDepth when not specified is 3.
A delegating agent can re-delegate permissions it received. The subset check runs against the agent’s own permissions plus the active delegations into it, so
sub above, created with permissions: [], can pass on what it was given, never more. The new link also cannot outlive the delegation it was derived from: its expiry is capped at the earliest expiry among the delegations into the parent, unless the parent’s own permissions already cover the request.Delegators must be live
A delegation lends authority only while its delegator is live. If a delegating agent is revoked or expired (or any status other thanactive), the links it gave stop counting: the delegate loses the permissions that came through it in authorize(), authorizeByToken(), policy.evaluate(), explain(), the simulator and the live MCP check, and the chain passed to beforeAuthorize no longer lists it. This applies down the chain, even when no revocation cascade ran. An agent that stands on its own permissions, and a root user as delegator, are not affected, and permissions the delegate holds directly are never touched. The same filter backs token vault consent (a downstream agent cannot use a vault credential through a dead intermediate) and the policy-shrink grant list, so unused-permission suggestions ignore dead links. If a delegator’s inbound links are all dead, its onward links still stand when they grant only permissions it holds directly, because that authority never came through the dead chain. Onward links that grant what it received through the dead chain stop.
Cascading revocation
Revoking a chain marks it revoked and does the same for active chains that start from the receiving agent.orchestrator → sub → subSub, revoking orchestrator → sub also revokes sub → subSub immediately. Any agent that relied on the revoked permissions will get allowed: false on its next authorization check.
In the TypeScript package,
agent.revoke() also revokes every active chain where the agent is the source or the target, and the chains downstream of them. It returns their ids as revokedDelegations and writes one agent.cascade.revoked audit row for the agent. Use delegation.revoke() when you want to cut one chain and keep the agent. This agent.revoke() cascade is pending in a changeset and is available in the next release after 1.1.2. Before it, revoke the agent’s chains with delegation.revoke().Tokens minted through MCP token exchange carry their chain in the
act claim, plus a signed theauth_dlg binding to the exact links and agents behind it. With auth passed to createMcpModule, the resource server checks that binding against the live rows on every request, so revoking a link (and every link below it in the cascade) or revoking an agent makes the next request carrying an affected token fail, on every instance that shares the database. A token never outlives the links and agents it came from. Resource servers that only verify the JWT see the revoke at token expiry. See MCP token revocation for the modes and limits. delegationStore remains as the opt in check for older tokens that have an act claim and no binding.Effective permissions
To see the full set of permissions an agent has at a given moment, including those received through active chains:authorize() checks the agent’s own permissions first and, if they deny, falls back to these delegated permissions. You can call it directly to inspect what an agent has received through delegation.
Listing chains
DelegationChain type
The human who owns the root agent of the chain. If the delegating agent was itself delegated to, the walk continues upward through active, unexpired chains, following the earliest created one when there are several.
rootOwnerId and path are returned by delegate() (listChains() does not include them). policy.evaluate() returns the same lineage as decision.principal, and each delegation is written to the audit log with the lineage on the row. The audit write is best effort: a failure does not fail the delegation, and it is counted (see Tamper-evident audit trail).
Typical pattern
An orchestrator holds broad permissions, plans a task, and issues short-lived narrow delegations to sub-agents.1
Create the orchestrator with the full permission set it needs.
2
Create the sub-agent with no direct permissions.
3
Delegate only what the sub-agent needs, with a short expiry and a small
maxDepth (later hops inherit it, see depth limiting above).Next steps
Audit trail
Authorization decisions made through delegated permissions are recorded in the audit log.
Agent identity
Create the agents that participate in delegation chains.
Remove unused permissions
Delegated permissions count as granted when you compare them with what an agent used.
MCP OAuth 2.1
Use delegation with MCP-authenticated agents. Tokens from token exchange are bound to their delegation, so revoking a link rejects them on the next request. See MCP token revocation.