Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md

Large diffs are not rendered by default.

19 changes: 3 additions & 16 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,22 +72,6 @@

## Backlog

- 2026-11-15, seen by the maintainer, not fixed: a fork of a conversation served before an opencode
restart replays it. Session `ses_e1f0664f3ffe...` is `(fork #1)` of the director session
`ses_e7198d765ffeUT1TqjM6JP7LiP`, made at 20:50:16Z through the parent's LAST message (boundary
`through`, seq 14362). Its first turn logged `replaying the conversation as text` with
`no-sibling-recorded` and 2,888 messages, bounded to 180,000 characters, so the fork lost almost all of
its context. The parent's resume record for the same model, agent and effort
(`claude-opus-5-5@appical`, build, xhigh) and its transcript were on disk, but `forkFromCheckpoint`
(h #g305) keeps its checkpoints in memory only and `forkSessions` is off and in memory too, and
opencode had restarted three times since the parent's last turn (19:56Z, 20:29Z, 20:41Z). Candidate
fix: when a new key is about to replay, look in the resume store for a record of another affinity on
the same cwd, model, scope, agent and binary whose STRICT chain this history continues with nothing
but the fork's own new message past it, and start with `--resume <id> --fork-session` (the cut-at-end
case needs no `--resume-session-at`). Same snapshot caveat as h #g305, same refusals (busy parent,
transcript gone, tool result in the trailing segment). opencode 2's `Session.fork` names the source
session and could narrow the scan. A fork mid-thread still needs a persisted checkpoint uuid.

- 2026-11-14, found while fixing h #g312, not fixed (not in that PR's scope): dcp's `compact`
message reference (`\n@1044@`) is not stripped in two places that strip its XML form.
`src/claude-session-wrapper.ts` (the interactive transport types it into the TUI with the
Expand Down Expand Up @@ -240,6 +224,9 @@ Verification still owed, copied from the vault's `Future Features.md` "Next up"

## Done

- 2026-11-15: **done** (h #g319): after an opencode restart, a fork of the WHOLE conversation starts
from the parent's saved Claude session (`--resume <id> --fork-session`) instead of replaying it. A
fork from an earlier message after a restart still replays (no persisted checkpoint uuid).
- 2026-11-15: **done** (v0.73.6, PR #190, h #g318): the wire-inactivity watchdog defaults to 90 s instead of 60, because 7
of 51 `stream timeout` closes on this machine came 0 to 2 s before Claude Code announced a retry after
a stalled connection. Still open: the other 40 closes had no retry behind them and are not diagnosed.
Expand Down
45 changes: 45 additions & 0 deletions docs/agents-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -13222,3 +13222,48 @@ Shipped as v0.73.6 on 2026-11-15 (PR #190), a patch: CI green on Linux and Windo
on the merge commit `bebeccd` before the tag and on the release commit `91f80ec`, the publish confirmed
by the `Publish package` step's tail and the version document's shasum (`b0c6603a`), with a GitHub
Release.


## A fork of a whole conversation replayed it after an opencode restart (2026-11-15)

h #g319. Seen by the maintainer on 2026-11-15: session `ses_e1f0664f3ffe...` is `(fork #1)` of the
director session `ses_e7198d765ffeUT1TqjM6JP7LiP`, made at 20:50:16Z through the parent's LAST
message (opencode 2.2.6 `Session.fork` boundary `{"type":"through"}`, seq 14362). Its first turn logged
`replaying the conversation as text` with `no-sibling-recorded` and 2,888 messages, bounded to 180,000
characters, so the fork started with almost none of its context.

The cause: `forkFromCheckpoint` (h #g305) keeps its checkpoints in memory and `forkSessions` (off by
default) its fingerprints, and opencode had restarted three times since the parent's last turn
(`plugin ready` at 19:56Z, 20:29Z and 20:41Z). The parent's resume record for the same model, agent
and effort (`claude-opus-5-5@appical`, build, xhigh) and its transcript were on disk.

Change: `findForkResumePoint` (`src/session-resume-store.ts`) looks for a record of a sibling key
(`forkSiblingSignature`: the affinity free, cwd, model, scope, agent, prompt cache TTL and effort
pinned), the same binary, not being written to, its transcript on disk, and a STRICT chain this
history continues with nothing but the reply past it (`findResumePoint`'s test, so no tool result in
the trailing segment); the longest match wins. The prologue runs it after the in-memory fork lookup,
only where the turn was still about to replay, gated on `forkFromCheckpoint` and `resumeAfterRestart`
(it reads that option's records) and on the `--fork-session` help probe (`fork-cli-too-old`
otherwise), and starts the fork as `forkSessions` does: `--resume <id> --fork-session` headless,
`forkOf` on the interactive transport. The parent keeps its record and its conversation.

The lookup is given `options.prompt`, the prompt `recordResumePoint` digests, NOT the
`filterSideQuestionHistory` thread the in-memory checkpoints use: that filter drops the plugin's `▌`
note parts, which opencode stores inside the reply, so a reply that carried one (a `usage` note, say)
digested differently and every such fork was refused as `conversation-changed`. Found live, not by the
first fake (whose replies had no notes); the test now has a noted reply and fails with the filter.

Live on opencode 2.2.6 with the worktree build (a private `serve` under scratch XDG dirs, Haiku 5.5 on
the default account): two turns in session A taught it OTTER-77 and HERON-12, the server was stopped
and started, and `POST /api/session/{A}/fork` with `{}` made a fork with boundary
`{"type":"through"}` like the maintainer's. Before the prompt fix the fork replayed (`no-sibling-recorded`,
21,163 tokens written to the cache); after it, the fork logged `forking the claude session of the
conversation this one was forked from, saved before the restart`, spawned with `--resume <A's session>
--fork-session`, wrote 29 tokens to the cache (56,798 read) and answered `OTTER-77, HERON-12`.

Not covered: a fork from an earlier message after a restart still replays, because the record keeps
no checkpoint uuid to cut at. Same snapshot caveat as h #g305 (the fork answers under the system
prompt the parent first ran with). `test/fork-from-checkpoint.test.ts` drives it through a fake CLI
across a simulated restart; controls with the branch off and with the filtered prompt both fail. A
refused candidate logs `not forking from a conversation saved before the restart` at INFO with its
reason.
2 changes: 1 addition & 1 deletion docs/configuration/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ The minimum config is just the `plugin` entry above. Everything below is optiona
| `forkSessions` | boolean | `false` | Branch a forked opencode session off the parent's Claude conversation with `--fork-session` instead of replaying its history as text. A fork taken from a turn this opencode process served is already continued that way, cut at the turn, by `forkFromCheckpoint`; this option adds forks of a parent whose turn left nothing to cut at, and the interactive transport. See [The prompt cache an agent writes](../configuration/subagents.md#the-prompt-cache-an-agent-writes). |
| `forkCompaction` | boolean | `false` | Run `/compact` inside a fork of the chat's own Claude session (`--resume <id> --fork-session`) on the chat's own model, so the summary reads that session's prompt cache and sees the whole thread, instead of a text transcript on `compactionModel`. Cheaper and more faithful on a warm cache with an inexpensive chat model, about even on Opus, dearer on a cold cache. Headless only; falls back to the transcript whenever it cannot fork. See [Compaction on a fork](../guides/compaction-and-thinking.md#compaction-on-a-fork). |
| `forkOnRewind` | boolean | `true` | After an `/undo`, an edited message or a regenerated reply, continue a copy of the chat's Claude session cut at the last turn both versions of the thread share (`--resume <id> --resume-session-at <uuid> --fork-session`), instead of ending the session and replaying the shorter thread as text. Each answered turn records where its reply ended in Claude's transcript, and the copy holds exactly the turns that are left; the old transcript is never changed. Measured on Claude Code 2.1.288, 2.1.293 and 2.1.314 on a four-turn thread: 38 to 121 tokens written to the prompt cache against 11,152 to 20,659 for the replay, 6.9 to 9.7 times cheaper, faster every time, and the model kept a document line and a tool result that the replay's clipping had dropped. Anything it cannot match falls back to the replay: no recorded turn that the thread now ends on, a transcript or entry that is gone, the interactive transport (Claude Code takes the cut in print mode only), Claude Code older than 2.1.288, an account in another `accountGroups` group, and compaction. Like any `--resume`, the copy keeps the system prompt the conversation started with. See [Sessions](../internals/how-a-turn-works.md#sessions). |
| `forkFromCheckpoint` | boolean | `true` | When a new chat is forked from another one ("Fork from here", `/fork`), continue a copy of the parent's Claude session cut at the turn the fork was taken from (`--resume <id> --resume-session-at <uuid> --fork-session`), instead of replaying the inherited thread as text into a fresh session. The fork is recognised by content, on both opencode majors: its history has to match, reply for reply, a turn another chat in the same project served on the same model, agent and effort in this opencode process, and end on that turn's reply. The parent's transcript is never changed. Measured through opencode 2.2.6 and Claude Code 2.1.322 on Haiku 5.5, a 22 KB document and two codewords, forked before a third: 30 to 39 tokens written to the prompt cache against about 25,000 for the replay, 7.3 times cheaper (5.4 on opencode 1.19.4), and the fork quoted a line of the document that the replay's clipping had dropped. Like any `--resume`, the copy keeps the system prompt the parent started with; a chat in the same project on the same agent gets the same prompt (byte-identical in the measurement), so what can differ is the date line and an instruction file edited since. Anything it cannot match falls back to the replay: an opencode restart since the parent's turn, a turn that ended on a tool call, the parent mid-turn, another account, a transcript that is gone, the interactive transport and Claude Code older than 2.1.288. See [Sessions](../internals/how-a-turn-works.md#sessions). |
| `forkFromCheckpoint` | boolean | `true` | When a new chat is forked from another one ("Fork from here", `/fork`), continue a copy of the parent's Claude session cut at the turn the fork was taken from (`--resume <id> --resume-session-at <uuid> --fork-session`), instead of replaying the inherited thread as text into a fresh session. The fork is recognised by content, on both opencode majors: its history has to match, reply for reply, a turn another chat in the same project served on the same model, agent and effort in this opencode process, and end on that turn's reply. The parent's transcript is never changed. Measured through opencode 2.2.6 and Claude Code 2.1.322 on Haiku 5.5, a 22 KB document and two codewords, forked before a third: 30 to 39 tokens written to the prompt cache against about 25,000 for the replay, 7.3 times cheaper (5.4 on opencode 1.19.4), and the fork quoted a line of the document that the replay's clipping had dropped. Like any `--resume`, the copy keeps the system prompt the parent started with; a chat in the same project on the same agent gets the same prompt (byte-identical in the measurement), so what can differ is the date line and an instruction file edited since. After an opencode restart only a fork of the WHOLE conversation is continued (from the parent's saved session, `--resume <id> --fork-session`, which needs `resumeAfterRestart`); a fork from an earlier message replays. Anything else it cannot match falls back to the replay too: a turn that ended on a tool call, the parent mid-turn, another account, a transcript that is gone, the interactive transport and Claude Code older than 2.1.288. See [Sessions](../internals/how-a-turn-works.md#sessions). |
| `resumeAfterRestart` | boolean | `true` | After opencode restarts, resume a conversation's Claude session with `--resume` instead of replaying the whole thread as text into a fresh one. After each successful turn, and after one that failed on a usage limit or an expired login (Claude Code keeps that message in the session), the session id and a digest of the conversation are kept in `$XDG_STATE_HOME/opencode-claude-code-plugin/claude-sessions.json` (`0600`, at most 256 conversations, 30 days). It resumes only for the same opencode session, model, agent and account, when the transcript is still on disk and the conversation is exactly the one recorded plus Claude's reply; an edit, revert or compaction replays as before. [opencode-dcp](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning)'s own additions to a message are left out of the digest: its `<dcp-message-id>` references, because dcp renumbers them when opencode restarts and a conversation that had an undo in it would otherwise never resume, and its `<dcp-system-reminder>` context-limit warning, because dcp appends that to messages already in the history and the message would otherwise look edited on the next turn. A digest written by an earlier plugin version is still compared the way it was written. opencode's own `<system-reminder>` blocks are stored with the message, so they stay part of the digest. Like any `--resume`, the conversation keeps the system prompt it started with. `false` never reads or writes the file. |
| `liveModelSwitch` | boolean | `true` | Apply a model or reasoning effort change to the conversation's running `claude` process, with Claude Code's own `set_model` and `apply_flag_settings` control requests, instead of stopping it and starting another with `--resume`. The conversation and the prompt cache are the same either way (measured on Claude Code 2.1.288 and 2.1.314); what it saves is starting a process, which took 4.6 to 6.6 seconds per change on a real install, against about 0.7 s for a model change and well under a second for an effort change. So that an effort change can apply, a headless spawn on Claude Code 2.1.288 or newer passes the effort as `--effort` and leaves `CLAUDE_CODE_EFFORT_LEVEL` out of the child's environment, because that variable would silently override a live change. It applies only when the process is idle and the change is to the model (on the same account and in the same fast mode) or between two explicit effort levels; a change that arrives while a turn is still running applies from the next turn, as before. Anything else, a refusal, or no answer within `CLAUDE_CODE_LIVE_SWITCH_TIMEOUT_MS`, falls back to the respawn. The interactive transport always respawns. Needs `resumeAcrossModelChanges`; `false` restores the respawn and the environment-variable effort exactly. |
| `resumeAcrossModelChanges` | boolean | `true` | When you change a conversation's model or reasoning effort mid-conversation, continue the same Claude session (`--resume <id> --model <new>`) instead of replaying the whole thread as text. Both the model and the effort level are part of the session key, so changing either used to land a live conversation on a key nothing had answered; neither needs a new Claude conversation, because `--model` and `CLAUDE_CODE_EFFORT_LEVEL` are both applied at spawn time and the CLI accepts either on a transcript it resumes. The Claude session is moved off the old key rather than shared, so one conversation always has one owner. It refuses on everything `resumeAfterRestart` refuses on, plus a sibling whose transcript may still be written to (that turn finishes on the old process, and the change applies from the next one) and anything that is not the same request scope, opencode session and agent. A session opencode moved to another working directory (a `session_move` into a lane's worktree, say) is carried the same way: its transcript is copied from the old directory's project folder into the new one's and resumed there, and a turn that was still running when the session moved finishes in the old directory first. A change to an agent's prompt-cache TTL, `maxTurns` or `maxBudgetUsd` carries the conversation the same way; the new `maxBudgetUsd` counts from zero in the new process, as it does after any resume. Never on a compaction turn or an account switch. It reads the record `resumeAfterRestart` writes, which is also what carries the first change after an opencode restart, so `resumeAfterRestart: false` disables it too. |
Expand Down
Loading
Loading