From 93b2f8e8673cec3adbd8b77a20ee5f313a3ee736 Mon Sep 17 00:00:00 2001
From: hexin <he.xin@h3c.com>
Date: Mon, 25 May 2026 11:41:44 +0800
Subject: [PATCH] fix(engine): use user role for sub-agent completion runtime
 message
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sub-agent completion hand-off injected into the parent turn used
role "system". Some OpenAI-compatible backends apply a strict chat
template (e.g. vLLM serving Qwen3) that requires any system message to
be messages[0]; a system message appended mid-conversation makes the
template raise "System message must be at the beginning", returned as a
400 BadRequest that breaks the entire sub-agent hand-off in the parent
turn.

Switch the role to "user". The internal-event framing is already carried
by the `visibility="internal"` tag and the surrounding text, so the role
change costs no semantics — it only removes the template incompatibility.
Updates the colocated unit test to pin the new role.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/tui/src/core/engine/turn_loop.rs | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/crates/tui/src/core/engine/turn_loop.rs b/crates/tui/src/core/engine/turn_loop.rs
index 9f2da5ffd..cf04a955a 100644
--- a/crates/tui/src/core/engine/turn_loop.rs
+++ b/crates/tui/src/core/engine/turn_loop.rs
@@ -2021,8 +2021,16 @@ impl Engine {
 }
 
 fn subagent_completion_runtime_message(payload: &str) -> Message {
+    // Role is "user", not "system": some OpenAI-compatible backends apply a
+    // strict chat template (e.g. vLLM serving Qwen3) that requires any system
+    // message to be messages[0]. A system message appended mid-conversation
+    // makes the template raise "System message must be at the beginning",
+    // which surfaces as a 400 BadRequest and breaks the whole sub-agent
+    // hand-off in the parent turn. The `visibility="internal"` tag already
+    // tells the model this is a runtime event rather than user input, so the
+    // role carries no semantic weight here — only template-compatibility cost.
     Message {
-        role: "system".to_string(),
+        role: "user".to_string(),
         content: vec![ContentBlock::Text {
             text: format!(
                 "<codewhale:runtime_event kind=\"subagent_completion\" visibility=\"internal\">\n\
@@ -2122,12 +2130,16 @@ mod tests {
     use super::*;
 
     #[test]
-    fn subagent_completion_handoff_is_internal_system_message() {
+    fn subagent_completion_handoff_is_internal_user_message() {
         let message = subagent_completion_runtime_message(
             "Build passed\n<codewhale:subagent.done>{\"agent_id\":\"agent_a\"}</codewhale:subagent.done>",
         );
 
-        assert_eq!(message.role, "system");
+        // Must be "user", not "system": a system message appended mid-stream
+        // trips strict chat templates (vLLM/Qwen3) into a 400 BadRequest
+        // ("System message must be at the beginning"). The internal-event
+        // framing lives in the text + visibility tag, not the role.
+        assert_eq!(message.role, "user");
         let text = match &message.content[0] {
             ContentBlock::Text { text, .. } => text,
             other => panic!("expected text block, got {other:?}"),