Skip to content

Selective tool proxy

Choose, per tool, whether Claude Code or opencode executes it.

This is the core feature.

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

proxyTools value Claude built-ins disabled Proxy MCP tool exposed
"Bash" Bash mcp__opencode_proxy__bash
"Edit" Edit, MultiEdit mcp__opencode_proxy__edit
"Write" Write mcp__opencode_proxy__write
"WebFetch" WebFetch mcp__opencode_proxy__webfetch
"Task" Agent mcp__opencode_proxy__task, mcp__opencode_proxy__task_batch, and on a host that runs background subagents mcp__opencode_proxy__task_status, mcp__opencode_proxy__task_cancel
"Question" AskUserQuestion mcp__opencode_proxy__question
"Compress" none mcp__opencode_proxy__compress

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.
  • Per-call model (opencode 2): task and each task_batch.tasks item take an optional model, opencode’s exact providerID/modelID reference with an optional #variant, such as claude-code/claude-sonnet-5-5#high. Claude is told to set it only when you asked for a model and never to guess an id, but a model named in words can still be guessed wrong first, so name the model by its id or full reference. A model id on its own (claude-sonnet-5-5, claude-sonnet-5-5#high) is completed to this conversation’s own provider and account, and any other value is left as written. The plugin then forwards it to opencode’s own subagent tool, beside any task_id and background, and opencode resolves it against the models it has. Leave it out and opencode picks the model as usual. It beats an agent’s forceModel, defaultSubagentModel and, with a variant, reasoningEffort; a task that names one is left out of the dispatch form; and one on another accountGroups group’s account is refused before any task starts. See A model you name in the conversation. opencode 1’s task tool has no such field, so the plugin reads opencode’s own schema, leaves model out there, and refuses one set anyway before any task starts. Contributed by @taylormitchell (PR #123).
  • 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: see Background subagents below. Foreground is the default.
  • Several at once: mcp__opencode_proxy__task_batch takes a tasks array of ordinary task inputs and runs them concurrently. It exists because Claude Code sends MCP requests one at a time: when the model emits two task calls in one response, the second only leaves the CLI after the first has returned (measured live, 2026-09-06), so “launch two subagents” was always serial. The plugin turns one task_batch call into N opencode task calls inside a single tool boundary, which opencode executes in parallel, then hands the model every result together, labelled in task order. Same permissions, same no-deadline default, same subagent_type list. Enabled whenever Task is proxied. Designed and first implemented by @broskees on his fork.

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.

Two neighbours of this section live elsewhere now: dispatching a subagent without blocking the conversation is Background subagents, and the proxy’s own HTTP endpoint and the files it writes are Scratch files and security.

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:

"options": {
"extraDisallowedTools": ["NotebookEdit"]
}

These go straight to claude --disallowedTools, so use Claude’s tool names rather than opencode’s. There is no replacement: the capability goes away rather than being routed through opencode, which is the point, but the model then has to work without it.

Unknown entries in proxyTools are logged as a warning at spawn rather than passing silently, so a typo shows up as “ignoring unknown proxyTools entries” in the plugin log instead of quietly leaving the matching built-in unmediated.

Context compression

"Compress" is off by default. Add it when you run a harness that expects the model to manage its own context (opencode-dcp injects exactly those instructions), and the plugin exposes mcp__opencode_proxy__compress:

"options": {
"proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task", "Compress"]
}

It is the one proxy tool opencode never sees. The call is answered inside the plugin: the model passes a summary, the plugin stores it, and the turn continues normally. At the start of the next turn the Claude Code session is discarded and a fresh claude starts with that summary prepended to its system prompt, and nothing else. The earlier conversation is not replayed, so a thin summary means real lost context. The reset waits if the incoming turn is carrying tool results for the running process.

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 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. Re-run unchanged on Claude Code 2.1.288 and opencode 1.18.35 (2026-10-07), with the summary confirmed at the top of the new spawn’s appended system prompt under ## Summary of earlier work (context was compressed).

Only those seven values are actually proxied; anything else you put in proxyTools is ignored. Proxying Edit also disables MultiEdit, because 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.

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:

"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. 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:

"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 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, 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:

"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.

What you get with proxying on

  • opencode’s permission prompts for every Bash/Edit/Write/WebFetch call. The default --dangerously-skip-permissions is still passed to claude, but it only governs Claude’s own built-in tools; a proxied call is executed by opencode and answers to opencode’s rules instead. Built-ins that are neither proxied nor listed in extraDisallowedTools do run under that flag.
  • opencode’s audit log captures the calls.
  • Per-tool policy rules in opencode apply.

What you give up

  • A small per-call latency hop through 127.0.0.1:<random>/mcp.

  • One opencode step per proxied call. Claude Code sends the proxied calls of one reply one at a time, each after the previous one has returned, so a reply with five calls is five opencode steps. On opencode 2.2.5 each step cost 0.7 to 1.4 s on top of the tool itself, and no extra tokens. The plugin does not hand the later calls to opencode early, because Claude Code decides each call only when it reaches it: a PreToolUse hook, a permission rule or an interrupt can still refuse it. Also, opencode runs the calls of one step at the same time, so a call that reads what an earlier one wrote could see the old state. For subagents, task_batch runs several at once. Full numbers: docs/agents-history.md under #g288. The one exception is webfetch, which changes nothing and is marked read-only, so one reply’s fetches run together in one step; see Parallel webfetch.

  • 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.

  • One extra Claude Code API call per claude process for a tool that is not always loaded, and it is a ToolSearch. A proxied tool reaches the model as an MCP tool, and Claude Code 2.1.280 defers MCP tools behind its own ToolSearch tool, so before the first proxied call of a session the model spends one request finding the tool. Claude’s built-in Bash is never deferred, so an unproxied tool goes straight to the call. Since this release bash, edit and write are served always loaded and skip it; see Always-loaded proxy tools.

    Measured on 2.1.280 with claude-haiku-4-5, three runs a side, one echo command: 3 CLI API calls with Bash proxied against 2 with the CLI running it, and roughly twice the cache reads. It is paid once per process, not once per call: the same task with two sequential commands measured 4 calls against 3, with a single ToolSearch either way. It is also not a function of how many tools you have, since a run with strictMcpConfig: true and 28 tools still spent it. Setting ENABLE_TOOL_SEARCH=0 does remove it, and costs far more than it saves (all ~164 tool definitions then sit in every prompt, which measured 2.5 to 4 times the total cost and tripped a compaction), so that is not a fix and the plugin does not do it. ToolSearch is one of Claude’s internal tools, so you never see the call, only the cost. Full numbers: docs/agents-history.md under #g166.

Always-loaded proxy tools

The proxy marks bash, edit and write with Claude Code’s _meta["anthropic/alwaysLoad"], so they sit in every request instead of behind ToolSearch, and the first proxied call of a process goes straight to the tool. Measured on Claude Code 2.1.314 with claude-haiku-5-5, three warm runs a side, one proxied echo:

API calls Prompt tokens Cost Time
deferred (before) 3 (ToolSearch, then the call) 75,030 $0.00097 3.9 to 5.2 s
bash, edit, write always loaded 2 50,640 $0.00056 to $0.00059 2.4 to 2.9 s

The price is the three schemas in every request: a turn that called no tool carried 531 more prompt tokens (24,689 against 25,220), read from the prompt cache, which came to the same cost to four decimal places. Loading all eight default proxy tools added 2,818 tokens and saved nothing more, so webfetch, task, task_batch and the background-subagent tools stay deferred. task and task_batch are deferred together, so the dispatch path the subagent hint describes is unchanged.

Change the set with alwaysLoadProxyTools:

"options": { "alwaysLoadProxyTools": ["bash", "edit", "write", "webfetch"] }

true loads every tool the proxy serves, MCP tools routed by proxyOpencodeMcpTools included, which is the shape of the 2.5 to 4 times cost above when there are many; false defers them all, as before this release. A Claude Code that predates the field ignores it.

The proxy does not raise _meta["anthropic/maxResultSizeChars"]. Claude Code saves an MCP result over 100,000 characters to a file and hands the model a preview, which it then reads with its own Read (measured: a 149,618-character result took 3 calls and the answer was right). opencode truncates its own tool output at 2,000 lines or 50 KB before the result reaches the proxy, so the limit is not met in practice, and raising it would put the whole result into the prompt instead.

Parallel webfetch

The proxy serves webfetch with the MCP readOnlyHint annotation. Claude Code reads that as safe to run beside the reply’s other read-only calls, so when Claude fetches several pages in one reply it sends the calls together instead of one after each result. The plugin then waits for the reply to finish streaming, at most 2 seconds, and hands the fetches to opencode as one step, where they run at the same time. Measured on Claude Code 2.1.314 with claude-haiku-5-5 and opencode 2.2.5, three fetches of one second each, three runs a side:

opencode steps First call to the answer API requests
before 4 (one per fetch, then the answer) 5.1 to 5.8 s 3
parallelWebfetch (default) 2 (all three fetches, then the answer) 2.2 to 2.4 s 3

Nothing else changes:

  • A bash, edit or write call is not read-only. Claude Code still runs it alone and in the order Claude wrote it, after the calls before it have returned, and the plugin hands it to opencode without waiting.
  • opencode’s own webfetch permission still decides each fetch. With "webfetch": "ask" you get one prompt per URL, all at once.
  • A PreToolUse hook, a --disallowedTools entry or a settings deny rule on mcp__opencode_proxy__webfetch still stops the call before it reaches opencode.
  • permissionPreset: "read-only" does not serve webfetch at all.
  • Under permissionMode: "plan" Claude can now fetch, as it can with its own WebFetch tool there; before, every proxied fetch was refused in plan mode. Fetching changes no file.

"parallelWebfetch": false serves webfetch without the annotation, which is the behaviour before this release. Full numbers: docs/agents-history.md under #g289.

Background shells (opencode 2)

On opencode 2 the proxied bash tool takes background: true, the field opencode 2’s own shell tool has in every 2.x release. Claude uses it for a dev server or a long build, and the call returns at once with opencode’s answer:

Command moved to the background (shell ID: sh_...).
Output is streaming to: <opencode data dir>/shell/<project>/sh_....out

followed by opencode’s instruction not to poll. Claude can read that file while the command runs. When the command ends, opencode adds its output to the session and starts a turn on it, so Claude reports the result without being asked:

<shell id="sh_..." state="completed" command="sleep 15; echo bg-done">
bg-done
</shell>

Nothing waits in between. The turn that started the command ends as usual, and a proxy deadline covers only the call that started it, which returns in milliseconds. opencode gives a background command no timeout unless the call passes one. The sidebar lists it as a bg row while it runs and shows how it ended.

Measured on opencode 2.2.6 and Claude Code 2.1.322 with claude-haiku-5-5, on both transports: asked to run sleep 15; echo bg-done in the background, Claude set the field, said in one line that the command had started and ended its turn. 15 seconds later the <shell> message arrived and Claude answered with bg-done, on the same claude process. Asked only to start a dev server, Claude chose the background on its own and checked the server with curl.

  • opencode 1.x: its bash tool has no such field, so the plugin does not offer it there.
  • permissionPreset: "read-only" serves no bash at all.
  • Stopping a background shell reaches the session too, and Claude may act on it: on opencode 2.2.6 a shell stopped through opencode’s HTTP API arrives as state="error" with Shell.NotFoundError, and Claude Haiku 5.5 read that as a crash and started the server again. Tell Claude when you stop one on purpose.

Per-tool proxy timeouts

Read How a proxied call ends first: a deadline is a backstop on top of the events that actually end a call, not the thing that decides it.

Deadlines still exist, as an explicit backstop rather than the mechanism that decides when a call is over. If a tool with one has not been resolved within that many milliseconds, the call is rejected and Claude receives a timeout error.

A deadline does not count time opencode is still spending on the call. When it passes, the plugin asks opencode whether the session is still busy. If it is (a permission prompt waiting for your answer, or the tool itself still running), the call keeps waiting and is checked again every minute. The deadline only applies once opencode is idle, or when opencode cannot be asked. Before this, answering a permission prompt after ten minutes meant Claude had already been told the command timed out. Your late approval then cancelled Claude’s next action, which it reported as you rejecting it. Resolved per tool, most-specific layer winning:

  1. flat default, 10 min (matches Claude CLI’s own Bash ceiling)
  2. per-tool default: task / task_batch: none, question: 30 min, everything else: 10 min
  3. your proxyToolTimeoutMs override (case-insensitive key; a positive value replaces the default, 0 removes the deadline, anything else is ignored)
  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)), and a positive input.timeout restores a deadline that bash: 0 removed

question keeps 30 minutes because it blocks on a human reading a form, and a form nobody answers is not an event. A positive task override restores a wall-clock backstop for operators who want one; if it fires, 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.

Two watchdogs are a different thing again and are unchanged: the start watchdog (90 s of complete silence after a turn is written, 150 s for a new process still waiting on its MCP servers, respawn then error, see CLAUDE_CODE_START_WATCHDOG_MS) and the wire-inactivity watchdog (90 s of silence after content, see CLAUDE_CODE_RESULT_FALLBACK_MS; when it fires the reply gets a ▌ **stream timeout:** note so the turn does not just stop, and the CLI’s turn is interrupted so it does not run on with nobody listening; a fire that comes well past its deadline because the machine slept waits a fresh 90 s instead). Those exist because a process that is alive but wedged emits no event to listen to, and a proxy call is never what they are waiting on: a CLI parked inside a proxied tool is producing nothing on purpose, and both watchdogs know that.

If Claude nevertheless abandons the HTTP call, the plugin preserves narration emitted while opencode was running the tool, renders it on return, and delivers the late completion as a plain-text continuation naming the original call. It tells Claude not to run the tool again. A silent post-tool continuation gets one resumed-process retry, preserving the original model, account, effort, and proxy configuration; a second failure ends with an error rather than an indefinite hang. Buffered narration is capped at 500 lines and 2 MiB, with a warning if output was dropped.

"options": {
"proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"],
"proxyToolTimeoutMs": { "Task": 5400000, "bash": 1800000 }
}

WebSearch routing

Claude Code ships a built-in WebSearch tool. The webSearch option controls who actually executes those calls:

webSearch value Behavior When to use
"claude" (default) Claude CLI runs WebSearch internally via Anthropic. Zero setup, no extra cost, no API key. The query is shown in the transcript as a > Web search: line (opencode has no WebSearch tool registry entry, so a raw tool row would render as ⚙ invalid). Most users.
"<opencode-tool-name>" (e.g. "websearch_web_search_exa") Forward to that opencode-side tool with executed:false. Requires the corresponding MCP server to be configured in opencode (e.g. exa-mcp-server). You want a specific search backend (Exa, Tavily, Brave) and have the MCP wired up in opencode.
"disabled" WebSearch is added to --disallowedTools so the model can’t call it. Compliance/security scenarios where outbound search isn’t allowed.
"options": { "webSearch": "websearch_web_search_exa" }

Trade-offs

  • Claude-side execution: free with your Claude usage, no API key, but no opencode visibility into queries/results, no caching/rate-limit hooks.
  • opencode-side execution: choose any backend, queries flow through opencode’s audit/policy/cache, but costs money (search APIs are paid) and adds a network hop.
  • Some Claude-specific tool features stay on the built-in side (notably MultiEdit, see the note above).

Free and MIT-licensed, made by @khalilgharbaoui. If the plugin saves you time, you can buy its maintainer a coffee.

Buy me a coffee