ripperdoc 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

ripperdoc/tools/enter_plan_mode_tool.py

@@ -0,0 +1,223 @@
+"""Enter plan mode tool for complex task planning.
+
+This tool allows the AI to request entering plan mode for complex tasks
+that require careful exploration and design before implementation.
+"""
+
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import AsyncGenerator, Optional
+
+from pydantic import BaseModel
+
+from ripperdoc.core.tool import (
+    Tool,
+    ToolOutput,
+    ToolResult,
+    ToolUseContext,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+TOOL_NAME = "EnterPlanMode"
+ASK_USER_QUESTION_TOOL = "AskUserQuestion"
+
+ENTER_PLAN_MODE_PROMPT = dedent(
+    """\
+    Use this tool when you encounter a complex task that requires careful planning and exploration before implementation. This tool transitions you into plan mode where you can thoroughly explore the codebase and design an implementation approach.
+
+    ## When to Use This Tool
+
+    Use EnterPlanMode when ANY of these conditions apply:
+
+    1. **Multiple Valid Approaches**: The task can be solved in several different ways, each with trade-offs
+       - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
+       - Example: "Improve performance" - many optimization strategies possible
+
+    2. **Significant Architectural Decisions**: The task requires choosing between architectural patterns
+       - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+       - Example: "Implement state management" - Redux vs Context vs custom solution
+
+    3. **Large-Scale Changes**: The task touches many files or systems
+       - Example: "Refactor the authentication system"
+       - Example: "Migrate from REST to GraphQL"
+
+    4. **Unclear Requirements**: You need to explore before understanding the full scope
+       - Example: "Make the app faster" - need to profile and identify bottlenecks
+       - Example: "Fix the bug in checkout" - need to investigate root cause
+
+    5. **User Input Needed**: You'll need to ask clarifying questions before starting
+       - If you would use {ask_tool} to clarify the approach, consider EnterPlanMode instead
+       - Plan mode lets you explore first, then present options with context
+
+    ## When NOT to Use This Tool
+
+    Do NOT use EnterPlanMode for:
+    - Simple, straightforward tasks with obvious implementation
+    - Small bug fixes where the solution is clear
+    - Adding a single function or small feature
+    - Tasks you're already confident how to implement
+    - Research-only tasks (use the Task tool with explore agent instead)
+
+    ## What Happens in Plan Mode
+
+    In plan mode, you'll:
+    1. Thoroughly explore the codebase using Glob, Grep, and Read tools
+    2. Understand existing patterns and architecture
+    3. Design an implementation approach
+    4. Present your plan to the user for approval
+    5. Use {ask_tool} if you need to clarify approaches
+    6. Exit plan mode with ExitPlanMode when ready to implement
+
+    ## Examples
+
+    ### GOOD - Use EnterPlanMode:
+    User: "Add user authentication to the app"
+    - This requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
+
+    User: "Optimize the database queries"
+    - Multiple approaches possible, need to profile first, significant impact
+
+    User: "Implement dark mode"
+    - Architectural decision on theme system, affects many components
+
+    ### BAD - Don't use EnterPlanMode:
+    User: "Fix the typo in the README"
+    - Straightforward, no planning needed
+
+    User: "Add a console.log to debug this function"
+    - Simple, obvious implementation
+
+    User: "What files handle routing?"
+    - Research task, not implementation planning
+
+    ## Important Notes
+
+    - This tool REQUIRES user approval - they must consent to entering plan mode
+    - Be thoughtful about when to use it - unnecessary plan mode slows down simple tasks
+    - If unsure whether to use it, err on the side of starting implementation
+    - You can always ask the user "Would you like me to plan this out first?"
+    """
+).format(ask_tool=ASK_USER_QUESTION_TOOL)
+
+
+PLAN_MODE_INSTRUCTIONS = dedent(
+    """\
+    In plan mode, you should:
+    1. Thoroughly explore the codebase to understand existing patterns
+    2. Identify similar features and architectural approaches
+    3. Consider multiple approaches and their trade-offs
+    4. Use AskUserQuestion if you need to clarify the approach
+    5. Design a concrete implementation strategy
+    6. When ready, use ExitPlanMode to present your plan for approval
+
+    Remember: DO NOT write or edit any files yet. This is a read-only exploration and planning phase."""
+)
+
+
+class EnterPlanModeToolInput(BaseModel):
+    """Input for the EnterPlanMode tool.
+
+    This tool takes no input parameters - it simply requests to enter plan mode.
+    """
+
+    pass
+
+
+class EnterPlanModeToolOutput(BaseModel):
+    """Output from the EnterPlanMode tool."""
+
+    message: str
+    entered: bool = True
+
+
+class EnterPlanModeTool(Tool[EnterPlanModeToolInput, EnterPlanModeToolOutput]):
+    """Tool for entering plan mode for complex tasks."""
+
+    @property
+    def name(self) -> str:
+        return TOOL_NAME
+
+    async def description(self) -> str:
+        return (
+            "Requests permission to enter plan mode for complex tasks "
+            "requiring exploration and design"
+        )
+
+    @property
+    def input_schema(self) -> type[EnterPlanModeToolInput]:
+        return EnterPlanModeToolInput
+
+    async def prompt(self, safe_mode: bool = False) -> str:  # noqa: ARG002
+        return ENTER_PLAN_MODE_PROMPT
+
+    def user_facing_name(self) -> str:
+        return ""
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return True
+
+    def needs_permissions(
+        self, input_data: Optional[EnterPlanModeToolInput] = None  # noqa: ARG002
+    ) -> bool:
+        return True
+
+    async def validate_input(
+        self,
+        input_data: EnterPlanModeToolInput,
+        context: Optional[ToolUseContext] = None,
+    ) -> ValidationResult:
+        """Validate that this tool is not being used in an agent context."""
+        if context and context.agent_id:
+            return ValidationResult(
+                result=False,
+                message="EnterPlanMode tool cannot be used in agent contexts",
+            )
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: EnterPlanModeToolOutput) -> str:
+        """Render the tool output for the AI assistant."""
+        if not output.entered:
+            return "User declined to enter plan mode. Continue with normal implementation."
+        return f"{output.message}\n\n{PLAN_MODE_INSTRUCTIONS}"
+
+    def render_tool_use_message(
+        self, input_data: EnterPlanModeToolInput, verbose: bool = False  # noqa: ARG002
+    ) -> str:
+        """Render the tool use message for display."""
+        return "Requesting to enter plan mode"
+
+    async def call(
+        self,
+        input_data: EnterPlanModeToolInput,  # noqa: ARG002
+        context: ToolUseContext,
+    ) -> AsyncGenerator[ToolOutput, None]:
+        """Execute the tool to enter plan mode."""
+        if context.agent_id:
+            output = EnterPlanModeToolOutput(
+                message="EnterPlanMode tool cannot be used in agent contexts",
+                entered=False,
+            )
+            yield ToolResult(
+                data=output,
+                result_for_assistant=self.render_result_for_assistant(output),
+            )
+            return
+
+        output = EnterPlanModeToolOutput(
+            message=(
+                "Entered plan mode. You should now focus on exploring "
+                "the codebase and designing an implementation approach."
+            ),
+            entered=True,
+        )
+        yield ToolResult(
+            data=output,
+            result_for_assistant=self.render_result_for_assistant(output),
+        )

ripperdoc/tools/exit_plan_mode_tool.py

@@ -0,0 +1,150 @@
+"""Exit plan mode tool for presenting implementation plans.
+
+This tool allows the AI to exit plan mode and present an implementation
+plan to the user for approval before starting to code.
+"""
+
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import AsyncGenerator, Optional
+
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.tool import (
+    Tool,
+    ToolOutput,
+    ToolResult,
+    ToolUseContext,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+TOOL_NAME = "ExitPlanMode"
+
+EXIT_PLAN_MODE_PROMPT = dedent(
+    """\
+    Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+
+    ## How This Tool Works
+    - You should have already written your plan to the plan file specified in the plan mode system message
+    - This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
+    - This tool simply signals that you're done planning and ready for the user to review and approve
+    - The user will see the contents of your plan file when they review it
+
+    ## When to Use This Tool
+    IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+
+    ## Handling Ambiguity in Plans
+    Before using this tool, ensure your plan is clear and unambiguous. If there are multiple valid approaches or unclear requirements:
+    1. Use the AskUserQuestion tool to clarify with the user
+    2. Ask about specific implementation choices (e.g., architectural patterns, which library to use)
+    3. Clarify any assumptions that could affect the implementation
+    4. Edit your plan file to incorporate user feedback
+    5. Only proceed with ExitPlanMode after resolving ambiguities and updating the plan file
+
+    ## Examples
+
+    1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
+    2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
+    3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.
+    """
+)
+
+
+class ExitPlanModeToolInput(BaseModel):
+    """Input for the ExitPlanMode tool."""
+
+    plan: str = Field(
+        description="The plan you came up with, that you want to run by the user for approval. "
+        "Supports markdown. The plan should be pretty concise."
+    )
+
+
+class ExitPlanModeToolOutput(BaseModel):
+    """Output from the ExitPlanMode tool."""
+
+    plan: str
+    is_agent: bool = False
+
+
+class ExitPlanModeTool(Tool[ExitPlanModeToolInput, ExitPlanModeToolOutput]):
+    """Tool for exiting plan mode and presenting a plan for approval."""
+
+    @property
+    def name(self) -> str:
+        return TOOL_NAME
+
+    async def description(self) -> str:
+        return "Prompts the user to exit plan mode and start coding"
+
+    @property
+    def input_schema(self) -> type[ExitPlanModeToolInput]:
+        return ExitPlanModeToolInput
+
+    async def prompt(self, safe_mode: bool = False) -> str:  # noqa: ARG002
+        return EXIT_PLAN_MODE_PROMPT
+
+    def user_facing_name(self) -> str:
+        return "Exit plan mode"
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return True
+
+    def needs_permissions(
+        self, input_data: Optional[ExitPlanModeToolInput] = None  # noqa: ARG002
+    ) -> bool:
+        return True
+
+    async def validate_input(
+        self,
+        input_data: ExitPlanModeToolInput,
+        context: Optional[ToolUseContext] = None,  # noqa: ARG002
+    ) -> ValidationResult:
+        """Validate that plan is not empty."""
+        if not input_data.plan or not input_data.plan.strip():
+            return ValidationResult(
+                result=False,
+                message="Plan cannot be empty",
+            )
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: ExitPlanModeToolOutput) -> str:
+        """Render the tool output for the AI assistant."""
+        return f"Exit plan mode and start coding now. Plan:\n{output.plan}"
+
+    def render_tool_use_message(
+        self, input_data: ExitPlanModeToolInput, verbose: bool = False  # noqa: ARG002
+    ) -> str:
+        """Render the tool use message for display."""
+        plan = input_data.plan
+        snippet = f"{plan[:77]}..." if len(plan) > 80 else plan
+        return f"Share plan for approval: {snippet}"
+
+    async def call(
+        self,
+        input_data: ExitPlanModeToolInput,
+        context: ToolUseContext,
+    ) -> AsyncGenerator[ToolOutput, None]:
+        """Execute the tool to exit plan mode."""
+        # Invoke the exit plan mode callback if available
+        if context.on_exit_plan_mode:
+            try:
+                context.on_exit_plan_mode()
+            except Exception:
+                logger.debug("[exit_plan_mode_tool] Failed to call on_exit_plan_mode")
+
+        is_agent = bool(context.agent_id)
+        output = ExitPlanModeToolOutput(
+            plan=input_data.plan,
+            is_agent=is_agent,
+        )
+        yield ToolResult(
+            data=output,
+            result_for_assistant=self.render_result_for_assistant(output),
+        )

ripperdoc/tools/file_edit_tool.py

@@ -16,6 +16,7 @@ from ripperdoc.core.tool import (
     ValidationResult,
 )
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
 
 logger = get_logger()
 
@@ -185,6 +186,18 @@ match exactly (including whitespace and indentation)."""
             with open(input_data.file_path, "w", encoding="utf-8") as f:
                 f.write(new_content)
 
+            try:
+                record_snapshot(
+                    input_data.file_path,
+                    new_content,
+                    getattr(context, "file_state_cache", {}),
+                )
+            except Exception:
+                logger.exception(
+                    "[file_edit_tool] Failed to record file snapshot",
+                    extra={"file_path": input_data.file_path},
+                )
+
             # Generate diff for display
             import difflib
 

ripperdoc/tools/file_read_tool.py

@@ -16,6 +16,7 @@ from ripperdoc.core.tool import (
     ValidationResult,
 )
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
 
 logger = get_logger()
 
@@ -143,6 +144,21 @@ and limit to read only a portion of the file."""
 
             content = "".join(selected_lines)
 
+            # Remember what we read so we can detect user edits later.
+            try:
+                record_snapshot(
+                    input_data.file_path,
+                    content,
+                    getattr(context, "file_state_cache", {}),
+                    offset=offset,
+                    limit=limit,
+                )
+            except Exception:
+                logger.exception(
+                    "[file_read_tool] Failed to record file snapshot",
+                    extra={"file_path": input_data.file_path},
+                )
+
             output = FileReadToolOutput(
                 content=content,
                 file_path=input_data.file_path,

ripperdoc/tools/file_write_tool.py

@@ -17,6 +17,7 @@ from ripperdoc.core.tool import (
     ValidationResult,
 )
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
 
 logger = get_logger()
 
@@ -125,6 +126,18 @@ NEVER write new files unless explicitly required by the user."""
 
             bytes_written = len(input_data.content.encode("utf-8"))
 
+            try:
+                record_snapshot(
+                    input_data.file_path,
+                    input_data.content,
+                    getattr(context, "file_state_cache", {}),
+                )
+            except Exception:
+                logger.exception(
+                    "[file_write_tool] Failed to record file snapshot",
+                    extra={"file_path": input_data.file_path},
+                )
+
             output = FileWriteToolOutput(
                 file_path=input_data.file_path,
                 bytes_written=bytes_written,

ripperdoc/tools/glob_tool.py

@@ -112,7 +112,11 @@ class GlobTool(Tool[GlobToolInput, GlobToolOutput]):
         rendered_path = ""
         if input_data.path:
             candidate_path = Path(input_data.path)
-            absolute_path = candidate_path if candidate_path.is_absolute() else (base_path / candidate_path).resolve()
+            absolute_path = (
+                candidate_path
+                if candidate_path.is_absolute()
+                else (base_path / candidate_path).resolve()
+            )
 
             try:
                 relative_path = absolute_path.relative_to(base_path)

ripperdoc/tools/ls_tool.py

@@ -142,22 +142,22 @@ def _should_skip(
     path: Path,
     root_path: Path,
     patterns: list[str],
-    ignore_map: Optional[Dict[Optional[Path], List[str]]] = None
+    ignore_map: Optional[Dict[Optional[Path], List[str]]] = None,
 ) -> bool:
     name = path.name
     if name.startswith("."):
         return True
     if "__pycache__" in path.parts:
         return True
-    
+
     # Check against ignore patterns
     if ignore_map and should_ignore_path(path, root_path, ignore_map):
         return True
-    
+
     # Also check against direct patterns for backward compatibility
     if patterns and _matches_ignore(path, root_path, patterns):
         return True
-    
+
     return False
 
 
@@ -346,7 +346,9 @@ class LSTool(Tool[LSToolInput, LSToolOutput]):
         try:
             root_path = _resolve_directory_path(input_data.path)
         except Exception:
-            return ValidationResult(result=False, message=f"Unable to resolve path: {input_data.path}")
+            return ValidationResult(
+                result=False, message=f"Unable to resolve path: {input_data.path}"
+            )
 
         if not root_path.is_absolute():
             return ValidationResult(result=False, message=f"Path is not absolute: {root_path}")
@@ -392,7 +394,9 @@ class LSTool(Tool[LSToolInput, LSToolOutput]):
             return f'path: "{input_data.path}"{ignore_display}'
 
         try:
-            relative_path = _relative_path_for_display(resolved_path, base_path) or resolved_path.as_posix()
+            relative_path = (
+                _relative_path_for_display(resolved_path, base_path) or resolved_path.as_posix()
+            )
         except Exception:
             relative_path = str(resolved_path)
 
@@ -431,18 +435,18 @@ class LSTool(Tool[LSToolInput, LSToolOutput]):
             git_root = get_git_root(root_path)
             if git_root:
                 git_info["repository"] = str(git_root)
-                
+
                 branch = get_current_git_branch(root_path)
                 if branch:
                     git_info["branch"] = branch
-                
+
                 commit_hash = get_git_commit_hash(root_path)
                 if commit_hash:
                     git_info["commit"] = commit_hash
-                
+
                 is_clean = is_working_directory_clean(root_path)
                 git_info["clean"] = "yes" if is_clean else "no (uncommitted changes)"
-                
+
                 tracked, untracked = get_git_status_files(root_path)
                 if tracked or untracked:
                     status_info = []