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. 👍