[backnotprop]

Problem

On OpenCode 2 (seen in the 0.28.6 release smoke, also in 0.28.5), /plannotator-annotate . notes.md opened nothing and showed the user nothing. notes.md . and please notes.md failed the same way. The only trace was File not found: . notes.md in the OpenCode log. A single file and a real list of files worked, and OpenCode 1 opened notes.md correctly.

Cause

1. When the words were not a list of files, buildAnnotateCliArgs in apps/opencode-plugin/cli-bridge.ts passed the whole string to the CLI as ONE argument: annotate ". notes.md" --json. The real CLI treats one argument as one path, so it never ran its tolerant resolution. That resolution, given separate words, drops . and opens notes.md. The fix(mod, opencode): name a review by what the CLI opened, not the typed words #1737 test passed only because its stub CLI split its one argument on whitespace and dropped ., which the real CLI does not do.
2. A failed OpenCode 2 slash command was only logged (cliFailure / reportFailure). OpenCode 2 discards that log, so the user saw nothing at all.

Fix

• Separate words. The new annotateCliTargets (cli-bridge) passes the slash command's words to the CLI as separate arguments when the input as a whole names nothing. The split is done by the shared annotateTargetWords (packages/shared/annotate-args.ts). It uses the same quote rule as review arguments (scanQuotedWords, now exported from review-args.ts): quotes group a path with spaces, and backslashes are kept so Windows paths work. An unterminated quote is read as prose (an apostrophe) and splits on whitespace. Known flags are dropped. The input stays ONE argument, as before, in three cases:

  • the whole input names an existing target (an unquoted path with spaces, my notes.md)
  • it is a single word
  • any word starts with -, so a mistyped flag, or a flag written in prose such as --require-approval, never reaches the CLI as a real flag.

  The plannotator tool's single target is never re-split, and strict flags are unchanged. The bundle pre-check reads the same words, so "a b.md" "c d.md" now works as a list of files.

• Visible failure. A failed OpenCode 2 slash command (a refused argument or the CLI's startup error) now posts a transcript notice, Plannotator /plannotator-annotate failed: <reason> (createCommandFailureNotifier in v2-client.ts). It uses session.synthetic with a description and resume: false, the mechanism the session-URL notice already uses.

  • Why not session.prompt with queue (the tool's late-failure path)? It would start a model turn, and a slash command must never reach the model unless it says so. The tool uses it because there the agent was told to wait for a decision.
  • The model does not read it. The notice is for the person, so the context hook drops it from model requests, exactly like the URL notice. There is one shared, known gap: a notice that the host promotes alone at an idle boundary stays in that one request.
  • Other hosts. The OpenCode 1 CLI runtime now shows an error toast for the same failures (before, only some review errors had one). Tool launches carry neither notice and keep reporting failures as the tool result. A prompt-delivery failure after a decision is not shown as "failed".

Note: ./ notes.md still does not open notes.md, and that is by design. ./ is an explicit path to a folder, so the CLI reads two targets and gives its ambiguity error, the same as on OpenCode 1's embedded path. The user now sees that error.

Tests

• apps/opencode-plugin/annotate-words-cli.test.ts (new) runs the REAL CLI (apps/hook/server/index.ts) through runNativeCommand, in a sandbox: temp HOME, XDG dirs and data dir.
  • . notes.md, notes.md . and please notes.md open notes.md, and the feedback names it as the target.
  • "my notes.md" please and unquoted my notes.md open the file.
  • A bad path is a synthetic notice with resume: false and no prompt.
  • ./ notes.md shows the ambiguity error.
  • All 6 fail against the old cli-bridge.ts.
• plannotator-tool.test.ts: the "targets" stub now behaves like the real CLI. One argument is one path ("File not found"), and several arguments go through the shared selection. The fix(mod, opencode): name a review by what the CLI opened, not the typed words #1737 test now fails without the fix. The tool's startup-error test also checks that no failure notice is posted.
• Unit tests: annotateTargetWords (quotes, apostrophes, backslashes, flags), annotateCliTargets, and dropping the failure notice from the model context.
• bun test in apps/opencode-plugin (362 pass), apps/pi-extension and the relevant packages/shared tests pass, and bun run typecheck is clean. Not checked against a live OpenCode 2.