[native] claude: three-mode alignment (proxy / launcher / native plugin) + runtime-info

[ranxianglei]

Goal

Bring claude to full three-mode alignment like pi / opencode / dsh already have:

1. Mode 1 — proxy (URL prefix, exists today via launcher)
2. Mode 2 — launcher (bili claude — exists)
3. Mode 3 — native plugin (bili plugin install claude — the gap): plugin loaded by the CLIENT itself, spawns/attaches its own proxy, rewrites model traffic, registers ACP tools natively, stamps plugin-mode headers, implements the runtime-info protocol.

Feasibility pre-assessment

hooks/MCP only
LOW-MEDIUM — Claude Code exposes hooks (shell commands), MCP, skills, but no in-process wire-interception API is documented. If no wire hook exists, full native mode is structurally out; document the best achievable posture (e.g. native TOOLS via MCP + wire via proxy) and stop there — do NOT ship a hybrid without discussing the design in this issue first.

Reference implementations (read these first)

• src/agent/dsh-native.ts — cleanest full native (dynamic service inject, fetch patch, header gating, runtime-info stamps). PR feat: dsh native mode — full plugin via bili plugin install dsh + upgraded launcher (#941) #942 / issue dsh: full plugin/native mode (mode 3) + upgrade launcher to plugin-mode compression (mode 2) #941.
• src/agent/opencode-native.ts (v1) + src/agent/opencode-v2.ts — config/catalog-based window+output maps, legacy-lane routing. PRs feat: OpenCode 1.x native support — V1 .server() hooks on the standard install path #919/feat: v1 legacy-lane routing — opencode-acp old sessions keep working, new sessions go to bili (#920) #921.
• src/agent/pi.ts / src/agent/pi-native.ts — header stamping discipline (toolsReady gate).
• Installer: src/plugin-install.ts (bili plugin install <client>); launcher wiring: src/launcher.ts.
• Runtime-info protocol ([native] runtime-info protocol: plugins report real model config (model / contextWindow / maxOutput) to the proxy #955, PR feat: runtime-info protocol — plugins report real model config to the proxy (#955) #956): per-request headers x-bili-plugin-context-window / x-bili-plugin-max-output / x-bili-plugin-model (gated on x-bili-plugin) + bootstrap POST /__bili/plugin/runtime-info. README "Runtime-info protocol" table is the contract — follow it exactly.

Requirements if feasible

• No launcher, no env vars, no fixed port for the end user; opt-out env BILI_NATIVE_CLAUDE=0
• Plugin-mode gating: stamp x-bili-plugin ONLY after native tools are registered (round 1 rides wire mode)
• Parent-pid watchdog proxy teardown; attach to a healthy proxy when present
• Runtime-info stamps (model + contextWindow + maxOutput whenever the client exposes them)
• npm run typecheck + npm test + npm run build green; new tests for the plugin module (see tests/dsh-native.test.ts for the harness style)
• README (en + zh) client table + install section updated

If NOT feasible

Post the evidence (what extension points exist, why wire interception / native tools are impossible) and close as wontfix — a documented no is a deliverable too.

For ework

This issue is directly implementable. Follow the dsh playbook; ask in this thread before inventing new protocol surface. PR must reference this issue (Fixes #N).

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Feasibility verdict: feasible as the documented hybrid (native TOOLS via MCP + wire via ANTHROPIC_BASE_URL rewrite + hook bootstrap) — NOT as full in-process native. This matches the posture your pre-assessment anticipated. Design proposal below; asking for go-ahead before cutting a branch, per the issue's "do NOT ship a hybrid without discussing the design first".

Evidence — Claude Code extension points (official docs, verified today)

Extension point	Nature	Wire-interception possible?
Hooks (SessionStart, PreCompact, PreModelSwitch, …)	shell subprocesses, JSON on stdin	No — separate process, runs after env load
MCP servers	subprocess (stdio/HTTP), tools/resources/prompts	No — but carries native TOOLS + gets CLAUDE_CODE_SESSION_ID env (verified against claude 2.1.227 in our mcp.ts)
Plugins / skills / commands	config + markdown packaging (plugins bundle hooks/MCP/commands)	No — packaging layer, still subprocess underneath
settings.json env block	static text, read at startup, applies "no matter how claude was launched"	No dynamic URL injection

There is no in-process hook API — no way to run JS inside the claude process, so the dsh --patch / opencode-plugin / pi-extension pattern (fetch patch in client memory) is structurally impossible. But nothing functional is lost: ANTHROPIC_BASE_URL gives the proxy full request/response visibility (every body, every SSE stream) — exactly what launcher mode already proves works (src/launcher.ts:313-329 routes claude this way because undici ignores HTTPS_PROXY). Compression quality is identical to launcher mode; only "in-process" is absent.

What the proxy side ALREADY has for claude (zero new protocol surface needed for mode detection)

• Plugin-mode gating without header stamping: claude sends x-claude-code-session-id on every model request (= the CLAUDE_CODE_SESSION_ID its MCP children receive). Our MCP shim registers that conversation id at initialize; the proxy's consumePluginRegisterFor() (server.ts:1242-1253) flips the matching session to plugin mode — race-free, sticky, upgrade-only. This is exactly the feat: launcher-first UX — native-plugin experience with zero persistent host config (plugin-in-launcher, 内外呼应) #162/用bili omp 启动omp之后, /acp命令不能正确执行. #268 launcher mechanism, production-proven. Round 1 rides wire mode if the shim isn't up yet — the pi toolsReady-gating semantics, achieved structurally instead of via headers.
• MCP shim (dist/mcp.js, src/mcp.ts): manifest-driven native tools (compress/decompress/search_context/acp_status) forwarded to /__bili/plugin/tool. Exists today as the companion install.
• ANTHROPIC_CUSTOM_HEADERS (v2.1.227+) could stamp x-bili-plugin headers, but values are static — they can't gate on tool registration — so identity-register is the correct channel. Rejected deliberately.
• Auto-compaction kill switch, verified in claude source: isAutoCompactEnabled() honors DISABLE_AUTO_COMPACT=1 (auto only; manual /compact survives) and DISABLE_COMPACT=1 (both), both settable via the settings env block. In plugin mode bili owns compression — a second compaction engine rewriting history mid-flight is exactly what pi/dsh/opencode all avoid (dsh: compaction-basic auto:false; opencode v2: native compaction auto-disabled).

Proposed design (all pieces exist except ~2 new modules)

1. Installer (bili plugin install claude, extends src/plugin-install.ts): writes a managed block into ~/.claude/settings.json (parse-state guarded, .bili-bak snapshot, never clobbers user keys — §7.3):
   • env.ANTHROPIC_BASE_URL = http://127.0.0.1:<STABLE_PORT>/bili/https://api.anthropic.com
   • env.DISABLE_AUTO_COMPACT = "1"
   • hooks.SessionStart → node <dist>/claude-native-bootstrap.js
   • mcpServers.bili (stdio shim — same registration path the companion install uses)
2. Bootstrap script (new dist/claude-native-bootstrap.js, ~100 lines): SessionStart hook = child of claude → ensureProxyRunning on <STABLE_PORT> (attach if a healthy proxy is already listening there, else spawn detached with parent-pid watchdog = claude's pid), health-probe loop before exiting, so the first model request can never race the proxy. markNativeHost("claude") coexistence marker.
3. MCP shim: existing dist/mcp.js + idempotent ensureProxyRunning fallback inside the shim (MCP connect order vs SessionStart hook is unspecified; both converge on the same port + instance file, single-flighted).
4. Runtime-info: claude exposes none of model/contextWindow/maxOutput to any extension point (hook input is session id/transcript/cwd/source; MCP gets no model context). Per the contract's "whenever the client exposes them", there is nothing to stamp — the proxy derives model from the request body, window via anthropic-beta negotiation > registry, output budget from max_tokens. My recommendation: no runtime-info POST from claude; document the exposure gap. (Keeps this work independent of PR feat: runtime-info protocol — plugins report real model config to the proxy (#955) #956, currently open/CI-clean/unmerged.)
5. Coexistence: bili claude (launcher) detects a native install and passes --settings '{"env":{"ANTHROPIC_BASE_URL":"<ephemeral>"}}' — CLI settings outrank user settings (documented precedence), so the launcher's ephemeral-port proxy wins over the static URL. Plain bili start --port <STABLE_PORT> is naturally an attach target.
6. Opt-out BILI_NATIVE_CLAUDE=0: installer refuses; hook + shim no-op. To keep the now-static URL from dead-ending the user, the opted-out hook spawns a passthrough-mode proxy on <STABLE_PORT> (existing verbatim-forward feature, zero new surface) — compression off, claude fully functional.

Open questions (my recommendations in bold)

• Q1 — Stable port. Unavoidable: the settings env value is static text read at startup, and hooks run after env load — no dynamic address injection point exists. User never sees or configures it (installer-managed constant, e.g. 48787, overridable in bili config, documented as reserved). Acceptable reading of "no fixed port for the end user"?
• Q2 — Opt-out via passthrough proxy (instead of leaving the URL dead): OK?
• Q3 — DISABLE_AUTO_COMPACT=1 baked into the managed block: strongly recommend yes (plugin mode correctness), manual /compact preserved.
• Q4 — Sequencing vs PR feat: runtime-info protocol — plugins report real model config to the proxy (#955) #956: build on current master with zero runtime-info dependency (recommended above) — fine?
• Q5 — Packaging: v1 = raw managed settings block (recommended); formal Claude Code plugin/marketplace packaging later as polish.

Test plan (if approved): new tests/claude-native.test.ts in the dsh-native harness style (bootstrap attach/spawn/watchdog, opt-out passthrough, shim convergence, installer block round-trip incl. malformed-settings rejection) + E2E note exercising real claude through the installed posture. README en+zh client table + install section updated.

中文摘要：结论是可行，但只能做到「文档化混合模式」——Claude Code 没有进程内扩展点（hooks/MCP 都是子进程），无法像 dsh/opencode/pi 那样在客户端内存里打补丁；不过 ANTHROPIC_BASE_URL 转发已提供完整流量可见性（launcher 模式已验证），插件模式门控可复用现成的 x-claude-code-session-id 身份注册通道（#162/#268），无需新协议面。方案核心：安装器写受管 settings 块（固定回环端口 + 禁用自动压缩）+ SessionStart hook 拉起带看门狗的代理 + 现有 MCP shim 提供原生工具。请确认上面 Q1–Q5（尤其固定端口和 passthrough 退出机制）后我即开工。

[ranxianglei]

Q1–Q5 全部按推荐拍板：Q1 固定端口 48787（安装器托管常量、bili config 可覆盖、README 标注 reserved）；Q2 opt-out 时 hook 拉起 passthrough 模式代理；Q3 DISABLE_AUTO_COMPACT=1 写进受管块（手动 /compact 保留）；Q4 零 runtime-info 依赖（claude 无暴露面，不 POST，文档记录 gap）；Q5 v1 = 原生受管 settings 块，plugin/marketplace 打包后续 polish。

⚠️ 本 issue 由 Owner 侧 Agent 亲自实现（ework 不要认领，避免撞车）。按上述混合方案做：安装器受管块 + SessionStart hook bootstrap（attach/spawn + parent-pid watchdog）+ 现有 MCP shim 身份注册做插件模式门控。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到，Q1–Q5 全部按拍板执行口径记录在案（48787 / passthrough opt-out / DISABLE_AUTO_COMPACT 进受管块 / 零 runtime-info 依赖 / v1 原生受管块）。ework 不认领本 issue：不开分支、不写码、不提 PR，避免与 Owner 侧 Agent 撞车。

交接给实现方的几条补充查证结论（均已在调研中核实，不在上一条设计回复正文里的）：

1. 端口 48787 已验证无冲突：bili 默认端口是 8787（src/config.ts:455，ACP_PORT ?? PORT ?? fileConfig.port ?? 8787），代码库内无任何占用 48787 的常量。
2. launcher 冲突修复的机制细节：claude 的 settings env 块在启动时替换继承的 shell/子进程环境值（官方文档原文确认）——所以一旦用户装了 native，bili claude 的子进程 env 里的临时端口 ANTHROPIC_BASE_URL 会被受管块的 48787 静默覆盖，launcher 模式直接失效。修复必须走 CLI --settings '{"env":{"ANTHROPIC_BASE_URL":"<ephemeral>"}}'（CLI 层优先级高于 user settings，文档 precedence 表确认）。
3. DISABLE_AUTO_COMPACT 语义已源码级验证（restored-src autoCompact.ts isAutoCompactEnabled()）：DISABLE_COMPACT 关全部；DISABLE_AUTO_COMPACT 只关自动、手动 /compact 保留；两者均可经 settings env 注入。与 Q3 拍板一致。
4. watchdog 接线点：ensureProxyRunning 导出在 src/launcher.ts:2040；hook 脚本里 claude 的 pid = process.ppid（hook 是 claude 的直接子进程）。实现时需确认现有 attach/spawn 支持"任意 watch-pid"而非仅直接子进程语义，必要时加一个参数即可。
5. ANTHROPIC_BASE_URL 改写的两个已知副作用（建议 README 注明）：非 first-party host 下 MCP tool search 默认禁用（我们只注册 4 个工具，无影响）；Remote Control 在非 api.anthropic.com host 下禁用（v2.1.196+，属预期行为）。
6. PR feat: runtime-info protocol — plugins report real model config to the proxy (#955) #956（runtime-info）目前 open / CI clean / 未合并——按 Q4 零依赖，本实现不需要等它；若日后想补 presence POST，届时 rebase 即可。

Owner 侧 Agent 提 PR 后我可以帮忙做一轮 review（diff 整洁度 + 双压缩模式推演 + 测试核对），需要时说一声即可。

中文摘要：确认 Q1–Q5 拍板并承诺不认领实现；补充 6 条已核实的实现细节（端口无冲突、launcher 必须用 --settings 覆盖否则被受管块静默劫持、DISABLE_AUTO_COMPACT 源码验证、watchdog 接线点、BASE_URL 副作用、#956 状态），供 Owner 侧 Agent 直接使用。

[ranxianglei]

Implemented in #979 ( Fixes #964 ).

Summary of what shipped:

1. Installer (bili plugin install claude): managed block in ~/.claude/settings.json — env.ANTHROPIC_BASE_URL pinned to a stable loopback /bili/ URL, DISABLE_AUTO_COMPACT=1, SessionStart hook — plus the user-scope MCP shell pinned to the same stable port. Pure JSON merge/strip, .bili-bak snapshot, foreign keys untouched; remove restores exactly. Port: BILI_CLAUDE_NATIVE_PORT > claude.nativePort > 48787.
2. SessionStart hook (dist/claude-native-bootstrap.js): before claude's first model request, attaches to a healthy proxy on the stable port or spawns one whose watchdog tracks claude's own pid — the proxy lives and dies with the session. Never fails claude. BILI_NATIVE_CLAUDE=0 → passthrough proxy (compression off) so claude stays functional.
3. bili claude coexistence: the launcher overrides the static URL with its ephemeral proxy; the hook stays dormant.
4. Bonus: claude status row never throws on a broken .claude.json (fix(plugin-install): non-object mcpServers in .claude.json crashes plugin remove/status (same class as #836) #839 hardening).

Pre-flight: typecheck ✅, 1933 tests pass ✅, build ✅. New 17-test suite incl. a real-dist e2e (hook actually brings up a proxy, second run attaches).

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

Reviewed #979 end to end (full diff read, code audited against the approved hybrid design, gates re-run on the rebased head). Verdict: implementation matches the design, no blocking issues found. Details below. One collision incident disclosed in §3 — please skim it.

1. The CI failure — root cause confirmed & resolved

All four matrix legs failed because ci.yml runs npm test before npm run build, while the new hook e2e exercises the built artifact (dist/claude-native-bootstrap.js) and hard-asserts its existence. Reproduced locally exactly: without dist/, 1/17 fails with dist script missing — run npm run build; with dist/, all 17 pass. Your pre-flight was green because you built first.

Your follow-up commit (test(#964): claude hook e2e builds dist on demand + hermetic TMPDIR) is the right fix — it keeps the shared CI step order untouched and makes the test self-sufficient (on-demand tsup when dist/ is absent + pins the child's TMPDIR so the spawned proxy's <tmpdir>/bili-proxy-<port>.log lands in the hermetic sandbox). Verified by simulating the exact CI order locally on the final head (no pre-build): typecheck ✅ → 1933 pass / 0 fail / 2 skip ✅ → build ✅, with the e2e building dist on demand and passing. (The log path itself is cross-platform safe: src/launcher.ts:2110 uses os.tmpdir().)

2. What I verified in the code audit

• Bootstrap planner (planClaudeNativeBootstrap): pure, exported, fully unit-tested; exit/passthrough/start decision order correct; catch-all guarantees the hook never fails claude (always exit 0); self-spawn guard prevents re-exec'ing the hook as the proxy entry.
• Managed block (applyClaudeManagedBlock): pure JSON merge/strip; foreign keys never touched (incl. foreign DISABLE_AUTO_COMPACT values — reported, not clobbered); SessionStart append is idempotent; .bili-bak snapshot + exact restore on remove; partial-state failure messages are accurate (block written vs MCP registered).
• Coexistence: bili claude overrides via both env and --settings '{"env":{"ANTHROPIC_BASE_URL":…}}' — the --settings belt-and-braces is correct per Claude Code's documented settings precedence (settings env replaces inherited process env; CLI --settings outranks user settings).
• Plugin-mode gating: rides the existing x-claude-code-session-id identity registration (mcp.ts initialize → register) — no new protocol surface invented, per the issue constraint.
• Tests: deterministic port via listen(0) (freePort()), sandboxed CLAUDE_CONFIG_DIR, fake claude CLI, real-dist e2e with attach-on-second-run assertion + cleanup sweep. Solid harness, consistent with tests/dsh-native.test.ts style.
• Scope clean, Fixes #964 present, no version touch, no load-bearing infra touched.

3. ⚠️ Collision incident (disclosure)

While preparing review fixes I force-pushed the branch without fetching immediately beforehand — the push clobbered your test(#964) commit (0a42f2e), which had landed between my fetch and my push. I caught this immediately after (git reported the overwritten tip), recovered the commit from the local object store, and rebuilt the branch as: current master → your feat commit (byte-identical tree) → your test-fix commit replayed verbatim (content identical; sha differs only by committer metadata) → my docs commit. Nothing of yours is lost; the branch is strictly master + your two commits + docs. Lesson taken: fetch-then-push every time.

4. Fix I applied directly on the branch (docs)

The issue requires "README (en + zh)", but the PR only added the en notes bullet. Added (commit docs: claude row in en/zh client tables + zh native-posture note):

• claude row in both client tables (en + zh);
• zh: the stale bullet claiming "claude / codex / omp … 不属于原生模式" is now factually wrong — corrected to codex / omp only, and mirrored the full en note into the zh notes (translated via the local translator for style consistency).

I initially also reordered ci.yml (build before test), but since your test-side fix supersedes it, I dropped that hunk to keep shared CI untouched — your approach wins.

5. Two non-blocking limitations (for the record; README note optional, your call)

1. Multi-session attach: instanceCompatible compares host/passthrough/domains/windows but not parent pid. If session A spawns the proxy (watchdog on A's claude pid) and session B attaches, A exiting kills the proxy under live B until B's next SessionStart event or restart. Inherited from the 无单实例守卫:多个 bili 代理进程并存共写 sessions 目录,伴随孤儿 ref、有注册表无 transcript、计数自相矛盾的污染簇 #394/实例治理伞形:身份/验活/attach-or-spawn/优雅退出/状态卫生 —— 合并修复 #394 #403 #407 #414 #410 #406 #417 shared-instance design, recovery path exists — worth at most a one-liner in the README notes.
2. MCP shim startup race: if the shim's initialize lands while the proxy is down, identity registration is fire-and-forget and issued once — that shim lifetime stays in wire mode (degraded-but-functional; compression still works via the URL rewrite; resolves on restart/reconnect). Rare in practice (hook completes before MCP connect).

---

中文摘要: 审查了 #979 全部改动,实现与拍板的混合方案一致、无阻塞问题;CI 全红是因为测试先于构建而新 e2e 依赖 dist —— 你侧的"按需构建 + 隔离 TMPDIR"修复已验证有效(按 CI 原顺序本地全绿 1933/1935);我误覆盖的该修复提交已从对象库恢复并原样重放,另按 issue 要求补齐了中英 README 的 claude 行与过时描述(未动共享 CI 配置),可以合并。

GitHub re-run on the final head (b4c1283) is in flight — I'll confirm the four legs go green.