@khalilgharbaoui/opencode-claude-code-plugin 0.8.2 → 0.9.1

package/README.md

@@ -1,5 +1,7 @@
 # @khalilgharbaoui/opencode-claude-code-plugin
 
+[![npm](https://img.shields.io/npm/v/@khalilgharbaoui/opencode-claude-code-plugin.svg)](https://www.npmjs.com/package/@khalilgharbaoui/opencode-claude-code-plugin)
+
 An [opencode](https://opencode.ai) plugin that wraps the **Claude Code CLI** (`claude`) and routes model traffic through it instead of the Anthropic HTTP API. You get to use opencode's UI, agents, MCP, and permission system while authenticating and billing through whichever method `claude` is logged into (Pro/Max plan, Bedrock, Vertex, or API key).
 
 > Maintained fork of [`unixfox/opencode-claude-code-plugin`](https://github.com/unixfox/opencode-claude-code-plugin). Published as `@khalilgharbaoui/opencode-claude-code-plugin` on npm.
@@ -101,16 +103,21 @@ This plugin drives Claude Code headlessly (`claude --print`), which Anthropic bi
 | Pro | $20 |
 | Max 5x | $100 |
 | Max 20x | $200 |
-| Team Standard | $20/seat |
-| Team Premium | $100/seat |
-| Enterprise (Standard seats) | none |
+| Team (Standard seats) | $20 |
+| Team (Premium seats) | $100 |
+| Enterprise (usage-based) | $20 |
+| Enterprise (seat-based Premium seats) | $200 |
+
+Credits are **per user, not pooled** across a team, and Standard seats on seat-based Enterprise plans aren't eligible. See Anthropic's [Agent SDK credit article](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for the authoritative table.
 
 What this means for plugin users:
 
-- **Claim the credit once.** It's a one-time opt-in via your Claude account (claim emails started going out June 8, 2026); after that it refreshes every billing cycle. Unused credit does not roll over.
+- **Claim the credit once.** It's a one-time opt-in via your Claude account; eligible users get an email with claim instructions before June 15, 2026. After that it refreshes every billing cycle, and unused credit does not roll over.
+- **Agent SDK usage drains the credit first**, before any other source.
 - **When the credit runs out, plugin requests stop** until the next billing cycle — unless you enable usage credits in your Claude account, in which case overflow is billed at standard API rates.
 - **The credit is denominated in dollars at standard API rates**, so the Price × column above maps directly to how fast each model drains it — Fable 5 / Mythos 5 burn it 10× faster than Haiku, 2× faster than Opus 4.8.
 - **API-key auth is unaffected.** If your `claude` CLI authenticates with an Anthropic API key / Console billing instead of a subscription, nothing changes — pay-as-you-go as before.
+- **Watch for a stray `ANTHROPIC_API_KEY`.** If that variable (or `ANTHROPIC_AUTH_TOKEN`) is present in your environment, Claude Code uses it and bills pay-as-you-go — silently bypassing the subscription credit even when `claude` is logged into a plan. The plugin logs a one-time warning when it detects a key. To force subscription auth, set `ignoreAnthropicApiKey: true`, which strips the key from the `claude` spawn environment.
 - **Interactive Claude Code in your terminal is unaffected.** The change targets programmatic usage only: the Agent SDK, `claude -p`, Claude Code GitHub Actions, and third-party apps like this plugin.
 
 Two related dates:
@@ -209,6 +216,11 @@ The account model IDs are internally suffixed, for example `claude-sonnet-4-6@wo
 | `multiStepContinuation` | boolean | `true` | Append a system-prompt hint nudging Claude to chain tool calls within one turn instead of pausing between subtasks. Each opencode turn boundary requires the user to manually press "continue", so for multi-step tasks this reduces friction. Set `false` to disable. |
 | `autoContinueIncompleteTurns` | boolean \| `"smart"` | `"smart"` | Smartly continue incomplete Claude CLI results inside the same opencode turn. Reduces manual "continue" presses when Claude ends after reasoning/tool activity without a useful final answer. Set `false` to disable. |
 | `compactionModel` | string | `"claude-haiku-4-5"` | Model used when opencode invokes `/compact`. Override per-process via the `CLAUDE_CODE_COMPACTION_MODEL` env var (env wins over config). See [Compaction](#compaction). |
+| `ignoreAnthropicApiKey` | boolean | `false` | Strip `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from every spawned `claude` process so it authenticates with your logged-in subscription instead of pay-as-you-go API billing. The plugin warns once at startup whenever an API key is detected, regardless of this setting. See [Billing](#billing-change-june-15-2026-agent-sdk-credit). |
+| `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. Env: `CLAUDE_CODE_INTERACTIVE_TRANSPORT=1`. See [Interactive transport](#interactive-transport-experimental). |
+| `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. |
+| `interactiveSystemPrompt` | boolean | `true` | With `interactive`: append this plugin's CLI/AGENTS/continuation prompt via `--append-system-prompt-file`. The transport intentionally does not forward opencode's own system prompt, because it can trigger Claude Code's third-party-app usage gate on subscription accounts. Set `false` only for diagnostics. |
 
 ### Overriding model metadata
 
@@ -234,6 +246,39 @@ Anything you supply is merged on top of the defaults; you don't need to redeclar
 
 ---
 
+## Interactive transport (experimental)
+
+By default the plugin spawns `claude --print` (headless). From **June 15, 2026** that usage bills against the separate [Agent SDK credit](#billing-change-june-15-2026-agent-sdk-credit) on subscription plans. The interactive transport instead drives the real interactive `claude` TUI — which bills as **normal plan usage** — under a native PTY inside opencode's Bun runtime, types your prompt into it, and streams the session transcript (`~/.claude/projects/<cwd>/<session-id>.jsonl`) back through the same pipeline the headless transport uses.
+
+```json
+"options": { "interactive": true }
+```
+
+Or per-process: `CLAUDE_CODE_INTERACTIVE_TRANSPORT=1`.
+
+### Requirements
+
+- opencode must be running under **Bun** with `Bun.Terminal` (PTY) support. If it isn't, the flag is ignored and the headless transport is used — nothing breaks.
+- A logged-in `claude` (subscription auth). The whole point is plan billing, so API-key auth gains nothing here.
+
+### What carries over from the headless transport
+
+- The plugin's appended prompt (Claude CLI context, AGENTS.md guidance, continuation rules). The interactive transport intentionally does not forward opencode's own system prompt, because live testing showed that payload can trigger Claude Code's third-party-app usage gate on subscription accounts.
+- The MCP bridge: bridged servers are passed via `--mcp-config` + `--strict-mcp-config`, and every bridged server is pre-allowed as `mcp__<server>__*`.
+- Model selection, session reuse, and the whole streaming/usage pipeline.
+
+Set `interactiveSystemPrompt: false` only for diagnostics. While disabled, the interactive session will not receive the plugin's CLI context, AGENTS.md guidance, or continuation hints.
+
+### What's different
+
+- **Permissions:** the interactive TUI has no `can_use_tool` control channel, so tools can't be approved per-call through opencode. Built-in tools are pre-allowed via a settings allow list (default `Bash, Edit, Write, Read, WebFetch`; override with `interactiveAllowTools`). `bypassPermissions` is intentionally not used here because Claude Code shows a manual safety confirmation in the TUI and defaults to exit.
+- **Input is text-only:** images and other non-text blocks are dropped (with a logged warning); tool results are rendered as labeled text.
+- **Output granularity:** text arrives per transcript record, not token-by-token, so it can feel chunkier than headless streaming.
+- **Turn timeout:** a turn that produces no terminal stop within 30 minutes is reported honestly as an error result (visible truncation), not silently ended.
+- `/compact` always uses the headless transport regardless of this setting.
+
+---
+
 ## Selective tool proxy
 
 This is the core feature.
@@ -500,7 +545,7 @@ Partial support since v0.5.1. DCP runs in a useful degraded mode: automatic stra
 | DCP feature | Status | Notes |
 |---|---|---|
 | `experimental.chat.messages.transform` (compression placeholders, dedup, error purge) | ✅ Works | Transforms run inside opencode before reaching this plugin. |
-| `experimental.chat.system.transform` (context-limit nudges, iteration reminders) | ✅ Works | `extractSystemMessages` forwards system-role content to Claude CLI via `--append-system-prompt-file`. |
+| `experimental.chat.system.transform` (context-limit nudges, iteration reminders) | ✅ Works in headless | Headless spawns forward system-role content via `--append-system-prompt-file`. Interactive mode intentionally omits opencode's forwarded system prompt and keeps only this plugin's CLI/AGENTS/continuation prompt. |
 | `/dcp compress`, `/dcp sweep`, `/dcp manual`, `/dcp context`, `/dcp stats` slash commands | ✅ Works | Handled by opencode's `command.execute.before` hook, not the model. |
 | Automatic `deduplication` + `purgeErrors` strategies | ✅ Works | Message-transform only, no model tool calls. |
 | Autonomous model-driven `compress` tool calls | ❌ Not supported | DCP registers `compress` as an opencode-native tool. Claude CLI only sees its own built-ins and MCP-bridged servers, so the model never sees `compress`. The plugin prepends a runtime note instructing Claude to ignore any system instruction that asks it to call `compress`/`distill`/`prune`. |

package/dist/index.d.ts

@@ -138,6 +138,16 @@ type LogMode = "silent" | "debug";
 interface ClaudeCodeConfig {
     provider: string;
     cliPath: string;
+    /** Drive interactive claude (subscription) instead of headless --print. */
+    interactive?: boolean;
+    /** Deprecated/no-op with interactive: Claude Code's TUI requires manual confirmation for bypassPermissions. */
+    interactiveBypass?: boolean;
+    /** With interactive: built-in tools to allow without prompting (replaces
+     *  the default Bash/Edit/Write/Read/WebFetch list; MCP wildcards are always
+     *  derived from the bridged config). */
+    interactiveAllowTools?: string[];
+    /** With interactive: append this plugin's own prompts via --append-system-prompt-file. Defaults to true. */
+    interactiveSystemPrompt?: boolean;
     cwd?: string;
     account?: string;
     configDir?: string;
@@ -157,6 +167,7 @@ interface ClaudeCodeConfig {
     multiStepContinuation?: boolean;
     autoContinueIncompleteTurns?: boolean | "smart";
     compactionModel?: string;
+    ignoreAnthropicApiKey?: boolean;
     logging?: LoggingConfig;
 }
 interface LoggingConfig {
@@ -190,6 +201,16 @@ interface LoggingConfig {
 type WebSearchRouting = "claude" | "disabled" | (string & {});
 interface ClaudeCodeProviderSettings {
     cliPath?: string;
+    /** Drive interactive claude (subscription) instead of headless --print. */
+    interactive?: boolean;
+    /** Deprecated/no-op with interactive: Claude Code's TUI requires manual confirmation for bypassPermissions. */
+    interactiveBypass?: boolean;
+    /** With interactive: built-in tools to allow without prompting (replaces
+     *  the default Bash/Edit/Write/Read/WebFetch list; MCP wildcards are always
+     *  derived from the bridged config). */
+    interactiveAllowTools?: string[];
+    /** With interactive: append this plugin's own prompts via --append-system-prompt-file. Defaults to true. */
+    interactiveSystemPrompt?: boolean;
     cwd?: string;
     name?: string;
     providerID?: string;
@@ -247,6 +268,17 @@ interface ClaudeCodeProviderSettings {
      * (see opencode's agent docs).
      */
     proxyTools?: string[];
+    /**
+     * Strip `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from the environment of
+     * every spawned `claude` process. When an API key is present, Claude Code
+     * authenticates with it (pay-as-you-go Console billing) instead of the
+     * logged-in Pro/Max subscription — silently bypassing the Agent SDK plan
+     * credit. Set this to `true` to force the CLI to fall back to its stored
+     * subscription auth. Defaults to `false` (the key is passed through, so
+     * deliberate API-key users are unaffected). Regardless of this setting, the
+     * plugin logs a one-time warning at startup when an API key is detected.
+     */
+    ignoreAnthropicApiKey?: boolean;
     /**
      * Routing for Claude's built-in `WebSearch` tool.
      *