Enum TriggerEvent 

pub enum TriggerEvent {
    TriggerHandlingStart {
        idempotency_key: String,
        source_kind: SourceKind,
        source_label: String,
        event_label: String,
        trace_id: String,
    },
    TriggerHandled {
        idempotency_key: String,
        trace_id: String,
        state: TriggerState,
        audit_entry_id: Option<String>,
        evaluator_decision: Option<Value>,
    },
    TriggerPromptRequest {
        request: TriggerPromptRequest,
    },
    PersistenceError {
        context: String,
        message: String,
    },
    TriggerExecutionStarted {
        trace_id: String,
        source_label: String,
        event_label: String,
        prompt_preview: String,
    },
    TriggerCompleted {
        trace_id: String,
        summary: Option<String>,
        cost_usd: Option<f64>,
        details: Value,
    },
    TriggerFailed {
        trace_id: String,
        reason: String,
    },
    TriggerRequestsMainRun {
        trace_id: String,
    },
    TriggerPromoted {
        trace_id: String,
        promote_kind: String,
        inserted_entry_id: String,
        template_name: Option<String>,
        redaction_status: String,
    },
    PromotionPending {
        trace_id: String,
        promote_kind: String,
        template_name: Option<String>,
        preview: Option<String>,
    },
}

Event emitted by the trigger executor as a trigger moves through its lifecycle.

Variants

TriggerHandlingStart

The executor has admitted a Trigger for processing — fires immediately at the start of TriggerExecutor::handle_trigger before evaluation. Carries the source identification needed to render a “processing X” banner. RFC 1 §2.7.

Fields

idempotency_key: String

source_kind: SourceKind

source_label: String

event_label: String

trace_id: String

TriggerHandled

Terminal: the trigger reached an end state. state is one of the terminal variants (Accepted / Deduped / CycleSuppressed / PermissionDenied / NeedsApproval).

audit_entry_id is the SessionTreeEntry::Custom id when persistence succeeded, None if persistence failed (a parallel PersistenceError event will describe the failure).

evaluator_decision mirrors what was persisted in the audit record (same JSON shape) so live subscribers (TUI banner, /triggers, JSONL logs) can render why the trigger reached its state without a secondary session lookup. Shape:

• Accept (Allow): { "outcome": "accept", "permission": "allow" }
• Accept (Deny): { "outcome": "accept", "permission": "deny", "reason": ... }
• Accept (Prompt):{ "outcome": "accept", "permission": "prompt", "reason": ... }
• Deduped: { "outcome": "deduped", "replacement_policy": ..., "previous_trace_id": ... }
• CycleSuppressed:{ "outcome": "cycle_suppressed", "hop_count": N }

None only when audit serialization failed (a PersistenceError will accompany).

Fields

idempotency_key: String

trace_id: String

state: TriggerState

audit_entry_id: Option<String>

evaluator_decision: Option<Value>

TriggerPromptRequest

A trigger admitted by the dedup / cycle evaluator reached BeforeTriggerDecision::Prompt and is awaiting an embedder-owned user decision.

The prompt is bound by trigger_prompt_id, not by a tool-call id / args hash, so a decision cannot be replayed onto a different trigger envelope. The executor also writes a trigger_prompt Custom audit entry when the prompt resolves.

Fields

request: TriggerPromptRequest

PersistenceError

Best-effort persistence error reflux from the trigger engine. The trigger itself still produced a TriggerHandled event with audit_entry_id = None; this event explains why so that observability (TUI banner, /triggers, JSONL logs) can mark the audit as best-effort lost rather than dropping it silently.

context is free-form with pinned strings: "trigger_audit", "trigger_result", "trigger_prompt", "trigger_promotion", "trigger_inject_and_run". New write sites must pin themselves to a stable string.

Fields

context: String

message: String

Short, secret-free message. The original SessionError is not exposed because some implementations include filesystem paths or storage backend details that belong in trace logs, not user-facing event surfaces.

TriggerExecutionStarted

A sub-agent execution started for an accepted trigger. Emitted by the spawned task just before the sub-agent’s first turn runs. prompt_preview is the first ~80 characters of the resolved action prompt, preview-safe for banners.

Fields

trace_id: String

source_label: String

event_label: String

prompt_preview: String

TriggerCompleted

A sub-agent execution finished successfully and the parent trigger_result audit entry has been written. summary is the sub-agent’s self-summary (size-capped at 4 KiB). cost_usd is None when the bare sub-Agent had no CostTracker wrapper (mirrors the audit’s cost_usd: null).

details is the structured sub-agent result envelope populated through marker tools (see TriggerResultDetailsBuilder). Defaults to serde_json::Value::Null. Authorization for PromoteAction::PromoteSummaryWhenResultDetailsMatch flows exclusively through this field — summary is display-only.

Fields

trace_id: String

summary: Option<String>

cost_usd: Option<f64>

details: Value

TriggerFailed

A sub-agent execution failed (agent loop error, panic-via-spawn-error, or aborted by TriggerExecutor::abort_trigger / abort_all_triggers). reason is sanitized — never contains raw payload, provider response bodies, or credential material. The parent trigger_result audit entry has been written with success: false.

Fields

trace_id: String

reason: String

TriggerRequestsMainRun

An TriggerDelivery::InjectAndRun trigger has injected its prompt into the idle parent conversation and is asking the embedder to run ONE model turn in the parent’s full context. The executor never runs the single-tenant parent agent itself from the detached trigger task, so it delegates: the embedder (which owns the parent agent and its input loop) should funnel this through the same serialized path as user input and call AgentHarness::continue_. Emitted only on the idle path — when the parent is mid-turn the runtime enqueues a follow-up instead and this event is NOT emitted.

Fields

trace_id: String

TriggerPromoted

A trigger’s PromoteAction rendered successfully and the executor committed to surfacing the sub-agent result to the user / LLM. theway_llm_provider has no System role today; the inserted entry is a Message::User with a [Trigger ...] body prefix so the LLM disambiguates trigger-driven context from human input.

inserted_entry_id semantics depend on the parent agent state at promotion time:

• Idle parent: durable id of the appended Message::User (matches the audit).
• Streaming parent (queued through the loop’s follow-up queue): empty string because the session entry ID is only known after the loop drains the queue. Consumers should correlate by trace_id in this case.

Fields

trace_id: String

promote_kind: String

inserted_entry_id: String

template_name: Option<String>

redaction_status: String

PromotionPending

A trigger’s PromoteAction was held pending approval (promote_requires_approval = true) and is awaiting an explicit /triggers approve <trace_id>. The parent transcript has NOT been modified; a trigger_promotion audit entry with state: "pending" has been written. preview is the rendered template body the approval UI would surface, or None when the render itself would have failed.

Fields

trace_id: String

promote_kind: String

template_name: Option<String>

preview: Option<String>

Trait Implementations

impl Clone for TriggerEvent

fn clone(&self) -> TriggerEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TriggerEvent

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

Formats the value using the given formatter.