package agent

// Handoff is a placeholder describing a transfer of control to another character
// or subagent. It deliberately carries no orchestration: wiring the handover to
// the agent-to-agent bus and subagent lifecycle belongs to the orchestration
// layer (M3, DevDocs/design/04-运行时.md §2).
type Handoff struct {
	// Target is the identity (character or subagent) receiving control.
	Target string
	// Reason explains why the agent is handing off, for the orchestrator and
	// audit logs.
	Reason string
}

// NewHandoff builds a Handoff placeholder for the given target and reason.
func NewHandoff(target, reason string) *Handoff {
	return &Handoff{Target: target, Reason: reason}
}

// Handoff returns the agent's configured handoff placeholder, or nil when none
// was set. It is read-only: orchestration interprets it without mutating it.
func (a *Agent) Handoff() *Handoff { return a.handoff }