Advisory Guards

AdvisorySignal and AdvisorySeverity

pub struct AdvisorySignal {
    /// Name of the advisory guard that produced this signal.
    pub guard_name: String,
    /// Human-readable description of the observation.
    pub description: String,
    /// Severity level.
    pub severity: AdvisorySeverity,
    /// Structured metadata about the observation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
    /// Whether this signal has been promoted to a deterministic denial.
    /// This is set by the promotion policy, not by the advisory guard itself.
    #[serde(default)]
    pub promoted: bool,
}

pub enum AdvisorySeverity {
    /// Informational observation -- no action needed.
    Info,
    /// Low-severity warning -- worth monitoring.
    Low,
    /// Medium-severity warning -- may warrant investigation.
    Medium,
    /// High-severity warning -- likely needs attention.
    High,
    /// Critical observation -- strong signal of abuse or anomaly.
    Critical,
}

The five severity levels are ordered by declaration, and promotion rules compare against that ordinal. metadata carries structured detail for the receipt and downstream tooling: the tool name, the count and threshold for an anomaly, the byte volume for a transfer guard. The pipeline writes the field through serde as the guard produced it, so each advisory guard keeps its own metadata schema stable.

AdvisoryGuard trait

pub trait AdvisoryGuard: Send + Sync {
    /// Human-readable guard name.
    fn name(&self) -> &str;

    /// Evaluate the request and return any advisory signals.
    ///
    /// The returned signals are informational only and do not affect the
    /// request verdict unless a promotion policy is in effect.
    fn evaluate(&self, ctx: &GuardContext) -> Result<Vec<AdvisorySignal>, KernelError>;
}

The trait is separate from chio_kernel::Guard: it returns a vector of signals instead of a verdict. A successful advisory evaluation leaves the decision as Allow unless a promotion rule returns Deny. An internal failure, such as a backing journal error, surfaces as KernelError, which the pipeline treats as fail-closed downstream.

AnomalyAdvisoryGuard

Reads from a session journal and emits signals on two patterns:

• A per-tool invocation count meets or exceeds invocation_threshold. Severity escalates to High at 2× the threshold; otherwise it is Medium.
• The maximum delegation depth meets or exceeds depth_threshold. Severity is High.

pub struct AnomalyAdvisoryGuard {
    journal: Arc<chio_http_session::SessionJournal>,
    invocation_threshold: u64,
    depth_threshold: u32,
}

The journal is shared across the kernel, and the advisory guards read it without mutating it. AnomalyAdvisoryGuard and DataTransferAdvisoryGuard each call SessionJournal::snapshot() once per evaluation; the single-lock read returns tool counts and data flow together in a SessionJournalSnapshot. Journal errors, including lock poisoning and backing-store failures, return KernelError::Internal.

DataTransferAdvisoryGuard

Reads cumulative bytes in plus bytes out from the journal's data-flow counters and emits one signal per call when the total meets or exceeds the configured threshold.

pub struct DataTransferAdvisoryGuard {
    journal: Arc<chio_http_session::SessionJournal>,
    bytes_threshold: u64,
}

• Below the threshold: no signal.
• At 1× and below 2×: Medium.
• At 2× and below 3×: High.
• At 3× and above: Critical.

BehavioralProfileGuard

Source crates/guards/chio-guards/src/behavioral_profile.rs, guard name behavioral-profile. It is a synchronous Guard whose verdict is always Allow, and it emits a GuardEvidence entry when a window trips its threshold. It tracks exponentially weighted moving-average baselines per agent and metric over four metrics, and flags a window whose sample crosses the configured sigma threshold against the rolling baseline.

call_rate

Receipts per window.

deny_rate

Fraction of denies per window.

unique_tools

Distinct tool names per window.

avg_parameter_entropy

Shannon entropy of invocation parameters.

Baselines live in an in-memory, Mutex-guarded map keyed by (agent, metric). Receipts arrive through the pluggable ReceiptFeedSource trait: deployments back it with chio-store-sqlite's ReceiptStore::query_receipts, and InMemoryReceiptFeed serves tests.

PromotionRule and PromotionPolicy

pub struct PromotionRule {
    /// Guard name pattern to match (exact match).
    pub guard_name: String,
    /// Minimum severity to promote. Signals at or above this level
    /// from the named guard become deterministic denials.
    pub min_severity: AdvisorySeverity,
}

pub struct PromotionPolicy {
    /// Rules for promoting advisory signals to deterministic denials.
    pub rules: Vec<PromotionRule>,
}

The match is exact on guard_name and ordinal on severity. A promoted signal has its promoted flag set by the policy, never by the advisory guard itself.

AdvisoryPipeline

Wraps a vector of advisory guards and a promotion policy. It implements chio_kernel::Guard, so the standard pipeline composes it without a second guard registry, and a promoted signal reaches the caller as an ordinary deny.

pub struct AdvisoryPipeline {
    guards: Vec<Box<dyn AdvisoryGuard>>,
    policy: PromotionPolicy,
    /// Collected signals from the last evaluation (for evidence export).
    signals: std::sync::Mutex<Vec<AdvisorySignal>>,
}

impl Guard for AdvisoryPipeline {
    fn name(&self) -> &str {
        "advisory-pipeline"
    }

    fn evaluate(&self, ctx: &GuardContext) -> Result<GuardDecision, KernelError> {
        let mut collected = Vec::new();
        let mut should_deny = false;

        for guard in &self.guards {
            let signals = guard.evaluate(ctx)?;
            for mut signal in signals {
                if self.policy.should_promote(&signal) {
                    signal.promoted = true;
                    should_deny = true;
                }
                collected.push(signal);
            }
        }

        let evidence = collected.iter().map(signal_evidence).collect();

        // Store collected signals for evidence export.
        let mut stored = self
            .signals
            .lock()
            .map_err(|_| KernelError::Internal("advisory pipeline lock poisoned".to_string()))?;
        *stored = collected;

        if should_deny {
            Ok(GuardDecision::deny(evidence))
        } else {
            Ok(GuardDecision::allow_with_evidence(evidence))
        }
    }

    fn revalidate_before_dispatch(&self, _ctx: &GuardContext) -> Result<(), KernelError> {
        // Advisory evaluation reads mutable session state and records evidence.
        // Preserve the admission verdict and evidence instead of evaluating the
        // pipeline a second time at dispatch.
        Ok(())
    }
}

revalidate_before_dispatch keeps the admission verdict and evidence instead of evaluating the pipeline a second time at dispatch, because advisory evaluation reads mutable session state. The diagnostic accessors read the most recent evaluation:

• last_signals() returns every collected AdvisorySignal from the most recent evaluation.
• last_outputs() wraps the same signals as GuardOutput::Advisory for unified export beside deterministic verdicts.

GuardOutput

pub enum GuardOutput {
    /// A deterministic verdict (allow or deny).
    Deterministic {
        guard_name: String,
        verdict: bool,
        details: Option<String>,
    },
    /// A non-blocking advisory signal.
    Advisory(AdvisorySignal),
}

The enum serializes with #[serde(tag = "type", rename_all = "snake_case")], so an advisory signal carries "type": "advisory" beside its own fields.

Performance

Each advisory guard runs once per call. Both journal-backed guards take a snapshot that clones the retained tool sequence and tool-count map, so snapshot cost grows with that retained state. The pipeline locks once per call to swap the last-signal cache, and readers of last_signals() and last_outputs() contend for that lock. Promotion scans the configured rules per signal; size the rule list and the retained journal for the deployment's evaluation budget.

Custom advisory guards

The built-in advisory guards read local state. A custom advisory implementation is trusted host code and can introduce I/O. The async adapter implementation in chio-guards::external supports external content-safety or threat-intelligence checks with explicit failure and circuit settings; account for provider deadlines and network access when you choose that path.