---
name: cache-safe-stop-hook-snapshotting
description: "Persist a cache-safe stop-hook context snapshot only for main session queries so later helpers can resume from stable state without fork pollution."
metadata:
  author: ychampion
---

# 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.