fix(agent): Hyperlink pull requests in agent replies (#3208)

Author: charlesvien

packages/agent/src/adapters/claude/session/instructions.ts

@@ -6,6 +6,12 @@ When working in a detached HEAD state, create a descriptive branch name based on
 When creating a new branch, prefix it with \`posthog-code/\` (e.g. \`posthog-code/fix-login-redirect\`).
 `;
 
+const PULL_REQUEST_LINKS = `
+# Pull Request Links
+
+When you mention a pull request in any reply or summary, always hyperlink it to its full URL (e.g. a Markdown link like [#123](https://github.com/org/repo/pull/123)) rather than plain text, so readers can open it directly.
+`;
+
 const PLAN_MODE = `
 # Plan Mode
 
@@ -26,4 +32,5 @@ If an MCP tool call is explicitly denied with a message, relay that denial messa
 If an MCP tool call returns an error, treat it as a normal tool error — troubleshoot, retry, or inform the user about the specific error. Do NOT assume it is a permissions issue and do NOT direct the user to any settings page.
 `;
 
-export const APPENDED_INSTRUCTIONS = BRANCH_NAMING + PLAN_MODE + MCP_TOOLS;
+export const APPENDED_INSTRUCTIONS =
+  BRANCH_NAMING + PULL_REQUEST_LINKS + PLAN_MODE + MCP_TOOLS;

packages/agent/src/server/agent-server.ts

@@ -2659,6 +2659,12 @@ we want:
   Generated-By: PostHog Code
   Task-Id: ${taskId}`;
 
+    const prLinkInstructions = `
+## Referencing pull requests
+When you mention a pull request in any reply or summary, always hyperlink it to its full URL
+(e.g. a Markdown link like [#123](https://github.com/org/repo/pull/123)) rather than plain
+text, so readers can open it directly.`;
+
     const whyContextInstruction = `   - Add a brief **Why** to the body — one or two sentences capturing the reason the user asked for this change (the motivation, not a restatement of the diff). Keep it short.`;
     const publicRepoSafetyInstruction = `   - **Public-repo safety.** Treat the target repository as public-readable unless you have verified otherwise. The PR title, description, and commit messages must not contain private operational scale (exact event counts, internal row volumes, customer-usage percentages), customer names / emails / companies, references to internal tickets or incidents, the contents of Slack threads (do not quote or paraphrase what was said), or unreleased roadmap details. Linking to the originating Slack thread is fine and encouraged — Slack links are auth-gated and useful as context — as are channel references like "raised in #team-foo". Describe findings qualitatively ("present on nearly all X events, absent from Y") rather than with quantitative figures pulled from analytics queries — the reasoning that uses those numbers can stay in the thread; the PR copy cannot.`;
     // Slack- and inbox-originated PRs are attributed to PostHog, not the
@@ -2685,7 +2691,7 @@ Do the requested work, but stop with local changes ready for review.
 Important:
 - Do NOT create new commits, push to the branch, or update the pull request unless the user explicitly asks.
 - Do NOT create a new branch or a new pull request.
-${signedCommitInstructions}
+${signedCommitInstructions}${prLinkInstructions}
 `;
       }
 
@@ -2706,7 +2712,7 @@ After completing the requested changes:
 Important:
 - Do NOT create a new branch or a new pull request.
 - Do NOT push fixes for review comments without replying to and resolving each related thread.
-${signedCommitInstructions}
+${signedCommitInstructions}${prLinkInstructions}
 `;
     }
 
@@ -2745,7 +2751,7 @@ ${publishInstructions}
 
 Important:
 - Prefer using MCP tools to answer questions with real data over giving generic advice.
-${signedCommitInstructions}
+${signedCommitInstructions}${prLinkInstructions}
 `;
     }
 
@@ -2757,7 +2763,7 @@ Do the requested work, but stop with local changes ready for review.
 
 Important:
 - Do NOT create a branch, commit, push, or open a pull request unless the user explicitly asks.
-${signedCommitInstructions}
+${signedCommitInstructions}${prLinkInstructions}
 `;
     }
 
@@ -2784,7 +2790,7 @@ ${prFooter}
 
 Important:
 - Always create the PR as a draft. Do not ask for confirmation.
-${signedCommitInstructions}
+${signedCommitInstructions}${prLinkInstructions}
 `;
   }
 

packages/workspace-server/src/services/agent/agent.ts

@@ -603,7 +603,9 @@ When creating pull requests, add the following footer at the end of the PR descr
 \`\`\`
 ---
 *Created with [PostHog Code](https://posthog.com/code?ref=pr)*
-\`\`\``;
+\`\`\`
+
+When you mention a pull request in any reply or summary, always hyperlink it to its full URL (e.g. a Markdown link like [#123](https://github.com/org/repo/pull/123)) rather than plain text, so readers can open it directly.`;
 
     if (channelMode) {
       const localFolders = (knownLocalFolders ?? []).filter(