Implement GitHub suggestion format instructions (#79)

* implement github suggestion format instructions

add instructions for agents to use github's suggestion format (```suggestion blocks) when providing code suggestions in comments. this enables one-click apply for suggested changes.

updated:
- action/mcp/review.ts: added suggestion format guidance to create_pull_request_review tool description and comment body parameter
- action/mcp/comment.ts: added suggestion format guidance to all comment tools with clarification that suggestions only work on pr line-level review comments
- action/modes.ts: added detailed example in review mode and reminder in address reviews mode

fixes #70

* Address PR review feedback

- Remove suggestion format guidance from report_progress (not applicable)
- De-duplicate description across Comment, EditComment, ReplyToReviewComment
- Drop outer fence in suggestion format example
- Clarify that suggestions only work for self-contained changes
- Remove useless example comment from review tool description

---------

Co-authored-by: pullfrog <team@pullfrog.com>

mcp/comment.ts

@@ -77,6 +77,9 @@ async function buildCommentFooter({
   return buildPullfrogFooter(footerParams);
 }
 
+const SUGGESTION_FORMAT_DESCRIPTION =
+  "when suggesting code changes, use GitHub's suggestion format with ```suggestion blocks to enable one-click apply (e.g., 'you could do this\\n```suggestion\\nsuggested code here\\n```'). note: suggestions only work on pull request line-level review comments, not on issue/PR-level comments.";
+
 function buildImplementPlanLink(
   owner: string,
   repo: string,
@@ -99,7 +102,7 @@ async function addFooter(
 
 export const Comment = type({
   issueNumber: type.number.describe("the issue number to comment on"),
-  body: type.string.describe("the comment body content"),
+  body: type.string.describe(`the comment body content. ${SUGGESTION_FORMAT_DESCRIPTION}`),
 });
 
 export function CreateCommentTool(ctx: ToolContext) {
@@ -130,7 +133,7 @@ export function CreateCommentTool(ctx: ToolContext) {
 
 export const EditComment = type({
   commentId: type.number.describe("the ID of the comment to edit"),
-  body: type.string.describe("the new comment body content"),
+  body: type.string.describe(`the new comment body content. ${SUGGESTION_FORMAT_DESCRIPTION}`),
 });
 
 export function EditCommentTool(ctx: ToolContext) {
@@ -472,7 +475,7 @@ export const ReplyToReviewComment = type({
   pull_number: type.number.describe("the pull request number"),
   comment_id: type.number.describe("the ID of the review comment to reply to"),
   body: type.string.describe(
-    "extremely brief reply (1 sentence max) explaining what was fixed, e.g. 'Fixed by renaming to X' or 'Added null check'"
+    `extremely brief reply (1 sentence max) explaining what was fixed, e.g. 'Fixed by renaming to X' or 'Added null check'. ${SUGGESTION_FORMAT_DESCRIPTION}`
   ),
 });
 

mcp/review.ts

@@ -29,7 +29,7 @@ export const CreatePullRequestReview = type({
       )
       .optional(),
     body: type.string.describe(
-      "The comment text for this specific line. For issues appearing multiple times, comment on the first occurrence and reference others."
+      "The comment text for this specific line. For issues appearing multiple times, comment on the first occurrence and reference others. When providing code suggestions, use GitHub's suggestion format with ```suggestion blocks to enable one-click apply. Only include explanatory text if the suggested code requires clarification."
     ),
     start_line: type.number
       .describe("Start line for multi-line comments (optional, for commenting on ranges)")
@@ -48,7 +48,8 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
     description:
       "Submit a review for an existing pull request. " +
       "IMPORTANT: 95%+ of feedback should be in 'comments' array with file paths and line numbers. " +
-      "Only use 'body' for a 1-2 sentence summary with urgency and critical callouts.",
+      "Only use 'body' for a 1-2 sentence summary with urgency and critical callouts. " +
+      "When suggesting code changes in comments, use GitHub's suggestion format (```suggestion blocks) to enable one-click apply.",
     parameters: CreatePullRequestReview,
     execute: execute(async ({ pull_number, body, commit_id, comments = [] }) => {
       // set PR context