Skip to content

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

docs: add Session Handoff page under How Beacon Works

Claude4e01a91eb6ae
diff --git a/docs/concepts/session-handoff.mdx b/docs/concepts/session-handoff.mdx
new file mode 100644
index 00000000..1c85f1ae
--- /dev/null
+++ b/docs/concepts/session-handoff.mdx
@@ -0,0 +1,102 @@
+---
+title: "Session Handoff"
+description: "Continue a local agent session in the same runtime or a different one, and keep the two linked in telemetry"
+---
+
+## Overview
+
+Session handoff lets you pick up an agent session where it stopped. You can reopen it
+in the runtime it ran in, or continue it in a different one. For example, you can move a
+Claude Code session into Codex when you hit a rate limit, or give a stalled task to
+another agent without explaining it all again.
+
+Handoff reads each runtime's own local session store, not Beacon's runtime log. That store is what
+the runtime resumes from, and it keeps content the runtime log truncates. Every read is
+local and read-only. Nothing is uploaded, no runtime file is changed, and no command in
+the handoff path touches the network.
+
+Handoff supports Claude Code, Codex CLI, OpenCode, and Cline. See
+[`beacon handoff`](/cli/handoff) for the full command reference.
+
+## Workflow
+
+```bash
+beacon handoff list --here # sessions that ran in this repository
+beacon handoff export 7f3c2a91 # write a brief for one session
+beacon handoff resume 7f3c2a91 --agent codex # continue it in another runtime
+```
+
+1. **Find the session.** `beacon handoff list` shows resumable sessions across every
+ supported runtime, newest first. You can filter it by runtime or by directory.
+2. **Summarize it.** `beacon handoff export` writes a handoff brief. The brief is a
+ Markdown summary of what the session asked for, what it changed, and where it stopped.
+3. **Continue it.** `beacon handoff resume` prints its plan, asks you to confirm, and
+ launches the runtime in this terminal, in the session's recorded directory.
+
+## Two ways to resume
+
+**Reopen natively.** Beacon reopens the session with its full context when you continue
+in 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.
+
+**Start a new session from a brief.** Beacon starts a new session from a brief when you
+continue in a different runtime, when you pass `--new`, or when the session can't be
+reopened natively. Subagent sessions and sessions known only from Beacon's runtime log
+always take this path. Beacon writes the brief, then starts a new session whose first
+prompt names the brief by its path and asks the agent to confirm the task before it
+changes anything.
+
+## What a brief contains
+
+A brief is a summary, not a full transcript:
+
+- The source runtime, session id, directory, branch, and last activity.
+- The first and latest requests, and the last agent message.
+- Files changed and recent commands, with exit codes where the runtime reports them.
+- The last 30 steps of activity, each cut to 1,200 characters.
+
+Agent reasoning and file reads are left out. A brief is at most 48 KiB, and the oldest
+steps are dropped first to stay under that limit. If a session is no longer in its
+runtime's store, Beacon builds the brief from the runtime log instead. That works for
+any runtime Beacon captured, but the log keeps less of each step, and the brief says so.
+
+## Linking sessions in telemetry
+
+A session started from a brief has a new session id. To keep the two sessions
+connected, its first prompt ends with a handoff marker:
+
+```text
+[beacon-handoff from=claude_code session=ea7f210f-402b-53b1-aec2-864a488dfcd3]
+```
+
+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.
+This lets you follow one task across runtimes in the runtime log or a forwarded
+destination, and threat rules can match on `e.handoff.*`.
+
+The marker is text in a prompt, not a verified identity, and anyone can type it. The
+`observed` fidelity on the event means Beacon saw the marker. It does not mean that
+`beacon handoff resume` wrote it.
+
+## Safety boundary
+
+- **Local and read-only.** Handoff reads runtime session stores and never writes to
+ them. No step contacts the network.
+- **Redacted briefs.** Every event goes through the same secret redaction and truncation
+ as the runtime log before it reaches a brief.
+- **Private files.** Briefs are written to `~/.beacon/endpoint/handoffs`, a `0700`
+ directory, and each brief is a `0600` file, because briefs carry prompt text and
+ command output. An existing brief is never overwritten.
+- **Nothing on the command line.** The brief is passed by path and never inlined into
+ the launch command, which any local user can see in the process table.
+- **No forged structure.** Quoted content sits in code fences longer than any backtick
+ run inside it, so text from a session can't close its block and pass itself off as
+ part of the brief.
+- **Confirmation before launch.** `resume` asks before it starts a runtime, and it
+ launches 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.
diff --git a/docs/docs.json b/docs/docs.json
index b453580e..10ca30a1 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -75,6 +75,7 @@
},
"concepts/cross-harness-memory",
"concepts/beacon-skills",
+ "concepts/session-handoff",
{
"group": "Unified Telemetry Schema",
"root": "telemetry-schema/event-schema",