โ† Back to cheatsheet

Subagent Events System

OpenClaw v2026.3.1 replaces ad-hoc subagent handoff with typed task_completion internal events, providing consistent rendering and reliable state transitions across all announcement paths.

v2026.3.1Multi-Agent

What You Need to Know

Subagents are spawnable child agents that handle delegated tasks โ€” a main assistant might spawn a research subagent to gather information, then synthesize the results. Before this update, the handoff between subagent and parent was handled through ad-hoc message passing, which could produce inconsistent rendering depending on the channel and announcement configuration.

Typed task_completion events standardize how subagents report back. When a subagent finishes its task, it emits a structured event with the result, status (success, failure, partial), and metadata. The parent agent receives this event through a well-defined interface rather than parsing free-form text, making multi-agent orchestration more reliable.

Consistent rendering means the task completion looks the same whether it is announced in Telegram, Discord, webchat, or any other channel. The formatting adapts to each channel's capabilities (rich cards in Discord, clean text in Telegram) but the content and structure are identical. Users no longer see different representations of the same subagent result depending on where they are chatting.

This also improves error handling in multi-agent workflows. If a subagent fails, the task_completion event includes structured error information that the parent can act on โ€” retry with different parameters, escalate to the user, or fall back to an alternative approach. Previously, error handling depended on the parent parsing error messages from the subagent's text output.

For developers building custom multi-agent workflows, the typed event system provides a clean API for composing agent behavior. You can chain subagents, fan out parallel tasks, and aggregate results through a predictable event-driven pattern rather than prompt engineering around message formatting.