Skip to content

Commit c988e16

Browse files
committed
feat(mcp): delegate through background opencode-worker agents by default
The delegate tool blocks the main thread until OpenCode finishes. The server instructions now define delegating as spawning opencode-worker subagents in the background, and the worker sets background: true so it never runs in the foreground.
1 parent b706033 commit c988e16

6 files changed

Lines changed: 23 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ The run uses your existing OpenCode auth, config, agents and permission rules.
4343
4444
## Automatic routing
4545
46-
The MCP server sends `instructions` that clients inject into every session's system prompt, even when the tools themselves are deferred. They make delegation the default for self-contained implementation (new code, multi-file edits, tests, refactors, boilerplate) and broad read-only exploration, while Claude keeps planning, one-line edits, git and delivery, and anything the user asked it to do itself. The text lives in `INSTRUCTIONS` in `src/index.ts`.
46+
The MCP server sends `instructions` that clients inject into every session's system prompt, even when the tools are deferred; they make delegation the default for self-contained implementation and broad read-only exploration, and define delegating as spawning `opencode-worker` subagents in the background (one per independent task, parallel when files do not overlap) so the main thread is never blocked; the `delegate` tool blocks until OpenCode finishes, so it is used only on request or when no Agent tool is available; Claude keeps planning, one-line edits, git and delivery, and anything the user asked it to do itself; the text lives in `INSTRUCTIONS` in `src/index.ts`.
4747
4848
A plugin PreToolUse hook (`scripts/route-to-opencode.sh`, wired by `plugin-hooks/hooks.json`) rewrites `Agent`/`Task` calls to Claude Code's built-in subagents into a call to `opencode-delegate:opencode-worker` on Haiku. The `description` and any other input keys are kept; the worker runs the task through `opencode run` using OpenCode's configured default model. The prompt is kept as is for `general-purpose` and untyped calls. `Explore`, `Plan` and `claude-code-guide` calls get a `Read-only task (routed from the ... subagent).` prefix, which forces the worker into read-only mode. `statusline-setup` gets a `Routed from the ... subagent.` note; `claude` is kept as is. Only these built-ins are routed: custom, project, user and plugin agents (reviewers and SDD agents included, and `opencode-worker` itself) are never routed and stay on Claude.
4949

‎agents/opencode-worker.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ name: opencode-worker
33
description: Forwards one scoped task to a model running in OpenCode (Grok, Kimi, GLM, Qwen, DeepSeek, …) through `opencode run` and reports what happened. Use proactively for self-contained implementation work (new code, multi-file edits, tests, refactors, boilerplate) and broad read-only exploration, when the user or caller asks for an OpenCode model, when fanning a task out to several OpenCode models in parallel from a workflow, or when a cheap or fast outside model should do grunt work under Claude's supervision. Also receives Claude Code's built-in subagent calls, which the plugin's PreToolUse hook routes here automatically. Put the model name (e.g. "grok 4.7", "kimi k3"), if any, and the task in the prompt.
44
tools: Bash
55
model: haiku
6+
background: true
67
---
78

89
You are a thin forwarder. You run one `opencode run` command, then report. You do not gather context, review the result, fix anything or retry. The caller (Claude) reviews; iteration means the caller invokes you again with the session id and feedback.

‎dist/index.js‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21974,12 +21974,12 @@ async function waitTask(task, waitSec) {
2197421974

2197521975
// src/index.ts
2197621976
var pkg = JSON.parse(readFileSync(join2(import.meta.dir, "..", "package.json"), "utf8"));
21977-
var INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator.
21978-
- Send every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) to \`delegate\`, or \`delegate_async\` for long or parallel runs. Send broad read-only exploration there too, with \`auto: false\`.
21977+
var INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator. Delegating means spawning background agents, never blocking the main thread.
21978+
- Launch the \`opencode-delegate:opencode-worker\` subagent (Agent tool, in the background; set \`run_in_background: true\` where the Agent tool offers it) for every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) and for broad read-only exploration (say "read-only" in its prompt). Spawn one worker per independent task, in parallel when they do not edit the same files, and keep working while they run.
21979+
- Do not call the \`delegate\` tool for this: it blocks the main thread until OpenCode finishes. Use \`delegate\` or \`delegate_async\` only when the user asks for the MCP tools or no Agent tool is available; if they are deferred, load them (search "opencode delegate") first.
2197921980
- Keep for yourself: planning and design decisions, one-line edits, git/commit/PR/delivery, and anything the user asked you to do yourself.
21980-
- The OpenCode model cannot see this conversation: write a self-contained brief (goal, files, constraints, acceptance checks). Omit \`model\` unless the user named one.
21981-
- After it returns, review the reported git changes and run the project's checks before reporting. For fixes, continue with its \`session_id\` instead of redoing the work yourself.
21982-
- If these tools are deferred, load them (search "opencode delegate") before the first call.`;
21981+
- The OpenCode model cannot see this conversation: give the worker a self-contained brief (goal, files, constraints, acceptance checks). Name a model only if the user named one.
21982+
- When a worker reports back, review its git changes and run the project's checks before reporting. For fixes, spawn the worker again with its session id and precise feedback instead of redoing the work yourself.`;
2198321983
var server = new McpServer({ name: "opencode-delegate", version: pkg.version }, { instructions: INSTRUCTIONS });
2198421984
var text = (t, isError = false) => ({
2198521985
content: [{ type: "text", text: t }],

‎src/index.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,12 @@ const pkg = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"),
1616

1717
// Injected into every session's system prompt (unlike tool descriptions, which deferred-tool clients
1818
// hide until loaded), so this is what makes Claude delegate implementation without being asked.
19-
const INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator.
20-
- Send every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) to \`delegate\`, or \`delegate_async\` for long or parallel runs. Send broad read-only exploration there too, with \`auto: false\`.
19+
const INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator. Delegating means spawning background agents, never blocking the main thread.
20+
- Launch the \`opencode-delegate:opencode-worker\` subagent (Agent tool, in the background; set \`run_in_background: true\` where the Agent tool offers it) for every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) and for broad read-only exploration (say "read-only" in its prompt). Spawn one worker per independent task, in parallel when they do not edit the same files, and keep working while they run.
21+
- Do not call the \`delegate\` tool for this: it blocks the main thread until OpenCode finishes. Use \`delegate\` or \`delegate_async\` only when the user asks for the MCP tools or no Agent tool is available; if they are deferred, load them (search "opencode delegate") first.
2122
- Keep for yourself: planning and design decisions, one-line edits, git/commit/PR/delivery, and anything the user asked you to do yourself.
22-
- The OpenCode model cannot see this conversation: write a self-contained brief (goal, files, constraints, acceptance checks). Omit \`model\` unless the user named one.
23-
- After it returns, review the reported git changes and run the project's checks before reporting. For fixes, continue with its \`session_id\` instead of redoing the work yourself.
24-
- If these tools are deferred, load them (search "opencode delegate") before the first call.`;
23+
- The OpenCode model cannot see this conversation: give the worker a self-contained brief (goal, files, constraints, acceptance checks). Name a model only if the user named one.
24+
- When a worker reports back, review its git changes and run the project's checks before reporting. For fixes, spawn the worker again with its session id and precise feedback instead of redoing the work yourself.`;
2525

2626
const server = new McpServer(
2727
{ name: "opencode-delegate", version: pkg.version },

‎test/mcp-server.test.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,16 @@ describe.each(["src/index.ts", "dist/index.js"])("MCP server (%s)", (entry) => {
8181

8282
// Clients inject server instructions into every session's system prompt even when the tools
8383
// themselves are deferred, so this is what makes Claude delegate without being asked.
84-
test("initialize sends instructions that make delegation the default for implementation", async () => {
84+
test("initialize sends instructions that make background worker agents the default for implementation", async () => {
8585
const { instructions } = await handshake(entry);
8686
expect(instructions).toBeString();
8787
expect(instructions).toContain("delegate");
8888
expect(instructions).toContain("delegate_async");
8989
expect(instructions).toMatch(/by default/i);
9090
expect(instructions).toMatch(/review/i);
91+
expect(instructions).toContain("opencode-delegate:opencode-worker");
92+
expect(instructions).toMatch(/background/i);
93+
expect(instructions).toMatch(/blocks the main thread/i);
9194
}, 15000);
9295
});
9396

‎test/package.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,13 @@ describe("npm package", () => {
5353
});
5454
});
5555

56+
// Delegation must never block the main thread, even when Claude asks to wait for the worker.
57+
test("opencode-worker always runs in the background", () => {
58+
const md = readFileSync(join(root, "agents/opencode-worker.md"), "utf8");
59+
const frontmatter = md.split(/^---$/m)[1];
60+
expect(frontmatter).toMatch(/^background: true$/m);
61+
});
62+
5663
test("versions are in sync across manifests", () => {
5764
const v = readJson("package.json").version;
5865
expect(readJson(".claude-plugin/plugin.json").version).toBe(v);

0 commit comments

Comments
 (0)