第9章 在事件发生时运行命令 · Codewhale 文档

在事件发生时运行命令钩子会在 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_userCodewhale 开始等待你的审批、回答或暂停中的目标时。session_idle / session_busy会话闲下来，或重新开始工作时。session_error / on_error回合最终失败时，或发生任何错误、工具失败时。mode_change在 Plan、Work、Operate 之间切换时。subagent_spawn / subagent_complete子 Agent 启动或结束时。condition 可以缩小钩子的触发范围：按工具名（支持 * 通配）、工具类别、模式或退出码，也可以用 all 和 any 组合。永远不可能与所属事件匹配的条件，会在加载配置时直接被拒绝——这样你以为已经生效的拦截规则，不会悄无声息地失效。设置超时与失败行为timeout_secs钩子最长可运行多久。默认 30 秒。continue_on_errortrue（默认）：钩子失败只发出警告。false：失败即阻止。backgroundtrue 表示只作为观察者运行，不能阻止或改写。working_dir写在 [hooks] 下：钩子的运行目录。默认是会话的工作区。注意： [hooks] default_timeout_secs 会替换每个钩子自己的 timeout_secs，而不只是补上未设置的那些。如果想让各钩子使用各自的超时，请不要设置它。使用仓库自带的钩子仓库可以在 .codewhale/hooks.toml 中附带钩子。由于它们会在你的机器上运行命令，只有在你信任该工作区，并且批准了这份文件的确切内容之后，才会加载：/hooks review /hooks approve /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"下一步设置模式与审批钩子的决定如何与 Ask、Auto-Review 和 Full Access 共同起作用。用 MCP 连接工具用同样的 tool_call_before 钩子管控 MCP 工具。修改设置config.toml 在哪里，以及项目可以覆盖哪些设置。