Skip to content

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

WS1 — Event Identity: promote native tool call IDs and derive event IDs

Claude2316d655ed22
diff --git a/CLAUDE.md b/CLAUDE.md
index 1b95d32c..7236107c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -353,6 +353,7 @@ Use these npm trusted publisher values:
- For macOS-only behavior, gate tests with `runtime.GOOS == "darwin"` or assert the non-Darwin contract explicitly.
- Keep endpoint event schema fields stable: `vendor`, `product`, `schema_version`, required event fields, and Wazuh-compatible JSONL output are release contracts.
- Preserve optional event fields for agent-native metadata (`session`, `trace`, `tool`, `file`, `command`, `mcp`, `approval`, `content`, `model`, `repository`, and `branch`) without changing existing required field semantics.
+- Keep event identity derivable rather than asserted. `gen_ai.tool.call.id` carries the runtime's own name for one tool invocation, promoted on every capture path from the shared alias list in `pkg/asymptoteobserve.ToolCallIDKeys`; a new runtime adds its spelling there rather than in a mapper. `event.id` is a deterministic UUID derived by `EventIDForLine` from the event about to be written, so both capture paths name one action the same way. Its namespace constant and derivation are a contract: changing either renames every event ID Beacon has written, and a test pins the value.
- Keep `gen_ai.usage` as the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacy `llm.usage.*` aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields. `gen_ai.usage.cost_usd` carries runtime-reported cost only; do not derive cost from local pricing tables.
- When adding a new signal, include stable identifiers/counts/hashes alongside any retained raw content, and route raw fields through redaction, sanitization, truncation, and event-size controls.
- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.
diff --git a/beacon-sandbox/check/check_test.go b/beacon-sandbox/check/check_test.go
index b0fcae50..8c287a50 100644
--- a/beacon-sandbox/check/check_test.go
+++ b/beacon-sandbox/check/check_test.go
@@ -275,9 +275,14 @@ func TestSameHarnessRepeatsSurviveWithoutMatchingCallIDs(t *testing.T) {
}
}
-// An equal, non-empty call ID inside the window is the one case the writer does collapse, so
-// requiring two would be a guaranteed false failure.
-func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {
+// An equal, non-empty call ID is the one case the writer really does collapse, so requiring two
+// would be a guaranteed false failure.
+//
+// No window applies to it, which is the whole point: a hook writes when the tool runs and the
+// collector writes when its batch flushes, so the two reports of one call land further apart than
+// any window worth having. Both distances are pinned here because the near one used to be the only
+// one that collapsed.
+func TestMatchingCallIDsCollapseAtAnyDistance(t *testing.T) {
base := goodLog()
withID := func(line, ts, id string) string {
line = strings.Replace(line, "18:00:01Z", ts, 1)
@@ -286,7 +291,7 @@ func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {
}
first := withID(base[1], "18:00:01Z", "call-1")
same := withID(base[1], "18:00:02Z", "call-1") // 1s apart, identical call id
- later := withID(base[1], "18:00:11Z", "call-1") // 10s apart, outside the 2s window
+ later := withID(base[1], "18:00:11Z", "call-1") // 10s apart, well past the 2s window
sc := demoScenario()
sc.Expect = []scenario.Expect{{
@@ -301,8 +306,9 @@ func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {
}
outside := run(t, []string{base[0], first, later}, sc, presentSentinel(), nil)
- if outside.Outcome != Pass {
- t.Errorf("10s apart is outside the 2s window, so both survive:\n%s", outside.Report())
+ if outside.Outcome != Fail {
+ t.Errorf("equal call IDs are collapsed however far apart they are, so min_count 2 must "+
+ "fail at 10s too:\n%s", outside.Report())
}
}
diff --git a/beacon-sandbox/check/expect.go b/beacon-sandbox/check/expect.go
index adfc9b53..999577d5 100644
--- a/beacon-sandbox/check/expect.go
+++ b/beacon-sandbox/check/expect.go
@@ -231,8 +231,8 @@ func evaluate(v *Verdict, log Log, exp scenario.Expect, idx int, canary string)
// Three rules matter, all taken from pkg/asymptoteobserve/dedupe.go:
//
// - only dedupeActions are candidates at all; every other action is preserved verbatim
-// - same harness collapses only on equal non-empty call IDs; different harness collapses on
-// the window alone
+// - equal non-empty call IDs collapse on their own, with no window and regardless of harness;
+// otherwise a different harness collapses on the window alone and the same harness never does
// - the window is 2s, except tool.completed which uses 10s
func collapseDuplicates(events []Event) []Event {
if len(events) < 2 {
@@ -254,12 +254,16 @@ func collapseDuplicates(events []Event) []Event {
if prev.Action() != e.Action() || identity(prev) != identity(e) {
continue
}
- // Same harness needs matching, non-empty call IDs before the writer collapses.
+ // An equal, non-empty call ID settles it on its own: the writer applies no window
+ // there, because the hook and the collector report one call seconds apart.
+ if a, b := callIDOf(prev), callIDOf(e); a != "" && a == b {
+ suppressed = true
+ break
+ }
+ // Without that, the same harness never collapses: two adjacent calls can
+ // legitimately touch the same file or command.
if harnessOf(prev) == harnessOf(e) {
- a, b := callIDOf(prev), callIDOf(e)
- if a == "" || b == "" || a != b {
- continue
- }
+ continue
}
pts, err := time.Parse(time.RFC3339, prev.Typed.Timestamp)
if err != nil {
diff --git a/cli/beacon-hooks/cmd/cline_event.go b/cli/beacon-hooks/cmd/cline_event.go
index 0c483e2c..58933b63 100644
--- a/cli/beacon-hooks/cmd/cline_event.go
+++ b/cli/beacon-hooks/cmd/cline_event.go
@@ -574,7 +574,7 @@ func clineToolFields(input map[string]interface{}, completed bool) map[string]in
call["result"] = toolResponse
}
}
- if callID := getFirstStr(input, "callId", "call_id", "toolCallId", "tool_call_id"); callID != "" {
+ if callID := toolCallIDIn(input); callID != "" {
call["id"] = callID
}
fields["gen_ai"] = map[string]interface{}{
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index e940bfce..f6b74301 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -15,6 +15,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/cloudshuttle"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/git"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
var runInventoryHeartbeatCommand = exec.CommandContext
@@ -36,6 +37,7 @@ func emitHookEvent(logger *logging.Logger, action, category, severity, message s
if isCascadePlatform(platformFlag) {
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"cascade": input})
}
+ applyToolCallID(fields, input)
if model := getFirstStr(input, "model"); model != "" {
fields["model"] = model
}
@@ -257,9 +259,83 @@ func toolFieldsWithResponse(toolName string, toolInput, toolResponse map[string]
fields[key] = value
}
}
+ // The call ID goes on every tool event, not just the MCP ones that happened
+ // to build a gen_ai object for their arguments. It is the join key: without
+ // it nothing links this call to its result, or to the OTLP record of the
+ // same action. Only the ID is promoted here -- arguments and results are a
+ // separate question about what Beacon retains, not about identity.
+ if callID := toolCallIDIn(toolInput, toolResponse); callID != "" {
+ setToolCallID(fields, callID)
+ }
return fields
}
+// toolCallIDIn reads the runtime's own identifier for one tool invocation out of
+// the payload maps a hook mapper has to hand.
+//
+// The alias list is shared with the OTLP path so both capture paths promote the
+// same value to the same field, which is what lets duplicate suppression
+// recognise the two reports of one action as one action.
+func toolCallIDIn(inputs ...map[string]interface{}) string {
+ return firstToolStringAcross(inputs, asymptoteobserve.ToolCallIDKeys...)
+}
+
+// applyToolCallID promotes a call ID carried at the top level of a hook payload,
+// which is where Claude Code puts tool_use_id -- outside tool_input, so no
+// amount of reading the tool arguments would ever have found it.
+//
+// Only an event that already describes a tool action takes one. A session
+// lifecycle payload that happens to echo an ID is not a tool call, and giving it
+// the join key of one would join it to work it did not do.
+func applyToolCallID(fields, input map[string]interface{}) {
+ if fields == nil || toolCallIDOf(fields) != "" || !describesToolAction(fields) {
+ return
+ }
+ if callID := toolCallIDIn(input); callID != "" {
+ setToolCallID(fields, callID)
+ }
+}
+
+func describesToolAction(fields map[string]interface{}) bool {
+ for _, key := range []string{"tool", "command", "file", "mcp"} {
+ if value, ok := fields[key].(map[string]interface{}); ok && len(value) > 0 {
+ return true
+ }
+ }
+ return false
+}
+
+// toolCallIDOf reads back what setToolCallID wrote, so a mapper that already
+// found the ID somewhere better is not overwritten by a weaker source.
+func toolCallIDOf(fields map[string]interface{}) string {
+ genAI, _ := fields["gen_ai"].(map[string]interface{})
+ tool, _ := genAI["tool"].(map[string]interface{})
+ call, _ := tool["call"].(map[string]interface{})
+ id, _ := call["id"].(string)
+ return strings.TrimSpace(id)
+}
+
+// setToolCallID writes gen_ai.tool.call.id, creating the objects on the way down
+// and leaving whatever is already in them alone. mergeNested cannot do this: it
+// is a one-level merge, so writing the call through it would replace the whole
+// tool object and drop the name and arguments an MCP event puts there.
+func setToolCallID(fields map[string]interface{}, callID string) {
+ genAI := mutableChild(fields["gen_ai"])
+ tool := mutableChild(genAI["tool"])
+ call := mutableChild(tool["call"])
+ call["id"] = callID
+ tool["call"] = call
+ genAI["tool"] = tool
+ fields["gen_ai"] = genAI
+}
+
+func mutableChild(value interface{}) map[string]interface{} {
+ if existing, ok := value.(map[string]interface{}); ok && existing != nil {
+ return existing
+ }
+ return map[string]interface{}{}
+}
+
func mcpToolFields(toolName string, toolInput, toolResponse map[string]interface{}) map[string]interface{} {
maps := []map[string]interface{}{toolInput, toolResponse}
mcpServer := firstToolStringAcross(maps, "mcp_server", "mcp_server_name", "mcp.server", "mcp.server.name")
diff --git a/cli/beacon-hooks/cmd/opencode_event.go b/cli/beacon-hooks/cmd/opencode_event.go
index ef54dd50..de0b99bc 100644
--- a/cli/beacon-hooks/cmd/opencode_event.go
+++ b/cli/beacon-hooks/cmd/opencode_event.go
@@ -266,7 +266,7 @@ func opencodeToolFields(input map[string]interface{}, completed bool) map[string
toolInput := firstMap(input, "tool_input", "toolInput")
toolResponse := firstMap(input, "tool_response", "toolResponse")
fields := toolFieldsWithResponse(toolName, toolInput, toolResponse)
- callID := getFirstStr(input, "call_id", "callID")
+ callID := toolCallIDIn(input)
call := map[string]interface{}{}
if len(toolInput) > 0 {
call["arguments"] = toolInput
diff --git a/cli/beacon-hooks/cmd/post_tool.go b/cli/beacon-hooks/cmd/post_tool.go
index b0ccd7c8..b75ba52c 100644
--- a/cli/beacon-hooks/cmd/post_tool.go
+++ b/cli/beacon-hooks/cmd/post_tool.go
@@ -206,6 +206,11 @@ func recordLocalEdit(params *evaluationParams, input map[string]interface{}, log
fields["session"] = mergeNested(fields["session"], map[string]interface{}{"id": params.sessionID})
}
applyWorkspaceFields(fields, input, filepath.Dir(params.filePath))
+ // This emitter writes its event without going through emitHookEvent, so it
+ // has to promote the call ID itself. Every file edit in the log is recorded
+ // twice -- once here, once from OTLP -- and this is the field that lets the
+ // writer tell that the two are one edit.
+ applyToolCallID(fields, input)
logger.EndpointEvent("file.modified", "file", "info", "File edit observed", fields)
}
diff --git a/cli/beacon-hooks/cmd/tool_call_id_test.go b/cli/beacon-hooks/cmd/tool_call_id_test.go
new file mode 100644
index 00000000..b6fc585c
--- /dev/null
+++ b/cli/beacon-hooks/cmd/tool_call_id_test.go
@@ -0,0 +1,153 @@
+package cmd
+
+import (
+ "path/filepath"
+ "regexp"
+ "testing"
+)
+
+// leaf reads a string at a dotted path, returning "" for anything missing along
+// the way. nested is the fatal-on-missing variant and is the wrong tool here:
+// half these assertions are about a field legitimately not being there.
+func leaf(event map[string]interface{}, keys ...string) string {
+ var current interface{} = event
+ for _, key := range keys {
+ next, ok := current.(map[string]interface{})
+ if !ok {
+ return ""
+ }
+ current = next[key]
+ }
+ value, _ := current.(string)
+ return value
+}
+
+func callIDOfEvent(event map[string]interface{}) string {
+ return leaf(event, "gen_ai", "tool", "call", "id")
+}
+
+// Claude Code puts tool_use_id at the top level of the hook payload, outside
+// tool_input, so no amount of reading the tool arguments would ever have found
+// it. It is the only value that links this event to the tool's result, to the
+// approval that allowed it, and to the OTLP record of the same command.
+func TestRunPostToolPromotesClaudeToolUseID(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "claude"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ runHookWithInput(t, runPostTool, map[string]interface{}{
+ "session_id": "claude-session",
+ "cwd": "/repo",
+ "hook_event_name": "PostToolUse",
+ "tool_name": "Bash",
+ "tool_use_id": "toolu_01abc",
+ "tool_input": map[string]interface{}{"command": "echo hi"},
+ "tool_response": map[string]interface{}{"stdout": "hi"},
+ })
+
+ events := endpointEvents(t, logPath)
+ if len(events) != 1 {
+ t.Fatalf("event count = %d, want one command event: %#v", len(events), events)
+ }
+ if got := leaf(events[0], "event", "action"); got != "command.executed" {
+ t.Fatalf("event.action = %q, want command.executed", got)
+ }
+ if got := callIDOfEvent(events[0]); got != "toolu_01abc" {
+ t.Fatalf("gen_ai.tool.call.id = %q, want the tool_use_id Claude Code assigned", got)
+ }
+}
+
+// A Claude Edit reaches the log through recordLocalEdit, which writes its event
+// without going through emitHookEvent. Every file edit is recorded twice --
+// once here, once from OTLP -- so this is the path that most needs the join key.
+func TestRunPostToolPromotesToolUseIDOnFileEdits(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "claude"
+ dir := t.TempDir()
+ logPath := filepath.Join(dir, "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ runHookWithInput(t, runPostTool, map[string]interface{}{
+ "session_id": "claude-session",
+ "cwd": dir,
+ "hook_event_name": "PostToolUse",
+ "tool_name": "Write",
+ "tool_use_id": "toolu_01write",
+ "tool_input": map[string]interface{}{
+ "file_path": filepath.Join(dir, "notes.md"),
+ "content": "hello",
+ },
+ })
+
+ events := endpointEvents(t, logPath)
+ edits := 0
+ for _, event := range events {
+ if leaf(event, "event", "action") != "file.modified" {
+ continue
+ }
+ edits++
+ if got := callIDOfEvent(event); got != "toolu_01write" {
+ t.Fatalf("file.modified call ID = %q, want the tool_use_id Claude Code assigned", got)
+ }
+ }
+ if edits == 0 {
+ t.Fatalf("no file.modified event was written: %#v", events)
+ }
+}
+
+// A session lifecycle payload that happens to echo an ID is not a tool call.
+// Giving it the join key of one would join it to work it did not do.
+func TestSessionEventsDoNotTakeAToolCallID(t *testing.T) {
+ fields := map[string]interface{}{"session": map[string]interface{}{"id": "s1"}}
+ applyToolCallID(fields, map[string]interface{}{"tool_use_id": "toolu_01abc"})
+ if _, ok := fields["gen_ai"]; ok {
+ t.Fatalf("a session event took a tool call ID: %#v", fields)
+ }
+}
+
+// An MCP event already builds a gen_ai object for its arguments, so the call ID
+// has to be written into it rather than over it.
+func TestToolCallIDDoesNotDisplaceMCPToolFields(t *testing.T) {
+ fields := toolFieldsWithResponse("mcp__linear__list_issues", map[string]interface{}{
+ "mcp_server": "linear",
+ "call_id": "call_42",
+ "team": "beacon",
+ }, nil)
+ if got := callIDOfEvent(fields); got != "call_42" {
+ t.Fatalf("gen_ai.tool.call.id = %q, want call_42", got)
+ }
+ if got := leaf(fields, "gen_ai", "tool", "name"); got != "list_issues" {
+ t.Fatalf("gen_ai.tool.name = %q, want the MCP tool name to survive", got)
+ }
+ if got := nested(t, fields, "gen_ai", "tool", "call")["arguments"]; got == nil {
+ t.Fatal("gen_ai.tool.call.arguments was dropped when the call ID was written")
+ }
+}
+
+var uuidV5Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
+
+// Every event the hook writer emits carries an identity, whether or not the
+// runtime named the action itself.
+func TestHookEventsCarryAnEventID(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "claude"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ runHookWithInput(t, runPostTool, map[string]interface{}{
+ "session_id": "claude-session",
+ "cwd": "/repo",
+ "hook_event_name": "PostToolUse",
+ "tool_name": "Bash",
+ "tool_use_id": "toolu_01abc",
+ "tool_input": map[string]interface{}{"command": "echo hi"},
+ })
+
+ for _, event := range endpointEvents(t, logPath) {
+ id := leaf(event, "event", "id")
+ if !uuidV5Pattern.MatchString(id) {
+ t.Fatalf("event.id = %q, want an RFC 4122 version 5 UUID: %#v", id, event)
+ }
+ }
+}
diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.go
index ff018796..5ddeefd4 100644
--- a/cli/beacon-hooks/internal/logging/logging.go
+++ b/cli/beacon-hooks/internal/logging/logging.go
@@ -252,9 +252,40 @@ func writeEndpointJSON(path string, event map[string]interface{}) error {
if len(data) > 64*1024 {
return fmt.Errorf("endpoint event exceeds 64 KiB after metadata fallback")
}
+ // Stamped last, over the bytes that are actually about to be written, so
+ // none of the size fallbacks above can leave the ID describing an event that
+ // no longer exists.
+ if data, err = withEndpointEventID(event, data); err != nil {
+ return err
+ }
return appendEndpointJSONL(path, append(data, '\n'), defaultEndpointRotateBytes, defaultEndpointRotateArchives)
}
+// withEndpointEventID fills event.id on an event assembled as a map and returns
+// its re-marshalled line. line must be the marshalled form of event with no ID
+// on it, which is what EventIDForLine is derived from.
+func withEndpointEventID(event map[string]interface{}, line []byte) ([]byte, error) {
+ info, ok := event["event"].(map[string]interface{})
+ if !ok {
+ return line, nil
+ }
+ if id, _ := info["id"].(string); strings.TrimSpace(id) != "" {
+ return line, nil
+ }
+ info["id"] = asymptoteobserve.EventIDForLine(line)
+ data, err := json.Marshal(sanitizeEndpointMap(event))
+ if err != nil {
+ return nil, err
+ }
+ // An event already at the size limit keeps its bytes and goes without an ID:
+ // the limit is a hard contract, and refusing to write an event over forty
+ // bytes of identity would be the worse trade.
+ if len(data) > 64*1024 {
+ return line, nil
+ }
+ return data, nil
+}
+
func compactEndpointContent(event map[string]interface{}) {
if file, ok := event["file"].(map[string]interface{}); ok {
delete(file, "diff")
diff --git a/cli/beacon/internal/endpoint/writer/writer.go b/cli/beacon/internal/endpoint/writer/writer.go
index 3c18f86f..1d6fd85a 100644
--- a/cli/beacon/internal/endpoint/writer/writer.go
+++ b/cli/beacon/internal/endpoint/writer/writer.go
@@ -82,6 +82,21 @@ func AppendEvent(event schema.Event, opts Options) (string, error) {
if len(data) > opts.MaxBytes {
return "", fmt.Errorf("event exceeds maximum size after truncation: %d bytes", len(data))
}
+ // Stamped last, over the bytes that are actually about to be written, so the
+ // truncation fallback above cannot leave the ID describing an event that no
+ // longer exists. An event already at the size limit keeps its bytes and goes
+ // without one: the limit is a hard contract, and refusing to write an event
+ // over forty bytes of identity would be the worse trade.
+ if event.Event.ID == "" {
+ event.Event.ID = asymptoteobserve.EventIDForLine(data)
+ stamped, err := json.Marshal(event)
+ if err != nil {
+ return "", err
+ }
+ if len(stamped) <= opts.MaxBytes {
+ data = stamped
+ }
+ }
if err := appendJSONL(opts.Path, append(data, '\n'), opts.RotateSize, opts.RotateArchives); err != nil {
return "", err
}
diff --git a/cli/beacon/internal/endpoint/writer/writer_test.go b/cli/beacon/internal/endpoint/writer/writer_test.go
index b3674672..81e7d990 100644
--- a/cli/beacon/internal/endpoint/writer/writer_test.go
+++ b/cli/beacon/internal/endpoint/writer/writer_test.go
@@ -4,12 +4,14 @@ import (
"encoding/json"
"os"
"path/filepath"
+ "regexp"
"strconv"
"strings"
"sync"
"testing"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
func TestAppendEventWritesSingleJSONLine(t *testing.T) {
@@ -294,3 +296,80 @@ func TestSanitizeEventRedactsToolPolicyAndRawValues(t *testing.T) {
t.Fatalf("tool path was not truncated: %d", len(sanitized.Tool.Path))
}
}
+
+var uuidV5Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
+
+func TestAppendEventStampsAStableEventID(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ event := schema.NewEvent(schema.NewEventOptions{
+ Action: "command.executed",
+ Harness: schema.HarnessInfo{Name: "claude_code"},
+ Message: "Shell command executed",
+ })
+ event.Timestamp = "2026-08-21T18:00:01Z"
+ event.Session = &schema.SessionInfo{ID: "s1"}
+ event.Command = &schema.CommandInfo{Command: "echo hi"}
+ event.GenAI = &schema.GenAIInfo{Tool: &schema.GenAIToolInfo{Call: &schema.GenAIToolCallInfo{ID: "toolu_1"}}}
+
+ if _, err := AppendEvent(event, Options{Path: path}); err != nil {
+ t.Fatalf("AppendEvent returned error: %v", err)
+ }
+
+ line, err := LastLine(path)
+ if err != nil {
+ t.Fatalf("read last line: %v", err)
+ }
+ var written schema.Event
+ if err := json.Unmarshal([]byte(line), &written); err != nil {
+ t.Fatalf("decode written event: %v", err)
+ }
+ if !uuidV5Pattern.MatchString(written.Event.ID) {
+ t.Fatalf("event.id = %q, want an RFC 4122 version 5 UUID", written.Event.ID)
+ }
+ // The ID has to describe the line it is on, so re-deriving it from that line
+ // with the field cleared has to land on the same value.
+ bare := written
+ bare.Event.ID = ""
+ data, err := json.Marshal(bare)
+ if err != nil {
+ t.Fatalf("re-marshal event: %v", err)
+ }
+ if got := asymptoteobserve.EventIDForLine(data); got != written.Event.ID {
+ t.Fatalf("event.id = %s, but the written line derives %s", written.Event.ID, got)
+ }
+}
+
+// The regression the call ID exists to fix: after harness normalization both
+// capture paths report claude_code, and the collector's batch lands seconds
+// after the hook's write. Nothing but a shared call ID can collapse that pair.
+func TestAppendEventCollapsesTheHookAndCollectorReportsOfOneCall(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ hook := schema.NewEvent(schema.NewEventOptions{
+ Action: "command.executed",
+ Harness: schema.HarnessInfo{Name: "claude_code"},
+ Message: "Shell command executed",
+ })
+ hook.Timestamp = "2026-08-21T18:00:01Z"
+ hook.Session = &schema.SessionInfo{ID: "s1"}
+ hook.Command = &schema.CommandInfo{Command: "echo hi"}
+ hook.GenAI = &schema.GenAIInfo{Tool: &schema.GenAIToolInfo{Call: &schema.GenAIToolCallInfo{ID: "toolu_1"}}}
+
+ collector := hook
+ collector.Timestamp = "2026-08-21T18:00:07Z"
+ collector.Message = "Tool execution observed"
+
+ if _, err := AppendEvent(hook, Options{Path: path}); err != nil {
+ t.Fatalf("first AppendEvent returned error: %v", err)
+ }
+ if _, err := AppendEvent(collector, Options{Path: path}); err != nil {
+ t.Fatalf("second AppendEvent returned error: %v", err)
+ }
+
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read log: %v", err)
+ }
+ if lines := strings.Split(strings.TrimSpace(string(data)), "\n"); len(lines) != 1 {
+ t.Fatalf("one Bash call was recorded %d times: %s", len(lines), string(data))
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/exporter_test.go b/collector-builder/exporter/beaconjsonexporter/exporter_test.go
index 707c3220..278f0a32 100644
--- a/collector-builder/exporter/beaconjsonexporter/exporter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/exporter_test.go
@@ -11,6 +11,7 @@ import (
"testing"
"time"
+ "github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
"go.opentelemetry.io/collector/exporter"
"go.opentelemetry.io/collector/pdata/plog"
@@ -160,6 +161,46 @@ func TestJSONLWriterDedupesRuntimeEvents(t *testing.T) {
}
}
+// The collector writes an event with the same identity the hook writer would
+// give it, or the two capture paths cannot recognise each other's reports.
+func TestJSONLWriterStampsTheSameEventIDTheHookWriterWould(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ writer := jsonlWriter{
+ path: path,
+ maxEventBytes: defaultMaxEventBytes,
+ rotateBytes: defaultRotateBytes,
+ rotateArchives: defaultRotateArchives,
+ redactSecrets: true,
+ }
+ event := newBeaconEvent("command.executed", "command", "info", "claude_code", time.Date(2026, 8, 21, 18, 0, 7, 0, time.UTC))
+ event.Message = "Shell command executed"
+ event.Session = &sessionInfo{ID: "s1", WorkingDirectory: "/repo"}
+ event.Command = &commandInfo{Command: "echo hi"}
+ event.GenAI = &beaconevent.GenAIInfo{Tool: &beaconevent.GenAIToolInfo{Call: &beaconevent.GenAIToolCallInfo{ID: "toolu_1"}}}
+
+ if err := writer.append(event); err != nil {
+ t.Fatalf("append returned error: %v", err)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read log: %v", err)
+ }
+ var written beaconEvent
+ if err := json.Unmarshal([]byte(strings.TrimSpace(string(data))), &written); err != nil {
+ t.Fatalf("unmarshal event: %v", err)
+ }
+ // The hook path writes the same call at a different second with a different
+ // message, and derives its ID from the same four parts.
+ hookLine := `{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"command.executed"},` +
+ `"harness":{"name":"claude_code"},"session":{"id":"s1","working_directory":"/repo"},` +
+ `"command":{"command":"echo hi"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}},` +
+ `"message":"Tool execution observed"}`
+ if want := asymptoteobserve.EventIDForLine([]byte(hookLine)); written.Event.ID != want {
+ t.Fatalf("collector event.id = %s, but the hook's report of the same call derives %s",
+ written.Event.ID, want)
+ }
+}
+
func TestConsumeLogsWritesBeaconJSONL(t *testing.T) {
path := filepath.Join(t.TempDir(), "runtime.jsonl")
exp, err := newExporter(&Config{
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index 1522b3d5..edbc75cc 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -1031,10 +1031,11 @@ func GenAIToolFromAttrs(attrs map[string]interface{}) *GenAIToolInfo {
if definitions, ok := AnyAttr(attrs, "gen_ai.tool.definitions"); ok {
tool.Definitions = definitions
}
+ callID := ToolCallID(attrs)
if args, ok := AnyAttr(attrs, "gen_ai.tool.call.arguments", "beacon.gen_ai.tool.call.arguments", "function_args", "arguments"); ok {
- tool.Call = &GenAIToolCallInfo{Arguments: args, ID: FirstString(attrs, "gen_ai.tool.call.id", "beacon.gen_ai.tool.call.id")}
- } else if id := FirstString(attrs, "gen_ai.tool.call.id", "beacon.gen_ai.tool.call.id"); id != "" {
- tool.Call = &GenAIToolCallInfo{ID: id}
+ tool.Call = &GenAIToolCallInfo{Arguments: args, ID: callID}
+ } else if callID != "" {
+ tool.Call = &GenAIToolCallInfo{ID: callID}
}
if result, ok := AnyAttr(attrs, "gen_ai.tool.call.result", "beacon.gen_ai.tool.call.result"); ok {
if tool.Call == nil {
@@ -1689,6 +1690,18 @@ func HasToolCall(attrs map[string]interface{}) bool {
return IsMeaningfulValue(attrs["gen_ai.tool.call.arguments"])
}
+// ToolCallID reads the runtime's own identifier for one tool invocation.
+//
+// Claude Code writes it as tool_use_id and Codex as call_id; neither name was
+// on the promotion list, so the value reached the log only inside raw and
+// nothing linked a tool call to its result. The alias list is shared with the
+// hook path so both capture paths promote the same value to the same field --
+// which is what lets duplicate suppression recognise the two reports of one
+// action as one action.
+func ToolCallID(attrs map[string]interface{}) string {
+ return FirstString(attrs, asymptoteobserve.ToolCallIDKeys...)
+}
+
func IsMeaningfulValue(value interface{}) bool {
switch typed := value.(type) {
case nil:
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
index ec998d2f..df6b108b 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
@@ -765,6 +765,17 @@ func TestCapturedClaudeCodeLogNormalization(t *testing.T) {
t.Fatalf("raw attributes changed: %#v", bash.Raw)
}
+ // Claude Code names every tool call with a tool_use_id and puts the same one
+ // on the decision and the result. Promoting it is what links an approval to
+ // the execution it approved, and this event to the hook's report of the same
+ // command; until it was promoted the value reached the log only inside raw.
+ if got := toolCallIDOfEvent(decision); got != "toolu_fixture_bash" {
+ t.Fatalf("decision call ID = %q, want the tool_use_id Claude Code assigned", got)
+ }
+ if got := toolCallIDOfEvent(bash); got != "toolu_fixture_bash" {
+ t.Fatalf("bash call ID = %q, want the tool_use_id Claude Code assigned", got)
+ }
+
for _, tc := range []struct {
name string
action string
@@ -783,6 +794,38 @@ func TestCapturedClaudeCodeLogNormalization(t *testing.T) {
if event.Tool == nil || event.Tool.Path != event.File.Path {
t.Fatalf("%s tool = %#v, want mirrored path", tc.name, event.Tool)
}
+ if toolCallIDOfEvent(event) == "" {
+ t.Fatalf("%s has no call ID, so nothing links it to the hook's report of the same edit", tc.name)
+ }
+ }
+ if toolCallIDOfEvent(byName["write_result"]) == toolCallIDOfEvent(byName["read_result"]) {
+ t.Fatal("the write and the read are separate calls and must not share a call ID")
+ }
+}
+
+func toolCallIDOfEvent(event Event) string {
+ if event.GenAI == nil || event.GenAI.Tool == nil || event.GenAI.Tool.Call == nil {
+ return ""
+ }
+ return event.GenAI.Tool.Call.ID
+}
+
+// Codex names its calls call_id rather than tool_use_id. Both are read from one
+// shared alias list, so a runtime cannot be supported on one capture path and
+// invisible on the other.
+func TestCapturedCodexLogPromotesItsOwnCallID(t *testing.T) {
+ _, events := capturedLogEvents(t, "codex-0.142.4.json")
+ found := false
+ for _, event := range events {
+ if id := toolCallIDOfEvent(event); id != "" {
+ if id != "call_fixture" {
+ t.Fatalf("call ID = %q, want the call_id Codex assigned", id)
+ }
+ found = true
+ }
+ }
+ if !found {
+ t.Fatal("no event promoted Codex's call_id")
}
}
diff --git a/collector-builder/exporter/beaconjsonexporter/writer.go b/collector-builder/exporter/beaconjsonexporter/writer.go
index 48afc45d..830ddcc5 100644
--- a/collector-builder/exporter/beaconjsonexporter/writer.go
+++ b/collector-builder/exporter/beaconjsonexporter/writer.go
@@ -38,6 +38,21 @@ func (w jsonlWriter) append(event beaconEvent) error {
if len(data) > w.maxEventBytes {
return fmt.Errorf("event exceeds maximum size after truncation: %d bytes", len(data))
}
+ // Stamped last, over the bytes that are actually about to be written, so a
+ // size fallback above cannot leave the ID describing an event that no longer
+ // exists. Marshalling twice is the cost of an identity derived from the
+ // event rather than asserted about it. An event already at the size limit
+ // keeps its bytes and goes without one.
+ if event.Event.ID == "" {
+ event.Event.ID = asymptoteobserve.EventIDForLine(data)
+ stamped, err := json.Marshal(event)
+ if err != nil {
+ return err
+ }
+ if len(stamped) <= w.maxEventBytes {
+ data = stamped
+ }
+ }
if err := os.MkdirAll(filepath.Dir(w.path), 0755); err != nil {
return err
}
diff --git a/docs/telemetry-schema/event-schema.mdx b/docs/telemetry-schema/event-schema.mdx
index 007e72a3..1e4a9460 100644
--- a/docs/telemetry-schema/event-schema.mdx
+++ b/docs/telemetry-schema/event-schema.mdx
@@ -37,6 +37,10 @@ The schema gives every event a consistent backbone:
| `endpoint` | Host and operating system context |
| `harness` | Runtime that produced the signal |
+`event.id` is written alongside these: a deterministic UUID identifying the event, described under
+[event identity](/telemetry-schema/normalization#event-identity). It is not required, so events
+written by earlier agent versions remain valid.
+
## How it extends OpenTelemetry
Beacon accepts OpenTelemetry attributes, including the GenAI semantic conventions, and projects them into fields that are easier to query across agent runtimes. OpenTelemetry context is preserved under `gen_ai` where available, while commonly investigated values are also normalized into Beacon fields such as `model`, `tool.name`, `prompt.text`, `command.command`, `file.path`, and `gen_ai.usage`.
diff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdx
index e08b1246..5162b139 100644
--- a/docs/telemetry-schema/normalization.mdx
+++ b/docs/telemetry-schema/normalization.mdx
@@ -14,7 +14,8 @@ Beacon normalizes [OTLP](/concepts/core-concepts#otlp) attributes and [hook](/co
| `gen_ai.request.model`, `gen_ai.response.model`, `model`, `ai.model` | `model` |
| `gen_ai.tool.name`, `tool.name`, `beacon.tool.name`, `function_name`, `tool_name` | `tool.name` and `gen_ai.tool.name` |
| `gen_ai.tool.call.arguments`, `function_args`, `arguments` | `tool.command` when command-like, plus `gen_ai.tool.call.arguments` |
-| `gen_ai.tool.call.id`, `gen_ai.tool.call.result` | `gen_ai.tool.call.id`, `gen_ai.tool.call.result` |
+| `gen_ai.tool.call.id`, `tool_use_id`, `call_id`, `tool_call_id`, `callId` | `gen_ai.tool.call.id` |
+| `gen_ai.tool.call.result` | `gen_ai.tool.call.result` |
| `mcp.method.name`, `mcp.protocol.version`, `mcp.resource.uri`, `mcp.session.id` | `mcp.method.name`, `mcp.protocol.version`, `mcp.resource.uri`, `mcp.session.id` |
| `mcp.tool`, `beacon.mcp.tool`, `mcp.tool.name` | `mcp.tool` |
| `mcp.server`, `beacon.mcp.server`, `mcp.server.name` | `mcp.server` |
@@ -91,6 +92,23 @@ Canonical `gen_ai.usage` comes from the run-end payload only, including cache
reads and runtime-reported cost. Recording usage at a per-model-call boundary as
well would double-count every task's tokens in usage rollups.
+## Event identity
+
+Every event carries two identity fields, and both are filled on the hook path and the OTLP path alike.
+
+`gen_ai.tool.call.id` is the runtime's own name for one tool invocation, read from whichever
+attribute that runtime uses: Claude Code writes `tool_use_id`, Codex and OpenCode write `call_id`,
+Cline writes `callId`. It is what links a tool call to its result, an approval to the execution it
+approved, and a hook event to the OTLP event describing the same action. Where two events share
+one, they describe one call, and the writer records that call once rather than twice.
+
+`event.id` is Beacon's own identity for the event: a deterministic UUID, so the same event is
+named the same way in any process and any release. Where the runtime named the action itself, the
+UUID is derived from the session, action, target and call ID, and nothing else — so the hook's
+report and the collector's report of one action carry one `event.id` even though they are written
+seconds apart with different fields. Otherwise it is derived from the event's own content, which
+makes re-reading a log produce the IDs it already had.
+
## OpenTelemetry GenAI fields
Beacon preserves OpenTelemetry GenAI semantic convention fields under the nested `gen_ai` object and also projects selected fields into Beacon's common investigation fields. This keeps the raw GenAI context available without forcing downstream rules to parse runtime-specific attribute names.
diff --git a/pkg/asymptoteobserve/dedupe.go b/pkg/asymptoteobserve/dedupe.go
index 7a1e5a72..b0734be7 100644
--- a/pkg/asymptoteobserve/dedupe.go
+++ b/pkg/asymptoteobserve/dedupe.go
@@ -42,13 +42,29 @@ func IsDuplicateEndpointEvent(path string, candidateLine []byte, window time.Dur
if !ok || existing.key != candidate.key {
continue
}
- // Same-harness events are normally preserved because two adjacent calls
- // can legitimately target the same file or command. A stable tool call
- // ID makes an exact duplicate safe to collapse.
+ // An equal, non-empty tool call ID is the runtime's own statement that
+ // these two lines describe one call, and it settles the question on its
+ // own: no window, and no interest in which capture path reported it.
+ //
+ // The window is deliberately not applied here. A hook writes when the
+ // tool runs and the collector writes when its batch flushes, so the two
+ // reports of one call routinely land five seconds apart -- past the
+ // two-second window that is the only thing that ever collapsed them.
+ if existing.callID != "" && existing.callID == candidate.callID {
+ return true
+ }
+ // Without matching IDs, only the timing heuristic is left, and only
+ // across capture paths: two adjacent calls from one path can
+ // legitimately touch the same file or command, so same-harness
+ // lookalikes are preserved.
+ //
+ // Unequal IDs are not evidence of two calls unless one path assigned
+ // both. Beacon's paths do not share an ID space -- OpenCode's own call
+ // ID and the span ID the collector sees for the same call are simply
+ // different names -- so across harnesses the IDs are ignored rather
+ // than trusted to disagree.
if existing.harness == candidate.harness {
- if existing.callID == "" || candidate.callID == "" || existing.callID != candidate.callID {
- continue
- }
+ continue
}
diff := candidate.ts.Sub(existing.ts)
if diff < 0 {
diff --git a/pkg/asymptoteobserve/dedupe_test.go b/pkg/asymptoteobserve/dedupe_test.go
index 0e45c543..251f14b0 100644
--- a/pkg/asymptoteobserve/dedupe_test.go
+++ b/pkg/asymptoteobserve/dedupe_test.go
@@ -110,3 +110,28 @@ func TestIsDuplicateEndpointEventMatchesToolCompletion(t *testing.T) {
}
t.Fatal("expected duplicate tool completion within custom window")
}
+
+// The regression this exists to prevent. Duplicate suppression was fixed in July
+// to collapse the hook and OTLP reports of one action, keyed on the two paths
+// reporting different harness names. Harness normalization then landed in
+// August -- correct on its own terms, and a real fix -- after which both paths
+// reported claude_code, every pair took the same-harness branch, and that branch
+// needed a call ID that nothing ever populated. Suppression was inert from
+// that day on, and no test could have caught it because each change was right by
+// itself.
+func TestIsDuplicateEndpointEventCollapsesNormalizedHarnessOnCallID(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ hook := `{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"command.executed"},"harness":{"name":"claude_code"},"session":{"id":"s1","working_directory":"/repo"},"command":{"command":"echo hi"},"tool":{"name":"Bash","command":"echo hi"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}},"message":"Shell command executed"}`
+ otlp := []byte(`{"timestamp":"2026-08-21T18:00:07Z","event":{"action":"command.executed"},"harness":{"name":"claude_code"},"session":{"id":"s1","working_directory":"/repo"},"command":{"command":"echo hi"},"tool":{"name":"Bash","command":"echo hi"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}},"message":"Shell command executed"}`)
+ if err := os.WriteFile(path, []byte(hook+"\n"), 0644); err != nil {
+ t.Fatalf("write existing event: %v", err)
+ }
+
+ // Six seconds apart, which is the ordinary case rather than an edge one: the
+ // hook writes when the tool runs and the collector writes when its batch
+ // flushes. The two-second window never stood a chance, which is why an equal
+ // call ID does not consult it.
+ if !IsDuplicateEndpointEvent(path, otlp, EndpointDuplicateWindow) {
+ t.Fatal("the hook and OTLP reports of one Bash call should collapse on their shared call ID")
+ }
+}
diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.go
index a3934819..16975ba2 100644
--- a/pkg/asymptoteobserve/event.go
+++ b/pkg/asymptoteobserve/event.go
@@ -48,7 +48,11 @@ const (
AttributeRunEphemeral = "beacon.run.ephemeral"
)
+// EventInfo names what happened. ID is the event's stable identity: see
+// EventIDForLine for how it is derived and what equality between two of them
+// means.
type EventInfo struct {
+ ID string `json:"id,omitempty"`
Kind string `json:"kind"`
Action string `json:"action"`
Category string `json:"category,omitempty"`
diff --git a/pkg/asymptoteobserve/identity.go b/pkg/asymptoteobserve/identity.go
new file mode 100644
index 00000000..f67e246b
--- /dev/null
+++ b/pkg/asymptoteobserve/identity.go
@@ -0,0 +1,115 @@
+package asymptoteobserve
+
+import (
+ "crypto/sha1"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "strings"
+)
+
+// ToolCallIDKeys are the names a runtime uses for the identifier it assigns to
+// one tool invocation, in the order Beacon prefers them.
+//
+// Every supported runtime already emits this value -- Claude Code as
+// tool_use_id, Codex and OpenCode as call_id, Cline as callId -- and until this
+// list existed Beacon dropped all of them into raw, because the promotion list
+// held only the canonical OTel name that no runtime actually writes. It is the
+// one field that links a tool call to its result, an approval to the execution
+// it approved, and a hook event to the OTLP event for the same action, so it is
+// promoted to gen_ai.tool.call.id on every capture path from this single list.
+//
+// Order matters: the canonical names come first so an explicitly mapped value
+// always beats a runtime-native one, and the runtime-native names follow in no
+// significant order because no payload carries two of them.
+var ToolCallIDKeys = []string{
+ "gen_ai.tool.call.id",
+ "beacon.gen_ai.tool.call.id",
+ "tool_use_id",
+ "toolUseId",
+ "tool_call_id",
+ "toolCallId",
+ "call_id",
+ "callId",
+ "callID",
+}
+
+// eventIDNamespace is the fixed UUID namespace every Beacon event ID is derived
+// under, so the same event derives the same UUID in any process and any
+// release. It is an arbitrary constant, not a secret, and must never change:
+// changing it renames every event ID Beacon has ever written.
+var eventIDNamespace = [16]byte{
+ 0x1f, 0x4b, 0x2c, 0x8e, 0x6d, 0x3a, 0x5a, 0x7c,
+ 0x9b, 0x61, 0x3f, 0x0d, 0x5e, 0x8c, 0x2a, 0x14,
+}
+
+// EventIDForLine derives the deterministic identity of one serialized endpoint
+// event whose event.id has not been set yet.
+//
+// Deterministic means the same event derives the same ID every time, in either
+// capture path and in any later run. That is what makes an event addressable:
+// re-reading a log, merging two reports of one action, or uploading a trace
+// twice can all name the same event rather than guessing at it by position.
+//
+// Two identities are possible and the event decides which it gets:
+//
+// - When the runtime named the action itself -- a tool call ID plus a
+// resolvable target -- the ID is derived from session, action, target and
+// call ID alone. Timestamps and content are deliberately excluded, so the
+// hook report and the OTLP report of one real action derive one ID even
+// though they are written seconds apart with different fields.
+// - Otherwise the ID is a digest of the event itself, which is unique to the
+// extent the event is. Two events that agree on every recorded byte,
+// including the timestamp, are indistinguishable in the log and get one ID;
+// a per-session sequence number would separate them, and when events carry
+// one this derivation picks it up for free.
+//
+// The writer does not suppress duplicates on this field. Equality under the
+// content digest means "nothing recorded tells these apart", which is a weaker
+// claim than "this is the same action" and not one to drop an event over. The
+// call ID carries that claim, and duplicate suppression keys on it directly.
+//
+// line must be the event's JSON with event.id absent; passing a line that
+// already carries one derives an ID for a different event than the caller
+// meant, so callers marshal with the field empty and fill it afterwards.
+func EventIDForLine(line []byte) string {
+ var event map[string]interface{}
+ if err := json.Unmarshal(line, &event); err != nil {
+ // An event Beacon cannot parse is still an event Beacon is about to
+ // write, so it gets a content identity rather than no identity.
+ return eventUUID("content", string(line))
+ }
+ action := nestedString(event, "event", "action")
+ callID := nestedString(event, "gen_ai", "tool", "call", "id")
+ target := dedupeTarget(action, event)
+ if callID != "" && target != "" {
+ return eventUUID("call", strings.Join([]string{
+ nestedString(event, "session", "id"),
+ strings.ToLower(strings.TrimSpace(action)),
+ target,
+ callID,
+ }, "\x00"))
+ }
+ return eventUUID("content", string(line))
+}
+
+// eventUUID renders a name under eventIDNamespace as an RFC 4122 version 5
+// UUID. The kind prefix keeps the two identity modes in separate value spaces,
+// so a content digest can never collide with a call identity.
+//
+// SHA-1 is what version 5 specifies. It is used here as a namespaced identifier
+// function over data Beacon just wrote, never as a security boundary.
+func eventUUID(kind, name string) string {
+ buf := make([]byte, 0, len(eventIDNamespace)+len(kind)+len(name))
+ buf = append(buf, eventIDNamespace[:]...)
+ buf = append(buf, kind...)
+ buf = append(buf, name...)
+ sum := sha1.Sum(buf)
+ var id [16]byte
+ copy(id[:], sum[:16])
+ id[6] = (id[6] & 0x0f) | 0x50 // version 5
+ id[8] = (id[8] & 0x3f) | 0x80 // RFC 4122 variant
+ out := make([]byte, 32)
+ hex.Encode(out, id[:])
+ return fmt.Sprintf("%s-%s-%s-%s-%s", out[0:8], out[8:12], out[12:16], out[16:20], out[20:32])
+}
diff --git a/pkg/asymptoteobserve/identity_test.go b/pkg/asymptoteobserve/identity_test.go
new file mode 100644
index 00000000..d0d5376a
--- /dev/null
+++ b/pkg/asymptoteobserve/identity_test.go
@@ -0,0 +1,86 @@
+package asymptoteobserve
+
+import (
+ "regexp"
+ "testing"
+)
+
+// callLine is one endpoint event the runtime named itself, with the parts the
+// call identity is derived from left as parameters and everything else varying
+// freely, so a test can say exactly which difference it is testing.
+func callLine(harness, timestamp, callID, command string) []byte {
+ return []byte(`{"timestamp":"` + timestamp + `","event":{"action":"command.executed"},` +
+ `"harness":{"name":"` + harness + `"},"session":{"id":"s1","working_directory":"/repo"},` +
+ `"command":{"command":"` + command + `"},"gen_ai":{"tool":{"call":{"id":"` + callID + `"}}},` +
+ `"message":"Shell command executed"}`)
+}
+
+var uuidV5Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
+
+func TestEventIDForLineIsAVersion5UUID(t *testing.T) {
+ for name, line := range map[string][]byte{
+ "call identity": callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"),
+ "content identity": []byte(`{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"session.activity"},"session":{"id":"s1"}}`),
+ "unparseable": []byte(`not json at all`),
+ } {
+ if id := EventIDForLine(line); !uuidV5Pattern.MatchString(id) {
+ t.Errorf("%s: EventIDForLine = %q, want an RFC 4122 version 5 UUID", name, id)
+ }
+ }
+}
+
+// The point of the call identity: the hook writes when the tool runs and the
+// collector writes when its batch flushes, so the two reports of one call agree
+// on almost nothing except the call ID. They must still name one event.
+func TestEventIDForLineIgnoresWhatTheTwoCapturePathsDisagreeOn(t *testing.T) {
+ hook := EventIDForLine(callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"))
+ otlp := EventIDForLine(callLine("otel", "2026-08-21T18:00:07Z", "toolu_1", "echo hi"))
+ if hook != otlp {
+ t.Fatalf("one call reported twice derived two IDs: %s and %s", hook, otlp)
+ }
+}
+
+func TestEventIDForLineSeparatesDistinctCalls(t *testing.T) {
+ first := EventIDForLine(callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"))
+ for name, other := range map[string][]byte{
+ "another call": callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_2", "echo hi"),
+ "another target": callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "rm -rf /"),
+ } {
+ if id := EventIDForLine(other); id == first {
+ t.Errorf("%s derived the same ID as the original call: %s", name, id)
+ }
+ }
+}
+
+// Without a call ID there is nothing to identify the event by but the event, so
+// the ID has to move when any of it does -- and stay put when none of it does,
+// which is what makes re-reading a log derive the IDs it already had.
+func TestEventIDForLineFallsBackToTheEventItself(t *testing.T) {
+ line := []byte(`{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"session.activity"},"session":{"id":"s1"},"message":"Hook executed"}`)
+ later := []byte(`{"timestamp":"2026-08-21T18:00:02Z","event":{"action":"session.activity"},"session":{"id":"s1"},"message":"Hook executed"}`)
+ if EventIDForLine(line) != EventIDForLine(line) {
+ t.Fatal("the same line derived two IDs")
+ }
+ if EventIDForLine(line) == EventIDForLine(later) {
+ t.Fatal("events a second apart derived one ID")
+ }
+}
+
+// A content digest and a call identity must not be able to collide, because
+// they mean different things: see EventIDForLine.
+func TestEventIDForLineKeepsTheTwoIdentityModesApart(t *testing.T) {
+ if eventUUID("call", "x") == eventUUID("content", "x") {
+ t.Fatal("the call and content identity spaces overlap")
+ }
+}
+
+// The namespace and the derivation are a written contract: an event's ID has to
+// survive a release, or nothing downstream can address it across two of them.
+func TestEventIDForLineIsStableAcrossReleases(t *testing.T) {
+ const want = "244a6772-0cbe-5230-9f79-37cb62ce25ee"
+ got := EventIDForLine(callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"))
+ if got != want {
+ t.Fatalf("EventIDForLine = %s, want %s -- if this is deliberate, every ID Beacon has "+
+ "ever written just changed meaning", got, want)
+ }
+}
diff --git a/spec/threat-rules/FIELDS.md b/spec/threat-rules/FIELDS.md
index a424dd7e..df7157b7 100644
--- a/spec/threat-rules/FIELDS.md
+++ b/spec/threat-rules/FIELDS.md
@@ -30,6 +30,7 @@ Regenerate with `beacon rules fields --markdown > spec/threat-rules/FIELDS.md`.
| `e.error.type` | string |
| `e.event.action` | string |
| `e.event.category` | string |
+| `e.event.id` | string |
| `e.event.kind` | string |
| `e.field_truncated` | bool |
| `e.file.diff_bytes` | int |