# Sub-Agents Documentation

## Overview

Sub-agents are background agent processes spawned from a parent agent run. They execute in isolated sessions and report results back to the requesting chat channel upon completion.

## Key Commands

The `/subagents` slash command manages sub-agent runs:
- `list`: View all active sub-agents
- `stop`: Terminate specific or all sub-agents
- `log`: Access execution logs with optional filters
- `info`: Display run metadata and session details
- `send`: Transmit messages to running sub-agents

## Spawning Sub-Agents

The `sessions_spawn` tool initiates sub-agent runs with these parameters:
- `task` (required): The work assignment
- `label`, `agentId`, `model`, `thinking`: Optional configuration overrides
- `runTimeoutSeconds`: Execution time limit
- `cleanup`: Archive behavior (`delete` or `keep`)

## Design Principles

Sub-agents do not get session tools by default, maintaining security boundaries. They cannot spawn their own sub-agents, preventing cascade complexity. Each maintains separate token accounting for cost management.

## Session Management

Sub-agent sessions use the format `agent:<agentId>:subagent:<uuid>`. Authentication resolves through the target agent's configuration, with main agent profiles available as fallbacks. Sessions auto-archive after 60 minutes by default.

## Announce Mechanism

Upon completion, sub-agents report results through an announce step. These messages include:
- Status (success, error, timeout, unknown)
- Result summary from the announce step
- Error details and contextual notes
- Runtime metrics and token usage statistics

## Tool Restrictions

By default, sub-agents cannot access session-specific tools like `sessions_list`, `sessions_history`, `sessions_send`, or `sessions_spawn`. Administrators can customize allowed tools through configuration.

## Concurrency & Performance

Sub-agents operate on a dedicated queue lane with configurable maximum concurrent runs (default: 8). Each maintains independent context and resource usage for cost optimization on heavy workloads.