Crate zeph_tools 

Tool execution abstraction, shell backend, web scraping, and audit logging for Zeph.

This crate provides the ToolExecutor trait and its concrete implementations:

• ShellExecutor — executes bash blocks from LLM responses with sandboxing, blocklists, output filtering, transactional rollback, and audit logging.
• WebScrapeExecutor — fetches and scrapes web pages via CSS selectors, with SSRF protection and domain policies.
• CompositeExecutor — chains two executors with first-match-wins dispatch.
• FileExecutor — reads and writes local files within a sandbox.
• DiagnosticsExecutor — exposes agent self-diagnostics as a tool.

Architecture

The primary abstraction is ToolExecutor, an async trait implemented by every backend. When dynamic dispatch is needed (e.g., storing heterogeneous executors in a Vec), use ErasedToolExecutor or wrap with DynExecutor.

Tool calls originate from two paths:

1. Fenced code blocks — legacy LLM responses containing ```bash or ```scrape blocks dispatched via ToolExecutor::execute.
2. Structured tool calls — modern JSON tool calls dispatched via ToolExecutor::execute_tool_call.

Security

Every executor enforces security controls before execution:

• ShellExecutor checks the command against a blocklist, validates paths against an allowlist sandbox, and optionally requires user confirmation for destructive patterns.
• WebScrapeExecutor validates the URL scheme (HTTPS only), resolves DNS, and rejects private-network addresses (SSRF protection).
• AuditLogger writes a structured JSONL entry for every tool invocation.

Example

use zeph_tools::{ShellExecutor, ToolExecutor, ShellConfig};

let config = ShellConfig::default();
let executor = ShellExecutor::new(&config);

// Execute a fenced bash block from an LLM response.
let response = "```bash\necho hello\n```";
if let Ok(Some(output)) = executor.execute(response).await {
    println!("{}", output.summary);
}

Re-exports

pub use adversarial_gate::AdversarialPolicyGateExecutor;

pub use adversarial_policy::PolicyDecision as AdversarialPolicyDecision;

pub use adversarial_policy::PolicyValidator;

pub use adversarial_policy::parse_policy_lines;

pub use anomaly::AnomalyDetector;

pub use anomaly::AnomalySeverity;

pub use anomaly::is_reasoning_model;

pub use audit::AuditEntry;

pub use audit::AuditLogger;

pub use audit::AuditResult;

pub use audit::EgressEvent;

pub use audit::VigilRiskLevel;

pub use audit::chrono_now;

pub use audit::log_tool_risk_summary;

pub use cache::CacheKey;

pub use cache::ToolResultCache;

pub use cache::is_cacheable;

pub use composite::CompositeExecutor;

pub use config::build_permission_policy;

pub use config::validate_sandbox_denied_domains;

pub use cwd::SetCwdExecutor;

pub use diagnostics::DiagnosticsExecutor;

pub use error_taxonomy::ToolErrorFeedback;

pub use error_taxonomy::classify_http_status;

pub use error_taxonomy::classify_io_error;

pub use executor::ClaimSource;

pub use executor::DiffData;

pub use executor::DynExecutor;

pub use executor::ErasedToolExecutor;

pub use executor::ErrorKind;

pub use executor::FilterStats;

pub use executor::MAX_TOOL_OUTPUT_CHARS;

pub use executor::TOOL_EVENT_CHANNEL_CAP;

pub use executor::ToolCall;

pub use executor::ToolError;

pub use executor::ToolEvent;

pub use executor::ToolEventRx;

pub use executor::ToolEventTx;

pub use executor::ToolExecutor;

pub use executor::ToolOutput;

pub use executor::truncate_tool_output;

pub use executor::truncate_tool_output_at;

pub use file::FileExecutor;

pub use filter::CommandMatcher;

pub use filter::FilterConfidence;

pub use filter::FilterMetrics;

pub use filter::FilterResult;

pub use filter::OutputFilter;

pub use filter::OutputFilterRegistry;

pub use filter::sanitize_output;

pub use filter::strip_ansi;

pub use permissions::PermissionPolicy;

pub use policy::PolicyCompileError;

pub use policy::PolicyContext;

pub use policy::PolicyDecision;

pub use policy::PolicyEnforcer;

pub use policy_gate::PolicyGateExecutor;

pub use registry::ToolRegistry;

pub use sandbox::NoopSandbox;

pub use sandbox::Sandbox;

pub use sandbox::SandboxError;

pub use sandbox::SandboxPolicy;

pub use sandbox::build_sandbox;

pub use sandbox::build_sandbox_with_policy;

pub use schema_filter::DependencyExclusion;

pub use schema_filter::InclusionReason;

pub use schema_filter::ToolDependencyGraph;

pub use schema_filter::ToolEmbedding;

pub use schema_filter::ToolFilterResult;

pub use schema_filter::ToolSchemaFilter;

pub use scrape::WebScrapeExecutor;

pub use search_code::LspSearchBackend;

pub use search_code::SearchCodeExecutor;

pub use search_code::SearchCodeHit;

pub use search_code::SearchCodeSource;

pub use search_code::SemanticSearchBackend;

pub use shell::background::BackgroundCompletion;

pub use shell::background::BackgroundRunSnapshot;

pub use shell::background::RunId;

pub use shell::DEFAULT_BLOCKED_COMMANDS;

pub use shell::SHELL_INTERPRETERS;

pub use shell::ShellExecutor;

pub use shell::ShellOutputEnvelope;

pub use shell::ShellPolicyHandle;

pub use shell::check_blocklist;

pub use shell::effective_shell_command;

pub use tool_filter::ToolFilter;

pub use trust_gate::TrustGateExecutor;

pub use utility::UtilityAction;

pub use utility::UtilityContext;

pub use utility::UtilityScore;

pub use utility::UtilityScorer;

pub use utility::has_explicit_tool_request;

pub use verifier::DestructiveCommandVerifier;

pub use verifier::FirewallVerifier;

pub use verifier::InjectionPatternVerifier;

pub use verifier::PreExecutionVerifier;

pub use verifier::UrlGroundingVerifier;

pub use verifier::VerificationResult;

Modules

adversarial_gate

AdversarialPolicyGateExecutor: wraps an inner ToolExecutor and runs an LLM-based policy check before delegating any structured tool call.

adversarial_policy

LLM-based adversarial policy validator.

anomaly

Sliding-window anomaly detection for tool execution patterns.

audit

Structured JSONL audit logging for tool invocations.

cache

composite

Composite executor that chains two ToolExecutor implementations.

config

Tool configuration re-exports and runtime helpers.

cwd

diagnostics

domain_match

Domain pattern matching used by both the web scrape allowlist/denylist and the sandbox egress deny list.

error_taxonomy

12-category tool invocation error taxonomy (arXiv:2601.16280).

executor

file

filter

Command-aware output filtering pipeline.

net

Network utilities for tool crates.

patterns

Re-export of injection-detection patterns from zeph-common for backwards compatibility.

permissions

policy

Declarative policy compiler for tool call authorization.

policy_gate

PolicyGateExecutor: wraps an inner ToolExecutor and enforces declarative policy rules before delegating any tool call.

registry

sandbox

OS-level sandbox abstractions for subprocess tool execution.

schema_filter

Dynamic tool schema filtering based on query-tool embedding similarity (#2020).

scrape

Web scraping executor with SSRF protection and domain policy enforcement.

search_code

shell

Shell executor that parses and runs bash blocks from LLM responses.

tool_filter

trust_gate

Trust-level enforcement layer for tool execution.

trust_level

Re-export of SkillTrustLevel from zeph-common for backwards compatibility.

utility

Utility-guided tool dispatch gate (arXiv:2603.19896).

verifier

Pre-execution verification for tool calls.

Structs

AdversarialPolicyConfig

Configuration for the LLM-based adversarial policy agent.

AnomalyConfig

Configuration for the sliding-window anomaly detector.

AuditConfig

Configuration for audit logging of tool executions.

AuthorizationConfig

OAP-style declarative authorization config.

DependencyConfig

Configuration for the tool dependency graph feature.

DestructiveVerifierConfig

Configuration for the destructive command verifier.

EgressConfig

Configuration for egress network event logging.

FileConfig

Per-path read allow/deny sandbox for the file tool.

FilterConfig

Configuration for output filters.

FirewallVerifierConfig

Configuration for the firewall verifier.

InjectionVerifierConfig

Configuration for the injection pattern verifier.

OverflowConfig

Configuration for large tool response offload to SQLite.

PermissionRule

Single permission rule: glob pattern + action.

PermissionsConfig

TOML-deserializable permissions config section.

PolicyConfig

TOML-deserializable policy configuration.

PolicyMessage

Minimal message type for policy LLM calls.

PolicyRuleConfig

A single policy rule as read from TOML.

PreExecutionVerifierConfig

Top-level configuration for all pre-execution verifiers.

ResultCacheConfig

Configuration for the tool result cache.

RetryConfig

Configuration for tool error retry behavior.

SandboxConfig

OS-level subprocess sandbox configuration ([tools.sandbox] TOML section).

ScrapeConfig

Configuration for the web scrape tool.

SecurityFilterConfig

Configuration for tool output security filter.

ShellConfig

Shell-specific configuration: timeout, command blocklist, and allowlist overrides.

SpeculativeAllowlistConfig

Shell command regex allowlist for speculative execution.

SpeculativeConfig

Top-level configuration for speculative tool execution.

SpeculativePatternConfig

Pattern-based (PASTE) speculative execution config.

TafcConfig

Configuration for Think-Augmented Function Calling (TAFC).

ToolDependency

Dependency specification for a single tool.

ToolName

Strongly-typed tool name label.

ToolsConfig

Top-level configuration for tool execution.

UrlGroundingVerifierConfig

Configuration for the URL grounding verifier.

UtilityScoringConfig

Configuration for utility-guided tool dispatch.

Enums

AutonomyLevel

Tool access level controlling agent autonomy.

DefaultEffect

Default effect when no policy rule matches.

ErrorDomain

High-level error domain for recovery strategy dispatch.

PermissionAction

Action a permission rule resolves to.

PolicyEffect

Effect applied when a policy rule matches.

PolicyRole

Role for a PolicyMessage.

SandboxProfile

Baseline restriction profile for the OS-level sandbox.

SkillTrustLevel

Trust tier controlling what a skill is allowed to do.

SpeculationMode

Speculative tool execution mode.

ToolErrorCategory

Fine-grained 12-category classification of tool invocation errors.

ToolInvocationPhase

Invocation phase in which a tool failure occurred, per arXiv:2601.16280.

Traits

PolicyLlmClient

Trait for sending chat messages to the policy LLM.

Functions

is_private_ip

Returns true if addr is a non-routable or private IP address that should be blocked for outbound connections (SSRF defense).