fix(core,docs): correct what the deferred-tool bridge made stale or untested - #12355

Both DeepSeek clauses are fixed in 3d302b36cb (rebased onto the concurrent README re-baseline, disjoint files).

• The rewritten bridge bullet no longer lists "the automatic opt-out for prefix-caching models such as DeepSeek" as a way the bridge ends up unregistered.
• The trap-list entry no longer ends with "DeepSeek models opt out of ToolSearch automatically for this reason".

Verified against the tree before editing: packages/cli/src/config/config.ts gates purely on settings.tools?.toolSearch?.enabled === false (its only effect is the two mergedDeny.push calls for tool_search/tool_call), its own comment states the bridge stays enabled "including for prefix-cache-sensitive models", config.test.ts asserts deepseek models are not denied, and a repo-wide grep finds no model-based opt-out left in the CLI/core config paths — consistent with what #10410 shipped.

Left out of scope deliberately, per the stage-3 note that these are non-blocking and the author's call: the plan doc §2 and docs/verification/context-token-governance/README.md §2.6 wording questions. prettier --check passes on the changed file.

The DeepSeek finding is fixed — 3d302b36 (another session of mine, which removed the false fact) plus d5c22c20, which removes the false implication it left behind.

Verified against main before touching it: git grep -in deepseek origin/main -- packages/cli/src/config packages/core/src/config packages/core/src/tools returns only config.test.ts assertions that the bridge stays enabled for those models, and packages/cli/src/config/config.ts:2106 gates solely on settings.tools?.toolSearch?.enabled === false. Both clauses came from a September reading of the model-name regex #10410 deleted.

One thing worth separating, since the first commit stopped at the fact: the remaining sentence still said that for a prefix-caching model, keeping the declaration list identical beats keeping it small. Post-bridge that is no longer true for the deferral decision — reaching a withheld tool is prefix-stable — so a deployment that turned ToolSearch off by hand to protect a prefix is holding an expired reason, and the bullet now says so. It keeps the half that is still true: prefix stability argues against everything else that rewrites the prefix mid-session.

Thanks for the citations. They turned this into a two-minute edit instead of a re-derivation.

All nine findings are now closed. R1-1/R1-2/R1-3/R1-4 and §7 item 3 in 0ed2941b, 57b26d13, 70c9c3f8; the remaining five in 6d7c29d8.

R1-5 — you are right that I over-closed it. #10410 changed a default and added no cap: client.ts still sizes the budget as floor(window × percent / 100) with the percentage clamped to 100, which is symmetric in percent and not in tokens, and the preload stays all-or-nothing. The cell now records it as half-closed, and names the reason the open half matters — this repo's own brief tells a reader to raise the threshold when a session will certainly need those tools, which brings the gap straight back.

R1-6 — both rows corrected against the tag range: #12142 36887c49 shipped in v0.24.2, #12030's first half merged as fbd6ccc2 and the issue closed the same day. The row now also says what is genuinely undone, which the old wording buried: the conditional-rule mechanism landed and nobody has moved content onto it, so the 10,400 tokens are still on the table.

R1-7 — banner added at the top of the plan doc, naming §1/§2/§5 as v0.24.1 readings and pointing at §0.1. It also fixes §10's "less than a tenth of that step" against the 4.2k/11.4k split this PR's own README states, and notes §3's exemption list needs tool_call.

R1-8 — restated at ~2,230 with the three components that moved: tool_call 148 added, task_stop 102 dropped (it is shouldDefer=true, so it was never resident), tool_search 375 → 394. I did not re-run your probe, so the numbers are attributed to it rather than presented as mine, and the reader's own /context detail is named as the authority. Thank you for dropping the two limbs that did not survive verification — that is the part that made this a correction rather than a re-argument.

R1-9 — row 2 is now the required one, with the derived ~17,300 named as the fallback when row 1 is unobtainable. Both subtractions stay computable.

One note on process: two sessions of mine were editing this branch in parallel today, which is why some findings have two fixes. Where that happened I took the other commit's version and added only what it was missing, rather than layering a second rewrite on top.

@qwen-code /triage

Round 3 closeout — three of the five nits fixed, two deferred.

1a1c02ae corrects the three that were wrong in text this PR itself added. Each re-verified against the tree rather than taken from the review:

• The config.ts citation. Both files pointed at packages/cli/src/config/config.ts:2102-2114 for the tools.toolSearch.enabled === false gate. That range is auth-type resolution and validateModelProvidersConfig; the gate is shouldDisableToolSearch, at 2142. Both now cite the symbol instead of a range — the review's better suggestion, since a symbol cannot drift and this doc's whole premise is coordinates read from main.
• §0.1's commit count. The sentence announced a packages/core/src/{tools,permissions} basis and then listed six commits on a topical one. Confirmed through the API: fix(cli): require explicit trust for undecided workspaces #12198 has 0 of its 21 files under either directory, and fix(core): hide unavailable image zoom guidance #12271 / test(core): report what a tool-surface configuration actually withholds #12346 touch only tools/read-file.test.ts and permissions/eager-surface-report.test.ts there — so the announced filter yields 3 (feat(core): preserve prompt cache for deferred tools #10410, fix(core): gate teammate guidance and budget large tool surfaces #12142, fix(core): handle simple Bash comments in permission rules #12096), not 6. The two bases are now named separately, with the number a recomputing reader would otherwise get wrong.
• 70edbf47. One parent (dfdbbace), so it is a squash commit, not a merge commit.

Deferred, both now disclosed under Risk & Scope:

• The ~276 token figure. Real staleness, but it is upstream drift rather than a defect at this head: the pinning test still reads 1,104 characters (~276 tokens) at this PR's base (da695fea) and only became 1,421 characters (~355 tokens) on main afterwards, once the monitor bullet got gated too. Correcting it here means merging 10 commits of main to stay self-consistent, and base movement on its own is not a reason to push. It belongs with the next main merge.
• §10's stale "less than a tenth" sentence. Fixing it in place would pull docs/plans/…:300 — currently a context line — into the diff. The top banner already names and restates it, so a reader who lands on §10 is one hop from the correction.

The description now also covers docs/verification/context-token-governance/README.md (+97/−14, the entire new §0.1), which was the largest change in the diff and previously absent from it, and says plainly that §0.1's #12096 / #12198 upgrade-risk rows sit past the goal in its first line.

Scope ledger, recorded below so the next pass does not restart at round 0. Baseline is the earliest reviewed head e6e4c2db; docs went +8/−6 across 2 files → +119/−30 across 3, and this round added none of that — post-fix totals are identical to round start (4 files, +126/−30, implementation 0). The growth is author-driven (225a8925, a concurrent re-baseline of the handoff doc), not review-induced, so there was nothing to revert; the correct move was to make the description match the diff. This is substantive round 3, which is the limit — a next round needs a human decision rather than another automatic pass.

Prettier --check is clean on both files; the README's §6 table re-aligned, so 16 of its 24 changed lines are whitespace. No source touched, so no suite re-run. The push re-triggered review-pr on this head and dismissed the previous approval as dismiss_stale_reviews requires, leaving the PR at 0/2 — it needs the bot's re-review plus one human approval.

Unrelated to this PR's code: the sandboxed verification run 35621014837 from yesterday's /triage is still in_progress after ~24h, and its comment is stuck at verify-state=running. Worth cancelling.

Local real-environment verification: PR #12355 @ 1b956a82

Verdict: mergeable. No production code changed, the new test row is proven load-bearing on macOS, and the trial merge into current main is clean. The central rewrite in context-cost.md holds on a real provider: the declared list stays byte-stable across a bridge discovery, the prompt-cache prefix survives, and removing a bridge half behaves asymmetrically. I found one measurable error in text this PR adds (A), which I'd fix before merging; it is a two-sentence edit. B and C are wording nits that can go to a follow-up.

The sandboxed run (35621014837) used a scripted model in a container. This run covers what its "Not covered" section left open: a real model on a real provider (prefix-cache hits reported by the provider), a real stdio MCP server, the real interactive TUI, released v0.24.1/v0.24.2 as the before/after arms, threshold > 0, all four bridge-removal seams, the version-range and commit-sha claims (full history), and a trial merge into today's main.

Setup

1 · The core claim holds on a real provider: discovery no longer breaks the prefix

tools.eager: ["read_file"], threshold: 0, prompt "create marker.txt with the file-writing tool". The real model finds the withheld write_file by itself on both builds.

• PR head: tool_search("select:write_file") → tool_call(write_file). The tools sha is e6f6413a… on all 5 requests (the same bytes as the sandbox run's scripted harness), and the request after discovery gets 9,216 cached tokens (≈95% of the previous prompt) in both runs. The file is written.
• v0.24.1: the reveal changes the tools array (66a9b78b → 22f03eaa, 4 → 5 tools), and the next request gets only 1,024 / 5,120 cached tokens across two runs. The new bullet describes exactly this: "it used to, and old advice assumes it does".
• The extra cost that remains is one round trip, which matches the new text.

2 · The new test row, on macOS and on the merge with current main

git merge-tree with main c822995d is conflict-free. On the merged tree, packages/core/src/permissions/ passes 13 files, 1,025/1,025 (this includes main's new eager-allowlist-warning.test.ts from #12451). permission-manager.ts and its test are unchanged on main since the base.

3 · Bridge-removal seams with a real MCP server: all four behave as documented

permissions.deny, tools.disabled, --exclude-tools (each removing tool_call) and tools.toolSearch.enabled: false all have the same effect. All 8 MCP tools and the ordinary on-demand built-ins (task_stop, zoom_image) are force-declared, the tools.eager-demoted write_file stays withheld, and stderr logs bridge is incomplete (tool_call not registered) … they remain registered and direct calls by name still use normal approval: … write_file. The sandbox run proved the mechanism; this also covers the "all MCP tools" scale and the three seams it did not drive.

Findings

A · Suggestion: README §2.5 and §8 item 1 (new text) predict the wrong direction for the allowlist reading.
The new text says both expected values are "地板 + 白名单内 schema，不含按需池", that the ~4.2k #10410 removed "根本到不了这两个数里", and that on ≥ 0.24.2 the reading is "略高一点 (+67)". I measured the exact §2.2 aggressive list in the real TUI, v0.24.1 vs PR head. The reading goes down by 681, not up by 67.

• /context detail shows Built-in tools going from 6.9k to 6.3k. On the first real request, the declared tools drop 15 → 13, and the provider's prompt_tokens go 15,912 → 15,231 (−681). The repo's estimator applied to the captured bodies gives exactly −681.
• Why the prediction is off: an allowlist entry admits its whole family (rule-parser.ts toolMatchesRuleToolName). read_file admits zoom_image (READ_TOOLS) and run_shell_command admits monitor. Both are on demand by default, so v0.24.1's threshold-10 preload declared them, along with the exempt task_stop. The on-demand pool was therefore not "already excluded" under these allowlists. The +67 counts the floor change only (+148 tool_call, +19 tool_search, −102 task_stop) and misses −467 monitor, −279 zoom_image.
• The same mechanism explains the task_stop 102 in the old floor reading: v0.24.1's preload declared it on every request. The §2.1 correction's "本来就不常驻" is true on ≥ 0.24.2, but not of the v0.24.1 reading it corrects.
• Suggested fix: in §2.5 and §8 item 1, say that on ≥ 0.24.2 the reading also drops by whatever on-demand tools the list admits by family (zoom_image via read_file, monitor via run_shell_command), so the direction depends on the list. Measured here: −681 for the aggressive list (real TUI) and about −0.8k for the conservative list (-p, 9.0k → 8.2k). Remove "方向…恰恰相反，会略高一点" and "别把'读数比 9,481/5,868 高几十'当成配置没生效".

B · Nit: raising threshold does not preload MCP tools at a fresh launch (context-cost.md bullet; README §0.1 MCP row).
context-cost.md now says to "raise the threshold … for ordinary deferred tools (MCP tools and the on-demand built-ins)". README §0.1 says "之前 MCP 工具只要塞得进窗口 10% 就被预加载，现在全在桥接后面". Section 2 of figure 3 shows what I measured. In every fresh launch I ran (v0.24.1 defaults and head threshold: 10, TUI and -p), the first request declared 0 of 8 MCP tools. Instead the model got "The following MCP tools became available after startup and are reachable through tool_search and tool_call." v0.24.1's first request carries the same notice ("… reachable via tool_search"). The MCP tools were preloaded only after /clear (8/8) or with QWEN_CODE_LEGACY_MCP_BLOCKING=1 (8/8). The cause is ordering: Config.initialize() calls llmClient.initialize() → startChat → preload (config.ts:4340) before it starts background MCP discovery (:4399). client.ts's own comment says late servers "stay deferred until the next session start". settings.md's "(bundled built-ins and MCP alike)" from #10410 has the same gap, so this is consistent with the existing doc and not a regression. It would help to add "at session start; MCP servers usually connect after it", and to drop or soften the §0.1 MCP row, since in the CLI v0.24.1 already kept MCP tools behind tool_search. I did not test the daemon's pooled-MCP path, where servers may already be connected when a session starts.

C · Nit (raised in the sandbox run, still open at this head): the new test comment describes an effect that does not occur.
The comment says withholding tool_call "would leave every demoted tool readable and uncallable". I deleted that arm from the compiled bundle (one chunk rewritten in an APFS clone of dist/) and ran the real model. The tools sha was still e6f6413a… (identical to head), tool_call(write_file) executed, and no warning was logged (figure 1, bottom row). ToolCallTool passes alwaysLoad=true (tool-call.ts, fourth boolean after the schema). The row is still worth keeping, but the sandbox run's suggested comment wording is accurate and mine is not needed.

Other claims checked

• Every commit sha, date and count in §0.1 checks out against full history: 70edbf47 has one parent; v0.24.2 was published at 14:12:10Z; the range has 15 non-test files; the 6 topical PRs reduce to 3 under the directory filter; fix(cli): require explicit trust for undecided workspaces #12198 touches 21 files and none in those directories; fix(core): handle simple Bash comments in permission rules #12096 is +98/−5.
• feat(core,docs): add conditional extension rules and cap context warnings #12034: with a 46 KB QWEN.md (≈13.1k tokens) the startup warning is absent on v0.24.1 and present on v0.24.2 and head, and the context is not truncated (13.1k loaded on all three).
• fix(cli): require explicit trust for undecided workspaces #12198: with security.folderTrust.enabled unset, both versions honour an undecided workspace's settings. With it set to true, head ignores them and prints "Approval mode overridden … not trusted", while v0.24.1 still trusts the workspace.
• Rollback, §0.1 "推算约 17,300": with threshold: 10, head declares v0.24.1's 27 default built-ins plus tool_call. On the same build, threshold 10 → 0 moves /context Built-in tools from 15.6k to 9.1k (−6.5k of on-demand pool here). v0.24.1's default reads 15.5k, and v0.24.2 with threshold: 10 reads 15.6k (the gap is roughly tool_call's 148). So in this environment the cross-version drop on this line comes from the preload change, and fix(cli): make /context categories add up to the provider total #12119's re-derivation barely moves it.
• §2.4 still holds with a real model: the main session declares 14 tools and a general-purpose subagent gets 17, including on-demand monitor, zoom_image and web_fetch. Under the conservative allowlist, the subagent loses the demoted tools but keeps the family-admitted on-demand ones.
• /context detail shows tool_search 394 and tool_call 148, matching the corrected §2.1 figures.

Pre-existing, not introduced here (FYI, since §0.1/§8 ask readers to paste /context detail)

• qwen -p "/context detail" prints only Command executed successfully., on v0.24.1, head and main. The detail subcommand awaits the main action but drops its returned message (contextCommand.ts on main, around line 1041). /context -d works.
• When skill is itself demoted (for example tools.eager: []), the Built-in tools category reads 0 while its per-item list sums to 542. The category subtracts the skill schema even when skill is not declared. §2.2's lists keep skill, so they are not affected.

Not covered

The daemon/ACP deployment the README was written for, including pooled MCP; the Computer Use family (not registered here); #12096's comment-splitting permission flips (read, not exercised); the README's historical figures from a different deployment; Windows/Linux (the change is docs plus one test row).

@qwen-code /triage

Doc-accuracy pass — all six findings fixed, pushed as 1df0ecfd.

@wenshao A/B/C from your local run plus the sandbox round's Findings 2/3/4. Every one was re-verified against the tree at 1b956a82 before editing; nothing was taken on faith from either report. No production code touched — the commit is +41/−41 across the same four files.

A · fixed as you prescribed (README §2.5 + §8 item 1). The offending text was there verbatim: §2.5 said 「这两个预期值都是 地板 + 白名单内 schema，不含按需池 … 读数会比上表高约 67，这是正常的，不是配置没生效」, §8 item 1 said 「方向不是"≥ 0.24.2 上更低"——恰恰相反，会略高一点」 and 「别把"读数比 9,481/5,868 高几十"当成配置没生效」. Both direction sentences are gone. §2.5 now reads:

这两个预期值算的是 地板 + 白名单内 schema（激进版 = 2,163 + (4,080 − 375)），但别把它当成"不含按需池"：白名单条目会按族放行（rule-parser.ts 的 toolMatchesRuleToolName）——read_file 带出 zoom_image（READ_TOOLS）、run_shell_command 带出 monitor，这两个默认都是按需工具，所以 v0.24.1 的 threshold-10 预加载本来就把它们（连同豁免的 task_stop）声明了出来，那份预期值里含着按需池的一部分。≥ 0.24.2 上有两股相反的力：地板从 2,163 涨到 2,230（+67，见 §2.1 的更正），同时这批按族放行的按需工具不再被预加载（实测 monitor −467、zoom_image −279）。净方向取决于白名单，不是"一定略高"：评审在真实 TUI 里用 §2.2 的激进版量到 −681（首轮声明工具 15 → 13，provider 的 prompt_tokens 15,912 → 15,231），保守版约 −0.8k（-p，9.0k → 8.2k）。所以读数比上表低几百同样正常，不是配置没生效。

§8 item 1 carries the same correction plus your −467/−279 split; it keeps +67 and the 2,230 + 3,705 = 5,935 / 9,548 arithmetic but explicitly as "只算地板这一项", and ends with 「读数比 9,481/5,868 低几百或高几十都可能是正常的」. Your third bullet is applied too: §2.1's 更正 note now says 「但"本来就不常驻"是 ≥ 0.24.2 的说法，不适用于它所更正的那份 v0.24.1 读数：旧读数里那 102 是 v0.24.1 的 threshold-10 预加载把 task_stop 每次请求都声明了出来」.

B · minimal wording only, no restructuring. context-cost.md's threshold bullet gained one sentence: "The preload also runs at session start, and MCP servers usually connect after it, so a fresh launch declares no MCP tools whatever the threshold; they reach the preload from the next session start (in the CLI, after /clear), or immediately under QWEN_CODE_LEGACY_MCP_BLOCKING=1." In README §0.1 I softened the MCP row rather than dropped it: the cells now name the ordering cause (Config.initialize() → llmClient.initialize() → startChat preload, then background discovery), record your 0/8 on v0.24.1, and move the row's real bite to the "servers already connected at session start" path — with 「daemon 的池化 MCP，未实测」 stated, since you did not test it. The 怎么尽快发现 cell now warns that MCP reading 0 is also v0.24.1's CLI behaviour, so it is not by itself a regression signal. Reason for softening instead of dropping: this README is written for the daemon/ACP deployment, where the row still says something true. Say the word and it goes. settings.md untouched — outside this diff.

C · comment reworded, test row unchanged. Applied the sandbox's suggested wording verbatim, since you judged it accurate. The two consumers it names were checked at this head rather than assumed: followup/speculation.ts:338 toolRegistry.isPermissionDeferred?.(name) and skills/workflow-authoring-skill.ts:211 isToolDeferredBehindToolSearch.

Sandbox Finding 2 · fixed. Verified independently: this branch's own prompts.test.ts still reads saves about 1.1k characters / 1,104 characters (~276 tokens) / <1_400, while 733f58b6 — the main this PR merges into — reads saves about 1.4k characters / 1,421 characters (~355 tokens) with the monitor bullet gated too / <1_500. The PR does not touch that file, so the merged tree carries 1,421 and the deferral would have landed the stale number. Both re-emitted rows now say 1,421 字符 ≈ 355 token: plan-doc §10's #12032 row (with the 1,104 = subagent + codebase, 317 = monitor split spelled out) and README §0.1's §5 row. The PR body's deferral sentence is rewritten in both languages. The two other copies the sandbox named (docs/verification/resident-tool-prompt-assembly/README.md:40, docs/design/2026-09-18-resident-tool-prompt-assembly{,.zh-CN}.md:123) are outside this diff and stay out, as the sandbox itself scoped them.

Sandbox Finding 3 · body fixed, doc untouched. The diff does rewrite §10 in place and the banner does say 「已就地改写」, so the body was the wrong side of the contradiction. Both Risk & Scope bullets now state that §10 is rewritten in place and that no §10 follow-up is left to file.

Sandbox Finding 4 · fixed by adopting the table's own symbol convention. Re-verified all four against main: tools/tools.ts:233-240 holds version?: string; } + the ToolBuilder docblock; 241-246 holds TResult extends ToolResult, / > {; config/config.ts:6969-6977 holds getProjectRoot() / getCwd(); permission-manager.ts:848-866 lands on isExemptFromEagerAllowList (declared at main:846) — the function this PR's new test row targets, exactly as the sandbox said. They now cite DeclarativeTool 构造参数 shouldDefer / alwaysLoad, getVisibleTools()（读构造期存入的 visibleTools）, and getToolRegistrationStatus()（deny 分支 return 'disabled'）, matching the rows that already used symbols. The three ranges the sandbox confirmed accurate (tool-registry.ts:384-419, :289-321, client.ts:1746-1774) are left alone to keep the diff minimal; if you want the whole table symbol-only, that is a one-line follow-up.

Local verification. npx vitest run src/permissions/permission-manager.test.ts → 514/514, run twice (before and after the commit). npx prettier --check on all four changed files → clean (the two markdown files needed --write for table realignment; done, then re-checked). npm run typecheck in packages/core → 73 errors, 0 in any file I touched; 51 are TS2307 cannot find module (this worktree's node_modules is missing ajv, ignore, quickjs, grpc types) and the rest are knock-on implicit-any in src/telemetry/* and src/code-mode/host.ts. Same reason npm run build cannot complete here. Environment noise, not a regression from a comment-and-markdown commit.

Approval. This push voided @wenshao's approve under the repo's stale-approval dismissal — expected, since A was asked for before merging. Review re-requested.

Review details: Test +7: tool_call added to exempt array; isExemptFromEagerAllowList verified at head. context-cost.md: bridge + fallback docs verified against resolveDeferredToolsForReminder. Plans doc + Verification README: v0.24.2 corrections, §6 obsolescence notice. No blocking findings.

发布记账（本 PR 已于 2026-09-22 15:45Z 合并为 8af8b9df）

已给本 PR 补上 type/documentation 标签，因为标题的 conventional type 会把它归错段：

scripts/generate-release-notes.js 的 classifyChange() 先看标签，再用标题 type 兜底查 TYPE_CATEGORIES。本 PR 合并时标签为空、标题是 fix(core,docs): → 兜底命中 fix → Bug Fixes。而 compactEntry() 是把这个算好的 category 直接交给模型去组装 curated release notes 的，模型并不重新判段。实际 diff 是 3 篇文档 + 1 个测试文件（packages/core/src/permissions/permission-manager.test.ts，+7/−0），没有任何生产代码改动，归进 Bug Fixes 会让 CHANGELOG.md 出现一条并不存在的修复。type/documentation 在 classifyChange() 里的优先级高于 type 兜底，且标签在 PR 合并后依然有效，所以下次切版（v0.24.5）这一条会落到 Documentation 段。

标题不再改：squash 提交信息已经定死在 main 上，改 PR 标题不会影响它。

另一件同类的事已经发生，且还没解决：#10410（70edbf47）随 v0.24.2 发布（git tag --contains 70edbf475e 含 v0.24.2；该 release 09-20 14:12Z 列出 feat(core): preserve prompt cache for deferred tools），它把 tools.toolSearch.threshold 的默认值从 10 改成 0——一个默认行为变更。但 v0.24.2 的 release body 和 CHANGELOG.md 的 0.24.2 段写的都是「No known breaking changes.」。

机制与本 PR 正文预警的相同，只是判定点不是 ! 标记：classifyChange() 进 Breaking Changes 的条件是带 breaking-change 标签、或标题匹配 /^\w+(?:\([^)]*\))?!:/，#10410 两者都没有（标签为空，标题无 !）。

现在给 #10410 补标签已经没有作用：v0.24.2 的 body 早已发布，且该 PR 不会再落进后续版本的提交区间。唯一的补救是编辑已发布的 v0.24.2 release body 加一行披露，再跑 npm run changelog 重生成 CHANGELOG.md。这属于修改已发布产物并向 main 推送，没有在这条备注里顺手做掉。