Vision-aware subagent routing: image tasks must land on vision-capable models, and 'I couldn't see the image' reports must not read as ok

[justrach]

Evidence (my-website session, subagent sa-024-f0b3395f)

Root spawned "Analyze color palette screenshot" with a task naming a .png path. The worker's own report opens: "I couldn't open the image as a vision input" — it then spent 481 s on Python pixel-quantization, concluded the screenshot was the website itself (wrong, per the trajectory post-mortem: it was a reference palette), and returned status: ok. The root accepted the confident-but-fabricated palette and briefed two mockup generations on it ("exact rose colors", "glassy waves"). One missing capability check cascaded into a whole family of wrong deliverables.

What exists already

src/vision.zig has visionCapable/visionModel (allowlist), used for clipboard pastes (#258: vision is checked BEFORE the clipboard is touched) and MCP image handoff (#249: vision models only). The spawn path never consults it.

Fix, two halves

1. Spawn-time routing. When a subagent task references an image (staged attachment, or a path with an image extension in the prompt), treat it as a vision ask — same shape as a tier ask: resolve onto a vision-capable rung (visionModel already knows how to pick), source it in the Ultracode: learn orchestration and tier policy, not only prompt variants #372 agent_route trace (e.g. source=vision-ask), and if no vision-capable provider is credentialed, fail the spawn fast with an actionable error instead of letting a text-only worker improvise. Explicit model pins keep priority — but a pinned non-vision model + image input should at least warn in the trace.
2. Report-time honesty flag. A worker report matching capability-disclaimer markers ("couldn't open/view/see the image as a vision input" and kin) gets flagged in the tool result the root sees — not silent ok. One line ("worker disclaimed vision capability — its visual conclusions are inferred, not seen") converts confident fabrication into a root-visible decision point. Cheap, no model call.

Constraints

• fleet: model tier and shape slot belong in the MAP-Elites niche, not the genome #290/subagents: per-persona and per-spawn model pin (tier in agent frontmatter) #292 precedence unchanged: explicit pin > persona > vision-ask routing > session default.
• rungAffordable/sub-first gates still apply among vision-capable candidates.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QbsV84fdmf39Bh2RF8LdPs

[justrach]

Landed on main (eb59994, in CI run 30870211513 green — one unrelated #364 flake-rerun, now being root-caused on its own branch). Both halves:

Spawn-time vision ask. src/vision_ask.zig detects a plausible local path token ending in png/jpg/jpeg/gif/webp (word-boundary checked; globs, bare extensions, and http(s) URLs deliberately excluded — a remote URL can't become a vision block, so rerouting would buy nothing). Precedence: explicit spawn pin > persona > explicit --subagent-model > vision ask > learned policy > ladder — only automatic seats re-route; candidates prefer a logged-in flat-rate sub (subscriptionRung's rule), then provider-local vision rungs under rungAffordable; nothing metered crosses a provider boundary. Decision lands in the #372 trace as source=vision-ask. No vision anywhere → fast, actionable refusal (two variants: none-reachable vs cost-ceiling, the latter naming the model:"…" pin that authorizes the spend).

Report-time honesty flag. A worker report containing a capability disclaimer on an image task gets [vision warning] worker disclaimed image-viewing capability — visual conclusions below are inferred, not seen. prepended to the tool result the root sees; a blind explicit pin gets the analogous warning at spawn. The originating failure (sa-024: "couldn't open the image as a vision input" → 8 min of pixel-quantization → wrong palette → status ok → root briefed two generations on it) can no longer read as clean.

Live-verified twice (agent + independent): text-only deepseek root, real PNG task → resolved_model=gpt-5.6-luna source=vision-ask on the codex sub; blind-pin path shows pin kept + warning + flagged report text in the root's session file. 824 tests green both compilers. Scope notes on the module: workflow phases warn rather than hard-fail (one image task must not abort a run); the pre-existing #292 gateway explicit-pin resolution gap is untouched. Closing.