from __future__ import annotations

"""Custom exceptions for the OpenContracts llms package."""

from typing import Any


class ToolConfirmationRequired(Exception):
    """Internal signal that a tool invocation requires human approval.

    This exception is raised *inside* the tool wrapper when the wrapped
    :class:`~opencontractserver.llms.tools.tool_factory.CoreTool` has the
    flag ``requires_approval`` set to ``True``.  The surrounding
    framework‐specific adapter (e.g. :pymod:`pydantic_ai_agents`) is
    expected to intercept this error and convert it into a paused
    conversation state (``MessageState.AWAITING_APPROVAL``).

    Attributes
    ----------
    tool_name:
        The canonical name of the tool the model attempted to call.
    tool_args:
        The arguments that would have been supplied to the tool.
    tool_call_id:
        The unique identifier generated by the LLM for this tool call.  It
        is optional because some runtimes may not provide it.
    """

    def __init__(
        self,
        tool_name: str,
        tool_args: dict[str, Any] | None = None,
        tool_call_id: str | None = None,
    ):
        self.tool_name = tool_name
        self.tool_args: dict[str, Any] = tool_args or {}
        self.tool_call_id = tool_call_id
        super().__init__(f"Tool '{tool_name}' requires confirmation before execution.")
