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 hooks
import (
"encoding/json"
"fmt"
"os"
"path/filepath"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/hookcmd"
)
type Level string
const (
LevelUser Level = "user"
LevelProject Level = "project"
)
type HookRef struct {
Command string `json:"command"`
Matcher string `json:"matcher,omitempty"`
Timeout int `json:"timeout,omitempty"`
}
type HooksJSON struct {
Version int `json:"version"`
Hooks map[string][]HookRef `json:"hooks"`
}
type CursorOptions struct {
Level Level
LogPath string
UserMode bool
}
type CursorCloudOptions struct {
BinaryPath string
LogPath string
SafeHooks bool
}
type CursorStatus struct {
Installed bool `json:"installed"`
BinaryPath string `json:"binary_path,omitempty"`
HooksJSONPath string `json:"hooks_json_path,omitempty"`
Message string `json:"message,omitempty"`
}
var cursorRuntime = hookRuntime{
displayName: "Cursor",
configPath: cursorHooksJSONPath,
install: installCursorHooksJSON,
uninstall: removeCursorEndpointHooks,
isInstalled: isCursorInstalledAt,
}
// Extension points for a build of Beacon that compiles in hook subcommands of its own (see
// version.Edition). Both are nil in this build, which installs exactly the hooks listed in
// installCursorHooksJSON.
var (
// cursorExtraHooks returns further hook entries to install for Cursor, keyed by event, given
// the command prefix Beacon's own hooks use. Their commands carry that prefix, so repair,
// status and uninstall treat them as Beacon's hooks. Every event the map names is stripped of
// Beacon's entries like the events Beacon installs, then gets Beacon's own entry, if it has
// one, followed by these. An event named with no entries is stripped and left with only the
// user's, so a build stops installing a hook by naming its event with none: an event left out
// of the map keeps whatever Beacon wrote there until an uninstall.
cursorExtraHooks func(prefix string) map[string][]HookRef
// cursorHooksChanged runs after Beacon has written its hooks into a Cursor hooks.json
// (installed true) or taken them out (installed false), as whoever ran the install.
cursorHooksChanged func(hooksPath string, installed bool) error
)
func InstallCursor(opts CursorOptions) (CursorStatus, error) {
status, err := installRuntimeHooks(cursorRuntime, RuntimeOptions(opts))
if err != nil {
return CursorStatus{}, err
}
return cursorStatusFromRuntime(status), nil
}
func UninstallCursor(opts CursorOptions) (CursorStatus, error) {
status, err := uninstallRuntimeHooks(cursorRuntime, RuntimeOptions(opts))
if err != nil {
return CursorStatus{}, err
}
return cursorStatusFromRuntime(status), nil
}
func CursorHookStatus(opts CursorOptions) CursorStatus {
return cursorStatusFromRuntime(runtimeHookStatus(cursorRuntime, RuntimeOptions(opts)))
}
func IsCursorInstalled(opts CursorOptions) bool {
return isRuntimeInstalled(cursorRuntime, RuntimeOptions(opts))
}
func cursorStatusFromRuntime(status runtimeStatus) CursorStatus {
return CursorStatus{
Installed: status.Installed,
BinaryPath: status.BinaryPath,
HooksJSONPath: status.ConfigPath,
Message: status.Message,
}
}
func installCursorHooksJSON(path, binaryPath, logPath, configPath string) error {
hooksFile, err := readCursorHooksFile(path)
if err != nil {
return err
}
commandPrefix := endpointCommandPrefix("cursor", binaryPath, logPath, configPath)
// The subcommand-to-event wiring is hookcmd.CursorEvents, which the hooks binary also reads to
// decide which Cursor entries a Claude Code hook running the same subcommand may defer to.
entries := make(map[string][]json.RawMessage)
for subcommand, events := range hookcmd.CursorEvents {
ref := HookRef{Command: commandPrefix + " " + subcommand}
switch subcommand {
case "prompt-submit":
ref.Timeout = 30
case "pre-tool":
ref.Matcher = "Write|Edit|MultiEdit|Shell|MCP"
}
entry, err := json.Marshal(ref)
if err != nil {
return err
}
for _, event := range events {
entries[event] = []json.RawMessage{entry}
}
}
if cursorExtraHooks != nil {
for hookName, refs := range cursorExtraHooks(commandPrefix) {
list := entries[hookName]
for _, ref := range refs {
entry, err := json.Marshal(ref)
if err != nil {
return err
}
list = append(list, entry)
}
entries[hookName] = list
}
}
for hookName, list := range entries {
existing := hooksFile.hooks[hookName]
merged := mergeEndpointHooks(existing, list)
if len(merged) == 0 {
// Only an extension's event can end up empty. Drop it when Beacon's entries were
// all it held; an event that was already empty is the user's and stays as it was.
if len(existing) > 0 {
delete(hooksFile.hooks, hookName)
}
continue
}
hooksFile.hooks[hookName] = merged
}
data, err := hooksFile.marshal()
if err != nil {
return err
}
if err := os.WriteFile(path, data, 0644); err != nil {
return err
}
if cursorHooksChanged != nil {
return cursorHooksChanged(path, true)
}
return nil
}
func RenderCursorCloudHooks(opts CursorCloudOptions) (string, error) {
hooksJSON := HooksJSON{
Version: 1,
Hooks: CursorCloudHookRefs(opts),
}
data, err := json.MarshalIndent(hooksJSON, "", " ")
if err != nil {
return "", err
}
return string(data) + "\n", nil
}
func CursorCloudHookRefs(opts CursorCloudOptions) map[string][]HookRef {
if opts.LogPath == "" {
opts.LogPath = "/tmp/beacon/runtime.jsonl"
}
prefix := cursorCloudCommandPrefix(opts.BinaryPath, opts.LogPath)
refs := map[string][]HookRef{
"beforeSubmitPrompt": {{Command: prefix + " prompt-submit", Timeout: 30}},
"postToolUse": {{Command: prefix + " post-tool"}},
"postToolUseFailure": {{Command: prefix + " post-tool"}},
"beforeReadFile": {
{Command: prefix + " pre-tool"},
},
"subagentStart": {
{Command: prefix + " subagent-start"},
},
"subagentStop": {
{Command: prefix + " subagent-stop"},
},
"preCompact": {
{Command: prefix + " cursor-event"},
},
// The agent's reasoning, its replies and the end of each turn. The Cursor desktop app also
// runs the user-level afterAgentThought hook for a cloud agent it shows, which the endpoint
// leaves unrecorded (cursorRelaysCloudAgent in beacon-hooks), so these are where a cloud
// agent's reasoning is recorded. stop also uploads the log once the turn is over.
"afterAgentThought": {{Command: prefix + " agent-thought"}},
"afterAgentResponse": {{Command: prefix + " agent-response"}},
"stop": {{Command: prefix + " stop"}},
}
if !opts.SafeHooks {
refs["beforeShellExecution"] = []HookRef{{Command: prefix + " pre-tool"}}
refs["afterShellExecution"] = []HookRef{{Command: prefix + " post-tool"}}
refs["afterFileEdit"] = []HookRef{{Command: prefix + " post-tool"}}
}
return refs
}
func cursorCloudCommandPrefix(binaryPath, logPath string) string {
return fmt.Sprintf(
"BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=%s %s --platform cursor",
shellQuote(logPath),
shellQuote(binaryPath),
)
}
// cursorHooksFile is a Cursor hooks.json as read from disk. Beacon owns only the command entries it
// wrote, so everything else is held as the JSON it was read as and written back unchanged: other
// top-level keys, and every other hook entry with all of its fields. Cursor's hook options include
// `type` ("command" or "prompt"), `prompt`, `model`, `loop_limit` and `failClosed` besides the
// three HookRef models. Decoding the file into HookRef and encoding it back deleted them, which
// turned a user's fail-closed guard into a fail-open one and a prompt hook into `{"command":""}`.
type cursorHooksFile struct {
values map[string]json.RawMessage
hooks map[string][]json.RawMessage
}
func readCursorHooksFile(path string) (cursorHooksFile, error) {
file := cursorHooksFile{
values: map[string]json.RawMessage{},
hooks: map[string][]json.RawMessage{},
}
data, err := os.ReadFile(path)
if err == nil {
if err := json.Unmarshal(data, &file.values); err != nil {
return cursorHooksFile{}, err
}
if file.values == nil {
file.values = map[string]json.RawMessage{}
}
if rawHooks, ok := file.values["hooks"]; ok {
if err := json.Unmarshal(rawHooks, &file.hooks); err != nil {
return cursorHooksFile{}, err
}
}
} else if !os.IsNotExist(err) {
return cursorHooksFile{}, err
}
if file.hooks == nil {
file.hooks = map[string][]json.RawMessage{}
}
return file, nil
}
// marshal encodes the file with Beacon's indentation. A missing or zero version is written as 1,
// as Cursor requires a positive version; any other version is kept as it was.
func (file cursorHooksFile) marshal() ([]byte, error) {
out := make(map[string]json.RawMessage, len(file.values)+2)
for key, value := range file.values {
out[key] = value
}
var version int
if raw, ok := out["version"]; !ok || (json.Unmarshal(raw, &version) == nil && version == 0) {
out["version"] = json.RawMessage("1")
}
hooks, err := json.Marshal(file.hooks)
if err != nil {
return nil, err
}
out["hooks"] = hooks
return json.MarshalIndent(out, "", " ")
}
// onlyHooks reports whether the file holds nothing besides its version and hooks, so removing
// Beacon's last hook may remove the file instead of leaving an empty one.
func (file cursorHooksFile) onlyHooks() bool {
for key := range file.values {
if key != "version" && key != "hooks" {
return false
}
}
return len(file.hooks) == 0
}
// cursorHookCommand returns the command of one hook entry, or "" for an entry with no string
// command (a prompt hook, or anything Beacon cannot read), which is never Beacon's.
func cursorHookCommand(entry json.RawMessage) string {
var ref struct {
Command string `json:"command"`
}
if err := json.Unmarshal(entry, &ref); err != nil {
return ""
}
return ref.Command
}
func isEndpointHookEntry(entry json.RawMessage) bool {
return isEndpointHook(cursorHookCommand(entry))
}
// mergeEndpointHooks keeps an event's entries that are not Beacon's, in order, and appends refs.
func mergeEndpointHooks(existing []json.RawMessage, refs []json.RawMessage) []json.RawMessage {
out := make([]json.RawMessage, 0, len(existing))
for _, item := range existing {
if !isEndpointHookEntry(item) {
out = append(out, item)
}
}
return append(out, refs...)
}
func removeCursorEndpointHooks(path string) (bool, error) {
removed, err := removeEndpointHooks(path)
if err != nil {
return removed, err
}
if cursorHooksChanged != nil {
if err := cursorHooksChanged(path, false); err != nil {
return removed, err
}
}
return removed, nil
}
func removeEndpointHooks(path string) (bool, error) {
if _, err := os.Stat(path); os.IsNotExist(err) {
return false, nil
}
file, err := readCursorHooksFile(path)
if err != nil {
return false, err
}
changed := false
for hookName, entries := range file.hooks {
filtered := make([]json.RawMessage, 0, len(entries))
for _, entry := range entries {
if isEndpointHookEntry(entry) {
continue
}
filtered = append(filtered, entry)
}
if len(filtered) == len(entries) {
continue
}
changed = true
if len(filtered) == 0 {
delete(file.hooks, hookName)
} else {
file.hooks[hookName] = filtered
}
}
if !changed {
return false, nil
}
if file.onlyHooks() {
return true, os.Remove(path)
}
out, err := file.marshal()
if err != nil {
return false, err
}
return true, os.WriteFile(path, out, 0644)
}
func isEndpointHook(command string) bool {
return hookcmd.IsEndpointHook(command, "cursor")
}
func isCursorInstalledAt(path string) bool {
file, err := readCursorHooksFile(path)
if err != nil {
return false
}
for _, entries := range file.hooks {
for _, entry := range entries {
if isEndpointHookEntry(entry) {
return true
}
}
}
return false
}
func cursorHooksJSONPath(level Level) (string, error) {
targetDir, err := cursorTargetDir(level)
if err != nil {
return "", err
}
return filepath.Join(targetDir, "hooks.json"), nil
}
func cursorTargetDir(level Level) (string, error) {
switch level {
case "", LevelUser:
home, err := os.UserHomeDir()
if err != nil {
return "", err
}
return filepath.Join(home, ".cursor"), nil
case LevelProject:
cwd, err := os.Getwd()
if err != nil {
return "", err
}
return filepath.Join(cwd, ".cursor"), nil
default:
return "", fmt.Errorf("unknown hook level %q", level)
}
}