后台 Hooks

command Hook 默认等待处理器完成。日志收集等不需要控制当前动作的工作可设置 async: true，让 Codex 继续处理任务。

配置示例

[[hooks.PostToolUse]]
matcher = "Bash"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use.py"
async = true
timeout = 120

脚本必须已存在并通过信任审查。后台 Hook 使用与同步 Hook 相同的输入、匹配规则、超时单位和大输出处理；120 秒是示例覆盖，多数 command Hook 默认 600 秒。

输出什么时候可见

如果回合仍在运行，Codex 等当前模型请求及工具调用结束，在下一次模型请求前递送支持的信息输出。没有活动回合时，等待下一个用户回合。后台 Hook 完成本身不会启动新回合。

additionalContext 加入上下文，systemMessage 显示警告。输出仍需符合原事件的结构，不能因为后台执行就任意返回另一事件的字段。

不可用作同步策略

后台 Hook 无法阻断、批准、重写或控制已经触发它的动作。工具策略、审批决定、提示词拒绝或停止后的继续工作都应使用同步 Hook。

每个会话最多同时运行 8 个后台 Hooks，更多调用等待空位。每次匹配独立执行，完成顺序可能不同于启动顺序。会话结束时取消未完成 Hook，丢弃尚未递送的输出。

SessionEnd 始终同步执行；Interrupt 即使后台运行，也保持默认 1 秒、最多 3 秒的超时限制。