Task tool needs configurable timeout to prevent indefinite hangs

[jdocker8]

Problem

When using the Task tool to launch subagents (explore, general), there is no way to set a timeout. Subagents frequently hang for 5-15+ minutes on tasks that should take 15-30 seconds, blocking the entire conversation.

Context

The host repo has AI rules (AI_RULES.md §16) that explicitly require:

• "Set explicit timeout per request: 2 min (simple), 5 min (larger)"
• "On timeout: cancel, then re-issue with smaller scope or do it directly"
• "Never wait indefinitely"

But the Task tool schema has no timeout parameter, so these rules are unenforceable. The Bash tool has a timeout parameter — Task should too.

Expected behavior

1. Task tool should accept an optional timeout parameter (milliseconds, like Bash tool)
2. Reasonable default timeout (e.g., 120s) if none specified
3. On timeout: return a timeout error so the caller can fall back to doing the work directly

Current workaround

None. The caller agent just waits indefinitely, and the user has to manually abort.

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• This appears to be a feature request, but it does not use the required Feature Request template. Please resubmit using the correct template, which requires a verification checkbox and description, and the title should start with [FEATURE]:.

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:

• Feature Request: Async Task Management - Non-blocking Subagent Dispatch #15069: Feature Request for async/non-blocking Task tool dispatch — closely related improvement to the same Task tool (non-blocking execution vs. configurable timeout)

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

[jdocker8]

Real-world example of the problem

In my session, I launched an explore subagent to audit diagnostic step conditions across 5 workflow files. The agent hung for over 5 minutes before the user manually aborted it.

After aborting, I ran the exact same work directly using 5 parallel grep calls. It completed in ~2 seconds and I was immediately ready to move on.

The work was:

grep --pattern "if:.*always|if:.*failure|if:.*sst-deploy|Classify|Print deploy|Diagnose|diagnostics|Upload SST|Debug SST"

...across 5 YAML files. Trivially parallelizable, no complex reasoning needed.

Why a timeout is critical

Without a timeout parameter on the Task tool:

• The caller agent has no way to set a deadline
• The user has to manually notice the hang and abort
• Simple 2-second tasks can block the conversation for 5-15+ minutes
• The caller can't implement the fallback pattern ("on timeout, do it directly") because it never gets control back

A timeout parameter (like the Bash tool already has) would let the caller set e.g. timeout: 30000 (30s) for simple searches, get a timeout error, and immediately fall back to doing the work directly.

[jdocker8]

Closing in favor of #15080, which was recreated using the required feature request template.