Skip to content

Commit a30dc12

Browse files
committed
feat(mcp): send server instructions that make delegation the default for implementation
1 parent 4c57450 commit a30dc12

6 files changed

Lines changed: 47 additions & 5 deletions

File tree

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The plugin's runtime behaviour lives in the markdown files below plus the bundle
2121
| Agent | `agents/opencode-worker.md` | Thin forwarder: one `opencode run` (write: `build --auto`; read: `plan`), report |
2222
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
2323
| Hook | `scripts/route-to-opencode.sh`, `plugin-hooks/hooks.json` | PreToolUse `Agent\|Task`: rewrites only built-in subagent calls (general-purpose, claude, Explore, Plan, claude-code-guide, statusline-setup) to `opencode-worker` on Haiku (Explore/Plan/claude-code-guide forced read-only); custom, plugin, reviewer and SDD agents never routed; pass-through guards: `OPENCODE_DELEGATE_ROUTE=off`, missing opencode, `[no-opencode]`, no `jq` |
24-
| MCP | `.mcp.json`, `src/index.ts`, `dist/index.js` | `opencode` MCP server (stdio, `bun ${CLAUDE_PLUGIN_ROOT}/dist/index.js`) exposing `delegate`, `delegate_async`, `task_result`, `task_list`, `task_cancel`, `list_models`, `list_sessions` to the main thread |
24+
| MCP | `.mcp.json`, `src/index.ts`, `dist/index.js` | `opencode` MCP server (stdio, `bun ${CLAUDE_PLUGIN_ROOT}/dist/index.js`) exposing `delegate`, `delegate_async`, `task_result`, `task_list`, `task_cancel`, `list_models`, `list_sessions` to the main thread; its `instructions` (always in the system prompt) make delegation the default for implementation |
2525
| Manifests | `.claude-plugin/plugin.json`, `marketplace.json` | Plugin identity; `plugin.json` carries homepage/repository shown by Claude Code |
2626

2727
`src/` backs the MCP server (`src/index.ts`). The installed plugin cache has no `node_modules`, so what runs is the committed bundle `dist/index.js`: changing `src/` changes plugin behaviour only after `bun run build`, and CI fails if `dist/` is stale. Its exports (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) are also the reference for how `opencode run` must be invoked and how its JSON stream is parsed; `opencode-worker` shells out to `opencode run` itself, so keep its command consistent with `buildArgs`.

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ 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`.
47+
4648
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.
4749
4850
The hook never blocks. It passes the call through unchanged when:

‎agents/opencode-worker.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: opencode-worker
3-
description: Forwards one scoped task to a model running in OpenCode (Grok, Kimi, GLM, Qwen, DeepSeek, …) through `opencode run` and reports what happened. Use when the user or caller explicitly asks for a task to be done by 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.
3+
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
66
---

‎dist/index.js‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21975,7 +21975,13 @@ async function waitTask(task, waitSec) {
2197521975

2197621976
// src/index.ts
2197721977
var pkg = JSON.parse(readFileSync(join2(import.meta.dir, "..", "package.json"), "utf8"));
21978-
var server = new McpServer({ name: "opencode-delegate", version: pkg.version });
21978+
var INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator.
21979+
- 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\`.
21980+
- Keep for yourself: planning and design decisions, one-line edits, git/commit/PR/delivery, and anything the user asked you to do yourself.
21981+
- The OpenCode model cannot see this conversation: write a self-contained brief (goal, files, constraints, acceptance checks). Omit \`model\` unless the user named one.
21982+
- 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.
21983+
- If these tools are deferred, load them (search "opencode delegate") before the first call.`;
21984+
var server = new McpServer({ name: "opencode-delegate", version: pkg.version }, { instructions: INSTRUCTIONS });
2197921985
var text = (t, isError = false) => ({
2198021986
content: [{ type: "text", text: t }],
2198121987
isError

‎src/index.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,19 @@ const pkg = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"),
1414
version: string;
1515
};
1616

17-
const server = new McpServer({ name: "opencode-delegate", version: pkg.version });
17+
// Injected into every session's system prompt (unlike tool descriptions, which deferred-tool clients
18+
// 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\`.
21+
- 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.`;
25+
26+
const server = new McpServer(
27+
{ name: "opencode-delegate", version: pkg.version },
28+
{ instructions: INSTRUCTIONS },
29+
);
1830

1931
const text = (t: string, isError = false) => ({
2032
content: [{ type: "text" as const, text: t }],

‎test/mcp-server.test.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,16 @@ interface Tool {
1919
inputSchema: { required?: string[] };
2020
}
2121

22+
interface Handshake {
23+
instructions?: string;
24+
tools: Tool[];
25+
}
26+
2227
async function listTools(entry: string): Promise<Tool[]> {
28+
return (await handshake(entry)).tools;
29+
}
30+
31+
async function handshake(entry: string): Promise<Handshake> {
2332
const proc = Bun.spawn(["bun", join(root, entry)], {
2433
stdin: "pipe",
2534
stdout: "pipe",
@@ -44,6 +53,7 @@ async function listTools(entry: string): Promise<Tool[]> {
4453
const reader = proc.stdout.getReader();
4554
const dec = new TextDecoder();
4655
let buf = "";
56+
let instructions: string | undefined;
4757
try {
4858
while (true) {
4959
const { value, done } = await reader.read();
@@ -52,7 +62,8 @@ async function listTools(entry: string): Promise<Tool[]> {
5262
for (const line of buf.split("\n")) {
5363
if (!line.trim()) continue;
5464
const msg = JSON.parse(line);
55-
if (msg.id === 2) return msg.result.tools as Tool[];
65+
if (msg.id === 1) instructions = msg.result.instructions;
66+
if (msg.id === 2) return { instructions, tools: msg.result.tools as Tool[] };
5667
}
5768
}
5869
} finally {
@@ -67,6 +78,17 @@ describe.each(["src/index.ts", "dist/index.js"])("MCP server (%s)", (entry) => {
6778
const d = tools.find((t) => t.name === "delegate");
6879
expect(d?.inputSchema.required).toContain("prompt");
6980
}, 15000);
81+
82+
// Clients inject server instructions into every session's system prompt even when the tools
83+
// 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 () => {
85+
const { instructions } = await handshake(entry);
86+
expect(instructions).toBeString();
87+
expect(instructions).toContain("delegate");
88+
expect(instructions).toContain("delegate_async");
89+
expect(instructions).toMatch(/by default/i);
90+
expect(instructions).toMatch(/review/i);
91+
}, 15000);
7092
});
7193

7294
describe("MCP server version", () => {

0 commit comments

Comments
 (0)