agent-definitions
Render a specialist-verifier agent pair for Claude Code and OpenCode from one declaration, and validate rendered agent files against each harness's real schema. Use when adding or changing a global agent declaration, when the agent-delegation bootstrap emits a repo's project agents, or when an agent file needs checking.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agent-definitions
- description
- Render a specialist-verifier agent pair for Claude Code and OpenCode from one declaration, and validate rendered agent files against each harness's real schema. Use when adding or changing a global agent declaration, when the agent-delegation bootstrap emits a repo's project agents, or when an agent file needs checking.
02 资源文件 1
- 参考文档neutrality-allowlist.txt680 B
03 SKILL.md 正文
Agent definitions
One declaration, two harnesses, two files each. A pair is a specialist and a verifier that share a domain, skills, and references. The verifier is read-only and runs on the verifier tier. Neither half is hand-written.
The decisions that shaped the design are ADRs in docs/adr/. The harness facts come from the vendor documentation, read on 2026-09-19: the Claude Code subagent docs, the OpenCode agent docs, and the OpenCode config schema at https://opencode.ai/config.json. Codex is out of scope.
What a declaration is
[agents.java-spring]
description = "Spring Boot backend work: controllers, services, JPA, transactions, RFC 7807 errors."
tier = "standard" # strong | standard | cheap; the verifier half always uses the verifier tier
skills = ["clean-ddd-hexagonal", "api-design-principles", "tdd", "test-quality"]
maxTurns = 60 # optional
references = ["docs/architecture.md"] # optional read-first paths, listed in the body
prompt = "Domain notes the agent needs."
# effort = "high" # optional. Omit it. See "Effort" below.
# pair = false # a single agent instead of a pair
# readOnly = true # with pair = false: render the single agent as a verifier
# gateCommands = ["npm test", "./gradlew *"] # optional: the gates the verifier may run; " *" = free arguments (see "Gate commands")
# gateExtraFlags = ["--reporter", "-t <value>"] # optional: read-only flags the verifier may put after a gate (see "Gate commands")
# getOnlyCommands = ["./scripts/api"] # optional: commands the verifier may run only without a method, body or output flag, and with no subcommand after them (see "Gate commands")
# outputLanguage = "ste" # optional: "none" (the default) or "ste" (see "Rendering rules")
# trackedFileBuild = true # optional: the build reads tracked files only, as a flake does (default false)
# contextLoad = "read" # optional: "blocks" (the default) or "read"; how bootstrap writes the context skill (see "Bootstrap")
The full example is examples/java-spring.toml in the repository.
Commands
agent-definitions render examples/java-spring.toml -o /tmp/agents
agent-definitions validate /tmp/agents --skills-dir skills
render writes <out>/claude-code/<name>.md and <out>/opencode/<name>.md. validate exits 1 with one line per finding, or prints ok. Validate any directory of agent files, rendered or hand-written: --claude-code DIR, --opencode DIR.
The shell text of the verifier guard is no interface: its form changes between releases. To read the gate set, the free gates and the read set of each verifier, run agent-definitions render DECL --sets-json. It writes no file and prints JSON with a version field. The fields are in the reference.
To read the keys of a declaration, run agent-definitions schema. It prints JSON with the type, the requirement, the default and the first version of each key (the reference). delegate schema prints the same JSON. Check a consumer mirror of the kit against schema and render --sets-json, not against the shell text of a rendered file.
render and validate take two more optional flags, both repeatable, that override the OpenCode column of the tier table (ADR 0003).
agent-definitions render DECL -o /tmp/agents \
--opencode-model strong=gateway/claude-opus-5 \
--opencode-allow gateway/claude-opus-5
| Flag | Effect |
|---|---|
--opencode-model TIER=MODEL |
TIER uses MODEL in the OpenCode column. A tier left out keeps its tiers.toml value, and the Claude Code column never moves. An unknown tier name stops the command |
--opencode-allow MODEL |
adds MODEL to the OpenCode allowed set. It extends the set; the defaults stay allowed |
Give both, or the render carries a model the validator reports as BAD_MODEL. They are separate on purpose: a tier map that widened the allowed set by itself would accept whatever it named, so an override onto a model that no provider serves would stay green.
Use them where the provider is not the one tiers.toml names. OpenCode resolves a model through a provider, and a provider can belong to a job or a machine, while the tier table is global. The caller is therefore the configuration that sets up the provider, for example a work profile. When that configuration is off, the caller passes neither flag, and the defaults come back. bootstrap does not take these flags, because it writes a committed render that carries the defaults. Pass neither flag and every command behaves as it did before.
The same package ships a second command, verifier-brief. It prints a verifier's brief on stdout. The subcommand bootstrap of agent-definitions writes the agent set of a whole repository; the next section documents it.
<!-- not-a-command -->
verifier-brief full --repo PATH --branch NAME [--base main] --task 'TEXT or @FILE' [--stack HEADING ...]
verifier-brief fixup --repo PATH --branch NAME --rejected SHA --findings FILE [--authorised TEXT] [--stack HEADING ...]
| Mode | Sections it prints |
|---|---|
full |
## Task, ## Diff (git diff <base>...<branch>, three-dot), ## Gates |
fixup |
## Findings under verification (the file, verbatim), ## Coordinator-authorised additions (only with --authorised), ## Delta (git diff <rejected>..<branch>), ## Gates |
The gates come from docs/agents/delegation.md in the repository's working tree. Both modes use the same selection. The selection exists because the first block is not always the correct block: in a monorepo, a brief for a docs-only change once carried the backend test suite.
- One block for each stack. A sub-heading under the "Verification gates" heading that names a path in backticks claims that path, for example
### Backend (`api/`). The block of a sub-heading is the first fenced block before the next heading. A path claims the file of that name and each file below it as a directory:api/claimsapi/Main.java, notapiary/x. - The changed files decide. The brief carries each block that claims a changed file, in the order of the doc, each under its own
###heading.fullreads the changed files fromgit diff --name-only <base>...<branch>, andfixupreads them from the delta,git diff --name-only <rejected>..<branch>. --stack HEADINGoverrides the path match. It selects the block under that sub-heading. The name is compared without backticks, so--stack 'Backend (api/)'selectsBackend (`api/`). A sub-heading that claims no path, such as "Contract drift", is selected only this way. Give the flag again for a second block. An unknown name exits 1 and names the known headings.- A change that no block claims gets a placeholder line that tells the verifier to ask the coordinator for the gates. It never gets the first block, because the first block belongs to another stack.
- A doc with no path claim keeps the earlier behaviour, byte for byte: the first fenced block under the "Verification gates" heading. A repository without that document, that heading, or that block gets a placeholder line instead.
Exit conditions. full exits 1 when the three-dot diff is empty. fixup exits 1 when the rejected commit is not an ancestor of the branch tip, which means the specialist amended or rebased, and when the delta is empty, which means the tip is the rejected commit. Both modes exit 1 on a --stack name that no sub-heading has. A failed run prints the reason on stderr and nothing on stdout, so a coordinator cannot pass an empty brief to a verifier by mistake.
Why a command and not a prose instruction: the mode of the brief sets the mode of the verifier (below), and the diff form decides what the verifier reads. Both are easy to get wrong by hand and impossible to see afterwards.
The package lives in src/delegate/, and its tests in tests/. Its pytest suite runs in nix flake check as the tests check, which builds the package with runTests = true. The package itself runs no tests. The suite needs git and pytest-xdist, two nativeCheckInputs in package.nix. The guard tests run the rendered hooks with python3 as the only tool on PATH, so the suite needs no jq.
Bootstrap
One command writes a repository's context skill, its declaration, and its
rendered pair from arguments. It replaces the six manual steps in the
agent-delegation skill. The reason: context skills written by hand drift from
each other and from the worked example, and a later fix to their shape reaches
none of them.
<!-- not-a-command -->
agent-definitions bootstrap --repo PATH --name NAME --domain TEXT --tier TIER \
--skill NAME [--skill NAME ...] --reference PATH [--reference PATH ...] \
[--prompt-file FILE] [--max-turns N] [--gate-command CMD ...] [--get-only-command CMD ...] \
[--gate-extra-flag FLAG ...] [--output-language none|ste] [--tracked-file-build] \
[--context-load blocks|read] [--skills-root DIR] [--user-skills-dir DIR] [--dry-run]
agent-definitions bootstrap --skill-only --repo PATH --name NAME --domain TEXT \
--reference PATH [--reference PATH ...] [--context-load blocks|read] [--skills-root DIR] [--dry-run]
It writes six files.
| Path | Content |
|---|---|
<skills-root>/<name>-context/SKILL.md |
one live-read section for each reference |
<skills-root>/<name>-context/agents.toml |
the [agents.<name>] declaration |
<repo>/.claude/agents/<name>-{specialist,verifier}.md |
the Claude Code pair |
<repo>/.opencode/agents/<name>-{specialist,verifier}.md |
the OpenCode pair |
--skills-rootdefaults to.claude/skills, the only path Claude Code reads for a project skill. It is also the--skills-dirof the validation pass. A repository that keeps its skills in a different directory passes that directory and makes the.claude/skills/symlink by hand (theagent-delegationskill, § Then emit the repo's agents, in the same pass); the command makes no symlink.--user-skills-dirnames the second skills directory of the validation pass. The default is~/.claude/skills. A skill that is in either directory passes.- A reference carries its note. The value lands in the declaration as it is given, so
--reference '`docs/operate.md` — the component map'is one argument. The path is the first backticked word. A value with no backtick is the path itself. The command exits 1 and names the path when the path is not in the repository. - The skills list opens with
<name>-context, and each--skillfollows in the order given. - The command renders into a temporary directory and validates it, never the harness directory. On a finding it prints each finding, exits 1, and writes no agent file. The skill and the declaration are on disk before that pass, because the validator reports
MISSING_SKILLfor a context skill it cannot find. --dry-runprints every file with its content and writes nothing. It does not validate: the context skill is not on disk, so the pass would report a skill that the real run creates.--output-languageand--tracked-file-buildwrite the two neutral declaration options.--output-language stewritesoutputLanguage = "ste", and the rendered pair then carries the ASD-STE100 rule.--output-language nonewritesoutputLanguage = "none". Any other value exits 1 and names the permitted values,noneandste.--tracked-file-buildwritestrackedFileBuild = true, and the rendered Claude Code specialist then carries the flake reason (see "Rendering rules"). Without a flag the declaration holds no such key, and the declaration, the context skill, and the rendered pair are the same bytes as before the flags existed.--context-loadselects how the context skill loads its references.--context-load readwritescontextLoad = "read", and the context skill then has no load-time block. Its first instruction tells the agent to read each reference document with the Read tool before any other step, in the order of the references, and to stop and report when a reference is missing. Each reference gets a section with the instructionRead `<path>` with the Read tool.The skill carries the line<!-- agent-definitions:context-load read -->below its header comment, andvalidategivesLOAD_BLOCK_IN_READ_SKILLfor each load-time block in a skill with that line. Usereadon a host where a load-time block cannot run.--context-load blockswritescontextLoad = "blocks", and the skill is the skill of the default. Any other value exits 1 and names the permitted values,blocksandread. Without the flag the declaration holds nocontextLoadkey.renderreads the key and writes the same agent files for each value.--get-only-commandwritesgetOnlyCommands, as--gate-commandwritesgateCommands. Repeat it for each command. The entry rules are the rules of "Gate commands". Without the flag the declaration holds nogetOnlyCommandskey.--gate-extra-flagwritesgateExtraFlags, one entry for each use, in the entry format of "Gate commands":--gate-extra-flag --noEmitwrites"--noEmit", and--gate-extra-flag '--project <value>'writes"--project <value>". The word after the option is always its value, also when it starts with-. The command in the header comment of each generated file holds each--gate-extra-flag, so a run of that command gives the same declaration again. The declaration parser refuses an entry that is not a flag: the command then exits 1 and writes nothing. Without the flag the declaration holds nogateExtraFlagskey.--skill-onlywrites only<skills-root>/<name>-context/SKILL.md. It writes no declaration, renders nothing, and copies no agent file, so a declaration that holds a hand edit stays as it is, byte for byte. It needs only the options that the skill uses:--repo,--name,--domain, each--reference,--context-loadand--skills-root.--tier,--skilland--prompt-fileare not required with it. It works with--dry-run, which prints the skill and writes nothing. The header comment of the skill that it writes holds the--skill-onlycommand with these options. Use it whenvalidategivesLOAD_BLOCK_NOT_PLAINfor a skill that an olderbootstrapwrote: run it with the options of the command in the header comment of the skill, then runvalidateagain.- A second run with the same arguments writes the same bytes. A run with different arguments replaces all six files. The command never changes
docs/agents/delegation.md.
Each generated file opens with a comment that names the command to re-run, with --repo . in place of the path of one machine. The command names each option flag that the run used, so a re-run from the comment writes the same bytes. In the skill that comment is below the frontmatter, because Claude Code reads frontmatter from line 1 and from nowhere else.
A live-read block is one plain git grep command. Claude Code runs a load-time block only when it can analyse the command. The earlier compound block (R=$(...); if ...; fi) stopped a subagent from starting in the manual, acceptEdits and auto permission modes (measured on Claude Code 2.1.283, 2026-09-26). No Claude Code documentation states this rule: it is a measured behaviour. ADR 0006 records the measurements and their source, the issue tracker of a consumer repository, issues 171, 145 and 196. The generated skill carries the same note. bootstrap counts the lines of each reference when it writes the skill: a document of at most 200 lines gets git grep --untracked --no-exclude-standard -h -E -m 200 -e '^' -- :/<path>, and a longer one gets its heading index, git grep --untracked --no-exclude-standard -h -n -E -e '^#{1,6} ' -- :/<path>, with a note that gives the sed -n command for one section. A reference must be a file; a directory exits 1.
The :/ pathspec names the file from the top of the working tree, so a block reads the same file from the repository root and from each subdirectory. In a linked worktree it reads the files of that worktree, uncommitted changes included. An earlier form of the block used a path relative to the working directory, and a continuation spawned from app/ stopped in about 250 ms. --untracked with --no-exclude-standard also reads a file that is not in the index and a file that .gitignore names, so a block reads any file on disk, as the sed block did. -E sets the pattern type, because grep.patternType in a git config changes the default. A block needs no shell syntax and no assignment prefix, so it stays one command that Claude Code can analyse. The context skill is for a git repository: outside one, each block returns an error. A block that exits with no output can also mean that its reference file is missing or renamed.
The two templates are definitions/templates/context-skill.md and definitions/templates/context-skill-section.md, data in the package like the agent templates. With contextLoad = "read", definitions/templates/context-skill-read.md and definitions/templates/context-skill-read-section.md replace them. Both are string.Template files, so each dollar sign the generated text needs is written twice: $$(...) in context-skill.md is $(...) in the skill.
Verifier modes
A rendered verifier reads its mode from the shape of its brief.
| The brief | Mode | The verifier |
|---|---|---|
has a ## Findings under verification section |
fix-up | verifies each finding with evidence, confirms the delta touches only the findings and any ## Coordinator-authorised additions, runs the gates and the first pass's automated checks, stops |
| has no findings section | full | uses the full method: reads the whole diff, checks every acceptance criterion |
In fix-up mode the verifier does not read the full diff again. It does not repeat the cases the first pass broke by hand. A delta that goes past the findings is a scope finding for the coordinator. The verifier reports it and stays in fix-up mode. The coordinator decides whether a full pass follows.
The first line of every verifier report names the mode.
A rendered specialist carries the matching rule: a fix-up after a rejection is a new commit on top of the rejected commit, never an amend. An amend destroys the delta, and the fix-up mode of verifier-brief then refuses to build a brief.
The mode is in the template and in a generated brief because a rule in each brief did not stop fix-up verifiers from verifying the whole diff again. The coordinator's side of the protocol is in the agent-delegation skill, § Fix-up protocol.
Rendering rules
| Rule | Claude Code | OpenCode |
|---|---|---|
| Model | omitted; the spawn call sets it | the tier's model from tiers.toml; OpenCode sets nothing at spawn |
| Effort | omitted unless declared; follows the model through modelSettings.<model>.effortLevel (ADR 0001) |
variant, only when the declared effort is an OpenCode variant (high, max) |
| Skills | skills: preloads them for a subagent of the Agent tool. Under claude --print --agent the harness does not preload them, so the claude-code adapter of delegate run puts their text in the prompt (#215) |
cannot preload; the body tells the agent to load them with the skill tool |
| Verifier read-only | tools: Read, Grep, Glob, Bash, Write, plus a PreToolUse guard hook on Bash and one on Write |
permission with "*": deny first, then the read tools, then a bash pattern map that opens with its own "*": deny, an edit map that allows only ../*, and an external_directory map that allows only the temp prefixes |
| Specialist guardrails | isolation: worktree; a PreToolUse hook on Bash blocks git push (exit 2) |
permission.bash with "*": allow first, then git push*: deny and git -C * push*: deny; the catch-all must come first or the denies are shadowed. Two denies, because an OpenCode pattern is an anchored glob and git push* does not cover git -C <path> push |
| Mode | none | mode: all: the agent works with opencode run --agent <name> and as a subagent of a coordinator. mode: subagent is refused by opencode run, which runs its default agent instead, so validate gives the finding SUBAGENT_MODE for it (#214) |
| Turn cap | maxTurns |
steps |
outputLanguage |
"ste" opens the Report section of every agent file with "Write in ASD-STE100 Simplified Technical English."; "none" (the default) adds no rule |
the same |
trackedFileBuild |
true adds "An unstaged file is invisible to a flake." after the specialist's staging rule; false (the default) leaves the rule alone |
no change: the specialist states the staging rule without a reason |
Why the hook and not a denylist: a disallowedTools: Bash(git push *) entry removes Bash entirely. Why tools and not permissionMode: plan: permission mode is ignored when the parent session runs in auto mode, and a coordinator session can run in that mode. Why deny and never ask for the OpenCode verifier: --auto turns every ask into allow.
The verifier's shell
Read-only means "no write outside a temp directory, no write inside a git tree, and no write that holds one". It does not mean "no shell". A verifier that cannot run a command cannot run the gates, and the coordinator then does the verifier's work.
On Claude Code the verifier gets tools: Read, Grep, Glob, Bash, Write, a PreToolUse hook on Bash, and a PreToolUse hook on Write (see The Write tool). The hook is one bash line. It reads .tool_input.command with python3, turns each tab into a space, divides the command at &&, ||, ;, |, & and a newline outside quotes, and tests each segment. A segment that is not on the list exits 2, and the message names that segment. It fails closed: no python3, no command text, a quote that is not closed, or a shell without the bash string operators all end at exit 2. The hook carries the marker # agent-definitions:verifier-guard, which is what the validator looks for.
<!-- generated:begin verifier-guard-commands -->
<!-- Generated by delegate docs. Do not edit this section by hand. -->
| 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. |
<!-- generated:end verifier-guard-commands -->
The temp destination commands (cp and cd) follow more rules. This is what lets the verifier copy a worktree into a temp directory and go to the copy, which a red proof on a changed copy needs. A redirection does not end the scan. A path argument that comes after a redirection is a deny, in each order and in both the joined form (>/tmp/log) and the two-word form (> /tmp/log), because the shell removes the redirection and the path stays an argument of the command. A hyphen-led argument that holds t or T, and a long option that starts with --t or --n, are each a deny, because such a flag moves the destination into a word that the flag rule drops. Two literal prefixes are not enough: GNU short options cluster, so cp -Rt /Users/y /tmp/a still takes the next word as the destination, and a GNU long option accepts an unambiguous abbreviation such as --targ. cp -R, cp -a, cp -p, and cp -Rp stay permitted.
A cd writes nothing, so it may also go to a directory in the git toplevel of the working directory (#121). Many repositories give their gates in the form cd <dir> && <gate>, for example cd api && ./gradlew test or cd app && npm test, and the verifier of each stack must run its own gate. A cd takes one path argument: bash 3.2 goes to the first of two paths, and zsh reads two paths as a substitution in the working directory. The path must be a temp path or a path in that toplevel, which the next paragraph describes. A relative path counts from the working directory, and a relative path with no .. component stays below the working directory. When the working directory is in the toplevel, such a path is in the toplevel. When the working directory is in no git tree, the guard puts the working directory before the path, and permits the cd only when the result is a temp path, as it does for the same path in the absolute form (#131): in a temp copy with no .git entry, cd app && npm test is permitted. An absolute path must be a temp path, or the toplevel, or start with the toplevel and a /, after the guard removes a /private prefix and makes each // and /./ one /. The guard denies a .. component, a path that starts with ~ or =, and a path with a pattern or an expansion character (*, ?, [, { or $), because each one can name a directory outside the tree: cd ../outside, cd /etc, cd api/../.. and cd ~ are each a deny. With no git toplevel above the working directory, only a temp path is permitted, and the deny message says that the working directory is in no git tree. Each later segment is tested on its own, and after a cd in the same command a relative write target is not a temp path, so cd api && echo x > f stays a deny.
A relative write target counts from the working directory of the hook input, as the path of a cd does (#159). When the working directory is in no git tree, the guard puts the working directory and a / before the path, and it applies each rule of an absolute write target to the result: a temp path, no .. component, not inside a git tree, and not holding one. So in a temp copy with no .git entry, touch app/x and echo x > app/x are permitted, touch vendor/lib/x is denied when vendor/lib holds a .git entry, and touch ../../x is denied. The guard does not resolve a .. component, so the deny message of a write target with one names the .. component, not a temp directory (#165). The path may be in one pair of quotes. A relative path that starts with ~ or =, or that holds a pattern or an expansion character (*, ?, [, { or $), or a quote or a backslash in another place, stays as it is and is denied: the guard divides a segment into words at each space, also inside quotes, so touch "a b" is denied. When the working directory is in a git tree, each relative write target is in that tree, so it is denied. The guard does not follow a cd in the same command: after the cd, a relative write target stays as it is and is denied.
The tree under review stays read-only also when it is in a temp directory (#106), and so does each other git tree (#125). 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 the pointer file of a worktree. Each guard finds the git toplevel of its working directory: the nearest directory, from the cwd of the hook input (or else the working directory of the process) up, that holds a .git entry. Each guard also looks for a .git entry from each write target up, and in the directory that the target names (#125). Before #125, a verifier that went to a copy with no .git entry, as the break-a-copy recipe does, could write into the original worktree, because Claude Code keeps the working directory from one Bash call to the next. The python3 process that reads the hook input does each search, so the guard starts no git process. The Bash guard does not divide the command into commands in python3: it takes each word from a temp prefix to its end, also after a separator or a redirection sign in the word, as a path, and it gives the shell the git trees of each of these paths. An extra path is no risk, because each tree that it gives is a real git tree. The walk in a directory reads at most TREE_SEARCH_LIMIT (2000) directories, and it does not go into a directory that a pattern of the target cannot match. When the walk stops at that limit, a target that is the directory or holds it is a deny, because the guard cannot tell that the directory holds no git tree; a path in the directory stays permitted (#132). The section Limits below tells what to do then. The Bash guard denies a temp path as a write target when the path is inside a git tree or holds one: each temp-write command, a cp destination, a redirection target, and the output path of a GET-only command. It compares the paths after it removes a /private prefix on both sides. 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 /. A path with a pattern or an expansion character (*, ?, [, { or $) counts only up to the first such character. Such a path is a deny in all cases since #230, because the shell can expand it (see the next paragraph). A cd writes nothing, so it may go to the git toplevel of the working directory. A write to another temp path stays permitted: 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. For a red proof, the engine makes the proof copy beside it, with no .git entry, and adds it to the session of the verifier, so that verifier needs no cp and no rm (#153). The source of the rule is IN_TOPLEVEL_CHECK, TOPLEVEL_FINDER and TARGET_TREE_FINDER in src/delegate/definitions/render.py.
The guard reads each path and each argument of a command as text, and it does not expand them. So no word of a command may expand in the shell (#230). After each segment passes its own rules, the guard reads each word of each segment as the shell does: a path, an option, the path after git -C, and a redirection target too. A word with an unquoted {, }, *, ?, [, ], (, ), ^ or ~, with an unquoted = at the start, or with the zsh numeric glob <->, is a deny. A word with $ or a backtick outside single quotes is a deny too, except the temp prefix $TMPDIR/ and a $TMPDIR at the end of the word. The message names the word. Before #230, touch /tmp/d/{a,/Users/x/o} passed when no git tree was in /tmp/d, and the brace expansion wrote outside the temp directory. Bash ran -delete in find . {-delete,-print}, and zsh ran the glob qualifier of ls *(e:'touch x':). A word in single quotes is literal, so find . -name '*.py', rg 'a$' src, git diff 'HEAD~1' and touch '/tmp/d/{a,b}' are permitted where the guard permits the command. A word in double quotes is literal too, except for $ and a backtick. So the verifier cannot use a pattern in a path: ls src/*.py and rm -rf /tmp/copy/* are denied. Use find with a quoted -name pattern, or give each path.
The rendered verifier of each harness and the verifier brief give a binding rule for a verifier that cannot make the copy (#152), because the harness refuses a step of the recipe or a step fails. In a delegate run, the engine makes the proof copy (#153), and the brief gives the same rule for a proof copy that is missing. On one host, Claude Code refused each recursive cp, and the deny list of the host refused rm -r. The rule: do not break a check, a test or a file in the worktree under review, and do not make the red proof there. Put the red proof in unverified, with the refused command and its message. The gates can still run in the worktree. A gate can write build output there, for example dist/ or build/, and the verifier changes no source file there. The worktree is the work under review. In a delegate run, the engine checks that the verifier left it as it was (the worktree invariant). Outside a run, the rule is the same, and nothing checks it. An OpenCode verifier has no cp rule, so this rule applies to it each time.
Each entry matches the command alone or the command with arguments, and never a longer command name: ls does not match lsof. A segment that starts with git -C <path> loses that prefix before the test, so git -C <path> diff is the read git diff. This lets a verifier with no worktree of its own read a worktree by its path. The path is not examined, because a read of any path is a read. The subcommand after the path is examined, so git -C <path> push and git -C <path> commit stay denied. A segment that starts with nix develop -c or nix develop <flake-ref> -c (or --command) loses that prefix in the same way, so a gate that runs in a flake dev shell is tested as the gate command: nix develop -c python3 test.py is the read python3 test.py, and nix develop -c git push stays denied. Only a flake reference may come before -c. A flag there can write (--profile writes a symlink, --build runs build phases), so a hyphen-led word denies, and nix develop with no -c (an interactive shell) denies. A segment that starts with direnv exec <dir> loses that prefix too, so a gate that runs with the repository's .envrc is tested as the gate command. direnv allow writes direnv's allow list, and it denies. 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> (#121). A compose file is a read. So with the gate docker compose config, docker compose -f compose.yml config and docker compose -f a.yml -f b.yml config are the gate. 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, and docker compose -f x.yml with no subcommand denies. The guard removes no other option: docker compose -p x -f y.yml config and docker compose --file=y.yml config deny. The table is generated from VERIFIER_READ_COMMANDS, VERIFIER_TEMP_WRITE_COMMANDS, VERIFIER_TEMP_DEST_COMMANDS, and VERIFIER_TEMP_PATH_PREFIXES in src/delegate/definitions/render.py. Change the constants there and run delegate docs; a test fails when the table differs from the constants. The table holds no build tool and no tracker CLI. A verifier that must run one gets it from its declaration, with gateCommands or getOnlyCommands (below).
A git read command is a read only without an option that writes a file or runs a command (#140). After a git read command, the guard removes each quote and backslash from each word, and it denies --output and each prefix of it down to --o, alone or with =<path>, whether or not git accepts that prefix. The guard does not know which prefixes a git version accepts: git 2.54.0 rejects --outp= and --o= for git log, git show and git diff. An output path in a temp directory is permitted, by the rule of a GET-only output flag: git diff --output=/tmp/x/f is permitted, and git diff --output=/Users/x/f, git log --output /Users/x/f and git diff --outp=/Users/x/f deny. After git grep, the guard also denies -O, -O<cmd>, --open-files-in-pager with or without =<cmd>, and each prefix of it down to --o, because they run a command on the files that match. In a cluster of short options, git reads the rest of the word after -e, -f, -m, -A, -B or -C as the argument of that option, so -iOcat denies and -eFOO (the pattern FOO) is permitted. For git diff, git log and git show, -O<file> reads the order of the files from a file, so it stays permitted. The message names the option.
Gate commands
The reasons are in ADR 0004. A repository's verifier must run that repository's gates, and the gates differ per repository: npm test in one, dotnet test in another, zensical build in a third. The global list holds only what every verifier needs: no build tool and no tracker CLI is in it. A declaration adds its own gates with gateCommands, and bootstrap takes them as --gate-command (repeat it). Take them from the verification gates in the repository's docs/agents/delegation.md.
- Each gate command is permitted in that repository's verifier only, alone or with words after it that cannot make it write (#163). The specialist guard does not change. After a gate, the guard permits only a path that exists in the git toplevel of the working directory or in a temp directory (for example a test file), the separator
--, a number (all digits, #169), a redirection, and a flag ofgateExtraFlags. A relative path counts from the directory of the lastcdof the command. A path must not start with-,~or=, and must hold no..component and no pattern or expansion character. Each other word denies, and the message names the word and the gate: with the gatesnpm testand./gradlew test,npm test -- src/a.test.tsandnpm test 3are permitted, andnpm test -- -u(it updates snapshots),npm test -- --runand./gradlew test spotlessApply(a task that formats the source) deny.npm installdenies. - A gate that ends with
*takes free arguments (#169), for example"./gradlew *"or"nix eval *". The guard permits each word after it, as it did for each gate before #163, except a word that the shell can expand:./gradlew test jacocoTestReport -x processTestAotandnix eval --raw .#xare permitted. A task name does not expand, so./gradlew spotlessApplyis permitted too. The exception is a word that the shell can expand (#175, seegateExtraFlagsbelow):./gradlew test --tests *ITdenies, and./gradlew test --tests '*IT'is permitted. A word that holds$or a backtick denies too, also in quotes, except the temp prefix$TMPDIR/. The segment rules still apply: a redirection to a file outside a temp directory, a write into a git tree, and a write command after&∨deny. The rendered verifier names each such gate, and it tells the verifier that the guard permits each word after it, except a word that the shell can expand, that it must put a pattern character in single quotes, and that it must not put a word there that can make the gate write (#238). This is the rule of #124 in the text that the verifier reads, not a check of the guard. - Choose the form of each gate. Use a gate with no
*when the verifier runs the gate alone, with paths, or with numbers:npm test. Declare each other fixed form as a gate of its own, for examplenpx vitest run. Add a flag togateExtraFlagswhen the verifier needs a read-only flag after a gate:--reporter,-t <value>. Add*only when the arguments of the gate are words that the guard cannot examine, for example task names, flake refs or a subcommand of a runner:./gradlew *,nix eval *,npx vitest *. A*gate gives the guard no check of its words, so prefer the narrowest gate:nix eval *, notnix *. gateExtraFlagslists the flags that the verifier may put after any gate of the declaration. The list is declaration-wide: one list applies to each gate with no*, and no entry names a gate. List only a flag that cannot make a gate write, for example a filter or a reporter. A flag of the list is permitted alone, or with=and a value in the same word: the entry--reporterpermits--reporterand--reporter=dot. The guard cannot tell whether a flag takes a value word, so an entry"<flag> <value>"states it:-t <value>also permits the next word as the value,-t cart, unless that word starts with-: a parser such as yargs (Jest) takes no such word as a value, so the guard tests it as a word of its own, andnpm test -- -t -udenies. The guard reads the words after a gate as the shell does (#173): a single-quoted or double-quoted string is one word, with the quotes removed, and a backslash-escaped space does not divide. Sonpm test -- -t "renames the gift"is permitted, andnpm test -- -t "a b" -udenies-u. A word that holds$or a backtick denies, also in quotes, because the guard does not expand it. The temp prefix$TMPDIR/is the one exception. An unquoted word that the shell can expand denies too (#175): a word with{,},*,?,[,],(,),^or~, or with=at the start. The guard does not expand a word, and the shell does: in bash,npm test -- -t {a,-u}becomesnpm test -- -t a -u, and in zsh the glob qualifier of-t *(e:'touch x':)runstouch x. A word in single quotes is literal, and so is a word in double quotes, except for$and a backtick:npm test -- -t 'a*'andnpm test -- -t "[ab]"are permitted. The rule applies to each word after a gate, also a gate that ends with*, and after each entry ofgetOnlyCommands. A quote that is not closed denies. A flag with no<value>lets no word through: with--info,./gradlew test --info spotlessApplydenies. An entry is one flag:-or--, a letter or a digit, then the characters of a gate command. The declaration parser refuses each other entry.bootstrap --gate-extra-flagwrites the key, one entry for each use. Abootstraprun without the flag writes the declaration again without the key, so give each flag again, or make a skill current withbootstrap --skill-only, which leaves the declaration alone.- The
nix develop -canddirenv exec <dir>prefixes apply, sonix develop -c npm testanddirenv exec . npm testare the gatenpm test. A session started from a shell that direnv loaded runs the bare command. - A gate in a subdirectory runs as
cd <dir> && <gate>: with the gate./gradlew test,cd api && ./gradlew testis permitted, because acdmay go to a directory in the git toplevel of the working directory. Adocker composegate matches with its compose files: with the gatedocker compose config,docker compose -f compose.yml configis permitted (#121). - An entry is plain words separated by single spaces: letters, digits, and
. _ / : = @ + -. No quote, shell syntax, or glob character may reach the bash case pattern or the OpenCode glob. A gate of plain words can end with*; a*in another place is refused. - One exception is an exact gate: an entry of plain words in which one or more words are in double quotes and hold one
$(...)of plain words, for exampleuvx "zensical==$(cat .zensical-version)" build --strict. The first word stays plain, and the command in the$(...)must not open a write. The guard permits an exact gate only as the full command, character for character, and with no arguments.getOnlyCommandstakes no exact entry. - An entry must not open a write: a temp-write or temp-destination command (
rm,cp, and the others keep their path rules), or a prefix of a known write (git,git push,git reset). The declaration parser refuses both. - On OpenCode each plain gate command becomes the rule
<command>: allow, after the read commands, with no*(#163). A pattern cannot tell a path from a word that makes the gate write, so OpenCode permits each gate only as its exact text, and it does not usegateExtraFlags. A gate that ends with*becomes the rule<command> *: allow, so OpenCode permits it alone and with each word after it (#169):./gradlew *permits./gradlew test -x processTestAot. An exact gate is not in the OpenCode map.
Some commands read only while they stay a GET, for example a repository script ./scripts/api that sends a GET unless a flag names another method or gives a body. A declaration names them with getOnlyCommands. The verifier guard permits each one alone or with arguments, in that verifier only, and it examines every argument. An entry obeys the same rules as a gate command: plain words, and no write. A plain gate command cannot carry the argument rule, so do not put such a command in gateCommands.
After the words of an entry, the guard permits only these words (#164): an option (a word that starts with -), the word after an option with no = (the value of the option), a number, a path (a word with a /), and a redirection. Each other word can be a subcommand that writes, so it denies, and the message names the word and the entry. With the entry tea issues, tea issues, tea issues 12, tea issues --state open and tea issues --repo o/r 12 are permitted, and tea issues create -t x and tea issues close 12 deny. With the entry gh issue view, gh issue view 12 --comments is permitted. The guard examines the word after -- too: -- takes no value. An entry that ends with *, for example "tea issues list *", is a prefix on purpose: the guard permits each word after it, except a word that the shell can expand, and it still denies each flag of the table below. After each entry, also a prefix, an unquoted word that the shell can expand denies, by the rule of gateExtraFlags (#175): tea issues --search {a,create} denies, because bash makes it tea issues --search a create, and tea issues --search '{a,create}' is permitted. A word that holds $ or a backtick denies there too, except the temp prefix $TMPDIR/. The rendered Claude Code verifier states that each such entry is a prefix. Name the read subcommand in the entry when the command has write subcommands: "gh issue view" and "gh issue list", not "gh issue *".
The guard denies a GET-only command when any argument is one of these flags:
| Kind | Denied spellings |
|---|---|
| Method | -X <m>, -X<m>, --method <m>, --method=<m>, --request <m>, --request=<m> |
| Body | -d, --data, --data-* (for example --data-raw), --input, --input=<f>, -f, -F, --field, --field=<f>, --raw-field, --raw-field=<f> |
| Output | -o, --output and each prefix of --output down to --o (also -o<path>, --output=<path> and --out=<path>), unless the path is a temp path |
A single-hyphen word is a short flag or a cluster of short flags, so the guard denies it when it holds X, d, f, F or o (-sX and -dBODY deny). It removes quote and backslash characters from each word first, so '--method' POST denies. An output flag keeps the rule of the temp-write commands: -o /tmp/out.json and --output=/tmp/out.json pass, and -o ./out.json, -o /tmp/../x, and an -o with no path deny. A command built on argparse accepts a unique prefix of a long option, so the guard reads --o, --ou, --out, --outp and --outpu as --output (#141, #165): --out /tmp/out.json passes, and --out ./out.json and --ou ./out.json deny. The command with no such flag, and the command with read-only arguments (--paginate, --jq .title, -H Accept:application/json), stay permitted. The guard reads text. It does not see an argument that a shell expansion builds, so a GET-only command must not take its arguments from an expansion that an agent controls.
On OpenCode a getOnlyCommands entry is not permitted at all: a pattern cannot examine the arguments, so it cannot see a method flag, a body flag or an output flag. This is a limit of OpenCode, not a choice. The OpenCode verifier allows no GET-only command, whatever the flags.
A gate can write: npm test can write node_modules/ and a cache, and a path after a gate can be an output of the gate: npx tsc src/a.ts writes src/a.js. The guard permits each word that exists as a path, so a task name that is also the name of a directory passes: with a build/ directory, ./gradlew test build is permitted, and it runs the task build. The guard reads text and cannot confine that, as for python3. The verifier method still applies: copy the worktree into a temp directory, and run the gates in the copy.
On OpenCode the verifier keeps "*": deny as its first rule and allows the read tools, and it now adds a bash pattern map whose own first key is "*": deny. Each read command becomes <command> *: OpenCode treats a trailing * as optional, so one pattern covers the bare command and the command with arguments. The OpenCode map is smaller than the Claude Code list on purpose. An OpenCode pattern cannot examine a path argument, so the temp-write commands, the temp-destination commands, and each getOnlyCommands entry stay out. The map also leaves out echo, printf, git grep, env and file, and it permits mktemp only as the exact commands mktemp and mktemp -d. It ends with three deny rules, *>*, *| tee * and *|tee * (#123). OpenCode keeps the last rule that matches, so the denies win over the read allows: cat a >> /abs/b and grep x f | tee /abs/y are a deny, and cat f stays an allow. The *>* rule also denies 2>&1 and 2>/dev/null. The limit of these rules is in Limits below.
The two guards are not equal, and the differences are in Limits below.
The Write tool
The verifier writes its verdict with the Write tool. A Bash write of a verdict often fails: the Bash guard refuses a heredoc, and each $( and backtick of a command, also inside quotes, and a verdict names code.
- On Claude Code a
PreToolUsehook onWritereadstool_input.file_pathwithpython3. It permits the Write only when the path is absolute, starts with/tmp/,/private/tmp/,/var/folders/or/private/var/folders/, or with the value of$TMPDIRin the environment of the hook and a/, and has no..component. Only a safe$TMPDIRadds a prefix, by the rule of the row "runtime$TMPDIR", and the Bash guard uses the same rule (SAFE_TEMP_DIRECTORY, #166). It denies a path in the repository and a relative path. The Write tool does not expand a variable, so a path that starts with$TMPDIRis a relative path, and the guard denies it. Each deny exits 2, and the message names the path. With nopython3, or with no file path in the input, the hook fails closed. It also denies a path inside a git tree, or a path that holds one, by the rule of the Bash guard: the git toplevel of its working directory, the git tree above the path, and a git tree in the path when the path is a directory (#125). The Write tool expands no pattern and no variable, so the guard compares the path as it is. The hook carries the marker# agent-definitions:verifier-write-guard. The prefixes come fromVERIFIER_TEMP_PATH_PREFIXESwithout$TMPDIR(VERIFIER_WRITE_PATH_PREFIXES). - On OpenCode the
editpermission covers the write, edit and patch tools. OpenCode matches aneditrule against the path relative to the worktree, so a path in the project never starts with../. The verifier getsedit: {"*": deny, "../*": allow}. OpenCode asksexternal_directoryfor a path outside the project, with the absolute parent directory and/*as the target. The verifier gets anexternal_directorymap that opens with"*": denyand allows only/tmp/*,/private/tmp/*,/var/folders/*and/private/var/folders/*. The map has no$TMPDIRprefix, so on a host whose$TMPDIRis not under one of these prefixes, Claude Code permits a write to$TMPDIRand OpenCode denies it. The project of OpenCode is the git toplevel of its working directory, and theeditmap denies each path in it, so a worktree in a temp directory stays read-only on OpenCode too, when the path has the spelling of the real path. A path through a symbolic link is a limit (see Limits). - The validator accepts
Writeon a Claude Code verifier only beside the Write hook with its marker. On OpenCode it accepts anedit,writeorpatchmap only when the map opens with"*": denyand each allow starts with../, and then only beside anexternal_directorymap that opens with"*": denyand allows only temp prefixes. Each other case isVERIFIER_WRITE_TOOL.
Effort
Decision of 2026-09-19 (ADR 0001): effort by model is the default. A subagent whose file sets no effort uses modelSettings.<its own model>.effortLevel, so choosing a model at spawn chooses the effort. The configuration that renders settings.json sets that key for every tier model. Declare effort only when the two halves of a pair need different effort on the same model. Never launch the coordinator session with --effort or CLAUDE_CODE_EFFORT_LEVEL; both defeat the per-model value.
Validation findings
<!-- generated:begin finding-codes -->
<!-- Generated by delegate docs. Do not edit this section by hand. -->
| 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 |
<!-- generated:end finding-codes -->
The tier table
src/delegate/shared/tiers.toml is the single source: tier to model per harness, allowed models per harness, effort levels, OpenCode variants, the description budget. A consumer configuration that renders agents, for example a Nix module, reads the same file, so the tiers have one source. The OpenCode identifiers follow the provider/model-id shape; confirm them with opencode models before the first OpenCode rollout.
The OpenCode column is the one part a caller may override, with the two flags above (ADR 0003). The table stays the source of the defaults and of the whole Claude Code column. Do not edit the OpenCode column for one machine or one job: the table is global, and the override exists so the identifiers can live with whatever configures the provider.
Neutrality check
The check scans four directories: agent-delegation/ and agent-definitions/, the two skill directories in skills/, and plugins/ and .claude-plugin/, the two plugin directories in the repository root. In this section, the kit is these four directories. The kit must hold no personal or company term. The test tests/test_neutrality.py::test_the_kit_holds_no_denylisted_term_outside_the_allowlist reads every file in the kit and fails on each line that holds a term from a denylist, unless the allowlist names that file and that term. The code is src/delegate/docs/neutrality.py.
AGENT_DEFINITIONS_DENYLISTis the path of the denylist. The denylist is private, so it is never in the kit: the consumer repository keeps it and gives its path. Without the variable, the test skips with this notice:neutrality check skipped: AGENT_DEFINITIONS_DENYLIST is not set. A path with no file, or a denylist with no term, fails the test.AGENT_DEFINITIONS_KIT_ROOTis the directory that holds both skill directories. It is optional. Without it, the test uses theskills/directory of the repository, which is correct in a checkout. The check findsplugins/and.claude-plugin/in the parent of the kit root, which is the repository root in a checkout. A missing skill directory or plugin directory fails the test. A Nix build copies only the package, its tests and its example, sopackage.nixgives the kit as a second source, with the layout of the repository, when it gets aneutralityDenylistargument.- The denylist format. One term on each line. A term has no space. A line that starts with
#is a comment. The check matches each term case-insensitively, as a substring. - The allowlist format. The file is
agent-definitions/neutrality-allowlist.txt. One entry on each line:<path> <term>, with the path relative to the directory that holds both skill directories, for exampleagent-delegation/SKILL.md sometoken. The path of a plugin file is relative to the repository root, for exampleplugins/claude-code/hooks/register.tsx sometokenor.claude-plugin/marketplace.json sometoken. An entry permits every line of that file that holds that term. A line that starts with#is a comment. An entry is a permanent exception only, with a comment line directly above it that gives its reason. Today the kit has no permanent exception, so the allowlist holds no entry. The check does not scan the allowlist, because the allowlist names the terms. An entry names only a term that its file already holds, so the allowlist shows no term that the kit does not show. STALE_ALLOWLIST_ENTRY. The check reports an entry whose file does not hold its term, or that names a file that the check does not scan (a missing file, a generated file, or the allowlist). The finding gives the line of the entry, and the test fails. Remove the entry. Without this finding, a term that a change removes from its file stays visible in the allowlist.- Without Nix: from the repository root, run
pip install .andpytest, with the denylist path inAGENT_DEFINITIONS_DENYLIST. - The scan skips generated files: the directories
__pycache__,.pytest_cache,buildand*.egg-info, and the file.DS_Store. A pip build or a test run writes them, and they copy kit files. The scan also skipsplugins/<name>/.claude-plugin/types/, the type declarations that Claude Code writes when it loads a plugin from a folder.
Limits
- No harness composes agent files. A project-tier agent is a complete file, never an extension of a global one. Claude Code and Codex replace on a name collision; OpenCode merges per key, which this renderer does not rely on.
- Docs cannot be attached by path. Put reference material in a skill and list it in
skills; on OpenCode, name it in the prompt. - Both Claude Code guards read the hook input with
python3, which the kit already requires; they need nojq. Both fail closed: with nopython3on the agent's PATH, or with input that holds no command text, each guard exits 2 and blocks the call (ADR 0005). - The verifier guard reads the command as text.
python3andbash -care on the allow list because the gates and the reviews need them, and each of them can write through the guard.envis a prefix, not a read (#158): the guard removesenvand its options-i,-0,-,--,--ignore-environment,--null,-u <name>,-u<name>,--unset <name>and--unset=<name>, and it tests the rest as its own command. It denies each other option ofenv, a word before the command with a quote, a backslash, an expansion or a pattern character, an assignment before a command (GIT_EXTERNAL_DIFF=touch git diffwrites files), andbash -corpython3afterenv. Afterfindit denies-exec,-execdir,-ok,-okdir,-delete,-rm,-fprint,-fprint0,-fprintfand-fls, and afterrgit denies--preand--hostname-bin, because they run a command or write a file. A sed script can run a command (the GNUecommand) or write a file (w), so the guard permitssed -nonly as a line range,sed -n '<start>,<end>p' <path>. The OpenCode map has noenvrule, because a patternenv *also matchesenv touch <file>. The guard does not parse Python and it does not parse a nested shell. This is a contract for the verifier, not a sandbox. So the rule against a wrapper is in the text that the verifier reads, not in the guard (#124): a command that the guard refuses is not run in another form, throughbash -c,python3 -c,sh -c,env,xargsor a script file. The rendered verifier of each harness and the verifier brief state this rule, and the verifier reports the refusal inunverified, with the command and the message of the guard. After a gate that ends with*(#169), the guard permits each word, except a word that the shell can expand (#175), and the OpenCode map permits each word, also a word that the shell can expand. So the rendered verifier of each harness names each such gate, and it states the rule: do not put a word after such a gate that can make the gate write. - The verifier guard divides the command at
&&,||,;,|,&and a newline, but not inside quotes. An&in a redirection (2>&1,&>file) does not divide. A redirection with&must go to a file descriptor: the guard permits>&andn>&only before a file descriptor number or-, and it denies each>>&, because the shell writesls >&outand the zshls >>&1to a file. A quote right after the descriptor, as inbash -c "ls 2>&1", is denied too, because a quote there can make the target a file name. Under bash and/bin/sh, writebash -c "ls 2>&1 "instead. A segment that ends at a redirection sign is denied, because inls >|catthe shell writes the filecat. It reads single quotes, double quotes, an ANSI-C quote ($'...'), a backslash and a comment as bash and zsh do. It does not parse a$(or backtick substitution or a here-document, because each of these forms reads quotes in its own way. In a command that holds one of these forms, a separator inside a quoted argument divides the command, and the parts that are not commands are denied. A word with an ANSI-C quote or with a parameter expansion with braces (${) holds$, so the guard denies it, and the message names the full word (#238): a|,;or&in its quotes does not divide the command. The guard then tests a command with${or$'a second time, and divides it at each separator, also inside quotes, as before #238, sogit grep 'a${b}|c'still denies. A quote that is not closed denies the command. The guard fails closed in each case. - The guard uses the bash string operators. Measured 2026-09-19: under
bashand under macOS/bin/shit behaves as the table says; underdashit exits 2 on a syntax error, which is a deny, so the guard stays fail-closed. zsh does not divide an unquoted expansion into words, so the guard first turns on sh emulation underzsh, and it then gives the verdicts ofbash(#113). Before, it denied each temp write underzsh. - An assignment prefix is not on the allow list. A command substitution or a process substitution runs a command that the guard cannot examine, so a command that holds
$(, a backtick,<(,>(or the zsh=(is denied, also inside single quotes. The one exception is an exact gate of the declaration, given as the full command.T=$(mktemp -d)is denied. Usemktemp -dand then a literal path. To search for the text$(, write it as[$](. - The destination-flag rule is wider than the flags it must stop, because the guard does not know which flags a command takes. In a temp-destination command it denies every hyphen-led word that holds
torT, so it also deniescp --preserve=timestampsandcp --strip-trailing-slashes, which move no destination. Each such deny is a lost convenience, not a lost capability: the copy runs without the flag. - A temp path is a text prefix and a path with no
..component. The guard rejects.., it does not resolve it: the guard reads the command as text, and a resolution needs the file system./tmp/../Users/xis therefore a deny for each temp-write and temp-destination command, and for a redirection target. The rule reads a path component, so a name such as/tmp/a..bis permitted. A path that needs..must be written out in full. - The copy allow reads the source and it does not examine it. A
cpsource can be any path the agent can read, secrets included, and the copy then sits in a temp directory. The temp directory is the boundary, not the source. - The Write guard reads
file_pathas text, as the Bash guard reads a command. It does not resolve a symbolic link, so a link in a temp directory that points to a directory below the toplevel of a repository is a write into that repository. A link to the toplevel itself is a deny, because the search for a.gitentry goes through the link. It takes$TMPDIRfrom its own environment, and the Bash guard takes the same value for an absolute path (#166). Only a safe value counts: an absolute path with at least two components, with no empty component, no.component and no parent component, that is not the home directory or a parent of it, and that is not inside a git tree. So a host that sets$TMPDIRto/, to the home directory or to a directory in a repository opens nothing. - The rule for the tree under review and for each other git tree looks for a
.gitentry along the path as the command gives it (#125). It does not resolve a symbolic link first, so a link in a temp directory that points to a directory below the toplevel of a git tree hides that tree, and a write through the link is a write into the tree. A link to the toplevel itself is a deny. The Bash guard finds the trees of the words of the command text, so a target that a shell expansion builds is not examined, as in the rest of the guard. The walk in a directory reads at most 2000 directories, and a target that it could not search to the end is a deny, a lost convenience and not a hole (#132): leave a large temp copy in place, or first remove the parts that hold no git tree, one directory at a time, each with fewer than 2000 directories. The rule reads.gitentries and not the git configuration, soGIT_DIRandGIT_WORK_TREEdo not change a tree. A copy of a tree that keeps its.gitentry is a git tree too, so remove the.gitentry of the copy in the command that makes it. - The
cdrule reads the path as text (#121). It does not resolve a symbolic link, so a link in the tree that points out of the tree takes acdout of the tree. It does not readCDPATH, so in a shell that hasCDPATHset, a relativecdcan go to a directory ofCDPATH. A directory in the tree that holds its own.gitentry, such as a submodule or a nested repository, is a new git toplevel after thecd, and a latercdmay go only into that directory. In each case the guard still denies each write outside a temp directory, and each write inside a git tree. - The git option rule reads each word as text (#140). It does not know which option takes the next word as its argument, or where the pathspecs start after
--, so a pattern or a pathspec that looks like a denied option also denies:git grep -e -Ocatandgit grep foo -- --output=x. Search for such a text with the Grep tool or withgrep. As for a GET-only command, the guard cannot see an option that a shell expansion builds. - The OpenCode write rules have no
$TMPDIRprefix, because an OpenCode pattern holds no environment variable. On a host whose temp directory is not under/tmp/,/private/tmp/,/var/folders/or/private/var/folders/, OpenCode denies the write of the verdict, and the engine reads the verdict from the final text of the verifier. In a directory with no version control, OpenCode takes/as the worktree, so the relative path of a temp file does not start with../, and OpenCode denies the write too. Each of these is a deny, not a hole. - The OpenCode maps cannot deny each write in the tree that the verifier reviews. OpenCode takes the real path of the project, with each symbolic link resolved, and it compares that path as text with the path that the agent gives. The
editmap denies a path in the project in that real spelling. A path through a link to the project is outside the project as text, so its relative path starts with../, theeditmap allows it, and theexternal_directorymap allows its temp prefix. An OpenCode pattern holds no variable that names the project, and the path of the tree changes in each run, so no rule can deny that spelling. Measured on OpenCode 1.15.10 on 2026-10-19 on macOS: in a repository at/var/folders/<x>/copy, whose real path is/private/var/folders/<x>/copy, the write tool wrote/var/folders/<x>/copy/src/w1.txt, and it denied/private/var/folders/<x>/copy/src/w2.txtandsrc/w3.txt. In a repository whose real path is/private/tmp/<y>/copy, it wrote/tmp/<y>/copy/src/b.txt. On macOS the engine gives the verifier the path of its temporary copy under/var/folders, so the rendered OpenCode verifier states this limit. In a run, the tree is the temporary copy, and the worktree check of the engine still covers the real worktree. - The OpenCode verifier map holds none of the rules that let a verifier copy a worktree or read it by path: no
cprule, nocdrule, and nogit -C <path>rule. Acprule and acdrule must examine a path argument, which an OpenCode pattern cannot do. Agit -C * <read>rule needs no path examination, butgit -C * diff*compiles to the anchored^git -C .* diff.*$, and that pattern also matchesgit -C /x push; git diff. The OpenCode patterns stay narrow (ADR 0002), and this widening is not permitted, so the OpenCode map stays as it was. An OpenCode verifier therefore cannot make the copy, and it reports the red proof as a command it cannot run. - The subcommand rule of a
getOnlyCommandsentry (#164) does not know which option takes a value. It reads the word after each option with no=as the value of that option, so after an option that takes no value, a subcommand passes:tea issues --comments createis permitted with the entrytea issues. The guard reads the words after the entry as the shell does (#173): a quoted value with a space is one word, sogh issue list --search "a b"is permitted with the entrygh issue list. The guard does not expand a word, so a word that holds$or a backtick denies, also in quotes, except the temp prefix$TMPDIR/:-o $TMPDIR/out.jsonstays permitted. A word with an unquoted pattern or expansion character denies too, for example{a,create}or*(#175). - The OpenCode verifier allows no
getOnlyCommandsentry. A GET-only rule examines each argument for a method flag, a body flag and an output flag, and an OpenCode pattern cannot examine arguments. A GET-only command is therefore a deny on OpenCode, bare or with arguments, and a verifier there reports it as a command it cannot run. On Claude Code the guard also cannot see an argument that a shell expansion builds (the guard reads text). - The OpenCode verifier map has no
nix developrule. Anix develop * -c *pattern cannot test the command after-c, so it would permit every command in a dev shell. An OpenCode verifier reports a dev-shell gate as a command it cannot run. - The OpenCode verifier map does not divide a compound command either, for the same reason as the specialist map: OpenCode v1.18.31 hands the permission check the raw command.
git status && git commit -m xis one deny on Claude Code and one allow on OpenCode. - The OpenCode verifier map cannot deny each redirection to a file (#123). OpenCode keeps the last rule that matches:
evaluateinpackages/core/src/permission.tsof OpenCode at tag v1.15.10 is afindLastover the rules, read on 2026-10-20. So the deny rules*>*,*| tee *and*|tee *come after the read allows, and they win. OpenCode checks each simple command of a line on its own, with the text of a redirection that follows that command (sourceinpackages/opencode/src/tool/shell.tsat the same tag). A redirection after a group ({ cat f; } > x), a subshell, a loop, or the last command of a pipeline (cat f | grep x > y) is not in that text, so no glob can deny it. Measured on OpenCode 1.15.10 on 2026-10-20 withopencode debug agent <verifier> --tool bash: the map deniedecho x > <file>,cat f >> <file>,ls &> <file>,grep x f | tee <file>andgit status 2>/dev/null, and it permitted and wrote{ cat f; } > <file>andcat f | grep h > <file>. Because of this limit, the OpenCode map has noechorule and noprintfrule: a verifier needs them only to write. The rendered OpenCode verifier states the limit. The modelopencode_bash_actioninsrc/delegate/definitions/validate.pymatches the full command text, so it gives a deny for the group and the pipeline forms, and it does not show this limit. - The OpenCode verifier map has no
git greprule (#140).git grep -O<cmd>andgit grep --open-files-in-pagerrun a command on the files that match. A pattern matches the text of the command, and the shell makes the same option from other text:-iOcatand-'O'catare-Owith the commandcat,-eFOOholds no-O, and git accepts--op=catas the long option. A deny pattern that matches each of these forms also matches most searches. The OpenCode verifier searches with its grep tool. The map keepsgit diff *,git log *andgit show *, and a pattern cannot examine the path of--output=<file>, so the map permits that write. The rendered OpenCode verifier states this and tells the verifier not to use that option. - Frontmatter hooks in a project-scope agent do not run under
--print, also in a trusted directory (Claude Code 2.1.287, measured in issue 187). The harness documents that an interactive session runs them only after the workspace trust of the folder, and the measurement shows that trust does not help a--printsession. A project-tier verifier that such a session loads from a tree has a Bash tool with no guard. Adelegate runsession does not load it from the tree: it starts from the sealed agent, and the guard probe shows that its guard runs. The global tier is user-scope and it is not affected. - The two push guards are not equal, and no pattern makes them equal. Measured 2026-09-19: the Claude Code hook applies an unanchored regular expression to the raw command, so it also stops
git add . && git push,git pushwith two spaces, andGIT_DIR=/x git push. An OpenCode pattern is an anchored glob, and OpenCode v1.18.31 hands the permission check the raw command with no split at&&(packages/core/src/tool/bash.ts, which carries a TODO for a tree-sitter parser), so OpenCode allows all three. Do not widen the OpenCode pattern to*git push*(ADR 0002). The residual risk is an OpenCode specialist that pushes from inside a compound command. - Two files with one name in one directory resolve by read order. The renderer refuses to produce that; the validator reports it in hand-written sets.
- A turn cap is a cost stop, not a lost deliverable. Claude Code 2.1.267, measured 2026-09-19: at
maxTurnsthe Agent tool result gives only a harness NOTE and the agent'sagentId. The agent's own text is absent. The status is stillcompleted, andSubagentStopdoes not fire. ASendMessageto thatagentIdstarts the same transcript again and keeps its context, and the cap applies again on each resume. OpenCode atstepsmakes the agent write a summary with the tasks that remain, and it documents no resume. Set a cap to bound cost, and resume the agent when it hits the cap.
04 同仓库更多 Skills
agent-delegation
Protocol for delegating implementation work to subagents — the coordinator/specialist/verifier role split, the delegation brief template, blind adversarial verification, and sequential merge. Use when spawning agents to implement work, planning multi-agent work, writing a delegation brief, or bootstrapping a repo's gates and its specialist-verifier pair. Repos may add a docs/agents/delegation.md with repo-specific gates.
sample-style
The style rules of the sample project. Use when you write or change code in it.
delegate-context
The delegate kit: a harness-neutral delegation engine, the agent-definitions renderer and validator, and the delegation skills, in Python with a pytest suite. Use when you work in delegate and you need one of its reference documents: `docs/agents/delegation.md`, `AGENTS.md`.