agent hooks 装不上/不生效（仓库 setup 只做 git hooks）

你会遇到什么

按仓库文档跑完 setup，expect 的 agent hooks（如 pre-tool-call）却没有任何动静——工具调用前不触发、日志里也看不到。你重跑 setup 依然如此：因为 setup 安装的是 git hooks，不是 agent hooks——两者是不同事件系统里的注册，装完 git hooks 不等于 agent 生命周期事件被挂钩。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

先给结论：framework 仓库的 setup 任务只安装 git hooks，不提供 agent hooks 的安装途径（deftai/directive issue #3732，2026-08-25）。

链路：你跑 setup → 注册 git hooks（.git/hooks/ 下的 commit/checkout 等事件）→ agent 平台的工具调用事件（pre-tool-call 等）无人注册 → 不生效。断点：两类 hooks 的事件系统不同——git hooks 挂在 Git 操作上，agent hooks 挂在 agent 平台的生命周期事件上。

实测说明：本环境未实测 agent hooks 链路（如实标注）；判定依据 = 官方 setup 的实际行为（只做 git hooks）+ issue #3732 的样本。

推论：hooks 不生效先问「它注册在谁的事件系统里」：查 .git/hooks/ 有没有文件只是第一步，agent 侧还要按平台规范（MCP/扩展机制）单独注册配好。

一步步来

1. 区分两类 hooks — 必做

ls .git/hooks/ 看到的是 git hooks；agent hooks 不在这个目录——先在概念上分开。

2. 按 agent 平台注册 hooks — 必做

查对应平台（如支持 MCP/扩展的 agent）的 hooks 注册文档，把 framework 的 hook 入口配进去。

3. 重启会话验证 — 必做

注册后重启 agent 会话，触发一次工具调用，看 pre-tool-call 是否执行（日志/回调输出）。

4. 仍不生效 — 排查

核对 hook 可执行权限、入口路径、平台配置格式；带上平台与版本信息跟进 issue。

怎么确认修好了

• 工具调用前 hook 实际执行（日志可见）；
• git 侧行为不受影响（原有 git hooks 照常）。

其它环境的表现

• 不同 agent 平台的 hooks 注册机制差异大：按平台文档走，不要假设通用；
• 未实测说明：本环境未挂任何 agent 平台 hooks 链路，如实标注；

症状

按文档执行 setup 后 agent hooks（如 pre-tool-call 等）没有生效/无法安装。

原因

framework 仓库的 setup 任务只安装 git hooks，不提供 agent hooks 安装途径（demand 样本 #3732，2026-08-25）。

解法

1. 区分两类 hooks：git hooks（setup 装的）与 agent hooks（需按 agent 平台规范单独注册）。
2. 按对应 agent 平台（如 MCP/扩展机制）文档手工注册 hooks 配置。