fix: prevent context compaction from corrupting tool_use/tool_result pairing

Compaction could fire between adding the assistant tool_use message and
the user tool_result message, orphaning tool_use blocks and causing API
validation errors on long-running multi-iteration agent workflows.

Three fixes:
- Defer auto-compaction when the last message is a dangling tool_use
- Preserve the initial user task message during compaction
- Rewrite compaction algorithm to correctly build preserved + recent
  message sets without misordering via array_unshift

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Dale Hurley

src/AgentContext.php

@@ -207,8 +207,12 @@ public function addMessage(array $message): void
     {
         $this->messages[] = $message;
 
-        // Auto-compact if context manager is configured and threshold exceeded
-        if ($this->contextManager !== null) {
+        // Auto-compact if context manager is configured and threshold exceeded.
+        // Skip compaction when the last message is an assistant message with
+        // tool_use blocks but no following tool_result. Compacting at this point
+        // would separate the tool_use from its tool_result (which hasn't been
+        // added yet), corrupting the message structure required by the API.
+        if ($this->contextManager !== null && ! $this->hasDanglingToolUse()) {
             $usage = $this->contextManager->getUsagePercentage(
                 $this->messages,
                 $this->getToolDefinitions()
@@ -223,6 +227,39 @@ public function addMessage(array $message): void
         }
     }
 
+    /**
+     * Check if the last message is an assistant message with tool_use blocks
+     * that doesn't have a following tool_result message.
+     *
+     * This indicates we're between adding the assistant response and the
+     * tool results, and compaction must be deferred to avoid orphaning
+     * the tool_use blocks.
+     */
+    private function hasDanglingToolUse(): bool
+    {
+        if (empty($this->messages)) {
+            return false;
+        }
+
+        $lastMessage = $this->messages[count($this->messages) - 1];
+
+        if (($lastMessage['role'] ?? '') !== 'assistant') {
+            return false;
+        }
+
+        if (! is_array($lastMessage['content'] ?? null)) {
+            return false;
+        }
+
+        foreach ($lastMessage['content'] as $block) {
+            if (is_array($block) && ($block['type'] ?? '') === 'tool_use') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Get current iteration count.
      */

src/Context/ContextManager.php

@@ -81,31 +81,50 @@ public function compactMessages(array $messages, array $tools = []): array
             $messages = $this->clearToolResults($messages);
         }
 
-        // If still too large, remove oldest messages (keep first system message)
-        $compacted = [];
-        $systemMessage = null;
+        // If clearing tool results was enough, return early
+        if ($this->fitsInContext($messages, $tools)) {
+            return $messages;
+        }
+
+        // Extract preserved messages (system + initial user task) that must
+        // always remain at the start of the compacted result.
+        $preserved = [];
 
-        // Preserve system message if present
         if (! empty($messages) && ($messages[0]['role'] ?? '') === 'system') {
-            $systemMessage = $messages[0];
-            $compacted[] = $systemMessage;
+            $preserved[] = $messages[0];
             $messages = array_slice($messages, 1);
         }
 
-        // Add newer message units (tool_use + tool_result pairs) in reverse order until we fit
+        // Preserve the initial user message (the task prompt).
+        // Without it, compacted messages may start with an assistant message,
+        // violating the API requirement that messages begin with a user message.
+        if (! empty($messages) && ($messages[0]['role'] ?? '') === 'user') {
+            $preserved[] = $messages[0];
+            $messages = array_slice($messages, 1);
+        }
+
+        // Build message units from the remaining messages. Each unit is either
+        // a tool_use+tool_result pair or a standalone message. We add units
+        // from most recent to oldest, keeping as many as fit in the context.
         $units = $this->buildMessageUnits($messages);
         $recentUnits = array_reverse($units);
+
+        $recent = [];
         foreach ($recentUnits as $unit) {
-            foreach (array_reverse($unit) as $message) {
-                array_unshift($compacted, $message);
+            $candidateRecent = array_merge($unit, $recent);
+            $candidate = array_merge($preserved, $candidateRecent);
+
+            if ($this->fitsInContext($candidate, $tools)) {
+                $recent = $candidateRecent;
+            } else {
+                // Adding this unit would exceed the context. Stop here.
+                break;
             }
+        }
 
-            if ($this->fitsInContext($compacted, $tools)) {
-                $this->logger->debug('Compacted to ' . count($compacted) . ' messages');
+        $compacted = array_merge($preserved, $recent);
 
-                return $compacted;
-            }
-        }
+        $this->logger->debug('Compacted to ' . count($compacted) . ' messages');
 
         return $compacted;
     }

tests/Unit/AgentContextTest.php

@@ -298,4 +298,67 @@ public function testToResultFailure(): void
         $this->assertEquals('Test error', $result->getError());
         $this->assertEquals(1, $result->getIterations());
     }
+
+    public function testAddMessageDefersCompactionForDanglingToolUse(): void
+    {
+        $contextManager = new \ClaudeAgents\Context\ContextManager(
+            maxContextTokens: 50, // Very low to force compaction
+            options: ['compact_threshold' => 0.1] // Low threshold to trigger compaction
+        );
+
+        $context = new AgentContext(
+            client: $this->mockClient,
+            task: 'Analyze document',
+            tools: [],
+            config: $this->config,
+            contextManager: $contextManager,
+        );
+
+        // Add enough messages to exceed the context threshold
+        for ($i = 0; $i < 5; $i++) {
+            $context->addMessage([
+                'role' => 'assistant',
+                'content' => [
+                    ['type' => 'tool_use', 'id' => "tool_{$i}", 'name' => 'read', 'input' => []],
+                ],
+            ]);
+            $context->addMessage([
+                'role' => 'user',
+                'content' => [
+                    ['type' => 'tool_result', 'tool_use_id' => "tool_{$i}", 'content' => str_repeat('x', 100)],
+                ],
+            ]);
+        }
+
+        // Verify that every tool_use in the messages has a matching tool_result
+        $messages = $context->getMessages();
+        for ($i = 0; $i < count($messages); $i++) {
+            $msg = $messages[$i];
+            if (! is_array($msg['content'] ?? null)) {
+                continue;
+            }
+
+            $hasToolUse = false;
+            foreach ($msg['content'] as $block) {
+                if (is_array($block) && ($block['type'] ?? '') === 'tool_use') {
+                    $hasToolUse = true;
+                    break;
+                }
+            }
+
+            if (! $hasToolUse) {
+                continue;
+            }
+
+            // Next message must be a user message with tool_result
+            $this->assertArrayHasKey($i + 1, $messages,
+                "tool_use at message index {$i} must have a following message");
+            $this->assertEquals('user', $messages[$i + 1]['role'],
+                "Message after tool_use at {$i} must be user role");
+        }
+
+        // Verify first message is still the user task
+        $this->assertEquals('user', $messages[0]['role']);
+        $this->assertEquals('Analyze document', $messages[0]['content']);
+    }
 }