You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9e0ae1f
Browse filesBrowse the repository at this point in the historyBrowse files
feat(agent): optional reply guard reminds a silent turn to publish
A Buzz agent's assistant text and reasoning are never shown to anyone —
only what it posts through the CLI. A turn that runs fifteen tool calls
and never publishes is a silent failure: the requester waits on a result
that was produced and thrown away.
With BUZZ_AGENT_REQUIRE_REPLY=1 (default off, per-agent opt-in), a turn
about to end without a recognized attempt to post gets a reminder and is
rerolled. At most two, then the turn ends regardless — the guard catches
accidental omission, it does not compel speech. The reminder text
explicitly licenses silence so it cannot fight the base prompt's
"silence is usually correct".
This is not a new MCP hook. `RunCtx::run` *is* the turn, so the two
per-turn locals need no plumbing, and every tool call already passes
through it with its arguments visible. The objection is appended at the
existing `_Stop` gate and rides `push_hook_outputs_as_tool_results`, so
the model receives it as a lower-trust tool result with
`{hook, server, text}` attribution — no new trust path, no new
lifecycle event, no dev-mcp or CLI protocol change.
Reminders share BUZZ_AGENT_STOP_MAX_REJECTIONS, the existing outer cap
on every end-turn objection. A round carrying both a hook objection and
a reminder costs one rejection and delivers both texts; at budget 1 only
one reminder fits, and at 0 the guard is off along with the hooks. An
independent budget would either violate that bound or need a second
arbitration rule.
Recognition is deliberately coarse: a registered non-hook tool whose
qualified name ends in `__shell`, whose `command` argument contains
`messages send` or `reactions add`. Given the registry checks, that
suffix is exactly equivalent to a bare name of `shell` — registration
forbids `__` in server and bare names, so a trailing `__shell` could
only straddle the separator if the bare name began with `_`, which
`is_hook` excludes. It reads the structured `command` field rather than
serialized arguments, so a `description` that quotes a send cannot
disarm the guard. It recognizes an *attempt*, not a successful publish:
a failed send already returns non-zero exit and error JSON, which is
louder than this reminder. Detection runs after the per-turn tool-call
cap, since a discarded call never ran.
Adds FAKE_MCP_SHELL_TOOL=1 to the test MCP server: it previously exposed
no tool with a bare name of `shell`, so the satisfied-guard path was
untestable.
Plan reviewed to 9.5/10 with Wren; each guard behavior is pinned by a
mutation that breaks a specific named test.
Co-authored-by: Dawn (sprout agent) <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@sprout-oss.stage.blox.sqprod.co>
Signed-off-by: tlongwell-block <[email protected]>
Copy file name to clipboardExpand all lines: crates/buzz-agent/README.md
+55Lines changed: 55 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -163,6 +163,61 @@ Everything is environment variables. No flags, no config files. (We are a subpro
163
163
|`BUZZ_AGENT_MAX_LINE_BYTES`|`4194304`| 4 MiB. Hard cap on inbound JSON-RPC frames. |
164
164
|`BUZZ_AGENT_MAX_HISTORY_BYTES`|`1048576`| 1 MiB. Old turns are evicted past this. |
165
165
|`BUZZ_AGENT_MAX_TOOL_RESULT_TEXT_BYTES`|`51200`| 50 KiB. Per-result cap on tool-output text; oversize is middle-elided (head + tail kept) with an inline marker. Images are exempt. |
166
+
|`BUZZ_AGENT_REQUIRE_REPLY`|`0`|`1` enables the [reply guard](#reply-guard) — remind the model to publish when a turn is about to end with nothing posted to Buzz. |
167
+
168
+
169
+
## Reply Guard
170
+
171
+
Off by default. With `BUZZ_AGENT_REQUIRE_REPLY=1`, a turn that is about to end
172
+
without any recognized attempt to post to Buzz gets a reminder that its
173
+
assistant text is invisible to humans, and is rerolled.
174
+
175
+
This exists because a Buzz agent's reasoning and tool output are not shown to
176
+
anyone. A turn that does real work and never posts is a silent failure — the
177
+
requester waits on a result that was produced and thrown away.
178
+
179
+
**Advisory, never a trap.** At most two reminders, then the turn ends whether or
180
+
not anything was published. The guard catches accidental omission; it does not
181
+
compel speech. The reminder text explicitly licenses silence, because the
182
+
built-in system prompt says publishing is optional and silence is often the
183
+
correct outcome.
184
+
185
+
**Recognition contract.** A turn counts as having replied when it issues a call
186
+
that:
187
+
188
+
- resolves to a registered, non-hook tool (a hallucinated tool name is rejected
189
+
at preflight and never runs, so it must not disarm the guard),
190
+
- whose qualified name ends in `__shell` — i.e. the bare tool name is exactly
191
+
`shell`, which is `buzz-dev-mcp`'s shell tool and any other server's, and
192
+
- whose `command` argument contains `messages send` or `reactions add`.
193
+
194
+
`messages send` also covers `messages send-diff`. Reactions count because the
195
+
built-in prompt directs agents to react rather than post a bare
196
+
acknowledgement, so nagging an agent that reacted would punish documented
197
+
behavior.
198
+
199
+
Detection is checked **after** the per-turn tool-call cap
200
+
(`MAX_TOOL_CALLS_PER_TURN`) is applied: a publish-shaped call that was discarded
201
+
never ran.
202
+
203
+
**It recognizes an attempt, not a successful publish.** Only the command text is
204
+
inspected, never the exit status. A send that fails still satisfies the guard —
205
+
which is fine, since a failed send already returns a non-zero exit and error
206
+
JSON to the model, louder feedback than a reminder.
207
+
208
+
**Known limits**, both deliberate. A command assembled at runtime (`$CMD`) or
209
+
buried in a wrapper script is missed, so that turn is reminded despite having
210
+
posted. Text that merely quotes a send (`echo "buzz messages send"`) matches, so
211
+
that turn is not reminded. Missing a real post is the expensive direction, and
212
+
substring matching is the forgiving one there. Neither edge is pinned by a test;
213
+
the matcher is free to improve.
214
+
215
+
**Budget.** Reminders ride the existing `_Stop` gate and share
216
+
`BUZZ_AGENT_STOP_MAX_REJECTIONS` — the outer cap on every end-turn objection.
217
+
At the default 3 both reminders fit; at 1 only one does; at 0 the guard is off
218
+
along with the hooks. A round carrying both a `_Stop` hook objection and a
219
+
reminder costs one rejection and delivers both texts. This is not a new
220
+
lifecycle hook — see [MCP_DRIVEN_HOOKS.md](../../docs/MCP_DRIVEN_HOOKS.md).
0 commit comments