03 Permission System → 04 Hook System

Hook System

挂在循环上的扩展点 — 像墙壁上的插座一样优雅

🧱

墙壁 = Agent Loop

主循环是承重墙,结构稳定不动

🔌

插座 = Hook 点

预先埋好的接口,随时可以接入

💡

插头 = 你的函数

插入即生效,拔出不留痕迹

你不需要拆墙重装来加一盏灯。Hook System 让你在不修改核心循环的情况下,
像插电器一样"挂上"新功能。

1 核心理念

「挂在循环上,不写进循环里」

这句话是 Hook System 的灵魂。想象一下:如果每次想加日志、加权限检查都要改 Agent Loop 的源代码, 那代码会膨胀成什么样?开闭原则(Open-Closed Principle)告诉我们: 对扩展开放,对修改关闭。

Hook 不是"侵入式"的代码注入。它是声明式的扩展点——循环说"我在这里留了个插座", 你说"我要接一个灯"。循环本身完全不知道你接了什么。
❌ 错误做法 # 把日志逻辑直接塞进循环里 while True: user_input = get_input() log(f"收到输入: {user_input}") # ❌ 硬编码 if need_permission(tool): check_perm(tool) # ❌ 又一个硬编码 result = llm.run(user_input)
✅ Hook 做法 # 循环保持干净,扩展通过 Hook 挂载 while True: user_input = get_input() registry.trigger("UserPromptSubmit", user_input) result = llm.run(user_input) # 日志、权限、监控……全部由 Hook 处理
2 四大核心事件

Agent 循环的四个关键节点,每个都是一个 Hook 插座

📝

UserPromptSubmit

用户输入后
LLM 处理前

→
🔧

PreToolUse

工具调用前
可以拦截/审批

→
📊

PostToolUse

工具执行后
可以记录/修改

→
🛑

Stop

循环即将结束
可强制继续

📝

UserPromptSubmit — 用户输入拦截

▼

在用户的输入发送给 LLM 之前触发。你可以用来:

  • 过滤敏感词或注入攻击
  • 自动补充上下文信息
  • 记录用户输入用于分析
返回非 None 字符串可以阻断后续执行,相当于"拒绝这次输入"。
🔧

PreToolUse — 工具调用前拦截

▼

在 LLM 决定调用某个工具、但还没执行之前触发。这是权限系统的核心挂载点:

  • 检查权限:这个工具允许调用吗?
  • 参数校验:参数合理吗?
  • 审计日志:谁在什么时候调了什么?
返回非 None 字符串会阻止工具执行,LLM 会收到你的拒绝信息。
📊

PostToolUse — 工具执行后处理

▼

工具执行完成之后触发,你可以拿到工具的返回结果:

  • 记录工具执行结果
  • 检测异常输出并告警
  • 自动触发后续操作(如 git add)
PostToolUse 的返回值不会阻止执行(工具已经跑了),但可以影响后续流程。
🛑

Stop — 循环结束前的最后机会

▼

当 LLM 认为任务完成、准备结束循环时触发:

  • 生成会话摘要
  • 检查是否真的完成了(未完成可强制继续)
  • 清理临时资源
返回非 None 字符串会强制循环继续,相当于对 LLM 说"还没完呢!"
3 HookRegistry 详解

注册表 — 管理所有 Hook 的中央枢纽

Python class HookCallback: def __init__(self, callback, name, priority, description): self.callback = callback # 实际要执行的函数 self.name = name # Hook 的唯一名称 self.priority = priority # 优先级,数字越大越先执行 self.description = description # 人类可读的描述 class HookRegistry: def __init__(self): self._hooks = {} # {event_name: [HookCallback, ...]} def register(self, event, callback, name, priority=0, description=""): # 注册一个 Hook 到指定事件 hook = HookCallback(callback, name, priority, description) self._hooks.setdefault(event, []).append(hook) self._hooks[event].sort(key=lambda h: -h.priority) # 降序排列 def trigger(self, event, *args, **kwargs): # 触发事件,依次执行所有注册的 Hook for hook in self._hooks.get(event, []): try: result = hook.callback(*args, **kwargs) if result is not None: return result # 非 None → 停止传播 except Exception as e: log_error(f"Hook '{hook.name}' failed: {e}") # 错误隔离:一个 Hook 失败不影响其他 return None # 所有 Hook 正常执行完毕
Priority(优先级)是关键设计:数字越大,越先执行。这意味着权限检查(高优先级)总是在日志记录(低优先级)之前运行。
Error Isolation(错误隔离):每个 Hook 都在 try-except 中执行。一个 Hook 崩了,其他 Hook 继续正常工作。这保证了系统的健壮性。
4 返回值语义

Hook 的返回值决定了"继续"还是"拦截"

return None

什么都不返回(或显式返回 None)

✅ 继续执行下一个 Hook → 正常流程
return "reason"

返回一个字符串(拦截原因)

🛑 停止传播 → 拦截/阻断/强制继续
示例 # 权限检查 Hook — 返回 None 表示放行 def check_permission(tool_name, **kwargs): if tool_name in BLOCKED_TOOLS: return f"⛔ 工具 '{tool_name}' 被禁止使用" # 拦截! return None # 放行,继续执行下一个 Hook # Stop 事件中 — 返回非 None 强制循环继续 def force_continue(messages, **kwargs): if not task_completed(messages): return "任务还没完成,请继续工作" # 强制继续! return None # 确认完成,允许循环结束
5 五个实战示例

从权限检查到自动 git add,看 Hook 如何在真实场景中发挥作用

🔐

示例 1:权限检查 Hook

▼

挂载在 PreToolUse 事件上,在工具执行前检查权限:

def permission_hook(tool_name, tool_input, **kwargs): if tool_name == "run_command": cmd = tool_input.get("command", "") if "rm -rf /" in cmd: return "⛔ 危险命令被拦截:不允许删除根目录" return None registry.register("PreToolUse", permission_hook, "safety-check", priority=100)
priority=100 确保安全检查在所有其他 Hook 之前执行。
📋

示例 2:操作日志 Hook

▼

挂载在 PostToolUse 上,记录每次工具调用的详情:

def logging_hook(tool_name, tool_input, result, **kwargs): log({ "tool": tool_name, "input": tool_input, "output_len": len(str(result)), "timestamp": now() }) return None registry.register("PostToolUse", logging_hook, "audit-log", priority=10)
priority=10 较低,确保日志记录在所有重要操作之后执行。
⚠️

示例 3:大输出告警 Hook

▼

当工具返回的内容过长时发出警告,防止 Token 浪费:

def large_output_hook(tool_name, result, **kwargs): if len(str(result)) > 10000: warn(f"⚠️ '{tool_name}' 返回了超大输出") # 可以截断或添加摘要 return None registry.register("PostToolUse", large_output_hook, "output-guard", priority=50)
📦

示例 4:自动 Git Add Hook

▼

每次写文件后自动 git add,保持版本控制同步:

def auto_git_add(tool_name, tool_input, **kwargs): if tool_name == "write_file": path = tool_input.get("path", "") if path: run(f"git add {path}") return None registry.register("PostToolUse", auto_git_add, "git-auto", priority=20)
📝

示例 5:会话摘要 Hook

▼

在循环结束时自动生成会话摘要:

def session_summary(messages, **kwargs): summary = generate_summary(messages) save_to_file("session_log.md", summary) print(f"📋 会话摘要已保存") return None # 允许循环正常结束 registry.register("Stop", session_summary, "summary", priority=0)
6 自定义 Hook 三步走

从零开始创建你自己的 Hook

定义回调函数

写一个函数,接收事件相关的参数,返回 None(放行)或字符串(拦截):

def my_hook(tool_name, tool_input, **kwargs): print(f"🔧 正在调用: {tool_name}") return None

注册到 Registry

选择事件、设置名称和优先级:

registry.register( event="PreToolUse", # 挂在哪个事件上 callback=my_hook, # 你的函数 name="my-custom-hook", # 唯一名称 priority=50, # 越大越先执行 description="我的自定义 Hook" )

测试验证

触发事件,确认 Hook 行为符合预期:

# 触发 PreToolUse 事件,观察你的 Hook 是否被执行 result = registry.trigger("PreToolUse", "read_file", {"path": "test.py"}) print(f"返回值: {result}") # None = 放行
建议在开发阶段给 Hook 加上详细日志,方便调试。
7 知识测验

测试你对 Hook System 的理解

问题 1 / 5

Hook System 的核心设计原则是什么?
A. 把所有扩展逻辑直接写进 Agent Loop
B. 对扩展开放,对修改关闭(开闭原则)
C. 所有 Hook 必须在启动时一次性注册完毕
D. Hook 只能用于日志记录
✅ 正确!Hook System 体现了开闭原则:循环代码不修改,通过 Hook 扩展功能。
❌ 再想想。关键在于「挂在循环上,不写进循环里」——这是开闭原则的体现。

问题 2 / 5

当 Hook 返回一个非 None 字符串时,会发生什么?
A. 什么都不发生,继续执行下一个 Hook
B. 停止传播,后续 Hook 不再执行,返回值作为拦截原因
C. 抛出异常,Agent 循环崩溃
D. 自动重试当前 Hook
✅ 正确!非 None 返回值会停止传播,这就是"拦截"机制的核心。
❌ 非 None 返回值是"停止信号"——它阻止后续 Hook 执行,并将返回值作为拦截原因传递。

问题 3 / 5

哪个事件可以用来阻止工具的执行?
A. UserPromptSubmit
B. PreToolUse
C. PostToolUse
D. Stop
✅ 正确!PreToolUse 在工具执行之前触发,是拦截工具调用的最佳时机。
❌ 想想哪个事件发生在工具"执行之前"?只有 PreToolUse 能在工具还没跑时拦截它。

问题 4 / 5

Hook 的 priority(优先级)如何影响执行顺序?
A. 数字越小越先执行
B. 数字越大越先执行
C. 按注册时间顺序执行
D. 随机顺序执行
✅ 正确!优先级降序排列,priority 越大越先执行。这确保了安全检查等关键操作优先运行。
❌ 代码中使用 sort(key=lambda h: -h.priority),负号意味着降序——数字越大越靠前。

问题 5 / 5

一个 Hook 抛出异常时,会发生什么?
A. 整个 Agent 循环崩溃
B. 异常被捕获并记录,其他 Hook 继续正常执行
C. 自动跳过所有后续 Hook
D. 自动重试该 Hook
✅ 正确!这就是错误隔离机制——每个 Hook 都在 try-except 中执行,一个失败不影响其他。
❌ HookRegistry 对每个 Hook 都做了 try-except 包裹,异常被记录但不会传播,其他 Hook 照常执行。
8 深入探索

进阶话题,想深入的同学请展开阅读

🔄

深度 1:为什么不能在同一个事件的 Hook 里触发同一事件?

▼

这叫做循环依赖(Circular Dependency)。想象一下:

⚠️ 死循环陷阱

Hook A 挂在 PreToolUse 上 → A 的逻辑又触发了 PreToolUse → 又触发 A → 无限递归 → 栈溢出!

# ❌ 绝对不要这样做! def bad_hook(tool_name, **kwargs): # 在 PreToolUse Hook 里触发 PreToolUse → 死循环! registry.trigger("PreToolUse", "some_tool", {}) # 💥 return None

解决方案:

  • 使用标志位检测重入
  • 确保 Hook 内部只触发不同的事件
  • 在 Registry 层面添加重入检测
⚡

深度 2:Hook 的性能考量

▼

Hook 在主循环的关键路径上执行,慢 Hook = 慢 Agent:

⚠️ 性能陷阱

在 PreToolUse Hook 里做网络请求、数据库查询、大文件读写……这些都会阻塞 Agent 的响应速度。

最佳实践:

  • Hook 内逻辑尽量同步且快速
  • 需要 I/O 操作?使用异步 Hook或后台队列
  • 监控每个 Hook 的执行时间,设置超时
  • 低优先级 Hook 考虑延迟执行
🏗️

深度 3:Hook 与插件系统的关系

▼

Hook System 是插件系统的基础设施。插件本质上就是一组 Hook 的打包:

class MyPlugin: def setup(self, registry): # 一个插件可以注册多个 Hook registry.register("PreToolUse", self.check, "my-check", priority=80) registry.register("PostToolUse", self.log, "my-log", priority=10) registry.register("Stop", self.cleanup, "my-cleanup") def teardown(self, registry): # 插件卸载时移除所有 Hook registry.unregister("my-check") registry.unregister("my-log") registry.unregister("my-cleanup")
插件 = Hook 的生命周期管理 + 配置 + 依赖声明。理解了 Hook,就理解了插件的本质。
🧪

深度 4:测试 Hook 的策略

▼

Hook 是纯函数(输入 → 输出),天然适合单元测试:

def test_permission_hook_blocks_dangerous_command(): result = permission_hook("run_command", {"command": "rm -rf /"}) assert result is not None # 应该被拦截 assert "禁止" in result def test_permission_hook_allows_safe_command(): result = permission_hook("read_file", {"path": "test.py"}) assert result is None # 应该放行
测试时不需要真实的 Registry,直接调用函数即可。集成测试时再用 Registry 验证优先级和传播。
9 总结

回顾 Hook System 的核心要点

🧱 Hook System 知识图谱

🔗 模块连接

← 上一模块: 03 Permission System — Hook System 的 PreToolUse 事件是权限系统的天然挂载点。

→ 下一模块: 05 Planning System — 规划系统利用 Hook 监控任务执行进度。