SuperAPI AI 工具集

agents-hooks

智能体与模型

查看项目

更新于 10-15 23:57

技能介绍

用途:当钩子行为本身是主要关注点时使用本技能,包括 Claude 生命周期钩子、运行时预检、护栏、异步校验、worktree 生命周期检查、子智能体协调,以及 Codex 通知回调。Claude 与 Codex 在此并不等价:Claude 拥有面广且稳定的钩子体系;Codex 有两条路径——长期稳定的通知面(notify + tui.notifications)和生命周期钩子系统(hooks.json),后者的所支持事件、处理器类型与信任规则会随版本变化,并存在触发可靠性缺口。两者事件集都在增长,应查阅各运行时的钩子参考文档获取当前列表,不要依赖数量。必须可靠的行为优先用 notify;依赖 Codex 钩子前先确认在你所用运行时上确实会触发。

主要能力(Claude Code 事件面):会话生命周期 SessionStart、Setup、SessionEnd;每轮 UserPromptSubmit、UserPromptExpansion、Stop、StopFailure、MessageDisplay、Pre/PostModelSwitch;工具执行 PreToolUse、PermissionRequest、PermissionDenied、PostToolUse、PostToolUseFailure、PostToolBatch、Elicitation、ElicitationResult;子智能体与团队 SubagentStart、SubagentStop、TeammateIdle;任务 TaskCreated、TaskCompleted;配置与文件系统 ConfigChange、InstructionsLoaded、CwdChanged、DirectoryAdded、FileChanged、WorktreeCreate、WorktreeRemove;压缩与显示 PreCompact、PostCompact、Notification。两条规则:纯上下文事件不可阻塞,模型需知的信息应以 exit 0 的 hookSpecificOutput.additionalContext 传递;阻塞式 Stop 钩子需自设循环护栏,用 session 级状态文件计数。

使用方式:最小配置写入 ~/.claude/settings.json 或 .claude/settings.json,在 hooks 下按事件声明 matcher 与 hooks 数组。matcher 空串或 * 匹配全部,| 分隔为精确列表,其他字符视为 JavaScript 正则。钩子类型有 command、http、mcp_tool、prompt、agent。退出码 0 为成功并解析 stdout JSON,2 为硬阻塞并把 stderr 交给 Claude,其他非零为记录的非阻塞错误。PreToolUse 可通过 permissionDecision 设为 allow/deny/ask/defer,PostToolUse 可用 updatedToolOutput 替换结果,MessageDisplay 可用 displayContent 改写屏幕文字(不改 transcript)。用 args 数组可避免 shell 并跨平台;settings 中 disableAllHooks: true 可紧急旁路全部钩子。可参考校验清单:shellcheck 钩子脚本、按样例 payload 干跑、chmod +x、查看审计日志。

限制与注意:多个匹配钩子并行执行,不保证互相可见输出,也不以注册顺序决定优先级;相同命令或 URL 的钩子会去重,近似的重复钩子不会去重而会重复触发。冲突决策按限制性优先,当前 deny 优先于 defer、ask、allow。设置优先级为托管策略 > CLI 参数 > 项目 settings.local.json > 项目 settings.json > 用户设置;插件 hooks.json 与技能/智能体 frontmatter 也会合并生效。企业管理员可用 allowManagedHooksOnly 屏蔽非托管钩子。当前 Claude Code 中显式 PreToolUse deny 或退出 2 会阻塞工具调用,而超时的 command、http、mcp_tool 会退回常规权限评估;Agent SDK 回调超时则阻塞。钩子失败时必须保持关闭的策略,需另设拒绝规则或在执行底座中强制。Codex 侧优先使用可靠的 notify,hooks.json 需先验证触发。更多模板与模式见资料中引用的 references 与 patterns,官方文本暂未提供。