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 (
"bufio"
"encoding/json"
"os"
"path/filepath"
"strings"
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/state"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/policycontract"
)
var preToolCmd = &cobra.Command{
Use: "pre-tool",
Short: "Observe pre-tool events for local endpoint telemetry",
Long: `PreToolUse hook - triggered before a Write tool execution in Cursor.
Records local telemetry for the tool request and allows the runtime to continue.`,
Run: runPreTool,
}
func init() {
rootCmd.AddCommand(preToolCmd)
}
// cursorPreToolResponse is Cursor's answer to an observed pre-tool event. Cursor and goose are the
// only runtimes an observing pre-tool hook answers with an allow, because on both it is the only
// answer that lets a call proceed and neither reads it as a pre-approval; see preToolResponse and
// gooseBlockingEventResponse.
var cursorPreToolResponse = map[string]interface{}{"permission": "allow"}
func runPreTool(cmd *cobra.Command, args []string) {
input, err := readStdinJSON()
if err != nil {
writePreToolResponse()
return
}
sessionID := resolveSessionID(input, platformFlag)
logger := newHookLogger("pre-tool", platformFlag, sessionID)
logger.Debug("Pre-tool observed")
if denial := enforcePolicy(logger, input, sessionID, policycontract.PhasePreTool); denial != nil {
// emit does not return on a runtime that blocks by exit status, so nothing after this line
// runs there -- which is correct: the telemetry for the denial has already been written by
// enforcePolicy, and the observing event below would describe a call that is not going to
// happen.
denial.emit()
return
}
if platformFlag == "cursor" && emitCursorPreHook(logger, input, sessionID) {
maybeUploadCursorCloudTelemetry(logger)
} else if platformFlag == "antigravity" {
emitAntigravityPromptFromTranscript(logger, input, sessionID)
emitPreToolObserved(logger, input, sessionID)
} else if platformFlag == "claude" || platformFlag == "qwen" || isDevinLikePlatform(platformFlag) || platformFlag == "grok" || platformFlag == "hermes" || platformFlag == "vscode" || platformFlag == "muse" || platformFlag == openHandsPlatform || platformFlag == kiroPlatform || platformFlag == goosePlatform || platformFlag == dshPlatform || platformFlag == kimiPlatform {
// Muse Code belongs on the observing side rather than with the runtimes whose pre-tool
// notification gets turned into a synthesized approval, and the reason is that it has a
// real one. Its PermissionRequest event is a separate hook Beacon also subscribes to, so
// deriving an approval.allowed from PreToolUse as well would record two approvals for one
// tool call -- one of them inferred and describing nothing an operator did -- and put an
// invented decision next to a reported one for the same call.
//
// OpenHands is on the same side for the opposite reason: it exposes no approval hook at
// all. PreToolUse is the only pre-tool signal it sends, and it announces a tool call the
// agent is about to make, not a question anybody was asked -- its own confirmation mode is
// not surfaced to hooks. Synthesizing approval.allowed from it would put an operator
// decision in the log that no operator made, which is the call Cline, Pi and fx already
// settled the same way.
//
// Kiro is on that same side, and it is the sharpest case for it: Kiro genuinely does ask
// the operator, through permissions.yaml rules and an interactive trust picker, and it
// exposes none of that to a hook. PreToolUse fires whether the call was pre-approved by a
// rule, waved through by autopilot, or about to stop and wait for a person -- so an
// approval.allowed derived from it would claim a decision was made in the very cases where
// one has not been made yet, on a runtime where real decisions exist and are invisible.
// That is worse than the no-approval-gate runtimes, not better.
//
// goose is on that same side and for the Kiro reason: ToolApprovalOperation runs the
// permission judge, marks calls that need a person as not executable and stops the turn
// for an answer, and none of that reaches a hook -- goose's HookEvent set has no approval
// event at all. PreToolUse fires identically whether the call was pre-approved by
// goose_mode, waved through, or already confirmed by somebody, so an approval.allowed
// derived from it would claim a decision in exactly the cases where none was made.
//
// The reply goose gets is a separate question from this one, and the two answers point
// opposite ways; see preToolResponse.
//
// DeepSeek Harness is on the same side as OpenHands rather than Kiro or goose: its Claude
// Code hook bridge supports seven events and PermissionRequest is not among them, so there
// is no approval decision anywhere on this runtime's hook surface. PreToolUse announces a
// call the agent is about to make. Synthesizing approval.allowed from it would put an
// operator decision in the log that no operator made.
//
// Kimi Code is here for the Muse Code reason -- the strongest form of it. It exposes not
// one approval event but two, a PermissionRequest and a PermissionResult carrying the
// operator's actual answer, and Beacon subscribes to both. Deriving an approval.allowed
// from PreToolUse as well would record two approvals for one tool call, one of them
// invented, and put it next to a reported decision for the same call -- and it would be
// wrong even more often than on Muse, because PreToolUse on Kimi Code fires *before* the
// permission check runs, so at that moment nobody has been asked anything yet.
emitPreToolObserved(logger, input, sessionID)
} else {
emitPreToolDecision(logger, input, sessionID, "approval.allowed", "allow", "Pre-tool observed", asymptoteobserve.FidelityInferred)
}
writePreToolResponse()
}
// writePreToolResponse writes preToolResponse, or nothing at all when the runtime's no-opinion
// answer is silence.
func writePreToolResponse() {
if response := preToolResponse(); response != nil {
outputJSON(response)
}
}
func emitCursorPreHook(logger *logging.Logger, input map[string]interface{}, sessionID string) bool {
switch getFirstStr(input, "hook_event_name", "hookEventName") {
case "beforeShellExecution":
fields := sessionFields(sessionID, input)
command := getFirstStr(input, "command")
fields["command"] = map[string]interface{}{"command": command}
fields["approval"] = map[string]interface{}{
"required": true,
"decision": "allow",
"reason": "Shell execution observed",
}
emitInferredHookEvent(logger, "approval.allowed", "approval", "info", "Shell execution observed", input, fields)
return true
case "beforeReadFile":
fields := sessionFields(sessionID, input)
if filePath := getFirstStr(input, "file_path", "filePath", "path"); filePath != "" {
fields["file"] = map[string]interface{}{
"path": filePath,
"operation": "read",
"language": strings.TrimPrefix(filepath.Ext(filePath), "."),
}
}
emitHookEvent(logger, "file.read", "file", "info", "File read observed", input, fields)
return true
default:
emitPreToolDecision(logger, input, sessionID, "approval.allowed", "allow", "Pre-tool observed", asymptoteobserve.FidelityInferred)
return true
}
}
// emitPreToolDecision writes an approval-category event for a tool call.
//
// fidelity is a required parameter rather than a constant inside because this one function serves
// both kinds of caller, and the difference between them is the whole point of the field. The
// permission-request hook reaches it when a runtime genuinely asked for a decision; the pre-tool
// hook reaches it on runtimes that expose no approval gate at all, where the approval block below
// describes what Beacon concluded from seeing a tool call rather than anything an operator did.
func emitPreToolDecision(logger *logging.Logger, input map[string]interface{}, sessionID, action, decision, reason, fidelity string) {
toolName := getFirstStr(input, "tool_name", "toolName")
toolInput := resolveToolInput(input)
fields := sessionFields(sessionID, input)
for key, value := range toolFields(toolName, toolInput) {
fields[key] = value
}
fields["approval"] = map[string]interface{}{
"required": true,
"decision": decision,
"reason": reason,
}
emitHookEventWithFidelity(logger, action, "approval", "info", reason, fidelity, input, fields)
}
// preToolResponse is what an observing pre-tool hook tells the runtime: it must leave the tool call
// exactly where the runtime's own permission flow would put it. A nil return means write nothing.
//
// The rule every branch below follows is that a telemetry hook never answers "allow" where the
// runtime reads that as a pre-approval, because an observing hook that approved would silently
// disarm the user's own confirmation prompts for every tool call. A provider deny from the policy
// seam is not this function's business; policyDenyFor answers that in each runtime's deny shape.
func preToolResponse() map[string]interface{} {
// Antigravity gets no output at all. Its documented PreToolUse contract
// (https://antigravity.google/docs/hooks/) makes `decision` a required field, and its values
// are all opinions: "allow" "automatically allows the tool execution", which is exactly the
// bypass this function exists to avoid; "ask" prompts for every call, which would add prompts
// the user never configured; and an object with no decision -- `{}` -- is read as a deny with
// no reason, which would block every tool call (reported by integrators, e.g.
// spacesheep-dev/sessionpipe#50). A hook that prints nothing leaves the call to Antigravity's
// own permission settings; PrismorSec/prismor#603 checked that live and prints nothing for the
// calls it lets through for the same reason. Silence is therefore the only no-opinion answer
// this runtime has.
if platformFlag == "antigravity" {
return nil
}
// Cursor answers allow, because it has no other answer that lets a call proceed. Its hooks reference (https://cursor.com/docs/agent/hooks)
// does not mark `permission` optional on preToolUse, beforeShellExecution or beforeReadFile,
// says a response that "doesn't match the hook's schema blocks the action", and lists "no
// output" among the failures that let an action through, so `{}` risks blocking every call
// and silence is read the same as allow. "ask" is not an alternative: beforeReadFile does not
// accept it, and on the cloud agent's beforeShellExecution there is no person to answer it.
// What makes allow an observing answer here is that Cursor does not treat it as a
// pre-approval: Cursor staff confirmed on the forum (topics 144244 and 161342, the latter
// May 2026) that only a hook's "deny" is enforced, and that "allow" does not override the
// user's allowlist or approval mode -- a command the allowlist would prompt for still prompts.
// If Cursor ever makes hook verdicts authoritative, this branch must be revisited:
// TestPreToolResponseAllowsOnlyWhereAllowIsNotAPreApproval exists to make that a one-line decision.
if platformFlag == "cursor" {
return cursorPreToolResponse
}
// Grok Build reads a top-level `decision` and treats a response without one as no objection,
// passing the call to Grok's own permission gate; exit 0 is success and only "deny"/"block" or
// exit 2 stops a call (agenticcontrolplane.com/integrations/grok-build; gartnera/lite-sandbox#69
// notes a hook "allow" does not skip Grok's approval prompt today). `{}` carries no decision,
// so it asserts nothing about the call -- unlike "allow", which would start approving on the
// user's behalf the day Grok honors it.
// Qwen Code belongs with claude here, and the reason is a security property rather than a
// convention. Qwen's PreToolUse contract reads a decision from
// `hookSpecificOutput.permissionDecision`, where "allow" means *run the tool without the usual
// approval prompt*. An observing hook that answered "allow" would therefore not be observing:
// it would silently disarm the user's own permission prompts for every tool call, on a runtime
// where the hook was installed to watch. An empty object carries no decision, so Qwen's normal
// permission flow runs untouched -- which is the only correct answer for a telemetry hook, and
// what TestQwenPreToolDoesNotApproveOnBehalfOfTheUser holds in place.
// Muse Code requires the empty object for a second reason on top of the one above, and it is
// not a preference: its hook runner rejects a stdout object carrying keys it does not know, so
// `{"permission":"allow"}` would not read as a permissive answer -- it would fail the hook run
// outright. Emitting nothing speculative is the only shape that leaves a Muse turn untouched.
// OpenHands is here for the Qwen reason rather than the Muse one. It parses a hook's stdout as
// JSON and acts on `decision`, `reason`, `additionalContext` and `continue`; a `permission` key
// is not among them, so `{"permission":"allow"}` is inert on today's build. It is still the
// wrong thing to send. The string is stored verbatim on the HookExecutionEvent OpenHands shows
// in the conversation, so it puts a decision Beacon did not make in front of the user -- and if
// OpenHands ever reads that key, an observing hook would begin approving tool calls on the
// user's behalf without a line of Beacon changing. An empty object asserts nothing either way.
// Kiro reaches this branch and never uses what it returns: hookStdoutIsConsumedAsAgentContext
// suppresses the write entirely, because on Kiro stdout is model context rather than a
// response object. The empty object is still the right value to hand back -- it is what the
// suppression would have to fall back to if that ever changed, and it keeps this function
// answering the same question for every runtime rather than having one whose answer is
// "nothing, and the writer knows why".
// goose is the one runtime where the empty object is the harmful answer, so it is answered
// before the group below rather than joining it. gooseBlockingEventResponse carries why, and
// carries it once because Stop needs the same answer for the same reason.
if platformFlag == goosePlatform {
return gooseBlockingEventResponse
}
// DeepSeek Harness is here for the Qwen reason. Its bridge reads
// `hookSpecificOutput.permissionDecision`, where "allow" is a real pre-approval -- so an
// observing hook answering "allow" would not be observing, it would be disarming the
// deployment's own permission gate for every tool call. An empty object carries no decision,
// and the bridge's decoder treats stdout that parses to nothing as exactly that: no opinion.
// Kimi Code reaches this branch and never uses what it returns, the way Kiro does:
// hookStdoutIsConsumedAsAgentContext suppresses the write, because on UserPromptSubmit this
// runtime appends a hook's stdout to the model's context. The empty object is still the right
// value to hand back -- Kimi Code's decoder reads an object with no `permissionDecision` as no
// opinion, so it is what the suppression would fall back to if that ever changed.
//
// Every other runtime gets the empty object as well, and that includes the ones that reach
// pre-tool with no installer writing the hook (Codex CLI, GitHub Copilot CLI, Factory Droid,
// Cline, a hand-written config). Those runtimes read their own decision keys --
// `hookSpecificOutput.permissionDecision` on the Claude-shaped ones, where "allow" is a
// pre-approval -- and a default that answered allow would be one key rename away from the Qwen
// bypass. No decision is the safe default; a runtime that needs more must be named above.
return emptyResponse
}
func emitPreToolObserved(logger *logging.Logger, input map[string]interface{}, sessionID string) {
toolName := getFirstStr(input, "tool_name", "toolName")
if platformFlag == "antigravity" {
toolName = antigravityToolName(input)
}
toolInput := resolveToolInput(input)
fields := sessionFields(sessionID, input)
for key, value := range toolFields(toolName, toolInput) {
fields[key] = value
}
emitHookEvent(logger, "tool.invoked", "tool", "info", "Tool invocation observed", input, fields)
}
func emitAntigravityPromptFromTranscript(logger *logging.Logger, input map[string]interface{}, sessionID string) {
if sessionID == "" {
return
}
st := state.NewSessionState(sessionID, "antigravity")
if st.HasPromptEmitted() {
return
}
prompt := antigravityPromptFromTranscript(input, sessionID)
if prompt == "" {
return
}
// Claim the prompt before recording it. Parallel tool calls run parallel PreToolUse hooks, and
// a check followed by a later set let each of them see "not emitted" and record the prompt.
// A claim that could not be saved still records it: a duplicate beats a lost prompt.
claimed, err := st.MarkPromptEmittedIfNeeded()
if err != nil {
logger.Warn("Failed to persist prompt state", "error", err.Error())
} else if !claimed {
return
}
fields := sessionFields(sessionID, input)
setPromptFields(fields, prompt)
emitPromptSubmitted(logger, input, fields, prompt)
}
func antigravityPromptFromTranscript(input map[string]interface{}, sessionID string) string {
path := getFirstStr(input, "transcriptPath", "transcript_path")
if path == "" {
path = defaultAntigravityTranscriptPath(sessionID)
}
file, err := os.Open(path)
if err != nil {
return ""
}
defer file.Close()
scanner := bufio.NewScanner(file)
scanner.Buffer(make([]byte, 0, 1024*1024), 1024*1024)
for scanner.Scan() {
var entry map[string]interface{}
if err := json.Unmarshal(scanner.Bytes(), &entry); err != nil {
continue
}
if !asymptoteobserve.IsAntigravityUserInput(getFirstStr(entry, "source"), getFirstStr(entry, "type")) {
continue
}
if content := getFirstStr(entry, "content"); content != "" {
return asymptoteobserve.AntigravityPrompt(content)
}
}
return ""
}
func defaultAntigravityTranscriptPath(sessionID string) string {
home, err := os.UserHomeDir()
if err != nil {
return ""
}
return filepath.Join(home, ".gemini", "antigravity-cli", "brain", sessionID, ".system_generated", "logs", "transcript.jsonl")
}