PR Review
Reviewed head: e7d19ec4877fbc8b38d9b246ebb5e9011b9d1b02

Summary

• Refactors _format_error_message to accept exception objects and emit type-specific, actionable user messages.
• Replaces several generic fallback responses with concrete Telegram delivery error details and richer fallback classification.
• Updates orchestrator/message call sites to pass exception objects, plus lockfile churn from Poetry/Python version changes.

What looks good

• Good direction on surfacing actionable recovery steps (timeout/session/MCP/auth) instead of opaque “failed” text.
• The type-first dispatch plus keyword fallback is pragmatic and should improve UX for both known and partially-known failures.
• Nice improvement replacing generic Telegram send failures with actual provider error snippets.

Issues / questions

1. [Important] src/bot/handlers/message.py (_format_error_message) — the branch if isinstance(error_obj, ClaudeError): return _format_process_error(error_str) can unintentionally downgrade more specific ClaudeError subclasses that are not handled above (e.g., ClaudeToolValidationError) into a generic “Claude Process Error”, losing prior user-friendly messaging. Is that intended? If not, consider explicitly preserving known ClaudeError subtypes before this catch-all.
2. [Important] src/bot/handlers/message.py (_format_error_message) — keyword matching for auth/connection/MCP occurs on free-form strings and may misclassify unrelated errors (e.g., user content containing “connection” or “authentication”). Suggest tightening predicates (structured fields or known prefixes) to reduce false positives.
3. [Nit] poetry.lock — this PR includes a broad lockfile/toolchain shift (Poetry 2.1.3 -> 2.3.2, python-versions ^3.10 -> ^3.11) that appears orthogonal to error-message behavior. If unintentional, consider splitting to a separate PR to keep rollback/review risk lower.

Suggested tests (if needed)

• Add targeted unit tests for _format_error_message covering: each typed exception path, a generic ClaudeError, string-only fallbacks, and truncation boundaries (<=500 and >500).
• Add a regression test ensuring known validation/tool errors are not regressed to generic process text.
• Add one test for Telegram send fallback to verify the plain-text error includes provider details and remains bounded.

Verdict

• ⚠️ Merge after fixes