@khalilgharbaoui/opencode-claude-code-plugin 0.55.0 → 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 {
@@ -621,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
@@ -781,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` —
@@ -990,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.
      *
@@ -1403,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
@@ -1613,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`.