fix(auto-mode): improve timeout handling for Opus model (#1667) (#1676)

* fix(auto-mode): improve timeout handling for Opus model (#1667)

- Increase default timeout from 5 min to 30 min
- Add --no-timeout flag for unlimited execution
- Auto-detect Opus model and use 60 min timeout
- Add comprehensive tests for timeout resolution

Fixes timeout issues where Opus appeared to skip workflow
steps but was actually being terminated mid-execution.

Closes #1667

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add timeout configuration documentation and discovery

- Added 'Per-Turn Timeout' section to AUTO_MODE.md with examples
- Added 'Turn Timeouts' troubleshooting entry
- Documented the Opus timeout discovery in DISCOVERIES.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <claude@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: rysweet

.claude/context/DISCOVERIES.md

@@ -50,6 +50,39 @@ What insights should be remembered?
 
 ---
 
+## Auto Mode Timeout Causing Opus Model Workflow Failures (2025-11-26)
+
+### Problem
+
+Opus model was "skipping" workflow steps during auto mode execution. Investigation revealed the 5-minute per-turn timeout was cutting off Opus execution mid-workflow due to extended thinking requirements.
+
+### Root Cause
+
+The default per-turn timeout of 5 minutes was too aggressive for Opus model, which requires extended thinking time. Log analysis showed:
+
+- `Turn 2 timed out after 300.0s`
+- `Turn 1 timed out after 600.1s`
+
+### Solution (PR #1676)
+
+Implemented flexible timeout resolution system:
+
+1. **Increased default timeout**: 5 min → 30 min
+2. **Added `--no-timeout` flag**: Disables timeout entirely using `nullcontext()`
+3. **Opus auto-detection**: Model names containing "opus" automatically get 60 min timeout
+4. **Clear priority system**: `--no-timeout` > explicit > auto-detect > default
+
+### Key Insight
+
+**Extended thinking models like Opus need significantly longer timeouts.** Auto-detection based on model name provides a good default without requiring users to remember to adjust settings.
+
+### Files Changed
+
+- `src/amplihack/cli.py`: Added `--no-timeout` flag and `resolve_timeout()` function
+- `src/amplihack/launcher/auto_mode.py`: Accept `None` timeout using `nullcontext`
+- `tests/unit/test_auto_mode_timeout.py`: 19 comprehensive tests
+- `docs/AUTO_MODE.md`: Added timeout configuration documentation
+
 ## Power-Steering Session Type Detection Fix (2025-11-25)
 
 ### Problem

docs/AUTO_MODE.md

@@ -149,6 +149,35 @@ Adjust based on task complexity:
 amplihack claude --auto --max-turns 25 -- -p "complex multi-module refactoring"
 ```
 
+### Per-Turn Timeout
+
+Default: 30 minutes per turn
+
+Controls how long each turn can run before timing out. This prevents runaway executions while allowing complex operations to complete.
+
+**Priority order (highest to lowest):**
+
+1. `--no-timeout` flag (disables timeout entirely)
+2. Explicit `--query-timeout-minutes` value
+3. Auto-detection (Opus models → 60 minutes)
+4. Default (30 minutes)
+
+```bash
+# Use default 30-minute timeout
+amplihack claude --auto -- -p "implement feature"
+
+# Explicit timeout (45 minutes)
+amplihack claude --auto --query-timeout-minutes 45 -- -p "complex refactoring"
+
+# Disable timeout for very long operations
+amplihack claude --auto --no-timeout -- -p "comprehensive codebase analysis"
+
+# Opus model auto-detects to 60 minutes
+amplihack claude --auto -- --model opus -p "architectural design"
+```
+
+**Note:** Opus models automatically use 60-minute timeouts due to extended thinking requirements. Use `--no-timeout` for operations expected to exceed 60 minutes.
+
 ### Session Logging
 
 All auto mode sessions are logged to:
@@ -399,6 +428,17 @@ Auto mode excels at:
 **Cause**: Syntax errors, test failures during execution
 **Solution**: Auto mode logs errors and continues. Review logs in `.claude/runtime/logs/` to see what happened.
 
+### Turn Timeouts
+
+**Cause**: A turn exceeded the per-turn timeout (default 30 minutes)
+**Solution**:
+
+- Check logs for `Turn N timed out after X seconds`
+- For Opus models, ensure auto-detection is working (uses 60 min automatically)
+- Use `--query-timeout-minutes 60` for longer operations
+- Use `--no-timeout` for very long operations (use with caution)
+- Consider breaking complex tasks into smaller subtasks
+
 ### Installation Issues (Copilot)
 
 **Cause**: GitHub Copilot CLI not installed

src/amplihack/cli.py

@@ -244,8 +244,18 @@ def handle_auto_mode(
     # Check if UI mode is enabled
     ui_mode = getattr(args, "ui", False)
 
-    # Extract timeout from args
-    query_timeout = getattr(args, "query_timeout_minutes", 5.0)
+    # Extract model from cmd_args for timeout auto-detection
+    model = None
+    if cmd_args and "--model" in cmd_args:
+        try:
+            model_idx = cmd_args.index("--model")
+            if model_idx + 1 < len(cmd_args):
+                model = cmd_args[model_idx + 1]
+        except (ValueError, IndexError):
+            pass
+
+    # Resolve timeout using priority: --no-timeout > explicit > model auto-detect > default
+    query_timeout = resolve_timeout(args, model)
 
     auto = AutoMode(
         sdk, prompt, args.max_turns, ui_mode=ui_mode, query_timeout_minutes=query_timeout
@@ -358,14 +368,51 @@ def add_auto_mode_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--query-timeout-minutes",
         type=float,
-        default=5.0,
+        default=30.0,
         metavar="MINUTES",
         help=(
-            "Timeout for each SDK query in minutes (default: 5.0). "
-            "Prevents indefinite hangs in complex sessions. "
-            "Use higher values (10-15) for very long-running operations."
+            "Timeout for each SDK query in minutes (default: 30). "
+            "Opus models auto-detect to 60 minutes. "
+            "Use --no-timeout to disable timeout completely."
         ),
     )
+    parser.add_argument(
+        "--no-timeout",
+        action="store_true",
+        help="Disable timeout for SDK queries (allows indefinite execution).",
+    )
+
+
+def resolve_timeout(args: argparse.Namespace, model: Optional[str] = None) -> Optional[float]:
+    """Resolve timeout value based on CLI args and model detection.
+
+    Priority order:
+    1. --no-timeout flag (returns None)
+    2. Explicit --query-timeout-minutes value (if not default 30.0)
+    3. Auto-detect Opus model (60 minutes)
+    4. Default from argparse (30 minutes)
+
+    Args:
+        args: Parsed command line arguments
+        model: Model name from --model arg (for Opus detection)
+
+    Returns:
+        Timeout in minutes, or None for no timeout
+    """
+    # Priority 1: --no-timeout flag takes precedence
+    if getattr(args, "no_timeout", False):
+        return None
+
+    # Get the timeout value (defaults to 30.0 from argparse)
+    timeout = getattr(args, "query_timeout_minutes", 30.0)
+
+    # Priority 3: Auto-detect Opus model (60 minute timeout)
+    # Only apply if timeout is the default (30.0), meaning user didn't explicitly override
+    if model and "opus" in model.lower() and timeout == 30.0:
+        return 60.0
+
+    # Return the timeout value (explicit or default)
+    return timeout
 
 
 def add_common_sdk_args(parser: argparse.ArgumentParser) -> None:

src/amplihack/launcher/auto_mode.py

@@ -9,6 +9,7 @@
 import sys
 import threading
 import time
+from contextlib import nullcontext
 from pathlib import Path
 from typing import Optional, Tuple
 
@@ -80,7 +81,7 @@ def __init__(
         max_turns: int = 10,
         working_dir: Optional[Path] = None,
         ui_mode: bool = False,
-        query_timeout_minutes: float = 5.0,
+        query_timeout_minutes: Optional[float] = 30.0,
     ):
         """Initialize auto mode.
 
@@ -90,7 +91,8 @@ def __init__(
             max_turns: Max iterations (default 10)
             working_dir: Working directory (defaults to current dir)
             ui_mode: Enable interactive UI mode (requires Rich library)
-            query_timeout_minutes: Timeout for each SDK query in minutes (default 5.0)
+            query_timeout_minutes: Timeout for each SDK query in minutes (default 30.0).
+                None disables timeout. Opus detection is handled by cli.py:resolve_timeout().
         """
         self.sdk = sdk
         self.prompt = prompt
@@ -100,13 +102,23 @@ def __init__(
         self.working_dir = working_dir if working_dir is not None else Path.cwd()
         self.ui_enabled = ui_mode
         self.ui = None
-        # Validate timeout value
-        if query_timeout_minutes <= 0:
-            raise ValueError(f"query_timeout_minutes must be positive, got {query_timeout_minutes}")
-        if query_timeout_minutes > 120:  # 2 hours max - warn but allow
-            print(f"Warning: Very long timeout ({query_timeout_minutes} minutes)", file=sys.stderr)
 
-        self.query_timeout_seconds = query_timeout_minutes * 60.0  # Keep as float for precision
+        # Handle timeout: None means no timeout, otherwise validate
+        if query_timeout_minutes is None:
+            # No timeout - used for --no-timeout flag
+            self.query_timeout_seconds: Optional[float] = None
+        else:
+            # Validate positive timeout
+            if query_timeout_minutes <= 0:
+                raise ValueError(
+                    f"query_timeout_minutes must be positive, got {query_timeout_minutes}"
+                )
+            if query_timeout_minutes > 120:  # 2 hours max - warn but allow
+                print(
+                    f"Warning: Very long timeout ({query_timeout_minutes} minutes)", file=sys.stderr
+                )
+
+            self.query_timeout_seconds = query_timeout_minutes * 60.0  # Keep as float for precision
         self.log_dir = (
             self.working_dir / ".claude" / "runtime" / "logs" / f"auto_{sdk}_{int(time.time())}"
         )
@@ -527,8 +539,13 @@ async def _run_turn_with_sdk(self, prompt: str) -> Tuple[int, str]:
             # Track turn start time for accurate timeout reporting
             turn_start_time = time.time()
 
-            # Add timeout wrapper around SDK query
-            async with asyncio.timeout(self.query_timeout_seconds):
+            # Add timeout wrapper around SDK query (use nullcontext if no timeout)
+            timeout_ctx = (
+                asyncio.timeout(self.query_timeout_seconds)
+                if self.query_timeout_seconds is not None
+                else nullcontext()
+            )
+            async with timeout_ctx:
                 async for message in query(prompt=prompt, options=options):
                     print("\n[DEBUG] 💬 Got a message from query()", flush=True)
                     # Handle different message types