feat(sdk): expose custom conditions on createGovernance (0.17.0)

Add conditions?: RegisteredConditionType[] to GovernanceConfig and
mirror the engine's condition-registry surface
(registerCondition / unregisterCondition / getRegisteredCondition /
getRegisteredConditions / clearConditionRegistry) on
GovernanceInstance, so callers using the documented createGovernance
flow no longer have to drop down to createPolicyEngine to register
custom evaluators. Widen GovernanceConfig.defaultOutcome to the full
PolicyOutcome union to match PolicyEngineConfig.defaultOutcome.
Update the README's Quick Start with a Custom Conditions section.

Author: scotty595

README.md

@@ -189,6 +189,57 @@ if (decision.outcome === 'require_approval') {
 }
 ```
 
+### Custom Conditions
+
+When the built-in condition types aren't enough, register your own evaluators directly on the governance instance — no need to drop down to `createPolicyEngine` for this. Pass them at construction or register them at runtime:
+
+```typescript
+import { createGovernance } from 'governance-sdk';
+
+// Option A — register at construction time
+const gov = createGovernance({
+  conditions: [
+    {
+      name: 'geo_fence',
+      description: 'Block actions outside allowed regions',
+      evaluator: (ctx, params) => {
+        const region = (ctx.metadata?.region as string | undefined) ?? '';
+        const allowed = params.allowedRegions as string[];
+        return region.length > 0 && !allowed.includes(region);
+      },
+    },
+  ],
+  rules: [{
+    id: 'geo-rule',
+    name: 'Geo fence',
+    condition: { type: 'geo_fence', params: { allowedRegions: ['us', 'eu'] } },
+    outcome: 'block',
+    reason: 'Region not allowed',
+    priority: 100,
+    enabled: true,
+  }],
+});
+
+// Option B — register after construction
+gov.registerCondition({
+  name: 'high_cost',
+  description: 'Block when session cost exceeds threshold',
+  evaluator: (ctx, params) => (ctx.sessionCost ?? 0) > (params.maxCost as number),
+});
+
+gov.addRule({
+  id: 'cost-check',
+  name: 'Cost check',
+  condition: { type: 'high_cost', params: { maxCost: 10 } },
+  outcome: 'block',
+  reason: 'Session cost over budget',
+  priority: 100,
+  enabled: true,
+});
+```
+
+Mirror methods are available on the instance: `registerCondition`, `unregisterCondition`, `getRegisteredCondition`, `getRegisteredConditions`, `clearConditionRegistry`. Custom evaluators must be **synchronous** — the policy engine is sync by design.
+
 ### CLI
 
 ```bash

packages/governance/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [0.17.0] - 2026-05-07 — Custom conditions reachable from `createGovernance()`
+
+The condition registry (`registerCondition` / `unregisterCondition` /
+`getRegisteredCondition` / `getRegisteredConditions` /
+`clearConditionRegistry`) and `PolicyEngineConfig.conditions` were already
+on `PolicyEngine` since 0.15, but `GovernanceInstance` (the thing
+`createGovernance()` returns) didn't expose them — `instance.policies` is
+a `ReadonlyPolicyEngine` view that intentionally hides mutators. So
+callers who followed the documented `createGovernance()` flow had no path
+to register a custom condition without dropping down to
+`createPolicyEngine()` and re-wiring everything else themselves.
+
+This release closes that gap. Additive only — no breaking changes.
+
+### Added — `GovernanceConfig.conditions`
+
+```ts
+const gov = createGovernance({
+  conditions: [{
+    name: "geo_fence",
+    description: "Block actions outside allowed regions",
+    evaluator: (ctx, params) => /* ... */ false,
+  }],
+  rules: [/* ... */],
+});
+```
+
+Forwarded into the underlying `createPolicyEngine` call.
+
+### Added — registry passthroughs on `GovernanceInstance`
+
+Mirroring the existing `addRule` / `removeRule` pattern:
+
+- `gov.registerCondition(entry, opts?)`
+- `gov.unregisterCondition(name)`
+- `gov.getRegisteredCondition(name)`
+- `gov.getRegisteredConditions()`
+- `gov.clearConditionRegistry(opts?)`
+
+All thin forwarders to the engine.
+
+### Changed — `GovernanceConfig.defaultOutcome` accepts the full `PolicyOutcome` union
+
+Was `"allow" | "block"`; now matches `PolicyEngineConfig.defaultOutcome`
+(`"allow" | "block" | "warn" | "require_approval" | "mask"`). Existing
+callers passing `"allow"` or `"block"` are unaffected.
+
+### Docs
+
+README's "Quick Start" section gained a **Custom Conditions** subsection
+demonstrating both construction-time (`config.conditions`) and runtime
+(`gov.registerCondition()`) registration via `createGovernance()`. The
+previous custom-condition example used the lower-level `createPolicyEngine`
+which left users on the documented `createGovernance` path stuck.
+
 ## [0.16.0] - 2026-04-30 — Per-policy multi-modal scan dispatch
 
 0.15 introduced `governance-sdk/scan/multi-modal` as a host-callable

packages/governance/README.md

@@ -189,6 +189,57 @@ if (decision.outcome === 'require_approval') {
 }
 ```
 
+### Custom Conditions
+
+When the built-in condition types aren't enough, register your own evaluators directly on the governance instance — no need to drop down to `createPolicyEngine` for this. Pass them at construction or register them at runtime:
+
+```typescript
+import { createGovernance } from 'governance-sdk';
+
+// Option A — register at construction time
+const gov = createGovernance({
+  conditions: [
+    {
+      name: 'geo_fence',
+      description: 'Block actions outside allowed regions',
+      evaluator: (ctx, params) => {
+        const region = (ctx.metadata?.region as string | undefined) ?? '';
+        const allowed = params.allowedRegions as string[];
+        return region.length > 0 && !allowed.includes(region);
+      },
+    },
+  ],
+  rules: [{
+    id: 'geo-rule',
+    name: 'Geo fence',
+    condition: { type: 'geo_fence', params: { allowedRegions: ['us', 'eu'] } },
+    outcome: 'block',
+    reason: 'Region not allowed',
+    priority: 100,
+    enabled: true,
+  }],
+});
+
+// Option B — register after construction
+gov.registerCondition({
+  name: 'high_cost',
+  description: 'Block when session cost exceeds threshold',
+  evaluator: (ctx, params) => (ctx.sessionCost ?? 0) > (params.maxCost as number),
+});
+
+gov.addRule({
+  id: 'cost-check',
+  name: 'Cost check',
+  condition: { type: 'high_cost', params: { maxCost: 10 } },
+  outcome: 'block',
+  reason: 'Session cost over budget',
+  priority: 100,
+  enabled: true,
+});
+```
+
+Mirror methods are available on the instance: `registerCondition`, `unregisterCondition`, `getRegisteredCondition`, `getRegisteredConditions`, `clearConditionRegistry`. Custom evaluators must be **synchronous** — the policy engine is sync by design.
+
 ### CLI
 
 ```bash

packages/governance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "governance-sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "AI Agent Governance for TypeScript — policy enforcement, scoring, compliance, and audit for AI agents",
   "type": "module",
   "main": "./dist/index.js",

packages/governance/src/index.test.ts

@@ -175,6 +175,101 @@ describe("createGovernance", () => {
   });
 });
 
+describe("createGovernance — custom conditions", () => {
+  test("registerCondition + addRule lets enforce() match a custom condition", async () => {
+    const gov = createGovernance();
+    gov.registerCondition({
+      name: "geo_fence",
+      description: "Block actions outside allowed regions",
+      evaluator: (ctx, params) => {
+        const region = (ctx.metadata?.region as string | undefined) ?? "";
+        const allowed = params.allowedRegions as string[];
+        return region.length > 0 && !allowed.includes(region);
+      },
+    });
+
+    gov.addRule({
+      id: "geo-rule",
+      name: "Geo fence",
+      condition: { type: "geo_fence", params: { allowedRegions: ["us", "eu"] } },
+      outcome: "block",
+      reason: "Region not allowed",
+      priority: 100,
+      enabled: true,
+    });
+
+    const blocked = await gov.enforce({
+      agentId: "a1",
+      action: "tool_call",
+      tool: "any",
+      metadata: { region: "cn" },
+    });
+    assert.equal(blocked.blocked, true, "non-allowed region should be blocked");
+    assert.equal(blocked.ruleId, "geo-rule");
+
+    const allowed = await gov.enforce({
+      agentId: "a1",
+      action: "tool_call",
+      tool: "any",
+      metadata: { region: "us" },
+    });
+    assert.equal(allowed.blocked, false, "allowed region should pass");
+  });
+
+  test("config.conditions registers conditions at construction time", async () => {
+    const gov = createGovernance({
+      conditions: [
+        {
+          name: "high_cost",
+          description: "Block when session cost exceeds threshold",
+          evaluator: (ctx, params) => (ctx.sessionCost ?? 0) > (params.maxCost as number),
+        },
+      ],
+      rules: [
+        {
+          id: "cost-check",
+          name: "Cost check",
+          condition: { type: "high_cost", params: { maxCost: 10 } },
+          outcome: "block",
+          reason: "Session cost over budget",
+          priority: 100,
+          enabled: true,
+        },
+      ],
+    });
+
+    assert.ok(gov.getRegisteredCondition("high_cost"), "config.conditions should be registered");
+
+    const blocked = await gov.enforce({
+      agentId: "a1",
+      action: "tool_call",
+      sessionCost: 15,
+    });
+    assert.equal(blocked.blocked, true);
+    assert.equal(blocked.ruleId, "cost-check");
+
+    const allowed = await gov.enforce({
+      agentId: "a1",
+      action: "tool_call",
+      sessionCost: 5,
+    });
+    assert.equal(allowed.blocked, false);
+  });
+
+  test("unregisterCondition + clearConditionRegistry forward to engine", () => {
+    const gov = createGovernance();
+    gov.registerCondition({ name: "tmp", description: "tmp", evaluator: () => false });
+    assert.ok(gov.getRegisteredCondition("tmp"));
+    assert.equal(gov.unregisterCondition("tmp"), true);
+    assert.equal(gov.getRegisteredCondition("tmp"), undefined);
+
+    gov.registerCondition({ name: "x", description: "x", evaluator: () => false });
+    gov.clearConditionRegistry({ keepBuiltins: true });
+    assert.equal(gov.getRegisteredCondition("x"), undefined);
+    assert.ok(gov.getRegisteredCondition("tool_blocked"), "builtins kept");
+  });
+});
+
 describe("createPolicyEngine", () => {
   test("evaluates rules in priority order", () => {
     const engine = createPolicyEngine({

packages/governance/src/index.ts

@@ -37,7 +37,15 @@ import {
   type IntegrityAuditEvent,
 } from "./audit-integrity.js";
 import type { AgentRegistration, GovernanceAssessment, FleetSummary } from "./types.js";
-import type { PolicyRule, PolicyEngine, PolicyStage, EnforcementContext, EnforcementDecision } from "./policy.js";
+import type {
+  PolicyRule,
+  PolicyEngine,
+  PolicyOutcome,
+  PolicyStage,
+  EnforcementContext,
+  EnforcementDecision,
+  RegisteredConditionType,
+} from "./policy.js";
 import type { GovernanceStorage, StoredAgent, AuditEvent, AuditQueryFilters } from "./storage.js";
 
 /**
@@ -76,7 +84,20 @@ export { createMemoryStorage } from "./storage.js";
 export interface GovernanceConfig {
   storage?: GovernanceStorage;
   rules?: PolicyRule[];
-  defaultOutcome?: "allow" | "block";
+  /**
+   * Default outcome when no rules match. Accepts the full `PolicyOutcome`
+   * union to mirror `PolicyEngineConfig.defaultOutcome` — the common case
+   * is `"allow"` or `"block"`, but `"warn"` / `"require_approval"` /
+   * `"mask"` are valid too.
+   */
+  defaultOutcome?: PolicyOutcome;
+  /**
+   * Custom condition types to register on the underlying policy engine.
+   * Mirrors `PolicyEngineConfig.conditions` so callers using
+   * `createGovernance()` don't have to drop down to `createPolicyEngine()`
+   * just to register a custom evaluator.
+   */
+  conditions?: RegisteredConditionType[];
   /** When set, enforce() and register() POST to this URL instead of running locally */
   serverUrl?: string;
   /** Bearer token for remote calls — required when serverUrl is set */
@@ -189,6 +210,16 @@ export interface GovernanceInstance {
   addRule: (rule: PolicyRule) => void;
   /** Remove a policy rule by ID */
   removeRule: (ruleId: string) => void;
+  /** Register a custom condition type on the underlying policy engine */
+  registerCondition: (entry: RegisteredConditionType, opts?: { override?: boolean }) => void;
+  /** Unregister a condition type by name */
+  unregisterCondition: (name: string) => boolean;
+  /** Get a registered condition type by name */
+  getRegisteredCondition: (name: string) => RegisteredConditionType | undefined;
+  /** List all registered condition types (custom + built-ins) */
+  getRegisteredConditions: () => RegisteredConditionType[];
+  /** Clear all registered conditions. Set `keepBuiltins: true` to re-register built-ins. */
+  clearConditionRegistry: (opts?: { keepBuiltins?: boolean }) => void;
   /** Test API connectivity. Returns status without throwing. */
   connect: () => Promise<{ connected: boolean; mode: string; latencyMs: number }>;
   /** Current connection status (cached from last enforce/connect call). */
@@ -233,6 +264,7 @@ export function createGovernance(config: GovernanceConfig = {}): GovernanceInsta
   const policies = createPolicyEngine({
     rules: config.rules,
     defaultOutcome: config.defaultOutcome,
+    conditions: config.conditions,
   });
 
   // ── Integrity audit chain (opt-in) ───────────────────────────
@@ -600,6 +632,26 @@ export function createGovernance(config: GovernanceConfig = {}): GovernanceInsta
     policies.removeRule(ruleId);
   }
 
+  function registerCondition(entry: RegisteredConditionType, opts?: { override?: boolean }): void {
+    policies.registerCondition(entry, opts);
+  }
+
+  function unregisterCondition(name: string): boolean {
+    return policies.unregisterCondition(name);
+  }
+
+  function getRegisteredCondition(name: string): RegisteredConditionType | undefined {
+    return policies.getRegisteredCondition(name);
+  }
+
+  function getRegisteredConditions(): RegisteredConditionType[] {
+    return policies.getRegisteredConditions();
+  }
+
+  function clearConditionRegistry(opts?: { keepBuiltins?: boolean }): void {
+    policies.clearConditionRegistry(opts);
+  }
+
   const noopStatus = () => ({ connected: true, mode: "local" as const, latencyMs: 0 });
 
   const integrityChain = integrity
@@ -660,6 +712,11 @@ export function createGovernance(config: GovernanceConfig = {}): GovernanceInsta
     recordOutcome,
     score: scoreAgentFn, scoreFleet: scoreFleetFn,
     policies: readonlyPolicies, storage, addRule, removeRule,
+    registerCondition,
+    unregisterCondition,
+    getRegisteredCondition,
+    getRegisteredConditions,
+    clearConditionRegistry,
     connect: remote ? remote.connect : async () => noopStatus(),
     status: remote ? remote.status : noopStatus,
     waitForApproval: remote