{
"name": "ct",
"description": "USE ct — DO NOT ROUTE AROUND IT. When a task has a ct tool, call that tool instead of raw shell or the harness's generic search/read tools; each ct tool is bounded (it will not flood context), deterministic, and self-verifying (a framed --expect/--question verdict, exit 0/1/2), and the ad-hoc equivalent is none of those even when it appears to work. Map: search = find files / search content (not find, grep -r, rg, ag, Grep, Glob); view --range = read a line range or regions (not sed -n, head, tail, Read offset/limit); tree --summary = file tree with counts/totals and survey = crate/module survey (not ls -R, wc -l, ad-hoc cargo metadata); outline = declarations in a file/tree (not grepping for 'fn '/'class '/'def '); edit = previewed, --expect-gated find/replace (not sed -i, perl -i); patch = set/delete JSON/JSONC/JSONL nodes (not jq -i or hand-editing); test = run a command as a checked experiment (not eyeballing output); each = one command template per item (not for/while loops); await = poll until a probe passes (not sleep/retry loops). ONE CALL, NOT A PIPELINE: do not cobble commands with pipes, xargs, and command substitution — combine steps with `ct and`/`ct or` (shell-less &&/||), fan out with `ct each`, and get totals/verdicts with --summary and --expect/--question instead of piping into wc, grep, or test. A hand-built pipeline is unbounded and silent on failure; a ct call is bounded and reports its verdict. --- 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 okf runs ct-okf, 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). Two built-in boolean chains sequence several sub-commands in a single argv without a shell, using the separator ::: between segments: `ct and A ::: B ::: C` runs each in turn and stops at the first non-zero exit (shell-less &&, returning that code; 0 if all succeed); `ct or A ::: B` runs each in turn and stops at the first zero exit (shell-less ||, returning 0; the last segment's code if all fail). A blank segment is a usage error (exit 2), and chains do not nest. To invoke a chain through this schema set command to 'and' or 'or' and put the segments (with ::: separators) in args. 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), await (ct-await). Any other ct-* tool on PATH also works. The reserved words 'and' and 'or' run a shell-less boolean chain over the segments in args (separated by ':::') instead of a single tool.",
"enum": [
"search",
"view",
"tree",
"edit",
"patch",
"test",
"each",
"outline",
"rules",
"check",
"await",
"and",
"or"
]
},
"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."
},
"okf-type": {
"type": "string",
"description": "OKF: keep only Markdown concepts whose frontmatter `type` matches this pattern (substring->glob->regex promoted, also pinned by --mode)."
},
"okf-tag": {
"type": "array",
"items": {
"type": "string"
},
"description": "OKF: keep only Markdown concepts whose frontmatter carries all of these tags (repeated or comma-joined)."
},
"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."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result {tool, verdict, base, count, lines, matches:[paths]} instead of text; overrides the output mode and --emit."
},
"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."
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped); by default the walk skips what git would."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"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."
},
"frontmatter": {
"type": "boolean",
"description": "OKF: show only the concept's leading frontmatter block."
},
"no-frontmatter": {
"type": "boolean",
"description": "OKF: omit the concept's frontmatter block from the shown lines. With --json, a 'frontmatter' field is added whenever the file is an OKF concept, regardless of this flag."
},
"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."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"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 (and on-disk byte size). 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/--min-bytes/--max-bytes) 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|bytes|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). --bytes adds a byte-size column to the text modes (also enabled by --sort bytes). --json emits {tool, base, files:[{path,ext,lines,words,chars,bytes}], 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-bytes": {
"type": "integer",
"description": "Only include files of at least N bytes."
},
"max-bytes": {
"type": "integer",
"description": "Only include files of at most N bytes."
},
"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",
"bytes",
"ext",
"okf-type"
],
"description": "Sort key. Default 'path'. In --flat the sort is global; in --tree it orders entries within each folder. Sorting by bytes also turns on the byte column. 'okf-type' sorts by a Markdown concept's frontmatter type (files without one sort first)."
},
"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."
},
"bytes": {
"type": "boolean",
"description": "Add a byte-size (on-disk) column after chars in the text modes. Independent of --min-bytes/--max-bytes; also enabled by --sort bytes. JSON always includes bytes."
},
"group": {
"type": "string",
"enum": [
"ext",
"dir",
"none",
"okf-type"
],
"description": "Grouping for --summary: by extension (default), by immediate directory, by OKF frontmatter type (files without one group under '(none)'), 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."
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped); by default the walk skips what git would."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"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."
},
"squeeze-blank": {
"type": "boolean",
"description": "Blank-line tolerant block matching: a maximal run of blank (empty or whitespace-only) lines in a multi-line --find matches a run of one-or-more blank lines in the source, regardless of count. No effect on a single-line --find or on --replace. In scripts, set per-edit squeeze=true instead."
},
"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."
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped); by default the walk skips what git would."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"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."
},
"mode": {
"description": "Pin how --name is interpreted (promotion off): literal, glob, or regex.",
"enum": [
"literal",
"glob",
"regex"
],
"type": "string"
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped); by default the walk skips what git would."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"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 (a platform-aware read-only set: cross-platform core ct-await ct-check ct-outline ct-search ct-tree ct-view, plus the host OS native utilities — cat echo false file grep head ls pwd stat tail true wc on Unix/MSYS2, or findstr hostname more where whoami on native Windows), 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, with a Windows .exe suffix stripped). 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 (a platform-aware read-only set: cross-platform core ct-await ct-check ct-outline ct-search ct-tree ct-view, plus the host OS native utilities — cat echo false file grep head ls pwd stat tail true wc on Unix/MSYS2, or findstr hostname more where whoami on native Windows) 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."
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped); by default the walk skips what git would."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"required": [
"command"
]
}
},
{
"name": "ct-okf",
"description": "Author, query, and index Open Knowledge Format (OKF v0.1) bundles — directory trees of Markdown concepts whose leading YAML frontmatter carries a required `type` plus optional title/description/resource/tags/timestamp, alongside reserved index.md / log.md files and Markdown cross-links. ct-okf is SUBCOMMAND-shaped (`ct okf <verb>`); the `commands` array lists every verb and its arguments. It works over the project's configured OKF content roots and keeps a lazily-maintained full-text index, so `search` is always current. Roots are discovered three ways (any suffices, all converge on the .ct/okf.jsonc config): a `.okf` marker file, a bundle-root index.md declaring okf_version, or a config entry managed by `roots`/`init`. The index lives under .ct/okf/ as immutable fst segments (new content layers a segment; `index condense` merges and drops tombstones). Query verbs: `search QUERY...` (full-text across roots, auto-updates the index first; supports term, term* prefix, term~/term~N fuzzy, /regex/; filter --type/--tag, cap --limit) and `find` (list concepts by --type/--tag in the --base bundle). Configure: `roots list|add|rm|scan`, `index status|update|condense|rebuild`, `init` (discover roots, record them, build the index). Check (framed verdict): `validate` (conformance; --strict also fails on broken links) and `links` (broken bundle cross-links) — both take --question, --expect (any|none|N|=N|+N|-N, default none), --emit/--emit-stderr ({RESULT} {QUESTION} {COUNT} {TOTAL} {BASE} {MATCHES}). Author (these write): `show PATH`, `add PATH --type ...` (alias new), `mv SRC DST` (alias rename; fixes bundle cross-links), `set FIELD=VALUE --file`, `log MESSAGE --kind`, `gen-index` ((re)generate index.md, --scaffold for an okf_version stub), `script PATH` (atomic .ctb batch). Global flags (`base`/`name`/`hidden`/`follow`/`no-ignore`/`json`/`json-pretty`/`quiet`/`timeout`/heartbeat) apply across verbs. Exit 0 SUCCESS, 1 ERROR, 2 usage/runtime error. Because the authoring verbs write, ct-okf is not on the read-only allowlist (read-only OKF composition is provided by the OKF-aware ct-search/ct-tree/ct-view/ct-outline and the `okf` built-in check). Invoke as `ct okf <verb> ...` or `ct-okf <verb> ...`.",
"commands": [
{
"name": "search",
"summary": "Full-text search across content roots (auto-updates the index first).",
"args": "QUERY... [--limit N=20] [--type TYPE] [--tag T,...]"
},
{
"name": "find",
"summary": "List concepts by metadata in the --base bundle.",
"args": "[--type TYPE] [--tag T,...]"
},
{
"name": "roots",
"summary": "Manage content roots.",
"args": "list | add DIR [--marker] | rm DIR | scan [--write]"
},
{
"name": "index",
"summary": "Maintain the search index.",
"args": "status | update | condense | rebuild"
},
{
"name": "init",
"summary": "Discover content roots, record them, and build the index.",
"args": "[--marker]"
},
{
"name": "validate",
"summary": "Judge the --base bundle's OKF conformance (framed verdict).",
"args": "[--strict] [--question Q] [--expect SPEC] [--emit T] [--emit-stderr T]"
},
{
"name": "links",
"summary": "Report broken bundle cross-links (framed verdict).",
"args": "[--strict] [--question Q] [--expect SPEC] [--emit T] [--emit-stderr T]"
},
{
"name": "show",
"summary": "Print one concept's frontmatter.",
"args": "PATH"
},
{
"name": "add",
"summary": "Scaffold a new concept (alias: new).",
"args": "PATH --type TYPE [--title T] [--description D] [--tag T,...]"
},
{
"name": "mv",
"summary": "Move/rename a concept, fixing bundle cross-links (alias: rename).",
"args": "SRC DST"
},
{
"name": "set",
"summary": "Set or update a scalar frontmatter field.",
"args": "FIELD=VALUE --file PATH"
},
{
"name": "log",
"summary": "Prepend a dated entry to a bundle's log.md.",
"args": "MESSAGE [--kind LABEL]"
},
{
"name": "gen-index",
"summary": "(Re)generate a bundle's index.md from its concepts.",
"args": "[--scaffold]"
},
{
"name": "script",
"summary": "Run a .ctb batch of OKF mutations atomically.",
"args": "PATH [--dry-run] [--fence STR]"
}
],
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Search root for bundle-scoped verbs (validate/links/find/show); the directory project discovery starts from for search/index/roots/init. Default '.'.",
"default": "."
},
"name": {
"type": "string",
"description": "Limit to files whose name matches; '|'-separated alternatives, each substring->glob->regex promoted and anchored."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries (names starting with '.')."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped)."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result instead of text."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
},
"quiet": {
"type": "boolean",
"description": "Suppress informational output (exit status and --emit still report)."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 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-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)."
},
"frontmatter": {
"type": "boolean",
"description": "OKF: also report a Markdown concept's frontmatter as synthetic 'meta:KEY' entries (e.g. meta:type, meta:title), prepended before the headings. Filter them with --kind meta:type. Off by default, so ordinary outlines are unchanged."
},
"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."
},
"no-ignore": {
"type": "boolean",
"description": "Walk gitignored / .ignore files too (the .git directory is always skipped); by default the walk skips what git would."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"required": []
}
},
{
"name": "ct-survey",
"description": "Survey a codebase by the units its build system defines, not by raw filesystem shape — for Rust, the workspace -> crate -> module hierarchy, each element carrying file, line, word, character, and test counts. Reachable as `ct survey ...` or `ct-survey ...`; read-only. Honesty classes are kept distinct and never conflated: crate identity, workspace membership, and cargo target kinds are AUTHORITATIVE (read from `cargo metadata --no-deps --offline`); file/line/word/char counts are EXACT; the module bucketing (nearest source root, path-derived like ct's module graph) and the #[test] tally are HEURISTIC and render with a trailing '~' in text output (JSON tags each block under `honesty`). With no --group, the contextual group type is inferred from the given path's Cargo.toml: a [workspace] table -> cargo-workspace (survey every member crate); a lone [package] -> cargo-crate (survey just that crate, even inside a workspace). --group overrides the inference. --depth chooses crate (per-crate rows only) or module (per-crate then per-module, the default). --sort orders by name (ascending) or files/lines/tests (largest first), applied to crates and their modules. The heuristic test count scans for attributes whose final segment is `test` (#[test], #[tokio::test]); it excludes #[cfg(test)] and does not discount attributes in strings/comments. Authoritative cargo test/bench TARGET counts sit beside it. A crate total can exceed its module sum: integration tests and benches count toward the crate but belong to no module. Requires a resolvable Cargo.toml; cargo/metadata/argument errors exit 2 with a one-line message. Invoke as `ct survey ...` or `ct-survey ...`.",
"input_schema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Path to survey: a directory, or a Cargo.toml file. A directory uses its Cargo.toml. Default '.'.",
"default": "."
},
"group": {
"type": "string",
"enum": [
"cargo-workspace",
"cargo-crate"
],
"description": "Contextual group type. Omit to infer from the path's Cargo.toml ([workspace] -> cargo-workspace, else cargo-crate). cargo-workspace surveys every member; cargo-crate surveys just the crate whose Cargo.toml the path names."
},
"depth": {
"type": "string",
"enum": [
"crate",
"module"
],
"description": "How deep to descend: crate (per-crate rows only) or module (per-crate then per-module). Default: module."
},
"sort": {
"type": "string",
"enum": [
"name",
"files",
"lines",
"tests"
],
"description": "Sort key for crates and, within each crate, its modules: name (ascending) or files/lines/tests (largest first). Default: name."
},
"json": {
"type": "boolean",
"description": "Emit a structured JSON result {tool, group, name, root, honesty, crates:[{name,version,files,lines,words,chars,tests,test_targets,bench_targets,modules:[...]}], totals} instead of text."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
},
"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). A bare probe with no verb runs it and reports without saving — prototyping; the same probe with --add ID --question … then records it. 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-test, ct-each without --mutating), the built-in checks deps|mods (crate/module graph invariants, run in-process), 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-test, ct-each without --mutating), the built-in checks deps|mods (crate/module graph invariants, run in-process), 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)."
},
"mode": {
"type": "string",
"enum": [
"literal",
"glob",
"regex"
],
"description": "Pin how --id is interpreted (promotion off): literal, glob, or regex."
},
"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."
},
"json-pretty": {
"type": "boolean",
"description": "Like --json, but pretty-printed (indented)."
}
},
"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 (a platform-aware read-only set: cross-platform core ct-await ct-check ct-outline ct-search ct-tree ct-view, plus the host OS native utilities — cat echo false file grep head ls pwd stat tail true wc on Unix/MSYS2, or findstr hostname more where whoami on native Windows) 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 can itself be dispatched as a read-only probe, but it never polls itself (no self-nesting). 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"
]
}
},
{
"name": "ct-steer",
"description": "Steer ad-hoc shell to the ct tool that serves it, and install the steering hook. ct-steer recognises a fixed set of high-confidence shell idioms a suite tool serves better — `find … | xargs grep` / `find -exec grep` and `grep -r`/`rg`/`ag` (ct search), `find … -name` (ct search), `sed -i`/`perl -i` (ct edit), `head`/`tail`/`sed -n 'A,Bp'` on a file and `python -c`/`node -e`/`perl -e`/`ruby -e`/`jq` reading a file (ct view / ct search), `grep -c` (ct search --summary), `ls -R`/`tree` and `wc`/`wc -l` over files incl. `cat FILES | wc` (ct tree), `for`/`while` per-item loops (ct each), sleep-bearing `for`/`while`/`until` poll/wait loops (ct await), and `&&`/`||` chains whose every segment is itself ct-serviceable (ct and / ct or). A multi-line scriptlet is classified line by line (ignoring cd/assignments/echo/comments): when every meaningful step is already ct or ct-advisable and not all are yet ct, the whole thing folds into one shell-less `ct and A ::: B ::: C` chain; when some steps are opaque, the ct equivalents are advised individually. Run as a Claude Code PreToolUse hook, it steers the agent to the ct equivalent instead of running the raw command. The matcher is deliberately conservative: it only fires on those idioms, never re-steers a command that already invokes ct, and the hook is fail-open (anything it does not recognise, or any malformed input, is allowed silently). Beyond Bash, the hook can also gate the harness's own Grep/Glob/Read tools — Grep/Glob steer to ct search, Read to ct view (images/PDFs/notebooks pass through) — enabled per tool at install time. Subcommands: `hook` is the runtime hook — it reads a PreToolUse tool-call envelope on stdin and prints a decision JSON (`permissionDecision` deny/ask, or an `additionalContext` warn) on a match, nothing on a miss, always exiting 0 so it never fails the call on its own account; `--mode deny|ask|warn` (default deny) picks the action. `install`/`uninstall` merge or remove the PreToolUse steering hook in a Claude Code settings file (`--scope project|local|user`, default project → .claude/settings.json / .claude/settings.local.json / ~/.claude/settings.json; `--tools Bash,Grep,Glob,Read` (default Bash) chooses which tools to gate, one matcher entry each); the merge is idempotent and preserves the rest of the file — including comments and layout — because it edits through ct-patch's byte-range splices rather than reserialising, with `--dry-run` to show the resulting file and `--print` to emit just the snippet for manual paste. `check` classifies a command string and prints what the hook would decide, exiting 0 when the command is allowed and 1 when it would be steered. Invoke as `ct steer …` or `ct-steer …`.",
"input_schema": {
"type": "object",
"properties": {
"json": {
"type": "boolean",
"description": "Emit a structured JSON result instead of text where applicable (the install/uninstall outcome, or the check decision)."
},
"quiet": {
"type": "boolean",
"description": "Suppress informational output (exit status still reports)."
},
"timeout": {
"type": "number",
"description": "Abort with exit 2 if the run exceeds SECS seconds (fractional allowed)."
},
"heartbeat": {
"type": "number",
"description": "Print a liveness pulse every SECS seconds (fractional allowed) while running."
},
"heartbeat-emit": {
"type": "string",
"description": "Heartbeat line template. Tokens: {ELAPSED} {TOOL}. Default: \"[{ELAPSED}s]\"."
},
"heartbeat-to": {
"type": "string",
"enum": [
"stderr",
"stdout"
],
"description": "Stream heartbeat pulses are written to. Default: stderr."
}
}
},
"commands": [
{
"name": "hook",
"description": "Runtime PreToolUse hook: read a tool-call envelope on stdin, print a deny/ask/warn decision on a match (nothing on a miss). Handles Bash plus the harness Grep/Glob/Read tools. Always exits 0. --mode deny|ask|warn (default deny). --nudge-pipelines adds a warn-only (never deny) nudge against ANY shell pipeline the specific rules did not steer, prompting harder use of ct. Tool-call logging is ON by default: it appends one JSONL record per call — including the silent allows, the raw material for spotting un-steered idioms — to .ct/tclog/<yyyy-mm-dd>.jsonl under the nearest .ct (created if absent), and keeps a .ct/.gitignore '*log' rule so the logs stay out of git. Each record has event ('pre'), tool, command, cwd, session_id, decision, rule_id, ct_tool, ts_ms. --log-dir DIR (or CT_STEER_LOG) redirects the logs; --no-log disables them. Best-effort and fail-open."
},
{
"name": "post",
"description": "Runtime PostToolUse recorder: read a PostToolUse envelope on stdin and append a record of the call as it actually executed (event 'post', with tool, command, ct (whether the executed command used ct), cwd, session_id, ts_ms) to the same daily .ct/tclog log. Enables measuring whether steer guidance was followed — correlate a 'pre' steer decision with the follow-up 'post' call by session_id and time. Only observes; always exits 0. Shares --log-dir/--no-log with the hook. Wired by `install --measure`."
},
{
"name": "install",
"description": "Merge the PreToolUse steering hook into a Claude Code settings file. --scope project|local|user (default project), --mode deny|ask|warn, --tools Bash,Grep,Glob,Read (default Bash; one matcher per tool), --all-tools (a single '*' matcher, supersedes --tools; for full-coverage logging), --nudge-pipelines (bake the warn-only pipeline nudge into the hook), --measure (also install a PostToolUse '*' recorder running `ct steer post`, to measure whether guidance was followed), --log-dir DIR (bake a log-directory override; logging is on by default), --no-log (bake in disabling the default tool-call logging), --dry-run (show the file), --print (emit just the snippet). Before a real write, a preflight verifies the `ct` that will fire the hook can parse the armed command (subcommand + baked flags) — a hook the resolving `ct` rejects would clap-error and block tool calls; install REFUSES (exit non-zero, with a recovery hint) if that check fails. --force skips the preflight; --pin bakes THIS binary's absolute path into the hook (instead of resolving `ct` on PATH) so version skew or a missing `ct` can't break it. If a hook ever starts erroring, `ct steer uninstall` (which uses only stable syntax) clears it. Idempotent."
},
{
"name": "uninstall",
"description": "Remove the steering hook from a Claude Code settings file, pruning emptied entries. --scope project|local|user, --dry-run."
},
{
"name": "check",
"description": "Classify a COMMAND string and print what the hook would decide. Exit 0 when allowed, 1 when it would be steered. --mode affects the printed label; --json prints the decision JSON."
}
]
}
],
"builtin_checks": [
{
"name": "deps",
"description": "Built-in crate-graph check — a reserved probe head the rule layer runs in-process (not a standalone command). Asserts properties of the resolved dependency graph from one hermetic `cargo metadata --format-version 1 --locked --offline` invocation, with every violation carrying an evidence path. Use it as a rule probe (`ct rules --add ID --question … -- deps …`, verified by `ct check`) or prototype it without saving (`ct rules -- deps …`). It classifies its own outcome, so it takes no --expect adapter. Assertions (at least one required): --deny NAME (a crate reachable from any workspace member), --forbid 'A=>B' (package A reaches package B; A absent is broken), --duplicates (a crate at more than one version; --allow-duplicate NAME exempts low-level platform crates like windows-sys), --acyclic (any dependency cycle — Tarjan SCC; --members scopes it to the workspace-member subgraph, the actionable form), --layers L0,L1,... (ordered highest first, crate-name patterns; a lower layer must not reach a higher one, indirectly; --layers-closed flags members matching no layer). --edges normal,build,dev restricts traversed edge kinds (default all three). Outcome: holds (no violations), violated (with the evidence paths), or broken (no assertion, defective --forbid spec, empty --layers pattern, or cargo metadata failure).",
"input_schema": {
"type": "object",
"properties": {
"deny": {
"type": "array",
"items": {
"type": "string"
},
"description": "Violation if this crate is reachable from any workspace member (repeatable). Evidence: the shortest dependency path."
},
"forbid": {
"type": "array",
"items": {
"type": "string"
},
"description": "Violation if package A reaches package B, written 'A=>B' (repeatable, indirect). A must exist in the graph, else broken."
},
"duplicates": {
"type": "boolean",
"description": "Violation for every crate that resolves at more than one version, with the version list as evidence."
},
"allow-duplicate": {
"type": "array",
"items": {
"type": "string"
},
"description": "With --duplicates: crate names exempt from the duplicate check (comma-joined or repeated), for low-level platform crates like windows-sys that legitimately resolve at several versions."
},
"acyclic": {
"type": "boolean",
"description": "Violation for every dependency cycle among crates (Tarjan strongly-connected components). Honors --edges and --members; evidence is a concrete cycle path."
},
"members": {
"type": "boolean",
"description": "With --acyclic: restrict cycle detection to the workspace-member subgraph (the actionable form; third-party crate cycles are usually unfixable dev-dependency noise)."
},
"layers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ordered layers, highest first (comma-joined or repeated). Each entry is a crate-name pattern matched against workspace members; a layer may depend on layers listed after it, never before. Violation per offending member of a lower layer that reaches a higher one (indirectly). A pattern matching no member is broken."
},
"layers-closed": {
"type": "boolean",
"description": "With --layers: also report a violation for every workspace member that matches no layer (exhaustive assignment)."
},
"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."
}
},
"required": []
}
},
{
"name": "mods",
"description": "Built-in module-graph check — a reserved probe head the rule layer runs in-process (not a standalone command), the single-crate analogue of `deps`. Builds a heuristic module dependency graph from `use` statements over the crate source (the ct-outline honesty class: one module per source file; an edge A -> B when a file in module A has a `use crate::B…`/`self::…`/`super::…` resolving into module B; brace groups, aliases, globs, and `self` segments handled; it under-reports rather than inventing edges, and does not resolve pub-use re-export chains, macro/cfg-disabled code, or inline `mod {}` nesting). Use as a rule probe (`ct rules --add ID --question … -- mods …`, verified by `ct check`) or prototype with `ct rules -- mods …`. Classifies its own outcome, so it takes no --expect adapter. Targeting: --base DIR (crate source root, default src; module paths are crate-relative, e.g. src/domain/entity.rs is domain::entity), --name, --ext (default rs), --hidden, --follow. Assertions (at least one required): --forbid 'A=>B' (module A reaches module B, directly or transitively), --acyclic (any module-dependency cycle), --layers L0,L1,... (ordered highest first, module-name patterns — use domain* for a subtree; --layers-closed flags modules matching no layer). Outcome: holds, violated (with evidence paths), or broken (no assertion, defective spec, empty --layers pattern, or no source files).",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "The crate source root to walk; `crate::` resolves against it. Default: src."
},
"name": {
"type": "string",
"description": "Limit to files whose name matches; '|'-separated alternatives, promoted and anchored."
},
"ext": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extensions to include (no dots), e.g. ['rs']. May be comma-joined or repeated. Default: rs."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries; default skips them."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"forbid": {
"type": "array",
"items": {
"type": "string"
},
"description": "Violation if module A reaches module B, written 'A=>B' (repeatable, indirect). Module names match exactly."
},
"acyclic": {
"type": "boolean",
"description": "Violation for every module-dependency cycle (Tarjan strongly-connected components). Evidence is a concrete cycle path."
},
"layers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ordered layers, highest first (comma-joined or repeated). Each entry is a module-name pattern (use domain* for a subtree); a layer may depend on layers listed after it, never before. A pattern matching no module is broken."
},
"layers-closed": {
"type": "boolean",
"description": "With --layers: also report a violation for every module that matches no layer (exhaustive assignment)."
}
},
"required": []
}
},
{
"name": "okf",
"description": "Built-in OKF-conformance check — a reserved probe head the rule layer runs in-process (not a standalone command). Walks an Open Knowledge Format bundle under --base and asserts every non-reserved Markdown concept conforms to OKF v0.1: it opens with a parseable YAML frontmatter block carrying a non-empty `type`. Reserved files (index.md, log.md) need only have parseable frontmatter if any is present. Use as a rule probe (`ct rules --add ID --question … -- okf --base DIR`, verified by `ct check`) or prototype with `ct rules -- okf --base DIR`. Classifies its own outcome, so it takes no --expect adapter. Targeting: --base DIR (bundle root, default '.'), --name (limit by file name), --hidden, --follow. With --strict, a broken bundle-relative cross-link (a `/…` or document-relative link whose target file is missing) is also a violation. Outcome: holds (all concepts conform), violated (with the per-file reasons), or broken (the bundle base is missing, or a file could not be read).",
"input_schema": {
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Bundle root to check, relative to the project root. Default: '.'."
},
"name": {
"type": "string",
"description": "Limit to files whose name matches; '|'-separated alternatives, promoted and anchored."
},
"hidden": {
"type": "boolean",
"description": "Include dot-entries; default skips them."
},
"follow": {
"type": "boolean",
"description": "Follow symlinks while traversing."
},
"strict": {
"type": "boolean",
"description": "Also count a broken bundle-relative cross-link as a violation."
}
},
"required": []
}
}
]
}