fix(handoff): return wrong-tool correction to LLM instead of silent execute

[JumpLink]

When the model calls a handoff tool with a wrong name (e.g. duplicated suffix like lc_transfer_to_agent_...7yu7yu instead of ...7yu), we no longer execute the handoff silently with the resolved name. We return a ToolMessage that tells the LLM the used name was wrong and suggests the correct tool name, so the LLM can call the correct tool in the next turn and select the right agent itself.

Out of Scope?

I understand that the PR is out of scope and may simply be a problem with the model used. I have integrated it as a workaround and didn't want to leave it unmentioned and is more likely a workaround.

Problem

• Handoff tools are graph-managed; the host’s loadTools does not provide them.
• If the model emits a slightly wrong tool name (e.g. duplicated suffix), the call was previously resolved via prefix match and executed as a direct handoff with the correct name.
• That hid the mistake from the model and didn’t give it a chance to correct itself.

Solution

• ToolNode (dev/agents/src/tools/ToolNode.ts): For handoff calls that are not in directToolNames but can be resolved via resolveHandoffToolName() (prefix match), we do not add them to direct execution.
• Instead we create a ToolMessage per such call with:
  • a short explanation that the used tool name doesn’t match a registered handoff tool,
  • the name that was used,
  • the correct handoff tool name,
  • an instruction to call that tool instead.
• These messages are appended to the tool outputs; handleRunToolCompletions is called for them so the UI shows the step and the correction.
• The LLM sees the correction as a normal tool result and can issue a follow-up call with the suggested tool name.

Changes

• ToolNode.ts
  • Removed execution of resolved handoffs via directCallsResolved.
  • Added handoffCorrectionMessages: one ToolMessage per resolved handoff with the text above.
  • Outputs are now directOutputs + handoffCorrectionMessages + eventOutputs.
  • JSDoc for resolveHandoffToolName updated to describe the new behaviour.
  • Explicit null/size check for directToolNames to satisfy lint.
• docs/HANDOFF_TOOL_NAME_ANALYSIS.md: Conclusion and “Defensive fix” step updated to describe “return correction message to LLM” instead of “execute as direct”.

Related

• Fixes Handoff tool not found: wrong tool name (duplicated suffix) when transferring to agent #60