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-jsondelegate schemadelegate 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¶
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 \ |
--domain <domain> |
The domain in one sentence; it is also the skill description. Required. |
--skill-only |
Write only \ |
--tier <tier> |
The tier of the agent: strong, standard or cheap; required, except with --skill-only. |
--skill <name> |
A preloaded skill; repeat it. \ |
--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 \ |
--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 \ |
--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:
- 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;
- 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, withgit branch -D, whatever it holds: the old work of a failed step is in no other branch; - 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;
- removes each crash traceback file (
crash-<seq>.txt) that astep-endof the run names and the disk still holds. A crash that a retry built over leaves it; - 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 averify-startnames inscratch, and each directory in the temp directory whose name starts withdelegate-verifier-<run id>-; - with
--merged, deletes the run branch when the base branch holds it, or when the default branch of the repository holds it, withgit branch -d(#267). The default branch is the local branch thatrefs/remotes/origin/HEADnames. 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 examplebase/<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,--mergedmakes 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:
- It appends
run-endto the journal of the run, with the resultabandoned, the listsbuilt,failedandskipped, and the new fieldreason. It also removes a pause request that waits in the directory of the run. - 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 fromcleanwith no--abandon. - 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.
- It keeps the run branch, and prints its name. With
--delete-run-branch, it deletes the run branch too. - It appends a
cleanupevent after therun-end, ascleandoes.
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¶
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 |