ToolClad — Declarative Tool Contracts¶
ToolClad provides declarative tool contracts for the Symbiont runtime. Define what a tool does, what arguments it accepts, and how it executes — in a single .clad.toml manifest. The runtime handles argument validation, scope enforcement, secret injection, Cedar policy generation, and evidence capture.
Upgrading from 1.x? Read the 2.0 migration guide before replacing manifests or Rust integrations.
Why ToolClad¶
External tools (nmap, curl, whois, custom scripts) are useful but dangerous. Passing raw arguments to shell commands creates injection risk. Trusting tool output without validation creates integrity risk. ToolClad solves this by putting a contract between the agent and the tool.
The contract defines: - What arguments the tool accepts — typed, validated, injection-checked - How the tool executes — shell command, HTTP API, MCP proxy, interactive session, or browser - What scope the tool operates in — target restrictions, domain allowlists - What policies govern it — Cedar authorization, human approval gates - What output the tool produces — format, schema validation, evidence envelope
Quick start¶
Create a tool manifest¶
This creates tools/my_tool.clad.toml with a starter template.
Validate and test¶
# Validate all manifests
symbi tools validate
# Validate a specific manifest
symbi tools validate tools/my_tool.clad.toml
# Dry-run with arguments (validates without executing)
symbi tools test my_tool --arg target=10.0.1.5
# View the MCP schema generated for a tool
symbi tools schema my_tool
# List all discovered tools
symbi tools list
Use in the runtime¶
Tools in the tools/ directory are automatically discovered and exposed to the reasoning loop as MCP-compatible tool definitions. Agents can call them like any other tool — the runtime handles validation, execution, and evidence capture.
Manifest format¶
A .clad.toml file has up to 9 sections. The format follows the ToolClad
reference specification, plus Symbiont extensions ([source], [filesystem],
feeds_decision, finalize, [browser.network], [session] sentinel_command,
and the literal_text / agent_summary types).
Loading is strict. A manifest is a security contract, so an unknown key
anywhere (tiemout_seconds, block_internal_typo) is a load error, as is any
control Symbiont cannot enforce. When one manifest in tools/ fails to load,
the whole tool set fails: symbi up and symbi tools list exit with the
error, and a reasoning run refuses to start, instead of silently running
without that tool. toolclad.toml custom types are strict in the same way.
[tool] — Metadata¶
[tool]
name = "nmap_scan"
version = "1.0.0"
binary = "nmap" # argv[0]'s basename must match
description = "Network port scanner"
mode = "oneshot" # oneshot | session | browser
timeout_seconds = 60 # must be greater than zero (default 30)
risk_tier = "medium" # info | low | medium | high | critical
human_approval = false # require operator approval before execution
network_egress = true # the tool dials destinations from its arguments
allow_interpreter = false # permit sh/python/env/... as argv[0]
[tool.cedar]
resource = "Tool::NmapScan"
action = "execute_tool"
[tool.evidence]
output_dir = "{evidence_dir}/{scan_id}-nmap"
capture = true
hash = "sha256"
[tool.limits] # applied to the selected sandbox boundary
nproc = 64
nofile = 256
fsize_bytes = 10485760
address_space_bytes = 536870912
cpu_seconds = 120
risk_tier = "high"or"critical"(on the manifest or on a session or browser command) requires an exact-call human approval, likehuman_approval = true.- An interpreter as
argv[0](sh,bash,python,node,env,xargs, ...) turns an argument into code and is refused unlessallow_interpreter = true. [tool.limits]tightens the selected tier (Docker/gVisor: PIDs, open files, file size, memory, lifetime; Landlock: PIDs, memory, lifetime; Firecracker: memory, lifetime). A limit the tier cannot express refuses the call rather than running without it.dispatchis accepted only as"exec".
[args.*] — Argument definitions¶
Each argument has a type, validation rules, and metadata:
[args.target]
position = 1
type = "scope_target" # validated against project scope
required = true
description = "Target IP, CIDR, or hostname"
scope_check = true # enforce scope boundaries
[args.scan_type]
position = 2
type = "enum"
allowed = ["quick", "full", "stealth", "ping"]
default = "quick"
description = "Scan profile"
[args.max_rate]
position = 3
type = "integer"
min = 1
max = 10000
default = "1000"
description = "Maximum packets per second"
Built-in argument types:
| Type | Validation |
|---|---|
string |
Non-empty, string hygiene (below), shell-metacharacter blocklist, optional anchored pattern |
integer |
Plain decimal i64 with optional min/max/clamp; a negative result needs allow_leading_dash |
number |
Decimal float with optional min_float/max_float/clamp; NaN and infinity refused |
port |
1–65535 |
boolean |
"true" or "false" |
enum |
Must match one of the allowed values |
scope_target |
Canonical IP, CIDR, or ASCII hostname (no wildcards, punycode, traversal, non-canonical IP encodings such as 2130706433 or 127.1); egress policy applies; always checked against the project scope |
url |
Scheme allowlist (default http/https; file, gopher, data, javascript, ... are always refused), no userinfo, no backslash or whitespace, host through the egress policy, and the WHATWG parse must agree with the lexical host and re-serialize to the same string. The canonical URL is what reaches argv |
path |
Relative path; rejects absolute/rooted paths and .. components; preserves the validated spelling |
ip_address |
Canonical IPv4 or IPv6; egress policy applies |
cidr |
Canonical CIDR; the whole range is tested against the egress policy |
credential_file |
Relative path that must name an existing regular file on the controller |
msf_options |
One set KEY VALUE (Symbiont refuses ; chaining) |
duration |
Seconds, or h/m/s/ms components (1h30m), normalized to whole seconds |
literal_text |
Explicit bounded UTF-8 content (32 KiB), preserving whitespace and metacharacters; rejects NUL. Use with a pre-tokenized argv contract. An interpreter such as sh -c deliberately treats it as code and requires allow_interpreter, the appropriate policy, sandbox and approval. |
regex_match |
Must match the anchored pattern |
agent_summary |
Free text bound for a downstream agent's prompt — strips invisible Unicode and renderer-hidden markup, rejects known injection markers. Best-effort defense-in-depth, not a load-bearing control (see Typed + grounded decisions) |
String hygiene. "Valid according to the type" means "safe as exactly one
argv entry". Every string-derived type (string, path, credential_file,
regex_match, url, scope_target, duration, msf_options) refuses,
before any type-specific parsing and with nothing trimmed away:
| Rule | Refused | Opt-out |
|---|---|---|
| NUL | \0, for every type |
none |
| Control characters | U+0000–U+001F, U+007F–U+009F | none |
| Quotes and backslash | ' " \ |
none |
| Whitespace | any whitespace | allow_whitespace = true admits U+0020 only, and only with the exec command form (never for url) |
| Leading dash | a value starting with - or + |
allow_leading_dash = true |
The shell-metacharacter blocklist (; | & $ ` ( ) { }
[ ] < > !) stays on top as defense in depth. pattern is anchored:
[a-z]+ is compiled as ^(?:[a-z]+)$, a whole-value match. The explicit
literal_text type is exempt and preserves its content as data.
Egress policy. For scope_target, url, ip_address and cidr:
- always refused: link-local and cloud metadata (
169.254.0.0/16,fe80::/10, their IPv4-mapped forms) and the internal-name set (localhost,*.localhost,*.local,*.internal,*.home.arpa,*.lan,*.intranet,*.corp,*.private,metadata.google.internal); - refused with
block_internal = true: loopback, RFC 1918, CGNAT, unspecified, broadcast, documentation, benchmarking and reserved ranges, IPv6 equivalents, any address Symbiont's HTTP guard treats as non-public, IP literals embedded in a hostname (127.0.0.1.nip.io,10-0-0-1.nip.io), any CIDR that overlaps a blocked range (8.0.0.0/5contains10.0.0.0/8), and a hostname unless every A/AAAA answer is public (resolution failure is a refusal).
A tool is an egress tool when it sets network_egress = true, uses [http]
or [browser], or runs a known network binary (curl, wget, nmap, nc,
masscan, ssh, nikto, hydra, ffuf, ..., plus dig and whois). In an
egress tool every network-target argument must set block_internal = true,
and a custom type cannot stand in for one; otherwise the manifest does not load.
Path validation is lexical and portable. It does not canonicalize against the
controller filesystem: a relative path remains relative to the selected
worker's working directory. Ordinary dotted filenames such as report..csv
remain valid. For intentional absolute argv data, declare literal_text
explicitly and apply the appropriate policy and sandbox restrictions.
credential_file adds a controller-side regular-file preflight and preserves the
relative argument. It follows filesystem links and does not prove that a file
exists or is confined in the worker. Mounts, working directory and the selected
sandbox define the worker's filesystem authority; path syntax alone does not
prevent a tool from following symlinks within that authority.
Optional argument flags:
| Flag | Meaning |
|---|---|
scope_check = true |
Validate the value against the project scope (scope_target, url, ip_address, cidr only; scope_target is always scope-checked) |
block_internal = true |
Refuse non-public targets (see the egress policy) |
allow_leading_dash = true |
Permit a value starting with - or + |
allow_whitespace = true |
Permit U+0020 inside the value (exec form only) |
schemes = [...] |
url scheme allowlist |
sanitize = ["injection"] |
Accepted for compatibility; the blocklist always applies to string-derived types |
feeds_decision = true |
This argument's value feeds a privileged downstream decision (routing, escalation, authorization). Free-text types (string, literal_text, agent_summary, regex_match) marked this way are flagged as an anti-pattern by ToolClad manifest validation — use an enum plus Cedar grounding instead (see Typed + grounded decisions) |
allowed is honored only on enum; on any other type it is a load error.
Custom types can be defined in a project-level toolclad.toml. Accepted
keys are base, allowed, pattern, min, max, min_float, max_float,
clamp, schemes, scope_check and description; a custom type may not
shadow a built-in type:
[types.service_protocol]
base = "enum"
allowed = ["ssh", "ftp", "http"]
description = "Network service protocol"
[command] — Command construction¶
The argv array is the only form that reaches a process. Declare it with exec:
[command]
exec = [
"nmap",
"{_scan_type_flags}",
"--max-rate", "{max_rate}",
"-oX", "-",
"{target}",
]
end_of_options = "--" # optional; inserted before the first agent value
[command.defaults]
max_rate = 1000
[command.mappings.scan_type]
quick = "-sV --top-ports 100"
full = "-sV -sC -p-"
stealth = "-sS -T2"
ping = "-sn -PE"
[command.conditionals.verbose_flags]
when = "verbose != ''"
template = "-v {verbose}"
- Each
execelement is one argv entry. An argument placeholder ({target}) resolves to exactly one entry and is never re-split, so a value with spaces or quotes cannot add arguments. {_<arg>_flags}(from[command.mappings.<arg>]) and{_<cond>}(from[command.conditionals.<cond>]) are manifest text and may expand to zero or more entries; they must stand alone as a whole element. No other spelling (such as{_scan_flags}) is recognized. A mapping over anenummust cover every allowed value (map a value to""for no flags).{{and}}are literal braces ("-w", "%{{http_code}}"). Any other brace, and any placeholder that names nothing the manifest declares, is a load error.{_scan_id}is injected (128 bits of entropy). ToolClad's host-path variables{_output_file}and{_evidence_dir}are refused: tools run inside an isolated boundary, so write results to stdout, which is captured.end_of_options = "--"is the only accepted value.template = "..."is deprecated. It is tokenized at load, before any value exists; a placeholder inside quotes (-H '{headers}') is refused, andallow_whitespaceis not honored for it.- Divergence from the reference, kept because it is stricter: an empty
optional argument keeps its (empty) argv slot instead of being dropped, so
-H {headers} {url}can never turn into-H <url>. Omit optional syntax with a conditional instead.
symbi tools test <name> --arg k=v validates exactly as the executor does and
prints the argv that will run, element by element.
[output] — Output configuration¶
[output]
format = "xml" # json | xml | csv | jsonl | text
parser = "builtin:xml" # builtin:* or custom:<absolute path> (operator allowlist)
envelope = true # wrap in evidence envelope
max_bytes = 8388608 # per-stream capture cap (default 8 MiB, at most 1 GiB)
[output.schema]
type = "object"
properties.hosts.type = "array"
Schema validation is fail-closed: a violation replaces results with
{"schema_error": "<pointer>: <message>", "raw_output": ...} and sets the
envelope status to schema_error. The bundled validator supports type,
properties, required, items, additionalProperties (boolean), enum,
minimum, maximum, minLength, maxLength and pattern (anchored).
Output beyond max_bytes is truncated and flagged with
"output_truncated": true. XML containing <!DOCTYPE or <!ENTITY is
refused. A parser that is neither builtin:* nor custom:<absolute path> is
a load error; custom parsers run only when listed in
SYMBIONT_TOOLCLAD_ALLOWED_PARSERS and inside the command boundary.
Execution modes¶
Oneshot (default)¶
Single execution with a fixed timeout. Three backend options:
Shell backend — build and execute a command:
HTTP backend — make an HTTP request:
[tool]
mode = "oneshot"
[http]
method = "GET"
url = "https://api.example.com/lookup?q={target}"
headers = { Authorization = "Bearer {_secret:api_key}" }
success_status = [200]
The scheme and host of http.url are literal manifest text; a placeholder in
either is a load error. Argument values are percent-encoded into the path and
query, JSON-escaped into body_template, and a header value containing CR, LF
or NUL after interpolation is refused. With a project scope, the resolved URL
must be in scope. HTTP requests also include SSRF protection — private IP
ranges, localhost, and cloud metadata endpoints are blocked.
MCP proxy backend — governed passthrough to an upstream MCP tool:
[tool]
mode = "oneshot"
[mcp]
server = "upstream_server"
tool = "raw_tool_name"
[mcp.field_map]
target = "host"
scan_type = "mode"
Session (interactive CLI)¶
Spawns a real pseudo-terminal inside the selected Docker/gVisor container and maintains state across commands in one governed run. Requires toolclad-session, enabled in the default CLI. See terminal boundaries and SDK lifecycle for image requirements, limits and cleanup.
[tool]
mode = "session"
binary = "msfconsole"
[session]
startup_command = "msfconsole -q"
ready_pattern = "msf6\\s*>"
startup_timeout_seconds = 30
idle_timeout_seconds = 300
max_interactions = 50
[session.commands.run]
pattern = "help"
description = "Show command help"
risk_tier = "low"
human_approval = false
Each declared command becomes a separate MCP tool definition (e.g., msfconsole.run).
Session input rules (ToolClad S1–S3), applied identically on every path:
- The input is one line: C0 controls (tab, CR and LF included), DEL, C1
controls and U+2028/U+2029 are refused; the executor appends the only line
terminator. The command
patternmust match the whole input. - Sink policies, inferred from the startup binary and extendable with
[session.interaction] input_sanitize:psql_meta(psql sessions; no backslash, so\gexec,\c,\copy,\lo_import,\oand\!cannot be expressed),msf_meta(msfconsole sessions; no;chaining and noirb,pry,load,resource,makerc,edit,spool,save,cd, shell verbs or!), andinjection(the shell-metacharacter blocklist, opt-in only, so SQL such ascount(*)ora != bis not refused by default). msfconsole passes unknown verbs to the system shell, so pin the verb in each command'spattern. - In a session whose binary can name a network destination (
msfconsoleand the egress binaries), every command must setextract_target = truewith a(?P<target>...)group, which is checked against the project scope, or require human approval. - The session sandbox has no network unless
[tool] network_egress = true. - The prompt is detected with a fresh 128-bit sentinel per interaction: the
executor sends
sentinel_command(psql defaults to\echo {sentinel}) after the input, and acceptsready_patternonly at the start of the final line after the sentinel line, so prompt-shaped tool output cannot frame a response. Without a sentinel command the prompt must be the final, unterminated line (prompt_anchor: "end_of_output"). - Terminal output is stripped of CSI, OSC, DCS/SOS/PM/APC strings and every other C0/C1 control except newline and tab.
[session.child_detection]is refused: a child session is never registered from tool output (S7).
Browser (CDP)¶
Status: not yet executable. Browser (
mode = "browser") tools are parsed, argument-validated, and scope-checked, but Chrome DevTools Protocol execution is not implemented yet. It is gated behind thetoolclad-browsercargo feature, whose real backend is still pending — until then a browser command returns an honest error, never a fabricated result. Private transport fixtures can drive contained Chromium, but they do not enable the public browser executor.
The manifest describes the intended Chrome DevTools Protocol interface.
Neither connect = "launch" nor live attachment starts a browser today.
[tool]
mode = "browser"
[browser]
engine = "cdp"
headless = true
connect = "launch"
extract_mode = "accessibility_tree"
[browser.scope]
allowed_domains = ["example.com", "*.test.example.com"]
blocked_domains = ["admin.example.com"]
allow_external = false
[browser.network]
allowed_methods = ["GET", "HEAD"]
private_origins = []
[browser.commands.navigate]
description = "Navigate to URL"
Planned browser commands: navigate, snapshot, click, type_text, submit_form, extract, screenshot, execute_js, wait_for, go_back, list_tabs, network_timing.
Scope enforcement¶
ToolClad enforces target scope to prevent agents from operating outside authorized boundaries.
Project scope¶
Define allowed targets in scope/scope.toml:
[scope]
targets = ["10.0.1.0/24", "192.168.1.0/24"]
domains = ["example.com", "*.test.example.com"]
exclude = ["10.0.1.1"]
Every scope_target argument, and every argument with scope_check = true,
is validated against this scope; with no scope file the call is refused. The
whole requested range must fit an allowed rule and avoid every exclusion. An
allow rule *.example.com matches strict subdomains only — not the apex
example.com and not evil-example.com; an exclusion *.example.com also
covers the apex. URLs are scope-checked with the same strict parser the url
type uses, so a backslash or userinfo cannot give the scope check one host and
the tool another.
The ToolClad reference keys are accepted too and merge into the rules above:
[scope]
allowed_domains = ["example.com", "*.example.com"]
allowed_cidrs = ["10.0.1.0/24"]
blocked_domains = ["admin.example.com"]
blocked_cidrs = ["10.0.1.1/32"]
URL scope (browser mode)¶
Navigation requires [browser.scope] and an HTTP(S) URL without embedded
credentials. Domain comparisons use canonical hostnames, including case,
internationalized names, encoded host characters and a final DNS dot. Blocked
rules take precedence; *.example.com matches the base domain and its
subdomains. Malformed rules fail closed, including when allow_external = true.
At most 256 domain rules and an 8 KiB URL are accepted. Control characters,
backslashes and ambiguous URL forms are rejected.
Prepared navigation binds the normalized URL before policy, approval and audit.
Its prepared context also includes the effective [browser.network] settings;
the manifest digest binds these capabilities through authorization. GET and HEAD
are the default methods. Other supported methods (POST, PUT, PATCH, DELETE and
OPTIONS) require explicit inclusion; CONNECT and TRACE are refused.
Domain scope does not grant access to private addresses. An operator can grant an
exact literal origin, such as private_origins = ["http://127.0.0.1:8080"], and
also include its address in allowed_domains. The scheme, address and effective
port must match. The exception accepts loopback, RFC1918 and IPv6 unique-local
addresses, excluding the AWS IPv6 metadata endpoint. DNS names, link-local,
multicast, unspecified and mapped IPv6 addresses cannot use it. A redirect to
another port or origin needs its own grant. Blocked domain rules still win.
The reusable browser_network::BrowserNetworkPolicy builds scoped requests from
CDP interception events. It removes authority/framing and hop-by-hop headers,
requires complete bounded request bodies, and refuses multipart/file uploads.
Requests are limited to 2 MiB of application data, responses to 4 MiB, and headers
to 128 entries / 64 KiB. The broker client uses DNS filtering, no ambient proxy,
no redirect following and no automatic content decompression. Responses preserve
duplicate cookies and binary header values for CDP fulfillment. Chromium receives
redirect responses and each resulting request must be checked again.
These request-construction helpers do not issue execution authority. A trusted driver must retain the worker, mediate every target and use the call-bound journal before sending each unchanged request. The public browser route stays unavailable while that production driver and browser lifetime ownership are integrated. The contained Chromium transport fixtures include a real local HTTP case with pre-connection signed audit, an exact POST effect, denied method/subresource/redirect destinations and worker removal. This is component integration evidence, not a shipping browser-command E2E.
SSRF protection (HTTP backend)¶
HTTP backend requests automatically block:
- Localhost (127.0.0.1, ::1, localhost)
- Cloud metadata (169.254.169.254, metadata.google.internal)
- Shared address space (100.64.0.0/10), including 100.100.100.200, in both URL checks and DNS answers
- Private IP ranges (RFC 1918, link-local, broadcast)
- Non-HTTP/HTTPS schemes
HTTP exchange uses asynchronous I/O, a bounded request and response body, and the remaining call deadline. Automatic redirects and ambient proxies stay disabled. Preparation resolves the method and canonical destination before policy and approval, including path segments that the HTTP client would normalize. URL userinfo credentials are rejected; use explicit headers. URLs are limited to 8 KiB without control characters. Governed calls record the built request before connecting and record the actual response or incomplete outcome through their existing protected journal. See request audit records. No new approval or UI control is required.
Secret injection¶
Legacy HTTP manifests can inject secrets into trusted headers and body templates
using {_secret:NAME}. Secret placeholders in URLs are rejected:
[http]
url = "https://cases.example.com/records/{record}"
[http.headers]
authorization = "Bearer {_secret:case_service}"
The runtime resolves {_secret:case_service} from TOOLCLAD_SECRET_CASE_SERVICE.
Missing secrets produce an error before execution. The optional
outbound capability profile replaces these templates
with an explicit credential source and a named operation bound to the current
execution. It does not change legacy manifests until the operator opts in.
Cedar policy generation¶
ToolClad auto-generates Cedar policies from manifest metadata:
Each generated policy permits the manifest's action when
resource.base_tool names the manifest, which every session and browser
sub-command shares (their per-call tool_name is <manifest>.<command>). The
prepared resource also carries the call's effective risk_tier (the manifest
tier raised to a sub-command's own tier). Forbids carry the approval rules:
permit (principal, action == Tool::Exploit::Action::"execute_tool", resource)
when { resource has base_tool && resource.base_tool == "exploit" };
forbid (principal, action == Tool::Exploit::Action::"execute_tool", resource)
when { resource has base_tool && resource.base_tool == "exploit" &&
resource has risk_tier && (resource.risk_tier == "high" || resource.risk_tier == "critical") }
unless { context has has_human_approval && context.has_human_approval == true };
A manifest with human_approval = true gets an additional forbid without the
tier condition. Independently of Cedar, a high or critical call requires an
exact-call approval before dispatch.
Evidence envelope¶
All tool executions are wrapped in a structured evidence envelope:
{
"status": "success",
"scan_id": "1712073600-9f1c2e7a4b6d8e0f1a2b3c4d5e6f7a8b",
"tool": "nmap_scan",
"command": "nmap -sV --top-ports 100 --max-rate 1000 -oX - 10.0.1.5",
"duration_ms": 4523,
"timestamp": "2026-04-02T18:00:00Z",
"output_hash": "sha256:a1b2c3...",
"output_truncated": false,
"exit_code": 0,
"stderr": "",
"output_file": "/var/lib/symbiont/evidence/1712073600-9f1c...-nmap/output",
"results": { "hosts": [...] }
}
status is success, error, or schema_error. With [tool.evidence]
capture = true, the captured output is also written to output_file under the
evidence root (TOOLCLAD_EVIDENCE_DIR, or symbiont-evidence-<uid> in the
system temp directory). The root and each per-call directory are created mode
0700 and the root is refused if it is a symlink, foreign-owned, or group/other
accessible; the file is created with O_CREAT | O_EXCL | O_NOFOLLOW, mode 0600.
output_dir may use only {evidence_dir} and {scan_id} and must stay below
the root.
HTTP backend envelopes include http_method, http_url, http_status. MCP proxy envelopes include mcp_server, mcp_tool. Session envelopes include session_id, interaction_count, prompt_anchor, and a transcript with timestamps.
Hot-reload (development)¶
In development mode, ToolClad watches the tools/ directory for changes:
- New
.clad.tomlfiles are discovered automatically - Modified manifests are reloaded on save
- Deleted manifests are removed from the registry
- Parse errors produce warnings without crashing the runtime; the previous version of the manifest stays in effect
The executor also checks manifest version at execution time — if a manifest was reloaded between planning and execution, the call is rejected to prevent plan drift.
Built-in manifests¶
Symbiont ships these manifests in tools/:
| Manifest | Description | Mode | Loads in ToolClad's reference CLI |
|---|---|---|---|
whois_lookup.clad.toml |
WHOIS domain/IP lookup | Oneshot (shell) | Yes |
dig_lookup.clad.toml |
DNS record lookup | Oneshot (shell) | Yes |
curl_fetch.clad.toml |
HTTP request with scope and egress policy | Oneshot (shell) | Yes |
nmap_scan.clad.toml |
Network port scanner with evidence capture | Oneshot (shell) | Yes |
submit_triage.clad.toml |
Typed + grounded triage decision (reference) | Reference (typed decision) | No (feeds_decision) |
read_file, list_files, grep_files, git_* |
Fixed source-broker queries | Oneshot (source) | No ([source]) |
These serve as reference implementations for writing your own manifests.
Typed + grounded decisions¶
When one agent's output drives a privileged downstream decision — routing, escalation, or tool authorization — that decision must not be made over the upstream agent's free text. A free-text "summary" spliced into a downstream prompt is an injection surface: a held-out red-team evaluation showed the agent_summary marker fence reduces orchestrator-injection escape only from ~28% to ~26% (it does not generalize to novel paraphrases), while moving the decision onto typed fields grounded in trusted context reaches 0%.
The pattern that holds:
- Type the decision. The upstream agent emits an
enum-constrained decision (e.g.category,severity), never a free-text instruction. Enum validation makes paraphrase injection structurally inert — there is no instruction channel. - Ground it in trusted context. Derive the authoritative facts from trusted input (e.g. severity inferred from the ticket the system received, not from the agent's self-report), and make the decision a Cedar policy over that trusted context. The lower-trust agent's output is advisory, not authoritative.
- Keep
agent_summaryas defense-in-depth only. It still strips invisible Unicode / hidden markup and logs injection-shaped attempts, but it is never the load-bearing control for a privileged decision.
Mark any argument that feeds such a decision with feeds_decision = true. ToolClad manifest validation flags free-text decision inputs (string, literal_text, agent_summary, regex_match) as an anti-pattern, steering authors to an enum plus Cedar grounding.
Reference implementation:
tools/submit_triage.clad.toml— typedcategory/severityenums (feeds_decision = true), advisory-onlyrationaleexamples/policies/triage_routing.cedar— grounded escalation policy (permit … when { context.ticket_severity == "critical" })crates/runtime/src/toolclad/decision.rs— the Rust derives-facts / Cedar-decides reference (route_grounded,decide_route)
Integration with the reasoning loop¶
ToolClad tools are exposed to the reasoning loop as MCP-compatible tool definitions. The flow:
- Discovery — manifests in
tools/are loaded at startup - Schema generation — each tool (or session/browser command) becomes a ToolDefinition with JSON Schema
- Tool profile filtering — the ORGA loop's tool curator filters available tools based on glob patterns, max count, and
require_verifiedflags - Proposal — the LLM proposes a tool call with arguments
- Policy gate — Cedar policy evaluates whether the call is allowed
- Validation — ToolClad validates arguments against the manifest (types, ranges, scope, injection checks)
- Execution — the runtime executes via the appropriate backend (shell argv, HTTP, MCP proxy, session, browser). Only a call carrying an authorization grant from the governed dispatcher executes; a raw proposal handed to
ToolCladExecutor::execute_actionsis refused - Evidence — output is parsed, schema-validated, and wrapped in an evidence envelope
- Observation — the result is returned to the reasoning loop as an Observation
The policy gate and argument validation happen before execution. A failed policy check or invalid argument blocks the tool call entirely.
Which surfaces execute tools¶
Not every entry point runs ToolClad tools. Knowing which do is the difference between a policy that governs real execution and one that governs nothing:
| Surface | Executes ToolClad/MCP tools | Notes |
|---|---|---|
symbi run <agent> |
Yes | Loads tools/ at startup |
| DSL reasoning builtins | Yes | Same loader, invoked from .symbi programs |
symbi tools test |
No | Dry run: validates arguments and prints the argv |
| HTTP input server | Yes, when tools/ exists and holds at least one manifest |
Otherwise starts with no executor and every tool call is refused |
symbi up chat coordinator |
No | Has no ToolClad executor at all |
symbi shell (ORCH) |
No | Ships its own fixed tool set — read_file, search, edit_file, save_artifact — which are not ToolClad manifests |
The chat coordinator is deliberately monitoring-only: it answers questions about a running fleet and cannot act on it. A Cedar permit for tool_call::<name> has no effect there, because no tool call is ever proposed.
This matters when writing policy. Policies sitting flat in policies/*.cedar are loaded by every surface's gate. A permit written for symbi run reaches the coordinator's gate too — harmless while the coordinator executes nothing, but it becomes a real grant the moment a surface gains an executor. Put surface-specific grants in policies/<surface>/ instead, which only the named surface reads. The surface names are run, coordinator, http-input, managed-cli, eval, and shell.
If you want the coordinator to execute tools later, scope it per tool rather than switching it on globally — otherwise every permit already written for another surface applies to chat on day one.