Traditional permission models assume a human clicks each button. Agents issue tool calls at machine speed, and the app-permission model breaks down. You grant an agent access to “files” or “network,” and it inherits every permission you have. The blast radius is your entire user context.
Capability-based security flips the model. An agent starts with zero authority and receives unforgeable tokens for specific actions. Each token is a first-class object that grants exactly one narrow permission. No centralized ACL checks. No ambient authority. If you hold the capability, you can perform the action. If you don’t, you can’t.
This maps cleanly to agent orchestration patterns where a parent agent delegates a subset of its permissions to a sub-agent or tool, then revokes access when the task completes.
Why ACLs Fail for Agent Tool Calls
Access Control Lists check “who you are” against a permission table. The agent runs as you, so it passes every check you would pass. The system has no way to distinguish between you clicking a button and an agent issuing a tool call after reading untrusted input.
Problems this creates:
- Coarse grants: You can’t give an agent permission to read one specific file. You grant “file access,” and it can read everything.
- No delegation: If your agent spawns a sub-agent to handle a subtask, the sub-agent either inherits all permissions or none. There’s no middle ground.
- Revocation is global: Revoking access means killing the process or changing your user permissions, which affects everything else running as you.
- Audit trails are vague: Logs show “user X accessed file Y,” but they don’t show which agent, which task, or which tool call triggered it.
The ACL model assumes the principal (you) is trustworthy and the actions are human-paced. Agents break both assumptions.
Object Capabilities as Authorization Primitives
A capability is an unforgeable reference to an object plus a set of operations you can perform on it. In practice, it’s a token or handle that grants permission to do exactly one thing.
Core properties:
- Unforgeable: You can’t guess or construct a valid capability. The system generates it, and possession is the only proof of authority.
- Delegatable: You can pass a capability to another agent or process. The recipient gains the same permission you had, no more.
- Revocable: The issuer can invalidate the capability, and all future attempts to use it fail.
- Fine-grained: A capability can grant “read this specific file” or “transfer up to $100 from this account,” not “access all files” or “perform any financial operation.”
This is not a new idea. The E language, Capsicum, and several research operating systems implemented capability-based security decades ago. What changed is the actor: agents need exactly this kind of fine-grained, delegatable, revocable permission model.
Architecture: Capability Flow in Agent Orchestration
Here’s how capabilities move through a typical agent system:
- Agent runtime starts with zero authority. It can’t touch files, network, or external APIs.
- User grants a root capability for the task. Example: “read files in
/project/dataand call thesummarizeAPI.” - Agent receives two capabilities: a file-read capability scoped to
/project/dataand an API-call capability scoped tosummarize. - Agent spawns a sub-agent to process one file. It delegates the file-read capability for that specific file, not the entire directory.
- Sub-agent completes the task and returns a result. The parent agent revokes the delegated capability.
- Agent calls the API using the API-call capability. The MCP server validates the capability and forwards the request.
- Task completes. The runtime revokes all capabilities. The agent can no longer perform any actions.
Key difference from ACLs: At no point does the system check “is this agent allowed to read files?” It checks “does this agent hold a valid capability for this file?” The capability is the permission.
Serialization and Cross-Process Boundaries
Agents often delegate tool calls across process boundaries: agent runtime → MCP server → external API. The capability must survive serialization without becoming forgeable.
Common approaches:
- Cryptographic tokens: The capability is a signed JWT or HMAC token. The signature proves it was issued by the authority, and tampering invalidates it.
- Handle tables: The capability is an opaque integer that indexes into a table held by the issuing process. Passing the handle across boundaries requires a trusted channel.
- Membrane patterns: A proxy object wraps the capability and enforces additional constraints (rate limits, logging, revocation checks) before forwarding calls.
Example: File-read capability as a signed token
import hmac
import hashlib
import json
from datetime import datetime, timedelta
class CapabilityIssuer:
def __init__(self, secret_key):
self.secret = secret_key.encode()
def issue_file_read(self, path, expires_in_seconds=3600):
payload = {
"action": "file.read",
"resource": path,
"expires": (datetime.utcnow() + timedelta(seconds=expires_in_seconds)).isoformat()
}
message = json.dumps(payload, sort_keys=True).encode()
signature = hmac.new(self.secret, message, hashlib.sha256).hexdigest()
return {"payload": payload, "signature": signature}
def validate(self, capability):
payload = capability["payload"]
message = json.dumps(payload, sort_keys=True).encode()
expected_sig = hmac.new(self.secret, message, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected_sig, capability["signature"]):
raise ValueError("Invalid capability signature")
if datetime.fromisoformat(payload["expires"]) < datetime.utcnow():
raise ValueError("Capability expired")
return payload
# Usage in agent runtime
issuer = CapabilityIssuer(secret_key="runtime-secret")
cap = issuer.issue_file_read("/project/data/report.csv", expires_in_seconds=300)
# Agent passes capability to MCP server
# MCP server validates before performing action
try:
validated = issuer.validate(cap)
# Perform file read for validated["resource"]
except ValueError as e:
# Reject the tool call
pass
The agent can’t forge a new capability because it doesn’t know the secret. It can only use capabilities issued by the runtime.
Revocation Strategies
Revocation is where capability systems get messy. Once you hand someone a capability, how do you take it back?
| Strategy | How It Works | Trade-offs |
|---|---|---|
| Expiration | Capability includes a timestamp. System rejects expired tokens. | Simple, no coordination needed. Can’t revoke early. |
| Revocation list | Issuer maintains a list of invalidated capability IDs. Validator checks the list on each use. | Immediate revocation. Requires shared state and network calls. |
| Proxy indirection | Capability points to a proxy object. Issuer can disable the proxy. | Clean revocation. Adds latency and a single point of failure. |
| Short-lived + renewal | Capabilities expire quickly. Agent must renew them to continue. | Bounded blast radius. Renewal adds complexity. |
For agent tool calls, expiration + renewal is the sweet spot. Issue capabilities that last 5-10 minutes. If the agent is still working on the task, it requests a renewal. If the task completes or the agent misbehaves, the capability expires and isn’t renewed.
Failure Modes and Observability
Capability systems fail differently than ACL systems. Here’s what breaks and how to detect it:
Capability leakage: An agent logs a capability to a file or sends it to an external API. Now an attacker can replay it.
- Mitigation: Bind capabilities to the agent’s session ID. Validate the session on each use.
- Detection: Monitor for capability use from unexpected network locations or after session termination.
Confused deputy: An agent with a broad capability is tricked into using it on behalf of an attacker.
- Mitigation: Issue the narrowest possible capability. Don’t grant “write any file,” grant “write this specific file.”
- Detection: Log the call stack and input context for each capability use. Anomaly detection on input sources.
Revocation lag: A capability should be revoked, but the agent cached it and keeps using it until expiration.
- Mitigation: Use short expiration windows. Implement active revocation checks for high-risk operations.
- Detection: Track capability use after the task that justified it has ended.
Observability primitives:
- Log every capability issuance with task ID, agent ID, and scope.
- Log every capability use with the resource accessed and the result.
- Track capability lineage: which agent delegated to which sub-agent.
- Alert on capability use outside expected time windows or from unexpected agents.
When This Matters: Financial Agents
Capability-based security shines when agents handle money or sensitive data. A trading agent needs to place orders, but you don’t want it to withdraw funds. A payment agent needs to authorize transactions up to a limit, but not beyond.
Example: Payment authorization capability
payment_cap = issuer.issue_payment(
account="checking-001",
max_amount=100.00,
currency="USD",
expires_in_seconds=600
)
The agent can authorize payments up to $100 from that account for the next 10 minutes. It can’t touch other accounts. It can’t exceed the limit. When the task completes, the capability expires.
Compare this to an ACL model where the agent runs as you and inherits permission to perform any financial operation you can perform. The capability model gives you a much smaller blast radius.
Technical Verdict
Use capability-based security when:
- Agents delegate tool access to sub-agents or external services.
- You need fine-grained permissions that ACLs can’t express (specific files, dollar limits, time windows).
- Revocation must happen quickly without killing the entire agent process.
- You’re building financial agents, data agents, or anything touching sensitive resources.
Avoid it when:
- Your agent only calls a handful of tools and you trust them completely.
- The overhead of issuing, validating, and renewing capabilities exceeds the security benefit.
- Your runtime already provides strong sandboxing (containers, VMs) and you’re comfortable with coarse-grained permissions.
Capability-based security is not a replacement for sandboxing or input validation. It’s an authorization layer that sits between the agent and its tools. It answers the question “what is this agent allowed to do right now?” with a much finer brush than ACLs can manage.
The plumbing is more complex. The security boundaries are tighter. For agents that handle money or data you care about, that’s the right trade.
Source Links
- Capability-Based Security for AI Agents (primary source)
- Hacker News discussion