Capability Grants

Runtime capability grants allow operators (or parent agents) to temporarily extend an agent's capabilities beyond what is declared in its manifest, without requiring a restart.

Overview

Grants are temporary: they expire at a configurable time or when explicitly revoked. Every grant is logged in the audit trail.

Listing Grants

ash grants list <agent-id>

Output:

GRANT-ID                              CAPABILITY           GRANTED-BY  EXPIRES
f1e2d3c4-...                          fs.write:/tmp/**     operator    2026-02-22T13:00:00Z

Revoking a Grant

ash grants revoke <agent-id> <grant-id>

The grant is immediately removed and the agent loses the capability.

How Grants Are Issued

Grants are typically issued through the escalation hierarchy:

  1. Agent calls a tool and receives AccessDenied
  2. Agent (or parent) initiates a grant request via IPC
  3. Parent agent or operator approves the request
  4. agentd creates a CapabilityGrant for the agent with the requested capability and expiry
  5. Subsequent tool calls succeed until the grant expires or is revoked

Operators can also issue grants directly via the ash CLI or IPC.

Capabilities That Can Be Granted

Any valid capability string can be granted at runtime:

fs.read:/tmp/report.pdf
fs.write:/tmp/**
tool.invoke:web.search
secret.use:temp-key

Grants are additive; they extend the manifest's capability set for the duration of the grant.

Audit Trail

Every grant issuance and revocation appears in the audit log:

{"action": "capability_granted", "capability": "fs.write:/tmp/**", "agent_id": "...", "granted_by": "operator"}
{"action": "capability_revoked", "capability": "fs.write:/tmp/**", "agent_id": "...", "revoked_by": "operator"}

Security Considerations

  • Grants cannot exceed the agent's trust level ceiling
  • Expired grants are automatically cleaned up by the daemon
  • A privileged trust-level agent cannot be granted capabilities outside what privileged allows
  • Grants to untrusted agents are limited to the untrusted capability set