Skip to content

review: support review_heads with combined_perspectives (one kick per head, not heads x perspectives) #15058

Closed

Description

@gregoryhunt

Summary

review_heads (multi-model review with a decision step, #13548) only works with split perspectives. Under review.combined_perspectives: true, dispatchReviewers drops the heads, and the swarm falls back to single-model combined review. A hive that wants several models therefore pays heads × perspectives kicks per PR (10 with 2 heads and 5 perspectives), plus the decision kick. Every kick re-reads the same diff and the same surrounding code, so review latency and model cost scale with the perspective count rather than the number of independent opinions.

Proposal: support combined heads. Each head reviews every configured perspective in one kick and returns one verdict per perspective. The decision step reconciles them exactly as it does today.

Where (v5 @ 7e2fd91)

  • src/pkg/review/review_heads.go dispatchReviewers:
    if r.ReviewHead != "" && !combined {
        heads = append(heads, r)
    }
    The doc comment states it directly: "Under combined perspectives heads are dropped and every other reviewer works exactly as before."
  • planHeadKicks (around line 175) builds one record-only kick per (perspective, head) pair. Combined single-model kicks already exist (buildCombinedPublishInstruction, DispatchKick.Perspectives), and the relay already accepts a JSON array of per-perspective verdicts.

Measured cost of split heads (standalone hive; sonnet ×2, sol ×3; 5 perspectives)

Kick durations from kick turn ended … seconds_since_kick, over the 2.5 hours after #14706 shipped:

n median p90
sonnet head kick 61 70 s 117 s
sol head kick 73 144 s 264 s
decision kick 16 56 s 69 s
  • Per PR: 10 head kicks plus 1 decision.
  • In isolation, with sol's 5 kicks spread over 3 agents, the critical path is about 2 rounds of sol (≈5 min), then the decision.
  • Under load, with 2 PRs in flight, the median from start to posted review was 24 min.
  • Overall, push to posted review had a median of 99 min, most of it queueing for agent capacity. Every PR consumes 10 agent-kicks of capacity, and each kick re-reads the same diff.

Proposed behaviour

With combined_perspectives: true and an agent declaring review_heads:

  1. Dispatch: one record-only kick per head. Each carries every missing perspective for that head (DispatchKick.Perspectives) and uses the combined prompt body. The head records a JSON array of per-perspective verdicts with --record-verdict, exactly as split heads do, so PendingReview keeps one entry per (perspective, head), and settling, expiry and head_max_retries keep working per pair.
  2. Retries: a head that returns some perspectives and misses others is re-asked only for the missing ones. That is the existing per-pair logic, applied to a multi-perspective kick.
  3. Decision: unchanged (prompts_decision.go). It already receives every head's reports per perspective.
  4. Config: today validateReviewHeads rejects the combination (or it silently drops heads). Allow it. Optionally gate it behind review.combined_heads: true if maintainers want split to remain the default for heads.

Expected effect: 2 head kicks plus 1 decision per PR instead of 11. Each model reads the diff once, and the critical path becomes the slowest single combined head kick plus the decision. At our measured rates that should bring push-to-review down to about 10 min without adding agents, at roughly a third of the model spend.

Tests

  • With heads and combined_perspectives: true, planning yields one kick per head, carrying all missing perspectives, and pending entries per (perspective, head).
  • A combined head verdict array with 3 of 5 perspectives settles those 3 pairs; the next plan re-asks that head for the other 2 only.
  • The decision kick fires once every head has settled every configured perspective, and its prompt is unchanged.
  • The dispatchReviewers doc and the config validation are updated.

Refs #13548 (review heads), #13401 (combined kicks spread across reviewers), #13794, #14705/#14706.

🤖 Generated with Claude Code

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 28, 2026
  2. hivecommons-hive commented on Oct 28, 2026

    @hivecommons-hive
    Contributor

    🔒 Claimed by agent scanner (agent on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 2h0m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

  3. added a commit that references this issue on Oct 28, 2026
    cac064e
  4. github-actions commented on Oct 28, 2026

    @github-actions
    Contributor

    @gregoryhunt this issue was closed by @hivecommons-hive[bot] as completed.

    If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

    If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.

  5. hivecommons-hive commented on Oct 28, 2026

    @hivecommons-hive
    Contributor

    🔓 Claim by agent scanner released (holding agent relaunched).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions