---
title: "Hooks 把策略插入 agent 循环"
summary: "SessionStart、PreToolUse、PermissionRequest、PostToolUse、UserPromptSubmit、Stop、Interrupt。"
category: hooks
level: advanced
surfaces: [cli]
tags: ["hooks", "PreToolUse", "安全"]
canonical: /tips/hooks-lifecycle/
---

# Hooks 把策略插入 agent 循环

SessionStart、PreToolUse、PermissionRequest、PostToolUse、UserPromptSubmit、Stop、Interrupt。

当前稳定开关是 `features.hooks`（默认已开）。旧键 `codex_hooks` 仍当别名，新配置写这个：

```toml
[features]
hooks = true
```

钩子放 `~/.codex/hooks.json`、项目 `.codex/hooks.json`（需信任），或直接写进 `[hooks]`。stdin 收 JSON。`matcher` 是正则，常见：`Bash`、`apply_patch`、`Edit|Write`、`mcp__server__tool`。

用途：

- `SessionStart`：注入当前 git 分支、oncall 信息
- `PreToolUse`：拦 `rm -rf`、拦生产部署
- `PostToolUse`：每次补丁后跑 lint
- `UserPromptSubmit`：附加机密分类提醒
- `Stop`：失败时继续或停下；反复 block 要认 stdin 里的 stop_hook_active
- `Interrupt`：顶层轮被打断时跑清理（不用于子代理）。Esc 时 `Stop` 不会跑，不要把清理只挂在 Stop 上

当前会跑的 handler 只有 `command` 和 `mcp_tool`。配置里的 `prompt` / `agent` 会解析但跳过。

`/hooks` 可在 TUI 里浏览、信任、开关。新的或改过的钩子必须先信任。

## 来源

- [OpenAI · Hooks](https://developers.openai.com/codex/hooks)