First-Match-Wins

First-match-wins is a policy evaluation model in which rules are processed sequentially and the first rule whose conditions match the action being evaluated determines the verdict, with all subsequent rules ignored.

In Detail

When a policy engine receives an action to evaluate, it must determine which rule applies. In a first-match-wins model, the engine begins at the top of the rule list and checks each rule in order. The moment it finds a rule whose conditions match the action, it returns that rule's effect (allow, deny, or require_approval) and stops processing. No further rules are examined.

This model has several important properties:

Determinism

For any given action and any given rule set, the outcome is always the same. There is no ambiguity about which rule applies — it is the first one in the list that matches. This makes policy behavior predictable and debuggable.

Rule Order Significance

The order of rules is semantically meaningful. Reordering rules can change the outcome for the same action. This is both a strength and a responsibility. The administrator must arrange rules so that more specific rules appear before more general rules.

Consider this example:

Rule 1: file_write to ./src/generated/** → deny
Rule 2: file_write to ./src/**          → allow
Rule 3: deny all

An action writing to ./src/generated/output.ts matches both Rule 1 and Rule 2. Under first-match-wins, Rule 1 is checked first, matches, and returns deny. Rule 2 is never reached.

If the rules were reordered:

Rule 1: file_write to ./src/**          → allow
Rule 2: file_write to ./src/generated/** → deny
Rule 3: deny all

The same action now matches Rule 1 first and is allowed. Rule 2, which was intended to deny writes to generated files, is never reached. The policy has a logical error caused by incorrect ordering.

Performance

First-match-wins is efficient. In the best case (the first rule matches), evaluation requires checking a single rule. In the worst case (no rule matches), all rules are checked. For typical policy sizes (tens to hundreds of rules), evaluation is extremely fast.

Comparison with Other Models

• All-match / most-restrictive-wins. Every rule is evaluated, and the most restrictive matching effect is applied. This avoids ordering issues but is harder to reason about and slower.
• Most-specific-wins. All matching rules are considered, and the most specific one applies. This requires a definition of "specificity" and can be ambiguous when multiple rules have similar specificity.
• Priority-based. Each rule has an explicit priority number, and the highest-priority matching rule wins. This is similar to first-match-wins but decouples priority from ordering.

Examples

• A policy has three rules: (1) allow shell_exec for npm test, (2) allow shell_exec for npm run build, (3) deny all shell_exec. An agent running npm test matches Rule 1 and is allowed. An agent running npm run malicious matches no specific rule until Rule 3 and is denied.

• An administrator wants to deny network requests to .internal.corp but allow all other network requests. The correct ordering is: (1) deny network to .internal.corp, (2) allow network. Reversing these rules would allow all network requests, including those to internal domains.

• A policy accidentally places a broad allow all file_read rule before a specific deny file_read on ~/.ssh/** rule. Under first-match-wins, the broad allow matches first, and the SSH directory is exposed. Moving the deny rule above the allow rule fixes the issue.

Related Concepts

• Policy Engine — The component that implements first-match-wins evaluation.
• Deny-by-Default — The implicit final rule when no explicit rule matches.
• Action-Level Gating — The mechanism that sends each action to the policy engine for first-match-wins evaluation.
• Simulation Mode — A tool for testing rule ordering before enforcement.
• AI Agent Action Types — The action categories that rules specify conditions against.

In SafeClaw

SafeClaw, by Authensor, uses first-match-wins as its policy evaluation model. Policy rules are defined as an ordered list, and SafeClaw evaluates each action against the list sequentially. The first rule whose conditions match the action determines the verdict.

If no rule matches, SafeClaw's deny-by-default architecture applies: the action is denied. This means the rule list does not need an explicit "deny everything" rule at the end — the absence of a matching rule is equivalent to a denial.

SafeClaw's setup wizard and browser dashboard help administrators construct and order their rules correctly. Simulation mode is available for testing rule ordering before switching to enforcement, allowing administrators to observe how first-match-wins processes their specific agent workflows. SafeClaw evaluates policies locally with sub-millisecond latency across all four action types (file_write, file_read, shell_exec, network).

SafeClaw is 100% open source (MIT license), written in TypeScript strict mode with 446 tests and zero third-party dependencies. It works with Claude, OpenAI, and LangChain agents. Install with npx @authensor/safeclaw — free tier available with 7-day renewable keys and no credit card required.