hooks: cache-handoff Stop hook - wake idle claude before 1h prompt cache expires

[lroolle]

Description

Ship an opt-in Claude Code Stop hook that wakes an idle session ~50min in and has it write a hand-off while the 1h prompt cache is still warm.

Type

• New feature

Details

Reverse-engineered from claude 2.1.220: a command hook with asyncRewake: true that exits 2 is the only primitive that wakes an idle session (injects a priority-next task notification). Main-thread prompt cache TTL is 1h; the built-in away-summary fires only on terminal blur and hard-skips past 0.9x TTL, so an idle-but-focused session burns the cache with no hand-off.

The hook detaches on Stop, sleeps (default 50min), and exits 2 with a hand-off prompt on stderr only if the session is still idle, it is the newest sleeper for the session (pidfile supersede), and it has not already fired at this transcript position (donefile dedup).

Ships as a copy-in asset like skills/ — deva must not auto-write settings.json into the host-mounted ~/.claude (same call as the statusline non-redirect in deva.sh).

Related Files

• hooks/cache-handoff.sh (new)
• hooks/README.md (new)
• scripts/test-cache-handoff.sh (new)
• .github/workflows/ci.yml
• docs/advanced-usage.md
• CHANGELOG.md, DEV-LOGS.md

Test Plan

• hermetic test: skip on stop_hook_active, skip on missing session_id, fire exit 2 when idle, abort when transcript grew, dedup at same transcript position, supersede older sleeper
• shellcheck clean
• mkdocs section renders (existing page, no nav change)