feat: Add OnPipelineErrorCallback lifecycle hook to Plugin Config

[mramansayyad]

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.

[mramansayyad]

I have implemented this feature. The pull request is available here: #887