Which rule wins: priority
Priority is the number on a rule that decides order: the evaluator sorts every rule by priority from high to low and takes the first one that matches, so when two rules match the same call, the higher priority wins.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The Policy conditions and a missing field lesson matched one rule at a time. Real policies have rules that overlap, where a broad allow and a narrow deny both match the same call. Priority is how you say which one decides.
Two rules that both match a refund
This file has an allow rule and a deny rule, and both have a condition that matches a refund. The allow rule carries the higher priority, so it is checked first and wins.
version: "1.0"
name: refund-priority
rules:
- name: allow-refunds
condition: {field: action, operator: eq, value: refund}
action: allow
priority: 20
- name: deny-refunds
condition: {field: action, operator: eq, value: refund}
action: deny
priority: 10
defaults:
action: denyimport warnings; warnings.simplefilter("ignore")
from agent_os.policies.schema import PolicyDocument
from agent_os.policies.evaluator import PolicyEvaluator
doc = PolicyDocument.from_yaml("priority.yaml")
d = PolicyEvaluator(policies=[doc]).evaluate({"action": "refund"})
# both rules match; the evaluator takes the highest priority first
print("winner:", d.matched_rule, "| allowed:", d.allowed)winner: allow-refunds | allowed: True
Raising the deny rule above the allow
Nothing about the conditions changes. Raising deny-refunds above allow-refunds is enough to flip the verdict, because the evaluator now reaches the deny rule first.
# raise the deny rule above the allow rule; the conditions are untouched
rules = {r.name: r for r in doc.rules}
rules["deny-refunds"].priority = 30
d = PolicyEvaluator(policies=[doc]).evaluate({"action": "refund"})
print("winner:", d.matched_rule, "| allowed:", d.allowed)winner: deny-refunds | allowed: False
What the priority number did
- Both rules matched the refund in each run, so the condition is not what chose the winner.
- The first rule in priority order won, high to low, and the evaluator stopped at it without looking further.
- Flipping one number flipped the decision, from allowed to denied, with the two conditions left exactly as they were.
How the order is decided
| Priority | |
|---|---|
| Default when you omit it | 0 |
| Sorted | Highest first |
| The winner | The first matching rule in that order |
| A tie on priority | The earlier rule in the file is checked first |
Where priority matters
- A broad allow with a narrow exception, where a high-priority deny carves one tool out of a general allow.
- A deny you never want overruled, given the top priority so nothing checked later can allow it.
- A staged rollout, where a temporary high-priority rule sits above the permanent set and is removed later.
matched_rule on a decision to see which rule fired.Related
- Give both rules the same priority and see which one wins, then swap their order in the file.
- Remove the
priorityline from both rules and confirm they default to 0 and the file order decides. - Add a third rule with priority 100 that denies every action and watch it shadow the rest.
Little by little, you're building something great.