Hooks 生命周期¶

Hooks 是 Codex 的策略插槽。它们不只是“运行脚本”，而是可以阻止输入、改写工具输入、审批权限、阻止工具结果返回模型、向上下文注入额外信息。

Hook 配置¶

codex-rs/config/src/hook_config.rs 定义 10 类事件：

Hook Event	触发点
SessionStart	session 或 thread-spawn subagent 启动
UserPromptSubmit	用户输入提交
PreToolUse	工具执行前
PermissionRequest	工具需要权限审批时
PostToolUse	工具成功产生结果后
PreCompact	压缩前
PostCompact	压缩后
SubagentStart	子 agent 启动
SubagentStop	子 agent 停止
Stop	turn 准备结束时

每个事件下是 MatcherGroup，包含可选 matcher 和多个 handler。handler 类型包括：

• command
• prompt
• agent

PreToolUse¶

run_pre_tool_use_hooks 会构造稳定的 hook payload：

• session id
• turn id
• subagent context
• cwd
• transcript path
• model
• permission mode
• canonical tool name
• matcher aliases
• tool input

返回值可以：

• continue。
• continue 并提供 updated_input。
• block，并把 block reason 作为模型可见失败返回。

PermissionRequest¶

run_permission_request_hooks 返回可选 PermissionRequestDecision。如果 hook 返回 allow/deny，ToolOrchestrator 会把这个 decision 当成配置来源的审批决策；如果 hook 不处理，则走 Guardian 或用户审批。

PostToolUse¶

run_post_tool_use_hooks 在工具执行成功后运行。它可以：

• block 工具结果。
• 注入 additional contexts。
• 返回 feedback message，替换模型可见工具输出。

注意：PostToolUse block 阻止的是“结果回给模型”，不是撤销已经执行的工具。

Stop Hook¶

run_turn_stop_hooks 在 turn 准备结束时运行。如果 hook 返回 continuation fragments，Codex 会构造 hook prompt message 写入 history，并继续 agent loop。这让 hook 能实现“最后检查”或“要求模型补一步”的策略。

Hook 事件可见性¶

运行时会发出：

• HookStartedEvent
• HookCompletedEvent
• hook run summary

这让 UI 可以展示 hook 正在执行，也让 telemetry 记录 hook 状态和耗时。

可学习的设计¶

Hooks 在 Codex 中不是旁路，而是主执行链的一部分。它们的威力来自三个边界：

• payload 是稳定契约，不直接泄露内部工具结构。
• hook outcome 被转成明确的 control flow。
• hook events 被纳入协议事件和 telemetry。