Hierarchy and Escalations

Agents form a parent-child hierarchy tree. Escalations travel up this tree before reaching the human HITL gate, keeping human interrupt rates low.

The Hierarchy Tree

When agent A spawns agent B, A becomes B's parent. The root agent has no parent and escalates directly to the human.

Agent hierarchy tree

agentd tracks this tree. View it with:

ash hierarchy show

Escalation Flow

When an agent encounters a situation requiring escalation (capability request beyond its manifest, anomaly alert, plan deviation requiring human review):

  1. The escalation is sent to the agent's parent via the bus topic scarab.escalation.<parent-id>
  2. The parent agent receives the escalation via agent.pending_escalations()
  3. The parent can auto-resolve it (approve, deny, or reroute) or escalate further up
  4. Only the root agent escalates to the human HITL gate

Viewing Pending Escalations

ash hierarchy escalations

Lists agents with unresolved escalations in their mailbox.

Polling Escalations (SDK)

#![allow(unused)]
fn main() {
let escalations = agent.pending_escalations().await?;
for esc in escalations {
    println!("Escalation: {}", esc);
    // Decide: auto-resolve or escalate to parent
}
}

Types of Escalations

TypeTrigger
Capability requestAgent attempts action outside its manifest
Anomaly alertAnomaly detector fires (see Anomaly Detection)
Plan deviationAgent deviates from declared plan (Strict mode)
HITL approvalA tool requires human approval and no parent handles it
Budget exceededAgent exceeds its cost budget

Capability Grants via Escalation

When an agent needs a capability not in its manifest, it can request a runtime grant:

  1. Agent's tool call fails with AccessDenied
  2. Agent (or its SDK) sends a grant request
  3. Grant request escalates up the hierarchy
  4. Parent or human approves the grant
  5. agentd issues a temporary CapabilityGrant for that agent

See Capability Grants for operator details.