CLI Reference: Hierarchy
Commands for viewing the agent hierarchy tree and managing escalations.
Agents in Scarab-Runtime form a supervisor/child hierarchy: an agent that spawns another becomes its supervisor. Escalations are requests from a child agent to its supervisor for help or approval. See Hierarchy and Escalations for background.
ash hierarchy show
Render the current agent hierarchy as a tree.
ash hierarchy show
Example output:
root-agent (550e8400) [plan]
├── worker-1 (a1b2c3d4) [act]
│ └── sub-worker (b5c6d7e8) [observe]
└── worker-2 (f9e8d7c6) [plan]
Each node shows: name, agent ID (truncated), and current lifecycle state.
ash hierarchy escalations
List agents with pending escalations (unresolved requests to supervisors).
ash hierarchy escalations
Output per pending escalation:
| Field | Description |
|---|---|
escalation_id | UUID |
from_agent_id | Child agent requesting escalation |
to_agent_id | Supervisor agent (or operator if no supervisor) |
kind | Escalation type (e.g. CapabilityRequest, HumanApproval, Stuck) |
detail | Human-readable description of the escalation |
created_at | RFC3339 timestamp |
Responding to escalations
Escalations are typically resolved by the supervisor agent programmatically. For escalations that bubble up to the operator level (no supervisor, or supervisor is unresponsive), use:
# Approve a pending HITL request (which may be tied to an escalation)
ash approve <request-id>
# Or deny it
ash deny <request-id>
See HITL Approvals for the full human-in-the-loop workflow.
Hierarchy depth limits
To prevent runaway recursion, agentd enforces a maximum hierarchy depth (configurable in agentd.toml). Attempts to spawn beyond the limit are rejected with a HierarchyDepthExceeded error.