Enforce token_budget before each iteration #22

Merged

archeious merged 1 commit from fix/budget-enforcement into main

2026-04-08 21:30:27 +00:00

claude-code commented

2026-04-08 21:29:32 +00:00

Collaborator

Closes Issue #17

Change

Move the budget check from the bottom of each iteration to the top. A new iteration is never started past the budget.
Document the policy as a comment: token_budget is a soft cap on the tool-use loop only. The synthesis call is always allowed to complete so callers get a structured ResearchResult rather than a fallback stub.

Why uncap synthesis

Capping synthesis would force returning a parse-failure stub the moment evidence-gathering ran long — exactly the failure mode Issue #16 fixed. A proper budget that includes synthesis requires splitting the cap up-front (e.g. reserve 50% for synthesis), which is a separate design call.

Verified

With token_budget=5000, max_iterations=10:

	Before	After
Iterations run	(would run all 10)	2
`budget_exhausted`	true (post-hoc)	true (pre-iteration, accurate)
Citations	(varies / fallback risk)	10 real citations
Loop tokens	unbounded over budget	bounded at first iteration past 5000

88/88 tests still passing.

Closes Issue #17 ## Change - Move the budget check from the *bottom* of each iteration to the *top*. A new iteration is never started past the budget. - Document the policy as a comment: `token_budget` is a soft cap on the tool-use loop only. The synthesis call is always allowed to complete so callers get a structured ResearchResult rather than a fallback stub. ## Why uncap synthesis Capping synthesis would force returning a parse-failure stub the moment evidence-gathering ran long — exactly the failure mode Issue #16 fixed. A proper budget that includes synthesis requires splitting the cap up-front (e.g. reserve 50% for synthesis), which is a separate design call. ## Verified With `token_budget=5000, max_iterations=10`: | | Before | After | |---|---|---| | Iterations run | (would run all 10) | 2 | | `budget_exhausted` | true (post-hoc) | true (pre-iteration, accurate) | | Citations | (varies / fallback risk) | 10 real citations | | Loop tokens | unbounded over budget | bounded at first iteration past 5000 | 88/88 tests still passing.

claude-code added 1 commit 2026-04-08 21:29:33 +00:00

Enforce token_budget before each iteration (#17 ) 6ff1a6af3d

The loop previously checked the token budget at the *bottom* of each
iteration, after the LLM call and tool work had already happened. By
the time the cap was caught the budget had been exceeded and the
overshoot was unbounded by the iteration's cost.

Move the check to the *top* of the loop so a new iteration is never
started past the budget. Document the policy explicitly: token_budget
is a soft cap on the tool-use loop only; the synthesis call is always
allowed to complete so callers get a structured ResearchResult rather
than a fallback stub. Capping synthesis is a separate, larger design
question (would require splitting the budget between loop and
synthesis up-front).

Verified: token_budget=5000, max_iterations=10 now stops after 2
iterations with budget_exhausted=True and a complete answer with
10 citations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>