Governed runs (beyond codex): aggregate attempts, time, tokens, spend, and descendant tool budgets

[yxlyx]

Parent

#216

Problem

A goal turn has several local caps, but no aggregate budget controls the whole run:

• Agent.runTurn() repeats model/tool rounds with while (true).
• max_tokens = 16000 limits one response, not cumulative tokens.
• --max-tool-calls defaults to unlimited and counts only root calls; descendant subagent/workflow tool activity is not comprehensively charged.
• request/idle watchdogs do not bound total run wall time;
• cost is measured but never used as a stop condition;
• network retry limits are transport policy, not goal-attempt limits.

A production run must know before each action whether enough budget remains.

Proposal

Introduce a harness-owned RunBudget/RunUsage envelope for governed /goal and /loop runs. At minimum support:

• max_attempts / outer verifier retries;
• max_model_rounds;
• max_elapsed_ms using a monotonic deadline;
• aggregate input, cached-input, reasoning, and output token ceilings;
• max_usd for priced providers plus an explicit policy for unpriced/subscription providers;
• aggregate tool-call ceiling across root, subagent, workflow, and MCP descendants;
• optional concurrency ceiling.

Expose policy through terminal CLI flags/slash controls and TUI session persistence. Use finite documented defaults for governed runs; allow ordinary interactive chat to preserve its current behavior if clearly distinguished. This issue is exclusively TUI/harness scope.

Enforcement requirements

• Check budget before every model request and tool dispatch/reservation.
• Parallel work must reserve atomically so a batch cannot overshoot through races.
• Descendants inherit a non-widenable slice of the parent's remaining budget.
• Retries and verifier calls are charged, including failed API attempts where usage/cost is knowable.
• On exhaustion, cancel/stop descendants and emit a structured terminal reason rather than asking the model to stop voluntarily.
• The agent may request escalation but may not increase its own budget.

Acceptance criteria

• Governed runs start with finite defaults for every supported aggregate dimension.
• TUI users can lower limits through CLI flags or slash controls; widening an active run requires explicit human approval.
• Root + nested usage is visible as used/remaining values.
• A deliberately non-terminating tool loop stops at the configured model-round/tool/time ceiling.
• A subagent fan-out cannot exceed the parent's tool/token/cost allocation.
• Parallel reservations are race-safe and bounded.
• Exhaustion emits a machine-readable exhausted event with the exact dimension and used/limit values.
• Tests cover each limit independently and simultaneous-limit races.

Related

• Add harness-level max tool-call and duplicate-suppression controls #61 added optional root tool-call/dedupe controls; this issue extends accounting to finite governed defaults and the full descendant tree.
• codex/gpt-5.x: a single-turn tool-output burst overflows the context window before auto-compaction fires (no pre-send local-estimate gate) #193 covers context-window safety, which is distinct from cumulative token budget.
• Article: https://www.llmrumors.com/news/loop-engineering-designing-agent-stop-conditions

[justrach]

@yxlyx I checked #217 against how openai/codex actually governs a goal run (fresh deepwiki pass over the Goal Extension / State Runtime code: ThreadGoal, GoalExtension, GoalStore, GoalToolExecutor), so we can separate the parts of your design that have a codex reference to copy from the parts that are genuinely new ground.

What codex actually does (the grounded core of your proposal):

• Per-goal aggregate token budget, with tool usage folded in. A ThreadGoal carries token_budget / tokens_used, and when a tool finishes GoalExtension.on_tool_finish triggers account_active_goal_progress(), which flushes the recorded token deltas into the active goal's tokens_used. So there IS a single cumulative token counter per goal, and tool activity does count against it. That is your "aggregate token ceiling," and we already have it scoped concretely as Per-goal budget accounting: tokens + elapsed time, surfaced at goal start, with a budget-limit steering nudge #224 (per-goal token+time accounting + one-shot BudgetLimited steering nudge).
• Named limited/terminal states. ThreadGoalStatus = Active, Paused, Blocked, BudgetLimited, UsageLimited, Complete. Your "structured terminal reason" instinct is right; codex expresses it as these enum states, tracked as Structured goal state + status lifecycle (/goal pause, /goal resume, /goal status) #223 (status lifecycle).
• The agent cannot widen its own budget. The model can call update_goal to change the objective, or mark the goal Complete/Blocked, but it cannot raise token_budget (and the other status transitions are system-driven, not model-controlled). That matches your "agent may request escalation but may not increase its own budget."

What codex does NOT do (the parts of #217 that go beyond codex):

• No wall-clock deadline. time_used_seconds is accounting-only; it is incremented and persisted, but no code checks it against a limit to auto-terminate a goal. Your max_elapsed_ms monotonic deadline has no codex analog.
• No max_attempts, no outer verifier-retry ledger, no attempt-fingerprint dedup, no max_model_rounds.
• No max_usd stop condition. codex prices usage but never stops on spend.
• No non-widenable descendant SLICE. This is the key nuance: codex charges descendant/tool tokens against the parent, but as a flat rollup into one tokens_used counter, not a reserved, hierarchically-inherited, non-widenable sub-budget. There is no per-descendant allocation to widen or protect.
• No aggregate tool-CALL-count ceiling and no concurrency ceiling. codex meters tool tokens, not a capped count of tool/subagent/MCP calls.
• The philosophical divergence worth flagging: on per-goal budget exhaustion codex does the opposite of hard-cancel. It flips the goal to BudgetLimited and injects budget_limit_steering_item ONCE, a soft nudge to wind down, and the turn keeps accruing tokens past the budget. The only hard stop is the session usage-limit layer (UsageLimited via UsageLimitExceeded), not the per-goal budget. Your "on exhaustion cancel/stop descendants + emit a structured terminal reason, not ask the model to stop voluntarily" is a deliberate step past codex's soft-steer model.
• On completion, codex is model-asserted: update_goal -> Complete via GoalToolExecutor, with no independent verifier and no held-out acceptance gate. So the "outer verifier retries" budget has nothing in codex to attach to yet; it presupposes a verifier contract codex does not have.

Exact locations in codex (openai/codex, codex-rs tree, so each claim above is checkable):

• ThreadGoal { objective, status, token_budget, tokens_used, time_used_seconds } and the ThreadGoalStatus enum (Active, Paused, Blocked, BudgetLimited, UsageLimited, Complete): codex-rs/protocol/src/protocol.rs (the codex-protocol crate; re-used by the goal ext and the app-server).
• Tool tokens fold into the goal: codex-rs/ext/goal/src/extension.rs GoalExtension::on_tool_finish -> codex-rs/ext/goal/src/runtime.rs GoalRuntimeHandle::account_active_goal_progress -> codex-rs/state/src/runtime/goals.rs GoalStore::account_thread_goal_usage. That last function is where tokens_used is actually incremented and where the BudgetLimited transition fires when tokens_used exceeds token_budget.
• One-shot soft nudge: codex-rs/ext/goal/src/steering.rs budget_limit_steering_item, injected once by on_tool_finish (extension.rs) via GoalRuntimeHandle::inject_active_turn_steering.
• time_used_seconds is accounting-only: codex-rs/ext/goal/src/accounting.rs GoalWallClockAccounting computes the delta and account_thread_goal_usage (goals.rs) persists it; nothing compares it to a deadline.
• Hard session stop is the usage-limit layer, not the goal budget: ThreadGoalStatus::UsageLimited (protocol.rs) is set by codex-rs/state/src/runtime/goals.rs usage_limit_active_thread_goal, called from codex-rs/ext/goal/src/runtime.rs GoalRuntimeHandle::usage_limit_active_goal_for_turn, triggered by the UsageLimitExceeded variant of CodexErrorInfo.
• Completion is model-asserted and the agent cannot widen its own budget: codex-rs/ext/goal/src/tool.rs GoalToolExecutor::handle_update rejects any status other than Complete/Blocked and never accepts a token_budget change (tool schema in codex-rs/ext/goal/src/spec.rs create_update_goal_tool).

Cross-check - opencode (anomalyco/opencode, deepwiki): I ran the same question against a second real harness to triangulate. Like codex, opencode has NO cumulative-token STOP (token counting only drives compaction, isOverflow in packages/opencode/src/session/overflow.ts, i.e. the same context-window concern as #193, not a spend budget), NO agent-loop max_usd stop (dollar limits are subscription/service-level: OpenCode Go / Zen plus the console's providerBudgetTracker, not a per-run stop), and NO non-widenable descendant slice (each SessionV2 is metered independently in its own SessionTable row, packages/core/src/session/sql.ts, with no parent rollup at all, even flatter than codex). So #217's max_usd, cumulative-token stop, and reserved descendant slice are genuinely beyond BOTH harnesses. BUT two dimensions listed above as beyond-codex DO have an opencode reference, which is worth flagging: a per-run model-round cap (AgentConfig.steps, formerly maxSteps; enforced by SessionRunner in packages/core/src/session/runner/llm.ts, which forces toolChoice="none" + a MAX_STEPS_PROMPT at the limit; LLM.generate default is StopWhen.turnCount(20) -> stopReason: "max-turns"), and a HARD wall-clock + tool-call ceiling (ExecutionLimits.timeoutMs interrupts even a while (true) {} loop, and maxToolCalls -> ToolCallLimitExceeded, both in packages/codemode/src/codemode.ts) - though that hard ceiling is scoped to opencode's CodeMode sandbox runtime, not its general agent loop. Net: max_model_rounds and the aggregate tool-call ceiling are not unprecedented, just absent in codex, and shipping them has a working reference in opencode; hard-cancel-on-exhaustion, max_usd, and the non-widenable descendant slice remain new invariants relative to both.

Suggestion: This is a careful, well-structured design, and most of it is a genuine improvement over codex rather than a mismatch. I would lift the codex-grounded core out of #217 since it is already tracked (per-goal token budget with tool rollup = #224, terminal-state naming = #223), and keep #217 as the explicit beyond-codex "governed-run hardening" umbrella for the parts codex has no analog for: wall-clock deadline, attempts / verifier-retry ledger, max_usd, the non-widenable descendant slice, tool-call-count + concurrency ceilings, and hard-cancel-on-exhaustion. A small title reframe so it reads as "governed-run budgets (beyond codex): ..." would keep the design intact while making clear which slices ship on a codex-shaped foundation (#223/#224) and which are new invariants we are choosing to add on top.

Broader cross-check - other harnesses

Beyond codex and opencode, per-run budget STOP conditions across seven more harnesses are real but uneven: iteration/mistake caps are near-universal, agent-loop USD stops exist in three, and a true aggregate (across-runs) cost ceiling exists in exactly one. Wall-clock timeouts do turn up in a couple of harnesses, but none is tied to a token/USD budget, and no harness surveyed enforces a non-widenable descendant budget slice or a budget-tied concurrency ceiling.

• SWE-agent — closest reference for Governed runs (beyond codex): aggregate attempts, time, tokens, spend, and descendant tool budgets #217's cost model: per_instance_cost_limit (default $3.0) + total_cost_limit (aggregate across instances) + per_instance_call_limit step cap, all fields on GenericAPIModelConfig, each checked after every API call in LiteLLMModel._update_stats() and raising a distinct hard exception (InstanceCostLimitExceededError / TotalCostLimitExceededError / InstanceCallLimitExceededError, defined in sweagent/exceptions.py).
• OpenHands — max_iterations step cap (default 500) + max_budget_per_task USD hard-stop (default 0.0 = off; fires a ConversationErrorEvent "Budget has been exceeded!"), both in config.template.toml; accumulated_cost accrues across the run. No wall-clock, no descendant slice.
• Roo-Code — allowedMaxRequests + allowedMaxCost (per-task USD) auto-approval circuit breakers in packages/types/src/global-settings.ts, plus a per-task consecutiveMistakeLimit (default 3) on the Task class. The request/cost limits apply across the whole task hierarchy; the mistake limit is per-task. Exhaustion PAUSES (ask-to-continue), it does not hard-cancel. No token-ceiling or wall-clock stop.
• Cline — richest timeout story after SWE-agent: maxConsecutiveMistakes (hard-fail under YOLO, else ask-to-continue) in recursivelyMakeClineRequests (src/core/task/index.ts); AgentConfig.maxIterations (enforced when set), maxTokensPerTurn, and per-call apiTimeoutMs (default 180000) in sdk/packages/shared/src/agents/types.ts; an optional whole-run wall-clock abort via config.timeoutSeconds in run-agent.ts; and a server-side SpendLimit streaming abort (not an agent-loop USD knob).
• goose — turn caps only: GOOSE_MAX_TURNS (default 1000) + per-descendant GOOSE_SUBAGENT_MAX_TURNS (default 25) + GOOSE_GATEWAY_MAX_TURNS (default 5), enforced in Agent::reply (crates/goose/src/agents/agent.rs); tokens tracked via accumulated_total_tokens. No USD/time/cost-ceiling stop.
• gemini-cli — session turn cap: maxSessionTurns (default -1 = unlimited) plus a hardcoded MAX_TURNS = 100 loop safeguard (packages/core/src/core/client.ts), checked in GeminiClient / LegacyAgentSession; FatalTurnLimitedError (exit 53) non-interactive. A sub-agent wall-clock exists (RunConfig.maxTimeMinutes), but no USD or token-ceiling stop in the main loop.
• aider — only max_reflections (default 3) via num_reflections in aider/coders/base_coder.py, a reflection cap on auto lint/test fixes; total_cost is tracked but never used as a stop (context-length errors are reported, not budgeted).
• continue — tracks cumulative SessionUsage.totalCost via SessionManager.trackUsage and auto-compacts (shouldAutoCompact), but enforces no iteration cap, no USD stop, no token-ceiling stop, and no wall-clock in the CLI agent loop; ClawRouter's spendLimit is provider-specific, not core.

Bottom line: #217's core budget knobs have concrete prior art — SWE-agent for an aggregate + per-run USD/call ceiling with hard exceptions, OpenHands for a step-cap + per-task USD stop, Roo-Code for request + USD caps that span a task hierarchy. Wall-clock deadlines appear too, but only as untethered timeouts (Cline's whole-run timeoutSeconds, gemini-cli's sub-agent maxTimeMinutes), never tied to a token/USD budget. Still absent everywhere surveyed: a budget-tied max_elapsed_ms agent-loop deadline, a non-widenable descendant budget slice charged across subagents/MCP, and a budget-tied concurrency ceiling.

[justrach]

Progress note: run_budget.zig now enforces model-call count, concurrency (8), and depth atomically across all call kinds, and v0.0.233 fixed the --help text that falsely advertised a default budget of 256 (real default is 0 = unlimited; PR #362). Still missing from the original ask: time/token/USD ceilings, attempt caps, and subagent tool calls are currently exempt (agent_tools.zig:218-219).

[justrach]

Measured local archive (17 Jul–25 Aug, 603 turns) argues against a default inner-loop cap of 16: 174 successful turns already ran past that, and Interrupted p50 is 5 model-calls. Filed as #624 (pulse without default cap 16) and #625 (retry chrome — HungRequest/UnknownHostName are the other “looks hung” path). Run-level token/cost/time budgets in this issue stay the right layer for aggregate limits.