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 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, 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:

[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

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:

aura agent list

Sample output:

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:

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:

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 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:

[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.