Task Tool Timeouts & Early Termination in Multi-Agent Conductor Pattern

[DaveW001]

Question

Date: January 2, 2026
Environment: opencode Windows

Executive Summary

We are implementing a Multi-Agent "Conductor" Pattern where a primary agent orchestrates specialized sub-agents (Researcher, Writer) using the Task tool.

We are encountering a critical issue where tasks exceeding a short duration (~30-60s) return only a session_id string to the conductor, and the sub-agent session appears to terminate immediately, failing to complete the work (e.g., writing a file).

We have attempted to configure timeouts at the Provider and Agent level, but the behavior persists, suggesting a hardcoded timeout in the Task tool implementation or a signal handling issue that kills the child process.

1. Our Architecture

We are using the Conductor Pattern to keep context windows clean and enforce role separation.

Conductor (@content-factory):

• Role: Orchestration only. Never writes content itself.
• Action: Calls Task(subagent_type="researcher", prompt="...").
• Expectation: Waits for sub-agent to finish and return a string (e.g., "Report saved to path/to/file.md").

Sub-Agents (@researcher, @writer):

• Role: Execute heavy work (Search, Write 2k words).
• Action: Use tools (perplexity-search, write), then return a string result.

The Workflow Attempted

// Conductor calls Researcher
task({
  subagent_type: "researcher",
  prompt: "Research 'Government IT Trends'. Use perplexity. Save report to 'research.md'. Return path.",
  description: "Deep Research"
})

2. The Issue

• Behavior A: Short/Simple Tasks (Success)
• Task: "Write 3 bullet points." (Pure generation, < 10s)
• Result: The Task tool returns the actual string content.
• Outcome: Success.

Behavior B: Medium/Complex Tasks (Failure)

• Task: "Research X using Perplexity and write a report." (Tool use + Gen, > 60s)
• Result: The Task tool returns a metadata block:

<task_metadata>
session_id: ses_47ddfbc5affe...
</task_metadata>

• Critical Failure: The requested file (research.md) is NEVER created.
• Implication: The sub-agent did not just "detach"; it stopped running entirely.

3. Debugging & Attempts

We performed extensive testing to isolate the cause.

Attempt 1: Global Provider Timeout
Hypothesis: The model provider is timing out. Action: Updated opencode.json with extreme timeouts:

"provider": {
  "openai": { "options": { "timeout": 600000 } } // 10 minutes
}

Result: No change. Long tasks still return session_id immediately after ~60s.

Attempt 2: Agent-Level Timeout
Hypothesis: The agent definition needs its own timeout. Action: Added timeout: 600000 to .opencode/agent/researcher.md. Result: No change.

Attempt 3: Permission Fixes
Hypothesis: Sub-agent crashed due to missing permissions. Action: Discovered @researcher lacked perplexity-search permission. Fixed it. Result: "Medium" tasks (Find 5 stats) started working! BUT, "Full Research" (running multiple searches sequentially) still fails with session_id only.

Attempt 4: "Fire and Forget" (Async Polling)
Hypothesis: Maybe the session_id return is "working as designed" (async), and we just need to wait. Action:

Conductor sends task: "Write a 500-word essay to test.md."
Task tool returns session_id.
Conductor waits 60 seconds (bash sleep 60).
Conductor checks for test.md. Result: File never appears. Conclusion: The sub-agent session is killed or suspended the moment the Task tool "times out" and returns the session ID. It does not continue in the background.

4. Workaround: Chunking

The only reliable solution we found is to artificially break tasks into micro-chunks (30-60s max):
"Find 5 stats" (Return)
"Find 3 examples" (Return)
"Write report using stats+examples" (Return)
This defeats the purpose of an autonomous "Deep Research" agent and forces the Conductor to micro-manage.

5. Request for Help

Is there a timeout parameter for the Task tool itself? (Client-side wait time).
Why does the sub-agent die? If the Conductor stops waiting, shouldn't the sub-agent session continue running on the server?
Is wait: true supported? We need a way to force the Task tool to wait indefinitely (or 10m+) for the sub-agent to finish.

[github-actions]

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

• [feat] True Async/Background Sub-Agent Delegation #5887: [feat] True Async/Background Sub-Agent Delegation - Addresses the exact same core problem of sub-agents terminating prematurely and the need for non-blocking async delegation
• [FEATURE]: Dynamic model selection for subagents via Task tool #6651: [FEATURE]: Dynamic model selection for subagents via Task tool - Related to Task tool enhancements for better subagent control
• bash tool often times out #1721: bash tool often times out - Documents the underlying timeout issue affecting long-running operations (same root cause)
• [FEATURE]: Configurable command timeout in config.json #3950: [FEATURE]: Configurable command timeout in config.json - Requests configurable timeouts to extend execution duration

Feel free to ignore if none of these address your specific case.

[rekram1-node]

hm can u share examples of this happening? example configs maybe?

[DaveW001]

Yes. Please see attached. If there is something you need that isn't here, let me know what and where to find it. It is possible I've don't something wrong. This is my first attempt to use sub-agents.

opencode-troubleshooting.tar.gz

[moonray]

I'm seeing similar results

example (this happens intermittently):
orchestrator agent (primary) starts task for archiver agent
archiver agent completes steps 1-4 but never starts on step 5; orchestrator shows it's still waiting for task to complete, but when looking at archiver, it seems stuck right before starting on step 5

what I'd love to see is (probably not for this issue, but adding for reference):

• a way to see if the the task is still progressing (is it waiting for llm to return a response or something else?) or whatever it's doing, and how long it's been doing it, or if it considers itself done with its task
• a progress "spinner" on the task view itself when it's sending data to the model or waiting for the model to return a response
• perhaps a new tab in the console to see details of task or agent in addition to the very basic logs it currently outputs

I don't know if I would need a per-task timeout setting, but at least a global timeout setting for tasks so control would return to the parent agent, telling it that something happened that cause a timeout, allowing it to either retry, throw it back at the user, or anything really. 😁