Policies
Policies are declarative governance rules that control agent behavior. They define what actions are permitted, what requires approval, and what is denied — evaluated automatically at three points in the execution lifecycle.
Policy Structure
Section titled “Policy Structure”A policy is a JSON document with scopes, rules, and actions:
import type { PolicyDocument } from '@zakardo/core';
const destructiveApproval: PolicyDocument = { id: 'destructive-approval', name: 'Require approval for destructive operations', version: '1.0.0', scope: { environments: ['production', 'staging'] }, rules: [ { id: 'gate-destructive', description: 'Destructive capabilities require human approval', condition: { field: 'capability.effect_class', operator: 'eq', value: 'DESTRUCTIVE' }, action: { type: 'GATE', message: 'This operation will permanently delete data. Approve?', timeout_ms: 300_000, // 5 minutes }, }, ], metadata: { author: 'platform-team', created_at: '2026-01-01T00:00:00Z' },};Policy Scopes
Section titled “Policy Scopes”Scopes determine when a policy applies:
| Scope | Example | Meaning |
|---|---|---|
environments | ['production'] | Only applies in production |
tags | ['financial'] | Only applies to capabilities with matching tags |
roles | ['admin'] | Only applies to users with matching roles |
capabilities | ['contacts_delete'] | Only applies to specific capabilities |
Scopes can be combined. A policy with multiple scopes applies when all scope conditions are met.
Policy Rules
Section titled “Policy Rules”Each rule has three components:
- Condition — when the rule fires (e.g.,
effect_class == DESTRUCTIVE) - Action — what happens when the rule fires
- Priority — for conflict resolution when multiple rules match
Policy Actions
Section titled “Policy Actions”| Action Type | Effect |
|---|---|
GATE | Pauses execution and requires human approval to continue |
DENY | Blocks the capability entirely — the Planner must find an alternative |
WARN | Allows execution but logs a warning in the trace |
LOG | Records the action in the trace (audit trail) |
REQUIRE_MODE | Forces a specific execution mode (e.g., require DRY_RUN first) |
MODIFY_CONSTRAINT | Adjusts execution constraints (e.g., reduce timeout) |
Three Evaluation Points
Section titled “Three Evaluation Points”Policies are evaluated at three stages:
1. Pre-Generation (Planner)
Section titled “1. Pre-Generation (Planner)”Before the Planner includes a capability in a plan, it checks policies. If a capability would be DENY’d, the Planner finds an alternative (the Request Pattern). This ensures plans always succeed.
2. Pre-Execution (Validator)
Section titled “2. Pre-Execution (Validator)”The Validator’s policy compliance check (Check #8) evaluates all policies against the complete plan. This catches policy violations that span multiple steps.
3. Per-Step (Execution Engine)
Section titled “3. Per-Step (Execution Engine)”During execution, the Policy Engine evaluates policies before each capability invocation. GATE actions pause execution here, sending an A2UI prompt to the frontend for human approval.
Gates at Runtime
Section titled “Gates at Runtime”When a GATE action fires during execution:
- Execution pauses at the current step
- A gate prompt is sent to the frontend via SSE
- The user reviews the action and approves or rejects
- If approved, execution resumes. If rejected, execution fails gracefully
// Approve a gate via the client SDKawait client.executions.approveGate(executionId, { gate_id: gateId, approved: true, reason: 'Verified the deletion is intentional',});Gates have configurable timeouts. If no response arrives within the timeout, execution fails with a timeout error.
Default Policies
Section titled “Default Policies”Zakardo ships with two built-in policies:
- Destructive Approval —
DESTRUCTIVEcapabilities require aGATEin all environments - Audit Logging —
WRITE_EXTERNALcapabilities areLOGged in all environments
Import and use them:
import { DEFAULT_POLICIES } from '@zakardo/core';
const { app } = await createZakardoApp({ config, capabilities: [...], implementations: [...], policies: DEFAULT_POLICIES,});Conflict Resolution
Section titled “Conflict Resolution”When multiple policies match the same capability:
DENYtakes precedence over all other actionsGATEtakes precedence overWARNandLOG- Among same-type actions, higher priority wins
Further Reading
Section titled “Further Reading”- Writing Policies Guide — step-by-step guide to custom policies
- Effect Classes — the governance matrix
- Policy Specification — full 1,170-line specification