Skip to main content
Budget controls prevent runaway agent spend by enforcing cost ceilings at multiple levels of the organization. Every dispatch passes through two budget gates — the agent-level monthly budget and the envelope budget system — before reaching a gateway. When any budget is exhausted, execution is blocked immediately.

​
📊 Budget Hierarchy

Forge applies budgets at three scopes. A dispatch must satisfy all applicable budgets — the tightest constraint wins.

BUDGET ENVELOPE HIERARCHY

Global Budget. Organization-wide ceiling

Total spend across all agents and gateways. Ultimate cost ceiling.

contains↓
Gateway Budget

Per execution surface (OpenClaw, etc.)

Gateway Budget

Per execution surface (Vercel AI, etc.)

contains↓
Agent Budget

Per-agent ceiling

Agent Budget

Per-agent ceiling

Agent Budget

Per-agent ceiling

Tightest constraint wins. All applicable budgets must pass.

​
📅 Budget Periods

Each budget envelope has a period that determines its reset cycle:
PeriodReset ScheduleUse Case
dailyMidnight UTC, daily cronTight cost control for experimental or high-volume agents
weeklySunday midnight UTC, weekly cronStandard operational budgets with weekly review cycles
monthlyFirst of month, monthly cronStrategic budget allocation aligned with billing periods
Budget resets zero out the spentCents field and record a budget_period_reset audit event with the count of budgets reset.
An agent can have budget envelopes at multiple periods simultaneously. For example, a 10/daydailylimitanda10/day daily limit and a 200/month monthly limit. Both are checked on every dispatch, and the tightest constraint wins.

​
🛡️ Two Budget Gates

The governance pipeline checks budgets through two separate gates, each with different data sources:

​
Gate 5: Agent Budget

Checks the agent’s built-in monthly budget from the agent definition document. This is the legacy budget mechanism and remains the primary per-agent cost ceiling.
  • Source: agentDoc.budgetMonthlyCents and agentDoc.spentMonthlyCents
  • Resolution: Prefers role-derived resolvedBounds.maxSpendCents when a role is assigned, falling back to the agent’s own budgetMonthlyCents
  • Block Condition: spentMonthlyCents >= budgetMonthlyCents
  • Error Code: budget_exceeded
For delegated run dispatch, this gate also performs a headroom check: if the run’s maxCostCents guardrail exceeds the agent’s remaining budget, the dispatch is blocked with budget_insufficient even though the current spend has not yet exceeded the ceiling.

​
Gate 6: Envelope Budgets

Checks all applicable budget envelopes from the budgets table. Multiple envelopes may apply depending on scope:
  • Global budgets always apply
  • Gateway-scoped budgets apply when the dispatch targets that gateway
  • Agent-scoped budgets apply when the dispatch uses that agent
All matching, enabled envelopes are fetched and checked. If any single envelope is exhausted (spentCents >= amount), the gate blocks.

​
📋 Budget Envelope Schema

FieldTypeDescription
scopeglobal / gateway / agentBudget scope level
scopeIdstring (optional)Gateway ID or agent ID for scoped budgets
perioddaily / weekly / monthlyReset period
amountnumberBudget ceiling in cents
enabledbooleanWhether this budget is active
spentCentsnumber (optional)Current spend in this period
periodStarttimestamp (optional)When the current period started
lastResetAttimestamp (optional)Last period reset timestamp

​
📸 Budget Snapshot

Every GovernanceDecision includes a budgetSnapshot that captures the state of all applicable budgets at evaluation time: 
{
  budgetSnapshot: {
    // Agent-level monthly budget
    agentBudget: {
      spentCents: 4200,
      limitCents: 10000
    },
    // All applicable envelope budgets
    envelopes: [
      {
        scope: "global",
        period: "monthly",
        spentCents: 85000,
        limitCents: 100000
      },
      {
        scope: "agent",
        scopeId: "agent-123",
        period: "daily",
        spentCents: 450,
        limitCents: 500
      }
    ]
  }
}
This snapshot is persisted in the audit trail, providing point-in-time visibility into budget utilization at every governance decision.

​
💳 Token Spend Attribution

Forge tracks cost attribution through two parallel hierarchies, enabling both task-oriented and organizational budget analysis:

DUAL ATTRIBUTION CHAINS

TASK CHAIN

”How much did this project cost?”

TokenIndividual LLM call
↓
TaskWorkflow step
↓
WorkflowComplete run
↓
ProjectBusiness initiative
↓
ObjectiveStrategic goal
WORKER CHAIN

”How much is this team spending?”

TokenIndividual LLM call
↓
WorkerHuman or agent
↓
TeamOrganizational unit
↓
DepartmentBusiness division
↓
CompanyOrganization total
The task chain answers “how much did this project cost?” by rolling up token spend through workflow steps, runs, projects, and strategic objectives. The worker chain answers “how much is this team spending?” by rolling up token spend through individual workers (human or agent), teams, departments, and the company. Every token usage record carries both attribution paths, enabling budget analysis from either perspective.

​
💰 Post-Execution Cost Tracking

After every step completes (success or failure), a post-execution governance hook runs to:
  1. Accumulate cost — Add the step’s token usage cost to the agent’s spentMonthlyCents and applicable budget envelopes
  2. Check thresholds — Evaluate whether the updated spend triggers budget alerts
  3. Record audit event — Persist a PostExecutionDecision with cost data, budget state, and any triggered actions
The post-execution hook reports:
FieldDescription
costCentsTotal cost of the completed step
tokenUsageInput/output token counts and model used
budgetStateUpdated spend ratios for agent and all envelopes

​
⚙️ Budget Management

​
Creating Budgets

Budgets are created through the Platform API or any connected operator interface. Each budget requires a scope and optional scopeId, a period, an amount in cents, and an enabled flag. If a budget with the same scope, scopeId, and period already exists, the upsert operation updates the existing budget rather than creating a duplicate. Requires the cost:manage permission.

​
Period Resets

Budget periods are reset automatically by scheduled cron jobs:
PeriodCron ScheduleWhat Happens
DailyDaily at midnight UTCAll enabled daily budgets have spentCents zeroed
WeeklySunday midnight UTCAll enabled weekly budgets have spentCents zeroed
MonthlyFirst of month midnight UTCAll enabled monthly budgets have spentCents zeroed
Each reset records a budget_period_reset audit event with the number of budgets reset.

​
Enabling and Disabling

Budgets can be toggled on and off without deletion. Disabled budgets are excluded from governance evaluation — the envelope budget gate only fetches enabled budgets.
Disable a budget temporarily rather than deleting it to preserve the spend history and configuration. Re-enable it when you want enforcement to resume.

​
🔔 Budget Alerts and Auto-Pause

When the post-execution cost accumulation pushes an agent’s spend past a budget threshold, the system can:
  • Alert — Emit a notification at configurable threshold percentages (e.g., 80%, 90%)
  • Auto-pause — When a budget is fully exhausted, subsequent dispatch attempts are blocked by the budget gate with budget_exceeded
The auto-pause behavior is inherent in the budget gate — there is no separate pause mechanism. Once spentCents >= amount, the gate blocks all future dispatches for that scope and period until the budget resets or an operator increases the ceiling.
Budget gates are not retryable. When a budget is exhausted, the agent is effectively paused until the period resets or an operator adjusts the budget. Plan budget ceilings with headroom for expected workload variation.

​
🛡️ Delegated Run Budget Protection

Delegated runs (where an agent launches a sub-run) receive additional budget scrutiny. The agent budget gate performs a headroom check: If the delegated run specifies a maxCostCents guardrail, the gate verifies that the agent’s remaining monthly budget can cover the full run ceiling. This prevents launching runs that would inevitably exceed the budget mid-execution, which would cause partial work and wasted resources. 
Remaining budget: budgetMonthlyCents - spentMonthlyCents
If remaining < maxCostCents: BLOCK with budget_insufficient
This check runs in addition to the standard budget exhaustion check, providing proactive cost protection for delegated execution.
In Burgundy: Track budgets in Analytics.