aru-code 0.26.1__tar.gz → 0.28.0__tar.gz

{aru_code-0.26.1 → aru_code-0.28.0}/PKG-INFO

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

aru_code-0.28.0/aru/__init__.py

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

{aru_code-0.26.1 → aru_code-0.28.0}/aru/agent_factory.py

@@ -15,40 +15,47 @@ from aru.session import Session
 logger = logging.getLogger("aru.agent_factory")
 
 
+async def _fire_hook(event_name: str, data: dict) -> dict:
+    """Fire a plugin hook and return the (possibly mutated) event 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
+
+
+# Tools blocked while the session is in plan mode. Read-only tools (read,
+# glob, grep, list_directory, web_search, web_fetch, etc.) are NOT in this
+# set — the agent needs them to research and write the plan. Mutating or
+# execution-capable tools are gated: the agent must call exit_plan_mode and
+# get user approval before running any of these.
+_PLAN_MODE_BLOCKED_TOOLS: frozenset[str] = frozenset({
+    "edit_file",
+    "edit_files",
+    "write_file",
+    "write_files",
+    "bash",
+    "delegate_task",
+})
+
+
 def _wrap_tools_with_hooks(tools: list) -> list:
     """Wrap tool functions to fire tool.execute.before/after plugin hooks.
 
     Before hook can mutate args; after hook can mutate the result.
     If a before hook raises, the tool is not executed and the error is returned.
-    """
-    from aru.runtime import get_ctx
 
-    async def _fire(event_name: str, data: dict) -> dict:
-        try:
-            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 _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}
+    Also enforces the plan-mode gate: when `session.plan_mode` is True,
+    any tool in `_PLAN_MODE_BLOCKED_TOOLS` short-circuits with a structured
+    BLOCKED message telling the agent to call `exit_plan_mode` first. The
+    gate runs BEFORE plugin hooks so plan mode is the highest-priority
+    enforcement; plugins cannot accidentally bypass it.
+    """
 
     def _wrap_one(fn):
         if not callable(fn) or getattr(fn, "_hook_wrapped", False):
@@ -57,9 +64,26 @@ def _wrap_tools_with_hooks(tools: list) -> list:
         @functools.wraps(fn)
         async def wrapper(**kwargs):
             tool_name = fn.__name__
+            # Plan-mode gate — fires before any other logic so a mutating
+            # tool never reaches the permission layer or the actual executor.
+            if tool_name in _PLAN_MODE_BLOCKED_TOOLS:
+                try:
+                    from aru.runtime import get_ctx
+                    session = getattr(get_ctx(), "session", None)
+                except (LookupError, AttributeError):
+                    session = None
+                if session is not None and getattr(session, "plan_mode", False):
+                    return (
+                        f"BLOCKED: plan mode is active. Mutating tools "
+                        f"(edit/write/bash/delegate_task) are blocked until the "
+                        f"user approves the plan. Finish writing the plan as "
+                        f"your next assistant message, then call "
+                        f"exit_plan_mode(plan=<full plan text>) to request "
+                        f"approval. Do NOT retry {tool_name}."
+                    )
             # Before hook — plugins can mutate args or raise PermissionError to block
             try:
-                before_data = await _fire("tool.execute.before", {
+                before_data = await _fire_hook("tool.execute.before", {
                     "tool_name": tool_name,
                     "args": kwargs,
                 })
@@ -74,7 +98,7 @@ def _wrap_tools_with_hooks(tools: list) -> list:
                 result = fn(**kwargs)
 
             # After hook — plugins can mutate the result
-            after_data = await _fire("tool.execute.after", {
+            after_data = await _fire_hook("tool.execute.after", {
                 "tool_name": tool_name,
                 "args": kwargs,
                 "result": result,
@@ -87,58 +111,21 @@ 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]:
+async 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", {
+    data = await _fire_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", {
+    data = await _fire_hook("chat.params", {
         "model": model_ref,
         "max_tokens": max_tokens,
         "temperature": None,  # let plugin set if desired
@@ -149,7 +136,7 @@ def _apply_chat_hooks(instructions: str, model_ref: str, agent_name: str,
     return instructions, model_ref, max_tokens
 
 
-def create_agent_from_spec(
+async def create_agent_from_spec(
     spec: AgentSpec,
     session: Session | None = None,
     model_ref: str | None = None,
@@ -178,7 +165,7 @@ def create_agent_from_spec(
     tools = _wrap_tools_with_hooks(spec.tools_factory())
     instructions = _build_instructions(spec.role, extra_instructions)
 
-    instructions, resolved_model, max_tokens = _apply_chat_hooks(
+    instructions, resolved_model, max_tokens = await _apply_chat_hooks(
         instructions, resolved_model, spec.name, max_tokens=spec.max_tokens,
     )
 
@@ -192,7 +179,7 @@ def create_agent_from_spec(
     )
 
 
-def create_general_agent(
+async def create_general_agent(
     session: Session,
     config: AgentConfig | None = None,
     model_override: str | None = None,
@@ -202,7 +189,7 @@ def create_general_agent(
     extra = config.get_extra_instructions() if config else ""
     if env_context:
         extra = f"{extra}\n\n{env_context}" if extra else env_context
-    return create_agent_from_spec(
+    return await create_agent_from_spec(
         AGENTS["build"],
         session,
         model_ref=model_override or session.model_ref,
@@ -210,13 +197,13 @@ def create_general_agent(
     )
 
 
-def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
-                                  config: AgentConfig | None = None,
-                                  env_context: str = ""):
+async def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
+                                        config: AgentConfig | None = None,
+                                        env_context: str = ""):
     """Create an Agno Agent from a CustomAgent definition."""
     from agno.agent import Agent
     from aru.agents.base import BASE_INSTRUCTIONS
-    from aru.tools.codebase import resolve_tools
+    from aru.tools.registry import resolve_tools
 
     model_ref = agent_def.model or session.model_ref
     tools = _wrap_tools_with_hooks(resolve_tools(agent_def.tools))
@@ -230,7 +217,7 @@ def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
     instructions = "\n\n".join(parts)
 
     # Apply chat hooks (system.transform + params)
-    instructions, model_ref, max_tokens = _apply_chat_hooks(
+    instructions, model_ref, max_tokens = await _apply_chat_hooks(
         instructions, model_ref, agent_def.name, max_tokens=8192,
     )
 

{aru_code-0.26.1 → aru_code-0.28.0}/aru/agents/base.py

@@ -283,12 +283,39 @@ your summary, not the raw explorer output.
 
 ## Planning
 
-For tasks requiring 3+ coordinated changes across multiple files, call \
-`enter_plan_mode(task)` BEFORE starting work. It generates a structured plan via \
-the planner agent and stores it in the session. After it returns, a PLAN ACTIVE \
-reminder will appear in your context — execute the steps in order.
-
-For simple tasks (1-2 file changes), execute directly without planning.
+When the user asks you to "plan", "planeje", "propose", "think through", or \
+when a task requires 3+ coordinated changes across files, your FIRST action \
+MUST be `enter_plan_mode()` — before any read or other tool call.
+
+Plan mode is a session flag that blocks mutating tools (edit_file, write_file, \
+bash, delegate_task) until the user approves. The workflow is:
+
+1. Call `enter_plan_mode()` as the very first tool call in the turn.
+2. Optionally use read-only tools (read_file, grep_search, glob_search, \
+list_directory, web_search, web_fetch) to research what the plan needs.
+3. Write the full plan as your next assistant message — structured with \
+## Goal, ## Steps (numbered), and ## Files sections.
+4. **ALWAYS END YOUR TURN BY CALLING `exit_plan_mode(plan=<full plan text>)`.** \
+This is not optional. The user only sees the approval prompt when you call \
+`exit_plan_mode` — if you write the plan as text and stop without calling it, \
+the user cannot approve and execution stalls. The runner has a safety net that \
+auto-triggers approval at turn end, but you should not rely on it; call \
+`exit_plan_mode` explicitly as the last tool call of the turn.
+5. If approved, plan mode clears and the next turn executes the steps. If \
+rejected, plan mode stays ON and the user's feedback will appear in a \
+system-reminder on the next turn — revise the plan and call `exit_plan_mode` \
+again with the revised plan.
+
+CRITICAL — plan mode is a **pre-execution gate**, NOT a post-hoc summary. \
+Do NOT call `enter_plan_mode()` after you have already made changes in the \
+turn. If you already edited files, describe what you did as normal text.
+
+If you try to call edit_file, write_file, bash, or delegate_task while in \
+plan mode, they return a "BLOCKED: plan mode is active" error. Do NOT retry \
+those tools — finish the plan and call exit_plan_mode instead.
+
+For simple tasks (1-2 file changes) where the user did NOT ask for a plan, \
+execute directly without entering plan mode.
 
 ## Plan execution
 

{aru_code-0.26.1 → aru_code-0.28.0}/aru/agents/catalog.py

@@ -32,22 +32,22 @@ class AgentSpec:
 
 
 def _build_tools() -> list:
-    from aru.tools.codebase import GENERAL_TOOLS
+    from aru.tools.registry import GENERAL_TOOLS
     return GENERAL_TOOLS
 
 
 def _plan_tools() -> list:
-    from aru.tools.codebase import PLANNER_TOOLS
+    from aru.tools.registry import PLANNER_TOOLS
     return PLANNER_TOOLS
 
 
 def _exec_tools() -> list:
-    from aru.tools.codebase import EXECUTOR_TOOLS
+    from aru.tools.registry import EXECUTOR_TOOLS
     return EXECUTOR_TOOLS
 
 
 def _explore_tools() -> list:
-    from aru.tools.codebase import EXPLORER_TOOLS
+    from aru.tools.registry import EXPLORER_TOOLS
     return EXPLORER_TOOLS
 
 

{aru_code-0.26.1 → aru_code-0.28.0}/aru/cache_patch.py

@@ -175,6 +175,26 @@ def _patch_per_call_metrics():
     After each internal API call, Agno calls this function to sum tokens
     into RunMetrics. We intercept it to snapshot the last call's tokens,
     giving us the actual context window size (comparable to OpenCode/Claude Code).
+
+    Provider semantics differ and must be normalized:
+
+    - **Anthropic** reports `input_tokens` as *non-cached* only, with
+      `cache_read_input_tokens` and `cache_creation_input_tokens` as
+      separate, non-overlapping buckets. Total prompt =
+      ``input + cache_read + cache_write``.
+    - **OpenAI-compatible** (OpenAI, Qwen/Alibaba, DeepSeek, Groq, etc.)
+      report `prompt_tokens` as the *total* prompt, with
+      `prompt_tokens_details.cached_tokens` being a *subset* of that total.
+      Total prompt = ``input`` alone; ``cache_read`` is already inside it.
+
+    Agno's adapters populate `metrics.input_tokens` from each provider's
+    native field without normalizing, so the same name means different
+    things. That would double-count cached tokens for OpenAI-style providers
+    in any formula that does ``input + cache_read``. To keep the rest of
+    Aru provider-agnostic, normalize here: subtract `cache_read` from
+    `input_tokens` whenever the provider overlaps them, so downstream code
+    can always treat `(input, cache_read, cache_write)` as non-overlapping
+    and sum them safely.
     """
     from agno.metrics import accumulate_model_metrics as _original_accumulate
 
@@ -185,10 +205,26 @@ def _patch_per_call_metrics():
         global _last_call_cache_read, _last_call_cache_write
         usage = getattr(model_response, "response_usage", None)
         if usage is not None:
-            _last_call_input_tokens = getattr(usage, "input_tokens", 0) or 0
-            _last_call_output_tokens = getattr(usage, "output_tokens", 0) or 0
-            _last_call_cache_read = getattr(usage, "cache_read_tokens", 0) or 0
-            _last_call_cache_write = getattr(usage, "cache_write_tokens", 0) or 0
+            input_tokens = getattr(usage, "input_tokens", 0) or 0
+            output_tokens = getattr(usage, "output_tokens", 0) or 0
+            cache_read = getattr(usage, "cache_read_tokens", 0) or 0
+            cache_write = getattr(usage, "cache_write_tokens", 0) or 0
+
+            # For non-Anthropic providers, `input_tokens` already includes
+            # the cached portion, so subtract it to match Anthropic's
+            # non-overlapping semantics. See docstring above.
+            try:
+                provider_name = model.get_provider() if hasattr(model, "get_provider") else ""
+            except Exception:
+                provider_name = ""
+            is_anthropic = "anthropic" in (provider_name or "").lower()
+            if not is_anthropic and cache_read and input_tokens >= cache_read:
+                input_tokens -= cache_read
+
+            _last_call_input_tokens = input_tokens
+            _last_call_output_tokens = output_tokens
+            _last_call_cache_read = cache_read
+            _last_call_cache_write = cache_write
         return _original_accumulate(model_response, model, model_type, run_metrics)
 
     _metrics_module.accumulate_model_metrics = _patched_accumulate

{aru_code-0.26.1 → aru_code-0.28.0}/aru/cli.py

@@ -136,6 +136,11 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
 
     # Load project configuration
     config = load_config()
+    ctx.config = config
+    # Populate invoke_skill's dynamic docstring so the LLM-facing schema lists
+    # the skills actually available on this machine.
+    from aru.tools.skill import _update_invoke_skill_docstring
+    _update_invoke_skill_docstring(config.skills)
     if config.agents_md:
         console.print("[dim]Loaded AGENTS.md[/dim]")
     if config.commands:
@@ -283,12 +288,24 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                         f'  <style fg="ansigray">│</style>'
                         f'  <style fg="ansigray">{ctx.mcp_loaded_msg}</style>'
                     )
+                if ctx.permission_mode == "acceptEdits":
+                    mode_part = (
+                        f'  <style fg="ansigray">│</style>'
+                        f'  <b><style fg="ansigreen">⏵⏵ auto-accept edits on</style></b>'
+                        f'  <style fg="ansigray">(shift+tab to toggle)</style>'
+                    )
+                else:
+                    mode_part = (
+                        f'  <style fg="ansigray">│</style>'
+                        f'  <style fg="ansigray">shift+tab auto-accept</style>'
+                    )
                 return HTML(
                     f'  <style fg="ansigray">{model_tb}</style>'
                     f'  <style fg="ansigray">│</style>'
                     f'  <style fg="ansigray">/help</style>'
                     f'  <style fg="ansigray">│</style>'
                     f'  <style fg="ansigray">Esc+Enter newline</style>'
+                    f'{mode_part}'
                     f'{mcp_part}'
                 )
 
@@ -390,6 +407,12 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             if choice in ("b", "v"):
                 # Remove last turn from conversation
                 msgs_removed = session.undo_last_turn()
+                # Conversation restore also reverts plan-mode state — the
+                # undone turn may have entered plan mode, and leaving the
+                # flag on would block the next turn's mutating tools.
+                if session.plan_mode:
+                    session.plan_mode = False
+                    session.clear_plan()
 
             parts = []
             if restored_files:
@@ -528,6 +551,12 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                     console.print(f"  [bold cyan]{entry.name}[/bold cyan]  [dim]{entry.description}[/dim]")
             continue
 
+        if user_input.lower() == "/plugin" or user_input.lower().startswith("/plugin "):
+            from aru.commands import handle_plugin_command
+            rest = user_input[len("/plugin"):].strip()
+            handle_plugin_command(rest)
+            continue
+
         if user_input.lower() == "/help":
             _show_help(config)
             continue
@@ -623,14 +652,14 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 env_ctx = _build_env_ctx()
                 if cmd_def.agent and cmd_def.agent in config.custom_agents:
                     agent_def = config.custom_agents[cmd_def.agent]
-                    agent = create_custom_agent_instance(agent_def, session, config, env_context=env_ctx)
+                    agent = await create_custom_agent_instance(agent_def, session, config, env_context=env_ctx)
                 elif cmd_def.agent:
                     console.print(f"[yellow]Warning: agent '{cmd_def.agent}' not found, using default[/yellow]")
-                    agent = create_general_agent(session, config, model_override=cmd_def.model, env_context=env_ctx)
+                    agent = await create_general_agent(session, config, model_override=cmd_def.model, env_context=env_ctx)
                 elif cmd_def.model:
-                    agent = create_general_agent(session, config, model_override=cmd_def.model, env_context=env_ctx)
+                    agent = await create_general_agent(session, config, model_override=cmd_def.model, env_context=env_ctx)
                 else:
-                    agent = create_general_agent(session, config, env_context=env_ctx)
+                    agent = await create_general_agent(session, config, env_context=env_ctx)
                 session.add_message("user", user_input)
                 await run_agent_capture(agent, prompt, session, images=attached_images or None)
             elif cmd_name in config.skills:
@@ -641,7 +670,7 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                     prompt = render_skill_template(skill.content, cmd_args)
                     console.print(f"[bold magenta]Running skill /{cmd_name}...[/bold magenta]")
 
-                    agent = create_general_agent(session, config, env_context=_build_env_ctx())
+                    agent = await create_general_agent(session, config, env_context=_build_env_ctx())
                     session.add_message("user", user_input)
                     await run_agent_capture(agent, prompt, session, images=attached_images or None)
             elif cmd_name in config.custom_agents:
@@ -651,7 +680,7 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 else:
                     from aru.permissions import permission_scope
                     console.print(f"[bold magenta]Running agent /{cmd_name}...[/bold magenta]")
-                    agent = create_custom_agent_instance(agent_def, session, config, env_context=_build_env_ctx())
+                    agent = await create_custom_agent_instance(agent_def, session, config, env_context=_build_env_ctx())
                     session.add_message("user", user_input)
                     with permission_scope(agent_def.permission):
                         await run_agent_capture(agent, cmd_args or user_input, session, images=attached_images or None)
@@ -677,12 +706,12 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 agent_def = config.custom_agents[agent_name]
                 from aru.permissions import permission_scope
                 console.print(f"[bold magenta]Routing to @{agent_name}...[/bold magenta]")
-                agent = create_custom_agent_instance(agent_def, session, config, env_context=_build_env_ctx())
+                agent = await create_custom_agent_instance(agent_def, session, config, env_context=_build_env_ctx())
                 session.add_message("user", user_input)
                 with permission_scope(agent_def.permission):
                     await run_agent_capture(agent, message_text, session, images=attached_images or None)
             else:
-                agent = create_general_agent(session, config, env_context=_build_env_ctx())
+                agent = await create_general_agent(session, config, env_context=_build_env_ctx())
                 session.add_message("user", user_input)
                 await run_agent_capture(agent, user_input, session, images=attached_images or None)
 
@@ -728,6 +757,10 @@ async def run_oneshot(prompt: str, print_only: bool = False, skip_permissions: b
     ctx = init_ctx(console=console, skip_permissions=skip_permissions)
 
     config = load_config()
+    ctx.config = config
+    # Populate invoke_skill's dynamic docstring (same as interactive path)
+    from aru.tools.skill import _update_invoke_skill_docstring
+    _update_invoke_skill_docstring(config.skills)
     session = Session()
     if config.default_model:
         session.model_ref = config.default_model
@@ -771,7 +804,7 @@ async def run_oneshot(prompt: str, print_only: bool = False, skip_permissions: b
         # Full mode with tools
         from aru.runner import build_env_context
         env_ctx = build_env_context(session)
-        agent = create_general_agent(session, config, env_context=env_ctx)
+        agent = await create_general_agent(session, config, env_context=env_ctx)
         session.add_message("user", prompt)
         await run_agent_capture(agent, prompt, session)