Skip to content

fix(claude): shell-portable SessionStart hook + PATHEXT-aware CLI resolution (#1902) - #1905

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-02_win-claude-hook-node
Oct 2, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-02_win-claude-hook-node

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Two Windows defects in the claude install lane, both reported with repros in #1902 (bili 0.1.179, Claude Code 2.1.284):

1. The SessionStart hook never started under cmd.exe. portableHookCommand() emitted the install-time node path with a leading PowerShell-only & for spaced paths (& "C:/Program Files/nodejs/node.exe" <script>). Claude Code 2.1.284 runs hooks through non-interactive cmd.exe, which dies on the leading & (& was unexpected at this time.) — silently, so the lane just never came up. #1376 had probe-verified PowerShell on Claude Code 2.1.282, while #1902 measured cmd.exe on 2.1.284: the client's hook shell is not stable across versions, and no single spelling of a spaced command path survives both shells ("quoted" head args is a parse error in PowerShell; & "quoted" head args is an error in cmd).

Root fix: stop emitting a spaced command token at all — the claude hook now carries a bare node head (node C:/.../dist/claude-native-bootstrap.js), PATH-resolved by every client shell, exactly like the kimi hook already does. Soundness invariant: claude cannot run without node resolvable on PATH (its npm shim invokes bare node), and the hook inherits claude's environment. Bonus: the hook no longer pins an absolute node binary, so a node moved/upgraded after install can no longer strand it.

Self-heal for existing installs: refreshOurHookCommands() rewrites our owned hook commands (matched on the bootstrap script suffix, not the exe) on the next session-start repin or reinstall — no manual settings edit needed.

2. MCP registration ENOENTed at install time. resolveClaudeCli() took the raw first where.exe hit, which for npm global installs is the extensionless POSIX shim (...\npm\claude) — unspawnable by Node. Hits are now ranked the way cmd.exe itself resolves them: PATH order first, PATHEXT order within each directory (env PATHEXT, default .COM;.EXE;.BAT;.CMD); when nothing carries a PATHEXT extension the old first-hit behavior stands (the downstream ENOENT stays truthful). A CLAUDE= override still passes through untouched (the reporter's working bypass remains valid).

Behavior change (intended, disclosed)

Coordination

Pre-flight (rebased onto current master 562d0e6)

Fixes #1902

…olution (#1902)

Two Windows defects in the claude install lane, both reported with repros
in #1902 (bili 0.1.179, Claude Code 2.1.284):

1. The SessionStart hook command carried the install-time node path with a
   PowerShell-only leading '&' for spaced paths. Claude Code 2.1.284 runs
   hooks through cmd.exe, which dies on the '&' ('& was unexpected at this
   time.') — the lane silently never started. #1376 had probe-verified
   PowerShell on 2.1.282, so no single spelling of a spaced command path
   survives both client shells across versions. Root fix: emit a bare
   'node' head (PATH-resolved by every client shell — claude's own npm shim
   requires node on PATH), like the kimi hook already does. Existing
   installs self-heal: refreshOurHookCommands rewrites our owned hook
   commands on the next session-start repin or reinstall.

2. resolveClaudeCli took the raw first where.exe hit, which for npm global
   installs is the extensionless POSIX shim — unspawnable by Node (ENOENT),
   so MCP registration failed at install time. Hits are now ranked the way
   cmd.exe resolves them: PATH order first, PATHEXT order within each
   directory; no-match keeps the old first-hit behavior. A CLAUDE override
   (the reporter's working bypass) still passes through untouched.

Behavior change (intended, disclosed): the emitted claude hook command goes
from '& "<abs node path>" <script>' / '<abs node path> <script>' to
'node <forward-slashed script>'. The absolute-path form also went away, so
a node binary moved after install can no longer strand the hook.

Tests: resolveClaudeCli gains the #1902 repro (extensionless-first npm dir)
plus PATH-vs-PATHEXT precedence pins; the installer round-trip now asserts
the emitted hook carries a bare 'node' head; hook-command.test.ts comments
updated to record both observed client shells. Typecheck + targeted suites
(hook-command, claude-native, kimi-native) green locally; Windows CI runs
the shell integration tests.
@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-02_win-claude-hook-node (d55756d)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1896-pr.1905.b129983

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-pr1905.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

[bot] 🏷 Review 完成(PR #1905,Fixes #1902)。结论:可合并——代码、回归、测试三关均过;CI 尚余 2 个 Windows test job(win22/win24)在跑,绿了即可合。无小问题需要补 commit,也未发现需立项的新问题。

① 是什么问题:Windows 上 bili plugin install claude 写入的 SessionStart hook 命令带 PowerShell-only 的 & 前缀(仅当 node 路径含空格时),而 Claude Code 2.1.284 用非交互 cmd.exe 跑 hook → & was unexpected at this time. 静默失败 → claude lane 永远起不来;附带缺陷:安装期 MCP 注册 ENOENT,因为 resolveClaudeCli 取 where.exe 的原始首条命中——npm 全局目录里那是无扩展名 POSIX shim,Node spawnSync 无法直接执行。

② 什么原因导致的:根因不是「& 该不该加」,而是发出了含空格的 command token 本身——客户端 hook shell 跨版本不稳定(#1376 在 2.1.282 实测 PowerShell,#1902 在 2.1.284 实测 cmd.exe),而含空格路径的任何单一裸拼写都无法同时存活于两个 shell("quoted" head args 在 PowerShell 是 parse error,& "quoted" head args 在 cmd 是 error)。用户原建议「去掉 &」恰好会在 2.1.282 形态下翻车,PR 的修法比用户建议更进一层、修在了源头。MCP 侧根因:where.exe 首命中 ≠ cmd.exe 解析结果,npm 目录里 shim 排在 .cmd 前面。

③ 怎么修复的:hook 改为 bare node <script>——PATH 解析,三个 shell 通用,与 kimi lane 对齐;健全性不变量:claude 能跑则 node 必在 PATH(npm shim 本身就是 bare node),hook 继承 claude 环境。存量安装自愈:refreshOurHookCommands 按 bootstrap script 后缀匹配(正则同时认旧/新/带引号三种形态,已逐字核对 src/plugin-install.ts:582),下次 session-start repin 或重装自动改写,无需手改 settings。resolveClaudeCli 改为按 cmd.exe 自身语义排序:PATH 顺序优先,同目录内 PATHEXT 顺序(env 注入,默认 .COM;.EXE;.BAT;.CMD);无任何扩展名命中时退回旧 first-hit(下游 ENOENT 保持真实)。

④ 是否有回归问题:审过既有行为,无意回归为零:

  • 其他 lane(kimi/zcode/hermes/codex/opencode/pi/omp/dsh)不走这两个函数或用 argv 数组(无 shell 字符串解析),不受影响;kimi 本就是 bare node;
  • portableHookCommand 签名与非空格 head 的输出不变,& 分支保留且被测试钉住(现无 shipped caller);
  • CLAUDE= override(含路径或扩展名)仍在 where.exe 之前短路放行,报告者的绕行方式继续有效;非 win32、where.exe 失败/空输出路径均保持原行为;
  • bootstrap 进程树匹配(isClaudeHostArgv,src/claude-native-bootstrap.ts:238)按 argv basename 匹配,不依赖 hook 里的 node 路径,hook 进程 argv 未变([node, script]);remove 路径同样按后缀匹配;
  • 有意变更(PR 已披露):hook 命令 & "<abs node>" <script> / <abs node> <script> → node <script>;CLI 解析 first-hit → PATHEXT 排序(更早的 PATH 目录仍胜过更晚目录的任何扩展名——与 cmd 语义一致)。

⑤ 是否破坏缓存:不涉及。未触碰 prefix cache、会话持久化、更新节流。

⑥ 是否改了设计方向:无转向,反而是收敛——hook 生成回到最保守的可解析形态(bare token),与 kimi lane 统一,未来客户端再换 shell 也不会翻车。

⑦ 是否引入了新的配置:无。pathext 仅为测试注入参数;生产读系统 PATHEXT(默认值不变)。

测试有效性:新断言有牙——resolveClaudeCli 五个形态全钉(#1902 复现/同目录 PATHEXT 优先/PATH 序胜扩展名/无匹配回退/PATHEXT 注入);installer round-trip 断言发出的 hook 以 node 开头、以 bootstrap script 名结尾,此 bug 回归即红。diff 整洁度:3 文件 +84/-15,单 commit,每行都服务于本 issue,干净。

本地验证(rebased head d55756d):typecheck clean;定向套件(hook-command/claude-native/kimi-native)78 tests,69 pass,0 fail,9 skip(win32/live-e2e gated)——与 PR pre-flight 完全一致。CI:11 check-runs 已绿(build-artifact、version-guard、codex/opencode/pi/dsh real-lane e2e、hermetic registry e2e ubuntu+win、ubuntu 22/24 test),余 2 个 windows-latest test job 运行中——恰是本 fix 针对的 Windows shell 集成矩阵,等其绿完。

合并判定:可合。等最后两个 Windows job 转绿后由人工合并即可。

@ranxianglei
ranxianglei merged commit 771a72f into master Oct 2, 2026
13 checks passed
@ranxianglei
ranxianglei deleted the 2026-10-02_win-claude-hook-node 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

Development

Successfully merging this pull request may close these issues.

Windows: plugin install claude 的 SessionStart hook 带 PowerShell "&" 前缀,cmd.exe 下静默失败,claude lane 无法自举(附修复建议)

1 participant