feat(stream): add optional typed streaming callbacks

[activadee]

This PR introduces an optional sugar layer for handling typed streaming events without writing a large switch over ThreadEvent.

Summary

• Add StreamCallbacks with a generic OnEvent and type-specific hooks (message, reasoning, command execution, patch + per-file changes, web search, MCP tool call, todo list, error item).
• Wire callbacks into Thread.runStreamed so callbacks run first, then the raw event is forwarded through Events(), preserving backpressure semantics.
• Extend TurnOptions with a Callbacks field to opt into the feature.
• Document usage in README with a runnable example under examples/streaming_callbacks.
• Add tests verifying typed callback dispatch and stages.

Notes

• Callbacks execute on the streaming goroutine. Offload long-running work to avoid stalling the stream.
• Continue draining the Events() channel even when using callbacks to honour backpressure expectations.
  closes SDK DX: streaming callbacks (OnMessage/OnCommand/OnWebSearch/OnPatch/OnFileChange) #14

[github-actions]

Codex Review Summary

Recommendation: ✅ Ready to merge – no blocking issues detected.

Summary:
All changes look solid. The new callback plumbing in thread.go:97 invokes user hooks only after the thread ID is set, the typed payloads in callbacks.go:17 mirror our item types correctly, and the regression test in thread_stream_test.go:49 exercises the critical paths. With documentation updated in README.md:75 and the runnable sample in examples/streaming_callbacks/main.go:1, I’m confident the feature behaves as expected. Only remaining consideration is the documented need for callers to keep draining RunStreamed’s Events() channel when relying on callbacks.

Inline findings:

• No inline findings.

Generated at 2025-11-06T20:28:06.800Z.