@khalilgharbaoui/opencode-claude-code-plugin 0.1.6 → 0.2.0

package/README.md

@@ -170,6 +170,7 @@ The account model IDs are internally suffixed, for example `claude-sonnet-4-6@wo
 | `bridgeOpencodeMcp` | boolean | `true` | Auto-translate your opencode `mcp` block into Claude's `--mcp-config`. See [MCP bridge](#mcp-bridge). |
 | `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`. |
+| `webSearch` | `"claude"` \| `"disabled"` \| `<tool>` | `"claude"` | Routing for Claude's built-in `WebSearch`. See [WebSearch routing](#websearch-routing). |
 
 ### Overriding model metadata
 
@@ -227,6 +228,27 @@ To turn off proxying entirely:
 ### What you give up
 
 - A small per-call latency hop through `127.0.0.1:<random>/mcp`.
+
+---
+
+## WebSearch routing
+
+Claude Code ships a built-in `WebSearch` tool. The `webSearch` option controls who actually executes those calls:
+
+| `webSearch` value | Behavior | When to use |
+|---|---|---|
+| `"claude"` (default) | Claude CLI runs WebSearch internally via Anthropic. Zero setup, no extra cost, no API key. | Most users. |
+| `"<opencode-tool-name>"` (e.g. `"websearch_web_search_exa"`) | Forward to that opencode-side tool with `executed:false`. Requires the corresponding MCP server to be configured in opencode (e.g. [exa-mcp-server](https://github.com/exa-labs/exa-mcp-server)). | You want a specific search backend (Exa, Tavily, Brave) and have the MCP wired up in opencode. |
+| `"disabled"` | `WebSearch` is added to `--disallowedTools` so the model can't call it. | Compliance/security scenarios where outbound search isn't allowed. |
+
+```json
+"options": { "webSearch": "websearch_web_search_exa" }
+```
+
+**Trade-offs**
+
+- Claude-side execution: free with your Claude usage, no API key, but no opencode visibility into queries/results, no caching/rate-limit hooks.
+- opencode-side execution: choose any backend, queries flow through opencode's audit/policy/cache, but costs money (search APIs are paid) and adds a network hop.
 - Some Claude-specific tool features stay on the built-in side (notably `MultiEdit` — see the note above).
 
 ---

package/dist/index.d.ts

@@ -70,12 +70,35 @@ type OpenCodeConfig = {
         models?: Record<string, unknown>;
     }>;
 };
+/**
+ * Bus events surface to plugins. Shape mirrors what opencode core publishes
+ * via `GlobalBus.emit("event", { directory, payload: { type, properties } })`
+ * but kept loose since opencode adds events over time and this plugin only
+ * reacts to a small subset (currently just `global.disposed`).
+ */
+type OpenCodeEvent = {
+    type?: string;
+    payload?: {
+        type?: string;
+        properties?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+};
 type OpenCodeHooks = {
     config?: (input: OpenCodeConfig) => Promise<void>;
     provider?: {
         id: string;
         models?: (provider: OpenCodeProvider) => Promise<Record<string, OpenCodeModel>>;
     };
+    /**
+     * Called for every bus event opencode publishes. We use this to react to
+     * `global.disposed` (fired when opencode invalidates its config — e.g.
+     * after a UI MCP toggle or `updateGlobal`) and evict cached claude
+     * subprocesses so the next turn picks up the fresh config.
+     */
+    event?: (input: {
+        event: OpenCodeEvent;
+    }) => Promise<void>;
 };
 type OpenCodePlugin = (input: unknown, options?: Record<string, unknown>) => Promise<OpenCodeHooks>;
 
@@ -95,7 +118,10 @@ interface ClaudeCodeConfig {
     controlRequestToolBehaviors?: Record<string, ControlRequestBehavior>;
     controlRequestDenyMessage?: string;
     proxyTools?: string[];
+    webSearch?: WebSearchRouting;
+    hotReloadMcp?: boolean;
 }
+type WebSearchRouting = "claude" | "disabled" | (string & {});
 interface ClaudeCodeProviderSettings {
     cliPath?: string;
     cwd?: string;
@@ -147,6 +173,30 @@ interface ClaudeCodeProviderSettings {
      * Supported: `bash`, `write`, `edit`, `webfetch`. Leave empty or unset to disable proxying.
      */
     proxyTools?: string[];
+    /**
+     * Routing for Claude's built-in `WebSearch` tool.
+     *
+     * - `"claude"` (default): Claude CLI runs WebSearch internally via
+     *   Anthropic's web search. No MCP setup required, no extra cost.
+     * - `"<opencode-tool-name>"` (e.g. `"websearch_web_search_exa"`): forward
+     *   the call to that opencode-side tool with `executed:false`. Requires
+     *   the corresponding MCP server to be configured in opencode.
+     * - `"disabled"`: prevent the model from calling WebSearch entirely
+     *   (passes `WebSearch` via `--disallowedTools`).
+     */
+    webSearch?: WebSearchRouting;
+    /**
+     * Detect mid-session opencode MCP config changes and respawn the
+     * underlying claude process so newly enabled / disabled MCPs become
+     * visible to the model without restarting opencode or starting a new
+     * chat. Eviction happens at the start of the next user turn (never mid
+     * tool-call) and `--session-id` is preserved so the conversation
+     * continues seamlessly. Defaults to `true`.
+     *
+     * Set to `false` to keep the previous behavior (cached subprocess
+     * survives MCP changes until the chat is reset).
+     */
+    hotReloadMcp?: boolean;
 }
 type PermissionMode = "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
 type ControlRequestBehavior = "allow" | "deny";
@@ -248,9 +298,14 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     private toFinishReason;
     private requestScope;
     /**
-     * Build the combined `--mcp-config` list: user-configured paths plus the
-     * auto-bridged opencode MCP config (when enabled and present) and the
-     * proxy MCP scratch file (when proxyTools are enabled).
+     * Build the combined `--mcp-config` list and return both the list and the
+     * hash of the bridged opencode MCP block (or null when bridging is off /
+     * yields nothing). The hash is used to detect mid-session config changes
+     * and respawn the underlying claude process.
+     *
+     * `runtimeStatus` is a snapshot of opencode's `client.mcp.status()`. When
+     * provided it overlays opencode's UI-toggled state on top of disk config
+     * so `/mcps` toggles propagate without a config file write.
      */
     private effectiveMcpConfig;
     /** Resolve ProxyToolDef[] for the configured proxyTools names. */
@@ -284,15 +339,35 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     doStream(options: LanguageModelV3CallOptions): Promise<Awaited<ReturnType<LanguageModelV3["doStream"]>>>;
 }
 
+interface BridgedMcp {
+    /** Path to the temp file containing the translated `--mcp-config`. */
+    path: string;
+    /** Stable hash of the merged opencode mcp block (pre-translation). */
+    hash: string;
+}
 /**
- * Read opencode config file(s), translate their `mcp` block to Claude CLI
- * format, write a scratch file, and return its path. Later files override
- * earlier files per server-name (matching opencode's own merge semantics).
+ * Per-server runtime status from opencode's `client.mcp.status()`. Used as
+ * an overlay on top of the on-disk merged config so opencode's UI-toggled
+ * state — which lives only in-memory; `connect()`/`disconnect()` never
+ * touch disk — propagates to the bridged claude subprocess.
+ *
+ * Treatment per server:
+ *   - "connected"      → force `enabled: true` (mirror opencode)
+ *   - any other status → force `enabled: false` (don't ship a server
+ *     opencode can't run; user fixes it in opencode first)
+ *   - missing entry    → leave disk value
  *
- * Returns null when no opencode config with MCP servers is found — callers
- * should treat that as "nothing to bridge" and carry on.
+ * Omit the overlay and the bridge falls back to disk-only.
+ */
+type RuntimeMcpStatus = Record<string, string>;
+/**
+ * Read opencode config layers, deep-merge their `mcp` blocks per opencode's
+ * own semantics, optionally apply an opencode runtime-status overlay, then
+ * translate each server to Claude CLI format, write a scratch file, and
+ * return its path + a stable hash. Returns null when no enabled MCP servers
+ * remain after the merge + overlay.
  */
-declare function bridgeOpencodeMcp(cwd: string): string | null;
+declare function bridgeOpencodeMcp(cwd: string, runtimeStatus?: RuntimeMcpStatus): BridgedMcp | null;
 
 declare const defaultModels: Record<string, OpenCodeModel>;