agent.unobservable_handoff

What it checks

Crux reports agent.unobservable_handoff when an authored agent declares a handoff target, but the target agent is not visible in the project index.

Why it matters

Agent handoffs are control-flow boundaries. When the target is index-visible, Crux can connect the source agent, delegated work, trace spans, quality coverage, and architecture map into one inspectable path. If the target is missing, users can see disconnected spans or orphaned tool calls instead of a trustworthy handoff story.

How to fix

Define and export the target agent with a stable id, or update the handoff id so it matches the authored target.

export const billing = agent({
  id: 'billing',
  prompt: billingPrompt,
})

export const triage = agent({
  id: 'triage',
  prompt: triagePrompt,
  handoffs: ['billing'],
})

When to suppress

Suppress this rule only when the handoff intentionally targets an agent outside this index and you accept that Crux cannot fully connect that authored path yet.

// crux-lint-disable-next-line agent.unobservable_handoff -- external agent is registered at runtime
export const triage = agent({ id: 'triage', handoffs: ['external-billing'] })

Rule metadata

• Rule id: agent.unobservable_handoff
• Category: observability
• Maturity: preview
• Default profiles: recommended, strict
• Default severity: warning