feat(session-handoffs): opt-in hooks for one current note and a no-note nudge

[lhoupert]

Adds two opt-in Claude Code hooks to session-handoffs. Each is off unless its environment variable is set:

• SESSION_HANDOFFS_GUARD=1: when a session is asked for a handoff or writes a new note, it is told which of its notes and snapshots are still current, and which memory lines name them. If the new note supersedes one that still has no banner, Claude gets one more turn to add it.
• SESSION_HANDOFFS_NUDGE=1: for sessions that never write notes. The first time a session has made 30 tool calls over 2 hours without one, the user sees one line; it costs no model tokens.

Stacked on #13. Tested with 54 unit tests, a replay of a real duplicate-note incident, and timings on a 21 MB transcript (about 20–40 ms per event).

For reviewers: tried in a live Claude Code 2.1.285 session loaded with --plugin-dir. The prompt, Write and Stop hooks each gave the expected context, and the Stop feedback came once, with no loop. The nudge, which needs 2 hours, was checked only in tests. It reads the same undocumented transcript format as #13 and stays silent (exit 0, no output) on anything unexpected.

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

AI-assisted: Claude Code wrote the hook, tests and docs, after checking the hook contract against the Claude Code docs and real transcripts. It went through a /code-review max and two rounds of independent verification. Every rule has a test that fails without it.

🤖 Generated with Claude Code

[claude]

Claude finished @lhoupert's task in 18s —— View job

---

❌ Changes requested — see findings below.

Blocking

• skills/session-handoffs/scripts/handoff_guard.py:455 (on_stop): the Stop output is {"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": …}}. As far as I know, Claude Code's Stop hook doesn't accept hookSpecificOutput/additionalContext. It is only defined for events like UserPromptSubmit, PostToolUse and SessionStart. The way to give Claude one more turn from a Stop hook is {"decision": "block", "reason": "<text>"}.
  • As written, the "one more turn to add the banner" feature is probably a silent no-op.
  • Nothing in the tests or docs covers decision/block, so the tests can't catch this. The PR also says the hook has not been tried in a live session.
  • The existing stop_hook_active early return at line 496 only makes sense with block, which suggests that was the intent.
  • Suggested fix:

    s = listing(head, left, t, config)
    return {"decision": "block", "reason": s} if s else None

    Then update the Stop tests to assert this shape. Please confirm in a scratch session before merging, since the transcript and hook contract are undocumented.

Non-blocking notes

• handoff_guard.py:537: except BaseException also swallows KeyboardInterrupt and SystemExit. That is deliberate and documented, so fine.
• hooks.json: the || true after python3 is redundant. main() already never exits non-zero, apart from interpreter failure. Harmless.

Simplify (ponytail)

• handoff_guard.py (542 lines) and test_handoff_guard.py (1135 lines): a lot of regex heuristics (NOT_ASKED, SAYS, NEGATED, CONTINUED, REMARK) parse free text for "Supersedes". A fixed frontmatter/first-line convention such as Supersedes: <path> would let you delete most of them. Keep the current approach if typed-text tolerance matters more.
• NOTES_LINE plus the REMARK fallbacks in snapshots(): read one path from a single documented form, and delete the three-way retry loop.
• before(), last_turn() and lineage() each re-scan the transcript. lineage() could return the first-timestamp and call count as well, to avoid the separate pass.

I didn't run the tests.

---

💰 Estimated review cost: $0.15 · 0m17s · 6 turns

[dannybauman]

@lhoupert I don't think the Claude bot's blocking issue is real. it says the Stop hook can't hand Claude that extra turn the way you wrote it, but the Claude Code hooks docs say it can: https://code.claude.com/docs/en/hooks#stop-decision-control

that lines up with what you saw when you tried it live, and the tests pass for me too