Skip to content

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

Add the OpenClaw Gateway hook adapter

Claude06a10bc9593d
diff --git a/cli/beacon-hooks/cmd/helpers.go b/cli/beacon-hooks/cmd/helpers.go
index db0a6f0a..c2a66808 100644
--- a/cli/beacon-hooks/cmd/helpers.go
+++ b/cli/beacon-hooks/cmd/helpers.go
@@ -142,6 +142,14 @@ func resolveSessionID(input map[string]interface{}, platform string) string {
// own, which lands on the same key and needs no separate spelling.
case "pi", "omp":
return getFirstStr(input, "sessionId", "session_id", "sessionID")
+ // The Beacon plugin lifts OpenClaw's session id onto the envelope from the hook context,
+ // falling back to the event's own when the context did not carry one. `sessionKey` is
+ // deliberately not read here: it is the *conversation* key, stable across the session-id
+ // rotation a compaction causes, so reading it as the session id would merge every compaction
+ // generation of one conversation into a single session. It is kept under `raw` instead, where
+ // a query that wants the conversation can still reach it.
+ case openClawPlatform:
+ return getFirstStr(input, "sessionId", "session_id")
default:
id, _ := input["session_id"].(string)
return id
@@ -274,6 +282,17 @@ func resolveCwd(input map[string]interface{}, platform string) string {
return cwd
}
}
+ if platform == openClawPlatform {
+ // The plugin lifts `ctx.workspaceDir` onto the envelope as `cwd`. OpenClaw sets it for
+ // runs that have a repository and omits it for the rest -- a chat turn that never touched
+ // a workspace genuinely has none -- so an absent value leaves the field absent rather than
+ // falling back to the gateway process's own directory, which would attribute the work to
+ // wherever the daemon happens to have been started.
+ if cwd := getFirstStr(input, "cwd", "workspaceDir", "workspace_dir"); cwd != "" {
+ return cwd
+ }
+ return ""
+ }
if platform == "cline" {
if cwd := getFirstStr(input, "cwd", "workingDirectory", "working_directory"); cwd != "" {
return cwd
diff --git a/cli/beacon-hooks/cmd/openclaw_event.go b/cli/beacon-hooks/cmd/openclaw_event.go
new file mode 100644
index 00000000..d8c95cee
--- /dev/null
+++ b/cli/beacon-hooks/cmd/openclaw_event.go
@@ -0,0 +1,797 @@
+package cmd
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "path/filepath"
+ "strings"
+
+ hookdiff "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/diff"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+ "github.com/spf13/cobra"
+)
+
+// openclaw-event is the single entry point for every OpenClaw Gateway plugin hook payload.
+//
+// OpenClaw is a self-hosted gateway that connects chat apps -- Discord, Slack, Signal, WhatsApp
+// and the rest -- to coding agents. Its telemetry reaches Beacon over two paths that collect
+// different things and are both wanted:
+//
+// - The OTLP path (`beacon endpoint integrations openclaw`) configures OpenClaw's own
+// `diagnostics-otel` plugin. It carries gateway-level traces and metrics, and it carries
+// nothing about the agent's actions unless `captureContent` is turned on -- which OpenClaw
+// documents as off by default.
+// - This path, a Beacon-managed plugin, subscribes to OpenClaw's typed plugin hooks and reports
+// the agent's actual work: sessions, prompts, tool calls, commands, files, MCP activity and
+// token usage.
+//
+// The transport is the one every Beacon-managed plugin uses: the plugin spawns this binary and
+// writes one JSON object to its stdin. The envelope the plugin writes is
+//
+// {"hook": "before_tool_call", "sessionId": "...", "sessionKey": "...", "runId": "...",
+// "agentId": "...", "cwd": "...", "model": "openai/gpt-5", "channel": "discord",
+// "event": { ...the verbatim hook event... }}
+//
+// `event` stays nested rather than being spread onto the envelope, which is the one structural
+// difference from the Pi-family and Cline plugins. OpenClaw hands a handler `(event, ctx)` as two
+// separate objects whose field names overlap -- `runId`, `sessionKey` and `sessionId` are on both,
+// and `before_tool_call` carries a `params` object whose keys are the model's, not OpenClaw's. A
+// flattened envelope would let a tool argument named `sessionId` overwrite the session the event
+// belongs to. Keeping the two apart costs one level of nesting and makes that impossible.
+var openClawEventCmd = &cobra.Command{
+ Use: "openclaw-event",
+ Short: "Record OpenClaw Gateway hook telemetry",
+ Long: `openclaw-event receives raw Beacon OpenClaw plugin payloads and writes local endpoint telemetry.`,
+ Run: runOpenClawEvent,
+}
+
+func init() {
+ rootCmd.AddCommand(openClawEventCmd)
+}
+
+// openClawPlatform is the `--platform` value an OpenClaw install is recorded under.
+//
+// It selects the session-id and working-directory readers in helpers.go and is what
+// asymptoteobserve.CollectionMethodForPlatform keys on to report this runtime as `plugin` rather
+// than `hook`. The harness name it normalizes to is `openclaw_gateway`, shared with the OTLP path
+// so one gateway's activity is one harness in every query that groups by harness.name.
+const openClawPlatform = "openclaw"
+
+// openClawToolNameSeparator is what OpenClaw puts between an MCP server's name and its tool's.
+//
+// `TOOL_NAME_SEPARATOR` in OpenClaw's agent-bundle-mcp-names.ts. See openClawMCPServerTool for why
+// this separator is the only thing that identifies an MCP call on this runtime.
+const openClawToolNameSeparator = "__"
+
+func runOpenClawEvent(cmd *cobra.Command, args []string) {
+ input, err := readStdinJSON()
+ if err != nil {
+ outputJSON(emptyResponse)
+ return
+ }
+ sessionID := resolveSessionID(input, openClawPlatform)
+ logger := newHookLogger("openclaw-event", openClawPlatform, sessionID)
+ for _, event := range openClawEndpointEvents(input, sessionID) {
+ if event.action == "" {
+ continue
+ }
+ _ = logger.EndpointEvent(event.action, event.category, event.severity, event.message, event.fields)
+ }
+ outputJSON(emptyResponse)
+}
+
+// supportedOpenClawHooks lists every OpenClaw plugin hook this mapper handles.
+//
+// These strings are the contract between the managed plugin's registration list and the mapper: a
+// typo on either side produces no telemetry rather than an error, so both sides pin the list and a
+// test asserts each entry still maps to an event.
+//
+// OpenClaw publishes forty-one typed hooks. The ten below are the ones that describe what the
+// agent did; the rest describe how the gateway got its work done, and the notable exclusions are
+// worth stating because each looks collectible until you read its payload:
+//
+// - `llm_input` carries the full system prompt, the assembled prompt and the entire history
+// array on every model call. `message_received` already carries the operator's actual message,
+// which is the prompt an investigation asks about, at a fraction of the volume.
+// - `agent_end` carries the whole `messages` array for the turn. Its unique fields are a success
+// flag and a duration, which do not justify writing the conversation to the log a second time.
+// - `model_call_started` / `model_call_ended` fire once per provider call, so a single turn with
+// a tool loop produces a handful of pairs, and neither carries usage. `llm_output` reports the
+// turn's usage once.
+// - `tool_result_persist` and `before_message_write` are OpenClaw's two *synchronous* hooks:
+// promises are ignored with a warning, so a handler that spawns this binary could not wait for
+// it. Both also duplicate tool and message content already collected here.
+// - `before_prompt_build`, `agent_turn_prepare` and `heartbeat_prompt_contribution` are prompt
+// *injection* hooks. Beacon observes; registering them would ask OpenClaw for permission to
+// rewrite a prompt, which Beacon must never hold.
+// - The channel-delivery hooks (`message_sending`, `message_sent`, `reply_payload_sending`,
+// `reply_dispatch`, `before_dispatch`, `inbound_claim`) describe chat plumbing rather than
+// agent action, and the claim-kind ones can swallow a message outright.
+// - `skill_proposal_evaluate` is an Evaluate hook: registering it makes the plugin a voting
+// evaluator on whether a skill may be installed. That is enforcement, not observation.
+func supportedOpenClawHooks() []string {
+ return []string{
+ "session_start",
+ "session_end",
+ "message_received",
+ "before_tool_call",
+ "after_tool_call",
+ "llm_output",
+ "before_compaction",
+ "after_compaction",
+ "subagent_spawned",
+ "subagent_ended",
+ }
+}
+
+// openClawEndpointEvents maps one OpenClaw envelope onto the endpoint events it justifies.
+//
+// An unrecognized hook returns nothing rather than a generic event, matching the Cline and
+// Pi-family mappers: OpenClaw publishes four times as many hooks as the plugin registers, and one
+// arriving here should be silent rather than becoming an undifferentiated "something happened" row
+// that every query matches and none can explain.
+func openClawEndpointEvents(input map[string]interface{}, sessionID string) []normalizedEvent {
+ event := firstMap(input, "event")
+ if event == nil {
+ event = map[string]interface{}{}
+ }
+ fields := openClawBaseFields(input, event, sessionID)
+
+ switch getFirstStr(input, "hook") {
+ case "session_start":
+ // A resumed session has history behind it, which a reader counting sessions needs to know.
+ if resumed := getFirstStr(event, "resumedFrom"); resumed != "" {
+ fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"openclaw_resumed_from": resumed})
+ }
+ return openClawOne("session.started", "session", "info", "session started", fields)
+
+ case "session_end":
+ // OpenClaw names nine reasons a session ends, and they are not equivalent: `shutdown` and
+ // `restart` are the gateway stopping, `compaction` is the session rotating rather than
+ // finishing, and `deleted` is an operator removing it. Recorded verbatim rather than
+ // collapsed, because a session that ended by deletion and one that idled out are different
+ // facts about the same id.
+ extra := map[string]interface{}{}
+ if reason := getFirstStr(event, "reason"); reason != "" {
+ extra["openclaw_session_end_reason"] = reason
+ }
+ // The session id that continues this conversation, when a rotation produced one. Without
+ // it a compaction looks like a session ending and an unrelated one starting.
+ if next := getFirstStr(event, "nextSessionId"); next != "" {
+ extra["openclaw_next_session_id"] = next
+ }
+ if count, ok := firstToolIntAcross([]map[string]interface{}{event}, "messageCount"); ok {
+ extra["openclaw_message_count"] = count
+ }
+ if len(extra) > 0 {
+ fields["raw"] = mergeNested(fields["raw"], extra)
+ }
+ return openClawOne("session.ended", "session", "info", "session ended", fields)
+
+ case "message_received":
+ return openClawPromptEvents(input, event, fields)
+
+ case "before_tool_call":
+ // The pre-execution half of a tool call: OpenClaw has resolved the tool and its arguments
+ // but nothing has run yet. Recorded as tool.invoked, and deliberately not as an approval --
+ // see the approvals note below.
+ mergeMap(fields, openClawToolFields(event, nil))
+ applyToolCallID(fields, event)
+ return openClawOne("tool.invoked", "tool", "info", "tool invoked", fields)
+
+ case "after_tool_call":
+ return openClawAfterToolEvents(event, fields)
+
+ case "llm_output":
+ return openClawLlmOutputEvents(event, fields)
+
+ case "before_compaction":
+ if count, ok := firstToolIntAcross([]map[string]interface{}{event}, "messageCount"); ok {
+ fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"openclaw_message_count": count})
+ }
+ return openClawOne("session.compacting", "session", "info", "session compacting", fields)
+
+ case "after_compaction":
+ extra := map[string]interface{}{}
+ if count, ok := firstToolIntAcross([]map[string]interface{}{event}, "compactedCount"); ok {
+ extra["openclaw_compacted_count"] = count
+ }
+ // A compaction can rotate the physical session. The previous id is the only link back to
+ // the events written before the rotation.
+ if previous := getFirstStr(event, "previousSessionId"); previous != "" {
+ extra["openclaw_previous_session_id"] = previous
+ }
+ if len(extra) > 0 {
+ fields["raw"] = mergeNested(fields["raw"], extra)
+ }
+ return openClawOne("session.compacted", "session", "info", "session compacted", fields)
+
+ case "subagent_spawned":
+ extra := map[string]interface{}{}
+ if child := getFirstStr(event, "childSessionKey"); child != "" {
+ extra["openclaw_child_session_key"] = child
+ }
+ if mode := getFirstStr(event, "mode"); mode != "" {
+ extra["openclaw_subagent_mode"] = mode
+ }
+ if len(extra) > 0 {
+ fields["raw"] = mergeNested(fields["raw"], extra)
+ }
+ // The child's model rather than the parent's, when OpenClaw resolved a different one: a
+ // subagent routed to a cheaper or less restricted model is exactly what the row is for.
+ if model := getFirstStr(event, "resolvedModel"); model != "" {
+ fields["model"] = model
+ }
+ return openClawOne("subagent.started", "session", "info", "subagent started", fields)
+
+ case "subagent_ended":
+ extra := map[string]interface{}{}
+ if target := getFirstStr(event, "targetSessionKey"); target != "" {
+ extra["openclaw_child_session_key"] = target
+ }
+ if outcome := getFirstStr(event, "outcome"); outcome != "" {
+ extra["openclaw_subagent_outcome"] = outcome
+ }
+ if reason := getFirstStr(event, "reason"); reason != "" {
+ extra["openclaw_subagent_reason"] = reason
+ }
+ if len(extra) > 0 {
+ fields["raw"] = mergeNested(fields["raw"], extra)
+ }
+ if failure := getFirstStr(event, "error"); failure != "" {
+ fields["error"] = map[string]interface{}{"type": "subagent_error", "message": failure}
+ return openClawOne("subagent.stopped", "session", "high", "subagent failed", fields)
+ }
+ return openClawOne("subagent.stopped", "session", "info", "subagent stopped", fields)
+
+ default:
+ return nil
+ }
+}
+
+// Approvals: why this mapper writes none, stated where a reader will look for them.
+//
+// OpenClaw does ask operators to approve tool calls, and it exposes no hook that reports the
+// answer. Its forty-one typed hooks contain no `tool_approval_*` event; the only approval surface a
+// plugin has is `before_tool_call`'s `requireApproval` result, which is a plugin *requesting* a
+// prompt and being told its own outcome. Beacon does not request approvals, so it never sees one.
+//
+// There is a second thing on this runtime that looks like an approval and is not. An `exec` tool
+// result carries `details.approvalReviewOutcome` with values `approved`, `denied` and `reviewing`,
+// alongside `details.approvalReviews[]` entries that have a status and a rationale. OpenClaw's own
+// type calls these "model-backed approval reviews": they are an LLM judging the command, not a
+// person deciding about it. Recording one as `approval.allowed` would put a machine's opinion into
+// the field every approval detection reads as a human decision -- the single worst failure mode
+// this vocabulary has. They stay in `raw` with the rest of the tool result, where they are still
+// searchable and cannot be mistaken for consent.
+//
+// So approvals are not synthesized here, matching the Cline, Pi, goose, OpenHands and Kiro
+// decision. The endpoint policy seam is the supported way to gate an OpenClaw tool call, and it
+// records its own decisions with `policy.enforcement` rather than borrowing this vocabulary.
+
+// openClawOne wraps a single event, prefixing the runtime's name onto the message.
+func openClawOne(action, category, severity, messageSuffix string, values map[string]interface{}) []normalizedEvent {
+ return []normalizedEvent{{
+ action: action,
+ category: category,
+ severity: severity,
+ message: "OpenClaw " + messageSuffix,
+ fields: values,
+ }}
+}
+
+// openClawBaseFields builds the identity every OpenClaw event carries.
+//
+// The whole envelope goes under `raw.openclaw`, which is what preserves the fields OpenClaw
+// reports that the endpoint schema has no column for -- the channel a turn arrived on, the agent
+// id inside a multi-agent gateway, the requester's sender id. It is sanitized, secret-redacted and
+// string-limited like every other field, and it is the first thing dropped when an event exceeds
+// the size ceiling.
+func openClawBaseFields(input, event map[string]interface{}, sessionID string) map[string]interface{} {
+ fields := sessionFieldsForPlatform(sessionID, input, openClawPlatform)
+ applyWorkspaceFieldsForPlatform(fields, input, "", openClawPlatform)
+ fields["raw"] = map[string]interface{}{openClawPlatform: input}
+
+ // The model the turn ran on. `resolvedRef` is preferred over the context's because it keeps
+ // the provider prefix ("openai/gpt-5" rather than "gpt-5"), which the writer then splits into
+ // the canonical model name and `gen_ai.provider.name`. Handing it the bare id would leave the
+ // provider unrecorded, and a gateway routes one model through several of them.
+ if model := getFirstStr(event, "resolvedRef"); model != "" {
+ fields["model"] = model
+ } else if model := getFirstStr(input, "model"); model != "" {
+ fields["model"] = model
+ }
+
+ // OpenClaw's own identifiers for a turn and a conversation. `runId` is one end-to-end agent
+ // turn and is stable across every model call, retry and reply chunk inside it; `sessionKey` is
+ // the canonical conversation key, which survives the session-id rotation a compaction causes.
+ // Neither has an endpoint schema field, and both are how an operator correlates a Beacon row
+ // with what OpenClaw's own logs and dashboard show.
+ extra := map[string]interface{}{}
+ for key, value := range map[string]string{
+ "openclaw_run_id": getFirstStr(input, "runId"),
+ "openclaw_session_key": getFirstStr(input, "sessionKey"),
+ "openclaw_agent_id": getFirstStr(input, "agentId"),
+ "openclaw_channel": getFirstStr(input, "channel"),
+ } {
+ if value != "" {
+ extra[key] = value
+ }
+ }
+ if len(extra) > 0 {
+ fields["raw"] = mergeNested(fields["raw"], extra)
+ }
+ return fields
+}
+
+// openClawPromptEvents records the inbound message that started a turn.
+//
+// `message_received` rather than `llm_input` is the prompt on this runtime, and the choice is not
+// arbitrary. OpenClaw is a gateway: what a person actually wrote is the chat message that arrived
+// on Discord or Signal, while `llm_input`'s `prompt` is that message after channel context,
+// history and system material have been assembled around it. The first is evidence of what someone
+// asked for; the second is an artifact of how OpenClaw asked the model. `llm_input` also costs the
+// entire history array on every model call, and `message_received` is not behind the
+// `allowConversationAccess` config gate that every conversation hook is.
+func openClawPromptEvents(input, event, fields map[string]interface{}) []normalizedEvent {
+ prompt := getFirstStr(event, "content", "body")
+ if prompt == "" {
+ return nil
+ }
+ fields["prompt"] = map[string]interface{}{"text": prompt}
+ fields["gen_ai"] = mergeNested(fields["gen_ai"], map[string]interface{}{
+ "input": map[string]interface{}{"messages": asymptoteobserve.TextInputMessages(prompt)},
+ })
+ fields["content"] = retainedContentFields(prompt)
+
+ // Who sent it, and over which chat app. On a single-user coding CLI this is implied; on a
+ // gateway that fans several people's chat accounts into one agent it is the difference between
+ // "this machine ran a command" and "this person asked it to".
+ extra := map[string]interface{}{}
+ if from := getFirstStr(event, "from", "senderId"); from != "" {
+ extra["openclaw_sender"] = from
+ }
+ if channel := getFirstStr(input, "channel"); channel != "" {
+ extra["openclaw_channel"] = channel
+ }
+ if len(extra) > 0 {
+ fields["raw"] = mergeNested(fields["raw"], extra)
+ }
+ return []normalizedEvent{{
+ action: "prompt.submitted", category: "prompt", severity: "info",
+ message: "Prompt submitted to OpenClaw", fields: fields,
+ }}
+}
+
+// openClawLlmOutputEvents records what a finished model response reports: its token usage, and the
+// assistant's answer.
+//
+// This is the only OpenClaw hook that carries usage, and it is behind the
+// `plugins.entries.<id>.hooks.allowConversationAccess` config gate -- non-bundled plugins get no
+// conversation hooks without it, so an install that skips that key collects everything here except
+// tokens and the agent's reply. The installer writes it; `beacon endpoint hooks status` is where a
+// missing one shows up.
+func openClawLlmOutputEvents(event, fields map[string]interface{}) []normalizedEvent {
+ var events []normalizedEvent
+
+ if text := openClawAssistantText(event); text != "" {
+ messageFields := cloneFields(fields)
+ messageFields["gen_ai"] = mergeNested(messageFields["gen_ai"], map[string]interface{}{
+ "output": map[string]interface{}{
+ "messages": []interface{}{map[string]interface{}{
+ "role": "assistant",
+ "parts": []interface{}{map[string]interface{}{"type": "text", "content": text}},
+ }},
+ },
+ })
+ messageFields["content"] = retainedContentFields(text)
+ events = append(events, openClawOne("agent.message", "agent", "info", "agent message", messageFields)...)
+ }
+
+ if usage := openClawUsage(firstMap(event, "usage")); len(usage) > 0 {
+ usageFields := cloneFields(fields)
+ usageFields["gen_ai"] = mergeNested(usageFields["gen_ai"], map[string]interface{}{"usage": usage})
+ // The context window this turn was measured against. Kept separate from usage for the
+ // reason applyContextSize states: usage is additive and every report sums it, while a
+ // context budget is a level at one moment and summing it is meaningless.
+ if limit, ok := firstToolIntAcross([]map[string]interface{}{event}, "contextTokenBudget"); ok && limit > 0 {
+ if used, ok := usage["input_tokens"].(int); ok && used > 0 {
+ usageFields["gen_ai"] = mergeNested(usageFields["gen_ai"], map[string]interface{}{
+ "context": map[string]interface{}{"used_tokens": used, "limit_tokens": limit},
+ })
+ }
+ }
+ events = append(events, openClawOne("token.usage", "metric", "info", "token usage", usageFields)...)
+ }
+
+ return events
+}
+
+// openClawAssistantText joins the assistant's visible answer for one model response.
+//
+// `assistantTexts` is a string array because one response can be split across several text parts.
+// Only that field is read: `lastAssistant` is the provider's own message object, whose shape
+// differs per provider, and reading it would make Beacon's output depend on which model the
+// gateway happened to route to.
+func openClawAssistantText(event map[string]interface{}) string {
+ items, ok := event["assistantTexts"].([]interface{})
+ if !ok {
+ return ""
+ }
+ var parts []string
+ for _, item := range items {
+ if text, ok := item.(string); ok && text != "" {
+ parts = append(parts, text)
+ }
+ }
+ return strings.Join(parts, "\n")
+}
+
+// openClawUsage normalizes OpenClaw's usage object into gen_ai.usage.
+//
+// OpenClaw names its fields input/output/cacheRead/cacheWrite/total, none of which match the OTel
+// GenAI semconv names Beacon writes, and two of which are nested objects on Beacon's side rather
+// than scalars. The mapping is spelled out against the canonical shape rather than copied through,
+// so gen_ai.usage stays the only token representation in the log.
+//
+// `total` is deliberately dropped. Beacon's usage shape has no total, and a redundant field that
+// can disagree with its own parts is worse than an absent one.
+//
+// No cost. OpenClaw computes a per-turn USD figure (`turnUsd` on its reply usage state) from an
+// operator-configured cost table rather than from a provider report, and it is not on this hook.
+// Beacon records runtime-*reported* cost only, so a locally estimated one stays out of
+// gen_ai.usage.cost_usd even where it is available.
+func openClawUsage(usage map[string]interface{}) map[string]interface{} {
+ if usage == nil {
+ return nil
+ }
+ sources := []map[string]interface{}{usage}
+ out := map[string]interface{}{}
+ if value, ok := firstToolIntAcross(sources, "input"); ok {
+ out["input_tokens"] = value
+ }
+ if value, ok := firstToolIntAcross(sources, "output"); ok {
+ out["output_tokens"] = value
+ }
+ if value, ok := firstToolIntAcross(sources, "cacheRead"); ok {
+ out["cache_read"] = map[string]interface{}{"input_tokens": value}
+ }
+ if value, ok := firstToolIntAcross(sources, "cacheWrite"); ok {
+ out["cache_creation"] = map[string]interface{}{"input_tokens": value}
+ }
+ if len(out) == 0 {
+ return nil
+ }
+ return out
+}
+
+// openClawAfterToolEvents maps a completed tool call onto the outcome events it justifies.
+//
+// One call can become several events: an `apply_patch` that touched three files is three
+// `file.modified` rows, because a single row naming one of the three would under-report the change
+// and a row naming none would be unsearchable. That is the OpenHands shape and it is chosen for
+// the same reason.
+func openClawAfterToolEvents(event, fields map[string]interface{}) []normalizedEvent {
+ name := openClawToolName(event)
+ result := firstMap(event, "result")
+ mergeMap(fields, openClawToolFields(event, result))
+ applyToolCallID(fields, event)
+
+ // OpenClaw reports a failed tool call on the same hook as a successful one, distinguished by
+ // an `error` string. The write that did not land must not be recorded as a write that did.
+ if failure := getFirstStr(event, "error"); failure != "" {
+ fields["error"] = map[string]interface{}{"type": "tool_error", "message": failure}
+ return openClawOne("tool.failed", "tool", "high", "tool failed", fields)
+ }
+
+ if duration, ok := firstToolIntAcross([]map[string]interface{}{event}, "durationMs"); ok {
+ fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"openclaw_duration_ms": duration})
+ }
+
+ if paths := openClawPatchPaths(event); len(paths) > 0 {
+ return openClawPatchEvents(event, fields, paths)
+ }
+
+ action, category := openClawToolAction(name)
+ // A file action with no file is not a file action, and a command action with no command is not
+ // a command. A custom tool registered by a plugin can share a built-in's name, and a built-in
+ // can be called with arguments that failed to resolve, so reporting either would produce a row
+ // every scoped query matches and none can explain -- the guard the Cline and Pi-family mappers
+ // apply for the same reason.
+ if strings.HasPrefix(action, "file.") {
+ if _, ok := fields["file"]; !ok {
+ action, category = "tool.completed", "tool"
+ }
+ }
+ if action == "command.executed" {
+ if _, ok := fields["command"]; !ok {
+ action, category = "tool.completed", "tool"
+ }
+ }
+ return openClawOne(action, category, openClawSeverity(action, fields), openClawToolMessageSuffix(action), fields)
+}
+
+// openClawPatchEvents turns one apply_patch call into one file event per path it changed.
+func openClawPatchEvents(event, fields map[string]interface{}, paths []string) []normalizedEvent {
+ // openClawToolFields retained the patch on the shared fields, which every per-path event is
+ // cloned from. Lifted off before the clones are taken so it lands on exactly one of them --
+ // see the comment below the loop for why one and not all.
+ patchContent := fields["content"]
+ delete(fields, "content")
+
+ var events []normalizedEvent
+ for _, path := range paths {
+ pathFields := cloneFields(fields)
+ file := map[string]interface{}{"path": path, "operation": "modify"}
+ if language := strings.TrimPrefix(filepath.Ext(path), "."); language != "" {
+ file["language"] = language
+ }
+ pathFields["file"] = file
+ pathFields["tool"] = mergeNested(pathFields["tool"], map[string]interface{}{"path": path})
+ events = append(events, openClawOne("file.modified", "file", "info", "file modified", pathFields)...)
+ }
+ // The patch envelope itself, retained once on the first event rather than repeated on each.
+ // It is the only record of what actually changed -- OpenClaw's apply_patch result carries a
+ // summary, not the content -- and copying it per path would multiply the largest field in the
+ // event by the number of files the patch touched.
+ if len(events) > 0 && patchContent != nil {
+ events[0].fields["content"] = patchContent
+ }
+ return events
+}
+
+// openClawPatchPaths returns the files an apply_patch call changed.
+//
+// OpenClaw derives these itself and hands them to `before_tool_call` as `derivedPaths`, which its
+// own documentation calls a lenient convenience hint rather than an authoritative parse. That is
+// the right level of trust for telemetry and the wrong one for a policy decision: a path Beacon
+// records that the patch did not touch is a misleading row, while a path a policy engine misses is
+// an unenforced rule. Beacon only records, so the hint is used as given.
+//
+// `after_tool_call` does not carry `derivedPaths`, so the plugin copies the value forward from the
+// `before_tool_call` it saw for the same `toolCallId`. When it has none -- an OpenClaw build that
+// does not derive paths for this envelope, or a call the plugin never saw proposed -- this returns
+// nothing and the call is recorded as a completed tool with its patch text rather than as a file
+// change with an invented path.
+func openClawPatchPaths(event map[string]interface{}) []string {
+ if !strings.EqualFold(openClawToolName(event), "apply_patch") {
+ return nil
+ }
+ items, ok := event["derivedPaths"].([]interface{})
+ if !ok {
+ return nil
+ }
+ var paths []string
+ for _, item := range items {
+ if path, ok := item.(string); ok && strings.TrimSpace(path) != "" {
+ paths = append(paths, hookdiff.NormalizePath(path))
+ }
+ }
+ return paths
+}
+
+// openClawToolName reads the tool name off a before_tool_call or after_tool_call event.
+func openClawToolName(event map[string]interface{}) string {
+ return getFirstStr(event, "toolName", "tool_name")
+}
+
+// openClawToolFields builds the tool, command, file and MCP blocks for one OpenClaw tool event.
+//
+// OpenClaw's built-in tools have fixed, documented argument shapes, so these are read by name
+// rather than guessed at across spellings. A tool registered by another plugin carries an
+// arbitrary shape and gets `tool.name` plus its raw arguments without a command or file block
+// invented for it.
+func openClawToolFields(event map[string]interface{}, result map[string]interface{}) map[string]interface{} {
+ name := openClawToolName(event)
+ params := firstMap(event, "params")
+ if params == nil {
+ params = map[string]interface{}{}
+ }
+ details := firstMap(result, "details")
+
+ fields := map[string]interface{}{}
+ tool := map[string]interface{}{}
+ if name != "" {
+ tool["name"] = name
+ }
+
+ switch strings.ToLower(strings.TrimSpace(name)) {
+ case "exec":
+ if command := getFirstStr(params, "command"); command != "" {
+ tool["command"] = command
+ commandFields := map[string]interface{}{"command": command}
+ // The exit code and the captured output live on the result's details, and only for a
+ // call that finished: an exec that is still running reports `status: "running"` with a
+ // tail instead. Read by status rather than by presence so a backgrounded command's
+ // partial tail is never recorded as its final output.
+ switch getFirstStr(details, "status") {
+ case "completed", "failed":
+ if code, ok := firstToolIntAcross([]map[string]interface{}{details}, "exitCode"); ok {
+ commandFields["exit_code"] = code
+ }
+ if output := getFirstStr(details, "aggregated"); output != "" {
+ commandFields["output"] = output
+ fields["content"] = retainedContentFields(output)
+ }
+ }
+ if _, ok := fields["content"]; !ok {
+ fields["content"] = retainedContentFields(command)
+ }
+ fields["command"] = commandFields
+ }
+ case "read", "write", "edit":
+ if path := getFirstStr(params, "path", "file_path", "filePath"); path != "" {
+ path = hookdiff.NormalizePath(path)
+ tool["path"] = path
+ file := map[string]interface{}{"path": path, "operation": openClawFileOperation(name)}
+ if language := strings.TrimPrefix(filepath.Ext(path), "."); language != "" {
+ file["language"] = language
+ }
+ if diff := openClawFileDiff(name, path, params); diff != "" {
+ // The diff text itself, alongside the hash and byte count taken before the writer
+ // redacts or truncates the stored copy. The `content` marker beside it says
+ // whether what landed in the log is the whole diff; the hash and size say what the
+ // original was. diffFields builds the same three keys for the shared hook path, so
+ // a Beacon consumer reads one shape whichever runtime produced the row.
+ sum := sha256.Sum256([]byte(diff))
+ file["diff"] = diff
+ file["diff_hash"] = hex.EncodeToString(sum[:])
+ file["diff_bytes"] = len(diff)
+ fields["content"] = retainedContentFields(diff)
+ }
+ fields["file"] = file
+ }
+ case "apply_patch":
+ // The patch envelope is the whole argument. Paths come from derivedPaths in
+ // openClawPatchPaths; here it only supplies the tool block and the retained content for a
+ // call whose paths could not be derived.
+ if patch := getFirstStr(params, "input"); patch != "" {
+ fields["content"] = retainedContentFields(patch)
+ }
+ }
+
+ if len(tool) > 0 {
+ fields["tool"] = tool
+ }
+ openClawApplyMCPAttribution(fields, name)
+ return fields
+}
+
+// openClawFileDiff builds the diff for an OpenClaw write or edit.
+//
+// OpenClaw's `edit` takes `oldText` and `newText`, and requires `oldText` to match the file exactly
+// and uniquely -- so the pair describes a fragment, not the file, which is the shape
+// FromEditFragments exists for. Its `write` takes the whole `content` with no prior version
+// available on the hook, so the diff is the file's new content against nothing: a creation.
+//
+// A read has no diff, and neither does an edit whose two sides are identical; both return "" and
+// the event carries its path without one.
+func openClawFileDiff(name, path string, params map[string]interface{}) string {
+ switch strings.ToLower(strings.TrimSpace(name)) {
+ case "edit":
+ return hookdiff.FromEditFragments(path, getFirstStr(params, "oldText", "old_string", "oldString"), getFirstStr(params, "newText", "new_string", "newString"))
+ case "write":
+ return hookdiff.FromContentChange(path, "", getFirstStr(params, "content"))
+ default:
+ return ""
+ }
+}
+
+// openClawFileOperation maps an OpenClaw file tool onto the schema's operation vocabulary.
+func openClawFileOperation(name string) string {
+ switch strings.ToLower(strings.TrimSpace(name)) {
+ case "read":
+ return "read"
+ case "write":
+ return "create"
+ default:
+ return "modify"
+ }
+}
+
+// openClawToolAction maps an OpenClaw tool name onto the endpoint action its completion represents.
+func openClawToolAction(name string) (string, string) {
+ switch strings.ToLower(strings.TrimSpace(name)) {
+ case "exec":
+ return "command.executed", "command"
+ case "read":
+ return "file.read", "file"
+ case "write":
+ return "file.created", "file"
+ case "edit", "apply_patch":
+ return "file.modified", "file"
+ default:
+ if server, tool := openClawMCPServerTool(name); server != "" || tool != "" {
+ return "mcp.tool_invoked", "mcp"
+ }
+ // `ls`, `process`, the openclaw-family tools, and anything a plugin registered. Real tool
+ // activity with no file or command semantics worth asserting.
+ return "tool.completed", "tool"
+ }
+}
+
+// openClawSeverity raises a command event that reported a non-zero exit.
+//
+// Only commands, and only on a code the runtime actually reported: a tool whose result Beacon
+// could not read is not evidence of failure, and marking it as such would put noise where an
+// operator triages.
+func openClawSeverity(action string, fields map[string]interface{}) string {
+ if action != "command.executed" {
+ return "info"
+ }
+ command, ok := fields["command"].(map[string]interface{})
+ if !ok {
+ return "info"
+ }
+ if code, ok := command["exit_code"].(int); ok && code != 0 {
+ return "medium"
+ }
+ return "info"
+}
+
+// openClawToolMessageSuffix returns the human-readable half of a tool event's message.
+func openClawToolMessageSuffix(action string) string {
+ switch action {
+ case "command.executed":
+ return "command executed"
+ case "file.read":
+ return "file read"
+ case "file.created":
+ return "file created"
+ case "file.modified":
+ return "file modified"
+ case "tool.failed":
+ return "tool failed"
+ case "mcp.tool_invoked":
+ return "MCP tool invoked"
+ default:
+ return "tool completed"
+ }
+}
+
+// openClawApplyMCPAttribution fills the `mcp` block when a tool name names an MCP-routed tool.
+func openClawApplyMCPAttribution(fields map[string]interface{}, toolName string) {
+ server, tool := openClawMCPServerTool(toolName)
+ if server == "" && tool == "" {
+ return
+ }
+ mcp := map[string]interface{}{}
+ if server != "" {
+ mcp["server"] = server
+ }
+ if tool != "" {
+ mcp["tool"] = tool
+ }
+ fields["mcp"] = mergeNested(fields["mcp"], mcp)
+ fields["gen_ai"] = mergeNested(fields["gen_ai"], map[string]interface{}{
+ "operation": map[string]interface{}{"name": "execute_tool"},
+ })
+}
+
+// openClawMCPServerTool splits an OpenClaw MCP tool name into its server and tool halves.
+//
+// OpenClaw names a tool from an MCP server `<safeServerName>__<toolName>` -- two segments, with no
+// `mcp` anywhere in the name, no `mcp_*` argument, and nothing in the result that says where the
+// tool came from. So the shared `mcp__server__tool` reader finds nothing, and a GitHub server's
+// `github__create_issue` would otherwise be classified by tool name alone and land under
+// tool.completed with no server attribution at all. That is the goose situation and it has the
+// same single available signal: the separator.
+//
+// The `mcp__` form is tried first anyway, because OpenClaw's own Codex and Claude harness bridges
+// mint Claude-style names (`mcp__openclaw__automations`) that reach a hook through the same field,
+// and a three-segment name split on the first separator would report the server as `mcp`.
+//
+// Two segments are required and both must be non-empty, so a built-in tool with no separator, and
+// a name that merely ends in one, are left alone. A built-in whose own name contained `__` would be
+// misread here -- none does, in OpenClaw's factory descriptor list or its tool catalog.
+func openClawMCPServerTool(toolName string) (string, string) {
+ if server, tool := deriveMCPServerTool(toolName); server != "" || tool != "" {
+ return server, tool
+ }
+ trimmed := strings.TrimSpace(toolName)
+ server, tool, ok := strings.Cut(trimmed, openClawToolNameSeparator)
+ if !ok || server == "" || tool == "" {
+ return "", ""
+ }
+ return server, tool
+}
diff --git a/cli/beacon-hooks/cmd/openclaw_event_test.go b/cli/beacon-hooks/cmd/openclaw_event_test.go
new file mode 100644
index 00000000..8ca56164
--- /dev/null
+++ b/cli/beacon-hooks/cmd/openclaw_event_test.go
@@ -0,0 +1,593 @@
+package cmd
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// openClawEnvelope builds the envelope shape the Beacon OpenClaw plugin writes to this binary's
+// stdin, so every test below exercises the same contract the plugin has to honour.
+func openClawEnvelope(hook string, event map[string]interface{}, identity map[string]interface{}) map[string]interface{} {
+ envelope := map[string]interface{}{
+ "hook": hook,
+ "sessionId": "sess-1",
+ "cwd": "/workspace/repo",
+ "event": event,
+ }
+ for key, value := range identity {
+ envelope[key] = value
+ }
+ return envelope
+}
+
+func openClawEvents(t *testing.T, hook string, event map[string]interface{}, identity map[string]interface{}) []normalizedEvent {
+ t.Helper()
+ input := openClawEnvelope(hook, event, identity)
+ return openClawEndpointEvents(input, resolveSessionID(input, openClawPlatform))
+}
+
+func openClawSingle(t *testing.T, hook string, event map[string]interface{}, identity map[string]interface{}) normalizedEvent {
+ t.Helper()
+ events := openClawEvents(t, hook, event, identity)
+ if len(events) != 1 {
+ t.Fatalf("%s: got %d events, want 1: %+v", hook, len(events), events)
+ }
+ return events[0]
+}
+
+// The plugin's registration list and this mapper's switch are two halves of one contract, and a
+// mismatch is silent: an unregistered hook simply never fires, and an unmapped one produces no
+// event. Every supported hook must therefore still resolve to a case here.
+func TestOpenClawSupportedHooksAllMap(t *testing.T) {
+ payloads := map[string]map[string]interface{}{
+ "session_start": {"sessionId": "sess-1"},
+ "session_end": {"sessionId": "sess-1", "messageCount": 4},
+ "message_received": {"content": "ship the release", "from": "U123"},
+ "before_tool_call": {"toolName": "exec", "params": map[string]interface{}{"command": "ls"}},
+ "after_tool_call": {"toolName": "exec", "params": map[string]interface{}{"command": "ls"}},
+ "llm_output": {"usage": map[string]interface{}{"input": 10, "output": 5}},
+ "before_compaction": {"messageCount": 40},
+ "after_compaction": {"messageCount": 12, "compactedCount": 28},
+ "subagent_spawned": {"childSessionKey": "child-1", "agentId": "researcher", "mode": "run"},
+ "subagent_ended": {"targetSessionKey": "child-1", "targetKind": "subagent", "reason": "done"},
+ }
+ for _, hook := range supportedOpenClawHooks() {
+ payload, ok := payloads[hook]
+ if !ok {
+ t.Fatalf("hook %q has no fixture; add one when adding the hook", hook)
+ }
+ if got := openClawEvents(t, hook, payload, nil); len(got) == 0 {
+ t.Fatalf("hook %q produced no events", hook)
+ }
+ }
+}
+
+// An OpenClaw hook the plugin does not register must not become a generic row if it ever reaches
+// this binary by another route.
+func TestOpenClawUnknownHookProducesNothing(t *testing.T) {
+ for _, hook := range []string{"llm_input", "agent_end", "model_call_ended", "message_sent", ""} {
+ if got := openClawEvents(t, hook, map[string]interface{}{"content": "x"}, nil); len(got) != 0 {
+ t.Fatalf("hook %q produced %d events, want 0", hook, len(got))
+ }
+ }
+}
+
+func TestOpenClawSessionLifecycle(t *testing.T) {
+ start := openClawSingle(t, "session_start", map[string]interface{}{
+ "sessionId": "sess-1", "resumedFrom": "sess-0",
+ }, nil)
+ if start.action != "session.started" {
+ t.Fatalf("action = %q, want session.started", start.action)
+ }
+ if got := nested(t, start.fields, "session")["id"]; got != "sess-1" {
+ t.Fatalf("session.id = %v, want sess-1", got)
+ }
+ if got := nested(t, start.fields, "raw")["openclaw_resumed_from"]; got != "sess-0" {
+ t.Fatalf("resumed_from = %v, want sess-0", got)
+ }
+
+ end := openClawSingle(t, "session_end", map[string]interface{}{
+ "sessionId": "sess-1", "reason": "compaction", "nextSessionId": "sess-2", "messageCount": 9,
+ }, nil)
+ if end.action != "session.ended" {
+ t.Fatalf("action = %q, want session.ended", end.action)
+ }
+ raw := nested(t, end.fields, "raw")
+ if raw["openclaw_session_end_reason"] != "compaction" {
+ t.Fatalf("end reason = %v, want compaction", raw["openclaw_session_end_reason"])
+ }
+ if raw["openclaw_next_session_id"] != "sess-2" {
+ t.Fatalf("next session = %v, want sess-2", raw["openclaw_next_session_id"])
+ }
+}
+
+// sessionKey is the conversation, not the session. Reading it as the session id would merge every
+// compaction generation of one conversation into a single session, which is exactly what the
+// nextSessionId/previousSessionId pair exists to keep distinct.
+func TestOpenClawSessionKeyIsNotTheSessionID(t *testing.T) {
+ input := map[string]interface{}{
+ "hook": "session_start",
+ "sessionKey": "discord:chan-9",
+ "event": map[string]interface{}{},
+ }
+ if got := resolveSessionID(input, openClawPlatform); got != "" {
+ t.Fatalf("resolveSessionID from sessionKey alone = %q, want empty", got)
+ }
+ events := openClawEndpointEvents(input, "")
+ if len(events) != 1 {
+ t.Fatalf("got %d events, want 1", len(events))
+ }
+ if got := nested(t, events[0].fields, "raw")["openclaw_session_key"]; got != "discord:chan-9" {
+ t.Fatalf("raw session key = %v, want discord:chan-9", got)
+ }
+}
+
+func TestOpenClawPromptFromMessageReceived(t *testing.T) {
+ event := openClawSingle(t, "message_received", map[string]interface{}{
+ "content": "deploy staging", "from": "U42",
+ }, map[string]interface{}{"channel": "slack", "runId": "run-7"})
+
+ if event.action != "prompt.submitted" || event.category != "prompt" {
+ t.Fatalf("action/category = %q/%q", event.action, event.category)
+ }
+ if got := nested(t, event.fields, "prompt")["text"]; got != "deploy staging" {
+ t.Fatalf("prompt.text = %v", got)
+ }
+ messages, ok := nested(t, event.fields, "gen_ai", "input")["messages"]
+ if !ok {
+ t.Fatal("gen_ai.input.messages missing")
+ }
+ if len(messages.([]interface{})) == 0 {
+ t.Fatal("gen_ai.input.messages is empty")
+ }
+ raw := nested(t, event.fields, "raw")
+ if raw["openclaw_sender"] != "U42" {
+ t.Fatalf("sender = %v, want U42", raw["openclaw_sender"])
+ }
+ if raw["openclaw_channel"] != "slack" {
+ t.Fatalf("channel = %v, want slack", raw["openclaw_channel"])
+ }
+ if raw["openclaw_run_id"] != "run-7" {
+ t.Fatalf("run id = %v, want run-7", raw["openclaw_run_id"])
+ }
+ if _, ok := event.fields["content"]; !ok {
+ t.Fatal("retained content fields missing")
+ }
+}
+
+func TestOpenClawEmptyPromptProducesNothing(t *testing.T) {
+ if got := openClawEvents(t, "message_received", map[string]interface{}{"from": "U42"}, nil); len(got) != 0 {
+ t.Fatalf("got %d events for a contentless message, want 0", len(got))
+ }
+}
+
+func TestOpenClawExecCommand(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "exec",
+ "toolCallId": "call-1",
+ "params": map[string]interface{}{"command": "git push origin main", "workdir": "/workspace/repo"},
+ "durationMs": 1200,
+ "result": map[string]interface{}{
+ "details": map[string]interface{}{"status": "completed", "exitCode": 0, "aggregated": "Everything up-to-date"},
+ },
+ }, nil)
+
+ if event.action != "command.executed" || event.category != "command" {
+ t.Fatalf("action/category = %q/%q", event.action, event.category)
+ }
+ command := nested(t, event.fields, "command")
+ if command["command"] != "git push origin main" {
+ t.Fatalf("command = %v", command["command"])
+ }
+ if command["exit_code"] != 0 {
+ t.Fatalf("exit_code = %v, want 0", command["exit_code"])
+ }
+ if command["output"] != "Everything up-to-date" {
+ t.Fatalf("output = %v", command["output"])
+ }
+ if event.severity != "info" {
+ t.Fatalf("severity = %q, want info for a zero exit", event.severity)
+ }
+ if got := nested(t, event.fields, "gen_ai", "tool", "call")["id"]; got != "call-1" {
+ t.Fatalf("gen_ai.tool.call.id = %v, want call-1", got)
+ }
+}
+
+func TestOpenClawFailedCommandRaisesSeverity(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "exec",
+ "params": map[string]interface{}{"command": "make test"},
+ "result": map[string]interface{}{
+ "details": map[string]interface{}{"status": "failed", "exitCode": 2, "aggregated": "FAIL"},
+ },
+ }, nil)
+ if event.severity != "medium" {
+ t.Fatalf("severity = %q, want medium for a non-zero exit", event.severity)
+ }
+}
+
+// A backgrounded exec reports `status: "running"` with a partial tail and no exit code. Recording
+// the tail as the command's output would state an outcome the runtime has not reached.
+func TestOpenClawRunningExecRecordsNoOutcome(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "exec",
+ "params": map[string]interface{}{"command": "npm run dev"},
+ "result": map[string]interface{}{
+ "details": map[string]interface{}{"status": "running", "pid": 4242, "tail": "listening on 3000"},
+ },
+ }, nil)
+ command := nested(t, event.fields, "command")
+ if _, ok := command["exit_code"]; ok {
+ t.Fatalf("exit_code present for a running command: %v", command)
+ }
+ if _, ok := command["output"]; ok {
+ t.Fatalf("output present for a running command: %v", command)
+ }
+}
+
+func TestOpenClawFileTools(t *testing.T) {
+ read := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "read", "params": map[string]interface{}{"path": "/workspace/repo/main.go"},
+ }, nil)
+ if read.action != "file.read" {
+ t.Fatalf("read action = %q", read.action)
+ }
+ file := nested(t, read.fields, "file")
+ if file["path"] != "/workspace/repo/main.go" || file["operation"] != "read" || file["language"] != "go" {
+ t.Fatalf("file = %+v", file)
+ }
+
+ write := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "write",
+ "params": map[string]interface{}{"path": "/workspace/repo/new.txt", "content": "hello\n"},
+ }, nil)
+ if write.action != "file.created" {
+ t.Fatalf("write action = %q", write.action)
+ }
+ if nested(t, write.fields, "file")["operation"] != "create" {
+ t.Fatalf("write operation = %v", nested(t, write.fields, "file")["operation"])
+ }
+ if _, ok := write.fields["content"]; !ok {
+ t.Fatal("write produced no retained content")
+ }
+ if diff, _ := nested(t, write.fields, "file")["diff"].(string); !strings.Contains(diff, "+hello") {
+ t.Fatalf("write diff does not carry the new content: %q", diff)
+ }
+
+ edit := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "edit",
+ "params": map[string]interface{}{"path": "/workspace/repo/main.go", "oldText": "a := 1", "newText": "a := 2"},
+ }, nil)
+ if edit.action != "file.modified" {
+ t.Fatalf("edit action = %q", edit.action)
+ }
+ editFile := nested(t, edit.fields, "file")
+ diff, _ := editFile["diff"].(string)
+ if !strings.Contains(diff, "-a := 1") || !strings.Contains(diff, "+a := 2") {
+ t.Fatalf("edit diff does not describe the change: %q", diff)
+ }
+ if editFile["diff_bytes"] != len(diff) {
+ t.Fatalf("diff_bytes = %v, want %d", editFile["diff_bytes"], len(diff))
+ }
+ if hash, _ := editFile["diff_hash"].(string); len(hash) != 64 {
+ t.Fatalf("diff_hash = %q, want a sha256 hex digest", hash)
+ }
+ if _, ok := edit.fields["content"]; !ok {
+ t.Fatal("edit produced no retained content marker beside its diff")
+ }
+}
+
+// An edit whose two sides match changed nothing, so there is no diff to record; the file event
+// still carries its path.
+func TestOpenClawNoopEditHasNoDiff(t *testing.T) {
+ edit := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "edit",
+ "params": map[string]interface{}{"path": "/workspace/repo/main.go", "oldText": "same", "newText": "same"},
+ }, nil)
+ if _, ok := edit.fields["content"]; ok {
+ t.Fatalf("no-op edit produced content: %+v", edit.fields["content"])
+ }
+ if nested(t, edit.fields, "file")["path"] != "/workspace/repo/main.go" {
+ t.Fatal("no-op edit lost its path")
+ }
+}
+
+// A file tool whose path argument did not resolve is not a file action. Recording one would
+// produce a row every file-scoped query matches and none can explain.
+func TestOpenClawFileToolWithoutPathFallsBackToTool(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "read", "params": map[string]interface{}{},
+ }, nil)
+ if event.action != "tool.completed" || event.category != "tool" {
+ t.Fatalf("action/category = %q/%q, want tool.completed/tool", event.action, event.category)
+ }
+}
+
+func TestOpenClawApplyPatchBecomesOneEventPerPath(t *testing.T) {
+ patch := "*** Begin Patch\n*** Update File: a.go\n*** End Patch\n"
+ events := openClawEvents(t, "after_tool_call", map[string]interface{}{
+ "toolName": "apply_patch",
+ "toolCallId": "call-9",
+ "params": map[string]interface{}{"input": patch},
+ "derivedPaths": []interface{}{"/workspace/repo/a.go", "/workspace/repo/b.go"},
+ }, nil)
+
+ if len(events) != 2 {
+ t.Fatalf("got %d events, want one per derived path", len(events))
+ }
+ for i, want := range []string{"/workspace/repo/a.go", "/workspace/repo/b.go"} {
+ if events[i].action != "file.modified" {
+ t.Fatalf("event %d action = %q", i, events[i].action)
+ }
+ if got := nested(t, events[i].fields, "file")["path"]; got != want {
+ t.Fatalf("event %d path = %v, want %v", i, got, want)
+ }
+ if got := nested(t, events[i].fields, "gen_ai", "tool", "call")["id"]; got != "call-9" {
+ t.Fatalf("event %d lost the tool call id", i)
+ }
+ }
+ // The patch text is retained once rather than copied onto every path's event.
+ if _, ok := events[0].fields["content"]; !ok {
+ t.Fatal("first patch event carries no retained patch")
+ }
+ if _, ok := events[1].fields["content"]; ok {
+ t.Fatal("patch text repeated on the second event")
+ }
+}
+
+// Without derived paths there is nothing to name, so the call is recorded as a completed tool
+// carrying its patch rather than as a file change with an invented path.
+func TestOpenClawApplyPatchWithoutDerivedPathsRecordsNoFile(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "apply_patch",
+ "params": map[string]interface{}{"input": "*** Begin Patch\n*** End Patch\n"},
+ }, nil)
+ if _, ok := event.fields["file"]; ok {
+ t.Fatalf("file field invented without derived paths: %+v", event.fields["file"])
+ }
+ if event.action != "tool.completed" {
+ t.Fatalf("action = %q, want tool.completed", event.action)
+ }
+ if _, ok := event.fields["content"]; !ok {
+ t.Fatal("patch text not retained")
+ }
+}
+
+func TestOpenClawMCPToolAttribution(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "github__create_issue",
+ "params": map[string]interface{}{"title": "bug"},
+ }, nil)
+ if event.action != "mcp.tool_invoked" || event.category != "mcp" {
+ t.Fatalf("action/category = %q/%q", event.action, event.category)
+ }
+ mcp := nested(t, event.fields, "mcp")
+ if mcp["server"] != "github" || mcp["tool"] != "create_issue" {
+ t.Fatalf("mcp = %+v", mcp)
+ }
+}
+
+// OpenClaw's own Codex and Claude harness bridges mint Claude-style `mcp__server__tool` names.
+// Splitting those on the first separator would report the server as "mcp".
+func TestOpenClawClaudeStyleMCPName(t *testing.T) {
+ server, tool := openClawMCPServerTool("mcp__openclaw__automations")
+ if server != "openclaw" || tool != "automations" {
+ t.Fatalf("server/tool = %q/%q", server, tool)
+ }
+}
+
+func TestOpenClawBuiltinToolIsNotMCP(t *testing.T) {
+ for _, name := range []string{"exec", "read", "apply_patch", "ls", "process", "", "trailing__"} {
+ if server, tool := openClawMCPServerTool(name); server != "" || tool != "" {
+ t.Fatalf("%q read as MCP server %q tool %q", name, server, tool)
+ }
+ }
+}
+
+func TestOpenClawToolFailure(t *testing.T) {
+ event := openClawSingle(t, "after_tool_call", map[string]interface{}{
+ "toolName": "write",
+ "params": map[string]interface{}{"path": "/workspace/repo/x.txt", "content": "y"},
+ "error": "EACCES: permission denied",
+ }, nil)
+ if event.action != "tool.failed" || event.severity != "high" {
+ t.Fatalf("action/severity = %q/%q", event.action, event.severity)
+ }
+ if got := nested(t, event.fields, "error")["message"]; got != "EACCES: permission denied" {
+ t.Fatalf("error.message = %v", got)
+ }
+}
+
+func TestOpenClawLlmOutputUsageAndMessage(t *testing.T) {
+ events := openClawEvents(t, "llm_output", map[string]interface{}{
+ "assistantTexts": []interface{}{"pushed", "and tagged"},
+ "resolvedRef": "openai/gpt-5",
+ "contextTokenBudget": 200000,
+ "usage": map[string]interface{}{
+ "input": 1200, "output": 300, "cacheRead": 800, "cacheWrite": 64, "total": 1500,
+ },
+ }, nil)
+ if len(events) != 2 {
+ t.Fatalf("got %d events, want an agent.message and a token.usage", len(events))
+ }
+
+ message := events[0]
+ if message.action != "agent.message" {
+ t.Fatalf("first action = %q", message.action)
+ }
+ if message.fields["model"] != "openai/gpt-5" {
+ t.Fatalf("model = %v, want the provider-prefixed ref", message.fields["model"])
+ }
+
+ usageEvent := events[1]
+ if usageEvent.action != "token.usage" {
+ t.Fatalf("second action = %q", usageEvent.action)
+ }
+ usage := nested(t, usageEvent.fields, "gen_ai", "usage")
+ if usage["input_tokens"] != 1200 || usage["output_tokens"] != 300 {
+ t.Fatalf("usage = %+v", usage)
+ }
+ if got := nested(t, usageEvent.fields, "gen_ai", "usage", "cache_read")["input_tokens"]; got != 800 {
+ t.Fatalf("cache_read = %v, want 800", got)
+ }
+ if got := nested(t, usageEvent.fields, "gen_ai", "usage", "cache_creation")["input_tokens"]; got != 64 {
+ t.Fatalf("cache_creation = %v, want 64", got)
+ }
+ // `total` is redundant with its own parts and has no field in the canonical shape.
+ for key := range usage {
+ if key == "total" || key == "total_tokens" {
+ t.Fatalf("usage carries a total: %+v", usage)
+ }
+ }
+ // Cost is never derived locally, and OpenClaw reports none on this hook.
+ if _, ok := usage["cost_usd"]; ok {
+ t.Fatalf("usage carries a cost OpenClaw did not report: %+v", usage)
+ }
+ context := nested(t, usageEvent.fields, "gen_ai", "context")
+ if context["limit_tokens"] != 200000 || context["used_tokens"] != 1200 {
+ t.Fatalf("context = %+v", context)
+ }
+}
+
+func TestOpenClawLlmOutputWithoutUsageOrTextProducesNothing(t *testing.T) {
+ if got := openClawEvents(t, "llm_output", map[string]interface{}{"provider": "openai"}, nil); len(got) != 0 {
+ t.Fatalf("got %d events, want 0", len(got))
+ }
+}
+
+func TestOpenClawCompaction(t *testing.T) {
+ before := openClawSingle(t, "before_compaction", map[string]interface{}{"messageCount": 80}, nil)
+ if before.action != "session.compacting" {
+ t.Fatalf("action = %q", before.action)
+ }
+ after := openClawSingle(t, "after_compaction", map[string]interface{}{
+ "messageCount": 12, "compactedCount": 68, "previousSessionId": "sess-0",
+ }, nil)
+ if after.action != "session.compacted" {
+ t.Fatalf("action = %q", after.action)
+ }
+ raw := nested(t, after.fields, "raw")
+ if raw["openclaw_compacted_count"] != 68 || raw["openclaw_previous_session_id"] != "sess-0" {
+ t.Fatalf("raw = %+v", raw)
+ }
+}
+
+func TestOpenClawSubagentLifecycle(t *testing.T) {
+ spawned := openClawSingle(t, "subagent_spawned", map[string]interface{}{
+ "childSessionKey": "child-1", "agentId": "researcher", "mode": "run",
+ "resolvedModel": "anthropic/claude-opus-5",
+ }, nil)
+ if spawned.action != "subagent.started" {
+ t.Fatalf("action = %q", spawned.action)
+ }
+ if spawned.fields["model"] != "anthropic/claude-opus-5" {
+ t.Fatalf("model = %v, want the child's resolved model", spawned.fields["model"])
+ }
+
+ failed := openClawSingle(t, "subagent_ended", map[string]interface{}{
+ "targetSessionKey": "child-1", "targetKind": "subagent",
+ "reason": "error", "outcome": "error", "error": "provider timeout",
+ }, nil)
+ if failed.action != "subagent.stopped" || failed.severity != "high" {
+ t.Fatalf("action/severity = %q/%q", failed.action, failed.severity)
+ }
+ if got := nested(t, failed.fields, "error")["message"]; got != "provider timeout" {
+ t.Fatalf("error.message = %v", got)
+ }
+}
+
+// OpenClaw exposes no operator approval decision, and the one thing on this runtime that reads
+// like one -- an exec result's model-backed `approvalReviewOutcome` -- is an LLM's opinion, not a
+// person's. Neither may produce an approval event.
+func TestOpenClawNeverSynthesizesApprovals(t *testing.T) {
+ events := openClawEvents(t, "after_tool_call", map[string]interface{}{
+ "toolName": "exec",
+ "params": map[string]interface{}{"command": "rm -rf /tmp/build"},
+ "result": map[string]interface{}{
+ "details": map[string]interface{}{
+ "status": "completed", "exitCode": 0, "aggregated": "",
+ "approvalReviewOutcome": "approved",
+ "approvalReviews": []interface{}{
+ map[string]interface{}{"id": "r1", "label": "risk", "status": "approved", "rationale": "safe path"},
+ },
+ },
+ },
+ }, nil)
+ for _, event := range events {
+ if strings.HasPrefix(event.action, "approval.") {
+ t.Fatalf("synthesized an approval from a model-backed review: %+v", event)
+ }
+ if _, ok := event.fields["approval"]; ok {
+ t.Fatalf("event carries an approval block: %+v", event.fields["approval"])
+ }
+ }
+ // The review is still searchable, in raw with the rest of the payload.
+ body, err := json.Marshal(events[0].fields["raw"])
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(body), "approvalReviewOutcome") {
+ t.Fatalf("model-backed review dropped from raw: %s", body)
+ }
+}
+
+// A tool argument must never be able to overwrite the identity the envelope carries. This is the
+// reason the plugin nests the hook event instead of spreading it.
+func TestOpenClawToolParamsCannotOverwriteIdentity(t *testing.T) {
+ event := openClawSingle(t, "before_tool_call", map[string]interface{}{
+ "toolName": "exec",
+ "params": map[string]interface{}{
+ "command": "echo hi", "sessionId": "attacker-session", "cwd": "/etc",
+ },
+ }, nil)
+ if got := nested(t, event.fields, "session")["id"]; got != "sess-1" {
+ t.Fatalf("session.id = %v, want the envelope's sess-1", got)
+ }
+ if got := nested(t, event.fields, "session")["working_directory"]; got != "/workspace/repo" {
+ t.Fatalf("working_directory = %v, want the envelope's", got)
+ }
+}
+
+func TestOpenClawWorkspaceFields(t *testing.T) {
+ event := openClawSingle(t, "session_start", map[string]interface{}{"sessionId": "sess-1"}, nil)
+ if event.fields["repository"] != "/workspace/repo" {
+ t.Fatalf("repository = %v", event.fields["repository"])
+ }
+ if got := nested(t, event.fields, "session")["working_directory"]; got != "/workspace/repo" {
+ t.Fatalf("working_directory = %v", got)
+ }
+}
+
+// A chat turn that never touched a workspace genuinely has none. Falling back to the gateway
+// daemon's own directory would attribute the work to wherever it happened to be started.
+func TestOpenClawAbsentWorkspaceStaysAbsent(t *testing.T) {
+ input := map[string]interface{}{
+ "hook": "session_start",
+ "sessionId": "sess-1",
+ "event": map[string]interface{}{},
+ }
+ events := openClawEndpointEvents(input, "sess-1")
+ if len(events) != 1 {
+ t.Fatalf("got %d events, want 1", len(events))
+ }
+ if value, ok := events[0].fields["repository"]; ok && value != "" {
+ t.Fatalf("repository invented without a workspace: %v", value)
+ }
+}
+
+func TestOpenClawCollectionMethodIsPlugin(t *testing.T) {
+ if got := asymptoteobserve.CollectionMethodForPlatform(openClawPlatform); got != asymptoteobserve.CollectionMethodPlugin {
+ t.Fatalf("collection method = %q, want %q", got, asymptoteobserve.CollectionMethodPlugin)
+ }
+}
+
+func TestOpenClawHarnessName(t *testing.T) {
+ for _, spelling := range []string{"openclaw", "OpenClaw", "openclaw_gateway", "open-claw"} {
+ if got := asymptoteobserve.NormalizeHarnessName(spelling); got != "openclaw_gateway" {
+ t.Fatalf("NormalizeHarnessName(%q) = %q, want openclaw_gateway", spelling, got)
+ }
+ }
+}
diff --git a/pkg/asymptoteobserve/provenance.go b/pkg/asymptoteobserve/provenance.go
index 6231ded6..19671257 100644
--- a/pkg/asymptoteobserve/provenance.go
+++ b/pkg/asymptoteobserve/provenance.go
@@ -99,7 +99,7 @@ func CollectionMethodForPlatform(platform string) string {
switch strings.ToLower(strings.TrimSpace(platform)) {
case "":
return ""
- case "opencode", "cline", "pi", "omp", "prime":
+ case "opencode", "cline", "pi", "omp", "openclaw", "prime":
return CollectionMethodPlugin
default:
return CollectionMethodHook