feat(tool): wait async result with taskId

[rudy2steiner]

Background

The main agent often needs to delegate several independent subtasks to subagents, let them run in parallel, and collect results according to task dependencies. The framework already has agent_spawn / agent_send, background execution via timeout_seconds=0, task_output, completion callbacks, and the existing ToolkitConfig.parallel tool execution capability. However, async result collection is still too coarse:

• The legacy wait_async_results call only waits for any message to arrive in the session inbox. It cannot express “wait until these specific tasks are all done”.
• After launching multiple async subagents, the main agent has to poll each task with task_output, with no explicit wait-all barrier.
• The responsibilities of wait_all, task-id based waiting, automatic delivery, and explicit polling need to be aligned across tool descriptions, middleware prompts, and docs.
• Wakeup only schedules a future reasoning opportunity. It does not mean the result has already been injected into the model context.

This PR closes the loop for parallel subagent orchestration: launch async work, wait when a dependency barrier is needed, and collect results without breaking the legacy inbox-based wait behavior.

Main Changes

• Add wait_async_results(task_ids=...) to wait until a specific comma-separated task set is terminal.
• Add wait_async_results(wait_all=true) to wait for the current snapshot of non-terminal tasks in the session.
• Return fast diagnostics for unknown task ids, empty wait-all snapshots, missing session context, and unavailable TaskRepository.
• Keep legacy wait_async_results(timeout_seconds) inbox-any behavior when no barrier parameters are provided.
• Keep existing guardrails: timeout clamping, consecutive empty-wait budget, and non-blocking alternatives in timeout messages.
• Clarify agent_spawn, task_output, and wait_async_results tool descriptions for sync, async, polling, and barrier collection.
• Update SubagentsMiddleware prompt guidance and English/Chinese docs for task decomposition, parallel spawn, short-first/long-later collection, automatic delivery, and wakeup boundaries.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[codecov]

Codecov Report

❌ Patch coverage is 71.42857% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...scope/harness/agent/tool/WaitAsyncResultsTool.java	71.42%	17 Missing and 9 partials ⚠️

📢 Thoughts on this report? Let us know!