@khalilgharbaoui/opencode-claude-code-plugin 0.64.0 → 0.65.0

package/README.md

@@ -18,8 +18,6 @@
 [![License](https://img.shields.io/github/license/khalilgharbaoui/opencode-claude-code-plugin?style=flat-square&label=license&labelColor=15181E&color=FFC46B)](./LICENSE)
 [![Buy me a coffee](https://img.shields.io/badge/support-buy%20me%20a%20coffee-FFC46B?style=flat-square&labelColor=15181E&logo=buymeacoffee&logoColor=FFC46B)](https://www.buymeacoffee.com/khalilgharbaoui)
 
-<a href="https://www.buymeacoffee.com/khalilgharbaoui"><img src="site/public/buy-me-a-coffee.png" alt="Buy me a coffee" width="214" height="60"></a>
-
 **Claude Code is the provider.** This opencode plugin runs Anthropic's Claude models through the official **Claude Code CLI** (`claude`) as a subprocess instead of calling the HTTP API. opencode inherits whatever that CLI is logged in as (a Claude subscription, an API key, Bedrock or Vertex), gets Claude's own tools, MCP servers and skills, and keeps running the tools that touch your machine itself, behind its own permission prompts. One package serves opencode 1.x and 2.x.
 
 - **Your CLI's login, untouched.** The plugin never reads, stores or replays a token. Lifting the OAuth session out of the official client is what proxy-style plugins do, and Anthropic disallowed that for third-party Claude use in February 2026. This plugin structurally cannot do it.
@@ -46,9 +44,13 @@
    }
    ```
 
-   `~/.config/opencode/opencode.json` on opencode 1.x. opencode 2 reads the same key; its native spelling is `plugins`.
+   `~/.config/opencode/opencode.json`, on opencode 1.x and 2.x alike. opencode 2's native key is `plugins`, and `opencode plugin add @khalilgharbaoui/opencode-claude-code-plugin` writes that entry and installs the package for you.
+
+3. **Quit opencode fully and relaunch.** Plugins load once, at process start. The model picker now has a **Claude Code** provider (opencode 1.x labels it with its id, `claude-code`) with entries such as `Claude Sonnet 5.5 (2×)` and `Claude Opus 5 (5×)`; the suffix is each model's list price relative to Haiku. A model's full id is `claude-code/<model>`, so one line checks it from a terminal:
 
-3. **Quit opencode fully and relaunch.** Plugins load once, at process start. The model picker now has a **Claude Code (Default)** provider with entries such as `Claude Sonnet 5.5 (2×)` and `Claude Opus 5 (5×)`; the suffix is each model's list price relative to Haiku.
+   ```bash
+   opencode run -m claude-code/claude-haiku-5-5 "reply with ok"
+   ```
 
 Nothing in the picker? [Troubleshooting](./docs/troubleshooting/symptoms.md) is keyed on the first thing you see. `/claude-code-doctor` in any session prints what the plugin thinks is happening, without calling a model.
 
@@ -70,12 +72,14 @@ Nothing in the picker? [Troubleshooting](./docs/troubleshooting/symptoms.md) is
 | | opencode's native `anthropic` provider | This plugin | Proxy and token-reuse plugins |
 |---|---|---|---|
 | **Authentication** | A Platform API key in opencode's auth store. | Whatever the official `claude` CLI holds. No token is read, stored or replayed. | The Claude OAuth session, used outside the official client. |
-| **Terms-of-service status** | The ordinary API route. | Sanctioned: the official client does the authenticating. | Disallowed. Anthropic disallowed reusing subscription authentication for third-party Claude use in February 2026, and each of those projects carries its own disclaimer. |
+| **Terms-of-service status** | The ordinary API route. | Uses the official client: Claude Code does the authenticating, the same as running `claude -p` yourself. Anthropic's [legal page](https://code.claude.com/docs/en/legal-and-compliance) allows signing in to the unmodified binary; it has not approved or endorsed this plugin. | Disallowed. Anthropic disallowed reusing subscription authentication for third-party Claude use in February 2026, and each of those projects carries its own disclaimer. |
 | **Who runs Bash, Edit, Write** | opencode. | opencode, by default; `Read`, `Grep`, `Glob` run in Claude Code. | opencode. |
 | **What it costs you** | Baseline. | A `claude` child per conversation under a cap of 16; Claude Code may compact its own context behind opencode's back. | One more moving part, plus the account risk above. |
 
 The [full comparison](./docs/comparison.md) has nine rows, names the projects in the third column, and quotes their own READMEs.
 
+On opencode 2.2.3 or later with one Claude login, also look at opencode's own **Claude Agent** provider: it drives your own `claude` too, runs every tool in opencode, and leaves your `~/.claude` setup out. The comparison has [a section on it](./docs/comparison.md#opencodes-built-in-claude-agent-provider), including what this plugin still adds (opencode 1.x, several accounts, your Claude Code setup, fast mode, `/btw`, the sidebar).
+
 ## Built from measurements
 
 A dozen test files drive a fake `claude` through real turns: the stream parser, the proxy broker, both watchdogs, abort, respawn, account failover and the model fallback chain are exercised end to end. Every rule in [`AGENTS.md`](./AGENTS.md) names the probe, the version and the number that produced it, and the evidence lives in [`docs/agents-history.md`](./docs/agents-history.md). Two runtime dependencies. The [site](https://opencode-claude-code-plugin.dev/) reports the live numbers: it rebuilds itself after every release, on every push that moves a figure, and every six hours.

package/dist/index.d.ts

@@ -113,6 +113,81 @@ interface V2ModelRequestEvent {
 interface V2ModelHookOptions {
     readonly providerID?: string;
 }
+/**
+ * `@opencode/plugin` 2.2.2 `SessionRetry`, the `session.hook("retry")` event:
+ * opencode asks before it runs a failed turn again (h #g277).
+ */
+interface V2SessionRetryEvent {
+    readonly sessionID: string;
+    readonly model: {
+        readonly id: string;
+        readonly providerID: string;
+    };
+    readonly error: {
+        readonly type?: string;
+        readonly message?: string;
+    };
+    readonly attempt: number;
+    decision: {
+        retry: false;
+    } | {
+        retry: true;
+        delay: number;
+    };
+}
+/** One way to connect an integration (`IntegrationMethod`); only `type` is always there. */
+interface V2IntegrationMethod {
+    readonly type: string;
+    readonly id?: string;
+    readonly label?: string;
+}
+/** `@opencode/plugin` 2.2.2 `IntegrationEditor`, the calls we make. */
+interface V2IntegrationEditor {
+    get(id: string): {
+        id: string;
+        name: string;
+    } | undefined;
+    update(id: string, update: (integration: {
+        id: string;
+        name: string;
+    }) => void): void;
+    readonly method: {
+        list(integrationID: string): readonly V2IntegrationMethod[];
+        update(input: {
+            integrationID: string;
+            method: {
+                id: string;
+                type: "external";
+                label: string;
+            };
+        }): void;
+        remove(integrationID: string, method: V2IntegrationMethod): void;
+    };
+}
+/** `@opencode/client` `ConnectionInfo`, passed back to opencode untouched. */
+interface V2ConnectionInfo {
+    readonly type: string;
+    readonly id?: string;
+    readonly label?: string;
+}
+/** `@opencode/schema/connection` `Connection.Status`. */
+interface V2ConnectionStatus {
+    status: "needs_auth";
+    message: string;
+    url?: string;
+}
+/** `@opencode/plugin` 2.2.2 `IntegrationDomain`, the slice `/connect` needs. */
+interface V2IntegrationDomain {
+    transform(callback: (editor: V2IntegrationEditor) => void): Promise<V2Registration>;
+    readonly connection: {
+        active(integrationID: string): Promise<V2ConnectionInfo | undefined>;
+        status(input: {
+            integrationID: string;
+            connection: V2ConnectionInfo;
+            status: V2ConnectionStatus | undefined;
+        }): Promise<void>;
+    };
+}
 /** `@opencode/schema/prompt-input` `Prompt`: we only rewrite `text`. */
 type V2Prompt = {
     text?: string;
@@ -158,6 +233,8 @@ interface V2Context {
     readonly options: Record<string, unknown>;
     readonly provider: {
         transform(callback: (editor: V2ProviderEditor) => void): Promise<V2Registration>;
+        /** Re-runs the transforms. In `@opencode/plugin` 2.2.5; optional because older hosts may lack it. */
+        reload?(): Promise<void>;
     };
     readonly aisdk: {
         hook(name: "sdk", callback: (event: V2AISDKSdkEvent) => Promise<void> | void, options?: V2ModelHookOptions): Promise<V2Registration>;
@@ -165,6 +242,7 @@ interface V2Context {
     };
     readonly session: {
         hook(name: "model.request", callback: (event: V2ModelRequestEvent) => Promise<void> | void, options?: V2ModelHookOptions): Promise<V2Registration>;
+        hook(name: "retry", callback: (event: V2SessionRetryEvent) => Promise<void> | void, options?: V2ModelHookOptions): Promise<V2Registration>;
         prompt?(input: V2Prompt & {
             sessionID: string;
             delivery?: V2Delivery;
@@ -180,6 +258,8 @@ interface V2Context {
             signal?: AbortSignal;
         }): AsyncIterable<V2Event>;
     };
+    /** `/connect`'s entry for each provider (h #g277). Optional: early 2.0 releases lack parts of it. */
+    readonly integration?: V2IntegrationDomain;
     /**
      * Absent before 2.0.31's measured shape: the definition is plain JSON
      * Schema, which `Rpc.PortableDefinition` accepts, and the handlers object is
@@ -444,7 +524,11 @@ interface ClaudeCodeConfig {
     controlRequestDenyMessage?: string;
     proxyTools?: string[];
     proxyOpencodeTools?: string[];
+    /** See `ClaudeCodeProviderSettings.alwaysLoadProxyTools`. Default bash, edit, write. */
+    alwaysLoadProxyTools?: boolean | string[];
     stripContextReminders?: boolean;
+    /** See `ClaudeCodeProviderSettings.verbatimPrompts`. Default true. */
+    verbatimPrompts?: boolean;
     extraDisallowedTools?: string[];
     /** See `ClaudeCodeProviderSettings.mapReadRules`. Default true. */
     mapReadRules?: boolean;
@@ -481,6 +565,8 @@ interface ClaudeCodeConfig {
     resumeAfterRestart?: boolean;
     /** Carry a conversation's Claude session over when its model or effort changes. Default true. */
     resumeAcrossModelChanges?: boolean;
+    /** Apply a model or effort change to the live `claude` process. Default true. */
+    liveModelSwitch?: boolean;
     /** Carry a conversation's Claude transcript over on an account switch. Default true. */
     crossAccountResume?: boolean;
     /** See `ClaudeCodeProviderSettings.maxBudgetUsd`. Resolved; unset is off. */
@@ -536,6 +622,26 @@ type AccountFailoverMode = "ask" | "off" | "auto";
 type SubagentDispatchMode = "ask" | "off";
 interface ClaudeCodeProviderSettings {
     cliPath?: string;
+    /**
+     * Register the model catalog as the installed Claude Code describes it.
+     * Default `true`.
+     *
+     * A background probe asks the CLI, once per CLI version, which models it
+     * knows, the context window it runs each in and the effort levels it
+     * accepts, and keeps the answer in `cli-models.json` under
+     * `$XDG_STATE_HOME`. Providers are registered from that file: windows and
+     * effort variants follow the CLI, and a model the CLI's own picker offers
+     * that the catalog lacks is added at an unknown (zero) price. Costs and the
+     * `(N×)` labels stay the catalog's, because the CLI carries no prices.
+     *
+     * Free: each probe is a `--bare` process with no credential, sent
+     * `initialize` and `get_context_usage` and never a message (measured: no
+     * API request, h #g279). Registration never waits for it, so a fresh answer
+     * applies at once on opencode 2 (a provider reload) and from the next
+     * start on opencode 1. `false` registers the built-in catalog as it ships
+     * and runs no probe.
+     */
+    cliModelCatalog?: boolean;
     /** Internal: set by the opencode 2 entrypoint. See `ClaudeCodeConfig.hostApi`. */
     hostApi?: "v1" | "v2";
     /** Wins over the legacy interactive option and its environment fallback. */
@@ -839,6 +945,39 @@ interface ClaudeCodeProviderSettings {
      * reminder is then something the model can actually act on.
      */
     stripContextReminders?: boolean;
+    /**
+     * Which proxy tools Claude Code loads into every request instead of
+     * deferring them behind its `ToolSearch` tool. Default `["bash", "edit",
+     * "write"]`.
+     *
+     * Claude Code defers every MCP tool, the proxy's included, so the first
+     * proxied call in a `claude` process costs one extra API request to find
+     * the tool. A listed tool is served with `_meta["anthropic/alwaysLoad"]`,
+     * which skips that request: measured on Claude Code 2.1.314, a turn that
+     * ran a proxied `bash` took 2 API calls instead of 3, with 32% fewer prompt
+     * tokens and 41% lower cost, while a turn that called no tool carried 531
+     * more prompt tokens. `true` loads every tool the proxy serves (the MCP
+     * tools `proxyOpencodeMcpTools` adds included), `false` defers them all as
+     * before. Names are the proxy's lowercase tool names. An older Claude Code
+     * ignores the field.
+     */
+    alwaysLoadProxyTools?: boolean | string[];
+    /**
+     * Deliver the text of every message as written. Default true.
+     *
+     * Claude Code reads the last text block of a headless user message the way
+     * it reads typing: a leading `/` runs one of its commands and an `@path`
+     * attaches that file. Measured on Claude Code 2.1.314, a message `/model
+     * claude-sonnet-5-5` switched the running process to Sonnet without a
+     * model call, and a message starting with a path such as `/etc/hosts` lost
+     * the environment, deferred-tool, agent and skill context of its turn. On,
+     * each envelope carries `client_composed: true`, the field the Agent SDK's
+     * `verbatimPrompts` sets, and the text reaches Claude unchanged; hooks,
+     * CLAUDE.md and the skill listing still arrive. The one thing lost is the
+     * `ultrathink` keyword's reminder: use an effort variant instead. Headless
+     * transport only; an older Claude Code ignores the field.
+     */
+    verbatimPrompts?: boolean;
     /**
      * Extra Claude Code built-ins to switch off with `--disallowedTools`,
      * on top of the ones implied by `proxyTools`.
@@ -1079,6 +1218,29 @@ interface ClaudeCodeProviderSettings {
      * false` turns this off too.
      */
     resumeAcrossModelChanges?: boolean;
+    /**
+     * Apply a model or reasoning effort change to the conversation's running
+     * `claude` process, with the CLI's own `set_model` and `apply_flag_settings`
+     * control requests, instead of stopping it and starting another with
+     * `--resume`. Default `true`.
+     *
+     * Measured on Claude Code 2.1.288 and 2.1.314 (h #g278): the conversation is
+     * kept, the next request goes out under the new model or effort, and the
+     * prompt cache reads and writes are the same as the respawn's. What it saves
+     * is the respawn itself, 4.6 to 6.6 seconds to `system`/`init` per change on
+     * a real install, against about 25 ms for an effort change and 0.5 to 0.7 s
+     * for a model change. To make an effort change possible, a headless spawn
+     * carries its effort as `--effort` and drops CLAUDE_CODE_EFFORT_LEVEL: the
+     * variable beats a live change silently.
+     *
+     * Only between two models on the same account and in the same fast mode,
+     * between two explicit efforts, on an idle child (a change that lands
+     * mid-turn still finishes that turn on the old settings, h #g271), and on
+     * the headless transport: the interactive one has no control channel and
+     * keeps respawning. Any refusal or timeout falls back to the respawn. Needs
+     * `resumeAcrossModelChanges`; `false` here restores the respawn exactly.
+     */
+    liveModelSwitch?: boolean;
     /**
      * Continue the same Claude conversation when it moves to another account,
      * instead of replaying the whole thread as text into a fresh session there.