Gajae-Code Hooks钩子完全指南：pre_tool_use/post_tool_use等6种事件拦截机制详解

Gajae-Code Hooks钩子完全指南：pre_tool_use/post_tool_use等6种事件拦截机制详解

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code

Gajae-Code 是运行在你已有编程订阅上的外部编码代理（coding agent）框架，它的Hooks 钩子系统允许你在代理生命周期的 6 个关键节点注入自定义逻辑：拦截工具调用、改写工具结果、监听会话启停。本文面向新手，用最少代码讲清pre_tool_use、post_tool_use等全部 6 种事件的触发时机、执行契约与安全边界，并给出官方示例钩子的完整安装路径，帮你快速上手 Gajae-Code 钩子配置。

一、什么是 Hooks：给编码代理装"安全阀"

想象 AI 代理在替你执行 Bash 命令、编辑文件——如果它跑偏了怎么办？Gajae-Code 钩子（Hooks）就是你在关键节点设置的"检查站"：

• 工具执行前：审查命令，危险则直接拦截（fail closed，工具不会执行）；
• 工具执行后：检查并改写返回结果（截断超长输出、替换敏感内容）；
• 会话开始/结束：初始化环境或清理资源。

与某些产品"写一段 shell 脚本"不同，Gajae-Code 的目录钩子是TypeScript 模块，通过 Bunimport()加载，能拿到完整的进程内HookAPI，能力更强也更安全。

二、6种钩子事件一览表

Gajae-Code 将各运行时的事件统一归一化为6 个标准事件名（定义见 packages/coding-agent/src/hooks/events.ts），这是新手最需要记住的一张表：

💡 官方文档中特别指出：turn_end（每轮触发）被刻意拒绝归一化为stop（每次代理循环触发一次），避免静默改变调用次数——这种"语义严格"正是 Gajae-Code 钩子契约的设计哲学，详见 docs/hooks.md。

三、最快配置方法：两步安装目录钩子

3.1 钩子文件放在哪

Gajae-Code 按两个路径自动发现钩子模块：

文件名对应工具名，例如pre/bash.ts只会在Bash 工具调用前触发。

3.2 一个最小可用的 pre_tool_use 钩子

官方仓库自带可直接参考的示例，位于 docs/examples/gjc-hooks/pre/。其核心结构（摘自 docs/examples/gjc-hooks/pre/bash.ts）：

export default function registerPrPreflight(api: HookApi): void { api.on("tool_call", async event => { if (event.toolName !== "bash") return; // 只关注 Bash 工具 // ……审查 event.input.command，危险则： return { block: true, reason: "PR preflight failed." }; }); }

把选中的示例文件复制到.gjc/hooks/pre/bash.ts即完成安装。⚠️ 注意：不要同时安装两个官方 Bash 示例到同一路径，按项目需要二选一，或把两套逻辑合并进一个评审过的本地钩子。

四、pre_tool_use 深度解析：如何拦截工具调用

pre_tool_use是最常用的"守门员"事件，它的执行契约非常关键（新手最容易踩坑）：

• 串行执行、逐个等待，无超时限制；
• 错误即拦截（fail closed）：钩子抛错会导致工具调用被阻止，而不是静默放行；
• 第一个返回{ block: true }的钩子会终止后续处理——拦截理由会直接呈现给用户。

官方示例展示了两种真实场景：

1. PR 前置检查（docs/examples/gjc-hooks/pre/bash.ts）：当代理尝试执行gh pr create时，自动运行仓库验证脚本，不通过则拦截提交；
2. HOL Guard 命令预检（docs/examples/gjc-hooks/pre/bash-hol-guard.ts）：把外部 Guard 策略接入 Bash 调用，任何超时、CLI 失败、需要人工审查的命令一律拦截，并带超时清理与强制终止的有界宽限期。

五、post_tool_use 深度解析：改写工具结果

post_tool_use在工具成功执行后触发，与"守门员"相反，它是"质检员"：

典型用法：把超长ls输出压缩成结构化摘要、把敏感凭证从结果中脱敏、给失败结果补充人类可读的解释。下图来自仓库的会话统计脚本输出，直观展示了钩子监控工具调用场景下的调用量数据形态：

六、其余4种事件速览与 Codex 托管钩子

• user_prompt_submit：最接近"提示提交"的重叠事件，可返回消息注入上下文。注意它对应进程内before_agent_start回调，并非逐字节兼容其他产品的同名事件；
• stop：对应进程内agent_end（代理循环结束），适合发完成通知；
• session_start/session_shutdown：无插件/命令等价物，由 GJC 进程内直接派发；session_shutdown会等待处理器完成，不是发后即忘。

若你同时使用 Codex，gjc setup hooks会向~/.codex/hooks.json合并托管UserPromptSubmit与Stop两条入口，由 Codex 负责调度与超时，GJC 只处理命令载荷——调度、日志等字段标记为provider-owned，不会被误猜。

七、安全边界：新手必读的3条铁律 🛡️

1. 钩子代码=可信代码：项目目录钩子加载时即作为代码执行，当前没有独立的工作区信任提示，安装第三方钩子前务必审查源码；
2. 插件钩子不是沙箱：分发包插件只能注册受限形状（如tool_call必须带 target 和 before/after 阶段），exec、sendMessage、命令注册等调用会直接抛出security_policy，但它仍是宿主进程内的模块，保留环境全局能力；
3. 插件不支持别名：pre_tool_use、UserPromptSubmit等别名在插件清单中会被拒绝，只有目录钩子和进程内 API 使用标准名。

完整的事件契约表（超时、错误行为、取消/改写能力）以 packages/coding-agent/src/hooks/events.ts 中的CONVENTION_EVENT_CONTRACTS为准，规范文档见 docs/hooks.md。

八、常见问题 FAQ

Q：钩子和插件的区别？目录钩子（.gjc/hooks/）拿到完整进程内HookAPI，适合项目私有逻辑；插件钩子走受限 GJC API，适合随分发包分发，两者统一由ExtensionRunner执行。

Q：拦截后会发生什么？pre_tool_use返回{ block: true, reason }后，工具不会执行，理由会展示给模型/用户，代理会基于拦截信息调整下一步。

Q：钩子写错了会影响正常使用吗？pre_tool_use出错会 fail closed（拦截工具）；post_tool_use与生命周期事件出错则被隔离，不影响主流程——所以"写错前钩子"比"写错后钩子"风险更高，建议先用小项目验证。

总结

Gajae-Code 的 Hooks 系统用6 个标准事件名统一了目录钩子、插件钩子与托管命令钩子：pre_tool_use负责"事前拦截"，post_tool_use负责"事后质检"，加上user_prompt_submit、stop、session_start、session_shutdown覆盖完整会话生命周期。上手只需三步：创建.gjc/hooks/pre/目录、参考 官方示例 复制一个钩子模块、按block/ 改写契约编写逻辑——即可为你的编码代理装上一套可审查、可拦截、可扩展的安全阀。

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code