ToolClad¶
Declarative tool interface contracts for agentic runtimes.
ToolClad is the tool execution layer of the ThirdKey trust stack: SchemaPin (tool integrity) / AgentPin (agent identity) / ToolClad (tool contracts) / Symbiont (runtime).
Version: 0.6.2 | Status: Release Candidate | License: MIT (spec), Apache 2.0 (Symbiont integration)
What ToolClad Does¶
ToolClad is a manifest format (.clad.toml) that replaces wrapper scripts, MCP tool schemas, and execution wiring with a single declarative file. One manifest defines everything: typed parameters, command construction, output parsing, and policy metadata.
A ToolClad manifest answers four questions:
- What can this tool accept? Typed parameters with validation constraints (enums, ranges, regex, scope checks, injection sanitization).
- How do you invoke it? An
execargv array or an HTTP request (executed by the reference runtimes), or an MCP server call, PTY session, or browser engine action (parsed and validated here, executed by a hosting runtime). The LLM never generates raw invocation details. - What does it produce? Output format, parsing rules, and a mandatory output schema that normalizes raw output into structured JSON.
- What is the interaction model? Two executing backends plus three parsed-only contracts share a common governance layer.
Key Features¶
- 15 built-in type validators -- all with shell injection sanitization, NUL/control-character/quote/whitespace/leading-dash rejection and a host/IP policy (
block_internal), plus custom types viatoolclad.toml - Two executing backends -- Shell command (
[command]) and HTTP API ([http]). MCP proxy, PTY session and CDP browser manifests are parsed and validated but are not executable by the reference runtimes - Command construction --
execarray (canonical) with mappings, conditionals, defaults, brace escapes andend_of_options; the deprecatedtemplatestring is compiled toexecat load; nosh -c - Strict loading -- unknown manifest keys are refused at load
- Policy gate -- deny-by-default for
human_approval = trueandrisk_tierhigh/critical; Cedar evaluation is external - MCP schema generation -- Auto-generate
inputSchema+outputSchemafrom manifest declarations - Evidence envelopes -- Structured JSON with scan_id, timestamps, exit_code, output_hash (SHA-256)
- Cedar policy integration -- Manifests declare Cedar resource/action for policy evaluation
- SchemaPin signing --
.clad.tomlfiles are signed directly as first-class artifacts - Output parsers -- builtin:json, builtin:xml, builtin:csv, builtin:jsonl, builtin:text; fail-closed schema validation; custom parser scripts are refused at load
- Session mode -- Per-interaction ORGA gating contract for interactive CLIs (psql, msfconsole, redis-cli); parsed and validated by the reference runtimes, executed by a hosting runtime
- Browser mode -- Governed headless or live browser session contract via CDP with URL scope enforcement; parsed and validated by the reference runtimes, executed by a hosting runtime
Execution Modes¶
| Mode | Backend | Reference runtimes | Use Case |
|---|---|---|---|
| Oneshot | Shell ([command]), HTTP ([http]) |
Executed | Single command/request, get result |
| Oneshot | MCP proxy ([mcp]) |
Parsed and validated; execute returns a delegation_preview envelope, no upstream call |
Govern a third-party MCP tool |
| Session | PTY (pseudo-terminal) | Parsed and validated only; execute is refused |
Interactive CLIs: psql, msfconsole, redis-cli, gdb |
| Browser | CDP (Chrome DevTools Protocol) | Parsed and validated only; execute is refused |
Headless or live browser automation |
All modes share a common governance layer: typed parameters, argument validation, policy gating, scope enforcement, output schema validation, evidence capture, and audit trail. Session and browser execution is provided by a hosting runtime such as Symbiont, not by the reference CLIs or libraries in this repository.
Quick Example¶
# tools/whois_lookup.clad.toml
[tool]
name = "whois_lookup"
version = "1.0.0"
binary = "whois"
description = "WHOIS domain/IP registration lookup"
timeout_seconds = 30
risk_tier = "low"
[tool.cedar]
resource = "PenTest::ScanTarget"
action = "execute_tool"
[args.target]
position = 1
required = true
type = "scope_target"
description = "Domain name or IP address to query"
[command]
exec = ["whois", "{target}"]
[output]
format = "text"
envelope = true
[output.schema]
type = "object"
[output.schema.properties.raw_output]
type = "string"
description = "Raw WHOIS registration data"
The agent fills typed parameters. The executor validates, constructs the argv, executes with timeout, and returns structured JSON. The agent never generates a shell command; the evidence envelope reports the declared command with placeholders intact, so executor-injected paths and expanded secrets never reach the agent (the human-facing toolclad test dry run shows the resolved argv).
Why ToolClad?¶
ToolClad inverts the security model of sandbox-based approaches:
| Sandbox (deny-list) | ToolClad (allow-list) | |
|---|---|---|
| Flow | LLM generates command → sandbox intercepts → allow/deny | LLM fills typed parameters → executor validates → constructs command from template |
| What the agent sees | A shell | Typed fields with constraints |
| Dangerous actions | Possible but intercepted (gaps exist) | Cannot be expressed (interface does not permit it) |
| Static analysis | Not possible | Inspect manifest to determine all possible invocations |
| Policy integration | Post-hoc | Cedar policies reference manifest-declared properties |
The dangerous action cannot be expressed because the interface does not permit it.
Reference Implementations¶
| Language | Directory | Package |
|---|---|---|
| Rust | rust/ |
crates.io/crates/toolclad |
| Python | python/ |
pypi.org/project/toolclad |
| JavaScript | js/ |
npmjs.com/package/toolclad |
| Go | go/ |
go install ./cmd/toolclad |
All four implementations parse the same .clad.toml format, validate arguments with the same type system, and produce interoperable evidence envelopes.
Documentation¶
| Guide | Description |
|---|---|
| Getting Started | Install, create, validate, and run your first manifest |
| Manifest Format | Complete .clad.toml reference for every section |
| Type System | All 15 built-in types with validation rules and examples |
| Command Construction | Templates, mappings, conditionals, array-based execution |
| HTTP and MCP Backends | HTTP API tools and governed MCP proxy passthrough |
| Session Mode | PTY session contract with per-interaction governance (parsed, not executed, by the reference runtimes) |
| Browser Mode | CDP browser session contract (parsed, not executed, by the reference runtimes) |
| Security Model | Value hygiene, spawn hardening, policy gate, scope enforcement, output caps |
| Output & Evidence | Parsers, fail-closed schema validation, evidence envelopes |
| CLI Reference | validate, run, test, schema and their flags |
| API Reference | Library entry points in Rust, Python, JavaScript, and Go |
| SchemaPin v1.4 Features | Sign with TTL, schema-version + previous-hash lineage, and _schemapin.{domain} DNS TXT cross-verification |