Policies & Rules

9 core presets + 12 extended presets + ML classifier hook. Condition types, boolean combinators, priority clamp.

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

Policy Presets

9 core presets cover most 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 (host populates ctx.recentActionCount)
  requireLevel,           // Minimum governance level (L0–L4)
  requireSequence,        // Tool prerequisites (e.g., test → lint → deploy)
  requireSignedIdentity,  // Require Ed25519-signed identity token
  timeWindow,             // Restrict to business hours
} from 'governance-sdk';

12 extended presets are also re-exported from the main package for input/output scanning, PII handling, and resource ceilings:

import {
  inputBlocklist, inputLength, inputPattern,
  networkAllowlist, scopeBoundary,
  costBudget, concurrentLimit,
  outputLength, outputPattern,
  sensitiveDataFilter, maskSensitiveOutput, maskOutputPattern,
} from 'governance-sdk';

mlInjectionGuard bridges the synchronous policy engine with an async ML classifier. Your host runs the classifier before enforce() and populates ctx.mlInjectionScore; the preset reads that pre-computed score and blocks when it crosses the threshold.

import { mlInjectionGuard } from 'governance-sdk';

const gov = createGovernance({
  rules: [mlInjectionGuard({ threshold: 0.7, requireCategory: 'jailbreak' })],
});

// In your host wrapper:
const mlResult = await myClassifier.classify(userPrompt);
await gov.enforce({
  agentId,
  action: 'tool_call',
  input: { prompt: userPrompt },
  mlInjectionScore: mlResult.score,
  mlInjectionCategories: mlResult.categories,
});

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. User priorities are clamped at 998 so the kill switch (priority 999, reserved __ id prefix) remains the unconditional top rule. If you pass a user rule with priority: 1000, the engine silently rewrites it to 998 at registration time so no one can beat the kill switch.

Priority	Rule	Note
999	Kill switch (id prefix `__kill_switch__`)	Reserved — only internal `__`-prefixed rules may use this
998	Maximum user priority	Anything higher passed by a user rule is clamped to this
130	`mlInjectionGuard({ threshold: 0.7 })`	Preprocess stage
100	`blockTools(['shell_exec'])`	Tool allowlist/blocklist tier
95	`requireLevel(2)`	Agent-level gate
80	`requireApproval(['payment'])`	Approval-queue gate

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.