Diagnosing Hook Configuration 的目标是把任何 hook 问题归结为一个具体的修复动作。以下是基于资料整理的要点。
一、配置来源与合并 配置文件的 hook 位于 ~/.zcode/cli/config.json 的顶层 hooks 键，或工作区的 <repo>/.zcode/config.json、zcode.json，结构为 { enabled?, timeoutMs?, maxOutputBytes?, events: { <Event>: [ { matcher?, hooks: [...] } ] } }。这类 hook 默认禁用，必须设置 hooks.enabled: true 才会运行。插件 hook 来自各插件的 hooks/hooks.json 或其 manifest 的 hooks 字段，插件 matcher 追加在配置 matcher 之后；只要有插件贡献 hook，hook 运行器就会自动启用。非插件的用户或工作区配置 hook 没有信任门槛，设置 enabled: true 后无条件运行。资料特别说明：插件 hook 无论来自哪个市场都会执行，所谓市场 hook“仅诊断、需信任”的说法已过时，插件详情视图会把每个 hook 标记为可运行，这一点现在对所有 hook 成立。
二、hooks.json 结构 插件文件使用外层 hooks 包装，配置文件使用 hooks.events.<Event>，内层数组结构相同。受支持的事件恰有七个：SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop；其他名称均为不支持事件，Notification、SubagentStop、PreCompact 等也不支持。matcher 是区分大小写的正则表达式，按事件的匹配值测试：SessionStart 匹配 startup、resume、clear、compact 之一；工具事件匹配工具名（Bash、Read、Write、Edit、Agent 等），并有别名 Task ↔ Agent、Write/Edit ← ApplyPatch；UserPromptSubmit 匹配提示文本；Stop 匹配响应预览。省略 matcher 匹配全部，无效正则会静默地永不匹配。
三、hook 类型与超时 type 为 command 时使用 command（shell 字符串），可选 shell、timeout（秒）、timeoutMs（毫秒，优先）和 statusMessage；async 目前无运行时效果。type 为 process 时使用 command（可执行文件）加 args[]（不经 shell 的参数向量，最便携）、timeoutMs 和 statusMessage。超时解析顺序为 timeoutMs → timeout × 1000 → 配置的 timeoutMs → 默认 60000 毫秒。模板变量会在命令和每个参数中展开并注入为环境变量：${CLAUDE_PROJECT_DIR} / ${ZCODE_PROJECT_DIR}、${CLAUDE_SESSION_ID}；仅插件 hook 还支持 ${CLAUDE_PLUGIN_ROOT} / ${ZCODE_PLUGIN_ROOT} 及插件数据目录。技能目录变量在 hook 中无效并会报错。
四、输出与退出码 标准输出按严格 JSON 结构解析，任何多余键都会导致校验失败；也可使用退出码：0 通过、2 阻断（PreToolUse/PermissionRequest 视为拒绝），其他非零值报错。additionalContext 会注入对话；PreToolUse 可返回 allow/ask/deny 权限决定；Stop 最多可请求续接三次。
五、检查方式 客户端中可通过 Settings → Plugin Management 打开插件详情查看其注册的 hook 及是否可运行；作为智能体可读取插件的 hooks/hooks.json 或 manifest hooks 字段，以及配置文件中的 hooks 块。执行情况（触发、超时、阻断）记录在 ZCode 日志中，含来源、matcher、结果、耗时和错误流预览，足以区分超时、失败与阻断。
六、常见陷阱（症状→原因→修复） 配置文件 hook 不运行：默认禁用，仅在存在插件 hook 时自动启用，需设置 hooks.enabled: true。事件名错误：必须使用七个受支持事件之一。matcher 不匹配：区分大小写且为正则，"bash" 不会匹配 Bash，无效正则永不匹配，应使用准确工具名或正确表达式（如 "Edit|Write"），或省略 matcher。脚本不可执行：为脚本添加执行权限，或通过解释器调用，如 {"type":"command","command":"bash "${CLAUDE_PLUGIN_ROOT}/hooks/x.sh""}。模板变量未展开：只使用受支持变量，插件相对路径用 ${CLAUDE_PLUGIN_ROOT}。超时单位混淆：command 的 timeout 为秒，process 的 timeoutMs 为毫秒。命令与进程字段混用：process 只接受 command、args、timeoutMs；command 接受 command、shell、timeout、timeoutMs，字段须与类型匹配。JSON 输出校验失败：只输出被识别的键和正确事件名，或输出为空并依赖退出码。误以为 async 后台运行：async 无运行时效果，hook 始终内联运行，需要后台工作应让脚本自行守护化。跨平台失败：command hook 经 shell 运行，POSIX 语法在 Windows 上会失败，优先使用 process hook 或不带扩展名的多语言包装脚本。hook 意外阻断会话：检查日志中的阻断原因，修正退出码，返回 0 通过、仅在有意阻断时返回 2。误信第三方 hook“仅诊断”：所有插件 hook 均可运行，应按其他陷阱排查。
七、定位流程 按顺序：确认运行器是否激活（配置中 hooks.enabled: true 或至少一个插件贡献 hook）；枚举已注册项（插件详情或直接读取 hooks 块）；核对事件名与 matcher（对照七个事件，确认匹配值及区分大小写的表达式，可省略 matcher 测试）；确认可执行性与解释器；手动运行脚本并查看退出码与输出（0 加有效 JSON 为正常，2 为有意阻断，其他非零为失败）；触发事件并读取日志中的运行记录，区分超时、失败与阻断。
适用场景为 ZCode 客户端中 hook 的配置排错与修复。资料未提供该技能自身的收费、价格、平台支持范围等信息，暂未提供。