docs: audit Claude Code v2.1 log format changes

[zawakin]

Summary

Audits how the Claude Code JSONL transcript format diverged from what the agtrace-providers Claude parser was written against (v2.1.x, Opus 4.7–4.8). Establishes shared context and a roadmap for the follow-up fixes.

Captured from ~40k records across recent sessions. Key findings:

• thinking text is now empty (only an encrypted signature remains) — the original "thinking invisible" symptom. Plaintext is unrecoverable (upstream change).
• 7 new record types silently fall into Unknown: ai-title, custom-title, last-prompt, attachment, mode, permission-mode, agent-name.
• agentId removed from all records → subagent/sidechain attribution can no longer key on it (deferred: no subagent data available to reverse-engineer the new mechanism).
• New system subtypes (away_summary, api_error, informational), new usage fields (thinking_tokens = reasoning, iterations, server_tool_use), 13+ dropped attachment subtypes.

All files still parse without error — the format change causes silent information loss, not crashes.

Notes

Docs-only. Lands the design record under docs/dev/; code changes follow as separate focused PRs (redacted-thinking marker + reasoning tokens, then new record types + system subtypes).

🤖 Generated with Claude Code