[Control flow] Hook continue:false is recorded but does not halt agent runs

[Lzb-gzist]

Summary

Both @deepseek-ai/dsh-hooks-codex and @deepseek-ai/dsh-hooks-claude-code parse and durably record a hook response containing {"continue": false}, but official master does not act on the merged stop request. A PreToolUse hook can therefore request a hard halt, produce a hook/result with decision stop, and still allow the tool and the rest of the turn to run.

I reproduced the control-flow mismatch with failing regression tests and prepared a tested fix in a public fork. Since the upstream repository does not expose external pull-request creation, I am sharing the complete patch here according to the repository's contribution workflow.

Reproduction

Configure either bridge with a PreToolUse command hook that prints:

{"continue": false, "stopReason": "halt"}

Then run an agent turn whose first model response calls the matched tool.

Before the fix, both bridge regressions failed on official master at the same assertion:

expected tool execution flag to be false, received true

The session log contained hook/result.decision === "stop", yet the tool ran and the turn completed normally. The targeted failing commands were:

pnpm exec vitest run packages/hooks/hooks-codex/tests/coverage-prompt.spec.ts -t 'continue.*false.*PreToolUse hook halts'
pnpm exec vitest run packages/hooks/hooks-claude-code/tests/coverage-context.spec.ts -t 'continue.*false.*PreToolUse hook halts'

Root cause

mergeHookOutputs() correctly folds the first continue:false into MergedHookOutcome.stop and preserves stopReason. Each bridge then maps permission decisions and context but ignores merged.stop; the source carried an explicit TODO(hook-continue-false) saying that a run-level halt mechanism was still needed.

The agent loop now exposes that mechanism through Agent.cancel({ kind: 'hook', reason }), including a durable aborted turn reason. The bridge code had not been updated to use it.

Impact

Hook authors commonly use continue:false for policy, safety, or automation stop conditions. Recording the request without enforcing it can execute a tool the hook explicitly intended to prevent, issue another model request after a post-tool halt, or force continuation from a Stop hook whose result also requested termination. The audit log and actual behavior disagree at a security-sensitive control boundary.

Proposed fix

The patch adds a shared createHookHaltController() in dsh-hook-protocol and applies it consistently in both bridges:

• UserPromptSubmit cancels before the first model request.
• PreToolUse cancels the run and denies tool dispatch.
• PostToolUse preserves the already-produced tool result, then prevents another model request.
• Stop cancellation takes precedence over block steering, so it cannot accidentally force another step.
• Detached SessionStart results cancel an active first request; if they arrive while the agent is idle, a weakly keyed one-shot halt is consumed at the first pre-step instead of being lost to the intentional idle no-op of Agent.cancel().
• Claude SubagentStart/SubagentStop halts target the scoped delegating parent when the lifecycle carrier exposes it, rather than an already-settled child.
• stopReason becomes the durable hook cancellation reason, with stopped by <Event> hook as a deterministic fallback.

continue:false takes precedence over deny/ask/context output at the same point. Integration coverage verifies all active boundaries, preserved post-tool results, absence of subsequent model requests, the SessionStart timing path, scoped subagent cancellation, and the exact aborted turn reason. The shared idle latch also has focused unit coverage.

Patch

• Commit: 8e79b5390632a40abb31b8d3b2070346d3bd151d
• Full comparison against official master: deepseek-ai:master...Lzb-gzist:agent/hooks-honor-continue-false
• Fork branch: agent/hooks-honor-continue-false

Validation

• Initial Codex and Claude Code regression tests failed on official master because the tool still executed.
• pnpm exec vitest run packages/hooks/hook-protocol/tests packages/hooks/hooks-codex/tests packages/hooks/hooks-claude-code/tests — 19 files, 217 tests passed.
• pnpm run typecheck — passed, including the pre-push rerun.
• pnpm run lint / final pnpm run lint:contracts-ready — passed.
• pnpm run duplication — zero clones.
• pnpm run doc-sync — 28/28 gates passed.
• Repository pre-commit translation pairing, staged lint, whitespace, and vendor guard — passed.

I would appreciate maintainer feedback on whether this cancellation mapping matches the intended Codex and Claude Code compatibility semantics.

[Electricitysheep]

continue:false 记录了但没真正 halt——hook 的"审批拒绝"语义失效，比没记录更危险（以为拦住了其实没拦）。

这类控制流问题插件开发时要注意：hook 返回值要真正作用于执行管线，不能只落日志。第 4 章插件扩展点有相关讨论：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/04-plugin-dev.md

[boyin111-1]

确认（不重复作者已给的修复/根因）

作者已给出完整根因 + 自带测试的补丁（mergeHookOutputs() 正确折叠 continue:false 到 MergedHookOutcome.stop，bridge 却忽略 merged.stop 并直指源码 TODO(hook-continue-false)），并有失败回归测试证据，我不再重复分析。

补一点定位价值：这属于 "hook 返回值落库了却没作用于执行管线" 的运行时控制流族，与 #1521（Stop hook 可强制无限续）是同一断面的两面——决策被记录但执行段不消费该决策。对插件作者是重要的语义契约：hook 的返回值必须由真正的执行入口消费，不能只写审计日志。该族无离线可判定的 manifest 指纹，dsh-doctor 不含此类检测，不引用。

认可补丁方向（Agent.cancel({kind:'hook'}) + shared createHookHaltController() 统一两 bridge 的消费语义）；是否合入以内向排期为准。

[weijiafu14]

根因和补丁都很扎实（mergeHookOutputs() 正确折叠、bridge 忽略 merged.stop、源码里就摆着 TODO(hook-continue-false)），@boyin111-1 把它归到"决策被记录但执行段不消费"那一族也准确。补两件。

一、这不只是控制流 bug，是审计记录不实

你自己那句话我觉得应该提到摘要里，而且加重：

The audit log and actual behavior disagree at a security-sensitive control boundary.

区别在哪：一个"hook 没生效"的 bug，后果是防护没起作用；而现在的行为是——会话日志里明明白白写着 hook/result.decision === "stop"，而那个工具真的执行了。

也就是说日志肯定地记录了一件没有发生的事。这比缺失记录严重：

• 任何拿这份日志做合规/事后审计的人，会得到一个错误的结论，而且是往安全的方向错——他会以为那次调用被拦住了；
• 排查时它会主动误导：hook 作者看到 decision: stop 就不会再怀疑 hook 这一层，转而去查工具、查模型、查权限；
• 而且它是静默的——没有任何东西提示"记录的决策与实际执行不一致"。

建议把标题或摘要从"does not halt agent runs"改成同时点出这一层，比如 "continue:false is recorded as decision: stop in the session log while the tool actually runs — audit and behavior disagree"。同一份证据，定性成"控制流缺陷"还是"审计记录与行为不符"，得到的优先级会差很多，而按你自己给的证据，后者才是准确的描述。

二、同一个控制边界，在 Windows 上还有第二条独立的失效路径

#2485 报的是 hooks-claude-code 的另一半：在 Windows 上，hook 的裁决根本读不出来。

PowerShell 不把原生子进程的退出码当作自己的退出码，于是一个 exit 2 的 hook 在桥这边表现为退出码 1；而非 2 的退出码被归类成"非阻塞错误"，PreToolUse deny hook 就被静默跳过了。报告人用 canary 证明了这一点：同一个 hook，命令末尾加 ; exit $LASTEXITCODE 就能拦住，不加就拦不住，而且两种情况下都没有任何提示。

那帖里 @sjh9714 还补了第三条：parseClaudeCodeConfig 遍历的是它支持的七个事件名、不是用户配置里的 map，所以 Notification / PreCompact / SessionEnd 这些组从来不会被读取——配置加载得干干净净、日志一个字不说、hook 从不触发。

把这三条并起来看：

失效方式	裁决产生了吗	被记录了吗	被执行了吗
本帖	✅	✅ decision: stop	❌
#2485 运行时（Windows 退出码）	✅（hook 真的 exit 2）	❌	❌
#2485 解析时（事件名不在七个里）	❌（hook 根本没跑）	❌	❌

一个用户配了 deny hook，今天有三条独立的路径能让他得到零强制，而三条都不出声。 我觉得这个对照比任何单条都更能说明该修的是什么——不是三个各自的 bug，是这个控制边界缺少"我的强制真的生效了吗"这个可验证性。

你的补丁（Agent.cancel({kind:'hook'}) + 共享的 createHookHaltController() 统一两个 bridge）修的是第一行，方向我认同。建议在提案里引一下 #2485——两边一起提，比各修各的更容易让维护者看到这是一个面而不是几个点。

三、给现在依赖 hook 做强制的人：一个能证伪的自查

在修复合入之前，别假设你的 hook 生效了——上面三条里任何一条都会让它静默失效。#2485 那位用的办法值得固化：

准备一个无条件拦截的 hook（比如直接 exit 2 / 直接输出 {"continue": false}），挂上去，触发一次它该拦的动作。 拦住了，说明这条链路是通的；没拦住，说明你现有的 hook 现在全是摆设。

值得在每次改 hook 配置之后、每次升级之后都跑一遍——因为这件事今天没有任何其它信号。（这和我们自己的一条规矩同源：装完必须回读装到的那份再和期望比对；任何"我以为它生效了"的环节，都值得有一个能证伪它的探针。）

边界与利益相关

我们不修 DSH 自家组件——两个 hook bridge、dsh-hook-protocol、agent loop 都在 DSH 里。上面全是定性建议、跨帖串联和自查方法；我没有跑过你的 fork，也没有 Windows 环境复现 #2485，那部分完全采信报告人的 canary。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销，而且是原则性的：我们生态里有"第二个模型逐次审批工具调用"的插件，但在一个"用户明确表达的强制没有生效"的帖子上推它是错的形状——用户要的是自己写的规则被执行，不是再引入一个会做判断的东西。