aru-code 0.9.0__tar.gz → 0.10.1__tar.gz

{aru_code-0.9.0/aru_code.egg-info → aru_code-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.9.0
+Version: 0.10.1
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -69,7 +69,7 @@ An intelligent coding assistant for the terminal, powered by LLMs and [Agno](htt
 pip install aru-code
 ```
 
-> **Requirements:** Python 3.13+
+> **Requirements:** Python 3.11+
 
 ### 2. Configure the API Key
 
@@ -340,7 +340,7 @@ All resolved content is combined and appended to the agent's system prompt along
         └── SKILL.md
 ```
 
-Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
+Command files support frontmatter with `description`, `agent`, and `model` fields, plus OpenCode-style argument placeholders: `$ARGUMENTS` (full string), `$1`/`$2` (positional), and `$ARGUMENTS[N]` (0-indexed).
 
 ### Custom Agents
 
@@ -374,11 +374,22 @@ performance, and readability. Do NOT modify files.
 
 #### Invocation
 
+There are three ways to invoke a custom agent:
+
+| Method | Syntax | When to use |
+|--------|--------|-------------|
+| **Slash command** | `/reviewer src/auth.py` | Directly invoke a `primary` agent by name |
+| **@mention** | `@reviewer check this function` | Mention an agent anywhere in your message |
+| **delegate_task** | Automatic (subagents only) | Subagent names and descriptions are injected into the `delegate_task` tool description, so the LLM sees them and can call `delegate_task(task="...", agent="name")` on its own when it judges the task fits |
+
 ```
-aru> /reviewer src/auth.py        # invoke by slash + filename (without .md)
-aru> /agents                       # list all custom agents
+aru> /reviewer src/auth.py           # slash command (primary agents)
+aru> @reviewer check the auth module  # @mention (primary or subagent)
+aru> /agents                          # list all custom agents
 ```
 
+> **Note:** Slash commands (`/name`) are only available for `primary` agents — subagents are blocked with a warning. `@mention` works for any agent regardless of mode. Subagents can be invoked in two ways: automatically by the LLM via `delegate_task`, or manually by the user via `@name`.
+
 #### Discovery paths
 
 Agents are discovered from multiple locations (later overrides earlier):

{aru_code-0.9.0 → aru_code-0.10.1}/README.md

@@ -22,7 +22,7 @@ An intelligent coding assistant for the terminal, powered by LLMs and [Agno](htt
 pip install aru-code
 ```
 
-> **Requirements:** Python 3.13+
+> **Requirements:** Python 3.11+
 
 ### 2. Configure the API Key
 
@@ -293,7 +293,7 @@ All resolved content is combined and appended to the agent's system prompt along
         └── SKILL.md
 ```
 
-Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
+Command files support frontmatter with `description`, `agent`, and `model` fields, plus OpenCode-style argument placeholders: `$ARGUMENTS` (full string), `$1`/`$2` (positional), and `$ARGUMENTS[N]` (0-indexed).
 
 ### Custom Agents
 
@@ -327,11 +327,22 @@ performance, and readability. Do NOT modify files.
 
 #### Invocation
 
+There are three ways to invoke a custom agent:
+
+| Method | Syntax | When to use |
+|--------|--------|-------------|
+| **Slash command** | `/reviewer src/auth.py` | Directly invoke a `primary` agent by name |
+| **@mention** | `@reviewer check this function` | Mention an agent anywhere in your message |
+| **delegate_task** | Automatic (subagents only) | Subagent names and descriptions are injected into the `delegate_task` tool description, so the LLM sees them and can call `delegate_task(task="...", agent="name")` on its own when it judges the task fits |
+
 ```
-aru> /reviewer src/auth.py        # invoke by slash + filename (without .md)
-aru> /agents                       # list all custom agents
+aru> /reviewer src/auth.py           # slash command (primary agents)
+aru> @reviewer check the auth module  # @mention (primary or subagent)
+aru> /agents                          # list all custom agents
 ```
 
+> **Note:** Slash commands (`/name`) are only available for `primary` agents — subagents are blocked with a warning. `@mention` works for any agent regardless of mode. Subagents can be invoked in two ways: automatically by the LLM via `delegate_task`, or manually by the user via `@name`.
+
 #### Discovery paths
 
 Agents are discovered from multiple locations (later overrides earlier):

aru_code-0.10.1/aru/__init__.py

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

{aru_code-0.9.0 → aru_code-0.10.1}/aru/agent_factory.py

@@ -8,7 +8,11 @@ from aru.providers import create_model
 from aru.session import Session
 
 
-def create_general_agent(session: Session, config: AgentConfig | None = None):
+def create_general_agent(
+    session: Session,
+    config: AgentConfig | None = None,
+    model_override: str | None = None,
+):
     """Create the general-purpose agent."""
     from agno.agent import Agent
     from agno.compression.manager import CompressionManager
@@ -17,10 +21,11 @@ def create_general_agent(session: Session, config: AgentConfig | None = None):
     from aru.runtime import get_ctx
 
     extra = config.get_extra_instructions() if config else ""
+    model_ref = model_override or session.model_ref
 
     return Agent(
         name="Aru",
-        model=create_model(session.model_ref, max_tokens=8192),
+        model=create_model(model_ref, max_tokens=8192),
         tools=GENERAL_TOOLS,
         instructions=_build_instructions("general", extra),
         markdown=True,

{aru_code-0.9.0 → aru_code-0.10.1}/aru/cli.py

@@ -430,7 +430,16 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 prompt = render_command_template(cmd_def.template, cmd_args)
                 console.print(f"[bold magenta]Running /{cmd_name}...[/bold magenta]")
 
-                agent = create_general_agent(session, config)
+                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)
+                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)
+                elif cmd_def.model:
+                    agent = create_general_agent(session, config, model_override=cmd_def.model)
+                else:
+                    agent = create_general_agent(session, config)
                 session.add_message("user", user_input)
                 run_result = await run_agent_capture(agent, prompt, session)
                 if run_result.content:

{aru_code-0.9.0 → aru_code-0.10.1}/aru/config.py

@@ -27,6 +27,8 @@ class CustomCommand:
     description: str
     template: str
     source_path: str
+    agent: str | None = None
+    model: str | None = None
 
 
 @dataclass
@@ -325,6 +327,8 @@ def _load_commands(agents_dir: Path) -> dict[str, CustomCommand]:
             description=description,
             template=body,
             source_path=str(filepath),
+            agent=metadata.get("agent") or None,
+            model=metadata.get("model") or None,
         )
 
     return commands
@@ -518,26 +522,17 @@ def load_config(cwd: str | None = None) -> AgentConfig:
     return config
 
 
-def render_command_template(template: str, user_input: str) -> str:
-    """Render a command template with user input.
-
-    Replaces $INPUT with the user's arguments.
-    Also supports $SELECTION (empty if not provided) for future use.
-    """
-    result = template.replace("$INPUT", user_input)
-    result = result.replace("$SELECTION", "")
-    return result
-
-
-def render_skill_template(content: str, arguments: str) -> str:
-    """Render a skill template with argument substitution (agentskills.io).
+def render_template_arguments(
+    content: str, arguments: str, *, context_label: str = "Argument",
+) -> str:
+    """Render a template with $ARGUMENTS / $1 / $2 substitution.
 
     Supports:
     - $ARGUMENTS: Full argument string
     - $ARGUMENTS[N]: Nth argument (0-indexed)
     - $1, $2, ...: Nth argument (1-indexed, shell-style)
 
-    Also prepends an explicit argument context block so the agent cannot
+    Also prepends an explicit context block so the agent cannot
     miss or misread the user-supplied value.
     """
     parts = arguments.split() if arguments else []
@@ -561,7 +556,17 @@ def render_skill_template(content: str, arguments: str) -> str:
 
     # Prepend an explicit context block so the agent cannot miss the argument
     if arguments and arguments.strip():
-        header = f"> **Skill argument:** `{arguments.strip()}`\n> Use this value exactly where the skill instructions reference the argument.\n\n"
+        header = f"> **{context_label}:** `{arguments.strip()}`\n> Use this value exactly where the instructions reference the argument.\n\n"
         result = header + result
 
     return result
+
+
+def render_command_template(template: str, user_input: str) -> str:
+    """Render a command template with OpenCode-style argument substitution."""
+    return render_template_arguments(template, user_input, context_label="Command argument")
+
+
+def render_skill_template(content: str, arguments: str) -> str:
+    """Render a skill template with argument substitution (agentskills.io)."""
+    return render_template_arguments(content, arguments, context_label="Skill argument")

{aru_code-0.9.0 → aru_code-0.10.1}/aru/tools/codebase.py

@@ -1023,8 +1023,19 @@ async def delegate_task(task: str, context: str = "", agent: str = "") -> str:
 
         agent_perm = None
         custom_agent_defs = get_ctx().custom_agent_defs
-        if agent and agent in custom_agent_defs:
-            agent_def = custom_agent_defs[agent]
+        # 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_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]
@@ -1186,13 +1197,15 @@ def _update_delegate_task_docstring():
     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 of a specialized agent to use. ALWAYS prefer a specialized agent when one matches the task."""
 
     custom_agent_defs = get_ctx().custom_agent_defs
     if custom_agent_defs:
-        lines = [f"\n\n    Available specialized agents (use the agent parameter to invoke):"]
+        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:")
         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.")
         base_doc += "\n".join(lines)
 
     delegate_task.__doc__ = base_doc

{aru_code-0.9.0 → aru_code-0.10.1/aru_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.9.0
+Version: 0.10.1
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -69,7 +69,7 @@ An intelligent coding assistant for the terminal, powered by LLMs and [Agno](htt
 pip install aru-code
 ```
 
-> **Requirements:** Python 3.13+
+> **Requirements:** Python 3.11+
 
 ### 2. Configure the API Key
 
@@ -340,7 +340,7 @@ All resolved content is combined and appended to the agent's system prompt along
         └── SKILL.md
 ```
 
-Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
+Command files support frontmatter with `description`, `agent`, and `model` fields, plus OpenCode-style argument placeholders: `$ARGUMENTS` (full string), `$1`/`$2` (positional), and `$ARGUMENTS[N]` (0-indexed).
 
 ### Custom Agents
 
@@ -374,11 +374,22 @@ performance, and readability. Do NOT modify files.
 
 #### Invocation
 
+There are three ways to invoke a custom agent:
+
+| Method | Syntax | When to use |
+|--------|--------|-------------|
+| **Slash command** | `/reviewer src/auth.py` | Directly invoke a `primary` agent by name |
+| **@mention** | `@reviewer check this function` | Mention an agent anywhere in your message |
+| **delegate_task** | Automatic (subagents only) | Subagent names and descriptions are injected into the `delegate_task` tool description, so the LLM sees them and can call `delegate_task(task="...", agent="name")` on its own when it judges the task fits |
+
 ```
-aru> /reviewer src/auth.py        # invoke by slash + filename (without .md)
-aru> /agents                       # list all custom agents
+aru> /reviewer src/auth.py           # slash command (primary agents)
+aru> @reviewer check the auth module  # @mention (primary or subagent)
+aru> /agents                          # list all custom agents
 ```
 
+> **Note:** Slash commands (`/name`) are only available for `primary` agents — subagents are blocked with a warning. `@mention` works for any agent regardless of mode. Subagents can be invoked in two ways: automatically by the LLM via `delegate_task`, or manually by the user via `@name`.
+
 #### Discovery paths
 
 Agents are discovered from multiple locations (later overrides earlier):

{aru_code-0.9.0 → aru_code-0.10.1}/pyproject.toml

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

{aru_code-0.9.0 → aru_code-0.10.1}/tests/test_config.py

@@ -19,6 +19,7 @@ from aru.config import (
     _url_cache,
     render_command_template,
     render_skill_template,
+    render_template_arguments,
     load_config,
     MAX_README_CHARS,
 )
@@ -31,13 +32,27 @@ class TestDataClasses:
         cmd = CustomCommand(
             name="test",
             description="Test command",
-            template="Do $INPUT",
+            template="Do $ARGUMENTS",
             source_path="/path/to/test.md",
         )
         assert cmd.name == "test"
         assert cmd.description == "Test command"
-        assert cmd.template == "Do $INPUT"
+        assert cmd.template == "Do $ARGUMENTS"
         assert cmd.source_path == "/path/to/test.md"
+        assert cmd.agent is None
+        assert cmd.model is None
+
+    def test_custom_command_with_agent_and_model(self):
+        cmd = CustomCommand(
+            name="review",
+            description="Review code",
+            template="Review $ARGUMENTS",
+            source_path="/path/to/review.md",
+            agent="reviewer",
+            model="anthropic/claude-sonnet-4-5",
+        )
+        assert cmd.agent == "reviewer"
+        assert cmd.model == "anthropic/claude-sonnet-4-5"
 
     def test_skill_creation(self):
         skill = Skill(
@@ -198,37 +213,57 @@ class TestParseFrontmatter:
 
 
 class TestRenderCommandTemplate:
-    """Test command template rendering."""
+    """Test command template rendering with OpenCode-style arguments."""
 
-    def test_render_with_input(self):
-        template = "Execute $INPUT in the codebase"
-        result = render_command_template(template, "refactoring")
-        assert result == "Execute refactoring in the codebase"
+    def test_render_with_arguments(self):
+        result = render_command_template("Execute $ARGUMENTS in the codebase", "refactoring")
+        assert "Execute refactoring in the codebase" in result
 
-    def test_render_multiple_input_placeholders(self):
-        template = "Run $INPUT and verify $INPUT works"
-        result = render_command_template(template, "tests")
-        assert result == "Run tests and verify tests works"
+    def test_render_positional_args(self):
+        result = render_command_template("File: $1, Line: $2", "main.py 42")
+        assert "File: main.py, Line: 42" in result
 
-    def test_render_removes_selection(self):
-        template = "Process $INPUT and $SELECTION"
-        result = render_command_template(template, "data")
-        assert result == "Process data and "
+    def test_render_indexed_args(self):
+        result = render_command_template("$ARGUMENTS[0] and $ARGUMENTS[1]", "foo bar")
+        assert "foo and bar" in result
 
     def test_render_no_placeholders(self):
         template = "Just plain text"
         result = render_command_template(template, "input")
-        assert result == "Just plain text"
+        # Header is prepended but template body is unchanged
+        assert "Just plain text" in result
 
     def test_render_empty_input(self):
-        template = "Do $INPUT now"
-        result = render_command_template(template, "")
+        result = render_command_template("Do $ARGUMENTS now", "")
         assert result == "Do  now"
 
     def test_render_with_special_characters(self):
-        template = "Run $INPUT"
-        result = render_command_template(template, "pytest -v --cov")
-        assert result == "Run pytest -v --cov"
+        result = render_command_template("Run $ARGUMENTS", "pytest -v --cov")
+        assert "Run pytest -v --cov" in result
+
+    def test_render_missing_positional(self):
+        result = render_command_template("$1 and $3", "first second")
+        assert "first and " in result
+
+    def test_command_context_header(self):
+        result = render_command_template("Do $ARGUMENTS", "something")
+        assert result.startswith("> **Command argument:**")
+
+    def test_no_header_when_empty_args(self):
+        result = render_command_template("Do $ARGUMENTS", "")
+        assert not result.startswith(">")
+
+
+class TestRenderTemplateArguments:
+    """Test the shared render_template_arguments function."""
+
+    def test_custom_context_label(self):
+        result = render_template_arguments("Do $ARGUMENTS", "test", context_label="Custom label")
+        assert "> **Custom label:** `test`" in result
+
+    def test_delegates_correctly(self):
+        result = render_template_arguments("$1 + $2 = $ARGUMENTS", "a b")
+        assert "a + b = a b" in result
 
 
 class TestLoadConfig:
@@ -274,16 +309,32 @@ class TestLoadConfig:
     def test_load_config_with_commands(self, tmp_path):
         commands_dir = tmp_path / ".agents" / "commands"
         commands_dir.mkdir(parents=True)
-        
+
         cmd_file = commands_dir / "deploy.md"
-        cmd_file.write_text("---\ndescription: Deploy the app\n---\nDeploy $INPUT")
-        
+        cmd_file.write_text("---\ndescription: Deploy the app\n---\nDeploy $ARGUMENTS")
+
         config = load_config(str(tmp_path))
         assert "deploy" in config.commands
         cmd = config.commands["deploy"]
         assert cmd.name == "deploy"
         assert cmd.description == "Deploy the app"
-        assert cmd.template == "Deploy $INPUT"
+        assert cmd.template == "Deploy $ARGUMENTS"
+        assert cmd.agent is None
+        assert cmd.model is None
+
+    def test_load_config_command_with_agent_and_model(self, tmp_path):
+        commands_dir = tmp_path / ".agents" / "commands"
+        commands_dir.mkdir(parents=True)
+
+        cmd_file = commands_dir / "review.md"
+        cmd_file.write_text(
+            "---\ndescription: Review code\nagent: reviewer\nmodel: anthropic/claude-sonnet-4-5\n---\nReview $ARGUMENTS"
+        )
+
+        config = load_config(str(tmp_path))
+        cmd = config.commands["review"]
+        assert cmd.agent == "reviewer"
+        assert cmd.model == "anthropic/claude-sonnet-4-5"
 
     def test_load_config_command_without_frontmatter(self, tmp_path):
         commands_dir = tmp_path / ".agents" / "commands"
@@ -409,7 +460,7 @@ class TestLoadConfig:
 
         commands_dir = tmp_path / ".agents" / "commands"
         commands_dir.mkdir(parents=True)
-        (commands_dir / "test.md").write_text("---\ndescription: Test\n---\nRun $INPUT")
+        (commands_dir / "test.md").write_text("---\ndescription: Test\n---\nRun $ARGUMENTS")
 
         skill_dir = tmp_path / ".agents" / "skills" / "review"
         skill_dir.mkdir(parents=True)
@@ -529,7 +580,7 @@ class TestParseSkillMetadata:
 class TestRenderSkillTemplate:
     """Test render_skill_template with argument substitution."""
 
-    _HEADER = "> **Skill argument:** `{arg}`\n> Use this value exactly where the skill instructions reference the argument.\n\n"
+    _HEADER = "> **Skill argument:** `{arg}`\n> Use this value exactly where the instructions reference the argument.\n\n"
 
     def test_arguments_substitution(self):
         result = render_skill_template("Review $ARGUMENTS carefully", "src/main.py")

aru_code-0.9.0/aru/__init__.py

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