The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Read Claude Code's prompt id from the transcript in hooks
Claudeb59514f805cf
diff --git a/CLAUDE.md b/CLAUDE.mdindex 00019dcd..446625f5 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -539,7 +539,7 @@ unpacked through Chrome's developer mode.- 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.- Reading a runtime's own on-disk session store is a `poll` collection path, not a new method: it is a pull that sees committed records after the fact, which is what `poll` means. fx is the case that exercises it (`cli/beacon/internal/fxsession`); a future runtime with the same shape uses `poll` too rather than adding a fifth value to a release-contract field. The token aggregator relies on that marker: when one session (endpoint, normalized harness, session id) has usage from both a live method and `poll`, `preferLiveOverPoll` in `cli/beacon/internal/tokens/tokens.go` keeps live usage authoritative from the first event of that live channel in the session and drops the backfill's copies from then on, so a poll mapper must keep the runtime's own session id and real record timestamps rather than deduplicating against the live log itself.- Set the provenance markers on every new collection path. `harness.collection_method` (`hook`, `otlp`, `plugin`, `poll`) records the mechanism; `event.fidelity` (`observed`, `inferred`) records whether the source named the action or Beacon derived it. Both are defined in `pkg/asymptoteobserve/provenance.go` and are the only sanctioned way to express that difference — do not add per-runtime confidence fields, and do not leave a derived action unmarked. A new plugin-shaped runtime must be added to `CollectionMethodForPlatform`, whose default is `hook`. An action synthesized from an adjacent observation, such as an approval built from a pre-tool notification on a runtime with no approval hook, is `inferred`.-- 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. `prompt.id` names the turn an event belongs to (one user prompt and everything done for it, until the next prompt) and is promoted the same way from `asymptoteobserve.PromptIDKeys` (hook envelope, OTLP attributes, `beacon.prompt.id`); session-store mappers set it from the turn they are reading. OTel GenAI has no turn attribute, so the name is Claude Code's own; a spelling joins the list only when the runtime's value is exactly one prompt (Copilot's per-model-call turn ids are excluded). A present `prompt` object no longer means "this is a prompt": test `prompt.text` or the category. `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 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. `prompt.id` names the turn an event belongs to (one user prompt and everything done for it, until the next prompt) and is promoted the same way from `asymptoteobserve.PromptIDKeys` (hook envelope, OTLP attributes, `beacon.prompt.id`); session-store mappers set it from the turn they are reading. OTel GenAI has no turn attribute, so the name is Claude Code's own; a spelling joins the list only when the runtime's value is exactly one prompt (Copilot's per-model-call turn ids are excluded). Claude Code hooks carry none, so turn-scoped Claude hooks read the newest `promptId` from the transcript tail; `UserPromptSubmit` must not, because it runs before the prompt is recorded. A present `prompt` object no longer means "this is a prompt": test `prompt.text` or the category. `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.cache_creation.ephemeral_1h_input_tokens` (optional, Anthropic's own name) is the subset of `cache_creation.input_tokens` written with a one-hour TTL: a breakdown like `reasoning` inside output, never added to a total, built with `asymptoteobserve.NewCacheCreationUsage` (clamps it to the write count) and differenced with `GenAIUsageCacheCreationInfo.Minus`. It is set by Claude Code session files, Pi-family `cacheWrite1h` and the browser extension's Claude adapter; Claude Code's OTLP export has no split, and reports price unsplit writes at the five-minute rate. `gen_ai.usage.cost_usd` carries runtime-reported cost only and is never written from a price list; list-price estimates are computed only at report time from the embedded catalog (`cli/beacon/internal/pricing`), are always labeled as estimates, and are never stored in events.- `cli/beacon/internal/pricing` estimates list-price cost for reports: integer-microdollar math over the gen_ai.usage counts (disjoint input/output/cache read/cache write, a one-hour write subset, reasoning inside output), long-context bands only for a single request, and a strict model-name ladder (exact, canonical via `NormalizeModelName`, dotted version, Bedrock route prefix, then stripping a `[1m]` marker, snapshot date or effort suffix) that leaves a model unpriced rather than guess, including when two entries tie with different prices. Its `catalog.json` is embedded, offline and report-time only (hooks never import it); it is generated from LiteLLM's MIT-licensed `model_prices_and_context_window.json` and records the upstream URL, commit and fetch/generation dates. Regenerate with `cd cli/beacon && go run ./internal/pricing/internal/gen` (resolves LiteLLM's main with `git ls-remote` and fetches that commit; `-src`/`-commit` for a local copy) and review the one-model-per-line diff; the generator never runs in builds or tests. Operators price what the catalog cannot (internal models, new releases, gateway aliases, negotiated rates) in a local overrides file, `<BaseDir>/pricing/overrides.json` (`pricing.DefaultOverridesPath`, user or system mode; `--pricing-file` on `beacon token-usage` and `beacon pricing` names another), schema `beacon.pricing.overrides/v1`, documented in `docs/cli/pricing.mdx`. It is offline and Beacon never writes it: the CLI reads it per run, and the dashboard re-reads it per `/api/tokens` request, read-only, falling back to the catalog with `pricing.overrides.error` when it is invalid (the CLI fails instead). Rates are USD per MTok converted exactly to microdollars; zero, negative, quoted, sub-microdollar, absurd, unknown and duplicate keys are refused with the key named. `Pricer.Lookup` runs the same ladder over the file's names first and a row replaces the catalog row whole (omitted cache rates are unpublished, priced by the usual fallbacks); aliases map a reported name to an exact row or catalog key. Reports record `source` (`override`/`catalog`), `alias`, and the file's path and SHA-256. `beacon pricing show|list|info|validate` (`cli/beacon/cmd/pricing.go`) inspects resolution, the catalog, its provenance and the file.- 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.diff --git a/cli/beacon-hooks/cmd/prompt_id.go b/cli/beacon-hooks/cmd/prompt_id.goindex 41e38e67..0e2c69a3 100644--- a/cli/beacon-hooks/cmd/prompt_id.go+++ b/cli/beacon-hooks/cmd/prompt_id.go@@ -1,6 +1,11 @@package cmdimport (+ "bytes"+ "encoding/json"+ "io"+ "os"+ "path/filepath""strings""github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"@@ -15,6 +20,9 @@ import (// model-authored, and an argument that happened to be named turn_id is not the runtime naming its// turn.//+// Claude Code's hook payloads carry no prompt id, but they carry the transcript path, and Claude+// Code writes the prompt's id into that transcript; see claudeTranscriptPromptID.+//// 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{}) {@@ -27,8 +35,119 @@ func applyPromptID(fields, input map[string]interface{}) {}}id := asymptoteobserve.PromptIDFrom(input)+ if id == "" && platformFlag == "claude" && claudeTurnScopedHook(input) {+ id = claudeTranscriptPromptID(getFirstStr(input, "transcript_path", "transcriptPath"))+ }if id == "" {return}fields["prompt"] = mergeNested(fields["prompt"], map[string]interface{}{"id": id})}++// claudeTurnScopedHook reports whether a Claude Code hook fires inside a prompt's turn, after the+// prompt has been written to the transcript.+//+// UserPromptSubmit is excluded deliberately. It runs before Claude Code records the prompt it is+// about, so the newest id in the transcript at that moment is the previous prompt's, and stamping+// it would put the new prompt in the old turn. That event's id comes from Claude Code's own OTLP+// user_prompt event, which carries it. Session start and end are not part of any one turn.+func claudeTurnScopedHook(input map[string]interface{}) bool {+ switch getFirstStr(input, "hook_event_name", "hookEventName") {+ case "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest", "PermissionDenied",+ "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact":+ return true+ }+ return false+}++// claudeTranscriptTailBytes bounds how much of a transcript one hook reads. A hook runs on every+// tool call, and a long session's transcript is many megabytes; the prompt and every tool result+// since carry the id, so the newest one is almost always in the last chunk read.+const (+ claudeTranscriptTailBytes = 1 << 20+ claudeTranscriptChunkBytes = 64 << 10+)++// claudeTranscriptPromptID returns the newest promptId in a Claude Code session transcript.+//+// Claude Code stamps promptId on the prompt's entry and on every tool-result entry that follows+// it, and it is the same UUID its OTLP events carry as prompt.id, so a hook event reading it here+// joins the OTLP events of the same turn on one value. The file is read backwards a chunk at a+// time and the read stops at the first entry carrying one, so the usual cost is one small read+// however long the session is. Only a regular .jsonl file is read, and any failure returns+// nothing: a missing id costs one field, while a hook that failed or stalled would cost the event.+func claudeTranscriptPromptID(path string) string {+ path = strings.TrimSpace(path)+ if path == "" || !strings.EqualFold(filepath.Ext(path), ".jsonl") {+ return ""+ }+ file, err := os.Open(path)+ if err != nil {+ return ""+ }+ defer file.Close()+ info, err := file.Stat()+ if err != nil || !info.Mode().IsRegular() {+ return ""+ }+ size := info.Size()+ window := size+ if window > claudeTranscriptTailBytes {+ window = claudeTranscriptTailBytes+ }+ // tail holds the last `read` bytes of the file. It grows a chunk at a time from the front, so+ // the common case -- an id within the last chunk -- reads and allocates one chunk.+ var tail []byte+ read := int64(0)+ for read < window {+ n := window - read+ if n > claudeTranscriptChunkBytes {+ n = claudeTranscriptChunkBytes+ }+ chunk := make([]byte, n, n+int64(len(tail)))+ if _, err := file.ReadAt(chunk, size-read-n); err != nil && err != io.EOF {+ return ""+ }+ tail = append(chunk, tail...)+ read += n+ if id := newestPromptID(tail, size > read); id != "" {+ return id+ }+ }+ return ""+}++// newestPromptID scans transcript lines from the end for the first entry carrying a promptId,+// without splitting the buffer. When the buffer starts mid-file its first line is a fragment and+// is never parsed.+//+// The marker cannot match inside a string value: JSON escapes a quote inside a string, so quoted+// text containing promptId appears as \"promptId\" and never as the bare key.+func newestPromptID(tail []byte, partialFirstLine bool) string {+ marker := []byte(`"promptId"`)+ end := len(tail)+ for end > 0 {+ at := bytes.LastIndex(tail[:end], marker)+ if at < 0 {+ return ""+ }+ lineStart := bytes.LastIndexByte(tail[:at], '\n') + 1+ if lineStart == 0 && partialFirstLine {+ return ""+ }+ lineEnd := len(tail)+ if i := bytes.IndexByte(tail[at:], '\n'); i >= 0 {+ lineEnd = at + i+ }+ var entry struct {+ PromptID string `json:"promptId"`+ }+ if json.Unmarshal(bytes.TrimSpace(tail[lineStart:lineEnd]), &entry) == nil {+ if id := strings.TrimSpace(entry.PromptID); id != "" {+ return id+ }+ }+ end = lineStart+ }+ return ""+}diff --git a/cli/beacon-hooks/cmd/prompt_id_test.go b/cli/beacon-hooks/cmd/prompt_id_test.goindex ed56e540..55db59cd 100644--- a/cli/beacon-hooks/cmd/prompt_id_test.go+++ b/cli/beacon-hooks/cmd/prompt_id_test.go@@ -1,7 +1,9 @@package cmdimport (+ "os""path/filepath"+ "strings""testing")@@ -171,3 +173,200 @@ func TestCursorTurnCarriesOneIDAcrossHookFamilies(t *testing.T) {}}}++// writeClaudeTranscript writes a Claude Code transcript with the shape Claude Code gives it: the+// prompt and every tool result carry promptId, assistant entries do not.+func writeClaudeTranscript(t *testing.T, lines ...string) string {+ t.Helper()+ path := filepath.Join(t.TempDir(), "claude-session.jsonl")+ if err := os.WriteFile(path, []byte(strings.Join(lines, "\n")+"\n"), 0o600); err != nil {+ t.Fatal(err)+ }+ return path+}++// Claude Code's hook payloads carry no prompt id. Its transcript does, under the same UUID its+// OTLP events carry as prompt.id, so a tool hook reads the newest one there and joins the OTLP+// events of its turn.+func TestClaudeToolHookReadsPromptIDFromTranscript(t *testing.T) {+ setupHookConfigDirs(t)+ platformFlag = "claude"+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)+ t.Setenv("BEACON_DISABLE_GIT_METADATA", "1")+ transcript := writeClaudeTranscript(t,+ `{"type":"user","promptId":"p-old","message":{"role":"user","content":"first"}}`,+ `{"type":"assistant","message":{"role":"assistant","content":[]}}`,+ `{"type":"user","promptId":"p-new","message":{"role":"user","content":"second"}}`,+ `{"type":"assistant","message":{"role":"assistant","content":[]}}`,+ `{"type":"user","promptId":"p-new","message":{"role":"user","content":[{"type":"tool_result"}]}}`,+ `{"type":"assistant","message":{"role":"assistant","content":[]}}`,+ `{"type":"last-prompt","lastPrompt":"second"}`,+ )++ runHookWithInput(t, runPostTool, map[string]interface{}{+ "session_id": "claude-session",+ "transcript_path": transcript,+ "cwd": "/repo",+ "hook_event_name": "PostToolUse",+ "tool_name": "Bash",+ "tool_use_id": "toolu_1",+ "tool_input": map[string]interface{}{"command": "echo hi"},+ "tool_response": map[string]interface{}{"stdout": "hi"},+ })++ if got := promptIDOfEvent(lastEndpointEvent(t, logPath)); got != "p-new" {+ t.Fatalf("prompt.id = %q, want the newest promptId in the transcript", got)+ }+}++// UserPromptSubmit runs before Claude Code records the prompt, so the newest id in the transcript+// is the previous prompt's. Stamping it would file the new prompt under the old turn.+func TestClaudePromptSubmitDoesNotTakeThePreviousPromptsID(t *testing.T) {+ setupHookConfigDirs(t)+ platformFlag = "claude"+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)+ t.Setenv("BEACON_DISABLE_GIT_METADATA", "1")+ transcript := writeClaudeTranscript(t, `{"type":"user","promptId":"p-old","message":{"role":"user","content":"first"}}`)++ runHookWithInput(t, runPromptSubmit, map[string]interface{}{+ "session_id": "claude-session",+ "transcript_path": transcript,+ "cwd": "/repo",+ "hook_event_name": "UserPromptSubmit",+ "prompt": "second",+ })++ for _, event := range endpointEvents(t, logPath) {+ if got := promptIDOfEvent(event); got != "" {+ t.Fatalf("%s prompt.id = %q, want none", leaf(event, "event", "action"), got)+ }+ }+}++func TestNewestPromptIDFromTranscriptTail(t *testing.T) {+ for name, tc := range map[string]struct {+ tail string+ partial bool+ want string+ }{+ "newest wins": {`{"promptId":"a"}` + "\n" + `{"promptId":"b"}` + "\n", false, "b"},+ "skips entries without": {`{"promptId":"a"}` + "\n" + `{"type":"assistant"}` + "\n", false, "a"},+ "skips malformed": {`{"promptId":"a"}` + "\n" + `{"promptId":` + "\n", false, "a"},+ "partial first line": {`ptId":"cut"}` + "\n" + `{"type":"assistant"}`, true, ""},+ "none": {`{"type":"assistant"}`, false, ""},+ } {+ t.Run(name, func(t *testing.T) {+ if got := newestPromptID([]byte(tc.tail), tc.partial); got != tc.want {+ t.Fatalf("newestPromptID = %q, want %q", got, tc.want)+ }+ })+ }+}++// A transcript longer than the read window is read from its end only, and the fragment the window+// starts in is not mistaken for an entry.+func TestClaudeTranscriptPromptIDReadsOnlyTheTail(t *testing.T) {+ filler := `{"type":"assistant","message":{"content":"` + strings.Repeat("x", 4096) + `"}}`+ lines := []string{`{"type":"user","promptId":"p-early"}`}+ for i := 0; i < (claudeTranscriptTailBytes/len(filler))+8; i++ {+ lines = append(lines, filler)+ }+ lines = append(lines, `{"type":"user","promptId":"p-late"}`, filler)+ path := writeClaudeTranscript(t, lines...)++ if got := claudeTranscriptPromptID(path); got != "p-late" {+ t.Fatalf("claudeTranscriptPromptID = %q, want p-late", got)+ }+ if got := claudeTranscriptPromptID(filepath.Join(t.TempDir(), "missing.jsonl")); got != "" {+ t.Fatalf("missing transcript gave %q", got)+ }+ if got := claudeTranscriptPromptID(t.TempDir()); got != "" {+ t.Fatalf("a directory gave %q", got)+ }+}++// The reader works backwards a chunk at a time. An entry that straddles a chunk boundary, one+// several chunks back, and one beyond the read window are the cases that chunking can get wrong.+func TestClaudeTranscriptPromptIDAcrossChunkBoundaries(t *testing.T) {+ // filler builds assistant lines of an exact byte length, newline included.+ filler := func(total int) []string {+ var lines []string+ for total > 0 {+ n := 8192+ if total < n {+ n = total+ }+ if n < 64 {+ // A line too short to hold the JSON is folded into the previous one.+ lines[len(lines)-1] = lines[len(lines)-1][:len(lines[len(lines)-1])] + strings.Repeat(" ", n)+ break+ }+ body := `{"type":"assistant","pad":"` + strings.Repeat("x", n-len(`{"type":"assistant","pad":""}`)-1) + `"}`+ lines = append(lines, body)+ total -= n+ }+ return lines+ }+ idLine := func(id string) string { return `{"type":"user","promptId":"` + id + `"}` }++ for name, tc := range map[string]struct {+ after int // bytes of filler written after the newest id line+ want string+ }{+ "in the last chunk": {after: 1000, want: "p-new"},+ "straddling the chunk boundary": {after: claudeTranscriptChunkBytes - 10, want: "p-new"},+ "exactly at the boundary": {after: claudeTranscriptChunkBytes, want: "p-new"},+ "several chunks back": {after: 5*claudeTranscriptChunkBytes + 123, want: "p-new"},+ "beyond the window": {after: claudeTranscriptTailBytes + 4096, want: ""},+ } {+ t.Run(name, func(t *testing.T) {+ lines := append([]string{idLine("p-old")}, filler(3*claudeTranscriptChunkBytes)...)+ lines = append(lines, idLine("p-new"))+ lines = append(lines, filler(tc.after)...)+ path := writeClaudeTranscript(t, lines...)+ if got := claudeTranscriptPromptID(path); got != tc.want {+ t.Fatalf("claudeTranscriptPromptID = %q, want %q", got, tc.want)+ }+ })+ }+}++// Quoted text that mentions promptId -- a tool result that printed a transcript, say -- is escaped+// inside a JSON string and never matches the bare key.+func TestNewestPromptIDIgnoresQuotedMentions(t *testing.T) {+ tail := `{"type":"user","promptId":"real"}` + "\n" ++ `{"type":"assistant","message":{"content":"{\"promptId\":\"forged\"}"}}` + "\n"+ if got := newestPromptID([]byte(tail), false); got != "real" {+ t.Fatalf("newestPromptID = %q, want real", got)+ }+}++// Muse Code and DeepSeek Harness send Claude-shaped payloads with a transcript_path, but their+// transcripts are their own format, and promptId in them would not be Claude Code's prompt id.+// Only the claude platform reads one.+func TestOnlyClaudeReadsTheTranscriptForAPromptID(t *testing.T) {+ transcript := writeClaudeTranscript(t, `{"type":"user","promptId":"p-claude"}`)+ for _, platform := range []string{"muse", "dsh", "qwen"} {+ t.Run(platform, func(t *testing.T) {+ saved := platformFlag+ t.Cleanup(func() { platformFlag = saved })+ platformFlag = platform+ fields := map[string]interface{}{"command": map[string]interface{}{"command": "ls"}}+ applyPromptID(fields, map[string]interface{}{+ "hook_event_name": "PostToolUse",+ "transcript_path": transcript,+ })+ if _, ok := fields["prompt"]; ok {+ t.Fatalf("%s took a prompt id from the transcript: %#v", platform, fields["prompt"])+ }+ })+ }+ platformFlag = "claude"+ fields := map[string]interface{}{}+ applyPromptID(fields, map[string]interface{}{"hook_event_name": "PostToolUse", "transcript_path": transcript})+ if got := leaf(fields, "prompt", "id"); got != "p-claude" {+ t.Fatalf("claude prompt.id = %q, want p-claude", got)+ }+}diff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdxindex 65f45582..4c716b39 100644--- a/docs/runtimes/claude-code.mdx+++ b/docs/runtimes/claude-code.mdx@@ -75,7 +75,7 @@ Beacon detects Claude Code through the `claude` executable and Claude settings p| Area | Support ||------|---------|| Prompt telemetry | Supported when emitted through Claude Code OTLP or hooks |-| Turn identity | Supported on OTLP events, where Claude Code's `prompt.id` is kept as `prompt.id` |+| Turn identity | Supported. Claude Code's `prompt.id` is kept as `prompt.id` on OTLP events, and hook events after the prompt read the same id from the session transcript. The hook-recorded prompt itself takes its id from the OTLP `user_prompt` event, because the hook runs before Claude Code records the prompt || Command, tool, and file telemetry | Supported through Claude Code OTLP with detailed tool inputs enabled || Token usage and cost | Supported through OTLP token and cost metrics, with per-model and per-session attribution || Hook lifecycle and tool telemetry | Optional through `beacon endpoint hooks install --harness claude` |