Self-Regulating Agent Loops: Claude's Task Budget Tells the Model When to Wrap Up Gracefully

Add task_budget to output_config and Claude sees a live token countdown across the entire agentic loop — it self-regulates, summarizes findings, and finishes cleanly instead of cutting off mid-action.

The problem with long agent loops: Claude doesn't know when to stop. It uses 80k tokens on exploration, then either runs out of max_tokens and gets cut off mid-action, or keeps going until you stop it. Task budgets fix this.

How it works

Task budgets are a beta feature available on Claude Fable 5, Mythos 5, Opus 4.8, and Opus 4.7. Set task_budget in output_config alongside effort. The model sees a running token countdown covering thinking, tool calls, tool results, and output. As the budget depletes, it starts wrapping up — summarizing findings, skipping lower-priority exploration, finishing gracefully.

import anthropic

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-4-8",
    max_tokens=128000,
    messages=[{"role": "user", "content": "Audit this repo for security issues."}],
    output_config={
        "effort": "xhigh",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    betas=["task-budgets-2026-03-13"],
) as stream:
    response = stream.get_final_message()

print(response.usage)

Key points

Minimum 20,000 tokens. Below that, the API returns a 400. Set too small and Claude may refuse the task entirely — size it against your actual p99 token spend from a baseline run without the budget.

task_budget is advisory, max_tokens is hard. The budget tells Claude to pace itself; max_tokens truncates unconditionally. Use both: budget for graceful self-regulation, max_tokens as the absolute ceiling.

Compacted loops — pass remaining: If your client summarizes context between turns, the server loses track of what's been spent. Pass remaining on the next request so the countdown continues from where you left off:

output_config={
    "effort": "xhigh",
    "task_budget": {
        "type": "tokens",
        "total": 64000,
        "remaining": 64000 - tokens_spent_so_far,
    },
}

Caching note: Don't mutate remaining on every turn for loops that resend full history — changing the value invalidates the cache prefix. For full-history loops, omit remaining and let the server track the countdown.

When to reach for it

Any workflow where Claude makes repeated tool calls before returning a final answer: code audits, multi-file refactors, research + summarize loops, agentic search tasks. If your loop currently cuts off mid-action or goes wildly over budget, add a task budget sized at ~1.5× your median token spend and tune from there.

Sources: Task budgets — Claude Platform Docs · Effort — Claude Platform Docs