源码分析手册

第 03 章：钩子与扩展 (Hooks & Extensions)

如果 Claude Code 是一台固定的机器，那么它的“钩子系统 (Hook System)”就是其开放的扩展插槽。本章将揭秘 Claude Code 是如何实现高度解耦的事件驱动架构的。从用户提交 Prompt 的那一刻，到工具执行前后的拦截，钩子无处不在。

本章解答的核心问题是：如何让一个复杂的 Agent 框架具备可观测性与可扩展性？ 我们会研究 Claude Code 内部的“中枢神经系统”，看它如何监听工作目录的变化、如何劫持权限请求、以及如何在工具执行的间隙注入自定义逻辑。

推荐阅读顺序：

首先精读 hook-system-architecture.md，理解事件总线与订阅分发机制。
关注 pre-tool-use.md 和 post-tool-use.md，这对于理解 Agent 的可观测性至关重要。
通过 cwd-changed-file-changed.md 和 worktree-create-remove.md 观察文件系统事件如何反馈给 Agent。

读后心智模型：读完本章，你会明白 Claude Code 内部其实是由一系列互相独立的组件构成的，这些组件通过“钩子”进行松耦合通信。这种架构设计对于我们构建自己的 Agent 系统非常有启发意义。

本章文章

cwd-changed-file-changed.md — 探讨工作目录与文件变更事件的联动逻辑。
hook-system-architecture.md — 深度解析 Claude Code 的全局事件驱动架构。
instructions-loaded.md — 分析当自定义指令加载完成后的回调机制。
permission-request.md — 详述权限请求触发时的拦截逻辑。
post-tool-use.md — 探究工具执行后的结果处理与状态更新。
pre-tool-use.md — 解析工具调用前的预处理、参数校验与权限预检。
session-hooks.md — 探讨会话全生命周期中的关键业务钩子。
user-prompt-submit.md — 详述用户输入提交时的预处理流程。
worktree-create-remove.md — 分析在多工作树环境下事件的隔离与同步策略。