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, config::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::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::AdversarialPolicyConfig;

pub use config::AnomalyConfig;

pub use config::AuditConfig;

pub use config::AuthorizationConfig;

pub use config::DependencyConfig;

pub use config::FileConfig;

pub use config::OverflowConfig;

pub use config::ResultCacheConfig;

pub use config::RetryConfig;

pub use config::ScrapeConfig;

pub use config::ShellConfig;

pub use config::TafcConfig;

pub use config::ToolDependency;

pub use config::ToolsConfig;

pub use config::UtilityScoringConfig;

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::ToolCall;

pub use executor::ToolError;

pub use executor::ToolEvent;

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::FilterConfig;

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::AutonomyLevel;

pub use permissions::PermissionAction;

pub use permissions::PermissionPolicy;

pub use permissions::PermissionRule;

pub use permissions::PermissionsConfig;

pub use policy::DefaultEffect;

pub use policy::PolicyCompileError;

pub use policy::PolicyConfig;

pub use policy::PolicyContext;

pub use policy::PolicyDecision;

pub use policy::PolicyEffect;

pub use policy::PolicyEnforcer;

pub use policy::PolicyRuleConfig;

pub use policy_gate::PolicyGateExecutor;

pub use registry::ToolRegistry;

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::DEFAULT_BLOCKED_COMMANDS;

pub use shell::SHELL_INTERPRETERS;

pub use shell::ShellExecutor;

pub use shell::ShellOutputEnvelope;

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::DestructiveVerifierConfig;

pub use verifier::FirewallVerifier;

pub use verifier::FirewallVerifierConfig;

pub use verifier::InjectionPatternVerifier;

pub use verifier::InjectionVerifierConfig;

pub use verifier::PreExecutionVerifier;

pub use verifier::PreExecutionVerifierConfig;

pub use verifier::UrlGroundingVerifier;

pub use verifier::UrlGroundingVerifierConfig;

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

cwd

diagnostics

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

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

PolicyMessage

Minimal message type for policy LLM calls.

ToolName

Strongly-typed tool name label.

Enums

ErrorDomain

High-level error domain for recovery strategy dispatch.

PolicyRole

Role for a PolicyMessage.

SkillTrustLevel

Trust tier controlling what a skill is allowed to do.

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).