fix: omit tool-call narration from review output (#475)

## Summary
- drop streamed assistant narration that occurs before tool calls from
persisted review output
- apply the same trailing-text rule across codex, claude, gemini, and
opencode review parsers
- add anonymized regression tests based on recent log shapes so
tool-call chatter does not leak into reviews

## Testing
- go fmt ./...
- go vet ./...
- go test ./...

Author: wesm

internal/agent/claude.go

@@ -211,9 +211,9 @@ type claudeStreamMessage struct {
 	} `json:"error,omitempty"`
 }
 
-// extractContentText extracts text from a Claude message content field.
-// Content can be a plain string or an array of content blocks
-// (e.g. [{"type":"text","text":"..."}]).
+// extractContentText extracts only the text that appears after the last tool-use
+// block in a Claude message content field. Content can be a plain string or an
+// array of content blocks (e.g. [{"type":"text","text":"..."}]).
 func extractContentText(raw json.RawMessage) string {
 	if len(raw) == 0 {
 		return ""
@@ -229,13 +229,16 @@ func extractContentText(raw json.RawMessage) string {
 		Text string `json:"text"`
 	}
 	if json.Unmarshal(raw, &blocks) == nil {
-		var texts []string
+		texts := newTrailingReviewText()
 		for _, b := range blocks {
-			if b.Type == "text" && b.Text != "" {
-				texts = append(texts, b.Text)
+			switch b.Type {
+			case "text":
+				texts.Add(b.Text)
+			case "tool_use", "tool_result":
+				texts.ResetAfterTool()
 			}
 		}
-		return strings.Join(texts, "\n")
+		return texts.Join("\n")
 	}
 	return ""
 }
@@ -248,7 +251,7 @@ func parseStreamJSON(r io.Reader, output io.Writer) (string, error) {
 	br := bufio.NewReader(r)
 
 	var lastResult string
-	var assistantMessages []string
+	assistantMessages := newTrailingReviewText()
 	var errorMessages []string
 	var validEventsParsed bool
 
@@ -274,9 +277,14 @@ func parseStreamJSON(r io.Reader, output io.Writer) (string, error) {
 				// Content can be a string or an array of content blocks.
 				if msg.Type == "assistant" {
 					if text := extractContentText(msg.Message.Content); text != "" {
-						assistantMessages = append(assistantMessages, text)
+						assistantMessages.Add(text)
 					}
 				}
+				if msg.Type == "tool_use" || msg.Type == "tool_result" {
+					// Only the trailing post-tool assistant segment is treated
+					// as the review body.
+					assistantMessages.ResetAfterTool()
+				}
 
 				// The final result message contains the summary.
 				// When is_error is set, the result event signals a
@@ -315,7 +323,7 @@ func parseStreamJSON(r io.Reader, output io.Writer) (string, error) {
 	}
 
 	// Build partial output for error context
-	partial := strings.Join(assistantMessages, "\n")
+	partial := assistantMessages.Join("\n")
 
 	// If error events were received but we got no result, report them with any partial output
 	if len(errorMessages) > 0 && lastResult == "" {
@@ -326,8 +334,8 @@ func parseStreamJSON(r io.Reader, output io.Writer) (string, error) {
 	if lastResult != "" {
 		return lastResult, nil
 	}
-	if len(assistantMessages) > 0 {
-		return strings.Join(assistantMessages, "\n"), nil
+	if result := assistantMessages.Join("\n"); result != "" {
+		return result, nil
 	}
 
 	return "", nil

internal/agent/claude_test.go

@@ -193,6 +193,26 @@ still not json
 `,
 			expectedResult: "First block\nSecond block",
 		},
+		{
+			name: "AssistantFallbackDropsNarrationBeforeToolUse",
+			input: `{"type":"system","subtype":"init"}
+{"type":"assistant","message":{"content":"I am checking the relevant files first."}}
+{"type":"tool_use","name":"Read","input":{"file_path":"redacted.go"}}
+{"type":"tool_result","content":"redacted"}
+{"type":"assistant","message":{"content":"## Review Findings\n- **Severity**: Low; **Problem**: Final finding."}}
+`,
+			expectedResult: "## Review Findings\n- **Severity**: Low; **Problem**: Final finding.",
+		},
+		{
+			name: "AssistantFallbackPrefersFinalPostToolSegment",
+			input: `{"type":"system","subtype":"init"}
+{"type":"assistant","message":{"content":"## Review Findings\n- **Severity**: Low; **Problem**: Earlier provisional finding."}}
+{"type":"tool_use","name":"Read","input":{"file_path":"redacted.go"}}
+{"type":"tool_result","content":"redacted"}
+{"type":"assistant","message":{"content":"## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding."}}
+`,
+			expectedResult: "## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding.",
+		},
 		{
 			name: "ContentBlockArrayWithToolUse",
 			input: `{"type":"system","subtype":"init"}
@@ -280,7 +300,7 @@ func TestExtractContentText(t *testing.T) {
 		{
 			name: "MixedBlockTypes",
 			raw:  `[{"type":"text","text":"Analysis"},{"type":"tool_use","name":"Read"},{"type":"text","text":"Done"}]`,
-			want: "Analysis\nDone",
+			want: "Done",
 		},
 		{
 			name: "EmptyArray",

internal/agent/codex.go

@@ -268,6 +268,20 @@ func isCodexEventType(eventType string) bool {
 		strings.HasPrefix(eventType, "item.")
 }
 
+func isCodexToolEvent(ev codexEvent) bool {
+	if ev.Type != "item.started" &&
+		ev.Type != "item.updated" &&
+		ev.Type != "item.completed" {
+		return false
+	}
+	switch ev.Item.Type {
+	case "command_execution", "file_change":
+		return true
+	default:
+		return false
+	}
+}
+
 func codexFailureEventError(ev codexEvent) error {
 	switch ev.Type {
 	case "turn.failed":
@@ -298,8 +312,7 @@ func (a *CodexAgent) parseStreamJSON(r io.Reader, sw *syncWriter) (string, error
 	br := bufio.NewReader(r)
 
 	var validEventsParsed bool
-	var agentMessages []string
-	messageIndexByID := make(map[string]int)
+	agentMessages := newTrailingReviewText()
 	var streamFailure error
 
 	for {
@@ -324,19 +337,18 @@ func (a *CodexAgent) parseStreamJSON(r io.Reader, sw *syncWriter) (string, error
 						streamFailure = codexFailureEventError(ev)
 					}
 
+					if isCodexToolEvent(ev) {
+						// The persisted review is defined as the assistant text
+						// after the last tool event in the stream.
+						agentMessages.ResetAfterTool()
+					}
+
 					// Collect agent_message text from completed/updated items.
 					// For messages with IDs, keep only the latest text per ID to avoid duplicates
 					// from incremental updates while preserving first-seen order.
 					if (ev.Type == "item.completed" || ev.Type == "item.updated") &&
 						ev.Item.Type == "agent_message" && ev.Item.Text != "" {
-						if ev.Item.ID == "" {
-							agentMessages = append(agentMessages, ev.Item.Text)
-						} else if idx, ok := messageIndexByID[ev.Item.ID]; ok {
-							agentMessages[idx] = ev.Item.Text
-						} else {
-							messageIndexByID[ev.Item.ID] = len(agentMessages)
-							agentMessages = append(agentMessages, ev.Item.Text)
-						}
+						agentMessages.AddWithID(ev.Item.ID, ev.Item.Text)
 					}
 				}
 			}
@@ -355,8 +367,8 @@ func (a *CodexAgent) parseStreamJSON(r io.Reader, sw *syncWriter) (string, error
 		return "", streamFailure
 	}
 
-	if len(agentMessages) > 0 {
-		return strings.Join(agentMessages, "\n"), nil
+	if result := agentMessages.Join("\n"); result != "" {
+		return result, nil
 	}
 
 	return "", nil

internal/agent/codex_test.go

@@ -179,6 +179,32 @@ func TestCodexParseStreamJSON(t *testing.T) {
 			),
 			want: "Done reviewing.",
 		},
+		{
+			name: "DropsNarrationBeforeToolCalls",
+			input: buildStream(
+				jsonThreadStarted,
+				jsonTurnStarted,
+				`{"type":"item.completed","item":{"id":"msg1","type":"agent_message","text":"Checking the relevant files before I write the review."}}`,
+				`{"type":"item.started","item":{"id":"cmd1","type":"command_execution","command":"sh -lc sed ..."}}`,
+				`{"type":"item.completed","item":{"id":"cmd1","type":"command_execution","command":"sh -lc sed ...","exit_code":0}}`,
+				`{"type":"item.completed","item":{"id":"msg2","type":"agent_message","text":"## Review Findings\n- **Severity**: Low; **Problem**: Final finding."}}`,
+				jsonTurnCompleted,
+			),
+			want: "## Review Findings\n- **Severity**: Low; **Problem**: Final finding.",
+		},
+		{
+			name: "PrefersFinalPostToolSegment",
+			input: buildStream(
+				jsonThreadStarted,
+				jsonTurnStarted,
+				`{"type":"item.completed","item":{"id":"msg1","type":"agent_message","text":"## Review Findings\n- **Severity**: Low; **Problem**: Earlier provisional finding."}}`,
+				`{"type":"item.started","item":{"id":"cmd1","type":"command_execution","command":"sh -lc rg ..."}}`,
+				`{"type":"item.completed","item":{"id":"cmd1","type":"command_execution","command":"sh -lc rg ...","exit_code":0}}`,
+				`{"type":"item.completed","item":{"id":"msg2","type":"agent_message","text":"## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding."}}`,
+				jsonTurnCompleted,
+			),
+			want: "## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding.",
+		},
 		{
 			name:              "StreamsToWriter",
 			input:             buildStream(`{"type":"item.completed","item":{"type":"agent_message","text":"hello"}}`),

internal/agent/gemini.go

@@ -193,7 +193,7 @@ func (a *GeminiAgent) parseStreamJSON(r io.Reader, sw *syncWriter) (parseResult,
 	br := bufio.NewReader(r)
 
 	var lastResult string
-	var assistantMessages []string
+	assistantMessages := newTrailingReviewText()
 	var validEventsParsed bool
 
 	for {
@@ -217,11 +217,16 @@ func (a *GeminiAgent) parseStreamJSON(r io.Reader, sw *syncWriter) (parseResult,
 				// Collect assistant messages for the result
 				// Gemini format: type="message", role="assistant", content at top level
 				if msg.Type == "message" && msg.Role == "assistant" && msg.Content != "" {
-					assistantMessages = append(assistantMessages, msg.Content)
+					assistantMessages.Add(msg.Content)
 				}
 				// Claude Code format: type="assistant", message.content nested
 				if msg.Type == "assistant" && msg.Message.Content != "" {
-					assistantMessages = append(assistantMessages, msg.Message.Content)
+					assistantMessages.Add(msg.Message.Content)
+				}
+				if msg.Type == "tool" || msg.Type == "tool_result" {
+					// Treat pre-tool assistant text as provisional; only the
+					// trailing post-tool segment becomes review output.
+					assistantMessages.ResetAfterTool()
 				}
 
 				// The final result message contains the summary
@@ -245,8 +250,8 @@ func (a *GeminiAgent) parseStreamJSON(r io.Reader, sw *syncWriter) (parseResult,
 	if lastResult != "" {
 		return parseResult{result: lastResult}, nil
 	}
-	if len(assistantMessages) > 0 {
-		return parseResult{result: strings.Join(assistantMessages, "\n")}, nil
+	if result := assistantMessages.Join("\n"); result != "" {
+		return parseResult{result: result}, nil
 	}
 
 	return parseResult{}, nil

internal/agent/gemini_test.go

@@ -166,6 +166,34 @@ func TestGeminiParseStreamJSON(t *testing.T) {
 				}
 			},
 		},
+		{
+			name: "AssistantFallbackDropsNarrationBeforeToolUse",
+			input: `{"type":"system","subtype":"init"}
+{"type":"assistant","message":{"content":"I am checking the relevant files first."}}
+{"type":"tool","name":"Read"}
+{"type":"assistant","message":{"content":"## Review Findings\n- **Severity**: Low; **Problem**: Final finding."}}
+`,
+			assertResult: func(t *testing.T, res string) {
+				want := "## Review Findings\n- **Severity**: Low; **Problem**: Final finding."
+				if res != want {
+					t.Errorf("expected result %q, got %q", want, res)
+				}
+			},
+		},
+		{
+			name: "AssistantFallbackPrefersFinalPostToolSegment",
+			input: `{"type":"system","subtype":"init"}
+{"type":"assistant","message":{"content":"## Review Findings\n- **Severity**: Low; **Problem**: Earlier provisional finding."}}
+{"type":"tool","name":"Read"}
+{"type":"assistant","message":{"content":"## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding."}}
+`,
+			assertResult: func(t *testing.T, res string) {
+				want := "## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding."
+				if res != want {
+					t.Errorf("expected result %q, got %q", want, res)
+				}
+			},
+		},
 		{
 			name: "NoValidEvents",
 			input: `not json at all

internal/agent/opencode.go

@@ -172,12 +172,12 @@ func parseOpenCodeJSON(
 ) (string, error) {
 	br := bufio.NewReader(r)
 
-	var textParts []string
+	textParts := newTrailingReviewText()
 
 	for {
 		line, err := br.ReadString('\n')
 		if err != nil && err != io.EOF {
-			return strings.Join(textParts, ""), fmt.Errorf(
+			return textParts.Join(""), fmt.Errorf(
 				"read stream: %w", err,
 			)
 		}
@@ -193,11 +193,13 @@ func parseOpenCodeJSON(
 				ev.Part != nil {
 				var part opencodePart
 				if json.Unmarshal(ev.Part, &part) == nil &&
-					part.Type == "text" && part.Text != "" {
-					textParts = append(
-						textParts,
-						stripTerminalControls(part.Text),
-					)
+					part.Type != "" {
+					if part.Type == "tool" {
+						textParts.ResetAfterTool()
+					}
+					if part.Type == "text" && part.Text != "" {
+						textParts.Add(stripTerminalControls(part.Text))
+					}
 				}
 			}
 		}
@@ -207,7 +209,7 @@ func parseOpenCodeJSON(
 		}
 	}
 
-	return strings.Join(textParts, ""), nil
+	return textParts.Join(""), nil
 }
 
 // ansiPattern matches ANSI CSI and OSC escape sequences.

internal/agent/opencode_test.go

@@ -131,13 +131,30 @@ func TestOpenCodeReviewParsesJSONStream(t *testing.T) {
 
 	result, _, _ := runMockOpenCodeReview(t, "", "prompt", stdoutLines)
 
-	assertContains(t, result, "**Review:** Fix the typo.")
-	assertContains(t, result, " Done.")
+	assertEqual(t, result, " Done.")
 	// Tool events should not appear in the result text
 	assertNotContains(t, result, "Read")
 	assertNotContains(t, result, "file_path")
 }
 
+func TestOpenCodeReviewPrefersFinalPostToolSegment(t *testing.T) {
+	t.Parallel()
+	skipIfWindows(t)
+
+	stdoutLines := []string{
+		makeTextEvent("## Review Findings\n- **Severity**: Low; **Problem**: Earlier provisional finding."),
+		makeOpenCodeEvent("tool", map[string]any{
+			"type": "tool",
+			"tool": "Read",
+		}),
+		makeTextEvent("## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding."),
+	}
+
+	result, _, _ := runMockOpenCodeReview(t, "", "prompt", stdoutLines)
+
+	assertEqual(t, result, "## Review Findings\n- **Severity**: Medium; **Problem**: Final persisted finding.")
+}
+
 func TestOpenCodeReviewStreamsToOutput(t *testing.T) {
 	t.Parallel()
 	skipIfWindows(t)
@@ -214,8 +231,8 @@ func TestParseOpenCodeJSON(t *testing.T) {
 
 	lines := strings.Join([]string{
 		makeTextEvent("Part one."),
-		makeOpenCodeEvent("reasoning", map[string]any{
-			"type": "reasoning", "text": "thinking...",
+		makeOpenCodeEvent("tool", map[string]any{
+			"type": "tool", "tool": "Read",
 		}),
 		makeTextEvent(" Part two."),
 	}, "\n") + "\n"
@@ -228,7 +245,7 @@ func TestParseOpenCodeJSON(t *testing.T) {
 		t.Fatalf("parseOpenCodeJSON: %v", err)
 	}
 
-	assertEqual(t, result, "Part one. Part two.")
+	assertEqual(t, result, " Part two.")
 
 	// All raw lines should be written to output
 	out := outputBuf.String()