The Guard Trait

pub trait Guard: Send + Sync {
    /// Human-readable guard name (e.g. "forbidden-path").
    fn name(&self) -> &str;

    /// Evaluate the guard against a tool-call context.
    ///
    /// Returns `Ok(GuardDecision)` - a verdict plus any evidence the guard
    /// recorded - or `Err(KernelError)` to signal an internal guard failure
    /// (which the kernel treats as a fail-closed deny).
    fn evaluate(&self, ctx: &GuardContext<'_>) -> Result<GuardDecision, KernelError>;
}

pub struct GuardDecision {
    pub verdict: Verdict,
    pub evidence: Vec<GuardEvidence>,
}

impl GuardDecision {
    pub fn allow() -> Self {
        Self { verdict: Verdict::Allow, evidence: Vec::new() }
    }
    pub fn allow_with_evidence(evidence: Vec<GuardEvidence>) -> Self {
        Self { verdict: Verdict::Allow, evidence }
    }
    pub fn deny(evidence: Vec<GuardEvidence>) -> Self {
        Self { verdict: Verdict::Deny, evidence }
    }
    pub fn pending_approval(evidence: Vec<GuardEvidence>) -> Self {
        Self { verdict: Verdict::PendingApproval, evidence }
    }
}

pub struct GuardContext<'a> {
    /// The tool call request being evaluated.
    pub request: &'a ToolCallRequest,
    /// The verified capability scope.
    pub scope: &'a ChioScope,
    /// The agent making the request.
    pub agent_id: &'a AgentId,
    /// The target server.
    pub server_id: &'a ServerId,
    /// Session-scoped enforceable filesystem roots, when the request is being
    /// evaluated through the supported session-backed runtime path.
    pub session_filesystem_roots: Option<&'a [String]>,
    /// Index of the matched grant in the capability's scope, populated by
    /// check_and_increment_budget before guards run.
    pub matched_grant_index: Option<usize>,
}

pub trait Guard: Send + Sync {
    fn name(&self) -> &str;

    /// Returns `Ok(Verdict::Allow)` to pass, `Ok(Verdict::Deny)` to block,
    /// or `Err(KernelCoreError)` - treated as a fail-closed deny.
    fn evaluate(&self, ctx: &GuardContext<'_>) -> Result<Verdict, KernelCoreError>;
}

pub struct GuardContext<'a> {
    pub request: &'a PortableToolCallRequest,
    pub scope: &'a ChioScope,
    pub agent_id: &'a str,
    pub server_id: &'a str,
    pub session_filesystem_roots: Option<&'a [String]>,
    pub matched_grant_index: Option<usize>,
}

#[derive(Debug, Clone)]
pub struct PortableToolCallRequest {
    /// Unique request identifier.
    pub request_id: String,
    /// The tool to invoke.
    pub tool_name: String,
    /// The server hosting the tool.
    pub server_id: String,
    /// The calling agent's identifier (hex-encoded public key).
    pub agent_id: String,
    /// Tool arguments as canonical JSON.
    pub arguments: serde_json::Value,
}

/// Three-valued outcome of a kernel evaluation step.
///
/// The kernel core never emits `PendingApproval` itself; the full
/// `chio-kernel` orchestration shell wraps the core verdict with the
/// human-in-the-loop approval path where needed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Verdict {
    /// The action is allowed.
    Allow,
    /// The action is denied.
    Deny,
    /// The action is suspended pending a human decision. Only produced by
    /// the full `chio-kernel` shell, never by `chio-kernel-core` directly.
    PendingApproval,
}

/// Verdict of a guard or capability evaluation.
///
/// Phase 3.4 introduced the `PendingApproval` variant. The variant is a
/// marker: the payload (`ApprovalRequest`) is returned separately via
/// `crate::approval::HitlVerdict` so existing call sites that pattern-
/// match on `Verdict` and rely on its `Copy` semantics keep compiling
/// without change.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Verdict {
    /// The action is allowed.
    Allow,
    /// The action is denied.
    Deny,
    /// The action is suspended pending a human decision. Look up the
    /// associated `ApprovalRequest` via the HITL API.
    PendingApproval,
}

pub enum ToolAction {
    FileAccess(String),
    FileWrite(String, Vec<u8>),
    NetworkEgress(String, u16),
    ShellCommand(String),
    McpTool(String, Value),
    Patch(String, String),
    CodeExecution { language: String, code: String },
    BrowserAction { verb: String, target: Option<String> },
    DatabaseQuery { database: String, query: String },
    ExternalApiCall { service: String, endpoint: String },
    MemoryWrite { store: String, key: String },
    MemoryRead { store: String, key: Option<String> },
    Unknown,
}

pub struct GuardEvidence {
    /// Name of the guard.
    pub guard_name: String,
    /// Whether the guard passed (true) or denied (false).
    pub verdict: bool,
    /// Optional details about the guard's decision.
    pub details: Option<String>,
}

use std::collections::HashSet;

use chio_kernel::{Guard, GuardContext, GuardDecision, KernelError};

pub struct DenyByName {
    denied: HashSet<String>,
}

impl DenyByName {
    pub fn new(denied: impl IntoIterator<Item = String>) -> Self {
        Self { denied: denied.into_iter().collect() }
    }
}

impl Guard for DenyByName {
    fn name(&self) -> &str {
        "deny-by-name"
    }

    fn evaluate(&self, ctx: &GuardContext) -> Result<GuardDecision, KernelError> {
        if self.denied.contains(&ctx.request.tool_name) {
            Ok(GuardDecision::deny(vec![]))
        } else {
            Ok(GuardDecision::allow())
        }
    }
}