docs(tools): guide proportional wait_for_message timeouts

[devin-ai-integration]

Summary

wait_for_message resumes the instant a message arrives (it's event-driven, not polling), so timeout_seconds is purely a cap for the case where the expected message never comes. Agents were treating the 600s default as "how long to wait" and parking on trivial handoffs, stranding themselves idle far longer than needed when a reply doesn't arrive.

Docs-only change to the wait_for_message docstring (what the model sees) so agents pick a timeout proportional to the work:

- timeout_seconds: Hard cap (default 600s). On timeout the tool
-     returns and you decide whether to keep working or wait again.
+ timeout_seconds: Max seconds to wait (default 600). This is only a cap —
+     the tool returns the INSTANT a message arrives, so a larger value never
+     makes you wait longer when the reply does come. Right-size it: a short
+     wait (e.g. 10-60s) for a quick ack or a small/fast subtask, and a longer
+     one (e.g. ~100-200s) only for genuinely long-running work (deep recon,
+     exploitation, a full sub-scan). ...

Also adds one line to the opening ("…pick a timeout_seconds proportional to the work you're awaiting"). No behavior change.

Link to Devin session: https://app.devin.ai/sessions/dad023e379e942f287bcf6822463b7a4
Requested by: @0xallam

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[greptile-apps]

Greptile Summary

This PR clarifies how agents should choose wait_for_message timeouts.

• Explains that autonomous waits resume as soon as a message arrives.
• Recommends timeout caps proportional to the expected work.
• Notes that interactive and chat sessions park without enforcing the cap.

Confidence Score: 5/5

This looks safe to merge.

• The updated wording matches the autonomous and interactive wait paths.
• No blocking issues remain in the changed code.

Important Files Changed

Filename	Overview
strix/tools/agents_graph/tools.py	Updates the wait_for_message docstring with proportional timeout guidance and accurate runtime-mode scope.

_{Reviews (3): Last reviewed commit: "docs(tools): note wait_for_message timeo..." | Re-trigger Greptile}

[0xallam]

@greptile

[devin-ai-integration]

@greptile