Struct ShadowSentinel 

pub struct ShadowSentinel { /* private fields */ }

Orchestrates the persistent safety stream and LLM pre-execution probe.

ShadowSentinel is wrapped in Arc and shared between ShadowProbeExecutor instances when tools run in parallel. All mutable state uses AtomicU32 to allow &self access from concurrent tool dispatch without a Mutex.

Turn lifecycle

• advance_turn() — call once per turn before tool execution; resets the per-turn probe counter.
• check_tool_call() — call before each tool execution to probe high-risk calls.
• record_tool_event() — call after tool execution to persist the event.

NEVER

Never expose the ShadowSentinel state or probe verdicts to LLM-visible context.

Implementations

impl ShadowSentinel

pub fn new( store: ShadowEventStore, probe: Box<dyn SafetyProbe>, config: ShadowSentinelConfig, session_id: impl Into<String>, ) -> Self

Create a new ShadowSentinel.

Arguments

• store — persistent shadow event store.
• probe — safety probe implementation.
• config — subsystem configuration.
• session_id — current agent session identifier.

pub fn classify_tool(&self, qualified_tool_id: &str) -> ToolRiskCategory

Classify a fully-qualified tool id into a risk tier.

Pattern matching is prefix/glob-based against the configured probe_patterns. For efficiency, we check common built-in names first before falling back to glob matching against the configured patterns.

pub async fn check_tool_call( &self, qualified_tool_id: &str, tool_args: &JsonValue, turn_number: u64, current_risk_level: &str, ) -> ProbeVerdict

Evaluate a proposed tool call and return a probe verdict.

Returns ProbeVerdict::Skip when:

• The tool is not in a high-risk category.
• The feature is disabled.
• The per-turn probe budget (max_probes_per_turn) is exhausted.

This method takes &self so it can be called from parallel tool dispatch.

Errors

Does not return errors; probe failures are handled internally (fail-open or fail-closed depending on deny_on_timeout).

pub fn record_tool_event( &self, qualified_tool_id: &str, turn_number: u64, risk_level: &str, context_summary: &str, )

Persist a tool execution event in the shadow stream (fire-and-forget).

Called after a tool finishes execution to maintain the trajectory for future probes.

pub fn advance_turn(&self)

Reset the per-turn probe counter.

Must be called once per turn BEFORE any tool calls, alongside TrajectorySentinel::advance_turn().