Release v0.5.2 — full feature parity, 14 types, security hardening

Version bump to 0.5.2 across Rust, Python, JS, Go, docs, and metadata.

Since v0.5.1:
- 14 built-in types (added msf_options, credential_file, duration, regex_match)
- Custom types via toolclad.toml with base type inheritance
- Real timeout enforcement with process group kill (Rust)
- Output parsers: json, jsonl, csv, xml, text (all 4 languages)
- HTTP body JSON-escaping to prevent request injection
- HTTP error semantics: 4xx client_error, 5xx server_error
- Platform-aware evidence directories (no hardcoded /tmp)
- Rich MCP schema generation with format/pattern/min/max constraints
- command section optional for HTTP/MCP-only manifests
- Full feature parity across Rust, Python, JavaScript, Go
- Scope validation aligned across all implementations
- String type rejects shell metacharacters by default
- Unknown arg types fail closed

Author: jaschadub

AGENTS.md

@@ -9,7 +9,7 @@
 |-------|-------|
 | Name | ToolClad |
 | Description | Declarative CLI tool interface contracts for agentic runtimes |
-| Version | 0.5.1 |
+| Version | 0.5.2 |
 | License | MIT (spec), Apache 2.0 (Symbiont integration) |
 | Repository | https://github.com/ThirdKeyAI/ToolClad |
 
@@ -18,7 +18,7 @@
 ToolClad provides:
 
 - **Manifest parsing** — Load and validate `.clad.toml` tool interface contracts (oneshot, session, browser modes)
-- **Argument validation** — 14 typed validators (10 core + 4 extended) with shell injection sanitization
+- **Argument validation** — 14 built-in type validators with shell injection sanitization, plus custom types via `toolclad.toml`
 - **Five execution backends** — Shell command, HTTP API, MCP proxy, PTY session, CDP/Playwright browser
 - **HTTP backend** — REST/GraphQL API tools with `{_secret:name}` template variable injection
 - **MCP proxy backend** — Governed passthrough to upstream MCP servers with field mapping

README.md

@@ -44,7 +44,7 @@ type = "object"
 type = "string"
 ```
 
-The agent fills typed parameters. The executor validates, constructs the command, executes with timeout, and returns structured JSON. The agent never sees or generates a shell command.
+The agent fills typed parameters. The executor validates, constructs the command, executes with timeout, and returns structured JSON. The agent never sees or generates a shell command. The `[command]` section is optional for HTTP-only or MCP-only manifests.
 
 ## Security Model
 
@@ -62,6 +62,9 @@ The dangerous action cannot be expressed because the interface doesn't permit it
 - **Process group isolation**: Tools spawned in new PGID; timeout kills entire process group (no zombies)
 - **Absolute path blocking**: `path` type rejects `/etc/shadow`, `C:\...` style paths
 - **Newline injection blocking**: `\n` and `\r` rejected in all string-based types
+- **HTTP body JSON-escaping**: Values interpolated into HTTP body templates are JSON-escaped to prevent injection
+- **Platform-aware evidence directories**: Evidence output uses platform-appropriate temp directories
+- **HTTP error semantics**: 4xx responses map to `client_error`, 5xx to `server_error` in evidence envelopes
 - **No eval**: Conditional evaluators use closed-vocabulary parsers, never dynamic code execution
 
 ## Packages
@@ -86,12 +89,12 @@ npm install toolclad           # JavaScript / npm
 Each implementation provides:
 
 - **Manifest parsing** -- load and validate `.clad.toml` files (oneshot, session, browser modes)
-- **14 type validators** -- 10 core + 4 extended, all with injection sanitization
+- **14 built-in type validators** -- all with injection sanitization, plus custom types via `toolclad.toml`
 - **Command construction** -- template interpolation with mappings, conditionals, defaults
-- **Execution** -- direct argv dispatch, process group kill on timeout, SHA-256 evidence hashing
+- **Execution** -- direct argv dispatch, real timeout enforcement with process group kill, SHA-256 evidence hashing
 - **Output parsers** -- builtin:json, builtin:xml, builtin:csv, builtin:jsonl, builtin:text, custom scripts
 - **Output schema validation** -- validates parsed results against `[output.schema]`
-- **MCP schema generation** -- auto-generate inputSchema + outputSchema for LLM tool use
+- **MCP schema generation** -- rich inputSchema + outputSchema with format/pattern constraints for LLM tool use
 - **Evidence envelopes** -- structured JSON with scan_id, timestamps, exit_code, stderr, output_hash
 - **CLI** -- `validate`, `run`, `schema`, `test` (dry run) subcommands
 

SKILL.md

@@ -2,7 +2,7 @@
 name: toolclad
 title: ToolClad
 description: Declarative tool interface contracts for agentic runtimes — oneshot CLI, interactive session (PTY), and browser (CDP/Playwright) modes with typed parameters, per-interaction Cedar gating, evidence envelopes
-version: 0.5.1
+version: 0.5.2
 ---
 
 # ToolClad Development Skills Guide
@@ -20,7 +20,7 @@ ToolClad is a declarative manifest format (`.clad.toml`) that defines the comple
 - **Browser**: Maintain a governed headless browser session where navigation, clicks, form submission, and JS execution are typed, scoped, and policy-gated via CDP/Playwright.
 
 All three modes share:
-- **Typed Parameters**: 10 built-in types with injection sanitization
+- **Typed Parameters**: 14 built-in types (10 core + 4 extended) with injection sanitization, plus custom types via `toolclad.toml`
 - **Per-Interaction Cedar Gating**: Every command/action evaluated against policies
 - **Evidence Envelopes**: Every execution wrapped in JSON with scan_id, timestamps, SHA-256 hash
 - **Scope Enforcement**: URL/target scope checking against allow-lists
@@ -108,6 +108,12 @@ description = "Tool output"
 | `path` | No traversal (`../`) | |
 | `ip_address` | Valid IPv4/IPv6 | |
 | `cidr` | Valid CIDR notation | |
+| `msf_options` | Semicolon-delimited `set KEY VALUE` | Metasploit options |
+| `credential_file` | Relative path + must exist | Username/password lists |
+| `duration` | Integer with suffix (`30`, `5m`, `2h`) | Timeout overrides |
+| `regex_match` | Matches declared `pattern` (required) | Module paths |
+
+Custom types can be defined in `toolclad.toml` at the project root with a `base` type and additional constraints.
 
 All types reject shell metacharacters (`;|&$\`(){}[]<>!`) by default.
 

TOOLCLAD_DESIGN_SPEC.md

@@ -1,6 +1,6 @@
 # ToolClad: Declarative Tool Interface Contracts for Agentic Runtimes
 
-**Version**: 0.5.1  
+**Version**: 0.5.2
 **Status**: Release Candidate  
 **Author**: Jascha Wanger / ThirdKey AI  
 **Date**: 2026-03-21  
@@ -1981,6 +1981,19 @@ The 80/20 split from symbi-redteam confirms this: ~14 of 19 tools are pure templ
 
 ## Changelog
 
+### v0.5.2 (2026-03-22)
+
+- HTTP body JSON-escaping for injection safety in body templates
+- Platform-aware evidence directories (OS-appropriate temp dirs)
+- HTTP error semantics: 4xx maps to `client_error`, 5xx to `server_error`
+- Real timeout enforcement with process group kill across all implementations
+- Rich MCP schema generation with format/pattern constraints
+- `[command]` section is now optional for HTTP-only and MCP-only manifests
+- Custom types via `toolclad.toml` with `load_custom_types` and `validate_arg_with_custom_types` APIs
+- Full feature parity across Rust, Python, JavaScript, and Go implementations
+- All 14 built-in types fully implemented (no stubs)
+- All 5 output parsers (json, jsonl, csv, xml, text) fully implemented
+
 ### v0.5.1 (2026-03-21)
 
 - Adopted CDP-direct as primary browser backend (direct WebSocket to Chrome debug port, persistent daemon per tab, no Puppeteer/Playwright overhead). Playwright remains as optional convenience layer.

docs/api-reference.md

@@ -60,6 +60,24 @@ 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_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.
+
+```rust
+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).
+
+```rust
+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`.

docs/index.md

@@ -4,7 +4,7 @@
 
 ToolClad is the tool execution layer of the [ThirdKey](https://thirdkey.ai) trust stack: [SchemaPin](https://schemapin.org) (tool integrity) / [AgentPin](https://agentpin.org) (agent identity) / **ToolClad** (tool contracts) / [Symbiont](https://symbiont.dev) (runtime).
 
-**Version**: 0.5.1 | **Status**: Release Candidate | **License**: MIT (spec), Apache 2.0 (Symbiont integration)
+**Version**: 0.5.2 | **Status**: Release Candidate | **License**: MIT (spec), Apache 2.0 (Symbiont integration)
 
 ---
 
@@ -21,7 +21,7 @@ A ToolClad manifest answers four questions:
 
 ## Key Features
 
-- **14 typed validators** -- 10 core + 4 extended types with shell injection sanitization on all string-based types
+- **14 built-in type validators** -- all with shell injection sanitization, plus custom types via `toolclad.toml`
 - **Five execution backends** -- Shell command, HTTP API, MCP proxy, PTY session, CDP browser
 - **Command templates** -- `{arg_name}` interpolation with mappings, conditionals, and defaults; no `sh -c`
 - **MCP schema generation** -- Auto-generate `inputSchema` + `outputSchema` from manifest declarations

docs/security-model.md

@@ -46,6 +46,24 @@ sh -c "nmap -sT -sV --max-rate 1000 10.0.1.0/24"
 
 Array-based execution means that even if a metacharacter somehow passed validation (it cannot, but defense in depth), the shell would never interpret it. There is no shell.
 
+## HTTP Body JSON-Escaping
+
+When values are interpolated into HTTP body templates (`[http].body_template`), they are JSON-escaped before substitution. This prevents injection attacks where an agent-supplied value could break out of a JSON string field and alter the structure of the request body. Quotes, backslashes, newlines, and control characters are all escaped.
+
+## Platform-Aware Evidence Directories
+
+Evidence output directories use platform-appropriate temporary directories (`/tmp` on Linux/macOS, `%TEMP%` on Windows) when no explicit `output_dir` is configured. This ensures evidence capture works correctly across operating systems without hardcoded paths.
+
+## HTTP Error Semantics
+
+HTTP backend responses are classified by status code:
+
+- **2xx**: `success` status in the evidence envelope
+- **4xx**: `client_error` status -- the request was malformed or unauthorized
+- **5xx**: `server_error` status -- the upstream service failed
+
+This classification gives LLM agents actionable error semantics for self-correction.
+
 ## Process Group Kill
 
 Tools are spawned in a new process group (PGID). When a timeout fires, the executor kills the entire process group, not just the top-level process. This prevents:

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolclad",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "description": "Declarative tool interface contracts for agentic runtimes — typed parameters, command templates, evidence envelopes, session and browser modes",
   "main": "src/index.js",

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "toolclad"
-version = "0.5.1"
+version = "0.5.2"
 description = "Declarative tool interface contracts for agentic runtimes — typed parameters, command templates, evidence envelopes, session and browser modes"
 readme = "README.md"
 requires-python = ">=3.9"