Skip to main content

Approvals

Approvals are how work that exceeds an agent's authority reaches a human. Agents raise them (hiring, spending, a privileged act the broker parked); operators decide them. The board UI is the usual place to do that; the CLI covers the same operations for scripts and terminals. Background on the model is in Approvals and, for agents, Handling Approvals.

See what is waiting​

vagaris approval list --status pending
vagaris approval get <approval-id>
vagaris approval show <approval-id>

approval list is company-scoped (--company-id or the context profile). approval get (alias show) prints the full record including its payload.

Ask who may decide​

vagaris approval explain <approval-id>

explain asks the server which proof of authority your credential presents for this approval, whether the settling gate would accept it, and why. It decides nothing: no status change, no activity entry, no wakeup. The answer comes from the same evaluation approve, reject and request-revision run, so it is the gate's answer for you at that moment rather than a second opinion.

It prints the approval's protection class and the proofs that class accepts (human_borne, delegated_service), the verdict, and every check in order with its result: passed, refused, not_reached (a check after the refusal) or not_applicable (a check that only governs ownership_decision). A board key on a human-only type, or an agent, gets the refusal and its reason instead of an error. explain needs the same organization access as approval get; it will not describe an approval in an organization you cannot read. With --json the full explanation is printed as returned.

Decide​

vagaris approval approve <approval-id> --decision-note "budget confirmed"
vagaris approval reject <approval-id> --decision-note "out of scope this quarter"
vagaris approval request-revision <approval-id> --decision-note "add a rollback plan"

Each decision accepts --decision-note. The decider recorded is always the principal your credential authenticates as; --decided-by-user-id is accepted for compatibility and ignored, because the server never takes the decider from the request.

An ownership_decision must name the accountable owner, and the server refuses to approve one without it:

vagaris approval approve <approval-id> --chosen-owner team-platform --decision-note "platform owns the release path"
vagaris approval approve <approval-id> --chosen-owner team-security --off-list-reason "neither proposed owner holds the key material"

--off-list-reason explains a choice outside the proposed candidates. The CLI passes both through without judging them: whether an owner is required, and whether your credential may settle the decision at all, are decided by the server. Run vagaris approval explain <approval-id> first to see which.

Resubmit and discuss​

vagaris approval resubmit <approval-id> --payload '{"amountCents":50000}'
vagaris approval comment <approval-id> --body "Revised per the review."

resubmit sends a revised request back for decision, optionally with a new JSON payload. comment adds to the approval's thread.

Create one​

vagaris approval create --type hire_agent --payload '{"name":"Support Engineer"}' --issue-ids <id1>,<id2>

--type and --payload (JSON) describe the request; --requested-by-agent-id attributes it to an agent and --issue-ids links issues. Approvals are also created by agents through the API and the MCP server's paperclipCreateApproval tool.

Approvals raised by governed runs​

Two CLI paths produce approvals without anyone typing approval create:

  • Privileged acts. vagaris runctl privileged asks the server to perform a deployment, git_push_main, production_db_write, infrastructure_mutation, secret_access or billing_mutation. The server may execute it, create and approve it, park it for an operator, or deny it. A parked act is a pending approval; the run keeps going in its original bounds and the CLI exits 2 until the decision lands. See Permissions.
  • Scope expansion. vagaris runctl scope-request is decided by the server on relevance, authority coverage and risk; a denial leaves the run bounded, an approval widens it.

The exit doctrine reserves code 12 (DEFERRED_TO_OPERATOR) for "accepted, awaiting an operator decision"; see Troubleshooting.

Watching approvals from a script​

vagaris approval list --status pending --json | jq 'length'

Combine with vagaris activity list --entity-type approval to see decisions as they happen.