Skip to content

Post-Compaction Re-read Protocol

Compaction summarises conversation history but discards the soft operational knowledge agents accumulate by reading instruction files early in a session. A targeted re-read restores that knowledge.

Overview

When Claude Code compacts a long session, it summarises older turns to free context space. The summary preserves task state — what was done, what remains — but paraphrases instruction file references, losing precision. The agent continues working with degraded rule fidelity rather than any visible error signal.

Users report consistent behavioral drift after compaction — rules followed reliably before the event are violated afterward — not because CLAUDE.md was removed, but because the paraphrased summary no longer carries the full constraint set.

Claude Code does reload CLAUDE.md after compaction (the InstructionsLoaded hook fires with load_reason: "compact"), but reload alone does not reliably restore behavioral compliance (anthropics/claude-code#14258). The re-read protocol makes the refresh explicit and confirms it took effect.

How It Works

There are two implementation forms:

Manual (prompt-based):

After any compaction event, issue a targeted prompt before resuming task work:

Reread AGENTS.md so it's still fresh in your mind.

For higher compliance, add a confirmation requirement:

Reread AGENTS.md and confirm the key rules you found before continuing.

Automated (SessionStart hook with compact matcher):

SessionStart hooks fire when a session resumes — including after compaction. Filtering on matcher: "compact" restricts the hook to compaction events only. Stdout from SessionStart hooks is injected into Claude's context.

Configure in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.local/bin/claude-post-compact-reminder"
          }
        ]
      }
    ]
  }
}

The hook script outputs a directive prompt to stdout, which Claude receives as context:

#!/usr/bin/env bash
INPUT=$(cat)
SOURCE=$(echo "$INPUT" | jq -r '.source // empty')

# Only fire on compact events (belt-and-suspenders with the matcher)
[ "$SOURCE" = "compact" ] || exit 0

cat <<'EOF'
IMPORTANT: Context was just compacted. STOP. You MUST:
1. Read AGENTS.md NOW
2. Confirm by briefly stating the key rules you found.
Do not proceed with any task until you have done this.
EOF

The mandatory language and confirmation requirement are intentional — a polite suggestion is treated as optional; an explicit stop-and-confirm prompt is not.

Note: PostCompact (added in v2.1.76) fires after compaction but has no decision control and cannot inject prompts into Claude's context. It is appropriate for observability tasks (logging, external updates) rather than re-read injection. This pattern is independently documented in the post_compact_reminder reference implementation.

Trade-offs

Approach Pros Cons
Manual prompt No setup; works in any tool Requires user to remember after every compaction
SessionStart hook (compact matcher) Deterministic; stdout injected into context Claude Code only; fires on session resume, not mid-session auto-compact
Marker-based (PreCompact + UserPromptSubmit) Fires mid-session for auto-compact; more granular control More complex wiring; two hooks instead of one

Diagram

sequenceDiagram
    participant U as User
    participant CC as Claude Code
    participant H as SessionStart Hook

    CC->>CC: Context fills → auto-compact fires
    CC->>CC: Generates compaction summary
    Note over CC: Session resumes
    CC->>H: SessionStart (source: compact)
    H-->>CC: stdout: re-read directive
    CC->>CC: Reads AGENTS.md / CLAUDE.md
    CC->>U: Confirms key rules restored
    U->>CC: Continue with task

Key Takeaways

  • Compaction discards soft operational knowledge even when CLAUDE.md survives in context — behavioral drift follows silently.
  • The InstructionsLoaded hook with load_reason: "compact" confirms Claude Code reloads instruction files, but reload does not guarantee compliance is restored.
  • Use SessionStart with matcher: "compact" (not PostCompact) to inject a re-read directive — PostCompact has no context injection capability.
  • Confirmation requirements ("state the key rules you found") improve compliance versus directive-only prompts.
  • For multi-agent sessions, each subagent's context can compact independently — the re-read must be applied per-agent, not just at the orchestrator.
Adopted — practitioner-sourced, corroborated Last reviewed: 2026-05-27
Feedback