Refactor/refactor code review agent

[xueyulinn]

Summary

This PR starts refactoring the code review workflow from a single review agent into a multi-agent pipeline. It adds a planning agent to produce structured evidence-gathering questions and a structural evidence agent to
answer structural questions using indexed code tools.

Related Issue

N/A

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation
• Test
• CI/CD
• Chore

Changes Made

• Added Code Review Planning Agent.

  • Produces structured CodeReviewPlanning output.
  • Generates targeted review questions with question_id, question_type, file location, symbol, evidence goal, and priority.
  • Builds user prompts from PR metadata, commits, changed file patches, and static analysis summary.

• Added Structural Evidence Agent.

  • Answers structural review questions with CodeReviewEvidence.
  • Uses scoped code index tools:
    • find_code_chunks
    • find_code_references
    • find_usage_patterns
  • Returns evidence with coverage, confidence, answer text, and structured evidence items.

• Added agent system prompts.

  • PR_CODE_REVIEW_PLANNING_SYSTEM_PROMPT
  • PR_STRUCTURAL_EVIDENCE_SYSTEM_PROMPT

• Added shared review context model.

  • Introduces PRReviewContext with GitHub client, repo_id, and commit_id.
  • Keeps GitHub client as runtime context while exposing only safe metadata to prompts.

• Updated pull request review service flow.

  • Runs planning before evidence gathering.
  • Starts separating structural and convention questions for future evidence agents.

• Added a planning agent unit test.

  • Builds fake PR context inputs.
  • Mocks Runner.run.
  • Verifies generate_code_review_planning without making live model calls.

• Added placeholder files for future agents:

  • code_review_writer_agent.py
  • convention_evidence_agent.py

How to Test

Run the test suite:

uv run pytest

Current result:

12 passed

Optional lint check:

uv run ruff check .

## Checklist

- [x] Code builds successfully
- [x] Tests added or updated
- [x] Existing tests pass
- [ ] Documentation updated if needed
- [x] No secrets or sensitive data included
- [x] Breaking changes documented

## Breaking Changes

N/A

## Additional Notes

This PR establishes the first part of the planned multi-agent code review architecture. The convention evidence agent and writer agent are intentionally left as placeholders for follow-up implementation.

[codehawky]

Summary by CodeHawky

Status

• Summary type: full_pr_summary
• Current head: 2712706b327a9c77b6bd4462072b441e4a28fe54
• Generated at: 2026-05-13T02:30:04.502539+00:00

Summary

• Starts refactoring PR review from a single review agent into a multi-agent pipeline with a new planning agent and structural evidence agent.
• Adds structured planning/evidence models and prompts in codehawk/agents/code_review_planning_agent.py, structural_evidence_agent.py, and prompts.py.
• Adds PRReviewContext in codehawk/models/code_review.py for runtime agent/tool context.
• Updates codehawk/services/pull_request_review.py to run planning and begin evidence gathering; adds a unit test for planning agent behavior.

Risk

• High: the review service flow no longer calls create_pr_review, evidence gathering is launched via asyncio.gather(...) without awaiting it, and the structural/convention question filtering appears inconsistent with the variable names.

Review Path

1. Review codehawk/services/pull_request_review.py first for behavior changes to the production PR review flow.
2. Inspect codehawk/agents/code_review_planning_agent.py and its test to validate prompt construction, schema, and mocked runner behavior.
3. Review codehawk/agents/structural_evidence_agent.py for tool inputs, context use, async/thread boundaries, and output schema.
4. Check new prompts in codehawk/agents/prompts.py for schema alignment and constraints.
5. Skim codehawk/models/code_review.py and the small parser rename in code_reference_parser.py.

Open Questions

• Is disabling final PR review creation intentional for this refactor stage?
• Should structural evidence receive structural questions rather than convention questions?
• Should evidence gathering be awaited before the service exits?