用于构建 Claude Code hooks 的 Python 实用程序包

claude-hook-utils 一个 Python 实用程序包，用于使用最少的样板构建 Claude Code hooks。什么是克劳德代码钩子？ Claude Code 挂钩是在 Claude Code 执行期间的特定点运行的自定义脚本。它们允许您： 在执行之前验证工具调用 (PreToolUse) 在执行后对工具结果做出反应 (PostToolUse) 在 Claude 看到用户提示之前拦截用户提示 (UserPromptSubmit) 在会话启动时初始化状态 (SessionStart) 为什么使用此包？构建 Claude Code hooks 涉及重复的样板文件： 从 stdin 解析 JSON 验证输入结构 在正确的模式中格式化响应 优雅地处理错误 claude-hook-utils 可以处理所有这些，让您专注于验证逻辑。设计理念 一种模式 - 扩展 HookHandler ，覆盖您需要的钩子 类型安全 - 用于输入的类型化数据类，用于响应的构建器模式 显式控制 - 输入上的辅助方法，但您决定何时跳过/允许/拒绝 多钩子支持 - 一个 Python 程序可以处理多种钩子类型 无重依赖性 - 核心包具有最小的依赖性；如果需要，请带上自己的 AI SDK 安装 pip install claude-hook-utils 快速入门 #!/usr/bin/env python3 """验证数据类是否有 TypeScript 注释。""" from claude_hook_utils import HookHandler , PreToolUseInput , PreToolUseResponse class DataClassValidator ( HookHandler ): def pre_tool_use ( self , input : PreToolUseInput ) -> PreToolUseResponse | None: # 如果没有输入则不是数据类文件则跳过。 file_path_matches('**/app/Data/**/*.php'): return None # 如果输入则检查所需的注释。 content 和 '#[TypeScript()]' 不在 input 中。内容：返回 PreToolUseResponse 。 Deny(“数据类必须具有用于类型生成的#[TypeScript()]注释”)返回PreToolUseResponse。允许（）如果__name__ ==“__main__”：DataClassValidator（）。 run () 在 .claude/settings.json 中配置 : { "hooks" : { "PreToolUse" : [ { "matcher" : " Write|Edit " , "hooks" : [ { "type" : " command " , "command" : " python3 /path/to/data_class_validator.py " } ] } ] } } 支持的钩子类型 运行时的钩子类型 用例PreToolUse 工具执行之前 验证文件路径、检查内容、阻止危险操作 PostToolUse 工具完成后 记录结果、触发后续操作、收集指标 UserPromptSubmit 当用户提交提示时 验证提示、添加上下文、强制执行策略 SessionStart 当 Claude 代码会话开始时 初始化状态、设置环境变量 API 参考 HookHandler 基类 扩展此类并覆盖您需要的钩子： from claude_hook_utils import HookHandler class MyHandler ( HookHandler ): def __init__ ( self ): super (). __init__ () # 在此添加任何共享状态 self . _cache : dict = {} def pre_tool_use ( self , 输入 : PreToolUseInput ) -> PreToolUseResponse | None : """在工具执行之前调用。返回 None 以跳过。""" return None def post_tool_use ( self , input : PostToolUseInput ) -> PostToolUseResponse | None : """在工具执行后调用。返回 None 以跳过。""" return None def user_prompt_submit ( self , input : UserPromptSubmitInput ) -> UserPromptSubmitResponse | None : """当用户提交提示时调用。返回 None 以跳过。""" return None def session_start ( self , input : SessionStartInput ) -> SessionStartResponse | None : """会话开始时调用。返回 None 跳过。""" return None if __name__ == "__main__" : MyHandler ()。 run () PreToolUseInput PreToolUse 挂钩的输入： @ dataclass class PreToolUseInput : # 公共字段 session_id : str cwd : str hook_event_name : str # 始终为 "PreToolUse" # PreToolUse 特定 tool_name : str # "Write"、"Edit"、"Bash" 等 tool_input : dict # 工具特定参数 tool_use_id : str # 辅助方法 def file_path_matches ( self , * globs : str ) -> bool : """检查 tool_input.file_path 是否与任何 glob 模式匹配。""" def file_path_excludes ( self , * globs : str ) -> bool : """检查 tool_input.file_path 是否与任何 glob 模式不匹配。""" # 便利属性 @ property def file_path ( self ) -> str | None : """从 tool_input 获取 file_path（用于写入/编辑/读取工具）。""" @ property def content ( self ) -> str |无 : """从 tool_input 获取内容（用于写入工具）。""" @ property def command ( self ) -> str | None : """从 tool_input 获取命令（对于 Bash 工具）。""" PreToolUse 钩子的 PreTo