cc-reload-plugin CLAUDE.md

cc-reload — maintainer handoff

This file is the mental model for anyone (human or agent) changing this plugin. Read it before touching hooks/. The README explains what the plugin does for users; this explains why the code is shaped the way it is, which invariants are load-bearing, and how to change each piece without breaking the others.

What this is, in one paragraph

Four bash hooks + three slash commands + one skill that keep a Claude Code session's working thread alive across context resets. State machine on disk under the user's project at .reload/: a digest (session.md), a one-shot arm marker (pending, now stamped with its arming session id when known), a two-pass handshake marker (summarizing), a notify ladder (notified), a model/window stamp (model), per-project config (config), and — since 0.3 — side-filed digests from a detected cross-session collision (session.<id>.md). The fourth hook, PreToolUse, is a same-session enforcement point for that collision guard, not a new continuity mechanism. There is no daemon, no state anywhere else, and no network on the per-turn hot path — SessionStart makes one optional loopback-only lookup against a local cc-proxy (see the proxy_window() decision below), fail-open, never repeated per-turn.

Control flow (the whole system)

Stop hook (every turn end)
  ├─ summarizing marker present?  → PASS 2: consume marker; if digest exists, arm `pending`
  │     and VERIFY the arm with -f (not a regular file → "reload NOT armed", never "saved")
  │     (fresh digest → success msg; digest not rewritten this turn → arm anyway, warn honestly;
  │      no digest → do NOT arm, warn)
  │  (occupancy below = the last MAIN-THREAD assistant row of a tail window of the transcript,
  │   per-line parsed; full-file stream only if the window holds none — invariant 14)
  ├─ stop_hook_active && no marker? → stand down (broken handshake must never re-block = loop)
  ├─ occupancy < budget?          → clear the `notified` ladder, exit silently
  └─ occupancy ≥ budget           → branch on context_budget_mode (default notify):
        ├─ snapshot mode AND not armed (NO entry at `pending`: -e, not -f — invariant 15)   [legacy `checkpoint` aliases here]
        │   → PASS 1: write `summarizing` marker and VERIFY it with -f (or refuse to block),
        │     emit {decision:"block"} re-injecting "write .reload/session.md, then STOP"
        └─ notify mode, OR snapshot mode already armed
            → laddered nudge: {systemMessage} only — never blocks, zero model tokens.
              Fires on first crossing, then only at last-notified +10 points (`notified`
              stores the %). Ladder unwritable → silent (else it would nag every turn).

PreCompact hook (manual /compact or auto-compaction)
  └─ arm `pending`; if no digest exists, write a mechanical fallback stub (honest about being thin)

SessionStart hook (startup|resume|clear|compact)
  ├─ stamp model id + resolved window to .reload/model (Stop gets no model field — this bridges it)
  ├─ startup|clear|compact (NOT resume) → purge leaked `summarizing` + `notified`; a handshake
  │     must not outlive its context (see invariant 10)
  └─ `pending` present? → inject digest as additionalContext + visible systemMessage banner
        (WARNS if `pending`'s stamped owner differs from this session's id — never gates on it);
        consume the marker (one-shot). Not armed → do nothing (a deliberate /clear is respected).

PreToolUse hook (model Write/Edit)
  └─ path == $DIGEST && tool is Write|Edit && payload has session_id?
       → claim-digest.sh: foreign + fresh incumbent -> side-file + warn; ALWAYS exit 0 (permit)