refactor(toolkit): update default execution to parallel and enhance documentation

[chickenlj]

followup of #2529

[Copilot]

Pull request overview

This PR is a follow-up to #2529 that changes the default tool execution mode to parallel and updates harness tooling/docs so subagent orchestration semantics (sync parallel fan-out/fan-in, async barrier waiting, legacy inbox-any waiting) are clearer and more consistent.

Changes:

• Flip ToolkitConfig default to parallel=true and update core Javadocs to reflect parallel-by-default execution.
• Enhance wait_async_results barrier mode to embed terminal task results directly in the tool return (and mark tasks delivered), plus clarify legacy inbox-any behavior across docs/prompts.
• Update HarnessAgent defaults and documentation (EN/ZH, v1/v2) to match the new parallel default and recommended usage patterns.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/v2/zh/docs/harness/subagent.md	Clarifies sync parallel delegation defaults and barrier vs legacy inbox-any waiting (ZH).
docs/v2/en/docs/harness/subagent.md	Clarifies sync parallel delegation defaults and barrier vs legacy inbox-any waiting (EN).
docs/v1/zh/docs/task/tool.md	Updates toolkit config example and default value documentation (ZH).
docs/v1/en/docs/task/tool.md	Updates toolkit config example and default value documentation (EN).
agentscope-harness/src/test/java/io/agentscope/harness/agent/tool/WaitAsyncResultsToolTest.java	Extends tests to assert inbox-any labeling and barrier embedding + delivery marking behavior.
agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/WaitAsyncResultsTool.java	Implements barrier result embedding + delivery marking; updates tool descriptions and legacy-path messaging.
agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/AgentSpawnTool.java	Updates tool description to state sync calls run in parallel by default and how to opt out.
agentscope-harness/src/main/java/io/agentscope/harness/agent/middleware/SubagentsMiddleware.java	Updates middleware prompt guidance to prefer barrier modes and clarify legacy inbox-any.
agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgentBuilderSupport.java	Switches default toolkit construction to the Builder’s default-toolkit helper.
agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java	Uses a documented default-toolkit factory (now aligned with parallel-by-default).
agentscope-core/src/main/java/io/agentscope/core/tool/ToolkitConfig.java	Changes default parallel to true and updates documentation accordingly.
agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java	Updates constructor Javadoc to reflect parallel-by-default configuration.

Suppressed comments (4)

agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/WaitAsyncResultsTool.java:194

• This legacy inbox-any message recommends wait_all=true but doesn’t spell out the full call form. Using wait_async_results(wait_all=true) avoids ambiguity for tool callers.

                return "Async results have arrived (inbox-any: at least one message). "
                        + "Continue reasoning — the results will be injected into your context "
                        + "automatically. Prefer wait_async_results(task_ids=...) or "
                        + "wait_all=true when you need every task in a group.";

agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/WaitAsyncResultsTool.java:393

• Same ambiguity as the other legacy-path success messages: wait_all=true should be shown as wait_async_results(wait_all=true) so users know it’s a parameter to this tool.

            return "Async results have arrived (inbox-any: at least one message). "
                    + "Continue reasoning — the results will be injected into your context "
                    + "automatically. Prefer wait_async_results(task_ids=...) or "
                    + "wait_all=true when you need every task in a group.";

agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/WaitAsyncResultsTool.java:371

• When a task fails, err.getMessage() (or its cause message) can be null, producing an unhelpful Error:\nnull output. Falling back to the exception class name makes the embedded barrier result more actionable.

                Exception err = task.getError();
                sb.append("Error:\n").append(err.getMessage()).append('\n');
                if (err.getCause() != null) {
                    sb.append("Cause: ").append(err.getCause().getMessage()).append('\n');
                }

agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/WaitAsyncResultsTool.java:376

• trim() will strip trailing whitespace from the entire tool output, which can unintentionally alter the embedded result payload of the last task (e.g., if it ends with newlines or spaces). It’s safer to return the built string as-is.

        return sb.toString().trim();

[codecov]

Codecov Report

❌ Patch coverage is 60.52632% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...scope/harness/agent/tool/WaitAsyncResultsTool.java	62.50%	9 Missing and 3 partials ⚠️
...cope/harness/agent/HarnessAgentBuilderSupport.java	40.00%	0 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!