Skip to content

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

handoff: add Grok Build

Claude332ba5dd4eaa
diff --git a/cli/beacon/internal/groksession/handoff_test.go b/cli/beacon/internal/groksession/handoff_test.go
new file mode 100644
index 00000000..5400a794
--- /dev/null
+++ b/cli/beacon/internal/groksession/handoff_test.go
@@ -0,0 +1,124 @@
+package groksession
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+func TestMapSessionRecordsAHandoffLink(t *testing.T) {
+ prompt := "Continue the work.\n\n" + asymptoteobserve.HandoffMarker("claude_code", "src-1")
+ marked, _ := json.Marshal([]map[string]string{{"type": "text", "text": prompt}})
+ plain, _ := json.Marshal("no marker here")
+ data := SessionData{
+ Ref: SessionRef{ID: "new-1", Workspace: "/work", SourcePath: "/tmp/grok/new-1"},
+ Chat: []ChatMessage{
+ {Type: "user", Content: marked, Index: 1},
+ {Type: "user", Content: plain, Index: 2},
+ },
+ }
+ mapped := MapSession(data, MapOptions{})
+ var links []MappedEvent
+ for _, m := range mapped {
+ if m.Event.Event.Action == "session.handoff" {
+ links = append(links, m)
+ }
+ }
+ if len(links) != 1 {
+ t.Fatalf("links = %d, want 1: %+v", len(links), mapped)
+ }
+ link := links[0]
+ if link.SourceKind != SourceChat || link.SourceLine != 1 || link.Event.Handoff == nil || link.Event.Handoff.SourceHarness != "claude_code" || link.Event.Handoff.SourceSessionID != "src-1" {
+ t.Fatalf("link = %+v handoff=%+v", link, link.Event.Handoff)
+ }
+ if link.Event.Session == nil || link.Event.Session.ID != "new-1" || link.Event.Session.WorkingDirectory != "/work" {
+ t.Fatalf("link session = %+v", link.Event.Session)
+ }
+ if link.Event.Harness.Name != Harness || link.Event.Harness.CollectionMethod != "poll" || link.Event.Event.Fidelity != "observed" {
+ t.Fatalf("link provenance = %+v %+v", link.Event.Harness, link.Event.Event)
+ }
+ if link.Event.Prompt != nil || link.Event.Content != nil || link.Event.GenAI != nil {
+ t.Fatalf("the link must not repeat the prompt: %+v", link.Event)
+ }
+ // Every other Grok event is named by the writer from its bytes; the link names itself, from
+ // where it was read, because its bytes carry the time of the sync.
+ if link.Event.Event.ID == "" {
+ t.Fatal("the link has no id")
+ }
+ again := MapSession(data, MapOptions{})
+ for _, m := range again {
+ if m.Event.Event.Action == "session.handoff" && m.Event.Event.ID != link.Event.Event.ID {
+ t.Fatal("the link's id must be deterministic, so reading the prompt again names the same link")
+ }
+ }
+ other := data
+ other.Ref.ID = "new-2"
+ for _, m := range MapSession(other, MapOptions{}) {
+ if m.Event.Event.Action == "session.handoff" && m.Event.Event.ID == link.Event.Event.ID {
+ t.Fatal("links in different sessions share an id")
+ }
+ }
+}
+
+// The collector's cursor is what keeps a second sync from writing the link again; when the cursor
+// is lost, the link written again carries the same event.id.
+func TestCollectOnceWritesTheHandoffLinkOnce(t *testing.T) {
+ root := t.TempDir()
+ sessionDir := writeFixtureSession(t, root, "/tmp/grok project", "session-1")
+ marker := asymptoteobserve.HandoffMarker("codex_cli", "019a-thread")
+ appendLine(t, filepath.Join(sessionDir, "chat_history.jsonl"),
+ `{"type":"user","content":[{"type":"text","text":"Read the brief.\n\n`+marker+`"}]}`)
+ statePath := filepath.Join(t.TempDir(), "state.json")
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ opts := CollectOptions{SessionsDir: root, StatePath: statePath, LogPath: logPath, Write: true, UserMode: true}
+
+ if _, err := CollectOnce(opts); err != nil {
+ t.Fatalf("first CollectOnce: %v", err)
+ }
+ touchNewer(t, sessionDir)
+ if _, err := CollectOnce(opts); err != nil {
+ t.Fatalf("second CollectOnce: %v", err)
+ }
+ if got := logActions(t, logPath)["session.handoff"]; got != 1 {
+ t.Fatalf("session.handoff written %d times, want 1", got)
+ }
+
+ if err := os.Remove(statePath); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := CollectOnce(opts); err != nil {
+ t.Fatalf("CollectOnce without state: %v", err)
+ }
+ ids := linkIDs(t, logPath)
+ if len(ids) != 2 || ids[0] == "" || ids[0] != ids[1] {
+ t.Fatalf("link ids = %q, want the same id both times", ids)
+ }
+}
+
+func linkIDs(t *testing.T, path string) []string {
+ t.Helper()
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var ids []string
+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+ var record struct {
+ Event struct {
+ ID string `json:"id"`
+ Action string `json:"action"`
+ } `json:"event"`
+ }
+ if err := json.Unmarshal([]byte(line), &record); err != nil {
+ t.Fatal(err)
+ }
+ if record.Event.Action == "session.handoff" {
+ ids = append(ids, record.Event.ID)
+ }
+ }
+ return ids
+}
diff --git a/cli/beacon/internal/groksession/mapper.go b/cli/beacon/internal/groksession/mapper.go
index 8a77377a..d6320fff 100644
--- a/cli/beacon/internal/groksession/mapper.go
+++ b/cli/beacon/internal/groksession/mapper.go
@@ -1,7 +1,11 @@
package groksession
import (
+ "crypto/sha1"
+ "encoding/hex"
"encoding/json"
+ "fmt"
+ "io"
"sort"
"strings"
"time"
@@ -88,6 +92,15 @@ func (m *mapper) consumeChat(msg ChatMessage) {
ev.Prompt = &schema.PromptInfo{Text: text}
ev.Content = contentMarker(text)
m.append(ev, SourceChat, msg.Index)
+ if info, ok := asymptoteobserve.ParseHandoffMarker(text); ok {
+ link := m.base("", "session.handoff", "session", schema.SeverityInfo, schema.FidelityObserved, "Session continued from a "+info.SourceHarness+" session")
+ link.Handoff = &info
+ // The writer derives an event's id from its bytes, and a chat line carries no time, so
+ // this link is stamped with the time of the sync. It names its id from where it was
+ // read instead, so reading the prompt again always yields the same link.
+ link.Event.ID = grokEventID(fmt.Sprintf("%s:%s:%d:handoff", m.data.Ref.ID, m.data.Ref.SourcePath, msg.Index))
+ m.append(link, SourceChat, msg.Index)
+ }
case "assistant":
model := firstNonEmpty(msg.ModelID, m.summary().CurrentModelID)
if msg.Reasoning != nil && msg.Reasoning.Text != "" {
@@ -456,6 +469,25 @@ func parseTime(ts string) time.Time {
return t
}
+var grokIDNamespace = [16]byte{
+ 0x6b, 0x2e, 0x91, 0x0c, 0x4f, 0xd3, 0x47, 0x58,
+ 0xa2, 0x1b, 0x7e, 0x93, 0x05, 0xc8, 0x3d, 0x61,
+}
+
+// grokEventID is a version 5 UUID of coordinate under grokIDNamespace.
+func grokEventID(coordinate string) string {
+ digest := sha1.New()
+ digest.Write(grokIDNamespace[:])
+ io.WriteString(digest, coordinate)
+ var id [16]byte
+ copy(id[:], digest.Sum(nil))
+ id[6] = (id[6] & 0x0f) | 0x50
+ id[8] = (id[8] & 0x3f) | 0x80
+ out := make([]byte, 32)
+ hex.Encode(out, id[:])
+ return fmt.Sprintf("%s-%s-%s-%s-%s", out[0:8], out[8:12], out[12:16], out[16:20], out[20:32])
+}
+
func firstNonEmpty(values ...string) string {
for _, value := range values {
if strings.TrimSpace(value) != "" {
diff --git a/cli/beacon/internal/handoff/grok.go b/cli/beacon/internal/handoff/grok.go
new file mode 100644
index 00000000..950469fc
--- /dev/null
+++ b/cli/beacon/internal/handoff/grok.go
@@ -0,0 +1,119 @@
+package handoff
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/groksession"
+)
+
+// Grok Build keeps one directory per session, named by the session's id, under a directory named
+// for the working directory it ran in. summary.json indexes the session.
+
+type grokSource struct{ dir string }
+
+func (s *grokSource) Harness() string { return HarnessGrok }
+
+// store reads dir as Grok's sessions directory, as `beacon endpoint grok sync --sessions-dir` does.
+func (s *grokSource) store() (*groksession.Store, error) { return groksession.NewStore(s.dir) }
+
+func (s *grokSource) List() ([]Session, error) {
+ store, err := s.store()
+ if err != nil {
+ return nil, err
+ }
+ if !store.Exists() {
+ return nil, nil
+ }
+ refs, err := store.List()
+ if err != nil {
+ return nil, err
+ }
+ sessions := make([]Session, 0, len(refs))
+ for _, ref := range refs {
+ var summary groksession.Summary
+ if ref.Summary != nil {
+ summary = *ref.Summary
+ }
+ title := oneLine(firstNonEmpty(summary.GeneratedTitle, summary.SessionSummary))
+ if title == "" {
+ title = oneLine(readGrokFirstPrompt(filepath.Join(ref.SourcePath, "chat_history.jsonl")))
+ }
+ sessions = append(sessions, Session{
+ Harness: HarnessGrok,
+ ID: ref.ID,
+ Title: title,
+ Directory: grokWorkingDirectory(ref),
+ Branch: strings.TrimSpace(summary.HeadBranch),
+ SourcePath: ref.SourcePath,
+ UpdatedAt: unixMS(ref.ModTimeUnixMS),
+ // Grok reserves the subagent namespace of session kinds for the child sessions it
+ // spawns, which live in the same sessions tree as the sessions a person started.
+ Subagent: strings.HasPrefix(strings.ToLower(strings.TrimSpace(summary.SessionKind)), "subagent"),
+ })
+ }
+ return sessions, nil
+}
+
+func (s *grokSource) Events(session Session) ([]schema.Event, error) {
+ store, err := s.store()
+ if err != nil {
+ return nil, err
+ }
+ refs, err := store.List()
+ if err != nil {
+ return nil, err
+ }
+ for _, ref := range refs {
+ if ref.ID != session.ID || ref.SourcePath != session.SourcePath {
+ continue
+ }
+ data, _, err := store.Read(ref)
+ if err != nil {
+ return nil, err
+ }
+ mapped := groksession.MapSession(data, groksession.MapOptions{})
+ events := make([]schema.Event, 0, len(mapped))
+ for _, m := range mapped {
+ events = append(events, m.Event)
+ }
+ return events, nil
+ }
+ return nil, errSessionGone(session)
+}
+
+// grokWorkingDirectory is where the session ran. The store names its group directory by the
+// URL-encoded working directory, but a path too long for one directory name becomes a slug, so the
+// session's prompt_context.json, which records the directory itself, is preferred, as the sync's
+// own read does.
+func grokWorkingDirectory(ref groksession.SessionRef) string {
+ data, err := os.ReadFile(filepath.Join(ref.SourcePath, "prompt_context.json"))
+ if err == nil {
+ var prompt groksession.PromptContext
+ if json.Unmarshal(data, &prompt) == nil && strings.TrimSpace(prompt.WorkingDirectory) != "" {
+ return prompt.WorkingDirectory
+ }
+ }
+ return ref.Workspace
+}
+
+// readGrokFirstPrompt returns the first thing a person typed in a Grok chat history.
+func readGrokFirstPrompt(path string) string {
+ var prompt string
+ scanHead(path, func(line []byte) bool {
+ var msg struct {
+ Type string `json:"type"`
+ Content json.RawMessage `json:"content"`
+ SyntheticReason string `json:"synthetic_reason"`
+ }
+ if json.Unmarshal(line, &msg) != nil || msg.Type != "user" || msg.SyntheticReason != "" {
+ return false
+ }
+ prompt = piContentText(msg.Content)
+ return prompt != ""
+ })
+ return prompt
+}
diff --git a/cli/beacon/internal/handoff/grok_test.go b/cli/beacon/internal/handoff/grok_test.go
new file mode 100644
index 00000000..612cb437
--- /dev/null
+++ b/cli/beacon/internal/handoff/grok_test.go
@@ -0,0 +1,205 @@
+package handoff
+
+import (
+ "errors"
+ "net/url"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+var grokUpdated = time.Date(2026, 9, 24, 11, 0, 0, 0, time.UTC)
+
+const (
+ grokSessionID = "0199a3c4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
+ grokSubagentID = "0199a3c4-7777-7a8b-9c0d-1e2f3a4b5c6d"
+ grokLongID = "0199a3c4-8888-7a8b-9c0d-1e2f3a4b5c6d"
+)
+
+// grokFixture lays down a Grok sessions directory in the layout Grok writes: one directory per
+// session, named by its id, under a directory named for the URL-encoded working directory.
+func grokFixture(t *testing.T) (StoreDirs, string) {
+ t.Helper()
+ testenv.SetHome(t, t.TempDir())
+ isolateRuntimeEnv(t)
+ root := filepath.Join(t.TempDir(), "sessions")
+ dirs := StoreDirs{HarnessGrok: root}
+
+ main := writeGrokSession(t, root, url.PathEscape("/work/api"), grokSessionID, grokUpdated, map[string]interface{}{
+ "generated_title": "Tidy the\nrouter", "head_branch": "feat/grok", "current_model_id": "grok-build",
+ }, "/work/api", "tidy the router")
+ // A subagent is a child session in the same tree, marked by its session kind.
+ writeGrokSession(t, root, url.PathEscape("/work/api"), grokSubagentID, grokUpdated.Add(time.Minute), map[string]interface{}{
+ "generated_title": "Read the tests", "session_kind": "subagent",
+ }, "/work/api", "read the tests")
+ // A working directory too long for one directory name is grouped under a slug; the session's
+ // prompt_context.json still records it. With no title yet, the first prompt stands in.
+ writeGrokSession(t, root, "work-deep-3f9a1c", grokLongID, grokUpdated.Add(-time.Hour), map[string]interface{}{
+ "current_model_id": "grok-build",
+ }, "/work/"+strings.Repeat("deep/", 60), " plot the\nlatency ")
+ return dirs, main
+}
+
+func writeGrokSession(t *testing.T, root, group, id string, updated time.Time, summary map[string]interface{}, cwd, prompt string) string {
+ t.Helper()
+ dir := filepath.Join(root, group, id)
+ summary["created_at"] = updated.Add(-time.Minute).Format(time.RFC3339Nano)
+ summary["updated_at"] = updated.Format(time.RFC3339Nano)
+ writeFixture(t, filepath.Join(dir, "summary.json"), mustJSON(t, summary))
+ writeFixture(t, filepath.Join(dir, "prompt_context.json"), mustJSON(t, map[string]interface{}{"working_directory": cwd, "os_name": "linux"}))
+ writeFixture(t, filepath.Join(dir, "events.jsonl"),
+ jsonLine(t, map[string]interface{}{"ts": updated.Add(-time.Minute).Format(time.RFC3339Nano), "type": "turn_started", "session_id": id, "turn_number": 0}))
+ writeFixture(t, filepath.Join(dir, "chat_history.jsonl"),
+ jsonLine(t, map[string]interface{}{"type": "user", "content": "<system reminder>", "synthetic_reason": "reminder"})+
+ jsonLine(t, map[string]interface{}{"type": "user", "content": []interface{}{map[string]interface{}{"type": "text", "text": prompt}}})+
+ jsonLine(t, map[string]interface{}{"type": "assistant", "content": "Done."}))
+ setModTime(t, dir, updated.Add(-time.Hour))
+ return dir
+}
+
+func TestListReadsGrokSessions(t *testing.T) {
+ dirs, main := grokFixture(t)
+ sessions, err := List(DefaultSources(dirs), Filter{Harness: HarnessGrok, IncludeSubagents: true})
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ byID := map[string]Session{}
+ for _, s := range sessions {
+ byID[s.ID] = s
+ }
+ want := Session{Harness: HarnessGrok, ID: grokSessionID, Title: "Tidy the router", Directory: "/work/api", Branch: "feat/grok", SourcePath: main, UpdatedAt: grokUpdated}
+ if got := byID[grokSessionID]; !reflect.DeepEqual(got, want) {
+ t.Fatalf("grok session = %+v\nwant %+v", got, want)
+ }
+ if sub := byID[grokSubagentID]; !sub.Subagent {
+ t.Fatalf("grok subagent = %+v, want a subagent", sub)
+ }
+ long := byID[grokLongID]
+ if long.Directory != "/work/"+strings.Repeat("deep/", 60) || long.Title != "plot the latency" {
+ t.Fatalf("long-path session = %+v", long)
+ }
+
+ top, err := List(DefaultSources(dirs), Filter{Harness: HarnessGrok})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got := strings.Join(sessionKeys(top), ","); got != "grok/"+grokSessionID+",grok/"+grokLongID {
+ t.Fatalf("top-level sessions = %s, want newest first without the subagent", got)
+ }
+}
+
+func TestListGrokWithoutAStore(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ sessions, err := (&grokSource{dir: filepath.Join(t.TempDir(), "missing")}).List()
+ if err != nil || sessions != nil {
+ t.Fatalf("List = %v, %v; want nothing and no error", sessions, err)
+ }
+}
+
+func TestGrokSessionBuildsABrief(t *testing.T) {
+ dirs, _ := grokFixture(t)
+ sources := DefaultSources(dirs)
+ // A unique prefix finds the session too.
+ session, err := Find(sources, HarnessGrok, grokSessionID[:12])
+ if err != nil {
+ t.Fatalf("Find: %v", err)
+ }
+ if session.ID != grokSessionID {
+ t.Fatalf("Find = %s", session.ID)
+ }
+ events, err := Events(sources, session)
+ if err != nil {
+ t.Fatalf("Events: %v", err)
+ }
+ brief := BuildBrief(session, events, FromSessionStore, time.Now())
+ if brief.Prompts != 1 || brief.FirstRequest != "tidy the router" || brief.LastMessage != "Done." || brief.Branch != "feat/grok" {
+ t.Fatalf("brief prompts=%d first=%q last=%q branch=%q", brief.Prompts, brief.FirstRequest, brief.LastMessage, brief.Branch)
+ }
+ if !strings.Contains(brief.Render(), "Grok Build") {
+ t.Fatalf("the brief should name Grok Build:\n%s", brief.Render())
+ }
+}
+
+func TestGrokSessionGoneFromItsStore(t *testing.T) {
+ dirs, main := grokFixture(t)
+ session := Session{Harness: HarnessGrok, ID: grokSessionID, SourcePath: main}
+ if err := os.RemoveAll(main); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := Events(DefaultSources(dirs), session); !errors.Is(err, ErrNotFound) {
+ t.Fatalf("Events = %v, want ErrNotFound", err)
+ }
+}
+
+func TestPlanResumeReopensAGrokSessionByItsID(t *testing.T) {
+ session := resumableSession(t, HarnessGrok, grokSessionID)
+ plan, err := PlanResume(session, PlanOptions{LookPath: installed("grok")})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ // Grok resolves the id under the directory it runs in, so the plan runs in the session's own.
+ want := []string{"--permission-mode", "default", "--resume", grokSessionID}
+ if plan.Mode != ModeNative || plan.Executable != "/bin/grok" || plan.Dir != session.Directory || !reflect.DeepEqual(plan.Args, want) {
+ t.Fatalf("plan = %+v", plan)
+ }
+
+ brief := filepath.Join(t.TempDir(), "brief.md")
+ for _, tc := range []struct {
+ name string
+ edit func(*Session)
+ reason string
+ }{
+ {"subagent", func(s *Session) { s.Subagent = true }, ReasonNotResumable},
+ {"gone", func(s *Session) { s.SourcePath = filepath.Join(t.TempDir(), "missing") }, ReasonSessionGone},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ s := session
+ tc.edit(&s)
+ plan, err := PlanResume(s, PlanOptions{BriefPath: brief, LookPath: installed("grok")})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ want := []string{"--permission-mode", "default", NewSessionPrompt(s, brief)}
+ if plan.Mode != ModeNewSession || plan.Reason != tc.reason || !reflect.DeepEqual(plan.Args, want) {
+ t.Fatalf("plan = %+v", plan)
+ }
+ })
+ }
+}
+
+// Grok's config can make always-approve the default. No command Beacon runs may inherit it.
+func TestEveryGrokCommandAsksBeforeRunningTools(t *testing.T) {
+ command, _ := commandFor(HarnessGrok)
+ resume, _ := command.Resume(Session{ID: grokSessionID})
+ for _, args := range [][]string{resume, command.NewSession("go")} {
+ if len(args) < 2 || args[0] != "--permission-mode" || args[1] != "default" {
+ t.Fatalf("args %q do not pin the asking permission mode", args)
+ }
+ for _, arg := range args {
+ if arg == "--always-approve" || arg == "--yolo" || arg == "bypassPermissions" {
+ t.Fatalf("args %q approve tools on Beacon's say-so", args)
+ }
+ }
+ }
+}
+
+func TestParseHarnessAcceptsGrokNames(t *testing.T) {
+ for _, name := range []string{"grok", "grok-build", "GROK"} {
+ if got, err := ParseHarness(name); err != nil || got != HarnessGrok {
+ t.Fatalf("ParseHarness(%q) = %q, %v", name, got, err)
+ }
+ }
+ // Grok Bot is a different product and is not a runtime handoff can read.
+ if _, err := ParseHarness("grok_bot"); err == nil {
+ t.Fatal("grok_bot must not resolve to Grok Build")
+ }
+ // A Grok session continued elsewhere is named in the new session's marker.
+ if prompt := NewSessionPrompt(Session{Harness: HarnessGrok, ID: grokSessionID}, "/tmp/b.md"); !strings.HasSuffix(prompt, "[beacon-handoff from=grok session="+grokSessionID+"]") {
+ t.Fatalf("prompt %q does not end with the Grok marker", prompt)
+ }
+}
diff --git a/cli/beacon/internal/handoff/resume_test.go b/cli/beacon/internal/handoff/resume_test.go
index 54ed8c2d..4596f2bf 100644
--- a/cli/beacon/internal/handoff/resume_test.go
+++ b/cli/beacon/internal/handoff/resume_test.go
@@ -24,7 +24,7 @@ func installed(names ...string) func(string) (string, error) {
}
}
-var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent")
+var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent", "grok")
// resumableSession is a session whose directory and session file both exist.
func resumableSession(t *testing.T, harness, id string) Session {
@@ -80,6 +80,7 @@ func TestPlanResumeStartsANewSessionInEachRuntime(t *testing.T) {
{HarnessCline, "cline", []string{"--tui", "--auto-approve", "false"}},
{HarnessPi, "pi", []string{"--"}},
{HarnessPrime, "prime-agent", []string{"--"}},
+ {HarnessGrok, "grok", []string{"--permission-mode", "default"}},
} {
t.Run(tc.target, func(t *testing.T) {
source := HarnessCodex
diff --git a/cli/beacon/internal/handoff/runtimes.go b/cli/beacon/internal/handoff/runtimes.go
index 76162102..b1be5e35 100644
--- a/cli/beacon/internal/handoff/runtimes.go
+++ b/cli/beacon/internal/handoff/runtimes.go
@@ -7,6 +7,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/claudesession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/clinesession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/codexsession"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/groksession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/opencodesession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pisession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/primesession"
@@ -53,6 +54,7 @@ const (
HarnessCline = clinesession.Harness
HarnessPi = pisession.Harness
HarnessPrime = primesession.Harness
+ HarnessGrok = groksession.Harness
)
// runtimes lists every runtime handoff supports, in display order.
@@ -149,6 +151,27 @@ var runtimes = []Runtime{
NewSession: func(prompt string) []string { return []string{"--", prompt} },
},
},
+ {
+ Harness: HarnessGrok,
+ Label: "Grok Build",
+ Aliases: []string{"grok-build"},
+ NewSource: func(dir string) Source { return &grokSource{dir: dir} },
+ // Grok's configured permission mode can be always-approve. A session Beacon starts or
+ // reopens runs in the mode that asks, whatever the config says; the user can still change
+ // the mode inside the TUI.
+ Command: &runtimeCommand{
+ Executable: "grok",
+ Resume: func(s Session) ([]string, bool) {
+ // A subagent is a child of the session that spawned it, not one a person reopens.
+ if s.Subagent {
+ return nil, false
+ }
+ // Grok looks a session up under the directory it runs in, which is the session's own.
+ return []string{"--permission-mode", "default", "--resume", s.ID}, true
+ },
+ NewSession: func(prompt string) []string { return []string{"--permission-mode", "default", prompt} },
+ },
+ },
}
// Harnesses lists the runtimes handoff supports, in display order.
diff --git a/docs/cli/handoff.mdx b/docs/cli/handoff.mdx
index 4b458e2b..57527e5d 100644
--- a/docs/cli/handoff.mdx
+++ b/docs/cli/handoff.mdx
@@ -25,10 +25,11 @@ Sessions come from each runtime's own local session store, not from Beacon's run
| Cline | `~/.cline/data` | `cline` |
| Pi | `~/.pi/agent/sessions` (or under `PI_CODING_AGENT_DIR`) | `pi` |
| Prime Agent | `~/.prime/agent`, both `sessions` and `session-artifacts` (or `PRIME_AGENT_CODING_AGENT_DIR`) | `prime` |
+| Grok Build | `~/.grok/sessions` | `grok` |
-When a Codex thread has more than one rollout file, `beacon handoff` lists it once, under its newest file. Cline can hold the same task both as a CLI session and in its older task history; the CLI session is the copy that is listed. Cline kanban cards are not sessions and are not listed. Prime Agent subagent transcripts, under `session-artifacts`, are listed as subagents of the session that started them.
+When a Codex thread has more than one rollout file, `beacon handoff` lists it once, under its newest file. Cline can hold the same task both as a CLI session and in its older task history; the CLI session is the copy that is listed. Cline kanban cards are not sessions and are not listed. Prime Agent subagent transcripts, under `session-artifacts`, are listed as subagents of the session that started them. Grok Build keeps its subagents' child sessions in the same tree as other sessions; those whose `summary.json` has a subagent `session_kind` are listed as subagents.
-`--store-dir <runtime>=<path>` takes the location in the table: for Pi its sessions directory, as `beacon endpoint pi sync --sessions-dir` does, and for Prime Agent the agent directory holding both of its roots.
+`--store-dir <runtime>=<path>` takes the location in the table: for Pi its sessions directory, as `beacon endpoint pi sync --sessions-dir` does, for Prime Agent the agent directory holding both of its roots, and for Grok Build its sessions directory, as `beacon endpoint grok sync --sessions-dir` does. Like that sync, `beacon handoff` does not read `GROK_HOME`; pass `--store-dir grok=$GROK_HOME/sessions` when it is set.
## `beacon handoff list`
@@ -110,6 +111,7 @@ There are two ways to resume:
| Cline | `cline --tui --auto-approve false --id <id>` |
| Pi | `pi --session <session file>` |
| Prime Agent | `prime-agent --resume <session file>` |
+ | Grok Build | `grok --permission-mode default --resume <id>` |
- **Start a new session from a brief.** Otherwise, or with `--agent` naming another runtime or with `--new`, Beacon writes a brief (see `export`) and starts a new session. The first message of that session points at the brief:
@@ -121,18 +123,21 @@ There are two ways to resume:
| Cline | `cline --tui --auto-approve false "<prompt>"` |
| Pi | `pi -- "<prompt>"` |
| Prime Agent | `prime-agent -- "<prompt>"` |
+ | Grok Build | `grok --permission-mode default "<prompt>"` |
The prompt names the brief by its path and asks the agent to read it, then confirm the task before changing anything. The brief is never inlined into the command line, because a command line is visible to every local user through the process table. The prompt ends with a handoff marker (see below).
-Claude Code, Cline and Prime Agent subagent sessions, and Cline's older task history, can't be reopened by their CLIs, so they always continue from a brief. A session known only from Beacon's runtime log also continues from a brief, and it needs `--agent` if its own runtime isn't one Beacon can start.
+Claude Code, Cline, Prime Agent and Grok Build subagent sessions, and Cline's older task history, can't be reopened by their CLIs, so they always continue from a brief. A session known only from Beacon's runtime log also continues from a brief, and it needs `--agent` if its own runtime isn't one Beacon can start.
Cline approves every tool call by default. Beacon always passes `--auto-approve false`, so a session Beacon starts never gets auto-approval on Beacon's say-so. You can still turn it on inside the Cline TUI.
+Grok Build's configured permission mode can be always-approve. Beacon always passes `--permission-mode default`, the mode that asks before running tools, so a session Beacon starts or reopens never inherits always-approve from that config. You can still change the mode inside the Grok TUI. Grok looks a session id up under the directory it runs in, which is why the resume runs in the session's recorded directory.
+
The runtime runs in this terminal, in the session's recorded directory. If that directory no longer exists, Beacon stops rather than starting somewhere else; pass `--cwd` to choose a directory. Beacon prints the plan and asks `Continue? [Y/n]` before launching. Without a terminal, it launches only with `--yes`. `beacon handoff resume` exits with the runtime's own exit code.
| Flag | Description |
|------|-------------|
-| `--agent` | Runtime to continue in: `claude`, `codex`, `opencode`, `cline`, `pi` or `prime`. Defaults to the session's own runtime. |
+| `--agent` | Runtime to continue in: `claude`, `codex`, `opencode`, `cline`, `pi`, `prime` or `grok`. Defaults to the session's own runtime. |
| `--new` | Start a new session from a brief even when the session could be reopened. |
| `--cwd` | Directory to start the runtime in. |
| `--print` | Show the plan and command without writing a brief or launching anything. |
@@ -162,8 +167,8 @@ The link event keeps the new session's id, workspace and harness, and leaves the
Two paths record the link:
-- **Live hooks.** The prompt hook for Claude Code and the Cline and OpenCode plugins record it as the prompt is sent (`harness.collection_method: hook`).
-- **Session-store sync.** `beacon endpoint claude sync`, `codex sync`, `opencode sync`, `cline sync`, `pi sync` and `prime sync` record it when they read the prompt back from the runtime's store (`harness.collection_method: poll`).
+- **Live hooks.** The prompt hook for Claude Code and Grok Build and the Cline and OpenCode plugins record it as the prompt is sent (`harness.collection_method: hook`).
+- **Session-store sync.** `beacon endpoint claude sync`, `codex sync`, `opencode sync`, `cline sync`, `pi sync`, `prime sync` and `grok sync` record it when they read the prompt back from the runtime's store (`harness.collection_method: poll`).
Codex CLI prompts reach Beacon over OTLP and through `beacon endpoint codex sync`, not a prompt hook, so a session continued in Codex is linked by the sync. For a runtime that also has a prompt hook or plugin, a sync can record the same link the hook already did; the two carry different `collection_method` values, as every other event those runtimes report through both paths does. A sync's link has a deterministic `event.id`, so syncing again never duplicates it.