Hook 钩子

Hook 的定位

Hook 是 Agent 生命周期的可编程切入点。在"Agent 默认行为"之外，系统允许在 28 个关键事件点注入自定义逻辑——不改平台代码，就能改 Agent 行为。

Hook 与 Event Trigger 的区别

对比维度	Event Trigger	Hook
触发源	外部事件（webhook / cron / channel 消息）	内部事件（Agent 生命周期）
典型场景	"PR 来了做什么"	"每次 Agent 发消息前校验一下"
范围	跨 Session	可以是 Session 内也可以跨 Session
目的	启动 / 触发 Agent	改变 Agent 内部行为

28 个 Hook 事件

按生命周期阶段分类：

会话层

事件	触发时机
`SessionStart`	Session 创建
`SessionStop`	Session 结束
`SessionArchive`	Session 归档

Agent 层

事件	触发时机
`AgentInit`	Agent 初始化
`AgentStep`	Agent 每推进一步
`AgentFinish`	Agent 完成任务

消息层

事件	触发时机
`PreUserMessage`	用户消息进入之前
`PostUserMessage`	用户消息处理完
`PreAssistantMessage`	Agent 发出消息之前
`PostAssistantMessage`	Agent 消息发出后

工具层

事件	触发时机
`PreToolUse`	工具调用前（阻断式）
`PostToolUse`	工具调用后
`ToolError`	工具调用失败

记忆层

事件	触发时机
`MemoryRetrieve`	记忆检索
`MemoryGuardian`	记忆守护（自动监控）
`MemoryPromote`	KB → LTM 提升

技能层

事件	触发时机
`SkillInjector`	按上下文匹配技能
`SkillActivate`	技能激活
`SkillComplete`	技能完成

完整 28 事件清单见 AgentFlow/src/hooks/ 源码。

5 种 Handler 类型

同一 Hook 事件可以挂多个 Handler，按优先级串联执行：

Handler	执行方式	适用
command	执行 shell 命令	本地脚本、通知、日志
http	调用 HTTP 端点	接入外部系统
prompt	注入 / 修改 LLM prompt	引导 Agent 行为
agent	触发另一个 Agent	多 Agent 协作
python	执行内嵌 Python	复杂逻辑

阻断式前置钩子

PreToolUse 等 Pre 类钩子是阻断式的——如果 Handler 返回 block，原操作会被拒绝。

典型用法：

# 示例：工具调用前的安全审计
hooks:
  - event: PreToolUse
    handler:
      type: python
      code: |
        if tool_name == "execute_code" and "rm -rf" in tool_args.get("code", ""):
            return {"action": "block", "reason": "禁止删除命令"}
        return {"action": "allow"}