Skip to content

API Reference

ToolClad provides library APIs in four languages. Each implementation supports manifest parsing, argument validation, command construction, execution, and MCP schema generation.

Rust

Crate: toolclad

Functions

load_manifest(path) -> Result<Manifest>

Load and parse a .clad.toml manifest from a file path.

let manifest = toolclad::load_manifest("tools/nmap_scan.clad.toml")?;
println!("Tool: {} v{}", manifest.tool.name, manifest.tool.version);

parse_manifest(toml_str) -> Result<Manifest>

Parse a manifest from a TOML string (useful for testing or embedded manifests).

let toml = std::fs::read_to_string("tools/whois_lookup.clad.toml")?;
let manifest = toolclad::parse_manifest(&toml)?;

generate_mcp_schema(manifest) -> Value

Generate an MCP-compatible JSON Schema from a manifest, including both inputSchema (from [args]) and outputSchema (from [output.schema]).

let manifest = toolclad::load_manifest("tools/nmap_scan.clad.toml")?;
let schema = toolclad::generate_mcp_schema(&manifest);
println!("{}", serde_json::to_string_pretty(&schema)?);

validator::validate_arg(name, def, value) -> Result<()>

Validate a single argument value against its type definition. Returns Ok(()) if valid, or an error describing the validation failure. This entry point validates in template mode: whitespace is always rejected, regardless of allow_whitespace.

use toolclad::types::ArgDef;

let def = ArgDef {
    type_name: "enum".to_string(),
    allowed: Some(vec!["ping".into(), "service".into()]),
    required: true,
    position: 1,
    ..Default::default()
};

assert!(toolclad::validator::validate_arg("scan_type", &def, "ping").is_ok());
assert!(toolclad::validator::validate_arg("scan_type", &def, "exploit").is_err());

validator::validate_arg_mode(name, def, value, mode) -> Result<()>

Same as validate_arg, with an explicit validation mode. The mode is either template (strict; whitespace always rejected) or exec (honors allow_whitespace = true). The executor passes exec mode only when the manifest declared command.exec directly; a template compiled to exec at load is still template mode. All other hygiene rules (NUL, control characters, quotes/backslash, leading dash) and the host/IP policy apply in both modes.

validator::validate_arg_with_custom_types(name, def, value, custom_types) -> Result<()>

Validate a single argument value against its type definition, resolving custom types from a loaded toolclad.toml. If the type is not a built-in type, it is looked up in custom_types and validated against the base type with any additional constraints.

let custom_types = toolclad::load_custom_types("toolclad.toml")?;
toolclad::validator::validate_arg_with_custom_types("service", &def, "ssh", &custom_types)?;

load_custom_types(path) -> Result<HashMap<String, CustomTypeDef>>

Load custom type definitions from a toolclad.toml file. Returns a map of type name to definition (base type + constraints). The CLI discovers toolclad.toml by walking up from the manifest's directory; library callers that want the same behavior should do the same walk before calling validate_arg_with_custom_types.

let custom_types = toolclad::load_custom_types("toolclad.toml")?;
// custom_types["service_protocol"] -> base: "enum", allowed: ["ssh", "ftp", ...]

executor::build_command(manifest, args) -> Result<Vec<String>>

Construct the command argument array from a manifest and validated arguments. Does not execute. Returns the argv array that would be passed to execve.

use std::collections::HashMap;

let manifest = toolclad::load_manifest("tools/nmap_scan.clad.toml")?;
let mut args = HashMap::new();
args.insert("target".into(), "10.0.1.0/24".into());
args.insert("scan_type".into(), "service".into());

let cmd = toolclad::executor::build_command(&manifest, &args)?;
// ["nmap", "-sT", "-sV", "--version-intensity", "5", "--max-rate", "1000", ...]

executor::execute(manifest, args) -> Result<EvidenceEnvelope>

Validate arguments, run the default policy gate, construct the command, execute with timeout, parse output, and return the evidence envelope. The default gate denies when tool.human_approval is true or tool.risk_tier is high or critical; the error message starts with policy gate denied:.

use std::collections::HashMap;

let manifest = toolclad::load_manifest("tools/whois_lookup.clad.toml")?;
let mut args = HashMap::new();
args.insert("target".into(), "example.com".into());

let result = toolclad::executor::execute(&manifest, &args)?;
println!("Status: {}, Duration: {}ms", result.status, result.duration_ms);
Calling execute from async code

executor::execute is synchronous and blocks the current thread for the lifetime of the child process. Tokio (and any other async runtime) callers must not invoke it directly from an async fn, or the call will stall the runtime worker for seconds to minutes.

Wrap with tokio::task::spawn_blocking and, if you want an upper bound on the whole call (including argument validation and output parsing, which the manifest's timeout_seconds does not cover), add tokio::time::timeout:

use std::time::Duration;
use std::collections::HashMap;
use std::sync::Arc;

async fn run_tool(
    manifest: Arc<toolclad::Manifest>,
    args: HashMap<String, String>,
) -> Result<toolclad::EvidenceEnvelope, String> {
    const CALLER_TIMEOUT: Duration = Duration::from_secs(120);

    let handle = tokio::task::spawn_blocking(move || {
        toolclad::executor::execute(&manifest, &args)
    });

    match tokio::time::timeout(CALLER_TIMEOUT, handle).await {
        Ok(Ok(Ok(envelope))) => Ok(envelope),
        Ok(Ok(Err(e)))       => Err(format!("toolclad: {e}")),
        Ok(Err(join_err))    => Err(format!("task panicked: {join_err}")),
        Err(_)               => Err(format!("timed out after {:?}", CALLER_TIMEOUT)),
    }
}

Notes: - Two timeouts, two scopes. The manifest's timeout_seconds kills the child process if it runs too long. The caller tokio::time::timeout bounds the entire sync call and is your safety net if spawn, argument validation, or output parsing hangs. Set it to timeout_seconds + a small buffer. - Arc the manifest. Cloning a full Manifest into each blocking task is wasteful; wrap it in Arc at load time and Arc::clone per invocation. - Three nested Results. The outer one is the tokio::time::timeout verdict (Err = timed out). The middle is the JoinHandle (Err = task panicked). The inner is the ToolClad result. Handle all three.

executor::execute_with_gate(manifest, args, gate) -> Result<EvidenceEnvelope>

Like execute, but with a caller-supplied gate:

GateDecision = Allow | Deny(reason)
Gate         = fn(&Manifest, &validated_args) -> GateDecision

The gate runs after argument validation and before anything is spawned. Use it to wire an approval workflow or an external policy engine (Cedar evaluation is not performed by the library). default_gate is the gate execute uses.

let result = toolclad::executor::execute_with_gate(&manifest, &args, |m, _validated| {
    if m.tool.human_approval && !operator_has_approved(&m.tool.name) {
        toolclad::executor::GateDecision::Deny("awaiting operator approval".into())
    } else {
        toolclad::executor::GateDecision::Allow
    }
})?;

executor::execute_approved(manifest, args) -> Result<EvidenceEnvelope>

Like execute, with an allow-all gate. This is what toolclad run --approve calls. Use it only after the approval has been obtained elsewhere.

executor::dry_run(manifest, args) -> Result<DryRunResult>

Validate arguments and construct the command without executing. Returns the command that would be run plus validation details.

let manifest = toolclad::load_manifest("tools/nmap_scan.clad.toml")?;
let mut args = HashMap::new();
args.insert("target".into(), "10.0.1.0/24".into());
args.insert("scan_type".into(), "service".into());

let result = toolclad::executor::dry_run(&manifest, &args)?;
println!("Would run: {}", result.command.join(" "));

Types

Manifest

Top-level manifest structure containing all sections.

Field Type Description
tool ToolMeta Tool metadata ([tool] section)
args HashMap<String, ArgDef> Parameter definitions ([args.*])
command Option<CommandDef> Command template ([command])
http Option<HttpDef> HTTP backend ([http])
mcp Option<McpProxyDef> MCP proxy backend ([mcp])
session Option<SessionDef> Session configuration ([session])
browser Option<BrowserDef> Browser configuration ([browser])
output OutputDef Output configuration ([output])

ToolMeta

Tool metadata from the [tool] section.

Field Type Description
name String Tool identifier
version String Tool version
binary Option<String> Executable path (oneshot/session)
mode Option<String> "oneshot" (default), "session", or "browser"
description String Human-readable description
timeout_seconds u64 Execution timeout; must be greater than zero
risk_tier String "low", "medium", "high", or "critical"; high/critical are denied by the default gate
human_approval bool Denied by the default gate when true
network_egress bool Forces block_internal = true on every network-target arg at load
allow_interpreter bool Permits an interpreter as argv[0]
dispatch String "exec" (default) or "callback"
limits Option<Limits> [tool.limits] rlimits (applied in Rust and Python only)

ArgDef

Parameter definition from [args.*].

Field Type Description
type_name String Type identifier (e.g., "string", "enum", "scope_target")
position usize Positional order
required bool Whether the argument is mandatory
default Option<String> Default value
allowed Option<Vec<String>> Allowed values (for enum type)
pattern Option<String> Regex pattern constraint
min Option<i64> Minimum value (for integer type)
max Option<i64> Maximum value (for integer type)
clamp bool Clamp out-of-range values instead of rejecting
min_float / max_float Option<f64> Bounds for the number type
schemes Option<Vec<String>> Allowed URL schemes (default http, https)
scope_check bool Check against scope/scope.toml (fail-closed)
block_internal bool Apply the private-range policy and DNS resolution
allow_whitespace bool Permit whitespace (exec mode only)
allow_leading_dash bool Permit a leading -/+
description String Human-readable description

EvidenceEnvelope

Execution result with metadata.

Field Type Description
status String "success", "error", "timeout", "schema_error", "client_error", "server_error", "redirect_blocked", or "delegation_preview"
scan_id String Unique invocation identifier
tool String Tool name
command String Constructed command string
duration_ms u64 Execution time in milliseconds
timestamp String ISO 8601 timestamp
exit_code i32 Process exit code
stderr String Standard error output
output_hash String SHA-256 hash of raw output
results Value Parsed and validated output; on schema_error, {"schema_error": ..., "raw_output": ...}

Python

Package: toolclad

Functions

load_manifest(path) -> Manifest

Load and parse a .clad.toml manifest.

from toolclad import load_manifest

manifest = load_manifest("tools/nmap_scan.clad.toml")
print(f"Tool: {manifest.tool.name} v{manifest.tool.version}")

validate_arg(arg_def, value) -> None

Validate a value against an argument definition. Raises ValueError on failure.

from toolclad import validate_arg
from toolclad.manifest import ArgDef

arg_def = ArgDef(
    type_name="enum",
    allowed=["ping", "service", "version"],
    required=True,
    position=1,
)

validate_arg(arg_def, "ping")      # OK
validate_arg(arg_def, "exploit")   # raises ValueError

validate_arg validates in template mode (whitespace always rejected).

validate_arg_mode(arg_def, value, mode) -> None

Same as validate_arg with an explicit mode: template (strict) or exec (honors allow_whitespace = True). The executor uses exec mode only for manifests that declare command.exec directly.

build_command(manifest, args) -> list[str]

Construct the command argument array without executing.

from toolclad import load_manifest, build_command

manifest = load_manifest("tools/nmap_scan.clad.toml")
cmd = build_command(manifest, {"target": "10.0.1.0/24", "scan_type": "service"})
print(cmd)  # ["nmap", "-sT", "-sV", ...]

execute(manifest, args, *, gate=None, approve=False) -> dict

Validate, run the policy gate, construct, execute, parse, and return the evidence envelope.

  • With no keyword arguments the default gate is used: it denies when human_approval is true or risk_tier is high/critical, raising an error whose message starts with policy gate denied:.
  • gate= supplies a callable (manifest, validated_args) -> GateDecision (Allow or Deny(reason)) that replaces the default gate. Cedar evaluation is not performed by the library; wire it in here.
  • approve=True uses an allow-all gate (what toolclad run --approve does).
from toolclad import load_manifest, execute

manifest = load_manifest("tools/whois_lookup.clad.toml")
result = execute(manifest, {"target": "example.com"})
print(f"Status: {result['status']}, Duration: {result['duration_ms']}ms")

# Explicitly approved high-risk tool
result = execute(nikto_manifest, {"target": "example.com"}, approve=True)

Dataclass Types

Class Description
Manifest Top-level manifest with tool, args, command, http, mcp, session, browser, output
ToolMeta Tool metadata (name, version, binary, mode, description, timeout_seconds, risk_tier)
ArgDef Parameter definition (type_name, position, required, default, allowed, pattern, min, max)
HttpDef HTTP backend (method, url, headers, body_template, success_status, error_status)
McpProxyDef MCP proxy backend (server, tool, field_map)
SessionDef Session configuration (startup_command, ready_pattern, commands, timeouts)
BrowserDef Browser configuration (engine, connect, extract_mode, scope, commands)

JavaScript

Package: toolclad

Functions

loadManifest(path) -> Manifest

Load and parse a .clad.toml manifest.

import { loadManifest } from "toolclad";

const manifest = loadManifest("tools/nmap_scan.clad.toml");
console.log(`Tool: ${manifest.tool.name} v${manifest.tool.version}`);

validateArg(argDef, value) -> void

Validate a value against an argument definition. Throws on failure.

import { validateArg } from "toolclad";

const argDef = {
  type_name: "enum",
  allowed: ["ping", "service", "version"],
  required: true,
  position: 1,
};

validateArg(argDef, "ping");     // OK
validateArg(argDef, "exploit");  // throws Error

validateArg validates in template mode (whitespace always rejected). Because synchronous DNS is not available in Node, validateArg rejects a hostname on an argument with block_internal: true (hostname cannot be verified without DNS resolution; pass an IP literal or use validateArgAsync); IP literals are checked synchronously.

validateArgMode(argDef, value, mode) -> void

Same as validateArg with an explicit mode: template (strict) or exec (honors allow_whitespace: true).

validateArgAsync(argDef, value) -> Promise<void>

Asynchronous variant that resolves hostnames with dns.promises.lookup({ all: true }) and applies the host/IP policy to every answer when block_internal is set. Use it wherever a hostname must be accepted under block_internal.

import { validateArgAsync } from "toolclad";

await validateArgAsync({ type_name: "scope_target", block_internal: true }, "example.com");

buildCommand(manifest, args) -> string[]

Construct the command argument array without executing.

import { loadManifest, buildCommand } from "toolclad";

const manifest = loadManifest("tools/nmap_scan.clad.toml");
const cmd = buildCommand(manifest, { target: "10.0.1.0/24", scan_type: "service" });
// ["nmap", "-sT", "-sV", ...]

execute(manifest, args, { gate, approve }) -> Promise<object>

Validate, run the policy gate, construct, execute, parse, and return the evidence envelope. execute is asynchronous -- it spawns the child with spawn and a timer so the SIGTERM-then-SIGKILL sequence can run -- and must be awaited.

  • With no options the default gate is used: it denies when human_approval is true or risk_tier is high/critical, rejecting with an error whose message starts with policy gate denied:.
  • gate is a function (manifest, validatedArgs) => GateDecision (Allow or Deny(reason)) replacing the default gate. Cedar evaluation is not performed by the library.
  • approve: true uses an allow-all gate.
import { loadManifest, execute } from "toolclad";

const manifest = loadManifest("tools/whois_lookup.clad.toml");
const result = await execute(manifest, { target: "example.com" });
console.log(`Status: ${result.status}, Duration: ${result.duration_ms}ms`);

// Explicitly approved high-risk tool
const scan = await execute(nikto, { target: "example.com" }, { approve: true });

executeSync (deprecated)

executeSync is kept as a deprecated alias that throws a clear error telling the caller to await execute(...). It no longer runs anything; update call sites rather than catching the error.

generateMcpSchema(manifest) -> object

Generate an MCP-compatible JSON Schema.

import { loadManifest, generateMcpSchema } from "toolclad";

const manifest = loadManifest("tools/nmap_scan.clad.toml");
const schema = generateMcpSchema(manifest);
console.log(JSON.stringify(schema, null, 2));

executeHttp(manifest, args) -> object

Execute an HTTP backend tool. Constructs the request from [http] (secrets expanded before arguments, URL values percent-encoded, body values JSON-escaped), sends it without following redirects, and returns the evidence envelope. Uses the built-in fetch with redirect: "manual"; nothing is passed through a child process, so headers and the URL never appear on any argv. executeHttpSync remains as a deprecated alias that returns the same Promise.

import { loadManifest, executeHttp } from "toolclad";

const manifest = loadManifest("tools/slack_post_message.clad.toml");
const result = await executeHttp(manifest, { channel: "C01234", message: "hello" });

executeMcp(manifest, args) -> object

Preview an MCP proxy call. Validates arguments, maps fields through field_map, and returns a delegation_preview envelope. No upstream MCP server is contacted; forwarding the call is the job of a hosting runtime.

import { loadManifest, executeMcp } from "toolclad";

const manifest = loadManifest("tools/github_create_issue.clad.toml");
const result = await executeMcp(manifest, { repo: "org/repo", title: "Bug report" });

Go

Module: github.com/ThirdKeyAI/ToolClad/go

manifest package

manifest.LoadManifest(path) -> (*Manifest, error)

Load and parse a .clad.toml manifest.

package main

import (
    "fmt"
    "github.com/ThirdKeyAI/ToolClad/go/pkg/manifest"
)

func main() {
    m, err := manifest.LoadManifest("tools/nmap_scan.clad.toml")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Tool: %s v%s\n", m.Tool.Name, m.Tool.Version)
}

validator package

validator.ValidateArg(def ArgDef, value string) -> error

Validate a value against an argument definition, in template mode (whitespace always rejected).

import "github.com/ThirdKeyAI/ToolClad/go/pkg/validator"

err := validator.ValidateArg(argDef, "ping")
if err != nil {
    fmt.Printf("Validation failed: %s\n", err)
}

validator.ValidateArgMode(def ArgDef, value string, mode) -> error

Same as ValidateArg with an explicit mode: template (strict) or exec (honors AllowWhitespace). Under block_internal, hostnames are resolved with net.DefaultResolver.LookupIPAddr and a 2 s context; resolution failure is a rejection.

executor package

executor.BuildCommand(manifest, args) -> ([]string, error)

Construct the command argument array without executing.

import "github.com/ThirdKeyAI/ToolClad/go/pkg/executor"

args := map[string]string{
    "target":    "10.0.1.0/24",
    "scan_type": "service",
}
cmd, err := executor.BuildCommand(m, args)
// ["nmap", "-sT", "-sV", ...]

executor.Execute(manifest, args) -> (*EvidenceEnvelope, error)

Validate, run the default policy gate, construct, execute, parse, and return the evidence envelope. The signature is unchanged; the default gate denies when human_approval is true or risk_tier is high/critical, returning an error whose message starts with policy gate denied:.

import "github.com/ThirdKeyAI/ToolClad/go/pkg/executor"

args := map[string]string{"target": "example.com"}
result, err := executor.Execute(m, args)
if err != nil {
    panic(err)
}
fmt.Printf("Status: %s, Duration: %dms\n", result.Status, result.DurationMs)

executor.ExecuteWithGate(manifest, args, gate) -> (*EvidenceEnvelope, error)

Like Execute, with a caller-supplied gate func(*Manifest, map[string]string) GateDecision (Allow or Deny(reason)). The gate runs after validation and before the spawn. Cedar evaluation is not performed by the library; wire it in here. toolclad run --approve uses an allow-all gate.

Go cannot set child rlimits portably, so [tool.limits] is parsed but not applied by this runtime; the timeout kill sequence is implemented with cmd.Cancel (SIGTERM to the process group) and cmd.WaitDelay (the SIGKILL grace period).