Add optional async sub-agent delegation with report-back and wait control

[TommyBez]

Motivation

• Enable delegating long-running or asynchronous work to sub-agents without blocking the parent agent, and optionally notify the parent when the sub-agent completes.

Description

• Extend invocation payload and dispatch paths to carry parentAgentId and reportBackToParent through agent-event-store, session-events, and the event workflow handler.
• Add waitForCompletion option to the sub-agent tool (tools/sub-agents/agent-tool.ts) to control whether the parent waits for the child run or returns immediately.
• When waitForCompletion is false, the tool queues the child run and returns immediately with a started message; when true, it collects child messages and returns the final text as before.
• Implement maybeReportBackToParent in the invocation handler to dispatch a short invocation back to the parent agent with the child final text when reportBackToParent is set, plus helpers resolveAgentUserId and extractFinalAssistantText.

Testing

• Ran TypeScript type-check and project build to validate signatures and imports, which succeeded.
• Executed the existing automated test suite (unit/integration tests) and verified they passed after the changes.

---

Codex Task

Summary by CodeRabbit

• New Features
  • Sub-agents can now report completion status back to parent agents, enabling better agent orchestration and coordination.
  • Sub-agent invocations now support a waitForCompletion option—tasks can run asynchronously without blocking for results.
  • Enhanced parent-child agent tracking with improved linkage metadata for multi-level agent hierarchies.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v0-personal-assistant-agent	Ready	Preview, Comment, Open in v0	May 17, 2026 7:15pm

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 6c8eb87f-2bb8-45db-b06e-da2647b298fa

📥 Commits

Reviewing files that changed from the base of the PR and between cea5390 and 881e8e7.

📒 Files selected for processing (5)

• agent-runtime/server/agent-event-store.ts
• agent-runtime/server/session-events.ts
• agent-runtime/workflows/events/workflow.ts
• agent-runtime/workflows/session/handlers/handle-invocation.ts
• tools/sub-agents/agent-tool.ts

---

Walkthrough

This PR extends the sub-agent invocation system to support parent-agent completion reporting. The invocation event payload gains a parentAgentId field, dispatchInvocation requires this identifier and an optional reporting flag, the handler conditionally notifies parents of successful completion by dispatching a new parent invocation event with the child's final text, and the sub-agent tool gains a waitForCompletion option to return immediately instead of streaming completion.

Changes

Parent-agent completion reporting feature

Layer / File(s)	Summary
Event payload schema extension agent-runtime/server/agent-event-store.ts	The invocation payload type now includes an optional parentAgentId?: string | null field to carry parent-agent identity through events.
Dispatcher and workflow routing updates agent-runtime/server/session-events.ts, agent-runtime/workflows/events/workflow.ts	dispatchInvocation now requires parentAgentId and accepts optional reportBackToParent flag; these fields flow through event enqueueing and workflow routing to the invocation handler.
Invocation handler parent reporting agent-runtime/workflows/session/handlers/handle-invocation.ts	Handler accepts parent context and reporting flag, extracts final assistant text from streamed messages after successful execution, and conditionally dispatches a new invocation event to the parent agent with dynamically resolved user identity from the database. Utility helpers extract final assistant text and resolve agent user IDs.
Sub-agent tool async execution mode tools/sub-agents/agent-tool.ts	Sub-agent tool input schema adds optional waitForCompletion boolean; execution branches on this flag to either return immediately with a run ID (when false) or stream to completion (when true, default). Helper dispatchSubAgentInvocation forwards reportBackToParent flag based on the wait mode, and documentation updated to describe async delegation pattern.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A rabbit hops through nested flows,
Where parents trace what child agent knows.
Report back when the task is through,
Or dash away—the choice is true!
Completion rings, or fire and go,
The agent network starts to grow. 🌳

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 881e8e7dec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Make parent report-back failures non-fatal

Awaiting maybeReportBackToParent in the main try means any dispatch error (for example, parent agent deleted/disabled between queue and completion, or a transient DB failure) is treated as a child-run failure, because control falls into failInvocation after the child result has already been finalized. This mislabels successful async sub-agent runs as failed and can break monitoring/automation that depends on run status.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Use collision-resistant token for report-back invocation

The report-back streamToken is derived only from Date.now(), but dispatchInvocation builds idempotency keys from parentToolCallId ?? streamToken (with parentRunId set to root here). If two async children report back to the same parent within the same millisecond, they generate the same idempotency key and one event is dropped by the unique idempotency constraint, causing a lost completion notification.

Useful? React with 👍 / 👎.