feat(pr-review): enable sub-agent delegation for file-level reviews

[xingyaoww]

Why

This is the companion PR to OpenHands/extensions#164, which adds experimental sub-agent delegation support to the pr-review plugin.

Per-PR code reviews can get too large for a single agent to handle well. By delegating file-level reviews to sub-agents, we can:

1. Give each sub-agent focused context on a single file (or small group of related files)
2. Let the coordinator merge findings and post a cohesive review
3. Leverage the SDK DelegateTool / TaskToolSet for parallel file-level analysis

Summary

• Update pr-review-by-openhands.yml to point at the extensions feature branch (feat/pr-review-sub-agent-delegation) instead of main
• Enable use-sub-agents: 'true' to activate the experimental sub-agent delegation mode
• When enabled, the main review agent acts as a review coordinator that spawns file_reviewer sub-agents via TaskToolSet, delegates per-file review work, and consolidates findings into a single PR review

How to Test

Once both PRs are merged, the sub-agent review mode will be active on this repo's PR reviews. In the meantime, testing requires:

1. A PR opened on this repo (to trigger the workflow)
2. The extensions feature branch must be available at OpenHands/extensions@feat/pr-review-sub-agent-delegation

⚠️ Important

• This workflow currently pins to the feature branch of extensions — it should be updated to point back to @main once OpenHands/extensions#164 is merged
• The sub-agent delegation is experimental and can be disabled by setting use-sub-agents: 'false'

This PR was created by an AI assistant (OpenHands) on behalf of a user.

@xingyaoww can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.13-nodejs22-slim	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:85ddc2b-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-85ddc2b-python \
  ghcr.io/openhands/agent-server:85ddc2b-python

All tags pushed for this build

ghcr.io/openhands/agent-server:85ddc2b-golang-amd64
ghcr.io/openhands/agent-server:85ddc2b-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:85ddc2b-golang-arm64
ghcr.io/openhands/agent-server:85ddc2b-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:85ddc2b-java-amd64
ghcr.io/openhands/agent-server:85ddc2b-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:85ddc2b-java-arm64
ghcr.io/openhands/agent-server:85ddc2b-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:85ddc2b-python-amd64
ghcr.io/openhands/agent-server:85ddc2b-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:85ddc2b-python-arm64
ghcr.io/openhands/agent-server:85ddc2b-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:85ddc2b-golang
ghcr.io/openhands/agent-server:85ddc2b-java
ghcr.io/openhands/agent-server:85ddc2b-python

About Multi-Architecture Support

• Each variant tag (e.g., 85ddc2b-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 85ddc2b-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[all-hands-bot]

🟡 Acceptable - Reasonable experimental approach with proper documentation.

This workflow change enables sub-agent delegation for PR reviews by pinning to the feature branch. The approach is sound, but requires tracking to ensure the feature branch pin is reverted after the companion PR merges.

[all-hands-bot]

✅ QA Report: PASS

Workflow configuration successfully enables experimental sub-agent delegation with valid syntax and correct parameter passing.

Does this PR achieve its stated goal?

Yes. The PR achieves its goal of enabling experimental sub-agent delegation for file-level PR reviews. The changes correctly:

1. Point the workflow to the extensions feature branch (feat/pr-review-sub-agent-delegation) where sub-agent delegation is implemented
2. Enable the use-sub-agents: 'true' parameter that activates the experimental mode
3. The workflow runs successfully and correctly passes the parameter to the action

Phase	Result
Environment Setup	✅ Repository checked out, dependencies verified
CI & Tests	⚠️ 2 unrelated API breakage checks failing (security_policy_filename changes from different PR)
Functional Verification	✅ Workflow syntax valid, feature branch exists, parameter accepted, workflow runs successfully

Functional Verification

Test 1: Workflow YAML Syntax Validation

Verified the workflow file syntax:

python3 -c "import yaml; yaml.safe_load(open('.github/workflows/pr-review-by-openhands.yml'))" && echo "✅ YAML syntax is valid"

Output:

✅ YAML syntax is valid

This confirms the workflow YAML is syntactically correct.

Test 2: Feature Branch Exists in Extensions Repo

Verified the target branch exists:

gh api repos/OpenHands/extensions/branches/feat/pr-review-sub-agent-delegation --jq '.name'

Output:

feat/pr-review-sub-agent-delegation

This confirms the feature branch exists and can be referenced by the workflow.

Test 3: Action Parameter Validation

Fetched action.yml from the feature branch:

gh api repos/OpenHands/extensions/contents/plugins/pr-review/action.yml?ref=feat/pr-review-sub-agent-delegation --jq '.content' | base64 -d | head -80

Relevant excerpt:

use-sub-agents:
    description: "When true, enable sub-agent delegation for file-level reviews. The main agent acts as a coordinator that delegates per-file review work to file_reviewer sub-agents via the TaskToolSet, then consolidates findings into a single PR review. Experimental."
    required: false
    default: 'false'

This confirms:

• The use-sub-agents parameter exists in the action definition
• It has the correct description matching the PR's stated goal
• Default is 'false', so it must be explicitly enabled (which this PR does)

Test 4: Workflow Execution with New Configuration

Verified the workflow ran with the new configuration:

gh api repos/OpenHands/software-agent-sdk/actions/runs/24480056764

Key observations from workflow logs:

pr-review       Run PR Review   2026-04-15T21:46:30.2888109Z Download action repository 'OpenHands/extensions@feat/pr-review-sub-agent-delegation' (SHA:0ef1afca0e699d043bab8e72b769fb1ca5993cc0)
pr-review       Run PR Review   2026-04-15T21:46:32.3652071Z   use-sub-agents: true

Workflow status:

{
  "conclusion": "success",
  "status": "completed"
}

This confirms:

• The workflow correctly downloaded the feature branch
• The use-sub-agents: true parameter was passed to the action
• The workflow completed successfully

Test 5: Diff Verification

Verified the changes match PR description:

git diff main pr-2839 -- .github/workflows/pr-review-by-openhands.yml

Changes:

1. Line 43: @main → @feat/pr-review-sub-agent-delegation ✅
2. Lines 49-50: Added use-sub-agents: 'true' with comment ✅

Both changes match exactly what the PR description promises.

Issues Found

None. The configuration changes are correct and the workflow operates as expected. The CI failures are unrelated (they concern security_policy_filename API changes in a different part of the codebase).

---

Note: The PR description correctly mentions this is a companion to OpenHands/extensions#164 and that the workflow should be updated to point back to @main once that PR is merged. This temporary branch pinning is intentional and documented.

[all-hands-bot]

🟡 Acceptable - Reasonable experimental approach, but requires human review due to agent behavior changes.

[all-hands-bot]

[RISK ASSESSMENT]

⚠️ Risk Level: 🟡 MEDIUM

Rationale:

• Changes agent execution pattern (coordinator with sub-agent delegation)
• Experimental feature being deployed directly to production
• Could affect PR review quality, latency, and cost
• No mentioned monitoring or rollback plan

Recommendation: Per repo guidelines, PRs that change agent behavior should not be auto-approved. A human maintainer should review and consider:

1. Running lightweight evals to compare single-agent vs sub-agent review quality
2. Establishing metrics/monitoring before enabling in production
3. Defining rollback criteria

The workflow configuration itself is correct and properly documented with the TODO for reverting to @main.

[all-hands-bot]

✅ QA Report: PASS WITH ISSUES

Workflow configuration correctly enables sub-agent delegation; feature branch exists and parameter is valid; temporary branch pin requires follow-up.

Does this PR achieve its stated goal?

Yes. This PR successfully enables experimental sub-agent delegation for PR reviews by (1) pointing the workflow to the feat/pr-review-sub-agent-delegation branch in OpenHands/extensions where the sub-agent feature is implemented, and (2) passing use-sub-agents: 'true' to activate it. The companion PR (OpenHands/extensions#164) exists and implements the corresponding functionality. All verification checks pass: YAML syntax is valid, the referenced branch exists (SHA: 0ef1afca), the use-sub-agents parameter is accepted by the action, and no unintended changes were introduced.

Phase	Result
Environment Setup	✅ Repo checked out, workflow file accessible
CI & Tests	⚠️ Pre-commit ✓, SDK/tools/workspace tests ✓; Python/REST API failures unrelated to workflow change
Functional Verification	✅ YAML valid, branch exists, parameter accepted, diff matches description

Functional Verification

Test 1: YAML Syntax Validation

Step 1 — Establish baseline:
The workflow file is a GitHub Actions YAML that must parse correctly. Ran:

python3 -c "import yaml; yaml.safe_load(open('.github/workflows/pr-review-by-openhands.yml'))"

Result: ✓ YAML syntax is valid

This confirms the workflow file is syntactically correct and will be accepted by GitHub Actions.

---

Test 2: Extensions Branch Existence

Step 1 — Verify referenced branch exists:
The workflow now references OpenHands/extensions/plugins/pr-review@feat/pr-review-sub-agent-delegation. Ran:

gh api repos/OpenHands/extensions/git/refs/heads/feat/pr-review-sub-agent-delegation

Result:

{
  "ref": "refs/heads/feat/pr-review-sub-agent-delegation",
  "sha": "0ef1afca0e699d043bab8e72b769fb1ca5993cc0"
}

This confirms the feature branch exists and is accessible. The workflow will successfully resolve the action reference when it runs.

---

Test 3: Parameter Validation

Step 1 — Verify use-sub-agents parameter exists in target action:
Fetched the action definition from the feature branch:

curl -s https://raw.githubusercontent.com/OpenHands/extensions/feat/pr-review-sub-agent-delegation/plugins/pr-review/action.yml

Result: Found input definition:

use-sub-agents:
    description: "When true, enable sub-agent delegation for file-level reviews..."
    required: false
    default: 'false'

This confirms:

• The parameter exists in the action
• Its description matches the PR's stated purpose ("enable sub-agent delegation for file-level reviews")
• Default is 'false', so the workflow's use-sub-agents: 'true' will activate the experimental feature

---

Test 4: Change Precision

Step 1 — Verify diff contains only intended changes:
Ran:

git diff main .github/workflows/pr-review-by-openhands.yml

Result:

• Line 43-44: Added TODO comment and changed @main → @feat/pr-review-sub-agent-delegation
• Line 50-51: Added comment and use-sub-agents: 'true' parameter
• No other files changed (git diff main --name-only returned only the workflow file)

This confirms the changes are minimal, precise, and match the PR description exactly. No unintended modifications were introduced.

---

Test 5: Companion PR Verification

Step 1 — Verify companion PR exists:
Ran:

gh pr view 164 --repo OpenHands/extensions

Result: PR exists, state=OPEN, title="feat(pr-review): add sub-agent delegation for file-level reviews"

The companion PR's description states it "Add[s] experimental sub-agent delegation support to the pr-review plugin via use-sub-agents action input", which aligns with this PR's stated goal.

Issues Found

• 🟡 Minor: Workflow temporarily pins to feature branch @feat/pr-review-sub-agent-delegation — must be reverted to @main after OpenHands/extensions#164 merges (TODO comment exists at line 43)
• 🟢 Acceptable: CI checks "Python API" and "REST API (OpenAPI)" failed due to unrelated Field description changes in SDK code (not caused by this workflow-only PR)

[all-hands-bot]

🟡 Suggestion: After OpenHands/extensions#164 merges, remember to update this line back to @main and remove the use-sub-agents parameter (or keep it if you want the feature enabled permanently).

Consider adding a GitHub issue or tracking task to ensure this follow-up happens.