callback_wrapper middleware around every user-callback dispatch (#47 phase 2)

[ya-luotao]

Summary

Implements phase 2 of #47 (Option D): ClaudeAgentOptions#callback_wrapper — optional middleware composed around every user-callback dispatch through FiberBoundary (message blocks, observers, hooks, permission callbacks, SDK MCP tool/resource/prompt handlers), in both :thread and :inline modes.

ClaudeAgentSDK.configure do |config|
  config.default_options = {
    callback_wrapper: ->(inv) { Rails.application.executor.wrap { inv.call } }
  }
end

The wrapper runs on the same execution context as the callback — inside the worker thread in :thread mode (so executor.wrap checks ActiveRecord connections back in when the callback ends, retiring the stranded-connection workaround without adopting inline), in place on the reactor fiber in :inline mode. Also a generic hook for APM/logging context propagation. Default nil — zero behavior change.

Design points

• Composed before the thread hop in FiberBoundary.invoke — that ordering is the entire feature.
• Break is invisible to wrappers: the LocalJumpError → Break translation lives inside the invocation handed to the wrapper, so a conforming rescue/report/re-raise wrapper observes a clean return on a user's break, never an exception it could falsely report — and a swallowing wrapper cannot lose the break.
• Travels with the scheduling mode through the existing SchedulingScope fiber-storage carrier to shared SDK MCP servers; the pair is resolved atomically (effective_callback_dispatch, one liveness decision) so a scope closing mid-resolution can never yield a torn session-mode/server-wrapper mix. Server instances are never mutated; descendants outliving the dispatch fall back to server defaults — all phase-1 invariants preserved.
• Inline hook timeouts (InlineCancellation < Exception) pass through StandardError-rescuing wrappers un-swallowed.
• The timeout-bounded store-adapter path deliberately ignores wrappers (hard-timeout carve-out, unchanged).

Process

Implemented by a Claude Code agent against a written spec, reviewed by me, then adversarially reviewed by codex (gpt-5.6-sol ultra) — which found two real defects (torn pair resolution under concurrent scope closure, reviewer-reproduced; break exposed to wrappers as LocalJumpError), both fixed in 14a6fa9 and re-verified by the reviewer's own probes. Final verdict: SHIP.

Testing

• New spec/unit/callback_wrapper_spec.rb (37 examples): exactly-once wrapping per callback type in both modes, wrapper-on-worker-thread / wrapper-on-reactor-fiber assertions, return value passthrough + exception propagation (incl. wrapper-raised), break through wrappers (ensure-based, reporting, swallowing), InlineCancellation pass-through, shared-server cross-session wrapper isolation, descendant-fiber fallback, torn-pair regression (deterministic mid-resolution flip), direct-call defaults, validation, global config.
• Full suite: 1182 examples, 0 failures — including order-sensitive seeds 62610/48816; rubocop clean.

Closes the phase-2 item of #47. Refs #47.

🤖 Generated with Claude Code

https://claude.ai/code/session_019Manwfh1GRrJtQfgTm1dtt