@khalilgharbaoui/opencode-claude-code-plugin 0.26.2 → 0.27.0

package/README.md

@@ -250,6 +250,7 @@ What a pick does, in full:
 - **The conversation is replayed, not resumed.** Claude transcripts live under each account's own `CLAUDE_CONFIG_DIR`, so `--resume` cannot cross accounts. The plugin starts a fresh Claude session on the target and replays the thread from opencode's history, then tells it to carry on. That costs input tokens on the new account, and anything the CLI held but opencode did not is gone.
 - **Per-profile MCP servers do not come along.** A server configured only in the limited account's Claude profile is simply absent on the target.
 - **`stop`, dismissing the form, or any answer that is not one of the offered accounts** ends the turn exactly the way the rate-limit error ends it today.
+- **An account that cannot serve at all gets the same form.** When Claude Code reports that an account's login expired (`authentication_failed`), or that it is on hold, unverified or has a billing problem, the plugin writes a note naming the account and what to do, and offers the switch if another account is configured. For an expired login the note gives the exact command, for example `CLAUDE_CONFIG_DIR=~/.claude-work claude auth login`. The switch lasts until opencode restarts, so restart after logging in again to move back. With a single account you get the note alone.
 
 Only two things open the form: a `rate_limit_event` the CLI marked `rejected`, and the two known account-limit error texts (`Third-party apps now draw from your extra usage…`, `You've hit your individual spend limit`). A generic 4xx, a timeout or a bad flag never does, deliberately: a transient failure must not quietly move where your usage is billed.
 
@@ -365,7 +366,8 @@ model: claude-code-work/claude-opus-5@work
 | `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). |
 | `idleProcessTimeoutMs` | number | – | Kill a retained headless Claude worker after this many idle milliseconds following a completed turn. The timer starts when a turn finishes, a new turn cancels it, a worker that is mid-turn when it fires is left alone and re-timed, and the session id is preserved for `--resume`. Values above Node's maximum timer delay (`2147483647`) are ignored. Omit or set `0` to retain workers until LRU eviction (16 processes). Interactive transport is excluded. Contributed by [@bernardofortes](https://github.com/bernardofortes). |
-| `bridgeOpencodeSkills` | boolean | `false` | Expose your opencode skills to Claude's native `Skill` tool. Off by default because every bridged skill is also in the system prompt opencode forwards, so a large set is paid for twice per turn; the bundled configuration skill is staged either way. See [Skill bridge](#skill-bridge). Written by [@broskees](https://github.com/broskees). |
+| `bridgeOpencodeSkills` | boolean | `false` | Expose your opencode skills to Claude's native `Skill` tool, from every root opencode itself reads. Off by default because every bridged skill is also in the system prompt opencode forwards, so a large set is paid for twice per turn; the bundled configuration skill is staged either way. See [Skill bridge](#skill-bridge). Written by [@broskees](https://github.com/broskees). |
+| `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). |
 | `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`. |
@@ -777,6 +779,7 @@ Four Claude Code stream events used to reach nothing but a debug log:
 
 - **A rate-limit rejection.** When the CLI reports `status: "rejected"` (or a rejected extra-usage state), the turn now carries a `▌ **rate limit:**` line naming the window, the reason extra usage is unavailable, when it resets, and the four things that can be done about it. Warned once per identity per process. See [Billing](#billing-change-june-15-2026-agent-sdk-credit).
 - **A context compaction Claude Code did on its own.** A `▌ **context compacted:**` note says so, with the before and after token counts, so an answer that suddenly forgets the start of the conversation has a visible cause.
+- **A conversation Claude Code cleared.** Sending `/clear` as a message, or a plan-mode exit that clears context, makes Claude Code start a fresh conversation while opencode still shows the old messages. A `▌ **claude code reset:**` note says so. The plugin deliberately does not replay the earlier messages, since that would undo the clear. Start a new opencode session if you want the two to match.
 - **A `result` whose subtype is not `success`** (`error_max_turns`, `error_during_execution`, …). The subtype is named in the transcript and the turn finishes as an error instead of an ordinary reply.
 - **A CLI-executed tool that failed.** Its result is forwarded with the AI SDK's error flag, so opencode renders the row as failed rather than as a success whose output happens to be an error message.
 
@@ -798,7 +801,7 @@ No separate skill installation or copying is needed. It ships with each package
 
 ## Skill bridge
 
-opencode and Claude Code use the same on-disk skill format, a `<name>/SKILL.md` whose frontmatter carries `name` and `description`, but they read from different directories. opencode looks in `.opencode/skills/` and `~/.config/opencode/skills/`; the Claude CLI looks in `~/.claude/skills/` and its own plugins. So opencode advertises your skills in the system prompt it forwards, the model calls `Skill("browser-automation")`, and Claude answers `Unknown skill`.
+opencode and Claude Code use the same on-disk skill format, a `<name>/SKILL.md` whose frontmatter carries `name` and `description`, but they read from overlapping, not identical, directories. opencode looks in `.opencode/skills/`, `~/.config/opencode/skills/`, `~/.agents/skills/` and more; the Claude CLI looks in `~/.claude/skills/`, the project's `.claude/skills/` and its own plugins. Where they differ, opencode advertises a skill in the system prompt it forwards, the model calls `Skill("browser-automation")`, and Claude answers `Unknown skill`. Where they overlap, the same skill reaches one session twice.
 
 By default the plugin discovers your opencode skills, stages a throwaway Claude Code plugin directory that links them, and passes it as `claude --plugin-dir`. They register natively, prefixed with the plugin name:
 
@@ -809,9 +812,33 @@ opencode-skills:rtk
 
 Claude can invoke them with the Skill tool or as `/opencode-skills:<name>`. `--plugin-dir` is scoped to the spawned session, so nothing is written into your `~/.claude`.
 
-Discovery order, first match wins: `.opencode/skills/` walking up from the working directory, then `~/.opencode/skills/`, then `$OPENCODE_CONFIG_DIR/skills/`, then `~/.config/opencode/skills/`. A project skill shadows a global one of the same name. If the skill set is unchanged the staged directory is reused between spawns.
+Discovery covers every root opencode itself reads, first match wins:
 
-The bridge is **off by default**: every bridged skill's name and description is also in the system prompt opencode already forwards, so a large skill set is paid for twice on every turn. Set `bridgeOpencodeSkills: true` when the model tries `Skill("<name>")` for a skill opencode advertises and gets `Unknown skill`; the bundled configuration skill is staged either way. When on, the bridge applies to the headless, interactive and direct `doGenerate` spawns alike, never to compaction, and it is skipped on a Claude CLI without `--plugin-dir` (the plugin probes `claude --help` and logs a notice).
+1. Walking up from the working directory: `.opencode/skills/`, `.claude/skills/`, `.agents/skills/` at each level.
+2. `~/.opencode/skills/`.
+3. `$OPENCODE_CONFIG_DIR/skills/` and `.../skill/`.
+4. `~/.config/opencode/skills/` and `.../skill/` (or `$XDG_CONFIG_HOME`).
+5. `~/.claude/skills/` and `~/.agents/skills/`.
+
+A project skill shadows a global one of the same name, and an opencode-managed copy shadows an external one. Step 5 is opencode's own "external" scan and honours its `OPENCODE_DISABLE_EXTERNAL_SKILLS` and `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` variables. A skill is known by the `name:` its `SKILL.md` frontmatter declares, falling back to the directory name, which is what opencode advertises. If the skill set is unchanged the staged directory is reused between spawns.
+
+### Skills Claude already has
+
+Those roots overlap Claude Code's own, which reads `$CLAUDE_CONFIG_DIR/skills/` (`~/.claude/skills/` by default), the project's `.claude/skills/`, and the `skills/` folder of every installed plugin. Without care one skill reaches a single session twice, costing prompt tokens on every turn and leaving it ambiguous which copy answers.
+
+So `bridgeSkipNativeSkills` (**on by default**) leaves a skill unbridged when Claude already loads it. A skill counts as already loaded when:
+
+- it is literally the same directory, symlinks resolved;
+- its `SKILL.md` is byte-identical to a native one, wherever that one lives (this is the case for a skill installed as a Claude plugin *and* symlinked into `~/.agents/skills`);
+- a **different** skill of the same name is registered under user or project scope. Plugin skills are namespaced `<plugin>:<name>` and so never take a bridged name, only duplicate its content.
+
+Only that last case changes which copy answers `Skill("<name>")`, so it is logged at WARN naming both paths; the others are logged at INFO. Set `bridgeSkipNativeSkills: false` to bridge everything regardless and get the duplicates back.
+
+One limitation worth knowing: the plugin scan reads `installed_plugins.json` and does not check whether that plugin is actually enabled, so a skill from a disabled plugin can be treated as native. If a skill disappears, grep `plugin.log` for `skills claude code already loads`: one line names both paths and the reason.
+
+### Enabling it
+
+The bridge itself is **off by default**: every bridged skill's name and description is also in the system prompt opencode already forwards, so a large skill set is paid for twice on every turn. Set `bridgeOpencodeSkills: true` when the model tries `Skill("<name>")` for a skill opencode advertises and gets `Unknown skill`; the bundled configuration skill is staged either way. When on, the bridge applies to the headless, interactive and direct `doGenerate` spawns alike, never to compaction, and it is skipped on a Claude CLI without `--plugin-dir` (the plugin probes `claude --help` and logs a notice).
 
 This bridge was written by [@broskees](https://github.com/broskees) (Joseph Roberts) on his fork and absorbed here with credit; see [Credits](#credits).
 

package/dist/index.d.ts

@@ -407,6 +407,8 @@ interface ClaudeCodeConfig {
     idleProcessTimeoutMs?: number;
     /** Stage opencode skills as a `--plugin-dir` so Claude's Skill tool can run them. */
     bridgeOpencodeSkills?: boolean;
+    /** Leave out the skills the Claude session already loads natively. Default true. */
+    bridgeSkipNativeSkills?: boolean;
     /** Append a one-line cost / duration / cache footer to each finished turn. */
     turnStats?: boolean;
     logging?: LoggingConfig;
@@ -662,17 +664,41 @@ interface ClaudeCodeProviderSettings {
      */
     idleProcessTimeoutMs?: number;
     /**
-     * Expose your opencode skills (`.opencode/skills`, `~/.config/opencode/skills`)
-     * to Claude Code's native Skill tool by staging them as a session-scoped
-     * `--plugin-dir`, so a `Skill("<name>")` call for a skill opencode advertises
-     * does not fail with `Unknown skill`. Off by default: every bridged skill
-     * is also listed in the system prompt opencode forwards, so a large skill
-     * set costs prompt tokens twice per turn. When on it applies to the
-     * headless, interactive and direct `doGenerate` spawns alike; compaction
-     * never loads it, and the bundled configuration skill is staged either way.
-     * No-op on CLIs without `--plugin-dir`.
+     * Expose your opencode skills to Claude Code's native Skill tool by staging
+     * them as a session-scoped `--plugin-dir`, so a `Skill("<name>")` call for a
+     * skill opencode advertises does not fail with `Unknown skill`. Covers every
+     * root opencode itself reads: project `.opencode/`, `.claude/` and `.agents/`
+     * walking up from the workspace, the opencode config dirs, and the global
+     * `~/.claude/skills` and `~/.agents/skills` (those last two behind the same
+     * `OPENCODE_DISABLE_EXTERNAL_SKILLS` / `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS`
+     * switches opencode honours).
+     *
+     * Off by default: every bridged skill is also listed in the system prompt
+     * opencode forwards, so a large skill set costs prompt tokens twice per turn.
+     * When on it applies to the headless, interactive and direct `doGenerate`
+     * spawns alike; compaction never loads it, and the bundled configuration
+     * skill is staged either way. No-op on CLIs without `--plugin-dir`.
      */
     bridgeOpencodeSkills?: boolean;
+    /**
+     * Leave a skill unbridged when the Claude Code session already loads it:
+     * from `<CLAUDE_CONFIG_DIR>/skills` (`~/.claude/skills` by default), from the
+     * project's own `.claude/skills`, or from an installed plugin's `skills/`.
+     * On by default, because those roots overlap opencode's and the duplicate
+     * costs prompt tokens on every turn for nothing.
+     *
+     * A skill is treated as already loaded when it is literally the same
+     * directory (symlinks resolved), when its SKILL.md is byte-identical to a
+     * native one, or when a *different* skill of the same name is registered
+     * under user or project scope. That last case is the only one that changes
+     * behaviour, because `Skill("<name>")` then answers from Claude's copy
+     * rather than opencode's, so it is logged at WARN naming both paths. Plugin
+     * skills are namespaced `<plugin>:<name>` and so only ever match by content.
+     *
+     * Set `false` to bridge everything regardless, which restores the pre-0.25
+     * behaviour of advertising a shared skill twice.
+     */
+    bridgeSkipNativeSkills?: boolean;
     /**
      * Append one compact line to the end of every finished (non-compaction,
      * non-error) turn with what that turn cost: dollars, wall duration, how many
@@ -804,6 +830,14 @@ interface ClaudeStreamMessage {
         agent_id?: string;
         description?: string;
     };
+    /**
+     * On an `assistant` message the CLI synthesised to report a failure: the
+     * kind of failure (`authentication_failed`, `billing_error`, ...). Read by
+     * `accountBlockKind`; schema confirmed on Claude Code 2.1.280.
+     */
+    error?: string;
+    /** On a `conversation_reset`: the conversation Claude Code started. */
+    new_conversation_id?: string;
     message?: {
         role?: string;
         model?: string;
@@ -987,6 +1021,13 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * spawn block resolves anything: `userMsg` is built well ahead of it.
      */
     private stripContextRemindersEnabled;
+    /**
+     * Arguments the skill bridge needs beyond `cwd` / `cliPath`: which
+     * `CLAUDE_CONFIG_DIR` this spawn reads its native skills from, and whether
+     * to drop the ones it already loads. A failover moves the spawn to another
+     * account, and therefore to that account's config dir.
+     */
+    private skillBridgeSpawn;
     /** Share one lazy registry request within a turn without making it stale. */
     private createLiveToolInfoLoader;
     /**