Skip to main content

circuit-breaker-open Hook

Metadata​

name: circuit-breaker-open
version: 1.0.0
category: resilience
status: active
priority: P1
trigger: CircuitBreaker state changes to OPEN
derived_from: Claude Operating Preferences v4.0/v5.0

Description​

Triggered when a circuit breaker transitions to the OPEN state due to repeated failures. Logs the event, notifies the user, and suggests mitigation strategies.

Trigger Conditions​

  • Circuit breaker failure count exceeds threshold
  • Circuit transitions from CLOSED to OPEN
  • Circuit transitions from HALF_OPEN to OPEN (recovery failed)

Actions​

  1. Log Event

    • Record circuit name and failure count
    • Log last error details
    • Record timestamp and recovery timeout

  2. Notify User

    • Display warning about service degradation
    • Show affected operations
    • Provide retry_after time

  3. Suggest Mitigation

    • Recommend fallback strategies
    • Suggest manual intervention if needed
    • Provide health check command

Configuration​

# hooks/circuit-breaker-open.yaml
hook:
  name: circuit-breaker-open
  enabled: true

triggers:
  - event: circuit_state_change
    from_state: [CLOSED, HALF_OPEN]
    to_state: OPEN

actions:
  - type: log
    level: warning
    include:
      - circuit_name
      - failure_count
      - last_error
      - recovery_timeout

  - type: notify
    message: |
      Circuit breaker OPEN: {circuit_name}
      Failures: {failure_count}
      Retry after: {recovery_timeout}s

  - type: suggest
    options:
      - "Wait for recovery timeout"
      - "Use fallback service"
      - "Manual intervention required"

Example Output​

[HOOK: circuit-breaker-open]

Circuit Breaker OPEN
--------------------
Circuit:    external_api
State:      CLOSED → OPEN
Failures:   5 consecutive
Last Error: ConnectionTimeout after 30s
Recovery:   60s (retry at 15:05:00)

Health Report
-------------
Success Rate: 0%
Last Success: 15:02:45
P95 Latency:  28.5s (before failure)

Mitigation Options
------------------
1. Wait 60s for automatic recovery attempt
2. Use cached data if available
3. Run: /circuit-status external_api --force-half-open

Warning: Operations using external_api will fail until recovery.

Integration​

class CircuitBreakerOpenHook:
    """Hook handler for circuit breaker open events"""

    async def on_circuit_open(
        self,
        circuit_name: str,
        failure_count: int,
        last_error: str,
        recovery_timeout: float,
        health_report: dict
    ):
        """Handle circuit opening"""
        self._log_event(circuit_name, failure_count, last_error)
        self._notify_user(circuit_name, recovery_timeout)
        self._suggest_mitigation(circuit_name, health_report)

    def _log_event(
        self,
        circuit_name: str,
        failure_count: int,
        last_error: str
    ):
        """Log circuit open event"""
        import logging
        logger = logging.getLogger("circuit_breaker")
        logger.warning(
            f"Circuit {circuit_name} OPEN after {failure_count} failures. "
            f"Last error: {last_error}"
        )

    def _notify_user(self, circuit_name: str, recovery_timeout: float):
        """Notify user of circuit open"""
        from datetime import datetime, timedelta
        retry_time = datetime.now() + timedelta(seconds=recovery_timeout)

        print(f"\n[HOOK: circuit-breaker-open]")
        print(f"Circuit: {circuit_name}")
        print(f"Status: OPEN")
        print(f"Retry at: {retry_time.strftime('%H:%M:%S')}")

    def _suggest_mitigation(self, circuit_name: str, health_report: dict):
        """Suggest mitigation strategies"""
        success_rate = health_report.get("success_rate", 0)

        if success_rate == 0:
            print("\nRecommendation: Service appears down. Consider fallback.")
        else:
            print(f"\nRecommendation: Intermittent failures ({success_rate*100:.0f}% success)")

        print(f"Check status: /circuit-status {circuit_name}")
  • skills/circuit-breaker-patterns/ - Circuit breaker implementation
  • agents/circuit-breaker-monitor.md - Monitoring agent
  • commands/circuit-status.md - CLI command
  • scripts/circuit-breaker-manager.py - Management script