@khalilgharbaoui/opencode-claude-code-plugin 0.35.1 → 0.36.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khalil Gharbaoui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -345,6 +345,8 @@ One piece of Claude Code trivia is worth stating plainly, because it is the oppo
 
 Like model and effort, the TTL is part of the Claude session key, so changing it respawns rather than sharing a process. Compaction is exempt.
 
+Forking an opencode session normally throws that cache away: the fork arrives as a new session with the thread copied in and no Claude session behind it, so the whole conversation is re-rendered as text into the first message and paid for again as cache writes. Setting `forkSessions: true` in the provider options branches the parent's Claude conversation with `claude --resume <parent> --fork-session` instead. Measured on CLI 2.1.280 with haiku 4.5 over a ~13k-token thread, the forked turn wrote 814 cache tokens and read 39,710, against 22,355 written and 17,385 read for the replay: $0.0058 against $0.0467 for that one turn, with the parent's own transcript byte-identical afterwards. It is off by default because a resumed Claude conversation reuses the system prompt recorded on its first request, so a forked session answers under the parent's appended system prompt rather than the current turn's. Anything it cannot match exactly keeps today's replay: another account, an unknown or busy parent, a fork cut mid-conversation or taken mid tool call, a different cwd, model, agent, effort or cache TTL, compaction, and the interactive transport.
+
 To force an **account** rather than a model, pin the full string. This only applies if you declared [`accounts`](#multiple-claude-code-accounts) in the first place; with the default single-account setup there is nothing to pin. Both halves are needed, because the provider selects the account's config dir and the `@account` marker is what the model was registered under for that provider:
 
 ```yaml
@@ -483,6 +485,7 @@ reaches the CLI, so there is nothing there to fall back from.
 | `bridgeSkipNativeSkills` | boolean | `true` | Leave a skill unbridged when the Claude session already loads it from `$CLAUDE_CONFIG_DIR/skills`, the project's `.claude/skills`, or an installed plugin, so one skill does not reach the model twice. Matched by resolved path, by identical `SKILL.md`, or by name. `false` bridges everything and reinstates the duplicates. See [Skills Claude already has](#skills-claude-already-has). |
 | `logging` | object | all defaults | The plugin's own logger, four independent fields: `file` (boolean, default `false`), `dir` (string, default `~/.local/share/opencode-claude-code/`), `mode` (`"silent"` \| `"debug"`, default `"silent"`) and `level` (`"debug"` \| `"info"` \| `"notice"` \| `"warn"` \| `"error"`, default `"info"`). Goes under `provider.claude-code.options` like every other row here. See [Logging](#logging). |
 | `turnStats` | boolean | `false` | Append a one-line cost / duration / cache footer to each finished turn. See [Per-turn stats](#per-turn-stats). |
+| `forkSessions` | boolean | `false` | Branch a forked opencode session off the parent's Claude conversation with `--fork-session` instead of replaying its history as text. See [The prompt cache an agent writes](#the-prompt-cache-an-agent-writes). |
 | `interactive` | boolean | `false` | **Experimental.** Drive the interactive `claude` TUI (subscription billing) instead of headless `--print`. Requires opencode running under Bun with PTY support; silently falls back to headless otherwise. The tool proxy, `permissionMode` and `/btw` are all unavailable on it, so read [What it does not support](#what-it-does-not-support) before enabling. Env: `CLAUDE_CODE_INTERACTIVE_TRANSPORT=1`. |
 | `interactiveBypass` | boolean | `false` | Deprecated/no-op with `interactive`: Claude Code's TUI shows a manual safety confirmation for `bypassPermissions`, so the plugin intentionally does not pass it. |
 | `interactiveAllowTools` | string[] | `["Bash", "Edit", "Write", "Read", "WebFetch"]` | With `interactive`: built-in tools pre-allowed without prompting (replaces the default list). MCP server wildcards (`mcp__<server>__*`) are always added from the bridged config. |

package/dist/index.d.ts

@@ -420,6 +420,8 @@ interface ClaudeCodeConfig {
     bridgeSkipNativeSkills?: boolean;
     /** Append a one-line cost / duration / cache footer to each finished turn. */
     turnStats?: boolean;
+    /** Branch a forked opencode session off the parent's Claude conversation. */
+    forkSessions?: boolean;
     logging?: LoggingConfig;
 }
 interface LoggingConfig {
@@ -761,6 +763,37 @@ interface ClaudeCodeProviderSettings {
      * `permission_denials` always reach `providerMetadata`.
      */
     turnStats?: boolean;
+    /**
+     * When a new opencode session turns out to be a fork of one this provider
+     * already served, branch the parent's Claude conversation with
+     * `claude --resume <parent> --fork-session` instead of re-rendering the
+     * whole thread as text into the first message.
+     *
+     * Measured on Claude Code 2.1.280 with haiku 4.5 over a ~13k-token
+     * conversation: the forked turn wrote 814 cache tokens and read 39,710,
+     * against 22,355 written and 17,385 read for the replay of the same thread,
+     * which is $0.0058 against $0.0467 for that one turn. The parent's own
+     * transcript is byte-identical afterwards (checked by hash).
+     *
+     * Off by default, and the reason is measured rather than cautious: a
+     * resumed Claude conversation reuses the system prompt recorded on its
+     * FIRST request (`--system-prompt-snapshot`, default `on`), so a forked
+     * session is answered under the parent's appended system prompt, not this
+     * turn's. Probed directly: a parent seeded with "your codename is ZEBRA"
+     * and forked while passing "your codename is QUAIL" answered ZEBRA. The
+     * conversation the model sees is otherwise the real transcript rather than
+     * the replay's clipped rendering, which is strictly more faithful and
+     * strictly cheaper, so this is worth turning on for branch-heavy work.
+     *
+     * It is also conservative about when it fires. Everything below keeps
+     * today's replay, unchanged: a different account, a parent whose Claude
+     * session id is unknown or gone, a parent that is still busy, a fork cut
+     * mid-conversation or taken mid tool round trip, a different cwd, model,
+     * agent, effort or prompt-cache TTL, a compaction turn, the interactive
+     * transport, an account-failover switch, and a `claude` with no
+     * `--fork-session` flag.
+     */
+    forkSessions?: boolean;
     /**
      * Routing for Claude's built-in `WebSearch` tool.
      *

package/dist/index.js

@@ -3931,6 +3931,190 @@ async function cancelBackgroundTask(input, options) {
   };
 }
 
+// src/session-fork.ts
+import { createHash as createHash3 } from "crypto";
+var fingerprints = /* @__PURE__ */ new Map();
+var fingerprintSeq = 0;
+var MAX_FORK_FINGERPRINTS = 64;
+function hashPart(hash, part) {
+  const p = part;
+  const type = typeof p?.type === "string" ? p.type : "unknown";
+  switch (type) {
+    case "text":
+      hash.update("text\0");
+      hash.update(String(p?.text ?? ""));
+      break;
+    case "tool-call":
+      hash.update("call\0");
+      hash.update(String(p?.toolName ?? ""));
+      hash.update("\0");
+      hash.update(stableJson(p?.input));
+      break;
+    case "tool-result":
+      hash.update("result\0");
+      hash.update(String(p?.toolName ?? ""));
+      hash.update("\0");
+      hash.update(stableJson(p?.output));
+      break;
+    case "file":
+    case "image": {
+      hash.update(type);
+      hash.update("\0");
+      hash.update(String(p?.mediaType ?? ""));
+      hash.update("\0");
+      const data = p?.data ?? p?.image;
+      if (typeof data === "string") hash.update(data);
+      else if (data instanceof Uint8Array) hash.update(data);
+      else if (data instanceof URL) hash.update(data.href);
+      else hash.update(stableJson(data));
+      break;
+    }
+    default:
+      hash.update("other\0");
+      hash.update(type);
+      break;
+  }
+  hash.update("");
+}
+function stableJson(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const walk = (node) => {
+    if (node === null || typeof node !== "object") return node;
+    if (seen.has(node)) return "[circular]";
+    seen.add(node);
+    if (Array.isArray(node)) return node.map(walk);
+    const out = {};
+    for (const key of Object.keys(node).sort()) {
+      out[key] = walk(node[key]);
+    }
+    return out;
+  };
+  try {
+    return JSON.stringify(walk(value)) ?? "null";
+  } catch {
+    return "[unserializable]";
+  }
+}
+function messageDigest(msg) {
+  const hash = createHash3("sha256");
+  hash.update(msg.role);
+  hash.update("\0");
+  if (typeof msg.content === "string") {
+    hash.update("text\0");
+    hash.update(msg.content);
+    hash.update("");
+  } else if (Array.isArray(msg.content)) {
+    for (const part of msg.content) hashPart(hash, part);
+  }
+  return hash.digest("hex").slice(0, 32);
+}
+function conversationDigests(prompt) {
+  const out = [];
+  for (const msg of prompt) {
+    if (msg.role !== "user" && msg.role !== "assistant" && msg.role !== "tool") {
+      continue;
+    }
+    out.push({
+      role: msg.role,
+      digest: messageDigest(msg)
+    });
+  }
+  return out;
+}
+function recordForkFingerprint(sessionKey2, prompt, cliPath) {
+  const entries = conversationDigests(prompt);
+  if (entries.length === 0) return;
+  fingerprints.delete(sessionKey2);
+  fingerprints.set(sessionKey2, { entries, cliPath, seq: ++fingerprintSeq });
+  while (fingerprints.size > MAX_FORK_FINGERPRINTS) {
+    const oldest = fingerprints.keys().next();
+    if (oldest.done) break;
+    fingerprints.delete(oldest.value);
+  }
+}
+function forgetForkFingerprint(sessionKey2) {
+  fingerprints.delete(sessionKey2);
+}
+function forkSiblingSignature(sessionKey2) {
+  const parts = sessionKey2.split("::");
+  if (parts.length < 5) return null;
+  if (parts[2] === "compaction") return null;
+  const blanked = [...parts];
+  blanked[3] = "*";
+  return blanked.join("::");
+}
+function splitForkHistory(prompt) {
+  const messages = prompt;
+  let lastAssistant = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "assistant") {
+      lastAssistant = i;
+      break;
+    }
+  }
+  if (lastAssistant < 0) return { history: [], forkable: false };
+  for (let i = lastAssistant + 1; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg.role === "tool") return { history: [], forkable: false };
+    if (!Array.isArray(msg.content)) continue;
+    for (const part of msg.content) {
+      if (part?.type === "tool-result") return { history: [], forkable: false };
+    }
+  }
+  return {
+    history: conversationDigests(messages.slice(0, lastAssistant + 1)),
+    forkable: true
+  };
+}
+function findForkParent(opts) {
+  const signature = forkSiblingSignature(opts.sessionKey);
+  if (!signature) return null;
+  const { history, forkable } = splitForkHistory(opts.prompt);
+  if (!forkable || history.length === 0) return null;
+  let best = null;
+  let bestLength = 0;
+  let bestSeq = -1;
+  for (const [key, fingerprint] of fingerprints) {
+    if (key === opts.sessionKey) continue;
+    if (fingerprint.cliPath !== opts.cliPath) continue;
+    if (forkSiblingSignature(key) !== signature) continue;
+    const recorded = fingerprint.entries;
+    if (recorded.length === 0 || recorded.length > history.length) continue;
+    if (!isPrefix(recorded, history)) continue;
+    if (!tailIsReplyOnly(history, recorded.length)) continue;
+    const claudeSessionId = opts.lookupClaudeSessionId(key);
+    if (!claudeSessionId) continue;
+    if (opts.isBusy(key)) continue;
+    if (recorded.length > bestLength || recorded.length === bestLength && fingerprint.seq > bestSeq) {
+      best = { parentKey: key, claudeSessionId, matched: recorded.length };
+      bestLength = recorded.length;
+      bestSeq = fingerprint.seq;
+    }
+  }
+  if (best) {
+    log.info("found a fork parent for this conversation", {
+      sessionKey: opts.sessionKey,
+      parentKey: best.parentKey,
+      matchedMessages: best.matched,
+      historyMessages: history.length
+    });
+  }
+  return best;
+}
+function isPrefix(recorded, history) {
+  for (let i = 0; i < recorded.length; i++) {
+    if (recorded[i].role !== history[i].role) return false;
+    if (recorded[i].digest !== history[i].digest) return false;
+  }
+  return true;
+}
+function tailIsReplyOnly(history, from) {
+  for (let i = from; i < history.length; i++) {
+    if (history[i].role === "user") return false;
+  }
+  return true;
+}
+
 // src/permission-presets.ts
 var READ_ONLY_DISALLOWED_CLI_TOOLS = [
   "Bash",
@@ -4535,6 +4719,11 @@ function claudeSessionIsBusy(key) {
   if (activeProcesses.has(key)) return true;
   return getPendingProxyCalls(key).length > 0 || hasExitPlanModeQuestions(key);
 }
+function claudeSessionIsWriting(key) {
+  const active = activeProcesses.get(key);
+  if (active && isTurnInFlight(active)) return true;
+  return getPendingProxyCalls(key).length > 0 || hasExitPlanModeQuestions(key);
+}
 function capClaudeSessions() {
   for (const key of [...claudeSessions.keys()]) {
     if (claudeSessions.size <= MAX_CLAUDE_SESSION_ENTRIES) return;
@@ -4558,6 +4747,7 @@ function deleteClaudeSessionId(key) {
   const claudeSessionId = claudeSessions.get(key);
   if (claudeSessionId) clearLedger(claudeSessionId);
   claudeSessions.delete(key);
+  forgetForkFingerprint(key);
 }
 function effortSessionKey(baseKey, effort) {
   return effort ? `${baseKey}::effort=${effort}` : baseKey;
@@ -4694,6 +4884,25 @@ function spawnClaudeProcess(cliPath, cliArgs, cwd, sessionKey2, proxyServer, mcp
   return ap;
 }
 function appendResumeIfNeeded(sessionKey2, cliArgs) {
+  if (cliArgs.includes("--fork-session")) {
+    const forkedSessionId = claudeSessions.get(sessionKey2);
+    if (!forkedSessionId) return cliArgs;
+    const resumed = [];
+    for (let i = 0; i < cliArgs.length; i++) {
+      if (cliArgs[i] === "--fork-session") continue;
+      if (cliArgs[i] === "--resume") {
+        resumed.push("--resume", forkedSessionId);
+        i++;
+        continue;
+      }
+      resumed.push(cliArgs[i]);
+    }
+    log.info("respawning a forked session on its own claude conversation", {
+      sessionKey: sessionKey2,
+      claudeSessionId: forkedSessionId
+    });
+    return resumed;
+  }
   if (cliArgs.includes("--resume") || cliArgs.includes("--session-id")) {
     return cliArgs;
   }
@@ -4734,6 +4943,7 @@ function buildCliArgs(opts) {
     sessionKey: sessionKey2,
     skipPermissions,
     includeSessionId = true,
+    forkFromClaudeSessionId,
     model,
     permissionMode,
     mcpConfig,
@@ -4783,6 +4993,8 @@ function buildCliArgs(opts) {
     const sessionId = claudeSessions.get(sessionKey2);
     if (sessionId && !activeProcesses.has(sessionKey2)) {
       args.push("--resume", sessionId);
+    } else if (forkFromClaudeSessionId) {
+      args.push("--resume", forkFromClaudeSessionId, "--fork-session");
     }
   }
   if (mcpConfig) {
@@ -5138,7 +5350,7 @@ async function handleBtwCommand(client, input, options = {}) {
 }
 
 // src/diagnostic-bundle.ts
-import { createHash as createHash3, randomBytes as randomBytes2 } from "crypto";
+import { createHash as createHash4, randomBytes as randomBytes2 } from "crypto";
 import { openSync, readSync, closeSync, fstatSync, realpathSync } from "fs";
 import { homedir as homedir4 } from "os";
 
@@ -5208,6 +5420,8 @@ var PLUGIN_LOG_MESSAGES = /* @__PURE__ */ new Set([
   "falling back to the next model in the chain",
   "fast mode is in cooldown after a rate limit; this turn runs at standard speed and is billed at standard Opus rates, not the fast price shown in the model picker.",
   "file part without data, skipping",
+  "forkSessions is on but this claude CLI has no --fork-session; replaying the conversation instead",
+  "forking the parent conversation's claude session instead of replaying it",
   "ignoring a failover reset time that is not in the future",
   "ignoring unknown proxyOpencodeTools entries",
   "ignoring unknown proxyTools entries",
@@ -5459,7 +5673,7 @@ function shape(value) {
   return `[redacted, ${size} chars]`;
 }
 function createIdHasher(salt = randomBytes2(16).toString("hex")) {
-  return (raw) => createHash3("sha256").update(salt).update("\0").update(raw).digest("hex").slice(0, 8);
+  return (raw) => createHash4("sha256").update(salt).update("\0").update(raw).digest("hex").slice(0, 8);
 }
 function createRedactionContext(options = {}) {
   const home = options.home ?? homedir4();
@@ -11507,6 +11721,49 @@ var ClaudeCodeLanguageModel = class {
     if (failoverAnswer?.kind === "switch" && hasPriorConversation) {
       includeHistoryContext = true;
     }
+    let forkFromClaudeSessionId;
+    if (this.config.forkSessions === true && includeHistoryContext && !compactionMode && !useInteractive && failoverAnswer?.kind !== "switch") {
+      const parent = findForkParent({
+        sessionKey: sk,
+        prompt: options.prompt,
+        cliPath,
+        lookupClaudeSessionId: getClaudeSessionId,
+        // `claudeSessionIsWriting`, not `getActiveProcess`: this walks every
+        // sibling key, and that one refreshes LRU order and cancels idle
+        // timers on everything it touches. An idle live child is fine to
+        // branch from; a transcript mid-write is not.
+        isBusy: claudeSessionIsWriting
+      });
+      if (parent) {
+        const supported = await Promise.race([
+          detectCliSupportsFlag(cliPath, "--fork-session"),
+          turnAbort.whenAborted.then(() => false)
+        ]);
+        if (turnAbort.aborted) {
+          return abortedBeforeWork("probing --fork-session support");
+        }
+        if (supported) {
+          forkFromClaudeSessionId = parent.claudeSessionId;
+          includeHistoryContext = false;
+          log.notice(
+            "forking the parent conversation's claude session instead of replaying it",
+            {
+              sessionKey: sk,
+              parentKey: parent.parentKey,
+              matchedMessages: parent.matched
+            }
+          );
+        } else {
+          log.warn(
+            "forkSessions is on but this claude CLI has no --fork-session; replaying the conversation instead",
+            { cliPath }
+          );
+        }
+      }
+    }
+    if (this.config.forkSessions === true && !compactionMode && !useInteractive) {
+      recordForkFingerprint(sk, options.prompt, cliPath);
+    }
     const { model: spawnModelId, fast: fastMode } = parseModelId(failover.modelId);
     const exitPlanModeQuestionResult = compactionMode ? null : consumeExitPlanModeQuestionResult(sk, options.prompt);
     if (exitPlanModeQuestionResult) {
@@ -11981,6 +12238,7 @@ var ClaudeCodeLanguageModel = class {
               state.cliArgs = buildCliArgs({
                 sessionKey: sk,
                 skipPermissions,
+                forkFromClaudeSessionId,
                 model: spawnModelId,
                 permissionMode: self.config.permissionMode,
                 mcpConfig: mcp.paths,
@@ -13211,6 +13469,7 @@ function createClaudeCode(settings = {}) {
       bridgeOpencodeSkills: settings.bridgeOpencodeSkills === true,
       bridgeSkipNativeSkills: settings.bridgeSkipNativeSkills !== false,
       turnStats: settings.turnStats === true,
+      forkSessions: settings.forkSessions === true,
       interactive: settings.interactive,
       interactiveBypass: settings.interactiveBypass,
       interactiveAllowTools: settings.interactiveAllowTools,