aru-code 0.32.0__tar.gz → 0.33.0__tar.gz

{aru_code-0.32.0 → aru_code-0.33.0}/PKG-INFO

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

aru_code-0.33.0/aru/__init__.py

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

{aru_code-0.32.0 → aru_code-0.33.0}/aru/agent_factory.py

@@ -150,7 +150,15 @@ async def create_agent_from_spec(
         resolved_model = model_ref or session.model_ref
 
     tools = _wrap_tools_with_hooks(spec.tools_factory())
-    instructions = _build_instructions(spec.role, extra_instructions)
+    # Merge spec-level extra instructions (static, agent-specific policy like
+    # "you are read-only, never call write tools") with caller-provided extras
+    # (dynamic, session-specific context like cwd or AGENTS.md). Spec text
+    # comes first so the agent's baseline policy is established before any
+    # session-specific text that might try to override it.
+    combined_extra = "\n\n".join(
+        part for part in (spec.extra_instructions, extra_instructions) if part
+    )
+    instructions = _build_instructions(spec.role, combined_extra)
 
     instructions, resolved_model, max_tokens = await _apply_chat_hooks(
         instructions, resolved_model, spec.name, max_tokens=spec.max_tokens,

{aru_code-0.32.0 → aru_code-0.33.0}/aru/agents/base.py

@@ -374,11 +374,101 @@ Complete the search request efficiently and report your findings clearly.\
 """
 
 
+VERIFIER_ROLE = """\
+You are a verification sub-agent. Your sole job is to review a recent batch
+of edits for correctness and report issues.
+
+=== CRITICAL: READ-ONLY MODE — NO FILE MODIFICATIONS ===
+You are STRICTLY PROHIBITED from creating, editing, deleting, or moving
+files. You do not have access to edit tools; attempts will fail. No
+state-changing bash commands (no git add/commit, no npm/pip install, no
+mkdir/touch/rm/cp/mv).
+
+Your workflow:
+1. Read each file mentioned in the task using `read_file` or `read_files`
+2. Search for call sites / references to changed APIs using `grep_search`
+3. Skim related tests using `glob_search` + `read_file`
+4. Report findings in this structure:
+   - Inconsistencies found (with file:line refs)
+   - Missing follow-up edits (call sites not updated, etc.)
+   - Suspicious patterns worth the caller's attention (even if uncertain)
+   - What looks correct (brief — don't pad the report)
+
+Be concise. Skip nitpicks (formatting, naming preferences). Focus on
+bugs, broken contracts, or outdated call sites the caller likely missed.
+
+Return ONE final message. The caller is not able to ask follow-ups
+without a resume — include everything they need to act.\
+"""
+
+
+REVIEWER_ROLE = """\
+You are a code-review sub-agent. Review the files mentioned in the task
+against common quality heuristics and produce actionable findings.
+
+=== CRITICAL: READ-ONLY MODE — NO FILE MODIFICATIONS ===
+You may only read and search. No edit/write/delete/move operations. No
+state-changing bash.
+
+For each file covered:
+
+- Naming: are identifiers clear and consistent with the surrounding code?
+- Error handling: are edge cases covered? Any swallowed exceptions?
+- Testing: is there test coverage for the new/modified code paths?
+- Security: obvious injection, path traversal, secret exposure, unchecked
+  user input, missing auth checks?
+- Complexity: functions that should be split, duplicated logic, over-
+  engineered abstractions for simple cases?
+
+Report format:
+- One bullet per finding
+- Include file:line
+- Classify severity: (blocker) / (important) / (nit) — omit (nit) unless
+  asked for a thorough review
+- If nothing is wrong, say so plainly — do not fabricate issues
+
+Return ONE final message covering every file you looked at.\
+"""
+
+
+GUIDE_ROLE = """\
+You are the Aru user-guide sub-agent. You answer questions about how to
+use and configure Aru itself — slash commands, permission config, skills,
+plugins, tool catalog, session management.
+
+The questions are about Aru, NOT about the user's own codebase. When in
+doubt, treat the task as "explain how to do X with Aru" rather than "do X
+in the user's project".
+
+=== CRITICAL: READ-ONLY MODE — NO FILE MODIFICATIONS ===
+You may only read and search. No edit/write/delete/move operations.
+
+Authoritative sources, in priority order:
+1. `AGENTS.md` at the project root — architectural reference
+2. `docs/*.md` — user-facing documentation
+3. `aru.json` examples in the codebase — config shape
+4. Reading the code under `aru/` directly (last resort — prefer docs)
+
+Workflow:
+1. `read_file` AGENTS.md first
+2. `glob_search` + `read_file` relevant docs/*.md
+3. Search `aru.json` or permission config examples if the question is
+   configuration-related
+
+Never invent features. If the docs do not cover the topic, say so and
+suggest the closest available alternative. Cite file paths in your
+response so the user can verify.
+
+Return ONE final message.\
+"""
+
+
 def build_instructions(role: str, extra: str = "") -> str:
     """Build complete instructions for an agent role.
 
     Args:
-        role: One of 'planner', 'executor', 'general', 'explorer'.
+        role: One of 'planner', 'executor', 'general', 'explorer', 'verifier',
+            'reviewer', 'guide'.
         extra: Additional project-specific instructions (README, AGENTS.md, skills).
     """
     role_text = {
@@ -386,6 +476,9 @@ def build_instructions(role: str, extra: str = "") -> str:
         "executor": EXECUTOR_ROLE,
         "general": GENERAL_ROLE,
         "explorer": EXPLORER_ROLE,
+        "verifier": VERIFIER_ROLE,
+        "reviewer": REVIEWER_ROLE,
+        "guide": GUIDE_ROLE,
     }[role]
 
     parts = [role_text, BASE_INSTRUCTIONS]

{aru_code-0.32.0 → aru_code-0.33.0}/aru/agents/catalog.py

@@ -26,6 +26,15 @@ class AgentSpec:
     An explicit int caps the agent below that ceiling — providers.py always
     clamps the final value to min(requested, model_cap) so specs can never
     ask for more than the model supports.
+
+    `description` is the LLM-facing summary rendered into `delegate_task`'s
+    docstring. Only subagent specs need a meaningful description (primary
+    agents are never picked via `agent_name`). Keep it short (1-3 sentences)
+    and directive — the model uses it to decide when this agent fits.
+
+    `extra_instructions` is appended to the base role instructions when the
+    agent is built. Use it for agent-specific policy ("you are read-only,
+    never call write tools") that shouldn't leak into other roles.
     """
 
     name: str                            # display name passed to Agno
@@ -35,6 +44,8 @@ class AgentSpec:
     max_tokens: int | None
     small_model: bool = False            # if True, factory uses ctx.small_model_ref
     use_reasoning: bool = True           # False skips thinking params (e.g. explorer)
+    description: str = ""                # LLM-facing summary for `delegate_task` docstring
+    extra_instructions: str = ""         # appended to base role instructions on build
 
 
 def _build_tools() -> list:
@@ -90,5 +101,57 @@ AGENTS: dict[str, AgentSpec] = {
         max_tokens=8192,
         small_model=True,
         use_reasoning=False,  # fast read-only subagent — no thinking overhead
+        description=(
+            "Fast read-only codebase exploration agent. Use for searching "
+            "files, finding patterns, reading code, and understanding "
+            "structure. Specify thoroughness in the task text: \"quick\" "
+            "(basic searches), \"medium\" (moderate exploration), or "
+            "\"very thorough\" (comprehensive analysis)."
+        ),
+    ),
+    "verification": AgentSpec(
+        name="Verifier",
+        role="verifier",
+        mode="subagent",
+        tools_factory=_explore_tools,  # read-only
+        max_tokens=4096,
+        small_model=True,
+        use_reasoning=False,
+        description=(
+            "Double-check a recent batch of edits for correctness. Reads "
+            "changed files, searches for call sites, reports inconsistencies "
+            "and missing follow-up edits. Read-only — never edits. Use after "
+            "non-trivial multi-file edits to catch issues before the user sees them."
+        ),
+    ),
+    "reviewer": AgentSpec(
+        name="Reviewer",
+        role="reviewer",
+        mode="subagent",
+        tools_factory=_explore_tools,  # read-only
+        max_tokens=4096,
+        small_model=True,
+        use_reasoning=False,
+        description=(
+            "Code review against naming, error handling, test coverage, and "
+            "security heuristics. Read-only; produces bulleted findings with "
+            "file:line refs and severity tags. Use when you want a second "
+            "pair of eyes before finalising changes."
+        ),
+    ),
+    "guide": AgentSpec(
+        name="Guide",
+        role="guide",
+        mode="subagent",
+        tools_factory=_explore_tools,  # read-only
+        max_tokens=4096,
+        small_model=True,
+        use_reasoning=False,
+        description=(
+            "Answer questions about using Aru itself — slash commands, "
+            "permission config, skills, plugins, tool catalog. Reads "
+            "AGENTS.md and docs/ to ground answers. Use when the user's "
+            "question is about Aru's features, not their own codebase."
+        ),
     ),
 }

{aru_code-0.32.0 → aru_code-0.33.0}/aru/cli.py

@@ -634,6 +634,25 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             ))
             continue
 
+        if user_input.lower() == "/subagents":
+            from aru.commands import handle_subagents_command
+            handle_subagents_command(session)
+            continue
+
+        if user_input.lower().startswith("/subagent "):
+            from aru.commands import handle_subagent_detail_command
+            handle_subagent_detail_command(session, user_input[10:].strip())
+            continue
+        if user_input.lower() == "/subagent":
+            from aru.commands import handle_subagent_detail_command
+            handle_subagent_detail_command(session, "")
+            continue
+
+        if user_input.lower() == "/bg":
+            from aru.commands import handle_background_command
+            handle_background_command(session)
+            continue
+
         if user_input.lower() in ("/yolo", "/unsafe"):
             _toggle_yolo_mode(ctx)
             continue
@@ -776,6 +795,16 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                         console.print(f"[dim]Agents: {', '.join(f'/{k}' for k in primary)}[/dim]")
 
         else:
+            # Drain any background sub-agent notifications that completed
+            # during the previous turn. Prepend them to the user prompt so
+            # the model sees the results before processing the new message.
+            # Parity with claude-code's <task-notification> routing.
+            from aru.tools.delegate import drain_pending_notifications
+            bg_notifications = drain_pending_notifications(session)
+            effective_prompt = user_input
+            if bg_notifications:
+                effective_prompt = f"{bg_notifications}\n\n{user_input}"
+
             # Check for @agent mention anywhere in message
             agent_mention = _extract_agent_mention(user_input, config.custom_agents)
             if agent_mention:
@@ -785,12 +814,14 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 console.print(f"[bold magenta]Routing to @{agent_name}...[/bold magenta]")
                 agent = await create_custom_agent_instance(agent_def, session, config, env_context=_build_env_ctx())
                 session.add_message("user", user_input)
+                if bg_notifications:
+                    message_text = f"{bg_notifications}\n\n{message_text}"
                 with permission_scope(agent_def.permission):
                     await run_agent_capture(agent, message_text, session, images=attached_images or None)
             else:
                 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)
+                await run_agent_capture(agent, effective_prompt, session, images=attached_images or None)
 
         # Show token usage and auto-save
         if session.token_summary:

{aru_code-0.32.0 → aru_code-0.33.0}/aru/commands.py

@@ -21,6 +21,9 @@ SLASH_COMMANDS = [
     ("/commands", "List custom commands", "/commands"),
     ("/skills", "List available skills", "/skills"),
     ("/agents", "List custom agents", "/agents"),
+    ("/subagents", "Show sub-agent invocation tree for this session", "/subagents"),
+    ("/subagent", "Show detailed trace for a sub-agent by task_id", "/subagent <task_id>"),
+    ("/bg", "List background sub-agent tasks (pending notifications)", "/bg"),
     ("/mcp", "List loaded MCP tools", "/mcp"),
     ("/plugin", "Manage cached plugins (install/list/remove/update)", "/plugin <subcommand>"),
     ("/undo", "Undo last turn — restore files and/or conversation", "/undo"),
@@ -72,6 +75,135 @@ def ask_yes_no(prompt: str) -> bool:
         return False
 
 
+def handle_subagents_command(session) -> None:
+    """Render the session's sub-agent trace tree (`/subagents`).
+
+    Flat tabular output — task_id, agent name, duration, tokens in/out,
+    status, task preview. Nested delegations indent under their parent.
+    """
+    from rich.table import Table
+
+    traces = list(getattr(session, "subagent_traces", []) or [])
+    if not traces:
+        console.print("[dim]No sub-agents invoked in this session.[/dim]")
+        return
+
+    children_of: dict[str | None, list] = {}
+    for t in traces:
+        children_of.setdefault(t.parent_id, []).append(t)
+
+    status_style = {
+        "running": "yellow",
+        "completed": "green",
+        "cancelled": "dim",
+        "error": "red",
+    }
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Agent", no_wrap=True)
+    table.add_column("Duration", justify="right", no_wrap=True)
+    table.add_column("Tokens (in/out)", justify="right", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Task")
+
+    def _emit(node, depth: int = 0):
+        indent = "  " * depth + ("└ " if depth else "")
+        task_id = node.task_id[:12]
+        dur = f"{node.duration:.1f}s" if node.ended_at else "…"
+        tokens = f"{node.tokens_in:,}/{node.tokens_out:,}"
+        status = f"[{status_style.get(node.status, 'white')}]{node.status}[/]"
+        task_preview = (node.task[:60] + "…") if len(node.task) > 60 else node.task
+        table.add_row(
+            f"{indent}{task_id}", node.agent_name, dur, tokens, status, task_preview
+        )
+        for child in children_of.get(node.task_id, []):
+            _emit(child, depth + 1)
+
+    trace_ids = {t.task_id for t in traces}
+    roots = [t for t in traces if t.parent_id not in trace_ids]
+    for root in roots:
+        _emit(root)
+
+    console.print(
+        Panel(table, title=f"Sub-agent invocations ({len(traces)})",
+              border_style="cyan", padding=(0, 1))
+    )
+
+
+def handle_subagent_detail_command(session, task_id: str) -> None:
+    """Print detailed trace for one sub-agent by task_id prefix."""
+    task_id = task_id.strip()
+    if not task_id:
+        console.print("[yellow]Usage: /subagent <task_id>[/yellow]")
+        return
+
+    traces = list(getattr(session, "subagent_traces", []) or [])
+    matches = [t for t in traces if t.task_id == task_id or t.task_id.startswith(task_id)]
+    if not matches:
+        console.print(f"[yellow]No sub-agent found with task_id starting with '{task_id}'[/yellow]")
+        return
+    if len(matches) > 1:
+        console.print(
+            f"[yellow]Ambiguous: {len(matches)} traces match '{task_id}'. Showing the first.[/yellow]"
+        )
+
+    trace = matches[0]
+    lines: list[str] = [
+        f"[bold]task_id:[/bold]     {trace.task_id}",
+        f"[bold]agent:[/bold]       {trace.agent_name}",
+        f"[bold]status:[/bold]      {trace.status}",
+        f"[bold]parent:[/bold]      {trace.parent_id or '(primary)'}",
+    ]
+    if trace.ended_at:
+        lines.append(f"[bold]duration:[/bold]    {trace.duration:.2f}s")
+    else:
+        lines.append("[bold]duration:[/bold]    (running)")
+    lines.extend([
+        f"[bold]tokens:[/bold]      in={trace.tokens_in:,}  out={trace.tokens_out:,}",
+        "",
+        "[bold]task:[/bold]",
+        f"  {trace.task}",
+        "",
+    ])
+    if trace.tool_calls:
+        lines.append(f"[bold]tool calls ({len(trace.tool_calls)}):[/bold]")
+        for i, call in enumerate(trace.tool_calls, 1):
+            args = call.get("args_preview", "")
+            dur = call.get("duration", 0)
+            lines.append(f"  {i}. [cyan]{call.get('tool', '?')}[/cyan] ({dur}s)  {args}")
+        lines.append("")
+    if trace.result:
+        lines.append("[bold]result preview:[/bold]")
+        lines.append("  " + trace.result.replace("\n", "\n  "))
+
+    console.print(Panel("\n".join(lines), title="Sub-agent trace", border_style="cyan", padding=(1, 2)))
+
+
+def handle_background_command(session) -> None:
+    """List pending background-task notifications (`/bg`).
+
+    Each entry is a sub-agent spawned with `run_in_background=True` that
+    has already completed but hasn't been surfaced to the primary agent
+    yet. Notifications are drained automatically on the next turn — this
+    command just lets the user see what's queued.
+    """
+    pending = list(getattr(session, "pending_notifications", []) or [])
+    if not pending:
+        console.print("[dim]No pending background tasks.[/dim]")
+        return
+    for n in pending:
+        tid = n.get("task_id", "?")
+        result = n.get("result", "")
+        preview = (result[:200] + "…") if len(result) > 200 else result
+        console.print(Panel(
+            preview,
+            title=f"[bold]Background task: {tid}[/bold]",
+            border_style="cyan",
+            padding=(0, 1),
+        ))
+
+
 def handle_plugin_command(args: str) -> None:
     """Handle /plugin <subcommand> [args] — install/list/remove/update/info."""
     from rich.table import Table