feat(core): support returnDirect tool result short-circuit

[xzxiaoshan]

feat(core): 支持 returnDirect 工具语义

摘要

returnDirect 是工具调用的循环控制开关：工具执行成功后，结果不再交回模型推理，直接作为本轮最终输出返回调用方，对应 Spring AI 的 @Tool(returnDirect = true) 。

• 默认 false：结果喂回模型继续推理。
• true：跳过下一轮模型调用，结果直接返回。
• 一轮多个工具时：仅当该轮所有成功工具都 returnDirect=true 且执行成功时才整体返回，否则喂回模型。

多工具语义

一个 batch 产出多个结果时按整批决定去向：

• 有 suspended → 走 TOOL_SUSPENDED 挂起，returnDirect 不生效。
• 否则，当且仅当批内所有成功工具都 returnDirect=true 且 state 为 SUCCESS → 返回 TOOL_RETURN_DIRECT。
• 否则继续循环，全部结果喂回模型。

实现

returnDirect 触发的本质，是把工具结果「搬进消息序列」充当本轮最终答案。结构上做两件事：

• 结果提升：完整工具结果提升为一条合成的 assistant 消息，作为本轮最终输出写入 context 并返回，并打上 TOOL_RETURN_DIRECT 标记。
• 占位保住序列：messages 是完整性的表达，必须维持 tool call → tool result → assistant 的闭环。原 tool_result 保留、内容换成占位句：Tool call completed. The result has been presented to the user as the final output of this turn.。占位句作为 tool result 承接 tool call 的「语言表达」，合成的 assistant「模拟 LLM」收口。这样既避免结果重复，也满足供应商「每个 tool_use 后必须紧跟 tool_result」的要求。

判定上同时校验工具声明与结果状态：仅当该轮所有结果均 returnDirect=true 且 SUCCESS 才直接返回；suspended 挂起与 HITL 叫停优先于 returnDirect。

兼容性

• 默认关闭（returnDirect=false），无破坏性变更。
• 不改 ToolBase 位置构造器签名，内置工具无需改动。
• 新增枚举值只影响穷举 switch 的少数消费方；GenerateReasonTest 计数断言 11 → 12。

[codecov]

Codecov Report

❌ Patch coverage is 96.61017% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...e/src/main/java/io/agentscope/core/ReActAgent.java	95.65%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[xzxiaoshan]

完成 issue #1408 （新特性）
已重写 #1434 （可关闭）