进阶

钩子

钩子是在工具执行前后、发消息前、模型停下时、启动时自动跑的命令：改完文件自动格式化、拦下危险命令、注入当前分支、测试没过不许停。写在 config.json 的 hooks 里，项目里的要确认信任；Claude Code 的钩子也认。

预计用时: 约 6 分钟
适用版本: v0.5.0 及以上

改完文件自动格式化

钩子写在 config.json 的 hooks 里。最常用的是改完文件跑一下格式化：

{
  "hooks": {
    "post_tool": [{ "match": "edit_file|write_file", "command": "ruff format \"$HENG_FILE\"" }]
  }
}

match 按工具名正则匹配。命令能读到这几个环境变量：

变量	内容
`HENG_TOOL`	工具名
`HENG_TOOL_INPUT`	工具参数（JSON）
`HENG_FILE`	改的是哪个文件

post_tool 的输出附在工具结果后面交给模型：格式化改了什么、检查报了什么错，它下一步就能看到。

拦下不想让它做的事

pre_tool 在工具执行前跑，退出码 2 拦下这次调用，输出作为原因告诉模型：

{
  "hooks": {
    "pre_tool": [{ "match": "bash", "command": "python scripts/check_cmd.py" }]
  }
}

scripts/check_cmd.py 从 HENG_TOOL_INPUT 里取出命令，看不顺眼就打印原因、以退出码 2 结束。单纯想禁掉某些命令，用拒绝规则更简单，见权限模式与规则。

不针对工具的三个事件

这三个事件 match 可以省略；环境变量 HENG_PROMPT 是用户这句话或模型最后的回复：

事件	什么时候跑	输出 / 退出码 2
`user_prompt_submit`	消息发给模型前	输出作为补充上下文附在消息后面（如当前分支、最近的报错）；退出码 2 拦下这条消息不发（如防止把密钥发出去）
`stop`	模型准备停下时	退出码 2 要求模型继续，输出交给模型（如「测试还没过，接着修」），最多连续 3 次
`session_start`	启动时	输出附进系统提示词（如注入项目当前状态）

/hooks 查看当前生效的钩子。

项目里的钩子要你点头

~/.claude/settings.json、项目 .claude/settings.json 里写给 Claude Code 的钩子也认（PreToolUse、PostToolUse、UserPromptSubmit、Stop、SessionStart），照 Claude 的约定传参，见兼容 Claude Code。

做完是这样

让它改一个 Python 文件，工具结果后面跟着格式化的输出；/hooks 列出你配的钩子；项目里的钩子第一次运行前，它把命令完整列出来问你信不信任。