feat: Allow users to control Mechanism.Handled for captured exceptions

[vladbrincoveanu]

Closes #3383

Implements the approach agreed in this comment: SDK users get explicit control over Mechanism.Handled, and manually captured exceptions default to handled: true.

API changes

New overloads for explicit control:

• SentrySdk.CaptureException(Exception exception, bool handled, bool terminal = false)
• SentrySdk.CaptureException(Exception exception, bool handled, bool terminal, Action<Scope> configureScope)
• SentryClientExtensions.CaptureException(this ISentryClient client, Exception ex, bool handled, bool terminal = false)
• HubExtensions.CaptureException(this IHub hub, Exception ex, bool handled, bool terminal, Action<Scope> configureScope)

The existing signatures are kept, so this is source- and binary-compatible. handled is a required parameter rather than optional: an optional one would be permanently shadowed by the existing exact-match overloads, and replacing those signatures would be binary-breaking.

Behavior

• Explicit wins. Passing handled records that value, overriding any flag previously set on the exception (including via SetSentryMechanism).
• The existing overloads are untouched. They write nothing to Exception.Data, so there is no implicit precedence between a preset flag and a plain CaptureException(ex) call.
• The default moved into MainExceptionProcessor. Any exception no integration claimed is now marked handled: true, replacing the previous "thrown ⇒ true, never thrown ⇒ null" heuristic. This is what fixes the symptom Allow SDK users to control Mechanism.Handled for captured exceptions #3383 opens with: SentrySdk.CaptureException(new Exception()) reported Handled -- and now reports Handled: true, per the protocol docs ("exceptions captured using capture_exception are handled=true"), which are cited at the decision site. Thrown-and-caught exceptions reported Handled: true before and still do.
• CaptureExceptionInternal (the integration capture path) defaults to handled: false when no flag is already set, since integrations capture exceptions that user code did not handle. All four call sites set the flag via SetSentryMechanism first (WinUI forwards the platform's value), so the default is a defensive fallback only. Terminal is deliberately left unset there, so a missing SetSentryMechanism call still reads as a crash.
• Terminal is now controllable too, per the discussion below. It only applies when handled: false; passing handled: true removes any terminal flag left over from an earlier SetSentryMechanism call, mirroring that method's null-removes semantics. The default terminal: false means a manual unhandled capture marks the session as unhandled without ending it as crashed and leaves the active transaction running — a manual capture should not dent the crash-free-sessions rate when nothing actually crashed. terminal: true ends the session as crashed and aborts the active transaction. This is a deliberate divergence from SetSentryMechanism(type, handled: false), which leaves Terminal unset and therefore still counts as a crash. The WinUI integration is left as a follow-up rather than expanding this PR's scope.

Testing

Unit tests cover explicit true/false on every capture path, explicit values overriding preset flags, the untouched plain overloads, and the integration-path default. Terminal coverage asserts the session outcome for each combination (ReportError, MarkSessionAsUnhandled, EndSession(Crashed)) and that only terminal captures abort the active transaction. Verify snapshots updated: API approvals for all four target frameworks, the aggregate-exception mechanism snapshot, and the Sentry.DiagnosticSource / Sentry.EntityFramework integration snapshots, where constructed-and-captured exceptions now report Handled: true.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.74%. Comparing base (6516897) to head (6b50143).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5449      +/-   ##
==========================================
+ Coverage   74.62%   74.74%   +0.11%     
==========================================
  Files         512      513       +1     
  Lines       18672    18744      +72     
  Branches     3657     3666       +9     
==========================================
+ Hits        13934    14010      +76     
+ Misses       3865     3862       -3     
+ Partials      873      872       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[vladbrincoveanu]

We have a warden failing check.
Could you please have a look @jamescrosswell ?
Warden cannot review this fork pull request because GitHub withholds repository secrets from fork workflows
Thanks.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1d662b6. Configure here.}

[jamescrosswell]

@vladbrincoveanu thank you very much for the PR... it does raise some tricky problems though - see my inline comments below.

[jamescrosswell]

This would be a change in behaviour. I think it probably makes sense... we can probably do it without making a major release - arguably it's a bug fix rather than an arbitrary change.

@dingsdax do you have any steer?

[jamescrosswell]

@vladbrincoveanu huge thank you for the PR - it's a meaningful improvement to the SDK 🙏🏻