# Configuring Policy Conflict Resolution with ConflictResolutionStrategy in the Agent Governance Toolkit

> Configure policy conflict resolution in the Agent Governance Toolkit. Learn to use ConflictResolutionStrategy with DENY_OVERRIDES, ALLOW_OVERRIDES, PRIORITY_FIRST_MATCH, and MOST_SPECIFIC_WINS.

- Repository: [Microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit)
- Tags: how-to-guide
- Published: 2026-05-29

---

**The `ConflictResolutionStrategy` enum defines how the Microsoft Agent Governance Toolkit selects a winning decision when multiple policy rules generate conflicting candidate outcomes, supporting four strategies: `DENY_OVERRIDES`, `ALLOW_OVERRIDES`, `PRIORITY_FIRST_MATCH` (default), and `MOST_SPECIFIC_WINS`.**

Policy conflict resolution in the microsoft/agent-governance-toolkit ensures deterministic access control when overlapping governance rules apply to agent requests. When the policy engine evaluates a request, it collects **candidate decisions** from every matching rule and uses a configurable `ConflictResolutionStrategy` to determine the final outcome. The resolution process is handled by the `PolicyConflictResolver` class, which ranks candidates based on action type, priority values, or policy scope specificity.

## Understanding Conflict Resolution Strategies

The toolkit provides four distinct strategies in the `ConflictResolutionStrategy` enum defined in [`agent_os/policies/conflict_resolution.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent_os/policies/conflict_resolution.py) (lines 57-64). Each strategy implements a different decision hierarchy for resolving conflicts between candidate decisions.

### Available Resolution Strategies

**DENY_OVERRIDES** adopts a restrictive security posture where any deny rule takes precedence. If multiple candidates exist and at least one specifies a deny action, that decision wins regardless of priority or scope. Only when no deny rules are present does the highest-priority allow rule prevail.

**ALLOW_OVERRIDES** implements the opposite approach, favoring permissive access. Any allow rule automatically wins over deny rules. If no allow rules exist in the candidate set, the resolver falls back to selecting the highest-priority deny decision.

**PRIORITY_FIRST_MATCH** (the default) sorts candidates by their assigned priority value in descending order. The candidate with the highest integer priority wins the conflict, regardless of whether the action is allow or deny. This preserves legacy v1.0 toolkit behavior.

**MOST_SPECIFIC_WINS** evaluates the `PolicyScope` associated with each candidate, ranking by specificity where `AGENT` > `ORGANIZATION` > `TENANT` > `GLOBAL` (as defined in lines 66-76). When candidates share the same scope level, the strategy breaks ties using the priority value.

### Core Data Models

The resolution process relies on several Pydantic models defined in the canonical implementation. The `CandidateDecision` class (lines 87-109) encapsulates a rule's **action**, **priority**, **scope**, and audit metadata including the policy name, rule name, and approver information.

The `PolicyConflictResolver` class (lines 42-53) serves as the execution engine. It accepts a `ConflictResolutionStrategy` during initialization and exposes a `resolve()` method that processes a list of `CandidateDecision` objects and returns a `ResolutionResult`.

The `ResolutionResult` object (lines 31-40) contains the winning decision, the strategy applied, the count of candidates examined, a boolean indicating whether a genuine conflict occurred, and a human-readable **trace log** explaining the selection rationale.

## Configuring the Policy Engine

Configure the conflict resolution strategy when initializing the policy engine. The `Policy` class constructor in [`agentmesh/governance/policy.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agentmesh/governance/policy.py) (lines 491-513) accepts a `conflict_strategy` string parameter and internally converts it to the corresponding enum value.

```python
from agentmesh.governance.policy import Policy

# Initialize with MOST_SPECIFIC_WINS strategy

engine = Policy(
    conflict_strategy="most_specific_wins"
)

# Load and evaluate policies as usual

engine.load_policy(my_policy_definition)
result = engine.evaluate(request_context)

```

Valid string identifiers include `"deny_overrides"`, `"allow_overrides"`, `"priority_first_match"`, and `"most_specific_wins"`. Once configured, the engine automatically applies the selected strategy during every evaluation cycle without requiring manual intervention.

## Resolving Conflicts Programmatically

For advanced scenarios requiring direct control, instantiate `PolicyConflictResolver` explicitly with your preferred strategy and pass a list of `CandidateDecision` objects.

```python
from agentmesh.governance.conflict_resolution import (
    ConflictResolutionStrategy,
    CandidateDecision,
    PolicyConflictResolver,
    PolicyScope,
)

# Build candidate decisions from matching rules

candidates = [
    CandidateDecision(
        action="allow",
        priority=10,
        scope=PolicyScope.GLOBAL,
        policy_name="global-policy",
        rule_name="allow-everything",
    ),
    CandidateDecision(
        action="deny",
        priority=5,
        scope=PolicyScope.AGENT,
        policy_name="agent-override",
        rule_name="no-external-calls",
    ),
]

# Apply DENY_OVERRIDES strategy

resolver = PolicyConflictResolver(ConflictResolutionStrategy.DENY_OVERRIDES)
result = resolver.resolve(candidates)

print(f"Winner: {result.winning_decision.rule_name} -> {result.winning_decision.action}")
print("\n".join(result.resolution_trace))

```

This pattern is useful for unit testing custom rules or implementing custom policy evaluation pipelines outside the standard engine flow.

## Implementation Architecture and Backwards Compatibility

The codebase maintains backwards compatibility through a shim layer located at [`agentmesh/governance/conflict_resolution.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agentmesh/governance/conflict_resolution.py) (lines 19-34). This module attempts to re-export the canonical implementation from [`agent_os/policies/conflict_resolution.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent_os/policies/conflict_resolution.py) when the optional `agent_os` package is available, otherwise falling back to a pure-Python implementation in [`_conflict_resolution_impl.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/_conflict_resolution_impl.py) (lines 22-70).

This architecture ensures consistent import paths regardless of deployment context:

```python

# Works with or without agent_os installed

from agentmesh.governance.conflict_resolution import PolicyConflictResolver

```

The canonical implementation in [`agent_os/policies/conflict_resolution.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent_os/policies/conflict_resolution.py) serves as the source of truth for `ConflictResolutionStrategy`, `PolicyScope`, `CandidateDecision`, and `PolicyConflictResolver` definitions.

## Summary

- **ConflictResolutionStrategy** provides four resolution modes: `DENY_OVERRIDES`, `ALLOW_OVERRIDES`, `PRIORITY_FIRST_MATCH` (default), and `MOST_SPECIFIC_WINS`.
- Configure the strategy in `Policy.__init__` using the `conflict_strategy` parameter with lowercase string identifiers.
- The `PolicyConflictResolver` class executes the resolution logic on lists of `CandidateDecision` objects, producing a `ResolutionResult` with audit traces.
- **PolicyScope** specificity (AGENT > ORGANIZATION > TENANT > GLOBAL) determines rankings when using `MOST_SPECIFIC_WINS`.
- The `agentmesh.governance.conflict_resolution` module provides a stable import interface that automatically selects the appropriate underlying implementation.

## Frequently Asked Questions

### How do I change the default conflict resolution strategy for all policy evaluations?

Pass the desired strategy identifier to the `Policy` constructor via the `conflict_strategy` parameter. According to the source code in [`agentmesh/governance/policy.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agentmesh/governance/policy.py) (lines 491-513), the constructor converts this string to a `ConflictResolutionStrategy` enum and initializes the internal `PolicyConflictResolver`. For example, use `conflict_strategy="deny_overrides"` to ensure deny rules always take precedence.

### What happens when two rules have identical priority and scope under PRIORITY_FIRST_MATCH?

The resolver maintains the original candidate order during the priority sort (descending). When priority values are equal, the first candidate encountered in the input list wins the tie. The `resolution_trace` in the `ResolutionResult` documents which candidate was selected and why, enabling audit verification of tie-breaking behavior.

### Can I use different conflict resolution strategies for different policy sets?

Each `Policy` engine instance maintains a single conflict resolution strategy configured at initialization. To use different strategies for different policy sets, instantiate separate `Policy` objects with distinct `conflict_strategy` values. Alternatively, invoke `PolicyConflictResolver` directly with different strategies for ad-hoc evaluations without relying on the engine's default configuration.

### How does MOST_SPECIFIC_WINS determine scope specificity?

The strategy ranks candidates by the `PolicyScope` enum value defined in [`conflict_resolution.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/conflict_resolution.py) (lines 66-76). The specificity hierarchy is `AGENT` (most specific) > `ORGANIZATION` > `TENANT` > `GLOBAL` (least specific). When candidates share the same scope level, the resolver breaks ties using the numeric priority value assigned to each rule.