企业官网建设流程全解析

• 文档
• 提示工程
• 人工智能

会话级（session-scoped）Stop hook 是 Claude Code 中一套将"用户目标"固化为 Agent 持续执行指令的机制：它把一个明确的目标条件注入当前会话，在条件满足之前持续阻止 Claude 停止，条件达成后自动解除。本文围绕仓库中的 system-reminder-session-stop-hook-active.md 展开，结合 Hooks 配置、Stop 条件评估器与 ProposeGoal 目标提案等配套文档与源码，完整讲解该机制的工作语义、Agent 行为契约、生命周期以及/goal clear的正确用法。读完本文，你将掌握：Stop hook 何时激活、如何驱动 Agent 不停机推进、条件如何被判定，以及何时（以及何时不该）使用/goal clear。

一、什么是会话级 Stop hook：机制概览

在 Claude Code 的 Hook 体系中，Stop是一个独立事件，官方配置文档 system-prompt-hooks-configuration.md 明确将其定义为：

Stop（无 matcher）：Run when Claude stops (including clear, resume, compact)。

即 Stop hook 在 Claude 每次尝试停止时触发——包括正常收尾、用户执行 clear/resume/compact 等操作。而本文讨论的"会话级 Stop hook"是 Stop 事件的一种特殊用途：它携带一个目标条件（condition），在条件未满足之前，Claude 不允许真正停止。

该机制由配套的系统提醒消息 system-reminder-session-stop-hook-active.md 驱动，其核心语义可以拆解为四个阶段：

1. 激活：一个会话级 Stop hook 被激活，并携带具体条件文本；
2. 指令化：条件本身成为 Agent 的当前指令，Agent 需立即开始或继续工作，不得停顿询问用户；
3. 阻塞停止：在条件成立之前，hook 会阻止 Claude 停止（block stopping）；
4. 自动清除：条件一旦满足，hook 自动清除，会话恢复正常停止行为。

这段消息通过模板变量${STOP_HOOK_CONDITION}注入具体条件，消息头的variables字段（- "STOP_HOOK_CONDITION"）表明该文本是由上层系统在运行时填充的。也就是说，同一份提醒消息模板可以适配任意目标条件。

二、Agent 行为契约：把条件当作指令

原文档对激活后 Agent 的行为要求非常明确，这是整篇消息的实操核心，可归纳为三条行为准则：

1. 简要确认目标，立即行动：先简短确认目标内容，然后立刻开始（或继续）向目标工作——不要长篇复述、不要等待额外指示；
2. 条件即指令：把${STOP_HOOK_CONDITION}本身视为你的直接指令（directive），主动推进执行，而不是停下来反问用户"接下来做什么"；
3. 不停机推进：由于 hook 在条件满足前会阻塞停止，任何尝试结束回合的行为都会被拦截，Agent 应当意识到这一点，并持续工作直至条件成立。

这实际上是 Claude Code 对"多轮、可验证目标"任务的工程化表达：任务被固化成一条可判定的条件，Agent 在条件判定为真之前没有退路，从而保证长任务（如"迁移所有调用点"、"让测试全部通过"）不会在中途被过早收尾。

三、Stop 事件在 Hook 生命周期中的位置

要理解"阻塞停止"的底层机制，需要先回到 Hook 体系本身。在 system-prompt-hooks-configuration.md 中，Hook 运行于 Claude Code 生命周期的特定节点，整体事件表包括：

可以看到Stop是覆盖面最广的事件之一：只要 Claude 尝试停止，无论原因为何，Stop hook 都有机会介入。这正是会话级 Stop hook 能够"卡住"停止流程的事件基础。

Hook 返回的 JSON 输出中，与"阻塞停止"直接相关的字段是：

• continue：设为false即可阻止/停止（默认true）；
• stopReason：当continue为false时向用户展示的提示消息；
• systemMessage：向用户 UI 展示的消息（所有 hook 可用）。

也就是说，条件未满足时，Stop hook 通过输出continue: false来阻止 Claude 停止，并借助stopReason/systemMessage向用户解释原因；条件满足后则不再阻塞，Claude 得以正常结束回合。

四、条件如何被判定：Stop 条件评估器

会话级 Stop hook 的条件判定并非由 Agent 主观自评，而是由一个独立的评估器负责。仓库中的 agent-prompt-hook-condition-evaluator-stop.md 给出了该评估器的完整系统提示词，要点如下：

• 评估器会仔细阅读会话记录（transcript），判断用户提供的条件是否已被满足；
• 返回结果必须是 JSON 对象，且仅允许三种形态：
  • {"ok": true, "reason": "<引用会话记录中满足条件的证据文本>"}
  • {"ok": false, "reason": "<引用缺失或阻碍条件的内容>"}
  • {"ok": false, "impossible": true, "reason": "<解释条件为何永远无法满足>"}
• reason字段必须存在，且尽可能引用 transcript 中的原文；
• 若 transcript 中没有满足条件的明确证据，应返回{"ok": false, "reason": "insufficient evidence in transcript"}，即没有证据即视为未达成，体现严格的证据导向。

特别值得注意的是评估器对"impossible"分支的约束：只有当条件确实无法达成时才可使用——例如条件自相矛盾、依赖不可用的资源或能力、或 Agent 已明确尝试并穷尽合理手段后宣告无法完成。评估器被要求独立核实（"the assistant claiming the goal is impossible is evidence, not proof"），不能仅因目标尚未达成或进展缓慢就判为 impossible，也不能把 Agent 的自述当作最终结论。这保证了判定过程的客观性，防止 Agent 借"无法完成"之名提前脱身。

五、目标从哪来：ProposeGoal 与目标生命周期

会话级 Stop hook 的目标条件通常与 ProposeGoal 工具配套产生。tool-description-proposegoal.md 说明：

• ProposeGoal 用于为本次会话提出一个可验证的多轮目标，Agent 将持续工作直到独立评估器确认条件满足；
• 它是非阻塞式的：提案渲染在输出流中，Agent 可以在处理过程中继续工作；
• 默认ask_user true会先弹出一次性按键确认对话框；仅当用户在本会话原话明确表达该结果时，才可用ask_user false直接设定目标，否则必须询问；
• 提案条件需在最多 500 字符内，描述一个可测量的终态及其检查方式（例如bun test exits 0）；
• 同一时间仅有一个目标处于激活状态，新批准或新直接设定的提案会替换当前目标。

结合 Stop hook 提醒消息，完整的目标生命周期是：

用户提出可验证结果 → ProposeGoal 提案/确认 → 会话级 Stop hook 激活（携带条件） → Agent 以条件为指令持续推进 → 每次停止尝试时评估器核查 transcript → 条件满足 → hook 自动清除 → Agent 正常停止

这解释了为什么提醒消息中强调"条件一旦满足即自动清除"——评估器返回ok: true的时刻，就是目标达成、hook 解除的时刻，Agent 不需要额外动作。

六、/goal clear的正确用法：提前清除而非成功清除

原文档的最后一句是行为上的关键提醒：

It auto-clears once the condition is met — do not tell the user to run/goal clearafter success; that's only for clearing a goal early.

这包含两层语义：

1. 条件达成后目标自动清除：这是机制的正常出口，无需用户干预；
2. /goal clear仅用于提前清除目标：即用户主动放弃当前目标（例如目标已不再重要、需求已变更），而不是用于"庆祝成功"。

因此，Agent 在成功达成条件后不应建议用户执行/goal clear——这样做既多余，还会让用户误以为需要手动收尾。正确的做法是直接报告成果，因为 hook 已自动解除，会话恢复正常停止行为。只有当用户希望中途放弃目标、让 Agent 停止继续推进时，/goal clear才是正确指令。

七、阻塞失败与排障：Stop hook 报错形态

当 Stop hook 在运行过程中出错（例如命令执行失败、输出非法 JSON），Claude Code 会向 Agent 注入对应的阻塞错误提醒，仓库中有两个相关模板：

• system-reminder-stop-hook-blocking-error.md：Stop hook blocking error from command "${HOOK_NAME}"，专门针对 Stop 事件中阻塞性命令失败的情况；
• system-reminder-hook-blocking-error.md：通用的hookName hook blocking error from command ...，通过ATTACHMENT_OBJECT.hookName与ATTACHMENT_OBJECT.blockingError.command等字段定位出错的具体 hook 与命令。

遇到此类提醒时，应从 hook 配置的命令本身排查：命令是否可执行、stdin JSON 解析是否失败、输出是否符合 Hook JSON 规范（尤其是continue与stopReason字段的格式）。由于Stop事件会覆盖 clear、resume、compact 等操作，一个写坏的 Stop hook 可能让会话陷入"无法停止"的僵局，此时及时修正或移除对应 hook 配置是恢复的关键。

八、实战配置：一个会话级 Stop hook 的最小示例

虽然会话级 Stop hook 通常由上层系统（结合 ProposeGoal）动态注入，但理解其配置形态有助于掌握原理。基于 system-prompt-hooks-configuration.md 的 Hook 结构与 JSON 输出规范，一个面向Stop事件的最小配置骨架如下：

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "your-condition-check-command", "timeout": 60, "statusMessage": "Checking stop condition..." } ] } ] } }

对应的检查命令需要读取 stdin JSON 并输出符合规范的 Hook JSON，例如：

# 条件未满足时阻塞停止，并给出用户可见的原因 echo '{"continue": false, "stopReason": "目标尚未达成，继续推进", "systemMessage": "Working toward: 全部测试通过"}'

当条件满足时则输出{"continue": true}（或省略continue，默认即 true），允许 Claude 正常停止。整体可对照 system-prompt-hooks-configuration.md 中给出的 Auto-format、日志记录等Stop/PostToolUse模式的写法来扩展。

结语

会话级 Stop hook 是 Claude Code 将"目标管理"与"执行推进"耦合的关键机制：ProposeGoal 负责把用户意图固化为可验证条件，Stop 条件评估器在每次停止尝试时客观核查证据，而激活中的 Stop hook 则在条件达成前持续阻断停止。对 Agent 而言，激活消息的核心只有一句话——把${STOP_HOOK_CONDITION}当作指令，持续工作到评估器确认它成立为止；对用户而言，达成后无需任何手动操作，目标会自动清除，/goal clear仅在提前放弃时才有意义。理解这一机制，就能在编写自动化 Agent 流程、长任务会话与多步交付场景中，精确控制"何时该停、何时必须继续"。

• 文档
• 提示工程
• 人工智能