hooks: content-aware transcript wait in enforce-insight-publish (race fix + test)

[evansenter]

Summary

Fix the transcript-stabilization race in enforce-insight-publish.sh (the Stop hook that enforces ★ Insight → publish_event).

Problem: the hook races Claude Code's transcript writer. The turn's final text block (carrying the insight) is often flushed after the hook fires. The old wait polled line count only — a writer that hadn't started flushing yet read as "stable & empty", so the hook missed the insight and failed to block (the original incident saw this in 3/4 firings).

Fix: content-aware wait — poll until line count is stable and the current turn contains an assistant text block, with a ~2s hard cap so a turn that legitimately ends without text (pure tool_use) isn't penalized.

Test: new regression test backgrounds the final text-block append ~300ms after the hook starts and asserts it still blocks. Fails on the old line-count-only wait; passes now.

Separate PR (not bundled in the audit PR #314) because it's the enforcement hook and warranted its own focused change + test.

Test plan

• make check — 89 hook tests pass (was 88 + new race test), shellcheck clean
• Existing enforce-insight tests unaffected (fully-flushed fixtures pass the content gate immediately)

🤖 Generated with Claude Code

[claude]

Code Review

Summary: Content-aware transcript wait is a well-targeted fix for a documented race, and the new regression test fails cleanly against the old line-count-only logic. The main gap is documentation drift: hooks/README.md still describes the old algorithm (the hooks own comment now points at a stale section).

Findings:

• [Important] home/.claude/hooks/README.md:282 — stale guidance.
• [Suggestion] home/.claude/hooks/enforce-insight-publish.sh:69 — hard cap doubled to ~2s; pure-tool_use turns always pay the full budget.
• [Suggestion] home/.claude/hooks/enforce-insight-publish.sh:79 — full transcript slurp per poll iteration once stable.
• [Suggestion] tests/test-hooks.sh:1431 — no test for tool_use-only turn that ends without a text block.

Verdict: REQUEST_CHANGES — README update needed; suggestions are optional.

---

Automated review by Claude Code

[claude]

[Important] Documentation drift. This comment says See hooks/README.md Gotchas but home/.claude/hooks/README.md:282 still describes the OLD algorithm verbatim: poll wc -l every 100ms, break when unchanged for two samples, hard-cap at 1s. With this PR that is no longer the pattern — it is now stable-for-2-samples PLUS a content gate, with a ~2s cap. Per the project CLAUDE.md (When adding or modifying hooks, update the README), please update the Gotcha entry so it matches the new behavior and rationale (content gate + writer-not-yet-started failure mode + the 2s cap reasoning).

[claude]

[Suggestion] Hard cap is effectively doubled (1s -> 2s) on every Stop firing. For turns that legitimately end with no text block (the pure tool_use case called out in the comment), the loop will ALWAYS run all 20 iterations because the content gate can never trip — adding a worst-case +1s of latency to those Stop hooks vs. the old design. If you wanted to recover that, you could break out once stable has been very high for several consecutive iterations (e.g. stable >= 5 => ~500ms idle) on the grounds that a turn that has been quiescent that long is not racing the writer anymore, regardless of text-block presence. Optional — happy to keep the simpler shape if the latency is acceptable.

[claude]

[Suggestion] Once stable >= 2, turn_has_assistant_text runs on every subsequent iteration — and each call slurps the entire transcript via jq -s. In the no-text path, that is up to ~18 full-file slurps inside the 2s budget. On long-running sessions where the transcript is large, each slurp can be non-trivial (tens of ms+) and the loops own wall time can drift past the intended 2s cap. Two cheap ways to bound this: (a) gate the content check to run at most every Nth iteration, or (b) once the file looks stable, capture the line count and only re-run the content check when it changes. Not blocking — just flagging the cost shape.

[claude]

[Suggestion] Nice regression test — it cleanly fails against the old line-count-only logic. The complementary case worth adding is the pure tool_use turn, no text block ever lands path that the new comment explicitly calls out as acceptable: assert that the hook exits within ~2s (hard cap) and emits NO block decision. That pins down the trade-off the PR is making and guards against a future refactor that accidentally turns the cap into a hang or a false block.

[evansenter]

Feedback Addressed

Implemented

• [Important] hooks/README.md:282 stale algorithm — rewrote the "Stop hooks race the transcript writer" Gotcha to describe the content-gate behavior, the writer-not-yet-started failure mode, the ~500ms quiescence early-out, and the 2s cap.
• [Suggestion] doubled worst-case latency — a textless (pure tool_use) turn now breaks once the file is quiescent for ~500ms (5 stable samples) instead of paying the full 2s. The stable -ge 5 test is ordered first so it short-circuits the jq content check.
• [Suggestion] per-poll slurp cost — as a result, turn_has_assistant_text now runs only on stable samples 2–4 (≤3 calls), not every iteration to the cap.
• [Suggestion] pure-tool_use test — added test_enforce_insight_publish_no_block_on_tool_only_turn: asserts no block decision and bounded exit.

All 90 hook tests pass; shellcheck clean.

[claude]

Automated review by Claude Code. APPROVE: content-aware transcript wait correctly fixes the writer race. All four prior review items addressed. One Suggestion follows in a PR comment (inline comment posting blocked by sandbox).

[claude]

Automated review by Claude Code.

Summary: Content-aware transcript wait correctly fixes the writer race. All four items from the prior review round are addressed: README updated to match the new algorithm, pure-tool_use turns early-out at ~500ms (not the full 2s cap), jq runs at most three times (stable samples 2-4), and a new regression test pins the textless-turn contract.

Previously Addressed (Filtered):

• [Important] hooks/README.md:282 stale algorithm — verified rewritten to describe content-gate + 500ms early-out + 2s cap.
• [Suggestion] Doubled worst-case latency — verified stable -ge 5 short-circuits before the jq call.
• [Suggestion] Per-poll slurp cost — verified bounded to <=3 calls.
• [Suggestion] Missing pure-tool_use test — verified added.

Findings:

[Suggestion] home/.claude/hooks/enforce-insight-publish.sh — the is_real_user definition and $start computation (finding the index of the last real user message) are duplicated verbatim between turn_has_assistant_text (lines 37-49) and the main ANALYSIS block (lines 106-115). If the rule for what counts as a real user event ever changes (e.g., another non-user event type to filter), both copies must stay in lockstep or the wait gate and the enforcement check will drift apart. Not blocking — sharing jq snippets between a shell function and an inline filter is genuinely awkward — but worth a cross-reference comment so a future editor knows to update both.

Verdict: APPROVE — code, docs, and tests are consistent; only the minor Suggestion above.

(Note: inline comment posting via gh api was blocked by sandbox restrictions on file creation; finding posted as a PR comment instead, per the documented fallback path.)