opschain admin trust grant

packs:agentspacks:agent-governance

opschain admin trust grant --scope <node-path> [subject] [--action <pattern>]… [--tier <tier>] [--act-as <class>] [flags]

Writes one trust grant (POST /api/trust/grants): the subject may request work matching the action patterns under the scope at the tier. Grants are deliberately the authz rule shape — (subject, path, action) — with the decision widened from allow/deny to a tier.

Tiers

Tier	Meaning
advise	May only produce recommendations.
supervised	Executes behind a server-injected approval gate.
autonomous	Executes ungated.

No matching grant means the request is refused — ADVISE is the lowest grant, not the default. (The one softening: an assets-under-management assignment confers ADVISE on its scope unless agents.assignment_floor is deny — see opschain admin trust assign.)

Subject

One of three forms:

• One agent: --agent <code> --project <code> — resolved to the agent's service-account principal at write time.
• A group: --subject-kind agent_group --subject <group-name> — every agent in the named fleet group.
• An attribute selector: --subject-kind attribute --subject <key> with one or more --subject-value <v> — every agent whose group carries a matching registered attribute value (trust policy that survives fleet churn).

(--subject-kind service_account --subject <principal-id> also works when you already hold the principal id.)

Scope and resolution

--scope is an absolute node path in the authz path grammar (* within a segment, ** any depth) and covers its whole subtree — an asset created tomorrow is governed by today's grant the moment it exists. When several grants match a request, a narrower lower-tier grant on a sub-path wins by specificity; tied grants resolve least-permissive. Grant writes recompile the trust snapshot immediately.

Flags

Flag	Meaning
--scope <path>	Node-path scope, subtree-covering (e.g. /projects/acme/environments/prod). Required.
--agent <code>	Agent code the grant addresses (with --project).
--project <code>	The agent's project (with --agent).
--subject-kind <kind>	Explicit subject kind: service_account, agent_group or attribute (alternative to --agent).
--subject <id>	Subject id: service-account principal id, group name, or attribute key.
--subject-value <v>	Attribute selector value (repeatable; with --subject-kind attribute).
--action <pattern>	Action-name pattern (repeatable; e.g. deploy_*, *, governance verbs like trust.grant). A grant needs at least one action pattern or an act_as class.
--tier <tier>	advise, supervised or autonomous. Required whenever action patterns are granted.
--approver <username>	Approver for SUPERVISED outcomes (repeatable). Default: the asset's owner metadata, then the agents.approvers setting.
--act-as <class>	Run-as class this grant confers: owner (asset-owner resolver), asker (chat-delegated reads at the asking user's own authority — GET-only, live-exchange-scoped) or a username (static delegation). May stand alone or combine with a tier grant.
--rate <n>	Cap: governed work requests per minute under this grant. 0 (the default) leaves the grant rate-capless. Over-cap requests refuse loudly and land the audited warn:trust:cap_refused event.
--budget <n>	Cap: work invocations per UTC day under this grant. 0 (the default) leaves the grant budget-capless.
--tokens-per-minute <n>	Token cap, the burst window: model tokens (input + output) the grant lets the agent spend through the model gateway in any sliding sixty seconds. 0 (the default) leaves the window capless.
--tokens-per-day <n>	Token cap per local day on the estate's reporting calendar (usage.timezone, project override). --tokens <n> is its alias (--tokens-per-day wins when both are given).
--tokens <n>	Alias of --tokens-per-day.
--tokens-per-week <n>	Token cap per local week, Monday 00:00 to Sunday.
--tokens-per-month <n>	Token cap per local calendar month.
--tokens-per-quarter <n>	Token cap per fiscal quarter (usage.fiscal_year_start).
--tokens-per-year <n>	Token cap per fiscal year.
--release-stage <rung>	Condition: the grant admits only agent instances whose enrolled release sits at or above this rung of the estate's stage ladder (opschain admin agent-release stages), compared by ladder position in the compiled trust snapshot; an instance enrolled without a release never satisfies it. Default: unconditional. A name that is not a rung is refused.
--note <text>	Audit note stored on the grant.
--server <url>	Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>	Admin bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Every token-cap window set is enforced per brokered call on a shared counter (replica-safe); the windows are checked minute first, then the calendar windows coarsest last, and the first one that fails is the one named in the refusal and in the audited warn:trust:cap_refused event with its local reset boundary. warn:trust:cap_approaching fires once per window per period at model_usage.cap_warning_fraction. Spend is read off the provider's own usage events; cache tokens are recorded but never metered. Set the caps from measurement with opschain agents usage in its recommend-caps mode (opschain docs provider-usage).

Human vs agent writes

A grant written by a human trust administrator activates immediately. An agent proposing a grant through its own API lane is capped at SUPERVISED, must itself hold trust.grant at SUPERVISED on the scope, and lands as a pending proposal a human activates with opschain admin trust approve (or refuses with reject) — grant changes by agents are always human-approved. Every write is audited.

Output

Always a machine document (JSON unless -o yaml): the stored grant with its id, subject, scope, actions, tier, approvers, act_as, status, note, granted_by, granted_at, rate, budget, tokens (the day cap), the six windows as tokens_per_minute, tokens_per_day, tokens_per_week, tokens_per_month, tokens_per_quarter and tokens_per_year, and, when set, release_stage.

Exit codes

Code	Meaning
0	The grant was stored (and, for a human write, is already active).
1	The server refused the grant (validation, unknown agent, rejected admin token).
2	Usage — the scope flag not set, or no server / admin token resolvable.

Named errors

Server-side validation (422, exit 1), quoted as the server reports them:

• unknown trust tier "<value>": advise, supervised or autonomous
• no such agent in that project
• trust grant subject is required for kind "<kind>"
• an attribute-selector grant names a registered key and at least one value
• unknown trust grant subject kind "<kind>": expected service_account, agent_group or attribute
• trust grant scope must be an absolute node path (its whole subtree is covered)
• trust grant must name at least one action pattern or an act_as class
• trust grant tier is required: advise, supervised or autonomous

CLI-side:

• required flag(s) "scope" not set — exit 2.
• a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' — exit 2.
• this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login' — exit 2.
• the server rejected the credential — run 'opschain login' again, or check the admin token — exit 1.

Examples

Let one agent deploy autonomously in dev:

opschain admin trust grant --agent sre --project demo \
  --scope /projects/demo/environments/dev --action 'deploy_*' --tier autonomous

Supervise everything a group does in prod, with named approvers:

opschain admin trust grant --subject-kind agent_group --subject sre-agents \
  --scope /projects/demo/environments/prod --action '*' --tier supervised \
  --approver alice --approver bob --note "prod stays gated"

Confer owner run-as on an attribute-selected cohort:

opschain admin trust grant --subject-kind attribute --subject region \
  --subject-value ap-southeast-2 --scope /projects/demo --act-as owner

Let the bundled SME read estate context at each asking user's own authority (the reads stay bounded by what every individual asker may see):

opschain admin trust grant --agent opschain-sme --project demo \
  --scope / --act-as asker --note "SME asker delegation"

Cap a grant on the burst minute and the fiscal quarter:

opschain admin trust grant --agent felix --project limebank \
  --scope /projects/limebank --action 'patch_*' --tier supervised \
  --tokens-per-minute 20000 --tokens-per-quarter 50000000

Related settings

• agents.approvers — fallback approvers for SUPERVISED outcomes when the grant names none and the asset carries no owner metadata.
• agents.assignment_floor — the no-grant floor an assignment confers.
• usage.timezone, usage.fiscal_year_start — the calendar the day, week, month, quarter and year windows reset on.
• model_usage.cap_warning_fraction — when warn:trust:cap_approaching fires.

See also

• opschain docs cli/agents-usage — measure usage and propose caps.
• opschain docs cli/admin-trust-list — every grant, full history.
• opschain docs cli/admin-trust-revoke, opschain docs cli/admin-trust-approve, opschain docs cli/admin-trust-reject — the grant lifecycle.
• opschain docs cli/admin-agent-trust-review — the evidence for a grant change.