Agent and Delegation Commands

Agent and delegation commands communicate with the Coordinator service rather than the control-plane API. They require both CARACAL_ADMIN_TOKEN (for the API zone context) and CARACAL_COORDINATOR_TOKEN (a JWT with scope agent:lifecycle for the Coordinator).

export CARACAL_COORDINATOR_URL=http://localhost:4000
export CARACAL_COORDINATOR_TOKEN=<coordinator-jwt>

If either variable is missing, all agent and delegation commands fail with an actionable error:

coordinator URL not set — export CARACAL_COORDINATOR_URL
coordinator token not set — export CARACAL_COORDINATOR_TOKEN

All commands accept --zone <id>, --json, and --help.

---

Agent commands — caracal agent

caracal agent list

List all agent sessions in the zone.

caracal agent list
caracal agent list --json

Table columns: id, application_id, parent_id, status, depth, spawned_at, terminated_at

status values: active, suspended, terminated.

depth is the session’s position in the spawn hierarchy (root = 0). Maximum depth is 10.

---

caracal agent get <id>

Fetch a single agent session by ID.

caracal agent get agentsess_abc123

---

caracal agent tree <id>

List the direct child sessions of an agent session. Alias: caracal agent children.

caracal agent tree agentsess_abc123

Table columns: id, application_id, parent_id, status, depth, spawned_at

Use this to inspect the immediate children of a session. To walk the full tree, run tree recursively on each child’s ID.

---

caracal agent suspend <id>

Suspend an agent session. New token exchanges from this session are blocked until it is resumed.

caracal agent suspend agentsess_abc123

Suspension does not terminate the session or revoke existing mandates — in-flight requests with valid mandates complete normally. Future exchanges are blocked.

---

caracal agent resume <id>

Resume a suspended agent session.

caracal agent resume agentsess_abc123

---

caracal agent terminate <id>

Permanently terminate an agent session. Terminated sessions cannot be resumed.

caracal agent terminate agentsess_abc123

Output: terminated agentsess_abc123

Terminating a session also terminates all of its descendant sessions recursively and invalidates their delegation edges.

---

Delegation commands — caracal delegation

Delegation edges form a directed graph of authority transfers between sessions. Each edge has a source session, a target session, a resource, and an expiry.

caracal delegation inbound <session-id>

List delegation edges whose target is the given session.

caracal delegation inbound agentsess_abc123

Table columns: id, source_session_id, target_session_id, resource_id, status, expires_at

status values: active, revoked.

Inbound edges represent authority that other sessions have delegated to this session.

---

caracal delegation outbound <session-id>

List delegation edges whose source is the given session.

caracal delegation outbound agentsess_abc123

Table columns: same as inbound

Outbound edges represent authority this session has delegated to others.

---

caracal delegation traverse <edge-id>

Walk the full delegation chain for an edge.

caracal delegation traverse deledge_def456

Table columns: depth, id, source_session_id, target_session_id

Returns every edge in the chain from the root to the leaf, ordered by depth. Use this to audit the full authority path for a delegation.

---

caracal delegation revoke <edge-id>

Revoke a delegation edge and all edges that depend on it.

caracal delegation revoke deledge_def456

Output:

{"revoked_edges": 3, "affected_sessions": 2}

Revocation is cascading: revoking an edge also revokes all downstream edges that were derived from it. Mandates already issued before revocation remain valid until they expire (up to 15 minutes). Sessions that relied on the revoked edge cannot exchange for new mandates.

---

Common workflows

Investigate an agent that’s behaving unexpectedly:

# Find the agent session
caracal agent list --json | jq '.[] | select(.status == "active")'

# Inspect its children
caracal agent tree agentsess_abc123

# Check what authority it has delegated
caracal delegation outbound agentsess_abc123

Emergency: revoke all authority for a compromised session:

# Terminate the session (cascades to all children)
caracal agent terminate agentsess_abc123

# Revoke all outbound edges explicitly
caracal delegation outbound agentsess_abc123 --json | \
  jq -r '.[].id' | \
  xargs -I{} caracal delegation revoke {}

Audit a delegation chain end-to-end:

# Get the edge ID from a token's delegationEdgeId claim or from outbound edges
caracal delegation traverse deledge_def456