tunacode-cli 0.0.54__py3-none-any.whl → 0.0.56__py3-none-any.whl

tunacode/core/state.py

@@ -2,6 +2,8 @@
 
 State management system for session data in TunaCode CLI.
 Handles user preferences, conversation history, and runtime state.
+
+CLAUDE_ANCHOR[state-module]: Central state management and session tracking
 """
 
 import uuid
@@ -13,6 +15,8 @@ from tunacode.types import (
     InputSessions,
     MessageHistory,
     ModelName,
+    PlanDoc,
+    PlanPhase,
     SessionId,
     TodoItem,
     ToolName,
@@ -27,6 +31,8 @@ if TYPE_CHECKING:
 
 @dataclass
 class SessionState:
+    """CLAUDE_ANCHOR[session-state]: Core session state container"""
+
     user_config: UserConfig = field(default_factory=dict)
     agents: dict[str, Any] = field(
         default_factory=dict
@@ -44,9 +50,7 @@ class SessionState:
     input_sessions: InputSessions = field(default_factory=dict)
     current_task: Optional[Any] = None
     todos: list[TodoItem] = field(default_factory=list)
-    # ESC key tracking for double-press functionality
-    esc_press_count: int = 0
-    last_esc_time: Optional[float] = None
+    # Operation state tracking
     operation_cancelled: bool = False
     # Enhanced tracking for thoughts display
     files_in_context: set[str] = field(default_factory=set)
@@ -82,6 +86,12 @@ class SessionState:
     task_hierarchy: dict[str, Any] = field(default_factory=dict)
     iteration_budgets: dict[str, int] = field(default_factory=dict)
     recursive_context_stack: list[dict[str, Any]] = field(default_factory=list)
+    
+    # Plan Mode state tracking
+    plan_mode: bool = False
+    plan_phase: Optional[PlanPhase] = None
+    current_plan: Optional[PlanDoc] = None
+    plan_approved: bool = False
 
     def update_token_count(self):
         """Calculates the total token count from messages and files in context."""
@@ -92,6 +102,8 @@ class SessionState:
 
 
 class StateManager:
+    """CLAUDE_ANCHOR[state-manager]: Main state manager singleton"""
+
     def __init__(self):
         self._session = SessionState()
         self._tool_handler: Optional["ToolHandler"] = None
@@ -163,3 +175,39 @@ class StateManager:
     def reset_session(self) -> None:
         """Reset the session to a fresh state."""
         self._session = SessionState()
+
+    # Plan Mode methods
+    def enter_plan_mode(self) -> None:
+        """Enter plan mode - restricts to read-only operations."""
+        self._session.plan_mode = True
+        self._session.plan_phase = PlanPhase.PLANNING_RESEARCH
+        self._session.current_plan = None
+        self._session.plan_approved = False
+        # Clear agent cache to force recreation with plan mode tools
+        self._session.agents.clear()
+
+    def exit_plan_mode(self, plan: Optional[PlanDoc] = None) -> None:
+        """Exit plan mode with optional plan data."""
+        self._session.plan_mode = False
+        self._session.plan_phase = None
+        self._session.current_plan = plan
+        self._session.plan_approved = False
+        # Clear agent cache to force recreation without plan mode tools
+        self._session.agents.clear()
+
+    def approve_plan(self) -> None:
+        """Mark current plan as approved for execution."""
+        self._session.plan_approved = True
+        self._session.plan_mode = False
+
+    def is_plan_mode(self) -> bool:
+        """Check if currently in plan mode."""
+        return self._session.plan_mode
+
+    def set_current_plan(self, plan: PlanDoc) -> None:
+        """Set the current plan data."""
+        self._session.current_plan = plan
+
+    def get_current_plan(self) -> Optional[PlanDoc]:
+        """Get the current plan data."""
+        return self._session.current_plan

tunacode/core/tool_handler.py

@@ -41,6 +41,14 @@ class ToolHandler:
         Returns:
             bool: True if confirmation is required, False otherwise.
         """
+        # Never confirm present_plan - it has its own approval flow
+        if tool_name == "present_plan":
+            return False
+            
+        # Block write tools in plan mode
+        if self.is_tool_blocked_in_plan_mode(tool_name):
+            return True  # Force confirmation for blocked tools
+
         # Skip confirmation for read-only tools
         if is_read_only_tool(tool_name):
             return False
@@ -52,6 +60,18 @@ class ToolHandler:
 
         return not (self.state.session.yolo or tool_name in self.state.session.tool_ignore)
 
+    def is_tool_blocked_in_plan_mode(self, tool_name: ToolName) -> bool:
+        """Check if tool is blocked in plan mode."""
+        if not self.state.is_plan_mode():
+            return False
+        
+        # Allow present_plan tool to end planning phase
+        if tool_name == "present_plan":
+            return False
+            
+        # Allow read-only tools
+        return not is_read_only_tool(tool_name)
+
     def process_confirmation(self, response: ToolConfirmationResponse, tool_name: ToolName) -> bool:
         """
         Process the confirmation response.

tunacode/prompts/system.md

@@ -7,10 +7,11 @@ You are **"TunaCode"**, a **senior software developer AI assistant operating ins
 Your task is to **execute real actions** via tools and **report observations** after every tool use.
 
 **CRITICAL BEHAVIOR RULES:**
-1. When you say "Let me..." or "I will..." you MUST execute the corresponding tool in THE SAME RESPONSE
-2. Never describe what you'll do without doing it - ALWAYS execute tools when discussing actions
-3. When a task is COMPLETE, start your response with: TUNACODE_TASK_COMPLETE
-4. If your response is cut off or truncated, you'll be prompted to continue - complete your action
+1. **ALWAYS ANNOUNCE YOUR INTENTIONS FIRST**: Before executing any tools, briefly state what you're about to do (e.g., "I'll search for the main agent implementation" or "Let me examine the file structure")
+2. When you say "Let me..." or "I will..." you MUST execute the corresponding tool in THE SAME RESPONSE
+3. Never describe what you'll do without doing it - ALWAYS execute tools when discussing actions
+4. When a task is COMPLETE, start your response with: TUNACODE_TASK_COMPLETE
+5. If your response is cut off or truncated, you'll be prompted to continue - complete your action
 
 You MUST follow these rules:
 

tunacode/tools/exit_plan_mode.py

@@ -0,0 +1,191 @@
+"""Tool for exiting plan mode and presenting implementation plan."""
+
+from typing import Any, Dict, List
+
+from tunacode.tools.base import BaseTool
+from tunacode.ui import console as ui
+from tunacode.types import ToolResult
+
+
+class ExitPlanModeTool(BaseTool):
+    """Present implementation plan and exit plan mode."""
+    
+    def __init__(self, state_manager, ui_logger=None):
+        """Initialize the exit plan mode tool.
+        
+        Args:
+            state_manager: StateManager instance for controlling plan mode state
+            ui_logger: UI logger instance for displaying messages
+        """
+        super().__init__(ui_logger)
+        self.state_manager = state_manager
+    
+    @property
+    def tool_name(self) -> str:
+        return "exit_plan_mode"
+    
+    async def _execute(
+        self,
+        plan_title: str,
+        overview: str,
+        implementation_steps: List[str],
+        files_to_modify: List[str] = None,
+        files_to_create: List[str] = None,
+        risks_and_considerations: List[str] = None,
+        testing_approach: str = None,
+        success_criteria: List[str] = None,
+    ) -> ToolResult:
+        """Present the implementation plan and get user approval."""
+        
+        plan = {
+            "title": plan_title,
+            "overview": overview,
+            "files_to_modify": files_to_modify or [],
+            "files_to_create": files_to_create or [],
+            "implementation_steps": implementation_steps,
+            "risks_and_considerations": risks_and_considerations or [],
+            "testing_approach": testing_approach or "Manual testing of functionality",
+            "success_criteria": success_criteria or []
+        }
+        
+        # Present plan to user
+        await self._present_plan(plan)
+        
+        # Get user approval
+        approved = await self._get_user_approval()
+        
+        # Update state based on user approval
+        if approved:
+            # Store the plan and exit plan mode
+            self.state_manager.set_current_plan(plan)
+            self.state_manager.exit_plan_mode(plan)
+            await ui.success("✅ Plan approved! Exiting Plan Mode.")
+            return "Plan approved and Plan Mode exited. You can now execute the implementation using write tools (write_file, update_file, bash, run_command)."
+        else:
+            # Keep the plan but stay in plan mode
+            self.state_manager.set_current_plan(plan)
+            await ui.warning("❌ Plan rejected. Staying in Plan Mode for further research.")
+            return "Plan rejected. Continue researching and refine your approach. You remain in Plan Mode - only read-only tools are available."
+    
+    async def _present_plan(self, plan: Dict[str, Any]) -> None:
+        """Present the plan in a formatted way."""
+        # Build the entire plan output as a single string to avoid UI flooding
+        output = []
+        output.append("")
+        output.append("╭─────────────────────────────────────────────────────────╮")
+        output.append("│                  📋 IMPLEMENTATION PLAN                │")
+        output.append("╰─────────────────────────────────────────────────────────╯")
+        output.append("")
+        output.append(f"🎯 {plan['title']}")
+        output.append("")
+        
+        if plan["overview"]:
+            output.append(f"📝 Overview: {plan['overview']}")
+            output.append("")
+        
+        # Files section
+        if plan["files_to_modify"]:
+            output.append("📝 Files to Modify:")
+            for f in plan["files_to_modify"]:
+                output.append(f"  • {f}")
+            output.append("")
+            
+        if plan["files_to_create"]:
+            output.append("📄 Files to Create:")
+            for f in plan["files_to_create"]:
+                output.append(f"  • {f}")
+            output.append("")
+        
+        # Implementation steps
+        output.append("🔧 Implementation Steps:")
+        for i, step in enumerate(plan["implementation_steps"], 1):
+            output.append(f"  {i}. {step}")
+        output.append("")
+        
+        # Testing approach
+        if plan["testing_approach"]:
+            output.append(f"🧪 Testing Approach: {plan['testing_approach']}")
+            output.append("")
+        
+        # Success criteria
+        if plan["success_criteria"]:
+            output.append("✅ Success Criteria:")
+            for criteria in plan["success_criteria"]:
+                output.append(f"  • {criteria}")
+            output.append("")
+        
+        # Risks and considerations
+        if plan["risks_and_considerations"]:
+            output.append("⚠️ Risks & Considerations:")
+            for risk in plan["risks_and_considerations"]:
+                output.append(f"  • {risk}")
+            output.append("")
+        
+        # Print everything at once
+        await ui.info("\n".join(output))
+    
+    async def _get_user_approval(self) -> bool:
+        """Get user approval for the plan."""
+        try:
+            from prompt_toolkit import PromptSession
+            from prompt_toolkit.patch_stdout import patch_stdout
+            
+            session = PromptSession()
+            
+            with patch_stdout():
+                response = await session.prompt_async("\n🤔 Approve this implementation plan? (y/n): ")
+            
+            return response.strip().lower() in ['y', 'yes', 'approve']
+        except (KeyboardInterrupt, EOFError):
+            return False
+
+
+def create_exit_plan_mode_tool(state_manager):
+    """
+    Factory function to create exit_plan_mode tool with the correct state manager.
+    
+    Args:
+        state_manager: The StateManager instance to use
+        
+    Returns:
+        Callable: The exit_plan_mode function bound to the provided state manager
+    """
+    async def exit_plan_mode(
+        plan_title: str,
+        overview: str,
+        implementation_steps: List[str],
+        files_to_modify: List[str] = None,
+        files_to_create: List[str] = None,
+        risks_and_considerations: List[str] = None,
+        testing_approach: str = None,
+        success_criteria: List[str] = None,
+    ) -> str:
+        """
+        Present implementation plan and exit plan mode.
+        
+        Args:
+            plan_title: Brief title for the implementation plan
+            overview: High-level overview of the changes needed
+            implementation_steps: Ordered list of implementation steps  
+            files_to_modify: List of files that need to be modified
+            files_to_create: List of new files to be created
+            risks_and_considerations: Potential risks or important considerations
+            testing_approach: Approach for testing the implementation
+            success_criteria: Criteria for considering the implementation successful
+            
+        Returns:
+            str: Result message indicating plan approval status
+        """
+        tool = ExitPlanModeTool(state_manager=state_manager)
+        return await tool._execute(
+            plan_title=plan_title,
+            overview=overview,
+            implementation_steps=implementation_steps,
+            files_to_modify=files_to_modify,
+            files_to_create=files_to_create,
+            risks_and_considerations=risks_and_considerations,
+            testing_approach=testing_approach,
+            success_criteria=success_criteria,
+        )
+    
+    return exit_plan_mode

tunacode/tools/grep.py

@@ -7,6 +7,8 @@ This tool provides sophisticated grep-like functionality with:
 - Smart result ranking and deduplication
 - Context-aware output formatting
 - Timeout handling for overly broad patterns (3 second deadline for first match)
+
+CLAUDE_ANCHOR[grep-module]: Fast parallel file search with 3-second deadline
 """
 
 import asyncio
@@ -29,7 +31,10 @@ from tunacode.tools.grep_components.result_formatter import ResultFormatter
 
 
 class ParallelGrep(BaseTool):
-    """Advanced parallel grep tool with multiple search strategies."""
+    """Advanced parallel grep tool with multiple search strategies.
+
+    CLAUDE_ANCHOR[parallel-grep-class]: Main grep implementation with timeout handling
+    """
 
     def __init__(self, ui_logger=None):
         super().__init__(ui_logger)
@@ -123,7 +128,13 @@ class ParallelGrep(BaseTool):
             # 4️⃣ Execute chosen strategy with pre-filtered candidates
             # Execute search with pre-filtered candidates
             if search_type == "ripgrep":
+                # Try ripgrep first for performance. If ripgrep is unavailable or
+                # returns no results (e.g., binary missing), gracefully fallback to
+                # the Python implementation so the tool still returns matches.
                 results = await self._ripgrep_search_filtered(pattern, candidates, config)
+                if not results:
+                    # Fallback to python search when ripgrep produced no output
+                    results = await self._python_search_filtered(pattern, candidates, config)
             elif search_type == "python":
                 results = await self._python_search_filtered(pattern, candidates, config)
             elif search_type == "hybrid":

tunacode/tools/present_plan.py

@@ -0,0 +1,208 @@
+"""Tool for presenting a structured plan and exiting plan mode."""
+
+from typing import List, Optional
+
+from tunacode.tools.base import BaseTool
+from tunacode.ui import console as ui
+from tunacode.types import ToolResult, PlanDoc, PlanPhase
+
+
+class PresentPlanTool(BaseTool):
+    """Present a structured implementation plan and request user approval."""
+    
+    def __init__(self, state_manager, ui_logger=None):
+        """Initialize the present plan tool.
+        
+        Args:
+            state_manager: StateManager instance for controlling plan mode state
+            ui_logger: UI logger instance for displaying messages
+        """
+        super().__init__(ui_logger)
+        self.state_manager = state_manager
+    
+    @property
+    def tool_name(self) -> str:
+        return "present_plan"
+    
+    async def _execute(
+        self,
+        title: str,
+        overview: str,
+        steps: List[str],
+        files_to_modify: List[str] = None,
+        files_to_create: List[str] = None,
+        risks: List[str] = None,
+        tests: List[str] = None,
+        rollback: Optional[str] = None,
+        open_questions: List[str] = None,
+        success_criteria: List[str] = None,
+        references: List[str] = None,
+    ) -> ToolResult:
+        """Present the implementation plan for user approval."""
+        
+        # Create PlanDoc from parameters
+        plan_doc = PlanDoc(
+            title=title,
+            overview=overview,
+            steps=steps,
+            files_to_modify=files_to_modify or [],
+            files_to_create=files_to_create or [],
+            risks=risks or [],
+            tests=tests or [],
+            rollback=rollback,
+            open_questions=open_questions or [],
+            success_criteria=success_criteria or [],
+            references=references or []
+        )
+        
+        # Validate the plan
+        is_valid, missing_sections = plan_doc.validate()
+        if not is_valid:
+            return f"❌ Plan incomplete. Missing sections: {', '.join(missing_sections)}. Continue researching and refining your plan."
+        
+        # Set plan phase to PLAN_READY and store the plan
+        # The REPL will handle displaying the plan when it detects PLAN_READY phase
+        self.state_manager.session.plan_phase = PlanPhase.PLAN_READY
+        self.state_manager.session.current_plan = plan_doc
+        
+        return "Plan ready for review. The system will now present it to the user for approval."
+    
+    async def _present_plan(self, plan_doc: PlanDoc) -> None:
+        """Present the plan in a formatted way."""
+        output = []
+        output.append("")
+        output.append("╭─────────────────────────────────────────────────────────╮")
+        output.append("│                  📋 IMPLEMENTATION PLAN                │")
+        output.append("╰─────────────────────────────────────────────────────────╯")
+        output.append("")
+        output.append(f"🎯 **{plan_doc.title}**")
+        output.append("")
+        
+        if plan_doc.overview:
+            output.append(f"📝 **Overview:** {plan_doc.overview}")
+            output.append("")
+        
+        # Files section
+        if plan_doc.files_to_modify:
+            output.append("📝 **Files to Modify:**")
+            for f in plan_doc.files_to_modify:
+                output.append(f"  • {f}")
+            output.append("")
+            
+        if plan_doc.files_to_create:
+            output.append("📄 **Files to Create:**")
+            for f in plan_doc.files_to_create:
+                output.append(f"  • {f}")
+            output.append("")
+        
+        # Implementation steps
+        output.append("🔧 **Implementation Steps:**")
+        for i, step in enumerate(plan_doc.steps, 1):
+            output.append(f"  {i}. {step}")
+        output.append("")
+        
+        # Testing approach
+        if plan_doc.tests:
+            output.append("🧪 **Testing Approach:**")
+            for test in plan_doc.tests:
+                output.append(f"  • {test}")
+            output.append("")
+        
+        # Success criteria
+        if plan_doc.success_criteria:
+            output.append("✅ **Success Criteria:**")
+            for criteria in plan_doc.success_criteria:
+                output.append(f"  • {criteria}")
+            output.append("")
+        
+        # Risks and considerations
+        if plan_doc.risks:
+            output.append("⚠️ **Risks & Considerations:**")
+            for risk in plan_doc.risks:
+                output.append(f"  • {risk}")
+            output.append("")
+        
+        # Open questions
+        if plan_doc.open_questions:
+            output.append("❓ **Open Questions:**")
+            for question in plan_doc.open_questions:
+                output.append(f"  • {question}")
+            output.append("")
+        
+        # References
+        if plan_doc.references:
+            output.append("📚 **References:**")
+            for ref in plan_doc.references:
+                output.append(f"  • {ref}")
+            output.append("")
+        
+        # Rollback plan
+        if plan_doc.rollback:
+            output.append(f"🔄 **Rollback Plan:** {plan_doc.rollback}")
+            output.append("")
+        
+        # Print everything at once
+        await ui.info("\n".join(output))
+
+
+def create_present_plan_tool(state_manager):
+    """
+    Factory function to create present_plan tool with the correct state manager.
+    
+    Args:
+        state_manager: The StateManager instance to use
+        
+    Returns:
+        Callable: The present_plan function bound to the provided state manager
+    """
+    async def present_plan(
+        title: str,
+        overview: str,
+        steps: List[str],
+        files_to_modify: List[str] = None,
+        files_to_create: List[str] = None,
+        risks: List[str] = None,
+        tests: List[str] = None,
+        rollback: Optional[str] = None,
+        open_questions: List[str] = None,
+        success_criteria: List[str] = None,
+        references: List[str] = None,
+    ) -> str:
+        """
+        Present a structured implementation plan for user approval.
+        
+        This tool should ONLY be called when you have a complete, well-researched plan.
+        All required sections must be filled out before calling this tool.
+        
+        Args:
+            title: Brief, descriptive title for the implementation plan
+            overview: High-level summary of what needs to be implemented and why
+            steps: Ordered list of specific implementation steps (required)
+            files_to_modify: List of existing files that need to be modified
+            files_to_create: List of new files that need to be created  
+            risks: Potential risks, challenges, or considerations
+            tests: Testing approach and test cases to validate implementation
+            rollback: Plan for reverting changes if needed
+            open_questions: Any remaining questions or uncertainties
+            success_criteria: Specific criteria for considering the task complete
+            references: External resources, documentation, or research sources
+            
+        Returns:
+            str: Status message about plan presentation
+        """
+        tool = PresentPlanTool(state_manager=state_manager)
+        return await tool._execute(
+            title=title,
+            overview=overview,
+            steps=steps,
+            files_to_modify=files_to_modify,
+            files_to_create=files_to_create,
+            risks=risks,
+            tests=tests,
+            rollback=rollback,
+            open_questions=open_questions,
+            success_criteria=success_criteria,
+            references=references,
+        )
+    
+    return present_plan

tunacode/types.py

@@ -21,6 +21,9 @@ from typing import (
     Union,
 )
 
+# Plan types will be defined below
+from enum import Enum
+
 # Try to import pydantic-ai types if available
 try:
     from pydantic_ai import Agent
@@ -192,6 +195,60 @@ class SimpleResult:
     output: str
 
 
+# =============================================================================
+# Plan Types
+# =============================================================================
+
+
+class PlanPhase(Enum):
+    """Plan Mode phases."""
+    PLANNING_RESEARCH = "research"
+    PLANNING_DRAFT = "draft"
+    PLAN_READY = "ready"
+    REVIEW_DECISION = "review"
+
+
+@dataclass
+class PlanDoc:
+    """Structured plan document with all required sections."""
+    
+    # Required sections
+    title: str
+    overview: str
+    steps: List[str]
+    files_to_modify: List[str]
+    files_to_create: List[str]
+    
+    # Optional but recommended sections
+    risks: List[str] = field(default_factory=list)
+    tests: List[str] = field(default_factory=list)
+    rollback: Optional[str] = None
+    open_questions: List[str] = field(default_factory=list)
+    success_criteria: List[str] = field(default_factory=list)
+    references: List[str] = field(default_factory=list)
+    
+    def validate(self) -> Tuple[bool, List[str]]:
+        """
+        Validate the plan document.
+        
+        Returns:
+            tuple: (is_valid, list_of_missing_sections)
+        """
+        missing = []
+        
+        # Check required fields
+        if not self.title or not self.title.strip():
+            missing.append("title")
+        if not self.overview or not self.overview.strip():
+            missing.append("overview")
+        if not self.steps:
+            missing.append("steps")
+        if not self.files_to_modify and not self.files_to_create:
+            missing.append("files_to_modify or files_to_create")
+            
+        return len(missing) == 0, missing
+
+
 # =============================================================================
 # Session and State Types
 # =============================================================================

tunacode/ui/console.py

@@ -21,6 +21,7 @@ from .output import (
     spinner,
     sync_print,
     update_available,
+    update_spinner_message,
     usage,
     version,
 )
@@ -93,6 +94,7 @@ __all__ = [
     "spinner",
     "sync_print",
     "update_available",
+    "update_spinner_message",
     "usage",
     "version",
     # Unified logging wrappers