Skip to content
1 change: 1 addition & 0 deletions changelog.d/changed-15058-combined-head-fanout.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A combined review head kick (`review_heads` under `review.combined_perspectives: true`) now tells the head to read the PR once and judge each perspective in its own parallel sub-agent, then record the one verdict array itself, falling back to reviewing the perspectives in sequence when sub-agents are unavailable. Every sub-agent runs on the head's own model, so each head's verdicts still come from the model it is stamped with.
2 changes: 2 additions & 0 deletions src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,8 @@ Heads have no `review_models` pool of their own (the head is the model).

**Combined heads.** Under `combined_perspectives: true` ([#15058](https://github.com/hivecommons/hive/issues/15058)) each head gets **one** record-only kick per PR head carrying every perspective it still owes, instead of one kick per (perspective, head): with 2 heads and 5 perspectives a PR costs 2 head kicks plus the decision rather than 10 plus the decision, and each model reads the diff once. The head records one JSON array with a verdict per perspective through a single `hive-review --record-verdict`; pending entries stay one per (perspective, head), so settling, expiry and `head_max_retries` work per pair, and a head that answers only some perspectives is re-asked for the rest only. As with any combined review, `max_perspectives_per_pr` does not apply and the kick costs one `max_parallel_reviews` slot. The decision step is unchanged.

Inside that one kick the head **fans out**: it fetches the PR metadata, the diff and any linked issue or contract once, then starts one sub-agent per perspective in parallel (the Task tool on Claude Code, the backend's sub-agent facility on Codex and others), handing each the diff, the contract text, the shared instructions and its own perspective's focus (including any `review.perspective_prompts` override). Every sub-agent is launched on the head's own model (the kick names it), so the per-head `review_model` stamp stays true; the per-perspective sub-agents replace the single pinned sub-agent of the independent-review instruction rather than adding to it, and a head whose sub-agent facility cannot pin its model reviews the perspectives itself. Sub-agents return one verdict object each; they post nothing, never call `hive-review` and do not refetch the PR. The head collects them into the one JSON array and records it once. Where sub-agents are unavailable the head reviews the perspectives one by one in the same session; the array contract does not change. A kick that re-asks a single perspective has nothing to fan out and carries no fan-out section. The point is latency: a head kick then takes about as long as its slowest perspective instead of the sum of all of them.

### The decision step

The heads' raw reports are evidence, never a verdict: while any head report exists without a decision, the PR head aggregates to `incomplete` (`Perspectives` shows the strictest head verdict and `heads` which heads answered, for the queue), so nothing routes on a single head.
Expand Down
48 changes: 48 additions & 0 deletions src/pkg/review/prompts.go
Original file line number Diff line number Diff line change
Expand Up @@ -713,6 +713,7 @@ func BuildCombinedPrompt(pr PullRequest, perspectives []Perspective, opts Prompt
// in one pass, recorded as one array, posted nowhere.
b.WriteString(buildHeadRecordOnlyInstruction(pr, head))
fmt.Fprintf(&b, "The verdict file carries all %d verdicts as ONE JSON array, including the clean ones, recorded with a single --record-verdict call. A perspective missing from the array is dispatched to you again.\n", len(perspectives))
b.WriteString(buildHeadFanOutInstruction(pr, perspectives, opts.ReviewBackend, opts.ReviewModel))
} else if opts.PostComments {
b.WriteString(buildCombinedPublishInstruction(pr, perspectives, opts))
}
Expand All @@ -722,6 +723,53 @@ func BuildCombinedPrompt(pr PullRequest, perspectives []Perspective, opts Prompt
return b.String()
}

// buildHeadFanOutInstruction is the fan-out half of a combined review head
// kick (hivecommons/hive#15058). The head reads the PR once and then judges
// each perspective in its own parallel sub-agent, so one head kick costs
// about as long as its slowest perspective rather than the sum of all of
// them, and each perspective is still asked on its own evidence. The head
// stays the only caller of hive-review: sub-agents return verdict objects and
// the head records them as the one array the relay expects. Backend-neutral
// on purpose: Claude Code and Codex both run sub-agents, under different
// names. A kick carrying a single perspective (a re-ask) has nothing to fan
// out, so it gets no section.
func buildHeadFanOutInstruction(pr PullRequest, perspectives []Perspective, backend, model string) string {
if len(perspectives) < 2 {
return ""
}
var b strings.Builder
b.WriteString("\nFAN OUT: ONE SUB-AGENT PER PERSPECTIVE, IN PARALLEL.\n")
fmt.Fprintf(&b, "You orchestrate this review. The %d perspectives are independent questions, so answer them in parallel:\n", len(perspectives))
fmt.Fprintf(&b, "1. Fetch the PR metadata, the full diff of %s#%d and any linked issue or contract ONCE, yourself, as the read instructions above describe.\n", pr.Repo, pr.Number)
fmt.Fprintf(&b, "2. Start one sub-agent per perspective, all %d at once, IN PARALLEL, not one after another (Claude Code: the Task tool; Codex and other backends: their sub-agent facility). Give each sub-agent the diff, the PR metadata, the linked issue or contract text, the shared instructions above (scope contract, grounding, finding schema) and ONLY its own section from PERSPECTIVE SECTIONS below. Each sub-agent returns exactly one verdict object for its perspective.\n", len(perspectives))
writeFanOutModelPin(&b, backend, model)
b.WriteString("3. Sub-agents must NOT post anything on the PR, must NOT call hive-review, must NOT read other hive reviews of this head SHA, and must NOT fetch the PR or its diff again: they work from what you passed them. They may read the surrounding code in the checkout to ground a finding.\n")
b.WriteString("4. Collect every result, check each object names its own perspective and carries this PR's repo, number, head_sha and body_digest, write them as ONE JSON array to the verdict file, and record it ONCE with the --record-verdict command above. Only you call hive-review.\n")
b.WriteString("If sub-agents are unavailable, or one fails or returns no usable verdict, review those perspectives yourself one by one in this session. The array contract is unchanged either way.\n")
return b.String()
}

// writeFanOutModelPin keeps the head's model guarantee across the fan-out.
// A head IS its model (review_heads: each head's report is stamped with the
// model that head ran), and its kick already carries the independent-review
// instruction naming one sub-agent pinned to that model. The fan-out replaces
// that one sub-agent with one per perspective, so each of them must be pinned
// to the same model; a backend whose sub-agent facility defaults to another
// (often cheaper) model would otherwise produce verdicts under the head's name
// that the head's model never made.
func writeFanOutModelPin(b *strings.Builder, backend, model string) {
model = strings.TrimSpace(model)
if model == "" {
b.WriteString(" Run every sub-agent on the model you are running on now; never let one default to a different or cheaper model.\n")
return
}
target := model
if bk := strings.TrimSpace(backend); bk != "" {
target = bk + "/" + model
}
fmt.Fprintf(b, " Launch EVERY sub-agent with `model` set to `%s`, this head's model. These per-perspective sub-agents ARE the independent review described above: launch them instead of that single sub-agent, not in addition to it. A sub-agent on any other model must not contribute a verdict; if your sub-agent facility cannot pin `%s`, review the perspectives yourself one by one. Every verdict object records review_model %q.\n", target, model, model)
}

// combinedSharedHeader opens the once-per-session block of a combined kick so
// the reviewer knows the instructions that follow are not repeated per
// perspective and must be carried into each section below.
Expand Down
89 changes: 89 additions & 0 deletions src/pkg/review/review_heads_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,95 @@ func TestCombinedHeadsDecisionOnceEveryHeadSettled(t *testing.T) {
}
}

// A combined head kick fans the perspectives out to parallel sub-agents
// (hivecommons/hive#15058): the head reads the PR once, every perspective's
// focus (overrides included) is in the kick, the head alone records one array
// and nothing is posted. A single-perspective re-ask has nothing to fan out.
func TestCombinedHeadPromptFansOutPerPerspective(t *testing.T) {
set, err := NewPerspectiveSet(nil, map[string]string{"security": "custom security focus from perspective_prompts"})
if err != nil {
t.Fatal(err)
}
all := set.List()
pr := dispatchPR("sha1")
pr.BodyDigest = "digest1"
fanOut := []string{
"FAN OUT: ONE SUB-AGENT PER PERSPECTIVE, IN PARALLEL.",
"ONCE, yourself",
"IN PARALLEL, not one after another",
"must NOT post anything on the PR, must NOT call hive-review",
"must NOT fetch the PR or its diff again",
"record it ONCE with the --record-verdict command above. Only you call hive-review.",
"If sub-agents are unavailable",
}
for _, tc := range []struct {
name string
perspectives []Perspective
opts PromptOptions
wantFanOut bool
}{
{name: "head, every perspective", perspectives: all, opts: PromptOptions{HeadRecordOnly: "cr-sol", PostComments: true}, wantFanOut: true},
{name: "head, two missing perspectives", perspectives: all[3:], opts: PromptOptions{HeadRecordOnly: "cr-sol", PostComments: true}, wantFanOut: true},
{name: "head, single perspective re-ask", perspectives: all[:1], opts: PromptOptions{HeadRecordOnly: "cr-sol", PostComments: true}},
{name: "plain combined kick, not a head", perspectives: all, opts: PromptOptions{PostComments: true}},
} {
t.Run(tc.name, func(t *testing.T) {
opts := tc.opts
opts.Perspectives = set
opts.WritingGuideSection = "WRITING GUIDE MARKER"
msg := BuildCombinedPrompt(pr, tc.perspectives, opts)
want := []string{"WRITING GUIDE MARKER", "Head SHA: sha1", "digest1"}
for _, p := range tc.perspectives {
want = append(want, "[perspective:"+string(p)+"]", string(p)+" — "+set.Focus(p))
}
isHead := opts.HeadRecordOnly != ""
if isHead {
want = append(want, "INDEPENDENT REVIEW HEAD (cr-sol)", "Do NOT post anything on the PR", "--record-verdict --verdict-file <verdict>", "ONE JSON array")
}
if tc.wantFanOut {
want = append(want, fanOut...)
}
for _, w := range want {
if !strings.Contains(msg, w) {
t.Errorf("prompt missing %q", w)
}
}
if !tc.wantFanOut && strings.Contains(msg, "FAN OUT") {
t.Error("prompt carries a fan-out section it should not")
}
if isHead {
for _, bad := range []string{"--comment --body-file", "ONE COMMENT, EVERY PERSPECTIVE"} {
if strings.Contains(msg, bad) {
t.Errorf("combined head prompt tells the head to post: %q", bad)
}
}
}
})
}
if !strings.Contains(BuildCombinedPrompt(pr, all, PromptOptions{HeadRecordOnly: "cr-sol", Perspectives: set}), "custom security focus from perspective_prompts") {
t.Fatal("perspective_prompts override missing from the combined head prompt")
}

// The fan-out must not break the per-head model guarantee: every
// sub-agent runs on the head's model, and replaces (not adds to) the
// single pinned sub-agent of the independent-review section.
pinned := BuildCombinedPrompt(pr, all, PromptOptions{HeadRecordOnly: "cr-sol", Perspectives: set, ReviewBackend: "codex", ReviewModel: "gpt-6-sol"})
for _, w := range []string{
"Launch EVERY sub-agent with `model` set to `codex/gpt-6-sol`",
"instead of that single sub-agent, not in addition to it",
"cannot pin `gpt-6-sol`, review the perspectives yourself",
`review_model "gpt-6-sol"`,
} {
if !strings.Contains(pinned, w) {
t.Errorf("fan-out does not pin sub-agents to the head model: missing %q", w)
}
}
unpinned := BuildCombinedPrompt(pr, all, PromptOptions{HeadRecordOnly: "cr-sol", Perspectives: set})
if !strings.Contains(unpinned, "Run every sub-agent on the model you are running on now") {
t.Error("fan-out without a configured head model must keep sub-agents on the session's own model")
}
}

func TestHeadKicksCarryTheHeadModelAndStampPerHead(t *testing.T) {
plan := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{}, DispatchState{}, headsOpts())
for _, k := range plan.ReviewKicks {
Expand Down
Loading