agent_sdk/

capabilities.rs

use serde::{Deserialize, Serialize};
use std::sync::OnceLock;

/// Capabilities that control what the agent can do.
///
/// This provides a security model for primitive tools (Read, Write, Grep, Glob, Bash).
/// Paths are matched using glob patterns, commands using regex patterns.
///
/// By default, everything is allowed — the SDK is unopinionated and leaves
/// security policy to the client. Use the builder methods to configure restrictions.
///
/// # Path matching
///
/// Primitive tools resolve the model-supplied path to an **absolute** path
/// (against the environment root) *before* consulting these rules, so path
/// patterns are matched against that resolved absolute path — not the raw
/// relative input. Prefer `**/`-prefixed patterns (e.g. `**/src/**`) or
/// absolute patterns over bare relative ones like `src/**`, which never match
/// the absolute paths the tools produce.
///
/// # Example
///
/// ```rust
/// use agent_sdk::AgentCapabilities;
///
/// // Read-only agent restricted to the `src/` tree. Because tools check the
/// // resolved absolute path, use a `**/`-prefixed pattern rather than `src/**`.
/// let caps = AgentCapabilities::read_only()
///     .with_allowed_paths(vec!["**/src/**".into()]);
/// assert!(caps.can_read("/workspace/src/main.rs"));
///
/// // Full access agent with some restrictions
/// let caps = AgentCapabilities::full_access()
///     .with_denied_paths(vec!["**/.env*".into(), "**/secrets/**".into()]);
/// ```
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct AgentCapabilities {
    /// Can read files
    pub read: bool,
    /// Can write/edit files
    pub write: bool,
    /// Can execute shell commands
    pub exec: bool,
    /// Allowed path patterns (glob). Empty means all paths allowed.
    ///
    /// Matched against the resolved **absolute** path produced by primitive
    /// tools — see the type-level "Path matching" note.
    pub allowed_paths: Vec<String>,
    /// Denied path patterns (glob). Takes precedence over `allowed_paths`.
    ///
    /// Matched against the resolved **absolute** path produced by primitive
    /// tools — see the type-level "Path matching" note.
    pub denied_paths: Vec<String>,
    /// Allowed commands (regex patterns). Empty means all commands allowed when `exec=true`.
    pub allowed_commands: Vec<String>,
    /// Denied commands (regex patterns). Takes precedence over `allowed_commands`.
    pub denied_commands: Vec<String>,
    /// Lazily-compiled patterns, cached so per-result hot paths (grep/glob call
    /// `check_read` once per match) do not recompile regexes on every check.
    ///
    /// Populated on first use from the pattern lists above and reset by the
    /// `with_*` builder methods. Mutating the public pattern `Vec`s directly
    /// (instead of via the builders) will not refresh this cache.
    #[serde(skip)]
    compiled: OnceLock<CompiledPatterns>,
}

/// Pre-compiled forms of the pattern lists, built once per configuration.
///
/// Each entry is `None` when its source pattern failed to compile; matching
/// then falls back to the pattern list's documented fail-open (allow) or
/// fail-closed (deny) behaviour.
#[derive(Clone, Debug, Default)]
struct CompiledPatterns {
    allowed_paths: Vec<Option<regex::Regex>>,
    denied_paths: Vec<Option<regex::Regex>>,
    allowed_commands: Vec<Option<regex::Regex>>,
    denied_commands: Vec<Option<regex::Regex>>,
}

impl Default for AgentCapabilities {
    fn default() -> Self {
        Self::full_access()
    }
}

impl AgentCapabilities {
    /// Create capabilities with no access (must explicitly enable)
    #[must_use]
    pub const fn none() -> Self {
        Self {
            read: false,
            write: false,
            exec: false,
            allowed_paths: vec![],
            denied_paths: vec![],
            allowed_commands: vec![],
            denied_commands: vec![],
            compiled: OnceLock::new(),
        }
    }

    /// Create read-only capabilities
    #[must_use]
    pub const fn read_only() -> Self {
        Self {
            read: true,
            write: false,
            exec: false,
            allowed_paths: vec![],
            denied_paths: vec![],
            allowed_commands: vec![],
            denied_commands: vec![],
            compiled: OnceLock::new(),
        }
    }

    /// Create full access capabilities
    #[must_use]
    pub const fn full_access() -> Self {
        Self {
            read: true,
            write: true,
            exec: true,
            allowed_paths: vec![],
            denied_paths: vec![],
            allowed_commands: vec![],
            denied_commands: vec![],
            compiled: OnceLock::new(),
        }
    }

    /// Builder: enable read access
    #[must_use]
    pub const fn with_read(mut self, enabled: bool) -> Self {
        self.read = enabled;
        self
    }

    /// Builder: enable write access
    #[must_use]
    pub const fn with_write(mut self, enabled: bool) -> Self {
        self.write = enabled;
        self
    }

    /// Builder: enable exec access
    #[must_use]
    pub const fn with_exec(mut self, enabled: bool) -> Self {
        self.exec = enabled;
        self
    }

    /// Builder: set allowed paths
    #[must_use]
    pub fn with_allowed_paths(mut self, paths: Vec<String>) -> Self {
        self.allowed_paths = paths;
        self.compiled = OnceLock::new();
        self
    }

    /// Builder: set denied paths
    #[must_use]
    pub fn with_denied_paths(mut self, paths: Vec<String>) -> Self {
        self.denied_paths = paths;
        self.compiled = OnceLock::new();
        self
    }

    /// Builder: set allowed commands
    #[must_use]
    pub fn with_allowed_commands(mut self, commands: Vec<String>) -> Self {
        self.allowed_commands = commands;
        self.compiled = OnceLock::new();
        self
    }

    /// Builder: set denied commands
    #[must_use]
    pub fn with_denied_commands(mut self, commands: Vec<String>) -> Self {
        self.denied_commands = commands;
        self.compiled = OnceLock::new();
        self
    }

    /// Check read permission, returning the denial reason on failure.
    ///
    /// # Errors
    ///
    /// Returns the denial reason when read is disabled, the path matches a
    /// denied pattern, or the path is not in the allowed list.
    pub fn check_read(&self, path: &str) -> Result<(), String> {
        if !self.read {
            return Err("read access is disabled".into());
        }
        self.check_path(path)
    }

    /// Check write permission, returning the denial reason on failure.
    ///
    /// # Errors
    ///
    /// Returns the denial reason when write is disabled, the path matches a
    /// denied pattern, or the path is not in the allowed list.
    pub fn check_write(&self, path: &str) -> Result<(), String> {
        if !self.write {
            return Err("write access is disabled".into());
        }
        self.check_path(path)
    }

    /// Check exec permission, returning the denial reason on failure.
    ///
    /// # Errors
    ///
    /// Returns the denial reason when exec is disabled, the command matches a
    /// denied pattern, or the command is not in the allowed list.
    pub fn check_exec(&self, command: &str) -> Result<(), String> {
        if !self.exec {
            return Err("command execution is disabled".into());
        }
        self.check_command(command)
    }

    /// Returns `true` if reading `path` is allowed.
    #[must_use]
    pub fn can_read(&self, path: &str) -> bool {
        self.check_read(path).is_ok()
    }

    /// Returns `true` if writing `path` is allowed.
    #[must_use]
    pub fn can_write(&self, path: &str) -> bool {
        self.check_write(path).is_ok()
    }

    /// Returns `true` if executing `command` is allowed.
    #[must_use]
    pub fn can_exec(&self, command: &str) -> bool {
        self.check_exec(command).is_ok()
    }

    /// Check whether a path passes the allow/deny rules, returning
    /// the specific denial reason on failure.
    ///
    /// # Errors
    ///
    /// Returns the denial reason when the path matches a denied pattern
    /// or is not in the allowed list.
    pub fn check_path(&self, path: &str) -> Result<(), String> {
        let compiled = self.compiled();

        // Denied patterns take precedence. Glob denies fail OPEN: a pattern
        // that did not compile (`None`) simply does not match.
        for (pattern, regex) in self.denied_paths.iter().zip(&compiled.denied_paths) {
            if regex.as_ref().is_some_and(|re| re.is_match(path)) {
                return Err(format!("path matches denied pattern '{pattern}'"));
            }
        }

        // If allowed_paths is empty, all non-denied paths are allowed
        if self.allowed_paths.is_empty() {
            return Ok(());
        }

        // Check if path matches any allowed pattern
        for regex in &compiled.allowed_paths {
            if regex.as_ref().is_some_and(|re| re.is_match(path)) {
                return Ok(());
            }
        }

        Err(format!(
            "path not in allowed list (allowed: [{}])",
            self.allowed_paths.join(", ")
        ))
    }

    /// Check whether a command passes the allow/deny rules, returning
    /// the specific denial reason on failure.
    ///
    /// # Security Note
    ///
    /// Regex-based command filtering is a heuristic, not a security boundary.
    /// Shell metacharacters (`;`, `&&`, `|`, backticks, `$()`) allow chaining
    /// arbitrary commands. For example, `denied_commands: ["^sudo"]` does NOT
    /// block `bash -c "sudo rm -rf /"`. The `pre_tool_use` hook is the
    /// authoritative gate for command approval.
    ///
    /// Invalid deny patterns fail closed (block everything) to prevent
    /// misconfigured deny rules from silently allowing dangerous commands.
    ///
    /// # Errors
    ///
    /// Returns the denial reason when the command matches a denied pattern
    /// or is not in the allowed list.
    pub fn check_command(&self, command: &str) -> Result<(), String> {
        let compiled = self.compiled();

        // Denied patterns take precedence. Deny rules fail CLOSED: a pattern
        // that did not compile (`None`) blocks everything to prevent a
        // misconfigured deny rule from silently allowing dangerous commands.
        for (pattern, regex) in self.denied_commands.iter().zip(&compiled.denied_commands) {
            if regex.as_ref().is_none_or(|re| re.is_match(command)) {
                return Err(format!("command matches denied pattern '{pattern}'"));
            }
        }

        // If allowed_commands is empty, all non-denied commands are allowed
        if self.allowed_commands.is_empty() {
            return Ok(());
        }

        // Check if command matches any allowed pattern. Allow rules fail OPEN:
        // an invalid pattern (`None`) does not grant access.
        for regex in &compiled.allowed_commands {
            if regex.as_ref().is_some_and(|re| re.is_match(command)) {
                return Ok(());
            }
        }

        Err(format!(
            "command not in allowed list (allowed: [{}])",
            self.allowed_commands.join(", ")
        ))
    }

    /// Return the lazily-compiled patterns, building them once on first use.
    fn compiled(&self) -> &CompiledPatterns {
        self.compiled.get_or_init(|| CompiledPatterns {
            allowed_paths: self
                .allowed_paths
                .iter()
                .map(|p| compile_glob(p.as_str()))
                .collect(),
            denied_paths: self
                .denied_paths
                .iter()
                .map(|p| compile_glob(p.as_str()))
                .collect(),
            allowed_commands: self
                .allowed_commands
                .iter()
                .map(|p| regex::Regex::new(p.as_str()).ok())
                .collect(),
            denied_commands: self
                .denied_commands
                .iter()
                .map(|p| regex::Regex::new(p.as_str()).ok())
                .collect(),
        })
    }
}

/// Convert a glob pattern (supporting `*` and `**` wildcards) into an anchored
/// regex string.
///
/// - `**/` (prefix/middle): zero or more leading path components.
/// - `/**` (suffix): everything below a directory.
/// - `*`: any run of non-`/` characters.
fn glob_to_regex(pattern: &str) -> String {
    // Special case: a bare `**` matches everything (including across `/`).
    if pattern == "**" {
        return "^.*$".to_string();
    }

    // Escape regex special characters except the glob wildcards `*` and `?`.
    let mut escaped = String::with_capacity(pattern.len());
    for c in pattern.chars() {
        match c {
            '.' | '+' | '^' | '$' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '\\' => {
                escaped.push('\\');
                escaped.push(c);
            }
            _ => escaped.push(c),
        }
    }

    let body = escaped
        .replace("**/", "\x00") // **/ -> placeholder
        .replace("/**", "\x01") // /** -> placeholder
        .replace('*', "[^/]*") // * -> match non-slash characters
        .replace('\x00', "(.*/)?") // **/ as optional prefix (handles absolute paths)
        .replace('\x01', "(/.*)?"); // /** as optional suffix

    format!("^{body}$")
}

/// Compile a glob pattern to a regex, returning `None` if it does not compile.
fn compile_glob(pattern: &str) -> Option<regex::Regex> {
    regex::Regex::new(&glob_to_regex(pattern)).ok()
}

/// Simple glob matching (supports `*` and `**` wildcards).
///
/// Returns `false` on patterns that fail to compile (fail open). Used by the
/// unit tests; production checks go through the cached [`AgentCapabilities`].
#[cfg(test)]
fn glob_match(pattern: &str, path: &str) -> bool {
    compile_glob(pattern).is_some_and(|re| re.is_match(path))
}

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

    #[test]
    fn test_default_has_no_deny_lists() {
        let caps = AgentCapabilities::default();

        // Default is permissive — no paths or commands are denied
        assert!(caps.check_path("src/main.rs").is_ok());
        assert!(caps.check_path(".env").is_ok());
        assert!(caps.check_path("/workspace/secrets/key.txt").is_ok());
        assert!(caps.check_command("any command").is_ok());
    }

    #[test]
    fn test_full_access_allows_everything() {
        let caps = AgentCapabilities::full_access();

        assert!(caps.check_read("/any/path").is_ok());
        assert!(caps.check_write("/any/path").is_ok());
        assert!(caps.check_exec("any command").is_ok());
    }

    #[test]
    fn test_read_only_cannot_write() {
        let caps = AgentCapabilities::read_only();

        assert!(caps.check_read("src/main.rs").is_ok());
        assert!(caps.check_write("src/main.rs").is_err());
        assert!(caps.check_exec("ls").is_err());
    }

    #[test]
    fn test_client_configured_denied_paths() {
        let caps = AgentCapabilities::full_access().with_denied_paths(vec![
            "**/.env".into(),
            "**/.env.*".into(),
            "**/secrets/**".into(),
            "**/*.pem".into(),
        ]);

        // Denied paths (relative)
        assert!(caps.check_path(".env").is_err());
        assert!(caps.check_path("config/.env.local").is_err());
        assert!(caps.check_path("app/secrets/key.txt").is_err());
        assert!(caps.check_path("certs/server.pem").is_err());

        // Denied paths (absolute — after resolve_path)
        assert!(caps.check_path("/workspace/.env").is_err());
        assert!(caps.check_path("/workspace/.env.production").is_err());
        assert!(caps.check_path("/workspace/secrets/key.txt").is_err());
        assert!(caps.check_path("/workspace/certs/server.pem").is_err());

        // Normal files still allowed
        assert!(caps.check_path("src/main.rs").is_ok());
        assert!(caps.check_path("/workspace/src/main.rs").is_ok());
        assert!(caps.check_path("/workspace/README.md").is_ok());
    }

    #[test]
    fn test_allowed_paths_restriction() {
        let caps = AgentCapabilities::read_only()
            .with_allowed_paths(vec!["src/**".into(), "tests/**".into()]);

        assert!(caps.check_path("src/main.rs").is_ok());
        assert!(caps.check_path("src/lib/utils.rs").is_ok());
        assert!(caps.check_path("tests/integration.rs").is_ok());
        assert!(caps.check_path("config/settings.toml").is_err());
        assert!(caps.check_path("README.md").is_err());
    }

    #[test]
    fn allowed_paths_match_resolved_absolute_paths() {
        // Primitive tools resolve inputs to absolute paths before checking, so
        // a `**/`-prefixed pattern must permit the absolute paths they produce.
        let caps = AgentCapabilities::read_only().with_allowed_paths(vec!["**/src/**".into()]);

        assert!(caps.check_read("/workspace/src/main.rs").is_ok());
        assert!(caps.check_read("/workspace/src/lib/mod.rs").is_ok());
        assert!(caps.can_read("/Users/dev/project/src/deep/nested.rs"));

        // Paths outside the allowed tree are still denied.
        assert!(caps.check_read("/workspace/README.md").is_err());
        assert!(caps.check_read("/workspace/tests/it.rs").is_err());
    }

    #[test]
    fn rebuilding_patterns_invalidates_compiled_cache() {
        // First check populates the compiled-pattern cache for the empty list.
        let caps = AgentCapabilities::full_access();
        assert!(caps.check_path("/workspace/.env").is_ok());

        // A capability rebuilt via a `with_*` builder must honor the new deny
        // list — i.e. the builder resets the cached compiled patterns.
        let restricted = caps.with_denied_paths(vec!["**/.env".into()]);
        assert!(restricted.check_path("/workspace/.env").is_err());
        assert!(restricted.check_path("/workspace/src/main.rs").is_ok());
        // Repeated checks (which reuse the cache) stay consistent.
        assert!(restricted.check_path("/workspace/.env").is_err());
    }

    #[test]
    fn test_denied_takes_precedence() {
        let caps = AgentCapabilities::read_only()
            .with_denied_paths(vec!["**/secret/**".into()])
            .with_allowed_paths(vec!["**".into()]);

        assert!(caps.check_path("src/main.rs").is_ok());
        assert!(caps.check_path("src/secret/key.txt").is_err());
    }

    #[test]
    fn test_client_configured_denied_commands() {
        let caps = AgentCapabilities::full_access()
            .with_denied_commands(vec![r"rm\s+-rf\s+/".into(), r"^sudo\s".into()]);

        assert!(caps.check_command("rm -rf /").is_err());
        assert!(caps.check_command("sudo rm file").is_err());

        // Common shell patterns are NOT blocked
        assert!(caps.check_command("ls -la").is_ok());
        assert!(caps.check_command("cargo build").is_ok());
        assert!(caps.check_command("unzip file.zip 2>/dev/null").is_ok());
        assert!(
            caps.check_command("python3 -m markitdown file.pptx")
                .is_ok()
        );
    }

    #[test]
    fn test_allowed_commands_restriction() {
        let caps = AgentCapabilities::full_access()
            .with_allowed_commands(vec![r"^cargo ".into(), r"^git ".into()]);

        assert!(caps.check_command("cargo build").is_ok());
        assert!(caps.check_command("git status").is_ok());
        assert!(caps.check_command("ls -la").is_err());
        assert!(caps.check_command("npm install").is_err());
    }

    #[test]
    fn test_glob_matching() {
        // Simple wildcards
        assert!(glob_match("*.rs", "main.rs"));
        assert!(!glob_match("*.rs", "src/main.rs"));

        // Double star for recursive matching in subdirectories
        assert!(glob_match("**/*.rs", "src/main.rs"));
        assert!(glob_match("**/*.rs", "deep/nested/file.rs"));

        // Directory patterns with /** suffix
        assert!(glob_match("src/**", "src/lib/utils.rs"));
        assert!(glob_match("src/**", "src/main.rs"));

        // Match files in any subdirectory
        assert!(glob_match("**/test*", "src/tests/test_utils.rs"));
        assert!(glob_match("**/test*.rs", "dir/test_main.rs"));

        // Root-level matches need direct pattern
        assert!(glob_match("test*", "test_main.rs"));
        assert!(glob_match("test*.rs", "test_main.rs"));

        // Absolute paths (tools resolve to absolute before checking capabilities)
        assert!(glob_match("**/.env", "/workspace/.env"));
        assert!(glob_match("**/.env.*", "/workspace/.env.local"));
        assert!(glob_match("**/secrets/**", "/workspace/secrets/key.txt"));
        assert!(glob_match("**/*.pem", "/workspace/certs/server.pem"));
        assert!(glob_match("**/*.key", "/workspace/server.key"));
        assert!(glob_match("**/id_rsa", "/home/user/.ssh/id_rsa"));
        assert!(glob_match("**/*.rs", "/Users/dev/project/src/main.rs"));

        // Absolute paths should NOT false-positive
        assert!(!glob_match("**/.env", "/workspace/src/main.rs"));
        assert!(!glob_match("**/*.pem", "/workspace/src/lib.rs"));
    }

    // =============================================
    // Diagnostic reason tests (check_* methods)
    // =============================================

    #[test]
    fn check_read_disabled_explains_reason() {
        let caps = AgentCapabilities::none();
        let err = caps.check_read("src/main.rs").unwrap_err();
        assert!(err.contains("read access is disabled"), "got: {err}");
    }

    #[test]
    fn check_write_disabled_explains_reason() {
        let caps = AgentCapabilities::read_only();
        let err = caps.check_write("src/main.rs").unwrap_err();
        assert!(err.contains("write access is disabled"), "got: {err}");
    }

    #[test]
    fn check_exec_disabled_explains_reason() {
        let caps = AgentCapabilities::read_only();
        let err = caps.check_exec("ls").unwrap_err();
        assert!(err.contains("command execution is disabled"), "got: {err}");
    }

    #[test]
    fn check_read_denied_path_explains_pattern() {
        let caps = AgentCapabilities::full_access().with_denied_paths(vec!["**/.env*".into()]);
        let err = caps.check_read("/workspace/.env.local").unwrap_err();
        assert!(err.contains("denied pattern"), "got: {err}");
        assert!(err.contains("**/.env*"), "got: {err}");
    }

    #[test]
    fn check_read_not_in_allowed_list() {
        let caps = AgentCapabilities::full_access().with_allowed_paths(vec!["src/**".into()]);
        let err = caps.check_read("/workspace/README.md").unwrap_err();
        assert!(err.contains("not in allowed list"), "got: {err}");
        assert!(err.contains("src/**"), "got: {err}");
    }

    #[test]
    fn check_exec_denied_command_explains_pattern() {
        let caps = AgentCapabilities::full_access().with_denied_commands(vec![r"^sudo\s".into()]);
        let err = caps.check_exec("sudo rm -rf /").unwrap_err();
        assert!(err.contains("denied pattern"), "got: {err}");
        assert!(err.contains("^sudo\\s"), "got: {err}");
    }

    #[test]
    fn check_exec_not_in_allowed_list() {
        let caps = AgentCapabilities::full_access()
            .with_allowed_commands(vec![r"^cargo ".into(), r"^git ".into()]);
        let err = caps.check_exec("npm install").unwrap_err();
        assert!(err.contains("not in allowed list"), "got: {err}");
        assert!(err.contains("^cargo "), "got: {err}");
    }

    #[test]
    fn check_allowed_operations_return_ok() {
        let caps = AgentCapabilities::full_access();
        assert!(caps.check_read("any/path").is_ok());
        assert!(caps.check_write("any/path").is_ok());
        assert!(caps.check_exec("any command").is_ok());
    }

    /// Verify `full_access()` never blocks common shell patterns that agents
    /// routinely emit. Each entry here was either denied in a real session
    /// or represents a pattern class that naive deny-lists would break.
    #[test]
    fn full_access_allows_common_shell_patterns() {
        let caps = AgentCapabilities::full_access();

        let commands = [
            // Heredoc with cat redirect (denied in previous session)
            "cat > /tmp/test_caps.rs << 'EOF'\nfn main() { println!(\"hello\"); }\nEOF",
            // Grep with pipe-separated OR patterns (denied in previous session)
            r#"grep -n "agent_loop\|Permission\|permission\|denied\|Denied" src/agent_loop.rs"#,
            // Multi-command chains
            "cd /workspace && cargo build && cargo test",
            "mkdir -p /tmp/test && cd /tmp/test && echo hello > file.txt",
            // Pipes and redirects
            "cargo test 2>&1 | head -50",
            "cat file.txt | grep pattern | wc -l",
            "echo 'data' >> /tmp/append.txt",
            // Subshells and grouping
            "(cd /tmp && ls -la)",
            "{ echo a; echo b; } > /tmp/out.txt",
            // Process substitution and special chars
            "diff <(sort file1) <(sort file2)",
            "find . -name '*.rs' -exec grep -l 'TODO' {} +",
            // Common dev commands
            "cargo clippy -- -D warnings",
            "cargo fmt --check",
            "git diff --stat HEAD~1",
            "npm install && npm run build",
            "python3 -c 'print(\"hello\")'",
            // Commands with special regex chars that shouldn't trip up matching
            "grep -rn 'foo(bar)' src/",
            "echo '$HOME is ~/work'",
            "ls *.rs",
        ];

        for cmd in &commands {
            assert!(
                caps.check_exec(cmd).is_ok(),
                "full_access() unexpectedly blocked command: {cmd}"
            );
        }
    }

    /// Verify `full_access()` allows reading/writing any path, including
    /// paths that a naive deny-list might block (dotfiles, tmp, etc.).
    #[test]
    fn full_access_allows_all_paths() {
        let caps = AgentCapabilities::full_access();

        let paths = [
            "src/main.rs",
            ".env",
            ".env.local",
            "/tmp/test_caps.rs",
            "/home/user/.ssh/config",
            "/workspace/secrets/api_key.txt",
            "/workspace/certs/server.pem",
            "Cargo.toml",
            "node_modules/.package-lock.json",
        ];

        for path in &paths {
            assert!(
                caps.check_read(path).is_ok(),
                "full_access() unexpectedly blocked read: {path}"
            );
            assert!(
                caps.check_write(path).is_ok(),
                "full_access() unexpectedly blocked write: {path}"
            );
        }
    }

    #[test]
    fn invalid_deny_regex_fails_closed() {
        // An invalid regex in denied_commands should block everything (fail closed)
        let caps = AgentCapabilities::full_access().with_denied_commands(vec!["[unclosed".into()]);

        // The invalid pattern should cause all commands to be denied
        assert!(caps.check_command("cargo build").is_err());
        assert!(caps.check_command("ls").is_err());
    }

    #[test]
    fn invalid_allow_regex_fails_open() {
        // An invalid regex in allowed_commands should not grant access (fail open)
        let caps = AgentCapabilities::full_access().with_allowed_commands(vec!["[unclosed".into()]);

        // The invalid pattern should not match, so nothing is allowed
        assert!(caps.check_command("cargo build").is_err());
    }

    /// Verify `Default` is `full_access()` — the SDK is unopinionated out of the box.
    /// Consumers restrict from there, not opt-in to each capability.
    #[test]
    fn default_is_full_access() {
        let caps = AgentCapabilities::default();

        // Everything allowed by default
        assert!(caps.check_read("src/main.rs").is_ok());
        assert!(caps.check_write("src/main.rs").is_ok());
        assert!(caps.check_exec("ls").is_ok());

        // No deny lists
        assert!(caps.check_path(".env").is_ok());
        assert!(caps.check_path("/home/user/.ssh/id_rsa").is_ok());
        assert!(caps.check_command("sudo rm -rf /").is_ok());
    }
}