Docs: publish JSONL session schema for ~/.claude/projects/

Summary

The session transcripts at ~/.claude/projects/**/*.jsonl are a rich telemetry source, but there is no published schema. Anyone building performance tooling, analytics, or introspection scripts has to reverse-engineer the structure from live session files.

What would be useful

A documented schema covering:

• Top-level record types: user, assistant, tool_result, tool_error, queue-operation, and the attachment types (deferred_tools_delta, mcp_instructions_delta)
• For assistant records: message.model, message.content[] blocks (text, thinking, tool_use), message.usage with cache token fields, requestId, sessionId, cwd, gitBranch
• For tool_use blocks: name, input (shape varies per tool), id, caller
• Subagent layout: <SESSION_ID>/subagents/agent-<ID>.jsonl and .meta.json structure (agentType, description)
• Stability guarantees: which fields are stable across versions, which may change

Use cases this unlocks

• Performance digests (one-shot edit rate, agent-turn efficiency, model mix, activity distribution)
• Cost/usage dashboards built from the usage field
• Session replay and debugging tools
• Integration with observability platforms

Current workaround

Guessing from session samples, which breaks whenever the schema evolves. A CHANGELOG entry when it does would help too.