feat(annotate): add --silent-approve flag for naive hook compatibility

Hooks that treat any non-empty stdout as a block signal (spec-kit
PostToolUse pattern) need Approve to emit empty stdout. The default
--gate behavior emits "The user approved." so slash command templates
can distinguish approve from close in plaintext. --silent-approve
suppresses that marker, restoring silence-is-permission for hook
authors. No effect in --json mode.

Includes: shared parser update (FLAG_MAP refactor), 4 new tests,
docs for annotate, annotate-last, hook-integration, and gates guide.

For provenance purposes, this commit was AI assisted.

Author: backnotprop

apps/hook/server/index.ts

@@ -126,21 +126,29 @@ const cliNoJina = noJinaIdx !== -1;
 if (cliNoJina) args.splice(noJinaIdx, 1);
 
 // Annotate review-gate flags (#570): --gate adds an Approve button,
-// --json switches stdout to structured decision output.
+// --json switches stdout to structured decision output, --silent-approve
+// suppresses the plaintext approve marker (naive hooks that treat any
+// stdout as a block signal opt in here to keep silence-is-permission).
 const gateIdx = args.indexOf("--gate");
 const gateFlag = gateIdx !== -1;
 if (gateFlag) args.splice(gateIdx, 1);
 const jsonIdx = args.indexOf("--json");
 const jsonFlag = jsonIdx !== -1;
 if (jsonFlag) args.splice(jsonIdx, 1);
+const silentApproveIdx = args.indexOf("--silent-approve");
+const silentApproveFlag = silentApproveIdx !== -1;
+if (silentApproveFlag) args.splice(silentApproveIdx, 1);
 
 // Stdout matrix for annotate / annotate-last / copilot annotate-last (#570).
 // Plaintext mode:
 //   - Close emits empty stdout (naive PostToolUse / Stop hooks: empty = allow).
 //   - Approve emits "The user approved." so agents and templates can
-//     distinguish approval from close without needing --json.
+//     distinguish approval from close without needing --json. With
+//     --silent-approve, Approve also emits empty stdout (hook-friendly).
 //   - Send Annotations emits the plaintext feedback markdown.
-// --json switches to structured output across all three decisions.
+// --json switches to structured output across all three decisions;
+// --silent-approve has no effect in --json mode (JSON always routes by
+// decision field, so there's no ambiguity to silence).
 export const APPROVED_PLAINTEXT_MARKER = "The user approved.";
 
 function emitAnnotateOutcome(result: {
@@ -160,7 +168,7 @@ function emitAnnotateOutcome(result: {
   }
   if (result.exit) return; // empty stdout on close
   if (result.approved) {
-    console.log(APPROVED_PLAINTEXT_MARKER);
+    if (!silentApproveFlag) console.log(APPROVED_PLAINTEXT_MARKER);
     return;
   }
   if (result.feedback) console.log(result.feedback);

apps/marketing/src/content/docs/commands/annotate-last.md

@@ -75,7 +75,7 @@ The annotation UI in `annotate-last` mode works the same as `/plannotator-annota
 
 ## Flags
 
-`plannotator annotate-last` accepts the same `--gate` and `--json` flags as `plannotator annotate`. See [Annotate → Flags](/docs/commands/annotate/#flags) for the full matrix.
+`plannotator annotate-last` accepts the same `--gate`, `--json`, and `--silent-approve` flags as `plannotator annotate`. See [Annotate → Flags](/docs/commands/annotate/#flags) for the full matrix.
 
 The common use case for `--gate` on annotate-last is a turn-by-turn review gate wired to a Stop hook:
 

apps/marketing/src/content/docs/commands/annotate.md

@@ -103,7 +103,7 @@ All annotation types work identically: deletions, replacements, comments, insert
 
 ## Flags
 
-Two opt-in flags turn annotate into a review gate for hook integrations (spec-driven frameworks, turn-by-turn review, and so on). They are orthogonal: you can use either alone or combine them.
+Three opt-in flags turn annotate into a review gate for hook integrations (spec-driven frameworks, turn-by-turn review, and so on). They compose: use any alone or combine them.
 
 ### `--gate`
 
@@ -123,18 +123,25 @@ Switches stdout to a structured decision object so hooks can route programmatica
 
 `feedback` is only present when `decision === "annotated"`.
 
+### `--silent-approve`
+
+Suppresses the plaintext approve marker so Approve emits empty stdout instead of `The user approved.`. Use this with naive hooks that treat any non-empty stdout as a block signal. Approve and Close both become silent, and only Send Annotations blocks with feedback (silence-is-permission).
+
+`--silent-approve` only affects plaintext mode. In `--json` mode, Approve continues to emit `{"decision":"approved"}` — JSON callers route on the `decision` field, so there's no ambiguity to silence.
+
 ### Stdout matrix
 
 | Flags | UX | Approve | Close | Send Annotations |
 |---|---|---|---|---|
 | *(none)* | 2-button | n/a | empty | feedback (plaintext) |
 | `--gate` | 3-button | `The user approved.` | empty | feedback (plaintext) |
+| `--gate --silent-approve` | 3-button | empty | empty | feedback (plaintext) |
 | `--json` | 2-button | n/a | `{"decision":"dismissed"}` | `{"decision":"annotated","feedback":"..."}` |
 | `--gate --json` | 3-button | `{"decision":"approved"}` | `{"decision":"dismissed"}` | `{"decision":"annotated","feedback":"..."}` |
 
-**Key property:** `--gate` plaintext output is unambiguous across all three decisions. Close is empty, Send Annotations is feedback markdown, Approve is the exact line `The user approved.` — each case distinguishable without JSON parsing. Use `--json` when you want machine-readable decision objects instead of string matching.
+**Key property:** `--gate` plaintext output is unambiguous across three decisions — Close is empty, Send Annotations is feedback markdown, Approve is the line `The user approved.`. Drop the marker with `--silent-approve` when your hook treats any stdout as a block. Use `--json` when you want machine-readable decision objects instead of string matching.
 
-On OpenCode and Pi, `--json` is silently accepted because those harnesses write back into the session directly rather than via stdout. The `--gate` flag behaves identically across all three harnesses.
+On OpenCode and Pi, `--json` and `--silent-approve` are silently accepted because those harnesses write back into the session directly rather than via stdout. The `--gate` flag behaves identically across all three harnesses.
 
 See [Hook integration recipes](/docs/guides/hook-integration/) for ready-to-use PostToolUse and Stop hook examples.
 

apps/marketing/src/content/docs/guides/annotate-gates-and-json-responses.md

@@ -1,29 +1,31 @@
 ---
 title: "Annotate Gates and JSON Responses"
-description: "The --gate and --json flags extend plannotator annotate from a feedback tool into a structured review gate with machine-readable decisions. Use them to wire Plannotator into spec-driven workflows, Stop hooks, and agent pipelines."
+description: "The --gate, --json, and --silent-approve flags extend plannotator annotate from a feedback tool into a structured review gate with machine-readable decisions. Use them to wire Plannotator into spec-driven workflows, Stop hooks, and agent pipelines."
 sidebar:
   order: 28
 section: "Guides"
 ---
 
-`plannotator annotate` and `plannotator annotate-last` accept two flags that turn markdown annotation into a full review gate with structured output.
+`plannotator annotate` and `plannotator annotate-last` accept three flags that turn markdown annotation into a full review gate with structured output.
 
 ## Capabilities
 
 - **`--gate`** adds an Approve button to the annotation UI. The reviewer picks one of three decisions: approve, send annotations, or close.
 - **`--json`** emits every decision as a structured JSON object on stdout so hooks and plugins can route on the outcome without parsing free text.
-- The flags compose. Use them together, separately, or not at all.
+- **`--silent-approve`** suppresses the plaintext approve marker so Approve emits empty stdout. Naive hooks that treat any stdout as a block signal opt in here to keep silence-is-permission intact.
+- The flags compose. Use any alone or together.
 - Identical semantics across every supported harness: Claude Code, Copilot CLI, Gemini CLI, OpenCode, Pi, and Codex.
 
 ## Stdout contract
 
 ```
-     Flags      │        UX        │         Approve         │          Close           │                 Annotate
-─────────────── ┼──────────────────┼─────────────────────────┼──────────────────────────┼───────────────────────────────────────────────
- (none)         │  2-button        │  n/a                    │  empty                   │  feedback (plaintext)
- --gate         │  3-button        │  `The user approved.`   │  empty                   │  feedback (plaintext)
- --json         │  2-button        │  n/a                    │  {"decision":"dismissed"}│  {"decision":"annotated","feedback":"..."}
- --gate --json  │  3-button        │  {"decision":"approved"}│  {"decision":"dismissed"}│  {"decision":"annotated","feedback":"..."}
+          Flags           │        UX        │         Approve         │          Close           │                 Annotate
+──────────────────────────┼──────────────────┼─────────────────────────┼──────────────────────────┼───────────────────────────────────────────────
+ (none)                   │  2-button        │  n/a                    │  empty                   │  feedback (plaintext)
+ --gate                   │  3-button        │  `The user approved.`   │  empty                   │  feedback (plaintext)
+ --gate --silent-approve  │  3-button        │  empty                  │  empty                   │  feedback (plaintext)
+ --json                   │  2-button        │  n/a                    │  {"decision":"dismissed"}│  {"decision":"annotated","feedback":"..."}
+ --gate --json            │  3-button        │  {"decision":"approved"}│  {"decision":"dismissed"}│  {"decision":"annotated","feedback":"..."}
 ```
 
 ### JSON schema
@@ -68,7 +70,7 @@ A three-way review decision. The annotation UI adds an Approve button alongside
 - **Send Annotations.** The reviewer has specific changes. The feedback is returned verbatim.
 - **Close.** The session ends without a decision. Neither a signal to the agent nor an instruction set.
 
-In plaintext mode, Approve emits the single line `The user approved.` on stdout so templates and agents can distinguish approval from close without needing `--json`. Close emits nothing. Send Annotations emits the feedback markdown. Hook authors who treat any non-empty stdout as a block signal need to filter the approve marker (or use `--json` for cleaner routing).
+In plaintext mode, Approve emits the single line `The user approved.` on stdout so templates and agents can distinguish approval from close without needing `--json`. Close emits nothing. Send Annotations emits the feedback markdown. Hook authors who treat any non-empty stdout as a block signal can add `--silent-approve` to suppress the marker, or use `--json` for structured routing.
 
 ## `--json`
 
@@ -80,6 +82,18 @@ Structured stdout. Every decision is emitted as a JSON object with a `decision`
 - `--gate --json` unlocks all three decisions in structured form.
 - On OpenCode and Pi, `--json` is accepted silently. Those harnesses write back to the session directly rather than via stdout, so the flag has no effect there. Recipes remain portable.
 
+## `--silent-approve`
+
+Suppresses the plaintext approve marker. With `--gate --silent-approve`, Approve emits empty stdout (instead of `The user approved.`), matching Close. Send Annotations still emits feedback.
+
+This is the shape naive hooks want — the ones that treat any non-empty stdout as a block signal:
+
+- Approve → empty → hook passes → agent proceeds.
+- Close → empty → hook passes → agent proceeds.
+- Send Annotations → feedback → hook blocks with that feedback as the reason.
+
+`--silent-approve` only affects plaintext mode. In `--json` mode, Approve still emits `{"decision":"approved"}` — JSON callers route on the `decision` field, so there's no ambiguity to silence. The flag is accepted silently on OpenCode and Pi for the same reason `--json` is: those harnesses don't use stdout as the signal channel.
+
 ## Primary use cases
 
 ### Spec-driven development frameworks

apps/marketing/src/content/docs/guides/hook-integration.md

@@ -6,13 +6,14 @@ sidebar:
 section: "Guides"
 ---
 
-The `--gate` and `--json` flags on `plannotator annotate` and `plannotator annotate-last` turn annotation into a structured review decision. This guide shows how to wire them into agent hooks so a human can gate the agent at specific points in a workflow.
+The `--gate`, `--json`, and `--silent-approve` flags on `plannotator annotate` and `plannotator annotate-last` turn annotation into a structured review decision. This guide shows how to wire them into agent hooks so a human can gate the agent at specific points in a workflow.
 
 See [Annotate → Flags](/docs/commands/annotate/#flags) for the full stdout matrix. The short version:
 
 - `--gate` adds a three-button UX (Approve / Send Annotations / Close).
-- Without `--json`: Approve emits the line `The user approved.`, Close emits empty stdout, Send Annotations emits the feedback markdown. Three distinguishable outputs without parsing JSON.
-- With `--json`: every decision emits a structured `{ "decision": "approved" | "annotated" | "dismissed", "feedback": "..." }` object.
+- Plaintext default: Approve emits the line `The user approved.`, Close emits empty stdout, Send Annotations emits the feedback markdown. Three distinguishable outputs without parsing JSON.
+- `--silent-approve` collapses Approve to empty stdout, matching Close. Use this with naive "any stdout = block" hooks so silence means permission.
+- `--json` emits every decision as a structured `{ "decision": "approved" | "annotated" | "dismissed", "feedback": "..." }` object.
 
 ## Recipe 1: PostToolUse spec gate
 
@@ -47,7 +48,21 @@ Behavior:
 - **Send Annotations** → feedback markdown on stdout. Claude Code reports the feedback back.
 - **Close** → empty stdout. Claude Code proceeds silently.
 
-If your hook treats any non-empty stdout as a block signal (some scripts do), filter the approve marker explicitly, or use the `--json` recipe below to route on the parsed decision instead.
+### Silence-is-permission (`--silent-approve`)
+
+If your hook treats any non-empty stdout as a block signal (spec-kit and similar naive PostToolUse hooks), add `--silent-approve` so Approve also emits empty stdout:
+
+```json
+"command": "plannotator annotate \"$CLAUDE_TOOL_INPUT_file_path\" --gate --silent-approve"
+```
+
+Behavior with the flag:
+
+- **Approve** → empty stdout → hook passes → agent proceeds.
+- **Close** → empty stdout → hook passes → agent proceeds.
+- **Send Annotations** → feedback on stdout → hook blocks with feedback as the reason.
+
+Approve and Close collapse into the same "silent = allow" cell, which is what this class of hook expects. Only Send Annotations carries content the agent needs to react to.
 
 ### Structured (`--json`)
 
@@ -104,6 +119,8 @@ Behavior:
 - **Send Annotations** → feedback on stdout → Claude Code re-prompts with the feedback.
 - **Close** → empty stdout → turn ends.
 
+Add `--silent-approve` if your Stop hook treats any stdout as a re-prompt trigger — Approve then emits empty stdout too, so only Send Annotations re-fires the turn with feedback.
+
 ### Structured
 
 Same pattern as the PostToolUse recipe — pipe `--gate --json` through a shell wrapper if you want distinct handling per decision.
@@ -116,7 +133,7 @@ The same `--gate` flag works in OpenCode's `/plannotator-annotate` and Pi's `/pl
 /plannotator-annotate spec.md --gate
 ```
 
-On those harnesses there is no stdout channel back to the agent — the plugin writes back via `session.prompt` (OpenCode) or `sendUserMessage` (Pi). Approve and Close both result in no session injection; Send Annotations injects the feedback. `--json` is accepted silently on these harnesses so recipes stay portable.
+On those harnesses there is no stdout channel back to the agent — the plugin writes back via `session.prompt` (OpenCode) or `sendUserMessage` (Pi). Approve and Close both result in no session injection; Send Annotations injects the feedback. `--json` and `--silent-approve` are accepted silently on these harnesses so recipes stay portable.
 
 Third-party Pi or OpenCode plugins that want explicit decision routing can read `approved` directly from the server's decision object: