cc-reload-plugin: Instructions file for Claude Code

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, one session: line per session since 0.5.0), per-project config (config), side-filed digests from a detected cross-session collision (session.<id>.md, since 0.3), and — since 0.5.0 — per-lineage arms (pending.<pid>, keyed on the Claude Code PROCESS id, which /clear keeps) and an append-only journal of every snapshot/arm/side-file/rehydrate. The fourth hook, PreToolUse, is a same-session enforcement point for the collision guard (and the journal's snapshot writer), 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. User-facing docs: README (short) + docs/how-it-works.md, docs/concurrent-sessions.md, docs/statusline.md.

Control flow (the whole system)

Stop hook (every turn end)
  ├─ summarizing marker present AND not another LIVE process's (invariant 22)?
  │     → PASS 2: consume marker; if digest exists, arm THIS lineage's slot (lib.sh arm_reload:
  │     `pending.<CLAUDE_PID>`, else bare `pending`) and VERIFY it 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_here (no consumable arm entry; a foreign LIVE arm does
        │   NOT count — F12; a stray directory DOES: -e, invariant 15)   [legacy `checkpoint` aliases here]
        │   → PASS 1: unless another LIVE process's `summarizing` sits there (then notify instead),
        │     write `summarizing` (sid + pid) 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_here
            → 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 this lineage's slot (arm_reload); on failure journal `arm-failed` (CC DISCARDS PreCompact's
     systemMessage — the SessionStart(compact) that follows surfaces it); if no digest exists,
     write a mechanical fallback stub (honest about being thin)

SessionStart hook (startup|resume|clear|compact|fork)
  ├─ stamp model id + resolved window to .reload/model, PER SESSION (`session:` line; Stop gets no
  │     model field — this bridges it; another session's startup never moves this one's window)
  ├─ startup|clear|compact (NOT resume|fork) → purge `notified`, and `summarizing` unless it is
  │     another LIVE process's (invariant 22); a handshake must not outlive its context (invariant 10)
  ├─ arms_here (own `pending.<pid>` first, then bare `pending` + ORPHANS whose pid is dead, newest
  │     first; a foreign LIVE arm is NEVER listed) empty?
  │     ├─ foreign live arm(s) exist → 🔒 notice "left in place, this session starts fresh", journal
  │     │     `defer`, exit — invariant 21
  │     ├─ source=compact and the journal's last event is `arm-failed` → surface it once (F06)
  │     └─ else do nothing (a deliberate /clear is respected)
  └─ else → resolve the digest: session.md, or, when its owner ≠ the arm's sid and a side-file
        `session.<armsid>*.md` exists, that side-file (this lineage's OWN thread — no warning);
        no side-file → session.md + the incoherence WARNING (never gates — invariant 3);
        consume every listed arm (one-shot); claim session.md (only when it is the source);
        inject as additionalContext + visible banner; warn above the 10,000-char hook-output cap
        (F05); journal `rehydrate`

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