Skip to content

Commit 9f4722f

Browse files
committed
feat(hooks): route all Claude Code built-in subagents to opencode-worker
Allowlist: general-purpose, untyped, claude, Explore, Plan, claude-code-guide and statusline-setup are routed. Explore, Plan and claude-code-guide prompts get a read-only prefix, statusline-setup a routed-from note. Custom, project, user and plugin agents, including reviewers, SDD agents and the worker itself, stay on Claude.
1 parent 3f26c35 commit 9f4722f

5 files changed

Lines changed: 126 additions & 34 deletions

File tree

‎CLAUDE.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ Bun runs `.ts` directly. Nothing is compiled or bundled (`tsconfig` sets `noEmit
1515

1616
The plugin's runtime behaviour lives in markdown, not in `src/`:
1717

18-
| Surface | File | Role |
19-
| --------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
20-
| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules |
21-
| Agent | `agents/opencode-worker.md` | Thin forwarder: one `opencode run` (write: `build --auto`; read: `plan`), report |
22-
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
23-
| Hook | `scripts/route-to-opencode.sh`, `plugin-hooks/hooks.json` | PreToolUse `Agent\|Task`: rewrites general-purpose calls to `opencode-worker` on Haiku; pass-through guards: `OPENCODE_DELEGATE_ROUTE=off`, missing opencode, `[no-opencode]`, no `jq` |
24-
| Manifests | `.claude-plugin/plugin.json`, `marketplace.json` | Plugin identity; `plugin.json` carries homepage/repository shown by Claude Code |
18+
| Surface | File | Role |
19+
| --------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
20+
| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules |
21+
| Agent | `agents/opencode-worker.md` | Thin forwarder: one `opencode run` (write: `build --auto`; read: `plan`), report |
22+
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
23+
| 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+
| Manifests | `.claude-plugin/plugin.json`, `marketplace.json` | Plugin identity; `plugin.json` carries homepage/repository shown by Claude Code |
2525

2626
`src/` is a library that no plugin surface imports since the MCP server was removed; only the tests exercise it. Its exports (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) are the reference for how `opencode run` must be invoked and how its JSON stream is parsed. Changing behaviour in `src/` does NOT change what the plugin does — the markdown files do. `opencode-worker` shells out to `opencode run` itself; keep its command consistent with `buildArgs`.
2727

‎README.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ claude ▸ reads git diff, runs tests, reports which model did what and a verdic
1111

1212
## What ships
1313

14-
| Surface | File | Role |
15-
| ------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
16-
| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules |
17-
| Agent | `agents/opencode-worker.md` | Thin forwarder (`tools: Bash`, `model: haiku`): one `opencode run` |
18-
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
19-
| Hook | `scripts/route-to-opencode.sh` | PreToolUse hook (`plugin-hooks/hooks.json`): reroutes general-purpose subagent calls to `opencode-worker` |
14+
| Surface | File | Role |
15+
| ------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
16+
| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules |
17+
| Agent | `agents/opencode-worker.md` | Thin forwarder (`tools: Bash`, `model: haiku`): one `opencode run` |
18+
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
19+
| Hook | `scripts/route-to-opencode.sh` | PreToolUse hook (`plugin-hooks/hooks.json`): reroutes built-in subagent calls to `opencode-worker` |
2020

2121
No MCP server, no build step, no `dist/`. Claude Desktop is not supported.
2222

@@ -42,12 +42,13 @@ The run uses your existing OpenCode auth, config, agents and permission rules.
4242
4343
## Automatic routing
4444
45-
A plugin PreToolUse hook (`scripts/route-to-opencode.sh`, wired by `plugin-hooks/hooks.json`) rewrites every `Agent`/`Task` call whose subagent is `general-purpose`, or untyped, into a call to `opencode-delegate:opencode-worker` on Haiku. The `prompt` and `description` (and any other input keys) are kept; the worker runs the task through `opencode run` using OpenCode's configured default model. Calls to `Explore`, `Plan`, `sdd-*` and any other named or plugin agent pass through untouched.
45+
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.
4646
4747
The hook never blocks. It passes the call through unchanged when:
4848
49+
- The subagent is not a built-in one (custom, project, user or plugin agent, including reviewers and SDD agents).
4950
- `OPENCODE_DELEGATE_ROUTE` is `0`, `false`, `no` or `off` (global opt-out; unset or empty means routing is on).
50-
- `OPENCODE_BIN` (default `opencode`) cannot be found, so Claude falls back to its own general-purpose agent.
51+
- `OPENCODE_BIN` (default `opencode`) cannot be found, so Claude keeps the original subagent.
5152
- The prompt contains the literal `[no-opencode]` (per-task opt-out).
5253
- `jq` is missing, or the hook input is not valid JSON.
5354

‎agents/opencode-worker.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
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 tasks automatically routed from the general-purpose subagent by the plugin's PreToolUse hook. 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 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.
44
tools: Bash
55
model: haiku
66
---
77

88
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.
99

10-
Routed prompts were written for a general Claude agent, not for you: forward the task verbatim and infer the mode as described below (write by default; read-only for review, question, second opinion or an explicit "read-only").
10+
Routed prompts come from Claude Code's built-in subagents and were written for a Claude agent, not for you: forward the task verbatim, including any "Routed from the ... subagent" note, and infer the mode as described below (write by default; read-only for review, question, second opinion, an explicit "read-only" or a "Read-only task" prefix, which means read-only mode).
1111

1212
OpenCode restores its own context from engram, Graphiti memory and codegraph, so the prompt you send stays short.
1313

@@ -16,7 +16,7 @@ OpenCode restores its own context from engram, Graphiti memory and codegraph, so
1616
1. **Parse** your instructions:
1717
- model name, if any (may include `#variant`)
1818
- the task, kept verbatim
19-
- mode: **write** (default) or **read-only** (review, question, second opinion, or the caller says "read-only")
19+
- mode: **write** (default) or **read-only** (review, question, second opinion, a "Read-only task" prefix, or the caller says "read-only")
2020
- an optional session id to continue
2121
2. **Resolve the model.**
2222
- No model named: omit `-m`. OpenCode uses its configured default.

‎scripts/route-to-opencode.sh‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
#!/usr/bin/env bash
22
set -uo pipefail
33

4-
# PreToolUse hook (matcher: Agent|Task): reroute general-purpose subagent calls to
5-
# opencode-delegate:opencode-worker on Haiku. Never blocks: every guard below
6-
# passes the call through unchanged (exit 0, no stdout).
4+
# PreToolUse hook (matcher: Agent|Task): reroute Claude Code's built-in subagent calls
5+
# to opencode-delegate:opencode-worker on Haiku. Explore/Plan/claude-code-guide prompts
6+
# get a read-only prefix, statusline-setup a routed-from note; general-purpose, claude
7+
# and untyped prompts are kept as is. Custom and plugin agents are never routed.
8+
# Never blocks: every guard below passes the call through unchanged (exit 0, no stdout).
79

810
pass() { exit 0; }
911

@@ -20,9 +22,13 @@ printf '%s' "$input" | jq -e '.tool_input | type == "object"' >/dev/null 2>&1 \
2022
tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
2123
case "$tool" in Agent | Task) ;; *) pass ;; esac
2224

23-
# 4. Only general-purpose (missing or empty subagent_type counts as general-purpose).
25+
# 4. Built-in agents only. Custom, project, user and plugin agents (including reviewers,
26+
# SDD agents and opencode-worker itself) stay on Claude. Empty counts as general-purpose.
2427
subagent=$(printf '%s' "$input" | jq -r '.tool_input.subagent_type // empty')
25-
[ -z "$subagent" ] || [ "$subagent" = "general-purpose" ] || pass
28+
case "$subagent" in
29+
"" | general-purpose | claude | Explore | Plan | claude-code-guide | statusline-setup) ;;
30+
*) pass ;;
31+
esac
2632

2733
# 5. Global opt-out; same falsy values as src/config.ts bool(). Unset or empty means ON.
2834
route="${OPENCODE_DELEGATE_ROUTE:-}"
@@ -42,11 +48,21 @@ prompt=$(printf '%s' "$input" | jq -r '.tool_input.prompt // empty')
4248
case "$prompt" in *"[no-opencode]"*) pass ;; esac
4349

4450
# Rewrite. updatedInput replaces the whole input, so start from the original tool_input.
45-
printf '%s' "$input" | jq -c '{
46-
hookSpecificOutput: {
47-
hookEventName: "PreToolUse",
48-
permissionDecision: "allow",
49-
permissionDecisionReason: "routed general-purpose to opencode-worker",
50-
updatedInput: (.tool_input + {subagent_type: "opencode-delegate:opencode-worker", model: "haiku"})
51-
}
52-
}'
51+
# Missing or empty subagent_type counts as general-purpose. All text is built by jq.
52+
printf '%s' "$input" | jq -c '
53+
(.tool_input.subagent_type // "") as $t
54+
| (if $t == "" then "general-purpose" else $t end) as $name
55+
| (.tool_input.prompt // "") as $p
56+
| (if $name == "general-purpose" or $name == "claude" then $p
57+
elif $name == "Explore" or $name == "Plan" or $name == "claude-code-guide" then
58+
"Read-only task (routed from the `" + $name + "` subagent).\n\n" + $p
59+
else "Routed from the `" + $name + "` subagent.\n\n" + $p end) as $newp
60+
| {
61+
hookSpecificOutput: {
62+
hookEventName: "PreToolUse",
63+
permissionDecision: "allow",
64+
permissionDecisionReason: ("routed " + $name + " to opencode-worker"),
65+
updatedInput: (.tool_input + {subagent_type: "opencode-delegate:opencode-worker", model: "haiku"}
66+
+ (if .tool_input | has("prompt") then {prompt: $newp} else {} end))
67+
}
68+
}'

‎test/route-hook.test.ts‎

Lines changed: 78 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,13 +72,88 @@ describe("route-to-opencode hook: rewrites", () => {
7272
});
7373
});
7474

75-
describe("route-to-opencode hook: pass-through", () => {
76-
test("Explore is untouched", () => {
77-
expectPassThrough(run(call({ ...base, subagent_type: "Explore" })));
75+
const routed = (type: string, prompt: string, extra: ToolInput = {}) => {
76+
const input = { ...base, prompt, subagent_type: type, ...extra };
77+
const r = run(call(input));
78+
expect(r.code).toBe(0);
79+
const o = JSON.parse(r.out).hookSpecificOutput;
80+
expect(o.updatedInput.subagent_type).toBe(WORKER);
81+
expect(o.updatedInput.model).toBe("haiku");
82+
expect(o.updatedInput.description).toBe(base.description);
83+
return o as { updatedInput: ToolInput; permissionDecisionReason: string };
84+
};
85+
86+
describe("route-to-opencode hook: built-in subagent types", () => {
87+
test.each(["Explore", "Plan", "claude-code-guide"])("%s gets a read-only prefix", (t) => {
88+
const o = routed(t, "find x", { run_in_background: true });
89+
expect(o.updatedInput.prompt).toBe(
90+
`Read-only task (routed from the \`${t}\` subagent).\n\nfind x`,
91+
);
92+
expect(o.updatedInput.run_in_background).toBe(true);
93+
expect(o.permissionDecisionReason).toBe(`routed ${t} to opencode-worker`);
94+
});
95+
test("statusline-setup gets a routed-from note", () => {
96+
const o = routed("statusline-setup", "do it");
97+
expect(o.updatedInput.prompt).toBe("Routed from the `statusline-setup` subagent.\n\ndo it");
98+
expect(o.permissionDecisionReason).toBe("routed statusline-setup to opencode-worker");
99+
});
100+
test("claude prompt is unchanged", () => {
101+
const o = routed("claude", "plain");
102+
expect(o.updatedInput.prompt).toBe("plain");
103+
expect(o.permissionDecisionReason).toBe("routed claude to opencode-worker");
104+
});
105+
test("general-purpose prompt is unchanged and reason names it", () => {
106+
const o = routed("general-purpose", "plain");
107+
expect(o.updatedInput.prompt).toBe("plain");
108+
expect(o.permissionDecisionReason).toBe("routed general-purpose to opencode-worker");
109+
});
110+
test("missing type reason says general-purpose", () => {
111+
const r = run(call(base));
112+
expect(JSON.parse(r.out).hookSpecificOutput.permissionDecisionReason).toBe(
113+
"routed general-purpose to opencode-worker",
114+
);
115+
});
116+
test("tricky prompt stays verbatim inside the prefix", () => {
117+
const tricky = "a \"q\" 's'\nline2 $(id) `id` $HOME \\ ü";
118+
const o = routed("Explore", tricky);
119+
expect(o.updatedInput.prompt).toBe(
120+
`Read-only task (routed from the \`Explore\` subagent).\n\n${tricky}`,
121+
);
122+
const o2 = routed("statusline-setup", tricky);
123+
expect(o2.updatedInput.prompt).toBe(
124+
`Routed from the \`statusline-setup\` subagent.\n\n${tricky}`,
125+
);
126+
});
127+
test("[no-opencode] still opts out for named types", () => {
128+
expectPassThrough(run(call({ ...base, prompt: "x [no-opencode]", subagent_type: "Plan" })));
129+
});
130+
});
131+
132+
describe("route-to-opencode hook: custom, plugin, reviewer and SDD agents stay on Claude", () => {
133+
test.each([
134+
"review-risk",
135+
"review-refuter",
136+
"sdd-apply",
137+
"jd-judge-a",
138+
"pr-review-toolkit:code-reviewer",
139+
"gentle-ai:sdd-verify",
140+
"technical-copywriter",
141+
"tech-docs-writer",
142+
"universal-stack-expert",
143+
"superpowers:some-agent",
144+
WORKER,
145+
])("%s is untouched", (t) => {
146+
expectPassThrough(run(call({ ...base, subagent_type: t })));
78147
});
148+
});
149+
150+
describe("route-to-opencode hook: pass-through", () => {
79151
test("opencode-worker is untouched (no loop)", () => {
80152
expectPassThrough(run(call({ ...base, subagent_type: WORKER })));
81153
});
154+
test("bare opencode-worker is untouched (no loop)", () => {
155+
expectPassThrough(run(call({ ...base, subagent_type: "opencode-worker" })));
156+
});
82157
test("non-Agent tool is untouched", () => {
83158
expectPassThrough(run(call(base, "Bash")));
84159
});

0 commit comments

Comments
 (0)