Skip to content

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

Read Claude Code's prompt id from the transcript in hooks

Claudeb59514f805cf
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.go
index 41e38e67..0e2c69a3 100644
--- a/cli/beacon-hooks/cmd/prompt_id.go
+++ b/cli/beacon-hooks/cmd/prompt_id.go
@@ -1,6 +1,11 @@
package cmd
import (
+ "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.go
index 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 cmd
import (
+ "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.mdx
index 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` |