Action-level permissions

The failure that action-level permissions exist to prevent is easy to state and hard to notice in a code review. A support agent needs one read against the order database. Granted at the level of the system, it also holds whatever else that system exposes — the refund endpoint, the account-merge call, the bulk export. Nothing has gone wrong yet; the grant simply describes far more authority than anybody discussed. When the agent is later persuaded by a hostile ticket or a poisoned document to try something else, the boundary that decides how bad the day gets is the one written months earlier by somebody choosing between two lines of configuration.

The practical form is a resource string with a scheme, so that one vocabulary covers both surfaces an agent acts through. A model call is a resource such as a named model; a tool call is a server and a tool within it. That uniformity is what lets a single permission scope an entire tool server, or a model family, in one line, and it means a reviewer reads one grammar rather than two. Wildcards do the scoping, and the important detail is that the pattern is otherwise literal: every other metacharacter is escaped before matching, so a full stop in a tool name is a full stop rather than an accidental wildcard, and a permission on one tool does not match a differently-punctuated near-neighbour.

There is a hard boundary at the edge of what a permission can express, and honouring it is what keeps the model reviewable. A permission carries an effect, a resource pattern and a set of actions, and nothing else. It cannot read arguments. “Refunds above two hundred pounds need approval”, “no calls to this tool with data classified as health”, “redact card numbers on the way out” are all policy — a separate layer that matches on payload shape and data class and can block, redact, park a call on a named human or warn. Keeping the two apart is deliberate rather than a limitation: the question a permission answers is whether this agent may touch this tool at all, and that answer has to be readable in one line by a person who will put their name to it. A conditional grant that has to be simulated before anyone understands its scope is not something a reviewer can honestly attest to.

Visibility and enforcement are two jobs, and the difference is where implementations quietly fail. Filtering the catalogue an agent is shown — the model list, the tool list — to what its roles permit is worth doing, because a framework that picks a model off a list cannot pick one that will be refused three lines later, and an agent that never sees a tool does not spend its context reasoning about it. But the filter is not the control. The call itself has to be authorised again, or a client holding a stale catalogue reaches something that was revoked. There is a small related decision worth copying: asking directly for a model that exists but is not granted is better answered as not found than as forbidden, because telling an agent precisely which capabilities exist but are off-limits is free reconnaissance for whatever is driving it.

Refusing invisibly is not the same as refusing silently. A denied call is one of the most informative events an agent estate produces — an agent probing for tools it was never granted is exactly the pattern an investigation needs to see afterwards — so the refusal belongs on the record with the resource, the reason and the deciding role, whether or not the target existed. Two further limits are worth knowing before designing around them. Flat roles, without inheritance, mean a role intended as a superset of another has to restate its permissions: more typing, and far less to reason about when somebody asks what an agent can do. And most agent systems issue a single verb in practice, because a model call and a tool call are both invocations; a richer verb set is easy to add and hard to use meaningfully when the operation has no read-and-write distinction to express.