Skip to content

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.

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;

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 match against the capability being evaluated:

FieldDescriptionExample Values
effect_classThe capability’s effect classREAD, WRITE_INTERNAL, WRITE_EXTERNAL, DESTRUCTIVE
boundaryWhere the capability executesLOCAL, REMOTE, USER_ENV
capability_nameThe capability namecontacts_delete, email_send
tagsCapability tagsfinancial, admin
OperatorMeaning
equalsExact match
not_equalsDoes not match
inValue is in a list
not_inValue is not in a list
containsString/array contains value
ActionRuntime Behavior
GATEPauses execution, requires human approval to continue
DENYBlocks the capability — Planner must find an alternative
ALLOWExplicitly permits (useful for overriding broader denials)
WARNPermits but logs a warning in the trace

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.

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;

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,
],
});

When multiple policies match the same capability:

  1. DENY always wins — if any policy denies, the capability is blocked
  2. GATE overrides ALLOW and WARN
  3. Among same-action policies, higher priority wins (higher number = higher priority)

Set priority in the metadata:

metadata: {
// ...
priority: 200, // Higher = takes precedence
},

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 it