Aetheel/docs/future-changes.md

Future Changes

Planned features and architectural improvements for Aetheel.

---

Agent Teams & Delegation

The current subagent system spawns generic background workers that share the main agent's identity. The goal is to evolve this into a proper agent team architecture where specialized agents with their own roles, tools, and identity files can be created and coordinated.

Vision

A main agent (e.g. "CTO") talks to the user and delegates tasks to specialist agents (e.g. "Programmer", "Designer") that each have their own personality, tool access, and domain expertise. Results flow back through the main agent or directly to the channel.

User ──► Main Agent (CTO)
              │
              ├──► Programmer Agent
              │      • Own SOUL.md (code-focused personality)
              │      • Tools: Bash, Read, Write, Edit, Grep
              │      • Model: claude-sonnet for speed
              │
              ├──► Designer Agent
              │      • Own SOUL.md (design-focused personality)
              │      • Tools: WebSearch, WebFetch, Read
              │      • Model: claude-opus for creativity
              │
              └──► Researcher Agent
                     • Own SOUL.md (thorough, citation-heavy)
                     • Tools: WebSearch, WebFetch
                     • Model: gemini-2.5-pro for large context

What Exists Today

• SubagentManager spawns background tasks via [ACTION:spawn|<task>]
• SubagentBus provides pub/sub messaging between subagents
• Claude Code's Task, TaskOutput, TeamCreate, SendMessage tools are already in the allowed tools list
• All subagents currently share the same identity files (SOUL.md, USER.md, MEMORY.md)

How NanoClaw Does It

NanoClaw (the inspiration project) takes a fundamentally different approach — container-based isolation with per-group identity:

Architecture:

• Each chat group gets its own folder (groups/{name}/) with its own CLAUDE.md (identity/memory)
• A groups/global/CLAUDE.md provides shared context readable by all groups
• Each agent runs inside an Apple Container (lightweight Linux VM) with only its own folder mounted
• The main channel has elevated privileges (can manage groups, write global memory, schedule tasks for any group)
• Non-main groups can only access their own folder + read-only global memory

Agent Teams (Swarm):

• Claude Code has native TeamCreate, SendMessage tools for multi-agent orchestration
• NanoClaw enables this via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var in the container
• The lead agent creates teammates using Claude's built-in team tools
• Each teammate gets instructions to use send_message with a sender parameter
• On Telegram, each sender gets a dedicated bot identity (pool of pre-created bots renamed dynamically)
• The lead agent coordinates but doesn't relay every teammate message — users see them directly

Key design decisions:

• Identity is per-group, not per-agent — a "programmer" agent in one group is different from a "programmer" in another
• The AI itself decides when to create teams and how to structure them — it's not pre-configured
• Container isolation means agents can't read each other's files or sessions
• IPC is file-based (JSON files in a watched directory), not in-memory pub/sub
• Secrets are passed via stdin, never mounted as files

What Needs to Be Built

1. Agent Definitions

A new agents/ directory in the workspace where each agent gets its own folder:

~/.aetheel/workspace/agents/
├── programmer/
│   ├── AGENT.md          # Role, description, triggers
│   ├── SOUL.md           # Agent-specific personality
│   └── SKILL.md          # Optional: domain-specific skills
├── designer/
│   ├── AGENT.md
│   ├── SOUL.md
│   └── SKILL.md
└── researcher/
    ├── AGENT.md
    └── SOUL.md

AGENT.md frontmatter:

---
name: programmer
description: Senior software engineer specializing in Python and system design
triggers: [code, implement, build, fix, debug, refactor, PR]
model: anthropic/claude-sonnet-4-20250514
engine: claude
tools: [Bash, Read, Write, Edit, Glob, Grep]
max_turns: 5
---

2. Agent-Aware Routing

The main agent decides which specialist to delegate to based on:

• Explicit user request ("ask the programmer to...")
• Trigger word matching from AGENT.md
• AI-driven routing (the main agent's system prompt tells it about available agents)

New action tag: [ACTION:delegate|<agent_name>|<task>]

3. Per-Agent Identity

Each agent gets its own system prompt built from:

1. Its own SOUL.md (personality/role)
2. Shared USER.md (user context is universal)
3. Shared MEMORY.md (long-term memory is universal)
4. Its own skills from SKILL.md
5. Its tool restrictions from AGENT.md

4. Agent-to-Agent Communication

Extend SubagentBus to support:

• Named channels per agent (not just task IDs)
• Request/response patterns (agent A asks agent B, waits for reply)
• Broadcast messages (main agent sends context to all agents)
• Result aggregation (main agent collects results from multiple agents)

5. Team Orchestration Patterns

• Sequential: Programmer writes code → Designer reviews UI → Main agent summarizes
• Parallel: Programmer and Designer work simultaneously, main agent merges results
• Supervisory: Main agent reviews each agent's output before sending to user
• Collaborative: Agents can message each other directly via the bus

6. Chat Commands

team list                    # List defined agents
team status                  # Show which agents are active
team create <name>           # Interactive agent creation
team remove <name>           # Remove an agent definition
delegate <agent> <task>      # Manually delegate to a specific agent

7. Claude Code Native Teams

Claude Code already has TeamCreate, TeamDelete, SendMessage tools. These allow the AI itself to create and manage teams during a session. The integration path:

• When using Claude Code engine, the AI can use these tools natively
• Aetheel wraps the results and routes messages back to the right channel
• Agent definitions in AGENT.md pre-configure teams that get created on startup

Implementation Priority

There are two paths — pick based on complexity appetite:

Path A: Lightweight (extend current SubagentManager)

1. Agent definition format (AGENT.md) and discovery
2. Per-agent identity file loading (own SOUL.md, shared USER.md/MEMORY.md)
3. [ACTION:delegate|agent|task] tag parsing
4. Agent-specific system prompt building with tool restrictions
5. Chat commands for team management
6. Agent-to-agent communication via extended bus

Path B: Full isolation (NanoClaw-style containers)

1. Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 for Claude Code runtime
2. Per-group workspace folders with own CLAUDE.md
3. Container-based agent execution (Docker or Apple Container)
4. File-based IPC between host and containers
5. Mount security (allowlist, per-group isolation)
6. Bot pool for Telegram/Discord (each agent gets its own bot identity)
7. Lead agent orchestration via Claude's native team tools

Path A is simpler and works today. Path B is more secure and scalable but requires container infrastructure.

NanoClaw Reference Files

Key files to study in inspirations/nanoclaw/:

• src/container-runner.ts — Container spawning, volume mounts, IPC, per-group isolation
• src/types.ts — RegisteredGroup, ContainerConfig, AdditionalMount types
• groups/global/CLAUDE.md — Global identity shared across all groups
• groups/main/CLAUDE.md — Main channel with elevated privileges
• .claude/skills/add-telegram-swarm/SKILL.md — Full agent swarm implementation for Telegram
• docs/SPEC.md — Complete architecture spec
• docs/SECURITY.md — Security model for container isolation

---

Other Planned Changes

Security Fixes (from security-audit.md)

• Path containment check in memory/manager.py read_file()
• Mandatory webhook auth when enabled
• Input schema validation on webhook POST bodies
• Stricter cron expression validation
• Rate limiting on HTTP endpoints
• WebSocket authentication for WebChat
• Dependency version pinning

Persistent Usage Stats

Currently usage stats reset on restart. Persist to SQLite so usage command shows lifetime stats, daily/weekly/monthly breakdowns, and cost trends.

Multi-Model Routing

Route different types of requests to different models automatically:

• Quick questions → fast/cheap model (sonnet, gpt-4o-mini)
• Complex reasoning → powerful model (opus, o1)
• Large context → big-context model (gemini-2.5-pro)

Conversation Branching

Allow users to fork a conversation into a new thread with a different model or agent, then merge results back.