[FEATURE] Stable, documented schema for ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl line types

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Context

We are building a sibling VS Code / Cursor / Windsurf extension (aims.dashboard) that runs alongside the official anthropic.claude-code extension. The extension provides a four-pane operational shell over Claude Code: a persistent always-on chat pane that we drive ourselves through the Claude Agent SDK, and a per-task tab pane that is owned by the official extension. For the per-task pane we cannot use SDK in-process hooks, because we did not spawn those sessions; the official extension did. Our only viable observation channel for those sessions is to file-watch the append-only JSONL transcripts under ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl.

Direct inspection of extension.js v2.1.119 confirms there is no public VS Code API exported from the official extension, no extensionDependencies hook, no command surface for observing session state, and the IDE MCP bridge under ~/.claude/ide/<port>.lock exposes driver-side tools (manipulate the IDE) rather than observer-side events (watch what the CLI is doing). The JSONL transcript is the only durable, cross-process observation channel for sessions we did not spawn ourselves.

Several community dashboards already depend on this surface (examples in the references section). We expect more to appear as VS Code 1.109's multi-agent positioning takes hold.

What we observed

A spot-check of current local transcripts on Claude Code v2.1.118 / v2.1.119 surfaces the following top-level type values in a single mid-length project session:

agent-name
assistant
attachment
custom-title
file-history-snapshot
last-prompt
permission-mode
queue-operation
system
user

type=system carries a subtype field. The values we have observed are:

away_summary
bridge_status
compact_boundary
local_command
scheduled_task_fire
stop_hook_summary
turn_duration

When the CLI is launched with --include-hook-events, we additionally see system/hook_callback lines.

Several of these (agent-name, custom-title, queue-operation, local_command, scheduled_task_fire, pr-link, system/bridge_status) are recent additions that did not appear in older transcripts and are not described in the public docs. We have no way to know whether new types are additive (safe) or whether existing types may be renamed or removed (breaking).

Why I think this benefits Anthropic

• More durable third-party integrations. A documented and stable schema lets the ecosystem of dashboards, statusline scripts, and observability tools track Claude Code releases without breaking on every upgrade.
• Reduced support load. Tool-builders today reverse-engineer the schema from minified extension.js and a sample of live transcripts. A single documentation page absorbs the questions that currently end up on issues, Discord, and community blog posts.
• Aligns with VS Code 1.109 multi-agent direction. The official editorial line ("running Claude and Codex agents directly alongside Copilot is the future") implies a richer ecosystem of co-resident extensions. A stable observation contract is a load-bearing piece of that ecosystem.
• Existing community dependence. Several community dashboards already parse the format (jspw/Claude-Code-Dashboard, nateherkai/token-dashboard, withLinda/claude-JSONL-browser, phuryn/claude-usage, statusline scripts via ccusage and ClaudeCodeStatusLine). Documenting the contract recognises a surface the ecosystem is already treating as public.

Proposed Solution

We would like one or more of the following:

1. Documented schema for each line type and system.subtype value. A single page (e.g. under code.claude.com/docs/en/) listing each type/subtype and its required and optional fields. This need not be exhaustive; the core types (user, assistant, system/*, attachment, permission-mode) cover most observer use cases.

1. A stability commitment. A statement of the form "additions are safe at any minor release; removals or renames are announced in the changelog one minor release ahead." Even a SemVer-style versioning of the transcript schema (separate from the CLI SemVer if necessary) would be enough for tool-builders to pin a known-good schema and detect drift.

1. Changelog entry per minor release listing JSONL additions or changes. The current changelog at anthropics/claude-agent-sdk-typescript and the Claude Code release notes do not mention JSONL line-type changes. A one-line note when a new type or system.subtype is introduced would let tool-builders update their parsers in step.

Alternative Solutions

A public observation API. If the schema is too volatile to commit to, an alternative is a public event surface -- either via the existing IDE MCP bridge (additional MCP tools whose role is observation, e.g. mcp__ide__subscribeToolEvents), via a published cross-extension API on the official VS Code extension (an EventEmitter returned from activate()), or via a Language Model Chat Participant interface that other extensions can subscribe to. Any of these would let us drop the file-watch path entirely.

Priority

Critical - Blocking my work

Feature Category

Developer tools/SDK

Use Case Example

Use case

aims.dashboard provides a four-pane operational shell:

• Pane 1 (always-on CoS chat): SDK-driven; we own these sessions and use the SDK's in-process hook surface (SessionStart, PreToolUse, PostToolUse, Notification, Stop, PreCompact). This pane is unaffected by JSONL schema changes.
• Pane 2 (per-task session tabs): owned by the official extension via the URI handler vscode://anthropic.claude-code/open?prompt=...&session=.... We file-watch the JSONL to surface tool-call status, permission prompts, and session-end signals in a sidebar tray. This pane breaks silently when an unknown type or new required field appears.
• Pane 3 (status tray): Supabase-backed projection of state across cockpits. Receives events from both Pane 1 (SDK callbacks) and Pane 2 (JSONL tail).
• Pane 4 (preview): unaffected.

The hybrid model lets us keep the polished UX of the official extension for the per-task pane (auto-accept diffs, native diff viewer, plan-mode markdown editing, sessions list, checkpoints) while still surfacing per-tool-call activity to operators in Pane 3 within a sub-second budget.

If the JSONL schema is volatile, our Pane 2 observability degrades silently on every CLI upgrade. We currently mitigate this by pinning the CLI version via pathToClaudeCodeExecutable and writing a tolerant parser that ignores unknown type values, but a stability contract from Anthropic would let us decouple from the pinned version and keep up with upstream improvements automatically.

Additional Context

References

Related issues we found while scoping this request (these illustrate the broader observation gap and are not duplicates of this request):

• anthropics/claude-code#22968 -- high CPU/memory in long sessions; relevant because tools that observe CLI state often need to detect this condition.
• anthropics/claude-code#34640 -- feature request for folder-scoped launches via URI handler.
• anthropics/claude-code#36949 -- feature request for claudeCode.workingDirectory setting.
• anthropics/claude-code#23119 -- JetBrains plugin discovery via the lock-file pattern (related observation surface).
• anthropics/claude-code#24594 -- --input-format stream-json is undocumented; tool-builders depend on undocumented surfaces.
• Datadog Security Labs CVE-2025-52882 -- IDE MCP bridge auth-token model.
• Community dashboards depending on the JSONL: jspw/Claude-Code-Dashboard, nateherkai/token-dashboard, withLinda/claude-JSONL-browser, phuryn/claude-usage.
• Statusline references that show how the JSON-on-stdin schema (already documented at code.claude.com/docs/en/statusline) became a community-stable contract -- a similar treatment of JSONL would be welcome.

Environment

• Claude Code CLI: v2.1.118 / v2.1.119 (Linux + macOS spot-checks)
• Claude Agent SDK (TypeScript): @anthropic-ai/claude-agent-sdk >= 0.2.86
• VS Code 1.109+, Cursor 3.x, Windsurf
• Operating systems: Linux (primary), macOS, Windows

Happy to provide further sample transcripts or specific spot-check evidence if useful.