Subagents

Learn how to use the spawn tool to create asynchronous subagents for parallel task execution

Overview

PicoClaw supports spawning subagents - independent agent instances that can execute tasks asynchronously without blocking the main agent. This is particularly useful for:

• Long-running tasks (web searches, API calls)
• Parallel task execution
• Background jobs triggered by heartbeat
• Tasks that need isolation from the main conversation context

How Subagents Work

When you use the spawn tool, PicoClaw creates a new agent instance with:

• Independent context - No access to the parent’s conversation history
• Same workspace - Inherits workspace path and restrictions
• Tool access - Has access to all tools (message, web_search, exec, etc.)
• Isolated execution - Runs asynchronously without blocking the parent

Subagents inherit the same security restrictions as the parent agent (workspace sandboxing, exec safety patterns, etc.)

Using the Spawn Tool

Basic Syntax

{
  "tool": "spawn",
  "parameters": {
    "prompt": "Search the web for recent AI news and summarize the top 3 stories"
  }
}

With Target Agent

{
  "tool": "spawn",
  "parameters": {
    "prompt": "Analyze this code and suggest improvements",
    "target_agent_id": "code-reviewer"
  }
}

Common Use Cases

Heartbeat Long-Running Tasks

In HEARTBEAT.md, spawn subagents for tasks that take time:

# Periodic Tasks

## Quick Tasks (respond directly)
- Report current time
- Check workspace size

## Long Tasks (use spawn for async)
- Search the web for AI news and summarize
- Check email and report important messages
- Monitor system logs for errors

The main agent spawns a subagent for each long task, then continues to the next heartbeat task. The subagent uses the message tool to deliver results directly to the user.

Parallel Processing

Execute multiple independent tasks simultaneously:

{
  "tool": "spawn",
  "parameters": {
    "prompt": "Search for 'PicoClaw features' and summarize"
  }
}

{
  "tool": "spawn",
  "parameters": {
    "prompt": "Check GitHub issues and list any critical bugs"
  }
}

Both subagents run concurrently and deliver results via the message tool.

Specialized Agent Routing

Route tasks to specialized agents:

{
  "tool": "spawn",
  "parameters": {
    "prompt": "Review this pull request for security issues",
    "target_agent_id": "security-reviewer"
  }
}

Subagent Communication

Subagents communicate with users through the message tool:

Main Agent
    ↓
  spawn
    ↓
Subagent (independent context)
    ↓
  executes task
    ↓
  message tool → User receives result

Subagents don’t return data to the parent agent. They deliver results directly to the user via the message tool or take actions using other tools.

Configuration

Allow List

Subagents can be restricted by configuration:

{
  "agents": {
    "defaults": {
      "subagents": {
        "allowlist": ["default", "code-reviewer", "security-audit"]
      }
    }
  }
}

If allowlist is set, only agents in the list can be spawned.

Agent-Specific Subagent Config

{
  "agents": {
    "entries": [
      {
        "id": "main-agent",
        "subagents": {
          "allowlist": ["researcher", "coder"]
        }
      }
    ]
  }
}

Best Practices

Use for I/O-bound tasks

Web searches, API calls, file operations - anything that waits for external resources

Keep prompts focused

Give subagents clear, specific tasks with all necessary context in the prompt

Don't overuse

Each subagent uses memory and resources. Use judiciously for truly parallel work

Handle errors gracefully

Subagents may fail independently. Ensure main flow continues

Security

Subagents inherit all security restrictions:

• Workspace sandbox - Same restrict_to_workspace setting
• Exec safety - Same dangerous pattern blocks
• Path restrictions - Same allow/deny path patterns
• Tool access - Same tool availability

There is no way to bypass security through subagents.

Example: Heartbeat with Spawn

HEARTBEAT.md:

# Periodic Tasks

- Use spawn to search for "AI agent frameworks" and summarize top 3 results
- Use spawn to check my calendar and remind me of upcoming events

Agent behavior:

1. Agent reads HEARTBEAT.md
2. Spawns first subagent with search task
3. Spawns second subagent with calendar task
4. Returns HEARTBEAT_OK immediately
5. Subagents execute independently and message user with results

Troubleshooting

Subagent not spawning

• Check if target agent is in allowlist
• Verify agent ID exists in configuration
• Check logs for spawn errors

No response from subagent

• Ensure subagent uses message tool to deliver results
• Check if subagent completed successfully (logs)
• Verify channel context is available

Memory usage increasing

• Each subagent uses resources
• Limit concurrent subagents
• Use spawn only when necessary

Next Steps

Spawn Tool API

Complete API reference for the spawn tool

Heartbeat Feature

Learn about periodic tasks and HEARTBEAT.md

Message Tool

How subagents communicate with users

Agent Configuration

Configure agents and subagent allowlists