Skip to content

fix(claudecode): adopt the parent's Claude Code session on a fork child - #284

Merged
Anish Ramasekar (aramase) merged 1 commit into
agent-primitives:mainfrom
aramase:aramase/i/claudecode_fork_255
Nov 18, 2026
Merged

Anish Ramasekar (aramase) merged 1 commit into
agent-primitives:mainfrom
aramase:aramase/i/claudecode_fork_255

Conversation

@aramase

@aramase Anish Ramasekar (aramase) commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

A memory-tier fork clones the parent's compute, so the child's harness memory holds the parent's Claude Code session under the parent's UID and nothing under the child's. Every child turn then failed with errStateLost. This fixes that inside the harness, with no proto, capability or spec change. Fixes #255.

  • On a fork child's first turn the harness continues the parent's session under the child's own id: claude --resume <parent id> --fork-session --session-id <child id>. Later child turns resume the child's id. The parent's entry is only read.
  • Adoption needs a fork marker in the child's history with no turn after it, a fork point (the last execution before the marker, an INPUT-only one included) that this harness started, and exactly one idle session whose last execution is the fork point. An unknown fork point is never skipped for an older one, so a fork of a child whose turn never reached the harness, or of a parent turn the harness refused before starting, fails closed. Zero or ambiguous matches, and non-fork sessions with no state, also fail closed with errStateLost.
  • Until Claude Code confirms the child's own id, every child attempt rechecks that the parent is still idle at the fork point, so a retry after a cancelled or failed attempt never copies turns the parent ran later.
  • While such an attempt runs it reserves the parent, and any unconfirmed fork in between, until the attempt ends: their turns fail with a fork-in-progress error, so the parent's transcript can't move on before Claude Code copies it. A parent turn refused this way counts as never started, so a fork taken at it fails closed.
  • ForkSafe stays false; it still means a fork by replay is not supported. The package doc, docs/harness-authoring.md and a changelog fragment describe the new behavior.

Tested:

  • go vet, gofmt and go test -race in integrations/claudecode, including new fake-claude tests for adoption, the fail-closed cases, a new fork adopting again after the parent's next turn, child retries against an unchanged, advanced or busy parent, an unconfirmed parent, a fork of a fork, and the parent reservation (a paused child refusing the parent's turn, release on every exit path, retries, concurrent forks).
  • TestForkOverWire: controller.Fork on a real parent journal, then the child under its own UID over harnesswire.
  • Claude Code 2.1.311 against a local fake API with an isolated config dir: --resume P --fork-session --session-id C reports C, leaves P.jsonl byte-identical and writes a self-contained C.jsonl. --session-id with --resume and no --fork-session, a child id already in use, and a missing parent transcript each exit 1.

@aramase
Anish Ramasekar (aramase) marked this pull request as ready for review November 17, 2026 06:42
@aramase
Anish Ramasekar (aramase) requested a review from a team as a code owner November 17, 2026 06:42
Copilot AI balanced review requested due to automatic review settings November 17, 2026 06:42

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A second fork can skip an execution with uncertain delivery and adopt an older transcript, bypassing the state-loss check and continuing from a stale conversation.

1 open issue
What changed in this PR

This PR addresses #255 by letting the Claude Code harness adopt a parent's session on memory-snapshot fork children, without changing the protocol or capabilities.

Changes:

  • Adds parent-session matching and CLI flags to create an independent child session.
  • Adds adoption, failure-path, nested-fork, and controller-over-wire tests.
  • Documents fork requirements and the transcript filesystem constraint.
File Description
integrations/​claudecode/​turn.go Carries and logs the fork source session ID.
integrations/​claudecode/​integration_test.go Tests forked sessions through the controller and harness wire.
integrations/​claudecode/​fork_test.go Covers adoption, refusals, retries, cancellation, and nested forks.
integrations/​claudecode/​fake_test.go Models Claude Code's fork-session argument handling.
integrations/​claudecode/​claudecode.go Implements parent matching, adoption state, and fork arguments.
integrations/​claudecode/​claudecode_test.go Updates the cancellation test for the argument signature.
docs/​harness-authoring.md Describes memory-tier fork behavior and requirements.
changelog/​unreleased/​claudecode-fork.md Records the fork support fix and constraints.

Review effort: Balanced

Comment thread integrations/claudecode/claudecode.go Resolved
Copilot AI balanced review requested due to automatic review settings November 17, 2026 16:32

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two critical fork-validation gaps allow retries to copy a changed parent transcript and overlook INPUT-only executions, potentially resuming the wrong conversation.

2 open issues
1 resolved since last review

Review effort: Balanced

Comment thread integrations/claudecode/claudecode.go Resolved
Comment thread integrations/claudecode/claudecode.go Resolved
Copilot AI balanced review requested due to automatic review settings November 17, 2026 17:15

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A critical race allows a parent transcript to advance before a child forks, copying conversation beyond the intended fork point; source reservations and deterministic regression coverage, including retries, are needed.

1 open issue
2 resolved since last review

Review effort: Balanced

Comment thread integrations/claudecode/claudecode.go Resolved
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 18:26

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified in the Claude Code session-fork changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@aramase
Anish Ramasekar (aramase) merged commit 8077f2d into agent-primitives:main Nov 18, 2026
21 checks passed
@aramase
Anish Ramasekar (aramase) deleted the aramase/i/claudecode_fork_255 branch November 18, 2026 04:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

claudecode: fork child of a session with prior turns fails with errStateLost

3 participants