@khalilgharbaoui/opencode-claude-code-plugin 0.20.0 → 0.22.0

package/README.md

@@ -297,7 +297,9 @@ model: claude-code-work/claude-opus-5@work
 | `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`. |
 | `hotReloadMcp` | boolean | `true` | With MCP bridging on, compare the merged MCP config and runtime status at the start of each turn and respawn the `claude` process when they drifted, so a server you just enabled or disabled becomes visible without restarting opencode or opening a new chat. Eviction waits for pending proxy calls, never happening mid tool-call, and the session id is preserved for `--resume`. Set `false` to keep a cached subprocess until the chat is reset. It does not reload other provider options and does not watch the contents of files named in `mcpConfig`. |
-| `proxyOpencodeMcpTools` | boolean | `true` | Route the MCP tools discovered from opencode through the in-process `opencode_proxy` server instead of bridging them straight into Claude's `--mcp-config`. With both layers pointed at the same server, direct bridging executes every call twice, once in Claude's own MCP child process and once in opencode; proxying keeps opencode as the single execution site while preserving its permission prompts and tool rows. Falls back to direct bridging when discovery is unavailable, so do not treat it as an exactly-once guarantee for write-capable tools. |
+| `proxyOpencodeMcpTools` | boolean | `false` | Route opencode's MCP-backed tools through the in-process `opencode_proxy` server instead of bridging them straight into Claude's `--mcp-config`, so each call executes once, inside opencode, with its permission prompt and its tool row. **The default changed from `true` to `false` in this release, and no behaviour changed with it:** at `true` it used to route nothing at all, because discovery read opencode's tool registry, which contains built-ins and plugin-declared tools and has never contained an MCP tool. Discovery now reads the model tool set opencode passes the provider, which is where MCP tools actually are, so the option works, and turning it on is the operator's decision rather than a silent migration of traffic that the direct bridge is handling today. Two caveats before enabling it: pair it with `strictMcpConfig: true`, because a server also registered in Claude Code's own config is reached directly and bypasses the proxy entirely; and a routed call runs in opencode with the calling agent's permissions, the same trade [`proxyOpencodeTools`](#options-reference) makes. Servers whose tools are not found stay on the direct bridge, and a warning says so, so do not treat this as an exactly-once guarantee for write-capable tools. |
+| `proxyOpencodeTools` | string[] | `[]` | Forward named opencode tools through the proxy by their registry id, for tools another opencode plugin declares directly and that therefore belong to no MCP server (opencode-dcp's `compress`). Explicit allowlist; a forwarded tool runs inside opencode with the calling agent's permissions. A name already held by a proxy def is dropped with a warning rather than taking it over. See [Forwarding opencode's own tools](#forwarding-opencode-s-own-tools). |
+| `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. |
@@ -490,7 +492,7 @@ It is the one proxy tool opencode never sees. The call is answered inside the pl
 
 Without it, the appended system prompt tells the model that `compress` is unavailable and to ignore instructions that ask for it, which is the right answer when nothing implements it.
 
-The store, the interceptor and the two prompt variants are covered by tests, but the full "model calls compress, the next turn really is a fresh process carrying only the summary" round-trip has not been verified against a live CLI. Treat it as working-but-unproven and check the plugin log the first time you rely on it.
+The round trip is verified live (Claude Code 2.1.263, opencode 1.18.31, haiku): the model called `mcp__opencode_proxy__compress` with a build identifier in its summary, the plugin logged `compress stored summary; session resets next turn`, the next turn logged `compress reset: dropped claude process and session id` and spawned a second `claude`, and that fresh process answered with the identifier it could only have read from the summary in its system prompt.
 
 Only those seven 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. The `"Question"` proxy is version-gated on opencode's built-in `question` tool: on builds that lack the registry entry the def is silently dropped (a forwarded call would otherwise render as `⚙ invalid`), so add it only on opencode versions that ship the `question` tool.
 
@@ -500,6 +502,45 @@ Without `"Task"` in `proxyTools`, Claude's built-in `Agent` tool stays enabled a
 "options": { "proxyTools": [] }
 ```
 
+### Forwarding opencode's own tools
+
+`proxyTools` names the tools this plugin ships defs for, and MCP-backed opencode tools can be routed with [`proxyOpencodeMcpTools`](#options-reference). Neither covers a tool that **another opencode plugin declares directly**: it belongs to no MCP server, so the automatic match (`<server>` or `<server>_<tool>`) skips it and the model is never offered it. opencode-dcp's `compress` is the case that matters in practice, because DCP then injects "MAX CONTEXT LIMIT REACHED ... You MUST use the `compress` tool now" reminders that the model has no way to act on.
+
+`proxyOpencodeTools` is the explicit allowlist. Empty by default:
+
+```json
+"options": {
+  "proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"],
+  "proxyOpencodeTools": ["compress"]
+}
+```
+
+Names are opencode's tool ids as `client.tool.list()` reports them, matched case-insensitively. An unknown name is skipped with a warning rather than failing the spawn. Forwarded tools use the same broker as every other proxy tool, so [how a proxied call ends](#how-a-proxied-call-ends) applies to them unchanged: abort, orphan sweep, session deletion and child exit all release them.
+
+This is deliberately not automatic. A forwarded tool executes inside opencode with the calling agent's permissions, so which ones cross over is your decision, not the plugin's.
+
+**The `compress` name collision.** Two different tools want it: DCP's, which rewrites opencode's transcript, and [this plugin's](#context-compression), which resets the Claude Code session. They compress different windows, and after a DCP compress the live `claude` process still holds its full context until something restarts it. If you enable both, the plugin's own tool keeps the name and the forwarded one is dropped with a warning in the log:
+
+```
+WARN: proxyOpencodeTools entry dropped: a proxy tool already holds that name, and it keeps it {"collided":["compress"]}
+```
+
+Pick one. The appended system prompt describes whichever is actually reachable, so the model is told the right semantics either way.
+
+Verified live on Claude Code 2.1.263 and opencode 1.18.31 with DCP loaded: the plugin logged `forwarding opencode tools through the proxy {"tools":["compress"]}`, started the proxy with `tools: ["bash","compress"]`, received `proxy-mcp tool call received {"toolName":"compress"}`, queued it through the normal broker, and DCP really ran, returning `Compressed 3 messages into [Compressed conversation section]`. One wrinkle worth knowing: DCP's compress rewrites opencode's message history mid-turn, which makes opencode abort the provider stream at that tool boundary. The pending call is released normally and the result still reaches the model on the next step as text, so the turn completes, but you will see one `abort between proxy tool boundaries` line in the log each time.
+
+### Trimming unsatisfiable context reminders
+
+DCP anchors its nudges into message text as `<dcp-system-reminder>` blocks, so each one is re-sent with every message that carries it. If no `compress` tool is reachable they are an order the model cannot follow, and the plugin already tells it to ignore them. `stripContextReminders: true` stops paying for them too:
+
+```json
+"options": { "stripContextReminders": true }
+```
+
+Off by default. It removes those blocks from user and assistant text before the transcript reaches the CLI, including the fresh-session rebuild, where every anchored reminder would otherwise replay at once. It leaves opencode's own `<system-reminder>` blocks alone: those are opencode's instructions to the model, not an unsatisfiable order.
+
+It switches itself off whenever `compress` is named in `proxyTools` or `proxyOpencodeTools`, since the reminder is then something the model can act on. The check is on configuration, so a name that is configured but missing from opencode's registry still counts as reachable and nothing is stripped, which errs toward keeping the reminder.
+
 ### Subagent todos
 
 When Claude works through a multi-step task it emits `TaskCreate` / `TaskUpdate` calls. The plugin translates those into opencode's full-list `todowrite` so the todo panel populates. Inside a **subagent** that translation is blocked unless you say otherwise: opencode's task tool injects `todowrite: false` into the tools dict for any subagent without an explicit rule, so the plugin's synthetic emissions surface as `⚙ invalid todowrite` rows instead of todos. The built-in `general` subagent denies it by default.
@@ -568,6 +609,8 @@ A proxied call ends when something happens to it, not when a clock runs out. The
 
 Because every ending is observed rather than inferred from elapsed time, a `task` can run until it is finished: **`task` and `task_batch` have no deadline by default**. Earlier flat ceilings fired mid-subagent, Claude believed its dispatch had failed, and the eventual result was dropped because the parent turn had already ended on the timeout error; a 60-minute one did the same to anything longer. What the default gives up is only that nothing fires on the clock alone, so a chat parked in a `task` holds its `claude` worker until one of the events above happens. That is the operator's decision to make, so no timer makes it for them.
 
+So that a call with no deadline is never silent, the plugin says it is still waiting. Five minutes in, and every five minutes after, a call without a deadline logs a warning naming the tool, the call id, how long it has waited, and what will end it. It never ends the call, it only reports one, which is the whole point: the thing a deadline used to provide was visibility, not correctness, and visibility is what is kept. Calls that do have a deadline get one notice rather than a heartbeat, at 60% of the way to it, saying how long is left and which option would extend it. Before this, a deadline reported a call only by killing it: the first thing you heard was the failure, which is no use while there is still time to react. It is one line, never repeated, because the deadline itself is the next thing that will speak, and deadlines under a minute are skipped entirely since the notice and the rejection would arrive together. The line reaches your terminal (warnings always go to stderr), so a subagent that has genuinely wedged shows up on its own instead of waiting to be noticed. `/claude-code-doctor` lists the same calls on demand.
+
 The same events are also what let a legitimately long call complete, which is the second half of the story: the CLI's own HTTP client used to give up on a silent reply at about five minutes whatever the tool deadline said. Every held call therefore keeps its connection visibly alive. A client that advertises SSE gets immediate headers and a keepalive comment every 15 seconds (since 0.15.0); a client that only accepts JSON gets its headers immediately as well, as a chunked body carrying keepalive whitespace on the same cadence, which is still one valid JSON-RPC response when the result lands, on success and on error. Keepalives are about the connection, not the tool: they never extend or replace a deadline. Claude's MCP client timeout for the proxy server, written into the generated `--mcp-config`, is set to the largest effective deadline, and to the largest value the CLI accepts (Node's timer maximum, about 24.8 days) while any tool has no deadline, because the CLI rejects a `timeout` of `0` outright.
 
 ### Per-tool proxy timeouts
@@ -1053,10 +1096,17 @@ Partial support since v0.5.1. DCP runs in a useful degraded mode: its automatic
 | `experimental.chat.system.transform` (context-limit nudges, iteration reminders) | ✅ Works in headless | Headless spawns forward system-role content via `--append-system-prompt-file`. Interactive mode intentionally omits opencode's forwarded system prompt and keeps only this plugin's CLI/AGENTS/continuation prompt. |
 | `/dcp compress`, `/dcp sweep`, `/dcp manual`, `/dcp context`, `/dcp stats` slash commands | ✅ Works | Handled by opencode's `command.execute.before` hook, not the model. |
 | Automatic `deduplication` + `purgeErrors` strategies | ✅ Works | Message-transform only, no model tool calls. |
-| DCP's own autonomous `compress` / `distill` / `prune` tool calls | ❌ Not supported | DCP registers those as opencode-native tools. Claude CLI only ever sees its own built-ins and MCP-bridged servers, so the model never sees them. |
+| DCP's own autonomous `compress` / `distill` / `prune` tool calls | ⚠️ Opt-in | DCP registers those as opencode-native tools rather than through an MCP server, so the automatic MCP routing never saw them. Name one in [`proxyOpencodeTools`](#forwarding-opencode-s-own-tools) and it is forwarded: `proxyOpencodeTools: ["compress"]` makes `mcp__opencode_proxy__compress` run DCP's real tool. |
 | Model-driven compression through this plugin's `compress` proxy | ⚠️ Opt-in | Add `"Compress"` to `proxyTools` and the plugin exposes `mcp__opencode_proxy__compress`, which gives the model a working way to compress its own context. It is not DCP's tool and does not use DCP's strategies. See [Context compression](#context-compression). |
+| DCP's `<dcp-system-reminder>` context-limit nudges when no compress tool is reachable | ⚠️ Opt-in strip | Those reminders are anchored into messages, so each one is re-sent with every message that carries it. If you run without either compress route, `stripContextReminders: true` removes them. It turns itself off as soon as a `compress` tool is proxied. |
+
+So autonomous compression is available, and DCP's own implementation is now one of the options. Three routes, all opt-in:
+
+- `proxyOpencodeTools: ["compress"]` forwards **DCP's** tool, which compresses opencode's transcript using DCP's strategies.
+- `proxyTools: [..., "Compress"]` exposes **this plugin's** tool, which resets the Claude Code session and carries a summary into the fresh one.
+- Neither, and trigger DCP by hand with `/dcp compress`.
 
-So autonomous compression is available, just not DCP's implementation of it. Two routes: add `"Compress"` to `proxyTools` so the model can compress its own context through this plugin, or leave it off and trigger DCP manually with `/dcp compress` whenever you would have wanted the model to call it. With `"Compress"` absent, the plugin's appended system prompt tells Claude that no such tool exists and to ignore instructions asking for it, which is the correct answer in that case.
+The two compress different windows, so pick deliberately rather than enabling both; [Forwarding opencode's own tools](#forwarding-opencode-s-own-tools) explains what happens if you do. With neither enabled, the plugin's appended system prompt tells Claude that no such tool exists and to ignore instructions asking for it, which is the correct answer in that case.
 
 ---
 
@@ -1065,7 +1115,7 @@ So autonomous compression is available, just not DCP's implementation of it. Two
 - Tool inputs stream as they are constructed (Anthropic's `input_json_delta` is forwarded as `tool-input-delta`), but only for tool calls opencode actually sees. Calls the plugin deliberately does not forward, meaning proxy tools, CLI-internal `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, the todo-ledger `Task*` family and Claude's other internal tools, have their deltas suppressed, because a delta for a tool opencode never saw start renders as a permanently pending `⚙ unknown` row.
 - 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 no proxy deadline by default.** The plugin listens for the events that end a call instead of timing it (see [How a proxied call ends](#how-a-proxied-call-ends)), so a subagent runs to completion and a chat parked in one holds its `claude` worker until you abort, send another message, delete the chat, or the process goes away. Add a wall-clock backstop via [`proxyToolTimeoutMs`](#per-tool-proxy-timeouts) if you want one. For independent work that should not block the turn at all, use `background: true` after enabling opencode's experimental background-subagent flag.
+- **Foreground Task calls have no proxy deadline by default.** The plugin listens for the events that end a call instead of timing it (see [How a proxied call ends](#how-a-proxied-call-ends)), so a subagent runs to completion and a chat parked in one holds its `claude` worker until you abort, send another message, delete the chat, or the process goes away. Such a call warns that it is still waiting after five minutes and every five minutes after, so it is never silent. Add a wall-clock backstop via [`proxyToolTimeoutMs`](#per-tool-proxy-timeouts) if you want one. For independent work that should not block the turn at all, use `background: true` after enabling opencode's experimental background-subagent flag.
 - **Subagent todos require explicit permission.** See [Subagent todos](#subagent-todos) for the rule and a working config.
 
 ---

package/dist/index.d.ts

@@ -181,6 +181,8 @@ interface ClaudeCodeConfig {
     controlRequestToolBehaviors?: Record<string, ControlRequestBehavior>;
     controlRequestDenyMessage?: string;
     proxyTools?: string[];
+    proxyOpencodeTools?: string[];
+    stripContextReminders?: boolean;
     extraDisallowedTools?: string[];
     proxyToolTimeoutMs?: Record<string, number>;
     /**
@@ -316,6 +318,45 @@ interface ClaudeCodeProviderSettings {
       * entry, in which case the deny/markdown fallback applies.
       */
     proxyTools?: string[];
+    /**
+     * opencode tools to forward through the proxy by name, on top of the
+     * built-in `proxyTools` defs. Empty by default.
+     *
+     * MCP-backed opencode tools are already routed automatically (see
+     * `proxyOpencodeMcpTools`), but that match is `<server>` or
+     * `<server>_<tool>`, so a tool another opencode plugin declares directly
+     * belongs to no server and is never offered to Claude. opencode-dcp's
+     * `compress` is the motivating case: dcp injects "MAX CONTEXT LIMIT
+     * REACHED ... You MUST use the `compress` tool now" reminders that the
+     * model could not act on, because the tool was never in its list.
+     *
+     * Names are opencode's tool ids as `client.tool.list()` reports them
+     * (matched case-insensitively): `["compress"]`. An unknown name is
+     * skipped with a warning. This is an explicit allowlist and never
+     * automatic: a forwarded tool executes inside opencode with the calling
+     * agent's permissions.
+     *
+     * A name already held by a proxy def is NOT taken over. Listing
+     * `"compress"` here while `proxyTools` also contains `"Compress"` leaves
+     * the plugin's own in-process compress in charge and drops the forwarded
+     * one with a warning, because the two do different things: the plugin's
+     * resets the Claude Code session, opencode's compresses opencode's
+     * transcript. Pick one.
+     */
+    proxyOpencodeTools?: string[];
+    /**
+     * Remove `<dcp-system-reminder>` blocks from message text when no
+     * `compress` tool is being proxied. Off by default.
+     *
+     * opencode-dcp anchors those reminders into messages, so they are re-sent
+     * with every message that carries one. When compress is not reachable
+     * they are an instruction the model cannot follow, and the plugin already
+     * tells it to ignore them in the appended system prompt. Turning this on
+     * stops paying for them as well. It is inert whenever `compress` is
+     * proxied (via either `proxyTools` or `proxyOpencodeTools`), since the
+     * reminder is then something the model can actually act on.
+     */
+    stripContextReminders?: boolean;
     /**
      * Extra Claude Code built-ins to switch off with `--disallowedTools`,
      * on top of the ones implied by `proxyTools`.
@@ -446,16 +487,28 @@ interface ClaudeCodeProviderSettings {
     /**
      * Route opencode MCP server tools through the in-process `opencode_proxy`
      * MCP server instead of bridging them directly into Claude CLI's
-     * `--mcp-config`. With both layers configured for the same MCP server,
-     * direct bridging causes each tool invocation to execute twice — once by
-     * Claude CLI's own MCP child process and once by opencode. Routing through
-     * the proxy keeps a single execution site (opencode) while preserving the
-     * tool-call/result surface in opencode's UI and its permission prompts.
+     * `--mcp-config`. Routing through the proxy keeps a single execution site
+     * (opencode), so the call is permission-prompted and rendered as an
+     * opencode tool call instead of running inside Claude CLI's own MCP child.
+     *
+     * Defaults to `false`, and that is a change of default rather than of
+     * behaviour. It used to default to `true` while routing nothing at all:
+     * discovery read `client.tool.list()`, which enumerates opencode's tool
+     * registry (built-ins plus plugin-declared tools) and has never contained
+     * an MCP tool, so no def was ever built. Discovery now reads the model tool
+     * set opencode passes the provider, which is where MCP tools actually live,
+     * so the option works. Leaving it on by default would then have silently
+     * moved every existing user's MCP traffic off the direct bridge that is
+     * carrying it today, so switching over is the operator's call.
      *
-     * Defaults to `true`. Set to `false` to restore the prior direct-bridge
-     * behavior (Claude CLI executes MCP tools itself; opencode also re-executes
-     * — accept the duplication if you need Claude to invoke the tool without
-     * an opencode round-trip).
+     * Two things to know before enabling it:
+     *
+     * - It only affects the servers this plugin bridges. If the same server is
+     *   also registered in Claude Code's own config, Claude reaches it directly
+     *   and the proxy is bypassed. Pair this with `strictMcpConfig: true` so
+     *   Claude sees only the config this plugin writes.
+     * - A routed call executes inside opencode with the calling agent's
+     *   permissions, the same trade `proxyOpencodeTools` makes.
      */
     proxyOpencodeMcpTools?: boolean;
     /**
@@ -652,13 +705,24 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     /** Resolve ProxyToolDef[] for the configured proxyTools names. */
     private resolvedProxyTools;
     /**
-     * Resolve ProxyToolDef[] for opencode's MCP-bridged tools so they go
+     * Resolve ProxyToolDef[] for opencode's MCP-backed tools so they go
      * through the in-process proxy instead of being bridged into Claude CLI's
-     * `--mcp-config`. Direct bridging causes double execution because both
-     * Claude CLI's own MCP child and opencode hold their own connection to
-     * the same server; routing through the proxy keeps a single execution
-     * site (opencode). Returns null when the feature is disabled, the SDK
-     * client is unavailable, or no MCP servers are configured.
+     * `--mcp-config`. Routing through the proxy keeps a single execution site
+     * (opencode), so the call is permission-prompted and rendered as an
+     * opencode tool call.
+     *
+     * Opt-in (`proxyOpencodeMcpTools: true`) and off by default. It used to
+     * default to true while finding nothing, because it discovered tools via
+     * `client.tool.list()`, which enumerates opencode's `ToolRegistry` and not
+     * the MCP tools merged into the model's tool set afterwards. Discovery now
+     * reads that merged set, the `tools` array opencode passes `doStream`, so
+     * the option does what it says. Turning it on by default at the same time
+     * would have silently moved every existing user's MCP traffic off the
+     * working direct bridge, so the default went to false instead: today's
+     * behaviour is preserved exactly and crossing over is the operator's call.
+     *
+     * Returns null when the feature is off or nothing matched, which leaves
+     * every server on the direct bridge.
      */
     private resolvedProxyMcpTools;
     /**
@@ -680,6 +744,12 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * answered": only the former is a real version-gate signal.
      */
     private fetchLiveToolInfo;
+    /**
+     * Whether dcp-style context reminders should be stripped from this turn's
+     * messages. Config-only and synchronous, so it can be answered before the
+     * spawn block resolves anything: `userMsg` is built well ahead of it.
+     */
+    private stripContextRemindersEnabled;
     /** Share one lazy registry request within a turn without making it stale. */
     private createLiveToolInfoLoader;
     /**