Hook System - 主循环扩展机制

Hook 与 Permission 的区别#

很多人混淆 Hook 和 Permission：

核心区别：

• Permission：判断”能不能执行”——安全决策。
• Hook：扩展”执行前后做什么”——行为插入。

执行顺序：Permission 先检查，Hook 后触发。

Permission 通过后才触发 Hook。Hook 无法绕过 Permission——安全高于扩展。

Hook 管道代码#

1
def run_hooks(event_name: str, payload: dict) -> dict:
2
    for handler in HOOKS.get(event_name, []):
3
        result = handler(payload)
4
        if result["exit_code"] in (1, 2):  # 阻止或补充
5
            return result
6
    return {"exit_code": 0, "message": ""}  # 正常继续

关键点：HookRunner 统一调度——遍历 handlers，遇到阻止或补充就返回，否则继续下一个。

验证你的理解#

Q1：Hook 可以绕过 Permission 直接执行工具吗？

:::details 答案 不可以。Permission 先检查，Hook 后触发。

执行顺序：tool_use → Permission 检查 → Hook PreToolUse → 执行工具 → Hook PostToolUse。

Permission 是安全层，Hook 是扩展层。安全高于扩展——Permission deny 后，Hook 不会触发。

这是设计决策：安全判断优先于行为插入。Hook 不能绕过 Permission，否则安全边界失效。 :::

SessionStart：会话初始化#

1
event = {
2
    "name": "SessionStart",
3
    "payload": {
4
        "session_id": "abc123",
5
        "user_input": "帮我分析这个项目",
6
    },
7
}

用途：

• 加载用户配置
• 初始化 SkillLoader
• 设置会话上下文

特点：只在会话开始触发一次，后续不再触发。

PreToolUse：工具执行前#

1
event = {
2
    "name": "PreToolUse",
3
    "payload": {
4
        "tool_name": "bash",
5
        "input": {"command": "pytest"},
6
    },
7
}

用途：

• 拦截危险操作（exit_code=1）
• 补充上下文信息（exit_code=2）
• 记录审计日志

特点：每次工具执行前触发，可以阻止执行。

PostToolUse：工具执行后#

1
event = {
2
    "name": "PostToolUse",
3
    "payload": {
4
        "tool_name": "bash",
5
        "input": {"command": "pytest"},
6
        "output": "5 tests passed",
7
    },
8
}

用途：

• 处理执行结果
• 补充说明（exit_code=2）
• 记录审计日志

特点：每次工具执行后触发，不能阻止（已执行），只能补充。

验证你的理解#

Q2：PostToolUse 的 exit_code=1（阻止）有意义吗？

:::details 答案 没有意义。工具已执行，无法阻止。

PostToolUse 在工具执行后触发——结果已产生，文件已修改，命令已运行。此时”阻止”没有意义。

PostToolUse 的返回协议：

• exit_code=0：正常结束
• exit_code=1：阻止（无意义，不使用）
• exit_code=2：补充说明

设计决策：PostToolUse 只用 exit_code=0 和 exit_code=2，不用 exit_code=1。 :::

exit_code=0：正常继续#

1
result = {"exit_code": 0, "message": ""}

含义：Hook 不干预，主循环继续正常流程。

适用场景：观察、日志记录、审计。

exit_code=1：阻止动作#

1
result = {"exit_code": 1, "message": "Dangerous command blocked"}

含义：阻止工具执行，返回拒绝原因。

适用场景：PreToolUse 拦截危险操作。

执行流程：

1
PreToolUse → exit_code=1 → 阻止工具执行 → 返回拒绝原因给模型

exit_code=2：注入补充#

1
result = {"exit_code": 2, "message": "Remember to check test coverage"}

含义：注入补充消息给模型，再继续执行。

适用场景：PreToolUse 补充上下文，PostToolUse 补充说明。

执行流程：

1
PreToolUse → exit_code=2 → 注入消息 → 继续执行工具
2
PostToolUse → exit_code=2 → 追加说明 → 返回给模型

验证你的理解#

Q3：exit_code=2 和 exit_code=0 的区别是什么？

:::details 答案 exit_code=0 不注入消息，exit_code=2 注入补充消息。

exit_code=0：Hook 不干预，主循环继续正常流程。模型看不到 Hook 的存在。

exit_code=2：Hook 注入消息给模型，模型收到额外信息后再继续。消息可以是提示、警告、补充上下文。

场景差异：

• exit_code=0：观察、日志记录、审计（模型不需要知道）
• exit_code=2：补充上下文、提醒模型（模型需要知道）

例如：PreToolUse 检测到 pytest 命令，exit_code=2 注入 “记得检查覆盖率”，模型收到提示后再执行 pytest。 :::

与后续课程的关系#

理解 L08 后，你会发现后续课程都在 Hook System 上叠加——循环本身始终不变：

核心洞察：Hook System 是”主循环可扩展”的机制。理解 L08，就理解了 Agent 如何”不改主循环也能插入行为”。后续课程都在扩展 Hook 机制——记忆加载、团队协作、异步任务。

L08 核心概念的理解升级路径#

如何检验你达到了 L2？#

用这个问题自测：

如果要实现”每次 bash 执行后记录日志”，应该用什么 Hook？返回什么？

:::details L2 层级回答 使用 PostToolUse Hook，返回 exit_code=0。

设计：

1
def log_bash_handler(payload):
2
    tool_name = payload.get("tool_name")
3
    if tool_name != "bash":
4
        return {"exit_code": 0, "message": ""}
5

6
    command = payload["input"]["command"]
7
    output = payload["output"]
8
    write_log(f"[bash] {command} → {output}")
9

10
    return {"exit_code": 0, "message": ""}  # 正常继续

理由：

• PostToolUse 在工具执行后触发，适合记录结果
• exit_code=0 表示正常继续，不注入消息给模型
• 日志记录是观察行为，模型不需要知道

如果需要提醒模型”记得检查覆盖率”，应该用 exit_code=2 注入消息。 :::

本章目标：让每个核心概念都从 L0 升级到 L2。理解 L08，不只是记住三种事件，而是掌握”如何在循环上预留插口扩展行为”的设计原则。

Hook 执行流程#

Hook 与 Permission 关系#

三种事件时机#

统一返回协议#