Cache Safe Stop Hook Snapshotting

SKILL: Cache-Safe Stop-Hook Snapshotting

Domain: context-management
Trigger: Apply when end-of-turn hooks need to persist enough state for follow-up helpers, but background forks must not overwrite the main session snapshot. Source Pattern: Distilled from reviewed context, compaction, and memory-governance patterns.

Core Method

Build one structured hook context at turn end, then persist a cache-safe snapshot only when the query source belongs to the main interactive session or the SDK control path. This gives downstream helpers a stable resume surface while preventing side agents and background forks from clobbering shared state with their own narrower contexts. The snapshot gate lives outside optional prompt-suggestion features so every consumer that depends on the shared state still gets it.

Key Rules

• Create the snapshot from the full stop-hook context, not ad hoc fragments, so later consumers see the same system, user, and tool state.
• Gate snapshot persistence to the authoritative query sources such as repl_main_thread and sdk.
• Keep forked or background agents out of the shared snapshot path; their contexts are partial and will pollute resume behavior.
• Decouple snapshotting from optional background features so state persistence remains available even when prompt suggestions are off.

Example Application

If a REPL turn finishes and /btw or another side-question helper may run next, save a cache-safe snapshot from the main turn’s hook context. If a background memory extractor reaches the same stop-hook code, skip the snapshot so the main session state remains authoritative.

Anti-Patterns (What NOT to do)

• Do not let every subagent write to the same cache-safe snapshot location; later helpers will resume from polluted or incomplete context.
• Do not tie snapshot persistence to an unrelated feature flag when multiple consumers depend on it.