Enhance loop recovery hints and streamline error handling in tool execution

Author: vinhnx

src/agent/runloop/tool_output/mod.rs

@@ -35,8 +35,28 @@ use mcp::{
 use streams::render_stream_section;
 use styles::{GitStyles, LsStyles};
 
+fn tool_recovery_hint(val: &Value) -> Option<&'static str> {
+    if !val
+        .get("loop_detected")
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+    {
+        return None;
+    }
+    if val.get("spool_path").and_then(Value::as_str).is_some() {
+        return Some("Loop detected; continue from spooled output.");
+    }
+    if val.get("fallback_tool").and_then(Value::as_str).is_some() {
+        return Some("Loop detected; fallback is available.");
+    }
+    Some("Loop detected; change approach before retrying.")
+}
+
 fn tool_follow_up_hints(val: &Value) -> Vec<String> {
-    let mut hints = Vec::with_capacity(2);
+    let mut hints = Vec::with_capacity(3);
+    if let Some(hint) = tool_recovery_hint(val) {
+        hints.push(hint.to_string());
+    }
     if let Some(path) = val.get("spool_path").and_then(Value::as_str) {
         hints.push(format!(
             "Large output was spooled to \"{}\". Use read_file/grep_file to inspect details.",
@@ -759,6 +779,81 @@ mod tests {
         assert!(inline_output.contains("Large output was spooled to"));
     }
 
+    #[tokio::test]
+    async fn render_tool_output_renders_loop_recovery_hint_from_structured_fields() {
+        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
+        let mut renderer =
+            AnsiRenderer::with_inline_ui(InlineHandle::new_for_tests(sender), Default::default());
+        let payload = json!({
+            "loop_detected": true,
+            "fallback_tool": vtcode_core::config::constants::tools::UNIFIED_SEARCH
+        });
+
+        render_tool_output(
+            &mut renderer,
+            Some(vtcode_core::config::constants::tools::UNIFIED_SEARCH),
+            &payload,
+            None,
+        )
+        .await
+        .expect("loop recovery hint payload should render");
+
+        let inline_output = collect_inline_output(&mut receiver);
+        assert!(inline_output.contains("Loop detected; fallback is available."));
+    }
+
+    #[tokio::test]
+    async fn render_tool_output_renders_spooled_loop_recovery_hint() {
+        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
+        let mut renderer =
+            AnsiRenderer::with_inline_ui(InlineHandle::new_for_tests(sender), Default::default());
+        let payload = json!({
+            "loop_detected": true,
+            "spool_path": ".vtcode/context/tool_outputs/readme.txt",
+            "next_read_args": {
+                "path": ".vtcode/context/tool_outputs/readme.txt",
+                "offset": 81,
+                "limit": 40
+            }
+        });
+
+        render_tool_output(
+            &mut renderer,
+            Some(vtcode_core::config::constants::tools::READ_FILE),
+            &payload,
+            None,
+        )
+        .await
+        .expect("spooled loop recovery hint payload should render");
+
+        let inline_output = collect_inline_output(&mut receiver);
+        assert!(inline_output.contains("Loop detected; continue from spooled output."));
+    }
+
+    #[tokio::test]
+    async fn render_tool_output_does_not_duplicate_loop_recovery_hint() {
+        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
+        let mut renderer =
+            AnsiRenderer::with_inline_ui(InlineHandle::new_for_tests(sender), Default::default());
+        let payload = json!({
+            "loop_detected": true,
+            "fallback_tool": vtcode_core::config::constants::tools::UNIFIED_SEARCH,
+            "output": "Loop detected; fallback is available."
+        });
+
+        render_tool_output(&mut renderer, Some("custom_tool"), &payload, None)
+            .await
+            .expect("duplicate hint payload should render");
+
+        let inline_output = collect_inline_output(&mut receiver);
+        assert_eq!(
+            inline_output
+                .matches("Loop detected; fallback is available.")
+                .count(),
+            1
+        );
+    }
+
     #[test]
     fn tracker_summary_lines_include_progress_and_active_items() {
         let payload = json!({

src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs

@@ -283,7 +283,7 @@ pub(crate) fn build_error_content(
                 inline_full_args,
             );
         }
-        payload
+        compact_model_tool_payload(payload)
     } else {
         let mut payload = serde_json::json!({
             "error": error_text,
@@ -293,7 +293,7 @@ pub(crate) fn build_error_content(
             "next_action": next_action,
         });
         push_error_truncation_flag(&mut payload, error_truncated);
-        payload
+        compact_model_tool_payload(payload)
     }
 }
 
@@ -492,9 +492,9 @@ pub(crate) async fn handle_tool_execution_result<'a>(
     Ok(None)
 }
 
-pub(super) fn maybe_inline_spooled(_tool_name: &str, output: &serde_json::Value) -> String {
+pub(crate) fn compact_model_tool_payload(output: serde_json::Value) -> serde_json::Value {
     let Some(obj) = output.as_object() else {
-        return serialize_output(output);
+        return output;
     };
 
     let next_continue_args = obj
@@ -510,6 +510,10 @@ pub(super) fn maybe_inline_spooled(_tool_name: &str, output: &serde_json::Value)
             .map(|next_continue| next_continue.session_id.as_str())
     });
     let has_spool_path = obj.contains_key("spool_path");
+    let loop_detected = obj
+        .get("loop_detected")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false);
     let is_exec_like = obj.contains_key("command")
         || obj.contains_key("working_directory")
         || session_id.is_some()
@@ -538,26 +542,35 @@ pub(super) fn maybe_inline_spooled(_tool_name: &str, output: &serde_json::Value)
             "spool_hint" | "spooled_bytes" | "spooled_to_file" => has_spool_path,
             "id" => session_id.is_some_and(|sid| value == sid),
             "working_directory" => is_exec_like,
+            "next_action" => true,
             "has_more" | "preferred_next_action" => {
                 next_continue_args.is_some() || next_read_args.is_some() || is_false_bool(value)
             }
             "session_id" | "command" => is_exec_like,
-            "spool_path" => next_read_args
-                .as_ref()
-                .is_some_and(|next_read| value == next_read.path.as_str()),
+            "spool_path" => {
+                !loop_detected
+                    && next_read_args
+                        .as_ref()
+                        .is_some_and(|next_read| value == next_read.path.as_str())
+            }
             "next_offset" => next_read_args
                 .as_ref()
                 .is_some_and(|next_read| value_matches_usize(value, next_read.offset)),
             "chunk_limit" => next_read_args
                 .as_ref()
                 .is_some_and(|next_read| value_matches_usize(value, next_read.limit)),
             "stderr_preview" => has_stderr,
-            "truncated"
-            | "auto_recovered"
+            "loop_detected_note"
+            | "spool_ref_only"
+            | "result_ref_only"
             | "reused_spooled_output"
             | "reused_recent_result"
-            | "loop_detected"
-            | "query_truncated" => is_false_bool(value),
+            | "repeat_count"
+            | "tool" => loop_detected,
+            "limit" => loop_detected && obj.get("tool").is_some(),
+            "truncated" | "auto_recovered" | "loop_detected" | "query_truncated" => {
+                is_false_bool(value)
+            }
             "stdout" => output_value.is_some_and(|output| output == value),
             "process_id" => is_exec_like || process_session_id.is_some_and(|sid| value == sid),
             "is_exited" => {
@@ -581,7 +594,11 @@ pub(super) fn maybe_inline_spooled(_tool_name: &str, output: &serde_json::Value)
         sanitized.insert(key.clone(), cloned_value);
     }
 
-    serialize_output(&serde_json::Value::Object(sanitized))
+    serde_json::Value::Object(sanitized)
+}
+
+pub(super) fn maybe_inline_spooled(_tool_name: &str, output: &serde_json::Value) -> String {
+    serialize_output(&compact_model_tool_payload(output.clone()))
 }
 
 fn compact_next_continue_args(value: &serde_json::Value) -> serde_json::Value {
@@ -1118,6 +1135,31 @@ mod tests {
                 .and_then(|v| v.as_str())
                 .is_some()
         );
+        assert!(payload.get("next_action").is_none());
+    }
+
+    #[test]
+    fn build_error_content_keeps_structured_fallback_fields_only() {
+        let payload = build_error_content(
+            "boom".to_string(),
+            Some(tool_names::UNIFIED_SEARCH.to_string()),
+            Some(serde_json::json!({"action":"list","path":"."})),
+            "execution",
+        );
+
+        assert_eq!(
+            payload.get("fallback_tool"),
+            Some(&serde_json::json!(tool_names::UNIFIED_SEARCH))
+        );
+        assert_eq!(
+            payload.get("fallback_tool_args"),
+            Some(&serde_json::json!({"action":"list","path":"."}))
+        );
+        assert_eq!(
+            payload.get("is_recoverable").and_then(|v| v.as_bool()),
+            Some(true)
+        );
+        assert!(payload.get("next_action").is_none());
     }
 
     #[test]
@@ -1257,6 +1299,52 @@ mod tests {
         );
     }
 
+    #[test]
+    fn maybe_inline_spooled_keeps_loop_recovery_fields_and_drops_notes() {
+        let serialized = maybe_inline_spooled(
+            tool_names::READ_FILE,
+            &serde_json::json!({
+                "loop_detected": true,
+                "spool_path": ".vtcode/context/tool_outputs/unified_exec_loop.txt",
+                "next_read_args": {
+                    "path": ".vtcode/context/tool_outputs/unified_exec_loop.txt",
+                    "offset": 81,
+                    "limit": 40
+                },
+                "reused_spooled_output": true,
+                "spool_ref_only": true,
+                "loop_detected_note": "Read the spool file instead of re-running this call.",
+                "repeat_count": 4,
+                "limit": 3,
+                "tool": "read_file"
+            }),
+        );
+
+        let parsed: serde_json::Value =
+            serde_json::from_str(&serialized).expect("serialized JSON payload");
+        assert_eq!(parsed.get("loop_detected"), Some(&serde_json::json!(true)));
+        assert_eq!(
+            parsed.get("spool_path"),
+            Some(&serde_json::json!(
+                ".vtcode/context/tool_outputs/unified_exec_loop.txt"
+            ))
+        );
+        assert_eq!(
+            parsed.get("next_read_args"),
+            Some(&serde_json::json!({
+                "path": ".vtcode/context/tool_outputs/unified_exec_loop.txt",
+                "offset": 81,
+                "limit": 40
+            }))
+        );
+        assert!(parsed.get("reused_spooled_output").is_none());
+        assert!(parsed.get("spool_ref_only").is_none());
+        assert!(parsed.get("loop_detected_note").is_none());
+        assert!(parsed.get("repeat_count").is_none());
+        assert!(parsed.get("limit").is_none());
+        assert!(parsed.get("tool").is_none());
+    }
+
     #[test]
     fn maybe_inline_spooled_drops_terminal_exec_metadata_without_continuation() {
         let serialized = maybe_inline_spooled(

src/agent/runloop/unified/turn/tool_outcomes/handlers/fallbacks.rs

@@ -5,6 +5,7 @@ use vtcode_core::tools::registry::ToolPreflightOutcome;
 use vtcode_core::tools::tool_intent;
 
 use crate::agent::runloop::unified::turn::context::TurnProcessingContext;
+use crate::agent::runloop::unified::turn::tool_outcomes::execution_result::compact_model_tool_payload;
 
 pub(super) fn recovery_fallback_for_tool(tool_name: &str, args: &Value) -> Option<(String, Value)> {
     match tool_name {
@@ -64,6 +65,7 @@ pub(super) fn build_validation_error_content_with_fallback(
     fallback_tool_args: Option<Value>,
 ) -> String {
     let is_recoverable = fallback_tool.is_some();
+    let loop_detected = validation_stage == "loop_detection";
     let next_action = if is_recoverable {
         "Retry with fallback_tool_args."
     } else {
@@ -76,6 +78,7 @@ pub(super) fn build_validation_error_content_with_fallback(
         "validation_stage": validation_stage,
         "retryable": false,
         "is_recoverable": is_recoverable,
+        "loop_detected": loop_detected,
         "next_action": next_action,
     });
     if let Some(obj) = payload.as_object_mut() {
@@ -86,7 +89,7 @@ pub(super) fn build_validation_error_content_with_fallback(
             obj.insert("fallback_tool_args".to_string(), args);
         }
     }
-    payload.to_string()
+    compact_model_tool_payload(payload).to_string()
 }
 
 pub(super) fn preflight_validation_fallback(

src/agent/runloop/unified/turn/tool_outcomes/handlers/tests.rs

@@ -651,6 +651,24 @@ fn validation_error_payload_includes_fallback_metadata() {
     assert_eq!(parsed["is_recoverable"], true);
     assert_eq!(parsed["fallback_tool"], tool_names::UNIFIED_SEARCH);
     assert_eq!(parsed["fallback_tool_args"]["action"], "grep");
+    assert!(parsed.get("next_action").is_none());
+    assert!(parsed.get("loop_detected").is_none());
+}
+
+#[test]
+fn validation_error_payload_marks_loop_detection_without_prose_hint() {
+    let payload = build_validation_error_content_with_fallback(
+        "Tool 'read_file' is blocked due to excessive repetition (Loop Detected).".to_string(),
+        "loop_detection",
+        Some(tool_names::UNIFIED_SEARCH.to_string()),
+        Some(json!({"action":"list","path":"."})),
+    );
+    let parsed: serde_json::Value =
+        serde_json::from_str(&payload).expect("validation payload should be json");
+    assert_eq!(parsed.get("loop_detected"), Some(&json!(true)));
+    assert_eq!(parsed["fallback_tool"], tool_names::UNIFIED_SEARCH);
+    assert_eq!(parsed["fallback_tool_args"]["action"], "list");
+    assert!(parsed.get("next_action").is_none());
 }
 
 #[test]

vtcode.toml

@@ -59,7 +59,7 @@ read_file = true
 # Environment variable that stores the API key for the active provider
 # Default: "OPENAI_API_KEY"
 # Type: `string`
-api_key_env = "OPENROUTER_API_KEY"
+api_key_env = "MINIMAX_API_KEY"
 
 # Enable autonomous mode - auto-approve safe tools with reduced HITL prompts When true, the agent
 # operates with fewer confirmation prompts for safe tools.
@@ -86,7 +86,7 @@ default_editing_mode = "edit"
 # Default model to use
 # Default: "gpt-5.3-codex"
 # Type: `string`
-default_model = "nvidia/nemotron-3-super-120b-a12b:free"
+default_model = "MiniMax-M2.5"
 
 # Enable an extra self-review pass to refine final responses
 # Default: false
@@ -148,7 +148,7 @@ project_doc_max_bytes = 16384
 # Possible values: anthropic, gemini, openai, openrouter, zai
 # Default: "openai"
 # Type: `string`
-provider = "openrouter"
+provider = "minimax"
 
 # Reasoning effort level for models that support it (none, minimal, low, medium, high, xhigh) Applies
 # to: Claude, GPT-5 family, Gemini, Qwen3, DeepSeek with reasoning capability
@@ -209,7 +209,7 @@ temporal_context_use_utc = false
 # UI theme identifier controlling ANSI styling
 # Default: "ciapre"
 # Type: `string`
-theme = "ciapre"
+theme = "ansi-classic"
 
 # Enable TODO planning helper mode for structured task management
 # Default: true