@khalilgharbaoui/opencode-claude-code-plugin 0.11.0 → 0.11.2

package/README.md

@@ -281,6 +281,20 @@ By default, the plugin proxies `Bash`, `Edit`, `Write`, `WebFetch`, and `Task`.
 - **Nested tasks:** current opencode defaults `subagent_depth` to `1`, so a first-level child cannot launch another child. Increase top-level `subagent_depth` to permit deeper nesting, and explicitly grant `permission.task` on every subagent that should delegate; opencode otherwise adds a task deny to spawned subagent sessions.
 - **Background:** `background: true` returns after starting the child and lets opencode notify the parent when it finishes. Current opencode requires `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` in the environment of the opencode process. Foreground is the default.
 
+**Steering models to it.** Headless Claude Code CLIs expose no `Agent`/`Task`
+dispatch tool of their own (verified on 2.1.211), while they *do* expose
+`TaskCreate` — a todo tool. So "use a subagent" requests get mis-resolved:
+a todo appears, nothing runs, and the model may still narrate a successful
+dispatch. Two spawn-time countermeasures prevent that. The plugin injects
+opencode's live agent-type list into the `task` proxy description (so the model
+picks a real `subagent_type` instead of guessing a Claude Code name like
+`general-purpose`, and doesn't grep configs to check a subagent exists), and
+appends a system-prompt note naming
+`mcp__opencode_proxy__task` as the only dispatch path — with the ToolSearch
+recovery step for harnesses that defer MCP tool schemas. Both apply per Claude
+process at spawn, and provider options are read once at opencode startup, so
+`proxyTools` changes need a full opencode restart.
+
 Only those five values are actually proxied; anything else you put in `proxyTools` is ignored. Proxying `Edit` also disables `MultiEdit` — opencode has no batched-edit equivalent, so Claude is forced to fan out into single `Edit` calls that each flow through the permission UI.
 
 Without `"Task"` in `proxyTools`, Claude's built-in `Agent` tool stays enabled and Claude orchestrates subagents internally with no opencode child-session visibility. To opt out of all proxying, including Task, use an explicit empty list:
@@ -544,8 +558,8 @@ grep "plugin ready" ~/.local/share/opencode-claude-code/plugin.log
 
 ```json
 {
-  "plugin": "0.10.0",
-  "opencode": "unknown",
+  "plugin": "0.11.1",
+  "opencode": "1.18.5",
   "cwd": { "resolved": "/Users/you/code/app", "source": "process" },
   "providers": ["claude-code-default", "claude-code-work"],
   "accounts": ["default", "work"],
@@ -568,8 +582,9 @@ Reading it:
   flags like `--thinking-display`.
 - **`mcpServers`** is the on-disk merge, before opencode's runtime toggles
   are applied (those aren't settled yet at startup).
-- **`opencode`** reads `unknown` on current opencode: as of 1.17.18 it does
-  not expose its own version to plugins.
+- **`opencode`** is read from the running opencode binary (`--version`), since
+  opencode still does not hand its version to plugins. It reads `unknown` when
+  opencode is run from source rather than as the packaged binary.
 
 ### Default behavior (no config, no env)
 

package/dist/index.d.ts

@@ -505,6 +505,17 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * client is unavailable, or no MCP servers are configured.
      */
     private resolvedProxyMcpTools;
+    /**
+     * Live description of opencode's `task` tool for the current
+     * provider/model, exactly as opencode's registry renders it for native
+     * models — including the "Available agent types" list (built from the
+     * default agent's permissions). Overlaid onto the static `task` proxy
+     * def so Claude sees the same subagent catalog native opencode models
+     * see, instead of hunting through config files. Returns undefined when
+     * the SDK client is unavailable (direct AI-SDK use, tests) so the
+     * static def stands.
+     */
+    private fetchLiveTaskDescription;
     /**
      * Create a proxy MCP server for a single active Claude process/session.
      * The process lifecycle owns the server lifecycle via session-manager.

package/dist/index.js

@@ -2117,6 +2117,37 @@ function buildProxyTimeoutError(toolName, ms) {
   }
   return new Error(base);
 }
+var TASK_PROXY_NOTE = "This is the ONLY tool that dispatches opencode subagents (including user @-mentions). Claude Code's built-in TaskCreate/TaskUpdate manage a local todo list and cannot dispatch subagents. Do not search config files to verify a subagent type exists \u2014 invalid types fail fast with a clear error. Foreground calls block until the subagent finishes; set `background` to request opencode's background execution mode. Task calls get a 60-minute proxy deadline by default (configurable via proxyToolTimeoutMs).";
+var AGENT_TYPES_HEADING = "Available agent types";
+var AGENT_BLURB_LIMIT = 140;
+function extractAgentTypeList(liveDescription) {
+  const live = liveDescription?.trim();
+  if (!live) return void 0;
+  const start = live.indexOf(AGENT_TYPES_HEADING);
+  if (start === -1) return void 0;
+  const entries = [];
+  for (const raw of live.slice(start).split("\n")) {
+    const match = /^-\s*([^:]+):\s*(.+)$/.exec(raw.trim());
+    if (!match) continue;
+    const name = match[1].trim();
+    const blurb = match[2].trim();
+    entries.push(
+      `- ${name}: ${blurb.length > AGENT_BLURB_LIMIT ? `${blurb.slice(0, AGENT_BLURB_LIMIT).trimEnd()}\u2026` : blurb}`
+    );
+  }
+  if (entries.length === 0) return void 0;
+  return `Valid subagent_type values, from opencode's live registry \u2014 anything else fails:
+${entries.join("\n")}`;
+}
+function overlayTaskProxyDescription(tools, liveDescription) {
+  const agentTypes = extractAgentTypeList(liveDescription);
+  if (!agentTypes) return tools;
+  return tools.map(
+    (t) => t.name === "task" ? { ...t, description: `${agentTypes}
+
+${t.description}` } : t
+  );
+}
 var DEFAULT_PROXY_TOOLS = [
   {
     name: "bash",
@@ -2209,7 +2240,7 @@ var DEFAULT_PROXY_TOOLS = [
   },
   {
     name: "task",
-    description: "Launch an opencode subagent to handle a complex multi-step task autonomously. Routed through opencode's task tool so subagent orchestration, permission, and lifecycle are handled by opencode. Use `subagent_type` to pick which configured subagent runs (e.g. `build`, `general`, `explore`, or any custom subagent declared in opencode.json). Foreground calls block until the subagent finishes; set `background` to request opencode's background execution mode. Task calls get a 60-minute proxy deadline by default (configurable via proxyToolTimeoutMs).",
+    description: "Launch an opencode subagent to handle a complex multi-step task autonomously. Routed through opencode's task tool so subagent orchestration, permission, and lifecycle are handled by opencode. Use `subagent_type` to pick which configured subagent runs (e.g. `build`, `general`, `explore`, or any custom subagent declared in opencode.json). " + TASK_PROXY_NOTE,
     inputSchema: {
       type: "object",
       properties: {
@@ -2884,6 +2915,14 @@ than pausing for user confirmation between subtasks. End the turn only
 when the task is done, you need clarification on intent, or you hit a real
 blocker. The user can interrupt or abort at any time; turn endings should
 mark meaningful checkpoints, not every completed substep.`;
+var SUBAGENT_DISPATCH_HINT = `## opencode subagents
+
+Subagent dispatch in this environment goes through exactly one tool: \`mcp__opencode_proxy__task\`.
+
+- When the user mentions \`@<agent>\` or an instruction says "call the task tool with subagent: <name>", call \`mcp__opencode_proxy__task\` with \`subagent_type: "<name>"\`.
+- If that tool is not in your visible tool list it is deferred \u2014 load it with ToolSearch (\`select:mcp__opencode_proxy__task\`), then call it.
+- Claude Code's built-in TaskCreate/TaskUpdate/TaskList manage a local todo list. They cannot dispatch subagents; creating a task there runs nothing. Never report a subagent as dispatched unless \`mcp__opencode_proxy__task\` returned its result.
+- Do not verify a subagent's existence by searching config files \u2014 the tool's description lists the available agent types, and invalid types fail fast with a clear error.`;
 var CLAUDE_CLI_CONTEXT_NOTE = `## Runtime environment: Claude Code CLI
 
 You are running via the Claude Code CLI (not a direct API call). This affects context management:
@@ -3058,6 +3097,24 @@ var ClaudeCodeLanguageModel = class {
     }
     return out.length > 0 ? out : null;
   }
+  /**
+   * Live description of opencode's `task` tool for the current
+   * provider/model, exactly as opencode's registry renders it for native
+   * models — including the "Available agent types" list (built from the
+   * default agent's permissions). Overlaid onto the static `task` proxy
+   * def so Claude sees the same subagent catalog native opencode models
+   * see, instead of hunting through config files. Returns undefined when
+   * the SDK client is unavailable (direct AI-SDK use, tests) so the
+   * static def stands.
+   */
+  async fetchLiveTaskDescription() {
+    const items = await fetchOpencodeToolList(
+      this.config.provider,
+      this.modelId,
+      this.config.cwd
+    );
+    return items?.find((item) => item.id === "task")?.description || void 0;
+  }
   /**
    * Create a proxy MCP server for a single active Claude process/session.
    * The process lifecycle owns the server lifecycle via session-manager.
@@ -3929,7 +3986,23 @@ ${plan}
                 discovery.allEnabledServerNames
               );
               const excludeServers = proxyMcpTools ? new Set(discovery.allEnabledServerNames) : void 0;
-              const combinedProxyTools = resolvedProxy || proxyMcpTools ? [...resolvedProxy ?? [], ...proxyMcpTools ?? []] : null;
+              const taskProxyEnabled = resolvedProxy?.some((t) => t.name === "task") ?? false;
+              let enrichedProxy = resolvedProxy;
+              if (resolvedProxy && taskProxyEnabled) {
+                const liveTaskDescription = await self.fetchLiveTaskDescription();
+                enrichedProxy = overlayTaskProxyDescription(
+                  resolvedProxy,
+                  liveTaskDescription
+                );
+                log.info("task proxy description overlay", {
+                  applied: Boolean(liveTaskDescription),
+                  liveDescriptionLength: liveTaskDescription?.length ?? 0,
+                  listsAgentTypes: Boolean(
+                    liveTaskDescription?.includes("Available agent types")
+                  )
+                });
+              }
+              const combinedProxyTools = enrichedProxy || proxyMcpTools ? [...enrichedProxy ?? [], ...proxyMcpTools ?? []] : null;
               if (!proxyServer && combinedProxyTools) {
                 proxyServer = await self.ensureProxyServer(combinedProxyTools, sk);
               }
@@ -3946,7 +4019,10 @@ ${plan}
               const systemPromptFile = activeProcess ? void 0 : buildAppendedSystemPrompt(
                 cwd,
                 self.config.multiStepContinuation !== false,
-                extractSystemMessages(options.prompt)
+                [
+                  ...extractSystemMessages(options.prompt),
+                  ...taskProxyEnabled ? [SUBAGENT_DISPATCH_HINT] : []
+                ]
               );
               cliArgs = buildCliArgs({
                 sessionKey: sk,
@@ -5537,8 +5613,10 @@ function cleanupOne(cacheRoot, ourDir) {
 }
 
 // src/startup-diagnostics.ts
+import { execFile as execFile2 } from "child_process";
 import * as fs5 from "fs";
 import * as path6 from "path";
+import { promisify as promisify2 } from "util";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var cachedPluginVersion;
 function pluginVersion() {
@@ -5564,6 +5642,29 @@ function pickOpencodeVersion(input) {
   if (typeof direct === "string" && direct.length > 0) return direct;
   return void 0;
 }
+var execFileAsync2 = promisify2(execFile2);
+var opencodeVersionProbe;
+function detectOpencodeVersion(execPath = process.execPath) {
+  if (opencodeVersionProbe) return opencodeVersionProbe;
+  opencodeVersionProbe = (async () => {
+    if (!path6.basename(execPath).toLowerCase().includes("opencode")) {
+      log.debug("skipping opencode version probe: execPath is not opencode", { execPath });
+      return void 0;
+    }
+    try {
+      const { stdout } = await execFileAsync2(execPath, ["--version"], { timeout: 5e3 });
+      const match = /\d+\.\d+\.\d+\S*/.exec(stdout.trim());
+      return match ? match[0] : void 0;
+    } catch (err) {
+      log.debug("opencode version probe failed", {
+        execPath,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      return void 0;
+    }
+  })();
+  return opencodeVersionProbe;
+}
 function describeSpawnCwd(configured, live = process.cwd(), captured = getOpencodeProjectDirectory()) {
   if (typeof configured === "string" && configured.length > 0) {
     return { resolved: configured, source: "configured" };
@@ -5619,10 +5720,8 @@ function logStartupDiagnostics(providers, opencodeVersion) {
   logged = true;
   void (async () => {
     try {
-      const { claudeCliPath, ...rest } = collectStartupDiagnostics(
-        providers,
-        opencodeVersion
-      );
+      const version = opencodeVersion ?? process.env.OPENCODE_VERSION ?? await detectOpencodeVersion();
+      const { claudeCliPath, ...rest } = collectStartupDiagnostics(providers, version);
       const cli = await detectCliVersion(claudeCliPath);
       const diagnostics = {
         ...rest,