machi-tools 1.0.0

Tool trait, dispatch, and execution context for Machi
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//! Approval gate for destructive or privileged tool calls.

use async_trait::async_trait;
use serde_json::Value;

use crate::error::{ToolError, codes};
use crate::metadata::ToolMetadata;
use crate::tool::DynTool;

/// Decision for a pending tool call.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ApprovalDecision {
    /// Allow execution.
    Allow,
    /// Deny execution (fail-closed to the model as a tool error).
    Deny,
}

/// Host-supplied gate consulted before running tools that need confirmation.
#[async_trait]
pub trait ApprovalGate: Send + Sync {
    /// Decide whether `tool` may run with `arguments`.
    async fn approve(
        &self,
        tool: &dyn DynTool,
        metadata: &ToolMetadata,
        arguments: &Value,
    ) -> Result<ApprovalDecision, ToolError>;
}

/// Always allows (library tests / trusted offline hosts).
#[derive(Debug, Default, Clone, Copy)]
pub struct AutoApprove;

#[async_trait]
impl ApprovalGate for AutoApprove {
    async fn approve(
        &self,
        _tool: &dyn DynTool,
        _metadata: &ToolMetadata,
        _arguments: &Value,
    ) -> Result<ApprovalDecision, ToolError> {
        Ok(ApprovalDecision::Allow)
    }
}

/// Always denies (negative tests).
#[derive(Debug, Default, Clone, Copy)]
pub struct AlwaysDeny;

#[async_trait]
impl ApprovalGate for AlwaysDeny {
    async fn approve(
        &self,
        tool: &dyn DynTool,
        _metadata: &ToolMetadata,
        _arguments: &Value,
    ) -> Result<ApprovalDecision, ToolError> {
        Err(codes::approval_denied(format!(
            "approval denied for tool {}",
            tool.name()
        )))
    }
}

/// Map deny decision to a tool error.
#[must_use]
pub fn denied_error(tool_name: &str) -> ToolError {
    codes::approval_denied(format!("approval denied for tool {tool_name}"))
}