fix(tool): return suspended results for external tools

[jsiu93]

AgentScope-Java Version

2.0.0-SNAPSHOT

Description

Fixes #1582.

External tools were short-circuited with Mono.error(new ToolSuspendException()) before the executor's ToolSuspendException conversion path, so batch execution could convert external tool calls into generic error results.

This PR:

• Returns ToolResultBlock.suspended(toolCall) directly for external tools in ToolExecutor
• Emits RequireExternalExecutionEvent when the agent event stream sees suspended tool calls
• Updates external-tool Javadocs to describe the direct suspended-result flow
• Adds executor and ReActAgent regressions for TOOL_SUSPENDED, RUNNING state, and external execution events

How to test:

• mvn -pl agentscope-core -Dtest=ToolExecutorTest,ReActAgentNewLoopReplyTest test
• mvn -pl agentscope-core -Dtest=ReActAgentHitlTest,ExternalToolSupportTest,AgentEventStreamTest,GenerateReasonTest test
• mvn -pl agentscope-core test

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (external-tool Javadocs)
• Code is ready for review

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This is a clean, well-targeted fix for issue #1582. The core change — replacing Mono.error(new ToolSuspendException()) with Mono.just(ToolResultBlock.suspended(toolCall)) — eliminates exception-driven control flow for external tools, making the batch execution path more predictable and robust. The addition of RequireExternalExecutionEvent provides a proper event-stream signal for external orchestrators. Test coverage is solid at both unit (ToolExecutorTest) and integration (ReActAgentNewLoopReplyTest) levels. One minor behavior change worth noting: external tools now bypass the group activation check (see inline comment).

(inline comments could not be attached — line numbers fell outside PR hunks. See archived report.)