Agent permissions

The question you are answering here is narrower than it first looks: not what this agent is, but which exact actions it may take. An agent authenticates with an opaque bearer token — the credential the product issues by default — and any process holding that string is the agent: there is no cryptographic binding to a workload, and the product carries that as a stated residual risk rather than hiding it. That makes the permission set the load-bearing control. Whatever the token can reach is whatever the roles name, and the difference between a contained incident and a bad week is whether those roles were written as an allowlist or as a list of exceptions. An install that has configured workload identity can exchange a signed assertion for a short-lived, audience-bound capability instead of the static key, and that path refuses a caller-supplied delegation chain outright — but it is opt-in and unset until an operator wires an issuer up, so the static key is what an evaluation will meet first.

Conventional role models fail agents in two specific ways. The first is granularity: a role that grants a system rather than an action hands over the whole surface of that system, so a support agent that needs one read against the order database also gets the refund endpoint sitting next to it. The second is composition: agents call other agents, and a permission model with nothing to say about the second hop lets a low-privileged agent ask a higher-privileged one to do the thing it was just refused. Nobody has to escalate anything; the escalation is the architecture.

And an agent acting for a person is not the same as the person. A copilot running inside Alice’s authority should not be able to read what Alice cannot read — but the header that names Alice is a string the caller chose, with no signed claim behind it. Anything built on top of it has to stay safe when that string is a lie, which is a much stronger requirement than making it work when the string is true.

An action is allowed only when at least one permission on at least one of the agent’s roles explicitly allows it, and none denies it. There is no implicit grant anywhere in the evaluator. An agent holding no roles is refused, a role carrying an empty permission list grants nothing, and a resource that no permission names produces a refusal whose recorded reason ends in deny by default — which is the string an operator will search the flight recorder for when an agent starts failing.

The deny path returns before any allow is settled on, which is what makes precedence independent of ordering. A guardrail role that denies one refund tool wins whether it is listed before or after the broad role that grants the payments namespace, and it wins when both permissions sit inside the same role. That is what makes a subtractive guardrail a usable pattern rather than a race: you can grant tool:payments/* to a team and remove one action from one agent without rewriting the broad grant or duplicating it.

Matching is deliberately dull. A resource pattern is a literal string in which * matches any run of characters, slashes included; every other regex metacharacter is escaped before the pattern compiles, so an operator who types a full stop into a tool name gets a full stop rather than an accidental wildcard, and a permission on tool:orderdb/get_details does not match tool:orderdbXget_details. Actions are compared case-insensitively, and a permission listing * as its action matches any verb.

The on-behalf-of header names the person an agent is acting for, and it is recorded on the trace in every configuration — that much is unconditional, and it is what makes a request attributable to somebody. Whether it also narrows authority is a separate decision, staged in three settings, and it is off by default. Under off nothing is looked up at all: no principal lookup, no group lookup, no trace event, and the request costs what it cost before the feature existed. Under shadow the intersection is computed and written to the trace as a decision recording what it would have refused, while the request proceeds; the event’s status is never blocked, so a dry run stays distinguishable from an outage.

Under enforce, the roles that the named person’s directory groups map to are appended as the final link of the same delegation chain and run through the same evaluator, whose whole contract is that every link must allow. That single reuse is what makes the control safe to hand to an operator: a person whose group maps to a role granting the bare wildcard is a no-op rather than an escalation, because that wildcard satisfies its own link and cannot satisfy anyone else’s. It is the footgun an operator would otherwise reach for on day one, and the design removes it rather than documenting it.

Order is load-bearing in the other direction too. The agent’s own decision is derived before any field of the named human is read, and a deny short-circuits everything below it — no principal is resolved, no failure code is raised, and no event claims the human was the reason. A request the agent could never have made is refused for the reason the agent produced, so an intersection failure can never overwrite the real cause of a refusal in the record.

Failing to establish the human’s authority produces five distinct 403s rather than one shrug: the principal is not a known user; the principal is disabled; no group claims have ever been captured for them; the capture is older than the configured window; or their groups map to no role at all. The distinctions exist because the remedies differ — in one case that person needs to sign in through single sign-on, in another an administrator needs to add a group mapping — and an operator mid-rollout has to be able to tell those apart. A rollout can be rehearsed without committing: an administrator can preview a named person’s answer as though the instance were set to enforce, whatever it is actually set to.

Permissions are static grants: they stand until somebody edits the role. Nothing expires on its own, there is no just-in-time elevation, and agent credentials are long-lived bearer tokens rotated by hand — which the architecture decision record names as exactly the standing-privilege pattern the engineering handbook warns about. The controls that exist here are for noticing accumulation, not for preventing it, and saying so is more useful than implying otherwise.

Recertification is an append-only attestation that one named human reviewed one exact agent configuration, and what it binds is the part that matters for permissions: not merely the role ids an agent holds, but each referenced role’s name, its permission count and a digest of its normalised permissions. Editing a role therefore makes every affected review stale rather than letting an agent quietly inherit a review of the grant that role used to be. Ordering is normalised where ordering grants no different authority, so shuffling a permission list invalidates nothing, and a reviewer has to submit the exact snapshot digest they inspected — a review of a configuration that has since changed is refused rather than recorded.

A role cannot be deleted while anything still references it. The reference check runs unbounded inside the same transaction as the deletion and is serialised against the writers that assign roles to agents, to seats and to directory-group mappings, and the refusal reports how many of each still hold it along with a sample of the ids. Deleting a role out from under a running agent would be a silent permission change, and silent permission changes are the thing this part of the system exists to prevent.

Every role creation, edit and deletion is written to the hash-chained audit log with the acting user, and an edit records the previous permission list beside the new one. What a role granted last Tuesday therefore has an answer that does not depend on anybody’s memory, and the chain means an edit to that answer breaks verification at a known sequence number.