用途:Codex CLI 没有 Claude 式钩子事件,本技能定义了一套 Codex 钩子契约,通过钩子运行器(包装脚本或 CI 任务)在 codex exec 前后执行钩子脚本,可选解析 codex exec --json 输出以检测工具使用,并依据 hooks.json 决定运行哪些钩子。仓库提供参考运行器 scripts/codex-hook-runner,由 install.sh 安装;codex-autonomous 默认启用钩子,设 CODEX_DISABLE_HOOKS=1 可禁用。
主要能力:钩子分为 prompt 钩子(由 LLM 做上下文决策,返回 approve|deny 及原因)和 command 钩子(shell 脚本做快速确定性检查,可设 timeout)。推荐事件有 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd、SubagentStop,其中 PreToolUse/PostToolUse 需解析 --json。钩子脚本从 stdin 接收 JSON,通过退出码返回决定:0 允许/继续,2 阻止(stderr 消息会上报)。推荐输出含 decision(allow|deny|ask)、reason、systemMessage。输入字段建议含 event、tool_name、tool_input、tool_result、session_id、transcript_path、cwd、approval_policy、sandbox_mode。运行器应设置 CODEX_PROJECT_ROOT、CODEX_HOOK_ROOT、CODEX_ENV_FILE 环境变量。
使用方式:在 hooks.json 中定义 hooks,可省略 hooks 包装直接用顶层事件,scripts/validate-hook-schema.sh 两种格式都支持。开发时用 scripts/validate-hook-schema.sh 校验结构、scripts/hook-linter.sh 检查脚本、scripts/test-hook.sh 以样例输入运行。参考 references/patterns.md、references/advanced.md、references/migration.md 及 examples/ 样例。
限制:钩子运行器需自行实现,事件由运行器选择;PreToolUse/PostToolUse 依赖解析 codex exec --json 输出;具体平台、收费与效果暂未提供。