Subagents on reasoning-heavy open-ended tasks sometimes finish with prose instead of calling the required StructuredOutput tool — request opt-in harness-level enforcement/retry

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Environment: Claude Code (Windows 11), multi-agent orchestration via the Workflow tool running a custom fan-out script; agents are spawned with a required structured-return JSON schema (StructuredOutput). Models: claude-opus-4-8 (workers). Also reproduced with subagents spawned via the Agent tool.

Observed behavior: a subagent completes its task but ends its run with plain prose instead of calling the required StructuredOutput tool (or returns a verdict that does not go through the schema). The work itself is usually done — the structured envelope is what goes missing, so the orchestrator loses the machine-readable verdict.

Data points we measured (two internal repos, same schema + same model):

Project A: 7+ lifetime occurrences. Within the same session batch: narrow build-scoped lanes returned clean structured output 3/3, while open-ended review/reasoning lanes returned clean 1/3. The correlation we see is with task openness (reasoning-heavy, open-ended prompts), not with the schema or the model version.
Project B (narrow, schema-forced task design throughout): has not observed an equivalent rate. This supports the same correlation from the opposite direction.
Mitigations we already run user-side (all reduce, none eliminate):

Schema-forced structured return + a "verdict header on line 1" instruction in the task prompt (strongest single lever in our data: 6/6 clean after adding it in Project A).
A RETURN-FORMAT template embedded in the task prompt (6/7 clean).
Splitting open-ended tasks into narrow schema-friendly sub-tasks (3/3 vs 1/3).
N-lane redundancy so one garbled lane does not lose the verdict.
Orchestrator-side recovery from partial output (no re-spawn; reconstruct from transcript + diff backstop).
Why we cannot fully close this user-side: hooks are fail-open by design (per docs), so there is no hard user-side way to require "the final assistant message MUST be the expected tool call". Everything we can do is instruct-only.

Request: an opt-in, per-spawn flag for subagent/workflow spawns — e.g. requireStructuredOutput: true — that makes the harness enforce the contract: if the agent's final message is not the expected StructuredOutput call, the harness automatically re-prompts/retries (bounded, e.g. once) or fails loudly with a distinct error, instead of silently accepting prose. Even just the distinct error would let orchestrators handle this deterministically.

Impact: in multi-agent pipelines the structured verdict is the load-bearing artifact; silent prose fallback means orchestrators must run redundant lanes or manual recovery for a failure mode the harness can detect exactly.

Happy to provide more detail on the task shapes that trigger this.

What Should Happen?

When a subagent/workflow agent is spawned with a required structured-return schema, its final message should be the StructuredOutput tool call (schema-valid). If the model ends with plain prose instead, the harness should not silently accept that as the final result — it should either (a) automatically re-prompt/retry once (bounded), or (b) fail loudly with a distinct, machine-readable error so the orchestrator can handle it deterministically. An opt-in per-spawn flag (e.g. requireStructuredOutput: true) enabling this enforcement would be sufficient.

Error Messages/Logs

None — and that is part of the report: the run ends "successfully" with prose output, so the missing structured envelope produces no error, warning, or distinct exit state. The orchestrator only discovers it downstream when the machine-readable verdict is absent.

Steps to Reproduce

1. Spawn a subagent (Agent tool or Workflow tool) with a required structured-return JSON schema (StructuredOutput).
2. Give it an open-ended, reasoning-heavy task (e.g. a broad review/verdict prompt) rather than a narrow build-scoped one.
3. In a fraction of runs (we measured ~2/3 clean → 1/3 garbled on open-ended lanes vs 3/3 clean on narrow lanes, same schema + model), the agent finishes with plain prose and never calls StructuredOutput.
4. Intermittent — narrow, schema-friendly tasks rarely trigger it; open-ended prompts do.

Claude Model

Not sure / Multiple models

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

1.20186.0

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Other

Additional Information

Adjacent but distinct: #75086 covers StructuredOutput schema-retry exhaustion (the tool IS called but validation fails repeatedly). This report is the other path: the agent never calls the tool at all and ends with prose. Frequency data in the description comes from two internal repos instrumented over several weeks (same schema + same model, differing only in task openness).