aru-code 0.23.0__tar.gz → 0.24.0__tar.gz

{aru_code-0.23.0/aru_code.egg-info → aru_code-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.23.0
+Version: 0.24.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT

aru_code-0.24.0/aru/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.24.0"

{aru_code-0.23.0 → aru_code-0.24.0}/aru/agent_factory.py

@@ -33,6 +33,22 @@ def _wrap_tools_with_hooks(tools: list) -> list:
             pass
         return data
 
+    async def _fire_tool_definition(tool_name: str, description: str, parameters: dict) -> dict:
+        """Fire tool.definition hook — plugins can modify tool desc/params."""
+        try:
+            ctx = get_ctx()
+            mgr = ctx.plugin_manager
+            if mgr is not None and mgr.loaded:
+                event = await mgr.fire("tool.definition", {
+                    "tool_name": tool_name,
+                    "description": description,
+                    "parameters": parameters,
+                })
+                return event.data
+        except (LookupError, AttributeError):
+            pass
+        return {"tool_name": tool_name, "description": description, "parameters": parameters}
+
     def _wrap_one(fn):
         if not callable(fn) or getattr(fn, "_hook_wrapped", False):
             return fn
@@ -70,6 +86,68 @@ def _wrap_tools_with_hooks(tools: list) -> list:
     return [_wrap_one(t) for t in tools]
 
 
+def _fire_sync_hook(event_name: str, data: dict) -> dict:
+    """Fire a plugin hook synchronously (for agent creation context).
+
+    Agent creation happens in sync code, so we need a sync path.
+    """
+    try:
+        from aru.runtime import get_ctx
+        ctx = get_ctx()
+        mgr = ctx.plugin_manager
+        if mgr is not None and mgr.loaded:
+            import asyncio
+            from aru.plugins.hooks import HookEvent
+            event = HookEvent(hook=event_name, data=data or {})
+            for hooks in mgr._hooks:
+                for handler in hooks.get_handlers(event_name):
+                    try:
+                        if asyncio.iscoroutinefunction(handler):
+                            # Best-effort: try to run async handler
+                            try:
+                                loop = asyncio.get_running_loop()
+                            except RuntimeError:
+                                loop = None
+                            if loop and loop.is_running():
+                                # Can't await in sync context with running loop — skip
+                                continue
+                            else:
+                                asyncio.run(handler(event))
+                        else:
+                            handler(event)
+                    except Exception as e:
+                        logger.warning("Hook handler error (%s): %s", event_name, e)
+            return event.data
+    except (LookupError, AttributeError):
+        pass
+    return data
+
+
+def _apply_chat_hooks(instructions: str, model_ref: str, agent_name: str,
+                      max_tokens: int = 8192) -> tuple[str, str, int]:
+    """Apply chat.system.transform and chat.params hooks to agent creation params.
+
+    Returns (instructions, model_ref, max_tokens) — possibly modified by plugins.
+    """
+    # chat.system.transform — plugins can modify the system prompt
+    data = _fire_sync_hook("chat.system.transform", {
+        "system_prompt": instructions,
+        "agent": agent_name,
+    })
+    instructions = data.get("system_prompt", instructions)
+
+    # chat.params — plugins can modify LLM parameters
+    data = _fire_sync_hook("chat.params", {
+        "model": model_ref,
+        "max_tokens": max_tokens,
+        "temperature": None,  # let plugin set if desired
+    })
+    model_ref = data.get("model", model_ref)
+    max_tokens = data.get("max_tokens", max_tokens)
+
+    return instructions, model_ref, max_tokens
+
+
 def create_general_agent(
     session: Session,
     config: AgentConfig | None = None,
@@ -91,12 +169,18 @@ def create_general_agent(
     if env_context:
         extra = f"{extra}\n\n{env_context}" if extra else env_context
     model_ref = model_override or session.model_ref
+    instructions = _build_instructions("general", extra)
+
+    # Apply chat hooks (system.transform + params)
+    instructions, model_ref, max_tokens = _apply_chat_hooks(
+        instructions, model_ref, "Aru", max_tokens=8192,
+    )
 
     return Agent(
         name="Aru",
-        model=create_model(model_ref, max_tokens=8192),
+        model=create_model(model_ref, max_tokens=max_tokens),
         tools=tools,
-        instructions=_build_instructions("general", extra),
+        instructions=instructions,
         markdown=True,
         tool_call_limit=20,
     )
@@ -121,9 +205,14 @@ def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
         parts.append(extra)
     instructions = "\n\n".join(parts)
 
+    # Apply chat hooks (system.transform + params)
+    instructions, model_ref, max_tokens = _apply_chat_hooks(
+        instructions, model_ref, agent_def.name, max_tokens=8192,
+    )
+
     return Agent(
         name=agent_def.name,
-        model=create_model(model_ref, max_tokens=8192),
+        model=create_model(model_ref, max_tokens=max_tokens),
         tools=tools,
         instructions=instructions,
         markdown=True,

{aru_code-0.23.0 → aru_code-0.24.0}/aru/agents/base.py

@@ -161,7 +161,10 @@ Use `context_lines=30` for full function bodies.
 
 **Batch independent tool calls**: emit ALL independent tool calls in a single response.
 
-Use delegate_task to split work into independent subtasks for parallel execution.
+Use delegate_task to split work into independent subtasks for parallel execution. \
+For broad codebase exploration (searching many files, finding patterns, understanding code), \
+break the research into focused questions and spawn multiple \
+`delegate_task(task="<specific search>", agent_name="explorer")` calls in parallel.
 
 When given a plan, execute it step by step. When given a direct task, figure out what needs to be done and do it.
 **ZERO narration between tool calls.** No "Now I have enough context...", \
@@ -208,7 +211,34 @@ Batch what you need upfront, then execute.
 
 **When adding or modifying unit tests, ALWAYS run them to verify they pass before finishing.**
 
-Use delegate_task to split work into independent subtasks for parallel execution.\
+## Delegation strategy — CRITICAL for context efficiency
+
+For simple, directed lookups (one known file, one specific symbol) use \
+`grep_search` / `glob_search` / `read_file` directly.
+
+For **anything broader** — understanding a system, researching before implementing, \
+analyzing multiple files, writing specs or documentation — **always use explorer agents**. \
+Every `read_file` / `read_file_smart` / `grep_search` result you call directly accumulates \
+in YOUR context window and stays there forever. Explorer agents read files in their own \
+isolated context and return only a concise summary. This is critical: \
+**3 explorer summaries < 8 raw file reads** in context cost.
+
+**Rule of thumb**: If you'd need to read or search more than 2-3 files, use explorers instead.
+
+**Decompose, don't dump.** Never throw one vague task at one explorer. \
+Break the work into **focused, independent search questions** and spawn one explorer \
+per question — all in a single response so they run in parallel. Each explorer prompt \
+should be specific enough that it can search and answer on its own.
+
+Example — user asks "explain the authentication system":
+```
+delegate_task(task="Find auth middleware: search for login/logout handlers, session management, token validation", agent_name="explorer")
+delegate_task(task="Find auth configuration: search for auth-related config files, env vars, secrets setup", agent_name="explorer")
+delegate_task(task="Find auth tests: search for test files covering authentication flows", agent_name="explorer")
+```
+
+After all explorers return, **synthesize their findings yourself** — the user sees \
+your summary, not the raw explorer output.\
 """
 
 

aru_code-0.24.0/aru/agents/explorer.py

@@ -0,0 +1,91 @@
+"""Explorer agent — fast, read-only codebase exploration specialist."""
+
+import os
+
+from agno.agent import Agent
+
+from aru.providers import create_model
+from aru.runtime import get_ctx
+from aru.tools.codebase import (
+    bash,
+    glob_search,
+    grep_search,
+    list_directory,
+    rank_files,
+    read_file,
+    read_file_smart,
+)
+
+# Read-only tools only — no write/edit/delegate (prevents recursion and mutations)
+EXPLORER_TOOLS = [
+    read_file,
+    read_file_smart,
+    glob_search,
+    grep_search,
+    list_directory,
+    bash,
+    rank_files,
+]
+
+EXPLORER_ROLE = """\
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE — NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no write_file, touch, or file creation of any kind)
+- Modifying existing files (no edit_file operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. \
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use glob_search for broad file pattern matching
+- Use grep_search for searching file contents with regex
+- Use read_file when you know the specific file path you need to read
+- Use read_file_smart when you know the file and have a specific question about it
+- Use bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, \
+or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+
+NOTE: You are meant to be a FAST agent that returns output as quickly as possible. To achieve this:
+- Make efficient use of tools: be smart about how you search for files and implementations
+- Wherever possible, spawn MULTIPLE PARALLEL tool calls for grepping and reading files
+- Do not read files you don't need — stop as soon as you have enough information
+
+Complete the search request efficiently and report your findings clearly.\
+"""
+
+
+def create_explorer(task: str, context: str = "") -> Agent:
+    """Create and return an explorer agent for a specific task.
+
+    Args:
+        task: The exploration task description.
+        context: Optional extra context (file paths, constraints).
+    """
+    cwd = os.getcwd()
+    small_model_ref = get_ctx().small_model_ref
+
+    instructions = EXPLORER_ROLE + f"\nThe current working directory is: {cwd}\n"
+    if context:
+        instructions += f"\nAdditional context:\n{context}\n"
+
+    return Agent(
+        name="Explorer",
+        model=create_model(small_model_ref, max_tokens=4096),
+        tools=EXPLORER_TOOLS,
+        instructions=instructions,
+        markdown=True,
+        tool_call_limit=15,
+    )

{aru_code-0.23.0 → aru_code-0.24.0}/aru/cli.py

@@ -228,10 +228,20 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
     ctx.plugin_manager = _plugin_mgr
 
     try:
+        _config_dict = {
+            "default_model": config.default_model,
+            "model_aliases": config.model_aliases,
+            "permissions": config.permissions,
+            "plugin_specs": config.plugin_specs,
+            "disabled_tools": config.disabled_tools,
+            "plan_reviewer": config.plan_reviewer,
+        }
         _p_input = PluginInput(
             directory=os.getcwd(),
             config_path="aru.json" if os.path.isfile("aru.json") else "",
             model_ref=session.model_ref,
+            config=_config_dict,
+            session=session,
         )
         _plugin_specs = config.plugin_specs if hasattr(config, "plugin_specs") else []
         _plugin_count = await _plugin_mgr.load_all(_p_input, plugin_specs=_plugin_specs)
@@ -252,6 +262,17 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
 
     asyncio.create_task(_load_mcp_background())
 
+    # Event: session.start
+    if _plugin_mgr.loaded:
+        try:
+            await _plugin_mgr.publish("session.start", {
+                "session_id": getattr(session, "id", None),
+                "model_ref": session.model_ref,
+                "directory": os.getcwd(),
+            })
+        except Exception:
+            pass
+
     while True:
         try:
             paste_state.clear()
@@ -393,6 +414,14 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             continue
 
         if user_input.lower() in ("/quit", "/exit", "quit", "exit"):
+            # Event: session.end
+            if _plugin_mgr.loaded:
+                try:
+                    await _plugin_mgr.publish("session.end", {
+                        "session_id": getattr(session, "id", None),
+                    })
+                except Exception:
+                    pass
             store.save(session)
             console.print(f"\n[dim]Session saved: {session.session_id}[/dim]")
             console.print(f"[dim]Resume with:[/dim] [bold cyan]aru --resume {session.session_id}[/bold cyan]")
@@ -579,6 +608,26 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             cmd_name = parts[0].lower()
             cmd_args = parts[1] if len(parts) > 1 else ""
 
+            # Hook: command.execute.before — plugins can block or modify
+            _cmd_blocked = False
+            try:
+                _mgr = ctx.plugin_manager
+                if _mgr is not None and _mgr.loaded:
+                    _cmd_event = await _mgr.fire("command.execute.before", {
+                        "command": cmd_name,
+                        "command_args": cmd_args,
+                        "blocked": False,
+                    })
+                    if _cmd_event.data.get("blocked"):
+                        console.print(f"[yellow]Command /{cmd_name} blocked by plugin.[/yellow]")
+                        _cmd_blocked = True
+                    else:
+                        cmd_args = _cmd_event.data.get("command_args", cmd_args)
+            except Exception:
+                pass
+            if _cmd_blocked:
+                continue
+
             if cmd_name in config.commands:
                 cmd_def = config.commands[cmd_name]
                 prompt = render_command_template(cmd_def.template, cmd_args)

{aru_code-0.23.0 → aru_code-0.24.0}/aru/config.py

@@ -552,7 +552,7 @@ def load_config(cwd: str | None = None) -> AgentConfig:
     # Load config: global (~/.aru/config.json) first, then project-level on top.
     # Project values override global values via deep merge.
     home = Path.home()
-    global_config_paths = [home / ".aru" / "config.json"]
+    global_config_paths = [home / ".aru" / "aru.json", home / ".aru" / "config.json"]
     project_config_paths = [root / "aru.json", root / ".aru" / "config.json"]
 
     merged_data: dict = {}

{aru_code-0.23.0 → aru_code-0.24.0}/aru/display.py

@@ -204,6 +204,7 @@ TOOL_DISPLAY_NAMES = {
     "list_directory": "List",
     "bash": "Bash",
     "rank_files": "Rank",
+    "delegate_task": "Agent",
 }
 
 TOOL_PRIMARY_ARG = {
@@ -216,6 +217,12 @@ TOOL_PRIMARY_ARG = {
     "list_directory": "directory",
     "bash": "command",
     "rank_files": "task",
+    "delegate_task": "task",
+}
+
+# Agent type display names for delegate_task
+_AGENT_TYPE_LABELS = {
+    "explorer": "Explorer",
 }
 
 
@@ -225,6 +232,17 @@ def _format_tool_label(tool_name: str, tool_args: dict | None) -> str:
     if not tool_args:
         return display
 
+    # Special handling for delegate_task — show agent type and task summary
+    if tool_name == "delegate_task":
+        agent = str(tool_args.get("agent_name", "") or tool_args.get("agent", ""))
+        agent_label = _AGENT_TYPE_LABELS.get(agent, agent.title() if agent else "SubAgent")
+        task = str(tool_args.get("task", ""))
+        # Extract first meaningful line/sentence as summary
+        summary = task.split("\n")[0].strip()
+        if len(summary) > 60:
+            summary = summary[:57] + "..."
+        return f"{agent_label}({summary})" if summary else agent_label
+
     primary_key = TOOL_PRIMARY_ARG.get(tool_name)
     if primary_key and primary_key in tool_args:
         value = str(tool_args[primary_key])

{aru_code-0.23.0 → aru_code-0.24.0}/aru/plugins/hooks.py

@@ -29,14 +29,28 @@ logger = logging.getLogger("aru.plugins")
 
 # Valid hook names (mirrors relevant OpenCode hooks)
 VALID_HOOKS = frozenset({
+    # Lifecycle
     "config",                    # After config loaded
+    "event",                     # Subscribe to all bus events
+
+    # Tool lifecycle
     "tool.execute.before",       # Before any tool runs
     "tool.execute.after",        # After any tool runs
-    "tool.definition",           # When tools are resolved (can add/remove)
-    "permission.ask",            # Before permission prompt
+    "tool.definition",           # When tools are resolved (can modify desc/params)
+
+    # Chat lifecycle
+    "chat.message",              # Before user message is sent to LLM (can modify)
+    "chat.params",               # Before LLM call (can modify temperature, max_tokens)
+    "chat.system.transform",     # Before LLM call (can modify system prompt)
+    "chat.messages.transform",   # Before LLM call (can modify message history)
+
+    # Command lifecycle
+    "command.execute.before",    # Before slash command runs (can block/modify)
+
+    # Permission / shell
+    "permission.ask",            # Before permission prompt (can auto-allow/deny)
     "shell.env",                 # Before bash subprocess
     "session.compact",           # Before context compaction
-    "event",                     # Subscribe to all events
 })
 
 
@@ -75,6 +89,60 @@ class HookEvent:
     def env(self, value: dict[str, str]) -> None:
         self.data["env"] = value
 
+    # -- Chat hook accessors --
+
+    @property
+    def message(self) -> str:
+        return self.data.get("message", "")
+
+    @message.setter
+    def message(self, value: str) -> None:
+        self.data["message"] = value
+
+    @property
+    def messages(self) -> list:
+        return self.data.get("messages", [])
+
+    @messages.setter
+    def messages(self, value: list) -> None:
+        self.data["messages"] = value
+
+    @property
+    def system_prompt(self) -> str:
+        return self.data.get("system_prompt", "")
+
+    @system_prompt.setter
+    def system_prompt(self, value: str) -> None:
+        self.data["system_prompt"] = value
+
+    @property
+    def params(self) -> dict[str, Any]:
+        return self.data.get("params", {})
+
+    @params.setter
+    def params(self, value: dict[str, Any]) -> None:
+        self.data["params"] = value
+
+    # -- Command hook accessors --
+
+    @property
+    def command(self) -> str:
+        return self.data.get("command", "")
+
+    @property
+    def command_args(self) -> str:
+        return self.data.get("command_args", "")
+
+    @property
+    def blocked(self) -> bool:
+        return self.data.get("blocked", False)
+
+    @blocked.setter
+    def blocked(self, value: bool) -> None:
+        self.data["blocked"] = value
+
+    # -- Generic accessors --
+
     def get(self, key: str, default: Any = None) -> Any:
         return self.data.get(key, default)
 
@@ -91,6 +159,8 @@ class PluginInput:
     directory: str        # project root (os.getcwd())
     config_path: str      # path to aru.json (or "")
     model_ref: str        # current model reference
+    config: dict[str, Any] = field(default_factory=dict)  # full config dict
+    session: Any = None   # session object (if available at init time)
 
 
 class Hooks:

{aru_code-0.23.0 → aru_code-0.24.0}/aru/plugins/manager.py

@@ -12,6 +12,7 @@ Plugin sources:
 from __future__ import annotations
 
 import asyncio
+from collections import defaultdict
 import importlib
 import importlib.metadata
 import importlib.util
@@ -34,12 +35,20 @@ def _noop_manager():
 
 
 class PluginManager:
-    """Loads plugins, aggregates hooks, and fires events."""
+    """Loads plugins, aggregates hooks, fires events, and manages event bus.
+
+    Two dispatch mechanisms:
+      - ``fire(hook_name, data)`` — sequential interceptors, handlers can mutate data.
+      - ``publish(event_type, data)`` — fan-out notifications, read-only for subscribers.
+        Also fires the ``event`` hook so plugins registered via hooks see all events.
+    """
 
     def __init__(self) -> None:
         self._hooks: list[Hooks] = []
         self._plugin_names: list[str] = []
         self._loaded = False
+        # Event bus: subscribers keyed by event type (or "*" for all)
+        self._subscribers: dict[str, list[Callable]] = defaultdict(list)
 
     @property
     def loaded(self) -> bool:
@@ -125,6 +134,16 @@ class PluginManager:
             pass  # entry_points may fail on older Python
 
         self._loaded = True
+
+        # Fire config hook so plugins can react to the current configuration
+        if count > 0:
+            config_data: dict[str, Any] = {}
+            if plugin_input.config:
+                config_data = dict(plugin_input.config)
+            config_data.setdefault("directory", plugin_input.directory)
+            config_data.setdefault("model_ref", plugin_input.model_ref)
+            await self.fire("config", config_data)
+
         return count
 
     async def fire(self, event_name: str, data: dict[str, Any] | None = None) -> HookEvent:
@@ -152,6 +171,47 @@ class PluginManager:
 
         return event
 
+    # -- Event bus (pub/sub) --
+
+    def subscribe(self, event_type: str, callback: Callable) -> None:
+        """Subscribe to a specific event type (e.g. 'message.user', 'tool.called')."""
+        self._subscribers[event_type].append(callback)
+
+    def subscribe_all(self, callback: Callable) -> None:
+        """Subscribe to all events (wildcard)."""
+        self._subscribers["*"].append(callback)
+
+    async def publish(self, event_type: str, data: dict[str, Any] | None = None) -> None:
+        """Publish an event to all subscribers + fire the ``event`` hook.
+
+        Unlike ``fire()``, this is fan-out: subscribers receive a copy and
+        cannot mutate the event for other subscribers.
+        """
+        payload = {"event_type": event_type, **(data or {})}
+
+        # Notify typed subscribers
+        for cb in self._subscribers.get(event_type, []):
+            try:
+                if asyncio.iscoroutinefunction(cb):
+                    await cb(payload)
+                else:
+                    cb(payload)
+            except Exception as e:
+                logger.error("Event subscriber error (%s): %s", event_type, e)
+
+        # Notify wildcard subscribers
+        for cb in self._subscribers.get("*", []):
+            try:
+                if asyncio.iscoroutinefunction(cb):
+                    await cb(payload)
+                else:
+                    cb(payload)
+            except Exception as e:
+                logger.error("Event subscriber error (*): %s", e)
+
+        # Fire the ``event`` hook so hook-based plugins also see all events
+        await self.fire("event", payload)
+
     def get_plugin_tools(self) -> list[dict[str, Any]]:
         """Collect all tools registered by plugins.
 

{aru_code-0.23.0 → aru_code-0.24.0}/aru/runner.py

@@ -26,6 +26,50 @@ from aru.permissions import get_skip_permissions
 _MUTATION_TOOLS = {"write_file", "edit_file", "bash"}
 
 
+async def _fire_plugin_hook(event_name: str, data: dict) -> dict:
+    """Fire a plugin hook if the plugin manager is available. Returns (mutated) data."""
+    try:
+        from aru.runtime import get_ctx
+        ctx = get_ctx()
+        mgr = ctx.plugin_manager
+        if mgr is not None and mgr.loaded:
+            event = await mgr.fire(event_name, data)
+            return event.data
+    except (LookupError, AttributeError):
+        pass
+    return data
+
+
+async def _publish_event(event_type: str, data: dict | None = None) -> None:
+    """Publish an event to the plugin event bus (fire-and-forget)."""
+    try:
+        from aru.runtime import get_ctx
+        ctx = get_ctx()
+        mgr = ctx.plugin_manager
+        if mgr is not None and mgr.loaded:
+            await mgr.publish(event_type, data or {})
+    except (LookupError, AttributeError):
+        pass
+
+
+async def _fire_chat_message_hook(message: str, session=None) -> str:
+    """Fire chat.message hook — plugins can modify the user message."""
+    data = await _fire_plugin_hook("chat.message", {
+        "message": message,
+        "session_id": getattr(session, "id", None),
+    })
+    return data.get("message", message)
+
+
+async def _fire_chat_messages_transform_hook(messages: list, session=None) -> list:
+    """Fire chat.messages.transform hook — plugins can modify message history."""
+    data = await _fire_plugin_hook("chat.messages.transform", {
+        "messages": messages,
+        "session_id": getattr(session, "id", None),
+    })
+    return data.get("messages", messages)
+
+
 def build_env_context(session, cwd: str | None = None) -> str:
     """Build environment context string (cwd, git status) for system prompt.
 
@@ -133,6 +177,15 @@ async def run_agent_capture(agent, message: str, session=None, lightweight: bool
         else:
             run_message = message
 
+        # Hook: chat.message — let plugins intercept/modify user message
+        run_message = await _fire_chat_message_hook(run_message, session)
+
+        # Event: message.user
+        await _publish_event("message.user", {
+            "message": run_message,
+            "session_id": getattr(session, "id", None),
+        })
+
         # Build conversation history as real messages for the LLM.
         # At turn start we only do reversible pruning — destructive compaction
         # is reserved for the post-turn reactive path (below) which fires when
@@ -150,6 +203,10 @@ async def run_agent_capture(agent, message: str, session=None, lightweight: bool
             prior_history = session.history[:-1]
             history_messages = to_agno_messages(prior_history)
 
+        # Hook: chat.messages.transform — let plugins modify history before LLM
+        if history_messages:
+            history_messages = await _fire_chat_messages_transform_hook(history_messages, session)
+
         # Combine: history messages + current enriched message
         if history_messages:
             history_messages.append(Message(role="user", content=run_message, images=images or None))
@@ -203,6 +260,11 @@ async def run_agent_capture(agent, message: str, session=None, lightweight: bool
                     tracker.start(tool_id, label)
                     status.set_text(f"{label}...")
                     live.update(display)
+                    # Event: tool.called
+                    await _publish_event("tool.called", {
+                        "tool_name": tool_name, "tool_id": tool_id,
+                        "args": tool_args if isinstance(tool_args, dict) else {},
+                    })
 
                 elif isinstance(event, ToolCallCompletedEvent):
                     _stall_counter = 0
@@ -230,6 +292,11 @@ async def run_agent_capture(agent, message: str, session=None, lightweight: bool
                             })
                         pending_tool_uses.pop(tool_id, None)
 
+                    # Event: tool.completed
+                    await _publish_event("tool.completed", {
+                        "tool_id": tool_id,
+                        "result_length": len(str(tool_result_text)) if tool_result_text else 0,
+                    })
                     result = tracker.complete(tool_id)
                     for label, duration in tracker.pop_completed():
                         dur_str = f" {duration:.1f}s" if duration >= 0.5 else ""
@@ -334,6 +401,14 @@ async def run_agent_capture(agent, message: str, session=None, lightweight: bool
                         pass
 
         final_content = accumulated or final_content
+
+        # Event: message.assistant
+        await _publish_event("message.assistant", {
+            "content": final_content,
+            "tool_calls": collected_tool_calls,
+            "session_id": getattr(session, "id", None),
+        })
+
         remaining = (final_content or "")[display._flushed_len:]
         if remaining:
             console.print(Markdown(remaining))

{aru_code-0.23.0 → aru_code-0.24.0}/aru/tools/codebase.py

@@ -1218,14 +1218,14 @@ _SUBAGENT_TOOLS = [
 ]
 
 
-async def delegate_task(task: str, context: str = "", agent: str = "") -> str:
+async def delegate_task(task: str, context: str = "", agent_name: str = "") -> str:
     """Delegate a task to a sub-agent that runs autonomously. Multiple calls run concurrently.
     Use for independent research or subtasks to keep your own context clean.
 
     Args:
         task: What the sub-agent should do.
         context: Optional extra context (file paths, constraints).
-        agent: Optional custom agent name to use instead of the generic sub-agent.
+        agent_name: Name of a specialized agent to use instead of the generic sub-agent.
     """
 
     async def _run() -> str:
@@ -1243,19 +1243,15 @@ async def delegate_task(task: str, context: str = "", agent: str = "") -> str:
 
         agent_perm = None
         custom_agent_defs = get_ctx().custom_agent_defs
-        # Agno may pass the caller Agent object instead of a string — coerce to str
-        agent_name = str(agent) if agent and isinstance(agent, str) else ""
-
-        # Print delegation info so the user sees what's happening
-        from rich.console import Console
-        _console = Console()
-        if agent_name and agent_name in custom_agent_defs:
-            _console.print(f"[dim]  → Delegating to agent [bold]{agent_name}[/bold] (task: {task[:80]}{'...' if len(task) > 80 else ''})[/dim]")
-        else:
-            _console.print(f"[dim]  → Delegating to sub-agent #{agent_id} (task: {task[:80]}{'...' if len(task) > 80 else ''})[/dim]")
-
-        if agent_name and agent_name in custom_agent_defs:
-            agent_def = custom_agent_defs[agent_name]
+        _agent_name = str(agent_name).strip() if agent_name else ""
+
+        # Built-in explorer agent — fast, read-only codebase exploration
+        if _agent_name == "explorer":
+            from aru.agents.explorer import create_explorer
+            sub = create_explorer(task, context)
+            sub.name = f"Explorer-{agent_id}"
+        elif _agent_name and _agent_name in custom_agent_defs:
+            agent_def = custom_agent_defs[_agent_name]
             agent_perm = agent_def.permission
             tools = resolve_tools(agent_def.tools) if agent_def.tools else list(_SUBAGENT_TOOLS)
             tools = [t for t in tools if t is not delegate_task]
@@ -1288,15 +1284,16 @@ Do not create documentation files unless explicitly asked.
                 markdown=True,
             )
 
+        label = f"Explorer-{agent_id}" if _agent_name == "explorer" else f"SubAgent-{agent_id}"
         try:
             from aru.permissions import permission_scope
             with permission_scope(agent_perm):
                 result = await sub.arun(task, stream=False)
             if result and result.content:
-                return _truncate_output(f"[SubAgent-{agent_id}] {result.content}")
-            return f"[SubAgent-{agent_id}] Task completed but no output was returned."
+                return _truncate_output(f"[{label}] {result.content}")
+            return f"[{label}] Task completed but no output was returned."
         except Exception as e:
-            return f"[SubAgent-{agent_id}] Error: {e}"
+            return f"[{label}] Error: {e}"
 
     # Run in a separate asyncio Task so each sub-agent gets its own
     # contextvars snapshot — essential for parallel permission_scope isolation.
@@ -1408,15 +1405,21 @@ def _update_delegate_task_docstring():
     Args:
         task: What the sub-agent should do.
         context: Optional extra context (file paths, constraints).
-        agent: Name of a specialized agent to use. ALWAYS prefer a specialized agent when one matches the task."""
+        agent_name: Name of a specialized agent to use. ALWAYS prefer a specialized agent when one matches the task.
+
+    Built-in agents (always available):
+    - agent_name="explorer": Fast read-only codebase exploration agent. Use for searching files, \
+finding patterns, reading code, and understanding code structure. Optimized for speed with parallel tool calls. \
+When calling this agent, specify the desired thoroughness level: "quick" for basic searches, \
+"medium" for moderate exploration, or "very thorough" for comprehensive analysis."""
 
     custom_agent_defs = get_ctx().custom_agent_defs
     if custom_agent_defs:
-        lines = [f"\n\n    IMPORTANT: When a specialized agent matches the task, you MUST pass its name in the agent parameter."]
-        lines.append(f"    Available specialized agents:")
+        lines = [f"\n\n    IMPORTANT: When a specialized agent matches the task, you MUST pass its name in the agent_name parameter."]
+        lines.append(f"    Additional specialized agents:")
         for name, agent_def in custom_agent_defs.items():
-            lines.append(f"    - agent=\"{name}\": {agent_def.description}")
-        lines.append(f"\n    If no specialized agent fits, omit the agent parameter to use a generic sub-agent.")
+            lines.append(f'    - agent_name="{name}": {agent_def.description}')
+        lines.append(f"\n    If no specialized agent fits, omit the agent_name parameter to use a generic sub-agent.")
         base_doc += "\n".join(lines)
 
     delegate_task.__doc__ = base_doc

{aru_code-0.23.0 → aru_code-0.24.0/aru_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.23.0
+Version: 0.24.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT

{aru_code-0.23.0 → aru_code-0.24.0}/aru_code.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ aru/session.py
 aru/agents/__init__.py
 aru/agents/base.py
 aru/agents/executor.py
+aru/agents/explorer.py
 aru/agents/planner.py
 aru/plugins/__init__.py
 aru/plugins/custom_tools.py

{aru_code-0.23.0 → aru_code-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aru-code"
-version = "0.23.0"
+version = "0.24.0"
 description = "A Claude Code clone built with Agno agents"
 readme = "README.md"
 license = "MIT"

{aru_code-0.23.0 → aru_code-0.24.0}/tests/test_codebase.py

@@ -623,7 +623,7 @@ class TestDelegateTaskDocstring:
         }
         set_custom_agents(agents)
         doc = delegate_task.__doc__
-        assert 'agent="reviewer"' in doc
+        assert 'agent_name="reviewer"' in doc
         assert "Review code for quality" in doc
         # Primary agents should not be listed (only subagents are registered)
         assert "Primary" not in doc

aru_code-0.23.0/aru/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.23.0"