企业官网建设流程全解析

如何配置 CodeWhale Hooks 生命周期钩子：session_start 与 pre/post 三类事件实战指南

【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale

CodeWhale是一个用 Rust 编写的开源终端编码智能体（Coding Agent）。它的Hooks（生命周期钩子）机制可以让你在会话启动（session_start）、工具调用前后（pre/post）等 11 个关键时刻自动运行自己的 shell 命令——发通知、拦截危险操作、注入临时凭证，全部由你掌控 🐋

一、什么是 Hooks 生命周期钩子？

把 Hooks 理解成"事件订阅器"：当 CodeWhale 的交互式 TUI 到达某个生命周期节点时，它会自动执行你在配置文件里注册的一条 shell 命令。

每条钩子就是一个普通进程：

• 通过环境变量接收上下文（如DEEPSEEK_SESSION_ID、DEEPSEEK_WORKSPACE、DEEPSEEK_MODEL）
• 部分事件还会通过stdin 传入 JSON 负载
• 其中 3 类事件甚至能反向改变CodeWhale 的下一步行为

注意：Hooks 是 TUI 运行时功能——codewhale exec无头模式和 CLI 子命令不会触发钩子。

权威参考文档见 docs/HOOKS.md，事件枚举定义在 crates/tui/src/hooks/config.rs。

二、快速上手：5 分钟配置第一个 session_start 钩子

打开（或新建）~/.codewhale/config.toml，加入下面这段即可——当 TUI 引擎就绪、首次界面渲染前，session_start钩子会触发一次：

[hooks] enabled = true [[hooks.hooks]] name = "announce" event = "session_start" command = "echo 'CodeWhale 会话已启动'"

配置完成后，在 TUI 中输入/hooks命令即可查看全部已注册的钩子、全局开关状态以及加载时被拒绝的条目；/hooks events则列出全部 11 个事件名，非常适合初学者探索（命令实现见 crates/tui/src/commands/groups/core/hooks.rs）。

三、三类事件全景：11 个事件按"能不能改变行为"分

CodeWhale 共提供 11 个钩子事件，按干预能力可归为三类：

1️⃣ 观察型（Observer）——只看不改

如session_start、session_end、tool_call_after、turn_end、on_error、subagent_spawn、subagent_complete、mode_change等。

它们的结果会被忽略：stdout 直接丢弃，非零退出码只记录警告。这类钩子适合打日志、发通知、推送告警——不能改变 CodeWhale 的后续行为，但可以产生任意外部副作用（它毕竟是以你的身份运行的命令）。

2️⃣ Pre 类——行动前拦截/改写

• tool_call_before（pre 工具调用）：在每次工具执行前触发，可输出 JSON 裁决——allow/deny/ask，还能用updatedInput改写工具入参、用additionalContext追加给模型的上下文
• message_submit（pre 消息提交）：在消息进入历史和模型之前，可替换或拦截你发送的文本（退出码2表示阻断）

3️⃣ Post / 环境注入类

• tool_call_after（post 工具调用）：工具结果落定后触发，适合审计与统计
• shell_env：在每次exec_shell前同步运行，把 stdout 按KEY=VALUE解析成环境变量注入——注入临时凭证、按技能调整 PATH 的神器 🔑

四、实战：pre/post 钩子的三个高频用法

用法 1：危险命令守门员（pre）

[[hooks.hooks]] name = "gate" event = "tool_call_before" command = "~/.codewhale/hooks/gate.sh" condition = { type = "tool_name", name = "exec_shell" } continue_on_error = false

gate.sh检查$DEEPSEEK_TOOL_ARGS中的命令，想拦截就输出{"decision":"deny","reason":"原因"}。注意continue_on_error = false的语义：守门人没给出裁决，就不算放行——超时或异常退出会直接拒绝该工具调用。

用法 2：工具调用审计（post）

[[hooks.hooks]] event = "tool_call_after" command = "echo $DEEPSEEK_TOOL_NAME $DEEPSEEK_TOOL_EXIT_CODE >> ~/audit.log"

通过DEEPSEEK_TOOL_CALL_ID可以把同一次调用的 before/after/error 记录精确关联起来。

用法 3：临时凭证注入

[[hooks.hooks]] name = "aws-creds" event = "shell_env" command = "aws-vault export my-profile --format=env" condition = { type = "tool_category", category = "shell" }

解析后的键名（而非值）会写入~/.codewhale/audit.log，方便事后对账。

五、配置要点与避坑清单 ⚠️

完整字段示例可参考 config.example.toml 中被注释的[hooks]段落；执行器核心逻辑在 crates/tui/src/hooks/executor.rs，设计背景见 docs/rfcs/1364-hooks-lifecycle.md。

六、安全须知

• 钩子是来自你自己配置的可执行命令——请把~/.codewhale/config.toml当作可执行代码对待
• 钩子进程继承 CodeWhale 的完整环境，但本地exec_shell只拿到净化白名单 + 你的shell_env注入值
• 所有负载（工具参数、结果、错误信息）都有字节上限，钩子输入输出不可能无限复制对话内容

写在最后

Hooks 是 CodeWhale 从"能用"走向"合你心意"的关键开关：session_start打个招呼、tool_call_before守住边界、tool_call_after留好审计痕迹——三层防线，全在你的一条 TOML 配置里。更多细节欢迎通读 docs/HOOKS.md，它是逐事件契约的权威出处。

【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale