Struct AgentCapabilities 

pub struct AgentCapabilities {
    pub read: bool,
    pub write: bool,
    pub exec: bool,
    pub allowed_paths: Vec<String>,
    pub denied_paths: Vec<String>,
    pub allowed_commands: Vec<String>,
    pub denied_commands: Vec<String>,
}

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.

Example

use agent_sdk::AgentCapabilities;

// Read-only agent that can only access src/ directory
let caps = AgentCapabilities::read_only()
    .with_allowed_paths(vec!["src/**/*".into()]);

// Full access agent with some restrictions
let caps = AgentCapabilities::full_access()
    .with_denied_paths(vec!["**/.env*".into(), "**/secrets/**".into()]);

Fields

read: bool

Can read files

write: bool

Can write/edit files

exec: bool

Can execute shell commands

allowed_paths: Vec<String>

Allowed path patterns (glob). Empty means all paths allowed.

denied_paths: Vec<String>

Denied path patterns (glob). Takes precedence over allowed_paths.

allowed_commands: Vec<String>

Allowed commands (regex patterns). Empty means all commands allowed when exec=true.

denied_commands: Vec<String>

Denied commands (regex patterns). Takes precedence over allowed_commands.

Implementations

impl AgentCapabilities

pub const fn none() -> Self

Create capabilities with no access (must explicitly enable)

pub const fn read_only() -> Self

Create read-only capabilities

pub const fn full_access() -> Self

Create full access capabilities

pub const fn with_read(self, enabled: bool) -> Self

Builder: enable read access

pub const fn with_write(self, enabled: bool) -> Self

Builder: enable write access

pub const fn with_exec(self, enabled: bool) -> Self

Builder: enable exec access

pub fn with_allowed_paths(self, paths: Vec<String>) -> Self

Builder: set allowed paths

pub fn with_denied_paths(self, paths: Vec<String>) -> Self

Builder: set denied paths

pub fn with_allowed_commands(self, commands: Vec<String>) -> Self

Builder: set allowed commands

pub fn with_denied_commands(self, commands: Vec<String>) -> Self

Builder: set denied commands

pub fn check_read(&self, path: &str) -> Result<(), String>

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_write(&self, path: &str) -> Result<(), String>

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_exec(&self, command: &str) -> Result<(), String>

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 can_read(&self, path: &str) -> bool

Returns true if reading path is allowed.

pub fn can_write(&self, path: &str) -> bool

Returns true if writing path is allowed.

pub fn can_exec(&self, command: &str) -> bool

Returns true if executing command is allowed.

pub fn check_path(&self, path: &str) -> Result<(), String>

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_command(&self, command: &str) -> Result<(), String>

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.

Trait Implementations

impl Clone for AgentCapabilities

fn clone(&self) -> AgentCapabilities

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentCapabilities

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentCapabilities

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentCapabilities

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentCapabilities

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.