一、为什么需要选择
Hook 默认同步执行——Claude 等待 Hook 完成,读取退出码和输出,再决定下一步。这是合理的默认行为:阻断危险操作(退出码 2)、注入上下文信息、做权限决策,都需要 Claude 拿到 Hook 的结果。
但并非所有 Hook 都需要 Claude 等待。
选错的代价:
选错同步:性能损失。选错异步:功能失效。两个方向的代价不对称——异步选错的后果严重得多。
二、限制与红线
异步 Hook 通过 "async": true 启用,仅 command 类型支持。启动后 Claude 立即继续,不等待结果。
核心限制:异步 Hook 的所有输出通道失效。
异步 Hook 是纯粹的"发射后不管"模式。脚本是否执行成功、输出了什么、退出码是几,Claude 一概不知。
输出交付时机:异步 Hook 的输出(如果有)在下一对话轮次才交付——但由于输出通道已失效,这个交付对 Claude 的行为没有实际影响。
硬约束——以下场景绝不能用异步: