[BUG] WebSearch session cap (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION) fails silently: over-budget calls return non-error results and agents continue from model memory, corrupting long research workflows

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code enforces an undocumented per-session cap on WebSearch calls (env: CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION). When the cap is exceeded, the tool returns a NON-ERROR result instructing the model to "continue with what it has gathered" and, only if more searches are genuinely needed, to ask the user to raise the variable. In long-running multi-agent research workflows this produces silent degradation: nothing fails visibly, no error reaches the operator, and agents keep producing output sourced from stale model memory instead of live search.

My case: ~3 weeks of research workflows on a Max 20x plan, on a frontier technical topic where post-cutoff sources are essential. Agents hit the cap repeatedly (4 refusal records in one session .jsonl, refusal text found verbatim) and never surfaced it; they continued answering from memory. The env var string is present 6x in my claude.exe, while official documentation contains neither the cap, nor its default, nor the variable. Weeks of paid usage were consumed producing research that must now be audited and redone.

A hard resource exhaustion that returns a non-error result gives orchestration layers and operators zero signal, and "continue with what you have gathered" explicitly instructs degraded continuation.

What Should Happen?

1.Over-budget WebSearch should surface as a visible warning/error at the session UI level and in headless logs- not only as a tool-result instruction to the model
2.The cap, its default, and the env var should be documented in official docs
3./usage or /status should show remaining search budget
4.A mode should exist where search exhaustion HALTS the workflow instead of silently degrading it

Error Messages/Logs

Steps to Reproduce

1.Start a long multi-agent research workflow requiring many web searches
2.Let WebSearch calls exceed the session cap (default ~200)
3.Observe: no error or warning surfaces to the operator; the session .jsonl contains a non-error refusal instructing the model to continue with gathered material; agents proceed to answer from model memory
4.Compare deliverables against live sources: post-cutoff information is absent or fabricated

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.110.0

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Other

Additional Information

_No response_