Per-turn budget

Cap what a single agent turn can spend, in real dollars — flags, the /budget slash command, and the three enforcement modes.

A per-turn budget puts a real USD ceiling on what one agent turn is allowed to spend before it stops, pauses, or asks. It is off by default — turns run unbounded unless you enable one.

The budget is the same governed mechanism across every surface: the CLI, the app's chat composer, and the budget.policy.* API/MCP capabilities all share one evaluator (packages/billing/src/turn-budget.ts), so a budget behaves identically no matter where it's set.

Enable it at launch

oxagen --budget 2.50 "refactor the date helpers into a single module"
oxagen --budget 1.00 --budget-mode enforce "run the fastest possible pass on this"

Flag	Description
`--budget <usd>`	Enable a per-turn dollar budget, e.g. `--budget 2.50`. Session-scoped — not persisted between runs.
`--budget-mode <mode>`	What happens at the limit: `grace` \| `prompt` \| `enforce` (default `prompt`). Ignored when `--budget` is not also given.

The CLI budget is session-scoped only — it lives in memory for the life of the process. There is no platform persistence or auth call for the CLI flag form; it applies to every turn run in that session.

The `/budget` slash command

Inside the interactive REPL, change or inspect the budget at any time without restarting:

/budget                  # show the current policy
/budget status            # same as above
/budget 2.50              # enable at $2.50, default mode (prompt)
/budget 2.50 enforce       # enable at $2.50, enforce mode
/budget mode grace         # change the mode only, limit unchanged
/budget off                # disable — turns run unbounded again

The three enforcement modes

Ordered soft → gated → hard. Choose the mode based on how much you trust the turn to self-correct versus how badly a runaway turn would hurt:

Mode	Behavior
`grace`	Soft cap. Keeps going past the limit up to a grace cushion (default 25% over), then stops automatically. Good for "don't let this wildly overrun" without interrupting a turn that's almost done.
`prompt`	Gated cap (default). Pauses at the limit and asks whether to continue. Approving grants another full budget window from that point, so a turn you keep approving can still finish.
`enforce`	Hard cap. Halts the turn the instant the limit is crossed and fails with a budget-exceeded reason. Use this when you want a strict, no-exceptions ceiling — e.g. in CI or an unattended one-shot run.

How it's evaluated

After each step in the agent's tool loop, the cumulative token usage for the turn is converted to a dollar cost (turnCostUsd, using the resolved model's rate card) and compared against the policy. The guard runs on the SAME runCodingAgent loop the CLI, the app's chat route, and any future runner all share, so cost is measured identically everywhere a turn runs.

Where else a budget can be set

App composer — a Budget control next to the model picker lets a user set their own per-turn budget in the chat UI, using the same three modes.
Workspace governance — an Owner/Admin can set an org- or workspace-level budget via the workspace.budget_policy.read/write capabilities that seed a soft default for members (they may raise or lower it) or clamp a hard ceiling (they cannot exceed it, and the enforcement mode can only get stricter, never laxer). See docs/capabilities/budget.policy.read.md and docs/capabilities/workspace.budget_policy.read.md in the capability reference set for the full API/MCP shape.