A Policy File for Routing Agent Actions by Risk Tier

Three tiers cover almost every practical case, and the assignment rule is simpler than most teams expect.

The decision rule: classify by worst-case outcome, not by likelihood. If reversing the action requires a human, a backup restore, or a call to a customer, it belongs in approve or blocked. If the worst case is a bad line in a report that someone will notice by lunchtime, it belongs in log. This reverses the usual instinct, which is to ask "how likely is the agent to do this?" Attackers do not care about your likelihood estimate. The MiniScope work on least-privilege authorization for tool-calling agents makes the same point from a different angle: agents diverge from user intent because of indirect prompt injection, model unreliability, or ambiguity in the request, so permissions should be scoped to what the task requires and nothing broader (MiniScope).

A second rule prevents tier inflation. Before you add a new blocked rule, check whether the action should not be reachable at all. If your agent's identity cannot call the payments API, marking payments.refund as blocked is belt and braces, fine to keep but not your primary defense. Access control for LLM systems differs from traditional access control because models can take real actions through tools and API keys are often shared across a team, which erases per-agent accountability unless a layer above them reintroduces identity (Maxim AI). The policy file governs what the agent decides to do; the credentials govern what it is capable of doing. You need both, and they should not be the same document.

The file is YAML, checked into the same repository as the agent, with a version field, a default tier, and an ordered rule list. Order matters because the first matching rule wins.

# policy/agent-actions.yaml
api_version: policy.agent/v1
policy_version: 2026.02.1
default_tier: blocked
owner: platform-security
rules:
  - id: block-credential-access
    action: "secrets.*"
    tier: blocked
    reason: "Agents never read secret material directly."
    ref: SEC-114

  - id: block-destructive-db
    action: "database.drop*"
    tier: blocked
    reason: "Irreversible. No approval path."

  - id: log-read-ops
    action: "crm.contact.search"
    tier: log
    log_fields: [query_hash, result_count, tenant]
    redact: [email, phone]

  - id: approve-money-movement
    action: "billing.refund*"
    tier: approve
    conditions:
      amount_threshold_usd: 50
      when_below: log
    approvers: ["role:finance-ops"]
    timeout_minutes: 240
    escalate_to: ["role:controller"]
    log_fields: [order_id, amount, currency, requester, agent_run_id]

  - id: approve-external-send
    action: "email.send"
    tier: approve
    conditions:
      allow_domains: ["@ourcompany.com"]
      when_domain_allowed: log
    approvers: ["role:comms"]
    timeout_minutes: 60

Five schema decisions are worth locking down early.

Patterns, not enums. Action identifiers are dotted namespaces (billing.refund.create, crm.contact.export). Wildcards match one segment or trailing segments. Keep matching anchored so email.send does not accidentally match marketing.email.send_bulk; if you need prefix matching, write it explicitly as email.send* and audit how often that pattern fires.

Conditions narrow, never widen. A rule with conditions evaluates them against the request context. If the condition fails, the engine falls through to the next matching rule, or to the default tier. It never promotes an approve rule to log unless the rule says so explicitly, as when_below does above. This keeps the fall-through direction predictable.

Approvers are roles or groups, not individuals. People change teams. A rule naming a role survives that; a rule naming a person generates a policy that silently cannot be satisfied. The approver must not be the requesting principal, enforced in code, not in YAML.

Log fields are declared per rule. Blanket logging of all parameters sounds safer and is not: it writes personal data and credentials into a log store with weaker access controls than the systems the data came from. OWASP's guidance on access control for retrieval systems makes the related point that cross-context leakage and unauthorized embedding access are real risks that strict partitioning addresses (OWASP LLM08). Logging deserves the same discipline.

Every rule carries a reason and a reference. When an auditor asks why refunds above the threshold need finance approval, the YAML answers without a meeting. This is the same mechanism Git provides for infrastructure policy generally: every change is timestamped, versioned and reviewable, which is what makes continuous compliance auditable (Wiz).

The gate is small: load, validate, compile patterns, then call it for every proposed action before execution. The critical implementation detail is where it sits. It must wrap the tool executor, not the model, because models do not follow instructions reliably and the executor is the only place that actually does anything.

import fnmatch
from dataclasses import dataclass

@dataclass(frozen=True)
class Decision:
    tier: str          # blocked | log | approve
    rule_id: str | None
    reason: str

class PolicyGate:
    def __init__(self, doc):
        if doc.get("api_version") != "policy.agent/v1":
            raise ValueError("unsupported policy api_version")
        self.version = doc["policy_version"]
        self.default = doc["default_tier"]
        self.rules = doc["rules"]

    def decide(self, action: str, context: dict) -> Decision:
        for rule in self.rules:
            if not fnmatch.fnmatchcase(action, rule["action"]):
                continue
            if self._conditions_hold(rule, context):
                return Decision(rule["tier"], rule["id"], rule["reason"])
            # condition failed: fall through, never widen
        return Decision(self.default, None, "no matching rule")

    def _conditions_hold(self, rule, context) -> bool:
        cond = rule.get("conditions") or {}
        if "amount_threshold_usd" in cond:
            return context.get("amount_usd", 0) > cond["amount_threshold_usd"]
        if "allow_domains" in cond:
            return context.get("recipient_domain") not in cond["allow_domains"]
        return True

def execute_action(gate, action, context, tool_call, propose_approval, emit_log):
    d = gate.decide(action, context)
    if d.tier == "blocked":
        emit_log("policy.blocked", action=action, rule=d.rule_id, policy=gate.version)
        raise PermissionError(f"{action} blocked by {d.rule_id}")
    if d.tier == "approve":
        token = propose_approval(action, context, d.rule_id)
        return {"status": "pending_approval", "token": token}
    emit_log("policy.allowed", action=action, rule=d.rule_id, policy=gate.version)
    return tool_call()

Three properties to verify in review. First, default_tier is blocked in production files, and a startup check refuses to boot if it is not. Second, the decision carries the policy version, so an audit event can be tied to the exact file that was in force. Third, approval returns a pending status rather than blocking a thread; the agent run should be resumable when the decision arrives, and the approval token must be single-use and bound to the exact action and context, so replaying it against a different amount fails.

The approval path deserves its own timeout behavior. When timeout_minutes elapses, the decision is deny, not allow. Silent expiry that resolves to the permissive option is the most common bug in first drafts of these systems, and it is the one that turns your approval gate into a slow automatic approval.

For tool registries that span models and providers, one useful simplification: put the gate at a single egress layer rather than reimplementing it per tool. Access control applied at a gateway covers identity, model and provider restrictions, tool permissions and consumption limits in one policy for every request, instead of each application reimplementing authentication and limits (Maxim AI).

The divergence failure is subtle. Runtime enforcement reads the YAML. Tests hardcode assertions like "refunds over 50 dollars need approval." Six months later someone raises the threshold to 500 and updates the YAML. The tests still pass. The behavior changed and nothing noticed. From then on your test suite documents a policy that no longer exists, and your reviewers trust it.

The fix is one loader function used by both paths.

def load_policy(path="policy/agent-actions.yaml"):
    with open(path) as f:
        return PolicyGate(yaml.safe_load(f))

Then the tests build their expectations from the file.

import pytest

@pytest.fixture(scope="session")
def gate():
    return load_policy()

@pytest.mark.parametrize("action", ["secrets.read", "database.drop_table"])
def test_blocked_actions_never_execute(gate, action):
    assert gate.decide(action, {}).tier == "blocked"

def test_refund_above_threshold_requires_approval(gate):
    rule = next(r for r in gate.rules if r["id"] == "approve-money-movement")
    threshold = rule["conditions"]["amount_threshold_usd"]
    above = {"amount_usd": threshold + 1}
    assert gate.decide("billing.refund.create", above).tier == "approve"

def test_unlisted_action_defaults_to_blocked(gate):
    assert gate.decide("internals.shell.exec", {}).tier == "blocked"

def test_approval_timeout_denies(gate):
    rule = next(r for r in gate.rules if r["id"] == "approve-money-movement")
    assert resolve_after_timeout(rule) == "deny"

Four test shapes cover most of the ground: blocked actions never execute, approval actions pause and return a pending token, unmatched actions fall to the default, and expired approvals deny. On top of those, add a drift test: a golden file of action names sampled from production traces, asserted to resolve to the tiers you expect. That test fails the moment someone adds a rule with a too-broad wildcard, which is the change most likely to widen access without anyone intending it.

Security testing in pipelines follows the same principle: checks belong where they produce feedback the developer can act on, with static analysis early and context-dependent checks later, and findings surfaced in pull requests rather than dashboards (Cycode). Treating your policy file like code under review gets you that for free, since the diff of a tier change is visible in the pull request.

A support operations agent handles refunds. The team logs actions for a month before enforcing anything, and the sample is 10,000 actions.

The approval load is 202 decisions per month on a 10,000-action base, roughly 2 percent. That is a workable operator burden. Now the naive alternative: enforcing approval on every refund rather than only those above the threshold produces 620 approvals, triple the load, and most of them for amounts too small to justify human attention. Confirmation fatigue is not hypothetical; MiniScope reported a 43.4 to 89.4 percent reduction in simulated permission confirmations for cautious and typical personas under a role-based model compared with per-call prompting, with privilege-escalation attacks still mitigated (MiniScope). Thresholds are how you get that reduction without lowering the tier on the cases that matter.

Run the same arithmetic on your own trace before you finalize thresholds. If the approval column exceeds roughly five percent of daily actions for a single role, either the threshold is too low or you have an upstream permissions problem. Both are useful findings, and you get them before enforcement goes live rather than from an exhausted operator on day three.

Four practices keep the file trustworthy over time.

Version the content, not just the filename. policy_version appears in every audit event and in every approval request, so an incident review can reconstruct exactly which rules were in force. Tag releases; never edit a version in place after it has been enforced in production.

Review tier changes as security changes. Moving a rule from approve to log is a privilege expansion. Require a second reviewer from the security owner, the same way you would review a change to a firewall rule. Policy-as-code tooling exists precisely because manual oversight creates gaps that automated guardrails close at scale (Wiz).

Keep a break-glass path that is itself logged. Approvals time out, operators go home, incidents happen. A named role can force an action with an incident ticket reference; the action executes at the log tier and emits a distinct audit event. A blocked rule should not be breakable at all, which is a property of the code, not the YAML.

Audit the wildcards quarterly. Grep every rule for trailing wildcards, count how many distinct actions each matched over the last quarter, and reshuffle any rule that matched actions you did not intend. In an endpoint context the same problem appears as denylist-only policy: a block list can only name components already judged bad, while an approved connector can reach for credentials or push data to an unapproved destination without changing its identifier (Backslash Security). Allow by specific action, deny by default, and inspect the matches regularly.

One integration note. Where your agent calls different model types, keep the gate independent of the model. A single endpoint covering text, image, video, audio and embedding models with an OpenAI-compatible interface, as offered by Quanta Inference, means the policy layer governs the action regardless of which model proposed it, which is the property you want during a model swap.