feat(core): Add AgentCancel exception for control-flow in callbacks

[peteski22]

Summary

• Add AgentCancel abstract base class for control-flow exceptions in callbacks
• Modify run_async to preserve AgentCancel subclasses without wrapping in AgentRunError
• Document the new pattern in callbacks documentation

Rationale

Currently, AnyAgent.run_async unconditionally wraps all exceptions in AgentRunError, breaking user control-flow semantics. When users raise custom exceptions in callbacks to stop agent execution, they cannot catch them by their specific type:

class StopAgent(Exception): pass

class MyCallback(Callback):
    def before_tool_execution(self, context, *args, **kwargs):
        if some_condition:
            raise StopAgent("Limit reached")
        return context

try:
    agent.run(...)
except StopAgent:  # Never matches - wrapped in AgentRunError
    handle_stop()
except AgentRunError as e:
    # Must inspect e.original_exception instead
    if isinstance(e.original_exception, StopAgent):
        handle_stop()

This is particularly problematic for implementing safety guardrails, rate limits, and validation logic where stopping execution is expected behaviour rather than an error.

Solution

Introduce AgentCancel, an abstract base class for control-flow exceptions. Subclasses propagate directly to the caller with the execution trace attached:

from any_agent import AgentCancel

class StopAgent(AgentCancel):
    pass

try:
    agent.run(...)
except StopAgent as e:
    print(f"Stopped: {e}")
    print(f"Trace: {e.trace}")  # Access spans collected before cancellation

This follows Python conventions like asyncio.CancelledError and StopIteration where control-flow exceptions are distinct from error exceptions.

NOTE: This is a non-breaking, opt-in change. Existing code continues to work unchanged, only users who explicitly subclass AgentCancel will see the new behaviour.

Additional Fixes

This PR also includes two unrelated type fixes discovered during CI:

• fix(tools): Update type: ignore comment in wrappers.py - the isinstance check using a runtime-constructed tuple doesn't allow mypy to narrow the type, requiring [no-any-return] instead of [return-value]
• fix(openai): Remove type: ignore for reasoning_effort now that any-llm-sdk 1.7.0 supports xhigh

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/any_agent/__init__.py	77.77% <100.00%> (ø)
src/any_agent/frameworks/any_agent.py	85.79% <100.00%> (-4.83%)	⬇️
src/any_agent/frameworks/openai.py	62.58% <ø> (-6.46%)	⬇️
src/any_agent/tools/wrappers.py	94.68% <100.00%> (ø)
tests/unit/frameworks/test_agent_cancel.py	100.00% <100.00%> (ø)

... and 44 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.