connectonion 0.4.12__py3-none-any.whl → 0.5.0__py3-none-any.whl

connectonion/__init__.py

@@ -1,6 +1,6 @@
 """ConnectOnion - A simple agent framework with behavior tracking."""
 
-__version__ = "0.4.12"
+__version__ = "0.5.0"
 
 # Auto-load .env files for the entire framework
 from dotenv import load_dotenv
@@ -13,6 +13,7 @@ load_dotenv(_Path.cwd() / ".env")
 from .agent import Agent
 from .tool_factory import create_tool_from_function
 from .llm import LLM
+from .logger import Logger
 from .llm_do import llm_do
 from .prompts import load_system_prompt
 from .xray import xray
@@ -24,8 +25,10 @@ from .events import (
     after_user_input,
     before_llm,
     after_llm,
-    before_tool,
-    after_tool,
+    before_each_tool,
+    before_tools,
+    after_each_tool,
+    after_tools,
     on_error,
     on_complete
 )
@@ -33,6 +36,7 @@ from .events import (
 __all__ = [
     "Agent",
     "LLM",
+    "Logger",
     "create_tool_from_function",
     "llm_do",
     "load_system_prompt",
@@ -62,8 +66,10 @@ __all__ = [
     "after_user_input",
     "before_llm",
     "after_llm",
-    "before_tool",
-    "after_tool",
+    "before_each_tool",
+    "before_tools",
+    "after_each_tool",
+    "after_tools",
     "on_error",
     "on_complete"
 ]

connectonion/agent.py

@@ -1,10 +1,10 @@
 """
 Purpose: Orchestrate AI agent execution with LLM calls, tool execution, and automatic logging
 LLM-Note:
-  Dependencies: imports from [llm.py, tool_factory.py, prompts.py, decorators.py, console.py, tool_executor.py, trust.py, tool_registry.py] | imported by [__init__.py, trust.py, debug_agent/__init__.py] | tested by [tests/test_agent.py, tests/test_agent_prompts.py, tests/test_agent_workflows.py]
-  Data flow: receives user prompt: str from Agent.input() → creates/extends current_session with messages → calls llm.complete() with tool schemas → receives LLMResponse with tool_calls → executes tools via tool_executor.execute_and_record_tools() → appends tool results to messages → repeats loop until no tool_calls or max_iterations → console logs to .co/logs/{name}.log → returns final response: str
-  State/Effects: modifies self.current_session['messages', 'trace', 'turn', 'iteration'] | writes to .co/logs/{name}.log via console.py (default) or custom log path | initializes trust agent if trust parameter provided
-  Integration: exposes Agent(name, tools, system_prompt, model, trust, log), .input(prompt), .execute_tool(name, args), .add_tool(func), .remove_tool(name), .list_tools(), .reset_conversation() | tools stored in ToolRegistry with attribute access (agent.tools.tool_name) and instance storage (agent.tools.gmail) | tool execution delegates to tool_executor module | trust system via trust.create_trust_agent() | log defaults to .co/logs/ (None), can be True (current dir), False (disabled), or custom path
+  Dependencies: imports from [llm.py, tool_factory.py, prompts.py, decorators.py, logger.py, tool_executor.py, trust.py, tool_registry.py] | imported by [__init__.py, trust.py, debug_agent/__init__.py] | tested by [tests/test_agent.py, tests/test_agent_prompts.py, tests/test_agent_workflows.py]
+  Data flow: receives user prompt: str from Agent.input() → creates/extends current_session with messages → calls llm.complete() with tool schemas → receives LLMResponse with tool_calls → executes tools via tool_executor.execute_and_record_tools() → appends tool results to messages → repeats loop until no tool_calls or max_iterations → logger logs to .co/logs/{name}.log and .co/sessions/{name}_{timestamp}.yaml → returns final response: str
+  State/Effects: modifies self.current_session['messages', 'trace', 'turn', 'iteration'] | writes to .co/logs/{name}.log and .co/sessions/ via logger.py | initializes trust agent if trust parameter provided
+  Integration: exposes Agent(name, tools, system_prompt, model, trust, log, quiet), .input(prompt), .execute_tool(name, args), .add_tool(func), .remove_tool(name), .list_tools(), .reset_conversation() | tools stored in ToolRegistry with attribute access (agent.tools.tool_name) and instance storage (agent.tools.gmail) | tool execution delegates to tool_executor module | trust system via trust.create_trust_agent() | log defaults to .co/logs/ (None), can be True (current dir), False (disabled), or custom path | quiet=True suppresses console but keeps session logging
   Performance: max_iterations=10 default (configurable per-input) | session state persists across turns for multi-turn conversations | ToolRegistry provides O(1) tool lookup via .get() or attribute access
   Errors: LLM errors bubble up | tool execution errors captured in trace and returned to LLM for retry | trust agent creation can fail if invalid trust parameter
 """
@@ -22,7 +22,7 @@ from .prompts import load_system_prompt
 from .decorators import (
     _is_replay_enabled  # Only need this for replay check
 )
-from .console import Console
+from .logger import Logger
 from .tool_executor import execute_and_record_tools, execute_single_tool
 from .events import EventHandler
 
@@ -38,10 +38,11 @@ class Agent:
         tools: Optional[Union[List[Callable], Callable, Any]] = None,
         system_prompt: Union[str, Path, None] = None,
         api_key: Optional[str] = None,
-        model: str = "co/o4-mini",
+        model: str = "co/gemini-2.5-pro",
         max_iterations: int = 10,
         trust: Optional[Union[str, Path, 'Agent']] = None,
         log: Optional[Union[bool, str, Path]] = None,
+        quiet: bool = False,
         plugins: Optional[List[List[EventHandler]]] = None,
         on_events: Optional[List[EventHandler]] = None
     ):
@@ -56,27 +57,13 @@ class Agent:
         self.total_cost: float = 0.0  # Cumulative cost in USD
         self.last_usage: Optional[TokenUsage] = None  # From most recent LLM call
 
-        # Setup file logging (default to .co/logs/)
-        log_file = None
-        if log is None:
-            # NEW: Default to .co/logs/ for automatic audit trail
-            log_file = Path.cwd() / '.co' / 'logs' / f'{name}.log'
-        elif log is True:
-            # Explicit True: {name}.log in current directory
-            log_file = Path(f"{name}.log")
-        elif log is False:
-            # Explicit opt-out: no logging
-            log_file = None
-        elif log:
-            # Custom log file path
-            log_file = Path(log)
-
+        # Initialize logger (unified: terminal + file + YAML sessions)
         # Environment variable override (highest priority)
+        effective_log = log
         if os.getenv('CONNECTONION_LOG'):
-            log_file = Path(os.getenv('CONNECTONION_LOG'))
+            effective_log = Path(os.getenv('CONNECTONION_LOG'))
 
-        # Initialize console (always shows output, optional file logging)
-        self.console = Console(log_file=log_file)
+        self.logger = Logger(agent_name=name, quiet=quiet, log=effective_log)
         
 
         
@@ -93,12 +80,16 @@ class Agent:
             self.trust = create_trust_agent(trust, api_key=api_key, model=model)
 
         # Initialize event registry
+        # Note: before_each_tool/after_each_tool fire for EACH tool
+        # before_tools/after_tools fire ONCE per batch (safe for adding messages)
         self.events = {
             'after_user_input': [],
             'before_llm': [],
             'after_llm': [],
-            'before_tool': [],
-            'after_tool': [],
+            'before_each_tool': [],    # Fires before EACH tool
+            'before_tools': [],        # Fires ONCE before ALL tools in a batch
+            'after_each_tool': [],     # Fires after EACH tool (don't add messages here!)
+            'after_tools': [],         # Fires ONCE after ALL tools (safe for messages)
             'on_error': [],
             'on_complete': []
         }
@@ -200,7 +191,7 @@ class Agent:
             The agent's response after processing the input
         """
         start_time = time.time()
-        self.console.print(f"[bold]INPUT:[/bold] {prompt[:100]}...")
+        self.logger.print(f"[bold]INPUT:[/bold] {prompt[:100]}...")
 
         # Initialize session on first input, or continue existing conversation
         if self.current_session is None:
@@ -209,6 +200,8 @@ class Agent:
                 'trace': [],
                 'turn': 0  # Track conversation turns
             }
+            # Start YAML session logging
+            self.logger.start_session(self.system_prompt)
 
         # Add user message to conversation
         self.current_session['messages'].append({
@@ -238,11 +231,17 @@ class Agent:
             max_iterations or self.max_iterations
         )
 
-        # Calculate duration (console already logged everything)
+        # Calculate duration
         duration = time.time() - turn_start
 
-        self.console.print(f"[green]✓ Complete[/green] ({duration:.1f}s)")
+        self.current_session['result'] = result
+
+        self.logger.print(f"[green]✓ Complete[/green] ({duration:.1f}s)")
         self._invoke_events('on_complete')
+
+        # Log turn to YAML session (after on_complete so handlers can modify state)
+        self.logger.log_turn(prompt, result, duration * 1000, self.current_session, self.llm.model)
+
         return result
 
     def reset_conversation(self):
@@ -278,18 +277,21 @@ class Agent:
             tool_id=f"manual_{tool_name}_{time.time()}",
             tools=self.tools,
             agent=self,
-            console=self.console
+            logger=self.logger
         )
 
         # Note: trace_entry already added to session in execute_single_tool
 
         # Fire events (same as execute_and_record_tools)
-        # on_error fires first for errors/not_found, then after_tool always fires
+        # on_error fires first for errors/not_found
         if trace_entry["status"] in ("error", "not_found"):
             self._invoke_events('on_error')
 
-        # after_tool fires for ALL tool executions (success, error, not_found)
-        self._invoke_events('after_tool')
+        # after_each_tool fires for this tool execution
+        self._invoke_events('after_each_tool')
+
+        # after_tools fires after all tools in batch (for single execution, fires once)
+        self._invoke_events('after_tools')
 
         # Return simplified result (omit internal fields)
         return {
@@ -313,7 +315,7 @@ class Agent:
             self.current_session['iteration'] += 1
             iteration = self.current_session['iteration']
 
-            self.console.print(f"[dim]Iteration {iteration}/{max_iterations}[/dim]")
+            self.logger.print(f"[dim]Iteration {iteration}/{max_iterations}[/dim]")
 
             # Get LLM response
             response = self._get_llm_decision()
@@ -339,7 +341,7 @@ class Agent:
         # Show request info
         msg_count = len(self.current_session['messages'])
         tool_count = len(self.tools) if self.tools else 0
-        self.console.print(f"[yellow]→[/yellow] LLM Request ({self.llm.model}) • {msg_count} msgs • {tool_count} tools")
+        self.logger.print(f"[yellow]→[/yellow] LLM Request ({self.llm.model}) • {msg_count} msgs • {tool_count} tools")
 
         # Invoke before_llm events
         self._invoke_events('before_llm')
@@ -367,7 +369,7 @@ class Agent:
         # Invoke after_llm events (after trace entry is added)
         self._invoke_events('after_llm')
 
-        self.console.log_llm_response(duration, len(response.tool_calls), response.usage)
+        self.logger.log_llm_response(duration, len(response.tool_calls), response.usage)
 
         return response
 
@@ -377,7 +379,7 @@ class Agent:
             tool_calls=tool_calls,
             tools=self.tools,
             agent=self,
-            console=self.console
+            logger=self.logger
         )
 
     def add_tool(self, tool: Callable):
@@ -467,10 +469,10 @@ class Agent:
         addr_data = address.load(co_dir)
 
         if addr_data is None:
-            self.console.print("[yellow]No keys found, generating new identity...[/yellow]")
+            self.logger.print("[yellow]No keys found, generating new identity...[/yellow]")
             addr_data = address.generate()
             address.save(addr_data, co_dir)
-            self.console.print(f"[green]✓ Keys saved to {co_dir / 'keys'}[/green]")
+            self.logger.print(f"[green]✓ Keys saved to {co_dir / 'keys'}[/green]")
 
         # Create ANNOUNCE message
         # Use system_prompt as summary (first 1000 chars)
@@ -481,9 +483,9 @@ class Agent:
             endpoints=[]  # MVP: No direct endpoints yet
         )
 
-        self.console.print(f"\n[bold]Starting agent: {self.name}[/bold]")
-        self.console.print(f"Address: {addr_data['address']}")
-        self.console.print(f"Debug: https://oo.openonion.ai/agent/{addr_data['address']}\n")
+        self.logger.print(f"\n[bold]Starting agent: {self.name}[/bold]")
+        self.logger.print(f"Address: {addr_data['address']}")
+        self.logger.print(f"Debug: https://oo.openonion.ai/agent/{addr_data['address']}\n")
 
         # Define async task handler
         async def task_handler(prompt: str) -> str:

connectonion/cli/commands/init.py

@@ -79,7 +79,7 @@ def ensure_global_config() -> Dict[str, Any]:
         },
         "agent": {
             "algorithm": "ed25519",
-            "default_model": "gpt-4o-mini",
+            "default_model": "co/gemini-2.5-pro",
             "max_iterations": 10,
             "created_at": datetime.now().isoformat(),
         },

connectonion/cli/commands/project_cmd_lib.py

@@ -534,7 +534,7 @@ def configure_env_for_provider(provider: str, api_key: str) -> str:
     configs = {
         'openai': {
             'var': 'OPENAI_API_KEY',
-            'model': 'o4-mini'
+            'model': 'gpt-4o-mini'
         },
         'anthropic': {
             'var': 'ANTHROPIC_API_KEY',
@@ -624,8 +624,8 @@ def generate_custom_template_with_name(description: str, api_key: str, model: st
         try:
             from ...llm import create_llm
 
-            # Use the model specified or default to gpt-4o-mini
-            llm_model = model if model else "gpt-4o-mini"
+            # Use the model specified or default to co/gemini-2.5-pro
+            llm_model = model if model else "co/gemini-2.5-pro"
 
             if loading_animation:
                 loading_animation.update(f"Connecting to {llm_model}...")
@@ -710,7 +710,7 @@ def process_request(query: str) -> str:
 # Create agent
 agent = Agent(
     name="{suggested_name.replace('-', '_')}",
-    model="{'co/gpt-4o-mini' if model and model.startswith('co/') else 'gpt-4o-mini'}",
+    model="{'co/gemini-2.5-pro' if model and model.startswith('co/') else 'co/gemini-2.5-pro'}",
     system_prompt=\"\"\"You are an AI agent designed to: {description}
 
     Provide helpful, accurate, and concise responses.\"\"\",

connectonion/cli/commands/reset_commands.py

@@ -116,7 +116,7 @@ def handle_reset():
             "email_active": False,
             "created_at": datetime.now().isoformat(),
             "algorithm": "ed25519",
-            "default_model": "gpt-4o-mini",
+            "default_model": "co/gemini-2.5-pro",
             "max_iterations": 10,
         },
     }

connectonion/cli/docs/co-vibecoding-principles-docs-contexts-all-in-one.md

@@ -1530,13 +1530,13 @@ agent.input("Search for Python and calculate 15 * 8")
 **A plugin is an event list** - just like `on_events`, but reusable across agents:
 
 ```python
-from connectonion import after_tool, after_llm
+from connectonion import after_tools, after_each_tool, after_llm
 
 # This is a plugin (one event list)
-reflection = [after_tool(add_reflection)]
+reflection = [after_tools(add_reflection)]  # after_tools for message injection
 
 # This is also a plugin (multiple events in one list)
-logger = [after_llm(log_llm), after_tool(log_tool)]
+logger = [after_llm(log_llm), after_each_tool(log_tool)]  # after_each_tool for per-tool logging
 
 # Use them (plugins takes a list of plugins)
 agent = Agent("assistant", tools=[search], plugins=[reflection, logger])
@@ -1560,8 +1560,8 @@ logger = [after_llm(log_llm)]
 agent = Agent(
     name="assistant",
     tools=[search],
-    plugins=[logger],                                          # List of event lists
-    on_events=[after_llm(add_timestamp), after_tool(log_tool)] # One event list
+    plugins=[logger],                                                    # List of event lists
+    on_events=[after_llm(add_timestamp), after_each_tool(log_tool)]     # One event list
 )
 ```
 
@@ -1734,7 +1734,7 @@ Reflect in 1-2 sentences on what we learned:"""
 
 ```python
 # Plugin is an event list
-reflection = [after_tool(_add_reflection)]
+reflection = [after_tools(_add_reflection)]  # after_tools for message injection
 ```
 
 **That's it!** A plugin is just an event list.
@@ -1757,7 +1757,7 @@ def log_tool(agent):
     print(f"✓ {trace['tool_name']} completed in {trace['timing']}ms")
 
 # Plugin is an event list
-logger = [after_tool(log_tool)]
+logger = [after_each_tool(log_tool)]  # after_each_tool for per-tool logging
 
 # Use it
 agent = Agent("assistant", tools=[search], plugins=[logger])
@@ -1769,8 +1769,8 @@ Use the same plugin across multiple agents:
 
 ```python
 # Define once
-reflection = [after_tool(add_reflection)]
-logger = [after_llm(log_llm), after_tool(log_tool)]
+reflection = [after_tools(add_reflection)]  # after_tools for message injection
+logger = [after_llm(log_llm), after_each_tool(log_tool)]  # after_each_tool for per-tool logging
 
 # Use in multiple agents
 researcher = Agent("researcher", tools=[search], plugins=[reflection, logger])
@@ -1784,16 +1784,20 @@ analyst = Agent("analyst", tools=[calculate], plugins=[logger])
 
 ```python
 # Define a plugin (an event list)
-my_plugin = [after_llm(handler1), after_tool(handler2)]
+my_plugin = [after_llm(handler1), after_tools(handler2)]  # after_tools for message injection
 
 # Use it (plugins takes a list of event lists)
 agent = Agent("assistant", tools=[search], plugins=[my_plugin])
 ```
 
 **on_events vs plugins:**
-- `on_events=[after_llm(h1), after_tool(h2)]` → one event list
+- `on_events=[after_llm(h1), after_each_tool(h2)]` → one event list
 - `plugins=[plugin1, plugin2]` → list of event lists
 
+**Event naming:**
+- `after_each_tool` → fires for EACH tool (per-tool logging/monitoring)
+- `after_tools` → fires ONCE after all tools (safe for message injection)
+
 ---
 
 ## Best Practices

connectonion/cli/templates/minimal/agent.py

@@ -3,7 +3,7 @@ Purpose: Minimal agent template demonstrating basic ConnectOnion usage with a ca
 LLM-Note:
   Dependencies: imports from [connectonion.Agent] | template file copied by [cli/commands/init.py, cli/commands/create.py] | default template for 'co create' and 'co init'
   Data flow: user query → Agent.input() → calculator tool called if math expression → eval() computes result → returns answer
-  State/Effects: no persistent state | single Agent.input() call | uses co/gpt-5 model (OpenOnion hosted)
+  State/Effects: no persistent state | single Agent.input() call | uses co/gemini-2.5-pro model (OpenOnion hosted)
   Integration: template for 'co create --template minimal' | demonstrates function-as-tool pattern | shows system_prompt and model configuration
   Performance: single LLM call | eval() is fast
   Errors: ⚠️ Security: uses eval() - for demo only, not production safe
@@ -32,7 +32,7 @@ agent = Agent(
     name="calculator-agent", 
     system_prompt="pls use the calculator tool to answer math questions", # you can also pass a markdown file like system_prompt="path/to/your_markdown_file.md"
     tools=[calculator], # tools can be python classes or functions
-    model="co/gpt-5" # co/gpt-5 is hosted by OpenOnion, you can write your api key to .env file and change this to "gpt-5"
+    model="co/gemini-2.5-pro" # co/gemini-2.5-pro is hosted by OpenOnion, you can use your own API key by setting OPENAI_API_KEY in .env
 )
 
 # Run the agent

connectonion/console.py

@@ -1,10 +1,10 @@
 """
 Purpose: Handle agent terminal output with Rich formatting and optional file logging
 LLM-Note:
-  Dependencies: imports from [sys, datetime, pathlib, typing, rich.console, rich.panel, rich.text] | imported by [agent.py, tool_executor.py, auto_debug_exception.py] | tested by [tests/test_console.py]
-  Data flow: receives from Agent/tool_executor → .print(message, style) → formats with timestamp → prints to stderr via RichConsole → optionally appends to log_file as plain text
+  Dependencies: imports from [sys, datetime, pathlib, typing, rich.console, rich.panel, rich.text] | imported by [logger.py, tool_executor.py] | tested by [tests/test_console.py]
+  Data flow: receives from Logger/tool_executor → .print(), .log_tool_call(), .log_tool_result() → formats with timestamp → prints to stderr via RichConsole → optionally appends to log_file as plain text
   State/Effects: writes to stderr (not stdout, to avoid mixing with agent results) | writes to log_file if provided (plain text with timestamps) | creates log file parent directories if needed | appends session separator on init
-  Integration: exposes Console(log_file), .print(message, style), .print_xray_table(tool_name, tool_args, result, timing, agent) | used by Agent to show LLM/tool execution progress | tool_executor calls print_xray_table for @xray decorated tools
+  Integration: exposes Console(log_file), .print(message, style), .log_tool_call(name, args), .log_tool_result(result, timing), .log_llm_response(), .print_xray_table() | tool calls formatted as natural function-call style: greet(name='Alice')
   Performance: direct stderr writes (no buffering delays) | Rich formatting uses stderr (separate from stdout results) | regex-based markup removal for log files
   Errors: no error handling (let I/O errors bubble up) | assumes log_file parent can be created | assumes stderr is available
 """
@@ -159,6 +159,58 @@ class Console:
                 f.write(f"  result: {result_str}\n")
                 f.write(f"  Execution time: {timing/1000:.4f}s | Iteration: {iteration}/{max_iterations} | Breakpoint: @xray\n\n")
 
+    def log_tool_call(self, tool_name: str, tool_args: Dict[str, Any]) -> None:
+        """Log tool call - separate from result for clarity.
+
+        Short: → Tool: greet(name='Alice')
+        Long:  → Tool: write_file(path='test.py',
+                   content='...'
+                 )
+        """
+        formatted_args = self._format_tool_args_list(tool_args)
+        single_line = ", ".join(formatted_args)
+
+        if len(single_line) < 60 and len(formatted_args) <= 2:
+            self.print(f"[blue]→[/blue] Tool: {tool_name}({single_line})")
+        elif len(formatted_args) == 1:
+            # Single long arg: put on same line, will wrap naturally
+            self.print(f"[blue]→[/blue] Tool: {tool_name}({formatted_args[0]})")
+        else:
+            # Multi-line: first arg on same line as bracket, rest indented
+            base_indent = " " * (9 + len(tool_name) + 1)  # align with after "("
+            lines = [f"[blue]→[/blue] Tool: {tool_name}({formatted_args[0]},"]
+            for arg in formatted_args[1:-1]:
+                lines.append(f"{base_indent}{arg},")
+            lines.append(f"{base_indent}{formatted_args[-1]})")
+            self.print("\n".join(lines))
+
+    def log_tool_result(self, result: str, timing_ms: float) -> None:
+        """Log tool result - separate line for clarity."""
+        result_preview = result[:80] + "..." if len(result) > 80 else result
+        result_preview = result_preview.replace('\n', '\\n')
+        time_str = f"{timing_ms/1000:.4f}s" if timing_ms < 100 else f"{timing_ms/1000:.1f}s"
+        self.print(f"[green]←[/green] Tool Result ({time_str}): {result_preview}")
+
+    def _format_tool_args_list(self, args: Dict[str, Any]) -> list:
+        """Format each arg as key='value' with 150 char limit per value.
+
+        Escapes newlines so each arg stays on one line.
+        """
+        parts = []
+        for k, v in args.items():
+            if isinstance(v, str):
+                # Escape newlines for single-line display
+                v_str = v.replace('\n', '\\n').replace('\r', '\\r')
+                if len(v_str) > 150:
+                    v_str = v_str[:150] + "..."
+                parts.append(f"{k}='{v_str}'")
+            else:
+                v_str = str(v)
+                if len(v_str) > 150:
+                    v_str = v_str[:150] + "..."
+                parts.append(f"{k}={v_str}")
+        return parts
+
     def log_llm_response(self, duration_ms: float, tool_count: int, usage) -> None:
         """Log LLM response with token usage."""
         total_tokens = usage.input_tokens + usage.output_tokens

connectonion/events.py

@@ -4,7 +4,7 @@ LLM-Note:
   Dependencies: None (standalone module) | imported by [agent.py, __init__.py] | tested by [tests/test_events.py]
   Data flow: Wrapper functions tag event handlers with _event_type attribute → Agent organizes handlers by type → Agent invokes handlers at specific lifecycle points passing agent instance
   State/Effects: Event handlers receive agent instance and can modify agent.current_session (messages, trace, etc.)
-  Integration: exposes after_user_input(), before_llm(), after_llm(), before_tool(), after_tool(), on_error(), on_complete() | supports both decorator (@before_tool) and wrapper (before_tool(fn1, fn2)) syntax
+  Integration: exposes after_user_input(), before_llm(), after_llm(), before_each_tool(), before_tools(), after_each_tool(), after_tools(), on_error(), on_complete()
   Performance: Minimal overhead - just function attribute checking and iteration over handler lists
   Errors: Event handler exceptions propagate and stop agent execution (fail fast)
 """
@@ -79,11 +79,11 @@ def after_llm(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
     return funcs[0] if len(funcs) == 1 else list(funcs)
 
 
-def before_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+def before_each_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
     """
-    Mark function(s) as before_tool event handlers.
+    Mark function(s) as before_each_tool event handlers.
 
-    Fires before each tool execution.
+    Fires before EACH individual tool execution.
     Use for: validating arguments, approval prompts, logging.
 
     Access pending tool via agent.current_session['pending_tool']:
@@ -94,36 +94,115 @@ def before_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]
     Raise an exception to cancel the tool execution.
 
     Supports both decorator and wrapper syntax:
-        @before_tool
+        @before_each_tool
         def approve_dangerous(agent):
             ...
 
         # Multiple handlers
-        on_events=[before_tool(check_shell, check_email)]
+        on_events=[before_each_tool(check_shell, check_email)]
     """
     for fn in funcs:
-        fn._event_type = 'before_tool'  # type: ignore
+        fn._event_type = 'before_each_tool'  # type: ignore
     return funcs[0] if len(funcs) == 1 else list(funcs)
 
 
-def after_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+def before_tools(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
     """
-    Mark function(s) as after_tool event handlers.
+    Mark function(s) as before_tools event handlers.
 
-    Fires after each tool execution (success, error, or not_found).
-    Use for: adding reflection, logging performance.
+    Fires ONCE before ALL tools in a batch execute.
+
+    What is a "tools batch"?
+    When the LLM responds, it can request multiple tools at once. For example:
+        LLM Response: tool_calls = [search("python"), read_file("docs.md"), calculate(2+2)]
+
+    This group of tools from ONE LLM response is called a "tools batch".
+    - before_tools fires ONCE before the batch starts
+    - after_tools fires ONCE after ALL tools in the batch complete
+
+    Use for: batch validation, user approval before execution, setup.
 
     Supports both decorator and wrapper syntax:
-        @after_tool
-        def add_reflection(agent):
+        @before_tools
+        def log_batch_start(agent):
+            ...
+
+        on_events=[before_tools(handler)]
+    """
+    for fn in funcs:
+        fn._event_type = 'before_tools'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def after_each_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as after_each_tool event handlers.
+
+    Fires after EACH individual tool execution (success, error, or not_found).
+    Use for: logging individual tool performance, debugging.
+
+    ⚠️  WARNING: Do NOT add messages to agent.current_session['messages'] here!
+    When LLM returns multiple tool_calls, this fires after EACH tool, which would
+    interleave messages between tool results. This breaks Anthropic Claude's API
+    which requires all tool_results to immediately follow the tool_use message.
+
+    If you need to add messages after tools complete, use `after_tools` instead.
+
+    Supports both decorator and wrapper syntax:
+        @after_each_tool
+        def log_tool(agent):
             trace = agent.current_session['trace'][-1]
-            if trace['type'] == 'tool_execution' and trace['status'] == 'success':
-                print(f"Tool completed: {trace['tool_name']}")
+            if trace['type'] == 'tool_execution':
+                print(f"Tool: {trace['tool_name']} in {trace['timing']:.0f}ms")
+
+        on_events=[after_each_tool(handler1, handler2)]
+    """
+    for fn in funcs:
+        fn._event_type = 'after_each_tool'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def after_tools(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as after_tools event handlers.
+
+    Fires ONCE after ALL tools in a batch complete.
+
+    What is a "tools batch"?
+    When the LLM responds, it can request multiple tools at once. For example:
+        LLM Response: tool_calls = [search("python"), read_file("docs.md"), calculate(2+2)]
+
+    This group of tools from ONE LLM response is called a "tools batch".
+    - before_tools fires ONCE before the batch starts
+    - after_tools fires ONCE after ALL tools in the batch complete
+
+    This is the SAFE place to add messages to agent.current_session['messages']
+    after tool execution, because all tool_results have been added and message
+    ordering is correct for all LLM providers (including Anthropic Claude).
+
+    Message ordering when this event fires:
+        - assistant (with tool_calls)
+        - tool result 1
+        - tool result 2
+        - tool result N
+        - [YOUR MESSAGE HERE - safe to add]
+
+    Use for: reflection/reasoning injection, ReAct pattern, batch cleanup.
+
+    Supports both decorator and wrapper syntax:
+        @after_tools
+        def add_reflection(agent):
+            trace = agent.current_session['trace']
+            recent = [t for t in trace if t['type'] == 'tool_execution'][-3:]
+            agent.current_session['messages'].append({
+                'role': 'assistant',
+                'content': f"Completed {len(recent)} tools"
+            })
 
-        on_events=[after_tool(handler1, handler2)]
+        on_events=[after_tools(add_reflection)]
     """
     for fn in funcs:
-        fn._event_type = 'after_tool'  # type: ignore
+        fn._event_type = 'after_tools'  # type: ignore
     return funcs[0] if len(funcs) == 1 else list(funcs)