Skip to content

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

18.1 KB
Raw Blame
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")
}