How IterationBudget Stops Child Agents from Running Away

Why Agents Need an Iteration Budget: Prevent Endless Thinking

Without limits, a coding agent that repeatedly reads files, runs tests, and modifies code can loop indefinitely, causing four system‑level side effects: cost runaway, latency runaway, context inflation, and error amplification. The core question is when to stop exploring and acknowledge that the iteration budget is exhausted.

Core Implementation of IterationBudget

The agent/iteration_budget.py file defines a tiny thread‑safe class with consume(), refund(), and property accessors for used and remaining. Although it looks like a simple counter, its design carries several important meanings.

1) One Budget Object per Agent

Parent agents get their budget from max_iterations (default 90).

Child agents get theirs from delegation.max_iterations (default 50).

Each agent holds its own IterationBudget, making the budget an execution‑unit‑level quota rather than a global request quota.

2) Thread‑Safety

Because child agents can run concurrently, the class uses a lock to protect the counter. A race condition could either let the budget run past its limit (runaway) or stop it prematurely (early termination).

3) Support for Refund

Not every round should consume a full budget. When a round fails to start (e.g., Ollama runtime context too small) or consists solely of cheap RPC‑style calls like execute_code, the budget is refunded, ensuring that only genuine decision‑making rounds count.

How the Budget Takes Effect in the Main Loop

The main loop in conversation_loop.py checks both api_call_count and iteration_budget.remaining. api_call_count records how many model calls occurred, while iteration_budget governs whether another autonomous exploration is allowed. This separation clarifies the difference between factual call counts and governance eligibility.

Budget consumption is tied to an "iteration"—a full LLM decision round—not to individual tool calls. Multiple tool invocations within the same round (read file, grep, run test, summarize) are treated as a single exploration step, avoiding penalisation of legitimate multi‑tool workflows.

Grace Summary After Budget Exhaustion

When the budget is exhausted, Hermes does not abruptly cut off the agent. Instead, it emits a status message and gives the model a final, tool‑free summarisation turn. This provides the user with a coherent report of what was achieved, what failed, where the process stalled, and possible next steps.

Independent Parent‑Child Budgets

Each sub‑agent receives its own budget, allowing the total number of iterations across parent and children to exceed the parent’s max_iterations. This prevents the parent from being starved of budget by overly aggressive children and isolates failures to the offending sub‑agent.

Separating Budget, Timeout, and Concurrency

Hermes distinguishes three orthogonal constraints:

Iteration Budget – limits how many exploration rounds are allowed.

Child Timeout – caps wall‑clock time for a child agent (default 600 seconds).

Max Concurrent Children – caps the number of simultaneously running sub‑agents (default 3).

Keeping these controls separate avoids conflating different failure modes and enables fine‑grained tuning.

Industry Comparison

Other systems adopt similar budgeting ideas but at different granularities:

Claude Code / Codex CLI: per‑round limits with human‑in‑the‑loop handover.

LangGraph / AutoGen: graph‑node step limits and stop‑conditions.

Cursor / Devin‑style agents: budgets bound to tasks/jobs with additional wall‑clock and audit layers.

Hermes: per‑agent IterationBudget that governs autonomous reasoning while allowing cheap execution to be refunded.

Key Takeaways

IterationBudget is a governance boundary, not a simple counter.

Budget is applied to LLM decision rounds, not individual tool calls.

Refund mechanisms protect low‑cognition rounds from consuming budget.

Grace summary turns budget exhaustion into a useful final report.

Independent parent‑child budgets preserve hierarchical control.

Separating budget, timeout, and concurrency yields clearer, tunable system behaviour.