安装后 hook error（Windows SessionStart hook fails）

你会遇到什么

安装后 Claude Code 启动时报 hook 错误（SessionStart hook 执行失败）。你以为是装坏了，重装一遍还是报。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

两个常见根因：

hook 不是插件自己跑的，是 Claude Code 在会话启动时替插件执行的：它读取插件配置里的 hook 声明，找到 session-start.sh 的路径，然后拉起这个脚本。所以 hook 报错有两种完全不同的病因：一是脚本本身有问题（语法/依赖缺失），二是 Claude Code 找不到/执行不了这个路径（Windows 路径处理 bug 属于这一类）。

手动 bash session-start.sh 的意义就是绕过启动器，直接验证脚本：手动跑正常 = 启动器路径问题（升级或换形态）；手动跑也报错 = 脚本本身问题（修脚本）。一步就把两类病因分开。

一步步来

1. 升级 Claude Code 与插件版本后重试 — 必做

claude update

然后 /plugin update 更新插件，重开会话。

2. 手动执行对应 hook 脚本 — 必做

bash <插件目录>/session-start.sh

看真实报错（CSDN 案例路径：手动跑 session-start.sh 定位）。

3. Windows 场景改走纯技能形态 — 必做

不依赖 hook 的路径（见症状 6 条目）：把 skills/ 复制到技能目录，当技能用。

怎么确认修好了

启动不再报 hook 错误：

Claude Code 新会话启动 → 无 SessionStart hook 错误

或手动执行 hook 脚本输出正常（无报错）。

其它环境的表现

症状

安装后 Claude Code 启动报 hook 错误（SessionStart hook 执行失败）。

原因

Claude Code 在 Windows 上的路径处理 bug（上游 Issue #420 属此场景）；或插件版本与 Claude Code 版本不匹配。

解法

1. 升级 Claude Code 与插件版本后重试。
2. 手动执行对应 hook 脚本（session-start.sh）看真实报错。
3. Windows 场景可改走纯技能形态（不依赖 hook 的路径，见「症状 6」）。