from typing import Literal

from langchain.tools import tool


# ClarificationMiddleware owns the stop behaviour: it returns a Command that
# writes the ToolMessage and explicitly routes to END.  ``return_direct=True``
# makes the prebuilt tool node short-circuit before that Command update is
# checkpointed in some LangGraph versions, leaving an assistant tool call
# without its matching ToolMessage.  The next user reply then fails provider
# validation with "tool_calls must be followed by tool messages".
@tool("ask_clarification", parse_docstring=True, return_direct=False)
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,
    allow_multiple: bool | 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

    Batching multiple independent questions:
    - **You CAN and SHOULD call ask_clarification multiple times in the same turn** when the user's
      request leaves several **independent** aspects unclear (e.g. project type AND tech stack AND
      deployment target). Emit one tool call per aspect — do NOT cram several unrelated questions
      into one `question` string.
    - The frontend automatically groups all clarification cards in one turn into a single submission,
      so the user answers them together in one reply. You will then receive one combined user message
      addressing every question in order.
    - When the questions DEPEND on each other (the second only makes sense after the first is answered),
      ask only the first one and wait for the reply before asking the next.

    Best practices:
    - One question per ask_clarification call — keep each `question` focused on a single decision.
    - Be specific and clear in your question.
    - Provide `options` (with concise labels) whenever there is a discrete set of reasonable choices.
    - By default the UI is **single-select** (click an option to send). Pass `allow_multiple=True`
      only when the user may legitimately pick several options together (e.g. multiple constraints).
    - Don't make assumptions when clarification is needed.
    - For risky operations, ALWAYS ask for confirmation.
    - After calling this tool (or several in one turn), execution will be interrupted automatically.

    Args:
        question: The clarification question to ask the user. Focused on a single decision; 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. Present clear options for the user to choose from.
        allow_multiple: When True, the UI allows multi-select plus a submit button. When False or
            omitted, the UI is single-select and sends immediately on click (default).
    """
    # 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"