@khalilgharbaoui/opencode-claude-code-plugin 0.17.0 → 0.18.1

package/README.md

@@ -267,7 +267,7 @@ model: claude-code-appical/claude-opus-5@appical
 | `proxyTools` | string[] | `["Bash", "Edit", "Write", "WebFetch", "Task"]` | Claude built-in tools to route through opencode's executor + permission UI. Opt-in extras: `"Question"`, `"Compress"`. See [Selective tool proxy](#selective-tool-proxy). |
 | `extraDisallowedTools` | string[] | – | Extra Claude built-ins to switch off with `--disallowedTools`, on top of what `proxyTools` implies. Claude's names, e.g. `["NotebookEdit"]`. See [Closing a tool with no proxy](#closing-a-tool-with-no-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). |
-| `planModeQuestion` | boolean | `false` | Route `ExitPlanMode` approval through opencode's native `question` tool instead of a text "(yes/no)" prompt. Off because opencode's question form is currently broken upstream. See [Plan mode](#plan-mode). |
+| `planModeQuestion` | boolean | `false` | Route `ExitPlanMode` approval through opencode's native `question` tool instead of a text "(yes/no)" prompt. Opt-in; verify the form works in your installation first. See [Plan mode](#plan-mode). |
 | `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. |
@@ -553,6 +553,20 @@ Notes:
 
 Fully restart opencode after upgrading to load the command and runtime changes. Other providers do not gain Claude's native side-question behavior from this command.
 
+## Configuration skill
+
+The package includes a `claude-code-plugin` skill so your agent can configure it without asking you to navigate all its options. Ask, for example:
+
+```text
+Use the claude-code-plugin skill to configure a work account and idle worker cleanup.
+```
+
+It covers accounts, models and agent effort, proxy tools, permissions, MCP/skill bridging, timeouts, logging, upgrades and troubleshooting. It directs the agent to preserve JSONC comments, change only requested settings, validate the result, protect credentials and ask before paid probes or broader permissions.
+
+The plugin registers the bundled directory with opencode's `skills.paths`, making it available to other providers too on supporting opencode versions. For ordinary headless Claude turns it also loads through Claude's native Skill tool as `opencode-skills:claude-code-plugin`, even when `bridgeOpencodeSkills` is off. This requires CLI `--plugin-dir` support; interactive transport, compaction and direct `doGenerate` calls do not load the native bridge.
+
+No separate skill installation or copying is needed. It ships with each package version, so upgrading updates the reference. Fully restart opencode to load it. `test-configure-skill.ts` checks coverage of provider/logging options, model ids, proxy tools and environment variables; maintainers must update behavior and default guidance in the same change as the implementation.
+
 ## Skill bridge
 
 opencode and Claude Code use the same on-disk skill format, a `<name>/SKILL.md` whose frontmatter carries `name` and `description`, but they read from different directories. opencode looks in `.opencode/skills/` and `~/.config/opencode/skills/`; the Claude CLI looks in `~/.claude/skills/` and its own plugins. So opencode advertises your skills in the system prompt it forwards, the model calls `Skill("browser-automation")`, and Claude answers `Unknown skill`.
@@ -568,7 +582,7 @@ Claude can invoke them with the Skill tool or as `/opencode-skills:<name>`. `--p
 
 Discovery order, first match wins: `.opencode/skills/` walking up from the working directory, then `~/.opencode/skills/`, then `$OPENCODE_CONFIG_DIR/skills/`, then `~/.config/opencode/skills/`. A project skill shadows a global one of the same name. If the skill set is unchanged the staged directory is reused between spawns.
 
-It is **off by default** here, unlike on the fork it came from: every bridged skill is also listed in the system prompt opencode already forwards, so a large skill set is paid for twice on every turn. Turn it on when you see `Unknown skill`. It no-ops on the compaction path and on a Claude CLI without `--plugin-dir` (the plugin probes `claude --help` and logs a notice).
+Bridging **your own skills is off by default** here, unlike on the fork it came from: every bridged skill is also listed in the system prompt opencode already forwards, so a large skill set is paid for twice on every turn. Turn it on when you see `Unknown skill`. The bundled configuration skill is loaded independently of this opt-in. The native bridge is not used for compaction or interactive transport, or on a Claude CLI without `--plugin-dir` (the plugin probes `claude --help` and logs a notice).
 
 This bridge was written by [@broskees](https://github.com/broskees) (Joseph Roberts) on his fork and absorbed here with credit; see [Credits](#credits).
 
@@ -646,6 +660,10 @@ Each chat keeps a long-lived `claude` subprocess so the model retains its native
 
 Set `permissionMode: "plan"` to forward `--permission-mode plan` to Claude. The plugin handles `ExitPlanMode` specially — instead of forwarding it as a tool call, it converts it to a confirmation prompt that flows through opencode normally.
 
+> **Plan mode never permits edits, and you do not have to configure anything for that.** The CLI lets `--dangerously-skip-permissions` override `--permission-mode plan` outright, and `skipPermissions` defaults to `true`, so until this was fixed anyone asking for plan mode silently got full write access (measured on CLI 2.1.258: the run wrote a file on request without a prompt). The plugin now drops the skip flag whenever `permissionMode` is `"plan"`; every other mode governs prompting, which is what that flag is for, so those still pass it.
+>
+> Two things to know. Nothing releases plan mode mid-session: headless Claude Code is not offered an `ExitPlanMode` tool, so approving a plan in chat does not unlock writes, and leaving plan mode means changing the config and restarting opencode. The plugin warns about this once at startup. And the CLI still writes its own plan document under `~/.claude*/plans/`, which is its own feature and outside your workspace; your files and commands are untouched.
+
 By default that prompt is text: the plan is rendered as markdown, followed by `**Do you want to proceed with this plan?** (yes/no)`, and you answer in your next message.
 
 ### Approval as a real form (`planModeQuestion`, opt-in)
@@ -661,7 +679,7 @@ Set `planModeQuestion: true` to route the approval through opencode's native `qu
 
 The plan is still rendered, but the turn then ends on `tool-calls` and opencode runs its own `question` tool, so approval is a form rather than prose. Your answer is fed back to the CLI as the `tool_result` for the original `ExitPlanMode` call, which is what actually unlocks plan mode on the Claude side. A "yes" typed as ordinary text never does that. Anything other than picking `yes` (including custom text) comes back as rejection feedback the model is told to act on.
 
-> **Leave this off for now.** It depends on the same opencode `question` form that is [broken upstream](#with-question-in-proxytools-currently-blocked-upstream--leave-it-off): with it on, a plan approval hangs until you interrupt the turn. On opencode builds with no `question` registry entry at all the plugin silently keeps the text path (look for `plan-mode question gate` in the log). Re-test when [anomalyco/opencode#36603](https://github.com/anomalyco/opencode/pull/36603) merges.
+> **This cannot currently fire on the default headless transport, so leaving it off costs you nothing.** The form it delivers through works (see [AskUserQuestion](#askuserquestion)), but headless `--print` does not offer the model an `ExitPlanMode` tool at all on CLI 2.1.258, and the bridge keys on that tool call. Measured three ways: asked directly for its tool list in plan mode, the CLI returned `Agent, Bash, Edit, ListAgents, Read, ReportFindings, ScheduleWakeup, Skill, ToolSearch, Workflow, Write` and nothing else; asked to do work it said "I'm unable to exit plan mode from within the tool set available to me"; and a full probe through this plugin with `planModeQuestion: true` produced no `ExitPlanMode` anywhere in `plugin.log` while the model asked for approval in prose. The name is still known to the CLI (`--disallowedTools ExitPlanMode` validates silently, where a bogus name warns), so this reads as headless dormancy rather than removal, the same shape as the [`AskUserQuestion` fallback](#askuserquestion). The text path below is what you actually get, and it works. Re-run those probes on a newer CLI before assuming the bridge is reachable. On opencode builds with no `question` registry entry the plugin silently keeps the text path (look for `plan-mode question gate` in the log).
 
 Approval bridge contributed by [@CollieIsCute](https://github.com/CollieIsCute).
 
@@ -671,11 +689,17 @@ Approval bridge contributed by [@CollieIsCute](https://github.com/CollieIsCute).
 
 opencode ships a built-in `question` tool (`packages/opencode/src/tool/question.ts`) that renders a real TUI form with options and a custom-answer field — near-identical to Claude Code's `AskUserQuestion` (`multiSelect` → `multiple`). The plugin can route `AskUserQuestion` through it so the prompt becomes an actual form instead of plain text. Two modes:
 
-### With `"Question"` in `proxyTools` (currently blocked upstream — leave it off)
+### With `"Question"` in `proxyTools` (opt-in)
+
+> **Correction, September 6, 2026: this is no longer blocked, and earlier releases of this README were wrong about why.** The missing form was attributed to an upstream TUI regression. The real cause was local: a notification plugin awaited macOS `alerter` dismissal inside `tool.execute.before`, so the question tool never started. Native providers load that same global plugin, which is why their identical failure did not isolate the TUI. With the hook made non-blocking, the form renders, and the full path through this plugin is verified: on plugin 0.18.0 / Claude Code 2.1.258 / opencode 1.18.29, Claude called `mcp__opencode_proxy__question`, the request appeared in `GET /question`, the reply completed the tool, and Claude's answer contained a token it could only have read from the tool result. Confirmed in a real terminal too: with `"Question"` enabled and opencode relaunched, the proxied call rendered as a TUI form and the clicked answers came back into the turn.
+>
+> `"Question"` is still opt-in, because turning it on disables Claude's own `AskUserQuestion` (see the fallback below) and that trade should be deliberate. If your form does not render, see [question troubleshooting](#question-troubleshooting) before assuming an upstream bug.
+
+#### Question troubleshooting
 
-> **Known upstream breakage (opencode 1.15.x through at least 1.18.5).** opencode's `question` TUI form does not render, so the tool blocks until you interrupt the turn. This is not specific to this plugin: native providers hit it identically, and a `--pure` headless server drives the same question end to end successfully (`question.asked` → `GET /question` → `POST /question/{id}/reply` → tool completes), which isolates the fault to the TUI. Tracked upstream as [anomalyco/opencode#36604](https://github.com/anomalyco/opencode/issues/36604) with fix [PR #36603](https://github.com/anomalyco/opencode/pull/36603) (unmerged). Until that lands, enabling `"Question"` trades the working fallback below for a hang. The instructions here describe the intended behavior for when it is fixed.
+For a stalled call, inspect `GET /question` on the same opencode server and workspace. If no request exists, check awaited `tool.execute.before` hooks and custom tools replacing `question`, especially notification plugins: a hook opencode waits on runs *before* the tool, so the request cannot exist yet. If a request exists but no form appears, check session ownership, pending permissions, and event delivery. The separate detach/reattach issue [anomalyco/opencode#36604](https://github.com/anomalyco/opencode/issues/36604) remains open; [PR #36603](https://github.com/anomalyco/opencode/pull/36603) is closed without merging. Do not infer a universal platform or version failure from either symptom.
 
-Add `"Question"` to `proxyTools` and grant `permission.question: allow` to the calling agent. Claude's built-in `AskUserQuestion` is disabled via `--disallowedTools`, and the plugin exposes `mcp__opencode_proxy__question` in its place. The model calls the proxy, opencode renders the form, and the operator's answers come back as arrays of selected labels. On builds that lack the `question` registry entry the def is silently dropped at spawn (version gate), and the deny/markdown fallback below applies instead.
+Add `"Question"` to `proxyTools`. Claude's built-in `AskUserQuestion` is disabled via `--disallowedTools`, and the plugin exposes `mcp__opencode_proxy__question` in its place. A primary agent needs no permission entry (verified on opencode 1.18.29 with no `permission` block at all); if a subagent's form is refused, grant it `permission.question: "allow"` on that agent, the same way [subagent todos](#subagent-todos) need `todowrite`. The model calls the proxy, opencode renders the form, and the operator's answers come back as arrays of selected labels. On builds that lack the `question` registry entry the def is silently dropped at spawn (version gate), and the deny/markdown fallback below applies instead.
 
 `proxyTools` replaces the default list rather than adding to it, so repeat the defaults you still want:
 

package/dist/index.d.ts

@@ -78,6 +78,10 @@ type OpenCodeConfig = {
         models?: Record<string, unknown>;
     }>;
     agent?: Record<string, Record<string, unknown>>;
+    skills?: {
+        paths?: string[];
+        urls?: string[];
+    };
 };
 /**
  * Bus events surface to plugins. Shape mirrors what opencode core publishes
@@ -764,6 +768,8 @@ declare const DEFAULT_PROXY_TOOL_NAMES: string[];
  * so a user-defined command keeps opencode's normal behaviour end to end.
  */
 declare function registerSideQuestionCommand(config: OpenCodeConfig): boolean;
+declare function _resetPlanModeWarningForTests(): void;
+declare function warnIfPlanModeCannotExit(permissionMode: string | undefined): void;
 declare function createClaudeCode(settings?: ClaudeCodeProviderSettings): ClaudeCodeProvider;
 /**
  * Build models in OpenCode's config schema format (flat properties like
@@ -782,4 +788,4 @@ declare const _default: {
     server: OpenCodePlugin;
 };
 
-export { type AgentRecord, type ClaudeCodeConfig, ClaudeCodeLanguageModel, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeStreamMessage, DEFAULT_PROXY_TOOL_NAMES, type OpenCodeHooks, type OpenCodeModel, type OpenCodePlugin, bridgeOpencodeMcp, claudeCodeProviders, configModelsForProvider, createClaudeCode, _default as default, defaultModels, getAgentRegistry, getDefaultSubagentModel, registerSideQuestionCommand, resolveAgentModel };
+export { type AgentRecord, type ClaudeCodeConfig, ClaudeCodeLanguageModel, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeStreamMessage, DEFAULT_PROXY_TOOL_NAMES, type OpenCodeHooks, type OpenCodeModel, type OpenCodePlugin, _resetPlanModeWarningForTests, bridgeOpencodeMcp, claudeCodeProviders, configModelsForProvider, createClaudeCode, _default as default, defaultModels, getAgentRegistry, getDefaultSubagentModel, registerSideQuestionCommand, resolveAgentModel, warnIfPlanModeCannotExit };

package/dist/index.js

@@ -447,10 +447,13 @@ function detectCliSupportsFlag(cliPath, flag) {
   if (cached) return cached;
   const promise = (async () => {
     try {
-      const { stdout } = await execFileAsync(cliPath, ["--help"], {
+      const execution = execFileAsync(cliPath, ["--help"], {
         timeout: 5e3,
+        killSignal: "SIGKILL",
         maxBuffer: 4 * 1024 * 1024
       });
+      execution.child.stdin?.end();
+      const { stdout } = await execution;
       return stdout.includes(flag);
     } catch (err) {
       log.warn("failed to probe claude cli flag support", {
@@ -2252,7 +2255,7 @@ function buildCliArgs(opts) {
   if (fastMode && cliSupportsFastMode(cliVersion ?? null)) {
     args.push("--settings", JSON.stringify({ fastMode: true }));
   }
-  if (skipPermissions) {
+  if (skipPermissions && permissionMode !== "plan") {
     args.push("--dangerously-skip-permissions");
   }
   return args;
@@ -3302,7 +3305,17 @@ import * as crypto2 from "crypto";
 import * as fs3 from "fs";
 import * as os2 from "os";
 import * as path4 from "path";
+import { fileURLToPath } from "url";
 var SKILL_PLUGIN_NAME = "opencode-skills";
+function bundledSkillsDir() {
+  try {
+    const here = fileURLToPath(import.meta.url);
+    const dir = path4.resolve(path4.dirname(here), "..", "skills");
+    return dirExists(dir) ? dir : null;
+  } catch {
+    return null;
+  }
+}
 function dirExists(p) {
   try {
     return fs3.statSync(p).isDirectory();
@@ -3341,28 +3354,46 @@ function skillRoots(cwd) {
   if (xdg) push(path4.join(xdg, "opencode", "skills"));
   return roots;
 }
+function collectSkills(root, claimed, found) {
+  let entries;
+  try {
+    entries = fs3.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const name = entry.name;
+    if (name.startsWith(".")) continue;
+    if (claimed.has(name)) continue;
+    const dir = path4.join(root, name);
+    if (!fileExists(path4.join(dir, "SKILL.md"))) continue;
+    claimed.add(name);
+    found.push({ name, dir });
+  }
+}
+var byName = (a, b) => a.name.localeCompare(b.name);
 function discoverOpencodeSkills(cwd) {
   const found = [];
   const claimed = /* @__PURE__ */ new Set();
-  for (const root of skillRoots(cwd)) {
-    let entries;
-    try {
-      entries = fs3.readdirSync(root, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-      const name = entry.name;
-      if (name.startsWith(".")) continue;
-      if (claimed.has(name)) continue;
-      const dir = path4.join(root, name);
-      if (!fileExists(path4.join(dir, "SKILL.md"))) continue;
-      claimed.add(name);
-      found.push({ name, dir });
-    }
-  }
-  return found.sort((a, b) => a.name.localeCompare(b.name));
+  for (const root of skillRoots(cwd)) collectSkills(root, claimed, found);
+  return found.sort(byName);
+}
+function discoverBundledSkills() {
+  const root = bundledSkillsDir();
+  if (!root) return [];
+  const found = [];
+  collectSkills(root, /* @__PURE__ */ new Set(), found);
+  return found.sort(byName);
+}
+function registerBundledSkillPath(config) {
+  const dir = bundledSkillsDir();
+  if (!dir) return false;
+  config.skills ??= {};
+  const paths = config.skills.paths ??= [];
+  if (paths.some((p) => path4.resolve(p) === dir)) return false;
+  paths.push(dir);
+  return true;
 }
 function linkSkill(source, target) {
   try {
@@ -3408,8 +3439,10 @@ function buildSkillPluginDir(skills) {
   return root;
 }
 async function resolveSkillPluginDirs(opts) {
-  if (!opts.enabled) return [];
-  const skills = discoverOpencodeSkills(opts.cwd);
+  const user = opts.enabled ? discoverOpencodeSkills(opts.cwd) : [];
+  const claimed = new Set(user.map((s) => s.name));
+  const bundled = discoverBundledSkills().filter((s) => !claimed.has(s.name));
+  const skills = [...user, ...bundled].sort(byName);
   if (skills.length === 0) return [];
   const supported = await detectCliSupportsFlag(opts.cliPath, "--plugin-dir");
   if (!supported) {
@@ -3424,6 +3457,7 @@ async function resolveSkillPluginDirs(opts) {
   log.info("bridged opencode skills into claude", {
     count: skills.length,
     names: skills.map((s) => s.name),
+    bundled: bundled.map((s) => s.name),
     pluginDir: dir
   });
   return [dir];
@@ -7670,7 +7704,7 @@ import {
 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join8, resolve as resolve4 } from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 var STALE_PACKAGE_NAME = "opencode-claude-code-plugin";
 var SUSPECT_DESCRIPTION_TOKEN = "Claude Code";
 var alreadyRan = false;
@@ -7702,7 +7736,7 @@ function userIntendsToUseUnscoped() {
 }
 function ourLoadedDir() {
   try {
-    const filePath = fileURLToPath(import.meta.url);
+    const filePath = fileURLToPath2(import.meta.url);
     return realpathSync(resolve4(filePath, "..", ".."));
   } catch {
     return null;
@@ -7776,12 +7810,12 @@ import { execFile as execFile2 } from "child_process";
 import * as fs6 from "fs";
 import * as path8 from "path";
 import { promisify as promisify2 } from "util";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 var cachedPluginVersion;
 function pluginVersion() {
   if (cachedPluginVersion) return cachedPluginVersion;
   try {
-    const here = path8.dirname(fileURLToPath2(import.meta.url));
+    const here = path8.dirname(fileURLToPath3(import.meta.url));
     const raw = fs6.readFileSync(path8.join(here, "..", "package.json"), "utf8");
     const version = JSON.parse(raw).version;
     cachedPluginVersion = typeof version === "string" ? version : "unknown";
@@ -7905,6 +7939,7 @@ function pickOpencodeDirectory(input) {
   return void 0;
 }
 var warnedAnthropicApiKey = false;
+var warnedPlanModeNoExit = false;
 var DEFAULT_PROXY_TOOL_NAMES = [
   "Bash",
   "Edit",
@@ -7936,6 +7971,18 @@ function warnIfAnthropicApiKey(ignore) {
     );
   }
 }
+function _resetPlanModeWarningForTests() {
+  warnedPlanModeNoExit = false;
+}
+function warnIfPlanModeCannotExit(permissionMode) {
+  if (permissionMode !== "plan") return;
+  if (warnedPlanModeNoExit) return;
+  warnedPlanModeNoExit = true;
+  log.warn(
+    'permissionMode "plan" is enforced: claude cannot edit files or run commands, and --dangerously-skip-permissions is deliberately not passed so it stays that way. Headless Claude Code is not offered an ExitPlanMode tool, so nothing releases plan mode mid-session; approving a plan in chat does not unlock writes. Leaving plan mode means changing the config and restarting opencode.',
+    { permissionMode, measuredOn: "claude-code 2.1.258" }
+  );
+}
 function createClaudeCode(settings = {}) {
   if (settings.logging) {
     configureLogger({
@@ -7946,6 +7993,7 @@ function createClaudeCode(settings = {}) {
     });
   }
   warnIfAnthropicApiKey(settings.ignoreAnthropicApiKey);
+  warnIfPlanModeCannotExit(settings.permissionMode);
   const cliPath = settings.cliPath ?? process.env.CLAUDE_CLI_PATH ?? "claude";
   const providerName = settings.providerID ?? settings.name ?? "claude-code";
   const proxyTools = settings.proxyTools ?? [...DEFAULT_PROXY_TOOL_NAMES];
@@ -8177,6 +8225,7 @@ var server = async (input) => {
   return {
     config: async (config) => {
       if (registerSideQuestionCommand(config)) ownsSideQuestionCommand = true;
+      registerBundledSkillPath(config);
       config.provider ??= {};
       await buildAgentRegistry(config);
       const expanded = await expandAccountProviders(config);
@@ -8252,6 +8301,7 @@ var index_default = {
 export {
   ClaudeCodeLanguageModel,
   DEFAULT_PROXY_TOOL_NAMES,
+  _resetPlanModeWarningForTests,
   bridgeOpencodeMcp,
   claudeCodeProviders,
   configModelsForProvider,
@@ -8261,6 +8311,7 @@ export {
   getAgentRegistry,
   getDefaultSubagentModel,
   registerSideQuestionCommand,
-  resolveAgentModel
+  resolveAgentModel,
+  warnIfPlanModeCannotExit
 };
 //# sourceMappingURL=index.js.map