Data-driven capture mappings: make vendor hook-format drift a JSON edit (help wanted: real Cursor/Copilot payloads) #4

Background

Shale's capture adapters translate each agent's hook payload (Claude Code, Codex, Cursor, Copilot) into normalized evidence — which files were touched, which commands ran, the model and tokens. Each vendor's payload has its own field names, event names, and snake/camel quirks.

The problem: when a vendor changes its hook payload shape, capture breaks silently. Capture is fail-open by design (it must never disturb the agent), so a format change just produces zero events — no error, no crash, just a thinner card. Today, fixing that drift means a Go code change + rebuild + release.

The direction

We're moving every adapter's hook contract (event names, field names, variants, tool→op) out of Go and into per-tool JSON map files (internal/capture/maps/<tool>.json), read by a small shared engine. A vendor renaming a field becomes a JSON edit, not a code change. The maps are embedded in the binary, so a fresh install still works offline with zero setup.

The refactor is up as a draft PR: #2 (behavior-preserving — every existing fixture test passes unchanged). It'll merge a few days after the launch freeze.

Where you can help

The capture adapters are tier-2 'best-effort enhancement' — Shale always falls back to git for the file list, so a broken adapter degrades the card, it doesn't break anything. But better adapters mean better cards.

1. Real recorded payloads. Claude Code and Codex are the only adapters exercised against real sessions. Cursor and Copilot ship with synthetic fixtures — hand-shaped from docs, not recorded from live runs. If you use Cursor or Copilot, a captured real hook payload (with secrets scrubbed) is the single most valuable contribution: it lets us replace guesses with ground truth.
2. Drift reports. If your agent's card suddenly shows fewer files than it touched, that's likely payload drift. Open an issue with the (scrubbed) payload and we'll update the map.
3. New agents. Any agent with a hook mechanism can get an adapter — it's now mostly a JSON file.

Privacy note

Hook payloads can contain file paths and command strings. When sharing one, scrub secrets first. For reference, Shale's own capture already drops gitignored paths and masks token/secret shapes in commands before anything is committed.

Tracking PR: #2