Skip to content

[Feature]: Emit first-class plugin hooks for model failover and terminal all-models-failed outcomes #70976

Description

@mantisai-bot

[Feature]: Emit first-class plugin hooks for model failover and terminal all-models-failed outcomes

Summary

Add first-class plugin hooks for model failover decisions and terminal "all models failed before reply" outcomes.

Problem to solve

OpenClaw already detects when a run fails over to another model and when a run collapses before reply because no usable model remains. Today those signals are mainly exposed through logs such as embedded_run_failover_decision and Embedded agent failed before reply: ....

That leaves a real automation gap:

  • alerting depends on polling or tailing gateway logs
  • plugins cannot react in-process to failover decisions
  • existing hooks like agent_end are too coarse to explain which model failed, whether fallback was attempted, or why the chain was exhausted

This is currently one part of the broader #65824 item about silent model fallback, but the hook/event gap is narrow enough to track separately.

Proposed solution

Add a dedicated plugin hook surface for:

  • model failover decisions during a run
  • terminal before-reply failures when no usable model remains

The goal is to let plugins and operators react to failover activity through structured in-process events instead of log parsing.

Alternatives considered

  • Keep relying on logs: works today, but it is brittle, delayed, and depends on parsing stderr text.
  • Reuse agent_end: too coarse, loses the actual failover chain and reason details.
  • Add more log lines only: improves observability but still does not create a real automation surface.

Impact

Affected: plugin authors, operators, alerting workflows, provider-health automation
Severity: annoying to workflow-blocking during provider outages
Frequency: intermittent but high-value when it happens
Consequence: silent failures, delayed alerts, brittle monitoring, poor user-facing explanations

Evidence/examples

OpenClaw already has the relevant internal seam:

  • structured failover logging in src/agents/pi-embedded-runner/run/failover-observation.ts
  • terminal before-reply failure logging in src/agents/pi-embedded-runner/run.ts

That means the runtime already knows the right facts. The missing piece is a first-class plugin/event surface.

Related references:

  • #65824 meta issue, item fix: add @lid format support and allowFrom wildcard handling #1 explicitly notes there is no externally exposed fallback event for hooks
  • #63821 asks for better failover observability via logs, which is related but weaker than a real hook surface
  • #61485 expands plugin hook capability in nearby lifecycle areas, showing precedent for growing the hook system
  • #64085 wants provider health / circuit-breaker behavior, which also benefits from structured failover events

Additional information

This issue is intentionally scoped only to the hook/event gap. It does not try to solve the other parts of #65824 item #1, such as non-verbose fallback notices or workspace-context re-injection.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions