Advanced Hooks

高级用法：钩子协议

权威来源：钩子协议设计（追平 DSH 的钩子协议）。 状态：批次 1 / 2a 已落地；批次 2b（command）/ 3（webhook）/ 4（上下文注入）待拍板。

钩子是什么

在 agent 循环的固定挂载点上插入外部逻辑：审计、拦截、注入上下文、通知外部系统。 对标项目的钩子是进程内 TS 插件树；Chiron 走协议 + 多租户隔离，不做进程内插件。

代码在哪

python-engine/app/hooks/
  manager.py   生命周期与挂载点管理
  runner.py    执行（含超时/失败策略）
  config.py    配置与启用开关
  events.py    事件定义
  audit.py     审计流水（带 tenant/user/session 维度）

设计上的几个关键取舍

1. 挂载点是显式清单，不是"任何地方都能插" —— 落地前先出事件清单与执行边界设计。
2. 钩子失败不拖垮主流程：策略（忽略 / 记录 / 阻断）要显式声明，不能靠默认行为。
3. 审计与钩子分开：audit.py 的流水是证据，不随钩子开关关闭。
4. 不引新依赖：协议设计的目标是"把已经写对的东西变成类型/测试/文档"，不是引入框架。

待拍板的批次

批次	形态	状态
1 · 2a	协议与基础挂载	已落地
2b	command 类钩子	待拍板
3	webhook 类钩子	待拍板
4	上下文注入	待拍板

拍板前不宜先写实现 —— 因为这三批会扩大可执行面，属于产品决定。

延伸阅读

• 安全与护栏 · 工具与审批
• 会话 —— 挂载点挂在会话运行状态上

---

本页由仓库内 docs/wiki/ 同步生成（scripts/sync_github_wiki.py）。请不要直接编辑本 wiki —— 改动会下次同步时被覆盖；请改仓库里的对应文件。