fix(hooks): expose attempt_number, max_attempts, is_last_attempt on completion:error and completion:last_attempt hooks

[Kcstring]

Summary

Closes #2222

completion:error and completion:last_attempt handlers can now receive retry metadata as keyword arguments — attempt_number, max_attempts, and is_last_attempt — without any breaking changes.

What changed

instructor/core/hooks.py — CompletionErrorHandler Protocol updated to document the kwargs that retry.py already passes:

class CompletionErrorHandler(Protocol):
    def __call__(
        self,
        error: Exception,
        *,
        attempt_number: int = ...,
        max_attempts: int | None = ...,
        is_last_attempt: bool = ...,
    ) -> None: ...

No changes to retry.py — it already passes these kwargs to emit_completion_error() and emit_completion_last_attempt(). The existing inspect.signature fallback in Hooks.emit() means old-style handlers (def handler(error)) continue to work unchanged.

Usage

def on_error(
    error: Exception,
    *,
    attempt_number: int = 1,
    max_attempts: int | None = None,
    is_last_attempt: bool = False,
) -> None:
    severity = "ERROR" if is_last_attempt else "WARNING"
    print(f"[{severity}] attempt {attempt_number}/{max_attempts}: {error}")

client.on("completion:error", on_error)
client.on("completion:last_attempt", on_error)

Tests

9 new unit tests in tests/test_hooks_retry_metadata.py — no real API calls needed:

• attempt_number forwarded correctly
• max_attempts forwarded (including None for unbounded)
• is_last_attempt is False for intermediate errors, True for last attempt
• Old-style handlers (error-only) still called without breaking