unixfox · khalilgharbaoui · May 13, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -12,10 +12,11 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org
+      - run: npm install -g npm@latest
       - run: npm install
       - run: npm run build
       - name: Publish package

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/README.md b/README.md
diff --git a/TODO.md b/TODO.md
@@ -0,0 +1,101 @@
+# Deferred Checks
+
+## Ideas
+
+- 2026-09-06, maintainer: "maybe someday we still want to align it with plan mode of opencode maybe".
+  Deferred, not scheduled. Make `permissionMode: "plan"` follow opencode's own plan/build agent
+  instead of being a static provider option.
+
+  Cheaper than it looks, and the objection that killed it the first time does not apply:
+  the opencode agent is already part of the session key
+  (`...::ses_...::context=["claude-code-appical","build"]`), so plan and build turns already
+  run as separate `claude` processes. A Tab back to build would spawn one without the flag,
+  so a coupled design is not a one-way door the way the static option is.
+
+  What still argues against it, and what to re-check before building:
+  1. `"plan"` is only a name. Users define their own agents called plan, some of which write
+     plan documents into the repo, and forcing CLI plan mode would break those silently.
+     Any implementation needs an explicit opt-in rather than a name match.
+  2. The two disagree about how you leave. Claude Code expects an `ExitPlanMode` tool call
+     that headless `--print` never offers (measured on 2.1.258, probes recorded in AGENTS.md),
+     so the model searches for a tool it cannot find and narrates confusion. Re-run those
+     probes first: if a newer CLI offers `ExitPlanMode` headless, this objection dies and the
+     `planModeQuestion` bridge becomes reachable at the same time.
+  3. It buys little for the common config. opencode's plan mode already denies its own tools,
+     and `Bash`/`Edit`/`Write` are proxied by default, so the only gap it closes is Claude's
+     unproxied built-ins.
+
+  Shape if built: an explicit option (something like `planModePermission: "follow-agent"`),
+  never silent coupling. Do not start this without a user asking for it.
+
+- 2026-09-09, maintainer: "pin to appical but if limits hit switch to default is that possible?"
+  Asked while designing the `dev-support` agent, which must run on the appical account for
+  its per-profile MCP servers (Linear, Aikido, Sentry) but should survive that account's
+  spend limit. Today it is not possible: the account is the provider, it is fixed for the
+  life of the `claude` process, and a `forceModel` agent inherits whoever invoked it. When
+  the limit error arrives ("You've hit your individual spend limit", resets at a stated
+  time) the turn simply fails and the human restarts on the other account.
+
+  Shape if built: an optional `fallbackAccounts: ["default"]` per agent or per provider.
+  On a recognised limit error the plugin respawns the session on the next account with
+  the same model, effort and cwd, and says so in the turn. Things to check first:
+  1. The failover account may lack the MCP servers the run depends on; the resumed turn
+     would need to re-announce its tool list, or the option should refuse to fail over when
+     the tool sets differ.
+  2. Session key includes the account, so a failover is a new process and loses in-process
+     state; opencode's own transcript is what carries over, which is probably enough.
+  3. Detection must match the CLI's limit message exactly, not any 4xx, or a transient
+     error would silently move billing to another account.
+
+## Dropped
+
+- Dropped 2026-09-06 at the user's request: live observation of `idleProcessTimeoutMs: 900000`. The 15-minute eviction and subsequent resume remain unverified in the user's window; no test is planned.
+
+## Backlog
+
+## Deferred decisions
+
+- 2026-09-20: The maintainer chose "later" for adding the Appical MCP project block
+  to `Appical.IaC`, `Cl-nica-Aurora---Player-team`, `Manager-toolkit`,
+  `NOW-player-web` and `workshop-sep-2026`.
+- 2026-09-20: The maintainer chose "later" for choosing a Slack authentication
+  strategy. The current global server can still pay a 30-second 1Password unlock
+  timeout on startup.
+- 2026-09-20: The maintainer chose "later" for completing opencode's separate,
+  global Linear OAuth authentication.
+
+## Open from you
+
+Questions the maintainer still owes an answer on. Written here the turn they are
+raised, so they survive context compaction; removed when answered, done or dropped.
+
+No pending questions.
+
+## Parked
+
+- 2026-09-23: the skill-bridge native-dedup work (expanded discovery roots,
+  `bridgeSkipNativeSkills`, and the README/SKILL.md/AGENTS.md copy that goes with it)
+  was parked mid-flight on branch `skill-bridge-native-dedup`, commit `50df301`, so
+  master could be clean for the V2 lane. It is 9 files and roughly 830 lines, it is
+  **not gated** (no typecheck, test or build run since the last edits), and AGENTS.md
+  already describes it as offline-verified only with no live Claude session behind it.
+  To resume: `git checkout skill-bridge-native-dedup`, run the full gate, then open a PR.
+  Nothing is lost by leaving it there, but note the maintainer's local `file://` install
+  builds from the working tree, so master builds no longer carry these changes.
+
+## In progress
+
+- 2026-09-23: opencode **V2 support**. The plan lives in `V2.md` and is the active lane.
+  Short version: V2 is a new major of opencode, not a second API inside 1.x, and V1
+  plugin implementations do not run in it at all, so this plugin disappears the day the
+  maintainer's opencode moves to 2.x. The blocking capability question is answered:
+  `@opencode/plugin@2.0.11` ships an undocumented `ctx.aisdk` domain whose `language`
+  hook takes a `LanguageModelV3`, which is exactly what `ClaudeCodeLanguageModel`
+  already is, against the same `@ai-sdk/provider` major we already depend on. Dual V1
+  and V2 support from one package is officially supported and our default export is
+  already the right shape. Next step is phase 0, the six probes listed in `V2.md`.
+
+## Done
+
+- 2026-09-20: two lanes, account failover (PR #41) and small cleanup (PR #42), both
+  merged and shipped in v0.24.0.
diff --git a/V2.md b/V2.md
@@ -0,0 +1,210 @@
+# opencode V2 support
+
+Working plan for supporting opencode 1.x (V1) and opencode 2.x (V2) from one package.
+Written 2026-09-23 against `@opencode/plugin@2.0.11` and `@opencode-ai/plugin@1.18.31`.
+Tracker: issue #31. This file supersedes the "not planned" verdict recorded in AGENTS.md.
+
+## What changed, and why the old verdict is void
+
+AGENTS.md parked V2 on the reasoning that the v2 API was an additive alternative
+surface inside opencode 1.x (`@opencode-ai/plugin/v2`), with no reload of the model
+implementation path and therefore no payoff. That reading is now wrong on the premise.
+
+**V2 is a new major of opencode itself, not a second plugin API inside 1.x.** From the
+migration guide: V1 and V2 both use the `opencode` command, are no longer installed side
+by side, and the V2 installer replaces the V1 binary. And, stated as a warning rather
+than a footnote:
+
+> V1 plugin implementations do not run in V2. Moving a file or renaming its config entry
+> is not enough.
+
+So this is not an optimisation. The day the maintainer's opencode moves to 2.x, this
+plugin stops existing for them, along with every account provider, proxy tool and
+model id it registers. That is the actual deadline.
+
+Shipped and confirmed on the registry: `@opencode/plugin@2.0.11`, `@opencode/client@2.0.11`,
+`@opencode/ai@2.0.11`. V1's latest is `@opencode-ai/plugin@1.18.31`, which is what we
+build against today.
+
+## The decisive question, and its answer
+
+This plugin does not *describe* a provider. It *implements* one: `ClaudeCodeLanguageModel`
+is a real `LanguageModelV3` that spawns and drives the `claude` CLI. Any migration lives
+or dies on whether V2 lets a plugin supply a model implementation.
+
+The published V2 plugin documentation says no. Its provider surface is metadata only:
+`ctx.provider.transform` adds `{ info, models }`, where `info.package` names a package
+opencode instantiates itself (`"aisdk:@ai-sdk/openai-compatible"`,
+`"@opencode/ai/providers/openai-compatible"`). Model transforms "apply restrictions and
+overrides". Nothing in the documented API returns a model object. Taken at face value
+that would have forced a rewrite into a local HTTP shim speaking the Anthropic Messages
+protocol, with the CLI behind it.
+
+**The shipped package says otherwise.** `@opencode/plugin@2.0.11` carries an `aisdk`
+domain that the website does not document, and it is exactly the escape hatch needed:
+
+```ts
+// package/dist/promise/aisdk.d.ts
+import type { LanguageModelV3 } from "@ai-sdk/provider"
+
+export interface AISDKHooks {
+  sdk: {
+    readonly model: Model.Info
+    readonly package: string
+    readonly options: Record<string, any>
+    sdk?: any
+  }
+  language: {
+    readonly model: Model.Info
+    readonly sdk: any
+    readonly options: Record<string, any>
+    language?: LanguageModelV3
+  }
+}
+export interface AISDKDomain {
+  readonly hook: ModelHooks<AISDKHooks>
+}
+```
+
+`ctx.aisdk` is on the plugin context (`dist/promise/context.d.ts`), and `ModelHooks`
+takes an optional `{ providerID }` scope, so the hook can be limited to our own
+providers rather than intercepting everyone's models.
+
+Two facts make this cheap rather than a rewrite:
+
+1. `@opencode/plugin@2.0.11` depends on `@ai-sdk/provider` at **3.0.8**. This package
+   already depends on `^3.0.8` and has 3.0.10 installed.
+2. `ClaudeCodeLanguageModel.specificationVersion` is already `"v3"`.
+
+So the expensive part of this plugin, the several thousand lines of CLI transport,
+session management, proxy MCP broker and stream translation, is already the exact type
+V2 asks for. The port is a new entrypoint and a new wiring layer, not a rewrite of the
+thing that took a year to get right.
+
+**Not yet verified, and it is the first thing to probe:** whether a provider registered
+with no resolvable `package` still reaches the `language` hook, or whether opencode
+tries to instantiate the SDK first and fails before we are asked. The `sdk` hook exists
+and lets us supply that object too, which suggests the seam is intentional, but a
+suggestion is not a measurement.
+
+## Dual support is officially supported, and our entrypoint is already half of it
+
+From the plugin migration guide, verbatim shape:
+
+```ts
+export default {
+  ...Plugin.define({
+    id: "example",
+    async setup(ctx) { /* v2 */ },
+  }),
+  async server() {
+    return { /* v1 hooks */ }
+  },
+}
+```
+
+V1 calls `server()`, V2 calls `setup()`. The two implementations stay separate; nothing
+is translated for us. V1 object entrypoints require opencode **>= 1.18.29**, which is
+below the 1.18.31 we already verify against, so adopting this costs no V1 users.
+
+We are already at that shape. `src/index.ts:653`:
+
+```ts
+export default {
+  id: "@khalilgharbaoui/opencode-claude-code-plugin",
+  server,
+}
+```
+
+Adding V2 is spreading `Plugin.define({...})` into that object. The seam exists; what
+has to be built is what goes behind it.
+
+## Hook mapping
+
+| V1 | V2 | Note |
+|---|---|---|
+| `provider` returning `models()` | `ctx.provider.transform` + `ctx.aisdk.hook("language")` | The load-bearing one. Metadata and implementation split across two calls. |
+| `chat.params` (agent tagging) | `ctx.session.hook("context")`, set `event.options` | V2 gives `sessionID` directly instead of the `x-session-affinity` header. |
+| `config` (registering `/btw`, `/claude-code-doctor`) | `ctx.command.transform` with a real `execute()` | Strictly better. V1 forces us to inject into the user's config object and guard against clobbering their own command of that name. |
+| `event` (`session.deleted`) | `ctx.event.subscribe()` with an `AbortController` | Cleanup moves into the function `setup` returns. |
+| MCP bridging (`--mcp-config` on disk) | `ctx.mcp.transform` | May retire a lot of `mcp-bridge.ts`, including the content-addressed scratch file. |
+| skill bridge | `ctx.skill.transform` / `ctx.skill.list()` | V2 can register a skill directly instead of staging a throwaway plugin dir. |
+| proxy tool discovery | `ctx.tool.list()` | V1's registry deliberately excludes MCP tools, which is why `proxyOpencodeMcpTools` had to read `doStream`'s `tools` argument. Re-measure on V2. |
+| `tool.execute.before/after` | `ctx.tool.hook("execute.before"/"after")` | Not used here today. |
+| `permission.ask` | `ctx.permission.hook("evaluate")` | Not used here today. |
+
+V2 also adds things V1 never had that this plugin has hand-rolled around: `ctx.storage`
+for durable plugin state, `ctx.session.hook("retry")` for provider failure policy (which
+is the natural home for account failover), and `ctx.session.hook("compaction")` with a
+`result` field that can skip the model call entirely.
+
+## Open questions, in the order they should be probed
+
+Each is cheap, each is a measurement rather than a reasoning step, and none needs
+product code.
+
+1. **Does an unresolvable `package` still reach `aisdk.hook("language")`?** Register a
+   provider with a nonsense package, hook both `sdk` and `language`, log what arrives.
+   If it does not, the answer is to supply the `sdk` object from the `sdk` hook too.
+   Everything else in this plan depends on this one.
+2. **How does the model learn which session it is serving?** V1 reads the
+   `x-session-affinity` request header, and session affinity is the key to process reuse,
+   proxy call routing and the todo ledger. Check what V2 passes into `doStream`; if it
+   passes nothing, `ctx.session.hook("context")` knows the `sessionID` and can stash it.
+3. **Is there a native `question` tool in V2?** Account failover and the plan-mode bridge
+   both end a turn on a synthetic `question` tool-call and resume from its tool result.
+   V2 registers tools through plugins, so confirm the tool exists and the round-trip
+   still works before porting either feature.
+4. **Do MCP tools appear in `ctx.tool.list()`?** If yes, `resolveMcpProxyToolDefs` gets
+   simpler and the `doStream` `tools` argument read can go.
+5. **Does the proxy still get permission prompts?** V2 renamed permission actions
+   (`bash` to `shell`, `task` to `subagent`, `write`/`patch` to `edit`) and replaced the
+   per-tool map with one ordered array. The proxy exists so Claude's tool calls run under
+   opencode's permissions; confirm that still holds.
+6. **How do we run V2 at all without losing V1?** The installer replaces the V1 binary
+   and both use the `opencode` command. Testing needs a pinned V2 binary in an isolated
+   path with its own `XDG_CONFIG_HOME`, the same discipline the live probes already use.
+
+## Phases
+
+**Phase 0, probes.** Answer the six questions above with throwaway plugins against a
+sandboxed V2. No changes to this package. Write findings back into this file. Stop here
+and re-plan if question 1 comes back negative, because that answer changes the
+architecture rather than the schedule.
+
+**Phase 1, separate the transport from the V1 glue.** Nothing under the CLI transport
+should know what an opencode plugin API looks like. Today `src/opencode-types.ts` is a
+hand-written mirror of V1's types and the V1 wiring lives in `src/index.ts`. Target:
+`index.ts` becomes a thin dual entrypoint, `v1.ts` holds today's `server()`, `v2.ts`
+holds `setup()`, and everything else is shared and API-agnostic. This phase ships on its
+own with zero behaviour change and the full suite green.
+
+**Phase 2, V2 entrypoint, feature by feature.** Order by dependency: provider and models
+first (nothing works without a model), then commands, then MCP, then skills, then the
+question-dependent features (failover, plan mode) once probe 3 has an answer. V1 stays
+the default and stays untouched.
+
+**Phase 3, parity and release.** A parity checklist per feature with its V2 evidence,
+the README and the bundled skill updated to say which opencode majors are supported,
+and a minor release. Support both until the maintainer's own opencode is on 2.x and has
+stayed there.
+
+## Rules for this lane
+
+- **V1 may not regress.** 660 tests green at every step, and no V1 behaviour changed
+  because V2 would prefer it differently.
+- **Every V2 claim gets a measurement**, the same standard the rest of AGENTS.md holds.
+  The website's provider documentation would have sent this lane down a rewrite; the
+  shipped `.d.ts` did not. Read the package.
+- **Do not convert the maintainer's own opencode config to native V2 shape yet.** V1 and
+  V2 read the same paths, and the migration guide warns against pointing V1 at converted
+  files.
+- **Do not install V2 over the working V1** until the port runs, because the installer
+  replaces the binary and there is no plugin on the other side yet.
+
+## Test strategy
+
+The suite drives V1 by calling `server(input)` with a fake plugin input. V2 needs the
+same treatment: a fake `Context` with the domains we touch, so `setup(ctx)` can be
+asserted offline exactly as the V1 hooks are. Shared code keeps its existing tests. The
+probes in phase 0 are live and paid, and stay out of `npm test`.