Carrying Decisions Across Compaction with PreCompact and SessionEnd Hooks

#!/usr/bin/env python3
"""PreCompact: mine the transcript for decisions and append them to a handoff file.
stdin: hook JSON (session_id, transcript_path, trigger, cwd)
out:   .claude/handoff/<session_id>.md
"""
import json
import re
import sys
from pathlib import Path
 
# Markers that signal a judgment call. Widening this set bloats the handoff,
# so it stays intentionally narrow.
MARKERS = re.compile(
    r"(decided|decision|constraint|because|instead of|do not|rejected|we will not)",
    re.IGNORECASE,
)
MAX_LINES = 60           # ceiling on what we re-inject later
MAX_CHARS_PER_LINE = 240
 
 
def iter_assistant_text(transcript: Path):
    """Read JSONL line by line. Skip torn lines: the file is written while we read."""
    with transcript.open(encoding="utf-8", errors="replace") as f:
        for raw in f:
            raw = raw.strip()
            if not raw:
                continue
            try:
                rec = json.loads(raw)
            except json.JSONDecodeError:
                continue
            if rec.get("type") != "assistant":
                continue
            content = rec.get("message", {}).get("content", [])
            if isinstance(content, str):
                yield content
                continue
            for block in content:
                if isinstance(block, dict) and block.get("type") == "text":
                    yield block.get("text", "")
 
 
def extract(transcript: Path) -> list[str]:
    seen, picked = set(), []
    for text in iter_assistant_text(transcript):
        for line in text.splitlines():
            line = line.strip(" -*#\t")
            if len(line) < 12 or not MARKERS.search(line):
                continue
            line = line[:MAX_CHARS_PER_LINE]
            if line in seen:     # drop restatements of the same decision
                continue
            seen.add(line)
            picked.append(line)
    return picked[-MAX_LINES:]  # newest decisions win
 
 
def main() -> int:
    payload = json.load(sys.stdin)
    transcript = Path(payload["transcript_path"])
    if not transcript.exists():
        return 0                # nothing to rescue; exit quietly
 
    lines = extract(transcript)
    if not lines:
        return 0
 
    out_dir = Path(payload.get("cwd", ".")) / ".claude" / "handoff"
    out_dir.mkdir(parents=True, exist_ok=True)
    out = out_dir / f"{payload['session_id']}.md"
 
    with out.open("a", encoding="utf-8") as f:
        f.write(f"\n## compact ({payload.get('trigger', 'auto')})\n")
        for line in lines:
            f.write(f"- {line}\n")
 
    # stderr reaches the human, never the model's context.
    print(f"[handoff] {len(lines)} decisions -> {out}", file=sys.stderr)
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())

## compact (auto)
- Decision: articles.json holds metadata only; body HTML is split into public/content/
- Constraint: the Cloudflare Workers bundle ceiling is 62 MiB, so generated HTML cannot ship inside it
- We will not inline article bodies into articles.json again; that was reverted once already

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          { "type": "command", "command": "python3 .claude/hooks/handoff_capture.py", "timeout": 30 }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          { "type": "command", "command": "python3 .claude/hooks/handoff_capture.py", "timeout": 30 }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "resume",
        "hooks": [
          { "type": "command", "command": "python3 .claude/hooks/handoff_restore.py", "timeout": 10 }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
"""SessionStart: read the newest handoff and inject it as additionalContext."""
import json
import sys
from pathlib import Path
 
MAX_BYTES = 8_000   # inject more than this and you are spending budget, not buying clarity
 
 
def main() -> int:
    payload = json.load(sys.stdin)
    hand = Path(payload.get("cwd", ".")) / ".claude" / "handoff"
    files = sorted(hand.glob("*.md"), key=lambda p: p.stat().st_mtime)
    if not files:
        return 0
 
    text = files[-1].read_text(encoding="utf-8")[-MAX_BYTES:]
 
    # JSON printed to stdout is interpreted by Claude Code.
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "SessionStart",
            "additionalContext": (
                "Decisions confirmed in the previous session. "
                "Check here before proposing anything that contradicts them.\n\n" + text
            ),
        }
    }))
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())