feat(core): the eager tool surface is a hand-maintained static list — let something choose it, without invalidating the prompt prefix #12326

Part of #12028. Complements #12029 (which bounds the preload budget); this is about who chooses the resident set in the first place. No dependency on open work — the measurement ruler it needs landed in #12119.

What happens today

tools.eager is the one knob that materially shrinks the resident tool surface: in the #12028 sample it takes built-in tool schemas from 21,461 to ~5,868 tokens, more than every upstream code change on this umbrella put together. But it is a hand-written list, and it is static:

• The allowlist is snapshotted once in PermissionManager.initialize() (permissions/permission-manager.ts:353), and a tool's registration status is decided when it is registered (config.ts → registerLazyTool). The setting is requiresRestart.
• A demoted tool is not disabled: it stays registered, listed in /tools, and loadable through tool_search.

So the mechanism already in the codebase is static starting set + model-driven top-up. The dynamic half exists. What is missing is that nothing chooses the starting set — every deployment enumerates tool names by hand, or (much more commonly) never sets the key at all and pays for the whole surface on every request.

Why this cannot simply become per-turn

Function declarations sit at the very front of the prompt prefix, so changing the declared set mid-session rewrites the prefix and invalidates its KV cache. From the #12028 sample (prefix ≈ 42k tokens, implicit cache at 20% of full price):

Demotion saves on the order of ¥0.01 per cached turn, while a single mid-session reveal costs ¥0.28–0.40. That is why the design deliberately decides once at session start and thereafter only adds — see docs/design/toolsearch-preload-threshold.md.

The contrast worth noting: a skill's paths: activation is turn-level, because the skill listing lives in history[0] rather than in the tools block, so changing it does not break the tools → system prefix (the reasoning is in the comment at core/environmentContext.ts). The same "adapt to the session" idea is cheap one layer up and expensive here. This is a placement constraint, not a missing capability.

What could choose the set

Four options, cheapest first. None of them changes the declared set mid-session.

Recommendation: C, with B as the manual override. C puts the adaptation between sessions instead of inside one, so it gets the benefit without touching the prefix-cache constraint at all.

Questions to settle before implementation

1. Where usage state lives. A project-scope file under .qwen/? It has to survive /clear and be per-project, since the right set differs by codebase.
2. Cold start. The first session in a project has no history. Fall back to the current behaviour (everything eager), or to a preset?
3. Starvation, and it is the serious one. A tool that is never offered is never called, so a usage-driven set can lock itself in: absence of calls is not evidence the tool was not needed. Options: a floor set that is always eager, periodic re-offering, or counting tool_search reveals as usage (a reveal is direct evidence the model wanted something it was not given).
4. Interaction with 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. Should the computed set be capped in tokens by maxPreloadTokens, or is that cap only about preloading deferred tools?
5. How a wrong set is observed. tool_search calls per session is the natural signal — the tracking(core): non-conversation context token governance #12028 analysis put the break-even at ≤2 reveals per session. Anything above that means the computed set is wrong, and it should be visible in telemetry rather than inferred from complaints.

Explicitly not proposed

• Mid-session promotion or demotion of declared tools. The cache arithmetic above says no.
• Per-turn classification after the first turn, for the same reason.
• Routing the usage telemetry through fix(core): context-usage telemetry is dropped entirely when a non-function tool is present, and mixes two token estimators #12048 — that issue was closed NOT_PLANNED after validation against real samples, so this needs its own (small) path.

Acceptance

• Idle cost (the input tokens of a session that asks one question and calls no tool) falls to the same order as a hand-written allowlist achieves, without a deployment writing one.
• tool_search calls per session stay at or below ~2 on a representative task set; above that the saving is cancelled by prefix rebuilds.
• No drop in tool-call success rate or task completion on that task set. This needs the evaluation harness the umbrella still lacks — worth stating plainly, because without it the starvation risk in question 3 is unfalsifiable.