Repository navigation
Task Tool Timeouts & Early Termination in Multi-Agent Conductor Pattern #6792
Description
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.
Activity
github-actions commentedon Jan 4, 2026
This issue might be a duplicate of existing issues. Please check:
Feel free to ignore if none of these address your specific case.
rekram1-node commentedon Jan 4, 2026
hm can u share examples of this happening? example configs maybe?
DaveW001 commentedon Jan 4, 2026
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 commentedon Jan 19, 2026
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):
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. 😁
dcominottim commentedon Feb 3, 2026
opencode really needs some kind of sane timeout with automatic retries for tasks/subagents. When using Codex / OpenAI, my subagents are frequently getting stuck and apparently there's indeed no kind of timeout or retry whatsoever.
sbluemin commentedon Feb 11, 2026
My subagent also occasionally fails to process requests and becomes a zombie agent. I desperately need a timeout feature.
riccardo-algorime commentedon Feb 23, 2026
so, any way to increase the fix 10 minute timeouts? it gets easely hit with long thinking models like gpt 5.2 /5.3 and codex
DaveW001 commentedon Mar 8, 2026
I haven't seen this happening lately. Did you guys change something related?
diegonix commentedon Mar 9, 2026
Additional data point — grep tool call hanging inside nested subagent (v1.2.21, Linux)
I'm running OpenCode v1.2.21 on Ubuntu 24.04 with a two-layer subagent architecture (primary → subagent → sub-subagent).
A grep tool call inside one of the second-layer subagents hung indefinitely. Because the entire call chain is await-blocked (grep.execute() → child SessionProcessor → parent TaskTool.execute() → primary session loop), the whole session became completely unresponsive — not just the stuck subagent, but every other subagent and the orchestrator itself.
There was no way to cancel only the stuck subagent or the hung tool call. The only escape was killing the entire session (ESC×2).
Root cause insight: Looking at the source, grep (unlike bash) has no timeout at all — it relies entirely on the AbortSignal propagated from SessionPrompt.cancel(). But since there's no per-subagent cancellation in the UI, and no independent watchdog/deadline on tool calls, a single hung ripgrep process cascades into a full session freeze.
What would help (in priority order):
A per-tool-call timeout (e.g., grep should have a configurable timeout like bash already does via OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS)
Per-subagent cancellation — ability to cancel a specific stuck subagent without killing the entire session
A global subagent deadline configurable in opencode.json (e.g., "timeout": 300 per agent definition)
Related issues: #11865, #9003, #13916
rekram1-node commentedon Jun 23, 2026
Automated: closing question issues.
GitHub Issues are for bug reports and feature requests only — questions / support are no longer tracked here.
If this is a bug or feature request, please open a new issue with the appropriate template.