withheld-max-output-token-errors

SKILL: Withheld Max Output Token Errors

Domain: tool-orchestration
Trigger: Use this when a user turn hits the max-output-token limit but the system keeps retrying so the recovery loop should finish before reporting an error. Source Pattern: Distilled from reviewed tool-loop and result-shaping patterns.

Core Method

Detect the API’s max_output_tokens error inside the streaming loop, suppress it while recovery continues, and only expose it once all retries settle. During that delay, emit placeholder tool_result messages that say each tool is missing so the user sees a focused failure summary instead of a raw API error. This keeps recovery logic intact while still surfacing helpful, per-tool diagnostics after the recovery path finishes.

Key Rules

• Guard every assistant message against apiError === 'max_output_tokens' and only mark it for reporting once the recovery loop decides no more progress can happen.
• Track tool_use IDs for the assistant messages that triggered the error and emit sanitized messages with the standard tool_result shape so downstream components can handle them like any other tool failure.
• Log the withheld message only after isWithheldMaxOutputTokens returns true; do not surface the API error early or the SDK context may terminate the session.
• Keep the placeholder text short, include the original error message, and mark is_error: true so tooling knows it’s still an error.
• Preserve the tool ID so any transcripts or sidecars referencing the tool use still match the replayed replacement.

Example Application

When the per-turn token budget is exceeded while streaming a multi-tool answer, let the recovery loop run; once it fails, emit one user-facing tool_result block per tool use with the stored error message instead of leaking the API’s max_output_tokens field.

Anti-Patterns (What NOT to do)

• Do not throw or propagate the API error immediately; SDK callers might abort and the recovery path would never execute.
• Do not drop the tool_use IDs when rewriting the error, or transcripts/resumes will lose their references.