§ DOCUMENTATION

Agent Passport

Verifiable delegation chain-of-custody, capability inheritance, revocation cascade, declared-vs-observed tool diffs, and a non-human identity inventory — one place to audit every machine identity in your org.

§ 01

What a passport captures — chain-of-custody

An Agent Passport is the verifiable record of an agent's lineage and declared capabilities. When agent A delegates work to agent B, Execlave records a delegation — a chain-of-custody link that answers: who authorized whom, with which capabilities, and when.

Delegations are stored in the agent_delegations table, RLS-scoped per org. Each row carries the delegator agent ID, delegate agent ID, the declared tools the delegate is permitted to use, and a revocation timestamp that is null until the delegation is explicitly revoked.

Agent Passport builds on Agent Identity — every agent in a delegation tree must first have an Execlave identity before it can appear as a delegator or delegate.

Concept	What it records
Delegation	A single delegator → delegate link with declared tools and timestamps
Chain	The full ancestry path from root agent down to a given delegate
Declared tools	The subset of tools the delegate is authorised to use
Revocation	When a delegation is revoked, cascades to all descendants

§ 02

Capability inheritance — the subset rule

A delegate inherits only a subset of its delegator's declared capabilities — it cannot gain tools the delegator does not have. Execlave enforces this at delegation-creation time: the API rejects any declaredTools entry not present in the delegating agent's own declared tools list.

Because every delegator was itself bounded by its parent, the constraint propagates transitively through the entire delegation tree. No agent in the chain can hold capabilities that exceed its root ancestor.

§ 03

Revocation cascade

Revoking a delegation does not only deactivate that single link — it cascades downstream. Execlave runs a recursive query over the delegation tree and stamps revokedAt on every delegation that descends from the revoked one, regardless of depth.

A revoked intermediate agent does not leave its downstream delegates active. Every cascade event is recorded in the audit log with the parent revocation ID so you have a complete, traceable record of which delegations were affected and why.

§ 04

Declared-vs-observed tool diff — shadow tool detection

Each agent declares the tools it intends to use at registration time via declaredTools. Execlave continuously diffs that declaration against the tools the agent has actually been observed calling in trace events. Any tool that appears in observed calls but not in the declaration is a shadow tool — undeclared capability drift that warrants review.

Signal	Meaning	Recommended action
Declared, never observed	Tool declared but not yet used	Review — remove stale declarations
Declared and observed	Expected behaviour — tool in use as intended	No action required
Observed, not declared	Shadow tool — capability drift	Declare formally or block via tool_invocation policy

The diff endpoint is available at GET /api/v1/agents/:id/tools/diff and returns the three categories above for the specified agent.

§ 05

NHI inventory

The non-human identity inventory enumerates every agent identity registered in your org, its active delegations, and its declared tools — one place to audit all machine identities. This addresses the compliance requirement to know what non-human principals exist and what they are authorised to do.

# Fetch full delegation chain for an agentcurl https://api.execlave.com/api/v1/agents/agt_01j_child/delegations/chain \  -H "Authorization: Bearer $EXECLAVE_API_KEY" # Fetch NHI inventory — all agent identities, delegations, and declared toolscurl https://api.execlave.com/api/v1/agents/inventory \  -H "Authorization: Bearer $EXECLAVE_API_KEY"

Use POST /api/v1/agents/:id/delegations to record a new delegation, GET /api/v1/agents/:id/delegations/chain to fetch the full ancestry path, and GET /api/v1/agents/inventory for the org-wide NHI inventory.

curl -X POST https://api.execlave.com/api/v1/agents/agt_01j_parent/delegations \  -H "Authorization: Bearer $EXECLAVE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "delegateAgentId": "agt_01j_child",    "declaredTools": ["web_search", "read_file"],    "note": "Research sub-agent — read-only subset of parent tools"  }' # Response{  "data": {    "id": "del_01j...",    "delegatorAgentId": "agt_01j_parent",    "delegateAgentId":  "agt_01j_child",    "declaredTools":    ["web_search", "read_file"],    "revokedAt":        null,    "createdAt":        "2026-06-02T11:00:00Z"  }}

§ 06

Enabling Agent Passport

Agent Passport is gated by the AGENT_PASSPORT_ENABLED environment variable (default off). When the flag is absent or false, all passport endpoints return 404 and no delegation data is read or written — prior behavior is fully preserved.

Environment variable	Default	Effect when true
AGENT_PASSPORT_ENABLED	false	Activates delegation endpoints, tool diff, and NHI inventory

The migration that creates agent_delegations can be applied independently — the table will exist but remain inert until the flag is set.

§ 07

Frequently asked questions

How deep does the revocation cascade go?

The cascade is fully recursive. When you revoke a delegation, Execlave runs a recursive query over the agent_delegations table and revokes every delegation that is a descendant of the revoked one — regardless of depth. A revoked intermediate agent does not leave its downstream delegates active. The cascade is recorded in the audit log so you have a complete record of which delegations were affected.

What counts as a shadow tool?

A shadow tool is any tool an agent has been observed calling in traces that does not appear in its declared tools list. Execlave diffs the declared_tools column against the set of tools recorded in observed trace events for that agent and surfaces the gap. Shadow tools indicate capability drift — the agent is doing more than it was declared to do — and should be reviewed and either formally declared or blocked via a tool_invocation policy.

Does capability inheritance apply transitively across a delegation chain?

Yes. Each link in the chain is bounded: a delegate can inherit at most the capabilities its direct delegator had at delegation time. Because every delegator was itself bounded by its parent, the constraint propagates through the entire tree. No agent in the chain can hold capabilities that exceed its root delegator. Execlave enforces this at delegation-creation time — the API rejects declared_tools entries that are not a subset of the delegating agent's declared tools.

What happens if AGENT_PASSPORT_ENABLED is not set?

All passport endpoints return 404. No delegation data is written or read. The feature is completely inactive and prior behavior is fully preserved. This means you can deploy the migration (which creates agent_delegations) without activating the feature — it will have no effect until the flag is explicitly set to true in your backend environment.