用途:本技能教你在 Claude Code 与 Claude Agent SDK 中编写事件拦截器 hook,在 Agent 生命周期特定节点执行自定义逻辑,实现工具调用前校验、调用后日志、上下文注入、工作流自动化与安全强制执行。资料明确列出不适用场景:审计已有 hook 用 abstract:hooks-eval,选择 hook 位置用 abstract:hook-scope-guide,编写 skill 而非 hook 用 abstract:skill-authoring。
主要能力:事件类型包括 PreToolUse(执行前校验、过滤、转换输入,2.1.9+ 可返回 additionalContext)、PostToolUse(记录、分析、修改输出)、UserPromptSubmit、PermissionRequest、Notification、Stop/SubagentStop、TeammateIdle/TaskCompleted(2.1.33+)、PreCompact、SessionStart/SessionEnd、WorktreeCreate/WorktreeRemove(2.1.50+)。支持声明式 JSON(Claude Code,配置于 .claude/settings.json、项目配置或插件 hooks/hooks.json)与程序化 Python(AgentHooks 基类)。HTTP hook 自 2.1.63+ 支持,用 type: http 与 url 字段,向 URL POST JSON 并接收 JSON 响应。2.1.0+ 可在 skill、command、agent 的 frontmatter 中定义 hook 并使用 once: true 表示每会话只执行一次。
必要用法:JSON hook 使用字符串 matcher(如 "Bash"、"Read|Write|Edit"、".*"),对象 matcher 已弃用。示例:"hooks": [{"type": "command", "command": "..."}]。hooks/hooks.json 在插件启用时自动加载,不要再在 plugin.json 中重复配置,否则会重复加载报错。
适用场景:工具输入校验、危险命令拦截、生产配置保护、审计日志、指标收集、上下文注入、多 Agent 协调、会话初始化与清理、worktree 创建/移除等。
限制与安全要点:hook 超时为 10 分钟(2.1.3 起由 60s 提高),建议多数 hook 控制在 30s 内;不得记录 API key、token、密码等凭据;尊重沙箱边界,沙箱模式下 .claude/skills/ 为只读(2.1.38+);出错应返回 None 而非阻塞 Agent;需做限流与日志注入防护。资料未提供收费、价格与具体平台信息。