opschain admin agent trust-review

packs:agentspacks:agent-governance

opschain admin agent trust-review <agent> [--server <url>] [--auth-token <token>]

Shows one agent's trust review (v2 AgentService.GetAgentTrustReview) — the decision-support view a trust administrator reads before promoting (or demoting) the agent's grants:

• requests_by_tier — how many requests the agent made at each applied tier (counted from its audit timeline), and requests_refused — how many were refused outright (no matching grant).
• recommendations — the agent's recommendation outcomes by status (accepted, dismissed, expired, superseded, open): the track record of its ADVISE-tier output.
• grants — the active trust grants that apply to the agent's governance subject (its service-account principal, its group, and the group's registered attributes).
• assignments — its assets-under-management assignments.
• assignment_floor — the server's configured no-grant floor (advise or deny), so the review reads correctly on strict compositions.

Together: "this agent asked for N things, M were refused, its advice was accepted K times, and here is what it currently holds" — the evidence for a grant change via opschain admin trust grant.

<agent> is the agent's member id (the ID column of opschain admin agents list), <project>/<code>, or a bare agent code when exactly one project holds it. A bare code that several projects hold is refused with the project/code candidates to pick from, and a reference matching no agent is refused by name.

Flags

Flag	Meaning
--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.

Output

Always a machine document (JSON unless -o yaml) with the keys agent_id, code, requests_by_tier, requests_refused, recommendations, grants, assignments and assignment_floor, plus — where declared — owned_by, type (with tier_ceiling when the type has a ceiling row), release (the enrolment-bound signed AgentRelease: id, name, version, current stage) with the same facts flat beside it as release_name, release_version and release_stage (so a renderer names the release without opening the object), disclosures (the manifest disclosure set /; disclosures_from_release: true when it renders from the release's frozen manifest), tokens_by_provider (model-token spend per model provider over the reviewed timeline — calls, input, output and total tokens, read off each brokered call's audit event), token_caps (observed-versus-cap per window for every active token-capped grant that applies to the agent: per grant its grant_id, scope, the reporting timezone and fiscal_year_start, windows — each with window, cap, used, fraction, window_start and resets_at in the reporting zone — and the minute distribution p95_minute_tokens, peak_minute_tokens, minutes_observed; the evidence opschain agents usage in its recommend-caps mode turns into a proposal) and cost_centre (the effective core.cost_centre metadata at the agent's project, when one is set — the cost attribution AI spend lands under).

Exit codes

Code	Meaning
0	The review was printed.
1	The server refused or failed the request (including a rejected admin token, or an unknown id).
2	Usage — wrong arguments, or no server / admin token resolvable.

Named errors

• 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.
• agent <id> is not known to this estate — admin agent verbs take the ocr_ member id from 'opschain admin agents list' (a UUID is usually the identity-side service_account_id, not the member id) — the unknown, revoked or runner id 404, exit 1.
• agent code "<code>" is ambiguous across projects — name it as project/code: <candidates> — a bare code several projects hold; exit 1.
• no agent matches "<ref>" — use the ocr_ member id, project/code, or an agent code from 'opschain admin agents list' — exit 1.

Related settings

• agents.assignment_floor — what an assignment confers with no matching grant (advise, or deny for the strict posture); echoed in the review.

See also

• opschain docs cli/admin-agent-activity — the raw timeline behind the counts.
• opschain docs cli/admin-trust-grant — act on the review.
• opschain docs cli/agents-usage — the usage behind token_caps, and the recommend-caps mode.
• opschain docs cli/admin-trust-list — every grant, including pending and revoked history.