Skip to content

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

Promote prompt.id from hook payloads

Claudeaad97cb89a16
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index eb548fdd..0a9780c4 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -39,9 +39,9 @@ func emitInferredHookEvent(logger *logging.Logger, action, category, severity, m
//
// These runtimes carry real signal with no endpoint-schema field of its own -- Qwen's
// `permission_mode` on every tool event, its `source` on SessionStart and the `context_usage` /
-// `context_limit` / `input_tokens` trio on Stop; Muse Code's `turn_id`, which is the only per-turn
-// boundary anything in its payload offers. Keeping the payload preserves them without inventing
-// schema fields for one runtime. It is the whole event's own path through SanitizeMap, so raw is
+// `context_limit` / `input_tokens` trio on Stop; Muse Code's `permission_mode` and SessionStart
+// `source`. Keeping the payload preserves them without inventing schema fields for one runtime. It
+// is the whole event's own path through SanitizeMap, so raw is
// secret-redacted and string-limited like every other field, and it is the first thing dropped when
// an event exceeds the 64 KiB ceiling.
//
@@ -142,6 +142,7 @@ func emitHookEventWithFidelity(logger *logging.Logger, action, category, severit
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{key: input})
}
applyToolCallID(fields, input)
+ applyPromptID(fields, input)
applyContextSize(fields, input)
if model := getFirstStr(input, "model"); model != "" {
fields["model"] = model
diff --git a/cli/beacon-hooks/cmd/muse_hooks_test.go b/cli/beacon-hooks/cmd/muse_hooks_test.go
index 261b8450..343d693a 100644
--- a/cli/beacon-hooks/cmd/muse_hooks_test.go
+++ b/cli/beacon-hooks/cmd/muse_hooks_test.go
@@ -196,9 +196,9 @@ func TestMusePermissionRequestIsRecordedAsAnObservedApproval(t *testing.T) {
}
}
-// turn_id is the only per-turn boundary anything in a Muse payload offers, and the endpoint schema
-// has no field for it. Keeping the whole payload under raw.muse preserves it -- along with
-// permission_mode and the SessionStart `source` -- without inventing schema fields for one runtime.
+// turn_id is the only per-turn boundary anything in a Muse payload offers. It is promoted to
+// prompt.id like every runtime's turn id, and the whole payload is still kept under raw.muse for
+// permission_mode and the SessionStart `source`, which have no schema field.
func TestMuseRawPayloadPreservesTheTurnID(t *testing.T) {
setupHookConfigDirs(t)
platformFlag = "muse"
@@ -220,6 +220,9 @@ func TestMuseRawPayloadPreservesTheTurnID(t *testing.T) {
if got := leaf(event, "raw", "muse", "turn_id"); got != "turn-7" {
t.Fatalf("raw.muse.turn_id = %q, want turn-7", got)
}
+ if got := leaf(event, "prompt", "id"); got != "turn-7" {
+ t.Fatalf("prompt.id = %q, want turn-7", got)
+ }
if got := leaf(event, "raw", "muse", "permission_mode"); got != "acceptEdits" {
t.Fatalf("raw.muse.permission_mode = %q, want acceptEdits", got)
}
diff --git a/cli/beacon-hooks/cmd/post_tool.go b/cli/beacon-hooks/cmd/post_tool.go
index 2c5c9ef3..6e00878d 100644
--- a/cli/beacon-hooks/cmd/post_tool.go
+++ b/cli/beacon-hooks/cmd/post_tool.go
@@ -328,6 +328,7 @@ func recordLocalEdit(params *evaluationParams, input map[string]interface{}, log
if platformFlag == "dsh" {
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"dsh": input})
}
+ applyPromptID(fields, input)
logger.EndpointEvent("file.modified", "file", "info", "File edit observed", fields)
}
diff --git a/cli/beacon-hooks/cmd/prompt_id.go b/cli/beacon-hooks/cmd/prompt_id.go
new file mode 100644
index 00000000..41e38e67
--- /dev/null
+++ b/cli/beacon-hooks/cmd/prompt_id.go
@@ -0,0 +1,34 @@
+package cmd
+
+import (
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// applyPromptID records which user prompt a hook event belongs to, as prompt.id.
+//
+// The runtime's own identifier is read from the payload's top level through the shared alias list,
+// so Cursor's generation_id, Codex's and Muse Code's turn_id and Kimi Code's numbered turn_id all
+// land in the one field the collector fills from Claude Code's and Gemini CLI's OTLP attributes.
+// The envelope only, for the reason tool call ids are read from it only: tool arguments are
+// model-authored, and an argument that happened to be named turn_id is not the runtime naming its
+// turn.
+//
+// Every event a payload produces gets the id -- a tool call and the file edits it caused belong to
+// the same prompt -- and an id a mapper already set is left alone.
+func applyPromptID(fields, input map[string]interface{}) {
+ if fields == nil || input == nil {
+ return
+ }
+ if prompt, ok := fields["prompt"].(map[string]interface{}); ok {
+ if id, _ := prompt["id"].(string); strings.TrimSpace(id) != "" {
+ return
+ }
+ }
+ id := asymptoteobserve.PromptIDFrom(input)
+ if id == "" {
+ return
+ }
+ fields["prompt"] = mergeNested(fields["prompt"], map[string]interface{}{"id": id})
+}
diff --git a/cli/beacon-hooks/cmd/prompt_id_test.go b/cli/beacon-hooks/cmd/prompt_id_test.go
new file mode 100644
index 00000000..ed56e540
--- /dev/null
+++ b/cli/beacon-hooks/cmd/prompt_id_test.go
@@ -0,0 +1,173 @@
+package cmd
+
+import (
+ "path/filepath"
+ "testing"
+)
+
+func promptIDOfEvent(event map[string]interface{}) string {
+ return leaf(event, "prompt", "id")
+}
+
+// Cursor sends generation_id on every hook and changes it with every user message, so it is the
+// turn: a shell approval carries the id of the prompt that led to it.
+func TestCursorGenerationIDBecomesPromptID(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ runHookWithInput(t, runPreTool, map[string]interface{}{
+ "conversation_id": "conv-1",
+ "generation_id": "gen-7",
+ "hook_event_name": "beforeShellExecution",
+ "command": "npm test",
+ "cwd": "/repo",
+ })
+
+ event := lastEndpointEvent(t, logPath)
+ if got := promptIDOfEvent(event); got != "gen-7" {
+ t.Fatalf("prompt.id = %q, want Cursor's generation_id", got)
+ }
+ if got := leaf(event, "session", "id"); got != "conv-1" {
+ t.Fatalf("session.id = %q, want conversation_id -- the session, not the turn", got)
+ }
+}
+
+// Codex puts turn_id on every turn-scoped hook, the prompt submission included, so the prompt and
+// the tool calls it led to share one id.
+func TestCodexTurnIDBecomesPromptIDOnPromptAndTools(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "codex"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_DISABLE_GIT_METADATA", "1")
+
+ base := func(event string, extra map[string]interface{}) map[string]interface{} {
+ input := map[string]interface{}{
+ "hook_event_name": event,
+ "session_id": "codex-session",
+ "cwd": "/repo",
+ "turn_id": "turn-42",
+ }
+ for key, value := range extra {
+ input[key] = value
+ }
+ return input
+ }
+ runHookWithInput(t, runPromptSubmit, base("UserPromptSubmit", map[string]interface{}{"prompt": "run the tests"}))
+ runHookWithInput(t, runPostTool, base("PostToolUse", map[string]interface{}{
+ "tool_name": "Bash",
+ "tool_use_id": "call_1",
+ "tool_input": map[string]interface{}{"command": "go test ./..."},
+ "tool_response": map[string]interface{}{"stdout": "ok"},
+ }))
+
+ events := endpointEvents(t, logPath)
+ if len(events) < 2 {
+ t.Fatalf("event count = %d, want the prompt and the command: %#v", len(events), events)
+ }
+ for _, event := range events {
+ if got := promptIDOfEvent(event); got != "turn-42" {
+ t.Fatalf("%s prompt.id = %q, want turn-42", leaf(event, "event", "action"), got)
+ }
+ }
+ if got := leaf(events[0], "prompt", "text"); got != "run the tests" {
+ t.Fatalf("prompt.text = %q, want the prompt kept beside its id", got)
+ }
+}
+
+// Kimi Code numbers its turns. A decoded payload holds that as a float64, and the id is its
+// integer rendering rather than "3e+00" or nothing.
+func TestKimiNumberedTurnBecomesPromptID(t *testing.T) {
+ logPath := kimiTestSetup(t)
+
+ runHookWithInput(t, runPermissionRequest, kimiEvent("PermissionResult", "k-turn", map[string]interface{}{
+ "turn_id": float64(3),
+ "tool_call_id": "call_z",
+ "tool_name": "Bash",
+ "tool_input": map[string]interface{}{"command": "ls"},
+ "decision": "approved",
+ }))
+
+ if got := promptIDOfEvent(lastEndpointEvent(t, logPath)); got != "3" {
+ t.Fatalf("prompt.id = %q, want 3", got)
+ }
+}
+
+// The id is read from the runtime's envelope only. A tool argument is model-authored, and an
+// argument that happens to be called turn_id is not the runtime naming its turn.
+func TestPromptIDIgnoresToolArguments(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "codex"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_DISABLE_GIT_METADATA", "1")
+
+ runHookWithInput(t, runPostTool, map[string]interface{}{
+ "hook_event_name": "PostToolUse",
+ "session_id": "codex-session",
+ "cwd": "/repo",
+ "tool_name": "Bash",
+ "tool_input": map[string]interface{}{"command": "echo", "turn_id": "forged"},
+ "tool_response": map[string]interface{}{"stdout": "", "prompt_id": "forged"},
+ })
+
+ if got := promptIDOfEvent(lastEndpointEvent(t, logPath)); got != "" {
+ t.Fatalf("prompt.id = %q, want none -- tool arguments are not the envelope", got)
+ }
+}
+
+// One Cursor turn seen through every hook family it fires: the prompt, a file edit (written by the
+// local-edit emitter, which does not go through emitHookEvent), and the stop that ends the turn.
+// All of them carry the generation's id, and a later generation starts a new one.
+func TestCursorTurnCarriesOneIDAcrossHookFamilies(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ dir := t.TempDir()
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_DISABLE_GIT_METADATA", "1")
+
+ envelope := func(event, generation string, extra map[string]interface{}) map[string]interface{} {
+ input := map[string]interface{}{
+ "conversation_id": "conv-1",
+ "generation_id": generation,
+ "hook_event_name": event,
+ "workspace_roots": []interface{}{dir},
+ "cursor_version": "1.7.2",
+ }
+ for key, value := range extra {
+ input[key] = value
+ }
+ return input
+ }
+ runHookWithInput(t, runPromptSubmit, envelope("beforeSubmitPrompt", "gen-1", map[string]interface{}{"prompt": "add a main package"}))
+ runHookWithInput(t, runPostTool, envelope("afterFileEdit", "gen-1", map[string]interface{}{
+ "file_path": filepath.Join(dir, "main.go"),
+ "edits": []interface{}{map[string]interface{}{"old_string": "old line", "new_string": "package main"}},
+ }))
+ // Stop goes through its emitter rather than runStop, which ends with os.Exit; these are the
+ // arguments runStop passes it, as in the Kimi, Qwen and Kiro stop tests.
+ stopInput := envelope("stop", "gen-1", map[string]interface{}{"status": "completed"})
+ stopSession := resolveSessionID(stopInput, "cursor")
+ emitHookEvent(newHookLogger("stop", "cursor", stopSession), "tool.completed", "tool", "info",
+ "Agent response completed", stopInput, sessionFields(stopSession, stopInput))
+ runHookWithInput(t, runPromptSubmit, envelope("beforeSubmitPrompt", "gen-2", map[string]interface{}{"prompt": "now a license"}))
+
+ events := endpointEvents(t, logPath)
+ seen := map[string]string{}
+ for _, event := range events {
+ seen[leaf(event, "event", "action")+"@"+promptIDOfEvent(event)] = promptIDOfEvent(event)
+ }
+ for _, want := range []string{"prompt.submitted@gen-1", "file.modified@gen-1", "tool.completed@gen-1", "prompt.submitted@gen-2"} {
+ if _, ok := seen[want]; !ok {
+ t.Fatalf("missing %s; events: %v", want, seen)
+ }
+ }
+ for key, id := range seen {
+ if id == "" {
+ t.Fatalf("%s has no prompt.id; events: %v", key, seen)
+ }
+ }
+}
diff --git a/docs/runtimes/codex-cli.mdx b/docs/runtimes/codex-cli.mdx
index bd083d27..2ed44b06 100644
--- a/docs/runtimes/codex-cli.mdx
+++ b/docs/runtimes/codex-cli.mdx
@@ -106,6 +106,7 @@ Codex CLI endpoint hooks installed: /Users/you/.codex/hooks.json
| Area | Support |
|------|---------|
| Prompt telemetry | Supported when emitted through Codex semantic logs |
+| Turn identity | Supported. Codex's `turn_id` from hooks and `turn.id` from OTLP are promoted to `prompt.id` |
| Command, tool, and file telemetry | Supported when emitted through Codex semantic logs |
| Token usage | Supported per turn through a selective OTLP trace (input, output, cache read, cache creation, reasoning) |
| Cost attribution | Not available; Codex emits no cost signal |
diff --git a/docs/runtimes/cursor.mdx b/docs/runtimes/cursor.mdx
index cde25228..952b7618 100644
--- a/docs/runtimes/cursor.mdx
+++ b/docs/runtimes/cursor.mdx
@@ -57,6 +57,7 @@ beacon endpoint hooks install --harness cursor --level project
| Area | Support |
|------|---------|
| Prompt telemetry | Supported for local and cloud Cursor through `beforeSubmitPrompt` hooks. Cursor Cloud requires the project hook to be committed before the run starts and uploads observed prompts immediately; the initial launch prompt can precede hook activation during bootstrap. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support). |
+| Turn identity | Supported. Cursor's `generation_id`, which changes with every user message, is promoted to `prompt.id` on hook events |
| Command, tool, and file telemetry | Supported for tool, shell command, MCP-like, approval, and file edit payloads where Cursor exposes them; Cursor Cloud support is limited to Cursor's [cloud-supported command hooks](https://cursor.com/docs/hooks#cloud-agent-support). |
| Agent reasoning telemetry | Supported for local Cursor through `afterAgentThought` hooks. Each completed thinking block is recorded as an `agent.reasoning` event carrying the reasoning text in the OpenTelemetry GenAI output-messages shape (`gen_ai.output.messages` with a `reasoning` part), plus a `content` marker with the original text's hash and byte count. Reasoning is only available for models/modes where Cursor exposes visible thinking text. |
| Repository and branch context | Events include the workspace path as `repository`, and `branch` is resolved from the workspace's local git checkout (`.git/HEAD`) when Cursor does not supply one; disable local git resolution with `BEACON_DISABLE_GIT_METADATA=1`. |
diff --git a/docs/runtimes/kimi-code.mdx b/docs/runtimes/kimi-code.mdx
index b49e07f8..1f06c912 100644
--- a/docs/runtimes/kimi-code.mdx
+++ b/docs/runtimes/kimi-code.mdx
@@ -105,7 +105,7 @@ The seven events Beacon does not register:
- **`SessionHeartbeat`** is the one where subscribing would *create* the behavior rather than observe it. Kimi Code starts its sixty-second timer only when a hook is configured for it, so Beacon would be spawning a process a minute in every session to write an event saying nothing happened.
- **`UserPromptQueued`** fires when a message is typed while a turn is still running; the prompt is recorded when it is submitted, and recording the queueing too would count one prompt twice.
-- **`TurnStarted`** carries a turn id the endpoint schema has no field for, and its `prompt` is the text `UserPromptSubmit` already carried.
+- **`TurnStarted`** adds nothing: its turn id reaches `prompt.id` from the other turn-scoped events, and its `prompt` is the text `UserPromptSubmit` already carried.
- **`TaskStarted`** and **`Notification`** report background tasks, and the tool that started one — a `Bash` with `run_in_background`, an `Agent`, an `AskUserQuestion` — is already recorded as itself.
- **`StopFailure`** reports a turn that failed on an API or runtime error rather than anything the agent did.
- **`Interrupt`** fires in place of `Stop` when you cancel a turn. Beacon's closing action is `tool.completed`, which states the agent finished; a cancelled turn did not, and there is no action in the endpoint schema that says so. The session is still closed by `SessionEnd`.
@@ -143,6 +143,7 @@ Uninstall removes Beacon's entries and leaves your own hooks, settings, and comm
| Session lifecycle | Supported. `session.started` from `SessionStart`, `tool.completed` from `Stop`, and `session.ended` from `SessionEnd` |
| Prompts | Supported. `prompt.submitted` from `UserPromptSubmit` |
| Tool use | Supported for pre-tool and post-tool activity, with `gen_ai.tool.call.id` from `tool_call_id` |
+| Turn identity | Supported. Kimi Code's numbered `turn_id` is promoted to `prompt.id` |
| Commands | Supported. `command.executed` with the command and its output, plus `command.exit_code` on a failure |
| File activity | Supported. `file.read` and `file.modified` with paths, operations, and diffs |
| MCP activity | Supported. Recognized from `mcp__<server>__<tool>`, with the server and tool split out |
diff --git a/docs/runtimes/muse-code.mdx b/docs/runtimes/muse-code.mdx
index cd089ca8..897c9c5d 100644
--- a/docs/runtimes/muse-code.mdx
+++ b/docs/runtimes/muse-code.mdx
@@ -123,6 +123,7 @@ beacon endpoint hooks uninstall --harness muse
| Approval decisions | Supported. Observed from `PermissionRequest`, not synthesized from pre-tool |
| Context compaction | Supported. `session.compacting` and `session.compacted` |
| Tool call identity | Supported. Muse's `tool_use_id` is promoted to `gen_ai.tool.call.id` and joins pre-tool, approval and post-tool events |
+| Turn identity | Supported. Muse's `turn_id` is promoted to `prompt.id` on every event of the turn |
| Token usage and cost | Not collected. See [Known gaps](#known-gaps) |
| Local JSONL and dashboard | Supported |
| MDM deployment | Supported for the endpoint agent. Muse hooks are installed separately in the logged-in user's context |
@@ -147,7 +148,7 @@ Enforcement stays behind the optional, off-by-default policy provider seam (`BEA
Muse Code content is handled like every other runtime. Prompts, tool arguments, commands, paths, and diffs are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.
-Muse carries signal with no endpoint-schema field of its own — most importantly `turn_id`, which is the only per-turn boundary anything in its payload offers, plus `permission_mode` on tool events and `source` on `SessionStart`. Beacon preserves the verbatim payload under `raw.muse` rather than inventing schema fields for one runtime. It travels the event's normal path through sanitization, so `raw` is secret-redacted and string-limited like every other field, and it is the first thing dropped when an event exceeds the size ceiling.
+Muse's `turn_id`, the only per-turn boundary anything in its payload offers, is promoted to `prompt.id`. Muse also carries signal with no endpoint-schema field of its own: `permission_mode` on tool events and `source` on `SessionStart`. Beacon preserves the verbatim payload under `raw.muse` rather than inventing schema fields for one runtime. It travels the event's normal path through sanitization, so `raw` is secret-redacted and string-limited like every other field, and it is the first thing dropped when an event exceeds the size ceiling.
## Known gaps