# Agent Permissions

*"An agent with every capability is an agent with no boundary. A boundary is the entire point."*

## Overview

AI coding agents operate inside Aura under a capability-token model. Every agent session — whether Claude Code, Cursor, a bespoke in-house orchestrator, or an autonomous bot — receives a scoped capability token at start. The token enumerates exactly which actions the agent may perform. An agent without `push` cannot push. An agent without `claim_zone` cannot lock files. The token is revocable in seconds, and every action the agent takes is recorded in the [audit trail](/audit-trail) with its agent-id and the specific capability invoked.

This document defines the capability set, the revocation mechanism, and the operational procedures for reviewing agent activity. It assumes familiarity with the [threat model](/threat-model), particularly the rogue-agent adversary class.

## Threat Scope

Agents differ from human operators in three consequential ways. First, they can take tens of thousands of actions per hour — mistakes compound quickly. Second, they can be prompt-injected, meaning their intent is subject to contamination from untrusted content they read. Third, they do not pause to reconsider. A human developer staring at a large destructive diff often hesitates; an agent running a headless loop does not.

The capability model addresses these properties by constraining the blast radius. Even a fully prompt-injected agent holding the wrong capability token cannot perform an action outside its grant. The goal is not to detect malice — detection happens in the audit log after the fact — but to mathematically bound what is *possible*.

Out of scope: an agent operating under a capability set that was issued too broadly to begin with. Over-granting tokens is a policy failure the capability system cannot correct. Start narrow.

## Mechanism

### Capability set

The capability vocabulary is small and deliberately stable. Additions require a minor version bump and explicit documentation; subtractions require a major version bump.

| Capability | Grants the ability to | Typical role |
|---|---|---|
| `read_logic` | Read function bodies, read AST, query `aura prove` | Any agent |
| `write_logic` | Modify files tracked by Aura | Editor agents |
| `log_intent` | Call `aura_log_intent` | Committer agents |
| `commit` | Produce a commit locally | Committer agents |
| `push` | Propagate commits to peers / Mothership | Integrator agents |
| `pull` | Receive changes from peers | Any active agent |
| `claim_zone` | Lock files/functions to prevent concurrent edits | Coordinator agents |
| `send_message` | Post to team or sentinel inbox | Coordinator agents |
| `snapshot` | Create pre-edit snapshots for rewind | Any editor agent |
| `rewind` | Restore a function from a snapshot | Recovery agents |
| `admin` | Issue new tokens, revoke peers, rotate keys | Admin operators only |

Capabilities do not cascade. Holding `write_logic` does not imply `commit`; holding `commit` does not imply `push`. This is intentional. A common and useful configuration is an agent that may write and commit locally but cannot push — leaving push to a human reviewer.

### Role presets

For convenience, Aura ships role presets that map to capability bundles. Custom roles can be defined in the Mothership configuration.

| Role | Capabilities | Notes |
|---|---|---|
| `reader` | `read_logic`, `pull` | Read-only analyst; safe default for new agents |
| `contributor` | `read_logic`, `write_logic`, `log_intent`, `commit`, `snapshot`, `pull` | Typical coding agent; cannot push |
| `integrator` | `contributor` + `push` + `claim_zone` + `send_message` | Trusted agent responsible for coordinating merges |
| `admin` | all capabilities | Reserved for human operators running the Mothership CLI |
| `agent` | `contributor` + `send_message` + `claim_zone` | Default for AI agents |

The `admin` role should not, under any circumstances, be granted to an AI agent. Its actions cannot be undone by anyone below admin, which means a prompt-injected admin agent can irrecoverably damage the deployment.

### Token issuance

When a human starts a session with an AI agent, Aura's MCP server requests a capability token from the local peer. The token is:

- A JWT signed by the peer's identity key.
- Scoped to the agent process (not transferable).
- Time-bounded (default 4 hours, configurable).
- Carrying the capability set chosen by the human.

The agent includes the token in every MCP tool invocation. The Aura daemon checks, for every tool call, that the requested action is in the token's capability set. If not, the call fails with a clear error message.

Issuance is controlled by the per-repository `agents.toml`:

```toml
[agents.defaults]
# Default role for agents that don't specify one
role = "reader"
# Max token TTL in seconds
max_ttl = 14400

[agents.roles.coder]
capabilities = ["read_logic", "write_logic", "log_intent", "commit", "snapshot", "pull"]
max_files_per_commit = 25
max_commits_per_hour = 20

[agents.roles.auto_merger]
capabilities = ["read_logic", "pull", "push", "claim_zone", "log_intent"]
# Cannot write source — may only merge already-approved function bodies
```

Quotas (`max_files_per_commit`, `max_commits_per_hour`) provide a blast-radius cap distinct from capabilities. A `coder` with `write_logic` can still only commit 25 files in one go; the 26th is refused.

### Revocation

```bash
aura agent revoke <agent-id>
```

Revokes the token. The revocation list propagates on the next peer sync (sub-second on healthy networks). An agent attempting to use a revoked token receives an `E_REVOKED` error on the next tool call and must obtain a new token from a human operator.

List active agents:

```bash
aura agent list
```

Sample output:

```text
AGENT-ID              ROLE         CAPABILITIES                          ISSUED     EXPIRES
claude-7f3a           agent        read+write+intent+commit+snap+msg     12:04:15   16:04:15
cursor-local-b82c     coder        read+write+intent+commit+snap         13:22:01   17:22:01
auto-merger-ci        auto_merger  read+pull+push+claim+intent           00:00:00   never (service)
```

For service accounts (e.g., a CI runner), tokens are issued without expiration but must be rotated on a schedule and revoked the instant the corresponding automation is decommissioned.

### Audit of agent activity

Every intent log entry carries `actor.kind = "agent"` and `actor.id = <agent-id>` when the commit originates from an agent. To enumerate a specific agent's actions:

```bash
aura trace --actor claude-7f3a --since 24h
```

Output is a chronological list of every intent, capability used, files touched, and AST delta hash. For suspicious sessions, pair with `aura pr-review --actor <agent-id>` to get a security-focused diff summary of everything the agent touched.

For SIEM ingestion the same data is available as JSONL:

```bash
aura audit export --actor claude-7f3a --format jsonl > claude-session.jsonl
```

### Collision and zone coordination

When multiple agents operate on the same repository, the `claim_zone` capability gates exclusive access to a file or function region. An agent holding a zone prevents other agents (and warns humans) from editing the same area. Claims have a TTL and auto-release; see [agent collision detection](/agent-collision-detection) for the coordination protocol. Agents without `claim_zone` cannot acquire locks but still receive advisory warnings when they touch a claimed region.

## Configuration

Full example of a hardened agents configuration for a regulated team:

```toml
[agents.defaults]
role = "reader"
max_ttl = 7200

# Coding agents: can edit and commit, cannot push
[agents.roles.coder]
capabilities = [
    "read_logic",
    "write_logic",
    "log_intent",
    "commit",
    "snapshot",
    "pull",
    "send_message",
]
max_files_per_commit = 15
max_commits_per_hour = 10
max_ttl = 14400

# CI integrator: can push approved changes, cannot write new code
[agents.roles.ci_integrator]
capabilities = [
    "read_logic",
    "pull",
    "push",
    "log_intent",
    "claim_zone",
]
max_commits_per_hour = 60

# Analysis agents: read-only, can send messages
[agents.roles.analyst]
capabilities = ["read_logic", "pull", "send_message"]
max_ttl = 28800

[agents.enforcement]
# Reject any agent session that does not specify a role
require_explicit_role = true
# Refuse tokens whose capabilities exceed the requested role
deny_capability_escalation = true
# Log every tool invocation, not just mutations
log_all_calls = true
```

`log_all_calls = true` produces heavy audit volume but is necessary for some compliance regimes. Standard deployments log only mutating calls.

## Limitations

- **Capabilities bound actions, not intentions.** An agent with `write_logic` can write the wrong thing. Pair capabilities with review (`aura pr-review`) and with the strict-mode intent-vs-AST consistency check.
- **Tokens are bearer credentials.** If an agent process is compromised by another local process with the same UID, the token can be stolen. The host OS is below Aura's trust boundary; protect agent processes accordingly.
- **Over-granting is the usual failure.** Teams under deadline pressure tend to bump agents to `integrator`. Review role assignments quarterly; the default should be the narrowest grant that lets the agent do its job.
- **Revocation is not retroactive.** An agent that committed malicious code before revocation has still committed. Revocation prevents future actions; recovery of past actions is a `rewind` + intent-log review problem.
- **Service-account tokens live forever by design.** Their lifetime is a policy choice, not a cryptographic limit. Ensure your provisioning pipeline revokes them when the corresponding automation is retired.

## See Also

- [Threat model](/threat-model) — rogue-agent adversary class
- [Audit trail](/audit-trail) — how agent actions appear in the log
- [Agent collision detection](/agent-collision-detection) — coordinating multiple agents
- [Sentinel (agent messaging)](/agent-inbox) — inter-agent communication
- [Incident response](/incident-response) — responding to a rogue agent
- [Claude Code integration](/claude-code-integration) — configuring the MCP client
- [Cryptographic design](/cryptographic-design) — JWT structure