fix(agent): stop collapsing the output cap to 1 token near a full context window

[OmarB97]

What does this PR do?

output_tokens_that_fit() returned its min_output floor (1) when the reserved input filled the window, and both callers consumed that fabricated 1 as a real budget — sending max_tokens=1 to the provider.

The reservation is multiplicative — int(est * 1.2) + 1024 + 512 — so it exhausts the window once the rough estimate passes ~(ctx - 1536) / 1.2, about 82.7% fill. Past that point:

• the pre-flight clamp in build_api_kwargs set max_tokens=1 on every request, with no provider error involved at all; and
• the reactive output-cap retry clamped a healthy provider-authoritative cap down to 1 — directly contradicting the branch immediately above it, which deliberately falls back to the provider's number precisely because "the rough local estimate can overshoot the real request size".

Measured against a 200,000-token window:

prompt fill	provider available_tokens	cap actually sent
80%	35,000	6,455
83%	30,000	1
85%	25,000	1

A cliff, not a degradation — and it applies to any window size, not just this shape.

max_tokens=1 is the worst available failure mode: the provider accepts it and returns a single truncated token, so the turn reports success while handing back output the user cannot use. Nothing fails loudly.

Why this approach: the fix is to report None — "no usable cap; leave max_tokens to your own budget logic" — instead of fabricating a floor. Both call sites already guarded None correctly, so neither needed a code change. min_output has no external callers, so the semantic change is fully contained in one function.

Regression introduced in #271. That PR's vLLM / deepseek-v4-flash-w2 convergence property is unaffected — that regime sits at ~44% fill, where the fit stays positive and the reactive retry still converges in one step.

Relationship to #295

#295 refreshed two assertions. One was right, one was not:

• test_codex_content_filter_incomplete_routes_to_policy_fallback — correct, and stands. conversation_loop.py:2174 really does pass the classified FailoverReason into the fallback switch since fix: make provider fallback policy explicit and visible #269; asserting it is strictly stronger.
• test_output_cap_retry_request_pressure_lower_bound — reverted here. That assertion was loosened to max(1, min(expected_cap, local_fit)), which amounts to asserting whatever the code did. The original arithmetic was right; it now passes for the right reason (903, not 1).

Known tradeoff

Above 82.7% fill the pre-flight clamp now no-ops, so those turns eat a provider 400 before the reactive retry corrects it with the provider's authoritative budget. That is strictly better than silently returning a 1-token answer, but it costs a round-trip. Bounding the safety reservation so the clamp degrades gracefully instead of going silent is worth a follow-up; it is a reservation-policy redesign and does not belong in a defect fix.

Related Issue

Regression from #271. Test-side follow-up to #295.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• agent/model_metadata.py — output_tokens_that_fit() returns None instead of the min_output floor when the reserved input leaves no positive cap. Docstring now states that None means "no usable cap" (never a licence to shrink), that min_output is the smallest fit worth reporting rather than a fallback value, and documents the ~82.7% fill threshold explicitly.
• agent/conversation_loop.py — comment only, at the reactive output-cap retry: records why the None case must keep the provider-authoritative safe_out so the floor is not reinstated.
• tests/test_output_fit_preflight_clamp.py — new TestNearFullWindowNeverYieldsAUselessCap (5 cases) covering the 82.7–100% fill band at both call sites.
• tests/run_agent/test_run_agent.py — reverts the test half of test(agent): refresh two assertions that predate current retry/fallback behavior #295 for test_output_cap_retry_request_pressure_lower_bound.

How to Test

1. Reproduce the defect — on main, output_tokens_that_fit(131072, [{"role": "user", "content": "x" * 460000}]) returns 1. That prompt is ~115k tokens in a 131,072 window, leaving ~16k of genuine headroom.
2. See it reach the wire — scripts/run_tests.sh tests/test_output_fit_preflight_clamp.py -q with this PR's tests but main's model_metadata.py fails 4 of them, each on the value 1:
   • test_reports_none_rather_than_a_floor → assert 1 is None
   • test_preflight_leaves_cap_alone_instead_of_clamping_to_one → assert 1 is None
   • test_reactive_retry_keeps_provider_authoritative_cap → assert 1 > 1000
   • test_every_reported_fit_is_a_real_fit → reported fit does not fit
3. Verify the fix — scripts/run_tests.sh tests/test_output_fit_preflight_clamp.py tests/run_agent/test_run_agent.py -q → 14 + 436 pass.

test_every_reported_fit_is_a_real_fit sweeps the whole fill range and holds every non-None answer to the safety property the function documents (a server tokenizing ~15% denser must still leave the request in-window). A fabricated floor fails that by construction, so a reintroduction is caught at the root rather than by pattern-matching the literal 1.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix
• I've run the suite and all tests pass — see below
• I've added tests for my changes
• I've tested on my platform: macOS 15 (Darwin 25.6.0)

Full-suite status: scripts/run_tests.sh reports 34 pre-existing failures on unmodified origin/main in this environment (systemd/WSL paths on macOS, absent Codex credentials, one concurrency flake in test_base_environment.py). This branch reproduces exactly that set — no new failures. tests/agent/test_anthropic_adapter.py fails identically (3) on both refs. The directly affected files are fully green: tests/run_agent/test_run_agent.py 436/436, tests/test_output_fit_preflight_clamp.py 14/14.

Documentation & Housekeeping

• I've updated relevant documentation (docstrings) — the output_tokens_that_fit contract is the thing that was misread, so it is now explicit about what None means and what min_output is not
• cli-config.yaml.example — N/A, no config keys
• CONTRIBUTING.md / AGENTS.md — N/A, no architecture or workflow change
• Cross-platform impact — N/A, pure arithmetic
• Tool descriptions/schemas — N/A

🤖 Generated with Claude Code