Tool System

graph TB
    Agent[Agent Engine] --> Registry[Tool Registry]
    Registry --> Builtin[Built-in Tools]
    Registry --> MCP[MCP Tools]
    Registry --> SubAgent[Sub-Agent Tools]
    Registry --> Custom[Custom Discovery]
    
    subgraph "Tool Interface"
        Base[Tools ABC]
        Base --> Name[name: str]
        Base --> Desc[description: str]
        Base --> Kind[kind: ToolKind]
        Base --> Schema[schema: Pydantic Model]
        Base --> Execute[execute(invocation) -> ToolResult]
    end
    
    ToolKind[ToolKind Enum] --> READ[READ]
    ToolKind --> WRITE[WRITE]
    ToolKind --> SHELL[SHELL]
    ToolKind --> NETWORK[NETWORK]
    ToolKind --> MEMORY[MEMORY]
    ToolKind --> MCP[MCP]
    
    style Agent fill:#a191f8,stroke:#8bcefc,color:#fff
    style Registry fill:#8bcefc,stroke:#7fe4eb,color:#fff
    style Base fill:#e7aafb,stroke:#a191f8,color:#fff

class Tools(abc.ABC):
    name: str = "base_tool"
    description: str = "Base tool"
    kind: ToolKind = ToolKind.READ

    @property
    def schema(self) -> dict | type[BaseModel]:
        # Pydantic model or dict defining parameters
        ...

    @abc.abstractmethod
    async def execute(self, invocation: ToolInvocation) -> ToolResult:
        # Execute the tool with validated parameters
        ...

sequenceDiagram
    participant Agent as Agent
    participant Registry as Tool Registry
    participant Safety as Approval Manager
    participant Hook as Hook System
    participant Tool as Tool

    Agent->>Registry: invoke(name, params, cwd)
    activate Registry
    
    Registry->>Registry: Look up tool by name
    alt Tool not found
        Registry-->>Agent: ToolResult.error("Unknown tool")
    end
    
    Registry->>Registry: validate_params(params)
    alt Invalid params
        Registry-->>Agent: ToolResult.error("Invalid parameters")
    end
    
    Registry->>Hook: trigger_before_tool(name, params)
    
    Registry->>Tool: get_confirmation(invocation)
    Tool-->>Registry: ToolConfirmation
    
    Registry->>Safety: check_approval(context)
    alt Rejected
        Registry-->>Agent: ToolResult.error("Rejected by safety policy")
    end
    
    alt Needs Confirmation
        Registry->>Safety: request_confirmation(confirmation)
        Safety-->>Registry: approved?
    end
    
    Registry->>Tool: execute(invocation)
    Tool-->>Registry: ToolResult
    
    Registry->>Hook: trigger_after_tool(name, params, result)
    deactivate Registry
    
    Registry-->>Agent: ToolResult

class ToolDiscoveryManager:
    def discover_from_directory(self, directory: Path) -> None:
        tool_dir = directory / ".flux-cli" / "tools"
        for py_file in tool_dir.glob("*.py"):
            module = self._load_tool_modules(py_file)
            tool_classes = self._find_tool_classes(module)
            for tool_class in tool_classes:
                tool = tool_class(self.config)
                self.registry.register(tool)

@dataclass
class ToolResult:
    success: bool              # Whether execution succeeded
    output: str                # Text output from the tool
    error: str | None          # Error message if failed
    metadata: dict             # Additional structured data
    truncated: bool            # Whether output was truncated
    diff: FileDiff | None       # File diff for write operations
    exit_code: int | None      # Exit code for shell commands