aru-code 0.25.2__tar.gz → 0.26.0__tar.gz

{aru_code-0.25.2/aru_code.egg-info → aru_code-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.25.2
+Version: 0.26.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -49,17 +49,22 @@ Dynamic: license-file
 
 An intelligent coding assistant for the terminal, powered by LLMs and [Agno](https://github.com/agno-agi/agno) agents.
 
+📖 **Full documentation:** [https://estevaofon.github.io/aru/](https://estevaofon.github.io/aru/)
+
 ![0329(3)](https://github.com/user-attachments/assets/e84d5139-ebaa-4d12-bbae-628fae7dbc7a)
 
 ## Highlights
 
-- **Multi-Agent Architecture** — Specialized agents for planning, execution, exploration, and conversation
+- **Catalog-Driven Multi-Agent Architecture** — `build`, `plan`, `executor`, and `explorer` (subagent) specs resolved from a single source of truth (`aru/agents/catalog.py`)
+- **Autonomous Plan Mode** — Agents self-trigger planning via `enter_plan_mode(task)`; plan steps are persisted in the session and surfaced each turn as a `PLAN ACTIVE` reminder
+- **Structured Subtask Tracking** — `create_task_list` / `update_task` / `update_plan_step` force the executor to plan, execute, and mark subtasks as it goes
 - **Interactive CLI** — Streaming responses, multi-line paste, session management
 - **Image Support** — Attach images via `@` mentions for multimodal analysis (Claude, GPT-4o, Gemini)
-- **11 Integrated Tools** — File operations, code search, shell, web search, task delegation
-- **Task Planning** — Break down complex tasks into steps with automatic execution
+- **17 Integrated Tools** — File I/O (single + batched), code search, shell, web, delegation, plan/task tracking
 - **Multi-Provider** — Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek, and others via custom configuration
 - **Custom Commands, Skills, and Agents** — Extend aru via the `.agents/` directory
+- **Custom Tools** — Add your own Python tools with a simple `@tool` decorator
+- **Plugin System** — OpenCode-compatible hooks for tool lifecycle, chat, permissions, and more
 - **MCP Support** — Integration with Model Context Protocol servers
 
 ## Quick Start
@@ -491,6 +496,116 @@ Each agent gets its own isolated "always" memory — approvals during an agent's
 
 Agents with `mode: subagent` can be referenced by the LLM via `delegate_task(task, agent="name")` but are not directly invocable from the CLI.
 
+### Custom Tools
+
+You can extend aru with your own Python tools. Drop a `.py` file in `.aru/tools/` (project) or `~/.aru/tools/` (global) — aru auto-discovers and registers every function found.
+
+```python
+# .aru/tools/deploy.py
+from aru.plugins import tool
+
+@tool(description="Deploy the current branch to an environment")
+def deploy(environment: str = "staging") -> str:
+    """Runs the deploy script and returns the output."""
+    import subprocess
+    result = subprocess.run(
+        ["./scripts/deploy.sh", environment],
+        capture_output=True, text=True,
+    )
+    return result.stdout or result.stderr
+```
+
+The LLM sees each tool as a first-class function — name, description, and typed parameters are inferred from the signature.
+
+#### Rules
+
+- **Decorator is optional.** A bare `def fn(...) -> str` with a docstring works too. Use `@tool(...)` when you want a custom description or to override a built-in.
+- **Parameters** are read from type hints; defaults become optional params.
+- **Return type** should be `str` (or something stringifiable) — the result is sent back to the LLM as tool output.
+- **Override built-ins** with `@tool(override=True)` if you want to replace, say, `bash` with your own implementation.
+- **Discovery paths** (later roots override earlier ones):
+  1. `~/.aru/tools/`
+  2. `.aru/tools/`
+  3. `~/.agents/tools/`
+  4. `.agents/tools/`
+
+Both sync and `async def` functions are supported.
+
+### Plugins
+
+For more control than custom tools — e.g. intercepting tool calls, mutating chat messages, injecting env vars into shell commands, or blocking permissions — use the plugin system. Plugins are Python files that return a `Hooks` object, mirroring OpenCode's hook pattern.
+
+```python
+# .aru/plugins/audit.py
+from aru.plugins import Hooks, PluginInput
+
+async def plugin(ctx: PluginInput, options: dict | None = None) -> Hooks:
+    hooks = Hooks()
+
+    @hooks.on("tool.execute.before")
+    async def before_tool(event):
+        print(f"[audit] running {event.tool_name} with {event.args}")
+
+    @hooks.on("tool.execute.after")
+    async def after_tool(event):
+        print(f"[audit] {event.tool_name} → ok")
+
+    @hooks.on("shell.env")
+    async def inject_env(event):
+        event.env["DEPLOY_TOKEN"] = "••••"
+
+    # You can also register tools directly from a plugin:
+    def greet(name: str) -> str:
+        """Say hello."""
+        return f"hello, {name}"
+    hooks.tools["greet"] = greet
+
+    return hooks
+```
+
+Save the file as `.aru/plugins/<name>.py` and aru will load it automatically at startup.
+
+#### Available hooks
+
+| Hook | When it fires | Typical use |
+|------|---------------|-------------|
+| `config` | After config is loaded | Read/adjust config |
+| `tool.execute.before` | Before any tool runs | Audit, block, mutate args |
+| `tool.execute.after` | After any tool runs | Log, post-process results |
+| `tool.definition` | When tool list is resolved | Modify tool descriptions/params |
+| `chat.message` | Before a user message is sent to the LLM | Rewrite the message |
+| `chat.params` | Before the LLM call | Adjust `temperature`, `max_tokens` |
+| `chat.system.transform` | Before the LLM call | Modify the system prompt |
+| `chat.messages.transform` | Before the LLM call | Modify the full message history |
+| `command.execute.before` | Before a slash command runs | Block or rewrite commands |
+| `permission.ask` | Before a permission prompt | Auto-allow/deny |
+| `shell.env` | Before `bash` runs | Inject env vars |
+| `session.compact` | Before context compaction | React to compaction |
+| `event` | Any published event | Generic subscription |
+
+Handlers can be sync or `async`. They run sequentially so each can mutate the event before the next handler sees it. Raise `PermissionError` to block an action.
+
+#### Loading plugins
+
+Plugins come from three sources:
+
+1. **Auto-discovery** — `.aru/plugins/*.py`, `.agents/plugins/*.py`, and the same paths under `~/`
+2. **Config** — explicit list in `aru.json`:
+
+   ```json
+   {
+     "plugins": [
+       "my-package-plugin",
+       ["./.aru/plugins/audit.py", { "verbose": true }]
+     ]
+   }
+   ```
+
+   The second form passes options to the plugin as the `options` argument.
+3. **Entry points** — installed packages can register via the `aru.plugins` entry point group
+
+Every plugin file must export a `plugin(ctx, options)` function (sync or async) that returns a `Hooks` instance.
+
 ### MCP Support (Model Context Protocol)
 
 Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
@@ -508,33 +623,53 @@ Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
 
 ## Agents
 
-| Agent | Role | Tools |
-|-------|------|-------|
-| **Planner** | Analyzes codebase, creates structured implementation plans | Read-only tools, search, web |
-| **Executor** | Implements code changes based on plans or instructions | All tools including delegation |
-| **General** | Handles conversation and simple operations | All tools including delegation |
-| **Explorer** | Fast, read-only codebase exploration and search | Read-only tools, search, bash (read-only) |
+Built-in agents are declared as specs in `aru/agents/catalog.py` and instantiated on demand by `agent_factory.create_agent_from_spec`. A single construction path resolves the model, tool list, prompt role, and plugin hooks for all native agents.
+
+| Agent | Mode | Role | Tools |
+|-------|------|------|-------|
+| **`build`** (General) | primary | Conversational coding assistant. Self-triggers `enter_plan_mode` for 3+ file changes | Full tool set including `delegate_task` |
+| **`plan`** (Planner) | primary | Read-only analysis → `## Summary` + `## Steps` markdown plan | Read/search only (`read_file`, `read_files`, `glob_search`, `grep_search`, `list_directory`) |
+| **`executor`** | primary | Step-by-step execution of a stored plan with mandatory task list tracking | Full tool set |
+| **`explorer`** | **subagent** | Fast, read-only codebase research. Invoked only via `delegate_task(task, agent_name="explorer")` | Read/search + read-only `bash` + `rank_files` |
+
+> **Scope reviewer:** `aru/agents/planner.py` also exposes `review_plan(request, plan)`, a one-shot, no-tool reviewer that runs on the small model to trim scope creep from generated plans. Enabled via `plan_reviewer: true` in `aru.json`.
+
+### Plan mode flow
+
+The `plan` agent runs in two ways:
+
+1. **Manual:** the user types `/plan <task>` — the planner produces a plan, the reviewer optionally trims it, and the result is stored in the session.
+2. **Autonomous:** the `build` agent calls `enter_plan_mode(task)` when it detects a multi-file task. This invokes the planner, stores the plan, and returns a summary.
+
+Once a plan is stored, every following turn prepends a `<system-reminder>` listing all plan steps with their status icons. The build/executor agent works through them in order, calling `update_plan_step(index, "completed")` after each. Within a step, it calls `create_task_list([...])` to break the step into 1–10 concrete subtasks, then `update_task(i, "completed")` as they finish.
 
 ## Tools
 
 ### File Operations
 - `read_file` — Reads files with line range support and binary detection
-- `read_files` — Reads multiple files in parallel (single batched call)
+- `read_files` — Reads multiple files in parallel (batched)
 - `write_file` — Writes content to files, creating directories as needed
+- `write_files` — Writes multiple files in one call
 - `edit_file` — Find-and-replace edits on files
+- `edit_files` — Batched find-and-replace across multiple files
 
 ### Search & Discovery
 - `glob_search` — Find files by pattern (respects .gitignore)
 - `grep_search` — Content search with regex and file filtering
 - `list_directory` — Directory listing with gitignore filtering
+- `rank_files` — Multi-factor file relevance ranking (explorer subagent only)
 
 ### Shell & Web
 - `bash` — Executes shell commands with permission gates
 - `web_search` — Web search via DuckDuckGo
 - `web_fetch` — Fetches URLs and converts HTML to readable text
 
-### Advanced
-- `delegate_task` — Spawns autonomous sub-agents for parallel task execution
+### Planning & Delegation
+- `enter_plan_mode` — Generate a structured plan via the planner agent and store it in the session
+- `update_plan_step` — Mark a macro plan step as `in_progress` / `completed` / `failed` / `skipped`
+- `create_task_list` — Declare 1–10 subtasks for the current step (mandatory first executor call)
+- `update_task` — Mark a subtask as `in_progress` / `completed` / `failed`
+- `delegate_task` — Spawn an autonomous subagent (defaults to `explorer`) for parallel research or execution
 
 ## Architecture
 
@@ -542,22 +677,25 @@ Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
 aru-code/
 ├── aru/
 │   ├── cli.py              # Main REPL loop, argument parsing, and entry point
-│   ├── agent_factory.py    # Agent instantiation (general and custom agents)
+│   ├── agent_factory.py    # Single factory — builds Agno Agents from catalog specs
 │   ├── 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
+│   ├── runner.py           # Agent execution, streaming, PLAN ACTIVE reminder injection
+│   ├── session.py          # Session state, persistence, plan steps tracking
+│   ├── runtime.py          # Request context (TaskStore, session, display handles)
 │   ├── 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
-│   │   └── explorer.py     # Explorer agent (fast, read-only codebase search)
+│   │   ├── base.py         # Shared prompt templates + build_instructions(role)
+│   │   ├── catalog.py      # AgentSpec registry — build / plan / executor / explorer
+│   │   └── planner.py      # review_plan() — small-model scope reviewer
 │   └── tools/
-│       ├── codebase.py     # 11 core tools
+│       ├── codebase.py     # Core tool implementations + GENERAL/EXECUTOR/PLANNER/EXPLORER sets
+│       ├── plan_mode.py    # enter_plan_mode tool (agent-invokable planner entry)
+│       ├── tasklist.py     # create_task_list / update_task / update_plan_step
 │       ├── ast_tools.py    # Tree-sitter code analysis
 │       ├── ranker.py       # File relevance ranking
 │       ├── mcp_client.py   # MCP client

{aru_code-0.25.2 → aru_code-0.26.0}/README.md

@@ -2,17 +2,22 @@
 
 An intelligent coding assistant for the terminal, powered by LLMs and [Agno](https://github.com/agno-agi/agno) agents.
 
+📖 **Full documentation:** [https://estevaofon.github.io/aru/](https://estevaofon.github.io/aru/)
+
 ![0329(3)](https://github.com/user-attachments/assets/e84d5139-ebaa-4d12-bbae-628fae7dbc7a)
 
 ## Highlights
 
-- **Multi-Agent Architecture** — Specialized agents for planning, execution, exploration, and conversation
+- **Catalog-Driven Multi-Agent Architecture** — `build`, `plan`, `executor`, and `explorer` (subagent) specs resolved from a single source of truth (`aru/agents/catalog.py`)
+- **Autonomous Plan Mode** — Agents self-trigger planning via `enter_plan_mode(task)`; plan steps are persisted in the session and surfaced each turn as a `PLAN ACTIVE` reminder
+- **Structured Subtask Tracking** — `create_task_list` / `update_task` / `update_plan_step` force the executor to plan, execute, and mark subtasks as it goes
 - **Interactive CLI** — Streaming responses, multi-line paste, session management
 - **Image Support** — Attach images via `@` mentions for multimodal analysis (Claude, GPT-4o, Gemini)
-- **11 Integrated Tools** — File operations, code search, shell, web search, task delegation
-- **Task Planning** — Break down complex tasks into steps with automatic execution
+- **17 Integrated Tools** — File I/O (single + batched), code search, shell, web, delegation, plan/task tracking
 - **Multi-Provider** — Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek, and others via custom configuration
 - **Custom Commands, Skills, and Agents** — Extend aru via the `.agents/` directory
+- **Custom Tools** — Add your own Python tools with a simple `@tool` decorator
+- **Plugin System** — OpenCode-compatible hooks for tool lifecycle, chat, permissions, and more
 - **MCP Support** — Integration with Model Context Protocol servers
 
 ## Quick Start
@@ -444,6 +449,116 @@ Each agent gets its own isolated "always" memory — approvals during an agent's
 
 Agents with `mode: subagent` can be referenced by the LLM via `delegate_task(task, agent="name")` but are not directly invocable from the CLI.
 
+### Custom Tools
+
+You can extend aru with your own Python tools. Drop a `.py` file in `.aru/tools/` (project) or `~/.aru/tools/` (global) — aru auto-discovers and registers every function found.
+
+```python
+# .aru/tools/deploy.py
+from aru.plugins import tool
+
+@tool(description="Deploy the current branch to an environment")
+def deploy(environment: str = "staging") -> str:
+    """Runs the deploy script and returns the output."""
+    import subprocess
+    result = subprocess.run(
+        ["./scripts/deploy.sh", environment],
+        capture_output=True, text=True,
+    )
+    return result.stdout or result.stderr
+```
+
+The LLM sees each tool as a first-class function — name, description, and typed parameters are inferred from the signature.
+
+#### Rules
+
+- **Decorator is optional.** A bare `def fn(...) -> str` with a docstring works too. Use `@tool(...)` when you want a custom description or to override a built-in.
+- **Parameters** are read from type hints; defaults become optional params.
+- **Return type** should be `str` (or something stringifiable) — the result is sent back to the LLM as tool output.
+- **Override built-ins** with `@tool(override=True)` if you want to replace, say, `bash` with your own implementation.
+- **Discovery paths** (later roots override earlier ones):
+  1. `~/.aru/tools/`
+  2. `.aru/tools/`
+  3. `~/.agents/tools/`
+  4. `.agents/tools/`
+
+Both sync and `async def` functions are supported.
+
+### Plugins
+
+For more control than custom tools — e.g. intercepting tool calls, mutating chat messages, injecting env vars into shell commands, or blocking permissions — use the plugin system. Plugins are Python files that return a `Hooks` object, mirroring OpenCode's hook pattern.
+
+```python
+# .aru/plugins/audit.py
+from aru.plugins import Hooks, PluginInput
+
+async def plugin(ctx: PluginInput, options: dict | None = None) -> Hooks:
+    hooks = Hooks()
+
+    @hooks.on("tool.execute.before")
+    async def before_tool(event):
+        print(f"[audit] running {event.tool_name} with {event.args}")
+
+    @hooks.on("tool.execute.after")
+    async def after_tool(event):
+        print(f"[audit] {event.tool_name} → ok")
+
+    @hooks.on("shell.env")
+    async def inject_env(event):
+        event.env["DEPLOY_TOKEN"] = "••••"
+
+    # You can also register tools directly from a plugin:
+    def greet(name: str) -> str:
+        """Say hello."""
+        return f"hello, {name}"
+    hooks.tools["greet"] = greet
+
+    return hooks
+```
+
+Save the file as `.aru/plugins/<name>.py` and aru will load it automatically at startup.
+
+#### Available hooks
+
+| Hook | When it fires | Typical use |
+|------|---------------|-------------|
+| `config` | After config is loaded | Read/adjust config |
+| `tool.execute.before` | Before any tool runs | Audit, block, mutate args |
+| `tool.execute.after` | After any tool runs | Log, post-process results |
+| `tool.definition` | When tool list is resolved | Modify tool descriptions/params |
+| `chat.message` | Before a user message is sent to the LLM | Rewrite the message |
+| `chat.params` | Before the LLM call | Adjust `temperature`, `max_tokens` |
+| `chat.system.transform` | Before the LLM call | Modify the system prompt |
+| `chat.messages.transform` | Before the LLM call | Modify the full message history |
+| `command.execute.before` | Before a slash command runs | Block or rewrite commands |
+| `permission.ask` | Before a permission prompt | Auto-allow/deny |
+| `shell.env` | Before `bash` runs | Inject env vars |
+| `session.compact` | Before context compaction | React to compaction |
+| `event` | Any published event | Generic subscription |
+
+Handlers can be sync or `async`. They run sequentially so each can mutate the event before the next handler sees it. Raise `PermissionError` to block an action.
+
+#### Loading plugins
+
+Plugins come from three sources:
+
+1. **Auto-discovery** — `.aru/plugins/*.py`, `.agents/plugins/*.py`, and the same paths under `~/`
+2. **Config** — explicit list in `aru.json`:
+
+   ```json
+   {
+     "plugins": [
+       "my-package-plugin",
+       ["./.aru/plugins/audit.py", { "verbose": true }]
+     ]
+   }
+   ```
+
+   The second form passes options to the plugin as the `options` argument.
+3. **Entry points** — installed packages can register via the `aru.plugins` entry point group
+
+Every plugin file must export a `plugin(ctx, options)` function (sync or async) that returns a `Hooks` instance.
+
 ### MCP Support (Model Context Protocol)
 
 Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
@@ -461,33 +576,53 @@ Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
 
 ## Agents
 
-| Agent | Role | Tools |
-|-------|------|-------|
-| **Planner** | Analyzes codebase, creates structured implementation plans | Read-only tools, search, web |
-| **Executor** | Implements code changes based on plans or instructions | All tools including delegation |
-| **General** | Handles conversation and simple operations | All tools including delegation |
-| **Explorer** | Fast, read-only codebase exploration and search | Read-only tools, search, bash (read-only) |
+Built-in agents are declared as specs in `aru/agents/catalog.py` and instantiated on demand by `agent_factory.create_agent_from_spec`. A single construction path resolves the model, tool list, prompt role, and plugin hooks for all native agents.
+
+| Agent | Mode | Role | Tools |
+|-------|------|------|-------|
+| **`build`** (General) | primary | Conversational coding assistant. Self-triggers `enter_plan_mode` for 3+ file changes | Full tool set including `delegate_task` |
+| **`plan`** (Planner) | primary | Read-only analysis → `## Summary` + `## Steps` markdown plan | Read/search only (`read_file`, `read_files`, `glob_search`, `grep_search`, `list_directory`) |
+| **`executor`** | primary | Step-by-step execution of a stored plan with mandatory task list tracking | Full tool set |
+| **`explorer`** | **subagent** | Fast, read-only codebase research. Invoked only via `delegate_task(task, agent_name="explorer")` | Read/search + read-only `bash` + `rank_files` |
+
+> **Scope reviewer:** `aru/agents/planner.py` also exposes `review_plan(request, plan)`, a one-shot, no-tool reviewer that runs on the small model to trim scope creep from generated plans. Enabled via `plan_reviewer: true` in `aru.json`.
+
+### Plan mode flow
+
+The `plan` agent runs in two ways:
+
+1. **Manual:** the user types `/plan <task>` — the planner produces a plan, the reviewer optionally trims it, and the result is stored in the session.
+2. **Autonomous:** the `build` agent calls `enter_plan_mode(task)` when it detects a multi-file task. This invokes the planner, stores the plan, and returns a summary.
+
+Once a plan is stored, every following turn prepends a `<system-reminder>` listing all plan steps with their status icons. The build/executor agent works through them in order, calling `update_plan_step(index, "completed")` after each. Within a step, it calls `create_task_list([...])` to break the step into 1–10 concrete subtasks, then `update_task(i, "completed")` as they finish.
 
 ## Tools
 
 ### File Operations
 - `read_file` — Reads files with line range support and binary detection
-- `read_files` — Reads multiple files in parallel (single batched call)
+- `read_files` — Reads multiple files in parallel (batched)
 - `write_file` — Writes content to files, creating directories as needed
+- `write_files` — Writes multiple files in one call
 - `edit_file` — Find-and-replace edits on files
+- `edit_files` — Batched find-and-replace across multiple files
 
 ### Search & Discovery
 - `glob_search` — Find files by pattern (respects .gitignore)
 - `grep_search` — Content search with regex and file filtering
 - `list_directory` — Directory listing with gitignore filtering
+- `rank_files` — Multi-factor file relevance ranking (explorer subagent only)
 
 ### Shell & Web
 - `bash` — Executes shell commands with permission gates
 - `web_search` — Web search via DuckDuckGo
 - `web_fetch` — Fetches URLs and converts HTML to readable text
 
-### Advanced
-- `delegate_task` — Spawns autonomous sub-agents for parallel task execution
+### Planning & Delegation
+- `enter_plan_mode` — Generate a structured plan via the planner agent and store it in the session
+- `update_plan_step` — Mark a macro plan step as `in_progress` / `completed` / `failed` / `skipped`
+- `create_task_list` — Declare 1–10 subtasks for the current step (mandatory first executor call)
+- `update_task` — Mark a subtask as `in_progress` / `completed` / `failed`
+- `delegate_task` — Spawn an autonomous subagent (defaults to `explorer`) for parallel research or execution
 
 ## Architecture
 
@@ -495,22 +630,25 @@ Aru can load tools from MCP servers. Configure in `.aru/mcp_config.json`:
 aru-code/
 ├── aru/
 │   ├── cli.py              # Main REPL loop, argument parsing, and entry point
-│   ├── agent_factory.py    # Agent instantiation (general and custom agents)
+│   ├── agent_factory.py    # Single factory — builds Agno Agents from catalog specs
 │   ├── 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
+│   ├── runner.py           # Agent execution, streaming, PLAN ACTIVE reminder injection
+│   ├── session.py          # Session state, persistence, plan steps tracking
+│   ├── runtime.py          # Request context (TaskStore, session, display handles)
 │   ├── 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
-│   │   └── explorer.py     # Explorer agent (fast, read-only codebase search)
+│   │   ├── base.py         # Shared prompt templates + build_instructions(role)
+│   │   ├── catalog.py      # AgentSpec registry — build / plan / executor / explorer
+│   │   └── planner.py      # review_plan() — small-model scope reviewer
 │   └── tools/
-│       ├── codebase.py     # 11 core tools
+│       ├── codebase.py     # Core tool implementations + GENERAL/EXECUTOR/PLANNER/EXPLORER sets
+│       ├── plan_mode.py    # enter_plan_mode tool (agent-invokable planner entry)
+│       ├── tasklist.py     # create_task_list / update_task / update_plan_step
 │       ├── ast_tools.py    # Tree-sitter code analysis
 │       ├── ranker.py       # File relevance ranking
 │       ├── mcp_client.py   # MCP client

aru_code-0.26.0/aru/__init__.py

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

{aru_code-0.25.2 → aru_code-0.26.0}/aru/agent_factory.py

@@ -1,4 +1,4 @@
-"""Agent creation: general-purpose and custom agent instantiation."""
+"""Agent creation: catalog-driven factory plus custom agent instantiation."""
 
 from __future__ import annotations
 
@@ -6,13 +6,40 @@ import functools
 import inspect
 import logging
 
+from agno.compression.manager import CompressionManager
+from agno.utils.log import log_warning
+
 from aru.agents.base import build_instructions as _build_instructions
+from aru.agents.catalog import AGENTS, AgentSpec
 from aru.config import AgentConfig, CustomAgent
 from aru.providers import create_model
 from aru.session import Session
 
 logger = logging.getLogger("aru.agent_factory")
 
+# Max chars for truncation fallback when compression fails
+_TRUNCATE_FALLBACK = 3000
+
+
+class _SafeCompressionManager(CompressionManager):
+    """CompressionManager that truncates on failure instead of leaving messages uncompressed.
+
+    Agno's default behavior: if compression returns None, the message stays with
+    compressed_content=None → should_compress() fires again → infinite retry loop.
+    This subclass marks failed messages with a truncated version so the loop moves on.
+    """
+
+    async def acompress(self, messages, run_metrics=None):
+        before = {id(m) for m in messages if m.role == "tool" and m.compressed_content is None}
+        await super().acompress(messages, run_metrics=run_metrics)
+        for msg in messages:
+            if id(msg) in before and msg.compressed_content is None:
+                content_str = str(msg.content or "")
+                msg.compressed_content = content_str[:_TRUNCATE_FALLBACK] + (
+                    "... [truncated, compression failed]" if len(content_str) > _TRUNCATE_FALLBACK else ""
+                )
+                log_warning(f"Compression fallback (truncate) for {msg.tool_name}")
+
 
 def _wrap_tools_with_hooks(tools: list) -> list:
     """Wrap tool functions to fire tool.execute.before/after plugin hooks.
@@ -148,44 +175,77 @@ def _apply_chat_hooks(instructions: str, model_ref: str, agent_name: str,
     return instructions, model_ref, max_tokens
 
 
-def create_general_agent(
-    session: Session,
-    config: AgentConfig | None = None,
-    model_override: str | None = None,
-    env_context: str = "",
+def _make_compression_manager() -> _SafeCompressionManager:
+    """Construct the safe compression manager used for every native agent."""
+    from aru.runtime import get_ctx
+    return _SafeCompressionManager(
+        model=create_model(get_ctx().small_model_ref, max_tokens=2048),
+        compress_tool_results=True,
+        compress_tool_results_limit=25,
+    )
+
+
+def create_agent_from_spec(
+    spec: AgentSpec,
+    session: Session | None = None,
+    model_ref: str | None = None,
+    extra_instructions: str = "",
 ):
-    """Create the general-purpose agent.
+    """Build an Agno Agent from a catalog spec.
 
-    Args:
-        env_context: Environment context (cwd, tree, git status) to include
-            in the system prompt. Placed in instructions so it's cacheable.
+    Single construction path for all native agents (build/plan/executor/explorer).
+    Resolves model, wraps tools with plugin hooks, applies chat.system.transform
+    and chat.params hooks, and attaches the safe compression manager.
+
+    `session` may be None for subagent specs that always use the small model.
     """
     from agno.agent import Agent
+    from aru.runtime import get_ctx
 
-    from aru.tools.codebase import GENERAL_TOOLS
-    tools = _wrap_tools_with_hooks(GENERAL_TOOLS)
+    if spec.small_model:
+        resolved_model = model_ref or get_ctx().small_model_ref
+    else:
+        if session is None:
+            raise ValueError(f"AgentSpec {spec.name!r} requires a session to resolve the model")
+        resolved_model = model_ref or session.model_ref
 
-    extra = config.get_extra_instructions() if config else ""
-    if env_context:
-        extra = f"{extra}\n\n{env_context}" if extra else env_context
-    model_ref = model_override or session.model_ref
-    instructions = _build_instructions("general", extra)
+    tools = _wrap_tools_with_hooks(spec.tools_factory())
+    instructions = _build_instructions(spec.role, extra_instructions)
 
-    # Apply chat hooks (system.transform + params)
-    instructions, model_ref, max_tokens = _apply_chat_hooks(
-        instructions, model_ref, "Aru", max_tokens=8192,
+    instructions, resolved_model, max_tokens = _apply_chat_hooks(
+        instructions, resolved_model, spec.name, max_tokens=spec.max_tokens,
     )
 
     return Agent(
-        name="Aru",
-        model=create_model(model_ref, max_tokens=max_tokens),
+        name=spec.name,
+        model=create_model(resolved_model, max_tokens=max_tokens),
         tools=tools,
         instructions=instructions,
         markdown=True,
+        compress_tool_results=True,
+        compression_manager=_make_compression_manager(),
         tool_call_limit=None,
     )
 
 
+def create_general_agent(
+    session: Session,
+    config: AgentConfig | None = None,
+    model_override: str | None = None,
+    env_context: str = "",
+):
+    """Create the general-purpose agent (thin wrapper around the catalog factory)."""
+    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(
+        AGENTS["build"],
+        session,
+        model_ref=model_override or session.model_ref,
+        extra_instructions=extra,
+    )
+
+
 def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
                                   config: AgentConfig | None = None,
                                   env_context: str = ""):