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

package/README.md

@@ -163,7 +163,7 @@ The account model IDs are internally suffixed, for example `claude-sonnet-4-6@wo
     "claude-code": {
       "options": {
         "cliPath": "claude",
-        "proxyTools": ["Bash", "Edit", "Write", "WebFetch"],
+        "proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"],
         "skipPermissions": true,
         "permissionMode": "default",
         "bridgeOpencodeMcp": true,
@@ -181,7 +181,8 @@ The account model IDs are internally suffixed, for example `claude-sonnet-4-6@wo
 | `cwd` | string | `process.cwd()` | Working directory for the spawned CLI. Resolved **lazily per request**, so opencode's project switching works. |
 | `skipPermissions` | boolean | `true` | Pass `--dangerously-skip-permissions` to `claude`. Ignored when `proxyTools` is set — the proxy handles permissions through opencode instead. |
 | `permissionMode` | `acceptEdits` \| `auto` \| `bypassPermissions` \| `default` \| `dontAsk` \| `plan` | – | Forwarded to `claude --permission-mode`. |
-| `proxyTools` | string[] | `["Bash", "Edit", "Write", "WebFetch"]` | Claude built-in tools to route through opencode's executor + permission UI. See [Selective tool proxy](#selective-tool-proxy). |
+| `proxyTools` | string[] | `["Bash", "Edit", "Write", "WebFetch", "Task"]` | Claude built-in tools to route through opencode's executor + permission UI. See [Selective tool proxy](#selective-tool-proxy). |
+| `proxyToolTimeoutMs` | `Record<string, number>` | – | Per-tool proxy call deadline in ms, keyed by proxy tool name (`bash`, `task`, …). Defaults: 10 min flat, `task` → 60 min. For `bash`, the call's own `input.timeout` is honoured on top (`max(resolved, input.timeout)`). See [Selective tool proxy](#selective-tool-proxy). |
 | `controlRequestBehavior` | `allow` \| `deny` | `allow` | Default response when `skipPermissions: false` and Claude sends a `can_use_tool` control request. |
 | `controlRequestToolBehaviors` | `Record<string, "allow" \| "deny">` | – | Per-tool override for `can_use_tool`. Example: `{ "Bash": "deny", "Read": "allow" }`. |
 | `controlRequestDenyMessage` | string | built-in message | Message returned to Claude on a deny. |
@@ -259,7 +260,7 @@ Set `interactiveSystemPrompt: false` only for diagnostics. While disabled, the i
 
 This is the core feature.
 
-By default, when Claude Code's CLI uses `Bash`, `Edit`, `Write`, etc., it executes them itself — bypassing opencode's permission UI, audit trail, and policy rules entirely. With `proxyTools`, you tell the plugin to disable Claude's built-in version of a tool and expose an equivalent through an in-process MCP server. Claude calls the MCP version, which blocks until opencode runs the tool through its own executor.
+By default, the plugin proxies `Bash`, `Edit`, `Write`, `WebFetch`, and `Task`. It disables Claude's corresponding built-in tool and exposes an equivalent through an in-process MCP server. Claude calls the MCP version, which blocks until opencode runs the tool through its own executor and permission system.
 
 ### Default proxied tools
 
@@ -271,11 +272,18 @@ By default, when Claude Code's CLI uses `Bash`, `Edit`, `Write`, etc., it execut
 | `"WebFetch"` | `WebFetch` | `mcp__opencode_proxy__webfetch` |
 | `"Task"` | `Agent` | `mcp__opencode_proxy__task` |
 
-The `Task` proxy is the way to let Claude orchestrate opencode's configured subagents (`build`, `general`, custom subagents defined in `opencode.json`) instead of Claude CLI's internal-only general-purpose / Explore / Plan options. With `"Task"` in `proxyTools` and `permission.task: allow` granted to the calling agent, a Claude session can invoke `task(subagent_type="build", prompt="...")` and the subagent runs natively under opencode (with its own permission UI, lifecycle, model assignment, and Tab visibility). Without `"Task"`, Claude's built-in `Agent` tool stays enabled and Claude orchestrates subagents internally with no opencode visibility.
+### OpenCode-native subagents
+
+`Task` is proxied by default. The proxy disables Claude CLI's `Agent` tool and emits an unexecuted `task` call; it does not register a replacement task tool. OpenCode's built-in TaskTool remains responsible for permission checks, creating or resuming the child session, selecting the configured subagent, and foreground/background lifecycle.
+
+- **Permissions:** the calling agent's `permission.task` rule applies to the target `subagent_type`. Grant `task: "allow"` on agents that should delegate without a prompt; an `ask` or `deny` rule remains authoritative. The plugin never bypasses this decision.
+- **Resume:** pass the child session ID back as `task_id` to continue that subagent session. Omit it to create a fresh child.
+- **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.
 
 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.
 
-To turn off proxying entirely:
+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:
 
 ```json
 "options": { "proxyTools": [] }
@@ -292,6 +300,24 @@ To turn off proxying entirely:
 - A small per-call latency hop through `127.0.0.1:<random>/mcp`.
 - Batched-edit ergonomics: with `Edit` proxied, Claude can no longer use `MultiEdit`, so a refactor that would have been one tool call becomes N single `Edit` calls.
 
+### Per-tool proxy timeouts
+
+Every proxied tool call has a deadline: if opencode hasn't resolved it (run the underlying tool and returned a result) within that many milliseconds, the call is rejected and Claude receives a timeout error. Deadlines are resolved per tool, most-specific layer winning:
+
+1. flat default — 10 min (matches Claude CLI's own Bash ceiling)
+2. per-tool default — **`task`: 60 min**, **`question`: 30 min**, everything else: 10 min
+3. your `proxyToolTimeoutMs` override (case-insensitive key)
+4. for `bash` only, the call's own `input.timeout` — the proxy never undercuts a build the caller explicitly asked to run long (`max(resolved, input.timeout)`)
+
+The `task` and `question` defaults are deliberately generous. Subagents routinely run 20–40 min, and a question can sit on a slow operator; under the old flat 10-minute ceiling the proxy fired mid-call, Claude believed its dispatch had failed, and the subagent's eventual result was dropped (the parent turn had already ended on the timeout error). If a `task` call *does* time out, the error tells Claude not to "schedule a wake-up" — that is a Claude Code affordance which cannot fire in this headless/proxy context, so deferring silently loses the work.
+
+```json
+"options": {
+  "proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"],
+  "proxyToolTimeoutMs": { "Task": 5400000, "bash": 1800000 }
+}
+```
+
 ---
 
 ## WebSearch routing
@@ -505,6 +531,46 @@ Boolean env vars accept `1/true/on/yes` for on and `0/false/no/off` for
 off; empty / unset falls through to config. Invalid `level` values fall
 through to config.
 
+### Startup diagnostics
+
+Once per process, right after the provider(s) register, the plugin logs a
+single `NOTICE: claude-code plugin ready` line summarizing everything worth
+knowing before you start debugging anything else:
+
+```bash
+OPENCODE_CLAUDE_CODE_LOG_FILE=1 opencode
+grep "plugin ready" ~/.local/share/opencode-claude-code/plugin.log
+```
+
+```json
+{
+  "plugin": "0.10.0",
+  "opencode": "unknown",
+  "cwd": { "resolved": "/Users/you/code/app", "source": "process" },
+  "providers": ["claude-code-default", "claude-code-work"],
+  "accounts": ["default", "work"],
+  "proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"],
+  "mcpServers": ["github", "slack"],
+  "interactiveTransport": false,
+  "anthropicApiKeyInEnv": false,
+  "claudeCli": { "path": "claude", "version": "2.1.211 (Claude Code)" }
+}
+```
+
+Reading it:
+
+- **`cwd.source`** is which rule picked the working directory Claude will be
+  spawned in — `configured` (you pinned `options.cwd`), `process` (normal),
+  `captured` (`process.cwd()` was unusable and opencode's project directory
+  rescued it, the macOS GUI-launch case), or `unresolved` (neither worked).
+- **`claudeCli.version`** reading `not detected` means the `claude` binary at
+  that path didn't answer `--version`, which also disables version-gated
+  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.
+
 ### Default behavior (no config, no env)
 
 Nothing persists; only WARN and ERROR bubble in the TUI. The plugin
@@ -535,6 +601,7 @@ Workaround for autonomous compression: trigger it manually with `/dcp compress`
 - No streaming of tool inputs as they're being constructed (Anthropic's `input_json_delta`); the plugin emits them once complete.
 - Raw chain-of-thought is not available. Claude 4 family models ship summarized thinking only. See [Extended thinking](#extended-thinking) for the full picture.
 - Recommended Claude Code CLI: **2.1.142+**. Older CLIs work for everything else but skip the `--thinking-display` flag, so Claude Opus 4.7 turns may render empty Thinking rows. If something breaks after a Claude Code update, the CLI version is the first thing to check.
+- **Foreground Task calls have a 30-minute proxy timeout.** The same timeout is written into Claude's generated HTTP MCP configuration so long-running opencode subagents are not cut off by Claude's 60-second default. For independent longer work, use `background: true` after enabling opencode's experimental background-subagent flag.
 - **Subagent todos require explicit permission.** opencode's task tool gates `todowrite` per subagent: without a `permission: { todowrite: "allow" }` rule on the subagent definition, opencode injects `todowrite: false` into the tools dict and the plugin's synthetic `todowrite` emissions surface as `⚙ invalid todowrite` rows. The built-in `general` subagent denies `todowrite` by default; use a custom subagent for parallel work that needs todo visibility. Subagent todos render inline in the **subagent's** session view (navigate with the TUI's `session.child.next` / `session.parent` commands), not in the parent session's panel.
 
 ---

package/dist/index.d.ts

@@ -161,6 +161,7 @@ interface ClaudeCodeConfig {
     controlRequestToolBehaviors?: Record<string, ControlRequestBehavior>;
     controlRequestDenyMessage?: string;
     proxyTools?: string[];
+    proxyToolTimeoutMs?: Record<string, number>;
     webSearch?: WebSearchRouting;
     hotReloadMcp?: boolean;
     proxyOpencodeMcpTools?: boolean;
@@ -268,6 +269,23 @@ interface ClaudeCodeProviderSettings {
      * (see opencode's agent docs).
      */
     proxyTools?: string[];
+    /**
+     * Per-tool proxy call timeouts in milliseconds, keyed by the proxy tool
+     * name (`bash`, `edit`, `write`, `webfetch`, `task`, `question` —
+     * case-insensitive). When a proxied tool call waits longer than its
+     * deadline for opencode to resolve it, the call is rejected and Claude
+     * receives a timeout error.
+     *
+     * Defaults (used when a tool is absent here): `bash`/`edit`/`write`/
+     * `webfetch` → 10 min (matches Claude CLI's Bash ceiling); `task` →
+     * 60 min (subagents routinely run 20–40 min); `question` → 30 min
+     * (operator AFK). Setting a key here replaces the default for that tool.
+     *
+     * For `bash` specifically the call's own `input.timeout` is honoured on
+     * top: the effective deadline is `max(resolved, input.timeout)`, so a
+     * long build the caller explicitly asked to run is never undercut.
+     */
+    proxyToolTimeoutMs?: Record<string, number>;
     /**
      * Strip `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from the environment of
      * every spawned `claude` process. When an API key is present, Claude Code
@@ -449,6 +467,11 @@ interface ClaudeStreamMessage {
     index?: number;
 }
 
+interface DiagnosticsProviderEntry {
+    name?: string;
+    options?: Record<string, unknown>;
+}
+
 declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     readonly specificationVersion = "v3";
     readonly modelId: string;
@@ -580,9 +603,15 @@ declare function createClaudeCode(settings?: ClaudeCodeProviderSettings): Claude
  * so the config-path provider loader parses them correctly.
  */
 declare function configModelsForProvider(providerModels: OpenCodeProvider["models"], providerID: string, modelSuffix?: string): Record<string, Record<string, unknown>>;
+/**
+ * Narrow opencode's full provider map down to the ones this plugin owns
+ * (`claude-code` plus every `claude-code-<account>` expansion) so startup
+ * diagnostics never report another provider's options.
+ */
+declare function claudeCodeProviders(providers: Record<string, DiagnosticsProviderEntry> | undefined): Record<string, DiagnosticsProviderEntry>;
 declare const _default: {
     id: string;
     server: OpenCodePlugin;
 };
 
-export { type ClaudeCodeConfig, ClaudeCodeLanguageModel, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeStreamMessage, type OpenCodeHooks, type OpenCodeModel, type OpenCodePlugin, bridgeOpencodeMcp, configModelsForProvider, createClaudeCode, _default as default, defaultModels };
+export { type ClaudeCodeConfig, ClaudeCodeLanguageModel, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeStreamMessage, type OpenCodeHooks, type OpenCodeModel, type OpenCodePlugin, bridgeOpencodeMcp, claudeCodeProviders, configModelsForProvider, createClaudeCode, _default as default, defaultModels };