Delegation

Delegation lets Mona spawn isolated child agents for parallel work. This is powerful for multi-step tasks that can be broken into independent subtasks.

When to delegate

• Parallel research — Search multiple sources simultaneously
• Multi-file work — Edit several files at once
• Code review — Review different parts of a PR in parallel
• Data processing — Process multiple datasets concurrently

Basic delegation

# Inside a Python script or code execution block
from monoclaw import delegate_task

results = await delegate_task([
    {"prompt": "Summarize the README.md", "tools": ["file_read"]},
    {"prompt": "Check for security issues in src/auth.ts", "tools": ["file_read", "terminal"]},
    {"prompt": "List all TODO comments in the codebase", "tools": ["terminal"]},
])

Each task runs in an isolated child agent with its own context and tools.

Delegation from chat

Delegate these tasks in parallel:
1. Read README.md and summarize the project
2. Check package.json for outdated dependencies
3. Run the test suite and report failures

Mona will spawn child agents, monitor their progress, and synthesize the results.

Child agent isolation

Child agents are isolated in several ways:

• Separate context — Each child has its own conversation history
• Tool restrictions — Child agents only get the tools you specify
• File sandboxing — Children operate within a scoped directory
• Timeout — Child agents have a default 5-minute timeout

Configuration

# ~/.monoclaw/config.yaml
delegation:
  max_agents: 5          # Max concurrent child agents
  default_timeout: 300   # Seconds
  share_memory: true     # Share parent memory with children

Return values

Child agents return structured results:

{
    "status": "success",  # success | error | timeout
    "result": "...",      # The agent's output
    "tools_used": [...],  # Tools invoked
    "duration": 45.2      # Seconds elapsed
}

Error handling

If a child agent fails:

• The parent agent is notified
• Other child agents continue running
• Failed tasks can be retried or handled gracefully

Best practices

• Keep tasks focused — Each child should have one clear objective
• Limit concurrency — Too many parallel agents can hit API rate limits
• Specify tools — Give children only the tools they need
• Set timeouts — Prevent runaway child agents
• Synthesize results — The parent should combine child outputs into a coherent response

Limits

• Max concurrent agents — 5 by default
• Max nesting — 2 levels (parent → child → grandchild)
• Total execution time — 30 minutes for all delegated tasks