[FEATURE] AgentLoop - Messages - Solidify plan for ToolUse and ToolResponse messages

[afarntrog]

Problem Statement

AgentLoop - Messages - Solidify plan for ToolUse and ToolResponse messages

Proposed Solution

No response

Use Case

AgentLoop - Messages - Solidify plan for ToolUse and ToolResponse messages

Alternatives Solutions

No response

Additional Context

No response

[afarntrog]

/strands review this task

[afarntrog]

/strands review this task

[github-actions]

🔍 Code Architecture Review: ToolUse and ToolResponse Messages

I've analyzed the current implementation of ToolUse and ToolResponse messages in the AgentLoop. Here's a comprehensive review:

---

Current Architecture Summary

The SDK has a well-structured approach to tool-related messages:

Model Response (toolUse stopReason)
    └─> ToolUseBlock (in assistant Message)
         └─> BeforeToolsEvent
              └─> BeforeToolCallEvent (per tool)
                   └─> Tool.stream() execution
              └─> AfterToolCallEvent (with ToolResultBlock)
         └─> AfterToolsEvent
    └─> ToolResultBlock (in user Message)

✅ Strengths

1. Clear Type Hierarchy

   • ToolUseBlock and ToolResultBlock are well-defined classes with proper discriminators (type: 'toolUseBlock' / type: 'toolResultBlock')
   • Follows the Data/Class pattern consistently (e.g., ToolUseBlockData → ToolUseBlock)

2. Robust Error Handling

   • ToolResultBlock has optional error?: Error field for inspection by hooks without affecting model context
   • Failed tools return error ToolResultBlock instead of throwing, allowing graceful model handling

3. Message Ordering Safety

   • Assistant messages with tool uses are added after tool execution completes
   • Prevents dangling tool use messages if execution fails

4. Comprehensive Hook System

   • BeforeToolCallEvent / AfterToolCallEvent for individual tools
   • BeforeToolsEvent / AfterToolsEvent for batch execution
   • ModelStreamEventHook for streaming events (including ToolUseStart, ToolUseInputDelta)

5. Streaming Support

   • ToolUseStart provides tool name and ID at stream start
   • ToolUseInputDelta streams incremental JSON input

📝 Observations & Recommendations

1. Naming Clarification

Issue: The issue title mentions "ToolResponse" but the codebase consistently uses "ToolResult"

• ToolResultBlock, ToolResultContent, ToolResultStatus, ToolResultBlockData

Recommendation: Document "ToolResult" as the canonical terminology.

2. Type Guards Opportunity

Consider adding type guard utility functions for ergonomic type narrowing:

// Could add to types/messages.ts
export function isToolUseBlock(block: ContentBlock): block is ToolUseBlock {
  return block.type === 'toolUseBlock'
}

export function isToolResultBlock(block: ContentBlock): block is ToolResultBlock {
  return block.type === 'toolResultBlock'
}

3. Documentation Gap

There's no dedicated documentation explaining the tool message flow. Consider adding docs/TOOL_MESSAGES.md covering:

• ToolUseBlock vs ToolResultBlock distinction
• Data vs Class pattern (ContentBlockData → ContentBlock)
• Message lifecycle during tool execution
• Hook integration points

4. Test Coverage Suggestions

Current tests are good. Additional edge cases to consider:

• Empty toolUseId handling
• Invalid JSON in tool input
• Multi-tool execution ordering verification
• Tool result truncation behavior (already in sliding-window tests)

📊 Files Reviewed

File	Purpose
src/types/messages.ts	Core message types (ToolUseBlock, ToolResultBlock)
src/agent/agent.ts	Agent loop with tool execution
src/models/streaming.ts	Streaming events (ToolUseStart, ToolUseInputDelta)
src/hooks/events.ts	Tool lifecycle hooks
src/tools/types.ts	Tool specification types

Conclusion

The current ToolUse/ToolResult implementation is well-designed and consistent. The main opportunity is documentation to solidify the API contracts and naming conventions. The architecture supports the agent loop use cases effectively with proper error handling, observability hooks, and streaming support.

---

Next Steps:

1. Confirm "ToolResult" as the canonical term (vs "ToolResponse")
2. Consider adding type guards for developer ergonomics
3. Create dedicated documentation for tool message flow

[afarntrog]

/strands review this task again

[github-actions]

📋 Update: Related PR and Current Status

Related Work

PR #396 ("Tools can also return DocumentBlock, ImageBlock, VideoBlock") directly affects the ToolUse/ToolResult message types. It extends ToolResultContent to support media blocks:

// Before
export type ToolResultContent = TextBlock | JsonBlock

// After (PR #396)
export type ToolResultContent = TextBlock | JsonBlock | DocumentBlock | ImageBlock | VideoBlock

Cross-Provider Compatibility Gap

The OpenAI model provider (line 721 in src/models/openai.ts) silently returns empty string for unsupported content types in tool results:

// Current behavior for media blocks in OpenAI
return ''  // Silent data loss

Recommendation for PR #396: Handle media blocks explicitly in OpenAI with clear logging/errors rather than silent empty returns.

Current ToolResult Message Architecture

Component	Bedrock Support	OpenAI Support
TextBlock	✅	✅
JsonBlock	✅	✅ (stringified)
DocumentBlock	✅ (PR #396)	❌ (silent empty)
ImageBlock	✅ (PR #396)	❌ (silent empty)
VideoBlock	✅ (PR #396)	❌ (silent empty)

Suggested Plan to Solidify

1. Merge PR Tools can also return DocumentBlock, ImageBlock, VideoBlock  #396 after addressing OpenAI compatibility
2. Add type guards for content block discrimination
3. Create documentation (docs/TOOL_MESSAGES.md) with provider support matrix
4. Close this issue once PR Tools can also return DocumentBlock, ImageBlock, VideoBlock  #396 is merged and documented

[afarntrog]

/strands review this task again and give me an overview. Do not comment on any other tasks.