feat(subagent): enforce explicit summary output from subagents

When a subagent completes without providing a structured summary, the
executor now requests an additional turn specifically asking for a summary.
This ensures subagents always return properly formatted output for the
orchestrator to process.

The fix:
- Adds has_summary_output() function to detect summary markers in output
- Requests explicit summary turn if output doesn't contain summary markers
- Uses SUMMARY_REQUEST_PROMPT constant with structured format requirements
- Combines original response with summary in the final result
- Properly tracks token usage across both turns

This follows the Codex pattern of ensuring structured agent output and
resolves the issue where subagents would terminate without providing
feedback to the orchestrator.

Author: factorydroid

cortex-engine/src/tools/handlers/subagent/executor.rs

@@ -8,7 +8,9 @@ use tokio::sync::{RwLock, mpsc};
 use tokio::time::timeout;
 use uuid::Uuid;
 
-use crate::agent::{AgentConfig, AgentEvent, Orchestrator, SandboxPolicy, TurnStatus};
+use crate::agent::{
+    AgentConfig, AgentEvent, Orchestrator, OrchestratorTurnResult, SandboxPolicy, TurnStatus,
+};
 use crate::agents::{Agent, AgentRegistry};
 use crate::client::ModelClient;
 use crate::error::{CortexError, Result};
@@ -424,7 +426,7 @@ impl SubagentExecutor {
         );
 
         // Execute with optional timeout (like OpenCode, no timeout by default)
-        let turn_result = if let Some(timeout_duration) = config.effective_timeout() {
+        let mut turn_result = if let Some(timeout_duration) = config.effective_timeout() {
             // With timeout
             match timeout(timeout_duration, orchestrator.process_turn(&mut turn_ctx)).await {
                 Ok(result) => result,
@@ -439,6 +441,65 @@ impl SubagentExecutor {
             orchestrator.process_turn(&mut turn_ctx).await
         };
 
+        // MANDATORY: Request explicit summary if the response doesn't contain one
+        // This ensures subagents always provide structured output for the orchestrator
+        if let Ok(ref result) = turn_result {
+            if result.status == TurnStatus::Completed && !has_summary_output(&result.response) {
+                tracing::info!(
+                    session_id = %session_id,
+                    "Subagent output missing summary, requesting explicit summary turn"
+                );
+
+                // Request a summary turn
+                let summary_prompt = SUMMARY_REQUEST_PROMPT.to_string();
+
+                let summary_turn_id = session.turns_completed as u64 + 2;
+                let mut summary_turn_ctx = crate::agent::TurnContext::new(
+                    summary_turn_id,
+                    session_id.clone(),
+                    summary_prompt,
+                    config.working_dir.clone(),
+                );
+
+                // Execute summary turn with a reasonable timeout
+                let summary_result = timeout(
+                    Duration::from_secs(60),
+                    orchestrator.process_turn(&mut summary_turn_ctx),
+                )
+                .await;
+
+                // Update turn_result with the summary if successful
+                if let Ok(Ok(summary_response)) = summary_result {
+                    if summary_response.status == TurnStatus::Completed
+                        && !summary_response.response.is_empty()
+                    {
+                        tracing::info!(
+                            session_id = %session_id,
+                            "Received explicit summary from subagent"
+                        );
+                        // Combine original response with summary
+                        turn_result = Ok(OrchestratorTurnResult {
+                            turn_id: result.turn_id,
+                            status: TurnStatus::Completed,
+                            response: format!(
+                                "{}\n\n{}",
+                                result.response, summary_response.response
+                            ),
+                            tool_calls: result.tool_calls.clone(),
+                            token_usage: result.token_usage.clone(),
+                            duration: result.duration,
+                        });
+                        // Update token counts
+                        turn_ctx.tokens.input_tokens += summary_turn_ctx.tokens.input_tokens;
+                        turn_ctx.tokens.output_tokens += summary_turn_ctx.tokens.output_tokens;
+                        turn_ctx.tokens.cached_tokens += summary_turn_ctx.tokens.cached_tokens;
+                        turn_ctx.tokens.reasoning_tokens +=
+                            summary_turn_ctx.tokens.reasoning_tokens;
+                    }
+                }
+            }
+        }
+
         // CRITICAL: Drop orchestrator to close the event channel
         // This allows event_handler to exit its recv() loop
         // Without this, we'd have a deadlock:
@@ -646,6 +707,56 @@ pub struct SubagentTypeInfo {
 }
 
 /// Extract file path from tool output.
+/// Prompt used to request an explicit summary from a subagent when none was provided.
+/// This follows the Codex pattern of ensuring structured output from agents.
+const SUMMARY_REQUEST_PROMPT: &str = r#"You have completed your work but did not provide a summary. Please provide a final summary NOW using EXACTLY this format:
+
+## Summary for Orchestrator
+
+### Tasks Completed
+- [List each task you completed with brief outcome]
+
+### Key Findings/Changes
+- [Main discoveries or modifications made]
+
+### Files Modified (if any)
+- [List of files with type of change]
+
+### Recommendations (if applicable)
+- [Any follow-up actions or suggestions]
+
+### Status: COMPLETED
+
+DO NOT use any tools. Just provide the summary based on the work you have already done."#;
+
+/// Check if the response contains a proper summary for the orchestrator.
+/// Returns true if summary markers are present, false otherwise.
+fn has_summary_output(response: &str) -> bool {
+    // Empty responses definitely don't have a summary
+    if response.trim().is_empty() {
+        return false;
+    }
+
+    // Check for key summary markers that indicate structured output
+    let summary_markers = [
+        "## Summary for Orchestrator",
+        "### Tasks Completed",
+        "### Key Findings",
+        "### Status: COMPLETED",
+        "Status: COMPLETED",
+        // Also accept some variations
+        "## Summary",
+        "### Summary",
+        "## Final Summary",
+        "### Final Summary",
+    ];
+
+    let response_lower = response.to_lowercase();
+    summary_markers
+        .iter()
+        .any(|marker| response_lower.contains(&marker.to_lowercase()))
+}
+
 fn extract_file_path(output: &str) -> Option<String> {
     // Try to extract path from common patterns
     // "Created file: path/to/file"
@@ -697,6 +808,49 @@ mod tests {
         assert_eq!(extract_file_path("No path here"), None);
     }
 
+    #[test]
+    fn test_has_summary_output_with_proper_summary() {
+        let response_with_summary = r#"
+## Summary for Orchestrator
+
+### Tasks Completed
+- Analyzed the codebase structure
+
+### Key Findings
+- Found 10 modules
+
+### Status: COMPLETED
+"#;
+        assert!(has_summary_output(response_with_summary));
+    }
+
+    #[test]
+    fn test_has_summary_output_with_variation() {
+        // Test case-insensitive matching
+        let response = "## summary\nSome content here";
+        assert!(has_summary_output(response));
+
+        // Test "Status: COMPLETED" alone
+        let response2 = "Work done.\n\nStatus: COMPLETED";
+        assert!(has_summary_output(response2));
+    }
+
+    #[test]
+    fn test_has_summary_output_empty() {
+        assert!(!has_summary_output(""));
+        assert!(!has_summary_output("   "));
+        assert!(!has_summary_output("\n\n"));
+    }
+
+    #[test]
+    fn test_has_summary_output_no_markers() {
+        let response_without_summary = "I analyzed the code and found some issues.";
+        assert!(!has_summary_output(response_without_summary));
+
+        let response_partial = "Here are some findings:\n- Item 1\n- Item 2";
+        assert!(!has_summary_output(response_partial));
+    }
+
     #[test]
     fn test_subagent_type_info() {
         let executor = SubagentExecutor::new(