Policy

A policy is an ordered list of rules. The first rule that matches a tool call wins. If no rule matches, the default_verdict applies.

YAML policy

Policies are defined in your guard_config.yaml file. Each policy has a name, a list of action types to match, a condition expression, and a verdict:

version: "1.0"

global:
  default_verdict: BLOCK

policies:
  - name: block-system-config
    action_types: ["*"]
    condition: 'parameters.get("path", "").startswith("/etc/")'
    verdict: BLOCK
    message: "System config is off-limits"

  - name: block-env-files
    action_types: ["*"]
    condition: '".env" in parameters.get("path", "")'
    verdict: BLOCK
    message: "No .env access"

  - name: allow-tmp
    action_types: ["file.read", "file.write", "file.delete"]
    condition: 'parameters.get("path", "").startswith("/tmp/")'
    verdict: ALLOW

  - name: escalate-schema-changes
    action_types: ["db.execute"]
    condition: '"DROP TABLE" in str(parameters)'
    verdict: ESCALATE
    message: "Schema changes require human approval"

guard = ActionGuard.from_config("guard_config.yaml")

Policy fields

Field	Type	Description
`name`	`str`	Unique identifier for the rule
`action_types`	`list[str]`	Action types to match. `["*"]` matches all.
`condition`	`str`	Python expression evaluated against the `ActionIntent`
`verdict`	`str`	One of `ALLOW`, `BLOCK`, `ESCALATE`, `DEFER`, `WARN`
`message`	`str`	Human-readable reason shown when the rule fires
`escalate_to`	`str \| None`	Target for escalation (e.g. `"human"`)

Verdict types

Verdict	Behaviour
`ALLOW`	Tool executes normally
`BLOCK`	Tool not called. `ExecutionBlockedError` raised.
`ESCALATE`	Execution paused. `ActionEscalatedError` raised. Pending human approval.
`DEFER`	Deferred for async evaluation. `ActionDeferredError` raised.
`WARN`	Executes but emits a warning to the audit log

Default verdict

Always set default_verdict: BLOCK in production. This fails closed — any tool call that doesn’t match a policy rule is blocked. Unmatched calls are the most common source of unexpected agent behaviour.

Risk levels

The RiskLevel enum sets a baseline risk score for a protected action. The dynamic risk scorer adjusts it based on context (agent trust, parameters, etc.).

from plyra_guard import RiskLevel

@guard.protect("db.delete", risk_level=RiskLevel.HIGH)
def delete_record(id: str): ...

Level	Base score	Intent
`RiskLevel.LOW`	0.1	Read operations
`RiskLevel.MEDIUM`	0.3	Reversible writes (default)
`RiskLevel.HIGH`	0.6	Destructive or irreversible
`RiskLevel.CRITICAL`	0.9	System-level or wide-scope

Trust levels

The TrustLevel enum classifies agents in multi-agent systems. Trust determines what risk thresholds an agent can execute under.

from plyra_guard import TrustLevel

guard.register_agent("researcher", trust_level=TrustLevel.PEER)

Level	Trust score	Description
`TrustLevel.HUMAN`	1.0	Human operator — full trust
`TrustLevel.ORCHESTRATOR`	0.8	Top-level orchestrating agent
`TrustLevel.PEER`	0.5	Peer agent in a collaborative system
`TrustLevel.SUB_AGENT`	0.3	Delegated sub-agent
`TrustLevel.UNKNOWN`	0.0	Unregistered or unknown agent

Dry-run evaluation

Test a policy without executing anything:

from plyra_guard import ActionIntent, Verdict

intent = ActionIntent(
    action_type="file.delete",
    tool_name="delete_file",
    parameters={"path": "/etc/passwd"},
    agent_id="default",
)

result = guard.evaluate(intent)
print(result.verdict)    # Verdict.BLOCK
print(result.reason)     # "System config is off-limits"

guard.evaluate() takes an ActionIntent object, not a plain string. See the API reference for all ActionIntent fields.

Real-world policy example

A policy for a database agent that can read freely but must escalate any destructive operation and block schema changes entirely:

version: "1.0"

global:
  default_verdict: BLOCK

policies:
  - name: allow-select
    action_types: ["db.query", "db.execute"]
    condition: 'str(parameters.get("sql", "")).strip().upper().startswith("SELECT")'
    verdict: ALLOW

  - name: escalate-delete
    action_types: ["db.execute"]
    condition: |
      any(kw in str(parameters.get("sql", "")).upper()
          for kw in ["DELETE", "UPDATE", "TRUNCATE"])
    verdict: ESCALATE
    message: "Destructive DB operation requires human approval"
    escalate_to: "human"

  - name: block-schema
    action_types: ["db.execute"]
    condition: |
      any(kw in str(parameters.get("sql", "")).upper()
          for kw in ["DROP", "ALTER", "CREATE TABLE", "RENAME"])
    verdict: BLOCK
    message: "Schema changes are not permitted by agents"

Rules are evaluated top to bottom. A SELECT query matches the first rule and is allowed immediately. A DELETE matches the second rule and is paused for approval. A DROP TABLE matches the third rule and is blocked outright. Any query that matches none of the rules hits the default_verdict: BLOCK.

Getting started

Core concepts

Integrations

Reference

YAML policy

Policy fields

Verdict types

Default verdict

Risk levels

Trust levels

Dry-run evaluation

Real-world policy example

​YAML policy

​Policy fields

​Verdict types

​Default verdict

​Risk levels

​Trust levels

​Dry-run evaluation

​Real-world policy example

YAML policy

Policy fields

Verdict types

Default verdict

Risk levels

Trust levels

Dry-run evaluation

Real-world policy example