feat(agent): add concurrent_invocation_mode parameter

[zastrowm]

Motivation

Users who need to re-trigger an agent during invocation (e.g., to provide feedback out-of-band) are currently blocked by ConcurrencyException introduced in #1453. While concurrent invocation detection is valuable for safety, power users requested an escape hatch to restore the previous behavior when they need concurrent re-invocations.

Resolves #1702

Public API Changes

Agent.__init__ now accepts a concurrent_invocation_mode parameter:

# Before: no way to allow concurrent invocations
agent = Agent(model=model)
# Concurrent calls raise ConcurrencyException

# After: opt into unsafe reentrant behavior
agent = Agent(model=model, concurrent_invocation_mode="unsafe_reentrant")
# Concurrent calls proceed without exception (user assumes responsibility)

The parameter accepts:

• "throw" (default): Maintains existing behavior - raises ConcurrencyException on concurrent invocation attempts
• "unsafe_reentrant": Skips lock acquisition entirely, allowing concurrent invocations

The new type ConcurrentInvocationMode is available via strands.types.agent.ConcurrentInvocationMode for type annotations.

Use Cases

• Re-triggering agents: Users who want to interrupt and re-invoke an agent mid-invocation
• Legacy behavior: Teams migrating from pre-fix: add concurrency protection to prevent parallel invocations from corrupting agent state #1453 behavior who rely on concurrent invocations
• Future extensibility: Opens the door for an "interrupt" mode to cleanly interrupt agents with new user messages

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Assessment: Approve

Clean implementation that provides an escape hatch for power users who need concurrent agent invocations while maintaining safe defaults.

Review Summary

• API Design: Well-designed parameter with clear naming (unsafe_reentrant makes the risk explicit). Default "throw" maintains backward compatibility and safety.
• Implementation: Lock handling is correctly conditional with proper cleanup in finally block.
• Testing: Comprehensive coverage of both modes, sequential invocations, and exception scenarios.
• Documentation: PR description and parameter docstrings are clear and complete.

Note: This PR introduces a new public API parameter. Per the API Bar Raising guidelines, moderate changes like this benefit from informal API review. Consider adding the needs-api-review label if not already informally reviewed, though the design looks sound and aligns with the issue requirements.

[github-actions]

Thanks for the documentation update! The explicit warnings about unsafe_reentrant making no guarantees are a good addition. The changes look great and the PR is ready to merge. 👍

[afarntrog]

Nit: Let's use enums for the concurrent mode values

[github-actions]

This has been addressed in the latest commit - ConcurrentInvocationMode is now a str Enum that supports both enum values (ConcurrentInvocationMode.THROW) and string values ("throw").

[github-actions]

Re-review after enum refactor

The switch from Literal to str Enum is a good improvement:

✅ Enum benefits: Better IDE autocompletion, self-documenting, can add methods later if needed
✅ Backward compatible: Inheriting from str allows both ConcurrentInvocationMode.THROW and "throw" to work
✅ Tests cover both patterns: Tests verify string and enum usage work correctly

The implementation looks good. Ready to merge once the design question about public vs private instance variables is resolved (I've added context in my reply to that thread).

[pgrayy]

Nit: I don't think this lock is necessary. Even if the GIL was disabled, list append is thread safe.