Feature Request: OnPipelineErrorCallback Lifecycle Hook

🔴 Required Information

Is your feature request related to a specific problem?

Currently, the plugin.Config struct provides precise, granular hooks for structural runtime failures like OnModelErrorCallback and OnToolErrorCallback. However, there is a visibility and control gap for errors encountered during orchestrator lifecycles.

If an error occurs during runtime execution setups-such as within an OnUserMessageCallback or a BeforeRunCallback-the underlying framework immediately propagates the error up the call stack, halting execution. Independent plugin developers lack a native mechanism to intercept these orchestrator-level failures to perform telemetry logging, clean up transient states, or implement custom retry/fallback behaviors globally for the agent pipeline.

Proposed Solution

Introduce an OnPipelineErrorCallback lifecycle hook to the plugin.Config and plugin.Plugin structures. This callback will capture any pipeline-level error that escapes granular tool/model loops, allowing plugins to inspect the error context, log telemetry data, gracefully transform or wrap the error before propagation, or return a fallback response payload.

Impact on your work

This feature significantly improves the design of enterprise-grade telemetry and resilience plugins. Without it, our global error tracking wrappers cannot safely intercept lifecycle anomalies without risking unhandled pipeline failures or losing context from the agent.InvocationContext.

🟡 Recommended Information

Alternatives Considered

Writing custom boilerplate code inside every individual agent implementation to wrap the runner call in a recover() or manual try-catch style pattern defeats the modularity and design pattern of the ADK plugin infrastructure.

Willingness to contribute

Yes, I am interested in implementing this feature and submitting a PR.

Proposed API / Implementation

1. Extend plugin.Config and plugin.Plugin

type OnPipelineErrorCallback func(agent.InvocationContext, error) error

type Config struct {
	Name string

	// Existing fields...
	OnUserMessageCallback OnUserMessageCallback
	BeforeRunCallback     BeforeRunCallback

	// OnPipelineErrorCallback intercepts errors occurring during orchestration lifecycles.
	OnPipelineErrorCallback OnPipelineErrorCallback
}

2. Expose an accessor on the Plugin struct

func (p *Plugin) OnPipelineErrorCallback() OnPipelineErrorCallback {
	return p.onPipelineErrorCallback
}

3. Integrate into Runtime Orchestration Engine

The runner component executing the lifecycle callbacks will pass unresolved lifecycle errors into the active plugin stack’s OnPipelineErrorCallback loop before aborting execution entirely.

Additional Context

Completes the parity lifecycle symmetry alongside OnModelError and OnToolError blocks already present in plugin.go.