Skip to content

Reference: delegate render, schema, validate, bootstrap, brief, clean and stop

NAME
delegate-render, delegate-schema, delegate-validate, delegate-bootstrap, delegate-brief, delegate-clean, delegate-stop — render, validate and bootstrap agent pairs, print the schema of a declaration, print a verifier brief, clean up after runs, and stop a run
SYNOPSIS
delegate render <declaration> -o <out> [--opencode-model <tier>=<model>] [--opencode-allow <model>]
delegate render <declaration> --sets-json
delegate schema
delegate validate [<rendered>] [--claude-code <dir>] [--opencode <dir>] [--skills-dir <dir>] [--user-skills-dir <dir>] [--opencode-model <tier>=<model>] [--opencode-allow <model>]
delegate bootstrap --repo <repo> --name <name> --domain <domain> --tier <tier> --skill <name> --reference <path> [<option>...]
delegate brief full|fixup [<option>...]
delegate clean [<run-id>...] [--ended] [--merged] [--dry-run] [--repo <repo>]
delegate clean --abandon <run-id> --reason <text> [--delete-run-branch] [--repo <repo>]
delegate stop <run-id> [--repo <repo>]

These five subcommands of delegate take the arguments of the standalone commands agent-definitions (render, schema, validate, bootstrap) and verifier-brief (brief). The exit code, the output and the files written are the same for the two spellings: delegate render ... is agent-definitions render ..., and delegate brief ... is verifier-brief .... On a terminal, the delegate spelling also sets the title of the terminal to delegate <subcommand>, for example delegate render, and the standalone commands set no title. See the terminal title. After Ctrl-C, the delegate spelling prints delegate: interrupted on stderr and exits 130. The standalone commands do not catch Ctrl-C. The tables of options on this page are generated from the argument parsers by delegate docs. See delegate docs. delegate clean has no standalone command.

The skill agent-definitions holds the rules that the commands apply: the rendering rules, the tier table, and the rules of the verifier's shell.

Options before the subcommand

--version goes before the subcommand, also. delegate --version, agent-definitions --version and verifier-brief --version print the name of the command and the version of the package, for example delegate 1.16.0, and exit 0. The version comes from the version field of the pyproject.toml above the module when the package runs from a source tree, because a source tree can hold a stale metadata directory. An installed package has no such file, so it reads its package metadata. The release step changes only that field.

The help of each command (--help) ends with the address of the docs site and the title and the address of the reference page of the command. A coordinator that reads no page finds the page there.

--tiers goes before render, validate or bootstrap. schema takes it there too, and does not use it. Before brief, run, pause, stop, status, runs, watch, clean or docs, delegate refuses it and exits 2. delegate run takes its own --tiers after the subcommand. See the options of delegate run.

Option Meaning
--version Print the version of the package and exit.
--tiers <tiers> Path to a tiers.toml; default is the bundled table.

delegate render

delegate render <declaration> -o <out> [--opencode-model <tier=model>] [--opencode-allow <model>]
delegate render <declaration> --sets-json

render reads a declaration (TOML) and writes the agent files for each harness into <out>/claude-code and <out>/opencode. It prints the path of each file that it wrote, and exits 0.

With --sets-json in place of -o, render writes no file. It prints the command sets of the guard of each verifier as JSON, and exits 0. See the guard sets as JSON. Give -o or --sets-json, not both: else render exits 2.

Option Meaning
<declaration> The declaration file (TOML) to render. Required.
-o, --out <out> The output directory; it receives the subdirectories claude-code and opencode.
--sets-json Write no file; print the gate set, the free gates and the read set of each verifier as JSON.
--opencode-model <tier=model> Use MODEL for TIER in the OpenCode column; repeat it.
--opencode-allow <model> Add MODEL to the OpenCode allowed set; repeat it. It extends the set, never replaces it.

delegate schema

delegate schema

schema takes no argument. It prints the schema of a declaration as JSON, and exits 0 (#172). A consumer that declares agents in its own configuration language derives its list of keys from this output, or compares its list with it in a test, so a new key of the kit does not break its check by surprise. The output is one object:

{
  "version": 1,
  "keys": {
    "description": {"type": "string", "required": true, "default": null, "since": "0.1.0"},
    "contextLoad": {"type": "string", "required": false, "default": "blocks", "since": "1.8.0", "values": ["blocks", "read"]},
    "gateExtraFlags": {"type": "array", "required": false, "default": [], "since": "1.10.0", "items": "string"}
  }
}
Field Meaning
version The version of the format. It increases when a field changes its meaning or goes away. A new field does not change it.
keys One entry for each key of an agent in a declaration, with the name of the key as the name of the entry, in the order of the table below.
type string, integer, boolean or array.
required true when the parser refuses an agent without the key.
default The value that the parser uses when the key is absent. null for a required key and for a key with no value.
since The version of the kit that added the key.
items The type of each entry of an array key. Only an array key has it.
values The only values that the parser accepts for the key. Only a key with fixed values has it.

The keys of an agent, as the parser reads them:

Key Type Required Default Values Since
description string yes none 0.1.0
tier string no "standard" 0.1.0
skills array of string no [] 0.1.0
prompt string no "" 0.1.0
references array of string no [] 0.1.0
maxTurns integer no null 0.1.0
effort string no null 0.1.0
pair boolean no true 0.1.0
readOnly boolean no false 0.1.0
gateCommands array of string no [] 0.1.0
getOnlyCommands array of string no [] 0.1.0
outputLanguage string no "none" none, ste 0.1.0
trackedFileBuild boolean no false 0.1.0
contextLoad string no "blocks" blocks, read 1.8.0
gateExtraFlags array of string no [] 1.10.0

The command takes no declaration: the schema is the same for each one. To read the command sets of the guard of one declaration, use render --sets-json. To check a consumer mirror of the kit, compare it with the output of schema and the output of render --sets-json, not with the shell text of a rendered file.

delegate validate

delegate validate [<rendered>] [--claude-code <dir>] [--opencode <dir>] [--skills-dir <dir>] [--user-skills-dir <dir>] [--opencode-model <tier>=<model>] [--opencode-allow <model>]

validate checks rendered agent files against the schema of each harness. It prints one line for each finding, and then N finding(s) on stderr, and exits 1. It prints ok and exits 0 when there is no finding. With no directory to check it exits 2. See the finding codes.

Option Meaning
[<rendered>] A root with claude-code/ and opencode/ subdirectories.
--claude-code <claude-code> A directory of rendered Claude Code agents to validate.
--opencode <opencode> A directory of rendered OpenCode agents to validate.
--skills-dir <skills-dir> Check that every preloaded skill exists here.
--user-skills-dir <user-skills-dir> A second skills directory to search; default: ~/.claude/skills.
--opencode-model <tier=model> Use MODEL for TIER in the OpenCode column; repeat it.
--opencode-allow <model> Add MODEL to the OpenCode allowed set; repeat it. It extends the set, never replaces it.

With --skills-dir, validate also reads each skill that a Claude Code agent preloads, in --skills-dir and in --user-skills-dir, and checks each load-time block: a fenced block that opens with ```!. A block that holds $(, a backtick, ;, &&, a double pipe, a pipe, if or a redirection outside quotes gives the finding LOAD_BLOCK_NOT_PLAIN, with the file and the line. One plain command passes, for example sed -n '1,20p' docs/gates.md. A sign in single quotes is text, so grep -n -E 'a|b' docs/gates.md also passes. The rule comes from ADR 0006, docs/adr/0006-load-time-blocks-are-one-plain-command.md. A skill that carries the line <!-- agent-definitions:context-load read --> was written with contextLoad = "read", and each load-time block in it gives the finding LOAD_BLOCK_IN_READ_SKILL, with the file and the line, also when the block is one plain command.

delegate bootstrap

delegate bootstrap --repo <dir> --name <name> --domain <text> --tier <tier> --skill <name> --reference <path> [...]

bootstrap writes the context skill of a repository, its declaration, and the rendered pair. With --dry-run it prints each file with its content and writes nothing. With --skill-only it writes only <skills root>/<name>-context/SKILL.md: no declaration, no render and no agent file. --skill-only needs only --repo, --name, --domain, each --reference, --context-load and --skills-root; --tier, --skill and --prompt-file are not required with it. Use it to make the context skill current in a repository whose declaration holds a hand edit, for example after validate gives LOAD_BLOCK_NOT_PLAIN: run it with the options of the command in the header comment of the skill. --gate-extra-flag writes gateExtraFlags, one entry for each use, in the entry format of the declaration: --gate-extra-flag --noEmit and --gate-extra-flag '--project <value>'. The word after --gate-extra-flag is always its value, also when it starts with -. The header comment of each file that bootstrap writes holds each --gate-extra-flag, so that command gives the same declaration again. It exits 0 when it wrote the files, and 1 on a problem that the message on stderr names.

Option Meaning
--repo <repo> The repository root. Required.
--name <name> The agent name; the skill is \-context. Required.
--domain <domain> The domain in one sentence; it is also the skill description. Required.
--skill-only Write only \/\-context/SKILL.md: no declaration, no render, no agent file. It needs only --repo, --name, --domain, --reference, --context-load and --skills-root.
--tier <tier> The tier of the agent: strong, standard or cheap; required, except with --skill-only.
--skill <name> A preloaded skill; repeat it. \-context is added first. Required, except with --skill-only.
--reference <path> A read-first document; repeat it. A note may follow the backticked path. Required.
--prompt-file <file> The domain rules; the file body becomes the prompt.
--max-turns <n> The turn cap for both halves.
--gate-command <cmd> A gate the verifier may run, alone or with paths after it; end it with ' *' to permit each word after it, except a word that the shell can expand; repeat it.
--get-only-command <cmd> A command the verifier may run only without -X, alone or with arguments; repeat it.
--gate-extra-flag <flag> A read-only flag the verifier may put after a gate, in the entry format of gateExtraFlags: '--flag' or '--flag \'; the next word is always the value of this option; repeat it.
--output-language <language> The language of agent text: none | ste (ASD-STE100); default: write no field.
--tracked-file-build The build reads tracked files only, as a flake does; the specialist then stages every new file.
--context-load <mode> How the context skill loads its references: blocks | read (the Read tool, no load-time block); default: write no field.
--skills-root <skills-root> The skills directory under --repo that gets \-context/, and the --skills-dir of the validation pass; default .claude/skills.
--user-skills-dir <user-skills-dir> A second skills directory to search; default: ~/.claude/skills.
--dry-run Print every file with its content and write nothing.

Each load-time block of the context skill is one plain command. A block with $(...), ;, if or a pipe stopped a subagent from starting with each of the --permission-mode values default (manual), acceptEdits and auto, measured on Claude Code 2.1.283 on 2026-09-26. No Claude Code documentation states this rule: it is a measured behaviour. ADR 0006, docs/adr/0006-load-time-blocks-are-one-plain-command.md, records the measurements and their source. See the decision records. The context skill carries the same note.

With --context-load read, the declaration gets contextLoad = "read", and the context skill has no load-time block. Its first instruction tells the agent to read each reference with the Read tool before any other step, in the order of the references, and to stop and report when a reference is missing. Use it on a host where a load-time block cannot run. --context-load blocks writes contextLoad = "blocks" and the skill of the default. Any other value exits 1 and names the permitted values, blocks and read. Without the flag, the declaration holds no contextLoad key, and the files are the same bytes as before the flag existed.

delegate brief

delegate brief full --repo <dir> --branch <branch> --task <text> [--base <base>] [--stack <heading>]
delegate brief fixup --repo <dir> --branch <branch> --rejected <commit> --findings <file> [--authorised <text>] [--stack <heading>]

brief prints the brief of a verifier. The shape of the brief sets the mode of the verifier: full is a first pass, and fixup is a scoped pass over the delta since the rejected commit. It exits 0. It exits 1, and names the cause on stderr, when git or a file cannot be read, when the diff or the fix-up delta is empty, when the rejected commit is not an ancestor of the branch, or when a --stack heading names no gate block. It exits 2 on a usage error.

brief full

Option Meaning
--repo <repo> Path to the repository or worktree. Required.
--branch <branch> The branch under verification. Required.
--base <base> The base of the three-dot diff; default main.
--task <task> The task text, or @PATH to read it from a file. Required.
--stack <heading> Select the gate block under this sub-heading of "Verification gates"; it overrides the path match; give it again for a second block.

brief fixup

Option Meaning
--repo <repo> Path to the repository or worktree. Required.
--branch <branch> The branch that holds the fix-up commit. Required.
--rejected <rejected> The commit the first verifier rejected. Required.
--findings <findings> Path to the first verifier's findings. Required.
--authorised <authorised> Additions the coordinator authorised beyond the findings.
--stack <heading> Select the gate block under this sub-heading of "Verification gates"; it overrides the path match; give it again for a second block.

delegate clean

delegate clean [<run-id>...] [--ended] [--merged] [--dry-run] [--repo <repo>]
delegate clean --abandon <run-id> --reason <text> [--delete-run-branch] [--repo <repo>]

clean removes what ended runs left behind: the worktree of each ticket, the ticket branches, and the temporary copies of a verifier. A run that ends built removes its worktrees and its ticket branches itself, and keep-worktrees = true turns that off. See the clean-up. clean does the same for a run that ended before that clean-up existed, or that kept its worktrees.

clean takes run ids, --ended, or both. A run id is the run id or the short run id. --ended selects each run of the repository. With no run id and no --ended, the command exits 2.

A run is cleaned only when the newest run-end of its journal after its newest resume has the result built, and no live process holds the lock of its run branch. A run that is active, failed, paused or stopped keeps everything. For each run that is cleaned, the command:

  1. stops the file watcher of each ticket worktree, and removes each worktree that has no change that is not committed, with its push-guard hooks;
  2. deletes each ticket branch that the run branch holds, with the safe delete of git (git branch -d). The branch of a worktree that stays, stays too. It also deletes each branch <branch>-failed-<n> that a retry with a new text kept, with git branch -D, whatever it holds: the old work of a failed step is in no other branch;
  3. removes each verifier copy and proof copy that the journal names and the disk still holds. A run process that was killed during a verifier leaves them;
  4. removes each crash traceback file (crash-<seq>.txt) that a step-end of the run names and the disk still holds. A crash that a retry built over leaves it;
  5. removes the scratch directory of the run, runs/<run id>/scratch/, which holds the scratch directory of each specialist and fix-up session (#227), and each scratch directory of a verifier that a kill left in the temp directory (#294): each directory that a verify-start names in scratch, and each directory in the temp directory whose name starts with delegate-verifier-<run id>-;
  6. with --merged, deletes the run branch when the base branch holds it, or when the default branch of the repository holds it, with git branch -d (#267). The default branch is the local branch that refs/remotes/origin/HEAD names. When the repository has no such ref, it is the branch that the main checkout holds. The default branch is needed for a stacked run, whose base branch is the run branch of an earlier run that the command deleted already, and for a fixed base branch (for example base/<milestone>) that never moves. A base branch that does not exist holds nothing, and it is no error. When neither branch holds the run branch, it stays, and the line names each branch that the command checked. When the run branch is gone already, --merged makes the base branch the holder of the ticket branches, and the default branch holds them too. Without --merged, the run branch stays.

The command holds the lock of the run branch while it cleans a run, so a resume cannot start then. Before it cleans the runs, and again at the end, it runs git worktree prune: git refuses to delete the branch of a worktree whose directory is gone while it still records that worktree. It takes the lock as a run does: a lock file that no process holds is free (#288). When that file names an old holder, the journal of the run gets lock-broken first, with the run id and the process id of the old holder, as for a resume that takes over a lock (#207). The journal of each run where something went gets one cleanup event after its run-end, with the fields of the clean-up, copies_removed, tracebacks_removed, scratch_removed, and bytes_freed. delegate watch and delegate status read a cleanup after run-end as part of a run that ended.

The command prints one line for each run: the worktrees removed, the branches deleted, the verifier copies removed, the crash tracebacks removed, each item kept with its reason, the scratch directories removed, and the space freed. A run that it does not clean gets the line run <run-id>: not cleaned: <reason>, and a run with nothing left gets run <run-id>: nothing to remove. With --dry-run, the command changes nothing: no file, no branch, no journal and no lock. Each line then says what the command would remove and keep.

The command forgets the record of each run that it cleans in the run index of this machine (see the run index), so delegate runs on another host lists it no more (#317, #323). A run that it does not clean keeps its record, and --dry-run forgets none. A record that cannot be forgotten is an error of the run.

The command exits 0 when it removed or kept each item by these rules. It exits 1 on an error: a run id that names no run, a journal that cannot be read, or a removal that git refused. Each error is a line on stderr. The command still cleans the other runs.

Abandon a run

clean --abandon <run-id> --reason <text> ends a run that is not built, for good, and removes what it left. The run is paused, halted, failed, or stopped with no run-end, and no live process works on it. The reason is required: without --reason, the parser exits 2. --abandon takes no other run id, and it cannot be used with --ended, --merged or --dry-run. --reason and --delete-run-branch need --abandon.

The command holds the lock of the run branch, so a resume cannot start then. It does these steps in this order:

  1. It appends run-end to the journal of the run, with the result abandoned, the lists built, failed and skipped, and the new field reason. It also removes a pause request that waits in the directory of the run.
  2. It removes the worktree of each ticket that the run started, with its push-guard hooks, and deletes the ticket branch. It does this also when the worktree has a change that is not committed, or when the run branch does not hold the branch, with git branch -D. The work that no other branch holds is lost. This is the difference from clean with no --abandon.
  3. It removes each verifier copy and proof copy that the journal names and the disk still holds, the scratch directory of the run, and each scratch directory of a verifier of the run that a kill left.
  4. It keeps the run branch, and prints its name. With --delete-run-branch, it deletes the run branch too.
  5. It appends a cleanup event after the run-end, as clean does.

The command forgets the record of the run in the run index after the removal (#317). An error of the configuration file stops delegate clean with exit 1 before it changes anything (#323).

The command prints the line run <run-id>: abandoned: <reason>, then the line of what it removed, then the line of the run branch. It exits 0 when it removed each item. It exits 1 on an error: a run id that names no run, a journal that cannot be read, or a removal that git refused. Each error is a line on stderr. The run-end is written already when a removal fails. A second call with the same run id writes no second run-end: it removes what is left.

The command takes the lock as a run does: a lock file that no process holds is free (#288). When that file names an old holder, the command appends lock-broken before the run-end, with the run id and the process id of the old holder (#207). The command exits 1 and changes nothing in two cases, apart from that event. A live process works on the run, or holds the run branch for another run: the message names delegate stop <run-id>. The run ended built: the message names delegate clean.

delegate status shows an abandoned run with the state abandoned and the note abandoned: <reason>. The live view of delegate watch shows the reason on the line run abandoned. delegate run --resume refuses the run and exits 1, also with --retry or a change of the tickets. A later delegate clean of the run prints not cleaned and the reason.

Option Meaning
[<run-id>] A run to clean: the run id or the short run id; give more than one to clean more.
--ended Clean every run whose newest run-end has the result built.
--merged Also delete the run branch of each cleaned run when the base branch or the default branch holds it.
--dry-run Print what the command would remove and keep, and change nothing.
--abandon <run-id> End the run for good: it is paused, halted, failed or stopped, and no process works on it; write run-end with the result abandoned, then remove its worktrees, ticket branches and hooks, and keep the run branch; needs --reason.
--reason <reason> With --abandon, the reason: the text goes to the journal of the run and to delegate status.
--delete-run-branch With --abandon, also delete the run branch.
--repo <repo> The git repository that holds the runs; default is the current directory.

delegate stop

delegate stop <run-id> [--repo <repo>]

stop stops a run now, and leaves it in a state that delegate run --resume goes on from. delegate pause stops a run at its next step boundary, and that can be many minutes away. stop does not wait for a boundary, so it can cut off an agent or a gate.

The command reads the lock of the run, and sends SIGTERM to the process that holds it. It sends the signal only while a process holds the kernel lock of the lock file, and only to the process id that the file names (#288). A lock file that no process holds can name a process id that the system gave to another process, so it gets no signal. See the run lock. The run handles SIGTERM as Ctrl-C: it ends the process group of its running child, writes interrupted in the journal, and releases the run lock. See SIGTERM and SIGHUP. The run id is the run id or the short run id.

The command waits up to 30 seconds for the lock to be free. It then prints two lines on stdout, run <run id>: stopped and go on with delegate run --resume <run id>, and exits 0. When a process still holds the lock at the end of the wait, the command prints a line on stderr that names the process, and exits 1. The signal is sent already, so look at the run with delegate status.

The command sends no signal and exits 1 with the reason for a run that has no live process that holds its lock: a run that ended, a run that is paused, a run whose process stopped already, and a run that does not exist. For a run that is paused or stopped, the reason gives the command that goes on with it.

Option Meaning
<run-id> The run to stop; it must have a live process. Required.
--repo <repo> The git repository that holds the run; default is the current directory.

The verifier guard

On Claude Code, render writes two guards into each verifier: a guard on Bash and a guard on the Write tool. Together they permit the commands and the writes in the table below, and no other. The rules that apply to the commands, the gate commands of a repository and the limits of the guard are in the skill.

Group Commands
git reads git diff, git log, git show, git grep, git status, git ls-files, git ls-tree, git rev-parse, git merge-base, git worktree list, git branch --show-current
shell reads ls, cat, head, tail, sed -n, grep, rg, find, wc, diff, jq, shasum, stat, readlink, file, which, env, pwd, echo, printf, date, mktemp, python3, bash -c
temp writes mkdir, mv, rm, tee, touch — each one only when every path argument starts with /tmp/, /private/tmp/, $TMPDIR, /var/folders/, or /private/var/folders/. A redirection target obeys the same rule, in every segment, but it can also be exactly /dev/null, which writes no file: 2>/dev/null is permitted. A relative path counts from the working directory of the hook, as the path of a cd does: in a temp copy with no .git entry, touch app/x is permitted.
temp destination cp, cd — each one only when the last path argument is a temp path. The earlier path arguments are sources, and a read of any path is a read. A cd takes one path argument, and it may also go to a directory in the git toplevel of the working directory, with no .. component: cd api && ./gradlew test.
Write tool Write — only when file_path is an absolute path that starts with /tmp/, /private/tmp/, /var/folders/, or /private/var/folders/, or with the safe value of $TMPDIR in the environment of the hook and a /, and has no .. component.
runtime $TMPDIR The Bash guard and the Write guard also accept a path that starts with the value of $TMPDIR in the environment of the hook and a /, for example a directory from mktemp -d. The two guards use the same rule. The value counts only when it is safe: an absolute path with at least two components, with no empty, . or .. component, that is not the home directory or a parent of it, and that is not inside a git tree. Otherwise only the fixed prefixes count. A safe value with a /private prefix also gives its short form, when the short form has at least two components: with TMPDIR=/private/var/tmp/x, the guards accept /private/var/tmp/x/f and /var/tmp/x/f, and a relative path from that directory (#300). A path under the value obeys each other rule of a temp path. The OpenCode maps cannot follow this value.
git trees No temp write, no cp destination, no redirection target, no output path and no Write may be inside a git tree, or hold one. A git tree is a directory that holds a .git entry: the git toplevel of the working directory of the hook, and each directory with a .git entry above a write target or in it. The working directory is the cwd of the hook input, or else the working directory of the process. The guards compare the paths after they remove a /private prefix on both sides, so a worktree in a temp directory stays read-only. A cd may go to the git toplevel of the working directory.

A cd writes nothing, so it may go to a temp path or to a directory in the git toplevel of the working directory. Many repositories give their gates in the form cd <dir> && <gate>: with the gate ./gradlew test, cd api && ./gradlew test is permitted. A cd takes one path argument. A relative path must have no .. component, and an absolute path must be the toplevel or a path in it. The guard denies a path that starts with ~ or =, and a path with *, ?, [, { or $. So cd ../outside, cd /etc, cd api/../.. and cd ~ are denied. Each later segment is tested on its own, so cd api && echo x > f stays denied: after a cd in the same command, a relative write target is not a temp path. With no git toplevel above the working directory, only a temp path is permitted. The rule reads text, so a symbolic link in the tree, a CDPATH of the shell, or a directory with its own .git entry can take the working directory out of the tree. The guard still denies each write outside a temp directory.

A segment that starts with docker compose loses each -f <file> and --file <file> that comes directly after it, as a segment that starts with git loses -C <path>. With the gate docker compose config, docker compose -f compose.yml config is permitted. The subcommand after the options is still tested, so docker compose -f x.yml up and docker compose -f x.yml run app sh stay denied.

A segment that starts with env loses env and its options -i, -0, -u <name>, - and --, and the guard tests the rest as its own command, with every rule (#158). So env touch <file>, env -i rm <file> and env bash -c '<cmd>' are denied, and env, env -0 and env | grep PATH are permitted. A bare env, or env with only options and NAME=value assignments, is a read. An assignment before a command is denied, as an assignment prefix without env is: GIT_EXTERNAL_DIFF=touch makes git diff write files, and GIT_CONFIG_* and PATH can do the same. The guard also denies each other option of env (-S runs a string as a command, -C changes the directory), a word before the command with a quote, a backslash, an expansion or a pattern character, and bash -c or python3 after env.

Three read commands of the table can run a command or write a file, so the guard examines their words (#158). After find, it denies -exec, -execdir, -ok, -okdir, -delete, -rm, -fprint, -fprint0, -fprintf and -fls. After rg, it denies --pre and --hostname-bin, in each form. sed -n is permitted only as a line range: sed -n '<start>,<end>p' <path>, with digits, $ as the last address in single quotes, and paths with no option, quote, backslash, expansion or pattern character. A sed script can run a command (the GNU e command) or write a file (w), and -i edits a file in place, so the guard denies each other form of sed -n. To search for a pattern, use grep. Commands that run another command and are not in the table, such as xargs, nice, nohup, timeout, time, command and exec, are denied.

Two more read commands of the table can write a file, so the guard examines their words (#161). mktemp makes a file, and the guard permits it only when the file is in a temp directory: with no template (mktemp, mktemp -d), with -t and one name with no / (mktemp -d -t x), with -p <dir>, --tmpdir or --tmpdir=<dir> where <dir> is a temp path and each name has no / (mktemp -p /tmp x.XXXXXX), or with templates that are temp paths (mktemp /tmp/x.XXXXXX). It denies each other form, for example mktemp /Users/x/fXXXXXX, mktemp -p /Users/x and mktemp fXXXXXX in a git tree. macOS mktemp makes one more file for each template, in the working directory, also with -t, so -t permits one name only. After -p, --tmpdir or -t, mktemp makes the template in that directory or in the system temp directory, not in the working directory, and macOS mktemp puts also an absolute template after the directory of -p. GNU mktemp and macOS mktemp read these options also after a template. So when one of them is in the command, the guard denies each template with a /, for example mktemp -p /tmp/par wt/fXXXXXX and mktemp -t sub/f: the / can go into a git tree in that directory. A file of mktemp in a git tree is denied, also when the tree is in a temp directory. After file, the guard denies -C and --compile, also in a cluster of short options such as -bC, because they write a compiled magic file. file without them is a read.

A redirection with & must go to a file descriptor, not to a file. The guard permits >& and n>& only when the word after the & is a file descriptor number or -: 2>&1, >&2, >&1 and >&- are permitted. With another word, bash, /bin/sh and zsh write the output to a file of that name, so the guard denies ls >&src/out, ls >& out, cat x >& rm -rf src and ls 2>&out. It denies each >>&, because zsh then appends to a file, also with a number. A segment that ends at a redirection sign is also denied: in ls >|cat and ls >&|cat, the shell writes the file cat. The guard reads a quoted search pattern as text too, so it also denies grep -F '2>&1' src. To search for the text 2>&1, write a . in place of the >: grep -n '2.&1' src. The guard divides a segment into words at spaces, also inside quotes, so in bash -c "ls 2>&1" the word after the & is 1". A quote there can make the target a file name, as in ls >&1")", which writes the file 1). So the guard denies the word, and its message tells the agent to put a space before the closing quote: bash -c "ls 2>&1 " is permitted under bash, /bin/sh and zsh.

Each guard keeps the verifier read-only on the tree under review and on each other git tree, also when the tree is in a temp directory. On macOS, a worktree from mktemp -d is under /var/folders, which is a link to /private/var/folders. A git tree is a directory that holds a .git entry: a directory, or a file that points to a git directory. The guard finds the git toplevel of its working directory: the nearest directory, from the working directory up, that holds a .git entry. It also looks for a .git entry from each write target up, and in the directory that the target names (#125), so a verifier whose working directory is a copy with no .git entry cannot write into the original tree. It reads the file system in the python3 process that it starts to read the hook input, so it starts no git process. The walk in a directory reads at most 2000 directories. When it stops at that limit, a target that is the directory or holds it is denied, because the guard cannot tell that the directory holds no git tree. The Bash guard then denies each temp path that is inside a git tree, or that holds one, as a write target: cp /tmp/x <file>, echo x > <file>, tee <file>, rm <file>, mkdir <dir> and touch <file> are denied, and so is rm -rf of a directory that holds a git tree. Before it compares, it reads the path as the shell will: it removes each quote and backslash, puts the value of $TMPDIR in place of a leading $TMPDIR, and makes each // and /./ one /. For a path with a pattern or an expansion character (*, ?, [, { or $), only the text before the first such character counts. The Write guard denies a file_path inside a git tree, or that holds one, in the same way. A write to another temp path stays permitted, so a verifier can still copy the tree into a temp directory, remove the .git entry of the copy in the same command, and change the copy. The working directory of a delegate run verifier is the temporary copy of the engine, and it writes its verdict beside the copy, not in it. For a red proof, the engine makes the proof copy beside the temporary copy, with no .git entry, and the verifier goes to it with cd (#153). A verifier outside a delegate run makes its own copy: the copy and the removal of the .git entry of the copy are one command from the working directory, cp -R <tree> /tmp/x && rm -r /tmp/x/.git, and the cd /tmp/x comes after it. A copy that holds a .git entry is a git tree, so the guard denies the removal of that entry in a later command.

The guard does not parse a nested shell. So the rendered verifier states a rule that the guard does not enforce: a command that the guard refuses is not run in another form, through bash -c, python3 -c, sh -c, env, xargs or a script file. The verifier reports the refusal in unverified, with the command and the message of the guard. See the enforcement model and its limits.

The verifier writes its verdict with the Write tool. On Claude Code the verifier lists Write in tools, and a PreToolUse hook on Write reads tool_input.file_path with python3. The hook permits the Write only when the path is absolute, starts with a temp prefix of the table or with the value of $TMPDIR in its environment, has no .. component, is not inside a git tree, and does not hold one. Only a safe $TMPDIR adds a prefix, by the rule of the row "runtime $TMPDIR" in the table, and the Bash guard uses the same rule (#166). A $TMPDIR that is /, the home directory, a parent of the home directory, or a directory inside a git tree adds no prefix. The hook denies a path in the repository, a relative path, and a path with a $, because the Write tool does not expand a variable. Each deny exits 2, and the message names the path. With no python3, or with no file path in the input, the hook fails closed. The hook carries the marker # agent-definitions:verifier-write-guard, which the validator looks for.

On OpenCode the edit permission covers the write, edit and patch tools. OpenCode matches an edit rule against the path relative to the worktree, and an external_directory rule against the absolute parent directory of a path outside the project. The verifier gets an edit map that opens with "*": deny and allows only ../*, a path outside the project, and an external_directory map that opens with "*": deny and allows only /tmp/*, /private/tmp/*, /var/folders/* and /private/var/folders/*. An OpenCode pattern holds no variable, so $TMPDIR is not in the map. On a host whose $TMPDIR is not under one of these prefixes, the two harnesses permit different paths: Claude Code permits a write to $TMPDIR, and OpenCode denies it. OpenCode denies each edit of a path in the project, and the project is the git toplevel of the working directory, so a worktree in a temp directory stays read-only there too, when the path has the spelling of the real path. OpenCode takes the real path of the project, with each symbolic link resolved, and compares it as text with the path that the agent gives. A path through a link to the project is outside the project as text, so the two maps allow it. Measured on OpenCode 1.15.10 on 2026-10-19 on macOS: in a repository at /var/folders/<x>/copy, the write tool wrote a file of the tree through /var/folders, and it denied the same file through /private/var/folders and through a relative path. An OpenCode pattern holds no variable that names the project, so no rule of the maps can deny that spelling, and the rendered OpenCode verifier states this limit. The verifier stays read-only on the repository and the worktree in both harnesses, except for this OpenCode limit.

The OpenCode bash map of the verifier is smaller than the table. It has no echo rule, no printf rule, no env rule, no temp-write command and no GET-only command. It ends with the deny rules *>*, *| tee * and *|tee *, so it also denies 2>&1 and 2>/dev/null. A redirection after a group, a subshell, a loop or the last command of a pipeline is not in the text that OpenCode matches, so no rule can deny it. See the permission rules.

The renderer writes mode: all for each OpenCode agent (#214). opencode run --agent <name> refuses an agent with mode: subagent: the harness writes a warning, runs its default agent, and exits 0, so the prompt and the permission map of the agent do not apply. With mode: all, the agent works with opencode run and as a subagent of a coordinator. validate gives the finding SUBAGENT_MODE for an OpenCode agent file with mode: subagent, and it checks each directory that the command gets. See the OpenCode adapter.

The guard sets as JSON

The shell text of the guard is no interface. Its form can change in each release: v1.14.0 changed the branch of each gate and each read command (#173, #175), and a check that read the gates from the text with a regular expression found no gate. To read the command sets of a guard, use render --sets-json (#237). It reads the declaration, writes no file, and prints one JSON object:

{
  "version": 1,
  "agents": {
    "app-verifier": {
      "gates": ["make test", "./gradlew"],
      "freeGates": ["./gradlew"],
      "reads": ["gh issue view", "tea issues list"],
      "readPrefixes": ["tea issues list"]
    }
  }
}
Field Meaning
version The version of the format. It increases when a field changes its meaning or goes away. A new field does not change it.
agents One entry for each rendered verifier, with the name of the verifier as the key. An agent that renders no verifier has no entry.
gates Each entry of gateCommands: a plain gate, a gate that takes free arguments, and an exact gate.
freeGates Each gate that ends with * in the declaration, and so takes free arguments (#169).
reads Each entry of getOnlyCommands.
readPrefixes Each read command that ends with * in the declaration, and so is a prefix (#164).

Each list keeps the order of the declaration. Each entry is the words of the command, with no * at the end. To check a committed pair, render its declaration with --sets-json, and compare the sets with the sets that the check expects.

The finding codes

validate writes one line for each finding: the code, the file, and a message. A finding about one line of a file gives the file as <file>:<line>. The code is one of these.

Code Meaning
UNKNOWN_KEY a frontmatter key the harness does not recognise; inert on Claude Code, swept into provider options on OpenCode
BAD_MODEL model not in the tier table's allowed set for that harness
BAD_EFFORT Claude Code effort outside the levels, or OpenCode variant outside the variants
MISSING_TWIN a -specialist without its -verifier, or the reverse
DUPLICATE_NAME two files declare one name; the harness picks one by filesystem read order
VERIFIER_WRITE_TOOL a verifier lists Edit, MultiEdit, NotebookEdit, an unguarded Bash, or a Write with no PreToolUse hook on Write whose command carries # agent-definitions:verifier-write-guard; on OpenCode it permits a write tool with allow or ask, except an edit map that opens with "*": deny and allows only patterns that start with ../, beside an external_directory map that opens with "*": deny and allows only temp prefixes; or its bash map does not open with "*": deny, or that map resolves a write command to allow
VERIFIER_BASH_UNGUARDED a Claude Code verifier lists Bash with no PreToolUse hook on Bash whose command carries # agent-definitions:verifier-guard
RULE_SHADOWED an OpenCode permission rule placed before "*" in the same map; the last matching rule wins, so it does nothing
VERIFIER_NOT_READONLY a Claude Code verifier with no tools allowlist; an OpenCode verifier whose first rule is not "*": deny
SPECIALIST_CAN_PUSH a -specialist with no push guard: on Claude Code no PreToolUse hook that selects Bash and names push; on OpenCode no permission.bash deny that covers git push. A deny that the catch-all shadows does not count
BAD_FRONTMATTER frontmatter absent on line 1, unclosed, or not YAML
NAME_INVALID a name that starts with a hyphen or holds a character outside letters, digits, hyphen and underscore, so the harness would skip the file
MISSING_NAME a Claude Code file with no name; the harness treats it as documentation
MISSING_DESCRIPTION a name with no description; the harness skips the file, and OpenCode needs a description for routing
SUBAGENT_MODE an OpenCode agent with mode: subagent; opencode run --agent refuses a subagent and runs its default agent, so the engine cannot start the agent. Use mode: all
BAD_TYPE OpenCode tools as a string; that aborts config load for the whole session
CROSS_HARNESS_MISMATCH an agent present for one harness and absent for the other
MISSING_SKILL a preloaded skill absent from --skills-dir
DESCRIPTION_BUDGET combined Claude Code descriptions exceed the budget in tiers.toml
LOAD_BLOCK_NOT_PLAIN a load-time block (```!) of a preloaded skill holds, outside quotes, $(, a backtick, ;, &&, a double pipe, a pipe, if or a redirection; Claude Code cannot analyse the command, so a subagent that preloads the skill does not start (ADR 0006). The finding gives the file and the line
LOAD_BLOCK_IN_READ_SKILL a preloaded skill that carries <!-- agent-definitions:context-load read --> (a context skill with contextLoad = "read") holds a load-time block (```!); that skill must read its references with the Read tool only. The finding gives the file and the line

Version main