agents-hooks

Name: agents-hooks
Author: vasilyu1983

github.com/vasilyu1983Agent 工作流136 次安装

代码仓库

关于 agents-hooks

用于配置和排查 Claude Code 钩子，以及 Codex 通知或生命周期钩子的技能。提供事件选择、保护规则、验证步骤，并说明不同运行时在可靠性与行为上的差异。

主要功能

01Claude Code 生命周期钩子指南
02Codex 通知与钩子指南
03工具调用前的保护与审批模式
04异步验证和审计方案
05子 Agent 与工作树生命周期协调
06钩子测试和运行时验证

适用场景

01执行前拦截高风险 Shell 命令
02编辑后运行格式化和检查
03注入会话上下文或协调子 Agent
04发送 Codex 轮次完成通知

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vasilyu1983/ai-agents-public --skill agents-hooks

安装后在 Claude Code 中输入/agents-hooks确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

learnings.consolidated.md

learnings.md

agents/

openai.yaml

assets/

template-preflight-runtime-hook.sh

data/

sources.json

references/

budget-and-loop-hooks.md

hook-patterns.md

hook-security.md

hook-templates.md

runtime-preflight-hooks.md

scenario-preflight-chain.md

scripts/

test_hook_templates.py

详细介绍

Claude Code Hooks + Codex Notifications

当钩子行为是主要关注点时，使用此技能：Claude 生命周期钩子、运行时预检、护栏、异步验证、工作树生命周期检查、子 Agent 协调或 Codex 通知回调。

Claude 和 Codex 在这方面并不等同。Claude 拥有广泛且稳定的钩子系统。Codex 有两个接口：长期稳定的通知接口（notify + tui.notifications），以及生命周期钩子系统（hooks.json；参见 developers.openai.com/codex/hooks），其事件、处理器类型和信任规则会随版本变化，并且存在触发可靠性方面的缺陷。两种运行时的事件集都在不断扩展，因此请在各自运行时的钩子参考文档中查询当前列表，而不要依赖事件数量。本技能将 Codex 钩子相关信息作为查阅步骤，收录在 references/hook-templates.md §Codex 中。对于任何必须可靠执行的任务，优先使用 notify，并在依赖 Codex 钩子前确认它能在你的运行时中触发。

快速参考

需求	事件 / 方法
强制执行工具调用前策略或护栏	`PreToolUse` 命令钩子
在会话开始时进行快速运行时检查	`SessionStart` 或 `Setup`
在 Claude 看到用户提示词前作出响应	`UserPromptSubmit`
在编辑后运行检查（非阻塞）	`PostToolUse`（异步 / 后台）
单独捕获工具调用失败	`PostToolUseFailure`
在一批并行工具调用全部完成后进行检查	`PostToolBatch`
向子 Agent 注入上下文或协调子 Agent	`SubagentStart` / `SubagentStop`
转换用户看到的内容（而不是对话记录）	`MessageDisplay`
在压缩前持久化精简的长期状态	`PreCompact`
在压缩完成后作出响应	`PostCompact`
处理工作树的创建和清理	`WorktreeCreate` / `WorktreeRemove`
响应 `cd` 或受监控的文件变更	`CwdChanged` / `FileChanged`
防止 Agent 团队进入空闲状态	`TeammateIdle`
在轮次结束时处理 API 错误	`StopFailure`
安全地重新加载插件钩子	原子化的清除后注册替换
添加 Codex 回调行为	`notify` 外部程序以及 `tui.notifications`
强制执行预算、迭代上限、停滞检测和终止开关	`references/budget-and-loop-hooks.md`

何时使用此技能

在以下任务中使用此技能：

构建 Claude 钩子自动化
添加命令护栏或审批逻辑
配置验证或审计钩子
管理钩子范围内的代码库规范
配置 Codex 通知或回调程序

如果主要关注点如下，请转到其他技能：

需求	改用
持久化项目记忆或压缩内容	../agents-memory/SKILL.md
MCP 设计或服务集成	../agents-mcp/SKILL.md
子 Agent 设计或委派边界	../agents-subagents/SKILL.md
多 Agent 编排	../agents-swarm-orchestration/SKILL.md
编码 Agent 的权限模式和审批路由	../ai-coding-agents-safety-envelope/SKILL.md

能力边界

能力	Claude Code	Codex
广泛的生命周期钩子	是（稳定；请查阅当前事件表）	是，通过 `hooks.json`（事件集较小，可靠性存在不足；请查阅匹配器表）
命令或决策控制	是	是（`PreToolUse` 拒绝；`Stop`/`SubagentStop` 阻止并继续）；请确认哪些处理程序类型会执行，哪些会被解析但跳过
修改受支持事件的负载	是（`updatedInput`、`updatedToolOutput`）	请确认你的版本中 `PreToolUse` 是否接受 `updatedInput`
外部回调程序	是	`notify`（可靠）+ `hooks.json` 钩子（先验证；信任审查可能会静默跳过已变更的钩子）
最佳用途	策略、验证、规范	可靠：使用 `notify` 发出提醒/记录日志；实验性：通过 `hooks.json` 实现生命周期自动化

典型场景

将实际场景对应到能解决问题的最精简事件和方案。选择与场景匹配的最窄一行。

场景	事件	处理程序	方案
在执行前阻止 `rm -rf`、`git push --force`、`git add .`	`PreToolUse`（匹配器 `Bash`）	`command`	`references/hook-templates.md`，模式 §8/§11
每次编辑后自动格式化并进行冒烟测试，且不拖慢 Agent	`PostToolUse`（匹配器 `Edit\|Write`，`async: true`）	`command`	模式 §1
对生产环境/破坏性工具要求审批，而非直接拒绝	`PreToolUse` → `permissionDecision: ask`，`PermissionRequest`	`command`	模式 §8
在会话开始时注入仓库状态（分支、任务 ID、常用命令）	`SessionStart` / `Setup`	`command`	`references/runtime-preflight-hooks.md`，模式 §6
在上下文压缩期间保留关键状态	`PreCompact`（检查点）+ `SessionStart`（恢复）	`command`	`hook-templates.md`，模式 §5
在一轮并行工具调用后，为下一次模型调用设置门控	`PostToolBatch`	`command`/`agent`	`hook-templates.md`，模式 §1
向子 Agent 传递上下文，并在其返回报告前验证输出	`SubagentStart`（注入）+ `SubagentStop`（阻止）	`command`	`hook-templates.md`，SKILL.md §子 Agent 协调
防止 Agent 团队过早进入空闲状态	`TeammateIdle`	`command`	快速参考
按工作树执行设置/清理（缓存、环境文件、索引）	`WorktreeCreate` / `WorktreeRemove`	`command`	`hook-templates.md`，模式 §7
立即将审计事件发送到本机以外的 SIEM/webhook	`PostToolUse` / `Notification`	`http`	模式 §2
进行语义层面的“是否满足验收标准？”门控，而非语法层面的门控	`Stop` / `SubagentStop`	`agent`	模式 §3
对自主循环设置令牌/迭代/停滞预算或熔断开关	`Stop` / `PostToolBatch` / `UserPromptSubmit`	`command`	`references/budget-and-loop-hooks.md`
审计对钩子/审批/沙箱策略本身的编辑	`ConfigChange`	`command`	`hook-templates.md`，模式 §4
目录变更时重新加载 `.envrc`/本地配置	`CwdChanged` / `FileChanged`	`command`	模式 §6
衡量各项技能在不同会话中的实际触发情况	`PreToolUse`（匹配器 `Skill`）+ `UserPromptExpansion`（`/skillname` 路径）	`command`	模式 §15
桌面提醒/将“执行完成”通知交给本地进程（Codex）	`notify` + `tui.notifications`	外部程序	模式 §12

工作流

确认任务涉及 Claude hooks、Codex 通知，还是混合设置。
选择满足需求的最小事件范围。
优先使用确定性的命令 hooks 来实施约束。
保持同步 hooks 快速；将繁重工作移至异步或后台路径。
在给出最终建议前，根据当前文档验证事件支持情况和负载假设。
针对具体的运行时、事件和处理程序类型，说明超时和错误处理策略。在当前的 Claude Code 中，明确的 PreToolUse 拒绝或退出码 2 会阻止工具调用，而超时的 command、http 或 mcp_tool 处理程序会将调用交回正常权限评估；Agent SDK 回调超时则会阻止调用。如果策略要求处理程序失败时保持默认拒绝，应在运行时支持的 command 或 http hook 上设置 "onFailure": "block"；否则，应添加单独的拒绝规则，或在执行底层实施约束。请分别测试超时、格式错误的输出和重复投递，而不只是测试正常情况。

验证和安装清单

# 1. Lint every hook script before deployment
shellcheck ~/.claude/hooks/*.sh

# 2. Dry-run a hook by piping a sample payload
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | bash ~/.claude/hooks/preflight-guard.sh

# 3. Confirm hook files are executable
chmod +x ~/.claude/hooks/*.sh

# 4. Check audit log after a test session
cat /tmp/claude-hook-audit.log

# 5. Disable all hooks for emergency bypass
# Set "disableAllHooks": true in ~/.claude/settings.json

事件范围（Claude Code）

来源：code.claude.com/docs/en/hooks。下表按用途对事件分组；它们只是索引，并非权威列表。新事件会在不同版本之间陆续加入，因此在接入事件前，请先在参考文档的事件表中确认该事件，并查看其是否可阻止。

以下两条规则适用于整张表：

仅提供上下文的事件无法阻止操作。 对于 SessionStart、SubagentStart 以及参考文档标记为“无法阻止”的任何事件，退出码 2 只会将标准错误输出显示给用户，作为 hook 错误通知；Claude 不会看到它。必须让模型知晓的内容，应在退出码为 0 时通过 hookSpecificOutput.additionalContext 发送。
阻止操作的停止 hooks 需要循环保护。 Stop 和 SubagentStop 负载包含 stop_hook_active；如果其值为 true，则应以退出码 0 返回且不阻止操作。hooks 参考文档说明了连续停止 hook 继续执行的次数上限，以及用于提高该上限的环境变量；如果门控逻辑需要自行限制次数，应在按会话区分的状态文件中计数，而不要依赖运行时上限。

会话生命周期

事件	触发时机	能否阻止？
`SessionStart`	会话开始或恢复时	否（仅提供上下文；见上方规则）
`Setup`	执行 `claude --init-only`，或在 `-p` 模式下执行 `--init` / `--maintenance` 时；为 CI 或脚本进行一次性准备（匹配器为 `init` / `maintenance`）	否
`SessionEnd`	会话终止时	否（在较短的默认超时下运行；在此处添加清理工作前，请查明默认值、最大值和覆盖用的变量）

每轮对话

事件	触发时机	能否阻止？
`UserPromptSubmit`	用户提交提示词后、Claude 看到提示词前	能
`UserPromptExpansion`	用户输入的命令扩展为提示词时	能
`Stop`	Claude 完成回复时	能（检查 `stop_hook_active`）
`StopFailure`	由于 API 错误导致本轮结束时	否
`MessageDisplay`	显示助手文本时（仅影响显示，不会更改对话记录）	否
`PreModelSwitch`	会话切换模型前	能
`PostModelSwitch`	模型切换完成后	否（仅提供上下文）

工具执行

事件	触发时机	能否阻止？
`PreToolUse`	任何工具调用前	能
`PermissionRequest`	权限对话框出现时	仅通过 `hookSpecificOutput.decision`；不接受退出码 `2`
`PermissionDenied`	自动模式分类器拒绝工具调用时	否
`PostToolUse`	工具调用成功后	否
`PostToolUseFailure`	工具调用失败后	否
`PostToolBatch`	并行工具调用的整个批次完成后	能
`Elicitation`	MCP 服务请求用户输入时	能
`ElicitationResult`	用户响应 MCP 询问后	能

子 Agent / 团队

事件	触发时机	能否阻止？
`SubagentStart`	子 Agent 启动时	否（仅提供上下文，通过 `hookSpecificOutput.additionalContext`）
`SubagentStop`	子 Agent 完成时	是（检查 `stop_hook_active`；读取 `agent_transcript_path`，而不是 `transcript_path`）
`TeammateIdle`	Agent 团队的队友即将进入空闲状态时	是

任务

事件	触发时机	能否阻止？
`TaskCreated`	通过 `TaskCreate` 创建任务时	是
`TaskCompleted`	将任务标记为完成时	是

配置 / 文件系统

事件	触发时机	能否阻止？
`ConfigChange`	会话期间配置文件发生更改时	是（`policy_settings` 除外）
`InstructionsLoaded`	加载指令文件时（CLAUDE.md、包含文件、glob/路径匹配、压缩时）	否（用于可观测性；忽略退出代码）
`CwdChanged`	工作目录发生更改时（`cd`）	否
`DirectoryAdded`	将目录添加到会话工作区时	否
`FileChanged`	受监视的文件在磁盘上发生更改时	否
`WorktreeCreate`	创建工作树时	是（任何非零退出代码）；从有效负载中读取请求的 `name`
`WorktreeRemove`	移除工作树时	用作门控条件前，请先查看参考文档中的阻止列

压缩 / 显示

事件	触发时机	能否阻止？
`PreCompact`	压缩上下文前	是
`PostCompact`	压缩完成后	否
`Notification`	Claude Code 发送通知时	否

Hook 配置片段

最精简的 settings.json 配置（复制到 ~/.claude/settings.json 或 .claude/settings.json）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/preflight-guard.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/post-audit.sh",
            "async": true
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/pre-compact-state.sh"
          }
        ]
      }
    ]
  }
}

匹配器规则：空字符串或 "*" = 匹配全部；以 | 分隔的单词 = 精确列表（例如 "Edit|Write"）；包含其他字符的字符串 = JavaScript 正则表达式（例如 "mcp__memory__.*"）。

Hook 类型：command（Shell 脚本）、http（向 URL 发送 POST 请求）、mcp_tool（调用 MCP 服务工具）、prompt（单轮大模型调用）、agent（启动子 Agent，实验性）。

退出代码：0 = 成功，解析 stdout 中的 JSON；2 = 强制阻止，stderr 会传给 Claude；其他非零值 = 记录非阻止性错误。

有效负载修改（退出代码为 0，且包含 JSON hookSpecificOutput）：PreToolUse 可将 permissionDecision 设为 allow / deny / ask / defer；PostToolUse 可通过 updatedToolOutput 替换工具结果；MessageDisplay 可通过 displayContent 重写屏幕上显示的文本（仅限屏幕 — 记录文本和 Claude 看到的内容不会改变）。务必在输出中将 hookEventName 设为触发的事件。

Exec 与 Shell 形式：添加 "args": [...] 以避免使用 Shell，并支持跨平台。省略 args 则使用带有管道和 && 的 sh -c。

禁用所有 Hook：在设置中将 "disableAllHooks": true 设为 true，以便紧急绕过。

选择 Hook 类型

类型	延迟	故障模式	适用场景
`command`	通常延迟最低；请实测	脚本错误、退出代码错误、缺少二进制文件	确定性检查 — 默认选择
`http`	网络往返	端点宕机、超时、无本地回退	审计必须立即离开本机（SIEM、Webhook）
`mcp_tool`	取决于服务	服务未连接、工具架构发生偏移	策略已存在于已连接的 MCP 服务上
`prompt`	额外一次大模型调用	非确定性、取决于模型的令牌成本	单轮语义判断已足够（无需使用工具）
`agent`（实验性）	通常延迟更高、用量更多；请实测	用于高频路径时，成本/延迟可能持续攀升	多步骤语义验证（例如“是否满足验收标准”）

只有在较简单的类型无法表达所需检查时，才逐步升级到列表中更靠后的类型；在声称成本之前，请比较观测到的延迟和用量 — 实际应用中的 command 与 agent 选择请参见 references/hook-patterns.md §3。

执行模型与优先级

并行，而非顺序执行。 当多个已注册的钩子匹配同一事件时，Claude Code 会并行运行所有钩子。不要假设一个钩子的输出对另一个钩子可见，也不要依赖注册顺序来解决冲突。完全相同的 command 钩子会按命令字符串和 args 去重；完全相同的 http 钩子会按 URL 去重——近似重复的钩子（标志不同、意图相同）不会去重，因而会触发多次。
决策冲突时采用限制更严格的优先级。 当前 Claude Code 会优先处理 deny，然后依次处理 defer、ask 和 allow。不过，仍应避免存在意见相左的重叠钩子：缩小匹配范围，让实际生效的规则便于审查；并测试合并后的配置，而不是依赖某个钩子单独运行。
设置优先级（依据 code.claude.com/docs/en/settings；当钩子的作用范围很重要时，请重新查看）：托管（组织）策略 > CLI 标志 > 项目 .claude/settings.local.json > 项目 .claude/settings.json > 用户 ~/.claude/settings.json。这修正了本技能的早期版本；早期版本将 .claude/settings.local.json 排在最后——实际上，它会覆盖项目和用户设置，而非相反。除了这四种范围外，还有两种包含钩子的范围：插件 hooks/hooks.json（启用插件时始终生效）和技能/Agent frontmatter（调用技能后，该技能的钩子会在本次会话的剩余时间内保持注册；子 Agent 的钩子仅在其运行期间保持注册）。所有范围中的钩子会合并并一起运行，而非相互覆盖——作用范围更广的钩子不会悄然取代范围更窄的钩子——因此，此优先级主要适用于 disableAllHooks 和单值设置冲突，不决定某个钩子是否触发。
allowManagedHooksOnly：企业管理员可以在托管设置中设置此项，以阻止所有用户/项目/插件钩子，但通过托管 enabledPlugins 强制启用的插件所捆绑的钩子除外。如果你注册的钩子在托管环境中莫名停止触发，请先检查此项，再调试钩子脚本。
不使用 shell 条件来限定钩子范围：工具事件钩子（如 PreToolUse）接受 if 字段——这是一个权限规则字符串，例如 "if": "Bash(git *)"——可进一步缩小处理程序触发的范围，弥补仅用 matcher 无法表达的条件。优先使用此字段，而不是在脚本中重复实现相同逻辑。

安全规则

将 stdin JSON 视为不可信输入
使用前验证字段
优先使用规范路径检查，而非文件名正则表达式
为 Shell 变量加引号，并避免使用 eval
不要将机密信息写入日志或签入配置
保持阻塞钩子的范围狭窄且便于审计
对非简单的 Shell 钩子运行 ShellCheck

常见陷阱

认为 Claude 生命周期事件与 Codex 通知界面可以互换。解决方法：接入任何钩子之前，先查看上面的能力边界表。Codex 有两个独立界面：notify/tui.notifications 和 hooks.json 生命周期系统；两者都与 Claude 的事件集不同。查阅 Codex 匹配器表，并在实际运行时进行测试后再部署。
在始终启用的钩子中执行耗时的网络调用、大型测试套件或全仓库扫描。解决方法：在自己的运行时中测量钩子延迟（官方未公布预算），并将任何明显阻塞循环的操作移至文档所述的 async: true 路径。单纯的后台作业（&）无法传递输出，也无法处理超时。同步钩子仅用于快速、范围明确的检查。
在钩子中修改文件或配置，却不留下可审查的差异或审计记录。解决方法：通过常规的 Git 跟踪文件路径进行修改。将每次修改记录到只追加的审计文件中（例如 /tmp/claude-hook-audit.log）。请参阅 references/scenario-preflight-chain.md 中的可用示例。
以非原子方式重新加载插件钩子，导致旧处理程序与新处理程序同时生效。解决方法：先清除所有处理程序，再注册新的一组。切勿在移除旧处理程序之前添加新处理程序。如果注册过程可能被中断，请使用锁文件或原子替换（写入临时路径，然后执行 mv）。
未对负载、cwd 或路径值进行规范化和边界检查，就盲目信任它们。解决方法：使用负载中的任何路径之前，始终调用 realpath -m（或同等命令）。执行操作之前，验证解析后的路径是否位于预期根目录内。无论钩子类型如何，都要将 stdin JSON 视为不可信输入。
认为同一事件上的两个钩子会按顺序运行。解决方法：Claude Code 会并行运行所有匹配的钩子，并按照上文执行模型中的限制性优先级处理冲突的决定（先处理 deny；对于有各自决定集的事件，确切顺序请查阅钩子参考文档）。仍应收窄匹配器，以减少同一事件上的钩子意见不一致的情况；与其依赖仲裁，不如使用经过审查的合并配置，这样更易于理解。
编写 Stop 或 SubagentStop 门控，却未检查 stop_hook_active。解决方法：当 stop_hook_active 为 true 时退出并返回 0。如果没有此保护，持续存在的失败条件会导致额外轮次，直到运行时的阻止次数上限将其停止。
读取负载字段时使用自己预期的名称，而不是参考文档所记录的名称。解决方法：使用文档中的字段名称构建试运行负载，并测试门控必须阻止的输入。键名错误会读取为空，因此门控不会输出任何内容并以 0 退出，看起来像是通过了。scripts/test_hook_templates.py 会对模板执行此操作。
钩子在开发环境中运行正常，之后却悄无声息地停止触发，而脚本本身看起来也没有问题。解决方法：调试脚本之前，先检查设置优先级和 allowManagedHooksOnly——组织级托管策略可能会完全抑制用户、项目和插件钩子，表现得与钩子损坏完全相同。

反模式

在每个钩子中运行耗时的同步测试套件
对 Codex 事件等价性作出未记录的假设
仅使用正则表达式进行路径验证
未脱敏地记录原始负载或环境信息
悄无声息地进行危险且无法审查的重写

references/hook-templates.md
references/hook-patterns.md
references/hook-security.md
references/runtime-preflight-hooks.md
references/scenario-preflight-chain.md — 端到端可运行场景：组合使用 PreToolUse + PostToolUse + PreCompact
references/budget-and-loop-hooks.md — 用于自主循环、触发式运行和始终运行的机器人的预算、迭代上限、停滞和紧急停止钩子
assets/template-preflight-runtime-hook.sh
scripts/test_hook_templates.py — 使用符合文档格式的负载运行每个模板；编辑模板后运行
data/sources.json

相关技能

学习反馈循环

如果先前的决策或陷阱与当前情况相关，请在 learnings.consolidated.md 存在时查阅；只有在需要了解历史记录或将其作为可用的备用文件时，才使用 learnings.md。否则跳过这两个文件。

应用这些内容后，如果你遇到了值得记住的模式、值得避免的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目符号。不要修改 SKILL.md 本身。

支持 Markdown

登录后评论

基本信息

作者: vasilyu1983
仓库: vasilyu1983/ai-agents-public
分类: Agent 工作流
安装次数: 136

报告问题