Struct ScopedToolExecutor 

pub struct ScopedToolExecutor<E: ToolExecutor> { /* private fields */ }

Wraps any ToolExecutor and enforces a capability scope on both tool listing and dispatch.

Type parameter

E is the inner executor (e.g., PolicyGateExecutor<TrustGateExecutor<CompositeExecutor>>).

Examples

use std::collections::HashSet;
use zeph_tools::scope::{ScopedToolExecutor, ToolScope};
use zeph_tools::{ToolExecutor, ToolCall};
use zeph_common::ToolName;

// Build a full (no-op) scope — identity, admits everything.
let scope = ToolScope::full();

// Wrap some inner executor (omitted for brevity).
struct MockExecutor;
impl ToolExecutor for MockExecutor {
    async fn execute(&self, _: &str) -> Result<Option<zeph_tools::ToolOutput>, zeph_tools::ToolError> { Ok(None) }
}
let executor = ScopedToolExecutor::new(MockExecutor, scope);

Implementations

impl<E: ToolExecutor> ScopedToolExecutor<E>

pub fn new(inner: E, initial_scope: ToolScope) -> Self

Create a new ScopedToolExecutor with the given initial scope.

Examples

use zeph_tools::scope::{ScopedToolExecutor, ToolScope};

struct Noop;
impl zeph_tools::ToolExecutor for Noop {
    async fn execute(&self, _: &str) -> Result<Option<zeph_tools::ToolOutput>, zeph_tools::ToolError> { Ok(None) }
}
let executor = ScopedToolExecutor::new(Noop, ToolScope::full());

pub fn with_audit(self, audit: Arc<AuditLogger>) -> Self

Attach an audit logger so every OutOfScope rejection writes an audit entry.

pub fn with_signal_queue(self, queue: RiskSignalQueue) -> Self

Attach a shared signal queue so OutOfScope rejections are recorded in the sentinel.

pub fn register_scope(&mut self, name: impl Into<String>, scope: ToolScope)

Register a named scope for use with set_scope_for_task.

pub fn set_scope_for_task(&self, task_type: &str) -> bool

Switch the active scope by task-type name. Returns false when the name is not found.

pub fn set_scope(&self, scope: ToolScope)

Replace the active scope with the given one directly.

pub fn scope_for_task(&self, task_type: &str) -> Option<Vec<String>>

Return the list of tool ids admitted by the scope for task_type.

Returns None when task_type is not registered.

Examples

use zeph_tools::scope::{ScopedToolExecutor, ToolScope};

struct Noop;
impl zeph_tools::ToolExecutor for Noop {
    async fn execute(&self, _: &str) -> Result<Option<zeph_tools::ToolOutput>, zeph_tools::ToolError> { Ok(None) }
}
let mut executor = ScopedToolExecutor::new(Noop, ToolScope::full());
// scope_for_task returns None for unregistered task types
assert!(executor.scope_for_task("unknown").is_none());

pub fn scope_at_definition_name(&self) -> Option<String>

Name of the active scope at the last tool_definitions() call (for audit).

pub fn active_scope_name(&self) -> Option<String>

Name of the currently active scope (for audit at dispatch time).

Trait Implementations

impl<E: ToolExecutor> ToolExecutor for ScopedToolExecutor<E>

fn tool_definitions(&self) -> Vec<ToolDef>

Return the filtered tool definitions visible to the LLM under the active scope.

Captures the active scope name into scope_at_definition for audit use.

async fn execute_tool_call( &self, call: &ToolCall, ) -> Result<Option<ToolOutput>, ToolError>

Execute a structured tool call, rejecting out-of-scope ids before any side-effect.

Returns ToolError::OutOfScope when the tool id is not in the active scope. The audit log entry at the call site must carry error_category = "out_of_scope".

async fn execute(&self, response: &str) -> Result<Option<ToolOutput>, ToolError>

Parse response for fenced tool blocks and execute them.

async fn execute_confirmed( &self, response: &str, ) -> Result<Option<ToolOutput>, ToolError>

Execute bypassing confirmation checks (called after user approves).

async fn execute_tool_call_confirmed( &self, call: &ToolCall, ) -> Result<Option<ToolOutput>, ToolError>

Execute a structured tool call bypassing confirmation checks.

fn set_skill_env(&self, env: Option<HashMap<String, String>>)

Inject environment variables for the currently active skill. No-op by default.

fn set_effective_trust(&self, level: SkillTrustLevel)

Set the effective trust level for the currently active skill. No-op by default.

fn is_tool_retryable(&self, tool_id: &str) -> bool

Whether the executor can safely retry this tool call on a transient error.

fn is_tool_speculatable(&self, tool_id: &str) -> bool

Whether a tool call can be safely dispatched speculatively (before the LLM finishes).

fn requires_confirmation(&self, _call: &ToolCall) -> bool

Return true when call would require user confirmation before execution.