feat: add clarification feature (#13)

backend/src/tools/builtins/__init__.py

@@ -1,3 +1,4 @@
+from .clarification_tool import ask_clarification_tool
 from .present_file_tool import present_file_tool
 
-__all__ = ["present_file_tool"]
+__all__ = ["present_file_tool", "ask_clarification_tool"]

backend/src/tools/builtins/clarification_tool.py

@@ -0,0 +1,55 @@
+from typing import Literal
+
+from langchain.tools import tool
+
+
+@tool("ask_clarification", parse_docstring=True, return_direct=True)
+def ask_clarification_tool(
+    question: str,
+    clarification_type: Literal[
+        "missing_info",
+        "ambiguous_requirement",
+        "approach_choice",
+        "risk_confirmation",
+        "suggestion",
+    ],
+    context: str | None = None,
+    options: list[str] | None = None,
+) -> str:
+    """Ask the user for clarification when you need more information to proceed.
+
+    Use this tool when you encounter situations where you cannot proceed without user input:
+
+    - **Missing information**: Required details not provided (e.g., file paths, URLs, specific requirements)
+    - **Ambiguous requirements**: Multiple valid interpretations exist
+    - **Approach choices**: Several valid approaches exist and you need user preference
+    - **Risky operations**: Destructive actions that need explicit confirmation (e.g., deleting files, modifying production)
+    - **Suggestions**: You have a recommendation but want user approval before proceeding
+
+    The execution will be interrupted and the question will be presented to the user.
+    Wait for the user's response before continuing.
+
+    When to use ask_clarification:
+    - You need information that wasn't provided in the user's request
+    - The requirement can be interpreted in multiple ways
+    - Multiple valid implementation approaches exist
+    - You're about to perform a potentially dangerous operation
+    - You have a recommendation but need user approval
+
+    Best practices:
+    - Ask ONE clarification at a time for clarity
+    - Be specific and clear in your question
+    - Don't make assumptions when clarification is needed
+    - For risky operations, ALWAYS ask for confirmation
+    - After calling this tool, execution will be interrupted automatically
+
+    Args:
+        question: The clarification question to ask the user. Be specific and clear.
+        clarification_type: The type of clarification needed (missing_info, ambiguous_requirement, approach_choice, risk_confirmation, suggestion).
+        context: Optional context explaining why clarification is needed. Helps the user understand the situation.
+        options: Optional list of choices (for approach_choice or suggestion types). Present clear options for the user to choose from.
+    """
+    # This is a placeholder implementation
+    # The actual logic is handled by ClarificationMiddleware which intercepts this tool call
+    # and interrupts execution to present the question to the user
+    return "Clarification request processed by middleware"

backend/src/tools/tools.py

@@ -2,10 +2,11 @@ from langchain.tools import BaseTool
 
 from src.config import get_app_config
 from src.reflection import resolve_variable
-from src.tools.builtins import present_file_tool
+from src.tools.builtins import ask_clarification_tool, present_file_tool
 
 BUILTIN_TOOLS = [
     present_file_tool,
+    ask_clarification_tool,
 ]