Summary

Adds an opt-in capability contract so image_gen providers can accept reference images, and wires the openai-codex plugin up as the first provider to opt in. The image_generate tool gains an optional references field (array of local file paths); the dispatcher forwards it only when the active provider advertises supports_references=True, otherwise rejects early with references_unsupported instead of silently dropping it.

Motivation — the Codex image_generation tool accepts input_image after all

The existing baoyu-comic skill documents image_generate as "prompt-only — it does NOT accept reference images", and #14317 explicitly scoped the openai-codex plugin to the generate endpoint. This PR's finding contradicts both: passing one or more input_image content items on the user message of the Codex responses.stream(...) call works, and the image_generation tool uses the attached images for composition, style transfer, and edits.

Empirically verified against the live Codex backend with three tests:

1. Two-subject composition — red apple (reference 1) + blue ceramic teapot (reference 2) → single still-life on a shared wooden table with consistent lighting. Both subjects reproduced faithfully (same shape, same surface, same highlights).
2. Cross-reference style transfer — a minimalist line-drawn mountain (reference 1) + a photographic teapot (reference 2), prompt says "reproduce reference 1 exactly, place reference 2 on a shelf, keep reference 1's line style" → teapot rendered in reference 1's ink style, mountain preserved. Style transfer and subject extraction both work.
3. Single-reference re-lighting — apple on white (reference 1) → apple on grey gradient, preserving the exact fruit silhouette and surface. Works end-to-end through the new dispatcher path.

(Happy to share the PNGs in a follow-up comment if useful — they're local and not on a public host yet.)

Scope

In:

• agent/image_gen_provider.py: supports_references property (defaults False) with doc for the references kwarg.
• plugins/image_gen/openai-codex/__init__.py: opts in; adds _load_reference_images + _build_user_content; wires references through generate() with invalid_argument / invalid_reference error paths. Caps at MAX_REFERENCES = 16 (matches OpenAI's documented upstream cap).
• tools/image_generation_tool.py: references in the agent-facing schema; dispatcher forwards only to capable providers; clear references_unsupported error for FAL and any non-capable plugin.
• Tests: TestReferences in the openai-codex suite (7 new cases), TestReferencesDispatch in the dispatcher suite (4 new cases), schema invariant test updated.

Out (deliberately, happy to follow up in a separate PR):

• Opting openai (API-key) plugin in to references via the Images Edit endpoint.
• Masking / image-variation flows.
• Remote URL references (only local file paths for now — the plugin encodes each as a data URL).

Non-breaking

• fal, openai, xai all inherit supports_references=False — their behaviour is byte-identical to before.
• The dispatcher rejects reference payloads for non-capable providers before they reach generate(), so no provider is silently passed kwargs it doesn't understand.
• The image_generate tool with no references field continues to behave exactly as before.

Test plan

• pytest tests/plugins/image_gen/ tests/tools/test_image_generation.py tests/tools/test_image_generation_env.py tests/tools/test_image_generation_plugin_dispatch.py → 133 passed.
• Live run against the Codex backend through the standalone Responses call: text-only 22s, 2-ref composition 51s, 2-ref style-transfer 73s — all produced coherent outputs matching the references.
• Integration check via tools.image_generation_tool._handle_image_generate (same path a real tool call takes): {"prompt": "...", "references": ["/path/a.png"]} with image_gen.provider: fal → returns references_unsupported.
• Integration check via _handle_image_generate with image_gen.provider: openai-codex: single-reference re-lighting prompt → returns success=True, provider=openai-codex, references=1, image points to a 1.9 MB PNG that preserves the reference subject. Full round-trip 30s.

Open questions

1. Preferred name for the kwarg — I used references since it's what OpenAI's docs call them; other options include input_images or reference_images.
2. Whether to expose this in the tool description as "currently honoured only by openai-codex" (what I did) or stay silent and let users discover via the error. The current text is probably clearer.
3. If you'd rather ship this as a separate image_edit tool instead of growing image_generate, I'm happy to refactor.