lean_ctx/core/

roles.rs

//! Role-based access control for agent governance.
//!
//! Roles define what tools an agent can use, its shell policy, and I/O boundaries.
//! Resolution order: Env (`LEAN_CTX_ROLE`) -> Project `.lean-ctx/roles/` -> Global `~/.lean-ctx/roles/` -> Built-in.

use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet};
use std::env;
use std::path::{Path, PathBuf};
use std::sync::OnceLock;

static ACTIVE_ROLE_NAME: OnceLock<std::sync::Mutex<String>> = OnceLock::new();

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Role {
    #[serde(default)]
    pub role: RoleMeta,
    #[serde(default)]
    pub tools: ToolPolicy,
    #[serde(default)]
    pub io: IoPolicy,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoleMeta {
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub inherits: Option<String>,
    #[serde(default)]
    pub description: String,
    #[serde(default = "default_shell_policy")]
    pub shell_policy: String,
}

impl Default for RoleMeta {
    fn default() -> Self {
        Self {
            name: String::new(),
            inherits: None,
            description: String::new(),
            shell_policy: default_shell_policy(),
        }
    }
}

fn default_shell_policy() -> String {
    "track".to_string()
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ToolPolicy {
    #[serde(default)]
    pub allowed: Vec<String>,
    #[serde(default)]
    pub denied: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IoPolicy {
    /// Boundary enforcement mode for sensitive I/O (warn|enforce).
    #[serde(default = "default_boundary_mode")]
    pub boundary_mode: String,
    /// Allow search to ignore .gitignore and scan everything.
    #[serde(default)]
    pub allow_ignore_gitignore: bool,
    /// Allow reading/indexing secret-like paths (e.g. .env, *.pem).
    #[serde(default)]
    pub allow_secret_paths: bool,
    /// Enable output redaction for tool outputs (admin can disable; non-admin always on).
    #[serde(default = "default_redact_outputs")]
    pub redact_outputs: bool,
    /// Allow cross-project knowledge search (default: false for non-admin roles).
    #[serde(default)]
    pub allow_cross_project_search: bool,
}

fn default_boundary_mode() -> String {
    "enforce".to_string()
}

fn default_redact_outputs() -> bool {
    true
}

impl Default for IoPolicy {
    fn default() -> Self {
        Self {
            boundary_mode: default_boundary_mode(),
            allow_ignore_gitignore: false,
            allow_secret_paths: false,
            redact_outputs: default_redact_outputs(),
            allow_cross_project_search: false,
        }
    }
}

impl IoPolicy {
    fn is_default(&self) -> bool {
        self.boundary_mode == default_boundary_mode()
            && !self.allow_ignore_gitignore
            && !self.allow_secret_paths
            && self.redact_outputs == default_redact_outputs()
    }
}

impl Role {
    pub fn is_tool_allowed(&self, tool_name: &str) -> bool {
        if !self.tools.denied.is_empty()
            && self.tools.denied.iter().any(|d| d == tool_name || d == "*")
        {
            return false;
        }
        if self.tools.allowed.is_empty() || self.tools.allowed.iter().any(|a| a == "*") {
            return true;
        }
        self.tools.allowed.iter().any(|a| a == tool_name)
    }

    pub fn is_shell_allowed(&self) -> bool {
        self.role.shell_policy != "deny"
    }

    pub fn allowed_tools_set(&self) -> HashSet<String> {
        if self.tools.allowed.is_empty() || self.tools.allowed.iter().any(|a| a == "*") {
            return HashSet::new(); // empty = all allowed
        }
        self.tools.allowed.iter().cloned().collect()
    }
}

// ── Built-in roles ──────────────────────────────────────────────

fn builtin_coder() -> Role {
    Role {
        role: RoleMeta {
            name: "coder".into(),
            description: "Full access for code implementation".into(),
            shell_policy: "track".into(),
            inherits: None,
        },
        tools: ToolPolicy {
            allowed: vec!["*".into()],
            denied: vec![],
        },
        io: IoPolicy::default(),
    }
}

/// A role used when an inherited source view has closed or lost its authority.
/// Returning a denying role prevents stale worker state from falling through
/// to a more permissive process-wide active role.
pub(crate) fn closed_source_view_role() -> Role {
    Role {
        role: RoleMeta {
            name: "closed-source-view".into(),
            inherits: None,
            description: "closed source policy view".into(),
            shell_policy: "deny".into(),
        },
        tools: ToolPolicy {
            allowed: Vec::new(),
            denied: vec!["*".into()],
        },
        io: IoPolicy::default(),
    }
}

fn builtin_reviewer() -> Role {
    Role {
        role: RoleMeta {
            name: "reviewer".into(),
            description: "Read-only access for code review".into(),
            shell_policy: "track".into(),
            inherits: None,
        },
        tools: ToolPolicy {
            allowed: vec![
                "ctx_read".into(),
                "ctx_search".into(),
                "ctx_tree".into(),
                "ctx_graph".into(),
                "ctx_diff".into(),
                "ctx_expand".into(),
                "ctx_deps".into(),
                "ctx_session".into(),
                "ctx_knowledge".into(),
                "ctx_preload".into(),
                "ctx_metrics".into(),
                "ctx_cost".into(),
                "ctx_gain".into(),
            ],
            denied: vec!["ctx_edit".into(), "ctx_shell".into(), "ctx_execute".into()],
        },
        io: IoPolicy {
            boundary_mode: "enforce".into(),
            ..Default::default()
        },
    }
}

fn builtin_debugger() -> Role {
    Role {
        role: RoleMeta {
            name: "debugger".into(),
            description: "Debug-focused with shell access".into(),
            shell_policy: "track".into(),
            inherits: None,
        },
        tools: ToolPolicy {
            allowed: vec!["*".into()],
            denied: vec![],
        },
        io: IoPolicy::default(),
    }
}

fn builtin_ops() -> Role {
    Role {
        role: RoleMeta {
            name: "ops".into(),
            description: "Infrastructure and CI/CD operations".into(),
            shell_policy: "compress".into(),
            inherits: None,
        },
        tools: ToolPolicy {
            allowed: vec![
                "ctx_read".into(),
                "ctx_shell".into(),
                "ctx_search".into(),
                "ctx_tree".into(),
                "ctx_session".into(),
                "ctx_knowledge".into(),
                "ctx_metrics".into(),
                "ctx_cost".into(),
            ],
            denied: vec!["ctx_edit".into()],
        },
        io: IoPolicy::default(),
    }
}

fn builtin_admin() -> Role {
    Role {
        role: RoleMeta {
            name: "admin".into(),
            description: "Unrestricted access, all tools and unlimited budgets".into(),
            shell_policy: "track".into(),
            inherits: None,
        },
        tools: ToolPolicy {
            allowed: vec!["*".into()],
            denied: vec![],
        },
        io: IoPolicy {
            boundary_mode: "enforce".into(),
            allow_ignore_gitignore: true,
            allow_secret_paths: true,
            redact_outputs: true,
            allow_cross_project_search: true,
        },
    }
}

fn builtin_roles() -> HashMap<String, Role> {
    let mut m = HashMap::new();
    m.insert("coder".into(), builtin_coder());
    m.insert("reviewer".into(), builtin_reviewer());
    m.insert("debugger".into(), builtin_debugger());
    m.insert("ops".into(), builtin_ops());
    m.insert("admin".into(), builtin_admin());
    m
}

// ── Disk loading ────────────────────────────────────────────────

fn roles_dir_global() -> Option<PathBuf> {
    crate::core::data_dir::lean_ctx_data_dir()
        .ok()
        .map(|d| d.join("roles"))
}

fn roles_dir_project() -> Option<PathBuf> {
    match crate::core::policy::runtime::REQUEST_PROJECT.try_with(|slot| slot.borrow().clone()) {
        Ok(Some(project_root)) => {
            let candidate = project_root.join(".lean-ctx").join("roles");
            candidate.is_dir().then_some(candidate)
        }
        // An explicit unbound scope must not fall back to the process CWD.
        Ok(None) => None,
        Err(_) => roles_dir_project_from(None),
    }
}

fn roles_dir_project_from(project_root: Option<&str>) -> Option<PathBuf> {
    if let Some(root) = project_root {
        let candidate = PathBuf::from(root).join(".lean-ctx").join("roles");
        if candidate.is_dir() {
            return Some(candidate);
        }
    }
    let mut dir = std::env::current_dir().ok()?;
    loop {
        let candidate = dir.join(".lean-ctx").join("roles");
        if candidate.is_dir() {
            return Some(candidate);
        }
        if !dir.pop() {
            break;
        }
    }
    None
}

fn try_load_toml(path: &Path) -> Option<Role> {
    let content = std::fs::read_to_string(path).ok()?;
    toml::from_str(&content).ok()
}

fn load_role_from_disk(name: &str) -> Option<Role> {
    if !is_valid_role_name(name) {
        tracing::warn!(
            "[SECURITY] Invalid role name rejected (path-traversal/special chars): {name}"
        );
        return None;
    }

    let filename = format!("{name}.toml");
    if let Some(dir) = roles_dir_project() {
        let path = dir.join(&filename);
        if path.exists() {
            if RESERVED_ROLE_NAMES
                .iter()
                .any(|r| r.eq_ignore_ascii_case(name))
            {
                tracing::warn!(
                    "[SECURITY] Project-level shadowing of reserved role '{name}' ignored. \
                     Use global ~/.lean-ctx/roles/ to customize built-in roles."
                );
            } else if let Some(mut r) = try_load_toml(&path) {
                r.role.name = name.to_string();
                return Some(r);
            }
        }
    }
    if let Some(dir) = roles_dir_global() {
        let path = dir.join(&filename);
        if let Some(mut r) = try_load_toml(&path) {
            r.role.name = name.to_string();
            return Some(r);
        }
    }
    None
}

fn merge_roles(parent: &Role, child: &Role) -> Role {
    Role {
        role: RoleMeta {
            name: child.role.name.clone(),
            inherits: child.role.inherits.clone(),
            description: if child.role.description.is_empty() {
                parent.role.description.clone()
            } else {
                child.role.description.clone()
            },
            shell_policy: if child.role.shell_policy == default_shell_policy()
                && parent.role.shell_policy != default_shell_policy()
            {
                parent.role.shell_policy.clone()
            } else {
                child.role.shell_policy.clone()
            },
        },
        tools: if child.tools.allowed.is_empty() && child.tools.denied.is_empty() {
            parent.tools.clone()
        } else {
            child.tools.clone()
        },
        io: if child.io.is_default() && !parent.io.is_default() {
            parent.io.clone()
        } else {
            child.io.clone()
        },
    }
}

fn load_role_recursive(name: &str, visited: &mut HashSet<String>) -> Option<Role> {
    if !visited.insert(name.to_string()) {
        tracing::warn!("[SECURITY] Circular role inheritance detected at '{name}'");
        return None;
    }
    let role = load_role_from_disk(name).or_else(|| builtin_roles().remove(name))?;
    if let Some(parent_name) = &role.role.inherits {
        if is_privileged_role(parent_name) && roles_dir_project().is_some() {
            let is_from_project =
                roles_dir_project().is_some_and(|d| d.join(format!("{name}.toml")).exists());
            if is_from_project {
                tracing::warn!(
                    "[SECURITY] Project-level role '{name}' inheriting from privileged \
                     role '{parent_name}' is blocked."
                );
                return None;
            }
        }
        if let Some(parent) = load_role_recursive(parent_name, visited) {
            return Some(merge_roles(&parent, &role));
        }
    }
    Some(role)
}

// ── Public API ──────────────────────────────────────────────────

pub fn load_role(name: &str) -> Option<Role> {
    let mut visited = HashSet::new();
    load_role_recursive(name, &mut visited)
}

pub fn active_role_name() -> String {
    let lock = ACTIVE_ROLE_NAME.get_or_init(|| std::sync::Mutex::new(String::new()));
    let mut guard = lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);

    if guard.is_empty() {
        let from_env = env::var("LEAN_CTX_ROLE")
            .ok()
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty());
        *guard = from_env.unwrap_or_else(|| "coder".to_string());
    }

    guard.clone()
}

pub fn active_role() -> Role {
    if let Some(role) = crate::core::policy::runtime::pinned_role() {
        return role;
    }
    #[cfg(any(test, feature = "test-support"))]
    if let Ok(Some(role)) = TEST_ACTIVE_ROLE.try_with(|slot| slot.borrow().clone()) {
        return role;
    }
    let name = active_role_name();
    load_role(&name).unwrap_or_else(builtin_coder)
}

#[cfg(any(test, feature = "test-support"))]
tokio::task_local! {
    static TEST_ACTIVE_ROLE: std::cell::RefCell<Option<Role>>;
}

#[cfg(any(test, feature = "test-support"))]
pub fn with_test_active_role<T>(role: Role, operation: impl FnOnce() -> T) -> T {
    TEST_ACTIVE_ROLE.sync_scope(std::cell::RefCell::new(Some(role)), operation)
}

#[cfg(test)]
pub(crate) fn set_test_active_role(role: Role) {
    TEST_ACTIVE_ROLE.with(|slot| *slot.borrow_mut() = Some(role));
}

/// Held by every test that changes the process-wide role with
/// [`set_active_role`]: serializes them and restores the previous role on
/// drop, so a switch to `reviewer` or `admin` neither races another such test
/// nor leaks into unrelated tests. Tests that only need a role for their own
/// thread use [`with_test_active_role`] instead.
#[cfg(any(test, feature = "test-support"))]
pub struct GlobalRoleGuard {
    previous: String,
    _lock: std::sync::MutexGuard<'static, ()>,
}

#[cfg(any(test, feature = "test-support"))]
pub fn lock_global_role() -> GlobalRoleGuard {
    static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
    let lock = LOCK
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    GlobalRoleGuard {
        previous: active_role_name(),
        _lock: lock,
    }
}

#[cfg(any(test, feature = "test-support"))]
impl Drop for GlobalRoleGuard {
    fn drop(&mut self) {
        let slot = ACTIVE_ROLE_NAME.get_or_init(|| std::sync::Mutex::new(String::new()));
        slot.lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .clone_from(&self.previous);
    }
}

/// Roles that grant elevated privileges and cannot be activated via MCP tool calls.
/// These roles must be set via env var (`LEAN_CTX_ROLE`) or config file.
const PRIVILEGED_ROLES: &[&str] = &["admin", "ops"];

/// Reserved role names that cannot be shadowed from project-level config.
const RESERVED_ROLE_NAMES: &[&str] = &["coder", "reviewer", "debugger", "ops", "admin"];

/// Returns true if the named role has elevated privileges that require
/// explicit configuration (env/config) rather than runtime activation.
/// Case-insensitive comparison to prevent "Admin" bypass.
pub fn is_privileged_role(name: &str) -> bool {
    let lower = name.to_ascii_lowercase();
    PRIVILEGED_ROLES.iter().any(|p| *p == lower)
}

/// Validate role name: alphanumeric, underscore, hyphen only. No path traversal.
fn is_valid_role_name(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= 64
        && name
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
}

/// Check if a merged role is effectively privileged (wildcard tools + no denials, or secret paths).
fn is_effectively_privileged(role: &Role) -> bool {
    let wildcard_tools =
        role.tools.allowed.iter().any(|a| a == "*") && role.tools.denied.is_empty();
    wildcard_tools || role.io.allow_secret_paths
}

pub fn set_active_role(name: &str) -> Result<Role, String> {
    set_active_role_with_source(name, false)
}

/// Set active role. `from_config` = true allows privileged roles (env/config startup).
pub fn set_active_role_with_source(name: &str, from_config: bool) -> Result<Role, String> {
    if !is_valid_role_name(name) {
        return Err(format!(
            "[SECURITY] Invalid role name '{name}'. Only alphanumeric, underscore, and hyphen allowed."
        ));
    }

    let role = load_role(name).ok_or_else(|| format!("Role '{name}' not found"))?;

    if !from_config && is_privileged_role(name) {
        return Err(format!(
            "[SECURITY] Cannot escalate to privileged role '{name}' at runtime. \
             Set LEAN_CTX_ROLE={name} in your environment or config to use this role."
        ));
    }

    let is_builtin = builtin_roles().contains_key(name);
    if !from_config && !is_builtin && is_effectively_privileged(&role) {
        return Err(format!(
            "[SECURITY] Cannot activate role '{name}' at runtime: it has effectively \
             privileged permissions (wildcard tools or secret path access). \
             Set LEAN_CTX_ROLE={name} in environment or config."
        ));
    }

    let prev = active_role_name();
    let lock = ACTIVE_ROLE_NAME.get_or_init(|| std::sync::Mutex::new("coder".to_string()));
    match lock.lock() {
        Ok(mut g) => *g = name.to_string(),
        Err(poisoned) => *poisoned.into_inner() = name.to_string(),
    }
    if prev != name {
        crate::core::events::emit_role_changed(&prev, name);
    }
    Ok(role)
}

pub fn list_roles() -> Vec<RoleInfo> {
    let active = active_role_name();
    let builtins = builtin_roles();
    let mut seen = HashSet::new();
    let mut result = Vec::new();

    for dir in [roles_dir_project(), roles_dir_global()]
        .into_iter()
        .flatten()
    {
        if let Ok(entries) = std::fs::read_dir(&dir) {
            for entry in entries.flatten() {
                let path = entry.path();
                if path.extension().is_some_and(|e| e == "toml")
                    && let Some(stem) = path.file_stem().and_then(|s| s.to_str())
                    && seen.insert(stem.to_string())
                    && let Some(r) = load_role(stem)
                {
                    result.push(RoleInfo {
                        name: stem.to_string(),
                        source: if dir == roles_dir_project().unwrap_or_default() {
                            RoleSource::Project
                        } else {
                            RoleSource::Global
                        },
                        description: r.role.description.clone(),
                        is_active: stem == active,
                    });
                }
            }
        }
    }

    for (name, r) in &builtins {
        if seen.insert(name.clone()) {
            result.push(RoleInfo {
                name: name.clone(),
                source: RoleSource::BuiltIn,
                description: r.role.description.clone(),
                is_active: name == &active,
            });
        }
    }

    result.sort_by_key(|r| r.name.clone());
    result
}

#[derive(Debug, Clone)]
pub struct RoleInfo {
    pub name: String,
    pub source: RoleSource,
    pub description: String,
    pub is_active: bool,
}

#[derive(Debug, Clone, PartialEq)]
pub enum RoleSource {
    BuiltIn,
    Project,
    Global,
}

impl std::fmt::Display for RoleSource {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::BuiltIn => write!(f, "built-in"),
            Self::Project => write!(f, "project"),
            Self::Global => write!(f, "global"),
        }
    }
}

// ── Tests ───────────────────────────────────────────────────────

#[cfg(test)]
pub mod tests {
    use super::*;

    #[test]
    fn builtin_count() {
        assert_eq!(builtin_roles().len(), 5);
    }

    #[test]
    fn coder_allows_all() {
        let r = builtin_coder();
        assert!(r.is_tool_allowed("ctx_read"));
        assert!(r.is_tool_allowed("ctx_edit"));
        assert!(r.is_tool_allowed("ctx_shell"));
        assert!(r.is_tool_allowed("anything"));
    }

    #[test]
    fn reviewer_denies_edits() {
        let r = builtin_reviewer();
        assert!(r.is_tool_allowed("ctx_read"));
        assert!(!r.is_tool_allowed("ctx_edit"));
        assert!(!r.is_tool_allowed("ctx_shell"));
        assert!(!r.is_tool_allowed("ctx_execute"));
    }

    #[test]
    fn ops_denies_edit() {
        let r = builtin_ops();
        assert!(!r.is_tool_allowed("ctx_edit"));
        assert!(r.is_tool_allowed("ctx_shell"));
        assert!(r.is_shell_allowed());
    }

    #[test]
    fn admin_allows_edit_and_shell() {
        let r = builtin_admin();
        assert!(r.is_tool_allowed("ctx_edit"));
        assert!(r.is_tool_allowed("ctx_shell"));
    }

    #[test]
    fn legacy_limits_section_still_parses() {
        let role: Role = toml::from_str(
            "[role]\nname = \"legacy\"\n\n[limits]\nmax_context_tokens = 1000\nwarn_at_percent = 50\n",
        )
        .expect("retired [limits] section must be ignored");
        assert_eq!(role.role.name, "legacy");
    }

    #[test]
    fn denied_overrides_allowed() {
        let r = Role {
            role: RoleMeta {
                name: "test".into(),
                ..Default::default()
            },
            tools: ToolPolicy {
                allowed: vec!["*".into()],
                denied: vec!["ctx_edit".into()],
            },
            io: IoPolicy::default(),
        };
        assert!(r.is_tool_allowed("ctx_read"));
        assert!(!r.is_tool_allowed("ctx_edit"));
    }

    #[test]
    fn shell_deny_policy() {
        let r = Role {
            role: RoleMeta {
                name: "noshell".into(),
                shell_policy: "deny".into(),
                ..Default::default()
            },
            tools: ToolPolicy::default(),
            io: IoPolicy::default(),
        };
        assert!(!r.is_shell_allowed());
    }

    #[test]
    fn load_builtin_by_name() {
        assert!(load_role("coder").is_some());
        assert!(load_role("reviewer").is_some());
        assert!(load_role("debugger").is_some());
        assert!(load_role("ops").is_some());
        assert!(load_role("admin").is_some());
        assert!(load_role("nonexistent").is_none());
    }

    #[test]
    fn merge_inherits_parent_tools() {
        let parent = builtin_reviewer();
        let child = Role {
            role: RoleMeta {
                name: "custom".into(),
                inherits: Some("reviewer".into()),
                description: "Custom reviewer".into(),
                ..Default::default()
            },
            tools: ToolPolicy::default(),
            io: IoPolicy::default(),
        };
        let merged = merge_roles(&parent, &child);
        assert_eq!(merged.role.name, "custom");
        assert_eq!(merged.role.description, "Custom reviewer");
        assert!(!merged.is_tool_allowed("ctx_edit"));
    }

    #[test]
    fn default_role_is_coder() {
        let name = active_role_name();
        assert!(!name.is_empty(), "`name` is empty");
    }

    #[test]
    fn list_roles_includes_builtins() {
        let roles = list_roles();
        let names: Vec<_> = roles.iter().map(|r| r.name.as_str()).collect();
        assert!(names.contains(&"coder"));
        assert!(names.contains(&"reviewer"));
        assert!(names.contains(&"admin"));
    }

    #[test]
    fn runtime_escalation_to_admin_blocked() {
        let _role = lock_global_role();
        let result = set_active_role("admin");
        assert!(
            result.is_err(),
            "runtime escalation to admin must be blocked"
        );
        let err = result.unwrap_err();
        assert!(
            err.contains("SECURITY"),
            "error must indicate security: {err}"
        );
    }

    #[test]
    fn runtime_escalation_to_ops_blocked() {
        let _role = lock_global_role();
        let result = set_active_role("ops");
        assert!(result.is_err(), "runtime escalation to ops must be blocked");
    }

    #[test]
    fn config_escalation_to_admin_allowed() {
        let _role = lock_global_role();
        let result = set_active_role_with_source("admin", true);
        assert!(
            result.is_ok(),
            "config-source escalation to admin must work"
        );
    }

    #[test]
    fn runtime_switch_to_coder_allowed() {
        let _role = lock_global_role();
        let result = set_active_role("coder");
        assert!(result.is_ok(), "switching to coder must always work");
    }

    #[test]
    fn runtime_switch_to_reviewer_allowed() {
        let _role = lock_global_role();
        let result = set_active_role("reviewer");
        assert!(result.is_ok(), "switching to reviewer must always work");
    }

    #[test]
    fn privileged_roles_detected() {
        assert!(is_privileged_role("admin"));
        assert!(is_privileged_role("ops"));
        assert!(!is_privileged_role("coder"));
        assert!(!is_privileged_role("reviewer"));
        assert!(!is_privileged_role("debugger"));
    }

    // --- Phase 2 V2: Role name validation ---

    #[test]
    fn valid_role_names() {
        assert!(is_valid_role_name("coder"));
        assert!(is_valid_role_name("my-custom-role"));
        assert!(is_valid_role_name("Role_123"));
        assert!(is_valid_role_name("ADMIN"));
    }

    #[test]
    fn invalid_role_names() {
        assert!(!is_valid_role_name(""));
        assert!(!is_valid_role_name("../../evil"));
        assert!(!is_valid_role_name("role with spaces"));
        assert!(!is_valid_role_name("role;drop"));
        assert!(!is_valid_role_name("a".repeat(65).as_str()));
    }

    #[test]
    fn case_insensitive_privileged_check() {
        assert!(is_privileged_role("Admin"));
        assert!(is_privileged_role("ADMIN"));
        assert!(is_privileged_role("Ops"));
        assert!(is_privileged_role("OPS"));
    }

    #[test]
    fn invalid_role_name_rejected_at_set() {
        let _role = lock_global_role();
        let result = set_active_role("../../evil");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Invalid role name"));
    }

    #[test]
    fn effectively_privileged_role_blocked_at_runtime() {
        let role = Role {
            role: RoleMeta {
                name: "sneaky".into(),
                ..Default::default()
            },
            tools: ToolPolicy {
                allowed: vec!["*".into()],
                denied: vec![],
            },
            io: IoPolicy::default(),
        };
        assert!(
            is_effectively_privileged(&role),
            "wildcard + no denials = effectively privileged"
        );
    }

    #[test]
    fn debugger_runtime_switch_allowed() {
        let _role = lock_global_role();
        let result = set_active_role("debugger");
        assert!(
            result.is_ok(),
            "built-in debugger must be activatable at runtime"
        );
    }
}