Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(beaconjson): normalize Claude Code OTLP events

shukieshah85f69acfa464
diff --git a/README.md b/README.md
index 8c921f86..9e8baa9f 100644
--- a/README.md
+++ b/README.md
@@ -79,7 +79,7 @@ CI, and cloud surfaces.
| Agent harness | Collection path | Telemetry coverage |
| --- | --- | --- |
| [Antigravity CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-antigravity-cli) | Native hooks | Prompt, pre-tool, post-tool, stop, invocation, command, and file telemetry where Antigravity exposes hook payloads |
-| [Claude Code](https://docs.asymptotelabs.ai/cli/supported-runtimes-claude-code) | Local OTLP export plus optional hooks | Prompt, command, tool, file, lifecycle, subagent, and permission telemetry where emitted through OTLP or hooks |
+| [Claude Code](https://docs.asymptotelabs.ai/cli/supported-runtimes-claude-code) | Local OTLP export plus optional hooks | Prompt, command, tool, file, approval, API/model lifecycle, MCP connection, subagent, and session telemetry where emitted through OTLP or hooks |
| [Codex CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-codex-cli) | Local OTLP logs | Session, prompt, approval, and tool-result activity from Codex semantic logs |
| [Cursor](https://docs.asymptotelabs.ai/cli/supported-runtimes-cursor) | Native hooks | Prompt, tool, shell command, MCP-like, approval, and file edit telemetry |
| [Devin CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-devin) | Native hooks | Session, prompt, pre-tool, post-tool, permission request, stop, session-end, approval, and file telemetry |
diff --git a/collector-builder/exporter/beaconjsonexporter/README.md b/collector-builder/exporter/beaconjsonexporter/README.md
index 7dd7d59f..2913cd0d 100644
--- a/collector-builder/exporter/beaconjsonexporter/README.md
+++ b/collector-builder/exporter/beaconjsonexporter/README.md
@@ -12,9 +12,16 @@ Required behavior:
- Write one complete JSON object per line.
- Use the canonical `vendor=beacon`, `product=endpoint-agent`,
`schema_version=1.0` event contract.
-- Identify Claude Cowork OTLP resources and map prompts, tool/MCP calls, file
- access, approval decisions, API usage, token counts, costs, and errors into
- Beacon endpoint events.
+- Identify Claude Code and Claude Cowork OTLP resources and map prompts,
+ tool/MCP calls, file access, approval decisions, API usage, token counts,
+ costs, and errors into Beacon endpoint events.
+- For Claude Code logs, decode JSON-string `tool_input` and `tool_parameters`
+ attributes into canonical `command.*` and `file.*` fields. Only actual tool
+ results may become tool, command, or file actions; API, assistant, plugin,
+ hook, skill, and other lifecycle logs use session actions, while MCP
+ connection lifecycle uses `mcp.connection`.
+- Preserve explicitly supplied Beacon action/category attributes and retain the
+ original OTLP attributes under `raw.attributes`.
- Include configured content fields by default, with `metadata` and `redacted`
modes available for stricter deployments.
- Redact common secrets and cap event size before writing.
diff --git a/collector-builder/exporter/beaconjsonexporter/exporter_test.go b/collector-builder/exporter/beaconjsonexporter/exporter_test.go
index 64ea8b29..707c3220 100644
--- a/collector-builder/exporter/beaconjsonexporter/exporter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/exporter_test.go
@@ -1194,6 +1194,118 @@ func TestCodexToolResultExtractsShellCommand(t *testing.T) {
}
}
+func TestConsumeLogsNormalizesCapturedClaudeCodeToolEvents(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ exp, err := newExporter(&Config{
+ Path: path,
+ MaxEventBytes: defaultMaxEventBytes,
+ RotateBytes: defaultRotateBytes,
+ RedactSecrets: true,
+ }, exporter.Settings{})
+ if err != nil {
+ t.Fatalf("newExporter returned error: %v", err)
+ }
+
+ logs := capturedClaudeLogs(t, "claude-code-2.1.220.json")
+ if err := exp.consumeLogs(context.Background(), logs); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+
+ output, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read runtime JSONL: %v", err)
+ }
+ var sawAPI, sawAllowed, sawCommand, sawWrite, sawRead bool
+ for _, line := range strings.Split(strings.TrimSpace(string(output)), "\n") {
+ var event beaconEvent
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("decode runtime event: %v", err)
+ }
+ switch event.Event.Action {
+ case "session.activity":
+ if event.Message == "claude_code.api_request" {
+ sawAPI = sawAPI || event.Event.Category == "session"
+ }
+ case "approval.allowed":
+ sawAllowed = sawAllowed || event.Approval != nil && event.Command != nil && event.Command.Command == "echo CLAUDE_MARKER"
+ case "command.executed":
+ sawCommand = sawCommand || event.Command != nil && event.Command.Command == "echo CLAUDE_MARKER" && event.Command.DurationMS == 94 && event.Command.ExitCode == nil
+ if attrs, ok := event.Raw["attributes"].(map[string]interface{}); !ok || attrs["tool_input"] == "" {
+ t.Fatalf("command raw attributes missing: %#v", event.Raw)
+ }
+ case "file.modified":
+ sawWrite = sawWrite || event.File != nil && event.File.Path == "/tmp/beacon-otel-fixture/CLAUDE_FILE_MARKER.txt"
+ case "file.read":
+ sawRead = sawRead || event.File != nil && event.File.Path == "/tmp/beacon-otel-fixture/CLAUDE_FILE_MARKER.txt"
+ }
+ }
+ if !sawAPI || !sawAllowed || !sawCommand || !sawWrite || !sawRead {
+ t.Fatalf("normalized events missing: api=%v allowed=%v command=%v write=%v read=%v\n%s", sawAPI, sawAllowed, sawCommand, sawWrite, sawRead, output)
+ }
+}
+
+func TestConsumeLogsClassifiesCapturedClaudeCodeLifecycleEvents(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ exp, err := newExporter(&Config{
+ Path: path,
+ MaxEventBytes: defaultMaxEventBytes,
+ RotateBytes: defaultRotateBytes,
+ RedactSecrets: true,
+ }, exporter.Settings{})
+ if err != nil {
+ t.Fatalf("newExporter returned error: %v", err)
+ }
+
+ logs := capturedClaudeLogs(t, "claude-code-lifecycle-2.1.220.json")
+ unknown := logs.ResourceLogs().At(0).ScopeLogs().At(0).LogRecords().AppendEmpty()
+ unknown.Body().SetStr("claude_code.future_lifecycle_event")
+ unknown.Attributes().PutStr("service.name", "claude-code")
+ unknown.Attributes().PutStr("event.name", "future_lifecycle_event")
+ if err := exp.consumeLogs(context.Background(), logs); err != nil {
+ t.Fatalf("consumeLogs returned error: %v", err)
+ }
+
+ output, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read runtime JSONL: %v", err)
+ }
+ expected := map[string]eventInfo{
+ "claude_code.assistant_response": {Action: "session.activity", Category: "session"},
+ "claude_code.api_error": {Action: "session.error", Category: "session"},
+ "claude_code.api_refusal": {Action: "session.status", Category: "session"},
+ "claude_code.permission_mode_changed": {Action: "session.status", Category: "session"},
+ "claude_code.mcp_server_connection": {Action: "mcp.connection", Category: "mcp"},
+ "claude_code.internal_error": {Action: "session.error", Category: "session"},
+ "claude_code.future_lifecycle_event": {Action: "session.activity", Category: "session"},
+ }
+ seen := map[string]bool{}
+ for _, line := range strings.Split(strings.TrimSpace(string(output)), "\n") {
+ var event beaconEvent
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("decode runtime event: %v", err)
+ }
+ if strings.HasPrefix(event.Message, "claude_code.") {
+ switch event.Event.Action {
+ case "tool.invoked", "command.executed", "mcp.tool_invoked":
+ t.Errorf("%s incorrectly serialized as %s", event.Message, event.Event.Action)
+ }
+ }
+ want, ok := expected[event.Message]
+ if !ok {
+ continue
+ }
+ if event.Event.Action != want.Action || event.Event.Category != want.Category {
+ t.Errorf("%s event = %#v, want %s/%s", event.Message, event.Event, want.Action, want.Category)
+ }
+ seen[event.Message] = true
+ }
+ for message := range expected {
+ if !seen[message] {
+ t.Errorf("missing representative lifecycle event %s", message)
+ }
+ }
+}
+
func TestCodexPromptMessageKeepsTypedPrompt(t *testing.T) {
exp, err := newExporter(&Config{
Path: filepath.Join(t.TempDir(), "runtime.jsonl"),
@@ -1717,6 +1829,33 @@ func TestVSCodeCopilotInvokeAgentUserRequestBecomesPrompt(t *testing.T) {
}
}
+func capturedClaudeLogs(t *testing.T, name string) plog.Logs {
+ t.Helper()
+ data, err := os.ReadFile(filepath.Join("internal", "beaconevent", "testdata", name))
+ if err != nil {
+ t.Fatalf("read captured Claude fixture: %v", err)
+ }
+ var fixture struct {
+ Records []struct {
+ Body string `json:"body"`
+ Attributes map[string]interface{} `json:"attributes"`
+ } `json:"records"`
+ }
+ if err := json.Unmarshal(data, &fixture); err != nil {
+ t.Fatalf("decode captured Claude fixture: %v", err)
+ }
+ logs := plog.NewLogs()
+ scopeLogs := logs.ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty()
+ for _, captured := range fixture.Records {
+ record := scopeLogs.LogRecords().AppendEmpty()
+ record.Body().SetStr(captured.Body)
+ if err := record.Attributes().FromRaw(captured.Attributes); err != nil {
+ t.Fatalf("load captured attributes: %v", err)
+ }
+ }
+ return logs
+}
+
func containsString(values []string, want string) bool {
for _, value := range values {
if value == want {
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index bcedba7d..bdbbd342 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -22,8 +22,43 @@ const (
CodexUserPrompt = "codex.user_prompt"
CodexToolDecision = "codex.tool_decision"
CodexToolResult = "codex.tool_result"
+ ClaudeAPIRequest = "claude_code.api_request"
+ ClaudeToolDecision = "claude_code.tool_decision"
+ ClaudeToolResult = "claude_code.tool_result"
)
+type eventClassification struct {
+ action string
+ category string
+}
+
+var claudeLogEventClassifications = map[string]eventClassification{
+ "claude_code.user_prompt": {action: "prompt.submitted", category: "prompt"},
+ "claude_code.assistant_response": {action: "session.activity", category: "session"},
+ ClaudeToolResult: {},
+ ClaudeAPIRequest: {action: "session.activity", category: "session"},
+ "claude_code.api_error": {action: "session.error", category: "session"},
+ "claude_code.api_refusal": {action: "session.status", category: "session"},
+ "claude_code.api_request_body": {action: "session.activity", category: "session"},
+ "claude_code.api_response_body": {action: "session.activity", category: "session"},
+ ClaudeToolDecision: {},
+ "claude_code.permission_mode_changed": {action: "session.status", category: "session"},
+ "claude_code.auth": {action: "session.activity", category: "session"},
+ "claude_code.mcp_server_connection": {action: "mcp.connection", category: "mcp"},
+ "claude_code.internal_error": {action: "session.error", category: "session"},
+ "claude_code.plugin_installed": {action: "session.activity", category: "session"},
+ "claude_code.plugin_loaded": {action: "session.activity", category: "session"},
+ "claude_code.skill_activated": {action: "session.activity", category: "session"},
+ "claude_code.at_mention": {action: "session.activity", category: "session"},
+ "claude_code.api_retries_exhausted": {action: "session.error", category: "session"},
+ "claude_code.hook_registered": {action: "session.activity", category: "session"},
+ "claude_code.hook_execution_start": {action: "session.activity", category: "session"},
+ "claude_code.hook_execution_complete": {action: "session.activity", category: "session"},
+ "claude_code.hook_plugin_metrics": {action: "session.activity", category: "session"},
+ "claude_code.compaction": {action: "session.activity", category: "session"},
+ "claude_code.feedback_survey": {action: "session.activity", category: "session"},
+}
+
var allowedCodexLogEvents = map[string]struct{}{
CodexConversationStarts: {},
CodexUserPrompt: {},
@@ -259,12 +294,13 @@ func shouldDropCopilotMetric(resourceAttrs map[string]interface{}, name string,
func (c Converter) EventFromLog(resourceAttrs map[string]interface{}, record plog.LogRecord) Event {
attrs := MergeMaps(resourceAttrs, AttrsToMap(record.Attributes()))
+ body := record.Body().AsString()
ts := Timestamp(record.Timestamp().AsTime())
action := FirstString(attrs, "beacon.event.action", "event.action", "gen_ai.agent.action", "ai.agent.action")
if action == "" {
- action = InferAction(attrs, record.Body().AsString())
+ action = InferAction(attrs, body)
}
- message := FirstNonEmpty(record.Body().AsString(), FirstString(attrs, "message", "log.message", "event.name"))
+ message := FirstNonEmpty(body, FirstString(attrs, "message", "log.message", "event.name"))
event := NewEvent(action, EventCategory(action, FirstString(attrs, "beacon.event.category", "event.category", "category")), Severity(record.SeverityText(), record.SeverityNumber().String()), HarnessName(attrs, message), ts)
event.Message = message
c.PopulateCommon(&event, attrs)
@@ -279,6 +315,7 @@ func (c Converter) EventFromLog(resourceAttrs map[string]interface{}, record plo
"severity": record.SeverityText(),
})
c.NormalizeCodexLogEvent(&event, attrs)
+ c.NormalizeClaudeLogEvent(&event, attrs, body)
return event
}
@@ -397,6 +434,162 @@ func codexArgumentCommand(args string) string {
return strings.TrimSpace(payload.Cmd)
}
+func (c Converter) NormalizeClaudeLogEvent(event *Event, attrs map[string]interface{}, body string) {
+ if event == nil || event.Harness.Name != "claude_code" {
+ return
+ }
+ originalAction := event.Event.Action
+ originalCategory := event.Event.Category
+ preserveAction := FirstString(attrs, "beacon.event.action", "event.action", "gen_ai.agent.action", "ai.agent.action") != ""
+ preserveCategory := preserveAction || FirstString(attrs, "beacon.event.category", "event.category", "category") != ""
+
+ eventName := ClaudeLogEventName(attrs, body)
+ switch eventName {
+ case ClaudeToolDecision:
+ NormalizeClaudeToolDecision(event, attrs)
+ case ClaudeToolResult:
+ NormalizeClaudeToolResult(event, attrs)
+ case "":
+ return
+ default:
+ classification, ok := claudeLogEventClassifications[eventName]
+ if !ok {
+ classification = eventClassification{action: "session.activity", category: "session"}
+ }
+ event.Event.Action = classification.action
+ event.Event.Category = classification.category
+ }
+ if preserveAction {
+ event.Event.Action = originalAction
+ }
+ if preserveCategory {
+ event.Event.Category = originalCategory
+ }
+}
+
+func ClaudeLogEventName(attrs map[string]interface{}, body string) string {
+ if normalized := strings.ToLower(strings.TrimSpace(body)); strings.HasPrefix(normalized, "claude_code.") {
+ return normalized
+ }
+ normalized := strings.ToLower(strings.TrimSpace(FirstString(attrs, "event.name")))
+ if strings.HasPrefix(normalized, "claude_code.") {
+ if _, ok := claudeLogEventClassifications[normalized]; ok {
+ return normalized
+ }
+ return ""
+ }
+ if normalized != "" {
+ candidate := "claude_code." + normalized
+ if _, ok := claudeLogEventClassifications[candidate]; ok {
+ return candidate
+ }
+ }
+ return ""
+}
+
+func NormalizeClaudeToolDecision(event *Event, attrs map[string]interface{}) {
+ toolName := FirstString(attrs, "tool_name", "tool.name")
+ decision := FirstString(attrs, "decision")
+ switch strings.ToLower(decision) {
+ case "accept", "approve", "approved", "allow", "allowed":
+ event.Event.Action = "approval.allowed"
+ case "reject", "rejected", "deny", "denied":
+ event.Event.Action = "approval.denied"
+ default:
+ event.Event.Action = "approval.requested"
+ }
+ event.Event.Category = "approval"
+ event.Approval = &ApprovalInfo{
+ Required: true,
+ Decision: decision,
+ Reason: FirstString(attrs, "source"),
+ }
+ ensureClaudeTool(event, toolName)
+
+ params := JSONMapAttr(attrs, "tool_parameters")
+ if command := claudeCommand(nil, params); command != "" {
+ event.Command = &CommandInfo{Command: command}
+ event.Tool.Command = command
+ }
+ if path := FirstString(params, "file_path", "notebook_path"); path != "" {
+ event.File = &FileInfo{Path: path, Operation: claudeFileOperation(toolName)}
+ event.Tool.Path = path
+ }
+}
+
+func NormalizeClaudeToolResult(event *Event, attrs map[string]interface{}) {
+ toolName := FirstString(attrs, "tool_name", "tool.name")
+ ensureClaudeTool(event, toolName)
+ input := JSONMapAttr(attrs, "tool_input")
+ params := JSONMapAttr(attrs, "tool_parameters")
+
+ switch strings.ToLower(toolName) {
+ case "bash":
+ command := claudeCommand(input, params)
+ event.Event.Action = "command.executed"
+ event.Event.Category = "command"
+ event.Command = &CommandInfo{Command: command}
+ if duration, ok := Int64Attr(attrs, "duration_ms"); ok {
+ event.Command.DurationMS = duration
+ }
+ event.Tool.Command = command
+ case "read":
+ normalizeClaudeFileResult(event, toolName, input, "file.read")
+ case "write", "edit", "notebookedit":
+ normalizeClaudeFileResult(event, toolName, input, "file.modified")
+ }
+}
+
+func ensureClaudeTool(event *Event, toolName string) {
+ if event.Tool == nil {
+ event.Tool = &ToolInfo{}
+ }
+ if toolName != "" {
+ event.Tool.Name = toolName
+ }
+}
+
+func normalizeClaudeFileResult(event *Event, toolName string, input map[string]interface{}, action string) {
+ path := FirstString(input, "file_path", "notebook_path")
+ event.Event.Action = action
+ event.Event.Category = "file"
+ event.File = &FileInfo{
+ Path: path,
+ Operation: claudeFileOperation(toolName),
+ }
+ event.Tool.Path = path
+}
+
+func claudeFileOperation(toolName string) string {
+ switch strings.ToLower(toolName) {
+ case "read":
+ return "read"
+ case "write":
+ return "create"
+ case "edit", "notebookedit":
+ return "modify"
+ default:
+ return ""
+ }
+}
+
+func claudeCommand(input, params map[string]interface{}) string {
+ return FirstNonEmpty(
+ FirstString(input, "command"),
+ FirstString(params, "full_command"),
+ FirstString(params, "bash_command"),
+ )
+}
+
+func JSONMapAttr(attrs map[string]interface{}, key string) map[string]interface{} {
+ value, ok := AnyAttr(attrs, key)
+ if !ok {
+ return nil
+ }
+ decoded, _ := value.(map[string]interface{})
+ return decoded
+}
+
func (c Converter) EventFromMetric(resourceAttrs map[string]interface{}, metric pmetric.Metric) Event {
attrs := MergeMaps(resourceAttrs, map[string]interface{}{})
action := FirstString(attrs, "beacon.event.action", "event.action")
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
index d737e48f..5fb36f38 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
@@ -2,6 +2,8 @@ package beaconevent
import (
"encoding/json"
+ "os"
+ "path/filepath"
"strings"
"testing"
"time"
@@ -716,6 +718,374 @@ func TestEventsFromTracesDoesNotPromotePlainGenAIToolToMCP(t *testing.T) {
}
}
+func TestCapturedClaudeCodeLogNormalization(t *testing.T) {
+ fixture, events := capturedLogEvents(t, "claude-code-2.1.220.json")
+ if len(events) != len(fixture.Records) {
+ t.Fatalf("events = %d, want %d", len(events), len(fixture.Records))
+ }
+ byName := map[string]Event{}
+ for i, record := range fixture.Records {
+ byName[record.Name] = events[i]
+ }
+
+ apiRequest := byName["api_request"]
+ if apiRequest.Event.Action != "session.activity" || apiRequest.Event.Category != "session" {
+ t.Fatalf("api request event = %#v, want session.activity/session", apiRequest.Event)
+ }
+ if apiRequest.GenAI == nil || apiRequest.GenAI.Usage == nil || apiRequest.GenAI.Usage.InputTokens == nil || *apiRequest.GenAI.Usage.InputTokens != 2 {
+ t.Fatalf("api request usage = %#v, want captured input tokens", apiRequest.GenAI)
+ }
+
+ decision := byName["bash_decision"]
+ if decision.Event.Action != "approval.allowed" || decision.Event.Category != "approval" {
+ t.Fatalf("decision event = %#v, want approval.allowed/approval", decision.Event)
+ }
+ if decision.Approval == nil || !decision.Approval.Required || decision.Approval.Decision != "accept" || decision.Approval.Reason != "config" {
+ t.Fatalf("approval = %#v, want captured accept/config decision", decision.Approval)
+ }
+ if decision.Command == nil || decision.Command.Command != "echo CLAUDE_MARKER" {
+ t.Fatalf("decision command = %#v, want full command", decision.Command)
+ }
+
+ bash := byName["bash_result"]
+ if bash.Event.Action != "command.executed" || bash.Event.Category != "command" {
+ t.Fatalf("bash event = %#v, want command.executed/command", bash.Event)
+ }
+ if bash.Command == nil || bash.Command.Command != "echo CLAUDE_MARKER" || bash.Command.DurationMS != 94 {
+ t.Fatalf("bash command = %#v, want command and string duration", bash.Command)
+ }
+ if bash.Command.ExitCode != nil {
+ t.Fatalf("bash exit code = %#v, want nil without an exact process status", bash.Command.ExitCode)
+ }
+ if bash.Tool == nil || bash.Tool.Name != "Bash" || bash.Tool.Command != "echo CLAUDE_MARKER" {
+ t.Fatalf("bash tool = %#v, want normalized command", bash.Tool)
+ }
+ rawAttrs, ok := bash.Raw["attributes"].(map[string]interface{})
+ if !ok || rawAttrs["tool_input"] != fixture.Records[2].Attributes["tool_input"] {
+ t.Fatalf("raw attributes changed: %#v", bash.Raw)
+ }
+
+ for _, tc := range []struct {
+ name string
+ action string
+ operation string
+ }{
+ {name: "write_result", action: "file.modified", operation: "create"},
+ {name: "read_result", action: "file.read", operation: "read"},
+ } {
+ event := byName[tc.name]
+ if event.Event.Action != tc.action || event.Event.Category != "file" {
+ t.Fatalf("%s event = %#v, want %s/file", tc.name, event.Event, tc.action)
+ }
+ if event.File == nil || event.File.Path != "/tmp/beacon-otel-fixture/CLAUDE_FILE_MARKER.txt" || event.File.Operation != tc.operation {
+ t.Fatalf("%s file = %#v, want captured path/%s", tc.name, event.File, tc.operation)
+ }
+ if event.Tool == nil || event.Tool.Path != event.File.Path {
+ t.Fatalf("%s tool = %#v, want mirrored path", tc.name, event.Tool)
+ }
+ }
+}
+
+func TestCapturedClaudeCodeLifecycleTaxonomy(t *testing.T) {
+ fixture, events := capturedLogEvents(t, "claude-code-lifecycle-2.1.220.json")
+ if len(events) != len(fixture.Records) {
+ t.Fatalf("events = %d, want %d", len(events), len(fixture.Records))
+ }
+ expected := map[string]eventClassification{
+ "user_prompt": {action: "prompt.submitted", category: "prompt"},
+ "assistant_response": {action: "session.activity", category: "session"},
+ "api_request": {action: "session.activity", category: "session"},
+ "api_error": {action: "session.error", category: "session"},
+ "api_refusal": {action: "session.status", category: "session"},
+ "api_request_body": {action: "session.activity", category: "session"},
+ "api_response_body": {action: "session.activity", category: "session"},
+ "permission_mode_changed": {action: "session.status", category: "session"},
+ "auth": {action: "session.activity", category: "session"},
+ "mcp_server_connection": {action: "mcp.connection", category: "mcp"},
+ "internal_error": {action: "session.error", category: "session"},
+ "plugin_installed": {action: "session.activity", category: "session"},
+ "plugin_loaded": {action: "session.activity", category: "session"},
+ "skill_activated": {action: "session.activity", category: "session"},
+ "at_mention": {action: "session.activity", category: "session"},
+ "api_retries_exhausted": {action: "session.error", category: "session"},
+ "hook_registered": {action: "session.activity", category: "session"},
+ "hook_execution_start": {action: "session.activity", category: "session"},
+ "hook_execution_complete": {action: "session.activity", category: "session"},
+ "hook_plugin_metrics": {action: "session.activity", category: "session"},
+ "compaction": {action: "session.activity", category: "session"},
+ "feedback_survey": {action: "session.activity", category: "session"},
+ }
+ if len(claudeLogEventClassifications) != len(expected)+2 {
+ t.Fatalf("documented Claude taxonomy has %d events, want %d", len(claudeLogEventClassifications), len(expected)+2)
+ }
+ for i, captured := range fixture.Records {
+ want, ok := expected[captured.Name]
+ if !ok {
+ t.Fatalf("fixture %q has no expected classification", captured.Name)
+ }
+ event := events[i]
+ if event.Event.Action != want.action || event.Event.Category != want.category {
+ t.Errorf("%s event = %#v, want %s/%s", captured.Name, event.Event, want.action, want.category)
+ }
+ switch event.Event.Action {
+ case "tool.invoked", "command.executed", "mcp.tool_invoked":
+ t.Errorf("%s lifecycle event incorrectly classified as %s", captured.Name, event.Event.Action)
+ }
+ }
+ if prompt := events[0].Prompt; prompt == nil || prompt.Text != "CLAUDE_LIFECYCLE_MARKER" {
+ t.Fatalf("user prompt = %#v, want captured prompt", prompt)
+ }
+}
+
+func TestClaudeLogEventNameRecognizesKnownShortNames(t *testing.T) {
+ for eventName := range claudeLogEventClassifications {
+ shortName := strings.TrimPrefix(eventName, "claude_code.")
+ if got := ClaudeLogEventName(map[string]interface{}{"event.name": shortName}, "unstructured body"); got != eventName {
+ t.Errorf("short event %q normalized to %q, want %q", shortName, got, eventName)
+ }
+ }
+}
+
+func TestClaudeLifecycleUsesResourceHarnessIdentity(t *testing.T) {
+ logs := plog.NewLogs()
+ resourceLogs := logs.ResourceLogs().AppendEmpty()
+ resourceLogs.Resource().Attributes().PutStr("service.name", "claude-code")
+ resourceLogs.Resource().Attributes().PutStr("service.version", "2.1.220")
+ record := resourceLogs.ScopeLogs().AppendEmpty().LogRecords().AppendEmpty()
+ record.Body().SetStr("claude_code.assistant_response")
+ record.Attributes().PutStr("event.name", "assistant_response")
+
+ events := NewConverter(Options{}).EventsFromLogs(logs)
+ if len(events) != 1 {
+ t.Fatalf("events = %d, want 1", len(events))
+ }
+ if events[0].Harness.Name != "claude_code" || events[0].Event.Action != "session.activity" || events[0].Event.Category != "session" {
+ t.Fatalf("event = %#v, want resource-scoped Claude session activity", events[0])
+ }
+}
+
+func TestClaudeUnknownFullBodyDefaultsToSessionActivity(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.future_lifecycle_event")
+ record.Attributes().PutStr("service.name", "claude-code")
+ record.Attributes().PutStr("event.name", "future_lifecycle_event")
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "session.activity" || event.Event.Category != "session" {
+ t.Fatalf("event = %#v, want safe session.activity fallback", event.Event)
+ }
+ if got := ClaudeLogEventName(map[string]interface{}{"event.name": "future_lifecycle_event"}, "unstructured body"); got != "" {
+ t.Fatalf("unknown short event normalized to %q, want no match", got)
+ }
+}
+
+func TestClaudeNormalizationPreservesExplicitClassification(t *testing.T) {
+ t.Run("explicit action keeps inferred category", func(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.assistant_response")
+ record.Attributes().PutStr("service.name", "claude-code")
+ record.Attributes().PutStr("event.name", "assistant_response")
+ record.Attributes().PutStr("beacon.event.action", "prompt.submitted")
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "prompt.submitted" || event.Event.Category != "prompt" {
+ t.Fatalf("event = %#v, want explicit prompt classification", event.Event)
+ }
+ })
+
+ t.Run("explicit category overrides taxonomy category", func(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.assistant_response")
+ record.Attributes().PutStr("service.name", "claude-code")
+ record.Attributes().PutStr("event.name", "assistant_response")
+ record.Attributes().PutStr("beacon.event.category", "custom")
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "session.activity" || event.Event.Category != "custom" {
+ t.Fatalf("event = %#v, want taxonomy action with explicit category", event.Event)
+ }
+ })
+
+ t.Run("tool operands still normalize", func(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.tool_result")
+ record.Attributes().PutStr("service.name", "claude-code")
+ record.Attributes().PutStr("event.name", "tool_result")
+ record.Attributes().PutStr("event.action", "custom.tool_result")
+ record.Attributes().PutStr("event.category", "custom")
+ record.Attributes().PutStr("tool_name", "Bash")
+ record.Attributes().PutStr("tool_input", `{"command":"echo explicit"}`)
+ record.Attributes().PutStr("duration_ms", "12")
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "custom.tool_result" || event.Event.Category != "custom" {
+ t.Fatalf("event = %#v, want explicit tool classification", event.Event)
+ }
+ if event.Command == nil || event.Command.Command != "echo explicit" || event.Command.DurationMS != 12 {
+ t.Fatalf("command = %#v, want normalized tool operands", event.Command)
+ }
+ })
+}
+
+func TestClaudeToolDecisionMapsRejectAndCommand(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.tool_decision")
+ attrs := record.Attributes()
+ attrs.PutStr("service.name", "claude-code")
+ attrs.PutStr("event.name", "tool_decision")
+ attrs.PutStr("tool_name", "Bash")
+ attrs.PutStr("decision", "reject")
+ attrs.PutStr("source", "user_reject")
+ attrs.PutStr("tool_parameters", `{"bash_command":"rm","full_command":"rm -rf /tmp/example"}`)
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "approval.denied" || event.Event.Category != "approval" {
+ t.Fatalf("event = %#v, want approval.denied/approval", event.Event)
+ }
+ if event.Approval == nil || event.Approval.Decision != "reject" || event.Approval.Reason != "user_reject" {
+ t.Fatalf("approval = %#v, want reject/user_reject", event.Approval)
+ }
+ if event.Command == nil || event.Command.Command != "rm -rf /tmp/example" {
+ t.Fatalf("command = %#v, want denied full command", event.Command)
+ }
+}
+
+func TestClaudeToolResultOperandPrecedenceAndCoercion(t *testing.T) {
+ event := NewEvent("tool.invoked", "tool", "info", "claude_code", time.Now())
+ NormalizeClaudeToolResult(&event, map[string]interface{}{
+ "tool_name": "Bash",
+ "duration_ms": int64(71),
+ "tool_input": `{"command":"echo input"}`,
+ "tool_parameters": `{"full_command":"echo parameters","bash_command":"echo"}`,
+ "success": "true",
+ })
+ if event.Command == nil || event.Command.Command != "echo input" || event.Command.DurationMS != 71 {
+ t.Fatalf("command = %#v, want tool_input command and numeric duration", event.Command)
+ }
+ if event.Command.ExitCode != nil {
+ t.Fatalf("exit code = %#v, want nil", event.Command.ExitCode)
+ }
+}
+
+func TestClaudeEditToolResultsMapFileOperations(t *testing.T) {
+ for _, tc := range []struct {
+ toolName string
+ inputKey string
+ operation string
+ }{
+ {toolName: "Edit", inputKey: "file_path", operation: "modify"},
+ {toolName: "NotebookEdit", inputKey: "notebook_path", operation: "modify"},
+ } {
+ t.Run(tc.toolName, func(t *testing.T) {
+ event := NewEvent("tool.invoked", "tool", "info", "claude_code", time.Now())
+ NormalizeClaudeToolResult(&event, map[string]interface{}{
+ "tool_name": tc.toolName,
+ "tool_input": `{"` + tc.inputKey + `":"/tmp/example.ipynb"}`,
+ })
+ if event.Event.Action != "file.modified" || event.Event.Category != "file" {
+ t.Fatalf("event = %#v, want file.modified/file", event.Event)
+ }
+ if event.File == nil || event.File.Path != "/tmp/example.ipynb" || event.File.Operation != tc.operation {
+ t.Fatalf("file = %#v, want path/%s", event.File, tc.operation)
+ }
+ })
+ }
+}
+
+func TestClaudeToolResultToleratesMalformedJSON(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.tool_result")
+ attrs := record.Attributes()
+ attrs.PutStr("service.name", "claude-code")
+ attrs.PutStr("event.name", "tool_result")
+ attrs.PutStr("tool_name", "Bash")
+ attrs.PutStr("tool_input", "{")
+ attrs.PutStr("tool_parameters", "[")
+ attrs.PutStr("duration_ms", "not-a-number")
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "command.executed" || event.Command == nil {
+ t.Fatalf("event = %#v command = %#v, want classified empty command", event.Event, event.Command)
+ }
+ if event.Command.Command != "" || event.Command.DurationMS != 0 {
+ t.Fatalf("command = %#v, want empty values for malformed attributes", event.Command)
+ }
+}
+
+func TestCapturedCodexLogNormalizationIsUnchanged(t *testing.T) {
+ fixture, events := capturedLogEvents(t, "codex-0.142.4.json")
+ if len(events) != len(fixture.Records) {
+ t.Fatalf("events = %d, want %d", len(events), len(fixture.Records))
+ }
+ if events[0].Event.Action != "approval.requested" || events[0].Approval == nil || events[0].Approval.Decision != "approved" {
+ t.Fatalf("Codex decision changed: %#v", events[0])
+ }
+ if events[1].Event.Action != "command.executed" || events[1].Command == nil || events[1].Command.Command != "echo CODEX_MARKER" {
+ t.Fatalf("Codex result changed: %#v", events[1])
+ }
+}
+
+func TestClaudeNormalizerDoesNotAffectOtherHarnesses(t *testing.T) {
+ for _, serviceName := range []string{
+ "generic-runtime",
+ "codex_cli_rs",
+ "gemini-cli",
+ "github-copilot",
+ "copilot-chat",
+ "cursor",
+ "claude-cowork",
+ "claude_agent_sdk",
+ "claude_web",
+ } {
+ t.Run(serviceName, func(t *testing.T) {
+ record := plog.NewLogRecord()
+ record.Body().SetStr("claude_code.assistant_response")
+ attrs := record.Attributes()
+ attrs.PutStr("service.name", serviceName)
+ attrs.PutStr("event.name", "assistant_response")
+
+ event := NewConverter(Options{}).EventFromLog(nil, record)
+ if event.Event.Action != "tool.invoked" || event.Event.Category != "tool" {
+ t.Fatalf("%s event changed by Claude normalizer: %#v", serviceName, event)
+ }
+ })
+ }
+}
+
+type capturedLogFixture struct {
+ Runtime string `json:"runtime"`
+ Version string `json:"version"`
+ Records []capturedLogRecord `json:"records"`
+}
+
+type capturedLogRecord struct {
+ Name string `json:"name"`
+ Body string `json:"body"`
+ Attributes map[string]interface{} `json:"attributes"`
+}
+
+func capturedLogEvents(t *testing.T, name string) (capturedLogFixture, []Event) {
+ t.Helper()
+ data, err := os.ReadFile(filepath.Join("testdata", name))
+ if err != nil {
+ t.Fatalf("read captured fixture: %v", err)
+ }
+ var fixture capturedLogFixture
+ if err := json.Unmarshal(data, &fixture); err != nil {
+ t.Fatalf("decode captured fixture: %v", err)
+ }
+ logs := plog.NewLogs()
+ scopeLogs := logs.ResourceLogs().AppendEmpty().ScopeLogs().AppendEmpty()
+ for _, captured := range fixture.Records {
+ record := scopeLogs.LogRecords().AppendEmpty()
+ record.Body().SetStr(captured.Body)
+ if err := record.Attributes().FromRaw(captured.Attributes); err != nil {
+ t.Fatalf("load %s attributes: %v", captured.Name, err)
+ }
+ }
+ return fixture, NewConverter(Options{}).EventsFromLogs(logs)
+}
+
func newObserveSDKTraceSpan(name string) (ptrace.Span, ptrace.Traces) {
traces := ptrace.NewTraces()
resourceSpans := traces.ResourceSpans().AppendEmpty()
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/claude-code-2.1.220.json b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/claude-code-2.1.220.json
new file mode 100644
index 00000000..350e2da2
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/claude-code-2.1.220.json
@@ -0,0 +1,84 @@
+{
+ "runtime": "Claude Code",
+ "version": "2.1.220",
+ "records": [
+ {
+ "name": "api_request",
+ "body": "claude_code.api_request",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_request",
+ "session.id": "claude-session",
+ "model": "claude-opus-5",
+ "duration_ms": 2183,
+ "input_tokens": 2,
+ "output_tokens": 101,
+ "cache_read_tokens": 15398,
+ "cache_creation_tokens": 4415
+ }
+ },
+ {
+ "name": "bash_decision",
+ "body": "claude_code.tool_decision",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "tool_decision",
+ "session.id": "claude-session",
+ "tool_name": "Bash",
+ "tool_use_id": "toolu_fixture_bash",
+ "decision": "accept",
+ "source": "config",
+ "tool_source": "builtin",
+ "tool_parameters": "{\"bash_command\":\"echo\",\"full_command\":\"echo CLAUDE_MARKER\",\"description\":\"Echo a marker string\"}"
+ }
+ },
+ {
+ "name": "bash_result",
+ "body": "claude_code.tool_result",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "tool_result",
+ "session.id": "claude-session",
+ "tool_name": "Bash",
+ "tool_use_id": "toolu_fixture_bash",
+ "success": "true",
+ "duration_ms": "94",
+ "tool_input": "{\"command\":\"echo CLAUDE_MARKER\",\"description\":\"Echo a marker string\"}",
+ "tool_parameters": "{\"bash_command\":\"echo\",\"full_command\":\"echo CLAUDE_MARKER\",\"description\":\"Echo a marker string\"}"
+ }
+ },
+ {
+ "name": "write_result",
+ "body": "claude_code.tool_result",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "tool_result",
+ "session.id": "claude-session",
+ "tool_name": "Write",
+ "tool_use_id": "toolu_fixture_write",
+ "success": "true",
+ "duration_ms": "2",
+ "tool_input": "{\"file_path\":\"/tmp/beacon-otel-fixture/CLAUDE_FILE_MARKER.txt\",\"content\":\"CLAUDE_FILE_MARKER\\n\"}"
+ }
+ },
+ {
+ "name": "read_result",
+ "body": "claude_code.tool_result",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "tool_result",
+ "session.id": "claude-session",
+ "tool_name": "Read",
+ "tool_use_id": "toolu_fixture_read",
+ "success": "true",
+ "duration_ms": "6",
+ "tool_input": "{\"file_path\":\"/tmp/beacon-otel-fixture/CLAUDE_FILE_MARKER.txt\"}"
+ }
+ }
+ ]
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/claude-code-lifecycle-2.1.220.json b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/claude-code-lifecycle-2.1.220.json
new file mode 100644
index 00000000..010f56c9
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/claude-code-lifecycle-2.1.220.json
@@ -0,0 +1,299 @@
+{
+ "runtime": "Claude Code",
+ "version": "2.1.220",
+ "records": [
+ {
+ "name": "user_prompt",
+ "body": "claude_code.user_prompt",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "user_prompt",
+ "session.id": "claude-lifecycle-session",
+ "prompt": "CLAUDE_LIFECYCLE_MARKER",
+ "prompt_length": 23
+ }
+ },
+ {
+ "name": "assistant_response",
+ "body": "claude_code.assistant_response",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "assistant_response",
+ "session.id": "claude-lifecycle-session",
+ "model": "claude-opus-5",
+ "response": "CLAUDE_RESPONSE_MARKER",
+ "response_length": 22
+ }
+ },
+ {
+ "name": "api_request",
+ "body": "claude_code.api_request",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_request",
+ "session.id": "claude-lifecycle-session",
+ "model": "claude-opus-5",
+ "duration_ms": 321,
+ "input_tokens": 10,
+ "output_tokens": 4
+ }
+ },
+ {
+ "name": "api_error",
+ "body": "claude_code.api_error",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_error",
+ "session.id": "claude-lifecycle-session",
+ "model": "claude-opus-5",
+ "error": "request failed",
+ "status_code": 500,
+ "duration_ms": 2000
+ }
+ },
+ {
+ "name": "api_refusal",
+ "body": "claude_code.api_refusal",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_refusal",
+ "session.id": "claude-lifecycle-session",
+ "model": "claude-opus-5",
+ "attempt": 1,
+ "server_fallback_hop": false
+ }
+ },
+ {
+ "name": "api_request_body",
+ "body": "claude_code.api_request_body",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_request_body",
+ "session.id": "claude-lifecycle-session",
+ "body": "{\"model\":\"claude-opus-5\"}",
+ "body_length": 25
+ }
+ },
+ {
+ "name": "api_response_body",
+ "body": "claude_code.api_response_body",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_response_body",
+ "session.id": "claude-lifecycle-session",
+ "body": "{\"stop_reason\":\"end_turn\"}",
+ "body_length": 26
+ }
+ },
+ {
+ "name": "permission_mode_changed",
+ "body": "claude_code.permission_mode_changed",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "permission_mode_changed",
+ "session.id": "claude-lifecycle-session",
+ "from_mode": "default",
+ "to_mode": "plan",
+ "trigger": "shift_tab"
+ }
+ },
+ {
+ "name": "auth",
+ "body": "claude_code.auth",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "auth",
+ "session.id": "claude-lifecycle-session",
+ "action": "login",
+ "success": "true",
+ "auth_method": "oauth"
+ }
+ },
+ {
+ "name": "mcp_server_connection",
+ "body": "claude_code.mcp_server_connection",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "mcp_server_connection",
+ "session.id": "claude-lifecycle-session",
+ "status": "connected",
+ "transport_type": "stdio",
+ "server_scope": "project",
+ "duration_ms": 42,
+ "server_name": "fixture-server"
+ }
+ },
+ {
+ "name": "internal_error",
+ "body": "claude_code.internal_error",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "internal_error",
+ "session.id": "claude-lifecycle-session",
+ "error_name": "TypeError",
+ "error_code": "ERR_FIXTURE"
+ }
+ },
+ {
+ "name": "plugin_installed",
+ "body": "claude_code.plugin_installed",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "plugin_installed",
+ "session.id": "claude-lifecycle-session",
+ "marketplace.is_official": "true",
+ "install.trigger": "cli",
+ "plugin.name": "fixture-plugin"
+ }
+ },
+ {
+ "name": "plugin_loaded",
+ "body": "claude_code.plugin_loaded",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "plugin_loaded",
+ "session.id": "claude-lifecycle-session",
+ "plugin.name": "fixture-plugin",
+ "plugin.scope": "official",
+ "has_hooks": true,
+ "has_mcp": false
+ }
+ },
+ {
+ "name": "skill_activated",
+ "body": "claude_code.skill_activated",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "skill_activated",
+ "session.id": "claude-lifecycle-session",
+ "skill.name": "fixture-skill",
+ "invocation_trigger": "claude-proactive",
+ "skill.source": "bundled"
+ }
+ },
+ {
+ "name": "at_mention",
+ "body": "claude_code.at_mention",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "at_mention",
+ "session.id": "claude-lifecycle-session",
+ "mention_type": "file",
+ "success": "true"
+ }
+ },
+ {
+ "name": "api_retries_exhausted",
+ "body": "claude_code.api_retries_exhausted",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "api_retries_exhausted",
+ "session.id": "claude-lifecycle-session",
+ "model": "claude-opus-5",
+ "status_code": 503,
+ "total_attempts": 3,
+ "total_retry_duration_ms": 5000
+ }
+ },
+ {
+ "name": "hook_registered",
+ "body": "claude_code.hook_registered",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "hook_registered",
+ "session.id": "claude-lifecycle-session",
+ "hook_event": "PreToolUse",
+ "hook_type": "command",
+ "hook_source": "projectSettings"
+ }
+ },
+ {
+ "name": "hook_execution_start",
+ "body": "claude_code.hook_execution_start",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "hook_execution_start",
+ "session.id": "claude-lifecycle-session",
+ "hook_event": "PreToolUse",
+ "hook_name": "PreToolUse:Bash",
+ "num_hooks": 1
+ }
+ },
+ {
+ "name": "hook_execution_complete",
+ "body": "claude_code.hook_execution_complete",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "hook_execution_complete",
+ "session.id": "claude-lifecycle-session",
+ "hook_event": "PreToolUse",
+ "hook_name": "PreToolUse:Bash",
+ "num_hooks": 1,
+ "num_success": 1,
+ "total_duration_ms": 25
+ }
+ },
+ {
+ "name": "hook_plugin_metrics",
+ "body": "claude_code.hook_plugin_metrics",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "hook_plugin_metrics",
+ "session.id": "claude-lifecycle-session",
+ "plugin_id": "fixture@official",
+ "hook_event": "PostToolUse",
+ "finding_count": 1
+ }
+ },
+ {
+ "name": "compaction",
+ "body": "claude_code.compaction",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "compaction",
+ "session.id": "claude-lifecycle-session",
+ "trigger": "auto",
+ "success": "true",
+ "duration_ms": 750,
+ "pre_tokens": 150000,
+ "post_tokens": 25000
+ }
+ },
+ {
+ "name": "feedback_survey",
+ "body": "claude_code.feedback_survey",
+ "attributes": {
+ "service.name": "claude-code",
+ "service.version": "2.1.220",
+ "event.name": "feedback_survey",
+ "session.id": "claude-lifecycle-session",
+ "event_type": "responded",
+ "appearance_id": "survey-fixture",
+ "survey_type": "session",
+ "response": "positive",
+ "enabled_via_override": false
+ }
+ }
+ ]
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/codex-0.142.4.json b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/codex-0.142.4.json
new file mode 100644
index 00000000..306dac25
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/testdata/codex-0.142.4.json
@@ -0,0 +1,35 @@
+{
+ "runtime": "Codex CLI",
+ "version": "0.142.4",
+ "records": [
+ {
+ "name": "tool_decision",
+ "body": "codex.tool_decision",
+ "attributes": {
+ "service.name": "codex_exec",
+ "service.version": "0.142.4",
+ "event.name": "codex.tool_decision",
+ "conversation.id": "codex-session",
+ "tool_name": "exec_command",
+ "call_id": "call_fixture",
+ "decision": "approved",
+ "source": "Config"
+ }
+ },
+ {
+ "name": "tool_result",
+ "body": "codex.tool_result",
+ "attributes": {
+ "service.name": "codex_exec",
+ "service.version": "0.142.4",
+ "event.name": "codex.tool_result",
+ "conversation.id": "codex-session",
+ "tool_name": "exec_command",
+ "call_id": "call_fixture",
+ "success": "true",
+ "duration_ms": "60",
+ "arguments": "{\"cmd\":\"echo CODEX_MARKER\",\"workdir\":\"/tmp/beacon-otel-fixture\",\"yield_time_ms\":10000,\"max_output_tokens\":2000}"
+ }
+ }
+ ]
+}
diff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdx
index 28340186..294f0d67 100644
--- a/docs/runtimes/claude-code.mdx
+++ b/docs/runtimes/claude-code.mdx
@@ -75,6 +75,37 @@ Asymptote detects Claude Code through the `claude` executable and Claude setting
Claude Code hooks cover `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStart`, `SubagentStop`, `PermissionRequest`, and `SessionEnd`. Pre-tool matching includes common Claude tools such as `Bash`, `Edit`, `Write`, `MultiEdit`, `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Agent`, and `mcp__.*`.
+## Normalized OTLP events
+
+Beacon maps Claude Code's OTLP logs into canonical endpoint actions instead of
+treating every unrecognized record as a tool invocation:
+
+- `user_prompt` becomes `prompt.submitted`.
+- A successful or failed `Bash` `tool_result` becomes `command.executed`, with
+ the decoded command in `command.command` and the reported duration in
+ `command.duration_ms`.
+- `Read` results become `file.read`; `Write`, `Edit`, and `NotebookEdit` results
+ become `file.modified`, with the decoded path in `file.path`.
+- Accepted and rejected `tool_decision` records become `approval.allowed` and
+ `approval.denied`. Bash decisions also retain the full command when Claude
+ provides it.
+- API requests, assistant responses, hooks, plugins, skills, compaction, and
+ other ordinary lifecycle records become session activity. API and internal
+ errors become `session.error`; refusals and permission-mode changes become
+ `session.status`.
+- MCP server connection lifecycle records become `mcp.connection`, not
+ `mcp.tool_invoked`.
+
+Claude reports tool success and duration but does not provide an exact process
+exit status, so Beacon does not invent `command.exit_code`. The original OTLP
+attributes remain under `raw.attributes`, subject to the configured redaction
+and event-size controls. Future full-body `claude_code.*` lifecycle records
+default to `session.activity` until Beacon assigns a more specific mapping.
+
+Optional hook events are an additional telemetry source. A hook pre-tool
+observation can appear as `tool.invoked`; the completed OTLP `tool_result` is
+the record that supplies the canonical command or file action.
+
Detailed tool inputs can contain sensitive command arguments, paths, URLs, search terms, and MCP request data. Beacon sends this telemetry only to the configured local collector during normal endpoint execution; apply the same access, retention, and redaction controls used for other retained prompt and tool data.
## Deployment notes
diff --git a/docs/runtimes/integration-model.mdx b/docs/runtimes/integration-model.mdx
index 7a1071d4..0ae06a82 100644
--- a/docs/runtimes/integration-model.mdx
+++ b/docs/runtimes/integration-model.mdx
@@ -46,7 +46,7 @@ During install, Beacon configures the runtime surfaces it can safely manage:
| Runtime | Collection path | Notes |
|---------|-----------------|-------|
-| [Claude Code](/runtimes/claude-code) | Local OTLP export plus optional hooks | Uses Claude settings to enable telemetry and point OTLP to localhost; optional hooks add lifecycle, subagent, permission, and tool event detail. |
+| [Claude Code](/runtimes/claude-code) | Local OTLP export plus optional hooks | Uses Claude settings to enable telemetry and point OTLP to localhost; Beacon decodes nested tool operands and separates API/session lifecycle from tool execution, while optional hooks add lifecycle, subagent, permission, and tool detail. |
| [Codex CLI](/runtimes/codex-cli) | Local OTLP logs, traces, and metrics | Beacon writes structured Codex OTLP config and filters noisy internal transport spans. |
| [Gemini CLI](/runtimes/gemini-cli) | Opt-in local OTLP logs, traces, and metrics | Beacon writes Gemini telemetry settings and maps Gemini prompts, tool calls, MCP activity, file operations, and approval events into endpoint events. |
| [GitHub Copilot CLI](/runtimes/github-copilot-cli) | MDM-managed OTLP HTTP export | Beacon validates Copilot's effective launch environment and maps Copilot spans into prompt, session, tool, and approval-like endpoint events. |