docs(buzz-agent): record why [Reflect] stays out of the state machine

Reflect was step 3 of the migration plan. It should not be an Operation,
and the reason is worth writing down rather than leaving as an omission.

StateEffect can append a message or patch a tool request's metadata, but
nothing edits tool result *content*. PatchToolRequestMeta is applied via
SessionManager -- the store this branch deliberately does not write to --
and patches metadata, not what the model reads.

So as an operation the reflection would arrive as a separate message
after the result rather than inside it. That is exactly the arrangement
this port moved away from when it stopped delivering reflections as
steers. Structure follows behaviour.

Also corrected reflect.rs's module comment, which still described the
steer-based delivery an intermediate commit used.

Signed-off-by: Michael Neale <michael.neale@gmail.com>
Co-authored-by: Michael Neale <michael.neale@gmail.com>

crates/buzz-agent/src/tools.rs

@@ -110,6 +110,15 @@ async fn run_one(
 /// content block as the failure, rather than as a separate steer message
 /// arriving at an unrelated point in the conversation. Capped so a tool
 /// failing in a loop cannot flood the context.
+///
+/// **Deliberately not a goose `Operation`**, unlike the other loop decisions.
+/// An operation cannot reach inside a tool result: `StateEffect` can append a
+/// message or patch a request's *metadata*
+/// (`PatchToolRequestMeta`, which goose applies through `SessionManager` --
+/// the store buzz does not write to), but nothing edits result *content*. As
+/// an operation the reflection would arrive as a separate message after the
+/// result instead of inside it, which is the arrangement this deliberately
+/// moved away from. Structure follows behaviour, not the other way round.
 fn reflect_on_failure(
     result: ToolResult<CallToolResult>,
     reflections: &mut usize,

crates/buzz-agent/tests/reflect.rs

@@ -1,15 +1,15 @@
 //! Proves `[Reflect]`: a failed tool result must nudge the model to diagnose
 //! before retrying.
 //!
-//! buzz-agent appended the text to the tool result itself (`agent.rs:364`).
-//! Goose gives no interception point for that — `PostToolUseFailure` is
-//! fire-and-forget and its output is discarded (`agent.rs:589-620`) — so we
-//! deliver the same text via `steer()`, which goose drains at the round
-//! boundary.
+//! buzz-agent appends the text to the failed tool result itself, which is
+//! where the model reads it in context. An earlier draft of this port
+//! delivered it as a steer instead, because `Agent::reply` owned the tool
+//! result and gave no interception point; owning the loop put it back on the
+//! result. This comment described that intermediate state and no longer did.
 //!
-//! Observable consequence: the reflection must appear in the *next* request
-//! the provider receives. That is what this asserts, rather than trusting that
-//! `steer()` was called.
+//! Observable consequence either way: the reflection must appear in the *next*
+//! request the provider receives. That is what this asserts, rather than
+//! trusting that any particular delivery mechanism was invoked.
 
 use std::io::{BufRead, BufReader, Write};
 use std::net::TcpListener;