ragbits-agents 1.4.0.dev202512050236__py3-none-any.whl → 1.4.0.dev202601310254__py3-none-any.whl

ragbits/agents/__init__.py

@@ -9,8 +9,12 @@ from ragbits.agents._main import (
     ToolCall,
     ToolCallResult,
 )
+from ragbits.agents.hooks import (
+    EventType,
+    Hook,
+    HookManager,
+)
 from ragbits.agents.post_processors.base import PostProcessor, StreamingPostProcessor
-from ragbits.agents.tool import requires_confirmation
 from ragbits.agents.tools import LongTermMemory, MemoryEntry, create_memory_tools
 from ragbits.agents.types import QuestionAnswerAgent, QuestionAnswerPromptInput, QuestionAnswerPromptOutput
 
@@ -22,6 +26,9 @@ __all__ = [
     "AgentResultStreaming",
     "AgentRunContext",
     "DownstreamAgentResult",
+    "EventType",
+    "Hook",
+    "HookManager",
     "LongTermMemory",
     "MemoryEntry",
     "PostProcessor",
@@ -32,5 +39,4 @@ __all__ = [
     "ToolCall",
     "ToolCallResult",
     "create_memory_tools",
-    "requires_confirmation",
 ]

ragbits/agents/_main.py

@@ -1,6 +1,4 @@
 import asyncio
-import hashlib
-import json
 import types
 import uuid
 from collections.abc import AsyncGenerator, AsyncIterator, Callable
@@ -32,6 +30,10 @@ from ragbits.agents.exceptions import (
     AgentToolNotAvailableError,
     AgentToolNotSupportedError,
 )
+from ragbits.agents.hooks import (
+    Hook,
+    HookManager,
+)
 from ragbits.agents.mcp.server import MCPServer, MCPServerStdio, MCPServerStreamableHttp
 from ragbits.agents.mcp.utils import get_tools
 from ragbits.agents.post_processors.base import (
@@ -40,7 +42,7 @@ from ragbits.agents.post_processors.base import (
     StreamingPostProcessor,
     stream_with_post_processing,
 )
-from ragbits.agents.tool import Tool, ToolCallResult, ToolChoice
+from ragbits.agents.tool import Tool, ToolCallResult, ToolChoice, ToolReturn
 from ragbits.core.audit.traces import trace
 from ragbits.core.llms.base import (
     LLM,
@@ -65,10 +67,6 @@ with suppress(ImportError):
 
     from ragbits.core.llms import LiteLLM
 
-# Confirmation ID length: 16 hex chars provides sufficient uniqueness
-# while being compact for display and storage
-CONFIRMATION_ID_LENGTH = 16
-
 _Input = TypeVar("_Input", bound=BaseModel)
 _Output = TypeVar("_Output")
 
@@ -212,9 +210,10 @@ class AgentRunContext(BaseModel, Generic[DepsT]):
     """Whether to stream events from downstream agents when tools execute other agents."""
     downstream_agents: dict[str, "Agent"] = Field(default_factory=dict)
     """Registry of all agents that participated in this run"""
-    confirmed_tools: list[dict[str, Any]] | None = Field(
-        default=None,
-        description="List of confirmed/declined tools from the frontend",
+    tool_confirmations: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="List of confirmed/declined tool executions. Each entry has 'confirmation_id' and 'confirmed' "
+        "(bool)",
     )
 
     def register_agent(self, agent: "Agent") -> None:
@@ -375,6 +374,7 @@ class Agent(
         keep_history: bool = False,
         tools: list[Callable] | None = None,
         mcp_servers: list[MCPServer] | None = None,
+        hooks: list[Hook] | None = None,
         default_options: AgentOptions[LLMClientOptionsT] | None = None,
     ) -> None:
         """
@@ -394,6 +394,7 @@ class Agent(
             keep_history: Whether to keep the history of the agent.
             tools: The tools available to the agent.
             mcp_servers: The MCP servers available to the agent.
+            hooks: List of tool hooks to register for tool lifecycle events.
             default_options: The default options for the agent run.
         """
         super().__init__(default_options)
@@ -409,11 +410,14 @@ class Agent(
                 self.tools.append(Tool.from_agent(agent, **kwargs))
             elif isinstance(tool, Agent):
                 self.tools.append(Tool.from_agent(tool))
+            elif isinstance(tool, Tool):
+                self.tools.append(tool)
             else:
                 self.tools.append(Tool.from_callable(tool))
         self.mcp_servers = mcp_servers or []
         self.history = history or []
         self.keep_history = keep_history
+        self.hook_manager = HookManager(hooks)
 
         if getattr(self, "system_prompt", None) and not getattr(self, "input_type", None):
             raise ValueError(
@@ -534,7 +538,9 @@ class Agent(
                 ):
                     if isinstance(result, ToolCallResult):
                         tool_calls.append(result)
-                        prompt_with_history = prompt_with_history.add_tool_use_message(**result.__dict__)
+                        prompt_with_history = prompt_with_history.add_tool_use_message(
+                            id=result.id, name=result.name, arguments=result.arguments, result=result.result
+                        )
 
                 turn_count += 1
             else:
@@ -760,7 +766,9 @@ class Agent(
                         elif isinstance(result, ToolCallResult):
                             # Add ALL tool results to history (including pending confirmations)
                             # This allows the agent to see them in the next turn
-                            prompt_with_history = prompt_with_history.add_tool_use_message(**result.__dict__)
+                            prompt_with_history = prompt_with_history.add_tool_use_message(
+                                id=result.id, name=result.name, arguments=result.arguments, result=result.result
+                            )
                             returned_tool_call = True
 
                     # If we have pending confirmations, prepare for text-only summary generation
@@ -956,54 +964,37 @@ class Agent(
 
         tool = tools_mapping[tool_call.name]
 
-        # Check if tool requires confirmation
-        if tool.requires_confirmation:
-            # Check if this tool has been confirmed in the context
-            confirmed_tools = context.confirmed_tools or []
-
-            # Generate a stable confirmation ID based on tool name and arguments
-            confirmation_id = hashlib.sha256(
-                f"{tool_call.name}:{json.dumps(tool_call.arguments, sort_keys=True)}".encode()
-            ).hexdigest()[:CONFIRMATION_ID_LENGTH]
+        # Execute PRE_TOOL hooks with chaining
+        pre_tool_result = await self.hook_manager.execute_pre_tool(
+            tool_call=tool_call,
+            context=context,
+        )
 
-            # Check if this specific tool call has been confirmed or declined
-            is_confirmed = any(
-                ct.get("confirmation_id") == confirmation_id and ct.get("confirmed") for ct in confirmed_tools
+        # Check decision
+        if pre_tool_result.decision == "deny":
+            yield ToolCallResult(
+                id=tool_call.id,
+                name=tool_call.name,
+                arguments=tool_call.arguments,
+                result=pre_tool_result.reason or "Tool execution denied",
             )
-            is_declined = any(
-                ct.get("confirmation_id") == confirmation_id and not ct.get("confirmed", True) for ct in confirmed_tools
+            return
+        # Handle "ask" decision from hooks
+        elif pre_tool_result.decision == "ask" and pre_tool_result.confirmation_request is not None:
+            yield pre_tool_result.confirmation_request
+
+            yield ToolCallResult(
+                id=tool_call.id,
+                name=tool_call.name,
+                arguments=tool_call.arguments,
+                result=pre_tool_result.reason or "Hook requires user confirmation",
             )
+            return
 
-            if is_declined:
-                # Tool was explicitly declined - skip execution entirely
-                yield ToolCallResult(
-                    id=tool_call.id,
-                    name=tool_call.name,
-                    arguments=tool_call.arguments,
-                    result="❌ Action declined by user",
-                )
-                return
-
-            if not is_confirmed:
-                # Tool not confirmed yet - create and yield confirmation request
-                request = ConfirmationRequest(
-                    confirmation_id=confirmation_id,
-                    tool_name=tool_call.name,
-                    tool_description=tool.description or "",
-                    arguments=tool_call.arguments,
-                )
-
-                # Yield confirmation request (will be streamed to frontend)
-                yield request
+        # Always update arguments (chained from hooks)
+        tool_call.arguments = pre_tool_result.arguments
 
-                # Yield a pending result and exit without executing
-                yield ToolCallResult(
-                    id=tool_call.id,
-                    name=tool_call.name,
-                    arguments=tool_call.arguments,
-                    result="⏳ Awaiting user confirmation",
-                )
-                return
+        tool_error: Exception | None = None
 
         with trace(agent_id=self.id, tool_name=tool_call.name, tool_arguments=tool_call.arguments) as outputs:
             try:
@@ -1017,35 +1008,51 @@ class Agent(
                     else asyncio.to_thread(tool.on_tool_call, **call_args)
                 )
 
-                if isinstance(tool_output, AgentResultStreaming):
+                if isinstance(tool_output, ToolReturn):
+                    tool_return = tool_output
+                elif isinstance(tool_output, AgentResultStreaming):
                     async for downstream_item in tool_output:
                         if context.stream_downstream_events:
                             yield DownstreamAgentResult(agent_id=tool.id, item=downstream_item)
-
-                    tool_output = {
-                        "content": tool_output.content,
+                    metadata = {
                         "metadata": tool_output.metadata,
                         "tool_calls": tool_output.tool_calls,
                         "usage": tool_output.usage,
                     }
+                    tool_return = ToolReturn(value=tool_output.content, metadata=metadata)
+                else:
+                    tool_return = ToolReturn(value=tool_output, metadata=None)
 
                 outputs.result = {
-                    "tool_output": tool_output,
+                    "tool_output": tool_return.value,
                     "tool_call_id": tool_call.id,
                 }
 
             except Exception as e:
+                tool_error = e
                 outputs.result = {
                     "error": str(e),
                     "tool_call_id": tool_call.id,
                 }
-                raise AgentToolExecutionError(tool_call.name, e) from e
+
+        # Execute POST_TOOL hooks with chaining
+        post_tool_result = await self.hook_manager.execute_post_tool(
+            tool_call=tool_call,
+            output=tool_output,
+            error=tool_error,
+        )
+        tool_output = post_tool_result.output
+
+        # Raise error after hooks have been executed
+        if tool_error:
+            raise AgentToolExecutionError(tool_call.name, tool_error) from tool_error
 
         yield ToolCallResult(
             id=tool_call.id,
             name=tool_call.name,
             arguments=tool_call.arguments,
-            result=tool_output,
+            result=tool_return.value,
+            metadata=tool_return.metadata,
         )
 
     @requires_dependencies(["a2a.types"], "a2a")

ragbits/agents/hooks/__init__.py

@@ -0,0 +1,77 @@
+"""
+Hooks system for lifecycle events.
+
+This module provides a comprehensive hook system that allows users to register
+custom logic at various points in the execution lifecycle.
+
+Available event types:
+- PRE_TOOL: Before a tool is invoked
+- POST_TOOL: After a tool completes
+
+Example usage:
+
+    from ragbits.agents.hooks import (
+        EventType,
+        Hook,
+        PreToolInput,
+        PreToolOutput,
+    )
+
+    # Create a pre-tool hook callback
+    async def validate_input(input_data: PreToolInput) -> PreToolOutput:
+        if input_data.tool_call.name == "dangerous_tool":
+            return PreToolOutput(
+                arguments=input_data.tool_call.arguments,
+                decision="deny",
+                reason="This tool is not allowed"
+            )
+        return PreToolOutput(arguments=input_data.tool_call.arguments, decision="pass")
+
+    # Create hook instance with proper type annotation
+    hook: Hook[PreToolInput, PreToolOutput] = Hook(
+        event_type=EventType.PRE_TOOL,
+        callback=validate_input,
+        tool_names=["dangerous_tool"],
+        priority=10
+    )
+
+    # Register hooks with agent
+    agent = Agent(
+        ...,
+        hooks=[hook]
+    )
+"""
+
+from ragbits.agents.hooks.base import Hook, HookInputT, HookOutputT
+from ragbits.agents.hooks.confirmation import create_confirmation_hook
+from ragbits.agents.hooks.manager import HookManager
+from ragbits.agents.hooks.types import (
+    EventType,
+    PostToolHookCallback,
+    PostToolInput,
+    PostToolOutput,
+    PreToolHookCallback,
+    PreToolInput,
+    PreToolOutput,
+)
+
+__all__ = [
+    # Event types
+    "EventType",
+    # Core classes
+    "Hook",
+    # Type variables
+    "HookInputT",
+    "HookManager",
+    "HookOutputT",
+    "PostToolHookCallback",
+    # Input/output types
+    "PostToolInput",
+    "PostToolOutput",
+    # Callback type aliases
+    "PreToolHookCallback",
+    "PreToolInput",
+    "PreToolOutput",
+    # Hook factories
+    "create_confirmation_hook",
+]

ragbits/agents/hooks/base.py

@@ -0,0 +1,94 @@
+"""
+Base classes for the hooks system.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Generic, TypeVar
+
+from ragbits.agents.hooks.types import EventType, HookEventIO
+
+HookInputT = TypeVar("HookInputT", bound=HookEventIO)
+HookOutputT = TypeVar("HookOutputT", bound=HookEventIO)
+
+
+class Hook(Generic[HookInputT, HookOutputT]):
+    """
+    A hook that intercepts execution at various lifecycle points.
+
+    Hooks allow you to:
+    - Validate inputs before execution (pre hooks)
+    - Control access (pre hooks)
+    - Modify inputs (pre hooks)
+    - Deny execution (pre hooks)
+    - Modify outputs (post hooks)
+    - Handle errors (post hooks)
+
+    Attributes:
+        event_type: The type of event (e.g., PRE_TOOL, POST_TOOL)
+        callback: The async function to call when the event is triggered
+        tool_names: List of tool names this hook applies to. If None, applies to all tools.
+        priority: Execution priority (lower numbers execute first, default: 100)
+
+    Example:
+        ```python
+        from ragbits.agents.hooks import Hook, EventType, PreToolInput, PreToolOutput
+
+
+        async def validate_input(input_data: PreToolInput) -> PreToolOutput:
+            if input_data.tool_call.name == "dangerous_tool":
+                return PreToolOutput(arguments=input_data.tool_call.arguments, decision="deny", reason="Not allowed")
+            return PreToolOutput(arguments=input_data.tool_call.arguments, decision="pass")
+
+
+        hook: Hook[PreToolInput, PreToolOutput] = Hook(
+            event_type=EventType.PRE_TOOL, callback=validate_input, tool_names=["dangerous_tool"], priority=10
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        event_type: EventType,
+        callback: Callable[[HookInputT], Awaitable[HookOutputT]],
+        tool_names: list[str] | None = None,
+        priority: int = 100,
+    ) -> None:
+        """
+        Initialize a hook.
+
+        Args:
+            event_type: The type of event (e.g., PRE_TOOL, POST_TOOL)
+            callback: The async function to call when the event is triggered
+            tool_names: List of tool names this hook applies to. If None, applies to all tools.
+            priority: Execution priority (lower numbers execute first, default: 100)
+        """
+        self.event_type = event_type
+        self.callback = callback
+        self.tool_names = tool_names
+        self.priority = priority
+
+    def matches_tool(self, tool_name: str) -> bool:
+        """
+        Check if this hook applies to the given tool name.
+
+        Args:
+            tool_name: The name of the tool to check
+
+        Returns:
+            True if this hook should be executed for the given tool
+        """
+        if self.tool_names is None:
+            return True
+        return tool_name in self.tool_names
+
+    async def execute(self, hook_input: HookInputT) -> HookOutputT:
+        """
+        Execute the hook callback with the given input.
+
+        Args:
+            hook_input: The input to pass to the callback
+
+        Returns:
+            The output from the callback
+        """
+        return await self.callback(hook_input)

ragbits/agents/hooks/confirmation.py

@@ -0,0 +1,51 @@
+"""
+Helper functions for creating common hooks.
+
+This module provides factory functions for creating commonly used hooks.
+"""
+
+from ragbits.agents.hooks.base import Hook
+from ragbits.agents.hooks.types import EventType, PreToolInput, PreToolOutput
+
+
+def create_confirmation_hook(
+    tool_names: list[str] | None = None, priority: int = 1
+) -> Hook[PreToolInput, PreToolOutput]:
+    """
+    Create a hook that requires user confirmation before tool execution.
+
+    The hook returns "ask" decision, which causes the agent to yield a ConfirmationRequest
+    and wait for user approval/decline.
+
+    Args:
+        tool_names: List of tool names to require confirmation for. If None, applies to all tools.
+        priority: Hook priority (default: 1, runs first)
+
+    Returns:
+        Hook configured to require confirmation
+
+    Example:
+        ```python
+        from ragbits.agents import Agent
+        from ragbits.agents.hooks.confirmation import create_confirmation_hook
+
+        agent = Agent(
+            tools=[delete_file, send_email], hooks=[create_confirmation_hook(tool_names=["delete_file", "send_email"])]
+        )
+        ```
+    """
+
+    async def confirm_hook(input_data: PreToolInput) -> PreToolOutput:
+        """Hook that always returns 'ask' to require confirmation."""
+        return PreToolOutput(
+            arguments=input_data.tool_call.arguments,
+            decision="ask",
+            reason=f"Tool '{input_data.tool_call.name}' requires user confirmation",
+        )
+
+    return Hook(
+        event_type=EventType.PRE_TOOL,
+        callback=confirm_hook,
+        tool_names=tool_names,
+        priority=priority,
+    )

ragbits/agents/hooks/manager.py

@@ -0,0 +1,194 @@
+"""
+Hook manager for organizing and executing hooks.
+
+This module provides the HookManager class which handles registration,
+organization, and execution of hooks during lifecycle events.
+"""
+
+import hashlib
+import json
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any
+
+from ragbits.agents.confirmation import ConfirmationRequest
+from ragbits.agents.hooks.base import Hook
+from ragbits.agents.hooks.types import EventType, PostToolInput, PostToolOutput, PreToolInput, PreToolOutput
+from ragbits.core.llms.base import ToolCall
+
+if TYPE_CHECKING:
+    from ragbits.agents._main import AgentRunContext
+
+# Confirmation ID length: 16 hex chars provides sufficient uniqueness
+# while being compact for display and storage
+CONFIRMATION_ID_LENGTH = 16
+
+
+class HookManager:
+    """
+    Manages registration and execution of hooks for an agent.
+
+    The HookManager organizes hooks by type and executes them in priority order,
+    with proper chaining of modifications between hooks.
+    """
+
+    def __init__(self, hooks: list[Hook] | None = None) -> None:
+        """
+        Initialize the hook manager.
+
+        Args:
+            hooks: Initial list of hooks to register
+        """
+        self._hooks: dict[EventType, list[Hook]] = defaultdict(list)
+
+        if hooks:
+            for hook in hooks:
+                self.register(hook)
+
+    def register(self, hook: Hook) -> None:
+        """
+        Register a hook.
+
+        Hooks are organized by type and sorted by priority
+        (lower numbers execute first).
+
+        Args:
+            hook: The hook to register
+        """
+        self._hooks[hook.event_type].append(hook)
+        self._hooks[hook.event_type].sort(key=lambda h: h.priority)
+
+    def get_hooks(self, event_type: EventType, tool_name: str | None) -> list[Hook]:
+        """
+        Get all hooks for a specific event type that match the tool name.
+
+        Args:
+            event_type: The type of event
+            tool_name: Optional tool name to filter hooks. If None, returns all hooks for the event type.
+
+        Returns:
+            List of matching hooks, sorted by priority
+        """
+        hooks = self._hooks.get(event_type, [])
+
+        if tool_name is None:
+            return hooks
+
+        return [hook for hook in hooks if hook.matches_tool(tool_name)]
+
+    async def execute_pre_tool(
+        self,
+        tool_call: ToolCall,
+        context: "AgentRunContext",
+    ) -> PreToolOutput:
+        """
+        Execute pre-tool hooks with proper chaining.
+
+        Each hook sees the modified arguments from the previous hook.
+        Execution stops immediately if any hook returns "deny" or "ask" (unless confirmed).
+
+        Args:
+            tool_call: The tool call to process
+            context: Agent run context containing tool_confirmations
+
+        Returns:
+            PreToolOutput with final arguments and decision
+        """
+        hooks = self.get_hooks(EventType.PRE_TOOL, tool_call.name)
+
+        # Start with original arguments
+        current_arguments = tool_call.arguments
+
+        for hook in hooks:
+            # Generate confirmation_id: hash(hook_function_name + tool_name + arguments)
+            hook_name = hook.callback.__name__
+            confirmation_id_str = f"{hook_name}:{tool_call.name}:{json.dumps(current_arguments, sort_keys=True)}"
+            confirmation_id = hashlib.sha256(confirmation_id_str.encode()).hexdigest()[:CONFIRMATION_ID_LENGTH]
+
+            # Create input with current state (chained from previous hook)
+            hook_input = PreToolInput(
+                tool_call=tool_call.model_copy(update={"arguments": current_arguments}),
+            )
+
+            result: PreToolOutput = await hook.execute(hook_input)
+
+            if result.decision == "deny":
+                return PreToolOutput(
+                    arguments=current_arguments,
+                    decision="deny",
+                    reason=result.reason,
+                )
+
+            elif result.decision == "ask":
+                # Check if already confirmed/declined in context
+                for conf in context.tool_confirmations:
+                    if conf.get("confirmation_id") == confirmation_id:
+                        if conf.get("confirmed"):
+                            # Approved → convert to "pass" and continue to next hook
+                            result = PreToolOutput(arguments=current_arguments, decision="pass")
+                            break
+                        else:
+                            # Declined → convert to "deny" and stop immediately
+                            return PreToolOutput(
+                                arguments=current_arguments,
+                                decision="deny",
+                                reason=result.reason or "Tool execution declined by user",
+                            )
+                else:
+                    # Not in context → return "ask" with full ConfirmationRequest
+                    return PreToolOutput(
+                        arguments=current_arguments,
+                        decision="ask",
+                        reason=result.reason,
+                        confirmation_request=ConfirmationRequest(
+                            confirmation_id=confirmation_id,
+                            tool_name=tool_call.name,
+                            tool_description=result.reason or "Hook requires user confirmation",
+                            arguments=current_arguments,
+                        ),
+                    )
+
+            # Chain arguments for next hook
+            current_arguments = result.arguments
+
+        # All hooks passed
+        return PreToolOutput(arguments=current_arguments, decision="pass")
+
+    async def execute_post_tool(
+        self,
+        tool_call: ToolCall,
+        output: Any,  # noqa: ANN401
+        error: Exception | None,
+    ) -> PostToolOutput:
+        """
+        Execute post-tool hooks with proper output chaining.
+
+        Each hook sees the modified output from the previous hook.
+
+        Args:
+            tool_call: The tool call that was executed
+            output: The tool output
+            error: Any error that occurred
+
+        Returns:
+            PostToolOutput with final output
+        """
+        hooks = self.get_hooks(EventType.POST_TOOL, tool_call.name)
+
+        # Start with original output
+        current_output = output
+
+        for hook in hooks:
+            # Create input with current state (chained from previous hook)
+            hook_input = PostToolInput(
+                tool_call=tool_call,
+                output=current_output,
+                error=error,
+            )
+
+            result: PostToolOutput = await hook.execute(hook_input)
+
+            # Chain output for next hook
+            current_output = result.output
+
+        # Return final chained result
+        return PostToolOutput(output=current_output)

ragbits/agents/hooks/types.py

@@ -0,0 +1,141 @@
+"""
+Type definitions for the hooks system.
+
+This module contains all type definitions including EventType, callback types,
+input types, and output types for the hooks system.
+"""
+
+from collections.abc import Awaitable, Callable
+from enum import Enum
+from typing import Any, Literal, TypeAlias
+
+from pydantic import BaseModel, Field, model_validator
+
+from ragbits.agents.confirmation import ConfirmationRequest
+from ragbits.core.llms.base import ToolCall
+
+
+class EventType(str, Enum):
+    """
+    Types of events that can be hooked.
+
+    Attributes:
+        PRE_TOOL: Triggered before a tool is invoked
+        POST_TOOL: Triggered after a tool completes
+    """
+
+    PRE_TOOL = "pre_tool"
+    POST_TOOL = "post_tool"
+
+
+class HookEventIO(BaseModel):
+    """
+    Base class for hook inputs and outputs.
+
+    Contains the common event_type attribute shared by all hook events.
+
+    Attributes:
+        event_type: The type of event
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    event_type: EventType
+
+
+class PreToolInput(HookEventIO):
+    """
+    Input passed to pre-tool hook callbacks.
+
+    This is provided before a tool is invoked, allowing hooks to:
+    - Inspect the tool call
+    - Modify tool arguments
+    - Deny execution
+
+    Attributes:
+        event_type: Always EventType.PRE_TOOL (unchangeable)
+        tool_call: The complete tool call (contains name, arguments, id, type)
+    """
+
+    event_type: Literal[EventType.PRE_TOOL] = Field(default=EventType.PRE_TOOL, frozen=True)
+    tool_call: ToolCall
+
+
+class PostToolInput(HookEventIO):
+    """
+    Input passed to post-tool hook callbacks.
+
+    This is provided after a tool completes, allowing hooks to:
+    - Inspect the tool result
+    - Modify tool output
+    - Handle errors
+
+    Attributes:
+        event_type: Always EventType.POST_TOOL (unchangeable)
+        tool_call: The original tool call
+        output: The result returned by the tool (None if error occurred)
+        error: Any error that occurred during execution (None if successful)
+    """
+
+    event_type: Literal[EventType.POST_TOOL] = Field(default=EventType.POST_TOOL, frozen=True)
+    tool_call: ToolCall
+    output: Any = None
+    error: Exception | None = None
+
+
+class PreToolOutput(HookEventIO):
+    """
+    Output returned by pre-tool hook callbacks.
+
+    This allows hooks to control tool execution. The output always contains
+    arguments (either original or modified).
+
+    Attributes:
+        event_type: Always EventType.PRE_TOOL (unchangeable)
+        arguments: Tool arguments to use (original or modified) - always present
+        decision: The decision on tool execution ("pass", "ask", "deny")
+        reason: Explanation for ask/deny decisions (required for "ask" and "deny", can be None for "pass")
+        confirmation_request: Full confirmation request when decision is "ask" (set by HookManager)
+    """
+
+    event_type: Literal[EventType.PRE_TOOL] = Field(default=EventType.PRE_TOOL, frozen=True)  # type: ignore[assignment]
+    arguments: dict[str, Any]
+    decision: Literal["pass", "ask", "deny"] = "pass"
+    reason: str | None = None
+    confirmation_request: ConfirmationRequest | None = None
+
+    @model_validator(mode="after")
+    def validate_reason(self) -> "PreToolOutput":
+        """Validate that reason is provided for ask and deny decisions."""
+        if self.decision in ("ask", "deny") and not self.reason:
+            raise ValueError(f"reason is required when decision='{self.decision}'")
+        return self
+
+
+class PostToolOutput(HookEventIO):
+    """
+    Output returned by post-tool hook callbacks.
+
+    The output always contains the tool output (either original or modified).
+
+    Attributes:
+        event_type: Always EventType.POST_TOOL (unchangeable)
+        output: Tool output to use (original or modified) - always present
+
+    Example:
+        ```python
+        # Pass through unchanged
+        return PostToolOutput(output=input.output)
+
+        # Modify output
+        return PostToolOutput(output={"filtered": data})
+        ```
+    """
+
+    event_type: Literal[EventType.POST_TOOL] = Field(default=EventType.POST_TOOL, frozen=True)  # type: ignore[assignment]
+    output: Any
+
+
+# Type aliases for hook callbacks
+PreToolHookCallback: TypeAlias = Callable[["PreToolInput"], Awaitable["PreToolOutput"]]
+PostToolHookCallback: TypeAlias = Callable[["PostToolInput"], Awaitable["PostToolOutput"]]

ragbits/agents/tool.py

@@ -1,11 +1,10 @@
 from collections.abc import Callable
 from contextlib import suppress
 from dataclasses import dataclass
-from functools import wraps
-from typing import TYPE_CHECKING, Any, Literal, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Literal, cast
 
 from pydantic import BaseModel
-from typing_extensions import ParamSpec, Self
+from typing_extensions import Self
 
 from ragbits.core.llms.base import LLMClientOptionsT
 from ragbits.core.prompt.prompt import PromptInputT, PromptOutputT
@@ -18,45 +17,18 @@ if TYPE_CHECKING:
 with suppress(ImportError):
     from pydantic_ai import Tool as PydanticAITool
 
-P = ParamSpec("P")
-T = TypeVar("T")
 
-
-def requires_confirmation(func: Callable[P, T]) -> Callable[P, T]:
+@dataclass
+class ToolReturn:
     """
-    Decorator to mark a tool function as requiring user confirmation before execution.
-
-    When a function decorated with @requires_confirmation is used as a tool in an Agent,
-    the agent will request user confirmation before executing the tool.
-
-    Example:
-        ```python
-        @requires_confirmation
-        def delete_file(filepath: str) -> str:
-            '''Delete a file from the system.'''
-            # Implementation
-            return "File deleted"
-
-
-        agent = Agent(llm=llm, tools=[delete_file])
-        # The agent will automatically mark delete_file as requiring confirmation
-        ```
-
-    Args:
-        func: The function to mark as requiring confirmation
-
-    Returns:
-        The same function with a _requires_confirmation attribute set to True
+    Represents an object returned from the tool. If a tool wants to return a value with some content hidden
+    from LLM, it needs to return an object of this class directly.
     """
 
-    @wraps(func)
-    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-        return func(*args, **kwargs)
-
-    # Mark the function as requiring confirmation
-    wrapper._requires_confirmation = True  # type: ignore[attr-defined]
-
-    return wrapper
+    value: Any
+    "Value passed directly to LLM as a result of the tool"
+    metadata: Any = None
+    "Metadata not passed to the LLM, but which can be used in the application later on"
 
 
 @dataclass
@@ -72,7 +44,9 @@ class ToolCallResult:
     arguments: dict[str, Any]
     """Dictionary containing the arguments passed to the tool"""
     result: Any
-    """The output from the tool call."""
+    """The output from the tool call passed to the LLM"""
+    metadata: Any = None
+    """Metadata returned from a tool that is not meant to be seen by the LLM"""
 
 
 @dataclass
@@ -92,35 +66,26 @@ class Tool:
     context_var_name: str | None = None
     """The name of the context variable that this tool accepts."""
     id: str | None = None
-    requires_confirmation: bool = False
-    """Whether this tool requires user confirmation before execution."""
 
     @classmethod
-    def from_callable(cls, callable: Callable, requires_confirmation: bool = False) -> Self:
+    def from_callable(cls, callable: Callable) -> Self:
         """
         Create a Tool instance from a callable function.
 
         Args:
             callable: The function to convert into a Tool
-            requires_confirmation: Whether this tool requires user confirmation before execution.
-                If not provided, checks if the callable has been decorated with @requires_confirmation.
 
         Returns:
             A new Tool instance representing the callable function.
         """
         schema = convert_function_to_function_schema(callable)
 
-        # Check if the callable has been decorated with @requires_confirmation
-        # Priority: explicit parameter > decorator attribute
-        needs_confirmation = requires_confirmation or getattr(callable, "_requires_confirmation", False)
-
         return cls(
             name=schema["function"]["name"],
             description=schema["function"]["description"],
             parameters=schema["function"]["parameters"],
             on_tool_call=callable,
             context_var_name=get_context_variable_name(callable),
-            requires_confirmation=needs_confirmation,
         )
 
     def to_function_schema(self) -> dict[str, Any]:

{ragbits_agents-1.4.0.dev202512050236.dist-info → ragbits_agents-1.4.0.dev202601310254.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragbits-agents
-Version: 1.4.0.dev202512050236
+Version: 1.4.0.dev202601310254
 Summary: Building blocks for rapid development of GenAI applications
 Project-URL: Homepage, https://github.com/deepsense-ai/ragbits
 Project-URL: Bug Reports, https://github.com/deepsense-ai/ragbits/issues
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: ragbits-core==1.4.0.dev202512050236
+Requires-Dist: ragbits-core==1.4.0.dev202601310254
 Provides-Extra: a2a
 Requires-Dist: a2a-sdk<1.0.0,>=0.2.9; extra == 'a2a'
 Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == 'a2a'

{ragbits_agents-1.4.0.dev202512050236.dist-info → ragbits_agents-1.4.0.dev202601310254.dist-info}/RECORD

@@ -1,13 +1,18 @@
-ragbits/agents/__init__.py,sha256=SuM-RMiS_EkMsOgVXwhNtfZKSoKiA5B4QmaaOYWw7a4,996
-ragbits/agents/_main.py,sha256=nW2CL0VSaYrLZdMJPJ-s7Hz6IbpK_CXCvyjNHluL1d0,51823
+ragbits/agents/__init__.py,sha256=rKqDbbppy70HmDN6AtC3eXzyVWTTagkRpLvPjWulGuY,1040
+ragbits/agents/_main.py,sha256=bxMBogDl1dWxfGZk3cSztogj8gK8VoYo38jfoMzsBXU,52013
 ragbits/agents/cli.py,sha256=xUS7k8IAn0479n165i4YVFKo4Jx0M2iCpaMILZi9xt8,17649
 ragbits/agents/confirmation.py,sha256=cwdd1feSSobxa7gxBvEZcL9e3tcLdc8CyfvvQwaHF1Y,619
 ragbits/agents/exceptions.py,sha256=TiompKlP1QRD4TZ7hpp52dyZqg0rjoq1t5QUTxFZud8,3552
 ragbits/agents/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ragbits/agents/tool.py,sha256=86a1ilbErXLFLgIQeLu0HBXUy5yUvkL91XXaYqgkZPE,7829
+ragbits/agents/tool.py,sha256=c7TcexLMZSzWGS3nWKp5BX0zAipdkVAuRyvjCL220EE,6501
 ragbits/agents/types.py,sha256=_dzhn4HzrWuSK1dNVZEpznWTrxKMnKuTJfdUCwJWKuc,869
 ragbits/agents/a2a/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ragbits/agents/a2a/server.py,sha256=4a-cq87OeMoVOjEM_PbwTSHhPTpJv8r_xOVaZAzFIiI,3031
+ragbits/agents/hooks/__init__.py,sha256=xvWTFLkbM6aRLEz-Ypw9MMDOKVIJqhZzN5XE0jEvy3o,1984
+ragbits/agents/hooks/base.py,sha256=Rl_SUgnI-e8Rgrg7TAlxDsdC2nqtRAOIGpIsPV3Y_Sk,3137
+ragbits/agents/hooks/confirmation.py,sha256=ykSRR2sF8lbxG4pJN5amtT6qstnDoTbrYWZaafoSa9Y,1648
+ragbits/agents/hooks/manager.py,sha256=ssQjICFmmstQhfVY3Vzhr5mj8K3npGVZ7Q5HL-dj6RE,6910
+ragbits/agents/hooks/types.py,sha256=XIJZIVtjgrBGFh59T8ljkfj3qF9fzY0tqC_Iv59zLak,4407
 ragbits/agents/mcp/__init__.py,sha256=7icbSe4FCBMgPADNNoeQBKiLY8J6gIlqFS77gFGr6Ks,405
 ragbits/agents/mcp/server.py,sha256=slob6ns-sbLmG-bQAbwz-23MWsaAENeKhE2eNdoI3Vs,16397
 ragbits/agents/mcp/utils.py,sha256=o_UXS-olS1uRdfZHTRJdG697Xmq3q77twfcHzmyRTY0,1394
@@ -20,6 +25,6 @@ ragbits/agents/tools/memory.py,sha256=IrRGpZvdylNbn_Z7FFFwun9Rx3OSQimjVynSt3WgUo
 ragbits/agents/tools/openai.py,sha256=SpoB6my_T6LwfHjrP7ivQL6H4KvwInVampXq-6nGAHE,4955
 ragbits/agents/tools/todo.py,sha256=R86_Hu0HIl5Ujp8B2ctOo1iSLAHmfrzyu6jnyCLs4uc,18576
 ragbits/agents/tools/types.py,sha256=6yNG7IjG476muiCIcXKRgDJSemCeO2ZgycpXLyfu8jc,441
-ragbits_agents-1.4.0.dev202512050236.dist-info/METADATA,sha256=SiT1brR1hYVL-AIf9RUVK-vhpuER3ENA0imopbiBxhk,2273
-ragbits_agents-1.4.0.dev202512050236.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-ragbits_agents-1.4.0.dev202512050236.dist-info/RECORD,,
+ragbits_agents-1.4.0.dev202601310254.dist-info/METADATA,sha256=O2-1QB13Z7km26KnXDhIGOpy4vjU5AaRAYyPYwf4Uwg,2273
+ragbits_agents-1.4.0.dev202601310254.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ragbits_agents-1.4.0.dev202601310254.dist-info/RECORD,,