Gajae-Code Hooks钩子完全指南pre_tool_use/post_tool_use等6种事件拦截机制详解【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-codeGajae-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这是新手最需要记住的一张表事件名触发时机核心能力典型用途pre_tool_use工具调用执行前可返回{ block: true }拦截拦截危险 Bash 命令、PR 前置检查post_tool_use工具结果返回后可改写content、details、isError清洗/压缩工具输出user_prompt_submit用户提交提示后、代理启动前可注入消息、调整 systemPrompt自动附加上下文stop代理循环结束时仅观测收尾通知、日志归档session_start会话开始时仅观测初始化埋点、环境检查session_shutdown会话关闭时仅观测会被等待清理资源 官方文档中特别指出turn_end每轮触发被刻意拒绝归一化为stop每次代理循环触发一次避免静默改变调用次数——这种语义严格正是 Gajae-Code 钩子契约的设计哲学详见 docs/hooks.md。三、最快配置方法两步安装目录钩子3.1 钩子文件放在哪Gajae-Code 按两个路径自动发现钩子模块作用域路径说明用户全局~/.gjc/hooks/pre/与~/.gjc/hooks/post/所有项目生效项目级仓库内.gjc/hooks/pre/与.gjc/hooks/post/仅当前项目生效可随仓库分发文件名对应工具名例如pre/bash.ts只会在Bash 工具调用前触发。3.2 一个最小可用的 pre_tool_use 钩子官方仓库自带可直接参考的示例位于 docs/examples/gjc-hooks/pre/。其核心结构摘自 docs/examples/gjc-hooks/pre/bash.tsexport 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 }的钩子会终止后续处理——拦截理由会直接呈现给用户。官方示例展示了两种真实场景PR 前置检查docs/examples/gjc-hooks/pre/bash.ts当代理尝试执行gh pr create时自动运行仓库验证脚本不通过则拦截提交HOL Guard 命令预检docs/examples/gjc-hooks/pre/bash-hol-guard.ts把外部 Guard 策略接入 Bash 调用任何超时、CLI 失败、需要人工审查的命令一律拦截并带超时清理与强制终止的有界宽限期。五、post_tool_use 深度解析改写工具结果post_tool_use在工具成功执行后触发与守门员相反它是质检员维度契约超时30 秒超时/错误被隔离不影响主流程可改写字段content结果正文、details、isError链式传递多个钩子按注册顺序接力改写后一个看到的是前一个的替换结果典型用法把超长ls输出压缩成结构化摘要、把敏感凭证从结果中脱敏、给失败结果补充人类可读的解释。下图来自仓库的会话统计脚本输出直观展示了钩子监控工具调用场景下的调用量数据形态六、其余4种事件速览与 Codex 托管钩子user_prompt_submit最接近提示提交的重叠事件可返回消息注入上下文。注意它对应进程内before_agent_start回调并非逐字节兼容其他产品的同名事件stop对应进程内agent_end代理循环结束适合发完成通知session_start/session_shutdown无插件/命令等价物由 GJC 进程内直接派发session_shutdown会等待处理器完成不是发后即忘。若你同时使用 Codexgjc setup hooks会向~/.codex/hooks.json合并托管UserPromptSubmit与Stop两条入口由 Codex 负责调度与超时GJC 只处理命令载荷——调度、日志等字段标记为provider-owned不会被误猜。七、安全边界新手必读的3条铁律 ️钩子代码可信代码项目目录钩子加载时即作为代码执行当前没有独立的工作区信任提示安装第三方钩子前务必审查源码插件钩子不是沙箱分发包插件只能注册受限形状如tool_call必须带 target 和 before/after 阶段exec、sendMessage、命令注册等调用会直接抛出security_policy但它仍是宿主进程内的模块保留环境全局能力插件不支持别名pre_tool_use、UserPromptSubmit等别名在插件清单中会被拒绝只有目录钩子和进程内 API 使用标准名。完整的事件契约表超时、错误行为、取消/改写能力以 packages/coding-agent/src/hooks/events.ts 中的CONVENTION_EVENT_CONTRACTS为准规范文档见 docs/hooks.md。八、常见问题 FAQQ钩子和插件的区别目录钩子.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-codeGajae-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这是新手最需要记住的一张表事件名触发时机核心能力典型用途pre_tool_use工具调用执行前可返回{ block: true }拦截拦截危险 Bash 命令、PR 前置检查post_tool_use工具结果返回后可改写content、details、isError清洗/压缩工具输出user_prompt_submit用户提交提示后、代理启动前可注入消息、调整 systemPrompt自动附加上下文stop代理循环结束时仅观测收尾通知、日志归档session_start会话开始时仅观测初始化埋点、环境检查session_shutdown会话关闭时仅观测会被等待清理资源 官方文档中特别指出turn_end每轮触发被刻意拒绝归一化为stop每次代理循环触发一次避免静默改变调用次数——这种语义严格正是 Gajae-Code 钩子契约的设计哲学详见 docs/hooks.md。三、最快配置方法两步安装目录钩子3.1 钩子文件放在哪Gajae-Code 按两个路径自动发现钩子模块作用域路径说明用户全局~/.gjc/hooks/pre/与~/.gjc/hooks/post/所有项目生效项目级仓库内.gjc/hooks/pre/与.gjc/hooks/post/仅当前项目生效可随仓库分发文件名对应工具名例如pre/bash.ts只会在Bash 工具调用前触发。3.2 一个最小可用的 pre_tool_use 钩子官方仓库自带可直接参考的示例位于 docs/examples/gjc-hooks/pre/。其核心结构摘自 docs/examples/gjc-hooks/pre/bash.tsexport 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 }的钩子会终止后续处理——拦截理由会直接呈现给用户。官方示例展示了两种真实场景PR 前置检查docs/examples/gjc-hooks/pre/bash.ts当代理尝试执行gh pr create时自动运行仓库验证脚本不通过则拦截提交HOL Guard 命令预检docs/examples/gjc-hooks/pre/bash-hol-guard.ts把外部 Guard 策略接入 Bash 调用任何超时、CLI 失败、需要人工审查的命令一律拦截并带超时清理与强制终止的有界宽限期。五、post_tool_use 深度解析改写工具结果post_tool_use在工具成功执行后触发与守门员相反它是质检员维度契约超时30 秒超时/错误被隔离不影响主流程可改写字段content结果正文、details、isError链式传递多个钩子按注册顺序接力改写后一个看到的是前一个的替换结果典型用法把超长ls输出压缩成结构化摘要、把敏感凭证从结果中脱敏、给失败结果补充人类可读的解释。下图来自仓库的会话统计脚本输出直观展示了钩子监控工具调用场景下的调用量数据形态六、其余4种事件速览与 Codex 托管钩子user_prompt_submit最接近提示提交的重叠事件可返回消息注入上下文。注意它对应进程内before_agent_start回调并非逐字节兼容其他产品的同名事件stop对应进程内agent_end代理循环结束适合发完成通知session_start/session_shutdown无插件/命令等价物由 GJC 进程内直接派发session_shutdown会等待处理器完成不是发后即忘。若你同时使用 Codexgjc setup hooks会向~/.codex/hooks.json合并托管UserPromptSubmit与Stop两条入口由 Codex 负责调度与超时GJC 只处理命令载荷——调度、日志等字段标记为provider-owned不会被误猜。七、安全边界新手必读的3条铁律 ️钩子代码可信代码项目目录钩子加载时即作为代码执行当前没有独立的工作区信任提示安装第三方钩子前务必审查源码插件钩子不是沙箱分发包插件只能注册受限形状如tool_call必须带 target 和 before/after 阶段exec、sendMessage、命令注册等调用会直接抛出security_policy但它仍是宿主进程内的模块保留环境全局能力插件不支持别名pre_tool_use、UserPromptSubmit等别名在插件清单中会被拒绝只有目录钩子和进程内 API 使用标准名。完整的事件契约表超时、错误行为、取消/改写能力以 packages/coding-agent/src/hooks/events.ts 中的CONVENTION_EVENT_CONTRACTS为准规范文档见 docs/hooks.md。八、常见问题 FAQQ钩子和插件的区别目录钩子.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考