agent-governance-policy.yaml

export enum AgentPhase {
  EXPLORE = 'EXPLORE',
  DECIDE = 'DECIDE',
  COMMIT = 'COMMIT'
}

export interface PhaseGuard {
  currentPhase: AgentPhase;
  canExecutePayment(): boolean;
  transitionTo(phase: AgentPhase): void;
}

export class StrictPhaseGuard implements PhaseGuard {
  currentPhase: AgentPhase = AgentPhase.EXPLORE;

  canExecutePayment(): boolean {
    if (this.currentPhase !== AgentPhase.COMMIT) {
      throw new PhaseError(
        `Payment blocked: Agent is in ${this.currentPhase} phase. ` +
        `Must transition to COMMIT before executing financial tools.`
      );
    }
    return true;
  }

  transitionTo(phase: AgentPhase): void {
    // Enforce valid state transitions
    const validTransitions: Record<AgentPhase, AgentPhase[]> = {
      [AgentPhase.EXPLORE]: [AgentPhase.DECIDE],
      [AgentPhase.DECIDE]: [AgentPhase.COMMIT],
      [AgentPhase.COMMIT]: []
    };

    if (!validTransitions[this.currentPhase].includes(phase)) {
      throw new Error(`Invalid phase transition from ${this.currentPhase} to ${phase}`);
    }
    this.currentPhase = phase;
  }
}

export interface CompensatingAction {
  execute(): Promise<v

oid>; }

export class AgentTransactionScope { private actions: Array<{ execute: () => Promise<any>; compensate: CompensatingAction; }> = [];

async executeStep<T>( action: () => Promise<T>, compensation: CompensatingAction ): Promise<T> { this.actions.push({ execute: action, compensate }); try { return await action(); } catch (error) { await this.rollback(); throw error; } }

private async rollback(): Promise<void> { // Execute compensation in reverse order for (let i = this.actions.length - 1; i >= 0; i--) { try { await this.actions[i].compensate.execute(); } catch (compError) { console.error(Compensation failed for step ${i}:, compError); } } }

commit(): void { this.actions = []; } }

#### 3. Graduated Budget Gates
Budget policies must be behavioral, not binary. Gates should trigger different responses based on spend velocity and thresholds. High-value single calls require explicit approval regardless of remaining budget.

```typescript
export interface BudgetPolicy {
  sessionLimit: number;
  singleCallThreshold: number;
  graduatedThresholds: {
    warning: number; // e.g., 0.50 for 50%
    restrict: number; // e.g., 0.75 for 75%
    halt: number;     // e.g., 0.90 for 90%
  };
}

export class DynamicBudgetPolicy {
  private spent: number = 0;

  constructor(private policy: BudgetPolicy) {}

  evaluate(cost: number, requiresApproval: boolean = false): BudgetDecision {
    if (this.spent + cost > this.policy.sessionLimit) {
      return { status: 'DENIED', reason: 'Session limit exceeded' };
    }

    if (cost > this.policy.singleCallThreshold) {
      if (!requiresApproval) {
        return { status: 'PENDING_APPROVAL', reason: `Cost ${cost} exceeds threshold ${this.policy.singleCallThreshold}` };
      }
    }

    const spendRatio = (this.spent + cost) / this.policy.sessionLimit;
    
    if (spendRatio > this.policy.graduatedThresholds.halt) {
      return { status: 'DENIED', reason: 'Halt threshold reached' };
    }
    
    if (spendRatio > this.policy.graduatedThresholds.restrict) {
      return { status: 'ALLOWED_WITH_RESTRICTION', reason: 'Restrict scope due to high spend ratio' };
    }

    return { status: 'ALLOWED' };
  }

  recordSpend(amount: number): void {
    this.spent += amount;
  }
}

4. Proof Traces

Every payment decision must generate a structured audit record. This trace captures the decision, the evaluated rules, the agent phase, budget status, and approval context. This distinguishes between a system bug and a policy violation.

export interface ProofTrace {
  decision: 'ALLOWED' | 'DENIED' | 'PENDING_APPROVAL';
  tool: string;
  timestamp: string;
  context: {
    phase: AgentPhase;
    budgetSpent: number;
    cost: number;
    rulesEvaluated: string[];
    approvalGranted?: boolean;
  };
  reason: string;
}

export class DecisionAuditTrail {
  private traces: ProofTrace[] = [];

  log(trace: ProofTrace): void {
    this.traces.push(trace);
    // In production, emit to structured logging system
    console.log(JSON.stringify({ event: 'PAYMENT_DECISION', ...trace }));
  }

  getTraceForTransaction(txId: string): ProofTrace | undefined {
    return this.traces.find(t => t.tool === txId);
  }
}

Architecture Rationale:

• Interceptor Pattern: Governance is applied via wrappers around payment tools. This ensures policy enforcement is unavoidable and decoupled from agent reasoning logic.
• TypeScript Interfaces: Strong typing for policies and traces ensures compile-time safety and clear contracts between the agent framework and the governance layer.
• External Policy Engine: By keeping rules external to the agent code, non-technical stakeholders can review and update policies without modifying application logic.

Pitfall Guide

Pitfall Name	Explanation	Fix
The Ceiling Fallacy	Treating a spending limit as a complete policy. A limit only stops execution at the end; it does not prevent wasteful spending during exploration.	Implement phase enforcement. Block payment tools until the agent commits to a plan.
Compensation Blindness	Assuming payments are atomic with workflow steps. If an agent pays for data and the analysis fails, the cost is lost without a compensation handler.	Design compensating actions for every payment step. Use a transaction scope that triggers compensation on downstream failure.
Threshold Flatness	Using a single budget limit for all transactions. This fails to catch high-risk single calls that are within the total budget but exceed acceptable per-call risk.	Implement graduated budget gates with per-call approval thresholds. Require explicit authorization for calls above a defined cost.
Log vs. Trace Confusion	Relying on transaction logs for auditing. Logs show what happened, but not why a decision was made or which rules were evaluated.	Generate proof traces for every decision. Include context like phase, budget ratio, and rule evaluation results.
Framework Dependency	Assuming orchestration frameworks (LangGraph, CrewAI, etc.) provide financial governance out of the box. Most frameworks focus on execution, not policy.	Implement governance as an external layer. Do not rely on framework primitives for financial safety.
Static Auth Trap	Granting wallet access once and assuming it covers all future actions. Initial authorization does not account for runtime context changes.	Re-evaluate policy at every tool call. Use runtime checks for phase, budget, and approval requirements.
Temporal Neglect	Allowing agents to spend at any time, including off-hours or during maintenance windows.	Add temporal rules to the policy engine. Restrict spending to defined business hours or approved windows.

Production Bundle

Action Checklist

• Define Phase Model: Map agent states to EXPLORE, DECIDE, and COMMIT. Ensure payment tools are gated behind COMMIT.
• Map Compensation Paths: For every payment tool, define a compensating action (refund, credit, or loss record) for workflow failures.
• Configure Graduated Gates: Set session limits, single-call thresholds, and behavioral triggers at 50%, 75%, and 90% spend ratios.
• Implement Proof Traces: Ensure every payment decision generates a structured trace with context, rules, and approval status.
• Test Failure Modes: Simulate downstream failures after payments to verify compensation triggers correctly.
• Review Rule DSL: Validate that policy rules are readable by stakeholders and accurately reflect business intent.
• Monitor Spend Drift: Track actual spend patterns against policy expectations to identify gaps in governance rules.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal Research Agent	Phase Enforcement + Flat Limit	Low risk; prevents exploration waste; simple implementation.	Low
Customer-Facing Service	Full Governance + Approval Gates	High risk; requires strict control, auditability, and approval workflows.	Medium
Multi-Agent Swarm	Centralized Policy Engine	Consistency across agents; shared budget management; unified audit.	High
High-Frequency Micropayments	Batched Transactions + Phase Guard	Reduces overhead; ensures grouping of related payments under policy.	Low

Configuration Template

# agent-governance-policy.yaml
phases:
  allowed_payment_phase: COMMIT
  transition_rules:
    EXPLORE: [DECIDE]
    DECIDE: [COMMIT]
    COMMIT: []

budget:
  session_limit: 10.00
  single_call_threshold: 0.50
  graduated_gates:
    warning: 0.50
    restrict: 0.75
    halt: 0.90

rules:
  - id: block_explore_payments
    condition: "phase != COMMIT"
    action: DENY
    message: "Payment tools require COMMIT phase"
    
  - id: require_approval_high_cost
    condition: "cost > 0.50"
    action: PENDING_APPROVAL
    message: "Cost exceeds threshold; approval required"
    
  - id: halt_budget_exhaustion
    condition: "budget_ratio > 0.90"
    action: DENY
    message: "Halt threshold reached"

compensation:
  enabled: true
  default_action: REFUND_REQUEST
  timeout: 30s

Quick Start Guide

1. Initialize Policy Engine: Load the governance configuration and instantiate the PhaseGuard, DynamicBudgetPolicy, and DecisionAuditTrail.
2. Wrap Payment Tools: Create interceptor wrappers for all payment-capable tools. Inject the policy engine to evaluate requests before execution.
3. Implement Transaction Scope: Refactor multi-step workflows to use AgentTransactionScope. Register compensating actions for each payment step.
4. Deploy and Monitor: Run the agent in a sandbox environment. Verify proof traces are generated for all decisions. Test phase violations and compensation triggers before production deployment.