Agent door
Capabilities & grants
A grant lists the exact capabilities an agent may exercise. Capabilities are the door's first authority layer; row-level security is the independent second.
Every tool the door exposes names a capability — a dotted
resource.verb string — that a caller's grant must hold. A workspace admin
issues a capability grant listing exactly which capabilities an agent may
exercise. The capability gate is the first authority layer; row-level security on
ctx.db is a second, independent one, so a bug in either cannot read or write a
row the other forbids.
The capability namespace
The grantable capabilities are derived from the live tool registry — a capability is
grantable if, and only if, some tool actually gates on it. There are eleven today — they back
the twelve tools in the Tools reference, because
action_item.update backs two: the write (update_action_item) and its
read-only status poll (get_approval_status).
| Capability | Kind | Grants access to |
|---|---|---|
diagnostic.list | read | List diagnostics |
diagnostic.read | read | Read a diagnostic |
report.read | read | Read a completed forensic report |
action_item.list | read | List action items |
action_item.read | read | Read an action item |
action_item.update | write | Request an action-item update (held for approval), and poll its status |
usage.read | read | Read workspace usage / quota |
strategic_assessment.list | read | List published strategic assessments |
strategic_assessment.read | read | Read a published strategic assessment |
infrastructure_audit.list | read | List published infrastructure audits |
infrastructure_audit.read | read | Read a published infrastructure audit |
Each capability maps to one or more tools in the Tools reference, which is generated from the same registry.
Reads: verb wildcards
For read tools, the gate honours a verb wildcard: a grant holding
diagnostic.* satisfies both diagnostic.list and
diagnostic.read. The wildcard is a convenience for read scopes only.
Writes: exact match, opt-in, never default
The single write capability, action_item.update, is exact-match:
a verb wildcard never unlocks it. Holding action_item.* for reads does
not grant the write. A workspace opts into a write deliberately, one capability at
a time, and no code path adds a write capability to a grant automatically. The approval poll
(get_approval_status) shares the same exact-match rule, so a read-only wildcard
grant can never even see the write queue.
Even with the write capability granted, the write itself is held for a human by default — see Write approvals.
Grants are org-scoped
A grant authorises exactly one organization. Every tool binds its query to that org in addition to row-level security, so a grant issued for one workspace can never reach another's rows — even if the underlying identity happened to have membership elsewhere.