bug(hook): SDK session string-form user prompts defeat stop-hook staleness guard (re-opens #60)

[codevibesmatter]

Summary

The stop-hook escape hatch hasActiveBackgroundAgents() (src/commands/hook.ts:610-671) is silently broken for SDK-driven sessions (entrypoint: "sdk-ts" — duraclaw, eval harness, anything using @anthropic-ai/claude-agent-sdk). The staleness heuristic added in PR #61 for issue #60 never fires because SDK sessions encode typed user prompts as a bare string on message.content, not as an [{type:'text', text:'...'}] array. Unmatched Agent tool_use IDs persist forever and the guard false-allows exit for the rest of the session — the exact symptom #60 was filed to fix, still present.

Findings

The guard assumes array-of-blocks shape — src/commands/hook.ts:640-659:

const contentBlocks = (message.content as Array<...>) ?? []
for (const block of contentBlocks) {
  if (block.type === 'text' && block.text?.trim()) hasUserText = true
  ...
}
if (hasUserText && !hasToolResult) agentToolUseIds.clear()  // #61 staleness clear

SDK sessions produce string-form content:

{"type":"user","message":{"role":"user","content":"fix the button position"}}

When message.content is a string, for...of iterates characters. Each char is a one-letter primitive with no .type → hasUserText stays false → agentToolUseIds.clear() never runs → stale IDs persist forever.

Empirical data — one representative SDK transcript (~/.claude/projects/-data-projects-duraclaw-dev2/8d76757f-....jsonl, 594 lines, version: 2.1.98, entrypoint: sdk-ts):

user message.content shape	count
STRING (typed prompt)	5
ARRAY with [0].type == 'tool_result'	138
ARRAY with [0].type == 'text'	0

A comparable CLI-entrypoint session in the same tree had 4 ARRAY_text entries — that's where #61's heuristic works today. SDK sessions literally never produce the shape that triggers it.

Secondary issue: tool-spawn tool name differs across CC versions. Guard only matches block.name === 'Agent' (hook.ts:631), but 2.1.50 sessions emit "name":"Task". Recent 2.1.98+ SDK/CLI sessions use Agent. The eval harness allowedTools whitelist includes Task (eval/harness.ts:310).

Follow-up

Order by smallest-diff-first:

• Normalize content in hook.ts scanner: treat non-empty string as [{type:'text',text:content}]. Single-line fix, restores fix(hook): ignore stale unmatched Agent tool_uses in stop-conditions #61 staleness clear for SDK sessions.
• Time-based staleness floor (issue bug(hook): stop-conditions false-allows exit due to stale unmatched Agent tool_uses #60 recommendation (a)): ignore Agent tool_use IDs older than e.g. 120s. Necessary for fire-and-forget SDK orchestrators that never send a second user prompt.
• Match block.name === 'Task' too for older CC/SDK compatibility.
• Unit tests in src/commands/hook.test.ts:
  • SDK fixture with string-content user prompt after unmatched Agent → guard returns false
  • 2.1.50-shape transcript using "name":"Task" → guard detects when fresh, ignores when stale
  • Recency-filter boundary case

Evidence

Research doc: planning/research/2026-04-23-sdk-stop-hook-guard-failure.md (commit 1e4e30e).

Related: #60 (closed by #61 — incomplete fix for SDK sessions).

[codevibesmatter]

Eval validation for the fix (d80ee91)

Unit tests

`bun test src/commands/hook.test.ts` → 44 pass, 0 fail (8 new tests added, including the full duraclaw issue #60 scenario: stale agents from 7h ago + SDK string-form user prompts → guard returns false).

End-to-end SDK transcript repro

Hand-crafted SDK-shape transcript (two unmatched Agent tool_uses + string-form content: "next task" user prompt). Pre-fix: hasActiveBackgroundAgents returned true (stale IDs poison the guard). Post-fix: returns false.

Agentic evals

• `npm run eval -- --scenario=task-mode` → 1/1 passed ($0.95, 66 turns, 1 subagent call). Stop hook fired once at session end with `decision: "allow", reasons: [], note: "all conditions met"` — guard behaves correctly around subagent use, no regression.
• `npm run eval -- --scenario=stop-hook-enforcement` → workflow assertions pass (mode, commit, clean tree, can-exit, tasks completed, task-deps, no TaskCreate), eventually-allowed passes. The two failing assertions (`stop hook blocked >= 1 time(s)`, `blocked with reason task.*pending`) are scenario-level flakiness: SDK-driven sessions only fire the Stop hook when the `query()` message stream concludes, not between tool calls, so the agent completed all 6 prompted steps in a single SDK run and the hook never got an opportunity to block intermediately. This is unrelated to bug(hook): SDK session string-form user prompts defeat stop-hook staleness guard (re-opens #60) #68 — no subagents were spawned (0 Agent/Task tool_uses in transcript), so the guard was never in play.

The fix is correct and non-regressive. The stop-hook-enforcement scenario's block-count expectation is incompatible with how the SDK drives Stop hooks; that's a separate scenario-design issue.