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
package cmd
import (
"context"
"fmt"
"os"
"path/filepath"
"regexp"
"strconv"
"strings"
"sync"
"time"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/cloudshuttle"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/git"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
func emitHookEvent(logger *logging.Logger, action, category, severity, message string, input map[string]interface{}, fields map[string]interface{}) {
emitHookEventWithFidelity(logger, action, category, severity, message, asymptoteobserve.FidelityObserved, input, fields)
}
// emitInferredHookEvent is emitHookEvent for an action Beacon derived rather than read.
//
// The case that requires it: several runtimes expose a pre-tool notification but no approval hook,
// and Beacon has long turned the former into an approval.allowed event carrying
// approval.required=true. Nothing was gated -- a tool call was observed -- so recording that as a
// reported approval overstates what is known, and it is indistinguishable from Claude Code's
// PermissionRequest, which is a real operator decision. Marking it inferred leaves the action
// where downstream rules expect it while letting anything that counts approvals exclude the ones
// Beacon made up.
func emitInferredHookEvent(logger *logging.Logger, action, category, severity, message string, input map[string]interface{}, fields map[string]interface{}) {
emitHookEventWithFidelity(logger, action, category, severity, message, asymptoteobserve.FidelityInferred, input, fields)
}
// rawPayloadKeys names the runtimes whose whole hook payload is kept under `raw.<key>`, and the
// key each one uses.
//
// These runtimes carry real signal with no endpoint-schema field of its own -- Qwen's
// `permission_mode` on every tool event, its `source` on SessionStart and the `context_usage` /
// `context_limit` / `input_tokens` trio on Stop; Muse Code's `permission_mode` and SessionStart
// `source`. Keeping the payload preserves them without inventing schema fields for one runtime. It
// is the whole event's own path through SanitizeMap, so raw is
// secret-redacted and string-limited like every other field, and it is the first thing dropped when
// an event exceeds the 64 KiB ceiling.
//
// A table rather than one `if` per runtime. The branches were identical apart from the key, so each
// new runtime copied the same three lines and the only thing distinguishing them was a string --
// which is data, and belongs in one. The Cascade entry is why this is keyed on the --platform value
// rather than derived from it: `devin-desktop` writes under `cascade`, so the key is not always the
// flag.
var rawPayloadKeys = map[string]string{
"grok": "grok",
"hermes": "hermes",
"qwen": "qwen",
"vscode": "vscode",
"muse": "muse",
"devin-desktop": "cascade",
// DeepSeek Harness is here for one tool and the shape of its whole tool surface. `run_code`
// executes a TypeScript program against the other tools, and the program itself -- the `code`
// argument -- is the entire content of that call; the endpoint schema has no field for it,
// because it is neither a shell command line nor a file. Without the payload, the highest-
// privilege tool dsh ships would be recorded as a bare tool.invoked carrying only its name.
//
// It is not only run_code. Non-MCP tool arguments reach no schema field at all on any runtime
// -- gen_ai.tool.call.arguments is written for MCP calls only -- so on dsh this is also where a
// glob or grep pattern, a terminal_send `submit` flag and a job id survive. `source` on
// SessionStart is the ordinary rawPayloadKeys case on top of that.
//
// The cost is stated rather than hidden: on a `write` the payload repeats the file content the
// diff already carries. raw goes through SanitizeMap like every other field and is the first
// thing dropped when an event exceeds the 64 KiB ceiling, so the duplication is bounded and the
// diff is what survives. Qwen Code and Muse Code already pay the same cost for the same reason.
"dsh": "dsh",
// Kimi Code carries several things with no endpoint-schema field, and two of them are the
// reason this entry exists rather than being a habit.
//
// The first is the approval pair. A PermissionResult's `scope` says whether the operator
// approved this one call or every call like it for the rest of the session, and `feedback` is
// the reason they typed when they refused. The approval block has a `decision` and a `reason`
// and nowhere to put a standing grant, so without the payload the difference between "yes,
// once" and "yes, and stop asking" is lost -- which is the single most load-bearing fact about
// any approval row, the same one the Pi family records as approval_mode.
//
// The second is tool arguments. gen_ai.tool.call.arguments is written for MCP calls only, so
// on this runtime the payload is also where a Grep pattern, a Glob pattern, an Agent's prompt,
// a CronCreate schedule and a Bash `run_in_background` flag survive. `session_title`,
// `client_type`, `is_steer` on a prompt, `source` and `profile` on SessionStart and `reason`
// on SessionEnd are the ordinary rawPayloadKeys cases on top of that.
//
// The cost is stated rather than hidden: on a Write the payload repeats the file content the
// diff already carries. raw goes through SanitizeMap like every other field and is the first
// thing dropped when an event exceeds the 64 KiB ceiling, so the duplication is bounded and
// the diff is what survives. Qwen Code, Muse Code and DeepSeek Harness already pay the same
// cost for the same reason.
"kimi": "kimi",
}
func rawPayloadKey(platform string) string {
return rawPayloadKeys[platform]
}
// applyContextSize promotes a runtime's reported context size into gen_ai.context.
//
// Separate from usage on purpose. gen_ai.usage is additive and every report sums it; context size
// is a level at one moment, and Qwen Code -- the first runtime to report one -- is exactly where
// summing goes wrong: its Stop payload's input_tokens is the prompt for that turn, which already
// contains every prior turn, so a session's total would grow with the square of its length. Read as
// context occupancy the same number is exact and worth having.
//
// Both halves are required before either is written. "input_tokens" is Qwen's name for the context
// measure and also the ecosystem's name for an additive usage count, so a reported limit beside it
// is what says which one this payload means. Promoting a bare input_tokens here would reclassify
// other runtimes' spend as context.
//
// Read from the shared alias lists rather than a per-runtime branch, the way tool call ids are, so
// a second runtime reporting the same thing needs a spelling added and nothing else.
func applyContextSize(fields, input map[string]interface{}) {
if fields == nil || input == nil {
return
}
limit, ok := firstToolIntAcross([]map[string]interface{}{input}, asymptoteobserve.ContextLimitKeys...)
if !ok || limit <= 0 {
return
}
used, ok := firstToolIntAcross([]map[string]interface{}{input}, asymptoteobserve.ContextUsedKeys...)
if !ok || used <= 0 {
return
}
fields["gen_ai"] = mergeNested(fields["gen_ai"], map[string]interface{}{
"context": map[string]interface{}{"used_tokens": used, "limit_tokens": limit},
})
}
func emitHookEventWithFidelity(logger *logging.Logger, action, category, severity, message, fidelity string, input map[string]interface{}, fields map[string]interface{}) {
if fields == nil {
fields = map[string]interface{}{}
}
seedCursorCloudRunID(input)
if key := rawPayloadKey(platformFlag); key != "" {
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{key: input})
}
applyToolCallID(fields, input)
applyPromptID(fields, input)
applyContextSize(fields, input)
if model := getFirstStr(input, "model"); model != "" {
fields["model"] = model
}
cwd := resolveCwd(input, platformFlag)
if cwd != "" {
fields["session"] = mergeNested(fields["session"], map[string]interface{}{"working_directory": cwd})
fields["repository"] = cwd
}
if branch := resolveBranch(input, cwd); branch != "" {
fields["branch"] = branch
}
if err := logger.EndpointEventWithFidelity(action, category, severity, message, fidelity, fields); err != nil {
logger.Error("Failed to write endpoint event", "error", err.Error(), "action", action)
}
}
// normalizedEvent is one endpoint event a mapper has decided to write, before it reaches the
// logger.
//
// Mappers that receive a whole runtime's event stream through a single command return a slice of
// these rather than writing as they go, because one payload routinely becomes several events -- a
// tool result plus the file mutations it caused -- and because returning them makes the mapping
// itself testable without a log file. Shared rather than per-runtime: the five parts are the
// logger's own arguments, so a per-runtime copy would be the same struct under another name.
type normalizedEvent struct {
action string
category string
severity string
message string
fields map[string]interface{}
}
// resolveBranch prefers a runtime-provided branch and otherwise derives the
// checked-out branch from the event's working directory. Runtime-provided
// values pass through even when local git metadata enrichment is disabled.
func resolveBranch(input map[string]interface{}, cwd string) string {
if branch := getFirstStr(input, "branch", "git_branch"); branch != "" {
return branch
}
if cwd == "" || gitMetadataDisabled() {
return ""
}
return git.CurrentBranch(cwd)
}
// applyWorkspaceFields fills workspace context (session.working_directory,
// repository, branch) for emitters that write endpoint events without going
// through emitHookEvent, mirroring emitHookEvent's enrichment. fallbackDir
// seeds branch resolution when the payload carries no working directory,
// such as a file edit identified only by its path; it is never used for
// repository, which must reflect the actual workspace path.
func applyWorkspaceFields(fields map[string]interface{}, input map[string]interface{}, fallbackDir string) {
applyWorkspaceFieldsForPlatform(fields, input, fallbackDir, platformFlag)
}
// applyWorkspaceFieldsForPlatform is applyWorkspaceFields for a named runtime. See
// sessionFieldsForPlatform for why a single-runtime mapper should name its runtime.
func applyWorkspaceFieldsForPlatform(fields map[string]interface{}, input map[string]interface{}, fallbackDir, platform string) {
cwd := resolveCwd(input, platform)
if cwd != "" {
fields["session"] = mergeNested(fields["session"], map[string]interface{}{"working_directory": cwd})
if existing, ok := fields["repository"]; !ok || existing == "" {
fields["repository"] = cwd
}
}
if existing, ok := fields["branch"]; ok && existing != "" {
return
}
branchDir := cwd
if branchDir == "" {
branchDir = fallbackDir
}
if branch := resolveBranch(input, branchDir); branch != "" {
fields["branch"] = branch
}
}
// gitMetadataDisabled accepts 1/true/yes, matching other Beacon disable flags.
func gitMetadataDisabled() bool {
switch strings.ToLower(strings.TrimSpace(os.Getenv("BEACON_DISABLE_GIT_METADATA"))) {
case "1", "true", "yes":
return true
}
return false
}
func uploadCloudTelemetry(logger *logging.Logger, force bool) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := cloudshuttle.MaybeUpload(ctx, force); err != nil {
logger.Warn("Cloud telemetry upload failed", "error", err.Error(), "force", force)
}
}
func isCursorCloudMode() bool {
return strings.TrimSpace(os.Getenv("BEACON_ORIGIN")) == "cloud" &&
strings.TrimSpace(os.Getenv("BEACON_RUN_PROVIDER")) == "cursor_cloud"
}
func seedCursorCloudRunID(input map[string]interface{}) {
if platformFlag != "cursor" || !isCursorCloudMode() || strings.TrimSpace(os.Getenv("BEACON_RUN_ID")) != "" {
return
}
if runID := getFirstStr(input, "conversation_id", "parent_conversation_id"); runID != "" {
_ = os.Setenv("BEACON_RUN_ID", runID)
}
}
func maybeUploadCursorCloudTelemetry(logger *logging.Logger) {
if platformFlag != "cursor" {
return
}
if !isCursorCloudMode() {
return
}
uploadCloudTelemetry(logger, true)
}
func sessionFields(sessionID string, input map[string]interface{}) map[string]interface{} {
return sessionFieldsForPlatform(sessionID, input, platformFlag)
}
// sessionFieldsForPlatform builds the same fields for a named runtime rather than for whichever
// --platform the binary happened to be invoked with.
//
// A mapper that only ever handles one runtime's payloads should say which one. Reading the flag
// instead made the workspace resolution depend on the invocation: a Cline payload processed without
// --platform cline fell through to the default reader, found none of Cline's keys, and produced an
// event with no working directory, no repository and no branch -- while the file path in the same
// event resolved correctly, because that path already asked for the Cline shape by name.
func sessionFieldsForPlatform(sessionID string, input map[string]interface{}, platform string) map[string]interface{} {
fields := map[string]interface{}{}
session := map[string]interface{}{}
if sessionID != "" {
session["id"] = sessionID
}
if cwd := resolveCwd(input, platform); cwd != "" {
session["working_directory"] = cwd
fields["repository"] = cwd
}
if len(session) > 0 {
fields["session"] = session
}
return fields
}
func toolFields(toolName string, toolInput map[string]interface{}) map[string]interface{} {
return toolFieldsWithResponse(toolName, toolInput, nil)
}
func toolFieldsWithResponse(toolName string, toolInput, toolResponse map[string]interface{}) map[string]interface{} {
fields := map[string]interface{}{}
if toolName != "" {
fields["tool"] = map[string]interface{}{"name": toolName}
}
// normalizeToolString keeps the quote trimming every hook string field gets.
command := normalizeToolString(asymptoteobserve.ToolCommandLine(toolName, toolInput))
if command != "" {
// OpenHands file editors multiplex operations onto one tool name via a `command` argument
// that names the editor operation (view, str_replace, create), not a shell command.
// Promoting it into command.command would store an editor operation as shell execution and
// let the policy seam upgrade tool.invoked to command.executed.
// Kiro's write tool has the same shape for the same reason: its `command` argument may name
// an editor operation (create, str_replace, insert) rather than a shell command, because
// the tool descends from Amazon Q Developer CLI's multiplexed fs_write. Guarded on the
// tool name so `shell`/`execute_bash`, where `command` really is the command line, keeps
// the field that makes a shell event worth recording.
// DeepSeek Harness's `str_replace_editor` is the third instance of the same shape, and the
// one that publishes it: its schema documents `command` as an enum of view/create/
// str_replace/insert over a `path`.
if !(platformFlag == openHandsPlatform && openHandsFileEditorTools[strings.ToLower(strings.TrimSpace(toolName))]) &&
!(platformFlag == kiroPlatform && kiroWriteCommandIsEditorOperation(toolName, toolInput)) &&
!(platformFlag == dshPlatform && dshEditorCommandIsOperation(toolName, toolInput)) {
fields["command"] = map[string]interface{}{"command": command}
fields["tool"] = mergeNested(fields["tool"], map[string]interface{}{"name": toolName, "command": command})
}
}
// `absolute_path` and `notebook_path` are the snake_case siblings of `AbsolutePath` already in
// this list: the first is Gemini CLI's (and so early Qwen Code's) `read_file` parameter, the
// second is what `notebook_edit` names its target on both Qwen and Claude. Both are unambiguous
// file paths, so reading them costs nothing and their absence costs a `file` field.
// `dir_path` is the snake_case sibling of `DirectoryPath` already in this list: it is what
// OpenHands' list_directory names its target. Unambiguous, so reading it costs nothing and its
// absence costs a `file` field on every directory listing.
path := firstToolString(toolInput, "file_path", "filePath", "path", "Path", "AbsolutePath", "absolute_path", "notebook_path", "DirectoryPath", "dir_path", "SearchPath", "searchPath")
// Kiro's read tool -- its most frequent one -- puts the path inside an `operations` array
// rather than at the top level of tool_input, so every key above misses it and a read event
// would carry no file at all. Asked after the shared list rather than before it, because a
// payload that does carry a top-level path has said something more direct.
if path == "" && platformFlag == kiroPlatform {
path = kiroToolPath(toolInput)
}
// goose's read_image names its target `source`, not `path`, so every key above misses it and
// the call would record no file at all. Asked after the shared list for the Kiro reason -- a
// payload carrying a top-level path has said something more direct -- and `source` is
// deliberately not added to that list: it is an ordinary key other runtimes use for other
// things, and gooseReadImageSource also has to reject the http(s) URLs this one argument
// legitimately carries.
if path == "" && platformFlag == goosePlatform {
path = gooseToolPath(toolName, toolInput)
}
// Antigravity names a file tool's target TargetFile (its write and replace tools) or
// SearchDirectory (find_by_name), neither in the shared list above. Asked after it for the Kiro
// reason, from the vocabulary the session-store collector reads too.
if path == "" && platformFlag == "antigravity" {
path = asymptoteobserve.AntigravityToolPath(toolInput)
}
if path != "" {
fields["file"] = map[string]interface{}{
"path": path,
"operation": fileOperation(toolName, toolInput),
"language": strings.TrimPrefix(filepath.Ext(path), "."),
}
fields["tool"] = mergeNested(fields["tool"], map[string]interface{}{"path": path})
}
if mcp := mcpToolFields(toolName, toolInput, toolResponse); len(mcp) > 0 {
fields["mcp"] = mcp
tool := firstNestedString(mcp, "tool")
fields["gen_ai"] = genAIToolFields(tool, toolInput, toolResponse)
for key, value := range mcpStandardFields(toolInput, toolResponse) {
fields[key] = value
}
}
// No call ID is read here, deliberately: this function sees only the tool's
// arguments and its output, and neither is where identity lives. Callers
// promote it from the payload envelope instead -- emitHookEvent for every
// hook mapper, and the Cline, OpenCode and file-edit emitters by name.
//
// Scanning the arguments was worse than merely useless. tool_input is what
// the model chose to pass, so a tool that legitimately takes an argument
// called call_id -- an MCP wrapper over an API whose objects have call IDs,
// say -- had that value written as gen_ai.tool.call.id, and because an ID
// already present is treated as authoritative it then blocked the runtime's
// real tool_use_id. One wrong join key, and the right one shut out.
// Reported by Cursor Bugbot.
return fields
}
// applyIngestedToolResult records the result of a tool that brought outside content into the
// agent's context -- a file read, a web fetch -- as gen_ai.tool.call.result, with the retention
// marker that describes it.
//
// toolFieldsWithResponse writes gen_ai.tool.call.result for MCP calls only, so before this the live
// hook path dropped the response of every other tool (#743). A Read or WebFetch was recorded with
// its path and nothing it returned, and the threat-rules field derived from the result,
// gen_ai.tool.call.result_text, was empty on every event a live install wrote: indirect prompt
// injection was visible to `beacon scan` after `claude sync` and invisible in real time.
//
// The scope is the shared one in pkg/asymptoteobserve, the same predicate the rules engine reads,
// so a capture path cannot drop a result the engine would match or record one it ignores. It is
// deliberately not every tool: a shell command's output already has command.output, a write echoes
// what the agent itself produced, and recording either again would only grow the log.
//
// Called once the action is known, because the action is half of the scope. An MCP call already
// carries its result from toolFieldsWithResponse and is left exactly as it was. The value goes out
// through the logger's sanitizer like every other field -- secret redaction, the per-string limit
// and the 64 KiB event ceiling, which drops the result and marks content not included -- and the
// marker is computed over the text before that, so its hash and byte count describe what the tool
// returned, not the stored copy.
func applyIngestedToolResult(fields map[string]interface{}, action, toolName string, toolResponse map[string]interface{}) {
if len(toolResponse) == 0 {
return
}
// The target is read from the event's own tool.path, the field the engine reads it from.
target, _ := mutableChild(fields["tool"])["path"].(string)
if !asymptoteobserve.IngestedContentAction(action) && !asymptoteobserve.IngestedContentToolName(toolName) &&
!asymptoteobserve.IngestedContentTarget(target) {
return
}
genAI := mutableChild(fields["gen_ai"])
tool := mutableChild(genAI["tool"])
call := mutableChild(tool["call"])
if _, exists := call["result"]; exists {
return
}
call["result"] = toolResponse
tool["call"] = call
if _, exists := tool["name"]; !exists && toolName != "" {
tool["name"] = toolName
}
genAI["tool"] = tool
if _, exists := genAI["operation"]; !exists {
genAI["operation"] = map[string]interface{}{"name": "execute_tool"}
}
fields["gen_ai"] = genAI
// The marker describes this result only when nothing more specific was already retained.
if _, exists := fields["content"]; !exists {
if marker := retainedContentFields(asymptoteobserve.ToolResultPlainText(toolResponse)); marker != nil {
fields["content"] = marker
}
}
}
// claudeBashExitLine is the first line Claude Code writes into a failed Bash call's `error` when
// the command ran and exited. Its absence means the shell itself could not be started.
var claudeBashExitLine = sync.OnceValue(func() *regexp.Regexp { return regexp.MustCompile(`^Exit code (-?\d+)$`) })
// applyClaudeBashResult maps the result of Claude Code's Bash tool onto the command field, and
// reports whether the payload is a failure of a command that ran and exited.
//
// The two outcomes arrive in different shapes. A success (`PostToolUse`) carries `tool_response`
// with `stdout` and `stderr` as separate strings and no exit code. They are stored stdout first,
// then stderr, so the order in which the command interleaved them is lost. A failure
// (`PostToolUseFailure`) carries no tool response, only a top-level `error`: a first line
// `Exit code N`, then the output with both streams interleaved as Claude saw it. That line is
// the only exit code Claude reports, so it is parsed rather than synthesized. An `error` without
// it is a shell that never started; that is a message, not command output, and is not recorded.
//
// Claude reports an interrupted command as a success with `interrupted` set, or as a failure with
// `is_interrupt`, and its output is partial either way, so that is recorded beside it.
func applyClaudeBashResult(fields, input map[string]interface{}, toolName string, toolResponse map[string]interface{}) bool {
if !strings.EqualFold(strings.TrimSpace(toolName), "bash") {
return false
}
var output string
var exitCode int
exited := false
if errText := getFirstStr(input, "error"); errText != "" {
firstLine, rest, _ := strings.Cut(errText, "\n")
match := claudeBashExitLine().FindStringSubmatch(strings.TrimSpace(firstLine))
if match == nil {
return false
}
code, err := strconv.Atoi(match[1])
if err != nil {
return false
}
output, exitCode, exited = rest, code, true
} else if toolResponse != nil {
output = getFirstStr(toolResponse, "stdout")
if stderr := getFirstStr(toolResponse, "stderr"); stderr != "" {
if output != "" && !strings.HasSuffix(output, "\n") {
output += "\n"
}
output += stderr
}
}
command := mutableChild(fields["command"])
if exited {
command["exit_code"] = exitCode
}
if output != "" {
command["output"] = output
if _, exists := fields["content"]; !exists {
fields["content"] = retainedContentFields(output)
}
}
if len(command) > 0 {
fields["command"] = command
}
if interrupted, _ := toolResponse["interrupted"].(bool); interrupted || input["is_interrupt"] == true {
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"claude_interrupted": true})
}
return exited
}
// toolCallIDFromEnvelope reads the runtime's own identifier for one tool
// invocation out of a hook payload's top level.
//
// The envelope only. The runtime writes this field itself, whereas tool_input is
// model-authored and tool_response is the tool's own output -- neither is a
// statement by the runtime about which call this is, and reading identity out of
// either lets a tool argument masquerade as the join key.
//
// The alias list is shared with the OTLP path so both capture paths promote the
// same value to the same field, which is what lets duplicate suppression
// recognise the two reports of one action as one action.
func toolCallIDFromEnvelope(input map[string]interface{}) string {
return firstToolStringAcross([]map[string]interface{}{input}, asymptoteobserve.ToolCallIDKeys...)
}
// applyToolCallID promotes a call ID carried at the top level of a hook payload,
// which is where Claude Code puts tool_use_id -- outside tool_input, so no
// amount of reading the tool arguments would ever have found it.
//
// The envelope is the only source of a call ID anywhere in the hook path, so
// this is a plain promotion rather than a contest between sources. Tool
// arguments were once read too, which let a tool parameter that happened to be
// called call_id become the join key and shut out the runtime's real
// tool_use_id; that read is gone rather than merely outranked, because a tool
// parameter is not weaker evidence of identity, it is not evidence at all.
//
// Only an event that already describes a tool action takes one. A session
// lifecycle payload that happens to echo an ID is not a tool call, and giving it
// the join key of one would join it to work it did not do.
func applyToolCallID(fields, input map[string]interface{}) {
if fields == nil || !describesToolAction(fields) {
return
}
if callID := toolCallIDFromEnvelope(input); callID != "" {
setToolCallID(fields, callID)
}
}
func describesToolAction(fields map[string]interface{}) bool {
for _, key := range []string{"tool", "command", "file", "mcp"} {
if value, ok := fields[key].(map[string]interface{}); ok && len(value) > 0 {
return true
}
}
return false
}
// setToolCallID writes gen_ai.tool.call.id, creating the objects on the way down
// and leaving whatever is already in them alone. mergeNested cannot do this: it
// is a one-level merge, so writing the call through it would replace the whole
// tool object and drop the name and arguments an MCP event puts there.
func setToolCallID(fields map[string]interface{}, callID string) {
genAI := mutableChild(fields["gen_ai"])
tool := mutableChild(genAI["tool"])
call := mutableChild(tool["call"])
call["id"] = callID
tool["call"] = call
genAI["tool"] = tool
fields["gen_ai"] = genAI
}
func mutableChild(value interface{}) map[string]interface{} {
if existing, ok := value.(map[string]interface{}); ok && existing != nil {
return existing
}
return map[string]interface{}{}
}
func mcpToolFields(toolName string, toolInput, toolResponse map[string]interface{}) map[string]interface{} {
maps := []map[string]interface{}{toolInput, toolResponse}
mcpServer := firstToolStringAcross(maps, "mcp_server", "mcp_server_name", "mcp.server", "mcp.server.name")
mcpTool := firstToolStringAcross(maps, "mcp_tool", "mcp_tool_name", "mcp.tool", "mcp.tool.name")
mcpMethod := firstToolStringAcross(maps, "mcp.method.name", "mcp_method_name", "mcp_method")
mcpProtocol := firstToolStringAcross(maps, "mcp.protocol.version", "mcp_protocol_version")
mcpResource := firstToolStringAcross(maps, "mcp.resource.uri", "mcp_resource_uri")
mcpSession := firstToolStringAcross(maps, "mcp.session.id", "mcp_session_id")
hasCascadeServerToolPair := isCascadePlatform(platformFlag) && firstToolStringAcross(maps, "server_name") != "" && firstToolStringAcross(maps, "tool_name") != ""
// OpenHands calls an MCP tool by whatever name its server gave it, with no prefix and no
// mcp_* argument, so every signal above misses it and the call would be recorded as an
// ordinary tool.invoked. Its result says so instead: tool observations are pydantic dumps
// carrying a `kind` discriminator, and an MCP call returns MCPToolObservation. Keyed on the
// platform like the Cascade pair above, because `kind` is a key other runtimes use for other
// things.
hasOpenHandsMCPObservation := platformFlag == openHandsPlatform && openHandsIsMCPToolCall(toolResponse)
// Kiro says so in the tool name, which is the easy case -- but it says it with a prefix no
// generic signal above recognizes: `@postgres/query` contains no "mcp", carries no mcp_*
// argument, and comes back with whatever the server returned. Keyed on the platform because a
// leading "@" is Kiro's convention and not a general one.
hasKiroMCPToolName := platformFlag == kiroPlatform && kiroIsMCPToolName(toolName)
// goose says so in the tool name too, but only by exclusion. It calls an MCP tool
// `<extension>__<tool>` with no "mcp" anywhere, no mcp_* argument, and -- since goose populates
// no tool output at all -- no result to inspect. What identifies the call is that the prefix is
// not one of goose's built-in extensions. Keyed on the platform because `a__b` is goose's
// convention and not a general one.
hasGooseMCPToolName := platformFlag == goosePlatform && gooseIsMCPToolName(toolName)
server := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "server", "server_name", "mcp_server", "mcp_server_name", "mcp.server", "mcp.server.name")
tool := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "tool", "tool_name", "function_name", "mcp_tool", "mcp_tool_name", "mcp.tool", "mcp.tool.name", "gen_ai.tool.name")
genericToolName := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "name")
method := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "mcp.method.name", "mcp_method_name", "mcp_method", "method_name", "method")
protocol := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "mcp.protocol.version", "mcp_protocol_version", "protocol_version")
resource := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "mcp.resource.uri", "mcp_resource_uri", "resource_uri", "uri")
session := firstToolStringAcross([]map[string]interface{}{toolInput, toolResponse}, "mcp.session.id", "mcp_session_id")
if hasKiroMCPToolName {
// Read before the shared derivation rather than after, because deriveMCPServerTool
// recognizes only the `mcp:` and `mcp__` spellings and would leave both halves empty for
// an `@server/tool` name -- recording an MCP call whose server and tool are blank.
if server == "" || tool == "" {
derivedServer, derivedTool, _ := kiroMCPServerTool(toolName)
if server == "" {
server = derivedServer
}
if tool == "" {
tool = derivedTool
}
}
}
if hasGooseMCPToolName {
// Same placement and the same reason as Kiro just above: the shared derivation matches
// `mcp__` and `mcp:` and would find neither half of `github__create_issue`, recording an
// MCP call whose server and tool are blank.
if server == "" || tool == "" {
derivedServer, derivedTool := gooseMCPServerTool(toolName)
if server == "" {
server = derivedServer
}
if tool == "" {
tool = derivedTool
}
}
}
if derivedServer, derivedTool := deriveMCPServerTool(toolName); derivedServer != "" || derivedTool != "" {
if server == "" {
server = derivedServer
}
if tool == "" {
tool = derivedTool
}
}
isMCP := mcpServer != "" || mcpTool != "" || mcpMethod != "" || mcpProtocol != "" || mcpResource != "" || mcpSession != "" || hasCascadeServerToolPair || hasOpenHandsMCPObservation || hasKiroMCPToolName || hasGooseMCPToolName || strings.Contains(strings.ToLower(toolName), "mcp")
if !isMCP {
return nil
}
if tool == "" {
tool = genericToolName
}
if method == "" {
method = "tools/call"
}
out := map[string]interface{}{"server": server, "tool": tool}
if method != "" {
out["method"] = map[string]interface{}{"name": method}
}
if protocol != "" {
out["protocol"] = map[string]interface{}{"version": protocol}
}
if resource != "" {
out["resource"] = map[string]interface{}{"uri": resource}
}
if session != "" {
out["session"] = map[string]interface{}{"id": session}
}
return out
}
func deriveMCPServerTool(toolName string) (string, string) {
trimmed := strings.TrimSpace(toolName)
lower := strings.ToLower(trimmed)
if strings.HasPrefix(lower, "mcp:") {
return "", strings.TrimSpace(trimmed[len("MCP:"):])
}
if strings.HasPrefix(lower, "mcp__") {
parts := strings.Split(trimmed, "__")
if len(parts) >= 3 {
return parts[1], strings.Join(parts[2:], "__")
}
}
return "", ""
}
func genAIToolFields(tool string, toolInput, toolResponse map[string]interface{}) map[string]interface{} {
genAI := map[string]interface{}{
"operation": map[string]interface{}{"name": "execute_tool"},
}
toolInfo := map[string]interface{}{}
if tool != "" {
toolInfo["name"] = tool
}
call := map[string]interface{}{}
if len(toolInput) > 0 {
call["arguments"] = toolInput
}
if len(toolResponse) > 0 {
call["result"] = toolResponse
}
if len(call) > 0 {
toolInfo["call"] = call
}
if len(toolInfo) > 0 {
genAI["tool"] = toolInfo
}
return genAI
}
func mcpStandardFields(toolInput, toolResponse map[string]interface{}) map[string]interface{} {
fields := map[string]interface{}{}
maps := []map[string]interface{}{toolInput, toolResponse}
if errorType := mcpErrorType(toolResponse); errorType != "" {
fields["error"] = map[string]interface{}{"type": errorType}
} else if errorType := firstToolStringAcross(maps, "error.type", "error_type"); errorType != "" {
fields["error"] = map[string]interface{}{"type": errorType}
}
jsonrpc := map[string]interface{}{}
if id := firstToolStringAcross(maps, "jsonrpc.request.id", "jsonrpc_request_id", "request_id"); id != "" {
jsonrpc["request"] = map[string]interface{}{"id": id}
}
if version := firstToolStringAcross(maps, "jsonrpc.protocol.version", "jsonrpc_protocol_version", "jsonrpc"); version != "" {
jsonrpc["protocol"] = map[string]interface{}{"version": version}
}
if len(jsonrpc) > 0 {
fields["jsonrpc"] = jsonrpc
}
network := map[string]interface{}{}
networkProtocol := map[string]interface{}{}
if name := firstToolStringAcross(maps, "network.protocol.name", "network_protocol_name"); name != "" {
networkProtocol["name"] = strings.ToLower(name)
}
if version := firstToolStringAcross(maps, "network.protocol.version", "network_protocol_version"); version != "" {
networkProtocol["version"] = version
}
if len(networkProtocol) > 0 {
network["protocol"] = networkProtocol
}
if transport := firstToolStringAcross(maps, "network.transport", "network_transport", "transport"); transport != "" {
network["transport"] = strings.ToLower(transport)
}
if len(network) > 0 {
fields["network"] = network
}
if status := firstToolStringAcross(maps, "rpc.response.status_code", "rpc_response_status_code", "status_code"); status != "" {
fields["rpc"] = map[string]interface{}{"response": map[string]interface{}{"status_code": status}}
}
server := map[string]interface{}{}
if address := firstToolStringAcross(maps, "server.address", "server_address", "serverAddress", "address"); address != "" {
server["address"] = address
}
if port, ok := firstToolIntAcross(maps, "server.port", "server_port", "serverPort", "port"); ok {
server["port"] = port
}
if len(server) > 0 {
fields["server"] = server
}
return fields
}
func mcpErrorType(toolResponse map[string]interface{}) string {
if toolResponse == nil {
return ""
}
if errorType := firstToolString(toolResponse, "error.type", "error_type"); errorType != "" {
return errorType
}
if isError := firstToolString(toolResponse, "isError", "is_error"); strings.EqualFold(isError, "true") {
return "tool_error"
}
if mcpHasErrorValue(toolResponse, "error") {
return "tool_error"
}
return ""
}
func mcpHasErrorValue(toolResponse map[string]interface{}, key string) bool {
value, ok := toolResponse[key]
if !ok || value == nil {
return false
}
if boolValue, ok := value.(bool); ok {
return boolValue
}
return normalizeToolString(value) != ""
}
func diffFields(filePath, diffStr string) map[string]interface{} {
if filePath == "" {
return nil
}
file := map[string]interface{}{
"path": filePath,
"operation": "modify",
"language": strings.TrimPrefix(filepath.Ext(filePath), "."),
}
fields := map[string]interface{}{"file": file}
if diffStr != "" {
// diff_hash (of the whole redacted diff) and diff_bytes (its original size) describe the diff; the marker
// adds what they cannot say -- whether the stored copy is the whole diff,
// and whether redaction rewrote part of it.
fields["content"] = retainedDiffFields(file, diffStr)
}
return fields
}
func mergeNested(existing interface{}, values map[string]interface{}) map[string]interface{} {
out := map[string]interface{}{}
if current, ok := existing.(map[string]interface{}); ok {
for key, value := range current {
out[key] = value
}
}
for key, value := range values {
if value != "" && value != nil {
out[key] = value
}
}
return out
}
func firstToolString(input map[string]interface{}, keys ...string) string {
for _, key := range keys {
if value, ok := input[key]; ok {
if str := normalizeToolString(value); str != "" {
return str
}
}
}
return ""
}
func firstToolStringAcross(inputs []map[string]interface{}, keys ...string) string {
for _, input := range inputs {
if input == nil {
continue
}
if value := firstToolString(input, keys...); value != "" {
return value
}
}
return ""
}
func firstToolIntAcross(inputs []map[string]interface{}, keys ...string) (int, bool) {
for _, input := range inputs {
if input == nil {
continue
}
for _, key := range keys {
value, ok := input[key]
if !ok {
continue
}
switch typed := value.(type) {
case int:
return typed, true
case int64:
return int(typed), true
case float64:
return int(typed), true
case string:
parsed, err := strconv.Atoi(strings.TrimSpace(typed))
if err == nil {
return parsed, true
}
}
}
}
return 0, false
}
func firstNestedString(input map[string]interface{}, key string) string {
if input == nil {
return ""
}
value, ok := input[key]
if !ok {
return ""
}
return normalizeToolString(value)
}
// normalizeToolString returns a tool argument as text. A value wrapped whole in one pair of double
// quotes ("npm test", "C:\tools\run.exe") loses that pair; quotes that belong to the value, as in
// echo "hi", stay. Nothing is unescaped: backslashes are what the shell or the path holds.
func normalizeToolString(value interface{}) string {
str := strings.TrimSpace(fmt.Sprint(value))
if str == "" || str == "<nil>" {
return ""
}
if len(str) >= 2 && str[0] == '"' && str[len(str)-1] == '"' && !strings.Contains(str[1:len(str)-1], `"`) {
return strings.TrimSpace(str[1 : len(str)-1])
}
return str
}
// fileOperation classifies what a tool did to the file it named.
//
// toolInput is part of the question rather than extra context: a runtime is free to multiplex
// several operations onto one tool name and select between them with an argument, and OpenHands
// does exactly that -- `file_editor` is a read with command="view" and a write with
// command="str_replace". A classifier that only sees the name is wrong on one of those two
// whichever way it answers, so the arguments have to be in reach. Callers with nothing to pass
// give nil.
func fileOperation(toolName string, toolInput map[string]interface{}) string {
if platformFlag == "qwen" {
if operation := qwenFileOperation(toolName); operation != "" {
return operation
}
}
if platformFlag == openHandsPlatform {
if operation := openHandsFileOperation(toolName, toolInput, nil); operation != "" {
return operation
}
}
if platformFlag == kiroPlatform {
if operation := kiroFileOperation(toolName, toolInput, nil); operation != "" {
return operation
}
}
if platformFlag == goosePlatform {
if operation := gooseFileOperation(toolName, toolInput); operation != "" {
return operation
}
}
// DeepSeek Harness needs the arguments for the reason this function takes them at all: its
// `str_replace_editor` is one name over four operations, one of which is a read.
if platformFlag == dshPlatform {
if operation := dshFileOperation(toolName, toolInput); operation != "" {
return operation
}
if _, known := dshToolKindFor(toolName); known {
return ""
}
}
// Kimi Code needs the arguments for the reason this function takes them at all: its `Write`
// is a create or a modify depending on a `mode` argument. The known-name short circuit below
// it is what keeps `CronCreate`, `CronList`, `TaskList` and `TodoList` away from the substring
// rules, which would answer "create" and "read" for tools that touch no file.
if platformFlag == kimiPlatform {
if operation := kimiFileOperation(toolName, toolInput); operation != "" {
return operation
}
if _, known := kimiToolKindFor(toolName); known {
return ""
}
}
lower := strings.ToLower(toolName)
switch {
case strings.Contains(lower, "read") || strings.Contains(lower, "view") || strings.Contains(lower, "list") || strings.Contains(lower, "grep") || strings.Contains(lower, "search"):
return "read"
case strings.Contains(lower, "write") || strings.Contains(lower, "create"):
return "create"
case strings.Contains(lower, "edit") || strings.Contains(lower, "patch"):
return "modify"
default:
return ""
}
}
// actionForTool classifies a tool call as an endpoint event action.
//
// toolInput and toolResponse are read for the same reason fileOperation reads the arguments, and
// for one more: on a runtime that does not decorate MCP tool names, the only thing that says a
// call went to an MCP server is the result it came back with. Callers with neither give nil.
func actionForTool(hookEvent, toolName string, toolInput, toolResponse map[string]interface{}) string {
lower := strings.ToLower(toolName)
if platformFlag == openHandsPlatform {
if action := openHandsToolAction(toolName, toolInput, toolResponse); action != "" {
return action
}
}
if platformFlag == kiroPlatform {
if action := kiroToolAction(toolName, toolInput, toolResponse); action != "" {
return action
}
}
if platformFlag == goosePlatform {
// Asked before the failure checks other runtimes do here, and it needs none of its own:
// goose reports a failed call as a different event, and emitPostToolObserved has already
// classified that as tool.failed and returned before reaching this function.
if action := gooseToolAction(toolName, toolInput); action != "" {
return action
}
}
if platformFlag == dshPlatform {
// No failure check of its own, and unlike goose that is not because the failure arrives as
// a different event -- the DeepSeek Harness bridge sends no failure signal at all. See the
// note on parseDshEdit.
if action := dshToolAction(toolName, toolInput); action != "" {
return action
}
}
if platformFlag == kimiPlatform {
// No failure check of its own, and unlike grok and qwen below that is not an omission:
// Kimi Code reports a failure as a different event, and emitPostToolObserved has already
// classified that as tool.failed and returned before reaching this function.
if action := kimiToolAction(toolName, toolInput); action != "" {
return action
}
}
if platformFlag == "grok" {
if hookEvent == "post_tool_use_failure" {
return "tool.failed"
}
switch lower {
case "run_terminal_command":
return "command.executed"
case "read_file":
return "file.read"
case "search_replace", "write_file":
return "file.modified"
}
}
if isDevinLikePlatform(platformFlag) {
switch {
case strings.HasPrefix(lower, "mcp__"):
return "mcp.tool_invoked"
case lower == "exec":
return "command.executed"
case lower == "read":
return "file.read"
case lower == "edit" || lower == "write":
return "file.modified"
}
}
if platformFlag == "qwen" {
// PostToolUseFailure is classified before the tool id, so a failed edit is recorded as a
// failure rather than as a successful file.modified. Same ordering as grok, for the same
// reason: the tool name says what was attempted, not whether it worked.
if hookEvent == "PostToolUseFailure" {
return "tool.failed"
}
if action := qwenToolAction(toolName); action != "" {
return action
}
}
if platformFlag == "antigravity" {
if action := asymptoteobserve.AntigravityToolAction(toolName); action != "" {
return action
}
}
switch {
case strings.Contains(lower, "mcp"):
return "mcp.tool_invoked"
case lower == "bash" || strings.Contains(lower, "shell") || strings.Contains(lower, "terminal") || strings.Contains(lower, "command"):
return "command.executed"
case strings.Contains(lower, "read"):
return "file.read"
case isFileEditTool(platformFlag, toolName) || hookEvent == "afterFileEdit":
return "file.modified"
default:
return "tool.invoked"
}
}