> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Architecture

# Policy Architecture

In Svantic, **everything is a policy**. Governance rules, safety guards, approval workflows, and alert routing are all expressed as policies — a single, unified system for controlling what agents can do and who gets notified when they do it.

***

## How Policies Work

Every operation in Svantic passes through the **Policy Engine**. When an agent invokes a tool, registers with the mesh, or triggers a platform event, the engine evaluates all matching policies in priority order and applies the first decisive enforcement.

<img src="https://mintcdn.com/svantic/BQDiyUefGxsfzbyO/images/diagrams/approval-workflow.svg?fit=max&auto=format&n=BQDiyUefGxsfzbyO&q=85&s=b30ffded64cf219d4f96978d15799cc9" alt="Policy evaluation: agent action triggers PolicyEngine, enforcement applied, notifications delivered" width="600" height="380" data-path="images/diagrams/approval-workflow.svg" />

The policy engine is the single control plane for governance, safety, and alerting. There is no separate "guardrails" system or "notification rules" system — it's all policies.

***

## Policy Anatomy

Every policy has:

| Field           | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| **Name**        | Human-readable identifier                                                             |
| **Scope type**  | What the policy applies to: `tool`, `admission`, or `event`                           |
| **Enforcement** | What happens when matched: `block`, `allow`, `require_approval`, `audit`, or `notify` |
| **Severity**    | `info`, `warning`, or `critical`                                                      |
| **Evaluator**   | Plugin that inspects the request (for governance policies)                            |
| **Channels**    | Where notifications are delivered                                                     |
| **Priority**    | Evaluation order (lower = higher priority)                                            |

***

## Scope Types

Policies apply to one of three scopes:

### Tool Policies (`scope_type: "tool"`)

Evaluated on every tool invocation. These control what agents can do — block dangerous operations, require approval for sensitive actions, enforce resource budgets.

### Admission Policies (`scope_type: "admission"`)

Evaluated when an agent registers with the mesh. These control which agent types are allowed to join — open registration, allow-list, or audit mode.

### Event Policies (`scope_type: "event"`)

Evaluated when platform events occur (agent health changes, session lifecycle, dispatch failures). These are purely informational — they don't block anything, they route alerts to the right channels.

***

## Enforcement Types

| Enforcement        | Behavior                                                                        | Stops Evaluation? |
| ------------------ | ------------------------------------------------------------------------------- | ----------------- |
| `block`            | Deny the request. Returns an error to the caller.                               | Yes               |
| `require_approval` | Pause the request and queue it for human review via [A2UI](/concepts/a2ui).     | Yes               |
| `audit`            | Allow the request but log it for review.                                        | No                |
| `allow`            | Permit the request. Typically a catch-all default.                              | No                |
| `notify`           | No enforcement — purely informational. Delivers alerts through linked channels. | No                |

Policies are evaluated in priority order. The first matching policy with a decisive enforcement (`block` or `require_approval`) stops evaluation. `audit`, `allow`, and `notify` policies continue evaluation so multiple can fire.

***

## Evaluator Plugins

Governance policies use evaluator plugins to inspect the request and decide whether the policy matches. Svantic ships with five built-in evaluators:

| Plugin              | Purpose                                                                       | Default Enforcement |
| ------------------- | ----------------------------------------------------------------------------- | ------------------- |
| `file_access`       | Blocks access to sensitive files (`.env`, `.key`, `.pem`, `~/.ssh`, `~/.aws`) | `block`             |
| `bulk_operation`    | Gates broad sweep operations (bulk deletes, mass updates)                     | `require_approval`  |
| `content_size`      | Limits maximum bytes per file read or tool result                             | `block`             |
| `resource_budget`   | Per-turn caps on reads, writes, and tool calls                                | `block`             |
| `command_execution` | Restricts shell commands — allowlisted patterns, blocks dangerous ops         | `require_approval`  |

Each evaluator is configurable. For example, `file_access` accepts a `denied_patterns` array, `resource_budget` accepts per-turn limits, and `bulk_operation` accepts a threshold.

***

## Flow-Level Safety

Beyond per-tool policies, Svantic enforces flow-level safety at the execution run level:

| Guard               | What It Prevents                                        |
| ------------------- | ------------------------------------------------------- |
| **Step limit**      | Infinite loops — caps total agent steps per task        |
| **Timeout**         | Runaway execution — maximum wall-clock time per task    |
| **Cycle detection** | Circular transfers — agents passing work back and forth |

These are always active and operate independently of tool-level policies.

***

## Creating Policies

**Dashboard:** Navigate to **Settings → Policies**, click **New Policy**, and configure the scope, enforcement, evaluator, and channels.

**API:**

```bash theme={null}
curl -X POST https://api.svantic.com/internal/policies/new \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block credential access",
    "scope_type": "tool",
    "enforcement": "block",
    "severity": "critical",
    "reason": "Access to credential files is prohibited",
    "evaluator": {
      "plugin": "file_access",
      "config": {
        "denied_patterns": [".env", "*.key", "*.pem"]
      }
    }
  }'
```

**Event policy (alerts):**

```bash theme={null}
curl -X POST https://api.svantic.com/internal/policies/new \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alert on failures",
    "scope_type": "event",
    "enforcement": "notify",
    "event_type": "dispatch.failed",
    "severity": "critical",
    "cooldown_seconds": 300,
    "channels": [
      { "channel_id": "your-slack-channel-id" }
    ]
  }'
```

***

## Built-in Policies

Every tenant receives a set of built-in policies during provisioning. These can be toggled on/off but cannot be deleted:

| Policy                       | Scope       | Enforcement        |
| ---------------------------- | ----------- | ------------------ |
| File access protection       | `tool`      | `block`            |
| Bulk operation gating        | `tool`      | `require_approval` |
| Content size limits          | `tool`      | `block`            |
| Resource budgets             | `tool`      | `block`            |
| Command execution            | `tool`      | `require_approval` |
| Default admission            | `admission` | `allow`            |
| Approval needed notification | `event`     | `notify`           |

These provide sensible defaults out of the box. Customize thresholds and enforcement levels to match your requirements.

***

## Managing Policies via API

| Endpoint                            | Purpose                                         |
| ----------------------------------- | ----------------------------------------------- |
| `POST /internal/policies/get`       | List policies (with optional filters)           |
| `POST /internal/policies/get_by_id` | Get a single policy with its linked channels    |
| `POST /internal/policies/new`       | Create a policy                                 |
| `POST /internal/policies/update`    | Update a policy (partial updates supported)     |
| `POST /internal/policies/delete`    | Delete a policy                                 |
| `POST /internal/policies/test`      | Send test notifications through linked channels |

***

## Linking Channels

Any policy can deliver notifications through linked [channels](/guides/channels). Link channels when creating or updating a policy:

```bash theme={null}
curl -X POST https://api.svantic.com/internal/policies/update \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "bulk_ops_approval",
    "channels": [
      { "channel_id": "slack-channel-uuid", "enabled": true },
      { "channel_id": "email-channel-uuid", "enabled": true }
    ]
  }'
```

***

## Common Event Types

For `scope_type: "event"` policies:

| Event                    | When It Fires                    |
| ------------------------ | -------------------------------- |
| `message.input_required` | A request needs human input      |
| `agent.registered`       | An agent registers with the mesh |
| `agent.deregistered`     | An agent is removed              |
| `agent.health_changed`   | An agent's health status changes |
| `dispatch.failed`        | A tool dispatch failed           |
| `session.started`        | A new session begins             |
| `session.completed`      | A session finishes               |