aru-code 0.4.0__tar.gz → 0.6.0__tar.gz

{aru_code-0.4.0/aru_code.egg-info → aru_code-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.4.0
+Version: 0.6.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -58,7 +58,7 @@ An intelligent coding assistant for the terminal, powered by LLMs and [Agno](htt
 - **16 Integrated Tools** — File operations, code search, shell, web search, task delegation
 - **Task Planning** — Break down complex tasks into steps with automatic execution
 - **Multi-Provider** — Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek, and others via custom configuration
-- **Custom Commands and Skills** — Extend aru via the `.agents/` directory
+- **Custom Commands, Skills, and Agents** — Extend aru via the `.agents/` directory
 - **MCP Support** — Integration with Model Context Protocol servers
 
 ## Quick Start
@@ -103,6 +103,7 @@ That's it — `aru` is available globally after install.
 | `/mcp` | List available MCP servers and tools |
 | `/commands` | List custom commands |
 | `/skills` | List available skills |
+| `/agents` | List custom agents |
 | `/sessions` | List recent sessions |
 | `/help` | Show all commands |
 | `! <command>` | Execute shell commands |
@@ -206,25 +207,96 @@ You can configure custom providers with specific token limits:
 
 ### Permissions (`aru.json`)
 
-The `aru.json` file in the project root controls which shell commands aru can execute **without asking for confirmation**:
+Aru uses a granular permission system where each tool action resolves to one of three outcomes:
+
+- **`allow`** — executes without asking
+- **`ask`** — prompts for confirmation (once / always / no)
+- **`deny`** — blocks the action silently
+
+Configure permissions per tool category with glob patterns:
 
 ```json
 {
   "permission": {
-    "allow": [
-      "git *",
-      "npm *",
-      "pytest *",
-      "python *",
-      "uv run pytest *"
-    ]
+    "*": "ask",
+    "read": "allow",
+    "glob": "allow",
+    "grep": "allow",
+    "list": "allow",
+    "edit": {
+      "*": "allow",
+      "*.env": "deny"
+    },
+    "write": {
+      "*": "allow",
+      "*.env": "deny"
+    },
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "npm *": "allow",
+      "pytest *": "allow",
+      "rm -rf *": "deny"
+    },
+    "web_search": "allow",
+    "web_fetch": "allow",
+    "delegate_task": "allow"
+  }
+}
+```
+
+#### Available categories
+
+| Category | Matched against | Default |
+|----------|----------------|---------|
+| `read` | file path | `allow` |
+| `edit` | file path | `ask` |
+| `write` | file path | `ask` |
+| `bash` | command string | safe prefixes = `allow`, rest = `ask` |
+| `glob` | — | `allow` |
+| `grep` | — | `allow` |
+| `list` | — | `allow` |
+| `web_search` | — | `allow` |
+| `web_fetch` | URL | `allow` |
+| `delegate_task` | — | `allow` |
+
+#### Rule precedence
+
+Rules use **last-match-wins** ordering. Place catch-all `"*"` first, then specific patterns:
+
+```json
+{
+  "edit": {
+    "*": "allow",
+    "*.env": "deny",
+    "*.env.example": "allow"
   }
 }
 ```
 
-Each entry is a glob pattern. Any command that doesn't match a listed pattern will prompt for confirmation before executing.
+#### Shorthands
+
+```json
+"permission": "allow"
+```
+Allows everything (equivalent to `--dangerously-skip-permissions`).
+
+```json
+"permission": { "read": "allow", "edit": "ask" }
+```
+String value applies to all patterns in that category.
+
+#### Defaults
+
+Without any `aru.json` config, aru applies safe defaults:
+- Read-only tools (`read`, `glob`, `grep`, `list`) → `allow`
+- Mutating tools (`edit`, `write`) → `ask`
+- Bash → ~40 safe command prefixes auto-allowed (`ls`, `git status`, `grep`, etc.), rest → `ask`
+- Sensitive files (`*.env`, `*.env.*`) → `deny` for read/edit/write (except `*.env.example`)
 
 > `aru.json` can also be placed at `.aru/config.json`.
+>
+> A full `aru.json` config reference here: [`aru.json`](./aru.json)
 
 ### AGENTS.md
 
@@ -234,14 +306,98 @@ Place an `AGENTS.md` file in your project root with custom instructions that wil
 
 ```
 .agents/
+├── agents/         # Custom agents with their own model, tools, and prompt
+│   └── reviewer.md # Usage: /reviewer <args>
 ├── commands/       # Custom slash commands (filename = command name)
 │   └── deploy.md   # Usage: /deploy <args>
 └── skills/         # Custom skills/personas
-    └── review.md   # Loaded as additional agent instructions
+    └── review/
+        └── SKILL.md
 ```
 
 Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
 
+### Custom Agents
+
+Custom agents are Markdown files with YAML frontmatter stored in `.agents/agents/`. Each agent runs with its own system prompt, model, and tool set — unlike commands and skills, which reuse the General Agent.
+
+```markdown
+---
+name: Code Reviewer
+description: Review code for quality, bugs, and best practices
+model: anthropic/claude-sonnet-4-5
+tools: read_file, grep_search, glob_search, code_structure
+max_turns: 15
+mode: primary
+---
+
+You are an expert code reviewer. Analyze code for bugs, security,
+performance, and readability. Do NOT modify files.
+```
+
+#### Frontmatter fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name of the agent |
+| `description` | Yes | When to use this agent (shown in `/agents` and tab completion) |
+| `model` | No | Provider/model reference (e.g., `anthropic/claude-sonnet-4-5`). Defaults to session model |
+| `tools` | No | Comma-separated tool names (allowlist) or JSON object for granular control (e.g., `{"bash": false}`). Defaults to all general tools |
+| `max_turns` | No | Max tool calls before the agent stops. Default: 20 |
+| `mode` | No | `primary` (invocable via `/name`) or `subagent` (only via `delegate_task`). Default: `primary` |
+| `permission` | No | Permission overrides (same format as `aru.json` permission section). Replaces global rules for specified categories while the agent runs |
+
+#### Invocation
+
+```
+aru> /reviewer src/auth.py        # invoke by slash + filename (without .md)
+aru> /agents                       # list all custom agents
+```
+
+#### Discovery paths
+
+Agents are discovered from multiple locations (later overrides earlier):
+
+1. `~/.agents/agents/` — global (available in all projects)
+2. `~/.claude/agents/` — global (Claude Code compatible path)
+3. `.agents/agents/` — project-local
+4. `.claude/agents/` — project-local
+
+#### Agent-level permissions
+
+Agents can override global permission rules. Overrides replace the entire category — unspecified categories inherit from global config.
+
+```markdown
+---
+name: Code Reviewer
+description: Read-only code reviewer
+permission:
+  edit: deny
+  write: deny
+  bash:
+    git diff *: allow
+    grep *: allow
+---
+```
+
+You can also set agent permissions in `aru.json` (overrides frontmatter):
+
+```json
+{
+  "agent": {
+    "reviewer": {
+      "permission": { "edit": "deny", "write": "deny" }
+    }
+  }
+}
+```
+
+Each agent gets its own isolated "always" memory — approvals during an agent's run don't carry over to the global scope.
+
+#### Subagent mode
+
+Agents with `mode: subagent` can be referenced by the LLM via `delegate_task(task, agent="name")` but are not directly invocable from the CLI.
+
 ### MCP Support (Model Context Protocol)
 
 Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
@@ -296,9 +452,17 @@ Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
 ```
 aru-code/
 ├── aru/
-│   ├── cli.py              # Interactive CLI with streaming display
+│   ├── cli.py              # Main REPL loop, argument parsing, and entry point
+│   ├── agent_factory.py    # Agent instantiation (general and custom agents)
+│   ├── commands.py         # Slash commands, help display, shell execution
+│   ├── completers.py       # Input completions, paste detection, @file mentions
+│   ├── context.py          # Token optimization (pruning, truncation, compaction)
+│   ├── display.py          # Terminal display (logo, status bar, streaming output)
+│   ├── runner.py           # Agent execution orchestration with streaming
+│   ├── session.py          # Session state, persistence, plan tracking
 │   ├── config.py           # Configuration loader (AGENTS.md, .agents/)
 │   ├── providers.py        # Multi-provider LLM abstraction
+│   ├── permissions.py      # Granular permission system (allow/ask/deny)
 │   ├── agents/
 │   │   ├── planner.py      # Planning agent
 │   │   └── executor.py     # Execution agent

{aru_code-0.4.0 → aru_code-0.6.0}/README.md

@@ -11,7 +11,7 @@ An intelligent coding assistant for the terminal, powered by LLMs and [Agno](htt
 - **16 Integrated Tools** — File operations, code search, shell, web search, task delegation
 - **Task Planning** — Break down complex tasks into steps with automatic execution
 - **Multi-Provider** — Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek, and others via custom configuration
-- **Custom Commands and Skills** — Extend aru via the `.agents/` directory
+- **Custom Commands, Skills, and Agents** — Extend aru via the `.agents/` directory
 - **MCP Support** — Integration with Model Context Protocol servers
 
 ## Quick Start
@@ -56,6 +56,7 @@ That's it — `aru` is available globally after install.
 | `/mcp` | List available MCP servers and tools |
 | `/commands` | List custom commands |
 | `/skills` | List available skills |
+| `/agents` | List custom agents |
 | `/sessions` | List recent sessions |
 | `/help` | Show all commands |
 | `! <command>` | Execute shell commands |
@@ -159,25 +160,96 @@ You can configure custom providers with specific token limits:
 
 ### Permissions (`aru.json`)
 
-The `aru.json` file in the project root controls which shell commands aru can execute **without asking for confirmation**:
+Aru uses a granular permission system where each tool action resolves to one of three outcomes:
+
+- **`allow`** — executes without asking
+- **`ask`** — prompts for confirmation (once / always / no)
+- **`deny`** — blocks the action silently
+
+Configure permissions per tool category with glob patterns:
 
 ```json
 {
   "permission": {
-    "allow": [
-      "git *",
-      "npm *",
-      "pytest *",
-      "python *",
-      "uv run pytest *"
-    ]
+    "*": "ask",
+    "read": "allow",
+    "glob": "allow",
+    "grep": "allow",
+    "list": "allow",
+    "edit": {
+      "*": "allow",
+      "*.env": "deny"
+    },
+    "write": {
+      "*": "allow",
+      "*.env": "deny"
+    },
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "npm *": "allow",
+      "pytest *": "allow",
+      "rm -rf *": "deny"
+    },
+    "web_search": "allow",
+    "web_fetch": "allow",
+    "delegate_task": "allow"
+  }
+}
+```
+
+#### Available categories
+
+| Category | Matched against | Default |
+|----------|----------------|---------|
+| `read` | file path | `allow` |
+| `edit` | file path | `ask` |
+| `write` | file path | `ask` |
+| `bash` | command string | safe prefixes = `allow`, rest = `ask` |
+| `glob` | — | `allow` |
+| `grep` | — | `allow` |
+| `list` | — | `allow` |
+| `web_search` | — | `allow` |
+| `web_fetch` | URL | `allow` |
+| `delegate_task` | — | `allow` |
+
+#### Rule precedence
+
+Rules use **last-match-wins** ordering. Place catch-all `"*"` first, then specific patterns:
+
+```json
+{
+  "edit": {
+    "*": "allow",
+    "*.env": "deny",
+    "*.env.example": "allow"
   }
 }
 ```
 
-Each entry is a glob pattern. Any command that doesn't match a listed pattern will prompt for confirmation before executing.
+#### Shorthands
+
+```json
+"permission": "allow"
+```
+Allows everything (equivalent to `--dangerously-skip-permissions`).
+
+```json
+"permission": { "read": "allow", "edit": "ask" }
+```
+String value applies to all patterns in that category.
+
+#### Defaults
+
+Without any `aru.json` config, aru applies safe defaults:
+- Read-only tools (`read`, `glob`, `grep`, `list`) → `allow`
+- Mutating tools (`edit`, `write`) → `ask`
+- Bash → ~40 safe command prefixes auto-allowed (`ls`, `git status`, `grep`, etc.), rest → `ask`
+- Sensitive files (`*.env`, `*.env.*`) → `deny` for read/edit/write (except `*.env.example`)
 
 > `aru.json` can also be placed at `.aru/config.json`.
+>
+> A full `aru.json` config reference here: [`aru.json`](./aru.json)
 
 ### AGENTS.md
 
@@ -187,14 +259,98 @@ Place an `AGENTS.md` file in your project root with custom instructions that wil
 
 ```
 .agents/
+├── agents/         # Custom agents with their own model, tools, and prompt
+│   └── reviewer.md # Usage: /reviewer <args>
 ├── commands/       # Custom slash commands (filename = command name)
 │   └── deploy.md   # Usage: /deploy <args>
 └── skills/         # Custom skills/personas
-    └── review.md   # Loaded as additional agent instructions
+    └── review/
+        └── SKILL.md
 ```
 
 Command files support frontmatter with `description` and the `$INPUT` template variable for arguments.
 
+### Custom Agents
+
+Custom agents are Markdown files with YAML frontmatter stored in `.agents/agents/`. Each agent runs with its own system prompt, model, and tool set — unlike commands and skills, which reuse the General Agent.
+
+```markdown
+---
+name: Code Reviewer
+description: Review code for quality, bugs, and best practices
+model: anthropic/claude-sonnet-4-5
+tools: read_file, grep_search, glob_search, code_structure
+max_turns: 15
+mode: primary
+---
+
+You are an expert code reviewer. Analyze code for bugs, security,
+performance, and readability. Do NOT modify files.
+```
+
+#### Frontmatter fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name of the agent |
+| `description` | Yes | When to use this agent (shown in `/agents` and tab completion) |
+| `model` | No | Provider/model reference (e.g., `anthropic/claude-sonnet-4-5`). Defaults to session model |
+| `tools` | No | Comma-separated tool names (allowlist) or JSON object for granular control (e.g., `{"bash": false}`). Defaults to all general tools |
+| `max_turns` | No | Max tool calls before the agent stops. Default: 20 |
+| `mode` | No | `primary` (invocable via `/name`) or `subagent` (only via `delegate_task`). Default: `primary` |
+| `permission` | No | Permission overrides (same format as `aru.json` permission section). Replaces global rules for specified categories while the agent runs |
+
+#### Invocation
+
+```
+aru> /reviewer src/auth.py        # invoke by slash + filename (without .md)
+aru> /agents                       # list all custom agents
+```
+
+#### Discovery paths
+
+Agents are discovered from multiple locations (later overrides earlier):
+
+1. `~/.agents/agents/` — global (available in all projects)
+2. `~/.claude/agents/` — global (Claude Code compatible path)
+3. `.agents/agents/` — project-local
+4. `.claude/agents/` — project-local
+
+#### Agent-level permissions
+
+Agents can override global permission rules. Overrides replace the entire category — unspecified categories inherit from global config.
+
+```markdown
+---
+name: Code Reviewer
+description: Read-only code reviewer
+permission:
+  edit: deny
+  write: deny
+  bash:
+    git diff *: allow
+    grep *: allow
+---
+```
+
+You can also set agent permissions in `aru.json` (overrides frontmatter):
+
+```json
+{
+  "agent": {
+    "reviewer": {
+      "permission": { "edit": "deny", "write": "deny" }
+    }
+  }
+}
+```
+
+Each agent gets its own isolated "always" memory — approvals during an agent's run don't carry over to the global scope.
+
+#### Subagent mode
+
+Agents with `mode: subagent` can be referenced by the LLM via `delegate_task(task, agent="name")` but are not directly invocable from the CLI.
+
 ### MCP Support (Model Context Protocol)
 
 Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
@@ -249,9 +405,17 @@ Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
 ```
 aru-code/
 ├── aru/
-│   ├── cli.py              # Interactive CLI with streaming display
+│   ├── cli.py              # Main REPL loop, argument parsing, and entry point
+│   ├── agent_factory.py    # Agent instantiation (general and custom agents)
+│   ├── commands.py         # Slash commands, help display, shell execution
+│   ├── completers.py       # Input completions, paste detection, @file mentions
+│   ├── context.py          # Token optimization (pruning, truncation, compaction)
+│   ├── display.py          # Terminal display (logo, status bar, streaming output)
+│   ├── runner.py           # Agent execution orchestration with streaming
+│   ├── session.py          # Session state, persistence, plan tracking
 │   ├── config.py           # Configuration loader (AGENTS.md, .agents/)
 │   ├── providers.py        # Multi-provider LLM abstraction
+│   ├── permissions.py      # Granular permission system (allow/ask/deny)
 │   ├── agents/
 │   │   ├── planner.py      # Planning agent
 │   │   └── executor.py     # Execution agent

aru_code-0.6.0/aru/__init__.py

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

aru_code-0.6.0/aru/agent_factory.py

@@ -0,0 +1,66 @@
+"""Agent creation: general-purpose and custom agent instantiation."""
+
+from __future__ import annotations
+
+from aru.agents.base import build_instructions as _build_instructions
+from aru.config import AgentConfig, CustomAgent
+from aru.providers import create_model
+from aru.session import Session
+
+
+def create_general_agent(session: Session, config: AgentConfig | None = None):
+    """Create the general-purpose agent."""
+    from agno.agent import Agent
+    from agno.compression.manager import CompressionManager
+
+    from aru.tools.codebase import GENERAL_TOOLS, _get_small_model_ref
+
+    extra = config.get_extra_instructions() if config else ""
+
+    return Agent(
+        name="Aru",
+        model=create_model(session.model_ref, max_tokens=8192),
+        tools=GENERAL_TOOLS,
+        instructions=_build_instructions("general", extra),
+        markdown=True,
+        compress_tool_results=True,
+        compression_manager=CompressionManager(
+            model=create_model(_get_small_model_ref(), max_tokens=1024),
+            compress_tool_results=True,
+            compress_tool_results_limit=7,
+        ),
+        tool_call_limit=20,
+    )
+
+
+def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
+                                  config: AgentConfig | None = None):
+    """Create an Agno Agent from a CustomAgent definition."""
+    from agno.agent import Agent
+    from agno.compression.manager import CompressionManager
+    from aru.agents.base import BASE_INSTRUCTIONS
+    from aru.tools.codebase import resolve_tools, _get_small_model_ref
+
+    model_ref = agent_def.model or session.model_ref
+    tools = resolve_tools(agent_def.tools)
+
+    extra = config.get_extra_instructions() if config else ""
+    parts = [agent_def.system_prompt, BASE_INSTRUCTIONS]
+    if extra:
+        parts.append(extra)
+    instructions = "\n\n".join(parts)
+
+    return Agent(
+        name=agent_def.name,
+        model=create_model(model_ref, max_tokens=8192),
+        tools=tools,
+        instructions=instructions,
+        markdown=True,
+        compress_tool_results=True,
+        compression_manager=CompressionManager(
+            model=create_model(_get_small_model_ref(), max_tokens=1024),
+            compress_tool_results=True,
+            compress_tool_results_limit=7,
+        ),
+        tool_call_limit=agent_def.max_turns or 20,
+    )