Writing Policies
Policies are declarative governance rules that control what agents can do. This guide shows you how to write custom policies for your Zakardo application.
Policy Structure
Section titled “Policy Structure”Every policy is a PolicyDocument with these components:
import type { PolicyDocument } from '@zakardo/core';
const myPolicy: PolicyDocument = { policy_id: 'unique-policy-id', name: 'Human-readable name', description: 'What this policy does and why.', version: '1.0.0', rules: [/* one or more rules */], scope: {/* when this policy applies */}, metadata: { author: 'team-name', created_at: '2026-01-01T00:00:00Z', enabled: true, priority: 100, },} as PolicyDocument;Writing Rules
Section titled “Writing Rules”Each rule has a condition, an action, and a message:
rules: [ { rule_id: 'gate-destructive-ops', condition: { field: 'effect_class', operator: 'equals', value: 'DESTRUCTIVE', }, action: 'GATE', message: 'Destructive operations require admin approval before proceeding.', },],Conditions
Section titled “Conditions”Conditions match against the capability being evaluated:
| Field | Description | Example Values |
|---|---|---|
effect_class | The capability’s effect class | READ, WRITE_INTERNAL, WRITE_EXTERNAL, DESTRUCTIVE |
boundary | Where the capability executes | LOCAL, REMOTE, USER_ENV |
capability_name | The capability name | contacts_delete, email_send |
tags | Capability tags | financial, admin |
Operators
Section titled “Operators”| Operator | Meaning |
|---|---|
equals | Exact match |
not_equals | Does not match |
in | Value is in a list |
not_in | Value is not in a list |
contains | String/array contains value |
Actions
Section titled “Actions”| Action | Runtime Behavior |
|---|---|
GATE | Pauses execution, requires human approval to continue |
DENY | Blocks the capability — Planner must find an alternative |
ALLOW | Explicitly permits (useful for overriding broader denials) |
WARN | Permits but logs a warning in the trace |
Setting Scopes
Section titled “Setting Scopes”Scopes control when a policy applies:
scope: { // Only in production and staging environments: ['production', 'staging'],
// Only for destructive capabilities effect_classes: ['DESTRUCTIVE'],
// Only for capabilities with these tags tags: ['financial', 'pii'],
// Only for specific capabilities capabilities: ['contacts_delete', 'account_close'],},All scope conditions are AND’d together — the policy only applies when all conditions match.
Example: Financial Transaction Policy
Section titled “Example: Financial Transaction Policy”A policy requiring approval for any financial transaction above $10,000:
const financialPolicy: PolicyDocument = { policy_id: 'financial-high-value', name: 'High-Value Transaction Approval', description: 'Transactions above $10,000 require manager approval.', version: '1.0.0', rules: [ { rule_id: 'gate-high-value', condition: { field: 'tags', operator: 'contains', value: 'financial', }, action: 'GATE', message: 'High-value financial transactions require manager approval.', }, ], scope: { environments: ['production'], tags: ['financial'], effect_classes: ['WRITE_EXTERNAL', 'DESTRUCTIVE'], }, metadata: { author: 'finance-team', created_at: '2026-01-01T00:00:00Z', enabled: true, priority: 200 },} as PolicyDocument;Example: Environment-Restricted Operations
Section titled “Example: Environment-Restricted Operations”A policy that denies external writes in development (to prevent accidentally sending real emails during dev):
const devSafetyPolicy: PolicyDocument = { policy_id: 'dev-no-external-writes', name: 'No External Writes in Development', description: 'Prevents accidental external side effects during development.', version: '1.0.0', rules: [ { rule_id: 'deny-external-in-dev', condition: { field: 'effect_class', operator: 'equals', value: 'WRITE_EXTERNAL', }, action: 'DENY', message: 'External writes are not permitted in the development environment.', }, ], scope: { environments: ['development'], effect_classes: ['WRITE_EXTERNAL'], }, metadata: { author: 'platform-team', created_at: '2026-01-01T00:00:00Z', enabled: true, priority: 300 },} as PolicyDocument;Registering Policies
Section titled “Registering Policies”Pass policies when creating the Zakardo app:
import { createZakardoApp, DEFAULT_POLICIES } from '@zakardo/core';
const { app } = await createZakardoApp({ config, capabilities: [...], implementations: [...], policies: [ ...DEFAULT_POLICIES, // Built-in defaults financialPolicy, // Your custom policies devSafetyPolicy, ],});Priority and Conflict Resolution
Section titled “Priority and Conflict Resolution”When multiple policies match the same capability:
- DENY always wins — if any policy denies, the capability is blocked
- GATE overrides ALLOW and WARN
- Among same-action policies, higher priority wins (higher number = higher priority)
Set priority in the metadata:
metadata: { // ... priority: 200, // Higher = takes precedence},Testing Policies
Section titled “Testing Policies”Use @zakardo/testing to verify policy behavior:
import { testPolicy, createTestRuntime } from '@zakardo/testing';
const runtime = await createTestRuntime({ capabilities: [deleteCapability], implementations: [...], policies: [destructiveApprovalPolicy],});
const result = testPolicy(runtime, deleteCapability, { user_id: 'user-1', roles: ['viewer'],});
expect(result.outcome.allowed).toBe(false); // Gate blocks itFurther Reading
Section titled “Further Reading”- Policies Concept — how policies fit into the execution lifecycle
- Effect Classes — the governance matrix
- Policy Specification — full specification