Planner response hit the token ceiling and was truncated

The planner refuses a response whose stop_reason is max_tokens, and the comment above the check explains why it exists:

stop_reason: 'max_tokens' is the API telling us exactly this, and it was being ignored. Refusing here means the caller's retry/refinement path sees a real failure rather than a quietly shorter plan.

Why accepting it is worse than failing

A truncated plan is not a smaller plan. It is a plan whose last table row is cut mid-cell, whose final tasks have no dependency edges, and whose structure is therefore wrong in ways that parse cleanly.

The parser will do its best with it. What comes out is a plan that looks complete, is missing work nobody knows about, and has dependency edges that stop early — which means tasks that should have waited will run in parallel.

That failure surfaces days later as a merge conflict or a missing feature, with nothing connecting it back to a token limit.

How to fix it

The message names both levers. Raise WAVE_PLANNER_MAX_TOKENS if the spec is legitimately large, or narrow the spec if it is trying to plan too much at once.

The second is usually the better answer. A spec that needs an enormous plan is often a spec that should have been two.

The general rule

Any code reading a model response should check stop_reason before trusting the content. Length-truncation is the one failure mode that produces syntactically valid, semantically incomplete output — and it is the only one your parser cannot detect for you.