# 高级用法：钩子协议

> **权威来源**：[钩子协议设计](https://github.com/Athenavi/chiron/blob/master/docs/hook-protocol-design.md)（追平 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 | 上下文注入 | **待拍板** |

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

## 延伸阅读

- [安全与护栏](Advanced-Guardrails.md) · [工具与审批](Core-Tools.md)
- [会话](Core-Sessions.md) —— 挂载点挂在会话运行状态上

---

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