Skip to content

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

19.2 KB
Raw Blame
package cmd

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"strings"

	"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
	"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/policy"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/policycontract"
)

// policyCandidate describes the imminent tool call. The same fields feed both the
// provider request event and, on a deny, the denial telemetry event.
type policyCandidate struct {
	action   string
	category string
	fields   map[string]interface{}
}

// policyDenial is one runtime's way of saying "do not run this call".
//
// A struct rather than the response map this used to be, because the map could only express one of
// the two shapes runtimes actually use. Every runtime supported before Kiro answers a hook with a
// JSON object on stdout and a deny is a key in it. Kiro's hook contract has no response object at
// all: a block is exit code 2 with the reason on stderr, and stdout is either ignored or fed to
// the model. A function that could only return a map had exactly one option there -- return nil,
// which means "unknown platform, allow" -- so a provider deny would have been dropped silently on
// a runtime that does support blocking.
//
// The two are not exclusive by construction. A runtime that reads a stdout object *and* honors an
// exit code can carry both, which is the honest description of OpenHands even though only the
// object is used there today.
type policyDenial struct {
	// response is the object written to stdout, or nil when the runtime has no such shape.
	response map[string]interface{}
	// exitCode is the status the process exits with, or 0 to return normally.
	exitCode int
	// stderr is the message written to standard error. On an exit-code runtime this is not a log
	// line -- it is the text handed to the agent as the reason the call was refused, so without it
	// the model and the operator both see a call blocked with no account of why.
	stderr string
}

// policyExit is os.Exit, indirected so a test can observe the status without ending the run.
//
// Indirected for the same reason the runtime writers are: the behavior under test is a side effect
// on the process, and there is no way to assert on it otherwise.
var policyExit = os.Exit

// emit writes the denial in whatever shape the runtime reads, and does not return when that shape
// is an exit status.
//
// Order matters. stdout and stderr are written before the exit, because os.Exit runs no deferred
// work and skips any buffering a writer might be doing.
func (d policyDenial) emit() {
	if d.response != nil {
		outputJSON(d.response)
	}
	if d.stderr != "" {
		fmt.Fprintln(os.Stderr, d.stderr)
	}
	if d.exitCode != 0 {
		policyExit(d.exitCode)
	}
}

// enforcePolicy consults the configured policy provider for the imminent tool
// call. If the provider denies and the current platform has a deny shape, it
// records denial telemetry and returns that denial. Otherwise it returns nil and
// the caller proceeds with the normal allow flow. It is a no-op (nil) when no
// provider is configured.
func enforcePolicy(logger *logging.Logger, input map[string]interface{}, sessionID string, phase policycontract.Phase) *policyDenial {
	// A duplicate Cursor run records nothing, so it must not decide anything either: a deny here
	// would block a call with no record of why. Beacon's own Cursor hook asks the provider.
	if !policy.Enabled() || duplicateCursorRun {
		return nil
	}
	candidate := newPolicyCandidate(input, sessionID)
	resp := policy.Evaluate(context.Background(), policy.Request{
		Phase:    phase,
		Platform: platformFlag,
		Event:    candidate.event(),
	})
	if !resp.Denied() {
		return nil
	}
	reason := strings.TrimSpace(resp.Reason)
	if reason == "" {
		reason = "Tool call denied by policy provider"
	}
	deny := policyDenyFor(reason, phase)
	if deny == nil {
		// Platform has no deny shape: honor "unknown platform -> allow".
		return nil
	}
	emitPolicyDenied(logger, input, candidate, resp, reason)
	return deny
}

// newPolicyCandidate builds the candidate from hook input the same way the
// telemetry path does (session + tool fields), plus a top-level command fallback
// for runtimes (e.g. Cursor shell hooks) that carry the command outside tool input.
func newPolicyCandidate(input map[string]interface{}, sessionID string) policyCandidate {
	toolName := getFirstStr(input, "tool_name", "toolName")
	if platformFlag == "antigravity" {
		toolName = antigravityToolName(input)
	}
	toolInput := resolveToolInput(input)
	hookEvent := getFirstStr(input, "hook_event_name", "hookEventName")
	// goose spells it `event`; see the note in emitPostToolObserved for why that spelling stays out
	// of the shared list. It changes nothing on this path today -- the seam only runs pre-tool,
	// where no runtime's event name affects the classification -- and is read so the two callers of
	// actionForTool ask it the same question rather than one of them silently passing "".
	if platformFlag == goosePlatform {
		hookEvent = gooseHookEvent(input)
	}

	fields := sessionFields(sessionID, input)
	for key, value := range toolFields(toolName, toolInput) {
		fields[key] = value
	}
	if _, ok := fields["command"]; !ok {
		if command := getFirstStr(input, "command"); command != "" {
			fields["command"] = map[string]interface{}{"command": command}
		}
	}

	// The candidate describes a call that has not run yet, so there is no result to pass. On a
	// runtime whose MCP calls are only identifiable from their result, an MCP tool therefore
	// reaches the provider as the action its name implies -- stated rather than hidden, and the
	// same limit the telemetry path has on PreToolUse.
	action := actionForTool(hookEvent, toolName, toolInput, nil)
	// A command-bearing call with no more specific action is a command execution.
	if action == "tool.invoked" {
		if _, ok := fields["command"]; ok {
			action = "command.executed"
		}
	}
	return policyCandidate{action: action, category: categoryForAction(action), fields: fields}
}

func categoryForAction(action string) string {
	switch {
	case strings.HasPrefix(action, "command."):
		return "command"
	case strings.HasPrefix(action, "file."):
		return "file"
	case strings.HasPrefix(action, "mcp."):
		return "mcp"
	case strings.HasPrefix(action, "approval.") || strings.HasPrefix(action, "policy."):
		return "approval"
	default:
		return "tool"
	}
}

// event builds the asymptoteobserve.Event sent to the provider via a JSON
// round-trip of the same field map the telemetry writer uses, so the provider
// sees the same shape it would match in the runtime JSONL.
func (c policyCandidate) event() asymptoteobserve.Event {
	envelope := map[string]interface{}{
		"vendor":         "beacon",
		"product":        "endpoint-agent",
		"schema_version": "1.0",
		"event": map[string]interface{}{
			"kind":     "agent_runtime",
			"action":   c.action,
			"category": c.category,
		},
		"harness": map[string]interface{}{
			"name": platformFlag,
			// The contract promises the provider the same field names it would match in the
			// runtime JSONL, so the provenance marker belongs here too. No fidelity counterpart:
			// this event describes a tool call that has not happened yet, so there is no
			// observation for the action to be faithful to.
			"collection_method": asymptoteobserve.CollectionMethodForPlatform(platformFlag),
		},
	}
	for key, value := range c.fields {
		envelope[key] = value
	}
	var ev asymptoteobserve.Event
	data, err := json.Marshal(envelope)
	if err != nil {
		return ev
	}
	_ = json.Unmarshal(data, &ev)
	return ev
}

// emitPolicyDenied records the denial as endpoint telemetry, carrying
// policy.enforcement=enforce / policy.decision=deny and the matching approval
// fields.
func emitPolicyDenied(logger *logging.Logger, input map[string]interface{}, c policyCandidate, resp policycontract.Response, reason string) {
	fields := c.fields
	fields["approval"] = map[string]interface{}{
		"required": true,
		"decision": "deny",
		"reason":   reason,
	}
	policyField := map[string]interface{}{
		"enforcement": "enforce",
		"decision":    "deny",
		"reason":      reason,
	}
	if resp.RuleID != "" {
		policyField["id"] = resp.RuleID
	}
	fields["policy"] = policyField

	severity := strings.TrimSpace(resp.Severity)
	if severity == "" {
		severity = "high"
	}
	emitHookEvent(logger, "approval.denied", "approval", severity, reason, input, fields)
}

// policyDenyFor returns the runtime-specific denial. A nil return means the
// platform has no confirmed deny shape, so the caller allows (unknown platform ->
// allow).
//
// Kiro is the one runtime whose denial is not a stdout object, and it is the
// reason this function exists beside policyDenyResponse rather than being it.
// Kiro's hooks answer with exit codes: a `command` action that exits 2 blocks the
// triggering event, the reason on stderr is what the agent is told, and any other
// non-zero code is an error rather than a block. There is no key to set on
// stdout, and writing one would be worse than useless -- on the two events whose
// stdout Kiro reads at all, it is pasted into the model's context.
//
// Exit code 2 blocks only PreToolUse, UserPromptSubmit and PreTaskExec. The seam
// runs in the pre-tool and permission-request phases, and Beacon registers no
// permission-request hook on Kiro because Kiro exposes no such event -- so the
// only phase that can reach this on Kiro is the one where the code takes effect.
//
// Kimi Code is the second such runtime and the first whose answer depends on the phase. It reads
// both shapes -- exit code 2 with the reason on stderr, checked first, and a stdout object second
// -- but only three of its events are blockable and only one of them is a phase the seam runs in.
// kimiPolicyDenial carries that distinction, and returns nil for the phase that cannot be refused
// rather than emitting a denial the runtime discards.
func policyDenyFor(reason string, phase policycontract.Phase) *policyDenial {
	if platformFlag == kiroPlatform {
		return &policyDenial{exitCode: kiroBlockExitCode, stderr: reason}
	}
	if platformFlag == kimiPlatform {
		return kimiPolicyDenial(reason, phase)
	}
	if response := policyDenyResponse(reason, phase); response != nil {
		return &policyDenial{response: response}
	}
	return nil
}

// policyDenyResponse returns the runtime-specific hook response object that
// denies the tool call. A nil return means the platform has no confirmed
// object-shaped deny. A platform with a confirmed deny shape must honor a deny in
// every phase the seam runs in, so a provider deny is never silently dropped for a
// platform we enforce on -- which means the object follows the phase wherever the
// runtime reads a different one per event (Claude Code, Qwen Code, Muse Code).
func policyDenyResponse(reason string, phase policycontract.Phase) map[string]interface{} {
	switch {
	case platformFlag == "cursor":
		return map[string]interface{}{"permission": "deny"}
	case isDevinLikePlatform(platformFlag):
		return map[string]interface{}{"decision": "reject"}
	case platformFlag == "antigravity" || platformFlag == "grok":
		return map[string]interface{}{"decision": "deny"}
	// OpenHands reads the same `decision` key, and also a `reason` that antigravity and grok have
	// no field for. The reason is worth sending: OpenHands surfaces it in the conversation as the
	// explanation for the block and hands it to the agent as the tool's failure, so without it the
	// operator and the model both see a call refused with no account of why.
	//
	// Exit code 2 is the documented alternative to this object, not a requirement alongside it:
	// the executor parses stdout first and a parsed `decision: deny` sets blocked regardless of the
	// code. Beacon exits 0 on every hook path, so saying it in the object is the only shape that
	// works without changing that.
	case platformFlag == openHandsPlatform:
		return map[string]interface{}{"decision": "deny", "reason": reason}
	// goose reads the same two keys and one different value: its classifier accepts the literal
	// strings "allow" and "block", and nothing else. "deny" -- the word every runtime above uses --
	// is not a decision goose recognizes, so sending it would be read as a hook that exited 0
	// without a verdict, which goose classifies as a *failed* hook and, on a rule that is not
	// configured to block on failure, waves the tool call straight through. A seam that meant to
	// deny would have allowed.
	//
	// The reason rides along for the OpenHands purpose and one more: goose puts it in front of both
	// the operator and the model, prefixed with "Tool call denied by policy hook" and the
	// instruction not to retry, so the seam's explanation is what the agent is told.
	//
	// Exit code 2 with the reason on stderr is goose's documented alternative, not a requirement
	// alongside this: classify_output reads stdout first and a parsed `decision: block` denies
	// whatever the exit code. Beacon exits 0 on every hook path, so the object is the only shape
	// that works without changing that -- the same reasoning as OpenHands above.
	case platformFlag == goosePlatform:
		return map[string]interface{}{"decision": "block", "reason": reason}
	// Claude Code and Qwen Code answer the two phases the seam runs in with two different objects,
	// and each reads only its own. PreToolUse takes `hookSpecificOutput.permissionDecision` with a
	// `permissionDecisionReason`; PermissionRequest takes `hookSpecificOutput.decision` with
	// `behavior: "deny"` and a `message` that Claude is told as the reason
	// (https://code.claude.com/docs/en/hooks, "PermissionRequest decision control"). Sending the
	// PreToolUse object from the permission phase is not a weaker deny, it is no deny: the runtime
	// finds no `decision` and the permission flow carries on to the person, while emitPolicyDenied
	// has already recorded the call as enforced. Exit code 2 is no fallback either -- Claude Code
	// documents it as ignored on PermissionRequest.
	//
	// That gap is not hypothetical on Claude Code. The PreToolUse matcher Beacon installs names a
	// fixed list of tools while PermissionRequest matches every tool, so a tool outside the list
	// reaches the seam only in the permission phase.
	//
	// Qwen Code's PermissionRequestHookOutput reads the same `decision.behavior` and `message` and
	// does not check hookEventName; the name is set anyway so one object is right for both.
	case platformFlag == "claude" || platformFlag == "qwen":
		return claudePolicyDenyResponse(reason, phase)
	// DeepSeek Harness shares Claude Code's PreToolUse deny shape because its bridge exists to run
	// Claude Code hooks: the decoder reads `hookSpecificOutput.permissionDecision` as
	// allow/deny/ask and `permissionDecisionReason` as the reason, and maps a deny onto the
	// harness's own `tools/pre-execute` rejection with that reason handed to the model.
	//
	// `hookEventName` must equal the firing event or the whole hookSpecificOutput block is
	// discarded -- the bridge passes the point name as expectedEventName precisely to stop a hook
	// answering for an event that is not running. "PreToolUse" is correct in the only phase that
	// can reach this on dsh: Beacon registers no permission-request hook there, because the bridge
	// exposes no such event.
	case platformFlag == dshPlatform:
		return map[string]interface{}{
			"hookSpecificOutput": map[string]interface{}{
				"hookEventName":            "PreToolUse",
				"permissionDecision":       "deny",
				"permissionDecisionReason": reason,
			},
		}
	// Muse Code's deny contract is split between what has been measured and what has only been
	// read out of the binary, and this returns the half that has not been measured -- stated here
	// rather than left for a reader to discover.
	//
	// Measured, on a live hook: the host is fail-open on everything except `{"decision":"block"}`
	// and exit code 2. Every other shape, this one included, was ignored and the turn proceeded.
	// But that measurement was taken on UserPromptSubmit, whose deny cancels the whole turn --
	// which is not what a per-call policy deny means, and emitting it from a tool phase would
	// escalate "do not run this command" into "abandon what the user asked for". So the turn-family
	// shape is deliberately not used here.
	//
	// The tool-family shape below comes from the binary's own validation strings, which require
	// hookSpecificOutput to carry a hookEventName matching the firing event alongside
	// permissionDecision / permissionDecisionReason. Strong evidence, not measurement: the account
	// used for the measurement hit a billing error before any tool call, so no tool-side deny was
	// ever exercised.
	//
	// The cost of that being wrong is bounded and is the direction to be wrong in. Sending the
	// wrong family's shape was measured to be ignored silently, so an incorrect guess degrades to
	// exactly what returning nil does -- the deny does not take effect and the tool runs -- rather
	// than blocking a call for the wrong reason. Returning nil would give up the case where the
	// inference is right for no safety gain.
	//
	// hookEventName is derived from the phase rather than hardcoded, because Muse requires it to
	// match the firing event and Beacon binds each phase to a distinct Muse event in the hooks file
	// it writes. Unlike Claude Code above, the binary's strings name one object for both events, so
	// only the event name follows the phase.
	case platformFlag == "muse":
		return map[string]interface{}{
			"hookSpecificOutput": map[string]interface{}{
				"hookEventName":            museHookEventNameForPhase(phase),
				"permissionDecision":       "deny",
				"permissionDecisionReason": reason,
			},
		}
	default:
		return nil
	}
}

// claudePolicyDenyResponse is the Claude Code (and Qwen Code) deny for the phase the seam is
// answering.
//
// The permission phase gets the PermissionRequest `decision` object, and every other phase the
// PreToolUse object -- pre-tool is the phase the seam runs in on every runtime, so an unrecognized
// phase degrades to the common case, the same fallback museHookEventNameForPhase takes.
func claudePolicyDenyResponse(reason string, phase policycontract.Phase) map[string]interface{} {
	if phase == policycontract.PhasePermissionRequest {
		return map[string]interface{}{
			"hookSpecificOutput": map[string]interface{}{
				"hookEventName": "PermissionRequest",
				"decision": map[string]interface{}{
					"behavior": "deny",
					"message":  reason,
				},
			},
		}
	}
	return map[string]interface{}{
		"hookSpecificOutput": map[string]interface{}{
			"hookEventName":            "PreToolUse",
			"permissionDecision":       "deny",
			"permissionDecisionReason": reason,
		},
	}
}

// museHookEventNameForPhase names the Muse Code event the policy seam is answering.
//
// Muse validates that a hook's hookSpecificOutput echoes the event that fired it, so this must
// track the binding in the managed hooks file Beacon writes: PreToolUse for the pre-tool phase,
// PermissionRequest for the permission phase. PreToolUse is the fallback because it is the phase
// the seam runs in on every runtime, so an unrecognized phase degrades to the common case rather
// than to an event name Muse would reject.
func museHookEventNameForPhase(phase policycontract.Phase) string {
	if phase == policycontract.PhasePermissionRequest {
		return "PermissionRequest"
	}
	return "PreToolUse"
}