Rules reference
This page is the reference for rule files: every field a rule can have, how resources and conditions match, and how files layer.
A rules file is a YAML list of rule, list and macro entries, plus gate and budget entries, which are described in Runs, gates and budgets (preview). A required_engine_version entry says which engine level the file needs. Several files can be loaded in order, and later ones can change earlier ones.
Level 3 preview. Gates and budgets use run history supplied by the integration and need engine 0.2.0 or later. The local quickstart uses level-2 rules and works with any public release.
- required_engine_version: 1
- list: production_repositories
items: [acme/payments, acme/infra]
- macro: large_amount
condition:
- { field: amount, op: gt, value: 1000 }
- rule: Review production writes
desc: A person checks anything written to production.
tool: github
operation: issues.update
resource: { kind: repository, list: production_repositories }
effect: require_approval
tags: [write]
- rule: Review large refunds
tool: stripe
operation: refunds.create
resource: { kind: invoice, match: any }
condition:
- macro: large_amount
effect: require_approval
How a decision is made
Every matching rule counts, in any order. Deny beats require_approval, which beats allow. If no rule matches, the outcome is none, and whatever calls the engine must treat that as blocked.
Rule fields
| Field | Meaning |
|---|---|
rule | Unique name |
effect | allow, require_approval or deny |
tool, operation | The action, such as github and issues.update |
resource | kind plus one of the forms below |
command | Instead of tool, operation and resource. See Commands and tools |
condition | Conditions that must all hold |
agent, installation | Limit the rule to one agent, or one installation of it |
expires | ISO time when the rule stops applying |
enabled | false switches the rule off |
id | Keeps the rule's identity if it is renamed |
title | A display name, when two rules need to share one |
desc, tags | For people reading the file |
Resources
| Form | Matches |
|---|---|
{ kind: repository, match: any } | Anything of that kind |
{ kind: repository, match: exact, value: acme/app } | That value only |
{ kind: repository, match: prefix, value: acme/ } | Values starting with that text |
{ kind: repository, list: names } | One exact rule per list item. Add match: prefix for prefixes |
A prefix is literal text, so acme/support also matches acme/support-extra. End it with / when you mean a folder. File paths are in the machine's own form, so on Windows a folder is C:\repo\src\.
Conditions
- rule: Small refunds
tool: stripe
operation: refunds.create
resource: { kind: invoice, match: any }
condition:
- { field: amount, op: lte, value: 1000 }
- { field: currency, op: in, value: [USD, EUR] }
effect: allow
Operators: eq, neq, gt, gte, lt, lte, in and contains. contains tests whether an array has a value. field can reach into objects with dots.
Where a field lives depends on how the call was described. With nodrail.run() or check() it is the params you pass. A tool wrapped by guard() in @nodrail/client, or an MCP tool, carries its arguments under input, so the condition above reads { field: input.amount, op: lte, value: 1000 }. File calls carry path and path_parts; see Commands and tools.
An entry can also be { macro: name }, or { field: currency, op: in, list: name }.
{ field: path_parts, op: contains, list: name } matches when the array holds any item of the list. It compiles to one rule per item, so a rule can use it once. It needs required_engine_version: 2:
- required_engine_version: 2
- list: secret_places
items: [.env, .ssh, .aws]
- rule: Never read secrets
tool: files
operation: file.read
resource: { kind: file, match: any }
condition:
- { field: path_parts, op: contains, list: secret_places }
effect: deny
Conditions compare what the caller declares. A parameter that is missing or of the wrong type never helps an allow rule, while deny and review rules still apply. So "5" can't pass a rule that wants a number under 1000.
Ids
Decisions name the rule that won by its id: matchedRuleId in a result, and the reason Claude Code shows. Without an id, the id is made from the name: lowercased, with anything but letters, digits, _ and - turned into -, so Never force push is never-force-push. One rule can compile to several, and those get a suffix:
- A
command: { prefix: … }rule is two: the exact command keeps the id, and the command with arguments adds-args(never-force-push-args). - A rule over a list, or a condition with
containsand a list, adds a short hash of each item.
Set id when other things refer to the rule, such as dashboards, tests or a reviewer's notes, so renaming it keeps the same id. Gates and budgets take id the same way.
Lists and macros
A list is reusable values. A macro is reusable conditions, and can use other macros. They can be defined after the rules that use them. An empty list used by a rule is an error, so a list can't quietly remove a deny.
Layering files
Files load in the order given, and a folder loads its .yaml and .yml files by name. To change something from an earlier file, use override and say how each field changes:
- list: production_repositories
items: [acme/billing]
override: { items: append }
- rule: Review large refunds
effect: deny
override: { effect: replace }
- rule: Small refunds
enabled: false
override: { enabled: replace }
Lists, conditions and tags can be appended to. Everything else is replaced. Gates layer the same way; a budget's fields can only be replaced.
Unlike Falco, redefining a name without override is an error, so a later file can't silently weaken a rule.
Conditions are structured YAML rather than an expression language, which makes them simple to validate and leaves nothing to inject into. There is no general or: write two rules, or use contains with a list.
Limits
500 compiled rules, 20 conditions per rule, 1 MB per file. YAML aliases are limited, and duplicate keys are errors. Gates and budgets have their own limits (preview).
Files declare the engine level they need with required_engine_version. A file that needs a newer engine is refused. Level 1 is the base format, level 2 adds contains with a list, and level 3 adds gates and budgets and describes starting a subagent as an agent resource. See Versions (preview) for how this relates to the compiled document's version.