顶级 AI Agent 是如何利用 Hook 解耦的

同一个循环膨胀到两百多行：日志、写文件确认、结果通知、自动备份全塞进来，变成谁也不敢改的 if-else 堆。问题不在需求太多，而在扩展行为和核心编排没有分开。Hook 就是在确定的位置发布结构化上下文，让已注册回调按顺序响应——循环只负责确定性编排。

HOOK_EVENTS 冻结元组同时定义运行时集合和 TS 类型。每个事件的 HookContext 只有自己需要的字段：Submit 只拿 user message；Pre 只拿已校验的 prepared；Post 拿 prepared + result；Stop 拿 history + stopHookActive。给 Pre 塞一条 message 会立即得到 HookContractError，而不是让回调猜。

export const HOOK_EVENTS = Object.freeze([
  "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop",
] as const);
export type HookEvent = (typeof HOOK_EVENTS)[number];

一个 "stop" 至少有四种可能的意思（拒绝本次调用 / 执行但别再问 / 整个 run 失败 / 别让 Stop 续跑），副作用完全不同。"stpo" 拼错了运行时只会当成「未知返回值」忽略——正在阻断危险写入的 Hook 静默失效。结构化 HookResult 每个字段只有一种语义，且只在特定事件合法，用 validateFor() 检查非法字段。

interface HookResultOptions {
  readonly permissionBehavior?: PermissionBehavior; // Pre 建议
  readonly updatedInput?: PreparedToolCall;          // Pre 改写参数
  readonly updatedOutput?: ToolResult;               // Post 改写结果
  readonly additionalContext?: readonly ChatMessage[];// 四类，只能 system
  readonly blockingError?: ToolResult;                // Pre 阻断
  readonly preventContinuation?: boolean;             // Post 本轮结束
  readonly forceContinue?: ChatMessage;               // Stop 续跑一次
}

每个事件独立回调列表；run() 对每个回调用 await，同步/异步都保持注册顺序。返回普通 object 不算合法 HookResult（运行时 instanceof 检查）。合并规则按字段分：

updatedInput / updatedOutput  后覆盖前   ← 流水线加工，后者看到前者产出
additionalContext            顺序拼接
preventContinuation          布尔 OR     ← 只要有一个要求停就停(更保守的赢)
permissionBehavior           deny>ask>allow>passthrough (更保守的赢)
Pre 遇 blockingError 立即短路后续 Pre 回调
Stop 第一次遇 forceContinue 后停止后续 Stop 回调

三个 Post Hook 依次注册，Hook 2 看到的是 Hook 1 的产出——想做「先脱敏、再截断」还是反过来，靠注册顺序。

User Prompt 刚提交、模型还没收到请求时触发。可以记录输入或增加 system context（如「本轮需要特别核对验收结果」）。run() 先运行 Hook，再按固定顺序写入历史。P04 不允许替换、删除或阻断原始 user message。

const submitted = userMessage(prompt);
const promptHook = await hooks.runUserPrompt(submitted);
history.push(submitted, ...promptHook.additionalContext);

工具已存在、参数已过 Zod，但权限尚未判断、handler 尚未运行。可补上下文、改写合法输入、提权限建议或返回结构化阻断错误。命中 blockingError 后权限和 handler 都不跑，Error [hook_blocked] 仍回填给原调用。

// 阻断写入受管理文件
if (argumentsValue.path === "generated.txt") {
  return new HookResult({ blockingError: toolError(
    "hook_blocked", "generated.txt is managed elsewhere") });
}

Pre Hook 返回 permissionBehavior: "allow"，Loop 不会直接执行，而是转成结构化建议（source 是 pre-tool-hook）传给 PermissionPolicy，第 3 章的硬边界、Shell 审批、固定规则仍一起合并。只要任一系统参与方 deny，Hook 的 allow 就不会触发审批或 handler。

Pre Hook → hard permission policy → approval → handler
// Hook 是扩展机制，不是第二套权限系统

在 handler 完成后、tool message 写入历史前运行。`context.result` 反映前一个 Post Hook 的产出；返回 updatedOutput 覆盖结果。handler 成功或返回结构化错误时运行 Post；Pre 阻断、permission deny、Pre Hook 异常时不运行 Post。

// 长输出截断
if (result === undefined || result.isError || result.content.length <= 100_000) {
  return new HookResult();
}
return new HookResult({ updatedOutput: toolSuccess(
  `\${result.content.slice(0, 100_000)}\n[truncated]`) });

Post Hook 要求停止时，Loop 不能直接 return——同一 assistant 消息可能还有其它 tool call，直接 return 会让它们成为孤儿，OpenAI 会拒绝、validateToolPairing 抛 missing tool results。

call-1 → 正常执行并触发停止
call-2 → Error [hook_stopped_continuation]: Skipped after PostToolUse ...
call-3 → Error [hook_stopped_continuation]: ...
先写入全部三个 tool result，再以 call-1 的结果正常结束

模型返回没有工具调用的回答时运行 Stop Hook。第一次 forceContinue 追加明确的 user 消息并再次请求模型，stopHookActive=true；第二次模型停止时回调仍执行并看到 stopHookActive，即使再返回 forceContinue 也会被移除。一次 run() 最多增加一个模型 turn，不会死循环。

turn N    模型停止 → Stop Hook(active:false) → forceContinue → 续跑
turn N+1  模型停止 → Stop Hook(active:true)  → forceContinue 被移除 → 结束

npm run test:ch04
 Test Files  12 passed (12)
      Tests  94 passed (94)
# 从第 3 章的 61 涨到 94，多出的 33 个几乎全在 hooks.test.ts / ch04-hooks.test.ts

npm run ch04 -- --prompt '读取 README.md 并概括运行方式'
# stderr → [Hook] UserPromptSubmit
#          [Hook] PreToolUse: read_file
#          [Permission] read_file: allow (default) - ...
#          [Hook] PostToolUse: read_file -> ok
#          [Hook] Stop

npm run ch04 -- --prompt '把一句话写入 hook-demo.txt'
# 写文件时仍是第 3 章的逐次审批，只是多了四行 [Hook] 生命周期日志

• Hook 是在四个确定位置发布结构化上下文，让扩展逻辑从核心编排里搬出去。
• 返回值用结构化 HookResult 而不是字符串，因为控制流语义必须能被校验。
• Hook 能建议、能改写、能阻断，但不能授权——系统 deny 永远优先。

• [Hook] PreToolUse 和 [Permission] 哪个先出现？为什么不能反过来？
• 为什么 additionalContext 只允许 system 消息？允许 tool 消息会怎样？
• 一个恶意 Pre Hook 想把 write_file 伪装成 read_file，哪一条检查拦住了它？
• 三个 Post Hook 依次改写结果，第三个看到的是哪个版本？
• Post Hook 要求停止时，同一轮里其它调用为什么变成 hook_stopped_continuation？
• Stop Hook 第二次还能 forceContinue 吗？回调还会执行吗？
• Post Hook 抛异常，handler 执行过没有？为什么这个信息很重要？