Skip to content

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

add grok

Justin D'Souzaebe361968821
diff --git a/README.md b/README.md
index 0b481e41..c28b598e 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ Beacon is [Asymptote's open-source endpoint agent](https://justindsouza.substack
need visibility into local AI agent activity.
It runs locally, captures supported activity from local agent harnesses like
-Claude Code, Codex CLI, Gemini CLI, OpenCode, Devin, Factory Droid, Claude
+Claude Code, Codex CLI, Gemini CLI, Grok Build, OpenCode, Devin, Factory Droid, Claude
Cowork, OpenClaw Gateway, and Cursor, then normalizes that activity into endpoint
events your team can inspect and retain locally.
@@ -57,6 +57,7 @@ security pipelines.
| Claude Code | Local OpenTelemetry configuration |
| Codex CLI | Local OpenTelemetry configuration |
| Gemini CLI | Opt-in local OpenTelemetry configuration |
+| Grok Build | Beacon hook adapter |
| OpenCode | Beacon hook adapter |
| Devin | Beacon hook adapter |
| Factory Droid | Local OpenTelemetry configuration and optional hook adapter |
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index 9c9faed4..c9514724 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -15,6 +15,9 @@ func emitHookEvent(logger *logging.Logger, action, category, severity, message s
if fields == nil {
fields = map[string]interface{}{}
}
+ if platformFlag == "grok" {
+ fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"grok": input})
+ }
if model := getFirstStr(input, "model"); model != "" {
fields["model"] = model
}
@@ -132,6 +135,19 @@ func fileOperation(toolName string) string {
func actionForTool(hookEvent, toolName string) string {
lower := strings.ToLower(toolName)
+ if platformFlag == "grok" {
+ switch lower {
+ case "run_terminal_cmd":
+ return "command.executed"
+ case "read_file":
+ return "file.read"
+ case "search_replace", "write_file":
+ return "file.modified"
+ }
+ if hookEvent == "post_tool_use_failure" {
+ return "tool.failed"
+ }
+ }
if platformFlag == "devin" {
switch {
case strings.HasPrefix(lower, "mcp__"):
diff --git a/cli/beacon-hooks/cmd/grok_hooks_test.go b/cli/beacon-hooks/cmd/grok_hooks_test.go
new file mode 100644
index 00000000..6578fcf1
--- /dev/null
+++ b/cli/beacon-hooks/cmd/grok_hooks_test.go
@@ -0,0 +1,145 @@
+package cmd
+
+import (
+ "path/filepath"
+ "testing"
+)
+
+func TestGrokPromptSubmitRecordsPromptAndRawPayload(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "grok"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_MODE", "1")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_CONTENT_RETENTION", "full")
+
+ out := runHookWithInput(t, runPromptSubmit, map[string]interface{}{
+ "hookEventName": "user_prompt_submit",
+ "sessionId": "grok-session-1",
+ "workspaceRoot": "/tmp/grok-project",
+ "prompt": "summarize token=grok-secret",
+ })
+ if len(out) != 0 {
+ t.Fatalf("response = %#v, want empty object", out)
+ }
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "prompt.submitted" {
+ t.Fatalf("event.action = %q, want prompt.submitted", action)
+ }
+ if harness := event["harness"].(map[string]interface{})["name"]; harness != "grok" {
+ t.Fatalf("harness.name = %q, want grok", harness)
+ }
+ if got := event["prompt"].(map[string]interface{})["text"]; got != "summarize token=[REDACTED]" {
+ t.Fatalf("prompt.text = %q, want redacted prompt", got)
+ }
+ if got := event["session"].(map[string]interface{})["working_directory"]; got != "/tmp/grok-project" {
+ t.Fatalf("working_directory = %q, want workspace root", got)
+ }
+ if _, ok := event["raw"].(map[string]interface{})["grok"]; !ok {
+ t.Fatalf("raw.grok payload missing: %#v", event["raw"])
+ }
+}
+
+func TestGrokMetadataRetentionOmitsPromptAndRawPayload(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "grok"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_MODE", "1")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_CONTENT_RETENTION", "metadata")
+
+ runHookWithInput(t, runPromptSubmit, map[string]interface{}{
+ "hookEventName": "user_prompt_submit",
+ "sessionId": "grok-session-1",
+ "prompt": "secret prompt",
+ })
+ event := lastEndpointEvent(t, logPath)
+ if _, ok := event["prompt"]; ok {
+ t.Fatalf("metadata retention should omit prompt: %#v", event["prompt"])
+ }
+ raw := event["raw"].(map[string]interface{})
+ if _, ok := raw["grok"]; ok {
+ t.Fatalf("metadata retention should omit raw grok payload: %#v", raw)
+ }
+}
+
+func TestGrokPreToolRecordsToolAndAllows(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "grok"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_MODE", "1")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ out := runHookWithInput(t, runPreTool, map[string]interface{}{
+ "hookEventName": "pre_tool_use",
+ "sessionId": "grok-session-1",
+ "workspaceRoot": "/tmp/grok-project",
+ "toolName": "run_terminal_cmd",
+ "toolInput": map[string]interface{}{
+ "command": "npm test",
+ },
+ })
+ if got := out["decision"]; got != "allow" {
+ t.Fatalf("decision = %q, want allow", got)
+ }
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "tool.invoked" {
+ t.Fatalf("event.action = %q, want tool.invoked", action)
+ }
+ tool := event["tool"].(map[string]interface{})
+ if tool["name"] != "run_terminal_cmd" || tool["command"] != "npm test" {
+ t.Fatalf("tool fields = %#v, want name and command", tool)
+ }
+ if command := event["command"].(map[string]interface{})["command"]; command != "npm test" {
+ t.Fatalf("command = %q, want npm test", command)
+ }
+}
+
+func TestGrokPostToolMapsCommandAndFailure(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "grok"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_MODE", "1")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ runHookWithInput(t, runPostTool, map[string]interface{}{
+ "hookEventName": "post_tool_use",
+ "sessionId": "grok-session-1",
+ "toolName": "run_terminal_cmd",
+ "toolInput": map[string]interface{}{
+ "command": "go test ./...",
+ },
+ })
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "command.executed" {
+ t.Fatalf("event.action = %q, want command.executed", action)
+ }
+
+ runHookWithInput(t, runPostTool, map[string]interface{}{
+ "hookEventName": "post_tool_use_failure",
+ "sessionId": "grok-session-1",
+ "toolName": "unknown_tool",
+ })
+ event = lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "tool.failed" {
+ t.Fatalf("failure event.action = %q, want tool.failed", action)
+ }
+}
+
+func TestGrokCwdFallsBackToEnvironment(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "grok"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_MODE", "1")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("GROK_WORKSPACE_ROOT", "/tmp/grok-env-project")
+
+ runHookWithInput(t, runSessionStart, map[string]interface{}{
+ "hookEventName": "session_start",
+ "sessionId": "grok-session-1",
+ })
+ event := lastEndpointEvent(t, logPath)
+ if got := event["session"].(map[string]interface{})["working_directory"]; got != "/tmp/grok-env-project" {
+ t.Fatalf("working_directory = %q, want env workspace root", got)
+ }
+}
diff --git a/cli/beacon-hooks/cmd/helpers.go b/cli/beacon-hooks/cmd/helpers.go
index 55f4eeee..158b57a4 100644
--- a/cli/beacon-hooks/cmd/helpers.go
+++ b/cli/beacon-hooks/cmd/helpers.go
@@ -53,6 +53,8 @@ func resolveSessionID(input map[string]interface{}, platform string) string {
return getFirstStr(input, "conversation_id")
case "devin":
return getFirstStr(input, "session_id", "sessionId", "conversation_id")
+ case "grok":
+ return getFirstStr(input, "sessionId", "session_id", "sessionID")
case "opencode":
return getFirstStr(input, "session_id", "sessionID")
default:
@@ -80,6 +82,9 @@ func resolveSessionIDWithTranscript(input map[string]interface{}, platform strin
sessionID = getFirstStr(input, "session_id", "sessionId", "conversation_id")
transcriptPath = getFirstStr(input, "transcript_path", "transcriptPath")
return
+ case "grok":
+ sessionID = getFirstStr(input, "sessionId", "session_id", "sessionID")
+ return
case "opencode":
sessionID = getFirstStr(input, "session_id", "sessionID")
return
@@ -129,6 +134,12 @@ func resolveCwd(input map[string]interface{}, platform string) string {
}
return os.Getenv("DEVIN_PROJECT_DIR")
}
+ if platform == "grok" {
+ if cwd := getFirstStr(input, "workspaceRoot", "workspace_root", "cwd"); cwd != "" {
+ return cwd
+ }
+ return os.Getenv("GROK_WORKSPACE_ROOT")
+ }
cwd, _ := input["cwd"].(string)
return cwd
}
diff --git a/cli/beacon-hooks/cmd/post_tool.go b/cli/beacon-hooks/cmd/post_tool.go
index eaeffa5f..fd26c9f8 100644
--- a/cli/beacon-hooks/cmd/post_tool.go
+++ b/cli/beacon-hooks/cmd/post_tool.go
@@ -119,7 +119,7 @@ func parseClaudeCopilotInput(input map[string]interface{}, logger *logging.Logge
var sessionID, toolName string
var toolInput, toolResponse map[string]interface{}
- if platformFlag == "copilot" || platformFlag == "devin" {
+ if platformFlag == "copilot" || platformFlag == "devin" || platformFlag == "grok" {
sessionID = resolveSessionID(input, platformFlag)
toolName = getFirstStr(input, "toolName", "tool_name")
toolInput = resolveToolInput(input)
@@ -185,6 +185,9 @@ func resolveToolInput(input map[string]interface{}) map[string]interface{} {
if m, ok := input["tool_input"].(map[string]interface{}); ok {
return m
}
+ if m, ok := input["toolInput"].(map[string]interface{}); ok {
+ return m
+ }
// Fallback: some Copilot versions send toolArgs as stringified JSON
if argsStr, ok := input["toolArgs"].(string); ok && argsStr != "" {
var parsed map[string]interface{}
@@ -203,6 +206,9 @@ func resolveToolResponse(input map[string]interface{}) map[string]interface{} {
if m, ok := input["tool_response"].(map[string]interface{}); ok {
return m
}
+ if m, ok := input["toolResponse"].(map[string]interface{}); ok {
+ return m
+ }
if m, ok := input["toolResult"].(map[string]interface{}); ok {
return m
}
@@ -215,7 +221,7 @@ func resolveToolResponse(input map[string]interface{}) map[string]interface{} {
func emitPostToolObserved(logger *logging.Logger, input map[string]interface{}) {
toolName := getFirstStr(input, "tool_name", "toolName")
- hookEvent := getFirstStr(input, "hook_event_name")
+ hookEvent := getFirstStr(input, "hook_event_name", "hookEventName")
toolInput := resolveToolInput(input)
if toolInput == nil {
if nested, ok := input["tool_input"].(map[string]interface{}); ok {
@@ -263,5 +269,9 @@ func isFileEditTool(platform, toolName string) bool {
lower := strings.ToLower(toolName)
return lower == "edit" || lower == "write"
}
+ if platform == "grok" {
+ lower := strings.ToLower(toolName)
+ return lower == "search_replace" || lower == "write_file" || strings.Contains(lower, "edit") || strings.Contains(lower, "write")
+ }
return toolName == "Write" || toolName == "Edit" || toolName == "MultiEdit"
}
diff --git a/cli/beacon-hooks/cmd/pre_tool.go b/cli/beacon-hooks/cmd/pre_tool.go
index fa7cb72d..efcd337c 100644
--- a/cli/beacon-hooks/cmd/pre_tool.go
+++ b/cli/beacon-hooks/cmd/pre_tool.go
@@ -37,7 +37,7 @@ func runPreTool(cmd *cobra.Command, args []string) {
}
logger.Debug("Pre-tool observed")
- if platformFlag == "devin" {
+ if platformFlag == "devin" || platformFlag == "grok" {
emitPreToolObserved(logger, input, sessionID)
} else {
emitPreToolDecision(logger, input, sessionID, "approval.allowed", "allow", "Pre-tool observed")
@@ -61,6 +61,9 @@ func emitPreToolDecision(logger *logging.Logger, input map[string]interface{}, s
}
func preToolResponse() map[string]interface{} {
+ if platformFlag == "grok" {
+ return map[string]interface{}{"decision": "allow"}
+ }
if platformFlag == "devin" {
return emptyResponse
}
diff --git a/cli/beacon-hooks/cmd/pre_tool_test.go b/cli/beacon-hooks/cmd/pre_tool_test.go
index 046566f9..21b026e6 100644
--- a/cli/beacon-hooks/cmd/pre_tool_test.go
+++ b/cli/beacon-hooks/cmd/pre_tool_test.go
@@ -320,6 +320,7 @@ func setupHookConfigDirs(t *testing.T) {
origCursorDir := hookconfig.CursorDir
origDevinDir := hookconfig.DevinDir
origFactoryDir := hookconfig.FactoryDir
+ origGrokDir := hookconfig.GrokDir
origOpenCodeDir := hookconfig.OpenCodeDir
origPlatform := platformFlag
hookconfig.BeaconDir = tmp
@@ -328,6 +329,7 @@ func setupHookConfigDirs(t *testing.T) {
hookconfig.CursorDir = filepath.Join(tmp, "cursor")
hookconfig.DevinDir = filepath.Join(tmp, "devin")
hookconfig.FactoryDir = filepath.Join(tmp, "factory")
+ hookconfig.GrokDir = filepath.Join(tmp, "grok")
hookconfig.OpenCodeDir = filepath.Join(tmp, "opencode")
t.Cleanup(func() {
hookconfig.BeaconDir = origBeaconDir
@@ -336,6 +338,7 @@ func setupHookConfigDirs(t *testing.T) {
hookconfig.CursorDir = origCursorDir
hookconfig.DevinDir = origDevinDir
hookconfig.FactoryDir = origFactoryDir
+ hookconfig.GrokDir = origGrokDir
hookconfig.OpenCodeDir = origOpenCodeDir
platformFlag = origPlatform
})
diff --git a/cli/beacon-hooks/cmd/prompt_submit.go b/cli/beacon-hooks/cmd/prompt_submit.go
index 85ad4857..2998b6ee 100644
--- a/cli/beacon-hooks/cmd/prompt_submit.go
+++ b/cli/beacon-hooks/cmd/prompt_submit.go
@@ -42,7 +42,7 @@ func runPromptSubmit(cmd *cobra.Command, args []string) {
logger.Debug("Prompt submit observed")
fields := sessionFields(sessionID, input)
if config.ContentRetentionMode() != config.ContentRetentionMetadata {
- if prompt := getFirstStr(input, "prompt", "user_prompt", "text"); prompt != "" {
+ if prompt := getFirstStr(input, "prompt", "user_prompt", "text", "promptText"); prompt != "" {
fields["prompt"] = map[string]interface{}{"text": prompt}
}
}
diff --git a/cli/beacon-hooks/cmd/root.go b/cli/beacon-hooks/cmd/root.go
index 545bef94..c06cd808 100644
--- a/cli/beacon-hooks/cmd/root.go
+++ b/cli/beacon-hooks/cmd/root.go
@@ -11,8 +11,8 @@ var platformFlag string
var rootCmd = &cobra.Command{
Use: "beacon-hooks",
- Short: "Beacon hooks for Claude Code, GitHub Copilot, Cursor, Devin, Factory, and opencode",
- Long: `Beacon hooks binary for Claude Code, GitHub Copilot, Cursor, Devin, Factory, and opencode integration.
+ Short: "Beacon hooks for Claude Code, GitHub Copilot, Cursor, Devin, Factory, Grok, and opencode",
+ Long: `Beacon hooks binary for Claude Code, GitHub Copilot, Cursor, Devin, Factory, Grok, and opencode integration.
This binary provides hook commands that are called by IDE plugin systems
to evaluate code changes for security violations.
@@ -21,7 +21,7 @@ Use --platform to specify the calling platform (default: claude).`,
}
func init() {
- rootCmd.PersistentFlags().StringVar(&platformFlag, "platform", "claude", "Platform context: claude, copilot, cursor, devin, factory, or opencode")
+ rootCmd.PersistentFlags().StringVar(&platformFlag, "platform", "claude", "Platform context: claude, copilot, cursor, devin, factory, grok, or opencode")
}
// Execute runs the root command
diff --git a/cli/beacon-hooks/internal/config/config.go b/cli/beacon-hooks/internal/config/config.go
index f311bbe1..1547d08f 100644
--- a/cli/beacon-hooks/internal/config/config.go
+++ b/cli/beacon-hooks/internal/config/config.go
@@ -15,6 +15,7 @@ var (
CursorDir = filepath.Join(BeaconDir, "cursor")
DevinDir = filepath.Join(BeaconDir, "devin")
FactoryDir = filepath.Join(BeaconDir, "factory")
+ GrokDir = filepath.Join(BeaconDir, "grok")
OpenCodeDir = filepath.Join(BeaconDir, "opencode")
)
@@ -93,6 +94,8 @@ func GetStateDir(platform string) string {
return DevinDir
case "factory":
return FactoryDir
+ case "grok":
+ return GrokDir
case "opencode":
return OpenCodeDir
default:
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 914171aa..c7e6538e 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -69,6 +69,9 @@ that may need review.
./beacon endpoint hooks install --harness opencode
./beacon endpoint hooks status --harness opencode
+./beacon endpoint hooks install --harness grok
+./beacon endpoint hooks status --harness grok
+
./beacon endpoint hooks install --harness devin --level project
./beacon endpoint hooks status --harness devin --level project
@@ -88,6 +91,11 @@ normalization, retention, redaction, and JSONL output locally. For local
troubleshooting, set `BEACON_OPENCODE_DEBUG=1` in the environment that launches
opencode to emit best-effort plugin debug logs.
+The Grok Build integration writes Beacon's owned local hook file at
+`~/.grok/hooks/beacon.json` for user-level installs or `.grok/hooks/beacon.json`
+for project-level installs. Project hooks require trusting the project in Grok
+with `/hooks-trust` before they execute.
+
The Devin integration writes Claude-compatible command hooks for Devin for
Terminal. Project-level installs use `.devin/hooks.v1.json`; user-level installs
use `~/.config/devin/config.json` under the `hooks` key. The hooks invoke
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 989fc136..832d0345 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -523,6 +523,19 @@ func runEndpointHooksInstall(cmd *cobra.Command, args []string) error {
return err
}
fmt.Printf("opencode plugin installed: %s\n", status.PluginPath)
+ case "grok":
+ status, err := endpointhooks.InstallGrok(endpointhooks.GrokOptions{
+ Level: endpointhooks.Level(endpointOpts.hookLevel),
+ LogPath: cfg.LogPath,
+ UserMode: cfg.UserMode,
+ })
+ if err != nil {
+ return err
+ }
+ fmt.Printf("Grok hooks installed: %s\n", status.HooksPath)
+ if strings.Contains(status.Message, "/hooks-trust") {
+ fmt.Println(status.Message)
+ }
case "devin":
status, err := endpointhooks.InstallDevin(endpointhooks.DevinOptions{
Level: endpointhooks.Level(endpointOpts.hookLevel),
@@ -575,6 +588,16 @@ func runEndpointHooksUninstall(cmd *cobra.Command, args []string) error {
return err
}
fmt.Println(status.Message)
+ case "grok":
+ status, err := endpointhooks.UninstallGrok(endpointhooks.GrokOptions{
+ Level: endpointhooks.Level(endpointOpts.hookLevel),
+ LogPath: cfg.LogPath,
+ UserMode: cfg.UserMode,
+ })
+ if err != nil {
+ return err
+ }
+ fmt.Println(status.Message)
case "devin":
status, err := endpointhooks.UninstallDevin(endpointhooks.DevinOptions{
Level: endpointhooks.Level(endpointOpts.hookLevel),
@@ -616,6 +639,12 @@ func runEndpointHooksStatus(cmd *cobra.Command, args []string) error {
LogPath: cfg.LogPath,
UserMode: cfg.UserMode,
})
+ case "grok":
+ statuses["grok"] = endpointhooks.GrokHookStatus(endpointhooks.GrokOptions{
+ Level: endpointhooks.Level(endpointOpts.hookLevel),
+ LogPath: cfg.LogPath,
+ UserMode: cfg.UserMode,
+ })
case "devin":
statuses["devin"] = endpointhooks.DevinHookStatus(endpointhooks.DevinOptions{
Level: endpointhooks.Level(endpointOpts.hookLevel),
@@ -644,6 +673,10 @@ func runEndpointHooksStatus(cmd *cobra.Command, args []string) error {
status := statuses["opencode"].(endpointhooks.OpenCodeStatus)
fmt.Printf("opencode plugin: installed=%t path=%s\n", status.Installed, status.PluginPath)
fmt.Println(status.Message)
+ case "grok":
+ status := statuses["grok"].(endpointhooks.GrokStatus)
+ fmt.Printf("Grok hooks: installed=%t path=%s\n", status.Installed, status.HooksPath)
+ fmt.Println(status.Message)
case "devin":
status := statuses["devin"].(endpointhooks.DevinStatus)
fmt.Printf("Devin hooks: installed=%t path=%s\n", status.Installed, status.ConfigPath)
diff --git a/cli/beacon/internal/embedded/hooks.bin b/cli/beacon/internal/embedded/hooks.bin
index 8adea8cc..adf56310 100644
Binary files a/cli/beacon/internal/embedded/hooks.bin and b/cli/beacon/internal/embedded/hooks.bin differ
diff --git a/cli/beacon/internal/endpoint/dashboard/static/app.js b/cli/beacon/internal/endpoint/dashboard/static/app.js
index fd6a1ca5..a6bd3c00 100644
--- a/cli/beacon/internal/endpoint/dashboard/static/app.js
+++ b/cli/beacon/internal/endpoint/dashboard/static/app.js
@@ -567,6 +567,7 @@ function harnessLabel(value) {
cursor: "Cursor",
claude_code: "Claude Code",
codex_cli: "Codex CLI",
+ grok: "Grok Build",
cli: "Beacon CLI",
};
return labels[value] || value;
diff --git a/cli/beacon/internal/endpoint/hooks/grok.go b/cli/beacon/internal/endpoint/hooks/grok.go
new file mode 100644
index 00000000..9a1a5be1
--- /dev/null
+++ b/cli/beacon/internal/endpoint/hooks/grok.go
@@ -0,0 +1,178 @@
+package hooks
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+const grokManagedHookFileName = "beacon.json"
+
+type GrokOptions struct {
+ Level Level
+ LogPath string
+ UserMode bool
+}
+
+type GrokStatus struct {
+ Installed bool `json:"installed"`
+ BinaryPath string `json:"binary_path,omitempty"`
+ HooksPath string `json:"hooks_path,omitempty"`
+ Message string `json:"message,omitempty"`
+}
+
+type grokHooksFile struct {
+ Description string `json:"description,omitempty"`
+ Hooks map[string][]grokHookGroup `json:"hooks"`
+}
+
+type grokHookGroup struct {
+ Matcher string `json:"matcher,omitempty"`
+ Hooks []grokHookRef `json:"hooks"`
+}
+
+type grokHookRef struct {
+ Type string `json:"type"`
+ Command string `json:"command"`
+ Timeout int `json:"timeout,omitempty"`
+ Env map[string]string `json:"env,omitempty"`
+}
+
+var grokRuntime = hookRuntime{
+ displayName: "Grok",
+ configPath: grokHooksPath,
+ install: installGrokHooks,
+ uninstall: removeGrokHooks,
+ isInstalled: isGrokInstalledAt,
+}
+
+func InstallGrok(opts GrokOptions) (GrokStatus, error) {
+ status, err := installRuntimeHooks(grokRuntime, RuntimeOptions(opts))
+ if err != nil {
+ return GrokStatus{}, err
+ }
+ return grokProjectTrustMessage(grokStatusFromRuntime(status), opts.Level), nil
+}
+
+func UninstallGrok(opts GrokOptions) (GrokStatus, error) {
+ status, err := uninstallRuntimeHooks(grokRuntime, RuntimeOptions(opts))
+ if err != nil {
+ return GrokStatus{}, err
+ }
+ return grokStatusFromRuntime(status), nil
+}
+
+func GrokHookStatus(opts GrokOptions) GrokStatus {
+ return grokProjectTrustMessage(grokStatusFromRuntime(runtimeHookStatus(grokRuntime, RuntimeOptions(opts))), opts.Level)
+}
+
+func IsGrokInstalled(opts GrokOptions) bool {
+ return isRuntimeInstalled(grokRuntime, RuntimeOptions(opts))
+}
+
+func grokStatusFromRuntime(status runtimeStatus) GrokStatus {
+ return GrokStatus{
+ Installed: status.Installed,
+ BinaryPath: status.BinaryPath,
+ HooksPath: status.ConfigPath,
+ Message: status.Message,
+ }
+}
+
+func installGrokHooks(path, binaryPath, logPath, configPath string) error {
+ prefix := endpointCommandPrefix("grok", binaryPath, logPath, configPath)
+ hooks := grokHooksFile{
+ Description: "Beacon managed Grok endpoint telemetry hooks.",
+ Hooks: map[string][]grokHookGroup{
+ "SessionStart": {{Hooks: []grokHookRef{{Type: "command", Command: prefix + " session-start"}}}},
+ "UserPromptSubmit": {{Hooks: []grokHookRef{{Type: "command", Command: prefix + " prompt-submit", Timeout: 30}}}},
+ "PreToolUse": {{Hooks: []grokHookRef{{Type: "command", Command: prefix + " pre-tool", Timeout: 10}}}},
+ "PostToolUse": {{Hooks: []grokHookRef{{Type: "command", Command: prefix + " post-tool", Timeout: 10}}}},
+ "PostToolUseFailure": {
+ {Hooks: []grokHookRef{{Type: "command", Command: prefix + " post-tool", Timeout: 10}}},
+ },
+ "Stop": {{Hooks: []grokHookRef{{Type: "command", Command: prefix + " stop", Timeout: 45}}}},
+ "SessionEnd": {{Hooks: []grokHookRef{{Type: "command", Command: prefix + " session-end"}}}},
+ },
+ }
+ data, err := json.MarshalIndent(hooks, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(path, data, 0644)
+}
+
+func removeGrokHooks(path string) (bool, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return false, nil
+ }
+ return false, err
+ }
+ if !isGrokManagedHookFile(data) {
+ return false, nil
+ }
+ return true, os.Remove(path)
+}
+
+func isGrokInstalledAt(path string) bool {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return false
+ }
+ return isGrokManagedHookFile(data)
+}
+
+func isGrokManagedHookFile(data []byte) bool {
+ var hooks grokHooksFile
+ if err := json.Unmarshal(data, &hooks); err != nil {
+ return false
+ }
+ for _, groups := range hooks.Hooks {
+ for _, group := range groups {
+ for _, hook := range group.Hooks {
+ if isEndpointHookCommand(hook.Command, "grok") {
+ return true
+ }
+ }
+ }
+ }
+ return false
+}
+
+func grokHooksPath(level Level) (string, error) {
+ dir, err := grokHooksDir(level)
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(dir, grokManagedHookFileName), nil
+}
+
+func grokHooksDir(level Level) (string, error) {
+ switch level {
+ case "", LevelUser:
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(home, ".grok", "hooks"), nil
+ case LevelProject:
+ cwd, err := os.Getwd()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(cwd, ".grok", "hooks"), nil
+ default:
+ return "", fmt.Errorf("unknown hook level %q", level)
+ }
+}
+
+func grokProjectTrustMessage(status GrokStatus, level Level) GrokStatus {
+ if level == LevelProject && status.Message != "" && !strings.Contains(status.Message, "/hooks-trust") {
+ status.Message += "; run /hooks-trust in Grok before project hooks execute"
+ }
+ return status
+}
diff --git a/cli/beacon/internal/endpoint/hooks/grok_test.go b/cli/beacon/internal/endpoint/hooks/grok_test.go
new file mode 100644
index 00000000..f5278986
--- /dev/null
+++ b/cli/beacon/internal/endpoint/hooks/grok_test.go
@@ -0,0 +1,114 @@
+package hooks
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func TestInstallGrokHooksWritesManagedHookFile(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "beacon.json")
+ if err := installGrokHooks(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json"); err != nil {
+ t.Fatalf("installGrokHooks returned error: %v", err)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read Grok hooks: %v", err)
+ }
+ text := string(data)
+ for _, want := range []string{
+ "Beacon managed Grok endpoint telemetry hooks",
+ "SessionStart",
+ "UserPromptSubmit",
+ "PreToolUse",
+ "PostToolUseFailure",
+ "BEACON_ENDPOINT_MODE=1",
+ "--platform grok",
+ "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'",
+ "BEACON_ENDPOINT_CONFIG='/tmp/config.json'",
+ } {
+ if !strings.Contains(text, want) {
+ t.Fatalf("Grok hook file missing %q:\n%s", want, text)
+ }
+ }
+}
+
+func TestRemoveGrokHooksOnlyRemovesManagedHookFile(t *testing.T) {
+ dir := t.TempDir()
+ userHook := filepath.Join(dir, "user.json")
+ if err := os.WriteFile(userHook, []byte(`{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"echo keep"}]}]}}`), 0644); err != nil {
+ t.Fatalf("write user hook: %v", err)
+ }
+ changed, err := removeGrokHooks(userHook)
+ if err != nil {
+ t.Fatalf("removeGrokHooks returned error: %v", err)
+ }
+ if changed {
+ t.Fatal("user hook should not be removed")
+ }
+ if _, err := os.Stat(userHook); err != nil {
+ t.Fatalf("user hook was removed: %v", err)
+ }
+
+ managed := filepath.Join(dir, "beacon.json")
+ if err := installGrokHooks(managed, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json"); err != nil {
+ t.Fatalf("installGrokHooks returned error: %v", err)
+ }
+ changed, err = removeGrokHooks(managed)
+ if err != nil {
+ t.Fatalf("removeGrokHooks returned error: %v", err)
+ }
+ if !changed {
+ t.Fatal("expected managed hook removal")
+ }
+ if _, err := os.Stat(managed); !os.IsNotExist(err) {
+ t.Fatalf("managed hook still exists or unexpected error: %v", err)
+ }
+}
+
+func TestGrokHookPathLevels(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ if got, want := mustGrokHooksPath(t, LevelUser), filepath.Join(home, ".grok", "hooks", "beacon.json"); got != want {
+ t.Fatalf("user Grok hook path = %q, want %q", got, want)
+ }
+
+ project := t.TempDir()
+ t.Chdir(project)
+ if got, want := mustGrokHooksPath(t, LevelProject), filepath.Join(project, ".grok", "hooks", "beacon.json"); got != want {
+ t.Fatalf("project Grok hook path = %q, want %q", got, want)
+ }
+}
+
+func TestGrokProjectStatusMentionsTrust(t *testing.T) {
+ status := grokProjectTrustMessage(GrokStatus{Message: "Grok endpoint hooks installed"}, LevelProject)
+ if !strings.Contains(status.Message, "/hooks-trust") {
+ t.Fatalf("project status message = %q, want /hooks-trust guidance", status.Message)
+ }
+}
+
+func TestGrokInstalledUsesManagedEndpointCommand(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "beacon.json")
+ if err := os.WriteFile(path, []byte(`{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"BEACON_ENDPOINT_MODE=1 echo keep"}]}]}}`), 0644); err != nil {
+ t.Fatalf("write unmarked hook: %v", err)
+ }
+ if isGrokInstalledAt(path) {
+ t.Fatal("unmanaged hook should not be detected as installed")
+ }
+ if err := installGrokHooks(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json"); err != nil {
+ t.Fatalf("installGrokHooks returned error: %v", err)
+ }
+ if !isGrokInstalledAt(path) {
+ t.Fatal("managed Grok hook should be detected")
+ }
+}
+
+func mustGrokHooksPath(t *testing.T, level Level) string {
+ t.Helper()
+ path, err := grokHooksPath(level)
+ if err != nil {
+ t.Fatalf("grokHooksPath returned error: %v", err)
+ }
+ return path
+}
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index cd025840..92eb7ad1 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -116,12 +116,13 @@ Recommended rollout:
4. Scope repair/remediation to unhealthy devices.
5. Broaden deployment in stages after inventory and validation stay healthy.
-Cursor, Devin, Factory, and opencode hook installation is separate from the base
+Cursor, Devin, Factory, Grok Build, and opencode hook installation is separate from the base
system package because these integrations write per-user or per-project runtime
settings. Run hook helpers only when an interactive console user is present.
Cursor hooks use `.cursor/hooks.json`; Devin hooks use `.devin/hooks.v1.json`
for project installs or `~/.config/devin/config.json` for user installs; Factory
-hooks use `.factory/settings.json`; opencode uses Beacon's owned plugin at
+hooks use `.factory/settings.json`; Grok Build uses `.grok/hooks/beacon.json`
+or `~/.grok/hooks/beacon.json`; opencode uses Beacon's owned plugin at
`~/.config/opencode/plugins/beacon.ts`. Restart the runtime after installation
so new sessions pick up the settings. Install hooks with the same endpoint log
path as the collector when you want hook telemetry and OTLP telemetry to appear
@@ -154,6 +155,15 @@ the logged-in user's context:
beacon endpoint hooks install --harness opencode --level user --log-path /var/log/beacon-agent/runtime.jsonl
```
+For Grok Build session/prompt/tool telemetry, install Beacon's Grok hook file.
+User-level hooks are always trusted by Grok; project-level hooks require
+`/hooks-trust` in Grok before they execute:
+
+```bash
+beacon endpoint hooks install --harness grok --level user --log-path /var/log/beacon-agent/runtime.jsonl
+beacon endpoint hooks install --harness grok --level project --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
For Devin prompt/session/tool/approval/file telemetry, install Beacon's Devin
hooks in the logged-in user's context or project context:
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index 10e97351..b21d1edc 100644
--- a/packaging/macos/pkgbuild.md
+++ b/packaging/macos/pkgbuild.md
@@ -90,6 +90,16 @@ normalization, retention, redaction, and JSONL output. Set
`BEACON_OPENCODE_DEBUG=1` in the opencode launch environment only when
troubleshooting plugin delivery.
+Grok Build support is also installed separately in the target user's context:
+
+```bash
+beacon endpoint hooks install --harness grok --level user --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+This writes Beacon's owned hook file to `~/.grok/hooks/beacon.json`. Project
+installs write `.grok/hooks/beacon.json` and require `/hooks-trust` in Grok before
+hooks execute.
+
## Jamf Deployment
Upload the generated `.pkg` to Jamf Pro and create a Policy scoped to a pilot