|
| 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. |
0 commit comments