Feature Request: Async Task Management - Non-blocking Subagent Dispatch

[jeasoncc]

Summary

Add support for asynchronous task management where the main session can dispatch subagents and continue interacting with the user while tasks execute in the background, rather than blocking until completion.

Current Behavior

When using the Task tool to dispatch subagents:

1. Main session dispatches a subagent
2. Main session blocks waiting for the subagent to complete
3. User cannot interact with main session during execution
4. After subagent returns, main session continues

This is a synchronous, blocking model.

Desired Behavior

The main session should act as a "secretary" or task coordinator:

1. Main session dispatches one or more subagents
2. Main session immediately returns and remains interactive
3. User can continue conversing with main session
4. User can dispatch additional tasks
5. Main session can query task status or receive notifications when tasks complete
6. Main session can retrieve results asynchronously

This is an asynchronous, non-blocking model.

Use Cases

1. Long-Running Tasks

User: "Refactor the authentication module and update all the tests"
Agent: "I've dispatched a subagent to handle that (task-123). What else can I help with?"
User: "Also, can you explain how the payment system works?"
Agent: "Sure, let me explain... [provides explanation]"
Agent: "By the way, task-123 just completed. The refactoring is done."

2. Multiple Independent Tasks

User: "Fix all the failing tests in these 5 files"
Agent: "I've dispatched 5 subagents, one per file. I'll monitor their progress."
User: "While they're running, show me the git history for the auth module"
Agent: [Shows git history while tasks run in background]
Agent: "3 of 5 tasks completed. 2 still running..."

3. Interactive Task Management

User: "Start implementing the new dashboard feature"
Agent: "Task dispatched (task-456). This will take a while."
User: "Actually, can you pause that? I need to check something first"
Agent: "Task paused. Let me know when you're ready to resume."

Technical Requirements

To support this pattern, OpenCode would need:

1. Non-blocking Task API

// Current (blocking)
const result = await Task("Do something")

// Proposed (non-blocking)
const taskId = await Task.dispatch("Do something", { async: true })
// Returns immediately with task ID

2. Task Status Query

const status = await Task.status(taskId)
// Returns: "pending" | "running" | "completed" | "failed"

3. Result Retrieval

const result = await Task.getResult(taskId)
// Returns result when task is completed

4. Task Notifications (Optional)

// System could notify main session when tasks complete
// Or main session could poll periodically

5. Task Management

await Task.cancel(taskId)
await Task.pause(taskId)
await Task.resume(taskId)
await Task.listAll() // Show all active tasks

Benefits

1. Better UX: User doesn't have to wait for long-running tasks
2. Parallelization: Multiple tasks can run truly in parallel
3. Flexibility: User can change priorities mid-execution
4. Efficiency: Main session remains responsive and useful
5. Scalability: Handle complex multi-task workflows more naturally

Implementation Considerations

• Task isolation: Ensure tasks don't interfere with each other
• Resource management: Limit concurrent tasks to prevent overload
• State management: Track task status, results, and errors
• Error handling: How to handle task failures asynchronously
• Context preservation: Main session needs to remember task context when results arrive

Alternative Approaches

If full async support is complex, consider intermediate solutions:

1. Fire-and-forget mode: Dispatch tasks that don't return results
2. Background monitoring: Main session periodically checks task status
3. Manual session management: User manages multiple sessions manually (current workaround)

Related

This pattern is similar to:

• Job queues in web applications
• Background workers in task processing systems
• Async/await patterns in modern programming languages

---

Context: This request comes from a user workflow where they want to dispatch multiple complex tasks and continue working with the AI while those tasks execute, rather than waiting for each to complete sequentially.

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• The title should start with [FEATURE]: to follow the feature request template (e.g., [FEATURE]: Async Task Management - Non-blocking Subagent Dispatch)
• The feature request template requires a verification checkbox confirming you searched for existing issues before submitting
• The issue appears to be AI-generated (extensive structured content, TypeScript API proposals, multiple code blocks). We ask that issues be written in your own words describing the actual problem you faced

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• [feat] True Async/Background Sub-Agent Delegation #5887: True Async/Background Sub-Agent Delegation — nearly identical request for non-blocking subagent execution with a fire-and-forget model
• Support background tool execution #9462: Support background tool execution — similar request for background tool/task execution with status queries (closed)

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

This issue has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new issue that follows our issue templates.