HeavySwarm: the question decomposer never sees img, so workers answer questions written without the image

[ayaangazali]

Found while fixing #1902 (the executors dropped img before calling the agents). That PR gets the image to the workers; this is the step before it, and it needs a design decision rather than a one-line fix.

execute_question_generation takes no image:

def execute_question_generation(self, task: str) -> Dict[str, str]:   # heavy_swarm.py:1310

So for a visual task the decomposer never sees the image it is decomposing. Given:

swarm.run("What does this chart imply for Q3 guidance?", img="revenue.png")

the question agent gets only the sentence. It has to guess what is in the image, then writes four (default/medium) or fifteen (heavy) sub-questions from that guess, and those questions are what every worker actually answers. With #1902 the workers can see the image, but they are answering questions written by something that could not.

The same gap applies to get_questions_only() and get_questions_as_list() (heavy_swarm.py:1405, 1485), which are public and also take task only.

What makes this a decision and not a fix:

1. Where the image goes. Passing img to the question agent's run() is easy, but the question-generation prompt is built around a text task and the tool schema returns *_question strings. Whether the prompt should be told "an image is attached, decompose it too" — and how — changes the generated questions, and therefore output for every existing caller with an image.
2. Cost. The image would be sent to the decomposer as well as to N workers, so a 15-agent heavy run goes from 15 image payloads to 16. Small, but it is a real per-run cost increase for a variant already priced per agent.
3. Public signatures. get_questions_only / get_questions_as_list would need an img parameter to stay consistent, which is an API change.

My suggestion, if you want one: add img: Optional[str] = None to execute_question_generation and the two public question helpers, pass it through to the question agent's run(), and add one line to the prompt telling it an image accompanies the task. That keeps existing text-only behaviour identical, since img=None changes nothing.

Happy to send it once you have picked a direction.