From 7bdcd6db4bc27fafec20cef4400bd9124f6c3bd1 Mon Sep 17 00:00:00 2001
From: Lazy Joe
 <dbd8c9941ba6dafebcef0abc015b65e75d52e7452f2ce483c9c3fd4d180f2504@buzz.block.builderlab.xyz>
Date: Mon, 10 Aug 2026 17:29:21 -0700
Subject: [PATCH] fix: add thread-resolution guidance to heartbeat prompt

Co-authored-by: Cameron Hotchkies <chotchkies@block.xyz>
Signed-off-by: Cameron Hotchkies <chotchkies@block.xyz>
refs: https://github.com/block/buzz/issues/5532
---
 crates/buzz-acp/src/lib.rs | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs
index fa348eeb3c..9dc2b3a93f 100644
--- a/crates/buzz-acp/src/lib.rs
+++ b/crates/buzz-acp/src/lib.rs
@@ -4019,15 +4019,32 @@ fn default_heartbeat_prompt() -> String {
          1. Run `buzz feed get --types needs_action` to check for pending workflow approvals or\n\
             high-priority requests addressed to you.\n\
          2. Run `buzz feed get --types mentions` to check for unanswered @mentions.\n\
-         3. If you find actionable items, address them using the appropriate CLI commands\n\
-            (e.g., `buzz workflows approve --token <UUID>`, `buzz messages send`,\n\
-            `buzz messages send --reply-to <event-id>`).\n\
-         4. If there are no pending actions or mentions, end your turn immediately.\n\n\
+         3. For each actionable feed mention, call\n\
+            `buzz messages thread --channel <h-tag> --event <event_id>` to get the thread root,\n\
+            then reply with `buzz messages send --channel <h-tag> --reply-to <root>`.\n\
+         4. Address other actionable items using the appropriate CLI commands\n\
+            (e.g., `buzz workflows approve --token <UUID>`, `buzz messages send`).\n\
+         5. If there are no pending actions or mentions, end your turn immediately.\n\n\
          Do not run `buzz channels list` or `buzz messages search` unless you have a specific reason.\n\
          Do not invent work — only act on items surfaced by the feed commands."
     )
 }
 
+#[cfg(test)]
+mod heartbeat_prompt_tests {
+    use super::default_heartbeat_prompt;
+
+    #[test]
+    fn default_heartbeat_prompt_resolves_thread_root_for_feed_mentions() {
+        let prompt = default_heartbeat_prompt();
+
+        assert!(prompt.contains("For each actionable feed mention"));
+        assert!(prompt.contains("buzz messages thread --channel <h-tag> --event <event_id>"));
+        assert!(prompt.contains("to get the thread root"));
+        assert!(prompt.contains("buzz messages send --channel <h-tag> --reply-to <root>"));
+    }
+}
+
 /// Spawn a background respawn task for a crashed agent slot.
 ///
 /// Does the circuit breaker check synchronously (non-blocking), then spawns