Skip to main content
Forge’s policy engine lets operators define governance rules as declarative conditions rather than code. Policies are evaluated during the governance pipeline and can block dispatch, require human approval, log warnings, or silently audit. Policies compose with the safety gate pipeline: the gate sequence handles infrastructure and resource checks (health, budget, concurrency), while policies handle business logic and organizational rules (trust boundaries, deployment controls, guardrails).

​
🏗️ Policy Structure

Every policy consists of six core properties:
PropertyDescriptionExample
nameHuman-readable policy nameProduction trust boundary
categoryThe domain this policy governstrust_boundary
scopeWhere the policy appliesgateway
conditionExpression evaluated against dispatch contextagent.trustLevel < 3
actionWhat happens when the condition matchesblock
enforcementHow strictly the action is appliedhard

POLICY EVALUATION FLOW

Policy Rules

Fetch by category + scope. Global + scope-specific policies.

Condition Matching

Evaluate field operator value against PolicyContext (agent, gateway, run, role).

enforcement check↓
Hard

Strictly enforced. Blocks.

Soft

Advisory. Reported only.

Audit

Observation only. Logged.

action↓
Block

Hard stop. Step fails with policy_blocked.

disposition: block
Require Approval

Hold for HITL. Execution pauses pending review.

disposition: hold
Warn

Log warning event. Proceed with dispatch.

disposition: pass
Log

Silent audit record. No execution impact.

disposition: pass

Hard enforcement + Block action = immediate dispatch failure. Audit enforcement = logged without blocking.

​
📋 Policy Categories

Policies are organized into categories that determine when and how they are evaluated:
CategoryPurposeExample Use Case
trust_boundaryEnforce trust-level requirements between agents and gatewaysBlock low-trust agents from production gateways
budgetEnforce cost-related business rules beyond envelope limitsRequire approval when agent spend exceeds 80% of budget
run_creationControl when new workflow runs can be createdBlock run creation on specific gateways during maintenance
deploymentControl deployment lifecycle transitionsRequire approval for production deployments
guardrailGeneral safety guardrails for agent behaviorBlock specific agent tiers from certain operations
config_changeControl when configuration changes are allowedRequire approval for agent configuration changes
During dispatch governance, policies in the trust_boundary, budget, and run_creation categories are evaluated. During workflow launch preflight, only run_creation policies are evaluated.

​
🎯 Policy Scopes

Every policy is scoped to control where it applies:
ScopeMeaningscopeId
globalApplies to all dispatch contextsNot set
gatewayApplies only to a specific gatewayGateway registry ID
agentApplies only to a specific agentAgent ID
environmentApplies to all gateways in an environmentEnvironment name
When the governance pipeline evaluates policies, it fetches both global policies and scope-specific policies for the target gateway, then evaluates them in priority order (lower number = higher priority).

​
🔍 Condition Language

Policy conditions use a simple field operator value syntax that is validated at creation time and evaluated at runtime against a PolicyContext. The evaluator uses strict parsing with no dynamic code execution — it parses conditions into structured comparisons against a whitelisted set of fields.

​
Allowed Fields

Conditions can reference any of these dot-path fields:
FieldTypeDescription
agent.trustLevelnumberAgent’s numeric trust level
agent.tierstringAgent tier (e.g., free, pro)
agent.lifecycleStatusstringCurrent lifecycle status
agent.lifecycleStagestringCurrent lifecycle stage
agent.agentIdstringAgent identifier
agent.ownerstringAgent owner
Only fields in this whitelist can be referenced. Conditions referencing unknown fields are rejected at creation time. This prevents data leakage and ensures all policy evaluations are predictable.

​
Supported Operators

OperatorDescriptionExample
==Equalsagent.tier == 'free'
!=Not equalsgateway.environment != 'production'
>Greater thanagent.trustLevel > 2
>=Greater than or equalagent.trustLevel >= 3
<Less thangateway.minTrustLevel < 5
<=Less than or equalagent.trustLevel <= 1
inValue in listagent.tier in ['free', 'pro']

​
Value Syntax

  • Strings: Single-quoted ('production', 'active')
  • Numbers: Unquoted (3, 100)
  • Booleans: true or false
  • Null: null
  • Arrays: Bracket-delimited for in operator (['staging', 'production'])

​
Example Conditions

agent.trustLevel < 3
gateway.environment == 'production'
agent.tier in ['free', 'trial']
role.autonomyTier == 'advisory'
agent.lifecycleStage != 'active'
Policies do not support boolean composition (AND/OR). To express compound conditions, create separate policies. This keeps the evaluator simple and each policy independently auditable.

​
⚡ Enforcement Levels

Each policy has an enforcement level that determines how seriously a match is treated:
LevelBehaviorWhen to Use
hardStrictly enforced. Block actions produce immediate dispatch failure.Production safety rules that must never be bypassed
softAdvisory enforcement. Matched policies are reported but may not block depending on action.Rules being tested before promotion to hard enforcement
auditObservation only. Matched policies are logged for analysis.New policies in observation mode before activation
A policy with action: block and enforcement: hard produces a hard block in the governance pipeline. The same policy with enforcement: audit would log the match without blocking.

​
🔄 Policy Lifecycle

1

Create

Policies are created through the Platform API or any connected operator interface. The condition expression is parsed and validated at creation time — malformed conditions are rejected before the policy is stored. Requires the governance:manage permission.
2

Enable / Disable

Policies have an enabled flag. Disabled policies are never evaluated during governance checks. Toggle a policy off to temporarily suspend enforcement without deleting the rule.
3

Update

Any property of a policy can be updated. If the condition changes, the new expression is re-validated. All updates are recorded in the audit trail.
4

Delete

Policies can be permanently removed. Deletion is audited with the policy name and category.
Every policy lifecycle event (create, update, toggle, delete) is recorded in the auditEvents table with category governance.

​
✋ Approval Policies

In addition to dispatch policies, Forge supports dedicated approval policies that define when human approval is required for specific triggers:
TriggerDescription
deploymentNew deployment activations
run_creationNew workflow run launches
budget_changeBudget configuration changes
agent_config_changeAgent definition changes
policy_changePolicy rule changes
agent_position_creationNew agent position creation in org hierarchy
Approval policies can include an optional triggerCondition — the same condition language used by dispatch policies. When a trigger condition is present, the approval requirement only applies when the condition matches. Approval policies are scoped to global, gateway, or environment and support specifying an approverRole and requiredApprovals count for multi-party approval workflows.

​
🧩 How Policies Compose with Safety Gates

Policies are evaluated as Gate 9 and Gate 10 in the safety gate pipeline. The relationship is sequential, not parallel:
  1. Gates 1-8 handle infrastructure and resource checks (health, status, concurrency, rate limits, budgets, trust)
  2. Gate 9 (Policy Rules) evaluates declarative policies — if a block policy matches, the pipeline returns immediately
  3. Gate 10 (Approval Required) checks whether any require_approval policies or approval policies matched — if so, the pipeline returns a hold disposition
This means policies are only evaluated if the dispatch has already passed all infrastructure and resource checks. A blocked budget gate will prevent policy evaluation entirely, which is the correct behavior: there is no point evaluating business rules for a dispatch that has already been rejected for resource reasons.
To understand why a policy was not evaluated for a specific dispatch, check the GovernanceDecision.gates array in the audit trail. Skipped gates include a detail field explaining why they were skipped (e.g., blocked_by_previous_gate).
In Burgundy: Configure policies in Governance settings.