{
"name": "ct",
"description": "Umbrella launcher for the coding_tools suite. `ct <command> [args...]` runs the matching ct-<command> binary git-style, so `ct search` runs ct-search, `ct test` runs ct-test, `ct each` runs ct-each, `ct outline` runs ct-outline, `ct rules` runs ct-rules, `ct check` runs ct-check, `ct deps` runs ct-deps, and `ct await` runs ct-await; any other ct-* tool installed beside ct or on PATH is reachable too. ct passes the child's stdout, stderr, and exit status through unchanged (0 success, 1 clean negative, 2 usage or runtime error). This definition also carries every suite tool's full tool-use definition under `tools`, so an agent can hoist them all in one call; for a single tool use `ct <command> --explain json` (e.g. `ct search --explain json`), and `ct --explain md` documents the suite for humans.",
"input_schema": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "Subcommand to run; resolves to the ct-<command> binary. Built-in: search (ct-search), view (ct-view), tree (ct-tree), edit (ct-edit), patch (ct-patch), test (ct-test), each (ct-each), outline (ct-outline), rules (ct-rules), check (ct-check), deps (ct-deps), await (ct-await). Any other ct-* tool on PATH also works.",
"enum": [
"search",
"view",
"tree",
"edit",
"patch",
"test",
"each",
"outline",
"rules",
"check",
"deps",
"await"
]
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arguments passed through verbatim to ct-<command> (e.g. [\"--name\", \"*.rs\", \"--grep\", \"TODO\"])."
}
},
"required": [
"command"
]
},
"tools": [
{
"name": "ct-search",
"description": "Recursively find files by name, type, size, and content from a chosen root, replacing find|xargs|grep pipelines. An entry matches only when all supplied predicates hold. A search can also be posed as a pass/fail test: --question frames it, --expect sets an expectation over the match count, and --emit prints a templated verdict. The exit status follows the verdict = --expect applied to the count: 0 SUCCESS, 1 ERROR, 2 usage/runtime error; the default expectation 'any' makes this 0 if anything matched and 1 if not. Pattern arguments use substring->glob->regex promotion: text with no metacharacters is a literal substring; glob metacharacters (* ? [ ]) that are not a valid regex are treated as a glob; otherwise the pattern is used as a regex. --mode literal|glob|regex pins the interpretation (promotion off) for every pattern in the invocation. --grep accepts payload schemes: file:PATH reads the pattern verbatim from a file (literal by default), text:VALUE escapes the prefix; a multi-line pattern matches as a line-anchored literal BLOCK (K lines match K consecutive source lines byte-for-byte; each occurrence counts at its start line; under --detail a block with no match reports its nearest miss to stderr). Invoke as `ct search ...` or `ct-search ...`.",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Search root, relative or absolute, independent of the current working directory.",
"default": "."
},
"name": {
"type": "string",
"description": "File-name pattern. '|'-separated alternatives, each substring->glob->regex promoted and anchored to the whole name (e.g. '*.java|*.kt')."
},
"type": {
"type": "array",
"items": {
"type": "string",
"enum": [
"f",
"d",
"l"
]
},
"description": "Restrict to entry kinds: f=regular file, d=directory, l=symlink. May be repeated or comma-joined."
},
"grep": {
"type": "string",
"description": "Content pattern, substring->glob->regex promoted and searched unanchored against file contents. Implies regular files. Accepts file:PATH / text:VALUE payloads; a multi-line payload matches as a line-anchored literal block."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how patterns are interpreted; promotion off for every pattern in the invocation. Use literal for verbatim code anchors."
},
"size": {
"type": "string",
"description": "Size predicate [+|-]N[k|m|g]: +N larger than, -N smaller than, N at least N. Applies to regular files."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries (names starting with '.'). Default: skipped."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"limit": {
"type": "integer",
"description": "Stop after this many matches."
},
"question": {
"type": "string",
"description": "Question this search answers, framing it as a test; printed as a '== ... ==' banner unless quiet."
},
"expect": {
"type": "string",
"description": "Verdict expectation over the match count; default 'any'. One of: any (>=1), none (==0), N (>=N), =N (==N), +N (>N), -N (<N). 'none' inverts a search into a negative assertion that passes when nothing matches."
},
"emit": {
"type": "string",
"description": "Template written to stdout after the search (alias: emit-stdout). Tokens: {RESULT} {QUESTION} {COUNT} {LINES} {BASE} {MATCHES}."
},
"emit-stderr": {
"type": "string",
"description": "Template written to stderr after the search. Same tokens as emit."
},
"list": {
"type": "boolean",
"description": "Output mode: print one matching path per line. This is the default mode."
},
"summary": {
"type": "boolean",
"description": "Output mode: print counts only. Mutually exclusive with the other output modes."
},
"detail": {
"type": "boolean",
"description": "Output mode: print matches plus, for --grep, each hit as path:line:text. Mutually exclusive with the other output modes."
},
"quiet": {
"type": "boolean",
"description": "Output mode: print no per-match output and no --question banner; report via exit status (and --emit, which still fires). Mutually exclusive with the other output modes."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 (and a one-line message) if the search exceeds SECS seconds (fractional allowed)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-view",
"description": "Show one file's lines by range, or the regions around a pattern with context, instead of dumping the whole file. --range A:B (1-based inclusive; also A:, :B, A) prints a span; --match PATTERN prints the windows around matching lines with --context lines on each side (overlapping windows merge, like grep -C). Read-only, no allow-gate. With --json, emits {tool, path, total_lines, shown, lines:[{n,text}], matched?}. Exit status: 0 shown, 1 if --match matched nothing, 2 on a read or usage error. --match uses substring->glob->regex promotion, searched unanchored per line; --mode literal|glob|regex pins the interpretation (promotion off). --match accepts payload schemes: file:PATH reads the pattern verbatim from a file (literal by default), text:VALUE escapes the prefix; a multi-line pattern matches as a line-anchored literal BLOCK (context expands around the whole matched region; a block with no match reports its nearest miss to stderr). Invoke as `ct view ...` or `ct-view ...`.",
"input_schema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The file to view (positional, required)."
},
"range": {
"type": "string",
"description": "Line range A:B (1-based, inclusive); also A: (to end), :B (from start), or A (one line)."
},
"match": {
"type": "string",
"description": "Show only lines matching this pattern (substring->glob->regex promoted, searched unanchored), with --context lines around each hit. Accepts file:PATH / text:VALUE payloads; a multi-line payload matches as a line-anchored literal block."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how the --match pattern is interpreted; promotion off. Use literal for verbatim code anchors."
},
"context": {
"type": "integer",
"description": "Lines of context shown around each --match hit. Default: 2.",
"default": 2
},
"limit": {
"type": "integer",
"description": "Cap the number of lines emitted."
},
"plain": {
"type": "boolean",
"description": "Suppress the line-number gutter in text output."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result instead of text."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 (and a one-line message) if the view exceeds SECS seconds (fractional allowed)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": [
"path"
]
}
},
{
"name": "ct-tree",
"description": "Walk a directory for chosen file types and report the effective file tree with per-file line, word, and character counts. Select files with --base/--name/--ext (--ext is a comma list of extensions added to --name as alternatives), filter with metric predicates (--min-lines/--max-lines/--min-words/--max-words/--min-chars/--max-chars) and per-folder predicates (--min-files-per-folder/--max-files-per-folder, counting matching files in a file's immediate directory), sort by path|name|lines|words|chars|ext (--desc for descending), and choose a summarisation level: --tree (indented tree with per-file counts and per-folder subtotals; default), --flat (one file per line: lines words chars path; best for ranked lists), or --summary (aggregates grouped by --group ext|dir|none). --json emits {tool, base, files:[{path,ext,lines,words,chars}], by_ext, totals}. Exit: 0 if any file is in the report, 1 if none, 2 on error. Read-only. Invoke as `ct tree ...` or `ct-tree ...`. Example: all *.rs files over 5000 lines sorted by line count descending = --ext rs --min-lines 5001 --flat --sort lines --desc.",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Root directory to walk, relative or absolute. Default '.'.",
"default": "."
},
"name": {
"type": "string",
"description": "File-name pattern; '|'-separated alternatives, each substring->glob->regex promoted and anchored to the whole name."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how --name/--ext patterns are interpreted; promotion off. Use literal for names whose characters would otherwise promote."
},
"ext": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restrict to these extensions (no dots), e.g. ['rs','toml']. Added to --name as alternatives. May be comma-joined."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries (names starting with '.'). Default: skipped."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"min-lines": {
"type": "integer",
"description": "Only include files with at least N lines."
},
"max-lines": {
"type": "integer",
"description": "Only include files with at most N lines."
},
"min-words": {
"type": "integer",
"description": "Only include files with at least N words."
},
"max-words": {
"type": "integer",
"description": "Only include files with at most N words."
},
"min-chars": {
"type": "integer",
"description": "Only include files with at least N characters."
},
"max-chars": {
"type": "integer",
"description": "Only include files with at most N characters."
},
"min-files-per-folder": {
"type": "integer",
"description": "Only include folders that directly contain at least N matching files."
},
"max-files-per-folder": {
"type": "integer",
"description": "Only include folders that directly contain at most N matching files."
},
"sort": {
"type": "string",
"enum": [
"path",
"name",
"lines",
"words",
"chars",
"ext"
],
"description": "Sort key. Default 'path'. In --flat the sort is global; in --tree it orders entries within each folder."
},
"desc": {
"type": "boolean",
"description": "Sort descending instead of ascending."
},
"tree": {
"type": "boolean",
"description": "Output mode: indented file tree with per-file counts and per-folder subtotals. This is the default mode."
},
"flat": {
"type": "boolean",
"description": "Output mode: one matching file per line with its counts. Mutually exclusive with the other modes."
},
"summary": {
"type": "boolean",
"description": "Output mode: aggregate counts only, grouped by --group. Mutually exclusive with the other modes."
},
"group": {
"type": "string",
"enum": [
"ext",
"dir",
"none"
],
"description": "Grouping for --summary: by extension (default), by immediate directory, or a single grand total."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result instead of text."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 (and a one-line message) if the report exceeds SECS seconds (fractional allowed)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-edit",
"description": "Find/replace across files chosen by ct-search-style predicates, framed as a self-checking edit. It computes every replacement first, classifies the total against --expect into a SUCCESS/ERROR verdict, and writes ONLY when the verdict is SUCCESS and --dry-run is not set; otherwise nothing is written. Replacements preserve every untouched byte (line terminators, indentation, surrounding text). --find/--replace accept payload schemes: file:PATH reads the value verbatim from a file (never promoted; literal by default), text:VALUE escapes the prefix. A single-line --find is substring->glob->regex promoted and matched per line (--mode literal|glob|regex pins the interpretation, promotion off — state literal for verbatim code anchors); a MULTI-LINE find payload matches as a line-anchored literal block (K lines match K consecutive source lines byte-for-byte; the replace payload's lines replace the block, an empty replace deletes it; a failed block reports its nearest miss: best-aligned candidate and first diverging line). With a regex --find, $1/${name} expand in --replace (use $$ for literal $); otherwise the replacement is literal. --script PATH runs a .ctb batch of edits atomically under the prepare/confirm/write standard: '#% edit expect=\"=1\" mode=literal file=...' opens an edit (expect defaults to =1 in scripts), '#% find' / '#% replace' carry verbatim payloads, '#% end' closes; the whole script is simulated in memory first (cascade: each edit sees earlier edits' output; --no-cascade matches pristine and rejects overlap), every changed file is pre-flighted for writability, and nothing is written unless EVERY edit passes — no flag permits a partial write. Only regular UTF-8 text files are edited. Not subject to the ct-test command allowlist (it runs no programs); safety is via --dry-run, --expect, atomicity, and your VCS. With --json emits {tool, verdict, dry_run, applied, replacements, files_changed, sites:[{path,line,before,after}]}; script runs emit per-edit results {ordinal, expect, mode, replacements, verdict, sites, nearest_miss?}. Exit: 0 SUCCESS, 1 ERROR, 2 usage/runtime error. Invoke as `ct edit ...` or `ct-edit ...`.",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Root to edit. A file edits just that file; a directory is descended. Default '.'.",
"default": "."
},
"name": {
"type": "string",
"description": "Limit to files whose name matches; '|'-separated alternatives, each substring->glob->regex promoted and anchored to the whole name."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries (names starting with '.'). Default: skipped."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"find": {
"type": "string",
"description": "Pattern to find (substring->glob->regex promoted), matched per line. Accepts file:PATH / text:VALUE payloads; a multi-line payload matches as a line-anchored literal block. Required unless script is given."
},
"replace": {
"type": "string",
"description": "Replacement text. With a regex --find, $1/${name} expand (use $$ for literal $); otherwise literal. Accepts file:PATH / text:VALUE; for a block find, an empty payload deletes the matched lines. Required unless script is given."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how --find (and --name) is interpreted; promotion off. Use literal for verbatim code anchors."
},
"script": {
"type": "string",
"description": "Run a .ctb edit script: a batch of find/replace blocks simulated and judged in full before any write; nothing is written unless every edit passes."
},
"fence": {
"type": "string",
"description": "Directive prefix for script lines. Default '#%'; change it for payloads containing '#%' at line start.",
"default": "#%"
},
"no-cascade": {
"type": "boolean",
"description": "Script edits match pristine content instead of cascading; overlapping edits become a usage error."
},
"expect": {
"type": "string",
"description": "Verdict expectation over the total replacement count; default 'any' (in scripts, per-edit expect= defaults to '=1'). One of: any (>=1), none (==0), N (>=N), =N (==N), +N (>N), -N (<N). The edit is written only if the verdict is SUCCESS."
},
"dry-run": {
"type": "boolean",
"description": "Compute and show the change and verdict, but write nothing."
},
"quiet": {
"type": "boolean",
"description": "Suppress the per-site diff; print only the summary line."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result instead of text."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 (and a one-line message) if the scan exceeds SECS seconds (fractional allowed). Never interrupts the write phase: once a SUCCESS verdict starts writing, every write completes."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-patch",
"description": "Make structured, format-preserving edits to JSON/JSONC/JSONL/YAML files: address a node by path and --set, --add, --delete, or --move-* it. For JSON/JSONC/JSONL, edits are byte-range splices against the parsed tree, so everything outside the changed node (comments, indentation, key order, blank lines, trailing commas) is preserved exactly; YAML uses the pure-Rust yaml-edit backend (comment-preserving, though a structural edit may relocate an adjacent comment). Format is detected from the extension (.json, .jsonc, .jsonl/.ndjson, .yaml/.yml) or forced with --format; for JSONL each op applies to every non-blank line. Paths are dot-separated keys with [N] array indices or [key=value] object predicates (leading dot optional, e.g. .servers[name=web].port). --set VALUE is parsed as JSON if possible else taken as a string (missing object keys are created and an index equal to the array length appends). --add appends VALUE to the array at PATH (no index needed). --delete removes the node and its separating comma (unresolved path is a no-op). --move-first/--move-last/--move-up/--move-down relocate the array element selected by PATH within its list. YAML currently supports --set (replace existing) and --delete only (both comment-preserving); --add, --move-*, and array-index/predicate paths are JSON-family-only for now and error clearly on YAML. The verdict is --expect applied to the total number of changes (default any); the edit is written only when the verdict is SUCCESS and --dry-run is not set. Not subject to the ct-test allowlist (it runs no programs). With --json emits {tool, verdict, dry_run, applied, changes, files_changed, files:[{path,changes}]}. Exit: 0 SUCCESS, 1 ERROR, 2 usage/runtime error. Invoke as `ct patch ...` or `ct-patch ...`. --set/--add VALUEs accept payload schemes: file:PATH reads the value verbatim as a string node (multi-line safe, never re-parsed as JSON), text:VALUE escapes the prefix.",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Root to patch. A file patches just that file; a directory is descended. Default '.'.",
"default": "."
},
"name": {
"type": "string",
"description": "Limit to files whose name matches; '|'-separated alternatives, each substring->glob->regex promoted and anchored to the whole name."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries (names starting with '.'). Default: skipped."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"set": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH=VALUE operations (repeatable). VALUE is parsed as JSON if possible, otherwise taken as a string. Missing object keys are created; an index equal to the array length appends. PATH may use [key=value] to select an array element. For YAML, --set replaces an existing key only. file:PATH reads the value verbatim as a string (never re-parsed as JSON); text:VALUE escapes the prefix."
},
"add": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH=VALUE operations (repeatable): append VALUE to the array at PATH, without computing an index. VALUE is parsed as JSON or taken as a string. JSON family only. file:PATH reads the value verbatim as a string; text:VALUE escapes the prefix."
},
"delete": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH operations (repeatable): remove the node at PATH, taking its separating comma. PATH may use [key=value] to select an array element. An unresolved path is a no-op."
},
"move-first": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH operations (repeatable): move the array element selected by PATH (by index or [key=value]) to the front of its list. JSON family only."
},
"move-last": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH operations (repeatable): move the selected array element to the end of its list. JSON family only."
},
"move-up": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH operations (repeatable): move the selected array element one position earlier. JSON family only."
},
"move-down": {
"type": "array",
"items": {
"type": "string"
},
"description": "PATH operations (repeatable): move the selected array element one position later. JSON family only."
},
"format": {
"type": "string",
"enum": [
"json",
"jsonc",
"jsonl",
"yaml"
],
"description": "Force the document format instead of detecting from the file extension."
},
"expect": {
"type": "string",
"description": "Verdict expectation over the total number of changes; default 'any'. One of: any (>=1), none (==0), N (>=N), =N (==N), +N (>N), -N (<N). The edit is written only if the verdict is SUCCESS."
},
"dry-run": {
"type": "boolean",
"description": "Compute and report the changes and verdict, but write nothing."
},
"quiet": {
"type": "boolean",
"description": "Suppress the per-file lines; print only the summary."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result instead of text."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 (and a one-line message) if the scan exceeds SECS seconds (fractional allowed). Never interrupts the write phase: once a SUCCESS verdict starts writing, every write completes."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-test",
"description": "Run a command as a framed experiment: pose a question, classify the result from stdout/stderr pattern matches, and emit a templated verdict. Pass/fail is decided by what the command prints, not only its exit code. ct-test is fail-closed; {RESULT} resolves in order: (0) the run timed out (--timeout) => ERROR (decisive — the experiment did not complete, so no match in partial output can establish success; {CODE} becomes 'timeout'); (1) any err-match hit => ERROR (decisive, never overridden); (2) else any ok-match hit => SUCCESS (a supplied --ok-match is a REQUIRED proof of success — a clean exit does not substitute for it); (3) else the run is inconclusive and --otherwise decides (success|error|exit), defaulting to error when an --ok-match was supplied, otherwise exit. The -stdout/-stderr matcher variants search only that one stream (e.g. cargo test writes 'test result: ok' to stdout, so --ok-match-stderr would miss it). On ERROR a one-line reason explaining which rule fired is printed to stderr and is available as the {REASON} emit token. --focus distils the captured output to the lines matching a pattern (with --context around each), printed to stderr and available as {FOCUS}; --capture-tail N bounds the {STDOUT}/{STDERR} emit tokens to the last N lines (matchers and --focus still see everything). --timeout SECS kills the command's whole process group after SECS seconds (fractional allowed). --heartbeat SECS prints a minimal liveness pulse while the command runs ([{ELAPSED}s] by default, customisable with --heartbeat-emit, routed to stderr or stdout by --heartbeat-to). Exit status is 0 when RESULT is SUCCESS, 1 when ERROR, 2 on a usage or runtime error. ct-test runs only a fixed, immutable built-in set of read-only commands (cat ct-check ct-deps ct-outline ct-search ct-tree ct-view echo false file grep head ls pwd stat tail true wc), so it is a ready conditional wrapper around the read-only ct-* tools; a command not on it is refused with exit 2 and nothing runs, and there is no run-time way to extend the list. Gating is by program name (the basename of cmd). There is no shell mode: the command is always launched directly, never through sh, so the match predicates and --focus replace the usual '| grep' post-processing (use ct-each for dispatch over many items). Pattern arguments use substring->glob->regex promotion and are searched unanchored. Invoke as `ct test ...` or `ct-test ...`. --stdin accepts payload schemes (file:PATH / text:VALUE); --mode literal|glob|regex pins matcher interpretation (promotion off).",
"input_schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "The question this experiment answers; printed as a '== ... ==' banner unless --quiet."
},
"cmd": {
"type": "string",
"description": "Program to run (must be on the fixed read-only allowlist). Trailing args (after --) are passed through to it. Always launched directly — there is no shell mode."
},
"stdin": {
"type": "string",
"description": "Literal text written to the child's standard input. Accepts file:PATH / text:VALUE payloads."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how matcher patterns are interpreted; promotion off. Use literal for verbatim code anchors."
},
"timeout": {
"type": "number",
"description": "Kill the command's process group after SECS seconds (fractional allowed). Decisive: the verdict is ERROR and {CODE} becomes 'timeout'."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the command runs."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL} {QUESTION} {CMD}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
},
"err-match": {
"type": "string",
"description": "Pattern that, if found in stdout OR stderr, forces RESULT=ERROR. Synonym for supplying both err-match-stdout and err-match-stderr."
},
"err-match-stdout": {
"type": "string",
"description": "Pattern that, if found in stdout, forces RESULT=ERROR."
},
"err-match-stderr": {
"type": "string",
"description": "Pattern that, if found in stderr, forces RESULT=ERROR."
},
"ok-match": {
"type": "string",
"description": "Pattern that, if found in stdout OR stderr, indicates RESULT=SUCCESS. Synonym for supplying both ok-match-stdout and ok-match-stderr."
},
"ok-match-stdout": {
"type": "string",
"description": "Pattern that, if found in stdout, indicates RESULT=SUCCESS."
},
"ok-match-stderr": {
"type": "string",
"description": "Pattern that, if found in stderr, indicates RESULT=SUCCESS."
},
"otherwise": {
"type": "string",
"enum": [
"success",
"error",
"exit"
],
"description": "Verdict when neither an --ok-match nor an --err-match matched (the inconclusive case). Default: error if any --ok-match was supplied, else exit (follow the exit code)."
},
"focus": {
"type": "string",
"description": "Distil the captured output to the lines matching this pattern, with --context lines around each (overlapping windows merge, line-numbered). Printed to stderr and available as the {FOCUS} emit token."
},
"context": {
"type": "integer",
"description": "Lines of context shown around each --focus match. Default: 2.",
"default": 2
},
"capture-tail": {
"type": "integer",
"description": "Keep only the last N lines of each captured stream in the {STDOUT}/{STDERR} emit tokens, with an elision marker. Matchers and --focus still see the full streams."
},
"emit": {
"type": "string",
"description": "Template written to stdout after the command finishes (alias: emit-stdout). Tokens: {RESULT} {CODE} {QUESTION} {CMD} {STDOUT} {STDERR} {REASON} {FOCUS}."
},
"emit-stderr": {
"type": "string",
"description": "Template written to stderr after the command finishes. Same tokens as emit."
},
"show-output": {
"type": "boolean",
"description": "Also pass the child's stdout/stderr through verbatim."
},
"quiet": {
"type": "boolean",
"description": "Suppress the question banner."
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arguments passed through to --cmd (supplied after `--`)."
}
},
"required": [
"cmd"
]
}
},
{
"name": "ct-each",
"description": "Run one command template once per item and judge the sweep with an aggregate verdict — the declarative replacement for a bash for-loop. Items come from --items, the shared walker (--base/--name/--ext/--hidden/--follow: matched file paths become items, in walk order — the natural source for per-file sweeps), and/or --stdin (one per line), in that order; everything after `--` is the command template, and {ITEM} (the current item) and {INDEX} (its 1-based position) expand inside every argv element. Each expansion is launched directly — there is no shell anywhere, so item values can never re-shape the command. Each run is classified by the suite's exit contract (exit 0 => that item SUCCESS, anything else => ERROR), and the count of per-item successes is judged against --expect: all (every item, the default) | any | none | N (at least) | =N (exactly) | +N (more than) | -N (fewer than). Dispatch targets are gated by program name against a fixed, immutable set: the read-only allowlist (cat ct-check ct-deps ct-outline ct-search ct-tree ct-view echo false file grep head ls pwd stat tail true wc) plus ct-test by default; with --mutating also ct-edit and ct-patch (each still enforces its own --expect/--dry-run gates). Nothing else is ever runnable and there is no run-time way to extend the set; every item's expanded command is gated before the first one runs, so a refusal (exit 2, nothing run) cannot strike mid-sweep. --dry-run prints each expanded command and runs nothing. --timeout SECS bounds each item's run (process-group kill; that item is ERROR with {CODE}=timeout). --heartbeat SECS prints a minimal liveness pulse ([{ELAPSED}s] by default, customisable with --heartbeat-emit, routed by --heartbeat-to). On a per-item ERROR a one-line reason goes to stderr; --show-output passes children's streams through verbatim. Exit status: 0 when the aggregate verdict is SUCCESS, 1 when ERROR, 2 on usage/runtime error or a refused target. Invoke as `ct each ...` or `ct-each ...`. --items accepts payload schemes: file:PATH expands to the file's non-empty lines, text:VALUE is one literal item.",
"input_schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "string"
},
"description": "Items to dispatch over, in order; one run per item. May be combined with stdin. A file:PATH item expands to the file's non-empty lines; text:VALUE is one literal item."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how --name/--ext walker patterns are interpreted; promotion off. Use literal for names whose characters would otherwise promote."
},
"base": {
"type": "string",
"description": "Walker item source: files under this root become items (paths). A file yields itself; a directory is descended."
},
"name": {
"type": "string",
"description": "Walker filter: limit to files whose name matches; '|'-separated alternatives, promoted and anchored. Implies --base . when --base is absent."
},
"ext": {
"type": "array",
"items": {
"type": "string"
},
"description": "Walker filter: restrict to these extensions (no dots); combined with --name as alternatives. Implies --base . when --base is absent."
},
"hidden": {
"type": "boolean",
"description": "Walker: include dot-entries; default skips them."
},
"follow": {
"type": "boolean",
"description": "Walker: follow symlinks."
},
"stdin": {
"type": "boolean",
"description": "Also read items from standard input, one per line (blank lines skipped), after any --items."
},
"question": {
"type": "string",
"description": "The question this sweep answers; printed as a '== ... ==' banner unless --quiet."
},
"expect": {
"type": "string",
"description": "Aggregate expectation over the per-item SUCCESS count: all|any|none|N|=N|+N|-N. Default: all (every item must succeed)."
},
"fail-fast": {
"type": "boolean",
"description": "Stop after the first per-item ERROR; remaining items are reported as skipped (and still count against --expect all)."
},
"mutating": {
"type": "boolean",
"description": "Permit the suite's mutating tools (ct-edit, ct-patch) as the dispatch target. Arbitrary external commands are never runnable."
},
"dry-run": {
"type": "boolean",
"description": "Print each fully-expanded command ('would run: ...') and run nothing."
},
"timeout": {
"type": "number",
"description": "Per item: kill that run's process group after SECS seconds (fractional allowed); the item is classified ERROR and its {CODE} becomes 'timeout'."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the sweep is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL} {QUESTION} {ITEM} {INDEX} {DONE} {TOTAL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
},
"emit-each": {
"type": "string",
"description": "Per-item template written to stdout. Tokens: {RESULT} {ITEM} {INDEX} {CODE} {CMD} {STDOUT} {STDERR}. Default (unless --quiet): \"{RESULT} {ITEM}\"."
},
"emit": {
"type": "string",
"description": "Summary template written to stdout after the sweep (alias: emit-stdout). Tokens: {RESULT} {OK} {ERRORS} {SKIPPED} {TOTAL} {QUESTION} {EXPECT} {REASON}."
},
"emit-stderr": {
"type": "string",
"description": "Summary template written to stderr. Same tokens as emit."
},
"show-output": {
"type": "boolean",
"description": "Also pass each child's stdout/stderr through verbatim."
},
"quiet": {
"type": "boolean",
"description": "Suppress the question banner, the default per-item lines, and the default summary."
},
"json": {
"type": "boolean",
"description": "Emit one structured JSON result (tool, verdict, expect, ok, errors, skipped, total, items[{index,item,cmd,code,result}]) instead of text; overrides the emit templates."
},
"command": {
"type": "array",
"items": {
"type": "string"
},
"description": "Command and arguments run per item (supplied after `--`); {ITEM} and {INDEX} expand in every element. The program must be on the fixed dispatch gate."
}
},
"required": [
"command"
]
}
},
{
"name": "ct-outline",
"description": "Report the declarations in a file or tree — kind, name, and start:end line span — so the next read can be a bounded ct-view --range instead of a whole-file dump. Detection is heuristic (per-language rule packs: line patterns plus a block heuristic — braces for Rust, indentation for Python, heading levels for Markdown); it is a comprehension aid, not a parser: start lines are exact, end lines are best-effort and render as 'start:?' (JSON \"end\": null) when underivable — the code wins when they disagree. Shipped languages: Rust (.rs: mod struct enum trait impl fn macro type const static), Python (.py: class, def/async def), Markdown (.md: h1..h6, fenced code blocks ignored); js/ts, java, go, sh are planned. Unrecognised extensions are skipped in directory walks and are an error (exit 2) when named directly. Targeting uses the suite's walker vocabulary (--base file-or-dir, --name, --ext, --hidden, --follow). Filter entries with --match (anchored to the whole declaration name, like --name — use 'Verdict*' for prefix semantics), --kind (per-language keyword list), and --depth (1 = top-level only); filters AND together. Tree output keeps a matched entry's ancestors visible marked '(context)', but only matched entries count toward {COUNT}/--expect and only matched entries appear in --flat (path:start:end:kind:name) and --json output. Framed verdict: --question banner, --expect over the matched-entry count (any|none|N|=N|+N|-N, default any), --emit templates with {RESULT} {QUESTION} {COUNT} {BASE} {MATCHES}; exit 0 SUCCESS, 1 ERROR, 2 usage/runtime error. Read-only — on the ct-test allowlist and ct-each's default gate. Invoke as `ct outline ...` or `ct-outline ...`.",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "A file outlines just that file; a directory is descended. Default '.'.",
"default": "."
},
"name": {
"type": "string",
"description": "Limit to files whose name matches; '|'-separated alternatives, each substring->glob->regex promoted and anchored to the whole name."
},
"ext": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restrict to these extensions (no dots), e.g. ['rs','py']. Added to --name as alternatives. May be comma-joined."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries (names starting with '.'). Default: skipped."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"match": {
"type": "string",
"description": "Keep entries whose name matches (substring->glob->regex promoted, anchored to the whole declaration name). Use a glob like 'Verdict*' for prefix semantics."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how --match/--name patterns are interpreted; promotion off. Use literal for names whose characters would otherwise promote."
},
"kind": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keep entries of these kinds (comma-joined or repeated), e.g. ['fn','struct']. Kinds are the source language's own keywords (Rust: mod struct enum trait impl fn macro type const static; Python: class def; Markdown: h1..h6)."
},
"depth": {
"type": "integer",
"description": "Keep entries nested at most N levels deep (1 = top-level only)."
},
"flat": {
"type": "boolean",
"description": "One grep-friendly row per matched entry: path:start:end:kind:name (end is '?' when unknown). Default is an indented per-file tree with '(context)' ancestors."
},
"question": {
"type": "string",
"description": "Question this outline answers, framing it as a test; printed as a '== ... ==' banner unless quiet."
},
"expect": {
"type": "string",
"description": "Verdict expectation over the matched-entry count; default 'any'. One of: any (>=1), none (==0), N (>=N), =N (==N), +N (>N), -N (<N)."
},
"emit": {
"type": "string",
"description": "Template written to stdout after the outline (alias: emit-stdout). Tokens: {RESULT} {QUESTION} {COUNT} {BASE} {MATCHES}."
},
"emit-stderr": {
"type": "string",
"description": "Template written to stderr after the outline. Same tokens as emit."
},
"quiet": {
"type": "boolean",
"description": "Print no outline and no banner; report via exit status (and --emit, which still fires)."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result {tool, verdict, base, count, files:[{path, entries:[{kind,name,start,end,depth}]}]} instead of text; overrides the text modes and --emit."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 (and a one-line message) if the run exceeds SECS seconds (fractional allowed)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-rules",
"description": "Say what the rules are: the specification and storage interface of the project's invariant surface (.ct/rules.jsonc; the verifying side is ct-check). Verbs (exactly one per invocation): --init scaffolds a commented store under .ct/ (the suite's home for project-local state; discovered by walking upward to the nearest .ct, --file overrides); --add ID records a rule — the probe after `--` is gate-validated and RUN immediately, and must hold (a violated candidate is refused exit 1 with the probe's own violation output; a broken probe is refused exit 2) unless --pending parks it as an aspiration that ct-check reports separately and never enforces; --promote ID re-runs a pending rule's probe and clears the pending flag once it holds; --remove ID deletes by exact id (duplicate ids are always refused — ids are history); --def NAME=VALUE sets named vocabulary (VALUE parsed as JSON, e.g. a list, else taken as a string) that rules reference as {def:NAME} inside probe argvs; --list prints defs and rules; --prompt TEXT (with --add) retains the verbatim human request behind the rule as provenance — the confirmation tells the user it was retained — and --flatten strips every retained prompt in one pass, leaving only the mechanical definitions; the store itself is human-friendly JSONC (a standing header comment re-established on every write, one field per line per rule, blank lines between rules); --hook cargo writes tests/ct_invariants.rs, a plain reviewed-in-git shim that makes `cargo test` run `ct check --quiet` and fail loudly (including when the ct binary is missing; a shim ct-rules did not generate is never overwritten). Probes observe and never change anything: the gate is compiled-in and immutable — the suite's read-only tools (ct-search ct-outline ct-tree ct-view ct-deps, ct-test, ct-each without --mutating) plus the bridge (cargo metadata / cargo tree hermetic, cargo deny check offline unless --network, rust-analyzer search|symbols search-only); never the mutating tools, ct-check (no self-recursion), ct-rules itself, shells, or unlisted externals. --add options: --question (required), --why (printed whenever the rule fails), --tag, --severity warn (violations report but never redden the exit), --expect empty | --expect-ok PATTERN | --expect-err PATTERN (outcome adapters for bridge tools; ct-test matcher semantics), --network, --timeout SECS, --pending. All store mutations are comment-preserving (the suite's own patch machinery). ct-rules writes only the store and the hook shim, and is on no allow-gate. Exit: 0 success; 1 refused on the merits (candidate/promotion does not hold); 2 usage or store error. Invoke as `ct rules ...` or `ct-rules ...`.",
"input_schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "The rule store. Default: the nearest .ct/rules.jsonc walking upward (created by --init or the first --add when absent)."
},
"init": {
"type": "boolean",
"description": "Create .ct/rules.jsonc (commented scaffold) if it does not exist."
},
"add": {
"type": "string",
"description": "Record a rule with this id; the probe (after `--`) is gate-validated and run now, and must hold unless --pending."
},
"pending": {
"type": "boolean",
"description": "With --add: record an aspiration that does not yet hold; reported as PENDING by ct-check, never enforced, until --promote."
},
"question": {
"type": "string",
"description": "With --add (required): the question this rule answers."
},
"why": {
"type": "string",
"description": "With --add: why this invariant exists; printed whenever the rule fails. Accepts file:PATH / text:VALUE payloads."
},
"prompt": {
"type": "string",
"description": "With --add: the verbatim human request behind this rule, retained in the store as provenance so the intent can be revisited (the confirmation tells the user it was retained). Never read by verification; strip all prompts with --flatten. Accepts file:PATH / text:VALUE payloads."
},
"tag": {
"type": "array",
"items": {
"type": "string"
},
"description": "With --add: tags for ct-check --tag selection (comma-joined or repeated)."
},
"severity": {
"type": "string",
"enum": [
"fail",
"warn"
],
"description": "With --add: fail (default) or warn (violations report as WARN but never redden the exit)."
},
"expect": {
"type": "string",
"enum": [
"exit",
"empty"
],
"description": "With --add: outcome adapter for bridge probes — exit (default, suite contract) or empty (holds iff exit 0 and no stdout)."
},
"expect-ok": {
"type": "string",
"description": "With --add: matcher adapter — the rule holds when this pattern (substring->glob->regex promoted) appears in the probe's output."
},
"expect-err": {
"type": "string",
"description": "With --add: matcher adapter — a violation when this pattern appears in the probe's output (decisive over expect-ok)."
},
"network": {
"type": "boolean",
"description": "With --add: permit network access where the bridge entry deems it meaningful (currently cargo deny check); everything else stays hermetic."
},
"timeout": {
"type": "number",
"description": "With --add: per-rule probe bound in seconds (fractional allowed), recorded in the store."
},
"promote": {
"type": "string",
"description": "Re-run this pending rule's probe; if it now holds, clear the pending flag (enforce it)."
},
"remove": {
"type": "string",
"description": "Remove the rule with this exact id."
},
"def": {
"type": "string",
"description": "Set a def: NAME=VALUE. VALUE is parsed as JSON (e.g. [\"A\",\"B\"]) or taken as a string; rules reference defs as {def:NAME}."
},
"list": {
"type": "boolean",
"description": "Print defs and rules without changing anything."
},
"flatten": {
"type": "boolean",
"description": "Strip the retained \"prompt\" prose from every rule in one pass (naming the rules touched), leaving only the mechanical definitions."
},
"hook": {
"type": "string",
"enum": [
"cargo"
],
"description": "Write the build hook: for cargo, a tests/ct_invariants.rs shim making `cargo test` enforce the rule store."
},
"quiet": {
"type": "boolean",
"description": "Suppress informational output."
},
"probe": {
"type": "array",
"items": {
"type": "string"
},
"description": "With --add: the probe argv (after `--`), run directly — never through a shell. Must pass the compiled-in gate."
}
},
"required": []
}
},
{
"name": "ct-check",
"description": "Verify the project's recorded invariants: load the rule store (.ct/rules.jsonc, discovered by walking upward to the nearest .ct directory, git-style), run every selected rule's probe in store order, and report each rule in one of five lanes — SUCCESS (zero violations), ERROR (violations, severity fail => exit 1), WARN (violations, severity warn => reported, never reddens the exit), PENDING (an aspiration recorded with --pending: current state reported, never enforced), BROKEN (the probe itself is defective: exited 2, died, timed out, or its binary is missing; any broken rule => the whole run exits 2 — a defective store is a maintenance signal). Probes are argv vectors (never a shell), gated to a compiled-in, immutable set: the suite's read-only tools (ct-search ct-outline ct-tree ct-view ct-deps, ct-test, ct-each without --mutating) plus the bridge of known read-only Rust-tool invocations (cargo metadata / cargo tree with hermetic flags enforced, cargo deny check offline unless the rule carries network:true, rust-analyzer search|symbols search-only). The store is validated before anything runs (malformed entries, duplicate ids, unknown {def:NAME} references, non-gated probes => exit 2 naming the rule). Bridge probes are read through the rule's expect adapter: exit (default), empty (holds iff exit 0 and no stdout), or ct-test-style ok-match/err-match patterns. ct-check is purely read-only (writes nothing, ever; ct-rules is the writing surface) and is itself on the suite's read-only allowlist, so ct-test/ct-each can wrap it — but a rule's probe may not run ct-check (no self-recursion). A red lane is never unexplained: the reason, the rule's why, and the head of the probe's violation output go to stderr. Exit: 0 all enforced rules hold, 1 any enforced violation, 2 usage/store error or any BROKEN rule. Invoke as `ct check ...` or `ct-check ...`.",
"input_schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "The rule store. Default: the nearest .ct/rules.jsonc walking upward from the current directory."
},
"id": {
"type": "string",
"description": "Select rules whose id matches (substring->glob->regex promoted, anchored to the whole id)."
},
"tag": {
"type": "array",
"items": {
"type": "string"
},
"description": "Select rules carrying any of these tags (comma-joined or repeated)."
},
"fail-fast": {
"type": "boolean",
"description": "Stop after the first enforced violation; remaining rules are reported as SKIPPED."
},
"list": {
"type": "boolean",
"description": "Print the selected rules (id, pending/warn flags, question, tags); run nothing."
},
"quiet": {
"type": "boolean",
"description": "Suppress per-rule lines and the default summary (stderr diagnostics remain)."
},
"json": {
"type": "boolean",
"description": "Emit one structured result {tool, verdict, store, ok, violated, warned, pending, broken, skipped, total, rules:[{id,question,lane,code,reason,why}]} instead of text; overrides the emit templates."
},
"emit-each": {
"type": "string",
"description": "Per-rule template written to stdout. Tokens: {RESULT} {ID} {QUESTION} {CODE} {WHY} {CMD}."
},
"emit": {
"type": "string",
"description": "Summary template written to stdout (alias: emit-stdout). Tokens: {RESULT} {OK} {ERRORS} {WARNED} {PENDING} {BROKEN} {SKIPPED} {TOTAL} {REASON}."
},
"emit-stderr": {
"type": "string",
"description": "Summary template written to stderr. Same tokens as emit."
},
"timeout": {
"type": "number",
"description": "Default per-rule probe bound in seconds (fractional allowed); a rule's own timeout field overrides it. A timed-out probe is BROKEN."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while rules run."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL} {ID} {DONE} {TOTAL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-deps",
"description": "Assert crate-graph invariants over the resolved dependency graph, with every violation carrying its evidence. The graph comes from one `cargo metadata --format-version 1 --locked --offline` invocation (hermetic by construction: the lockfile is read, never written; the network is never touched; a workspace that cannot resolve offline is exit 2, never a silent pass). Assertions (at least one required): --deny NAME (violation when a crate named NAME is reachable from any workspace member; evidence = the shortest dependency path), --forbid 'A=>B' (violation when any package named A reaches a package named B — the workspace-layering form; A absent from the graph is exit 2, a defective assertion rather than a clean pass; evidence = the path), --duplicates (violation per crate resolving at more than one version; evidence = the version list). --edges normal,build,dev restricts which dependency-edge kinds are traversed (default all three; --edges normal asks about the shipped artifact only). Output: one line per violation (check: subject: evidence) plus a summary; --quiet for exit-status only; --json emits {tool, verdict, count, violations:[{check,subject,evidence}]}; --emit/--emit-stderr templates take {RESULT} {COUNT} {VIOLATIONS} {QUESTION}. --timeout SECS bounds the cargo child (process-group kill, exit 2). Read-only: on the ct-test allowlist, admissible in ct-each dispatch and ct-rules probes (the native form of crate-graph rules, no expect adapter needed). Exit: 0 every assertion holds, 1 violations found, 2 usage/runtime error. Invoke as `ct deps ...` or `ct-deps ...`.",
"input_schema": {
"type": "object",
"properties": {
"deny": {
"type": "array",
"items": {
"type": "string"
},
"description": "Violation if this crate appears anywhere reachable from the workspace (repeatable). Evidence: the shortest dependency path."
},
"forbid": {
"type": "array",
"items": {
"type": "string"
},
"description": "Violation if package A reaches package B, written 'A=>B' (repeatable). A must exist in the graph (else exit 2). The workspace-layering assertion."
},
"duplicates": {
"type": "boolean",
"description": "Violation for every crate that resolves at more than one version, with the version list as evidence."
},
"edges": {
"type": "array",
"items": {
"type": "string",
"enum": [
"normal",
"build",
"dev"
]
},
"description": "Dependency-edge kinds traversed (comma-joined or repeated). Default: all three. 'normal' alone asks about the shipped artifact only."
},
"question": {
"type": "string",
"description": "Question this check answers; printed as a '== ... ==' banner unless --quiet."
},
"emit": {
"type": "string",
"description": "Template written to stdout after the check (alias: emit-stdout). Tokens: {RESULT} {COUNT} {VIOLATIONS} {QUESTION}."
},
"emit-stderr": {
"type": "string",
"description": "Template written to stderr. Same tokens as emit."
},
"quiet": {
"type": "boolean",
"description": "Print no violation lines or summary; report via exit status (and --emit, which still fires)."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result {tool, verdict, count, violations:[{check,subject,evidence}]} instead of text."
},
"timeout": {
"type": "number",
"description": "Kill the underlying cargo metadata invocation (process group) and abort with exit 2 after SECS seconds (fractional allowed)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
},
"required": []
}
},
{
"name": "ct-await",
"description": "Wait, observably and boundedly, for an external outcome: poll a gated read-only probe every --every seconds (default 5) until the condition is established — probe exit 0, or a required --ok-match pattern appearing in its output — or until an --err-match pattern appears (immediate ERROR, decisive over everything — a failed build reports in seconds, not after the timeout; exactly ct-test's matcher precedence, and a supplied --ok-match is the REQUIRED proof: exit 0 without it is still 'not yet'), or until the REQUIRED --timeout expires (ERROR; a wait is bounded by design, and no single probe run can outlive the bound — process-group kill). The probe is an argv after `--`, launched directly each tick (never through a shell) from the current directory; matchers see only what the probe prints (pair them with content-surfacing probes like cat or ct-view; self-classifying probes like ct-search --quiet need none); any non-zero probe exit simply means 'not yet' (a log file that does not exist yet is the normal waiting case) — only a probe that cannot launch, or a non-gated probe, is exit 2. Probes are the same fixed read-only set ct-each dispatches by default: the allowlist (cat ct-check ct-deps ct-outline ct-search ct-tree ct-view echo false file grep head ls pwd stat tail true wc) plus ct-test and ct-each (without --mutating); ct-check included means 'wait until the project's invariants hold' is one command. ct-await separates observation authority from execution authority: whoever owns the work (a human's mvn run, CI, a deploy) executes it; ct-await only watches its effects. ct-await itself is on no gate (it is a dispatcher, like ct-each). On ERROR the reason goes to stderr. --heartbeat pulses while waiting ({ELAPSED} {TOOL} {QUESTION} {CMD} {TICKS}); --emit/--emit-stderr templates take {RESULT} {ELAPSED} {TICKS} {REASON} {QUESTION} {CMD}. Exit: 0 the condition was established within the bound, 1 err-match matched or the timeout expired, 2 usage error / refused probe / launch failure. Invoke as `ct await ...` or `ct-await ...`.",
"input_schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "Question this wait answers; printed as a '== ... ==' banner unless --quiet."
},
"every": {
"type": "number",
"description": "Seconds between probe runs (fractional allowed). Default: 5.",
"default": 5
},
"timeout": {
"type": "number",
"description": "Required hard bound on the whole wait in seconds (fractional allowed). Expiry is ERROR with a reason naming the bound and the probe-run count."
},
"ok-match": {
"type": "string",
"description": "SUCCESS when this pattern (substring->glob->regex promoted) appears in the probe's stdout or stderr. When supplied it is the required proof: a probe exiting 0 without it is still 'not yet' (fail-closed)."
},
"err-match": {
"type": "string",
"description": "End the wait immediately with ERROR when this pattern appears in the probe's output. Decisive over --ok-match and exit status, exactly as in ct-test."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how --ok-match/--err-match patterns are interpreted; promotion off. Use literal for verbatim code anchors."
},
"emit": {
"type": "string",
"description": "Template written to stdout when the wait ends (alias: emit-stdout). Tokens: {RESULT} {ELAPSED} {TICKS} {REASON} {QUESTION} {CMD}."
},
"emit-stderr": {
"type": "string",
"description": "Template written to stderr when the wait ends. Same tokens as emit."
},
"quiet": {
"type": "boolean",
"description": "Suppress the banner and the default outcome line (stderr reasons and emits remain)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while waiting."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL} {QUESTION} {CMD} {TICKS}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
},
"probe": {
"type": "array",
"items": {
"type": "string"
},
"description": "The probe argv (after `--`), run directly each tick — never through a shell. Exit 0 (or the required --ok-match appearing) ends the wait with SUCCESS; any other outcome means 'not yet'. Must be on the fixed read-only gate."
}
},
"required": [
"timeout",
"probe"
]
}
}
]
}