Policy Overview

Pavri policies govern what instrumented agents are allowed to do at runtime. Policies are evaluated locally in the SDK against a cached snapshot, with updates streamed from the backend.

How it works

1. An operator creates a policy in the dashboard or via the API.
2. The policy is assigned to one or more agents.
3. When an agent starts, the SDK fetches its assigned policies via GetPolicyBootstrap.
4. On every tool call, model invocation, or sensitive action, the SDK evaluates the cached rules locally — no network round-trip.
5. If a rule denies the action, the SDK raises a PolicyDeniedError that the framework plugin converts into a clean, structured error the agent can handle.
6. Policy updates propagate to running agents via the WatchPolicyUpdates stream.

Policy types

Pavri ships five built-in policy types, each backed by a typed rule evaluator in the SDK:

Type	What it governs	Default action
Tool ACL	Which tools an agent may call, by name or glob pattern	Deny unmatched tools (allowlist) or deny matched tools (denylist)
Domain ACL	Which network domains outbound calls may reach	Deny unmatched domains (allowlist) or deny matched domains (denylist)
Cost Budget	Cumulative token/cost spend per session or per agent	Block when budget exceeded
Rate Limit	Tool call frequency within a sliding time window	Throttle when rate exceeded
Data Classification	Sensitive data patterns (PII, credentials) in tool inputs/outputs	Alert or block on regex match

Enforcement modes

Every policy runs in one of three modes:

• Active — decisions are enforced. Denied actions raise errors.
• Shadow — decisions are logged but not enforced. Useful for rollout validation.
• Audit — decisions generate telemetry events for review without blocking.

Fail-open vs. fail-closed

By default the SDK operates fail-open: if the policy cache is empty or evaluation fails, actions are allowed. Security-critical deployments can set fail_mode: "closed" in PavriConfig to deny all actions when the policy state is unavailable.

What exists today

• Full policy CRUD via gRPC (PolicyManagementService) and REST API
• Policy assignment to agents with agent_policies table
• 5 pre-built policy templates
• SDK evaluator registry with typed rule evaluation
• enforce_policy() shared enforcement in all 7 framework plugins
• Interactive policy editor in the dashboard with save, create, delete, enable/disable, and template selection
• Prometheus metrics for policy decisions in both Go and Python

Deferred

• Policy-as-code DSL (Phase 2)
• Enforcement rollout with replay and calibration (Phase 2)
• Execution governance and sandbox routing (Phase 2)