Cumulative USD budget tracker with threshold callbacks.

A budget process accumulates cost across turns and fires caller-supplied callbacks when configurable thresholds are first crossed. When a :max_usd ceiling is set, check/1 returns {:error, %ClaudeWrapper.Error{kind: :budget_exceeded}} once the running total is at or above the ceiling, giving callers a hard stop before the next CLI invocation.

This is the Elixir port of the Rust crate's BudgetTracker / BudgetBuilder. The Rust type is an Arc<Mutex<...>> handle shared across clones; the idiomatic Elixir equivalent is a GenServer whose pid (or registered name) is the shared handle. It mirrors the process-based style of ClaudeWrapper.SessionServer and ClaudeWrapper.DuplexSession.

It is self-contained: ClaudeWrapper.Session and ClaudeWrapper.SessionServer are not aware of it. Drive it yourself from a multi-turn loop -- record each turn's total_cost_usd, then check/1 before the next turn.

Threshold semantics

• :warn_at_usd -- :on_warning fires the first time the running total is at or above this value, and never again until reset/1.
• :max_usd -- :on_exceeded fires the first time the running total is at or above this value, and check/1 returns {:error, %ClaudeWrapper.Error{kind: :budget_exceeded}} from then on.

Both thresholds are "at or above" (>=), so a record that lands the total exactly on the threshold crosses it. Non-positive and non-finite costs are ignored. reset/1 clears the total and re-arms both callbacks so they can fire again.

Usage

{:ok, budget} =
  ClaudeWrapper.Budget.start_link(
    max_usd: 5.00,
    warn_at_usd: 4.00,
    on_warning: fn total -> IO.puts("warning: $#{total} spent") end,
    on_exceeded: fn total -> IO.puts("budget hit: $#{total}") end
  )

# In a multi-turn loop, after each turn:
:ok = ClaudeWrapper.Budget.record(budget, result.total_cost_usd)

case ClaudeWrapper.Budget.check(budget) do
  :ok -> :keep_going
  {:error, %ClaudeWrapper.Error{kind: :budget_exceeded, reason: %{total_usd: total, max_usd: max}}} -> {:halt, total, max}
end

ClaudeWrapper.Budget.total(budget)
#=> 4.32