Update safe outputs spec with discussions field from PR #16509

[Copilot]

The Safe Outputs specification was not documenting the optional discussions field added in PR #16509, which controls whether discussions:write permission is requested for add-comment and hide-comment safe output types.

Changes

• Version: Incremented to 1.13.0 with publication date 2026-02-18

• add_comment type documentation:

  • Added discussions to configuration parameters
  • Updated MCP tool schema description with permission note
  • Clarified conditional discussions:write permission in Required Permissions section
  • Added "Permission Control via discussions Field" subsection with example

• hide_comment type documentation:

  • Added Configuration Parameters section (previously missing)
  • Documented discussions field with same semantics as add_comment
  • Updated Required Permissions with conditional logic
  • Added configuration example

• Configuration examples (Section 5.4):

  • Added discussions: false to Comment Extensions example

• Change log: Added Version 1.13.0 entry in Appendix F

Example Configuration

safe-outputs:
  app:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
  add-comment:
    max: 1
    discussions: false  # Excludes discussions:write for Apps without Discussions permission

Default behavior: discussions: true (or omitted) includes discussions:write for backward compatibility
Opt-out behavior: discussions: false excludes discussions:write to prevent 422 errors when GitHub App lacks Discussions permission

Original prompt

Update safe outputs spec baesed on #16509

Custom agent used: w3c-specification-writer
AI technical specification writer following W3C conventions and best practices for formal specifications

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

Updates the Safe Outputs MCP Gateway specification to document the optional discussions configuration field for add-comment and hide-comment, which controls whether discussions: write permission is requested.

Changes:

• Bumps spec version to 1.13.0 and updates publication date to 2026-02-18
• Documents the discussions field for add_comment / hide_comment, including conditional permissions and examples
• Adds a 1.13.0 entry to Appendix F (Document History)

Comments suppressed due to low confidence (1)

docs/src/content/docs/reference/safe-outputs-specification.md:2576

• Similar to add_comment, this section should explicitly document the behavioral consequence of discussions: false: hiding/minimizing comments on discussions will not work without discussions: write. Consider adding a short note that opting out must only be used when you will not target discussion comments (otherwise the operation will fail).

The optional `discussions` boolean field controls whether `discussions:write` permission is requested:

- **Default behavior** (`discussions: true` or omitted): Includes `discussions:write` permission for maximum compatibility. Use this when the GitHub App has Discussions permission granted.
- **Opt-out** (`discussions: false`): Excludes `discussions:write` permission. Use this when the GitHub App lacks Discussions permission to prevent 422 errors during token generation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new discussions opt-out is documented as a permissions toggle, but this section doesn’t explicitly state the functional impact: with discussions: false, operations that target discussions (e.g., target: "discussion" or target: "*" when the resolved item is a discussion) will fail due to missing discussions: write. Please add a clear note about this incompatibility and recommend setting target to exclude discussions when opting out.

This issue also appears on line 2572 of the same file.

[Copilot]

In Appendix F, the entry refers to safe output types as add-comment / hide-comment, but elsewhere in the document history and type definitions the canonical identifiers use underscores (e.g., add_comment). For consistency and to avoid ambiguity between type IDs vs YAML keys, consider using add_comment / hide_comment here (or explicitly label them as configuration keys if you intend the hyphenated form).

Suggested change

	- **Added**: Optional `discussions` field for `add-comment` and `hide-comment` safe output types to control `discussions:write` permission
	- **Enhanced**: Permission documentation for `add-comment` and `hide-comment` to explain conditional `discussions:write` inclusion
	- **Added**: Configuration examples demonstrating `discussions: false` usage for GitHub Apps without Discussions permission
	- **Fixed**: Issue where `add-comment` and `hide-comment` unconditionally requested `discussions:write` permission, causing 422 errors for GitHub Apps lacking Discussions permission
	- **Added**: Optional `discussions` field for `add_comment` and `hide_comment` safe output types to control `discussions:write` permission
	- **Enhanced**: Permission documentation for `add_comment` and `hide_comment` to explain conditional `discussions:write` inclusion
	- **Added**: Configuration examples demonstrating `discussions: false` usage for GitHub Apps without Discussions permission
	- **Fixed**: Issue where `add_comment` and `hide_comment` unconditionally requested `discussions:write` permission, causing 422 errors for GitHub Apps lacking Discussions permission