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: 3 additions & 1 deletion AGENTS.md

Large diffs are not rendered by default.

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

## Backlog

- 2026-11-15, seen by the maintainer while h #g317 was in progress, not fixed: session
`ses_e324dbf7bffeRHQIz10AIxm7dT` (the h #g314 / h #g315 session) is stuck in a blocked-replay loop.
At 02:16:22Z a turn on `claude-fable-5-2@appical` (effort high, 510 messages, bounded to 152)
replayed with reason `sibling-conversation-changed`, agent-guard blocked it ("contains secret-like
values"), and v0.73.4 dropped the empty session as designed, so every next message replays and is
blocked the same way. The note's advice (switch back to the model or account that answered before)
likely does not help here: that key's resume record was written before the two usage-limited turns
(h #g315 fixes the recording only for turns from v0.73.4 on), so its own lookup refuses as
`conversation-changed` too, unless its `claude` is still alive in memory. To check: which keys hold a
record for this session, and whether accepting a lagging record whose missing messages the
transcript itself holds (h #g315's measurement) is safe. Never by changing what the replay sends to
get past the guard.

- 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 @@ -99,9 +112,9 @@
("agent-guard: the prompt exceeds the assignment-probe scan cap ...", `promptKept: false`) in the
worktree cwd's transcript `a9e1ac0c-416d-4644-bd57-e70eae20aae6.jsonl`, so the new key replayed the
history and the guard refused it by size. h #g314 turns that into a `prompt blocked` note and an
error. Still open: that a location switch replays the thread at all (a new cwd is a new session key,
and Claude's transcript lives under the old cwd's directory). The `fix/session-move` worktree
(no commits yet) is where that would go.
error. Why it replayed at all is FIXED on `fix/session-move` (h #g317): a moved session's
conversation is carried into the new directory (transcript copied, `--resume`), and a step that
answers the call that moved it finishes on the old directory's child.

- 2026-11-10, found by the pr173 lane (h #g295), not measured: Claude Code 2.1.322 adds fast mode on
Vertex, while `docs/models.md` says fast mode excludes Bedrock, Vertex and Foundry. Check on a Vertex
Expand Down
85 changes: 85 additions & 0 deletions docs/agents-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -13096,3 +13096,88 @@ Shipped as v0.73.4 on 2026-11-15 (PR #188), a patch, together with h #g314 and h
Linux and Windows on the PR head `eb00f1c`, on the merge commit `7f893c2` before the tag and on
the release commit `00a4f19`, the publish confirmed by the `Publish package` step's tail and the
version document's shasum (`a2d145ff`), with a GitHub Release.


## A session opencode moved to another directory replayed the thread instead of carrying it (2026-11-15)

h #g317. The location-switch empty turn recorded in TODO.md on 2026-11-14: in session
`ses_e2898d33effeo0ojQzfvfWVOJK` (opencode 2.2.6), a lane ran `shell` to create its worktree, then
Code Mode `execute` (`session_move` into that worktree). opencode recorded `location-switched` at
00:14:18Z, the next step started at 00:14:21Z, and at 00:14:27.770Z Claude Code 2.1.322 wrote
`blocked_by_hook` ("agent-guard: the prompt exceeds the assignment-probe scan cap ...",
`promptKept: false`) into the WORKTREE directory's transcript `a9e1ac0c-...`: the step had replayed
the whole history as text into a fresh session, and the guard refused it by size. h #g314 turns that
block into a note; this entry is why the step replayed at all.

The cause is the session key: `<cwd>::<model>::<scope>::<affinity>::context=[...]`. opencode 2
resolves the spawn's cwd from the session's own directory per call (`resolveSpawnCwdForSession`),
so after a move every turn lands on a key nothing has answered. `modelSiblingSignature` (the sibling
lookup over the resume store, h #g215) and `conversationIdentity` (h #g271's routing of a step to
the key whose child is still in the turn) both kept the cwd, so neither saw the old key.

Measured on Claude Code 2.1.322, Haiku 5.5, `--setting-sources ""`, no MCP, two scratch git repos A
and B, the appical config dir (the default account was at its 5-hour limit):

- Seeded in A (codeword ZEBRA-41): 11,160 read from the cache, 6,348 written.
- `--resume` of that session from B with nothing copied: found (the CLI searches every project
folder), the codeword kept, and the model gave B as its working directory: the environment block
is not part of the system prompt snapshot (h #g187). Cache: 14,071 read, 3,630 written. The CLI
appended to A's file (148,893 to 159,237 bytes) and wrote nothing under B's name.
- Control, a fresh seed resumed from A: 17,555 read, 25 written.
- A fresh seed whose transcript was copied under B's name first, resumed from B: 17,701 read, 0
written (the B prefix was already cached from the first resume), appended to the copy (159,161
bytes), A's file untouched (148,881).

So a move needs no new Claude conversation and costs about the environment block's tail once, while
the replay rewrites the whole thread and may be refused. But a resume with no copy keeps writing
under the old directory's name, where `findResumePoint` (it checks the transcript under the turn's
own cwd) and the interactive transport (it tails the path it computes from the cwd) never look.

What changed:

- `modelSiblingSignature` blanks the cwd as well as the model, the effort, the spawn settings and
the account, except for the shared `default` affinity, which is no one conversation (two
`opencode run`s in two folders). So `findSiblingResumePoint` finds the old directory's record,
checks its transcript under the sibling's own cwd, and returns `siblingCwd`.
- The caller carries the transcript with `carryTranscriptToAccount`, which takes `sourceCwds` now:
every config dir is searched under the turn's cwd and the source cwds, the longest copy wins, the
copy always lands under the turn's cwd, and nothing is overwritten (a taken target path takes a
fresh id, h #g218). Then the old key's child is stopped and `transferClaudeSession` moves the id,
the resume record and the served chain, as for a model change. Its own NOTICEs:
`continuing this conversation's claude session in the session's new directory instead of
replaying it`, and `replaying this conversation rather than carrying it to the session's new
directory` with the refusal token.
- `conversationIdentity` blanks the cwd, so a step that answers the call that moved the session
(parked in the old directory's child) is served on that child, and the turn's `cwd` becomes that
key's. The rest of that turn runs in the old directory, exactly as h #g271 finishes a model change
mid-turn under the old model; the next turn finds it idle and carries.
- Widening the signature also widens `findForeignAccountSibling`, the `accountGroups` detector,
which is the safe direction for a guard.

Live on opencode 2.2.6 with this build (a private `serve` under scratch XDG dirs, basic auth as
`opencode` with the printed server password, Haiku 5.5 on the default account): a session created in
repo A (`POST /api/session` with `{"location":{"directory":...}}`) answered "Remember the codeword
ZEBRA-41" on Claude session `ac24c30c-...`; `POST /api/session/{id}/move` with `{"directory": <repo
B>}` answered 204 and the session's `location.directory` became repo B; the next prompt logged
`carrying the claude conversation over to the new session key` and `continuing this conversation's
claude session in the session's new directory instead of replaying it`, spawned in repo B with
`--resume ac24c30c-...`, and answered `ZEBRA-41 | <repo B>`. Cache on that turn: 38,958 read, 18,292
written (the first turn wrote 56,776): opencode's forwarded system prompt carries the working
directory too, so more of it is rewritten than with the bare CLI, still about a third of what a
replay rewrites. The transcript: repo A's original left at 492,221 bytes, repo B's copy 502,753 after
the turn.

Not changed: it reads the resume store, so with `resumeAfterRestart: false` a move replays, as a
model change does. A fork into another directory (`forkSessions`, `forkFromCheckpoint`) still keys
on the cwd. Not measured live: the mid-turn move (a Code Mode `execute` calling `session_move`),
which the fake-CLI test covers, and the interactive transport (the copy lands where its tail looks,
by construction).

Tests: `test/session-move.test.ts` (two real `doStream` turns in two directories of one opencode
session, with a fake CLI that resumes only a transcript under its own directory: carried and
copied, the original untouched, one owner on disk; after a simulated restart too; another session
never carried; `resumeAfterRestart: false` replaying; the two carry tests fail with the signature
change switched off), the mid-turn step in `test/effort-sessions.test.ts` (without the routing the
step never reaches the parked child and the test times out), `sourceCwds` in
`test/account-transcript.test.ts`, and the updated signature cases in
`test/session-model-switch.test.ts` and `test/account-groups.test.ts`.
2 changes: 1 addition & 1 deletion docs/configuration/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ The minimum config is just the `plugin` entry above. Everything below is optiona
| `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). |
| `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 working directory, request scope, opencode session and agent. 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. |
| `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. |
| `crossAccountResume` | boolean | `true` | On an account switch, whether you pick another account's model by hand in the same session or through the [switch form](./accounts.md), and only between accounts in the same `accountGroups` group, continue the same Claude conversation on the other account instead of replaying the whole thread as text into a fresh session there. An account is a `CLAUDE_CONFIG_DIR` and a conversation is one transcript file inside it, so the switch copies that file into the target account's own `projects/<encoded cwd>/` (`0600`, never overwriting, never through a symlink) and spawns it with the `--resume` that already exists. Claude Code 2.1.288 resumes a copied transcript with its context intact and resolves a session by filename, so an older copy already sitting at the target path makes the carry take a fresh session id rather than overwrite it. The source transcript is never moved, emptied or written to. Any refusal falls back to the replay and says which in the log. Does nothing on a single-account install. |
| `usageWarnThresholds` | number[] | `[50, 75, 90, 95]` | Usage levels, in percent of a usage window, at which a served turn ends with one `▌ **usage:**` line: which account, which window, how much of it is used, and when it resets in your own time zone. Each threshold is said once per account per window (not again on the next turn, from another session, or after a restart) and again only after the window resets. Never on a `/compact` turn or in a subagent's session. Read from Claude Code's own usage reports, so the interactive transport (which gets none) only records a limit. `[]` turns the notes off; the readings are still kept for the sidebar and `/claude-code-doctor`. Works with one account. See [Usage before the limit](./accounts.md#usage-before-the-limit). |
| `usageSwitchAt` | number \| `false` | `90` | The usage level, in percent, at which work should leave an account **before** it hits the limit, when another account in the same `accountGroups` group is configured and is not itself at that level. With `accountFailover: "auto"`, new turns move to that account until the window resets (the same account-wide switch a usage limit makes, held in memory), and the `▌ **usage:**` line says so. With `"ask"` or `"off"` nothing moves and no form is raised: the line names the other account to pick a model from. The turn that crossed is never changed. `false` or `0` turns it off. See [Usage before the limit](./accounts.md#usage-before-the-limit). |
Expand Down
Loading
Loading