ci: fix Claude Code Review workflow to post PR comments

The Claude Code Review workflow was not posting comments on PRs due to:
1. Insufficient permissions: pull-requests: read (needs write to post)
2. Max turns exhaustion: Claude ran out of 5 turns before posting
3. No guidance for fork PR behavior

Changes:
- Update permissions from pull-requests: read to pull-requests: write
  to allow posting PR review comments
- Increase max-turns from 5 to 10 to ensure Claude completes review
  and successfully posts the comment
- Add comprehensive documentation about fork PR approval requirements
  and setup instructions for maintainers
- Add inline comment explaining the permission change

This fixes the issue where Claude would analyze PRs but never post
the review comments. With write permissions and more turns, Claude
can now complete the review cycle and post feedback.

Fork PRs will require manual approval by maintainers (security best
practice to prevent secret exfiltration).

Related: #722

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: tianjianjiang

.github/workflows/claude-code-review.yml

@@ -14,16 +14,21 @@ on:
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    # Note: For pull requests from forks, this workflow requires manual approval
+    # by a repository maintainer before it will run. This is a security measure
+    # to prevent malicious actors from accessing repository secrets.
+    #
+    # To enable fork PR reviews:
+    # 1. Go to Settings → Actions → General
+    # 2. Under "Fork pull request workflows from outside collaborators"
+    # 3. Select "Require approval for all outside collaborators"
+    #
+    # Maintainers: Review the PR code first, then approve the workflow run if safe.
 
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
+      pull-requests: write  # Changed from read to write - needed to post PR comments
       issues: read
       id-token: write
 
@@ -68,5 +73,6 @@ jobs:
 
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
-          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)" --max-turns 5'
+          # Increased max-turns to 10 to ensure Claude has enough iterations to complete review and post comment
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)" --max-turns 10'