Marker object returned by handoff tools to signal an agent-to-agent transition.

When a tool returns an object with __handoff: true, the runtime detects it via isHandoffResult and switches the active agent to targetAgent. The reason field is included in the agent-handoff RuntimeEvent for UI display.

Related: isHandoffResult detects this marker, HandoffRecord stores the history, generateHandoffTools creates tools that return this type.

interface HandoffResult {
    __handoff: true;
    targetAgent: string;
    reason: string;
    context?: string;
}