"""Base tool class and permission levels (stub for Day 2)."""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from enum import Enum
from typing import Any


class PermissionLevel(Enum):
    """Tool permission levels."""
    READ = "read"        # Auto-allowed (file reads, searches)
    WRITE = "write"      # Requires confirmation (file writes, edits)
    EXECUTE = "execute"  # Requires confirmation (shell commands)


@dataclass
class ToolSpec:
    """Tool specification for registration."""
    name: str
    description: str
    parameters: dict[str, Any]  # JSON Schema
    permission: PermissionLevel


class BaseTool(ABC):
    """Abstract base for all tools."""

    @abstractmethod
    def spec(self) -> ToolSpec:
        """Return the tool specification."""
        ...

    @abstractmethod
    def execute(self, **kwargs: Any) -> str:
        """Execute the tool and return result as string."""
        ...
