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"
"os"
"path/filepath"
"strings"
"testing"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/hookcmd"
)
// OpenHands is silent about a hooks.json it does not like: a file that fails validation is dropped
// with a log line the user never sees, and the agent goes on working with no hooks at all. Nothing
// in the runtime tells Beacon that an install stopped working, so these tests are what would.
// openHandsUserHooksPath points the user scope at a temp home and returns the path Beacon writes.
// OH_PERSISTENCE_DIR is cleared as well as HOME because openHandsConfigDir prefers it, and a
// developer with it set would otherwise have these tests resolve outside the temp directory.
func openHandsUserHooksPath(t *testing.T) string {
t.Helper()
home := t.TempDir()
testenv.SetHome(t, home)
t.Setenv("OH_PERSISTENCE_DIR", "")
path, err := openHandsHooksPath(LevelUser)
if err != nil {
t.Fatalf("openHandsHooksPath: %v", err)
}
return path
}
func writeOpenHandsFixture(t *testing.T, path, body string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
t.Fatalf("create hooks dir: %v", err)
}
if err := os.WriteFile(path, []byte(body), 0644); err != nil {
t.Fatalf("write hooks fixture: %v", err)
}
}
func readOpenHandsDocument(t *testing.T, path string) map[string]json.RawMessage {
t.Helper()
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read hooks.json: %v", err)
}
var document map[string]json.RawMessage
if err := json.Unmarshal(data, &document); err != nil {
t.Fatalf("decode hooks.json: %v", err)
}
return document
}
// openHandsCommands returns every hook command in the file, keyed by the event it is registered
// under, reading the document exactly as OpenHands does -- unwrapping a legacy wrapper first.
func openHandsCommands(t *testing.T, path string) map[string][]string {
t.Helper()
document := readOpenHandsDocument(t, path)
if wrapper, ok := document[openHandsWrapperKey]; ok {
document = map[string]json.RawMessage{}
if err := json.Unmarshal(wrapper, &document); err != nil {
t.Fatalf("decode hooks wrapper: %v", err)
}
}
out := map[string][]string{}
for key, raw := range document {
var groups []struct {
Matcher string `json:"matcher"`
Hooks []struct {
Command string `json:"command"`
} `json:"hooks"`
}
if err := json.Unmarshal(raw, &groups); err != nil {
t.Fatalf("decode hook event %q: %v", key, err)
}
for _, group := range groups {
for _, hook := range group.Hooks {
out[key] = append(out[key], hook.Command)
}
}
}
return out
}
func installOpenHandsFixture(t *testing.T, path string) {
t.Helper()
if err := installOpenHandsHooks(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json"); err != nil {
t.Fatalf("installOpenHandsHooks returned error: %v", err)
}
}
// ---------------------------------------------------------------------------
// Fresh install
// ---------------------------------------------------------------------------
// All six events OpenHands exposes get a hook, under the snake_case names its own writer emits.
// The event names are the wire contract: a typo in one is not an error, it is that event silently
// never firing.
func TestInstallOpenHandsBindsEveryEvent(t *testing.T) {
path := openHandsUserHooksPath(t)
installOpenHandsFixture(t, path)
commands := openHandsCommands(t, path)
wantSubcommands := map[string]string{
"session_start": "session-start",
"user_prompt_submit": "prompt-submit",
"pre_tool_use": "pre-tool",
"post_tool_use": "post-tool",
"stop": "stop",
"session_end": "session-end",
}
if len(commands) != len(wantSubcommands) {
t.Fatalf("registered events = %v, want exactly %d", commands, len(wantSubcommands))
}
for event, subcommand := range wantSubcommands {
got := commands[event]
if len(got) != 1 {
t.Fatalf("event %q has %d hooks, want exactly 1: %v", event, len(got), got)
}
if !strings.HasSuffix(got[0], " "+subcommand) {
t.Errorf("event %q command = %q, want it to end in the %q subcommand", event, got[0], subcommand)
}
if !strings.Contains(got[0], "--platform openhands") {
t.Errorf("event %q command = %q, want --platform openhands", event, got[0])
}
// The endpoint settings ride as flags rather than as an inline VAR=value prefix, so the
// hook reads the right log and config wherever the runtime is running.
for _, flag := range []string{"--log", "--config"} {
if !strings.Contains(got[0], flag) {
t.Errorf("event %q command = %q, want the %s flag", event, got[0], flag)
}
}
}
}
// Every hook Beacon writes is a command hook with an explicit timeout and the marker name. The
// timeout matters: OpenHands defaults to 60 seconds, which is a long time to hold an agent turn
// for a hook that finishes in milliseconds. No hook is async: an async hook is fire-and-forget with
// its stdout discarded, which would make the policy seam's deny unreachable on the one event that
// can block.
func TestInstallOpenHandsWritesTypedCommandHooks(t *testing.T) {
path := openHandsUserHooksPath(t)
installOpenHandsFixture(t, path)
document := readOpenHandsDocument(t, path)
for _, event := range openHandsEvents {
var groups []struct {
Matcher string `json:"matcher"`
Hooks []openHandsHookRef `json:"hooks"`
}
if err := json.Unmarshal(document[event.snakeKey], &groups); err != nil {
t.Fatalf("decode %q: %v", event.snakeKey, err)
}
if len(groups) != 1 || len(groups[0].Hooks) != 1 {
t.Fatalf("event %q shape = %#v, want one group with one hook", event.snakeKey, groups)
}
if groups[0].Matcher != openHandsAllToolsMatcher {
t.Errorf("event %q matcher = %q, want %q", event.snakeKey, groups[0].Matcher, openHandsAllToolsMatcher)
}
hook := groups[0].Hooks[0]
if hook.Type != "command" {
t.Errorf("event %q type = %q, want command", event.snakeKey, hook.Type)
}
if hook.Name != openHandsHookName {
t.Errorf("event %q name = %q, want %q", event.snakeKey, hook.Name, openHandsHookName)
}
if hook.Timeout != event.timeout {
t.Errorf("event %q timeout = %d, want %d", event.snakeKey, hook.Timeout, event.timeout)
}
}
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read hooks.json: %v", err)
}
if strings.Contains(string(data), "\"async\"") {
t.Fatalf("hooks.json declares async hooks:\n%s", data)
}
}
// hooks.json is a project file that gets committed and read by everyone working in the repository.
// A mode only its author can read would make the hooks stop working for the next checkout.
func TestInstallOpenHandsWritesAWorldReadableFile(t *testing.T) {
if os.Getenv("GOOS") == "windows" {
t.Skip("file modes are not meaningful on Windows")
}
path := openHandsUserHooksPath(t)
installOpenHandsFixture(t, path)
info, err := os.Stat(path)
if err != nil {
t.Fatalf("stat hooks.json: %v", err)
}
if perm := info.Mode().Perm(); perm&0044 == 0 {
t.Fatalf("hooks.json mode = %v, want it readable by group and other", perm)
}
}
// ---------------------------------------------------------------------------
// Merging
// ---------------------------------------------------------------------------
// hooks.json is where a user keeps their own hooks, so Beacon is a guest in it. An install that
// replaced the file would silently end whatever quality gate or block rule was registered there.
func TestInstallOpenHandsPreservesExistingHooks(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{
"stop": [
{"matcher": "*", "hooks": [{"command": ".openhands/hooks/on_stop.sh", "timeout": 120}]}
],
"pre_tool_use": [
{"matcher": "terminal", "hooks": [{"command": ".openhands/hooks/block_dangerous.sh", "timeout": 10}]}
]
}`)
installOpenHandsFixture(t, path)
commands := openHandsCommands(t, path)
if !openHandsHasCommand(commands["stop"], ".openhands/hooks/on_stop.sh") {
t.Fatalf("stop hooks = %v, want the user's on_stop.sh preserved", commands["stop"])
}
if !openHandsHasCommand(commands["pre_tool_use"], ".openhands/hooks/block_dangerous.sh") {
t.Fatalf("pre_tool_use hooks = %v, want the user's block_dangerous.sh preserved", commands["pre_tool_use"])
}
for _, event := range []string{"stop", "pre_tool_use"} {
if !openHandsHasBeaconCommand(commands[event]) {
t.Fatalf("%s hooks = %v, want Beacon's hook alongside the user's", event, commands[event])
}
}
// The user's own timeout and matcher survive: Beacon appends a group rather than rewriting one.
document := readOpenHandsDocument(t, path)
if !strings.Contains(string(document["pre_tool_use"]), `"matcher": "terminal"`) {
t.Fatalf("pre_tool_use = %s, want the user's terminal matcher untouched", document["pre_tool_use"])
}
}
// Re-running the install replaces Beacon's own hooks rather than adding a second copy, so a repair
// does not end with the binary firing twice per event.
func TestInstallOpenHandsIsIdempotent(t *testing.T) {
path := openHandsUserHooksPath(t)
installOpenHandsFixture(t, path)
installOpenHandsFixture(t, path)
installOpenHandsFixture(t, path)
for event, commands := range openHandsCommands(t, path) {
if len(commands) != 1 {
t.Fatalf("event %q has %d hooks after three installs, want 1: %v", event, len(commands), commands)
}
}
}
// The loader unwraps `{"hooks": {...}}` by replacing the whole document with what is under that
// key. Adding a top-level event beside the wrapper does not merge -- it discards Beacon's hooks
// with a log line nobody sees -- so Beacon writes inside the wrapper when it finds one.
func TestInstallOpenHandsWritesInsideTheLegacyWrapper(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{
"hooks": {
"PreToolUse": [
{"matcher": "terminal", "hooks": [{"command": ".openhands/hooks/block_dangerous.sh"}]}
]
}
}`)
installOpenHandsFixture(t, path)
document := readOpenHandsDocument(t, path)
if len(document) != 1 {
t.Fatalf("document keys = %v, want only the hooks wrapper", document)
}
if _, ok := document[openHandsWrapperKey]; !ok {
t.Fatalf("document = %v, want the wrapper preserved", document)
}
commands := openHandsCommands(t, path)
if !openHandsHasBeaconCommand(commands["PreToolUse"]) {
t.Fatalf("PreToolUse hooks = %v, want Beacon's hook inside the wrapper", commands["PreToolUse"])
}
if !openHandsHasCommand(commands["PreToolUse"], ".openhands/hooks/block_dangerous.sh") {
t.Fatalf("PreToolUse hooks = %v, want the user's hook preserved", commands["PreToolUse"])
}
}
// Providing both spellings of one event is a hard error that takes the entire file down, not just
// that event. Beacon writes under whichever spelling the file already uses and never introduces a
// second one -- which is why a Claude Code-shaped file keeps its PascalCase names.
func TestInstallOpenHandsFollowsTheExistingEventSpelling(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{
"PreToolUse": [
{"matcher": "terminal", "hooks": [{"command": ".openhands/hooks/block_dangerous.sh"}]}
],
"SessionStart": []
}`)
installOpenHandsFixture(t, path)
document := readOpenHandsDocument(t, path)
for _, pascal := range []string{"PreToolUse", "SessionStart"} {
if _, ok := document[pascal]; !ok {
t.Fatalf("document = %v, want %q kept", openHandsKeys(document), pascal)
}
}
for _, snake := range []string{"pre_tool_use", "session_start"} {
if _, ok := document[snake]; ok {
t.Fatalf("document = %v, want no second spelling %q", openHandsKeys(document), snake)
}
}
// Events the file did not already name get the canonical snake_case spelling.
if _, ok := document["post_tool_use"]; !ok {
t.Fatalf("document = %v, want post_tool_use under the canonical name", openHandsKeys(document))
}
commands := openHandsCommands(t, path)
if !openHandsHasBeaconCommand(commands["PreToolUse"]) {
t.Fatalf("PreToolUse hooks = %v, want Beacon's hook under the existing spelling", commands["PreToolUse"])
}
}
// ---------------------------------------------------------------------------
// Refusing a file the runtime would reject
// ---------------------------------------------------------------------------
// A file naming one event twice already fails to load, taking every hook in it down with it.
// Installing into it would report success while the runtime went on loading nothing at all.
func TestInstallOpenHandsRefusesDuplicateEventSpellings(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{
"PreToolUse": [{"matcher": "*", "hooks": [{"command": "a.sh"}]}],
"pre_tool_use": [{"matcher": "*", "hooks": [{"command": "b.sh"}]}]
}`)
err := installOpenHandsHooks(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json")
if err == nil {
t.Fatal("installOpenHandsHooks succeeded on a file OpenHands rejects")
}
// The file is left exactly as it was: Beacon cannot fix it and must not half-rewrite it.
commands := openHandsCommands(t, path)
if openHandsHasBeaconCommand(commands["PreToolUse"]) || openHandsHasBeaconCommand(commands["pre_tool_use"]) {
t.Fatalf("hooks were written into a rejected file: %v", commands)
}
}
// HookConfig forbids extra fields, so one unrecognized top-level key fails validation and the whole
// file loads as nothing.
func TestInstallOpenHandsRefusesUnknownEventKeys(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{
"stop": [{"matcher": "*", "hooks": [{"command": "a.sh"}]}],
"PreCompact": [{"matcher": "*", "hooks": [{"command": "b.sh"}]}]
}`)
err := installOpenHandsHooks(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json")
if err == nil {
t.Fatal("installOpenHandsHooks succeeded on a file OpenHands rejects")
}
}
func TestInstallOpenHandsRefusesMalformedJSON(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{"stop": [`)
if err := installOpenHandsHooks(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json"); err == nil {
t.Fatal("installOpenHandsHooks succeeded on malformed JSON")
}
}
// An empty file is not malformed JSON to a person, and failing on one would make install fail on a
// hooks.json somebody had created but not written.
func TestInstallOpenHandsTreatsAnEmptyFileAsNoHooks(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, " \n")
installOpenHandsFixture(t, path)
if len(openHandsCommands(t, path)) != len(openHandsEvents) {
t.Fatalf("commands = %v, want every event registered", openHandsCommands(t, path))
}
}
// ---------------------------------------------------------------------------
// Status and uninstall
// ---------------------------------------------------------------------------
func TestOpenHandsInstalledDetectionMatchesTheCommand(t *testing.T) {
path := openHandsUserHooksPath(t)
if isOpenHandsInstalledAt(path) {
t.Fatal("isOpenHandsInstalledAt = true before any install")
}
installOpenHandsFixture(t, path)
if !isOpenHandsInstalledAt(path) {
t.Fatal("isOpenHandsInstalledAt = false after install")
}
// A user's own hook is not Beacon's, however it is named.
other := filepath.Join(t.TempDir(), "hooks.json")
writeOpenHandsFixture(t, other, `{
"stop": [{"matcher": "*", "hooks": [{"name": "beacon-endpoint-telemetry", "command": "./my_stop.sh"}]}]
}`)
if isOpenHandsInstalledAt(other) {
t.Fatal("isOpenHandsInstalledAt = true for a hook that only borrowed the marker name")
}
}
// Uninstall removes what Beacon added and nothing more. A file that still holds another tool's
// hooks is rewritten without Beacon's rather than removed.
func TestUninstallOpenHandsLeavesOtherHooksInPlace(t *testing.T) {
path := openHandsUserHooksPath(t)
writeOpenHandsFixture(t, path, `{
"stop": [{"matcher": "*", "hooks": [{"command": ".openhands/hooks/on_stop.sh", "timeout": 120}]}]
}`)
installOpenHandsFixture(t, path)
changed, err := removeOpenHandsHooks(path)
if err != nil {
t.Fatalf("removeOpenHandsHooks: %v", err)
}
if !changed {
t.Fatal("removeOpenHandsHooks reported no change after an install")
}
if isOpenHandsInstalledAt(path) {
t.Fatal("Beacon hooks survived the uninstall")
}
commands := openHandsCommands(t, path)
if !openHandsHasCommand(commands["stop"], ".openhands/hooks/on_stop.sh") {
t.Fatalf("stop hooks = %v, want the user's hook left in place", commands["stop"])
}
// The events Beacon added and nobody else used are gone rather than left as empty entries.
if _, ok := commands["pre_tool_use"]; ok {
t.Fatalf("commands = %v, want the events Beacon added removed entirely", commands)
}
}
// An uninstall that emptied the file removes it, so nothing is left behind in somebody's
// repository. A file Beacon never touched is left alone and reported as no change.
func TestUninstallOpenHandsRemovesAFileItEmptied(t *testing.T) {
path := openHandsUserHooksPath(t)
installOpenHandsFixture(t, path)
changed, err := removeOpenHandsHooks(path)
if err != nil {
t.Fatalf("removeOpenHandsHooks: %v", err)
}
if !changed {
t.Fatal("removeOpenHandsHooks reported no change after an install")
}
if _, err := os.Stat(path); !os.IsNotExist(err) {
t.Fatalf("hooks.json still exists after removing the only hooks in it: %v", err)
}
}
func TestUninstallOpenHandsIsANoOpWhenNothingWasInstalled(t *testing.T) {
path := openHandsUserHooksPath(t)
changed, err := removeOpenHandsHooks(path)
if err != nil {
t.Fatalf("removeOpenHandsHooks on a missing file: %v", err)
}
if changed {
t.Fatal("removeOpenHandsHooks reported a change with no file present")
}
writeOpenHandsFixture(t, path, `{"stop": [{"matcher": "*", "hooks": [{"command": "./mine.sh"}]}]}`)
before, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read fixture: %v", err)
}
changed, err = removeOpenHandsHooks(path)
if err != nil {
t.Fatalf("removeOpenHandsHooks: %v", err)
}
if changed {
t.Fatal("removeOpenHandsHooks reported a change for a file with no Beacon hooks")
}
after, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read fixture: %v", err)
}
if string(before) != string(after) {
t.Fatalf("file was rewritten with no Beacon hooks to remove:\n%s\n%s", before, after)
}
}
// ---------------------------------------------------------------------------
// Scopes
// ---------------------------------------------------------------------------
// Both scopes are real, which is the opposite of the Muse and Hermes situation where the project
// scope does nothing at all. Project scope is the documented location every host reads; user scope
// is the SDK loader's second search location.
func TestOpenHandsConfigDirResolvesBothScopes(t *testing.T) {
home := t.TempDir()
testenv.SetHome(t, home)
t.Setenv("OH_PERSISTENCE_DIR", "")
userDir, err := openHandsConfigDir(LevelUser)
if err != nil {
t.Fatalf("openHandsConfigDir(user): %v", err)
}
if want := filepath.Join(home, ".openhands"); userDir != want {
t.Fatalf("user dir = %q, want %q", userDir, want)
}
// The empty level is the same as user scope, which is what an unset --level resolves to.
defaultDir, err := openHandsConfigDir("")
if err != nil {
t.Fatalf("openHandsConfigDir(\"\"): %v", err)
}
if defaultDir != userDir {
t.Fatalf("default dir = %q, want the user dir %q", defaultDir, userDir)
}
projectDir, err := openHandsConfigDir(LevelProject)
if err != nil {
t.Fatalf("openHandsConfigDir(project): %v", err)
}
cwd, err := os.Getwd()
if err != nil {
t.Fatalf("getwd: %v", err)
}
if want := filepath.Join(cwd, ".openhands"); projectDir != want {
t.Fatalf("project dir = %q, want %q", projectDir, want)
}
if _, err := openHandsConfigDir("machine"); err == nil {
t.Fatal("openHandsConfigDir accepted an unknown level")
}
}
// Sandboxed and containerized setups redirect OpenHands state onto a volume with
// OH_PERSISTENCE_DIR, and on a machine that sets it ~/.openhands is not where OpenHands looks. An
// install that ignored it would write a file the runtime never reads.
func TestOpenHandsUserScopeHonorsThePersistenceDirEnv(t *testing.T) {
testenv.SetHome(t, t.TempDir())
persistence := t.TempDir()
t.Setenv("OH_PERSISTENCE_DIR", persistence)
path, err := openHandsHooksPath(LevelUser)
if err != nil {
t.Fatalf("openHandsHooksPath: %v", err)
}
if want := filepath.Join(persistence, openHandsHookFileName); path != want {
t.Fatalf("hooks path = %q, want %q", path, want)
}
}
func openHandsHasCommand(commands []string, want string) bool {
for _, command := range commands {
if strings.Contains(command, want) {
return true
}
}
return false
}
func openHandsHasBeaconCommand(commands []string) bool {
for _, command := range commands {
if hookcmd.IsEndpointHook(command, "openhands") {
return true
}
}
return false
}
func openHandsKeys(document map[string]json.RawMessage) []string {
keys := make([]string, 0, len(document))
for key := range document {
keys = append(keys, key)
}
return keys
}