事件名	触发时机	主要用途
`SessionStart`	创建 Session 后、发起第一个对话前。	初始化环境、注入环境变量或补充上下文。
`UserPromptSubmit`	用户发送 Query 后、智能体开始处理前。	拦截不允许的请求，或向模型附加上下文。
`PreToolUse`	智能体发起工具调用后、实际执行前。	校验、拦截、修改工具参数，或要求用户确认。
`PostToolUse`	工具调用实际执行完成后。	检查工具执行结果，并向模型附加上下文。
`Stop`	智能体完成输出、准备结束当前 Query 时。	检查产出是否达标。必要时阻断停止并让智能体继续执行。
`Notification`	工具调用执行等待用户确认时，或智能体完成任务时。该事件异步触发，不阻塞主流程。	向用户发送通知。

Hook 的生命周期

Hook 在会话的特定节点触发。事件触发并命中所配置的条件后，TRAE 会将该事件的 JSON 上下文传递给你的 Hook 处理程序，由该程序根据返回结果决定是否附加上下文、拦截请求或继续执行。Hook 的生命周期示意图如下：

适用场景

场景	描述	建议事件
安全合规	拦截敏感请求、保护关键文件、阻止高风险命令。	`UserPromptSubmit`、`PreToolUse`
研发流程自动化	在代码变更后，调用脚本进行代码格式化或校验；在工具调用前后，调用脚本来记录日志或审计。	`PreToolUse`、`PostToolUse`
上下文增强	会话开始时，注入环境变量、工程约束或背景信息。	`SessionStart`
任务验收	任务结束前，检查产出质量。若质量不达标，则阻断停止，让智能体继续优化其输出。	`Stop`
工具链联动	将智能体的行为接入现有脚本、审查机制或规范检查流程。	根据实际需求选择。

TRAE IDE 支持全局和项目 Hook：

Hook 类型	生效范围	建议配置
全局 Hook	对本机当前用户下的所有工作区生效。	通用安全策略、统一上下文注入或跨项目校验规则。
项目 Hook	仅对当前项目或工作区生效。	与具体项目强相关的脚本、测试和格式化流程。

关于两类 Hook 的配置文件路径，参考 Hook 配置文件位置。

你可以在 TRAE IDE 中创建 Hook 配置文件，并在文件中配置具体事件和命令。步骤如下：

前往设置 > Hooks。
在配置部分，选择需创建的 Hook 类型：全局或项目。
在 已配置的 Hooks 处，点击创建按钮。
在弹出的安全警示面板中，阅读提示信息。确认无风险后，点击启用按钮。
根据你选的 Hook 类型，TRAE IDE 会在相应目录下创建 hooks.json 配置文件，并默认启用该 Hook 配置。
在 hooks.json 文件中，配置 Hook。配置格式和字段说明参考 Hook 配置。
保存配置。

在 TRAE 中新建 Hook 后，你后续可以根据实际需要修改这些 Hook 的配置，或禁用 Hook。

前往设置 > Hooks。
在配置部分，选择需修改的 Hook 类型：全局或项目。
在 已配置的 Hooks 处，按需完成以下操作：
- 点击齿轮图标，在编辑器内打开 hooks.json 编辑文件，然后修改 Hook 配置。
- 打开或关闭 Hook 的开关，从而启用或禁用相关 Hook。

提示

TRAE IDE 与 Claude Code 中同名 Hook 事件的输入参数和输出参数可能存在差异。导入 Claude Code Hook 后，建议根据 TRAE IDE 的 Hook 事件规范检查并调整相关配置，确保 Hook 命令能正确解析输入并返回符合预期的输出。

TRAE IDE 支持读取 Claude Code 的 Hook 配置。关于 Claude Code 配置文件路径和合并执行规则，参考 Hook 配置文件位置。

你可以控制 Hook 命令的运行方式。

在 运行方式 部分，选择 Hook 命令的运行方式。可选项如下：

方式	描述
沙箱运行	在沙箱中自动执行 Hook 命令。更多关于沙箱的信息，参考沙箱。
本地自动运行	始终在沙箱外自动执行 Hook 命令。该方式存在风险，请谨慎选择。