Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,34 @@ approved-with-notes prompts OpenCode and Pi use; plan: `composePlanDeniedMessage
unchanged for every caller. `noop` marks what never starts a turn: Done with
nothing to send, review LGTM, Close, and a review posted straight to the PR
platform (`platform: true`, logged plus a `$.prompt.suggest` to address the
comments).
comments). An annotate Done with nothing to send still posts the legacy
zero-state sentence ("User reviewed the document and has no feedback.") as
`feedback`, because plain stdout, `--json` and the OpenCode/Pi consumers print
or deliver those bytes; the editor additionally marks that body
`nothingToSend: true`, which both annotate servers carry onto the decision only
alongside empty `annotations`/`codeAnnotations` (`isNothingToSendFeedbackBody`,
`packages/shared/annotate-decision.ts`), and `annotateHostResult` turns it into
a `noop` record. Every plugin host that turns a decision into an agent message
skips it the same way: Pi's
`classifyAnnotateOutcome` reads it as "Annotation closed (no feedback).", the
OpenCode embedded handlers (`commands.ts`) send no prompt (on OpenCode 1 the
command's own message still runs its one empty turn, the known OC1 limit; no
second turn is added), and the OpenCode CLI bridge (OpenCode 1 CLI runtime and
OpenCode 2 native commands) reads the additive `nothingToSend: true` the CLI
adds to its `--json` / `opencode-annotate-last` record in that case only, as do
the Amp plugin (`formatAnnotationFeedback`) and the Droid plugin
(`emitAnnotateDecision`), which also read `annotate --json`. Skill-run hosts
(the classic Claude Code skill, Codex, Gemini, Copilot, Vibe, Kiro) still hand
the model the plain-stdout sentence, which is the unchanged stdout contract. The
feedback archive still records a bare Done as `feedback` with the sentence.
Multi-message annotate-last merges SSE external (agent / WebMCP) comments into
the current message's entry (`mergeExternalsIntoMessageEntries`), so they reach
the exported feedback, the submit body and the nothing-to-send check. The mod's `legacyResult` recognizes the two zero-state
sentences printed by a CLI older than the result file (#1701). The submit
body's `annotations` carries every document's comments (folder sessions,
linked documents, every message in multi-message annotate-last;
`collectSubmittedAnnotations` in `packages/editor/feedbackDocuments.ts`), so
`annotationCount` matches the feedback text.

**Version skew.** The plugin installs from the repo's main branch and the
binary updates separately, so with the mod on by default it routinely runs
Expand Down Expand Up @@ -1171,7 +1198,7 @@ The bang prefix in the Claude Code skill is deliberate: #872 (commit `aac5aacb`,

### Strict direct annotate results

Direct `plannotator annotate` invocations may add `--require-approval` and/or `--result-file <path>` only with `--gate --json`; both reject `--hook` and are not shared with OpenCode/Pi slash-command parsing. When neither strict option is present, single-target invocations keep the legacy plaintext, JSON, hook, and exit behavior unchanged; multi-token invocations go through the tolerant tiers described under "Tolerant argument resolution" above.
Direct `plannotator annotate` invocations may add `--require-approval` and/or `--result-file <path>` only with `--gate --json`; both reject `--hook` and are not shared with OpenCode/Pi slash-command parsing. When neither strict option is present, single-target invocations keep the legacy plaintext, JSON, hook, and exit behavior unchanged, with one additive JSON field: a non-gated Done with nothing to send prints `{"decision":"annotated","feedback":"User reviewed the document and has no feedback.","nothingToSend":true}` (the field appears only in that case and only on the non-strict `--json` record and the `opencode-annotate-last` record; decision values, the feedback text, plaintext, `--hook` output, the strict-gate record and every exit code are unchanged; the OpenCode CLI bridge, Amp and Droid read it; #1701). Multi-token invocations go through the tolerant tiers described under "Tolerant argument resolution" above.

Strict decisions use one newline-terminated JSON record on stdout and, when requested, identical bytes in the result file. Exit codes follow the grep convention: approval exits `0`; with `--require-approval`, annotated and dismissed decisions are published before exiting `1` (negative human outcome); usage/startup/validation failures — bad flag combinations, strict flags outside `annotate --gate --json`, a missing `--result-file` parent, a pre-existing or dangling-symlink destination, and every annotate startup failure (missing path, unreachable URL, empty folder, ambiguous name, missing file, oversized file) — exit `2` (the gate itself was misconfigured or could not start). Those startup sites exit `1` as before for non-strict invocations, with one deliberate exception: the multi-token zero-resolve handoff is not a startup failure, so in plain non-strict mode it prints on stdout and exits `0` (under `--json`/`--hook` it stays stderr + exit `1`). Under a strict flag `1` is reserved for "the reviewer did not approve", so a typo'd path must never masquerade as a rejection. Post-decision publication failures (destination appears between validation and publish, hard links unavailable) also exit `2`: the result *file* was not published, so they present as environment errors — "the gate could not publish its result" — never as a reviewer outcome, and never as approval (still fail-closed, since only `0` means approved). The stdout decision record is written **before** result-file publication and is still emitted whenever the decision itself completed; only a stdout write failure leaves no record anywhere. Signal deaths keep `128+n`. Result paths resolve from the invocation working directory, require an existing parent and absent destination, and publish via a flushed/closed `0600` same-directory temporary file plus an atomic no-clobber hard link—never copy or overwrite fallback (the `0600` mode is a no-op on Windows, and the atomic link/rename is not followed by a parent-directory fsync, so publication is atomic but not crash-durable). Keep reviewed sources at stable project paths; unique result and diagnostic log files may use a narrow temporary directory. Explicit Close emits `dismissed`; missing results or process/browser failures are recovery cases, never approval.

Expand Down Expand Up @@ -1456,8 +1483,11 @@ Details that surprise people:
would signal a real shape change rather than the arrival of new keys.
- **Folder-session records name the folder, not the open document.** A folder
annotate session submits one body of feedback for the session, so
`target.filePath` is the session's folder; the per-document path is not part
of the record.
`target.filePath` is the session's folder. The record's `annotations` hold
every document's comments (not only the open one's), and each comment made
on a document other than the session's own target carries the additive
`documentPath` field naming that document (absent means the session's own
target or message; distinct from `file`, a code annotation's file).
- **URL-session records store the full URL, query string included**, because
that is the page that was reviewed. A URL carrying a token in its query is
therefore written to disk; the opt-out is the control for that.
Expand Down
10 changes: 10 additions & 0 deletions apps/amp-plugin/plannotator.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,16 @@ describe("Amp Plannotator registered commands", () => {
const empty = await run(command, JSON.stringify({ decision: "annotated", feedback: "" }));
expect(empty.appended).toEqual([]);
expect(empty.notifications).toEqual([expect.stringMatching(/closed/i)]);

// #1701: a bare Done keeps the zero-state sentence as feedback and
// marks it; it must not become a "please address the feedback" turn.
const done = await run(command, JSON.stringify({
decision: "annotated",
feedback: "User reviewed the document and has no feedback.",
nothingToSend: true,
}));
expect(done.appended).toEqual([]);
expect(done.notifications).toEqual([expect.stringMatching(/closed/i)]);
});
},
);
Expand Down
12 changes: 11 additions & 1 deletion apps/amp-plugin/plannotator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ interface ReviewDecision {
interface AnnotateDecision {
decision: "approved" | "dismissed" | "annotated";
feedback?: string;
/** A Done with nothing to send (#1701): `feedback` is the zero-state
* sentence and nothing is delivered. Absent from an older CLI. */
nothingToSend?: boolean;
}

interface ExitState {
Expand Down Expand Up @@ -210,7 +213,11 @@ function parseAnnotateDecision(raw: string): AnnotateDecision | null {
parsed.decision === "annotated") &&
(parsed.feedback === undefined || typeof parsed.feedback === "string")
) {
return { decision: parsed.decision, feedback: parsed.feedback };
return {
decision: parsed.decision,
feedback: parsed.feedback,
...(parsed.nothingToSend === true && { nothingToSend: true }),
};
}
} catch {
return null;
Expand All @@ -226,6 +233,9 @@ export function formatAnnotationFeedback(
// Approved-with-notes carries reviewer guidance in `feedback` (#1092); only
// dismissed decisions and note-less approvals have nothing to surface.
if (decision.decision !== "annotated" && decision.decision !== "approved") return null;
// A Done with nothing to send carries the zero-state sentence as feedback;
// there is nothing for the agent (#1701).
if (decision.decision === "annotated" && decision.nothingToSend === true) return null;

const feedback = decision.feedback?.trim();
if (!feedback) return null;
Expand Down
4 changes: 3 additions & 1 deletion apps/droid-plugin/lib/run-plannotator.js
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,9 @@ function emitAnnotateDecision(rawOutput, heading) {

if (parsed.decision === "annotated") {
const feedback = typeof parsed.feedback === "string" ? parsed.feedback.trim() : "";
if (!feedback) {
// A Done with nothing to send (#1701): the zero-state sentence rides
// `feedback`, and nothing should reach the agent.
if (!feedback || parsed.nothingToSend === true) {
process.stdout.write("Annotation session closed.\n");
return;
}
Expand Down
10 changes: 10 additions & 0 deletions apps/droid-plugin/lib/run-plannotator.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,16 @@ describe("emitAnnotateDecision", () => {
);
});

// #1701: a bare Done keeps the zero-state sentence as feedback and marks
// it; it must not be framed as feedback for the agent to address.
test("a Done with nothing to send closes the session", () => {
emitAnnotateDecision(
'{"decision":"annotated","feedback":"User reviewed the document and has no feedback.","nothingToSend":true}',
"Markdown Annotations",
);
expect(output()).toBe("Annotation session closed.\n");
});

test("empty output closes the session", () => {
emitAnnotateDecision("", "Markdown Annotations");
expect(output()).toBe("Annotation session closed.\n");
Expand Down
39 changes: 39 additions & 0 deletions apps/hook/hooks/mod/controller.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -526,6 +526,45 @@ describe('a CLI older than the host result file', () => {
expect(host.submits[0]).toContain('Line 3: wrong date')
expect(host.logs.some((line) => line.includes('b.md closed with no annotations'))).toBe(true)
})

// #1701: what such a CLI prints for an annotate Done with nothing to send.
test('its printed zero-feedback sentence starts no turn', async () => {
const host = fakeHost()
serveOnLaunch(host)
const mod = new PlannotatorMod(host, SESSION)
await mod.runCommand('annotate', 'notes.md')
const [launch] = launches(host)
host.files.set(`${launchDirOf(launch!)}/stdout`, 'User reviewed the document and has no feedback.\n')
host.files.set(`${launchDirOf(launch!)}/exit`, '0')

await host.tick()

expect(host.submits).toEqual([])
expect(host.logs.some((line) => line.includes('notes.md closed with no annotations'))).toBe(true)
})
})

// #1701, end to end over the record the CLI builds: the editor's Done posts the
// zero-state sentence as feedback, marked nothingToSend; the session must not
// receive a "please address the annotation feedback" turn.
describe('annotate Done with nothing to send (CLI record → mod)', () => {
test('logs, never submits', async () => {
const { annotateHostResult } = await import('../../server/host-result')
const host = fakeHost()
serveOnLaunch(host)
const mod = new PlannotatorMod(host, SESSION)
await mod.runCommand('annotate', 'notes.md')
const record = annotateHostResult(
{ feedback: 'User reviewed the document and has no feedback.', annotations: [], nothingToSend: true },
{ kind: 'file', target: '/repo/notes.md' },
)
decide(host, launches(host)[0]!, record as unknown as Record<string, unknown>)

await host.tick()

expect(host.submits).toEqual([])
expect(host.logs.some((line) => line.includes('notes.md closed with no annotations'))).toBe(true)
})
})

describe('restore', () => {
Expand Down
17 changes: 17 additions & 0 deletions apps/hook/hooks/mod/delivery.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test'
import { DEFAULT_REVIEW_APPROVED_PROMPT, DEFAULT_REVIEW_APPROVED_WITH_NOTES_PROMPT } from '@plannotator/shared/prompts'
import {
deliveryFor,
LEGACY_ANNOTATE_NO_FEEDBACK_TEXTS,
LEGACY_REVIEW_APPROVED_TEXT,
LEGACY_REVIEW_APPROVED_WITH_NOTES_HEADING,
legacyResult,
Expand All @@ -10,6 +11,8 @@ import {
type HostResultRecord,
} from './delivery'
import { splitShellWords } from './shell-words'
import { ANNOTATE_NO_FEEDBACK_SENTENCE } from '../../../../packages/editor/annotateSubmission'
import { exportMessageAnnotations } from '@plannotator/ui/utils/parser'

const CONTEXT = { subject: 'notes.md', overflowPath: '/data/x/feedback.md' }

Expand Down Expand Up @@ -81,6 +84,20 @@ describe('legacyResult (a CLI that predates the host result file)', () => {
expect(deliveryFor(legacyResult('annotate', ''), CONTEXT).action).toBe('log')
})

test('an annotate Done with nothing to send starts no turn', () => {
for (const text of LEGACY_ANNOTATE_NO_FEEDBACK_TEXTS) {
expect(deliveryFor(legacyResult('annotate', `${text}\n`), CONTEXT).action).toBe('log')
expect(deliveryFor(legacyResult('last', text), CONTEXT).action).toBe('log')
}
// Only an annotate sentence: a review's stdout never carries it.
expect(deliveryFor(legacyResult('review', LEGACY_ANNOTATE_NO_FEEDBACK_TEXTS[0]!), CONTEXT).action).toBe('submit')
})

// The mod cannot import the editor: its copies must follow the editor's payloads.
test('the recognized no-feedback texts are what the editor posts', () => {
expect([...LEGACY_ANNOTATE_NO_FEEDBACK_TEXTS]).toEqual([ANNOTATE_NO_FEEDBACK_SENTENCE, exportMessageAnnotations([])])
})

// The mod cannot import packages/shared: its copies must follow the CLI's defaults.
test('the recognized approval texts are the CLI defaults', () => {
expect(LEGACY_REVIEW_APPROVED_TEXT).toBe(DEFAULT_REVIEW_APPROVED_PROMPT)
Expand Down
15 changes: 15 additions & 0 deletions apps/hook/hooks/mod/delivery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,18 @@ export function deliveryFor(record: HostResultRecord, context: DeliveryContext):
export const LEGACY_REVIEW_APPROVED_TEXT = '# Code Review\n\nCode review completed — no changes requested.'
export const LEGACY_REVIEW_APPROVED_WITH_NOTES_HEADING = '# Code Review — Approved with Notes'

/**
* What the editor posts, and an annotate CLI prints, for a Done with nothing
* to send (`ANNOTATE_NO_FEEDBACK_SENTENCE` in packages/editor/annotateSubmission.ts
* and the multi-message variant in packages/ui/utils/parser.ts; delivery.test.ts
* keeps them equal). A newer CLI marks that decision `noop` in its result
* record; an older one only prints the sentence.
*/
export const LEGACY_ANNOTATE_NO_FEEDBACK_TEXTS: readonly string[] = [
'User reviewed the document and has no feedback.',
'User reviewed the messages and has no feedback.',
]

/**
* A CLI that predates the host result file (the plugin and the binary update
* separately): what it printed on stdout, the text the skill would have shown
Expand All @@ -157,6 +169,9 @@ export function legacyResult(kind: SessionKind, printed: string): HostResultReco
return { v: 1, surface, decision: 'dismissed', message: '', noop: true }
}
if (text === 'The user approved.') return { v: 1, surface, decision: 'approved', message: '', noop: true }
if (surface !== 'review' && LEGACY_ANNOTATE_NO_FEEDBACK_TEXTS.includes(text)) {
return { v: 1, surface, decision: 'annotated', message: '', noop: true }
}
if (surface === 'review' && text === LEGACY_REVIEW_APPROVED_TEXT) {
return { v: 1, surface, decision: 'approved', message: '', noop: true }
}
Expand Down
Loading
Loading