Skip to content

mvschwarz/openrig / packages/daemon/specs/agents/shared/skills/core/session-source-fork

session-source-fork

Verified

Use when authoring a rig spec member or `rig expand` payload that needs to start a new managed seat from a prior runtime conversation source — `session_source: { mode: fork, ref: { kind, value } }`. v1 supports `mode: fork` with `ref.kind: native_id` for Claude and Codex. The new seat persists a NEW post-fork token; the parent token is NEVER written onto the new seat. NOT for restoring an existing seat or for artifact-backed mental-model rebuild.

session_source Fork

session_source is a member-level OpenRig field that declares how a newly-launched managed seat should derive its initial conversation continuity from a prior runtime conversation source.

v1 supports one mode: fork — start a new managed seat from a prior native runtime conversation source without claiming the original seat continued.

The schema is runtime-neutral; implementation is runtime-specific (Claude and Codex have their own native fork commands).

Use this when

  • Authoring a rig spec member that should fork from a prior session
  • Authoring a rig expand payload with session_source
  • Reasoning about whether to use fork vs rebuild vs resume vs fresh for a new seat
  • Composing fork + handover (seat-handover-over-fork) — see seat-continuity-and-handover skill

Don't use this when

  • The seat is being restored, not created. Restore continues an existing managed seat. Fork creates a new seat.
  • The continuity is artifact-backed mental-model rebuild (packet-derived understanding, not native runtime continuity). Use mode: rebuild (see seat-continuity-and-handover for the rebuild surface) — do NOT collapse fork into artifact-backed reentry; the distinction is load-bearing.
  • The runtime is terminal. Terminal runtime rejects session_source.

The shape (canonical YAML)

members:
  - id: reviewer-2
    runtime: claude-code        # or "codex"; not valid on terminal
    agent_ref: specs/agents/reviewer.yaml
    profile: reviewer
    cwd: .
    session_source:
      mode: fork
      ref:
        kind: native_id          # v1 fork mode supports native_id only
        value: "0b0165d7-cb4d-4650-90de-15c0a1ede9e6"

Rules:

  • mode v1 only valid value: fork.
  • ref.kind v1 supports native_id only. Schema rejects artifact_path, name, last, and artifact_set pre-launch with explicit deferred/weaker/wrong-mode error messages (see packages/daemon/src/domain/rigspec-schema.ts validateSessionSourceFork). Adapter-level refusal exists as defensive handling but should not be reachable in v1 because schema rejects first.
  • value required for ref.kind: native_id in v1 (the only schema-accepted kind). Future-state value semantics for artifact_path / name / last are not active in v1 because schema rejects those kinds pre-launch.
  • rig expand accepts the same shape so dynamically-added members can carry session-source attribution.

The primitive does NOT introduce a new top-level command. It flows through existing rig spec and expansion pathways.

State model

session_source is a launch-time input, not a long-lived stateful field:

  1. Declared — present in member config or expansion payload
  2. Resolved — at launch time, OpenRig resolves the ref against the runtime
  3. Realized — runtime fork succeeds; new managed seat receives a NEW native continuity token (Claude session id or Codex thread id). OpenRig persists that NEW token. Parent token is NEVER written onto the new seat.
  4. Failed — resolution or fork failed; seat not launched as a fork; clear error names the resolution step that failed

Once realized, session_source is essentially history. Restoring the seat later is restore of the new seat, not re-fork-from-parent.

Failure modes (5)

  1. Source session id not found — runtime cannot resolve native_id. Action: emit error naming runtime + missing id; do NOT silently launch fresh. (Future-state note: when artifact_path is supported in a follow-up slice, it could become a candidate fallback for Claude; in v1 schema rejects artifact_path pre-launch so no fallback path exists.)
  2. Source artifact path missing (out of v1 scope) — would apply once ref.kind: artifact_path becomes schema-accepted. v1 schema rejects this kind pre-launch.
  3. Unsupported runtime/kind combination (largely pre-empted in v1 by schema rejection) — schema rejects all non-native_id kinds upfront. Adapter-level refusal exists as defensive handling but is not reached in v1.
  4. Fork launch failed after source resolution — runtime command (claude --resume <parent> --fork-session or codex fork <id>) returned non-zero or hung. Preserve runtime stderr; do not record new seat as launched; do not write parent token onto seat.
  5. Persistence inconsistency — fork succeeded but seat-token persistence cannot record new continuity token. Internal failure: seat is not considered launched until new token is durably written.

Honest UX rule (verbatim)

The primitive must NOT report "restored the original agent" or "resumed the original seat" or "snapshot." The correct framing is "forked from source session" / "started from prior conversation source."

Check the actual user-facing outcome and persisted identity; wording alone does not prove the intended continuity was created.

Hard boundaries (do-not list; verbatim)

  • Do NOT introduce a DIVERGENT fork primitive. The primitive flows through existing spec/expansion pathways. (Update 2026-08-07: rig fork <source-session> has since shipped as a thin convenience verb that COMPOSES the existing agent-image fork path — this honors the boundary; it is not a divergent primitive. The rule now reads: no NEW fork mechanics outside the spec / expansion / agent-image pathways.)
  • Do NOT report "restored" / "resumed the original seat" / "snapshot" in any UX surface.
  • Do NOT couple session_source to AgentSpec. It's a member-level launch-time input.
  • Do NOT change restore semantics. session_source creates a seat; restore continues an existing managed seat.

Adapter command shape (shipped v1)

RuntimeCommand shape
Claude (mode: fork + ref.kind: native_id)claude --resume <parent-id> --fork-session
Codex (mode: fork + ref.kind: native_id)codex... fork <parent-id>
TerminalRejected at schema level

Mutual exclusion between resumeToken (restore path) and forkSource (fork path) is enforced at three layers in the daemon.

Continuity outcome literals

OutcomeWhen
forkedFork succeeded; new seat has new native token; parent never written onto new seat
freshFresh launch (no session_source declared)
resumedRestore of existing managed seat
failedResolution or fork failed

For seat handover over fork composition, the binding outcome is independent (see seat-continuity-and-handover skill).

Verify the running implementation

A source checkout and the running daemon can contain different implementations. Before an authorized fork, check the target daemon's build identity and support for the requested source. A source or isolated test establishes only that cut's behavior; it does not prove the live runtime uses it.

Record the actual parent history, new seat identity, new continuity token and independent binding outcome. Preserve errors and incomplete results rather than reporting a fresh launch or restored original seat as a successful fork. These checks confer no authority to launch, replace or retire a live seat.

Currently shipped (v1) vs deferred

Shipped at openrig c7b6df1 (2026-04-30):

  • Schema accept/reject for full Honest Refusal Matrix
  • Codec roundtrip (serialize → parse → normalize preserves session_source faithfully)
  • Expansion path through rig expand member-input
  • Adapter command shape for Claude + Codex native_id
  • Persistence honesty (seat's resume_token is the NEW post-fork token; parent token NEVER written)
  • Honest UX literal contract (continuityOutcome: forked)

Deferred:

  • Claude artifact_path mode (schema currently refuses with deferred message)
  • Provenance columns (parent_native_id / created_via for queryable RSI consumer)
  • Cross-host fork (source on host A, new seat on host B) — depends on cross-host-rig-commands

See also

  • seat-continuity-and-handover skill — sibling occupant-creation primitives (resume / fork / rebuild / fresh) + seat-binding (handover composes with fork)
  • agent-starters skill — composes session_source fork into named reusable starting points
  • cross-host-rig-commands skill — multi-host fork (deferred)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
discernment-nudgeanthropics/skillsAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
internal-commsanthropics/skillsA set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).Stars: 195kUpdated Claude CodeCodexVerifiedInstall