Plugin framework: on_state_change_callback is never invoked

[mportdata]

Description

The plugin framework provides hooks for various lifecycle events (before/after agent, tool, model callbacks, etc.), but there is no mechanism to notify plugins when session state changes occur via event.actions.state_delta.

The BigQueryAgentAnalyticsPlugin already implements an on_state_change_callback() method, demonstrating real demand for this hook, but the framework never invokes it because:

1. BasePlugin has no default on_state_change_callback method
2. PluginManager has no dispatcher for it
3. The runner never detects state deltas and triggers the callback

Expected Behavior

When an event with a non-empty state_delta is yielded from the runner, all registered plugins should have their on_state_change_callback invoked with the state delta (as a copy, to prevent mutation).

Proposed Solution

1. Add on_state_change_callback to BasePlugin as a default no-op method
2. Add "on_state_change_callback" to PluginCallbackName and a run_on_state_change_callback dispatcher to PluginManager
3. In Runner._exec_with_plugin, after yielding the final event, check for state_delta and invoke the callback

The callback should be observational (return value ignored) and receive a copy of the state delta to prevent plugins from mutating event state.

[mportdata]

Fix awaiting review here: #4395

[wuliang229]

@haiyuan-eng-google please take a look.

[haiyuan-eng-google]

Confirmation

You are absolutely correct. We have verified that:

1. BigQueryAgentAnalyticsPlugin implements on_state_change_callback, but it is effectively dead code.
2. BasePlugin and PluginManager do not define or support this callback.
3. The Runner does not dispatch any specific callback when yielding events with state_delta.

This is a clear gap in the plugin lifecycle hooks. While on_event_callback exists, a dedicated on_state_change_callback is cleaner and semantically more appropriate for state mutations, especially given that BigQueryAgentAnalyticsPlugin already expects it.

Plan

1. Framework Update: Add on_state_change_callback to BasePlugin (no-op default) and PluginManager.
2. Runner Integration: Update Runner._exec_with_plugin (and potentially _append_new_message_to_session) to invoke this callback whenever an event contains a non-empty state_delta.
3. Safety: Ensure the callback receives a copy of the delta to prevent accidental mutation of the event itself.