Skip to content

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.

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' },
};

Scopes determine when a policy applies:

ScopeExampleMeaning
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.

Each rule has three components:

  1. Condition — when the rule fires (e.g., effect_class == DESTRUCTIVE)
  2. Action — what happens when the rule fires
  3. Priority — for conflict resolution when multiple rules match
Action TypeEffect
GATEPauses execution and requires human approval to continue
DENYBlocks the capability entirely — the Planner must find an alternative
WARNAllows execution but logs a warning in the trace
LOGRecords the action in the trace (audit trail)
REQUIRE_MODEForces a specific execution mode (e.g., require DRY_RUN first)
MODIFY_CONSTRAINTAdjusts execution constraints (e.g., reduce timeout)

Policies are evaluated at three stages:

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.

The Validator’s policy compliance check (Check #8) evaluates all policies against the complete plan. This catches policy violations that span multiple steps.

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.

When a GATE action fires during execution:

  1. Execution pauses at the current step
  2. A gate prompt is sent to the frontend via SSE
  3. The user reviews the action and approves or rejects
  4. If approved, execution resumes. If rejected, execution fails gracefully
// Approve a gate via the client SDK
await 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.

Zakardo ships with two built-in policies:

  1. Destructive Approval — DESTRUCTIVE capabilities require a GATE in all environments
  2. Audit Logging — WRITE_EXTERNAL capabilities are LOGged in all environments

Import and use them:

import { DEFAULT_POLICIES } from '@zakardo/core';
const { app } = await createZakardoApp({
config,
capabilities: [...],
implementations: [...],
policies: DEFAULT_POLICIES,
});

When multiple policies match the same capability:

  • DENY takes precedence over all other actions
  • GATE takes precedence over WARN and LOG
  • Among same-type actions, higher priority wins