How the gate decides

Draft for review

Everything an agent does goes through the gate: every step of its plan (read a collection, write a record, call a tool, send an email, issue a refund) is checked before it runs. The gate gives one of three answers: go ahead, wait for a named person to approve, or refuse. People's own actions pass the same gate.

This page explains the checks in the order the gate makes them, what each answer means, and how to ask the gate what it would decide before anything happens. By the end you can predict why the demo refund waits for Ada, and check your prediction with Try an action.

To follow along, start the demo company and sign in as described in the Quickstart: each person signs in by pasting the token ok demo serve prints for them. The demo runs without a model unless you set a provider key; a stub planner then answers the walkthrough's asks. Nothing on this page needs a real model.

This page describes the gate as it works today on the golive branch. What is not possible yet, and known problems, are listed at the end.

The three answers#

Explain adds a fourth answer, Conditional (It depends), when the result hinges on something it cannot see, such as whether the run has read a value, and lists each case. An approval that nobody could be found for, or for an action that could not run later, becomes a refusal instead.

The checks, in order#

The gate works through these checks for every step. The names in the first column are the labels you see in Try an action and on an approval's Why am I asked?.

The first refusal decides. In Try an action, the checks after it are still shown, greyed and marked (after the decision), so you can see everything you would have to change, not just the first thing.

Some checks are made again at the moment the step really runs, even after an approval: the kill switches, the argument rules (with what the run has read by then), the tool's rate limit, and what the caller may read in the collection. Explain lists these under Checked again when the call runs. Approving also checks the policy again first; see Inbox and approvals.

Risk tiers and trust tiers#

Risk belongs to the action, never to the agent. Trust belongs to the agent and caps how much risk it may take on its own.

A tool's risk is set by the pack that defines it. Try an action shows it in the first step: "support-ops.billing.refund is a tool: risk critical, handles financial data, reaches outside the company".

Every agent in the demo is standard.

The defaults, when no rule matches#

So, in the demo, the Churn-risk watcher may read Northwind's billing account and raise a ticket's severity on its own, and a calendar invite from the Sales Assistant waits for Alice because it reaches outside.

Rules#

Rules come from three places, shown in the Owner column of the rules table on Governance › Policy:

How they combine:

• A rule matches on who (agents only, people only, named actors, teams, roles), what (actions, tools, collections, data classes, a minimum risk or sensitivity) and, for money, an amount cap.
• Among the matching rules, the highest priority decides. At the same priority, deny beats require approval, which beats allow.
• A matching rule replaces the default. That is how a module makes a critical tool usable by agents at all: without a rule, an agent's critical action is denied.
• An amount cap fails closed: an amount the gate cannot read (missing, or text such as "$250") counts as over the cap.
• Module rules (step 12), a separate layer, only tighten: they can turn an allow into approval or a deny, never the other way. They are not the same as the rules a module installs, which appear in the rules table.

A rule's effect is allow, deny, or require approval from one of these:

The agent itself is never its own approver.

Argument rules on tools#

A tool can carry rules on its arguments. They are checked before the gate's policy checks, so nobody is asked to approve a call that could not run, and again when the call runs. They apply to people and agents alike.

Rules on the same argument are alternatives (any one passing is enough), except not_repeated, which must always pass. Rules on different arguments must all pass.

In the demo the GitHub connection lists no repositories, so explain shows every review comment from the PR Reviewer refused at Arguments: "argument repo is not listed under repos in the tool's connection config".

Worked example: the demo refund#

Ticket T-1042: Northwind was charged twice and wants 250.00 back. Maya asks the Churn-risk watcher to deal with it. Predict the answer before you check it.

The watcher acts for Maya with her delegation, inside its skill churn-watch, and wants to call support-ops.billing.refund (critical, financial, outside) with 250.00 on invoice inv-2026-09-1042.

1. Arguments. The invoice must be one the run read. The watcher read Northwind's account first, so it passes.
2. Delegation held, kill switch, active, skill, delegation, budget. Maya delegated to the watcher up to critical risk and $50.00; nothing is paused; churn-watch declares the tool and financial data; the budgets have room.
3. Rule. Two Support operations rules match, both for agents only: support-ops-refunds-need-admin (over 100.00, priority 20) and support-ops-credits-need-approval (every credit, priority 15). The higher priority decides: approval from the admin role.
4. Approver. Ada is the only admin. On the real approval, Why am I asked? says "Ada Park would be asked, and the run would wait until they decide."

So the refund waits for Ada, and Maya, although the watcher acts for her, cannot approve it.

What changes the answer:

For a small refund to go through on its own, an admin would add a company allow rule for the refund tool with a priority between 15 and 20 (say 18). For 50.00 the allow rule then outranks "every credit"; for 250.00 the over-the-cap rule at 20 still wins and the refund waits for Ada. You can test this without changing anything: propose the rule and explain against the proposal (see For developers). We did, and got Allowed for 50.00 and Needs approval from ada for 250.00 (each still It depends on the invoice having been read). The proposal itself lands in Ada's inbox as "Change proposed: 1 policy rules (...)" until someone decides it; nothing changes until it is applied.

To see the real thing, follow the refund in the Quickstart. On the approval, Why am I asked? shows the same steps the gate took when the watcher asked.

Asking the gate first: Try an action#

Try an action on Governance › Policy asks the gate what it would decide for one step, and why. Nothing runs, nothing is recorded, nobody is asked.

The list of people and agents under Who shows only those you may choose.

Explain the demo refund#

1. Sign in as ada (or as maya: the watcher acts for her). Open Governance, then the Policy tab (Governance opens on Approvals). On a phone, the sidebar with Governance is behind the menu button at the top left. Try an action sits under Source of truth.

2. Who: Churn-risk watcher (agent). An Acting for list appears, set to No one; choose Maya Patel.

3. Action: Use a tool (the default). Tool: Issue a refund or credit · support-ops.billing.refund. Do not pick Issue refund · billing.refund, a different tool from the Support module. The tool's arguments appear as fields: Amount *, Invoice * and Reason *.

4. Fill Amount 250, Invoice inv-2026-09-1042, Reason double charge, and press Explain.

5. You should see a yellow Conditional badge, It depends, the rule support-ops-refunds-need-admin (pack:support-ops), and two cases:

   • If the run has read the value: Needs approval from ada
   • If the run has not read it: Denied: argument invoice passes if the run has read it

   Below come the steps (Exists, Route, Arguments, Delegation held, Kill switch, Active, Delegation, Budget, Rule, Approver: "Ada Park would be asked"), then Checked again when the call runs (switches, argument rules, "5 calls a minute allowed; 0 used in the last minute"), and the line Under the live policy 01806d4e0eb8 · ... · Nothing was executed or recorded.

6. Change Amount to 50 and press Explain again. The rule is now support-ops-credits-need-approval, and the answer is still Needs approval from ada.

7. Change Who to Knowledge-base writer (agent). Acting for goes back to No one; choose Maya Patel again. The tool and its fields keep their values. Press Explain. You should see a red Deny, Denied: delegation does not cover tool support-ops.billing.refund, failing at Delegation, with the later steps (the second delegation limit, the budget, the deny rule) marked (after the decision).

The answer is conditional because Try an action has no run, so it cannot know whether the agent read the invoice first. The API can explain inside a real run, and then answers plainly (below).

More to try in the demo#

To see a kill switch in an answer, as Ada:

1. On the same page, in Kill switches, press Pause an agent, choose Churn-risk watcher under Agent and press Pause. The card now reads "Paused agents: Churn-risk watcher (an admin)".
2. Explain any of its tools, for example Billing account acting for Maya. You should see Deny, Denied: actor churn-watcher is paused, and the step "Kill switch: Actor Churn-risk watcher is paused: held by the admin". The policy hash in the last line changes while the switch is held.
3. Press Resume an agent, choose Churn-risk watcher and press Resume. "Paused agents: none" again.

Allowed for a read does not mean you see every row: the collection's own access decides that, and the note under Checked again says who may read it. An answer holds under the policy hash shown; the gate decides again when the step really runs.

Not possible yet#

• Explaining inside a run, or against a proposed policy, from the screen. Try an action always explains outside any run and under the live policy; use the API or ok policy explain with --run or --proposal.
• Explaining every kind of step from the screen. The screen offers the common ones; rollback, artifacts, thread decisions, playbook proposals and promotions are API and CLI only.

Known problems on this page#

• Explain misses a repeated refund. Explain does not check not_repeated. After Ada approved the T-1042 refund, explaining the same refund still answered Needs approval from ada, while the watcher's real second attempt was refused ("Invoice inv-2026-09-1042 was already refunded").
• The stub claims a refund it did not make. With no model, that refused second attempt still ends Done with the note "Refunded after an admin approved it."
• The global switch stops people too. Its confirmation says "People can still work", but people's reads and writes are refused while it is on.
• Why am I asked? starts at Delegation held. The steps stored on an approval leave out Exists, Route and Arguments, which explain shows.
• Approver shown by id. In Try an action's answer the cases read Needs approval from ada rather than Ada Park.
• "you would see only any row". Explaining a read of a collection open to every row of a team ends with this broken phrase.

For developers#

API#

POST /api/policy/explain with Authorization: Bearer <token>.

{
  "actor": "churn-watcher",
  "for": "maya",
  "skill": "churn-watch",
  "run": "<run id>",
  "policy": { "proposal": "<proposal id>" },
  "do": { "op": "tool", "tool": "support-ops.billing.refund",
          "args": { "invoice": "inv-2026-09-1042", "amount": 250, "reason": "double charge" } }
}

Everything but do is optional; actor defaults to the caller. do is one plan op as an agent writes it (tool, query, aggregate, upsert, delete, rollback, llm, post, artifact, decide, delegate, remember, recall, task, propose_playbook) or a syscall no op reaches (schema_apply, policy_change, actor_change, promote, connection_change, thread_create). For llm, data_class is a label string such as "pii.customer".

The answer holds decision (kind: allow, deny, require_approval with approvers and parks, or conditional with branches), matched_rule, steps and at_dispatch (each step: check, result, says, after_decision), policy (label, hash), at and executed: false.

With run set to a parked run you can see, the arguments are judged with what the run read, and the answer is plain: require_approval with "parks": true and "ada would be asked, and the run would wait until they decide".

With policy.proposal set to a Rules or Policy proposal you can see (admins and its proposer), the candidate decides and policy.label is proposal. A Rules proposal is made with POST /api/changes, {"kind": "rules", "rules": [...], "rationale": "..."}.

GET /api/approvals/:id/explain returns { asked, now, changed }: the steps stored when the approval was asked, explain for the same call now, and whether the decision, approver rule or matched rule has changed since.

CLI#

OK_TOKEN=<ada's token> ok policy explain --server http://127.0.0.1:8080 \
  --actor churn-watcher --for maya \
  tool support-ops.billing.refund \
  --args '{"invoice": "inv-2026-09-1042", "amount": 250, "reason": "double charge"}'

It prints the same answer as text, starting "churn-watcher for maya: it depends:". --op takes the whole op as JSON; --skill, --task, --thread, --run and --proposal fill the request's fields; --json prints JSON.

Events#

Explain records nothing. The real gate records a policy_evaluated event for every decision, budget_alert when a budget crosses its alert threshold, and approval_requested when it asks someone. See Events and the audit log.