Policies & Rules

8 policy presets, 13 condition types, boolean combinators, and priority ordering.

Policies are the core of governance-sdk. Every enforce() call evaluates your policies against the proposed action and returns allow or block.

Policy Presets

8 built-in presets cover 90% of governance needs. Import them directly from the main package:

import {
  blockTools,       // Block specific tools by name
  allowOnlyTools,   // Allowlist-only — everything else blocked
  requireApproval,  // Flag for human review before execution
  tokenBudget,      // Per-session token limit
  rateLimit,        // Declarative threshold check
  requireLevel,     // Minimum governance level (L0–L4)
  requireSequence,  // Tool prerequisites (e.g., backup → delete)
  timeWindow,       // Restrict to business hours
} from 'governance-sdk';

Preset Reference

blockTools

Block specific tools from being called. The most common policy.

blockTools(['shell_exec', 'db_drop', 'fs_write', 'bulk_export'])

allowOnlyTools

Inverse of blockTools — only listed tools are permitted. Everything else is blocked.

allowOnlyTools(['email_draft', 'search', 'crm_read'])

requireApproval

Flag specific action types for human review. Returns a "requires_approval" outcome instead of blocking.

requireApproval(['payment', 'database_mutation', 'external_request'])

tokenBudget

Limit token usage per session. Blocks actions when budget is exceeded.

tokenBudget(50_000) // 50K tokens per session

rateLimit

Declarative threshold check. The SDK checks a caller-supplied count against the threshold — it does not track counts itself.

rateLimit(100, 60_000) // 100 actions per 60s window

Warning: This is a declarative check, not server-side rate limiting. For production rate limiting, use the governance API with Upstash/Redis.

requireLevel

Require agents to reach a minimum governance score level before acting.

requireLevel(2) // L2 (Basic) or higher required

requireSequence

Require prerequisite tools to run before a target tool. Useful for CI/CD-style pipelines.

requireSequence('deploy', ['test', 'lint', 'build'])
// deploy blocked until test → lint → build all complete

timeWindow

Restrict actions to specific time windows. Block deployments outside business hours.

timeWindow(9, 17, 'Restricted to business hours')

Boolean Combinators

Compose complex policies by combining conditions with any_of (OR), all_of (AND), and not (NEGATE). Nest infinitely.

// Block unless agent has BOTH auth AND guardrails
const rule = {
  id: 'require-security',
  condition: {
    type: 'all_of',
    params: {
      conditions: [
        { type: 'agent_level', params: { minLevel: 1 } },
        { type: 'tool_blocked', params: { tools: [] } },
      ],
    },
  },
  outcome: 'block',
  reason: 'Agent must have auth and guardrails enabled',
};

// Block shell_exec UNLESS agent is L3+ AND in business hours
const complexRule = {
  id: 'conditional-shell',
  condition: {
    type: 'all_of',
    params: {
      conditions: [
        { type: 'tool_blocked', params: { tools: ['shell_exec'] } },
        {
          type: 'not',
          params: {
            condition: {
              type: 'all_of',
              params: {
                conditions: [
                  { type: 'agent_level', params: { minLevel: 3 } },
                  { type: 'time_window', params: { allowedHours: { start: 9, end: 17 } } },
                ],
              },
            },
          },
        },
      ],
    },
  },
  outcome: 'block',
};

Priority Ordering

Rules are evaluated in priority order — higher numbers win. The kill switch uses priority 999 and overrides everything.

Priority	Rule	Note
999	Kill switch	Overrides all rules
100	`blockTools(['shell_exec'])`	Highest preset
95	`requireLevel(2)`	High priority
80	`requireApproval(['payment'])`	Medium priority

Policy Composition

Merge policy sets from different teams with conflict resolution. Import from governance-sdk/policy-compose.

import { composePolicies } from 'governance-sdk/policy-compose';

const merged = composePolicies([
  securityTeamRules,  // blockTools, requireApproval
  platformTeamRules,  // requireSequence, requireLevel
  complianceRules,    // timeWindow, auditRequirements
], {
  conflictStrategy: 'strict', // or 'permissive' | 'priority' | 'latest'
});

const gov = createGovernance({ rules: merged });

Note: When teams disagree, strict picks the stricter rule. Use priority to let higher-priority rules win regardless.