【免费下载链接】claude-code-source-codeClaude code source code项目地址https://gitcode.com/gh_mirrors/cla/claude-code-source-code点击查看免费下载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 子系统全景事件 → 匹配器 → 你的命令 整个钩子系统分三层配置层settings.json里的 hook 规则分四级——企业 managed 策略、用户级~/.claude/settings.json、项目级.claude/settings.json、本地级.claude/settings.local.json作用域越大优先级越高。执行层Agent 主循环在对应的生命周期节点把一份 JSON 事件数据写进你 shell 命令的 stdin。协议层命令的退出码 stdout 的 JSON决定 Agent 下一步干什么。钩子事件一览长尾关键词Claude Code hooks 有哪些事件触发时机能做什么PreToolUse⭐每次工具调用执行前拦截 / 放行 / 请求授权改写工具输入PostToolUse⭐工具调用成功后注入观察上下文、做后处理PostToolUseFailure工具调用失败后收集错误信息、告警UserPromptSubmit用户提交 prompt 时追加上下文、拒绝 promptStop/SubagentStop主 Agent / 子 Agent 结束响应时用退出码 2 强制继续干活SessionStart/SessionEnd会话开始 / 结束注入初始上下文、清理记录PreCompact上下文压缩前备份、通知Notification等待输入等通知触发时桌面通知等在 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 钩子 → 真正执行工具。钩子在“最后一刻”介入因此拥有最大话语权。Agent 产生一次工具调用例如Bash执行前把事件 JSON 通过 stdin 交给你的钩子命令{ hook_event_name: PreToolUse, tool_name: Bash, tool_input: { command: git push }, session_id: …, transcript_path: …, cwd: … }钩子的输出决定这次工具调用的命运。退出码与 JSON 协议pre 钩子的核心钩子输出Agent 行为退出码 0放行stdout 仅记录到 transcript退出码 2阻断stderr 回灌给 Claude工具不执行其他非 0非阻断错误stderr 展示给用户JSON{decision:block,reason:…}带理由阻断等效退出码 2JSONpermissionDecision: allow/deny/ask直接给出权限裁决跳过交互确认JSONupdatedInput改写工具输入实际执行的参数被钩子替换这里藏着 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记忆里文件上。记忆文件的分层与加载顺序文件范围用途企业 managed 策略组织级强制约束优先级最高项目根CLAUDE.md/.claude/CLAUDE.md团队共享代码规范、常用命令、架构约定~/.claude/CLAUDE.md个人跨项目个人偏好多层记忆都会在会话开始时被注入系统上下文是 Agent 每次行动前读到的“第一组规则”。支持path/to/file语法把别的文件内联进记忆如docs/api-notes.md。子目录里也可以放CLAUDE.mdAgent 碰到该目录下的文件时才加载实现“按目录生效”的局部记忆。用 /init 与 # 快捷键维护记忆最快上手方法新项目跑一次/initClaude Code 自动生成CLAUDE.md模板。输入框里按#把当前这句话直接存入项目记忆。/memory打开编辑器集中修改记忆文件。六、Hooks × Memory让 Agent 行为可演化两个子系统组合起来能做出“会成长的 Agent”SessionStart钩子会话开始时读取记忆里的最新约定additionalContext注入上下文PostToolUse钩子关键工具调用成功后如测试通过自动往记忆文件追加一行“经验”记忆随每次会话沉淀Agent 行为持续变好——全程不改任何源码。七、常见问题排查清单症状排查方法钩子不生效先确认matcher正则命中工具名用示例 payload 手动跑一遍jq .验证 JSON 能解析确认命令在bash -c下可执行钩子超时调大timeout钩子只做轻量判断重逻辑拆到独立进程block 与 ask 混淆退出码 2 硬阻断permissionDecision: ask 仍弹窗问用户记忆不生效检查文件所在层级项目根 vs~/.claude/改完开新会话记忆在会话开始注入八、总结PreToolUse拦截 改写靠decision/permissionDecision/updatedInput三个协议字段实现。PostToolUse后处理 上下文注入靠additionalContext把观察结果回灌给模型。CLAUDE.mdAgent 的分层长期记忆会话开始时整体注入。Hooks 是 Agent 行为的改写层Memory 是 Agent 行为的记忆层。读懂这两层你就能在不修改任何源码的前提下把 Claude Code 配置成贴合自己团队工程流的 Agent。赞分享【免费下载链接】claude-code-source-codeClaude code source code项目地址https://gitcode.com/gh_mirrors/cla/claude-code-source-code点击查看免费下载相关推荐GoReleaser Build Hooks 实战指南pre/post 构建钩子的配置、模板与源码原理GoReleaser Build Hooks 实战指南pre/post 构建钩子的配置、模板与源码原理 GoReleaser 的 builds .hooks开发工具CI/CD构建工具如何在 Windows 上为 Claude Code 编写跨平台的 SessionStart 钩子脚本如何在 Windows 上为 Claude Code 编写跨平台的 SessionStart 钩子脚本 Superpowers 仓库的 Claude CodeAI 技能AI 插件开发工具agno Agent 钩子机制实战指南基于 09_hooks 示例解析 pre/post hooks、工具中间件与流式生命周期agno Agent 钩子机制实战指南基于 09_hooks 示例解析 pre/post hooks、工具中间件与流式生命周期 本篇技术指南围绕 agno 开人工智能AI AgentAgent 框架多智能体工具调用RAGAgent 记忆Agent 工作流后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/23 19:56:18 · 阅读 1.2k Claude Code Hooks与Memory子系统源码解读：pre/post工具钩子如何改写Agent行为
【免费下载链接】claude-code-source-codeClaude code source code项目地址https://gitcode.com/gh_mirrors/cla/claude-code-source-code点击查看免费下载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 子系统全景事件 → 匹配器 → 你的命令 整个钩子系统分三层配置层settings.json里的 hook 规则分四级——企业 managed 策略、用户级~/.claude/settings.json、项目级.claude/settings.json、本地级.claude/settings.local.json作用域越大优先级越高。执行层Agent 主循环在对应的生命周期节点把一份 JSON 事件数据写进你 shell 命令的 stdin。协议层命令的退出码 stdout 的 JSON决定 Agent 下一步干什么。钩子事件一览长尾关键词Claude Code hooks 有哪些事件触发时机能做什么PreToolUse⭐每次工具调用执行前拦截 / 放行 / 请求授权改写工具输入PostToolUse⭐工具调用成功后注入观察上下文、做后处理PostToolUseFailure工具调用失败后收集错误信息、告警UserPromptSubmit用户提交 prompt 时追加上下文、拒绝 promptStop/SubagentStop主 Agent / 子 Agent 结束响应时用退出码 2 强制继续干活SessionStart/SessionEnd会话开始 / 结束注入初始上下文、清理记录PreCompact上下文压缩前备份、通知Notification等待输入等通知触发时桌面通知等在 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 钩子 → 真正执行工具。钩子在“最后一刻”介入因此拥有最大话语权。Agent 产生一次工具调用例如Bash执行前把事件 JSON 通过 stdin 交给你的钩子命令{ hook_event_name: PreToolUse, tool_name: Bash, tool_input: { command: git push }, session_id: …, transcript_path: …, cwd: … }钩子的输出决定这次工具调用的命运。退出码与 JSON 协议pre 钩子的核心钩子输出Agent 行为退出码 0放行stdout 仅记录到 transcript退出码 2阻断stderr 回灌给 Claude工具不执行其他非 0非阻断错误stderr 展示给用户JSON{decision:block,reason:…}带理由阻断等效退出码 2JSONpermissionDecision: allow/deny/ask直接给出权限裁决跳过交互确认JSONupdatedInput改写工具输入实际执行的参数被钩子替换这里藏着 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记忆里文件上。记忆文件的分层与加载顺序文件范围用途企业 managed 策略组织级强制约束优先级最高项目根CLAUDE.md/.claude/CLAUDE.md团队共享代码规范、常用命令、架构约定~/.claude/CLAUDE.md个人跨项目个人偏好多层记忆都会在会话开始时被注入系统上下文是 Agent 每次行动前读到的“第一组规则”。支持path/to/file语法把别的文件内联进记忆如docs/api-notes.md。子目录里也可以放CLAUDE.mdAgent 碰到该目录下的文件时才加载实现“按目录生效”的局部记忆。用 /init 与 # 快捷键维护记忆最快上手方法新项目跑一次/initClaude Code 自动生成CLAUDE.md模板。输入框里按#把当前这句话直接存入项目记忆。/memory打开编辑器集中修改记忆文件。六、Hooks × Memory让 Agent 行为可演化两个子系统组合起来能做出“会成长的 Agent”SessionStart钩子会话开始时读取记忆里的最新约定additionalContext注入上下文PostToolUse钩子关键工具调用成功后如测试通过自动往记忆文件追加一行“经验”记忆随每次会话沉淀Agent 行为持续变好——全程不改任何源码。七、常见问题排查清单症状排查方法钩子不生效先确认matcher正则命中工具名用示例 payload 手动跑一遍jq .验证 JSON 能解析确认命令在bash -c下可执行钩子超时调大timeout钩子只做轻量判断重逻辑拆到独立进程block 与 ask 混淆退出码 2 硬阻断permissionDecision: ask 仍弹窗问用户记忆不生效检查文件所在层级项目根 vs~/.claude/改完开新会话记忆在会话开始注入八、总结PreToolUse拦截 改写靠decision/permissionDecision/updatedInput三个协议字段实现。PostToolUse后处理 上下文注入靠additionalContext把观察结果回灌给模型。CLAUDE.mdAgent 的分层长期记忆会话开始时整体注入。Hooks 是 Agent 行为的改写层Memory 是 Agent 行为的记忆层。读懂这两层你就能在不修改任何源码的前提下把 Claude Code 配置成贴合自己团队工程流的 Agent。赞分享【免费下载链接】claude-code-source-codeClaude code source code项目地址https://gitcode.com/gh_mirrors/cla/claude-code-source-code点击查看免费下载相关推荐GoReleaser Build Hooks 实战指南pre/post 构建钩子的配置、模板与源码原理GoReleaser Build Hooks 实战指南pre/post 构建钩子的配置、模板与源码原理 GoReleaser 的 builds .hooks开发工具CI/CD构建工具如何在 Windows 上为 Claude Code 编写跨平台的 SessionStart 钩子脚本如何在 Windows 上为 Claude Code 编写跨平台的 SessionStart 钩子脚本 Superpowers 仓库的 Claude CodeAI 技能AI 插件开发工具agno Agent 钩子机制实战指南基于 09_hooks 示例解析 pre/post hooks、工具中间件与流式生命周期agno Agent 钩子机制实战指南基于 09_hooks 示例解析 pre/post hooks、工具中间件与流式生命周期 本篇技术指南围绕 agno 开人工智能AI AgentAgent 框架多智能体工具调用RAGAgent 记忆Agent 工作流后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考