会话钩子：SessionStart 与 SessionStop

Claude Code 的会话生命周期并非简单的进程启停，而是一个多阶段的环境装配与状态结算过程。SessionStart 和 SessionStop（常被称为 Stop 钩子）是这一过程中的核心扩展点，定义了模型在“睁眼”和“闭眼”瞬间的环境补丁与数据收口。

它解决了什么问题

这组钩子本质上是 推理会话的首尾拦截器（Session Interceptors）。

它们不是简单的启动/退出脚本。它们是运行时协议的一部分，决定了模型如何看待当前环境，以及如何从当前对话中沉淀状态。

• SessionStart：发生在首轮推理前。它不是一个简单的“热身”，而是一个运行时协议，允许向会话中注入额外的上下文、指令、甚至模拟用户的初始提问。
• SessionStop：发生在每轮推理结束时。它是运行时进行状态结算、背景任务调度以及下一步预测的关键时机。

实现机制

1. SessionStart：启动时的环境拦截

核心逻辑位于 claude-code-opensource/src/utils/sessionStart.ts 的 processSessionStartHooks：

1. 模式裁决：首先检查是否处于 --bare 模式。如果是，系统将跳过所有钩子加载和执行。
2. 插件加载：系统加载并缓存来自 ~/.claude/plugins/ 的第三方钩子。
3. 核心影响点：
   • 注入消息：直接向消息队列添加 HookResultMessage。
   • 上下文注入：通过 additionalContexts 向模型提供非对话形式的背景信息。
   • 初始提问模拟：设置 pendingInitialUserMessage，允许钩子代表用户发起“第一击”。
   • 动态监听：返回 watchPaths，告诉 fileChangedWatcher 需要监控的文件。

2. SessionStop：推理后的状态结算

核心逻辑位于 claude-code-opensource/src/query/stopHooks.ts 的 handleStopHooks：

1. 快照保存与分叉：通过 saveCacheSafeParams 保存上下文快照，支持 /btw 等功能在不破坏主会话缓存的情况下运行。
2. 并行背景任务：在非 --bare 模式下，并行启动记忆提取（Memory Extraction）、推理预测（Prompt Suggestion）和自动化推演（Auto Dream）。
3. 治理能力：
   • 阻断后续执行：如果发现环境状态异常（如编译失败），可抛出 blockingError。
   • 控制流改写：通过 preventContinuation 信号，强行停止 Claude 的自动化流水线。

踩坑指南

• SessionStart 的性能禁忌：源码中明确标注：do not add ANY "warmup" logic。该钩子严禁添加高耗时操作，因为它直接阻塞了用户的首次交互感官。
• 重复触发特性：当你执行 /compact 或 /clear 时，SessionStart 会被重新触发。请确保逻辑的幂等性。
• Stop 钩子的竞态：所有 Stop 钩子是并行执行的，不应在不同的钩子之间建立强依赖。
• 中断处理：即使用户通过 Ctrl+C 中断了模型输出，handleStopHooks 仍会被触发，进入“中断处理”分支。

相关主题

• 如果你想了解提取出的记忆存到了哪里，请看 本地记忆层：Auto Memory 机制。
• 如果你想了解 Hook 的基础调度机制，请看 Hook 系统架构解析。
• 如果你关心启动时的极致性能，请看 Bare 模式：极致的执行隔离。

源码锚点

• claude-code-opensource/src/utils/sessionStart.ts — processSessionStartHooks 主逻辑。

📄 src/utils/sessionStart.ts — `processSessionStartHooks` 主逻辑。L35-42 of 233

export async function processSessionStartHooks(
  source: 'startup' | 'resume' | 'clear' | 'compact',
  {
    sessionId,
    agentType,
    model,
    forceSyncExecution,
  }: SessionStartHooksOptions = {},

• claude-code-opensource/src/query/stopHooks.ts — handleStopHooks 收口流程及其背景任务调度。

📄 src/query/stopHooks.ts — `handleStopHooks` 收口流程及其背景任务调度。L65-69 of 474

export async function* handleStopHooks(
  messagesForQuery: Message[],
  assistantMessages: AssistantMessage[],
  systemPrompt: SystemPrompt,
  userContext: { [k: string]: string },

• claude-code-opensource/src/utils/hooks.ts — 钩子执行引擎的底层支撑。

📄 src/utils/hooks.ts — 钩子执行引擎的底层支撑。L56-58 of 5023

  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
} from 'src/services/analytics/index.js'
import { logOTelEvent } from './telemetry/events.js'