Trust grant and assignment

packs:agentspacks:agent-governance

A trust grant is one tiered permission for an agent subject: what actions it may take, where (a node-path scope), at which tier (advise, supervised or autonomous), under which caps, and — optionally — only from a release at or above a stage of the estate's ladder, with its full decision history on the row. Grants are proposed by agents or created by humans; the human approve/reject decisions settle pending proposals and pending revoke proposals. A trust assignment is one assets-under-management row: the agent's inventory, and the natural scope to hang higher-tier grants on. Served by the v2 TrustService (admin-only): ListTrustGrants, ApproveTrustGrant, RejectTrustGrant, CreateTrustAssignment, ListTrustAssignments and DeleteTrustAssignment; the agent-credential lane (grant creation and revoke proposals by agents) stays on the REST trust routes, which serve the same stored rows.

TrustGrant

TrustGrant is one grant with its full decision history — the same fields the REST listing serves, typed. The listing is the full history: active grants (the only ones compiled into the trust snapshot), pending proposals awaiting a human decision, and revoked grants kept as audit artifacts.

Field	Type	Meaning
act_as	string	The run-as class the grant confers, when it is an act-as grant.
actions	array of string	Action-name patterns the grant permits.
approved_at	timestamp	When the grant was approved (a pending proposal activated).
approved_by	string	Decision attributions, set where those transitions happened.
approvers	array of string	Approver usernames for SUPERVISED outcomes; empty falls back to the asset's owner metadata, then the configured agent approvers.
budget_per_day	integer	Work-invocation cap per UTC day; zero means capless.
granted_at	timestamp	When the grant was created (proposed or human-created).
granted_by	string	Who created the grant — the proposing agent's principal or the creating human.
id	string	The grant's identity.
note	string	Free-text note recorded with the grant.
rate_per_minute	integer	Caps: governed requests per minute, work invocations per UTC day and model tokens per UTC day; zero means capless.
release_stage	string	The release-stage condition: the grant admits only an instance whose enrolled release sits at or above this rung of the estate's stage ladder (opschain docs agent-releases); "" is unconditional. A rung the ladder lacks never admits; a ladder change that would strand the condition is refused.
revoke_proposed_at	timestamp	When a revoke was proposed; an active grant carrying a pending revoke proposal shows both fields while it stays active.
revoke_proposed_by	string	Who proposed the revoke.
revoked_at	timestamp	When the grant was revoked (a pending grant refused, or an active grant's revoke applied).
revoked_by	string	Who settled the revoke.
scope	string	The node-path glob the grant covers, whole subtree included.
status	string	"active", "pending" or "revoked".
subject_id	string	The subject's identifier per subject_kind: the service-account principal id, the agent-group name, or the attribute key.
subject_kind	string	The subject vocabulary: "service_account", "agent_group" or "attribute"; subject_id carries the principal id, group name or attribute key, and subject_values an attribute selector's accepted values.
subject_values	array of string	An attribute selector's accepted values (subject_kind "attribute" only).
tier	string	The granted tier: "advise", "supervised" or "autonomous".
tokens_per_day	integer/string	Model-token cap per local day on the estate's reporting calendar (usage.timezone); zero means capless. The --tokens alias writes it.
tokens_per_minute	integer/string	Model-token cap on the sliding sixty-second burst window; zero means capless.
tokens_per_month	integer/string	Model-token cap per local calendar month; zero means capless.
tokens_per_quarter	integer/string	Model-token cap per fiscal quarter (usage.fiscal_year_start); zero means capless.
tokens_per_week	integer/string	Model-token cap per local week (Monday 00:00); zero means capless.
tokens_per_year	integer/string	Model-token cap per fiscal year; zero means capless.

Decision semantics: ApproveTrustGrant activates a pending grant, or applies an active grant's pending revoke proposal; RejectTrustGrant revokes a pending grant without it ever activating, or clears a pending revoke proposal leaving the grant active. A grant held by an open trust-raise ceremony refuses the decision and names the approvals inbox; the GUI's Trust tab disables its Approve and Reject for such a grant with the checklist's eligibility reason and links the Inbox row instead.

TrustAssignment

TrustAssignment is one assets-under-management row: the agent's inventory, and the natural scope to hang higher-tier grants on.

Field	Type	Meaning
created_at	timestamp	When the assignment was recorded.
created_by	string	Username of the recording identity.
id	string	The assignment's identity.
note	string	Free-text note recorded with the assignment.
role	string	The management role the row records; defaults to "manages" when not supplied.
scope	string	The node-path scope assigned under management.
subject_id	string	The agent's service-account principal id.

Every token-cap window set is enforced per brokered call on a shared counter; the first failing window — minute first, then day, week, month, quarter, year — is named in the refusal and in warn:trust:cap_refused with its local reset boundary (opschain docs provider-usage).

What settings change this

• agents.approvers — the final fallback approver set for SUPERVISED outcomes when a grant names none and the asset's owner metadata is empty.
• usage.timezone, usage.fiscal_year_start — the calendar the day, week, month, quarter and year token windows reset on (project override); model_usage.cap_warning_fraction — when warn:trust:cap_approaching fires.

Related pages

• opschain docs agent-plane — the component page: tiers, the governed request lane and the trust snapshot.
• opschain docs resources/agent — the enrolled agent and its trust-review evidence views.
• opschain docs governance — how grants, reviews and recommendations compose.