Skip to content

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

feat(windows): emit hook commands as one argv, and resolve the console user

shukieshah3170048e083d
diff --git a/beacon-sandbox/scenario/suite_shipped_test.go b/beacon-sandbox/scenario/suite_shipped_test.go
new file mode 100644
index 00000000..79b21ce5
--- /dev/null
+++ b/beacon-sandbox/scenario/suite_shipped_test.go
@@ -0,0 +1,67 @@
+package scenario
+
+import (
+ "strings"
+ "testing"
+)
+
+// TestShippedSuiteLoadsAndValidates covers the scenarios this repository actually ships.
+//
+// Every other test in this file builds a scenario in a temp directory, so a typo in a real one --
+// an unknown field, a malformed expectation, a platform that does not exist -- was caught by nothing
+// here. It surfaced instead when someone dispatched a run, which on Windows means waiting several
+// minutes for a runner to tell you a YAML key was misspelled.
+//
+// Loading the directory is most of the value: LoadSuite validates each scenario as it reads it, so
+// this fails on anything Validate rejects.
+func TestShippedSuiteLoadsAndValidates(t *testing.T) {
+ suite, err := LoadSuite("../scenarios")
+ if err != nil {
+ t.Fatalf("the shipped scenario suite does not load: %v", err)
+ }
+ if len(suite.Scenarios) == 0 {
+ t.Fatal("the shipped scenario suite is empty; LoadSuite found no files")
+ }
+
+ seen := make(map[string]bool, len(suite.Scenarios))
+ for _, scenario := range suite.Scenarios {
+ if seen[scenario.ID] {
+ // Two scenarios with one id means one of them is unreachable by --scenario, and which one
+ // depends on directory order.
+ t.Fatalf("duplicate scenario id %q", scenario.ID)
+ }
+ seen[scenario.ID] = true
+
+ // Every expectation states why it exists. That convention is what makes a failure report
+ // readable by someone who did not write the scenario, and it is worth enforcing rather than
+ // hoping for -- a missing `why` shows up as a bare assertion name in the verdict.
+ for i, expect := range scenario.Expect {
+ if strings.TrimSpace(expect.Why) == "" {
+ t.Errorf("%s: expect[%d] (%s) has no `why`", scenario.ID, i, expect.Action)
+ }
+ }
+ }
+}
+
+// TestWindowsScenariosDeclareTheirPlatform guards a default that fails in the wrong direction.
+//
+// Platform defaults to linux when unset, so a Windows scenario that forgets the field is silently
+// filed as a Linux one: it would be selected for a Modal run, where its `C:\` paths and PowerShell
+// prompt cannot work, and skipped by the Windows runner that was meant to run it.
+func TestWindowsScenariosDeclareTheirPlatform(t *testing.T) {
+ suite, err := LoadSuite("../scenarios")
+ if err != nil {
+ t.Fatalf("LoadSuite: %v", err)
+ }
+ for _, scenario := range suite.Scenarios {
+ // The id prefix is the convention this suite already follows, so it is a usable independent
+ // signal for what the platform field should say.
+ wantWindows := strings.HasPrefix(scenario.ID, "w")
+ isWindows := scenario.TargetPlatform() == PlatformWindows
+ if wantWindows != isWindows {
+ t.Errorf("%s: id prefix and platform disagree (platform=%q); a w-prefixed scenario must "+
+ "declare platform: windows, or it will be dispatched to Linux",
+ scenario.ID, scenario.TargetPlatform())
+ }
+ }
+}
diff --git a/beacon-sandbox/scenarios/w03-hook-capture.yaml b/beacon-sandbox/scenarios/w03-hook-capture.yaml
new file mode 100644
index 00000000..fa151f1e
--- /dev/null
+++ b/beacon-sandbox/scenarios/w03-hook-capture.yaml
@@ -0,0 +1,68 @@
+id: w03-hook-capture
+platform: windows
+# The scenario the Windows port exists to pass: does an *installed* Windows endpoint capture what an
+# agent actually did?
+#
+# w01 and w02 assert the service, and mark capture optional because hook installation was assumed to
+# be broken on Windows. This one gates on capture, and it is the first Windows scenario where a
+# missing event is a failure rather than a finding.
+#
+# It runs through installed hooks rather than `beacon ci exec`. That distinction is the whole point:
+# `ci exec` wraps the agent and collects from the outside, so it can pass while every hook is
+# misconfigured -- and on Windows it currently captures only intermittently (#320). Installed hooks
+# are what a real user gets, and the only thing that proves the emitted command string is one the
+# runtime can actually execute.
+#
+# What made that worth measuring rather than assuming: the hook command was rewritten to pass the
+# endpoint settings as flags, because the previous inline `VAR=value cmd` prefix is a POSIX shell
+# construct. A dispatched probe then found that Claude Code on Windows runs hook commands through Git
+# Bash -- $BASH_VERSION expands, %COMSPEC% does not -- and that an *unquoted* Windows path does not
+# run at all there, because bash consumes the backslashes as escapes. Both facts are encoded in the
+# command this scenario exercises, and neither is visible from reading the code.
+prompt: >-
+ Do both of these steps in order, then report what you did.
+ First run exactly this PowerShell command: Write-Output '{{canary}}' | Tee-Object -FilePath '{{sentinel}}'
+ Then create a file at {{workdir}}\w03-written.txt containing the single line {{canary}}
+sentinel: '{{workdir}}\w03.sentinel'
+budget_usd: 1.5
+timeout_seconds: 480
+
+install:
+ mode: system
+ service: windows-service
+ expect_status_running: true
+ expect_service_kind: windows-service
+
+expect:
+ - action: prompt.submitted
+ contains: ["{{canary}}"]
+ why: >-
+ The baseline, and on Windows a load-bearing one. A hook command the runtime cannot parse
+ produces exactly this absence and nothing else: the install reports success, the settings file
+ is valid, the service is healthy, and no event ever arrives. If this is missing, the emitted
+ command string is the first thing to look at.
+
+ - action: command.executed
+ contains: ["{{canary}}"]
+ fields: ["command.command", "tool.name"]
+ why: >-
+ e.command.command is the detection surface for the whole rules/risky-command/ category, and
+ threat rules match scalar leaves, so an empty value disables every one of those rules silently.
+ It also pins the exporter fix that taught it to read Claude Code's PowerShell tool rather than
+ only bash -- before that, this field was empty on Windows while every other field looked right.
+
+ - action: file.modified
+ fields: ["file.path"]
+ why: >-
+ A second, differently-shaped signal. A capture path can be broken in ways that still deliver
+ prompts -- one hook event configured correctly and the rest not -- so asserting only the prompt
+ would pass a half-installed endpoint.
+
+ - action: approval.allowed
+ fields: ["approval.decision"]
+ optional: true
+ why: >-
+ Claude Code's tool_decision carries decision=accept regardless of platform, so this is expected
+ to fire. Optional because w04 is the scenario that gates the approval path; recording it here
+ keeps the answer visible without making this scenario fail for a reason w04 would explain
+ better.
diff --git a/beacon-sandbox/scenarios/w04-denied-tool.yaml b/beacon-sandbox/scenarios/w04-denied-tool.yaml
new file mode 100644
index 00000000..7b6c3689
--- /dev/null
+++ b/beacon-sandbox/scenarios/w04-denied-tool.yaml
@@ -0,0 +1,41 @@
+id: w04-denied-tool
+platform: windows
+# The approval path through installed Windows hooks, as s07 does on Linux.
+#
+# --disallowedTools makes the refusal deterministic: no interactive prompt is needed, so the decision
+# is produced the same way on every run. Nothing is asserted about the command running, because the
+# point is that it must not.
+#
+# Kept separate from w03 rather than folded into it. w03 gates the capture of things that happened;
+# this gates the capture of a decision about something that did not. A single scenario asserting both
+# would report one failure for two unrelated causes.
+prompt: >-
+ Run this shell command and report the result: echo {{canary}}
+disallowed_tools: ["Bash"]
+budget_usd: 1.0
+timeout_seconds: 420
+
+install:
+ mode: system
+ service: windows-service
+ expect_status_running: true
+ expect_service_kind: windows-service
+
+expect:
+ - action: prompt.submitted
+ contains: ["{{canary}}"]
+ why: Proves the session ran and hooks fired, since there is no sentinel to prove agent action here.
+
+ - action: approval.allowed
+ fields: ["approval.decision"]
+ why: >-
+ Approval decisions must arrive on an approval.* action with the decision populated. Anything
+ filtering on category=approval misses them otherwise, which is the bug this assertion exists to
+ keep fixed.
+
+ - action: approval.denied
+ optional: true
+ why: >-
+ Recorded rather than required, matching s07. Observed behavior on Linux is that Claude Code
+ never attempts an excluded tool, so only approval.allowed appears; this stays as a probe in case
+ Windows differs or the runtime starts reporting refusals.
diff --git a/cli/beacon/cmd/console_user_other.go b/cli/beacon/cmd/console_user_other.go
new file mode 100644
index 00000000..431f5d66
--- /dev/null
+++ b/cli/beacon/cmd/console_user_other.go
@@ -0,0 +1,10 @@
+//go:build !windows
+
+package cmd
+
+// windowsActiveConsoleUser is unreachable here -- defaultActiveConsoleUser dispatches on
+// runtime.GOOS -- and exists so that function compiles as one piece rather than being split per
+// platform for the sake of one branch.
+func windowsActiveConsoleUser() (consoleUserInfo, bool, error) {
+ return consoleUserInfo{}, false, nil
+}
diff --git a/cli/beacon/cmd/console_user_windows.go b/cli/beacon/cmd/console_user_windows.go
new file mode 100644
index 00000000..f72c62c1
--- /dev/null
+++ b/cli/beacon/cmd/console_user_windows.go
@@ -0,0 +1,132 @@
+//go:build windows
+
+package cmd
+
+import (
+ "fmt"
+
+ "golang.org/x/sys/windows"
+)
+
+// windowsActiveConsoleUser resolves the person whose runtime configuration a system install should
+// reach.
+//
+// This is the gap that made the Linux package install useless: a system endpoint configured the
+// *installing* account's Claude Code and Codex settings, which for a package install is root rather
+// than the person at the keyboard, so the collector was healthy and captured nothing. Windows has no
+// SUDO_USER to answer it with, and the shape of the question is different enough to be worth stating.
+//
+// Elevation on Windows does not change the account. "Run as administrator" gives the same user a
+// token with more privileges, so an admin running `beacon endpoint install --system` from an elevated
+// prompt *is* the console user -- no lookup needed, and no guessing. That covers every interactive
+// install.
+//
+// The case that needs real work is an install running as LocalSystem: an MSI custom action, a
+// scheduled task, a fleet management agent. There the current account is not a person at all, and the
+// interactive session has to be found. Splitting on "am I SYSTEM" rather than on "am I elevated" is
+// what makes both paths correct.
+func windowsActiveConsoleUser() (consoleUserInfo, bool, error) {
+ isSystem, err := runningAsLocalSystem()
+ if err != nil {
+ return consoleUserInfo{}, false, err
+ }
+ if !isSystem {
+ return currentWindowsUser()
+ }
+ return windowsConsoleSessionUser()
+}
+
+// runningAsLocalSystem reports whether this process's own account is LocalSystem.
+//
+// Compared by SID rather than by name: the account renders as "NT AUTHORITY\SYSTEM" in English and
+// differently in every other display language, and a name comparison would quietly take the wrong
+// branch on a localized machine.
+func runningAsLocalSystem() (bool, error) {
+ token, err := windows.OpenCurrentProcessToken()
+ if err != nil {
+ return false, fmt.Errorf("open this process's access token: %w", err)
+ }
+ defer token.Close()
+
+ user, err := token.GetTokenUser()
+ if err != nil {
+ return false, fmt.Errorf("read the account this process runs as: %w", err)
+ }
+ system, err := windows.CreateWellKnownSid(windows.WinLocalSystemSid)
+ if err != nil {
+ return false, fmt.Errorf("resolve the LocalSystem security identifier: %w", err)
+ }
+ return user.User.Sid.Equals(system), nil
+}
+
+// currentWindowsUser describes the account this process is already running as.
+func currentWindowsUser() (consoleUserInfo, bool, error) {
+ token, err := windows.OpenCurrentProcessToken()
+ if err != nil {
+ return consoleUserInfo{}, false, fmt.Errorf("open this process's access token: %w", err)
+ }
+ defer token.Close()
+ return describeTokenUser(token)
+}
+
+// windowsConsoleSessionUser finds whoever is logged on at the physical console.
+//
+// The analogue of logind on Linux, and used for the same reason: the account running the install is
+// not a person, so the person has to be identified some other way. Reported as absent rather than
+// guessed at whenever that fails, which keeps the Linux rule -- an unresolvable user is reported, not
+// invented, because configuring the wrong profile writes hooks nobody runs and reports success.
+func windowsConsoleSessionUser() (consoleUserInfo, bool, error) {
+ sessionID := windows.WTSGetActiveConsoleSessionId()
+ // 0xFFFFFFFF means no session is attached to the console, which happens on a headless server and
+ // while the machine is at the lock screen mid-boot.
+ if sessionID == 0xFFFFFFFF {
+ return consoleUserInfo{}, false, nil
+ }
+
+ var token windows.Token
+ // Needs SYSTEM rights, which is the only branch that reaches here. A failure normally means the
+ // session exists but nobody is signed in to it -- session 0 is the services session and has no
+ // interactive user -- so it is an absence, not an error to fail an install over.
+ if err := windows.WTSQueryUserToken(sessionID, &token); err != nil {
+ return consoleUserInfo{}, false, nil
+ }
+ defer token.Close()
+
+ return describeTokenUser(token)
+}
+
+// describeTokenUser reads the account name and profile directory out of an access token.
+//
+// The profile directory comes from the token rather than from %SystemDrive%\Users\<name>. That
+// convention is a default, not a rule: profiles can be redirected, roam, live on another volume, or
+// carry a suffix when a name collides with an existing profile directory. Assembling the path by hand
+// would configure a directory the person does not use, and the failure would be silence.
+func describeTokenUser(token windows.Token) (consoleUserInfo, bool, error) {
+ user, err := token.GetTokenUser()
+ if err != nil {
+ return consoleUserInfo{}, false, fmt.Errorf("read the account from the access token: %w", err)
+ }
+ account, domain, _, err := user.User.Sid.LookupAccount("")
+ if err != nil {
+ return consoleUserInfo{}, false, fmt.Errorf("resolve a name for the account: %w", err)
+ }
+ home, err := token.GetUserProfileDirectory()
+ if err != nil {
+ return consoleUserInfo{}, false, fmt.Errorf("read the profile directory for %s: %w", account, err)
+ }
+ if account == "" || home == "" {
+ // Nothing to configure, and saying so beats returning a half-identified user that a caller
+ // would then use to build paths.
+ return consoleUserInfo{}, false, nil
+ }
+ return consoleUserInfo{Username: qualifiedAccountName(domain, account), HomeDir: home}, true, nil
+}
+
+// qualifiedAccountName renders DOMAIN\user, which is how Windows names an account and how an operator
+// reading `endpoint status` will recognize it. The domain is omitted when there is none to report.
+func qualifiedAccountName(domain, account string) string {
+ if domain == "" {
+ return account
+ }
+ return domain + `\` + account
+}
diff --git a/cli/beacon/cmd/endpoint_hooks_repair.go b/cli/beacon/cmd/endpoint_hooks_repair.go
index 057bf900..40d07699 100644
--- a/cli/beacon/cmd/endpoint_hooks_repair.go
+++ b/cli/beacon/cmd/endpoint_hooks_repair.go
@@ -177,6 +177,8 @@ func defaultActiveConsoleUser() (consoleUserInfo, bool, error) {
return darwinActiveConsoleUser()
case "linux":
return linuxActiveConsoleUser()
+ case "windows":
+ return windowsActiveConsoleUser()
}
return consoleUserInfo{}, false, nil
}
diff --git a/cli/beacon/internal/endpoint/hooks/antigravity_test.go b/cli/beacon/internal/endpoint/hooks/antigravity_test.go
index a2868e07..85d83736 100644
--- a/cli/beacon/internal/endpoint/hooks/antigravity_test.go
+++ b/cli/beacon/internal/endpoint/hooks/antigravity_test.go
@@ -27,9 +27,8 @@ func TestInstallAntigravityHooksPreservesNonBeaconBlocks(t *testing.T) {
"my-linter-hook",
"echo keep",
"beacon-endpoint",
- "BEACON_ENDPOINT_MODE=1",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
"'/tmp/beacon hooks' --platform antigravity",
"PreInvocation",
"UserPromptSubmit",
diff --git a/cli/beacon/internal/endpoint/hooks/claude_test.go b/cli/beacon/internal/endpoint/hooks/claude_test.go
index 15873bf0..31264fdf 100644
--- a/cli/beacon/internal/endpoint/hooks/claude_test.go
+++ b/cli/beacon/internal/endpoint/hooks/claude_test.go
@@ -28,9 +28,8 @@ func TestInstallClaudeSettingsPreservesExistingSettingsAndHooks(t *testing.T) {
"defaultMode",
"echo keep",
"--platform factory",
- "BEACON_ENDPOINT_MODE=1",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
"'/tmp/beacon hooks' --platform claude",
"SessionStart",
"UserPromptSubmit",
diff --git a/cli/beacon/internal/endpoint/hooks/codex_test.go b/cli/beacon/internal/endpoint/hooks/codex_test.go
index e00eeae5..6293181c 100644
--- a/cli/beacon/internal/endpoint/hooks/codex_test.go
+++ b/cli/beacon/internal/endpoint/hooks/codex_test.go
@@ -29,8 +29,8 @@ func TestInstallCodexHooksUsesInventoryHeartbeatOnly(t *testing.T) {
"UserPromptSubmit",
"--platform codex",
"inventory-heartbeat",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
} {
if !strings.Contains(text, want) {
t.Fatalf("Codex hooks missing %q:\n%s", want, text)
diff --git a/cli/beacon/internal/endpoint/hooks/cursor_test.go b/cli/beacon/internal/endpoint/hooks/cursor_test.go
index e7c6570a..9ebecf40 100644
--- a/cli/beacon/internal/endpoint/hooks/cursor_test.go
+++ b/cli/beacon/internal/endpoint/hooks/cursor_test.go
@@ -27,13 +27,15 @@ func TestInstallCursorHooksJSONPreservesNonBeaconHooks(t *testing.T) {
if !strings.Contains(text, "echo keep") {
t.Fatalf("non-Beacon hook was not preserved: %s", text)
}
- if !strings.Contains(text, "BEACON_ENDPOINT_MODE=1") {
- t.Fatalf("endpoint env was not added: %s", text)
+ // The endpoint marker used to be an env prefix. It is now the settings flags themselves, which
+ // the two checks below assert, plus the platform this hook was installed for.
+ if !strings.Contains(text, "--platform cursor") {
+ t.Fatalf("endpoint hook was not installed for cursor: %s", text)
}
- if !strings.Contains(text, "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'") {
+ if !strings.Contains(text, "--log '/tmp/runtime.jsonl'") {
t.Fatalf("endpoint log env was not added: %s", text)
}
- if !strings.Contains(text, "BEACON_ENDPOINT_CONFIG='/tmp/config.json'") {
+ if !strings.Contains(text, "--config '/tmp/config.json'") {
t.Fatalf("endpoint config env was not added: %s", text)
}
if !strings.Contains(text, `"afterAgentThought"`) || !strings.Contains(text, "agent-thought") {
@@ -130,10 +132,10 @@ func TestInstallCursorHooksJSONReplacesExistingBeaconHook(t *testing.T) {
if !strings.Contains(string(data), "echo keep") {
t.Fatalf("non-endpoint hook was not preserved: %s", string(data))
}
- if !strings.Contains(string(data), "'/tmp/new beacon-hooks'") || !strings.Contains(string(data), "BEACON_ENDPOINT_LOG=") || !strings.Contains(string(data), "runtime") {
+ if !strings.Contains(string(data), "'/tmp/new beacon-hooks'") || !strings.Contains(string(data), "--log ") || !strings.Contains(string(data), "runtime") {
t.Fatalf("command values were not shell-quoted: %s", string(data))
}
- if !strings.Contains(string(data), "BEACON_ENDPOINT_CONFIG='/tmp/config path.json'") {
+ if !strings.Contains(string(data), "--config '/tmp/config path.json'") {
t.Fatalf("endpoint config path was not shell-quoted: %s", string(data))
}
}
diff --git a/cli/beacon/internal/endpoint/hooks/devin_test.go b/cli/beacon/internal/endpoint/hooks/devin_test.go
index f7be9051..8f716991 100644
--- a/cli/beacon/internal/endpoint/hooks/devin_test.go
+++ b/cli/beacon/internal/endpoint/hooks/devin_test.go
@@ -26,9 +26,8 @@ func TestInstallDevinProjectHooksPreservesNonBeaconHooks(t *testing.T) {
text := string(data)
for _, want := range []string{
"echo keep",
- "BEACON_ENDPOINT_MODE=1",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
"'/tmp/beacon hooks' --platform devin",
"PermissionRequest",
"permission-request",
diff --git a/cli/beacon/internal/endpoint/hooks/factory_test.go b/cli/beacon/internal/endpoint/hooks/factory_test.go
index 700b0111..25b65730 100644
--- a/cli/beacon/internal/endpoint/hooks/factory_test.go
+++ b/cli/beacon/internal/endpoint/hooks/factory_test.go
@@ -30,9 +30,8 @@ func TestInstallFactorySettingsPreservesNonBeaconHooks(t *testing.T) {
"enabledPlugins",
"logoAnimation",
"echo keep",
- "BEACON_ENDPOINT_MODE=1",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
"'/tmp/beacon hooks' --platform factory",
"SessionStart",
"UserPromptSubmit",
@@ -270,7 +269,7 @@ func TestInstallFactoryUsesSystemConfigForSystemLog(t *testing.T) {
// identical, which is why the raw comparison held until Windows joined the gate.
//
// The resolved values are used rather than hardcoded strings, since both are per-OS.
- wantConfig := jsonFragment(t, "BEACON_ENDPOINT_CONFIG='"+endpointconfig.SystemConfigPath()+"'")
+ wantConfig := jsonFragment(t, "--config '"+endpointconfig.SystemConfigPath()+"'")
if !strings.Contains(string(data), wantConfig) {
t.Fatalf("Factory hook did not use system config for system log; want %s in:\n%s",
wantConfig, string(data))
diff --git a/cli/beacon/internal/endpoint/hooks/grok_test.go b/cli/beacon/internal/endpoint/hooks/grok_test.go
index ef91161d..aafd311c 100644
--- a/cli/beacon/internal/endpoint/hooks/grok_test.go
+++ b/cli/beacon/internal/endpoint/hooks/grok_test.go
@@ -41,10 +41,9 @@ func TestInstallGrokHooksWritesManagedHookFile(t *testing.T) {
}
command := groups[0].Hooks[0].Command
for _, want := range []string{
- "BEACON_ENDPOINT_MODE=1",
"--platform grok",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
commandName,
} {
if !strings.Contains(command, want) {
diff --git a/cli/beacon/internal/endpoint/hooks/hermes.go b/cli/beacon/internal/endpoint/hooks/hermes.go
index e2c3375e..17f63093 100644
--- a/cli/beacon/internal/endpoint/hooks/hermes.go
+++ b/cli/beacon/internal/endpoint/hooks/hermes.go
@@ -78,7 +78,7 @@ func installHermesConfig(path, binaryPath, logPath, configPath string) error {
if err != nil {
return err
}
- prefix := hermesEndpointCommandPrefix(binaryPath, logPath, configPath)
+ prefix := endpointCommandPrefix("hermes", binaryPath, logPath, configPath)
endpointHooks := map[string]hermesHookRef{
"on_session_start": {Command: prefix + " session-start"},
"pre_llm_call": {Command: prefix + " prompt-submit", Timeout: 30},
@@ -96,9 +96,17 @@ func installHermesConfig(path, binaryPath, logPath, configPath string) error {
return writeHermesConfig(path, config)
}
-func hermesEndpointCommandPrefix(binaryPath, logPath, configPath string) string {
- return fmt.Sprintf("env BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s BEACON_ENDPOINT_CONFIG=%s %s --platform hermes", shellQuote(logPath), shellQuote(configPath), shellQuote(binaryPath))
-}
+// Hermes used to need its own builder, and now it does not.
+//
+// It prefixed the command with `env`, which is what an inline `VAR=value cmd` prefix requires when the
+// command is executed without a shell to interpret it. Passing the settings as flags removes the need
+// for a prefix at all, so there is nothing left for `env` to set and the special case collapses into
+// the shared builder.
+//
+// One pre-existing question this does not answer: if Hermes really does invoke without a shell, the
+// quoting around each path is literal there rather than syntax. That was equally true of the old form,
+// and Hermes is not a runtime this repository can exercise, so it stays as it was rather than being
+// changed on a guess.
func readHermesConfig(path string) (hermesConfig, error) {
config := hermesConfig{
diff --git a/cli/beacon/internal/endpoint/hooks/hermes_test.go b/cli/beacon/internal/endpoint/hooks/hermes_test.go
index cc169c14..f2838761 100644
--- a/cli/beacon/internal/endpoint/hooks/hermes_test.go
+++ b/cli/beacon/internal/endpoint/hooks/hermes_test.go
@@ -30,15 +30,25 @@ hooks:
t.Fatalf("read config: %v", err)
}
text := string(data)
+ // The command now begins with a quote, so the YAML emitter single-quotes the whole scalar and
+ // doubles the quotes inside it. The value a parser hands back is unchanged, which is what the hook
+ // assertions below are about -- so they are made against that rather than against the on-disk
+ // escaping. The preserved-settings assertions stay on the raw text, where the escaping is the point.
+ parsed := strings.ReplaceAll(text, "''", "'")
+ for _, want := range []string{
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
+ "'/tmp/beacon hooks' --platform hermes",
+ } {
+ if !strings.Contains(parsed, want) {
+ t.Fatalf("Hermes hook command missing %q:\n%s", want, text)
+ }
+ }
for _, want := range []string{
"model:",
"anthropic/claude-sonnet-4.6",
"hooks_auto_accept: true",
"~/.hermes/agent-hooks/user-policy.sh",
- "env BEACON_ENDPOINT_MODE=1",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
- "'/tmp/beacon hooks' --platform hermes",
"on_session_start:",
"pre_llm_call:",
"pre_tool_call:",
diff --git a/cli/beacon/internal/endpoint/hooks/opencode_test.go b/cli/beacon/internal/endpoint/hooks/opencode_test.go
index bfc42a46..e401686d 100644
--- a/cli/beacon/internal/endpoint/hooks/opencode_test.go
+++ b/cli/beacon/internal/endpoint/hooks/opencode_test.go
@@ -22,11 +22,10 @@ func TestInstallOpenCodePluginWritesManagedPlugin(t *testing.T) {
opencodeManagedPluginMarker,
"BeaconEndpointPlugin",
"BEACON_OPENCODE_DEBUG",
- "BEACON_ENDPOINT_MODE=1",
"--platform opencode",
"opencode-event",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
"forwardedEvents",
"tool.execute.before",
"tool.execute.after",
diff --git a/cli/beacon/internal/endpoint/hooks/runtime.go b/cli/beacon/internal/endpoint/hooks/runtime.go
index f892d886..75c74f13 100644
--- a/cli/beacon/internal/endpoint/hooks/runtime.go
+++ b/cli/beacon/internal/endpoint/hooks/runtime.go
@@ -111,12 +111,49 @@ func isRuntimeInstalled(runtime hookRuntime, opts RuntimeOptions) bool {
return runtime.isInstalled(configPath)
}
+// endpointCommandPrefix builds the command a runtime will execute for each hook.
+//
+// The three endpoint settings are passed as flags rather than as an inline `VAR=value cmd` prefix.
+// That prefix is a POSIX shell construct: valid in sh, bash and zsh, and not valid in cmd.exe or
+// PowerShell, so it cannot deliver anything on a Windows runtime that uses either. Flags carry the
+// same values with no shell semantics involved beyond quoting the paths.
+//
+// What a runtime actually does with this string was measured rather than assumed, because it decides
+// the quoting and there is no form that works everywhere. Claude Code on Windows runs hook commands
+// through Git Bash -- $BASH_VERSION expands, %COMSPEC% does not -- so the string is parsed by a POSIX
+// shell on all three platforms for that runtime. Two results from the same measurement shape the code
+// below: a quoted executable path followed by flags runs correctly, and an *unquoted* Windows path
+// does not run at all, because bash consumes the backslashes as escapes.
func endpointCommandPrefix(platform, binaryPath, logPath, configPath string) string {
- cliEnv := ""
+ args := []string{hookCommandQuote(binaryPath), "--platform", platform}
+ if logPath != "" {
+ args = append(args, "--log", hookCommandQuote(logPath))
+ }
+ if configPath != "" {
+ args = append(args, "--config", hookCommandQuote(configPath))
+ }
+ // Best-effort: the CLI path only enables the inventory heartbeat, and a hook with no --cli
+ // still captures everything else.
if cliPath, err := os.Executable(); err == nil && cliPath != "" {
- cliEnv = " BEACON_ENDPOINT_CLI=" + shellQuote(cliPath)
+ args = append(args, "--cli", hookCommandQuote(cliPath))
}
- return fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s BEACON_ENDPOINT_CONFIG=%s%s %s --platform %s", shellQuote(logPath), shellQuote(configPath), cliEnv, shellQuote(binaryPath), platform)
+ return strings.Join(args, " ")
+}
+
+// hookCommandQuote quotes one value for the shell that will parse this command.
+//
+// Single quotes, on every platform. In a POSIX shell they are fully literal, which is what a Windows
+// path needs: inside double quotes bash still processes `$`, a backtick, and a doubled backslash, so
+// a profile directory containing a `$` would be expanded away and a UNC path would lose a separator.
+// Single quotes have no such cases, and the measurement that showed Claude Code uses bash on Windows
+// is what makes them the right choice there too.
+//
+// The cost is stated rather than hidden: this is not valid quoting in cmd.exe, and in PowerShell a
+// quoted string in command position is an expression rather than a command. A Windows runtime that
+// invokes hooks through either would need a different form -- so if one turns up, this is the function
+// that grows a per-runtime branch, and the detection side already accepts both spellings.
+func hookCommandQuote(value string) string {
+ return "'" + strings.ReplaceAll(value, "'", `'\''`) + "'"
}
// isEndpointHookCommand decides whether a command already in a runtime's config is one Beacon wrote.
diff --git a/cli/beacon/internal/endpoint/hooks/vscode_test.go b/cli/beacon/internal/endpoint/hooks/vscode_test.go
index f867f027..18dd30d2 100644
--- a/cli/beacon/internal/endpoint/hooks/vscode_test.go
+++ b/cli/beacon/internal/endpoint/hooks/vscode_test.go
@@ -25,9 +25,8 @@ func TestInstallVSCodeHooksPreservesNonBeaconHooks(t *testing.T) {
text := string(data)
for _, want := range []string{
"echo keep",
- "BEACON_ENDPOINT_MODE=1",
- "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
- "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ "--log '/tmp/runtime.jsonl'",
+ "--config '/tmp/config.json'",
"'/tmp/beacon hooks' --platform vscode",
"SessionStart",
"UserPromptSubmit",