The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
handoff: describe every supported runtime in the help and docs
Claudeae3959089697
diff --git a/CLAUDE.md b/CLAUDE.mdindex 484bfc25..fcc84e07 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -65,7 +65,7 @@ Supported runtime surfaces today:- A local-only dashboard served by `beacon endpoint dashboard`, bound to loopback by default and backed by the runtime JSONL log.- Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into `gen_ai.usage`, with attribution rollups served by the dashboard token view (`/api/tokens`) and the `beacon token-usage` report command for local and CI logs.- Local threat detection via `beacon scan`, which runs the open Threat Rules format (`spec/threat-rules`; CEL match conditions over the endpoint event schema, with embedded conformance fixtures) over the runtime JSONL. The engine (`pkg/asymptoteobserve/threatrules`) ships in the binary; the rule corpus is external data loaded from a local store (`~/.beacon/endpoint/rules`) managed by `beacon rules`, so the corpus can grow without enlarging the binary. `scan` is read-only and offline; only the explicit, user-initiated `beacon rules pull <url>` reaches the network. A small frozen baseline is embedded so `scan` works before any rules are installed.-- Session handoff via `beacon handoff list|export|resume` (`cli/beacon/internal/handoff`, `cli/beacon/cmd/handoff*.go`; docs in `docs/cli/handoff.mdx`) for Claude Code, Codex CLI, OpenCode and Cline. It reads each runtime's own session store read-only and never touches the network. `resume` reopens a session natively (`claude --resume`, `codex resume`, `opencode --session`, `cline --tui --id`) when it can, and otherwise writes a brief to `~/.beacon/endpoint/handoffs` (0700/0600) and starts a new session pointed at it. The brief is passed by absolute path, never inlined on a command line. Every Cline launch passes `--auto-approve false`, because Cline defaults to approving every tool call. Briefs run every event through `SanitizeEvent`, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the `[beacon-handoff from=<harness> session=<id>]` marker (`pkg/asymptoteobserve/handoff.go`). The hook prompt paths and the four session-store mappers record a `session.handoff` event with `handoff.{source_harness,source_session_id}` when they see it; that is an observed claim, not a verified identity.+- Session handoff via `beacon handoff list|export|resume` (`cli/beacon/internal/handoff`, `cli/beacon/cmd/handoff*.go`; docs in `docs/cli/handoff.mdx` and `docs/concepts/session-handoff.mdx`). Every runtime is one entry in the registry in `cli/beacon/internal/handoff/runtimes.go`: its session source, the names it answers to, and the commands that reopen it or start it from a brief; `TestRegistryIsConsistent` checks the entries. Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw Gateway and Cursor read-only and never touches the network. Oh My Pi, Gemini CLI, Qwen Code, Kiro, Antigravity CLI, Devin CLI, Muse Code, OpenHands and goose have no store Beacon reads: their sessions come from the runtime log, and they take a brief as the target of `--agent`. `resume` reopens a session natively with its runtime's own command when it can, and otherwise writes a brief to `~/.beacon/endpoint/handoffs` (0700/0600) and starts a new session pointed at it. DeepSeek Harness cannot be started, and Hermes Agent and fx only reopen their own sessions, so their sessions continue in another runtime. fx, Grok Build and Cursor find a session by the directory they run in, so they are reopened natively only in the session's own directory. The brief is passed by absolute path, never inlined on a command line. Every launch keeps the runtime's approvals on: Beacon never passes a flag that turns them off, names the approval mode that asks where a CLI takes one (Cline always gets `--auto-approve false`, because Cline defaults to approving every tool call), and removes or overrides environment switches that would approve everything (`COPILOT_ALLOW_ALL`, `COPILOT_PLAN_THEN_AUTOPILOT`, `HERMES_YOLO_MODE`, `GOOSE_MODE`); `--print` shows them under `env`. Briefs run every event through `SanitizeEvent`, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the `[beacon-handoff from=<harness> session=<id>]` marker (`pkg/asymptoteobserve/handoff.go`). The hook and plugin prompt paths and the session-store mappers record a `session.handoff` event with `handoff.{source_harness,source_session_id}` when they see it; that is an observed claim, not a verified identity.- An optional, off-by-default policy seam in the hook path (`cli/beacon-hooks/internal/policy`) governed by the stable contract in `pkg/asymptoteobserve/policycontract`. When `BEACON_POLICY_PROVIDER` names an executable, the `pre-tool` and `permission-request` hooks send it a JSON request describing the imminent tool call and honor an allow/deny response, returning the runtime's native deny shape and `policy.enforcement=enforce` telemetry on a deny. The seam is inert when unset and fail-open on any error (timeout, non-zero exit, malformed output), so the open build ships no enforcement of its own; all audit/enforce decision logic lives in the external provider. `rules/agent-control/agent-permission-bypass-spawn.rule.yaml` is the open detect twin that flags the same pattern in `beacon scan`.Current non-goals unless explicitly requested:diff --git a/cli/beacon/cmd/handoff.go b/cli/beacon/cmd/handoff.goindex ecda3eb1..5440c7d9 100644--- a/cli/beacon/cmd/handoff.go+++ b/cli/beacon/cmd/handoff.go@@ -40,10 +40,7 @@ var handoffOpts handoffOptionsvar handoffCmd = &cobra.Command{Use: "handoff",Short: "Pick up a local agent session again, in the same runtime or another one",- Long: `Pick up a local agent session again, in the same runtime or another one.--Sessions are read from each runtime's own local session store (Claude Code, Codex CLI, OpenCode-and Cline). Nothing is uploaded and no runtime file is modified.`,+ // Long is set in init from the runtime registry, so it names every store Beacon reads.}var handoffListCmd = &cobra.Command{@@ -365,7 +362,31 @@ func addHandoffStoreFlags(cmd *cobra.Command) {f.StringVar(&handoffOpts.clineDir, "cline-dir", "", "Cline directory (default ~/.cline)")}+// handoffLong describes the handoff command, naming each runtime whose own session store it reads.+func handoffLong() string {+ var labels []string+ for _, harness := range handoff.Harnesses {+ if handoff.ReadsStore(harness) {+ labels = append(labels, handoff.RuntimeLabel(harness))+ }+ }+ return fmt.Sprintf(`Pick up a local agent session again, in the same runtime or another one.++Sessions are read from each runtime's own local session store: %s.+Sessions of the other runtimes come from Beacon's runtime log. Nothing is uploaded and no runtime+file is modified.`, joinWithAnd(labels))+}++// joinWithAnd joins items as prose: "a", "a and b", "a, b and c".+func joinWithAnd(items []string) string {+ if len(items) < 2 {+ return strings.Join(items, "")+ }+ return strings.Join(items[:len(items)-1], ", ") + " and " + items[len(items)-1]+}+func init() {+ handoffCmd.Long = handoffLong()rootCmd.AddCommand(handoffCmd)handoffCmd.AddCommand(handoffListCmd, handoffExportCmd)addHandoffStoreFlags(handoffExportCmd)diff --git a/cli/beacon/cmd/handoff_resume.go b/cli/beacon/cmd/handoff_resume.goindex 0b822010..68d945cd 100644--- a/cli/beacon/cmd/handoff_resume.go+++ b/cli/beacon/cmd/handoff_resume.go@@ -33,17 +33,20 @@ var handoffResumeCmd = &cobra.Command{Short: "Pick a session up again, in its own runtime or another one",Long: `Pick a session up again, in its own runtime or another one.-When the session's own runtime can reopen it, it is reopened with its full context:- claude --resume <id>, codex resume <id>, opencode --session <id>, cline --tui --id <id>+When the session's own runtime can reopen it, it is reopened with its full context by that+runtime's own command, such as claude --resume <id>, codex resume <id> or opencode --session <id>.+--print shows the exact command.Otherwise, or with --agent naming another runtime or --new, Beacon writes a handoff brief of thesession and starts a new session whose first message points at it. The brief is passed by path,-never inlined into the command line. Beacon cannot start DeepSeek Harness, so its sessions continue-in another runtime named with --agent.+never inlined into the command line. Beacon cannot start DeepSeek Harness, and Hermes Agent and fx+only reopen their own sessions, so a session of theirs continues in another runtime named with+--agent.The runtime runs in the session's directory, in this terminal. Beacon asks before launching unless---yes is given; --print shows what would run without writing or launching anything. Cline is always-started with --auto-approve false.`,+--yes is given; --print shows what would run without writing or launching anything. Beacon never+passes a flag that turns a runtime's approvals off, and names the mode that asks where a CLI takes+one: Cline, for example, is always started with --auto-approve false.`,Args: cobra.ExactArgs(1),SilenceUsage: true,RunE: runHandoffResume,diff --git a/cli/beacon/cmd/handoff_test.go b/cli/beacon/cmd/handoff_test.goindex b75663e5..351d94e3 100644--- a/cli/beacon/cmd/handoff_test.go+++ b/cli/beacon/cmd/handoff_test.go@@ -540,3 +540,25 @@ func TestHandoffLogReasonNamesRuntimesWithoutAStore(t *testing.T) {}}}++func TestHandoffHelpNamesEveryStoreItReads(t *testing.T) {+ long := handoffLong()+ _, list, ok := strings.Cut(long, "session store: ")+ list, _, _ = strings.Cut(list, ".\n")+ if !ok || list == "" {+ t.Fatalf("help has no list of session stores:\n%s", long)+ }+ named := map[string]bool{}+ for _, item := range strings.Split(strings.ReplaceAll(list, " and ", ", "), ", ") {+ named[item] = true+ }+ for _, harness := range handoff.Harnesses {+ label := handoff.RuntimeLabel(harness)+ if named[label] != handoff.ReadsStore(harness) {+ t.Errorf("help names %s = %v, want %v:\n%s", label, named[label], handoff.ReadsStore(harness), long)+ }+ }+ if got := joinWithAnd([]string{"a", "b", "c"}); got != "a, b and c" {+ t.Fatalf("joinWithAnd = %q", got)+ }+}diff --git a/docs/cli/handoff.mdx b/docs/cli/handoff.mdxindex 0810ff2b..c1ecf325 100644--- a/docs/cli/handoff.mdx+++ b/docs/cli/handoff.mdx@@ -174,9 +174,7 @@ There are two ways to resume:Hermes Agent has no row in the second table: its CLI has no way to start an interactive session with a first message, only one-shot runs, so it can't continue a session from a brief. A Hermes session continues from a brief in another runtime (`--agent`), and `--agent hermes` reopens only Hermes's own sessions.-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.--Claude Code, Cline, Prime Agent and Hermes 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, Hermes 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.Beacon cannot start DeepSeek Harness, because it has no interactive terminal session to start: `dsh --profile headless` answers one task and exits, and `dsh web` is a browser UI. A DeepSeek Harness session therefore continues in another runtime, named with `--agent`, and `--agent dsh` is refused.diff --git a/docs/concepts/session-handoff.mdx b/docs/concepts/session-handoff.mdxindex 1c85f1ae..f32505a7 100644--- a/docs/concepts/session-handoff.mdx+++ b/docs/concepts/session-handoff.mdx@@ -15,8 +15,13 @@ the runtime resumes from, and it keeps content the runtime log truncates. Everylocal and read-only. Nothing is uploaded, no runtime file is changed, and no command inthe handoff path touches the network.-Handoff supports Claude Code, Codex CLI, OpenCode, and Cline. See-[`beacon handoff`](/cli/handoff) for the full command reference.+Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent,+Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw+Gateway, and Cursor. It can also continue a session in Oh My Pi, Gemini CLI, Qwen Code, Kiro,+Antigravity CLI, Devin CLI, Muse Code, OpenHands, or goose. Beacon keeps no reader for those+runtimes' own stores, so it knows their sessions only from its runtime log. See+[`beacon handoff`](/cli/handoff) for the full command reference, including each runtime's+commands.## Workflow@@ -37,8 +42,10 @@ beacon handoff resume 7f3c2a91 --agent codex # continue it in another runtime**Reopen natively.** Beacon reopens the session with its full context when you continuein the same runtime, that runtime's CLI can load the session, and the session file is-still on this machine. This runs `claude --resume`, `codex resume`,-`opencode --session`, or `cline --tui --id`. The session keeps its own id.+still on this machine. This runs the runtime's own reopen command, such as+`claude --resume`, `codex resume`, or `opencode --session`. The session keeps its own id.+Some runtimes reopen a session only from the directory it ran in (fx, Grok Build, and+Cursor), so with `--cwd` pointing elsewhere their sessions are not reopened natively.**Start a new session from a brief.** Beacon starts a new session from a brief when youcontinue in a different runtime, when you pass `--new`, or when the session can't be@@ -47,6 +54,10 @@ always take this path. Beacon writes the brief, then starts a new session whoseprompt names the brief by its path and asks the agent to confirm the task before itchanges anything.+A few runtimes can take only one of the two paths. DeepSeek Harness has no interactive+session for Beacon to start, and Hermes Agent and fx can reopen their own sessions but can't+start one from a brief. Their sessions continue in another runtime, named with `--agent`.+## What a brief containsA brief is a summary, not a full transcript:@@ -73,8 +84,11 @@ connected, its first prompt ends with a handoff marker:When Beacon records a prompt that carries this marker, it writes a `session.handoff`event alongside the usual `prompt.submitted` event. The event's`handoff.source_harness` and `handoff.source_session_id` fields name the session it-continues. Live hooks record the link as the prompt is sent. The `claude`, `codex`,-`opencode`, and `cline` session-store syncs record it when they read the prompt back.+continues. Live hooks and plugins record the link as the prompt is sent. The session-store+syncs record it when they read the prompt back: `beacon endpoint <runtime> sync` for Claude+Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes+Agent, DeepSeek Harness, fx, Grok Build, and Cursor, and `beacon endpoint openclaw sessions+sync` for OpenClaw Gateway.This lets you follow one task across runtimes in the runtime log or a forwardeddestination, and threat rules can match on `e.handoff.*`.@@ -98,5 +112,9 @@ The marker is text in a prompt, not a verified identity, and anyone can type it.part of the brief.- **Confirmation before launch.** `resume` asks before it starts a runtime, and itlaunches without a terminal only with `--yes`. It stops if the session's directory no- longer exists, rather than starting somewhere else. Cline sessions are always started- with `--auto-approve false`, because Cline approves every tool call by default.+ longer exists, rather than starting somewhere else.+- **Approvals stay on.** Beacon never passes a flag that turns a runtime's approvals off.+ Where a CLI takes an approval mode, Beacon names the one that asks. For example, Cline+ is always started with `--auto-approve false`, because it approves every tool call by+ default. Beacon also removes environment switches that would approve everything, such+ as `COPILOT_ALLOW_ALL` and `HERMES_YOLO_MODE`.