Percentage-of-context-window budgets scale the wrong way: ToolSearch preload never engages, and the always-on context warning never fires, on large windows #12029

Part of #12028.

Two budgets in the codebase are expressed as a percentage of the model's context window. Both guard against costs that have nothing to do with the window size, so both stop working exactly as windows get large — and the project is moving towards large windows.

1. tools.toolSearch.threshold (default 10% of the window)

packages/core/src/core/client.ts:1766-1772 computes budget = floor(contextWindow * percent / 100), and packages/core/src/tools/tool-registry.ts:1073-1079 reveals the entire deferred set if it fits (all-or-nothing by design).

docs/design/toolsearch-preload-threshold.md explains the tradeoff being made, and it is a real one:

"every mid-session reveal rewrites the function-declaration list, which sits at the front of the tools→system→messages prefix, so a single ToolSearch load invalidates the entire prompt KV cache. For a small deferred set the deferral saves little and the cache damage plus the extra ToolSearch round-trip make it a net loss."

So the gate is asking: is the deferred set big enough that hiding it beats one prefix rebuild? Neither quantity depends on the context window. The window only appears because the 10% figure was carried over from Claude Code's ENABLE_TOOL_SEARCH=auto, where the same number is used under a different cost model (the doc says as much at lines 65-70).

The doc never discusses what the percentage means at 256K or 1M. The only sizing guard is an upper clamp at 100% (client.ts:1758-1764).

Observed on a 1M-context model: budget = 100,000 tokens, deferred pool ≈ 4.2k, so every deferred tool is revealed at session start. Ten tools that are shouldDefer: true upstream were all present in the request:

cron_create 1,103 · web_fetch 693 · web_search 499 · send_message 498 · monitor 475 · create_sub_session 409 · read_mcp_resource 191 · cron_delete 116 · task_stop 102 · cron_list 80 — 4,166 tokens, 19.4% of the built-in tool block, on every request of every session.

Deferral is not merely weakened here; at this window size it can never engage.

2. MEMORY_CONTEXT_WARNING_RATIO (15% of the window)

packages/core/src/config/config.ts:322, warning at :4702-4727:

Warning: Loaded always-on context (QWEN.md context files + auto-memory) uses about ${estimatedTokens} tokens, more than 15% of this model's ${contextWindowSize} token context window.

At 1M that warning fires at 150,000 tokens. The same session carried 15,400 tokens of context files — 33% of all its non-conversation context — and printed nothing. The warning is silent precisely where always-on context is cheapest to accumulate and most expensive in aggregate.

Suggestion

Express both as an absolute token budget, or as min(percent-of-window, absolute cap) so small-window behaviour is preserved. For the preload gate the natural cap is a small multiple of what one prefix rebuild costs, which is a function of the prefix size — not the window.

Worth stating explicitly in the docs either way: threshold: 0 is not a free win. It trades a fixed per-request cost (the deferred schemas) for an occasional prefix rebuild, so it pays off only when the deferred tools are rarely used in a session. Today that tradeoff is invisible to anyone who has not read the design doc.