Detect and gracefully handle Claude Code version drift

[Amb2rZhou]

Problem

Listed in RISKS.md as B3.

intern-clawd is tightly coupled to several Claude Code internals that are not part of any documented stable API:

• SessionStart and SessionEnd hook field names and JSON schema
• The customTitle JSONL entry format used by session-relocate.py
• The cwd-encoding rule for ~/.claude/projects/<encoded>/ (currently [^a-zA-Z0-9-] → -)
• The settings.json hooks schema

If Anthropic changes any of these in a future Claude Code release, the corresponding intern-clawd feature breaks silently — users see hooks no longer firing, sessions piling up in the wrong project dir, or context injection going missing.

There is currently no version detection and no compatibility shim.

Proposed fix

Phase 1 — make breakage visible

1. Version probe at install time — setup.sh runs claude --version (or reads it from ~/.claude/.config) and records the tested-against version into ~/.clawd/.cc-version
2. Version probe at hook time — every hook compares the live claude --version against the recorded one. On mismatch, log a warning to ~/.clawd/cc-version-drift.log (don't fail the hook, just warn)
3. Smoke test script — bash test-cc-compat.sh runs a synthetic session-start hook with a fixture JSON payload and asserts the hook produces a valid response. Include in CI.

Phase 2 — declare a tested matrix

4. README compatibility table — "Tested against Claude Code v1.x.y / v1.x.z; v1.a.b reported broken in #N"
5. CHANGELOG entries for any release that bumps the supported CC version

Phase 3 — abstract over schema (optional, if Anthropic shipped a stable hooks SDK)

6. Replace direct JSON parsing in hooks with a thin wrapper that hides the schema. Out of scope until Anthropic publishes one.

Acceptance criteria

• Phase 1 done: setup.sh records CC version, hooks warn on drift, smoke test exists
• Phase 2 done: README has a compatibility table

Open questions

• Where exactly does Claude Code expose its version? Is claude --version stable, or does the JSONL transcript contain it?
• Should we hard-fail on major version bumps, or always soft-warn?