[FEATURE] Implement agent-trace standard for event emission and observability

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

As developers build workflows and tools around Claude Code, we currently face a "black box" problem regarding observability. There is no structured, machine-readable way to monitor the agent's internal lifecycle (planning, tool execution, reasoning) in real-time.

Currently, if I want to visualize what Claude Code is doing in an external dashboard, or wrap it within another IDE/Tool, I have to rely on parsing the raw text/TUI output. This is brittle, prone to breaking if text formatting changes, and doesn't provide the semantic depth needed for advanced debugging or auditing.

Proposed Solution

I propose that Claude Code adopts the agent-trace standard (https://github.com/cursor/agent-trace) for optional event emission.

The ideal experience:

Users can run Claude Code with a flag (e.g., claude --trace) or enable it in configuration.

Claude Code emits structured JSON events to a specified output (stderr, a file, or a socket) following the agent-trace schema.

These events cover key lifecycle moments:

Run: The overall task execution.

Generation: The LLM streaming a thought or response.

Span: Discrete units of work like executing a tool, reading a file, or running a terminal command.

This allows any tool that supports agent-trace to instantly visualize and log Claude Code's activities without custom integration logic.

Alternative Solutions

1. Regex Parsing (Current Workaround): Scraping the TUI stdout/stderr. This is extremely fragile and misses internal context not displayed on screen.

1. Proprietary JSON Format: Anthropic could invent a custom JSON logging format. However, adopting agent-trace (which is gaining traction in the ecosystem, e.g., Cursor) fosters better interoperability and allows users to use existing visualization tools.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

Scenario: Building a specialized "Refactor Review" Dashboard

Context: I am a tech lead running a large-scale refactor using Claude Code across a monorepo.

Action: I invoke Claude Code via a script: claude "refactor util.ts" --trace=./traces/run_1.jsonl.

Visualization: I open a local viewer (like an open-source trace viewer) pointing to that file.

Result: I see a waterfall timeline showing exactly:

How long Claude spent "thinking" vs. "executing".

Which specific files were read and when.

The exact arguments passed to file-edit tools.

Benefit: I can identify loops where the agent got stuck or hallucinated file paths without reading through pages of conversational text.

Additional Context

Reference Implementation: The standard is defined here: https://github.com/cursor/agent-trace

Technical Consideration: This should likely be an opt-in feature to avoid performance overhead or log noise for standard users.

Privacy: Trace payloads should ideally respect existing privacy settings (e.g., scrubbing API keys).