@khalilgharbaoui/opencode-claude-code-plugin 0.21.0 → 0.22.0

package/README.md

@@ -297,7 +297,7 @@ model: claude-code-work/claude-opus-5@work
 | `mcpConfig` | string \| string[] | – | Extra `--mcp-config` paths/JSON passed alongside the bridged config. |
 | `strictMcpConfig` | boolean | `false` | Pass `--strict-mcp-config` so Claude loads **only** the configured servers and ignores `~/.claude/settings.json`. |
 | `hotReloadMcp` | boolean | `true` | With MCP bridging on, compare the merged MCP config and runtime status at the start of each turn and respawn the `claude` process when they drifted, so a server you just enabled or disabled becomes visible without restarting opencode or opening a new chat. Eviction waits for pending proxy calls, never happening mid tool-call, and the session id is preserved for `--resume`. Set `false` to keep a cached subprocess until the chat is reset. It does not reload other provider options and does not watch the contents of files named in `mcpConfig`. |
-| `proxyOpencodeMcpTools` | boolean | `true` | **Currently has no effect on opencode 1.18.31: its discovery step finds nothing to route.** Measured on 2026-09-19 with five MCP servers connected, opencode's tool registry returned only built-in and plugin-declared tools, so the server-name match this option depends on matches nothing. Your MCP servers still work, through the direct `--mcp-config` bridge; what is lost is only the routing of those calls through opencode's permissions and rendering. Left on by default because it is harmless and will resume working if the registry regains them. To forward a specific non-MCP opencode tool meanwhile, use [`proxyOpencodeTools`](#options-reference). Original intent: route the MCP tools discovered from opencode through the in-process `opencode_proxy` server instead of bridging them straight into Claude's `--mcp-config`. With both layers pointed at the same server, direct bridging executes every call twice, once in Claude's own MCP child process and once in opencode; proxying keeps opencode as the single execution site while preserving its permission prompts and tool rows. Falls back to direct bridging when discovery is unavailable, so do not treat it as an exactly-once guarantee for write-capable tools. |
+| `proxyOpencodeMcpTools` | boolean | `false` | Route opencode's MCP-backed tools through the in-process `opencode_proxy` server instead of bridging them straight into Claude's `--mcp-config`, so each call executes once, inside opencode, with its permission prompt and its tool row. **The default changed from `true` to `false` in this release, and no behaviour changed with it:** at `true` it used to route nothing at all, because discovery read opencode's tool registry, which contains built-ins and plugin-declared tools and has never contained an MCP tool. Discovery now reads the model tool set opencode passes the provider, which is where MCP tools actually are, so the option works, and turning it on is the operator's decision rather than a silent migration of traffic that the direct bridge is handling today. Two caveats before enabling it: pair it with `strictMcpConfig: true`, because a server also registered in Claude Code's own config is reached directly and bypasses the proxy entirely; and a routed call runs in opencode with the calling agent's permissions, the same trade [`proxyOpencodeTools`](#options-reference) makes. Servers whose tools are not found stay on the direct bridge, and a warning says so, so do not treat this as an exactly-once guarantee for write-capable tools. |
 | `proxyOpencodeTools` | string[] | `[]` | Forward named opencode tools through the proxy by their registry id, for tools another opencode plugin declares directly and that therefore belong to no MCP server (opencode-dcp's `compress`). Explicit allowlist; a forwarded tool runs inside opencode with the calling agent's permissions. A name already held by a proxy def is dropped with a warning rather than taking it over. See [Forwarding opencode's own tools](#forwarding-opencode-s-own-tools). |
 | `stripContextReminders` | boolean | `false` | Remove opencode-dcp's `<dcp-system-reminder>` blocks from message text when no `compress` tool is proxied, so an order the model cannot follow stops being re-sent with every message that carries it. Inert as soon as `compress` is reachable. See [Trimming unsatisfiable context reminders](#trimming-unsatisfiable-context-reminders). |
 | `webSearch` | `"claude"` \| `"disabled"` \| `<tool>` | `"claude"` | Routing for Claude's built-in `WebSearch`. See [WebSearch routing](#websearch-routing). |
@@ -504,7 +504,7 @@ Without `"Task"` in `proxyTools`, Claude's built-in `Agent` tool stays enabled a
 
 ### Forwarding opencode's own tools
 
-`proxyTools` names the tools this plugin ships defs for, and MCP-backed opencode tools are routed automatically ([`proxyOpencodeMcpTools`](#options-reference)). Neither covers a tool that **another opencode plugin declares directly**: it belongs to no MCP server, so the automatic match (`<server>` or `<server>_<tool>`) skips it and the model is never offered it. opencode-dcp's `compress` is the case that matters in practice, because DCP then injects "MAX CONTEXT LIMIT REACHED ... You MUST use the `compress` tool now" reminders that the model has no way to act on.
+`proxyTools` names the tools this plugin ships defs for, and MCP-backed opencode tools can be routed with [`proxyOpencodeMcpTools`](#options-reference). Neither covers a tool that **another opencode plugin declares directly**: it belongs to no MCP server, so the automatic match (`<server>` or `<server>_<tool>`) skips it and the model is never offered it. opencode-dcp's `compress` is the case that matters in practice, because DCP then injects "MAX CONTEXT LIMIT REACHED ... You MUST use the `compress` tool now" reminders that the model has no way to act on.
 
 `proxyOpencodeTools` is the explicit allowlist. Empty by default:
 
@@ -609,7 +609,7 @@ A proxied call ends when something happens to it, not when a clock runs out. The
 
 Because every ending is observed rather than inferred from elapsed time, a `task` can run until it is finished: **`task` and `task_batch` have no deadline by default**. Earlier flat ceilings fired mid-subagent, Claude believed its dispatch had failed, and the eventual result was dropped because the parent turn had already ended on the timeout error; a 60-minute one did the same to anything longer. What the default gives up is only that nothing fires on the clock alone, so a chat parked in a `task` holds its `claude` worker until one of the events above happens. That is the operator's decision to make, so no timer makes it for them.
 
-So that a call with no deadline is never silent, the plugin says it is still waiting. Five minutes in, and every five minutes after, a call without a deadline logs a warning naming the tool, the call id, how long it has waited, and what will end it. It never ends the call, it only reports one, which is the whole point: the thing a deadline used to provide was visibility, not correctness, and visibility is what is kept. Calls that do have a deadline are not reported this way, because their deadline already does it. The line reaches your terminal (warnings always go to stderr), so a subagent that has genuinely wedged shows up on its own instead of waiting to be noticed. `/claude-code-doctor` lists the same calls on demand.
+So that a call with no deadline is never silent, the plugin says it is still waiting. Five minutes in, and every five minutes after, a call without a deadline logs a warning naming the tool, the call id, how long it has waited, and what will end it. It never ends the call, it only reports one, which is the whole point: the thing a deadline used to provide was visibility, not correctness, and visibility is what is kept. Calls that do have a deadline get one notice rather than a heartbeat, at 60% of the way to it, saying how long is left and which option would extend it. Before this, a deadline reported a call only by killing it: the first thing you heard was the failure, which is no use while there is still time to react. It is one line, never repeated, because the deadline itself is the next thing that will speak, and deadlines under a minute are skipped entirely since the notice and the rejection would arrive together. The line reaches your terminal (warnings always go to stderr), so a subagent that has genuinely wedged shows up on its own instead of waiting to be noticed. `/claude-code-doctor` lists the same calls on demand.
 
 The same events are also what let a legitimately long call complete, which is the second half of the story: the CLI's own HTTP client used to give up on a silent reply at about five minutes whatever the tool deadline said. Every held call therefore keeps its connection visibly alive. A client that advertises SSE gets immediate headers and a keepalive comment every 15 seconds (since 0.15.0); a client that only accepts JSON gets its headers immediately as well, as a chunked body carrying keepalive whitespace on the same cadence, which is still one valid JSON-RPC response when the result lands, on success and on error. Keepalives are about the connection, not the tool: they never extend or replace a deadline. Claude's MCP client timeout for the proxy server, written into the generated `--mcp-config`, is set to the largest effective deadline, and to the largest value the CLI accepts (Node's timer maximum, about 24.8 days) while any tool has no deadline, because the CLI rejects a `timeout` of `0` outright.
 

package/dist/index.d.ts

@@ -487,16 +487,28 @@ interface ClaudeCodeProviderSettings {
     /**
      * Route opencode MCP server tools through the in-process `opencode_proxy`
      * MCP server instead of bridging them directly into Claude CLI's
-     * `--mcp-config`. With both layers configured for the same MCP server,
-     * direct bridging causes each tool invocation to execute twice — once by
-     * Claude CLI's own MCP child process and once by opencode. Routing through
-     * the proxy keeps a single execution site (opencode) while preserving the
-     * tool-call/result surface in opencode's UI and its permission prompts.
+     * `--mcp-config`. Routing through the proxy keeps a single execution site
+     * (opencode), so the call is permission-prompted and rendered as an
+     * opencode tool call instead of running inside Claude CLI's own MCP child.
      *
-     * Defaults to `true`. Set to `false` to restore the prior direct-bridge
-     * behavior (Claude CLI executes MCP tools itself; opencode also re-executes
-     * — accept the duplication if you need Claude to invoke the tool without
-     * an opencode round-trip).
+     * Defaults to `false`, and that is a change of default rather than of
+     * behaviour. It used to default to `true` while routing nothing at all:
+     * discovery read `client.tool.list()`, which enumerates opencode's tool
+     * registry (built-ins plus plugin-declared tools) and has never contained
+     * an MCP tool, so no def was ever built. Discovery now reads the model tool
+     * set opencode passes the provider, which is where MCP tools actually live,
+     * so the option works. Leaving it on by default would then have silently
+     * moved every existing user's MCP traffic off the direct bridge that is
+     * carrying it today, so switching over is the operator's call.
+     *
+     * Two things to know before enabling it:
+     *
+     * - It only affects the servers this plugin bridges. If the same server is
+     *   also registered in Claude Code's own config, Claude reaches it directly
+     *   and the proxy is bypassed. Pair this with `strictMcpConfig: true` so
+     *   Claude sees only the config this plugin writes.
+     * - A routed call executes inside opencode with the calling agent's
+     *   permissions, the same trade `proxyOpencodeTools` makes.
      */
     proxyOpencodeMcpTools?: boolean;
     /**
@@ -693,13 +705,24 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     /** Resolve ProxyToolDef[] for the configured proxyTools names. */
     private resolvedProxyTools;
     /**
-     * Resolve ProxyToolDef[] for opencode's MCP-bridged tools so they go
+     * Resolve ProxyToolDef[] for opencode's MCP-backed tools so they go
      * through the in-process proxy instead of being bridged into Claude CLI's
-     * `--mcp-config`. Direct bridging causes double execution because both
-     * Claude CLI's own MCP child and opencode hold their own connection to
-     * the same server; routing through the proxy keeps a single execution
-     * site (opencode). Returns null when the feature is disabled, the SDK
-     * client is unavailable, or no MCP servers are configured.
+     * `--mcp-config`. Routing through the proxy keeps a single execution site
+     * (opencode), so the call is permission-prompted and rendered as an
+     * opencode tool call.
+     *
+     * Opt-in (`proxyOpencodeMcpTools: true`) and off by default. It used to
+     * default to true while finding nothing, because it discovered tools via
+     * `client.tool.list()`, which enumerates opencode's `ToolRegistry` and not
+     * the MCP tools merged into the model's tool set afterwards. Discovery now
+     * reads that merged set, the `tools` array opencode passes `doStream`, so
+     * the option does what it says. Turning it on by default at the same time
+     * would have silently moved every existing user's MCP traffic off the
+     * working direct bridge, so the default went to false instead: today's
+     * behaviour is preserved exactly and crossing over is the operator's call.
+     *
+     * Returns null when the feature is off or nothing matched, which leaves
+     * every server on the direct bridge.
      */
     private resolvedProxyMcpTools;
     /**

package/dist/index.js

@@ -1303,6 +1303,47 @@ function resolveProxyOpencodeToolDefs(options) {
   }
   return out;
 }
+function resolveMcpProxyToolDefs(options) {
+  const empty = { defs: [], coveredServers: /* @__PURE__ */ new Set() };
+  const serverNames = options.serverNames ?? [];
+  if (serverNames.length === 0) return empty;
+  const tools = options.tools;
+  if (!tools || tools.length === 0) return empty;
+  const serversByLengthDesc = [...serverNames].sort((a, b) => b.length - a.length);
+  const taken = options.taken ?? /* @__PURE__ */ new Set();
+  const defs = [];
+  const coveredServers = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  const collided = [];
+  for (const tool of tools) {
+    if (tool?.type !== void 0 && tool.type !== "function") continue;
+    const name = typeof tool?.name === "string" ? tool.name.trim() : "";
+    if (!name) continue;
+    const matchedServer = serversByLengthDesc.find(
+      (server2) => name === server2 || name.startsWith(`${server2}_`)
+    );
+    if (!matchedServer) continue;
+    if (seen.has(name)) continue;
+    if (taken.has(name)) {
+      collided.push(name);
+      continue;
+    }
+    seen.add(name);
+    coveredServers.add(matchedServer);
+    defs.push({
+      name,
+      description: typeof tool.description === "string" ? tool.description : "",
+      inputSchema: tool.inputSchema && typeof tool.inputSchema === "object" ? tool.inputSchema : { type: "object", properties: {} }
+    });
+  }
+  if (collided.length > 0) {
+    log.warn(
+      "MCP tool not routed through the proxy: another proxy tool already holds that name, and it keeps it",
+      { collided }
+    );
+  }
+  return { defs, coveredServers };
+}
 function readBody(req) {
   return new Promise((resolve5, reject) => {
     const chunks = [];
@@ -1392,9 +1433,12 @@ function writeJson(res, body) {
 // src/proxy-broker.ts
 import { EventEmitter as EventEmitter2 } from "events";
 var PROXY_STALL_WARNING_MS = 5 * 6e4;
+var PROXY_DEADLINE_WARNING_FRACTION = 0.6;
+var PROXY_DEADLINE_WARNING_MIN_MS = 6e4;
 function clearPendingTimers(pending) {
   if (pending.timer) clearTimeout(pending.timer);
   if (pending.stallTimer) clearInterval(pending.stallTimer);
+  if (pending.deadlineWarnTimer) clearTimeout(pending.deadlineWarnTimer);
 }
 var pendingByCallId = /* @__PURE__ */ new Map();
 var callIdsBySession = /* @__PURE__ */ new Map();
@@ -1421,7 +1465,7 @@ function onPendingProxyCall(sessionKey2, handler) {
   emitter.on(name, handler);
   return () => emitter.off(name, handler);
 }
-function queuePendingProxyCall(sessionKey2, call, timeoutOverrides, stallWarningMs = PROXY_STALL_WARNING_MS) {
+function queuePendingProxyCall(sessionKey2, call, timeoutOverrides, stallWarningMs = PROXY_STALL_WARNING_MS, deadlineWarningMinMs = PROXY_DEADLINE_WARNING_MIN_MS) {
   const previous = pendingByCallId.get(call.id);
   if (previous) {
     clearPendingTimers(previous);
@@ -1464,6 +1508,24 @@ function queuePendingProxyCall(sessionKey2, call, timeoutOverrides, stallWarning
     });
   }, stallWarningMs) : null;
   stallTimer?.unref?.();
+  const warnAtMs = Math.floor(deadlineMs * PROXY_DEADLINE_WARNING_FRACTION);
+  const deadlineWarnTimer = deadlineMs >= deadlineWarningMinMs && deadlineMs > 0 && warnAtMs > 0 ? setTimeout(() => {
+    const current = pendingByCallId.get(call.id);
+    if (!current) return;
+    const waitedMs = Date.now() - current.createdAt;
+    log.warn("proxy call still waiting, deadline approaching", {
+      sessionKey: current.sessionKey,
+      toolCallId: current.toolCallId,
+      toolName: current.toolName,
+      waitedMs,
+      deadlineMs,
+      remainingMs: Math.max(0, deadlineMs - waitedMs),
+      emitted: current.emitted === true,
+      channelClosed: current.channel?.closed === true,
+      note: "it will be rejected when the deadline passes; raise this tool's proxyToolTimeoutMs if the work is legitimately this long"
+    });
+  }, warnAtMs) : null;
+  deadlineWarnTimer?.unref?.();
   const pending = {
     sessionKey: sessionKey2,
     toolCallId: call.id,
@@ -1474,6 +1536,7 @@ function queuePendingProxyCall(sessionKey2, call, timeoutOverrides, stallWarning
     deadlineMs,
     timer,
     stallTimer,
+    deadlineWarnTimer,
     resolve: call.resolve,
     reject: call.reject
   };
@@ -5920,43 +5983,46 @@ var ClaudeCodeLanguageModel = class {
     return picked.length > 0 ? picked : null;
   }
   /**
-   * Resolve ProxyToolDef[] for opencode's MCP-bridged tools so they go
+   * Resolve ProxyToolDef[] for opencode's MCP-backed tools so they go
    * through the in-process proxy instead of being bridged into Claude CLI's
-   * `--mcp-config`. Direct bridging causes double execution because both
-   * Claude CLI's own MCP child and opencode hold their own connection to
-   * the same server; routing through the proxy keeps a single execution
-   * site (opencode). Returns null when the feature is disabled, the SDK
-   * client is unavailable, or no MCP servers are configured.
+   * `--mcp-config`. Routing through the proxy keeps a single execution site
+   * (opencode), so the call is permission-prompted and rendered as an
+   * opencode tool call.
+   *
+   * Opt-in (`proxyOpencodeMcpTools: true`) and off by default. It used to
+   * default to true while finding nothing, because it discovered tools via
+   * `client.tool.list()`, which enumerates opencode's `ToolRegistry` and not
+   * the MCP tools merged into the model's tool set afterwards. Discovery now
+   * reads that merged set, the `tools` array opencode passes `doStream`, so
+   * the option does what it says. Turning it on by default at the same time
+   * would have silently moved every existing user's MCP traffic off the
+   * working direct bridge, so the default went to false instead: today's
+   * behaviour is preserved exactly and crossing over is the operator's call.
+   *
+   * Returns null when the feature is off or nothing matched, which leaves
+   * every server on the direct bridge.
    */
-  async resolvedProxyMcpTools(allEnabledServerNames) {
-    if (this.config.proxyOpencodeMcpTools === false) return null;
+  resolvedProxyMcpTools(allEnabledServerNames, modelTools, taken) {
+    if (this.config.proxyOpencodeMcpTools !== true) return null;
     if (this.config.bridgeOpencodeMcp === false) return null;
     if (allEnabledServerNames.length === 0) return null;
-    const items = await fetchOpencodeToolList(
-      this.config.provider,
-      this.modelId,
-      this.config.cwd
-    );
-    if (!items || items.length === 0) return null;
-    const serversByLengthDesc = [...allEnabledServerNames].sort(
-      (a, b) => b.length - a.length
-    );
-    const out = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const item of items) {
-      const matchedServer = serversByLengthDesc.find(
-        (name) => item.id === name || item.id.startsWith(`${name}_`)
+    const resolution = resolveMcpProxyToolDefs({
+      serverNames: allEnabledServerNames,
+      tools: modelTools,
+      taken
+    });
+    if (resolution.defs.length === 0) {
+      log.warn(
+        "proxyOpencodeMcpTools is on but no MCP tool was found in opencode's tool set; those servers stay on the direct bridge this spawn",
+        { servers: allEnabledServerNames, modelTools: modelTools?.length ?? 0 }
       );
-      if (!matchedServer) continue;
-      if (seen.has(item.id)) continue;
-      seen.add(item.id);
-      out.push({
-        name: item.id,
-        description: item.description ?? "",
-        inputSchema: item.parameters && typeof item.parameters === "object" ? item.parameters : { type: "object", properties: {} }
-      });
+      return null;
     }
-    return out.length > 0 ? out : null;
+    log.debug("routing opencode MCP tools through the proxy", {
+      servers: [...resolution.coveredServers],
+      tools: resolution.defs.map((def) => def.name)
+    });
+    return resolution;
   }
   /**
    * Live tool info derived from a single `client.tool.list()` fetch:
@@ -6419,7 +6485,7 @@ var ClaudeCodeLanguageModel = class {
     );
     const sk = effortSessionKey(baseKey, reasoningEffort);
     const compactionMode = this.isCompactionCall(options);
-    if (scope === "tools" && (this.resolvedProxyTools() || this.config.proxyOpencodeMcpTools !== false && this.config.bridgeOpencodeMcp !== false)) {
+    if (scope === "tools" && (this.resolvedProxyTools() || this.config.proxyOpencodeMcpTools === true && this.config.bridgeOpencodeMcp !== false)) {
       return this.doGenerateViaStream(options);
     }
     if (compactionMode) {
@@ -7165,10 +7231,13 @@ ${plan}
                 void 0,
                 runtimeStatus
               );
-              const proxyMcpTools = await self.resolvedProxyMcpTools(
-                discovery.allEnabledServerNames
+              const mcpResolution = self.resolvedProxyMcpTools(
+                discovery.allEnabledServerNames,
+                options.tools,
+                new Set((resolvedProxy ?? []).map((def) => def.name))
               );
-              const excludeServers = proxyMcpTools ? new Set(discovery.allEnabledServerNames) : void 0;
+              const proxyMcpTools = mcpResolution?.defs ?? null;
+              const excludeServers = mcpResolution ? mcpResolution.coveredServers : void 0;
               const taskProxyEnabled = resolvedProxy?.some((t) => t.name === "task") ?? false;
               const questionProxyEnabled = resolvedProxy?.some((t) => t.name === "question") ?? false;
               const opencodeToolsRequested = (self.config.proxyOpencodeTools?.length ?? 0) > 0;
@@ -9095,7 +9164,7 @@ function createClaudeCode(settings = {}) {
       planModeQuestion: settings.planModeQuestion ?? false,
       webSearch: settings.webSearch,
       hotReloadMcp: settings.hotReloadMcp ?? true,
-      proxyOpencodeMcpTools: settings.proxyOpencodeMcpTools ?? true,
+      proxyOpencodeMcpTools: settings.proxyOpencodeMcpTools === true,
       multiStepContinuation: settings.multiStepContinuation ?? true,
       autoContinueIncompleteTurns: settings.autoContinueIncompleteTurns ?? "smart",
       compactionModel: settings.compactionModel,