@khalilgharbaoui/opencode-claude-code-plugin 0.54.2 → 0.56.0

package/README.md

@@ -18,6 +18,8 @@
 [![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.
@@ -106,10 +108,16 @@ This README used to hold all of the above. Release notes and bookmarks point at
 
 Made and maintained by [Khalil Gharbaoui (@khalilgharbaoui)](https://github.com/khalilgharbaoui). This plugin absorbs work from its forks directly, cherry-picked with the original authorship preserved or reimplemented with the author named in the commit. The people behind the features you are using, and what each built, are on the [Credits](./docs/credits.md) page; `git log --author` on this repo shows the preserved authorship.
 
-Free and MIT-licensed. If the plugin saves you time, you can buy [its maintainer](https://github.com/khalilgharbaoui) a coffee:
+## Support
+
+This plugin is maintained, not a side project that gets abandoned when the next Claude Code or opencode release breaks something. Keeping it working means tracking CLI flag changes, opencode plugin API changes, and new model IDs as they ship.
+
+If the plugin saves you time, you can keep it maintained here:
 
 <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>
 
+One-off or recurring, both help. Bug reports and PRs are welcome too; see [`AGENTS.md`](./AGENTS.md) for the contribution rules.
+
 ## License
 
 MIT. See [LICENSE](./LICENSE). The first version was written by Émilien ([@unixfox](https://github.com/unixfox)); everything since by [Khalil Gharbaoui](https://github.com/khalilgharbaoui) and the people in [Credits](./docs/credits.md).

package/dist/index.d.ts

@@ -425,6 +425,8 @@ interface ClaudeCodeConfig {
     proxyOpencodeTools?: string[];
     stripContextReminders?: boolean;
     extraDisallowedTools?: string[];
+    /** See `ClaudeCodeProviderSettings.mapReadRules`. Default true. */
+    mapReadRules?: boolean;
     proxyToolTimeoutMs?: Record<string, number>;
     /**
      * Route `ExitPlanMode` through opencode's native `question` tool so plan
@@ -458,6 +460,16 @@ interface ClaudeCodeConfig {
     resumeAcrossModelChanges?: boolean;
     /** Carry a conversation's Claude transcript over on an account switch. Default true. */
     crossAccountResume?: boolean;
+    /** See `ClaudeCodeProviderSettings.maxBudgetUsd`. Resolved; unset is off. */
+    maxBudgetUsd?: number;
+    /** See `ClaudeCodeProviderSettings.budgetWarnAt`. Resolved percentages. */
+    budgetWarnAt?: number[];
+    /** See `ClaudeCodeProviderSettings.maxBackgroundSubagents`. Resolved; unset is off. */
+    maxBackgroundSubagents?: number;
+    /** Resolved `usageWarnThresholds`, in percent; empty for no notes. */
+    usageWarnThresholds?: number[];
+    /** Resolved `usageSwitchAt`, in percent, or null for never. */
+    usageSwitchAt?: number | null;
     logging?: LoggingConfig;
 }
 interface LoggingConfig {
@@ -490,12 +502,13 @@ interface LoggingConfig {
 }
 type WebSearchRouting = "claude" | "disabled" | (string & {});
 /**
- * What happens when the account a conversation runs on is out of usage.
- * `"ask"` (default) shows the operator a form listing the other configured
- * accounts and applies the pick inside the same turn; `"off"` keeps today's
- * behaviour, where the turn ends with the rate-limit error.
+ * What happens when the account a conversation is running on is out of usage
+ * or cannot serve. `"off"` (the default, also what unset means) ends the turn
+ * on one `▌ **usage limit:**` note; `"ask"` ends it on a form listing the
+ * other configured accounts and continues on the pick; `"auto"` moves the same
+ * request to the next eligible configured account without asking.
  */
-type AccountFailoverMode = "ask" | "off";
+type AccountFailoverMode = "ask" | "off" | "auto";
 /** `subagentDispatch`. Unset behaves as `"off"`; see the option's own note. */
 type SubagentDispatchMode = "ask" | "off";
 interface ClaudeCodeProviderSettings {
@@ -539,11 +552,13 @@ interface ClaudeCodeProviderSettings {
      */
     accountInProcess?: boolean;
     /**
-     * When this account is out of usage, show the operator a form listing the
-     * other configured accounts and continue the task on the pick, inside the
-     * same opencode turn. `"ask"` by default, which only does anything when
-     * more than one account is configured. `"off"` keeps the plain rate-limit
-     * error. See README "Account failover".
+     * What a usage limit or an account that cannot serve does to the turn.
+     * Unset or `"off"` (the default) ends it on one `▌ **usage limit:**` note.
+     * `"ask"` shows a form listing the other configured accounts and continues
+     * on the pick. `"auto"` continues the same request on the next eligible
+     * configured account, in configured order, without asking. Both only do
+     * anything when more than one account is configured. See
+     * docs/configuration/accounts.md.
      */
     accountFailover?: AccountFailoverMode;
     /**
@@ -618,6 +633,43 @@ interface ClaudeCodeProviderSettings {
      * the cache they wrote. See `resolveAgentCacheTtl` in `src/agent-models.ts`.
      */
     defaultSubagentCacheTtl?: string;
+    /**
+     * `--max-turns` for discovered `mode: subagent` agents that declare no
+     * `maxTurns` of their own. Counted by the CLI per user message, so a reused
+     * process is not used up by it (measured on 2.1.293, h #g245). Unset (the
+     * default) passes nothing. See `resolveAgentCliCaps` in `src/agent-models.ts`.
+     */
+    defaultSubagentMaxTurns?: number;
+    /**
+     * `--max-budget-usd` for discovered `mode: subagent` agents that declare no
+     * `maxBudgetUsd` of their own. The CLI counts it over the process's whole
+     * life, which is why it is a subagent-only cap (h #g245). Unset (the
+     * default) passes nothing.
+     */
+    defaultSubagentMaxBudgetUsd?: number;
+    /**
+     * A dollar cap on one opencode conversation: its own turns plus every
+     * subagent it dispatched, summed from the CLI's own `total_cost_usd`. Unset
+     * (the default) is no cap and no bookkeeping. Notes at `budgetWarnAt`, and
+     * once the sum reaches the cap the next turn ends before anything is spawned,
+     * with one `▌ **budget:**` note and an error finish. Compaction is exempt.
+     * In memory only: see `src/budget-ledger.ts`.
+     */
+    maxBudgetUsd?: number;
+    /**
+     * Percentages of `maxBudgetUsd` at which one `▌ **budget:**` note is
+     * written, each once per conversation. Default `[50, 80]`; `[]` keeps the
+     * stop and drops the notes.
+     */
+    budgetWarnAt?: number[];
+    /**
+     * How many background subagents may run at once, counted from the
+     * dispatches this opencode process saw opencode accept. A `background: true`
+     * `task` or `task_batch` that would go over it is refused as a whole with a
+     * tool result naming the cap and the running count. Foreground dispatch is
+     * never capped. Unset (the default) is no cap.
+     */
+    maxBackgroundSubagents?: number;
     /**
      * Models to try, in order, when the model a turn would have run on is
      * refused. The default for every agent that declares no `fallbackModels` of
@@ -778,6 +830,34 @@ interface ClaudeCodeProviderSettings {
      * the model has to work without it.
      */
     extraDisallowedTools?: string[];
+    /**
+     * Translate opencode's own `read` permission DENY rules into Claude Code
+     * deny rules for the Read the CLI runs itself. On by default: it closes a
+     * hole operators reasonably assume is already closed.
+     *
+     * `Read`, and whatever other file readers a CLI ships, are not proxied by
+     * default (`proxyTools` is Bash, Edit, Write, WebFetch, Task), so without
+     * this a file opencode would refuse to read for its own `read` tool is read
+     * by Claude with no prompt. Measured on 2026-10-16 with opencode 1.19.0 and
+     * Claude Code 2.1.293: "read .env with your Read tool" returned the planted
+     * secret.
+     *
+     * What is mapped, and what is not:
+     *   - a `deny` becomes `--disallowedTools "Read(<pattern>)"`, which covers
+     *     every file-reading tool the CLI has (its own rule validator says
+     *     Read rules are the only file rules matched);
+     *   - an `ask` is NOT turned into a deny. A headless spawn runs with the
+     *     skip flag and has nobody to ask, and opencode's own `*.env` default
+     *     is an `ask`, so denying it would refuse reads the operator expects to
+     *     approve. `/claude-code-doctor` lists them as not enforced;
+     *   - `glob`, `grep`, `list` and `external_directory` rules are not mapped:
+     *     Claude Code's deny beats its allow, so "outside the working directory"
+     *     cannot be said without denying the working directory too. Use
+     *     `permissionPreset: "read-only"` (which sends `--restricted`) for that.
+     *
+     * Set `false` to send nothing and keep the CLI's own posture.
+     */
+    mapReadRules?: boolean;
     /**
      * Per-tool proxy call timeouts in milliseconds, keyed by the proxy tool
      * name (`bash`, `edit`, `write`, `webfetch`, `task`, `question` —
@@ -987,6 +1067,23 @@ interface ClaudeCodeProviderSettings {
      * verified live. Set `false` to keep the replay.
      */
     crossAccountResume?: boolean;
+    /**
+     * Usage levels, in percent of a window, at which a served turn ends with one
+     * `▌ **usage:**` note naming the account, the window, how much is used and
+     * when it resets. Default `[50, 75, 90, 95]`; `[]` turns the notes off. Each
+     * threshold is said once per account per window, and again only after the
+     * window resets. Read from Claude Code's own `rate_limit_event`, so the
+     * headless transport only. See docs/configuration/accounts.md.
+     */
+    usageWarnThresholds?: number[];
+    /**
+     * The usage level, in percent, at which work should leave this account
+     * BEFORE it hits the wall. Default `90`; `false` or `0` never. With
+     * `accountFailover: "auto"` and another eligible account, new turns move to
+     * it until the window resets; otherwise the note names the other accounts to
+     * pick a model from. The turn that crossed is never changed: it was served.
+     */
+    usageSwitchAt?: number | false;
     /**
      * Routing for Claude's built-in `WebSearch` tool.
      *
@@ -1400,6 +1497,22 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * `⚙ invalid` and wedge the turn, so the plugin keeps the text path.
      */
     private resolvePlanModeQuestion;
+    /**
+     * The ledger this turn keeps under `maxBudgetUsd` (h #g245), or null for
+     * none. The parent lookup runs once per session per process and only with a
+     * cap set, so a default install never pays for it. A lookup that cannot
+     * answer reads as "no parent", which makes the session its own conversation:
+     * its spend is still counted, against its own budget.
+     */
+    private resolveTurnBudget;
+    /**
+     * A turn the session budget stopped before anything was spawned: one
+     * `▌ **budget:**` note (when the turn may write one) and an error finish,
+     * the shape a usage limit has had since h #g214. A child session gets an
+     * `error` part instead of the note, so the parent's `task` result says why
+     * without the note becoming the subagent's answer.
+     */
+    private budgetStopStream;
     /**
      * A dispatch form, as a turn: one synthetic `question` tool call and a
      * `tool-calls` finish, which is how the operator's answer comes back on the
@@ -1489,6 +1602,31 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * because which method opencode used is not in them.
      */
     private streamTurn;
+    /**
+     * Run the turn, moving the same request to the next eligible configured
+     * account when the one it ran on is out of usage or cannot serve
+     * (`accountFailover: "auto"`). The single wiring point for the automatic
+     * switch, and outside `runModelChain` on purpose: an account switch starts
+     * that account's own model chain from the top.
+     *
+     * Anything but `"auto"` is `runModelChain` and one `await`, so `"off"` and
+     * `"ask"` are exactly what they were. With `"auto"`, the attempt that failed
+     * decides the switch itself (`completeResult` sets `run.switchTo` and closes
+     * its stream without a `finish`), and the next attempt's prologue makes the
+     * switch the form's pick would have made. This only splices the attempts
+     * into one caller turn: one `stream-start`, and the `finish` of whichever
+     * attempt did not switch.
+     *
+     * The bound is `run.tried`, as it is `tried` for the model chain: every
+     * account spawned or switched to goes in, and none in it is picked again.
+     *
+     * Cancelling the returned stream is a stop, for every attempt: this loop is
+     * the plugin starting more work on the caller's behalf, so a caller that
+     * has gone away must reach all of it. Each attempt gets a signal that the
+     * caller's own `abortSignal` and a `cancel()` both abort, and the loop
+     * starts no further account once either has happened.
+     */
+    private runAccountFailover;
     /**
      * Run the turn, moving to the next model in the fallback chain if the one
      * it started on is refused. The single wiring point for `src/model-fallback.ts`.
@@ -1585,6 +1723,17 @@ type AgentRecord = {
      * and not the CLI's per-agent `experimental.cacheTtl`.
      */
     cacheTtl?: string;
+    /**
+     * `--max-turns` for this agent's own `claude` process. Raw as declared (a
+     * number in opencode.json, a string in frontmatter); `resolveAgentCliCaps`
+     * checks it.
+     */
+    maxTurns?: number | string;
+    /**
+     * `--max-budget-usd` for this agent's own `claude` process. Subagents only;
+     * see `resolveAgentCliCaps` for why.
+     */
+    maxBudgetUsd?: number | string;
     /**
      * Models to try, in order, when the one this agent would have run is
      * refused. Same account throughout; see `src/model-fallback.ts`.