Skip to content

Commit dbf3891

Browse files
zaxbysauceclaude
andauthored
fix(commands): mutate output.parts in place + document LLM-mediation gap (#845)
The `command.execute.before` hook in createSwarmCommandHandler was reassigning `output.parts = [{type: 'text', text}]`. OpenCode's Plugin.trigger discards the wrapper object that the hook receives (packages/opencode/src/plugin/index.ts on dev), and the runtime in packages/opencode/src/session/prompt.ts continues using its own local `parts` variable when invoking the model. As a result, the handler's reassignment was a no-op — the LLM never saw the canonical handler output, and chat-typed `/swarm <subcommand>` has always been answered by the model rephrasing only the user's literal command text. Fix: use `output.parts.splice(0, output.parts.length, ...)` so the underlying array (shared by reference with the OpenCode caller's local `parts` variable) is mutated in place. The handler text now reaches the model as its input. Note: this does NOT suppress the LLM call; OpenCode currently runs prompt() unconditionally after the hook returns (upstream issue anomalyco/opencode#9306). The deterministic in-chat path is tracked in #843 (MCP tool) and #844 (upstream noReply support). Also: - Export a `LLM_MEDIATION_WARNING` banner and prepend it to `/swarm help` output so users discover the limitation. - Add a matching note to the README `## Commands` section pointing users to `bunx opencode-swarm run <subcommand>` for canonical output. - Add src/commands/index.parts-mutation.test.ts: five regression tests asserting the parts array reference is preserved across handler calls for swarm, swarm-* shortcuts, the not-found path, the non-swarm early-return path, and pre-populated parts. - Add docs/releases/v7.18.3.md per release-please workflow. Refs: #843, #844 Co-authored-by: Claude <[email protected]>
1 parent a7759ca commit dbf3891

8 files changed

Lines changed: 323 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,14 @@ Core subcommands at a glance:
231231

232232
Use `/swarm help` to see all available commands categorized by function. Use `/swarm help <command>` for detailed usage information on a specific command.
233233

234+
> ⚠️ **Chat-typed `/swarm` is currently LLM-mediated.** The OpenCode runtime invokes the model unconditionally after the plugin handles a `command.execute.before` slash command (upstream issue [anomalyco/opencode#9306](https://github.com/anomalyco/opencode/issues/9306)). What you see in chat is the model's reformulation of the canonical handler output, which can drift on weak models or in long sessions. For deterministic, scriptable output, run the underlying command directly:
235+
>
236+
> ```bash
237+
> bunx opencode-swarm run <subcommand> # e.g. bunx opencode-swarm run agents
238+
> ```
239+
>
240+
> This is a temporary mitigation. A deterministic in-chat path (either a `swarm` MCP tool or upstream `noReply` support) is tracked separately.
241+
234242
Nine commands display a ⚠️ warning in help output because they share names with Claude Code built-in slash commands (e.g., `/plan`, `/reset`, `/status`). The warning reminds you to always use `/swarm <command>` — the bare CC command does something different and sometimes destructive. See [docs/commands.md#claude-code-command-conflicts](docs/commands.md#claude-code-command-conflicts) for the full conflict registry.
235243
236244
See [docs/commands.md](docs/commands.md) for the full command reference.

‎dist/cli/index.js‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ var package_default;
5252
var init_package = __esm(() => {
5353
package_default = {
5454
name: "opencode-swarm",
55-
version: "7.18.1",
55+
version: "7.18.2",
5656
description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
5757
main: "dist/index.js",
5858
types: "dist/index.d.ts",
@@ -51927,14 +51927,15 @@ __export(exports_commands, {
5192751927
createSwarmCommandHandler: () => createSwarmCommandHandler,
5192851928
buildHelpText: () => buildHelpText,
5192951929
VALID_COMMANDS: () => VALID_COMMANDS,
51930+
LLM_MEDIATION_WARNING: () => LLM_MEDIATION_WARNING,
5193051931
COMMAND_REGISTRY: () => COMMAND_REGISTRY,
5193151932
COMMAND_NAME_SET: () => COMMAND_NAME_SET,
5193251933
COMMAND_NAMES: () => COMMAND_NAMES
5193351934
});
5193451935
import fs28 from "fs";
5193551936
import path46 from "path";
5193651937
function buildHelpText() {
51937-
const lines = ["## Swarm Commands", ""];
51938+
const lines = ["## Swarm Commands", "", LLM_MEDIATION_WARNING, ""];
5193851939
const CATEGORIES = [
5193951940
"core",
5194051941
"agent",
@@ -52100,11 +52101,13 @@ ${text}`;
5210052101
`;
5210152102
text = welcomeMessage + text;
5210252103
}
52103-
output.parts = [
52104-
{ type: "text", text }
52105-
];
52104+
output.parts.splice(0, output.parts.length, {
52105+
type: "text",
52106+
text
52107+
});
5210652108
};
5210752109
}
52110+
var LLM_MEDIATION_WARNING;
5210852111
var init_commands = __esm(() => {
5210952112
init_registry();
5211052113
init_acknowledge_spec_drift();
@@ -52142,6 +52145,8 @@ var init_commands = __esm(() => {
5214252145
init_sync_plan();
5214352146
init_turbo();
5214452147
init_write_retro2();
52148+
LLM_MEDIATION_WARNING = "> \u26A0\uFE0F Chat-typed `/swarm` is LLM-mediated in current OpenCode (see anomalyco/opencode#9306).\n" + `> The text below is the canonical handler output, but the model may rephrase it before display.
52149+
` + "> For deterministic output, run `bunx opencode-swarm run <subcommand>` from a terminal.";
5214552150
});
5214652151

5214752152
// src/commands/registry.ts

‎dist/commands/index.d.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ export { handleStatusCommand } from './status';
4040
export { handleSyncPlanCommand } from './sync-plan';
4141
export { handleTurboCommand } from './turbo';
4242
export { handleWriteRetroCommand } from './write-retro';
43+
export declare const LLM_MEDIATION_WARNING: string;
4344
export declare function buildHelpText(): string;
4445
/**
4546
* Creates a command.execute.before handler for /swarm commands.

‎dist/index.js‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ var package_default;
5151
var init_package = __esm(() => {
5252
package_default = {
5353
name: "opencode-swarm",
54-
version: "7.18.1",
54+
version: "7.18.2",
5555
description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
5656
main: "dist/index.js",
5757
types: "dist/index.d.ts",
@@ -61092,14 +61092,15 @@ __export(exports_commands, {
6109261092
createSwarmCommandHandler: () => createSwarmCommandHandler,
6109361093
buildHelpText: () => buildHelpText,
6109461094
VALID_COMMANDS: () => VALID_COMMANDS,
61095+
LLM_MEDIATION_WARNING: () => LLM_MEDIATION_WARNING,
6109561096
COMMAND_REGISTRY: () => COMMAND_REGISTRY,
6109661097
COMMAND_NAME_SET: () => COMMAND_NAME_SET,
6109761098
COMMAND_NAMES: () => COMMAND_NAMES
6109861099
});
6109961100
import fs37 from "node:fs";
6110061101
import path55 from "node:path";
6110161102
function buildHelpText() {
61102-
const lines = ["## Swarm Commands", ""];
61103+
const lines = ["## Swarm Commands", "", LLM_MEDIATION_WARNING, ""];
6110361104
const CATEGORIES = [
6110461105
"core",
6110561106
"agent",
@@ -61265,11 +61266,13 @@ ${text}`;
6126561266
`;
6126661267
text = welcomeMessage + text;
6126761268
}
61268-
output.parts = [
61269-
{ type: "text", text }
61270-
];
61269+
output.parts.splice(0, output.parts.length, {
61270+
type: "text",
61271+
text
61272+
});
6127161273
};
6127261274
}
61275+
var LLM_MEDIATION_WARNING;
6127361276
var init_commands = __esm(() => {
6127461277
init_registry();
6127561278
init_acknowledge_spec_drift();
@@ -61307,6 +61310,8 @@ var init_commands = __esm(() => {
6130761310
init_sync_plan();
6130861311
init_turbo();
6130961312
init_write_retro2();
61313+
LLM_MEDIATION_WARNING = "> ⚠️ Chat-typed `/swarm` is LLM-mediated in current OpenCode (see anomalyco/opencode#9306).\n" + `> The text below is the canonical handler output, but the model may rephrase it before display.
61314+
` + "> For deterministic output, run `bunx opencode-swarm run <subcommand>` from a terminal.";
6131061315
});
6131161316

6131261317
// src/commands/registry.ts

‎docs/releases/v7.18.3.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# v7.18.3
2+
3+
## Slash-command in-place mutation fix + LLM-mediation transparency
4+
5+
The `command.execute.before` hook in `src/commands/index.ts` was reassigning
6+
`output.parts = [{type: 'text', text}]` to deliver handler output back to
7+
the OpenCode runtime. That assignment only mutated the throwaway wrapper
8+
object `Plugin.trigger` constructs, so the handler's text never reached
9+
the model as its input. Verified against current upstream OpenCode source
10+
(`packages/opencode/src/session/prompt.ts`, `packages/opencode/src/plugin/index.ts`,
11+
`packages/plugin/src/index.ts` on `dev`).
12+
13+
Even with the assignment-vs-mutation bug fixed, current OpenCode still
14+
invokes `prompt(...)` unconditionally after the hook returns (upstream
15+
issue [anomalyco/opencode#9306](https://github.com/anomalyco/opencode/issues/9306),
16+
closed without shipping `noReply`). The user-visible response in chat is
17+
therefore always the model's rephrasing of the canonical handler output —
18+
which can drift dramatically on weak models or in subagent contexts. The
19+
release documents this limitation and points users to the deterministic
20+
CLI path until a structural fix lands.
21+
22+
## What changed
23+
24+
- `src/commands/index.ts`:
25+
- `createSwarmCommandHandler` now calls `output.parts.splice(0, output.parts.length, ...)` instead of reassigning `output.parts`. The shared array reference is mutated in place so OpenCode's outer `parts` variable observes the handler output.
26+
- Removed an outdated comment claiming `output.parts` "overrides the LLM response". The new comment cites the upstream gap.
27+
- Exported a new `LLM_MEDIATION_WARNING` banner. `buildHelpText()` now prepends it so `/swarm help` is the first place users see the limitation.
28+
- `src/commands/index.parts-mutation.test.ts` (new): five regression tests pinning the in-place mutation contract for `/swarm`, `/swarm-*` shortcuts, the not-found path, the non-swarm early-return path, and the pre-populated-parts replacement case.
29+
- `README.md`: warning callout under `## Commands` directing users to `bunx opencode-swarm run <subcommand>` for canonical output until the structural fix lands.
30+
31+
## Why
32+
33+
Users (and other agents reading swarm state) have been treating LLM-rephrased
34+
`/swarm` output as authoritative. The original bug report showed a weak
35+
subagent fabricating `"There is no .swarm/agents.json"` — a string that
36+
exists nowhere in the codebase. A second screenshot showed a strong
37+
orchestrator producing plausible-looking-but-still-fabricated output. The
38+
plugin handler did run in both cases (it resolved the command, executed
39+
the handler, and wrote to `output.parts`), but because of the
40+
assignment-vs-mutation bug the canonical handler output never propagated
41+
to OpenCode's outer `parts` array — so the LLM saw only the raw
42+
`/swarm <subcommand>` text as its input and answered freeform.
43+
44+
This release does not fully fix the user-visible problem (only OpenCode
45+
upstream can), but it removes the silent failure mode (no-op assignment)
46+
and tells users when they cannot trust chat output.
47+
48+
## Follow-up tracking
49+
50+
- [#843](https://github.com/zaxbysauce/opencode-swarm/issues/843) — design and ship a `swarm` MCP tool so the orchestrator can call read-only subcommands deterministically.
51+
- [#844](https://github.com/zaxbysauce/opencode-swarm/issues/844) — file an upstream PR against `anomalyco/opencode` adding `noReply` / `abort` to `command.execute.before`. Once that lands, the banner can be removed and the hook can fully suppress the LLM.
52+
53+
## Migration
54+
55+
None required. Behavior change is:
56+
57+
- `bunx opencode-swarm run <subcommand>` output is unchanged.
58+
- Chat-typed `/swarm <subcommand>` output is unchanged in shape (still LLM-rephrased) but now has the canonical handler text in the model's input context, which on strong models produces noticeably more accurate rephrasings. Weak models will still drift.
59+
- `/swarm help` output now starts with a one-paragraph banner before the command list.
60+
61+
## Known caveats
62+
63+
- The LLM-mediation gap is unfixed at the plugin layer. Users running `/swarm` in chat on free or weak models should expect drift and prefer the CLI for anything they depend on (CI scripts, automation, state checks).
64+
- The banner relies on the model relaying its input. On models that ignore long preambles, users may not see the warning even though it is present in the handler output.
65+
66+
## Invariant audit
67+
68+
- 1 (plugin init): not touched — change is inside the `command.execute.before` hook body, not in plugin init; verified by `git diff origin/main..HEAD -- src/index.ts` returning no output.
69+
- 2 (runtime portability): touched — `dist/cli/index.js`, `dist/commands/index.d.ts`, and `dist/index.js` were rebuilt and committed. No `bun:` imports added, no `Bun.*` calls outside `bun-compat.ts` (verified by `grep -n "bun:" src/commands/index.ts src/commands/index.parts-mutation.test.ts` returning no top-level `bun:` imports). Bundle integrity verified: `bun --smol test tests/unit/build/bundle-portability.test.ts tests/unit/build/bundle-plugin-shape.test.ts tests/unit/build/bundle-node-load.test.ts` → 5/5 pass; `node --input-type=module -e "await import('./dist/index.js')"` → loads cleanly.
70+
- 3 (subprocesses): not touched — no `spawn`/`spawnSync`/`bunSpawn` calls in changed files; verified by `git diff --name-only origin/main..HEAD | xargs -r grep -nE "bunSpawn\(|spawn\(|spawnSync\("` returning empty.
71+
- 4 (.swarm containment): not touched — no new `.swarm/` paths; existing first-run sentinel write unchanged.
72+
- 5 (plan durability): not touched.
73+
- 6 (test_runner safety): not touched — validation used per-file `bun --smol test` shell invocations, never `test_runner` with broad scope.
74+
- 7 (test writing): touched — new `src/commands/index.parts-mutation.test.ts` uses `bun:test` directly, no `mock.module`, no shared state. Verified by `bun --smol test src/commands/index.parts-mutation.test.ts` → 5/5 pass.
75+
- 8 (session state): not touched.
76+
- 9 (guardrails/retry): not touched.
77+
- 10 (chat/system msg): touched — `command.execute.before` is part of the chat-message hook surface. The fix changes how the hook mutates the user-message parts array (in-place vs reassignment), and adds a warning banner to `/swarm help`. Verified by `bun --smol test src/commands/index.help-text.test.ts src/commands/shortcut-routing.test.ts src/commands/index.not-found.test.ts src/commands/index.parts-mutation.test.ts` → 49/49 of the tests affected by this change pass; 3 unrelated pre-existing shortcut-routing failures confirmed on `origin/main` via `git stash` + re-run.
78+
- 11 (tool registration): not touched.
79+
- 12 (release/cache): touched — this release-notes file added; `package.json`, `CHANGELOG.md`, `.release-please-manifest.json` untouched.

‎src/commands/index.help-text.test.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, expect, it, test } from 'bun:test';
2-
import { buildHelpText } from './index';
2+
import { buildHelpText, LLM_MEDIATION_WARNING } from './index';
33
import type { CommandEntry, RegisteredCommand } from './registry';
44
import { COMMAND_REGISTRY, VALID_COMMANDS } from './registry';
55

@@ -13,6 +13,21 @@ describe('buildHelpText()', () => {
1313
test('starts with "## Swarm Commands"', () => {
1414
expect(helpText.startsWith('## Swarm Commands')).toBe(true);
1515
});
16+
17+
test('includes the LLM-mediation warning banner', () => {
18+
expect(helpText).toContain(LLM_MEDIATION_WARNING);
19+
// Banner must appear before the first command category so users
20+
// see it before scrolling.
21+
const bannerIdx = helpText.indexOf(LLM_MEDIATION_WARNING);
22+
const firstCategoryIdx = helpText.indexOf('### ');
23+
expect(bannerIdx).toBeGreaterThan(-1);
24+
expect(firstCategoryIdx).toBeGreaterThan(bannerIdx);
25+
});
26+
27+
test('banner cites the upstream issue', () => {
28+
expect(LLM_MEDIATION_WARNING).toContain('anomalyco/opencode#9306');
29+
expect(LLM_MEDIATION_WARNING).toContain('bunx opencode-swarm run');
30+
});
1631
});
1732

1833
describe('command entries', () => {

0 commit comments

Comments
 (0)