Claude Code Hooks与Memory子系统源码解读：pre/post工具钩子如何改写Agent行为

Claude Code 是运行在终端里的 AI 编程 Agent，它的Hooks 钩子系统与Memory 记忆子系统决定了每一次工具调用会被拦截、改写还是放行。本文基于 Claude Code 源码架构做完整解读：讲清PreToolUse/PostToolUse两条 pre/post 钩子的执行链路、退出码协议，以及CLAUDE.md记忆文件如何分层注入上下文，帮你不改一行代码就能定制 Agent 行为。

一、先看仓库：源码在哪里

当前仓库是一个指针仓库，仅包含 README.md 和一个图片资产。README 的 “Main Projects” 部分给出了完整源码仓库的指引，想逐行读源码请从那里入手：

git clone https://gitcode.com/gh_mirrors/cla/claude-code-source-code

理解 Hooks 与 Memory 的关键，不在某个单文件，而在下面这套三层执行架构上。

二、Hooks 子系统全景：事件 → 匹配器 → 你的命令

💡 整个钩子系统分三层：

1. 配置层：settings.json里的 hook 规则，分四级——企业 managed 策略、用户级~/.claude/settings.json、项目级.claude/settings.json、本地级.claude/settings.local.json，作用域越大优先级越高。
2. 执行层：Agent 主循环在对应的生命周期节点，把一份 JSON 事件数据写进你 shell 命令的 stdin。
3. 协议层：命令的退出码 + stdout 的 JSON决定 Agent 下一步干什么。

钩子事件一览（长尾关键词：Claude Code hooks 有哪些）

在 settings.json 中注册钩子（最快配置方法）

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "jq -r '.tool_input.command'", "timeout": 30 } ] } ] } }

• matcher是匹配工具名的正则，甚至可以细到参数：Bash(git commit*)、Edit(/etc/*)。
• timeout单位为秒，默认 60 秒；超时后钩子被丢弃，主流程继续。

三、PreToolUse 源码链路：拦截与改写如何发生

在源码的工具执行管线中，顺序是：工具校验 → 权限门 → PreToolUse 钩子 → 真正执行工具。钩子在“最后一刻”介入，因此拥有最大话语权。

1. Agent 产生一次工具调用（例如Bash）；
2. 执行前，把事件 JSON 通过 stdin 交给你的钩子命令：

{ "hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": { "command": "git push" }, "session_id": "…", "transcript_path": "…", "cwd": "…" }

3. 钩子的输出决定这次工具调用的命运。

退出码与 JSON 协议（pre 钩子的核心）

这里藏着 pre 钩子改写 Agent 行为的两个杀手锏：

• 改参数（updatedInput）：例如在Bash执行前，把命令里的高危路径替换成沙箱路径，或给危险命令追加--dry-run——模型对“输入被换过”毫无感知。
• 改裁决（permissionDecision）：原本要弹窗问用户的权限确认，由钩子直接 allow / deny / ask，适合全自动流水线。

四、PostToolUse 源码链路：把观察结果回灌给模型

• 它的 stdin 与 pre 相同，但额外多一个tool_response（工具执行结果）。
• 在 JSON 输出里用hookSpecificOutput.additionalContext，可以把额外观察追加进 Claude 的上下文。例如：测试输出有 2 万行，钩子先跑一遍grep -E "FAIL|Error"，只把失败摘要塞给模型，下一轮推理更准、更省 token。
• 退出码 2 时，stderr 回灌给 Claude 而非用户，适合“工具成功了，但我要提醒模型注意”。

一句话总结这条闭环：pre 决定“能不能做、怎么做”，post 决定“做完后模型看到什么”——这就是工具钩子改写 Agent 行为的完整机制。

五、Memory 子系统：CLAUDE.md 的分层记忆

🧠 Memory 是 Agent 的“长期记忆”，全部落在CLAUDE.md记忆里文件上。

记忆文件的分层与加载顺序

• 多层记忆都会在会话开始时被注入系统上下文，是 Agent 每次行动前读到的“第一组规则”。
• 支持@path/to/file语法把别的文件内联进记忆，如@docs/api-notes.md。
• 子目录里也可以放CLAUDE.md：Agent 碰到该目录下的文件时才加载，实现“按目录生效”的局部记忆。

用 /init 与 # 快捷键维护记忆（最快上手方法）

• 新项目跑一次/init：Claude Code 自动生成CLAUDE.md模板。
• 输入框里按#：把当前这句话直接存入项目记忆。
• /memory：打开编辑器集中修改记忆文件。

六、Hooks × Memory：让 Agent 行为可演化

两个子系统组合起来，能做出“会成长的 Agent”：

• SessionStart钩子：会话开始时读取记忆里的最新约定，additionalContext注入上下文；
• PostToolUse钩子：关键工具调用成功后（如测试通过），自动往记忆文件追加一行“经验”；
• 记忆随每次会话沉淀，Agent 行为持续变好——全程不改任何源码。

七、常见问题排查清单

八、总结

• PreToolUse：拦截 + 改写，靠decision/permissionDecision/updatedInput三个协议字段实现。
• PostToolUse：后处理 + 上下文注入，靠additionalContext把观察结果回灌给模型。
• CLAUDE.md：Agent 的分层长期记忆，会话开始时整体注入。

Hooks 是 Agent 行为的改写层，Memory 是 Agent 行为的记忆层。读懂这两层，你就能在不修改任何源码的前提下，把 Claude Code 配置成贴合自己团队工程流的 Agent。