在事件发生时运行命令

钩子会在 Codewhale 会话的特定时刻运行你指定的命令。可以用它拦下危险的命令、给消息补充上下文、记录发生了什么，或者在 Codewhale 等你回应时提醒你。

添加第一个钩子

钩子写在 ~/.codewhale/config.toml 中。下面这个钩子会在每次会话开始时打印一行文字：

[hooks]
enabled = true

[[hooks.hooks]]
name = "announce"
event = "session_start"
command = "echo 'Codewhale session started'"

启动一个会话，运行 /hooks，就能看到所有已配置的钩子、钩子总开关是否打开，以及被拒绝加载的条目。/hooks events 会列出所有事件名称。

在命令执行前拦下它

tool_call_before 钩子会在每次工具调用执行之前看到它，并可以放行、拒绝，或强制弹出审批提示。下面这个钩子会拒绝强制推送。保存脚本并赋予可执行权限：

#!/bin/sh
# ~/.codewhale/hooks/no-force-push.sh
case "$DEEPSEEK_TOOL_ARGS" in
  *"push --force"*|*"push -f"*)
    echo '{"decision": "deny", "reason": "Force-push is blocked by a hook."}' ;;
esac
exit 0

[[hooks.hooks]]
name = "no-force-push"
event = "tool_call_before"
command = "~/.codewhale/hooks/no-force-push.sh"
condition = { type = "tool_name", name = "bash" }

钩子从环境变量中读取这次调用，并在标准输出上用 JSON 作答：allow、deny 或 ask，还可以附带 reason、改写后的输入（updatedInput）或给模型的补充上下文（additionalContext）。退出码 2 一律表示拒绝。多个钩子同时作答时，拒绝优先于询问，询问优先于放行。

注意： 在 Ask 和 Auto-Review 下，ask 会强制弹出提示。Full Access 从不显示审批提示，因此在那里 ask 不会新增提示。

选择触发时机

有三个事件能改变接下来发生的事，其余事件只做观察：它们的输出会被忽略，失败也只会产生警告。

message_submit: 在你的消息发给模型之前。可以替换文本，或阻止发送。
tool_call_before: 在每次工具调用之前。可以放行、拒绝、询问、改写输入或补充上下文。
shell_env: 在每条 shell 命令运行之前。可以添加环境变量。
session_start / session_end: 会话打开时，或正常关闭时。
turn_end: 回合结束后，附带状态、耗时和 token 用量。
tool_call_after: 每个工具结果返回之后，有退出码时会附带退出码。
waiting_for_user: Codewhale 开始等待你的审批、回答或暂停中的目标时。
session_idle / session_busy: 会话闲下来，或重新开始工作时。
session_error / on_error: 回合最终失败时，或发生任何错误、工具失败时。
mode_change: 在 Plan、Work、Operate 之间切换时。
subagent_spawn / subagent_complete: 子智能体启动或结束时。

condition 可以缩小钩子的触发范围：按工具名（支持 * 通配）、工具类别、模式或退出码，也可以用 all 和 any 组合。永远不可能与所属事件匹配的条件，会在加载配置时直接被拒绝——这样你以为已经生效的拦截规则，不会悄无声息地失效。

设置超时与失败行为

timeout_secs: 钩子最长可运行多久。默认 30 秒。
continue_on_error: true（默认）：钩子失败只发出警告。false：失败即阻止。
background: true 表示只作为观察者运行，不能阻止或改写。
working_dir: 写在 [hooks] 下：钩子的运行目录。默认是会话的工作区。

注意： [hooks] default_timeout_secs 会替换每个钩子自己的 timeout_secs，而不只是补上未设置的那些。如果想让各钩子使用各自的超时，请不要设置它。

使用仓库自带的钩子

仓库可以在 .codewhale/hooks.toml 中附带钩子。由于它们会在你的机器上运行命令，只有在你信任该工作区，并且批准了这份文件的确切内容之后，才会加载：

/hooks review
/hooks approve <digest>
/hooks revoke

/hooks review 会显示其中的命令以及文件摘要；批准该摘要后，从下一次会话起启用这份确切的内容。文件有任何改动都需要重新批准。命令调用的脚本也请一并审阅。

在脚本和 CI 中使用钩子

钩子在交互式会话中运行。codewhale exec 默认不触发任何钩子；加上 --hooks 后会触发 tool_call_before 和 shell_env。由于没有人可以回应，ask 会被当作拒绝。

codewhale exec --auto --hooks "run the test suite and fix the first failure"