@khalilgharbaoui/opencode-claude-code-plugin 0.36.5 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalilgharbaoui/opencode-claude-code-plugin",
-  "version": "0.36.5",
+  "version": "0.37.1",
   "description": "Claude Code CLI provider plugin for opencode",
   "homepage": "https://opencode-claude-code-plugin.dev/",
   "funding": {
@@ -26,7 +26,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "OPENCODE_CLAUDE_CODE_LOG_FILE=0 tsx --test test-bridge.ts test-broker.ts test-proxy-mcp.ts test-proxy-task.ts test-auto-continue.ts test-has-new-user-content.ts test-get-claude-user-message.ts test-logger.ts test-cli-args.ts test-permission-presets.ts test-session-manager.ts test-compaction-model.ts test-tool-mapping.ts test-cwd-resolution.ts test-todo-ledger.ts test-session-affinity.ts test-config-models.ts test-ask-user-question.ts test-claude-session-wrapper.ts test-spawn-env.ts test-respawn.ts test-startup-diagnostics.ts test-subagent-hint.ts test-exit-plan-mode-question.ts test-compress-tool.ts test-agent-models.ts test-side-question.ts test-btw-command.ts test-effort-sessions.ts test-tool-block-index.ts test-context-usage.ts test-skill-bridge.ts test-turn-stats.ts test-cli-events.ts test-cli-events-stream.ts test-result-fallback.ts test-doctor.ts test-configure-skill.ts test-unattended-replay.ts test-process-lifecycle.ts test-account-failover.ts test-host-tools.ts test-v2-entrypoint.ts test-v2-client.ts test-tmp-dir.ts test-cleanup-stale.ts test-account-wrapper.ts test-runtime-status-sessions.ts test-index-hooks.ts test-silent-turn.ts test-mcp-tool-result-name.ts test-model-fallback.ts test-do-generate.ts test-interactive-usage.ts test-background-subagents.ts test-interactive-result.ts test-cli-probe-cache.ts test-mcp-late-connect.ts test-prologue-abort.ts test-diagnostic-bundle.ts test-ids.ts test-session-fork.ts test-deferred-cli-tool-result.ts",
+    "test": "OPENCODE_CLAUDE_CODE_LOG_FILE=0 tsx --test test-bridge.ts test-broker.ts test-proxy-mcp.ts test-proxy-task.ts test-auto-continue.ts test-has-new-user-content.ts test-get-claude-user-message.ts test-logger.ts test-cli-args.ts test-permission-presets.ts test-session-manager.ts test-compaction-model.ts test-tool-mapping.ts test-cwd-resolution.ts test-todo-ledger.ts test-session-affinity.ts test-config-models.ts test-ask-user-question.ts test-claude-session-wrapper.ts test-spawn-env.ts test-respawn.ts test-startup-diagnostics.ts test-subagent-hint.ts test-exit-plan-mode-question.ts test-compress-tool.ts test-agent-models.ts test-side-question.ts test-btw-command.ts test-effort-sessions.ts test-tool-block-index.ts test-context-usage.ts test-skill-bridge.ts test-turn-stats.ts test-cli-events.ts test-cli-events-stream.ts test-result-fallback.ts test-doctor.ts test-configure-skill.ts test-unattended-replay.ts test-process-lifecycle.ts test-account-failover.ts test-host-tools.ts test-v2-entrypoint.ts test-v2-client.ts test-tmp-dir.ts test-cleanup-stale.ts test-account-wrapper.ts test-runtime-status-sessions.ts test-index-hooks.ts test-silent-turn.ts test-mcp-tool-result-name.ts test-model-fallback.ts test-do-generate.ts test-interactive-usage.ts test-background-subagents.ts test-interactive-result.ts test-cli-probe-cache.ts test-mcp-late-connect.ts test-prologue-abort.ts test-diagnostic-bundle.ts test-ids.ts test-session-fork.ts test-deferred-cli-tool-result.ts test-stale-build.ts test-tui-log-sink.ts",
     "generate:log-messages": "tsx scripts/generate-log-messages.ts"
   },
   "dependencies": {

package/skills/claude-code-plugin/SKILL.md

@@ -151,7 +151,7 @@ Defaults below describe normal headless opencode use when the key is absent.
 | `interactiveBypass` | boolean | `false` | Deprecated no-op. The TUI asks for a manual safety confirmation on `bypassPermissions`, so the plugin never passes it. |
 | `interactiveAllowTools` | string[] | `["Bash", "Edit", "Write", "Read", "WebFetch"]` | With `interactive`: replaces the built-in pre-allow list. MCP wildcards from discovered bridge names plus `mcp__opencode_proxy__*` are added even with `[]`. Not a capability denylist; review permissions before enabling. |
 | `interactiveSystemPrompt` | boolean | `true` | With `interactive`: append the plugin's own prompt. opencode's forwarded system prompt is deliberately not sent on this transport (it can trip Claude's third-party usage gate). `false` is for diagnostics only. |
-| `logging` | object | see below | File and TUI logging policy. |
+| `logging` | object | see below | File logging plus how much reaches the operator. |
 | `name` | string | unset | Low-level `createClaudeCode()` provider identity fallback after `providerID`, not the opencode display-name setting. Display name lives at `provider.<id>.name`; account expansion supplies its own label. Leave this option unset. |
 | `providerID` | string | derived | Config hook writes the actual provider id (`claude-code` or `claude-code-work`). Do not override manually. |
 | `hostApi` | `"v1"` \| `"v2"` | derived | Which opencode major created the model, which decides the tool names its stream uses (`bash` on 1.x, `shell` on 2.x). Set only by the opencode 2 entrypoint. Do not set it: forcing `"v2"` under opencode 1.x makes every proxied tool call fail as an unavailable tool. |
@@ -164,9 +164,25 @@ Defaults below describe normal headless opencode use when the key is absent.
 |---|---|---|---|
 | `file` | boolean | `false` | Persist entries that pass `level`. Logs can contain prompts/tool data/CLI arguments; enable temporarily with consent, not as a credential dump. |
 | `dir` | path | `~/.local/share/opencode-claude-code/` | Where `plugin.log` goes. |
-| `mode` | `"silent"` / `"debug"` | `"silent"` | After level filtering: silent routes lower levels only to the file if enabled; WARN/ERROR go to stderr/TUI too. Debug echoes all emitted levels to stderr, but does not lower the threshold. |
+| `mode` | `"silent"` / `"debug"` | `"silent"` | After level filtering: silent routes lower levels only to the file if enabled; WARN/ERROR are surfaced to the operator too. Debug surfaces all emitted levels, but does not lower the threshold. |
 | `level` | `debug` / `info` / `notice` / `warn` / `error` | `"info"` | Minimum level emitted anywhere. |
 
+Where a surfaced line goes depends on whether a full-screen TUI owns the terminal, and
+the plugin detects that itself (`isTuiHost`, true when the plugin is running off the main
+thread, which is how opencode 1.x's TUI runs a plugin). Outside a TUI (`opencode run`,
+`opencode serve`, tests, and opencode 2, which runs plugins in a separate `serve --stdio`
+process) it is stderr, prefixed `[opencode-claude-code] WARN:`, unchanged. Inside the TUI
+**nothing is written to stderr at any level**, because stderr there is the terminal the
+TUI is drawing on and a raw line sits on top of the interface until a redraw. Instead the
+line goes to opencode's own log (`client.app.log`, service `opencode-claude-code`, so it
+lands in `~/.local/share/opencode/log/`), and WARN/ERROR also raise a toast titled
+`claude-code`. The toast carries the message only, never the JSON data; the same message
+text toasts at most once per process, and a burst raises at most three toasts plus one
+line naming how many were held back. Nothing is held back from either log. So when a user
+reports "the plugin printed garbage over my opencode UI", the answer is to upgrade, not to
+turn logging off; and when they ask where a WARN went in the TUI, point them at opencode's
+own log or the toast rather than at stderr.
+
 ## Environment variables
 
 Set variables in the environment that launches opencode, then fully restart it.
@@ -808,6 +824,17 @@ else is flagged unsafe), and the last stderr of any child that produced some. Pr
 prompt. A user-defined `claude-code-doctor` command is never overwritten. The name has
 no space in it: opencode would read the second word as an argument.
 
+The `plugin build` row, directly under `plugin`, is the one field that says whether the
+version above it is the code actually answering. It compares the build this opencode
+process loaded at startup with the one on disk right now and reads `current`,
+`on disk <version>. Restart opencode to run it`, `the same version was rebuilt on disk
+at <time>. Restart opencode to run it`, or `the build on disk could not be read`. The
+last is not a fault: a package cache mid-reinstall or a build mid-`clean` is unreadable
+and says nothing about staleness. It names no path. The same comparison writes a
+one-per-conversation `▌ **restart opencode:**` note into the reply and one WARN per
+process, because a process can be months out of date with nothing else saying so. Check
+this row before investigating any bug the user says was already fixed.
+
 It also prints an **MCP config entries Claude Code skipped** section, but only when the
 CLI refused an entry in an `--mcp-config` it was given. Read it whenever MCP tools are
 missing: a skipped server is absent from the CLI's server list rather than listed
@@ -825,7 +852,8 @@ user's own Claude Code hooks (`hook_response` with `outcome: "error"` or a non-z
 `exit_code`), not opencode's. A failing `SessionStart` hook is otherwise invisible: the
 CLI drops its contribution and the turn succeeds, so the context it was meant to add is
 missing from every turn on that process. Read it whenever a hook's effect is absent. The
-first failure is also a WARN in the terminal. Only the hook's `stderr` is shown, capped
+first failure is also a plugin WARN, which in the TUI means a toast plus a line in
+opencode's own log rather than terminal text. Only the hook's `stderr` is shown, capped
 at 200 characters, because its stdout is spliced into the model's context. The plugin
 never passes `--include-hook-events`, so only `SessionStart` (and `Setup`) hooks are
 reported at all; `cancelled` is not a failure, since an abort produces it.
@@ -910,6 +938,8 @@ Prefer the doctor: it needs no logging change and no restart.
 | Symptom | Cause | Fix |
 |---|---|---|
 | A config change did nothing | Options are read at startup; another opencode window is still running the old process | Fully quit every opencode window and relaunch |
+| A `▌ **restart opencode:**` note at the top of a reply | Correct and acted on by the user, not by you: this opencode process loaded an older plugin build than the one now on disk, so a fix they installed is not running here. opencode reads a plugin once, at process start | Quit every opencode window (serve and GUI processes included) and relaunch. The note appears once per conversation, names the loaded version, the on-disk version and when the build was loaded, and is stripped from any transcript rebuilt for the CLI |
+| A bug the user is sure was fixed is back | Same cause as the row above, before they have seen the note: the window answering them predates the fix | The `plugin build` row of `/claude-code-doctor`, which reads the disk unthrottled: `current`, `on disk <version>`, `rebuilt on disk` or `could not be read`. Compare its loaded version with the version they installed before investigating the bug at all |
 | New plugin version or model not in the picker after upgrading | Frozen `@latest` in opencode's package cache | Remove the cache dir (recipe "Upgrade the plugin") and relaunch |
 | No `claude-code` provider or model in the picker at all | The plugin never loaded, or it loaded and the CLI was not usable | Check for a `plugin ready` line first: absent means not loaded (wrong `plugin`/`plugins` key, a 2.x local install not pointing at `dist/`, or no full relaunch), present with `claudeCli.version: not detected` means the binary did not answer `--version`, which also disables every version-gated flag |
 | `Model unavailable` for a model id the user typed | The provider id is not what they assumed | Use the id the ready block's `providers` field lists. With no `accounts` configured on opencode 2 the id is `claude-code`, so `claude-code-default/<model>` fails while the plugin is healthy (measured on opencode 2.0.16, 2026-09-27). Declaring `accounts` is what creates `claude-code-default`; on 1.x with accounts the ids are `claude-code-default` / `claude-code-<name>` and never a bare `claude-code` |