[feature]: add GitHub PR auto-review workflow via webhooks and agent reviews

[potlock-support]

1. Summary

Add an automatic GitHub pull request review workflow so FoxFang can receive PR webhooks, trigger an agent review, and post the review back to GitHub.

---

2. Problem

FoxFang does not currently provide a first-class workflow for automatic PR review.

• There is no dedicated PR retrieval tool for fetching metadata, changed files, and patches.
• There is no dedicated PR review posting tool for submitting comments, approvals, or change requests.
• There is no webhook-driven workflow to trigger an agent automatically when a PR is opened or updated.

---

3. Why it matters

A webhook-driven PR review flow would make FoxFang much more useful for engineering workflows.

• User impact: users can get faster, automated PR reviews without manually prompting an agent each time.
• Developer impact: the repo gains a reusable review pipeline that connects GitHub events to agent actions.
• Business impact (if applicable): improves FoxFang’s usefulness as an engineering assistant and expands GitHub workflow support.

---

4. Proposed Solution

Add a GitHub PR auto-review workflow to FoxFang built around GitHub App webhooks and new PR-specific GitHub tools.

Flow (if applicable)

1. GitHub sends a pull_request webhook when a PR is opened, synchronized, or reopened.
2. FoxFang validates the webhook and enqueues a system event for the agent.
3. The agent fetches the PR diff, reviews the changes, and posts a GitHub PR review.

Example

A pull request is opened in PotLock/foxfang. FoxFang receives the webhook, wakes the agent, fetches the PR files and patches, generates a review summary, and posts a GitHub review comment automatically.

---

5. Implementation Approach

Implement this in a few focused parts.

• Add new GitHub tools such as github_get_pr, github_add_pr_review, and github_list_prs.
• Add a webhook handler for GitHub pull request events with signature verification.
• Add agent workflow instructions so PR review behavior is automatic and consistent.

---

6. Alternatives Considered

Other approaches that were considered

Option	Reason rejected
Manual PR review only	Too much repeated manual prompting and no automation benefit
Polling GitHub for PR changes	Less efficient and less reliable than webhook-driven triggers
Reusing issue-only GitHub tooling	Does not cover PR diffs, PR review APIs, or webhook workflows cleanly

---

7. Acceptance Criteria

Conditions for this issue to be considered complete

• A GitHub App webhook can trigger FoxFang on pull request events.
• FoxFang can fetch PR metadata, changed files, and patches through dedicated GitHub tools.
• FoxFang can post a PR review with comment, approve, or request-changes behavior.

---

8. Scope

In scope

• GitHub PR retrieval tools
• GitHub PR review posting tools
• GitHub webhook route and signature verification
• agent-triggered PR review workflow
• config support for webhook secret handling

Out of scope

• full CI pipeline orchestration
• browser-based GitHub interactions
• advanced review assignment logic beyond basic webhook-driven review flow

---

9. Risks & Mitigations

• Risk: webhook security could be implemented incorrectly.

• Mitigation: require HMAC-SHA256 validation and reject invalid signatures.

• Risk: automated reviews may create noisy or low-quality feedback.

• Mitigation: keep review instructions concise and default to structured, useful summaries.

---

10. Rollback Plan

What to do if this needs to be reverted?

• disable the webhook route
• remove or unregister the new GitHub PR tools
• fall back to manual review workflows

---

11. Breaking Changes?

• No
• If yes: describe

---

12. Additional Notes

Links, references, or extra context (optional)

Relevant implementation areas mentioned in the plan:

• extensions/github/src/config.ts
• extensions/github/index.ts
• extensions/github/foxfang.plugin.json
• extensions/github/src/github-app-auth.ts
• src/infra/system-events.ts

---

13. Tasks (optional)

• Add github_get_pr
• Add github_add_pr_review
• Add github_list_prs
• Add GitHub webhook handler
• Add config support for webhook secret
• Add agent PR review workflow instructions
• Verify end-to-end PR review flow