aru-code 0.27.0__tar.gz → 0.30.0__tar.gz

{aru_code-0.27.0/aru_code.egg-info → aru_code-0.30.0}/PKG-INFO

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

aru_code-0.30.0/aru/__init__.py

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

{aru_code-0.27.0 → aru_code-0.30.0}/aru/agent_factory.py

@@ -81,6 +81,32 @@ def _wrap_tools_with_hooks(tools: list) -> list:
                         f"exit_plan_mode(plan=<full plan text>) to request "
                         f"approval. Do NOT retry {tool_name}."
                     )
+            # Active-skill disallowed-tools gate — honors the `disallowed-tools`
+            # frontmatter field of the currently active skill. Mirrors the
+            # plan-mode gate pattern above; runs before plugin hooks so a skill
+            # can hard-block a tool regardless of permission/plugin state.
+            try:
+                from aru.runtime import get_ctx
+                ctx = get_ctx()
+                session = getattr(ctx, "session", None)
+                config = getattr(ctx, "config", None)
+            except (LookupError, AttributeError):
+                session = None
+                config = None
+            if session is not None and config is not None:
+                active = getattr(session, "active_skill", None)
+                skills = getattr(config, "skills", None) or {}
+                active_skill_obj = skills.get(active) if active else None
+                disallowed = getattr(active_skill_obj, "disallowed_tools", None) or []
+                if tool_name in disallowed:
+                    return (
+                        f"BLOCKED: tool `{tool_name}` is disallowed by the "
+                        f"currently active skill `{active}`. Read the skill's "
+                        f"SKILL.md for the prescribed path. Do NOT retry "
+                        f"`{tool_name}`; use the alternative the skill specifies "
+                        f"(commonly: write the output to a `.md` file via "
+                        f"`write_file` instead of using in-session state)."
+                    )
             # Before hook — plugins can mutate args or raise PermissionError to block
             try:
                 before_data = await _fire_hook("tool.execute.before", {
@@ -112,10 +138,11 @@ def _wrap_tools_with_hooks(tools: list) -> list:
 
 
 async def _apply_chat_hooks(instructions: str, model_ref: str, agent_name: str,
-                            max_tokens: int = 8192) -> tuple[str, str, int]:
+                            max_tokens: int | None = None) -> tuple[str, str, int | None]:
     """Apply chat.system.transform and chat.params hooks to agent creation params.
 
     Returns (instructions, model_ref, max_tokens) — possibly modified by plugins.
+    When max_tokens is None, providers.create_model will use the model's full cap.
     """
     # chat.system.transform — plugins can modify the system prompt
     data = await _fire_hook("chat.system.transform", {
@@ -216,9 +243,9 @@ async def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
         parts.append(extra)
     instructions = "\n\n".join(parts)
 
-    # Apply chat hooks (system.transform + params)
+    # Apply chat hooks (system.transform + params). max_tokens=None → provider cap.
     instructions, model_ref, max_tokens = await _apply_chat_hooks(
-        instructions, model_ref, agent_def.name, max_tokens=8192,
+        instructions, model_ref, agent_def.name, max_tokens=None,
     )
 
     return Agent(

{aru_code-0.27.0 → aru_code-0.30.0}/aru/agents/catalog.py

@@ -21,13 +21,18 @@ class AgentSpec:
 
     The tools_factory is a lazy callable so module load order does not force
     aru.tools.codebase to be imported before this module.
+
+    `max_tokens=None` means "use the model's full cap" (see providers.py).
+    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.
     """
 
     name: str                            # display name passed to Agno
     role: str                            # key into build_instructions(role, ...)
     mode: Literal["primary", "subagent"]
     tools_factory: Callable[[], list]    # lazy resolver — invoked at agent creation
-    max_tokens: int
+    max_tokens: int | None
     small_model: bool = False            # if True, factory uses ctx.small_model_ref
 
 
@@ -52,12 +57,15 @@ def _explore_tools() -> list:
 
 
 AGENTS: dict[str, AgentSpec] = {
+    # Primary agents default to the model's full output cap (clamped by
+    # providers.create_model). Subagents keep a tight budget so a runaway
+    # explorer can't blow through the whole turn.
     "build": AgentSpec(
         name="Aru",
         role="general",
         mode="primary",
         tools_factory=_build_tools,
-        max_tokens=8192,
+        max_tokens=None,
     ),
     "plan": AgentSpec(
         name="Planner",
@@ -71,14 +79,14 @@ AGENTS: dict[str, AgentSpec] = {
         role="executor",
         mode="primary",
         tools_factory=_exec_tools,
-        max_tokens=8192,
+        max_tokens=None,
     ),
     "explorer": AgentSpec(
         name="Explorer",
         role="explorer",
         mode="subagent",
         tools_factory=_explore_tools,
-        max_tokens=4096,
+        max_tokens=8192,
         small_model=True,
     ),
 }

{aru_code-0.27.0 → aru_code-0.30.0}/aru/cache_patch.py

@@ -1,6 +1,6 @@
 """Monkey-patch Agno's model layer to reduce token consumption.
 
-Three optimizations:
+Four optimizations:
 
 1. **Tool result pruning** (ALL providers): After each tool execution, old tool
    results in the message list are truncated to a short summary. This prevents
@@ -12,6 +12,11 @@ Three optimizations:
 3. **Per-call metrics** (ALL providers): Captures input/output tokens of the
    last API call (context window size), exposed via get_last_call_metrics().
 
+4. **Stop-reason capture** (Anthropic + OpenAI-compatible): Captures the
+   `stop_reason` / `finish_reason` from the final message of the last API call,
+   exposed via get_last_stop_reason(). Lets the runner detect `max_tokens`
+   truncation and trigger the recovery loop.
+
 These patches intercept Agno's internal loop so they work transparently
 regardless of which provider is used.
 """
@@ -33,12 +38,36 @@ _last_call_output_tokens: int = 0
 _last_call_cache_read: int = 0
 _last_call_cache_write: int = 0
 
+# Last API call stop reason (Anthropic uses "end_turn"/"tool_use"/"max_tokens"/
+# "stop_sequence"/"pause_turn"; OpenAI uses "stop"/"length"/"tool_calls").
+# We normalize "length" → "max_tokens" so callers can check a single value.
+_last_call_stop_reason: str | None = None
+
 
 def get_last_call_metrics() -> tuple[int, int, int, int]:
     """Return (input, output, cache_read, cache_write) from the most recent API call."""
     return _last_call_input_tokens, _last_call_output_tokens, _last_call_cache_read, _last_call_cache_write
 
 
+def get_last_stop_reason() -> str | None:
+    """Return the stop reason from the most recent API call, normalized.
+
+    Returns one of: `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`,
+    `pause_turn`, or None if no call has happened yet / the provider did not
+    expose one. OpenAI's `length` is mapped to `max_tokens` and `stop` to
+    `end_turn` so callers have a single vocabulary.
+    """
+    return _last_call_stop_reason
+
+
+def reset_last_stop_reason() -> None:
+    """Clear the cached stop reason — call before starting a new turn so a
+    stale value from a prior turn never leaks into the next one.
+    """
+    global _last_call_stop_reason
+    _last_call_stop_reason = None
+
+
 def _prune_tool_messages(messages):
     """Clear old tool result content using a token-budget approach.
 
@@ -97,6 +126,7 @@ def apply_cache_patch():
     _patch_tool_result_pruning()
     _patch_claude_cache_breakpoints()
     _patch_per_call_metrics()
+    _patch_stop_reason_capture()
 
 
 def _patch_tool_result_pruning():
@@ -235,3 +265,94 @@ def _patch_per_call_metrics():
         _base_module.accumulate_model_metrics = _patched_accumulate
     except (ImportError, AttributeError):
         pass
+
+
+# OpenAI "length" and Anthropic "max_tokens" mean the same thing; normalize so
+# runner logic can check a single value.
+_STOP_REASON_NORMALIZE = {
+    "length": "max_tokens",        # OpenAI
+    "stop": "end_turn",            # OpenAI
+    "tool_calls": "tool_use",      # OpenAI
+    "function_call": "tool_use",   # legacy OpenAI
+    "MAX_TOKENS": "max_tokens",    # Gemini (all-caps)
+}
+
+
+def _record_stop_reason(raw: str | None) -> None:
+    """Normalize and cache the provider's stop reason."""
+    global _last_call_stop_reason
+    if raw is None or raw == "":
+        return
+    _last_call_stop_reason = _STOP_REASON_NORMALIZE.get(raw, raw)
+
+
+def _patch_stop_reason_capture():
+    """Forward `stop_reason` from Agno's provider parsers into a module-level
+    slot readable via `get_last_stop_reason()`.
+
+    Agno's Anthropic adapter sees `response.stop_reason` (non-streaming) and
+    `response.message.stop_reason` (streaming MessageStopEvent), but discards
+    both before anything downstream can observe them. We wrap the two parsers
+    and record the value as a side effect. The OpenAI-compatible adapter
+    already exposes `response.choices[0].finish_reason`, so we hook that too
+    for completeness (Qwen, DeepSeek, Groq, OpenRouter).
+    """
+    # Anthropic (native + streaming)
+    try:
+        from agno.models.anthropic import claude as _claude_mod
+
+        _original_parse = _claude_mod.Claude._parse_provider_response
+        _original_parse_delta = _claude_mod.Claude._parse_provider_response_delta
+
+        def _patched_parse(self, response, *args, **kwargs):
+            result = _original_parse(self, response, *args, **kwargs)
+            _record_stop_reason(getattr(response, "stop_reason", None))
+            return result
+
+        def _patched_parse_delta(self, response, *args, **kwargs):
+            result = _original_parse_delta(self, response, *args, **kwargs)
+            # MessageStopEvent / ParsedBetaMessageStopEvent carry the final
+            # stop_reason on their nested `message` object.
+            msg = getattr(response, "message", None)
+            if msg is not None:
+                _record_stop_reason(getattr(msg, "stop_reason", None))
+            return result
+
+        _claude_mod.Claude._parse_provider_response = _patched_parse
+        _claude_mod.Claude._parse_provider_response_delta = _patched_parse_delta
+    except (ImportError, AttributeError):
+        pass
+
+    # OpenAI-compatible (OpenAI, Qwen/DashScope, DeepSeek, Groq, OpenRouter)
+    try:
+        from agno.models.openai import chat as _openai_chat
+
+        _original_openai_parse = _openai_chat.OpenAIChat._parse_provider_response
+
+        def _patched_openai_parse(self, response, *args, **kwargs):
+            result = _original_openai_parse(self, response, *args, **kwargs)
+            try:
+                choice = response.choices[0]
+                _record_stop_reason(getattr(choice, "finish_reason", None))
+            except (AttributeError, IndexError, TypeError):
+                pass
+            return result
+
+        _openai_chat.OpenAIChat._parse_provider_response = _patched_openai_parse
+
+        if hasattr(_openai_chat.OpenAIChat, "_parse_provider_response_delta"):
+            _original_openai_delta = _openai_chat.OpenAIChat._parse_provider_response_delta
+
+            def _patched_openai_delta(self, response, *args, **kwargs):
+                result = _original_openai_delta(self, response, *args, **kwargs)
+                try:
+                    choice = response.choices[0]
+                    # Only the final chunk sets finish_reason.
+                    _record_stop_reason(getattr(choice, "finish_reason", None))
+                except (AttributeError, IndexError, TypeError):
+                    pass
+                return result
+
+            _openai_chat.OpenAIChat._parse_provider_response_delta = _patched_openai_delta
+    except (ImportError, AttributeError):
+        pass

{aru_code-0.27.0 → aru_code-0.30.0}/aru/cli.py

@@ -15,6 +15,7 @@ import sys
 
 from rich.markdown import Markdown
 from rich.panel import Panel
+from rich.text import Text
 
 # ── Re-exports for backward compatibility ─────────────────────────────
 # Tests and external code import these from aru.cli; keep them accessible.
@@ -92,7 +93,7 @@ _logging.getLogger("agno").setLevel(_logging.WARNING)
 
 from aru.agents.planner import review_plan
 from aru.config import load_config, render_command_template, render_skill_template
-from aru.permissions import get_skip_permissions
+from aru.permissions import get_skip_permissions, set_permission_mode
 from aru.providers import (
     MODEL_ALIASES,
     list_providers,
@@ -100,6 +101,39 @@ from aru.providers import (
 )
 
 
+def _toggle_yolo_mode(ctx) -> None:
+    """Toggle YOLO (dangerously-skip-permissions) mode from the REPL.
+
+    Turning YOLO *off* is unconditional — safety is not at risk.
+    Turning YOLO *on* requires an explicit y/n confirmation with a red warning panel.
+    """
+    if ctx.permission_mode == "yolo":
+        set_permission_mode("default")
+        console.print("[bold green]✔ YOLO disabled — safe mode restored.[/bold green]")
+        return
+
+    warning = Text.from_markup(
+        "[bold red]⚠  DANGEROUSLY SKIP PERMISSIONS (YOLO)[/bold red]\n\n"
+        "[red]All permission prompts will be bypassed for this session, including:[/red]\n"
+        "  • Reading/writing [bold].env[/bold] files and other sensitive paths\n"
+        "  • Arbitrary shell commands ([bold]rm -rf[/bold], package installs, network calls)\n"
+        "  • Edits outside the working directory\n"
+        "  • All sub-agents delegated during this session\n\n"
+        "[dim]Toggle off anytime with /yolo or shift+tab.[/dim]"
+    )
+    console.print(Panel(
+        warning,
+        title="[bold red]Enable YOLO mode?[/bold red]",
+        border_style="red",
+        padding=(1, 2),
+    ))
+    if ask_yes_no("Confirm enabling YOLO mode"):
+        set_permission_mode("yolo")
+        console.print("[bold red]🔥 YOLO MODE ACTIVE — all permissions bypassed.[/bold red]")
+    else:
+        console.print("[dim]Cancelled. Remaining in safe mode.[/dim]")
+
+
 # ── Main REPL ──────────────────────────────────────────────────────────
 
 async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
@@ -136,6 +170,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,7 +322,13 @@ 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":
+                if ctx.permission_mode == "yolo":
+                    mode_part = (
+                        f'  <style fg="ansigray">│</style>'
+                        f'  <b><style fg="ansired">🔥 YOLO — permissions bypassed</style></b>'
+                        f'  <style fg="ansigray">(/yolo to toggle)</style>'
+                    )
+                elif ctx.permission_mode == "acceptEdits":
                     mode_part = (
                         f'  <style fg="ansigray">│</style>'
                         f'  <b><style fg="ansigreen">⏵⏵ auto-accept edits on</style></b>'
@@ -546,6 +591,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
@@ -559,6 +610,10 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             ))
             continue
 
+        if user_input.lower() in ("/yolo", "/unsafe"):
+            _toggle_yolo_mode(ctx)
+            continue
+
         # Begin a new checkpoint turn for undo support
         _turn_counter += 1
         ctx.checkpoint_manager.begin_turn(_turn_counter)
@@ -656,7 +711,13 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 if not skill.user_invocable:
                     console.print(f"[yellow]Skill '{cmd_name}' is not user-invocable[/yellow]")
                 else:
+                    session.active_skill = cmd_name
                     prompt = render_skill_template(skill.content, cmd_args)
+                    # Record so the skill body survives compaction — mirror of
+                    # claude-code's addInvokedSkill. Store the rendered content
+                    # (post-argument substitution) so post-compact restoration
+                    # matches what the model initially read.
+                    session.record_invoked_skill(cmd_name, prompt, skill.source_path)
                     console.print(f"[bold magenta]Running skill /{cmd_name}...[/bold magenta]")
 
                     agent = await create_general_agent(session, config, env_context=_build_env_ctx())
@@ -746,6 +807,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
@@ -776,7 +841,7 @@ async def run_oneshot(prompt: str, print_only: bool = False, skip_permissions: b
 
         agent = Agent(
             name="Aru",
-            model=create_model(session.model_ref, max_tokens=8192),
+            model=create_model(session.model_ref),  # None → provider cap
             tools=[],
             instructions=build_instructions("general", extra_instructions),
             markdown=True,

aru_code-0.30.0/aru/commands.py

@@ -0,0 +1,245 @@
+"""Slash command definitions, help display, shell execution, and user prompts."""
+
+from __future__ import annotations
+
+import subprocess
+import os
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+from aru.display import console
+
+SLASH_COMMANDS = [
+    ("/help", "Show help and available commands", "/help"),
+    ("/plan", "Create an implementation plan", "/plan <task>"),
+    ("/model", "Switch model/provider", "/model [provider/model]"),
+    ("/sessions", "List recent sessions", "/sessions"),
+    ("/commands", "List custom commands", "/commands"),
+    ("/skills", "List available skills", "/skills"),
+    ("/agents", "List custom agents", "/agents"),
+    ("/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"),
+    ("/cost", "Show detailed token usage and cost", "/cost"),
+    ("/yolo", "Toggle DANGEROUSLY skip all permissions (YOLO mode)", "/yolo"),
+    ("/quit", "Exit aru", "/quit"),
+]
+
+
+def run_shell(command: str):
+    """Run a shell command directly, streaming output to the terminal."""
+    console.print()
+    console.print(Panel(
+        Syntax(command, "bash", theme="monokai"),
+        title="[bold]Shell[/bold]",
+        border_style="dim",
+        expand=False,
+    ))
+    try:
+        process = subprocess.Popen(
+            command,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            cwd=os.getcwd(),
+            bufsize=1,
+        )
+        for line in process.stdout:
+            console.print(Text(line.rstrip()))
+        process.wait()
+        if process.returncode != 0:
+            console.print(f"[red]Exit code: {process.returncode}[/red]")
+    except KeyboardInterrupt:
+        process.kill()
+        console.print("\n[yellow]Interrupted.[/yellow]")
+    except Exception as e:
+        from rich.markup import escape
+        console.print(f"[red]Error: {escape(str(e))}[/red]")
+    console.print()
+
+
+def ask_yes_no(prompt: str) -> bool:
+    """Ask the user a yes/no question."""
+    try:
+        answer = console.input(f"[bold yellow]{prompt} (y/n):[/bold yellow] ").strip().lower()
+        return answer in ("y", "yes", "s", "sim")
+    except (EOFError, KeyboardInterrupt):
+        return False
+
+
+def handle_plugin_command(args: str) -> None:
+    """Handle /plugin <subcommand> [args] — install/list/remove/update/info."""
+    from rich.table import Table
+    from rich.markup import escape
+
+    parts = args.strip().split(None, 2)
+    if not parts:
+        _show_plugin_help()
+        return
+
+    subcmd = parts[0].lower()
+
+    if subcmd == "list":
+        from aru.plugin_cache import list_installed
+        entries = list_installed()
+        if not entries:
+            console.print("[dim]No plugins installed. Use /plugin install <spec> to add one.[/dim]")
+            return
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Name", style="cyan")
+        table.add_column("Version", style="green")
+        table.add_column("Source")
+        table.add_column("Spec", style="dim")
+        for e in entries:
+            table.add_row(e.id, e.version or "-", e.source, e.spec)
+        console.print(table)
+        return
+
+    if subcmd == "install":
+        if len(parts) < 2:
+            console.print("[yellow]Usage: /plugin install <spec> [name][/yellow]")
+            return
+        spec = parts[1]
+        name = parts[2] if len(parts) >= 3 else None
+        from aru.plugin_cache import install
+        console.print(f"[dim]Installing {escape(spec)}...[/dim]")
+        result = install(spec, name=name)
+        if not result.ok:
+            console.print(f"[red]Install failed: {escape(result.error or 'unknown error')}[/red]")
+            return
+        provides = result.provides
+        provides_str = ", ".join(f"{c} {k}" for k, c in provides.items()) or "no resources"
+        console.print(
+            f"[green]Installed {escape(result.name or '')}"
+            f"{f'@{result.version}' if result.version else ''}[/green] "
+            f"([dim]{result.state}[/dim]) -> {escape(str(result.target))}"
+        )
+        console.print(f"[dim]Provides: {provides_str}[/dim]")
+        console.print(
+            "[dim]Discovery refreshes on next aru restart. "
+            "Skills/agents/tools from the plugin will then be available.[/dim]"
+        )
+        return
+
+    if subcmd == "remove":
+        if len(parts) < 2:
+            console.print("[yellow]Usage: /plugin remove <name>[/yellow]")
+            return
+        name = parts[1]
+        from aru.plugin_cache import remove
+        if remove(name):
+            console.print(f"[green]Removed plugin: {escape(name)}[/green]")
+        else:
+            console.print(f"[yellow]Plugin not found: {escape(name)}[/yellow]")
+        return
+
+    if subcmd == "update":
+        if len(parts) < 2:
+            console.print("[yellow]Usage: /plugin update <name>[/yellow]")
+            return
+        name = parts[1]
+        from aru.plugin_cache import update
+        console.print(f"[dim]Updating {escape(name)}...[/dim]")
+        result = update(name)
+        if not result.ok:
+            console.print(f"[red]Update failed: {escape(result.error or 'unknown error')}[/red]")
+            return
+        console.print(
+            f"[green]Updated {escape(result.name or '')}"
+            f"{f'@{result.version}' if result.version else ''}[/green] "
+            f"([dim]{result.state}[/dim])"
+        )
+        return
+
+    if subcmd == "info":
+        if len(parts) < 2:
+            console.print("[yellow]Usage: /plugin info <name>[/yellow]")
+            return
+        name = parts[1]
+        from aru.plugin_cache import list_installed, read_manifest
+        from pathlib import Path
+        entries = {e.id: e for e in list_installed()}
+        entry = entries.get(name)
+        if entry is None:
+            console.print(f"[yellow]Plugin not found: {escape(name)}[/yellow]")
+            return
+        manifest = read_manifest(Path(entry.target))
+        console.print(f"[bold cyan]{escape(entry.id)}[/bold cyan]")
+        console.print(f"  [dim]version:[/dim]     {entry.version or '-'}")
+        console.print(f"  [dim]source:[/dim]      {entry.source}")
+        console.print(f"  [dim]spec:[/dim]        {escape(entry.spec)}")
+        console.print(f"  [dim]target:[/dim]      {escape(entry.target)}")
+        console.print(f"  [dim]fingerprint:[/dim] {entry.fingerprint}")
+        console.print(f"  [dim]first_time:[/dim]  {entry.first_time}")
+        console.print(f"  [dim]last_time:[/dim]   {entry.last_time}")
+        if manifest:
+            desc = manifest.get("description")
+            if desc:
+                console.print(f"  [dim]description:[/dim] {escape(str(desc))}")
+            engines = manifest.get("engines") or {}
+            if isinstance(engines, dict) and engines.get("aru"):
+                console.print(f"  [dim]engines.aru:[/dim] {escape(str(engines['aru']))}")
+        return
+
+    _show_plugin_help()
+
+
+def _show_plugin_help() -> None:
+    """Print /plugin command usage."""
+    from rich.table import Table
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    table.add_column("Subcommand", style="cyan")
+    table.add_column("Description", style="dim")
+    table.add_row("/plugin install <spec> [name]", "Install a plugin from git or local path")
+    table.add_row("/plugin list", "List installed plugins")
+    table.add_row("/plugin remove <name>", "Uninstall a plugin")
+    table.add_row("/plugin update <name>", "Update a plugin (git pull)")
+    table.add_row("/plugin info <name>", "Show plugin metadata")
+    console.print(table)
+    console.print()
+    console.print("[dim]Spec formats:[/dim]")
+    console.print("[dim]  github:user/repo            — shorthand for GitHub[/dim]")
+    console.print("[dim]  github:user/repo@v1.0.0     — pin to tag/branch[/dim]")
+    console.print("[dim]  git+https://host/path.git   — any git URL[/dim]")
+    console.print("[dim]  file:///abs/path  or ./rel  — local directory[/dim]")
+
+
+def _show_help(config) -> None:
+    """Display help with available commands."""
+    from rich.table import Table
+
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    table.add_column("Command", style="cyan")
+    table.add_column("Description", style="dim")
+
+    table.add_row("/plan <task>", "Create detailed implementation plan")
+    table.add_row("/model [provider/model]", "Switch models (e.g., ollama/llama3.1, openai/gpt-4o)")
+    table.add_row("/sessions", "List recent sessions")
+    table.add_row("/commands", "List custom commands")
+    table.add_row("/skills", "List available skills")
+    table.add_row("/agents", "List custom agents")
+    table.add_row("/mcp", "List loaded MCP tools")
+    table.add_row("/plugin <subcmd>", "Manage plugins (install/list/remove/update/info)")
+    table.add_row("/undo", "Undo last turn (restore files and/or conversation)")
+    table.add_row("/help", "Show this help")
+    table.add_row("/quit", "Exit aru")
+    table.add_row("! <cmd>", "Run shell command")
+
+    if config and config.commands:
+        table.add_row("", "")
+        for name, cmd_def in config.commands.items():
+            table.add_row(f"/{name}", cmd_def.description)
+
+    if config and config.custom_agents:
+        primary = {k: v for k, v in config.custom_agents.items() if v.mode == "primary"}
+        if primary:
+            table.add_row("", "")
+            for name, agent_def in primary.items():
+                table.add_row(f"/{name}", f"[agent] {agent_def.description}")
+
+    console.print(table)
+    console.print()