@khalilgharbaoui/opencode-claude-code-plugin 0.27.2 → 0.28.0

package/README.md

@@ -345,6 +345,7 @@ model: claude-code-work/claude-opus-5@work
 | `cwd` | string | see description | Working directory for the spawned CLI. Resolved **lazily per request**, first match winning: this explicit value, then the opencode session's own `directory` (so `opencode serve` and the web UI spawn in the right project even though one server handles many), then `process.cwd()` when it is a real directory, then the project directory captured at plugin init (this rescues macOS GUI launches, where `process.cwd()` is `/`), and finally `process.cwd()` regardless. [Startup diagnostics](#startup-diagnostics) reports which tier won. Session tier contributed by [@galvani](https://github.com/galvani). |
 | `skipPermissions` | boolean | `true` | Pass `--dangerously-skip-permissions` to `claude`. It is still passed when `proxyTools` is set: proxied calls go through opencode's permission system regardless, but unproxied CLI built-ins do not. The one case where the flag is dropped is `permissionMode: "plan"`, because the CLI lets the skip flag override plan mode outright. See [Plan mode](#plan-mode). |
 | `permissionMode` | `acceptEdits` \| `auto` \| `bypassPermissions` \| `default` \| `dontAsk` \| `plan` | – | Forwarded to headless `claude --permission-mode`. `"plan"` also suppresses `--dangerously-skip-permissions` (see the row above). Not version-gated, so check that your installed CLI accepts the value. The [interactive transport](#interactive-transport-experimental) does not forward it. |
+| `permissionPreset` | `"read-only"` | – | A named permission posture, so you set one option instead of combining five and getting one wrong. Opt-in: unset is exactly today's behaviour. `"read-only"` replaces `skipPermissions`, `permissionMode`, `controlRequestBehavior` and `controlRequestToolBehaviors`, and filters the write and command tools out of `proxyTools`. See [Read-only mode](#read-only-mode). |
 | `defaultSubagentModel` | string | – | Model that plugin-discovered `mode: subagent` agents run on when their own definition pins nothing. The caller's account is kept; only the model name changes. An agent's own `forceModel` wins over it, and an unknown id is refused rather than spawned. Unset means no implicit override at all. See [Subagents: your account, their model](#subagents-your-account-their-model). |
 | `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). |
@@ -362,7 +363,7 @@ model: claude-code-work/claude-opus-5@work
 | `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). |
 | `multiStepContinuation` | boolean | `true` | Append a system-prompt hint nudging Claude to chain tool calls within one turn instead of pausing between subtasks. Each opencode turn boundary requires the user to manually press "continue", so for multi-step tasks this reduces friction. Set `false` to disable. |
-| `autoContinueIncompleteTurns` | boolean \| `"smart"` | `"smart"` | Smartly continue incomplete Claude CLI results inside the same opencode turn. Reduces manual "continue" presses when Claude ends after reasoning/tool activity without a useful final answer. Set `false` to disable. |
+| `autoContinueIncompleteTurns` | boolean \| `"smart"` | `"smart"` | Smartly continue incomplete Claude CLI results inside the same opencode turn. Reduces manual "continue" presses when Claude ends after reasoning/tool activity without a useful final answer. Also gates the `▌ **no reply:**` note on a turn that ends with no text and no tool call. Set `false` to disable both. |
 | `compactionModel` | string | `"claude-haiku-4-5"` | Model used when opencode invokes `/compact`. Override per-process via the `CLAUDE_CODE_COMPACTION_MODEL` env var (env wins over config). See [Compaction](#compaction). |
 | `ignoreAnthropicApiKey` | boolean | `false` | Strip `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from every spawned `claude` process so it authenticates with your logged-in subscription instead of pay-as-you-go API billing. The plugin warns once at startup whenever an API key is detected, regardless of this setting. See [Billing](#billing). |
 | `idleProcessTimeoutMs` | number | – | Kill a retained headless Claude worker after this many idle milliseconds following a completed turn. The timer starts when a turn finishes, a new turn cancels it, a worker that is mid-turn when it fires is left alone and re-timed, and the session id is preserved for `--resume`. Values above Node's maximum timer delay (`2147483647`) are ignored. Omit or set `0` to retain workers until LRU eviction (16 processes). Interactive transport is excluded. Contributed by [@bernardofortes](https://github.com/bernardofortes). |
@@ -391,7 +392,9 @@ Every variable the plugin itself reads, in one place. Config is read once at ope
 | `OPENCODE_CLAUDE_CODE_LOG_DIR` | logger | Directory for the log file, overriding `logging.dir`. |
 | `OPENCODE_CLAUDE_CODE_LOG_LEVEL` | logger | Minimum level to emit, overriding `logging.level`. An unrecognised value falls through to config. |
 | `DEBUG` | logger | `DEBUG=opencode-claude-code` promotes the logger to `mode: "debug"`, echoing every emitted level to opencode's TUI. |
-| `OPENCODE_CLAUDE_CODE_PLUGIN_NO_CLEANUP` | startup cleanup | `1` skips the one-time removal of a stale **unscoped** `opencode-claude-code-plugin` install from opencode's plugin cache. That old package is a different artifact that shadows this scoped one when both are present; set this if you are deliberately keeping it. |
+| `OPENCODE_CLAUDE_CODE_PLUGIN_NO_CLEANUP` | startup cleanup | `1` skips the removal of a stale **unscoped** `opencode-claude-code-plugin` install from opencode's plugin cache. That old package is a different artifact that shadows this scoped one when both are present; set this if you are deliberately keeping it. |
+| `OPENCODE_CLAUDE_CODE_PLUGIN_FORCE_CLEANUP` | startup cleanup | `1` runs that cleanup even when the marker at `$XDG_STATE_HOME/opencode-claude-code-plugin/cleanup-stale.json` (default `~/.local/state/...`) records that this plugin version already swept. Without it the cleanup walks opencode's plugin cache once per installed version rather than on every launch. |
+| `OPENCODE_CLAUDE_CODE_NO_TMP_SWEEP` | scratch directory | `1` skips the sweep of `<tmpdir>/opencode-claude-code-<pid>` directories left behind by plugin processes that were killed. See [Scratch files on disk](#scratch-files-on-disk). |
 | `OPENCODE_WORKTREE` | MCP bridge | Overrides worktree-root detection, which otherwise walks up from the working directory looking for a `.git` entry. |
 | `OPENCODE_CONFIG` / `OPENCODE_CONFIG_DIR` | config discovery | Where the plugin looks for your opencode config when bridging MCP and skills. See [Discovery order](#discovery-order-highest-to-lowest-priority). |
 | `OPENCODE_VERSION` | startup diagnostics | Reported as the opencode version when set, sparing the plugin a `--version` spawn. Diagnostics only. |
@@ -528,6 +531,23 @@ A patched process answers `401`. A `200` is a pre-0.13.2 process still running,
 
 Nothing to configure. If proxied tools ever stop working after a Claude Code upgrade, check the plugin log for `proxy-mcp rejected a request`, which names which guard failed.
 
+### Scratch files on disk
+
+Everything the plugin writes for the Claude CLI to read goes into one per-process directory, `<tmpdir>/opencode-claude-code-<pid>`, created `0700`:
+
+| File | Mode | Holds |
+| --- | --- | --- |
+| `mcp-<hash>.json` | `0600` | the bridged MCP config, including any `{env:VAR}` values substituted from your environment |
+| `proxy-<hash>.json` | `0600` | the proxy endpoint's bearer token |
+| `opencode-cc-sys-<uuid>.md` | `0600` | the full appended system prompt, forwarded opencode instructions and AGENTS.md included |
+| `skills-<hash>/` | inherits | staged skill plugin dirs for the skill bridge; the `0700` parent is what keeps them private |
+
+On a shared host the OS tmpdir is world-writable and the pid name is guessable, so the plugin refuses a path that already exists but is a symlink, is not a directory, or is not owned by you: it falls back to a fresh `mkdtemp` name and logs a warning naming both paths.
+
+The directory is removed on normal exit. `SIGKILL` skips that, so on first use each run the plugin also sweeps `<tmpdir>/opencode-claude-code-<pid>` directories whose pid is no longer running and which you own. Anything else, another user's directory, a live process's, a symlink, a name that is not exactly that pattern, is left alone. Set `OPENCODE_CLAUDE_CODE_NO_TMP_SWEEP=1` to turn the sweep off.
+
+**Windows is not hardened here.** Both spawn sites pass `shell: true` on `win32`, so the CLI argument list goes through `cmd.exe` unquoted. Treat Windows as unsupported until that is fixed; see the note in `docs/agents-history.md`.
+
 ### Closing a tool with no proxy
 
 `proxyTools` only reaches built-ins the plugin can replace. A built-in with no opencode equivalent, `NotebookEdit` today and whatever Claude Code ships next, stays enabled and unmediated no matter what you put in that list. `extraDisallowedTools` names them directly:
@@ -782,6 +802,7 @@ Four Claude Code stream events used to reach nothing but a debug log:
 - **A conversation Claude Code cleared.** Sending `/clear` as a message, or a plan-mode exit that clears context, makes Claude Code start a fresh conversation while opencode still shows the old messages. A `▌ **claude code reset:**` note says so. The plugin deliberately does not replay the earlier messages, since that would undo the clear. Start a new opencode session if you want the two to match.
 - **A `result` whose subtype is not `success`** (`error_max_turns`, `error_during_execution`, …). The subtype is named in the transcript and the turn finishes as an error instead of an ordinary reply.
 - **A CLI-executed tool that failed.** Its result is forwarded with the AI SDK's error flag, so opencode renders the row as failed rather than as a success whose output happens to be an error message.
+- **A turn that finished cleanly without saying anything.** No text, no tool call, no error: opencode files it as an ordinary reply, so what you get is a blank message with nothing to distinguish it from a crash. A `▌ **no reply:**` note now says which of the two shapes it was, thinking-with-no-answer or nothing at all, and that nothing failed and nothing is pending. It is its own text part and is stripped from any transcript rebuilt for the CLI. Never on a compaction turn, a failed turn, an aborted one, or one that ended on a question, and suppressed entirely by `"autoContinueIncompleteTurns": false`. There is deliberately no automatic retry: measured across the whole retained plugin log, every finished turn carried between 940 and 5,080 characters of reply and none was silent.
 
 At session start the plugin also warns once per process for each MCP server Claude Code could not connect (its tools are simply absent otherwise) and once when the CLI's own `apiKeySource` says an API key is in effect, which is the field that tells you pay-as-you-go billing is happening. See [`ignoreAnthropicApiKey`](#options-reference).
 
@@ -915,6 +936,64 @@ Each chat keeps a long-lived `claude` subprocess so the model retains its native
 
 ---
 
+## Read-only mode
+
+```json
+"options": {
+  "permissionPreset": "read-only"
+}
+```
+
+That is the whole configuration. The turn can read your code and search the
+web, and it cannot write a file, run a command, or execute code.
+
+Presets exist because read-only was previously a combination you had to get
+exactly right. `permissionMode: "plan"` alone does not do it, and neither does
+any single Claude Code flag, because this plugin puts a second execution path
+next to the CLI's own tools: `proxyTools` defaults to `Bash`, `Edit`, `Write`,
+`WebFetch` and `Task`, and each of those is an MCP tool the CLI calls and
+**opencode** executes. No CLI flag reaches them. So the preset works at three
+layers:
+
+| Layer | What read-only does | Why it is needed |
+| --- | --- | --- |
+| Claude CLI tools | `--restricted` (CLI 2.1.258+) | Removes Bash, the REPL and the other code-running built-ins, removes WebFetch, confines the file tools to the working directories, and refuses bypass |
+| Claude CLI tools, older CLIs | `--disallowedTools Bash Write Edit NotebookEdit REPL JavaScript WebFetch` | `--restricted` is version-gated; these names are not |
+| The opencode proxy | `bash`, `write`, `edit`, `webfetch`, `task` and `task_batch` are dropped from `proxyTools` | These run in opencode, so the CLI flags above never see them |
+| Everything else | `--permission-prompts none` (CLI 2.1.263+) and `controlRequestBehavior: "deny"` | A bridged MCP tool or a read outside the working directory is neither of the above |
+
+`skipPermissions` is forced to `false`, and that is not a style choice:
+`--restricted --dangerously-skip-permissions` is a startup error on CLI 2.1.280
+(`Error: bypassPermissions not supported in restricted mode`), so a spawn
+carrying both would not run at all.
+
+**The preset replaces rather than merges.** Setting `skipPermissions`,
+`permissionMode`, `controlRequestBehavior` or `controlRequestToolBehaviors`
+next to it has no effect; each dropped value is logged at NOTICE at startup so
+you can see it happen. `proxyTools` is the exception: it is filtered, so a list
+naming `Question` keeps it. An unrecognised preset name applies **nothing** and
+logs a WARN, rather than guessing at what you meant.
+
+**What stops working.** Reads are fine (`Read`, `Grep`, `Glob`, `WebSearch`),
+but anything that would raise a permission prompt is denied, and that includes
+bridged MCP tools and the `question` proxy. Claude's own `AskUserQuestion`
+still renders its stop-and-wait markdown, so the model can still ask you
+things. If you need one specific tool allowed, do not use the preset: set the
+underlying options yourself.
+
+**On an older CLI** the preset still holds through `--disallowedTools` plus the
+plugin's own denial of every permission request, and it warns naming what is
+missing. Below 2.1.258 you lose the cwd confinement on reads; below 2.1.263 the
+denial happens in the plugin rather than in the CLI, one layer instead of two.
+
+Measured end to end on CLI 2.1.280 and `claude-haiku-4-5`: a turn under the
+preset asked to write a file and run a command did neither, the file was never
+created, and the CLI's own `permission_denials` recorded the single blocked
+`Write` with no Bash attempt at all, because there was no Bash tool to attempt
+with.
+
+---
+
 ## Plan mode
 
 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.

package/dist/index.d.ts

@@ -376,7 +376,15 @@ interface ClaudeCodeConfig {
     accountFailover?: AccountFailoverMode;
     providerID?: string;
     skipPermissions?: boolean;
-    permissionMode?: PermissionMode;
+    /**
+     * Widened past `PermissionMode` because a resolved `permissionPreset` puts
+     * its own internal token here (`READ_ONLY_PERMISSION_MODE`), which
+     * `buildCliArgs` translates to CLI flags. The operator-facing option on
+     * `ClaudeCodeProviderSettings` stays a plain `PermissionMode`.
+     */
+    permissionMode?: EffectivePermissionMode;
+    /** The preset this config was resolved from, for diagnostics. */
+    permissionPreset?: PermissionPreset;
     mcpConfig?: string | string[];
     strictMcpConfig?: boolean;
     bridgeOpencodeMcp?: boolean;
@@ -492,6 +500,23 @@ interface ClaudeCodeProviderSettings {
     defaultSubagentModel?: string;
     skipPermissions?: boolean;
     permissionMode?: PermissionMode;
+    /**
+     * Apply a named permission preset instead of hand-combining
+     * `permissionMode`, `skipPermissions`, `proxyTools`,
+     * `extraDisallowedTools` and `controlRequestBehavior`.
+     *
+     * `"read-only"` makes the turn unable to change anything: no
+     * `--dangerously-skip-permissions` (the CLI refuses bypass under
+     * `--restricted` outright), `--restricted` so the CLI has no Bash, REPL or
+     * WebFetch at all, the mutating built-ins on `--disallowedTools` for CLIs
+     * too old for that flag, the write and command tools removed from the
+     * opencode proxy, and every remaining permission request denied.
+     *
+     * A preset overrides those five options rather than merging with them, so
+     * one setting decides the posture; the plugin warns about each value it
+     * drops. Unset (the default) changes nothing.
+     */
+    permissionPreset?: PermissionPreset;
     mcpConfig?: string | string[];
     strictMcpConfig?: boolean;
     /**
@@ -806,6 +831,25 @@ interface ClaudeCodeProviderSettings {
     logging?: LoggingConfig;
 }
 type PermissionMode = "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
+/**
+ * A named bundle of permission settings, so a safety posture is one option
+ * instead of a hand-rolled combination of `permissionMode`, `skipPermissions`,
+ * `proxyTools`, `extraDisallowedTools` and `controlRequestBehavior`. Opt-in:
+ * unset means today's behaviour, unchanged.
+ *
+ * `read-only` is the only preset so far. See `src/permission-presets.ts` for
+ * what it resolves to and why each part is needed.
+ */
+type PermissionPreset = "read-only";
+/**
+ * The `permissionMode` a resolved preset puts on `ClaudeCodeConfig`.
+ * Plugin-internal, never a value the operator sets: `buildCliArgs` translates
+ * `"read-only"` into `--restricted` (plus `--permission-prompts none` where
+ * the CLI has it) rather than passing it to `--permission-mode`, which would
+ * reject it.
+ */
+declare const READ_ONLY_PERMISSION_MODE = "read-only";
+type EffectivePermissionMode = PermissionMode | typeof READ_ONLY_PERMISSION_MODE;
 type ControlRequestBehavior = "allow" | "deny";
 /**
  * Claude CLI stream-json message types.
@@ -937,6 +981,61 @@ interface ClaudeStreamMessage {
     index?: number;
 }
 
+/**
+ * Named permission presets: one option that decides a safety posture, instead
+ * of the operator hand-combining `permissionMode`, `skipPermissions`,
+ * `proxyTools`, `extraDisallowedTools` and `controlRequestBehavior` and
+ * getting one of them wrong.
+ *
+ * Opt-in. No preset resolves to exactly today's behaviour, byte for byte.
+ *
+ * ## Why `read-only` is not just a CLI flag
+ *
+ * Claude Code 2.1.248 added `--restricted`, which removes the built-in tools
+ * that run commands or code plus WebFetch, confines the file tools to the
+ * working directories, and refuses bypassPermissions. That covers the CLI's
+ * own tools and nothing else, and this plugin's whole point is that it puts a
+ * second execution path next to them: `proxyTools` defaults to `Bash`, `Edit`,
+ * `Write`, `WebFetch` and `Task`, each an MCP tool the CLI calls and opencode
+ * executes. `--restricted` never sees those. So the preset has to work at
+ * three layers at once:
+ *
+ *   1. the CLI's own tools (`--restricted`, plus `--disallowedTools` for the
+ *      same names so a CLI too old for `--restricted` still refuses them),
+ *   2. the opencode proxy (the mutating defs are dropped before the proxy
+ *      server is built, so they are never offered),
+ *   3. everything left that would prompt (denied, because a bridged MCP
+ *      server or a file tool reaching outside the cwd is neither of the
+ *      above).
+ *
+ * ## Measured, on the CLI this was written against (2.1.280)
+ *
+ * `--restricted --dangerously-skip-permissions` is a hard startup error,
+ * `Error: bypassPermissions not supported in restricted mode`, so dropping
+ * the skip flag is a correctness requirement and not hygiene. In the binary,
+ * `restrictedMode` is a `bypassImmune` circuit breaker, which is the same
+ * fact from the other side. A `--restricted` run asked to write a file and
+ * run a command reported one `permission_denials` entry (`Write`) and no Bash
+ * attempt at all: the shell tool was not in the set to begin with.
+ */
+
+/** The options a preset decides, resolved. */
+interface ResolvedPermissionPreset {
+    preset: PermissionPreset;
+    permissionMode: EffectivePermissionMode;
+    skipPermissions: boolean;
+    proxyTools: string[];
+    extraDisallowedTools: string[];
+    controlRequestBehavior: ControlRequestBehavior;
+    /** Always undefined under a preset: see `overridden` below. */
+    controlRequestToolBehaviors: undefined;
+    /**
+     * Operator-set values the preset replaced, as `option: reason` lines, so
+     * the caller can warn once per option rather than silently winning.
+     */
+    overridden: string[];
+}
+
 interface DiagnosticsProviderEntry {
     name?: string;
     options?: Record<string, unknown>;
@@ -1139,6 +1238,19 @@ declare function registerSideQuestionCommand(config: OpenCodeConfig): boolean;
 declare function registerDoctorCommand(config: OpenCodeConfig): boolean;
 declare function _resetPlanModeWarningForTests(): void;
 declare function warnIfPlanModeCannotExit(permissionMode: string | undefined): void;
+/**
+ * Resolve `permissionPreset` for this provider, reporting what it replaced.
+ *
+ * The result is applied over the operator's settings by `createClaudeCode`,
+ * which is the one funnel both opencode majors reach the language model
+ * through, so a preset needs wiring in exactly one place.
+ *
+ * Every override is logged at NOTICE, and an unrecognised preset name is a
+ * WARN plus no preset at all. A safety option must never be approximated: a
+ * typo'd `"readonly"` silently running at full permissions is worse than one
+ * that says so.
+ */
+declare function applyPermissionPreset(settings: ClaudeCodeProviderSettings, defaultProxyTools: readonly string[]): ResolvedPermissionPreset | null;
 declare function createClaudeCode(settings?: ClaudeCodeProviderSettings): ClaudeCodeProvider;
 /**
  * Build models in OpenCode's config schema format (flat properties like
@@ -1178,4 +1290,4 @@ declare const _default: {
     setup: (ctx: V2Context) => Promise<V2Cleanup>;
 };
 
-export { type AgentRecord, type ClaudeCodeConfig, ClaudeCodeLanguageModel, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeStreamMessage, DEFAULT_PROXY_TOOL_NAMES, type OpenCodeHooks, type OpenCodeModel, type OpenCodePlugin, _resetPlanModeWarningForTests, bridgeOpencodeMcp, buildAgentRegistry, claudeCodeProviders, configModelsForProvider, createClaudeCode, _default as default, defaultModels, extractDeletedSessionId, getAgentRegistry, getDefaultSubagentModel, registerDoctorCommand, registerSideQuestionCommand, resolveAgentModel, warnIfPlanModeCannotExit };
+export { type AgentRecord, type ClaudeCodeConfig, ClaudeCodeLanguageModel, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeStreamMessage, DEFAULT_PROXY_TOOL_NAMES, type OpenCodeHooks, type OpenCodeModel, type OpenCodePlugin, _resetPlanModeWarningForTests, applyPermissionPreset, bridgeOpencodeMcp, buildAgentRegistry, claudeCodeProviders, configModelsForProvider, createClaudeCode, _default as default, defaultModels, extractDeletedSessionId, getAgentRegistry, getDefaultSubagentModel, registerDoctorCommand, registerSideQuestionCommand, resolveAgentModel, warnIfPlanModeCannotExit };