fix(cli): include fallback prompt in content array for image-only messages

When users send only images without text, the fallback prompt "See attached image(s)"
was being passed as a separate prompt parameter but ignored by buildUserMessageContent.
Now the fallback text is included directly in the content array so the model receives
the instruction.

Author: brandonkachen

cli/src/hooks/use-send-message.ts

@@ -468,10 +468,10 @@ export const useSendMessage = ({
       // and prepare context for the LLM
       const { pendingBashMessages, clearPendingBashMessages } =
         useChatStore.getState()
-      
+
       // Format bash context to add to message history for the LLM
       const bashContext = formatBashContextForPrompt(pendingBashMessages)
-      
+
       if (pendingBashMessages.length > 0) {
         // Convert pending bash messages to chat messages and add to history (UI only)
         // Skip messages that were already added to history (non-ghost mode)
@@ -594,17 +594,15 @@ export const useSendMessage = ({
         }
       }
 
-      // Build message content array for SDK
+      // Build message content array for SDK (images only - text comes from prompt parameter
+      // which includes bash context and fallback text for image-only messages)
       let messageContent: MessageContent[] | undefined
       if (validImageParts.length > 0) {
-        messageContent = [
-          { type: 'text' as const, text: content },
-          ...validImageParts.map((img) => ({
-            type: 'image' as const,
-            image: img.image,
-            mediaType: img.mediaType,
-          })),
-        ]
+        messageContent = validImageParts.map((img) => ({
+          type: 'image' as const,
+          image: img.image,
+          mediaType: img.mediaType,
+        }))
 
         logger.info(
           {
@@ -1111,10 +1109,12 @@ export const useSendMessage = ({
           const promptWithBashContext = bashContext
             ? bashContext + content
             : content
+          const hasNonWhitespacePromptWithContext =
+            (promptWithBashContext ?? '').trim().length > 0
 
           // Use a default prompt when only images are attached (no text content)
           const effectivePrompt =
-            promptWithBashContext ||
+            (hasNonWhitespacePromptWithContext ? promptWithBashContext : '') ||
             (messageContent ? 'See attached image(s)' : '')
 
           runState = await client.run({

packages/agent-runtime/src/util/__tests__/messages.test.ts

@@ -19,6 +19,7 @@ import {
   messagesWithSystem,
   getPreviouslyReadFiles,
   filterUnfinishedToolCalls,
+  buildUserMessageContent,
 } from '../../util/messages'
 import * as tokenCounter from '../token-counter'
 
@@ -40,6 +41,91 @@ describe('messagesWithSystem', () => {
   })
 })
 
+describe('buildUserMessageContent', () => {
+  it('wraps prompt in user_message tags when no content provided', () => {
+    const result = buildUserMessageContent('Hello world', undefined, undefined)
+
+    expect(result).toHaveLength(1)
+    expect(result[0].type).toBe('text')
+    expect((result[0] as any).text).toContain('<user_message>')
+    expect((result[0] as any).text).toContain('Hello world')
+  })
+
+  it('wraps text content in user_message tags', () => {
+    const result = buildUserMessageContent(undefined, undefined, [
+      { type: 'text', text: 'Hello from content' },
+    ])
+
+    expect(result).toHaveLength(1)
+    expect(result[0].type).toBe('text')
+    expect((result[0] as any).text).toContain('<user_message>')
+    expect((result[0] as any).text).toContain('Hello from content')
+  })
+
+  it('uses prompt when content has empty text part', () => {
+    const result = buildUserMessageContent('See attached image(s)', undefined, [
+      { type: 'text', text: '' },
+      { type: 'image', image: 'base64data', mediaType: 'image/png' },
+    ])
+
+    expect(result).toHaveLength(2)
+    expect(result[0].type).toBe('text')
+    expect((result[0] as any).text).toContain('See attached image(s)')
+    expect(result[1].type).toBe('image')
+  })
+
+  it('uses prompt when content has whitespace-only text part', () => {
+    const result = buildUserMessageContent('See attached image(s)', undefined, [
+      { type: 'text', text: '   ' },
+      { type: 'image', image: 'base64data', mediaType: 'image/png' },
+    ])
+
+    expect(result).toHaveLength(2)
+    expect(result[0].type).toBe('text')
+    expect((result[0] as any).text).toContain('See attached image(s)')
+    expect(result[1].type).toBe('image')
+  })
+
+  it('uses prompt when content has only images (no text part)', () => {
+    const result = buildUserMessageContent('See attached image(s)', undefined, [
+      { type: 'image', image: 'base64data', mediaType: 'image/png' },
+    ])
+
+    expect(result).toHaveLength(2)
+    expect(result[0].type).toBe('text')
+    expect((result[0] as any).text).toContain('See attached image(s)')
+    expect(result[1].type).toBe('image')
+  })
+
+  it('uses content text when it has meaningful content (ignores prompt)', () => {
+    const result = buildUserMessageContent(
+      'This prompt should be ignored',
+      undefined,
+      [
+        { type: 'text', text: 'User provided text' },
+        { type: 'image', image: 'base64data', mediaType: 'image/png' },
+      ],
+    )
+
+    expect(result).toHaveLength(2)
+    expect(result[0].type).toBe('text')
+    expect((result[0] as any).text).toContain('User provided text')
+    expect((result[0] as any).text).not.toContain(
+      'This prompt should be ignored',
+    )
+    expect(result[1].type).toBe('image')
+  })
+
+  it('ignores whitespace-only prompt when content has no text', () => {
+    const result = buildUserMessageContent('   ', undefined, [
+      { type: 'image', image: 'base64data', mediaType: 'image/png' },
+    ])
+
+    expect(result).toHaveLength(1)
+    expect(result[0].type).toBe('image')
+  })
+})
+
 // Mock logger for tests
 const logger = {
   debug: () => {},

packages/agent-runtime/src/util/messages.ts

@@ -43,8 +43,23 @@ export function buildUserMessageContent(
   params: Record<string, any> | undefined,
   content?: Array<TextPart | ImagePart>,
 ): Array<TextPart | ImagePart> {
+  const promptHasNonWhitespaceText = (prompt ?? '').trim().length > 0
+
   // If we have content array (e.g., text + images)
   if (content && content.length > 0) {
+    // Check if content has a non-empty text part
+    const firstTextPart = content.find((p): p is TextPart => p.type === 'text')
+    const hasNonEmptyText = firstTextPart && firstTextPart.text.trim()
+
+    // If content has no meaningful text but prompt is provided, prepend prompt
+    if (!hasNonEmptyText && promptHasNonWhitespaceText) {
+      const nonTextContent = content.filter((p) => p.type !== 'text')
+      return [
+        { type: 'text' as const, text: asUserMessage(prompt!) },
+        ...nonTextContent,
+      ]
+    }
+
     // Find the first text part and wrap it in <user_message> tags
     let hasWrappedText = false
     const wrappedContent = content.map((part) => {
@@ -67,7 +82,7 @@ export function buildUserMessageContent(
 
   // Only prompt/params, combine and return as simple text
   const textParts = buildArray([
-    prompt,
+    promptHasNonWhitespaceText ? prompt : undefined,
     params && JSON.stringify(params, null, 2),
   ])
   return [