Enum StopReason 

#[non_exhaustive]
pub enum StopReason {
    Converged,
    CriteriaMet {
        criteria: Vec<CriterionId>,
    },
    UserCancelled,
    HumanInterventionRequired {
        criteria: Vec<CriterionId>,
        approval_refs: Vec<ApprovalPointId>,
    },
    CycleBudgetExhausted {
        cycles_executed: u32,
        limit: u32,
    },
    FactBudgetExhausted {
        facts_count: u32,
        limit: u32,
    },
    TokenBudgetExhausted {
        tokens_consumed: u64,
        limit: u64,
    },
    TimeBudgetExhausted {
        duration_ms: u64,
        limit_ms: u64,
    },
    InvariantViolated {
        class: InvariantClass,
        name: String,
        reason: String,
    },
    PromotionRejected {
        proposal_id: ProposalId,
        reason: String,
    },
    Error {
        message: String,
        category: ErrorCategory,
    },
    AgentRefused {
        agent_id: String,
        reason: String,
    },
    HitlGatePending {
        gate_id: GateId,
        proposal_id: ProposalId,
        summary: String,
        agent_id: String,
        cycle: u32,
    },
}

Why execution stopped. Exhaustive enumeration for audit trails.

Every engine run terminates with a StopReason. This enables:

• Audit: Know exactly why execution ended
• Recovery: Different reasons may have different retry strategies
• Monitoring: Track termination patterns

Non-Exhaustive

Marked #[non_exhaustive] to allow adding new reasons without breaking existing match statements.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Converged

Convergence reached - context stabilized (fixed point). This is the ideal outcome.

CriteriaMet

Intent criteria satisfied before convergence. All success conditions met, no need to continue.

Fields

criteria: Vec<CriterionId>

Which criteria were satisfied

UserCancelled

User requested stop via cancellation. Graceful termination, not an error.

HumanInterventionRequired

Agents converged, but completion is blocked on human intervention. Unlike HitlGatePending, the engine did not pause mid-merge; the application-level criteria evaluation determined that a human must act before the truth can be considered complete.

Fields

criteria: Vec<CriterionId>

Which required criteria are blocked.

approval_refs: Vec<ApprovalPointId>

Optional approval/workflow references surfaced by the evaluator.

CycleBudgetExhausted

Maximum execution cycles exceeded. May indicate non-converging problem or need for larger budget.

Fields

cycles_executed: u32

How many cycles were executed

limit: u32

What the limit was

FactBudgetExhausted

Maximum facts in context exceeded. Prevents unbounded context growth.

Fields

facts_count: u32

How many facts were in context

limit: u32

What the limit was

TokenBudgetExhausted

Maximum LLM tokens exceeded. Cost control for LLM-based operations.

Fields

tokens_consumed: u64

How many tokens were consumed

limit: u64

What the limit was

TimeBudgetExhausted

Maximum wall-clock time exceeded. Prevents indefinite execution.

Fields

duration_ms: u64

How long execution ran (milliseconds)

limit_ms: u64

What the limit was (milliseconds)

InvariantViolated

An invariant was violated. Includes the class (Structural/Semantic/Acceptance) and invariant name.

Fields

class: InvariantClass

Which class of invariant

name: String

Name of the invariant

reason: String

Description of the violation

PromotionRejected

Promotion gate rejected a proposal. Proposal failed validation and could not be promoted.

Fields

proposal_id: ProposalId

ID of the rejected proposal

reason: String

Why it was rejected

Error

Unrecoverable error during execution. Something went wrong that couldn’t be handled.

Fields

message: String

Error message

category: ErrorCategory

Error category for programmatic handling

AgentRefused

An agent refused to continue. Suggestor explicitly declined to produce output.

Fields

agent_id: String

ID of the refusing agent

reason: String

Why it refused

HitlGatePending

Convergence paused at a human-in-the-loop gate. A proposal requires human approval before convergence can continue. The hosting application should notify the human and call Engine::resume() with the decision.

Fields

gate_id: GateId

Unique ID for this gate (used to resume)

proposal_id: ProposalId

ID of the proposal awaiting approval

summary: String

Human-readable summary of the proposal

agent_id: String

Which agent made the proposal

cycle: u32

Cycle at which convergence was paused

Implementations

impl StopReason

pub fn converged() -> StopReason

Create a Converged stop reason.

pub fn criteria_met(criteria: Vec<CriterionId>) -> StopReason

Create a CriteriaMet stop reason.

pub fn user_cancelled() -> StopReason

Create a UserCancelled stop reason.

pub fn human_intervention_required( criteria: Vec<CriterionId>, approval_refs: Vec<ApprovalPointId>, ) -> StopReason

Create a HumanInterventionRequired stop reason.

pub fn cycle_budget_exhausted(cycles_executed: u32, limit: u32) -> StopReason

Create a CycleBudgetExhausted stop reason.

pub fn fact_budget_exhausted(facts_count: u32, limit: u32) -> StopReason

Create a FactBudgetExhausted stop reason.

pub fn token_budget_exhausted(tokens_consumed: u64, limit: u64) -> StopReason

Create a TokenBudgetExhausted stop reason.

pub fn time_budget_exhausted(duration_ms: u64, limit_ms: u64) -> StopReason

Create a TimeBudgetExhausted stop reason.

pub fn invariant_violated( class: InvariantClass, name: impl Into<String>, reason: impl Into<String>, ) -> StopReason

Create an InvariantViolated stop reason.

pub fn promotion_rejected( proposal_id: impl Into<ProposalId>, reason: impl Into<String>, ) -> StopReason

Create a PromotionRejected stop reason.

pub fn error(message: impl Into<String>, category: ErrorCategory) -> StopReason

Create an Error stop reason.

pub fn agent_refused( agent_id: impl Into<String>, reason: impl Into<String>, ) -> StopReason

Create an AgentRefused stop reason.

pub fn hitl_gate_pending( gate_id: impl Into<GateId>, proposal_id: impl Into<ProposalId>, summary: impl Into<String>, agent_id: impl Into<String>, cycle: u32, ) -> StopReason

Create a HitlGatePending stop reason.

pub fn is_success(&self) -> bool

Returns true if this is a successful termination.

pub fn is_budget_exhausted(&self) -> bool

Returns true if this is a budget exhaustion.

pub fn is_validation_failure(&self) -> bool

Returns true if this is a validation failure.

pub fn is_error(&self) -> bool

Returns true if this is an error condition.

pub fn is_hitl_pending(&self) -> bool

Returns true if convergence is paused at a HITL gate.

pub fn is_human_intervention_required(&self) -> bool

Returns true if completion is blocked on human intervention.

Trait Implementations

impl Clone for StopReason

fn clone(&self) -> StopReason

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StopReason

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StopReason

fn deserialize<__D>( __deserializer: __D, ) -> Result<StopReason, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for StopReason

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for StopReason

fn eq(&self, other: &StopReason) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for StopReason

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for StopReason

impl StructuralPartialEq for StopReason