A provider-enforced spending limit for a fresh Claude Managed Agents session.
Pass it as the :budget option to ReqManagedAgents.run_to_completion/1,
ReqManagedAgents.start_session/1 or ReqManagedAgents.Session.run/2; a map with the same
atom keys is accepted interchangeably. The cap is max_list_cost_cents, a positive whole
number of US cents priced at public list rates, not at your contracted rates.
The provider checks the running cost between model requests and pauses the session once it reaches the cap. The request in flight at that moment still finishes, so the final cost can overshoot the cap by up to one model request per thread. Size the cap with that margin in mind.
A session that reaches its cap is not an error: the run returns {:ok, result} where
result is a ReqManagedAgents.SessionResult with terminal: :terminated and
stop_reason: %{"type" => "budget_reached"} (the provider's session.status_idle stop
reason, which the provider maps to :terminated).
The provider leaves the session idle, and RMA does not archive it; raising or removing the
budget through the provider API resumes it.
Only the Claude Managed Agents provider can enforce a budget; Session.run/2 and
Session.start_link/2 return {:error, :budget_unsupported} for any other provider.
Client retries apply to the create-session request, so one open can create more than one
budgeted session if a response is lost after the provider committed it. For one create per
open, pass a :client built with ReqManagedAgents.Providers.ClaudeManagedAgents.Client.new(req_options: [retry: false]).
A budget can only be set when the session is created. Passing :budget together with
:session_id is an error. When a budget is requested, the session is opened only if the
provider's create response echoes the same budget; otherwise the session is archived on a
best-effort basis (one attempt, no retries, a 5 s total deadline, shorter if the client's
receive timeout is) and the open fails with
{:budget_not_confirmed, %{session_id:, echoed:, archived:}}, where archived is :ok or
{:error, reason} so a caller can clean up a session the archive did not reach.
Summary
Functions
Check the Claude Managed Agents create-response budget echo.
Coerce a map or an existing %Budget{} into a validated %Budget{}.
Render the Claude Managed Agents budget field.
Types
@type t() :: %ReqManagedAgents.Budget{max_list_cost_cents: pos_integer()}
Functions
Check the Claude Managed Agents create-response budget echo.
Coerce a map or an existing %Budget{} into a validated %Budget{}.
max_list_cost_cents must be a positive integer. The provider has one budget type
(:limit) and one currency ("USD"), so the struct does not store them; a map may name
them, but only with those values. Anything else returns {:error, :invalid_budget}.
Render the Claude Managed Agents budget field.