Function ensureToolResultPairing

src/utils/messages.ts:5133–5460

(
  messages: (UserMessage | AssistantMessage)[],
)

 * that will be rejected at submission anyway.
 */
export function ensureToolResultPairing(
  messages: (UserMessage | AssistantMessage)[],
): (UserMessage | AssistantMessage)[] {
  const result: (UserMessage | AssistantMessage)[] = []
  let repaired = false

  // Cross-message tool_use ID tracking. The per-message seenToolUseIds below
  // only caught duplicates within a single assistant's content array (the
  // normalizeMessagesForAPI-merged case). When two assistants with DIFFERENT
  // message.id carry the same tool_use ID — e.g. orphan handler re-pushed an
  // assistant already present in mutableMessages with a fresh message.id, or
  // normalizeMessagesForAPI's backward walk broke on an intervening user
  // message — the dup lived in separate result entries and the API rejected
  // with "tool_use ids must be unique", deadlocking the session (CC-1212).
  const allSeenToolUseIds = new Set<string>()

  for (let i = 0; i < messages.length; i++) {
    const msg = messages[i]!

    if (msg.type !== 'assistant') {
      // A user message with tool_result blocks but NO preceding assistant
      // message in the output has orphaned tool_results. The assistant
      // lookahead below only validates assistant→user adjacency; it never
      // sees user messages at index 0 or user messages preceded by another
      // user. This happens on resume when the transcript starts mid-turn
      // (e.g. messages[0] is a tool_result whose assistant pair was dropped
      // by earlier compaction — API rejects with "messages.0.content:
      // unexpected tool_use_id").
      if (
        msg.type === 'user' &&
        Array.isArray(msg.message.content) &&
        result.at(-1)?.type !== 'assistant'
      ) {
        const stripped = msg.message.content.filter(
          block =>
            !(
              typeof block === 'object' &&
              'type' in block &&
              block.type === 'tool_result'
            ),
        )
        if (stripped.length !== msg.message.content.length) {
          repaired = true
          // If stripping emptied the message and nothing has been pushed yet,
          // keep a placeholder so the payload still starts with a user
          // message (normalizeMessagesForAPI runs before us, so messages[1]
          // is an assistant — dropping messages[0] entirely would yield a
          // payload starting with assistant, a different 400).
          const content =
            stripped.length > 0
              ? stripped
              : result.length === 0
                ? [
                    {
                      type: 'text' as const,
                      text: '[Orphaned tool result removed due to conversation resume]',
                    },
                  ]