Skip to content

fix: passthrough anthropic requests carrying a global-scope system block (#2648) - #2650

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-10_anthropic-global-scope-passthrough
Oct 10, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-10_anthropic-global-scope-passthrough

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2648

What & why

Claude Desktop's Code tab reaches bili through cert-MITM in proxy mode (no native lane → no x-bili-plugin). Its auxiliary side calls — notification / title / classification classifiers — pin their system blocks to cache_control.scope:"global". Anthropic renders tools before system, so the six ACP tools bili injects (narrower scope) land ahead of a global block → upstream rejects with:

scope:global … found after content with a narrower cache scope

This is class 1 of the two 400 families reported in #2648. Class 2 (thread_fingerprint_mismatch) is a separate mechanism (bili has no Threads awareness) and is deliberately out of scope here — see "Pending owner decision" below.

Fix (P1)

In src/server/prepare-anthropic.ts, forward the request untouched when any system block carries cache_control.scope:"global" — no ACP tools, no Compression Philosophy block, no nudge, no cache marks. This mirrors the existing auto-mode classifier bypass (#353): the gate sits at the decision point (removes the tool-injection producer), not by filtering payload in transit, so it holds if the same root cause resurfaces in another shape.

The trigger is keyed on the invariant actually being violated (a global-scope system block), not on "no tools": a tool-less conversation can still grow large and be compressed, so gating soft compression off on tool absence would be wrong — and it breaks the existing compress round-trip regression test. Healthy main turns use ephemeral/unscoped system and keep full compression; only genuine global-scope side calls are stood down for. The preflight hard-limit backstop still runs afterward (same code path #353 takes).

Regression test

tests/e2e-anthropic.test.ts: a global-scope request gains no ACP tools / compress prompt and keeps its breakpoint verbatim; the existing tool-less round-trip test still exercises injection (guards against over-broadening the gate). Targeted suite 6/6 pass; typecheck clean. Full suite left to CI.

Behavior-change disclosure (owner policy 2026-09-22)

  • Old: proxy mode injected ACP tools + Compression Philosophy into every anthropic request, including global-scope side calls → upstream 400 for those requests.
  • New: requests whose system contains a scope:"global" block are forwarded verbatim (no injection). No behavior change for any request without a global-scope system block — the overwhelming common case, including all healthy CC main-loop turns.
  • Why: those two cases are mutually exclusive — you cannot place narrower-scope injected content ahead of a global block without 400ing, so standing down is the only correct choice there.

Structured eight-question

  1. 是什么问题:宿主经 cert-MITM 接入后,bili 向「不该被注入」的辅助请求(side call)注入非 global 作用域的 ACP 工具,触发上游 400。
  2. 什么原因:注入是无条件的(proxy 模式恒开);Anthropic 把 tools 渲染在 system 之前,当宿主 system 块带 scope:"global" 时,注入的非 global 工具成为更窄前缀 → 400。
  3. 影响范围与严重程度:仅影响走 cert-MITM 的 Claude Desktop(及任何用 global-scope system 的 anthropic 宿主);主对话不受影响,受拒的是通知/标题/分类等辅助请求 → 特定条件下辅助功能静默失效,非完全不可用。
  4. 怎么修复的:在决策点(注入之前)对「system 含 global 块」的请求整段 passthrough,移除工具注入这个生产者;沿用 Auto mode classifier requires confirmation for this command. 3 consecutive actions were blocked. #353 分类器旁路模式。
  5. 是否有回归问题:只新增一条 early-return;无 global 块的请求(含所有健康主循环轮次)行为字节级不变;preflight 硬上限保护在其后照常跑。定向测试 6/6、typecheck 干净。
  6. 是否破坏缓存:不涉及既有失效策略;passthrough 分支不打 cache mark、不进会话折叠空间,客户端自带的 global 断点原样保留。
  7. 是否改了设计方向:无转向;仅在既有旁路机制上加一条同型闸门。
  8. 是否引入新配置:无新增 config/env/flag(纯行为判定)。

Pending owner decision (class 2 — NOT in this PR)

thread_fingerprint_mismatch (class 2) stems from bili having no Threads awareness: it re-injects on every continue, and when the client omits tools/system on a continue (relying on server inheritance) the fingerprint mismatches. Fixing it needs a Thread lifecycle model — three options (A: stand down entirely on the thread: field; B: per-thread consistent canonical injection; C: replay-as-create on mismatch). This is a wire/message-shape change → human-gated (§7.4), so it stays out of this bugfix pending your call. I recommend shipping A now + filing B/C as a dedicated follow-up issue.

Note (docs, user-reported — not independently verified here)

#2648 also reports that cert-MITM routing now works on Claude Desktop 2.31226.1 / CC 2.1.295 (host sets NODE_USE_ENV_PROXY=1; settings-env HTTPS_PROXY honored), which supersedes #2290's zero-CONNECT conclusion for that version. Since this is the reporter's observation and I can't reproduce Desktop here, I have not promoted it into CONFIGURATION.md / README yet — flagging for your confirmation before I touch the docs surface.

…ock (#2648)

Claude Desktop's Code tab routes through bili via cert-MITM in proxy mode. Its
notification / title / classification side calls pin their system blocks to
cache_control.scope:"global". Anthropic renders tools BEFORE system, so the six
ACP tools bili injects (narrower scope) land ahead of a global block and the
request 400s upstream ("scope:global … found after content with a narrower cache
scope").

Key the stand-down on the invariant actually being violated — a global-scope
system block — rather than on "no tools": a tool-less conversation can still grow
large and be compressed, so gating soft-compression off on tool absence would be
wrong (and breaks the compress round-trip regression test). Healthy main turns
use ephemeral/unscoped system and keep full compression; only genuine global-scope
side calls are forwarded untouched, mirroring the auto-mode classifier bypass (#353).

Regression test pins the boundary: a global-scope request gains no ACP tools /
compress prompt and keeps its breakpoint verbatim, while the existing tool-less
round-trip test still exercises injection (guards against over-broadening).
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-10_anthropic-global-scope-passthrough (2084f06)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2865-pr.2650.44c6aff

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2650.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

PR #2650 review 完成。在 pr-2650 head(2084f068c,base = 当前 master,0 commits behind)上逐段读了改动及其触碰路径的既有行为(prepare-anthropic 全路径、inject、handle.ts prepare→preflight 链、preflightCompressIfNeeded/preflightCompress)。结论:可合——根因修在决策点、回归面逐项核过、CI 全绿(除一个 windows test job 写作时仍在跑,其余含 ubuntu 22/24、docs-sync、各 guard 均 success)。按 §7.4 wire/message-shape 变更归 human merge。

查重:open+closed 检索 scope:global / thread_fingerprint —— 无既有或并行工作;#353 是模式先例不是重复项。判定:非重复。

结构化八问

  1. 是什么问题:Claude Desktop Code tab 经 cert-MITM 走 proxy mode,其辅助 side call(通知/标题/分类 classifier)不带 tools、system 块钉 cache_control.scope:"global";bili 无条件注入 ACP 工具 + Compression Philosophy prompt → Anthropic 渲染序 tools 先于 system → 注入的窄 scope 内容落在 global 块之前 → 上游 400,宿主辅助功能静默失效。

  2. 什么原因导致的:prepareAnthropic 的注入决策缺少对「被违反不变量」的 guard——不管宿主的 cross-prompt 缓存布局如何,每个请求都注入。根因层 = 决策点缺 gate,不是 payload 本身有问题。修法因此是加 gate(疏),不是转发时过滤/改写 payload(堵)。

  3. 影响范围与严重程度:所有用 prompt-caching-scope beta 且钉 global 断点的 proxy-mode Anthropic 宿主(已观察到 Desktop 2.31226.1 / CC 2.1.295)。side call 硬失败(400)→ 特定宿主配置下的部分功能损失;主循环 turn(ephemeral/unscoped system)不受影响,非全面故障。

  4. 怎么修复的:决策点 gate(src/server/prepare-anthropic.ts:66-69):proxy mode 下任一 system 块带 scope:"global" 即整体 passthrough(early return,形状与 Auto mode classifier requires confirmation for this command. 3 consecutive actions were blocked. #353 classifier bypass 完全一致),跳过 anchor/marker strip/kernel round-trip/cache marks/injectSystem/injectTool/nudge。predicate 键在不变量本身(任一 global 块 ⇒ 注入必违例)而非「无 tools」——tool-less 普通会话仍可压缩,现有 tool-less round-trip 测试(tests/e2e-anthropic.test.ts:301)继续钉住注入行为,防 gate 过宽。hasGlobalScopeSystem(:388)只认数组 system(string 不能带 cc,正确);任一 global 块成立即触发是对的,因为注入工具渲染在所有 system 块之前。

  5. 是否有回归问题:无。触碰路径既有行为逐项清点:

  6. 是否破坏缓存:否,方向相反——移除了 bili 在这些请求上引入的缓存扰动;client 自身断点 byte-exact 过线(测试 :406 断言 scope:"global" 原样存活)。受跟踪会话的前缀缓存锚点不受影响。

  7. 是否改了设计方向:否——沿用既有 bypass-lane 模式(Auto mode classifier requires confirmation for this command. 3 consecutive actions were blocked. #353)在同一决策点扩展。class 2(thread_fingerprint_mismatch)刻意排除:不同机制/失败域,待你拍板(见下)。

  8. 是否引入新配置:无。

测试有效性(④)

新 e2e 测试有牙:按名断言注入工具缺席、compress prompt 缺席、global 断点 verbatim 存活、SSE 完整到 client。过宽防护由既有 tool-less round-trip(:301)+ #353(:333)+ #1092 salvage(:415)覆盖。CI:head commit 全部 check success,仅 test (windows-latest, 24) 写作时 in_progress(无红)。

diff 整洁度(⑤)

2 文件 +61/-0(src 18 / test 43),每行都服务于本 PR 目的;base 新鲜、无其他 open PR 同文件竞争。干净。

发现处置

两件待你拍板的事(PR 正文自列)

  1. class 2(thread_fingerprint_mismatch):支持你的分阶段方案——本 PR 先合(严格改进),然后尽快定 A/B/C。需要把权衡摆明:只合本 PR 后,CC Desktop 主会话 turn 本身是 thread 请求,continue 仍会 400(首 turn 正常、后续 turn 挂),直到 class 2 落地。选项 A(thread 字段整体 stand down)立即止血,但 thread 流量变成纯 proxy(该宿主失去压缩直到 B 落地);B(per-thread 一致的 canonical 注入)恢复压缩、工作量更大;C 是 mismatch 后的恢复阀。我的建议:A 做止血 + B/C 单独立项设计。拍板后我再立 class 2 的 issue(现在不立,避免平台唤醒 agent 去撞一个还没定方向的设计题)。
  2. docs note(cert-MITM 在 Desktop 2.31226.1 / CC 2.1.295 可用,NODE_USE_ENV_PROXY=1):同意不进本 PR(diff 收敛)。落地时措辞带版本限定(「as of …」),目前仍是单一用户报告数据点。

判定:可合(human merge;F1/#2653 不阻塞,class 2 决策独立跟进)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

补充:head 2084f068c 的 CI 已全部跑完——26/26 check runs success(含此前仍在跑的 test (windows-latest, 24))。无红项,review 结论不变:可合。

@ranxianglei
ranxianglei merged commit df40d87 into master Oct 10, 2026
26 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.233-master.df40d87 (rolling master tag).

npm install -g billion-context@0.0.233-master.df40d87  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

@github-actions github-actions Bot mentioned this pull request Oct 11, 2026
ranxianglei pushed a commit that referenced this pull request Oct 12, 2026
The summary line still stated the over-strict reading (#2650 era): any
unmarked or narrower-scope content ahead of a global breakpoint is a 400.
#2884's traffic evidence contradicts it — the Claude Code main loop carries
56 unmarked tools + unmarked system[0..1] ahead of its global breakpoint on
system[2] and is accepted upstream. Restate the constraint at the observed
boundary: the 400 trigger is tools present + global on system[0] (upstream's
own 'not a true prefix when tools are present' note); unmarked predecessors
of a deeper global are accepted. Provenance already carried the refinement;
no gate, fake, or golden changed.
ranxianglei pushed a commit that referenced this pull request Oct 12, 2026
…nd-down (#2884)

#2650 whole-request passthrough fired on ANY system block carrying
cache_control.scope:"global". That stood down Claude Code main-conversation
requests wholesale -- their main loop carries unmarked tools plus a global
breakpoint mid-system that upstream accepts WITH extra unmarked tools ahead --
silently disabling compression there (no inject / nudge / fold). The decision
was also evaluated per request, so one threads create/continue pair could mix
raw and injected forwards -> upstream 400 thread_fingerprint_mismatch.

Narrow the gate to the shapes WC-016 actually rejects: stand down only when the
request carries NO tools OR the global breakpoint sits on system[0]. Make it
thread-granular -- computed at the thread create and inherited by every continue
through session.metadata -- so a single upstream thread never mixes raw and
injected forwards.

Regression tests: CC main-convo shape keeps compress injection; thread-granular
stand-down and inject inheritance across truncated continues.
ranxianglei pushed a commit that referenced this pull request Oct 12, 2026
The #2650 repair line in WC-016's provenance still described the gate as
"whole-request passthrough when any SYSTEM block pins scope:global". That
gate was narrowed in the preceding commit (#2884) to globalScopeRequiresStandDown
(NO tools OR global-on-system[0]) and made thread-granular. Add a short
refinement note so the ledger documents the live gate accurately. No wire
constraint changed; goldens do not pin provenance text.
@ranxianglei
ranxianglei deleted the 2026-10-10_anthropic-global-scope-passthrough branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant