Enum ToolError 

pub enum ToolError {
    Blocked {
        command: String,
    },
    BlockedWithFix {
        command: String,
        suggestion: Option<SafeFixSuggestion>,
    },
    SandboxViolation {
        path: String,
    },
    ConfirmationRequired {
        command: String,
    },
    Timeout {
        timeout_secs: u64,
    },
    Cancelled,
    InvalidParams {
        message: String,
    },
    Execution(Error),
    Http {
        status: u16,
        message: String,
    },
    Shell {
        exit_code: i32,
        category: ToolErrorCategory,
        message: String,
    },
    SnapshotFailed {
        reason: String,
    },
    OutOfScope {
        tool_id: String,
        task_type: Option<String>,
    },
    SafetyDenied {
        reason: String,
    },
}

Errors that can occur during tool execution.

Variants

Blocked

Fields

command: String

BlockedWithFix

Command was blocked and a safer alternative is available.

Emitted by ShellExecutor when suggest_fix returns a suggestion. The agent receives both the block reason and the alternative so it can self-correct without additional prompting.

Fields

command: String

suggestion: Option<SafeFixSuggestion>

SandboxViolation

Fields

path: String

ConfirmationRequired

Fields

command: String

Timeout

Fields

timeout_secs: u64

Cancelled

InvalidParams

Fields

message: String

Execution(Error)

Http

HTTP or API error with status code for fine-grained classification.

Used by WebScrapeExecutor and other HTTP-based tools to preserve the status code for taxonomy classification. Scope: HTTP tools only (MCP uses a separate path).

Fields

status: u16

message: String

Shell

Shell execution error with explicit exit code and pre-classified category.

Used by ShellExecutor when the exit code or stderr content maps to a known taxonomy category (e.g., exit 126 → PolicyBlocked, exit 127 → PermanentFailure). Preserves the exit code for audit logging and the category for skill evolution.

Fields

exit_code: i32

category: ToolErrorCategory

message: String

SnapshotFailed

Fields

reason: String

OutOfScope

Tool call rejected because the tool id is outside the active capability scope.

Emitted by ScopedToolExecutor before any tool side-effect runs. The audit log records error_category = "out_of_scope".

Fields

tool_id: String

Fully-qualified tool id that was rejected.

task_type: Option<String>

Active task type at dispatch time, if any.

SafetyDenied

Tool call blocked by ShadowProbeExecutor after the LLM safety probe returned Deny.

Emitted before any tool side-effect runs. The probe evaluated the full trajectory context and determined the call is unsafe. Reason is LLM-generated; shown to the agent loop as the tool result so the model can adapt.

Fields

reason: String

Human-readable explanation from the LLM safety probe.

Implementations

impl ToolError

pub fn category(&self) -> ToolErrorCategory

Fine-grained error classification using the 12-category taxonomy.

Prefer category() over kind() for new code. kind() is preserved for backward compatibility and delegates to category().error_kind().

pub fn kind(&self) -> ErrorKind

Coarse classification for backward compatibility. Delegates to category().error_kind().

For Execution(io::Error), the classification inspects io::Error::kind():

• Transient: TimedOut, WouldBlock, Interrupted, ConnectionReset, ConnectionAborted, BrokenPipe — these may succeed on retry.
• Permanent: NotFound, PermissionDenied, AlreadyExists, and all other I/O error kinds — retrying would waste time with no benefit.

Trait Implementations

impl Debug for ToolError

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

Formats the value using the given formatter.

impl Display for ToolError

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

Formats the value using the given formatter.

impl Error for ToolError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for ToolError

fn from(source: Error) -> Self

Converts to this type from the input type.