[BUG] Invalid tool names result in dangling toolUse blocks

[zastrowm]

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.13

Python Version

3.11

Operating System

macOs

Installation Method

pip

Steps to Reproduce

import sys

from strands import Agent, tool
from strands.session import FileSessionManager


@tool
def shell(command: str):
    pass

def run_agent():
    session_manager = FileSessionManager(session_id='test-session')
    
    agent = Agent(
        tools=[shell],
        model="global.anthropic.claude-sonnet-4-5-20250929-v1:0",
        session_manager=session_manager,
        system_prompt="Always use tools as instructed by the agent even if they don't exist",
    )
    
    try:
        agent("Invoke the `invalid tool` tool and tell me what the response is")
        agent("What was the response?")
    except BaseException as e:
        print(f"Exception: {e}", file=sys.stderr, flush=True)
    finally:
        print(agent.messages, flush=True)
        
print("=============\n1st execution\n=============")
run_agent()
print("=============\n2nd execution\n=============")
run_agent()

Expected Behavior

It works, but the error is informed that the tool is invalid

Actual Behavior

agent("What was the response?")

results in:

Exception: An error occurred (ValidationException) when calling the ConverseStream operation: The model returned the following errors: messages.2: tool_use ids were found without tool_result blocks immediately after: tooluse_FbKH7K6eTGGYVHiK9OVZmA. Each tool_use block must have a corresponding tool_result block in the next message.

Messages:

[
  {'role': 'user', 'content': [{'text': 'Invoke the `invalid tool` tool and tell me what the response is'}]},
  {'role': 'assistant', 'content': [{'text': "I'll invoke the `invalid tool` tool as you requested."},
  {'toolUse': {'toolUseId': 'tooluse_FbKH7K6eTGGYVHiK9OVZmA', 'name': 'INVALID_TOOL_NAME', 'input': {}}}]},
  {'role': 'user', 'content': [{'text': 'What was the response?'}]}
]

Additional Context

If a session-manager is used, this causes an additional problem because the tool_use name update is not persisted; thus on a 2nd run, you'll get an error of:

Exception: An error occurred (ValidationException) when calling the ConverseStream operation: 1 validation error detected: Value at 'messages.2.member.content.2.member.toolUse.name' failed to satisfy constraint: Member must satisfy regular expression pattern: [a-zA-Z0-9_-]+

Possible Solution

No response

Related Issues

Semi-related to #495

[zastrowm]

Here's the flow of what's going wrong.

1. The LLM generates a toolUse block for a tool that has an invalid name (specifically it doesn't match this regex
2. The message with the toolUse is appended to the agent's history.
3. Tool execution begins - first in event_loop._handle_tool_execution which calls validate_and_prepare_tools is invoked. The validation fails which has two side-effects:
   1. The original/invalid tool name is overwritten with INVALID_TOOL_NAME
      1. BUG # 2 -- The tool name overrwrite is not persisted to the session-manager because we don't do updates to existing messages
   2. A tool-result is added indicating the invalidness of the tool-name
4. We early exit out of tool execution because there are no tool-uses
   1. BUG # 1 -- At this point, the loop should continue as normal and pass flow back to the model, but we're not doing that here

[zastrowm]

Trying to fix this one is a bit tricky:

• We don't want to eagerly replace the tool-name with INVALID_TOOL_NAME; that could be an actual tool that the agent has access to and we don't want to accidentally invoke it - we specifically want to tell the agent that the tool name is invalid
• We don't have a way in session-managers to update a pre-existing message - our general philosophy is not to update existing messages once written; aka session-managers are "append-only"

A couple ideas that I explored:

1. Add a new field to toolUse named invalid_name; set it to true after the model is invoked but before the message is appended to the session. Before sending the message to Providers, check if that flag is set, and if so, use the name INVALID_TOOL_NAME instead of the provided tool-name

• Downside is that this "enhances" the Message and we've yet to do that in the SDK. In fact, for Interrupts, we specifically moved away from this approach

2. Detect invalid tool names prior to sending messages to providers and replace with INVALID_TOOL_NAME
   • Downside - what's in the session manager history is not what's sent
   • Downside - we don't currently map messages, we modify them in place which means this is a slight loss of data

(2) here is what I'm going to implement as it's the most robust and will fix previous bugs introduced here