AGENT SKILL

global-agent-guardrails

Install, audit, test, or update the Development System's global destructive-command guard for Codex, Claude Code and T3 Code. Use when configuring agent safety hooks or investigating whether dangerous shell operations are blocked.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
global-agent-guardrails
description
Install, audit, test, or update the Development System's global destructive-command guard for Codex, Claude Code and T3 Code. Use when configuring agent safety hooks or investigating whether dangerous shell operations are blocked.

02 资源文件 5

03 SKILL.md 正文

Global Agent Guardrails

This skill is the operator guide for the executable destructive-command policy. The hook is the enforcement layer; instructions alone are not protection.

Contract

  • Codex and T3 Code share the Codex PreToolUse adapter, matched on Bash|exec|apply_patch|mcp__.* (whether Codex sends MCP calls to hooks is not yet observed; until a live sentinel shows it, Codex MCP calls are a declared gap).
  • Claude Code uses a PreToolUse hook in its user settings, matched on Bash|Monitor|Edit|Write|MultiEdit|NotebookEdit|mcp__.*.
  • Existing Codex hooks and Claude Code settings are merged, never replaced.
  • Factory settings, skills, logs, and executables are outside the current runtime and are never read or changed.
  • The guard fails closed when a matched shell tool has malformed or missing command input.
  • Hard blocks do not imply sandboxing and do not replace repository permissions, review, backups, or explicit authorization.
  • The agent cannot bypass a block. A human may run the command outside the harness or deliberately remove the guard after reviewing the exact target and recovery plan.
  • Test-file writes and, from policy 2.3.0, docs-config-write (below) are the blocks the operator lifts without removing the guard. For tests: development-system allow-tests <dir> [--hours N] [--reason text] in their own terminal grants that directory for up to 24 hours (default 2); --revoke <dir> ends it and development-system test-grants lists active grants. Grants live in ~/.development-system/test-grants.json. allow-tests refuses agent shells (CLAUDECODE, AI_AGENT, CODEX_THREAD_ID or CODEX_SANDBOX set) and non-interactive terminals, and asks the operator to type the directory's name, so no spelling of the command (variables, xargs, runners) grants from an agent shell. The guard also blocks literal allow-tests invocations (except inside read-only Git commands such as git grep or git log) and writes to the grant file through inspected commands. Threat model: grants stop habitual or accidental self-granting. Like every other limit of this guard, they do not stop an agent that deliberately writes files through interpreter APIs or races a symlink into a granted path within one command.

Operate

Use the Development System CLI from its canonical checkout:

./bin/development-system guardrails-enable
./bin/development-system guardrails-audit
./bin/development-system guardrails-rollback

Use --home <isolated-home> for verification. Enabling requires the catalogued Codex and Claude global-agent-guardrails skills to be installed first.

The policy hard-blocks recursive forced deletion, catastrophic disk operations, destructive Git history/worktree operations, forced pushes, repository deletion, high-impact infrastructure destruction, and downloaded-code-to-shell pipelines. It intentionally does not block normal reads, ordinary file edits, dependency installation, or non-recursive deletion of a named file. For tracked paths, use git rm -r instead of rm -rf.

Policy 2.1.0: quote-aware evaluation and operator test grants

references/policy.json is evaluated against a parsed command, not raw text:

  • Quoted text, heredoc bodies with a quoted delimiter, and redirections such as 2>/dev/null are data. grep "git reset --hard" docs and git commit -m "..." pass.
  • $(…), backticks, <(…) and >(…) are evaluated recursively up to maxSubstitutionDepth (4); $((…)) is arithmetic. $(cat <<'EOF' … EOF) (the usual commit-message form) is read as its literal heredoc text unless the command can change what cat runs, in which case it is dynamic: a cat function (also zsh function a cat { … }), alias, hash or enable naming cat (also after command, builtin, noglob or nocorrect and their options), a trap action naming cat or PATH or built at run time, zsh autoload cat or functions -c f cat, a PATH or zsh path assignment or loop variable, an assigning expansion (${PATH:=…}, ${path::=…}), arithmetic that assigns and names PATH or holds an expansion, quote, backtick or backslash that can build that name ((( PATH = 5 )), (( "PATH" = 5 )), (( $(echo PATH) = 5 )), $[PATH=5], a[PATH=5]=1, ${a[PATH=5]}, ${s:PATH=1}, [[ PATH=5 -eq 1 ]], let x=PATH=5; reading, as in n = ${#path} + $#, and plain names, as in i += 1, do not count; (( n = $x )) counts), a variable, array element or integer value that arithmetic reads again and that assigns a PATH name (n='PATH=5', a=('PATH=5'), declare -i x=PATH=5; NODE_OPTIONS=--require=./path/x.js does not count), a name-taking builtin that sets PATH or takes a variable name (export, declare, read, getopts, readarray, printf -v, print -v, wait -p, zsh set -A, also inside an option cluster such as print -rv, …), a nameref (declare -n, local -n), or a function table entry (bash BASH_CMDS/BASH_ALIASES, zsh functions, commands, aliases). Unquoted heredoc bodies are scanned for substitutions. A heredoc or here-string fed to a shell (or source /dev/stdin) is evaluated as shell. For other interpreters (python -c, node -e/--eval/-p, deno eval, perl -e, ruby -e, osascript -e, php -r/-R/-B/-E, Rscript -e, lua -e, an awk program or awk -f, or a heredoc fed to one of them), each string literal in the code that contains whitespace, including literals joined with +, , or adjacency, and each code fragment between quotes, brackets and ; is evaluated as a shell command with interpolations (${…}, $name, {name}, %s) replaced by a placeholder. Code that calls a process API (system, exec*, spawn*, popen, run, backticks, …) with a lone shell name (os.system("sh")) is blocked. Native file APIs in that code (shutil.rmtree, fs.rmSync, open(…, 'w')) are not inspected.
  • Destructive rules apply to each simple command after wrappers (sudo, env, xargs, timeout, nohup, find -exec, …) are stripped, and to any argument position that names a destructive-capable command or shell (ssh host rm -rf …, watch 'git reset --hard', tmux new -d 'true; git reset --hard', parallel ::: '…'), including command positions inside one argument after ;, &, |, (, { or then/do. They are skipped for pure-read commands (readOnlyCommands, sed without -i/e/w, awk without system(/pipes/redirection).
  • Rule match values: command (default; canonical name args…, for git starting at the subcommand), pipeline (command names joined by |), raw (full source text).
  • Always blocked (structuralRules): eval, $'…' outside single quotes, ${!x}, a variable or substitution as the command name, sh|bash|zsh -c with a non-literal script, a shell or interpreter reading its program from a pipe, inherited or non-literal stdin, a process substitution or a device (echo … | sh, node -, python3 <<< "$x", awk -f -, bash <(…)), Git configuration that makes an ordinary command destructive (help.autocorrect, clean.requireForce=false, deleting or forced push refspecs, remote.*.mirror), unparseable input, and variable arguments to sensitiveCommands (rm, dd, mkfs, diskutil, gh, terraform, pulumi, kubectl, wrangler, vercel, and git outside readOnlyGitSubcommands). Executed inline Git configuration (-c alias.x=…, core.pager) and program-naming variables (GIT_PAGER=…) are evaluated as commands.
  • git-discard allows git checkout --ours/--theirs and git restore --staged.
  • test-file-write blocks creating or modifying paths matching testFilePatterns inside the payload cwd, unless a valid operator grant holds the target after symlinks resolve: unexpired, at most 24 hours long, for the same directory (same inode, not replaced by a symlink). A target with a variable, glob or .. segment, or a relative target after a cd, is never granted: redirections, tee, cp/mv/install destinations, sed -i targets, git diff --output, Edit/Write/MultiEdit file_path, NotebookEdit notebook_path, and apply_patch *** Add File:/*** Update File:/*** Move to:. Deleting test files is allowed.
  • guard-config-write blocks writes to protectedWriteTargets: ~/.codex/hooks.json, ~/.codex/config.toml, ~/.claude/settings.json, ~/.claude/settings.local.json and the installed global-agent-guardrails skills and the operator's ~/.development-system/test-grants.json and ~/.development-system/docs-grants.json (~, $HOME and absolute spellings), plus protectedProjectWriteTargets inside the payload cwd (.claude/settings.json, .claude/settings.local.json, .codex/hooks.json, .codex/config.toml, and .git/config, whose aliases run commands; use git config instead). Writers include redirections, tee, sponge, cp/mv/install/ln, recursive cp/rsync/ditto and tar/unzip/patch rooted above a protected path, perl/ruby -i, curl -o/-O (under the --output-dir of the same transfer; --next starts another), the -f/--file (or GIT_CONFIG, GIT_CONFIG_GLOBAL, GIT_CONFIG_SYSTEM file) of a git config that changes a setting (.git/config included), rsync --log-file/--write-batch files, wget -O/-P, dd of=, ex/vi/vim/nvim/view/ed file operands (also under -R, since :w! still writes), -w/-W logs, files named by write, open or dump commands in any abbreviation, after a line address (also *, \/, \?, \&, marks such as 'a, '<, '( and '{, and an address on a later | command) or :g (:w, %w, 1,$w, :wri, :sav, :x, :up, :wa, :e, :sp, :drop, :args, :redir >, :mksession, :wviminfo, :hardcopy >, ed W and f, with !, ++opt, +, +cmd or >>, and inside a literal :execute string, also after \| or an escaped space, as :execute and a cpo+=b mapping read them (exe "sil\ w FILE"); the +cmd run on the opened file, with its escaped spaces, is read as an editor command itself, as in e +w!\ FILE notes.txt or e +w!\ FILE with no file after it; a +cmd nested more than maxSubstitutionDepth deep is blocked) in -c, --cmd or +cmd scripts and in ed, ex and vim -e/-es scripts from a heredoc or here-string, and chmod/chown/chflags on a protected path or any ancestor, deleting or moving the project's settings directory (.codex, .claude, .git) itself, by name or by a glob that selects it, a write, delete, move, glob or find root through link/.. read from the link's target directory (for docs names and trees too; a cd/env -C to such a path, where logical and physical directories differ, leaves the directory unknown), and the files a recursive copy or sync tree, a patch (below git apply --directory), an archive member (at every suffix of its name under --strip-components or unzip -j) or a Git restore writes there (a patch, archive or remote source the guard cannot read is blocked above guard configuration; no docs grant lifts these), a recursive removal or move (rm -r, rsync --delete, --remove-source-files, mv, Git moves and removals) of a directory holding one that exists or whose directory exists (rsync -a --delete empty/ ., except below a plain --exclude name with no wildcards, --filter, --include or --delete-excluded; no docs grant lifts it), and find … -delete from a starting point that is, is inside or holds one (an existing protected file below it or, under -L/-follow, reached through a linked directory, or a link to one, unless a plain conjunction of -name/-iname and -type/-xtype tests before -delete excludes it, read from the last top-level -o before that -delete, since each -delete of A -delete -o B -delete removes only what its own branch selects; a missing one when find removes the existing directory that would hold it; a protected directory below it always). An editor file name expands ~, $VAR, %/# and wildcards, and after :cd a relative name has an unknown base. Substitution text is data. In an ed script the lines typed after a, i or c up to . are data too (ed exits at the first error in a script), except inside g/v or after G/V, where they are commands. vim and ex run those lines as commands when the append fails or is skipped (inside :g, a missing line or mark, nomodifiable, :if 0), so every line of a vim or ex script is read as a command. Shell commands in those editor scripts (:!, range filters such as %! and 1,2!, :r !, :w !) are evaluated as shell. A non-literal editor script, keys typed into a visual editor from a heredoc, here-string or pipe, a backtick file name, a vimscript process, file or option function (system(), writefile(), delete(), execute(), setbufvar(), …, also in a \= substitution), an embedded language (:lua, :python, …), :terminal, :shell, :source, :runtime, :make, :grep, :cscope, a :set or :let & of a program or shell option (shell, shellcmdflag/shcf, shellquote/shq, makeprg, …, also cleared, since an empty shellcmdflag runs :!notes.txt as a script) or of an expression option to a value (diffexpr, indentexpr, …; clearing one with set indentexpr= is allowed), :normal keys that run commands (!, Q, @, "=, <C-R>) or a built :execute is blocked. A glob target (*, ?, […], **, brace expansion, extglob and zsh groups, qualifiers and ^ # ~ operators, also with quoted or escaped characters inside a pattern; a fully quoted name such as "(backup)/settings.json" is not a glob) is read broadly: each group, brace, qualifier or operator becomes any text (any depth when it spans /; a repeated group spanning / also counts as absent, and from the fifth such group on the rest of the pattern is read as any path), and the target is blocked when that reading can match a protected path; * skips a leading dot unless the command mentions dotglob, GLOBIGNORE or GLOB_DOTS. cd, pushd, env -C and sudo -D move the directory used for later relative targets, and git -C the one its own targets are read from; after a conditional, backgrounded, piped or branch cd, cd -, popd, cd $(…), a missing directory or a CDPATH lookup, the directory is unknown. A path under an unknown directory (a variable prefix, ~-, or an unknown working directory) is blocked when its literal tail can name a protected path or a file below a protected directory.
  • shell-arithmetic-injection blocks text shaped like name[$(…)] in assignments, [[ … ]], for lists and name-taking builtins (let, printf -v, read, declare, export, test -v, …): bash runs that subscript when the text is later evaluated.
  • Known false positives, by design: interpreter code naming a shell next to a process API (shutil.which('bash') with subprocess in the same program), an interpreter with only preload options and no program (node -r ts-node/register), backtick prose with a destructive command inside a runner argument, glob or brace targets that could match a protected path, read-only editor sessions (vim -R, view) on a protected or test path, editor script text outside substitutions and ed typed lines that reads like a write, open or shell command (:echo "e tests/a.test.ts", or vim and ex append text such as terminal output below), conservative vimscript blocks (:make, :grep, :source, :normal keys containing ! or @), and a $(cat <<'EOF' …) commit message read as dynamic when the same command assigns arithmetic through an expansion ((( n = $x )), for ((i=0; i<$n; i++)), (( total += $x )), let i=$i+1) or stores text that assigns or steps a PATH name in a variable or array element (ARGS=--path=src, a=(--path=src), f=${f//--path/}). Known gaps: arithmetic that reads a variable holding a built assignment ((( $x )), (( n )) after read n) is not traced; editor settings such as .vscode/settings.json are not protected; editor script files (-s, -S, -u, ed < file), a SHELL prefix for the editor's :! and vimscript beyond the forms above are not read. The engine denies input over 64 KB and evaluations that exceed its own 3 s budget; the hook command denies when the engine exits abnormally, and the harness enforces the 5 s hook timeout, whose outcome on expiry is the harness's own behavior and is not verified here.

Policy 2.2.1: merge gate and temporary directories

  • merge-gate blocks gh pr merge unless it names the PR explicitly (its URL, or a number with -R owner/repo), --match-head-commit <40-hex head>, and ~/.development-system/private/merge-gates/<owner>-<repo>-<n>-<head>.json holds an unexpired pass (two hours) for that exact PR and head with mergeReady: true. Options are read wherever they sit (gh --repo o/r pr merge …); -R and --repo are one option and the last one wins, as in gh. development-system pr-review-status <pr> --gate writes the pass: a clean Codex review and, when the base is develop, behavioral evidence ok, nonvisual, waived (the owner's exact words quoted in the PR) or nonfunctional (every changed file is prose documentation). GitHub refuses the merge itself if the head moves after the check. gh api calls to the REST merge route (any host, query, encoding or slash spelling) and GraphQL mergePullRequest/enablePullRequestAutoMerge are blocked, as are a GraphQL body from --input and a GraphQL field read from a file or stdin (key=@file, @-), whatever the GraphQL endpoint's spelling. gh pr merge --disable-auto (cancelling) passes only when its value is effectively true. A gh alias set whose expansion mentions merging, gh alias import, and an existing alias in gh's config.yml that expands to a merge are blocked; URL schemes are matched case-insensitively. Read-only gh and quoted text are not affected.
  • The merge passes, evidence receipts and review records under ~/.development-system/private/merge-gates/**, ~/.development-system/private/evidence/** and ~/.development-system/private/reviews/** (locks included) are protected write targets: only the Development System CLI writes them.
  • The pass records evidence and review; it never authorizes a merge. Main, releases and production still wait for the owner.
  • Known gap: merges outside a shell (the GitHub MCP merge_pull_request tool, the web UI) and files an interpreter writes from its own code do not pass through this hook.
  • tmp-write blocks writes and archive extraction into shared temporary directories (/tmp, /private/tmp, /var/tmp, $TMPDIR) through every inspected writer (redirections, tee, cp/mv destinations, tar -C, Write/Edit/MultiEdit, apply_patch), resolving the longest existing prefix through symlinks, so a link into /tmp and a relative target after cd /tmp count. A dynamic name under a known temporary directory (/tmp/"$f") and a glob or brace pattern that can spell one (/t?p/x) are blocked too. $TMPDIR is read like $HOME. Reads, deletes, cd /tmp, mktemp and quoted text pass. Evidence and helper files go under ~/.development-system/private. Known gap: temporary files an interpreter or tool creates internally are not inspected; this is not universal prevention.

Policy 2.3.0: agent instructions, lint configuration and fewer false positives

  • docs-config-write blocks writing, editing, renaming (source and destination) and deleting files named in docsConfigNames in any directory: AGENTS.md, CLAUDE.md (so also .claude/CLAUDE.md), eslint.config.*, .eslintrc*, biome.json, biome.jsonc, oxlint.json and .oxlintrc*, case-insensitively on macOS. It covers every inspected writer and deleter (redirections, tee, cp/mv/ln, Git moves and removals, rm/unlink, sed -i, perl -i and ruby -i/--inplace and their backup files (every suffix given, attached, or for sed the next word as BSD reads it, with * as the file name; programs attached to -e included; switch clusters read per language, so -lpi, -0pi, -Wpi and ruby -dpi count, ruby -C/-X dir and -xdir move the edited files, and -c only checks syntax; switches end at the first argument, so a -c after the program file is the program's), backups cp/mv/install/rsync write with -b, --backup, -S/--suffix or BSD install -B (a recursive copy backs up every file it replaces, so each source name plus the suffix is checked below the destination or --backup-dir), attached ones included (default ~, plus any SIMPLE_BACKUP_SUFFIX the command sets as a prefix, through env or export; one it sets through read, printf -v/-vNAME, let, += (as a prefix, a plain assignment or with export), a declare -n reference, a name or value the guard cannot read is blocked; printf options end at the format, so later arguments are text), cp/mv/install -t directories attached or in a cluster (-rt.codex), BSD install -M metadata logs, tar archives written by create, append or update modes (-cf AGENTS.md; - is stdout) and the files GNU --remove-files deletes, each read under the -C in force where it appears (a -T list is blocked), GNU --index-file, --listed-incremental/-g and --volno-file files in any mode, git apply --build-fake-ancestor files (also with --stat), the -f/--file (abbreviations such as --fil included) of a git config that changes a setting (options read before --, skipping option values, so -- key --list sets a value), or the file GIT_CONFIG names (GIT_CONFIG_GLOBAL with --global, GIT_CONFIG_SYSTEM with --system; every value the command sets as a prefix, through env or export counts, and the environment's; one the guard cannot read is blocked), rsync --log-file, --write-batch/--only-write-batch (and their .sh) files, written even in a dry run, the destination of --read-batch as a tree of unknown contents, the paths rsync -R/--relative recreates under the destination (from a /./ mark, without a leading /), and --backup-dir (relative to the directory the files land in): a replaced file at dirname(destination)/backup-dir/name, and for a directory the source's names under the backup directory (the -R path kept, links followed as the copy follows them), plus the destination's whole old contents with --delete (rsync -t keeps times and names no target directory), a hard link to a protected file or a symbolic link to one or to its directory (its text read from the link's directory too; a link to a directory at or above guard configuration, project .codex/.claude and . included, is a guard-config-write), apply_patch Add/Update/Move/Delete, Edit/Write/MultiEdit/NotebookEdit), a symlink that resolves to such a file, a glob or brace pattern that can expand to one (rm *.md, {AGENTS,X}.md, through a link it selects or a brace expansion names too; a patterned or brace directory and a {1..9} sequence are walked like a glob), a diff that names one (patch, git apply, git am; Git C-quoted names decoded, each suffix of a name, as -p strips it, and links included; a patch -r reject file and -o output are checked as writes, in short option clusters too such as -frX, and every operand after the first is read as a diff; with -d the diff, the patched file and -o/-r are read under that directory, as patch opens them), a Git pathspec restored from the index or a revision (git checkout --ours|--theirs|-m|-p <paths>, git checkout <rev> <paths>, git checkout <path> when the first operand names no revision, git checkout -p [<rev>] without paths (every tracked file), matched against git ls-files and that revision's files), and a tree operation that reaches one at any depth: a delete (rm, trash, Git removals, rsync --delete or --remove-source-files, find … -delete unless a plain -name/-iname/-type conjunction before -delete excludes the protected file or link) or a move (mv and Git moves, source and destination) of a directory holding one, and a recursive copy (cp -R/-a, rsync, ditto) whose source tree holds one (cp -R docs/. ./). A trailing / or /. on a copy source names the directory's contents (a moved directory keeps its name: mv dir/ . is ./dir), and ditto copies a directory's contents into the destination. A glob source of a copy, link or move (cp -R docs/A* .) is expanded to the existing entries it selects, and each one is checked under its own name at the destination (a link keeps its own name) and as a tree; a source glob the guard cannot expand (a variable directory, a remote rsync host:dir/*) is blocked when its name pattern can match any protected name (compared pattern to pattern, so *.txt matches eslint.config.*). The tree is read from disk without following symlinks below it, up to 8 levels and 5000 entries; a copy that dereferences links (cp -L/-H, rsync -L/-k/--copy-links/--copy-dirlinks/--copy-unsafe-links) also walks each link to a directory within the same bounds under the link's own name (a second name for one directory is walked again), skips only a link back to one of its own ancestors, and is blocked on a broken or unreadable link. An entry with a protected name counts even when it is a symlink. A larger tree, an unknown operand ("$d") of a recursive delete, a move or a recursive copy source, and a glob in an unknown directory that can match a protected name are blocked, while a glob in a known directory, patterned ones included (*/eslint.config.[mc]ts), is walked within the same bounds and each path it reaches is checked by name and through links. A patch the guard cannot read (a pipe, a variable, git am --continue) and Git paths it cannot list (no repository, an unknown revision) are blocked unless a docs grant covers the whole directory. Extraction lands under -C/--directory/--cd (each read from the one before) or unzip -d, attached values and clusters included, also after an unzip -x list; listing, testing and extracting to stdout (tar -t, tar -xO, unzip -l/-p/-t/-v/-c/-z/-Z with no negated letter such as -l-l) only read. tar -xP (absolute member names) and tar or unzip with options from TAR_OPTIONS, UNZIP or UNZIPOPT are blocked. An archive (tar/unzip/ditto -x extraction) that is a literal readable file is listed with the system unzip -Z1 (zip, ditto -x -k) or tar -tf (tar family, ditto CPIO) within 3 s and 20000 members, and a member whose base name is protected is blocked unless a docs grant covers it at the target. An archive the guard cannot list (stdin or -, no -f, a variable or glob operand, a missing file, an unknown format, a failed, slow or oversized listing) or an extraction that renames members (tar -s, --transform) is blocked wherever it lands, unless a docs grant covers that whole directory. Remote contents (an rsync host:path source) cannot be read, so syncing them into a Git working tree (a .git in it or an ancestor) is blocked unless a docs grant covers that whole directory, and extracting or syncing into a directory that already holds a protected name at any depth is blocked the same way. rsync -n/--dry-run or --list-only (also in a cluster such as -avn, but not as the value of an option that takes one, such as --exclude -n) and git mv/git rm with -n/--dry-run (unless a later --no-dry-run or an abbreviation such as --no-dry turns it off) write nothing and pass these write and delete checks. A grant passes a tree operation only when every affected protected file, at its source and destination, lies inside the granted repository and every operand is fully known. Reads pass; README, ADRs and docs/ (including docs/current-work.md) are not covered. Known gaps: a non-recursive write whose name has an expansion in it ("$f", AGENTS.$ext), an archive member that writes through a symlink already in the target directory, member selection (tar -xf a.tar file, unzip a.zip -x AGENTS.md), which is ignored so every member counts, remote rsync contents outside a Git working tree, the server-chosen name curl -J saves under, output destinations set inside a curl -K/--config file (or the default .curlrc), which the guard does not read, other Git commands that rewrite tracked files (merge, pull, rebase, cherry-pick, stash pop), wget -P and chmod -R trees, and eslintConfig/biome keys inside package.json. Commands run by find -exec/-ok are checked once with {} as unknown text (so {}/hooks.json counts) and once for every protected file the expression selects before that action (tests after it do not filter it; a starting point or entry that is a link keeps its own name for -name and counts when it reaches a protected file; -L (or the -follow primary anywhere in the expression) follows links into directories; BSD option clusters with -f roots and -- are read; an unknown one-letter option, an unknown selection or more than 64 selected files stand in a protected name), so a writer or deleter there blocks while a reader passes; a word that adds text to {} ({}.json, .codex/{}.json) is built from the text find passes for every file the action selects (walked within the same bounds) and checked where it names a protected path; this walk runs only when the command writes such a word (read from the targets of the command after its wrappers such as env, so sort -o {}.json counts while sed -n p {}.json and cp {}.txt out do not; any other program counts as a writer, and a built path it would write that names a protected file is blocked), and then an unknown starting point, a larger tree or more than 64 hits fail closed; a + ends an action only right after {}; {} as the command name is blocked, and -fprint/-fprint0/-fprintf/-fls files and -delete count only outside -exec bodies; commands run by find -execdir/-okdir are checked with an unknown working directory, so every relative write operand fails closed; words xargs reads from standard input are checked as a protected name, and a replace string (-I{}) also as unknown text, so {}/hooks.json still names guard configuration; a writer fed by xargs blocks.
  • The operator lifts it for one repository and task: development-system allow-docs <repo> --task <slug> [--hours N] [--reason text] in their own terminal (default 2 hours, at most 24); --revoke <repo> ends it and development-system docs-grants lists active grants. Grants live in ~/.development-system/docs-grants.json ({schemaVersion: 1, grants: [{root, inode, task, createdAt, expiresAt, reason}]}) and cover files inside the canonical repository directory, with the same checks as test grants: unexpired, at most 24 hours long, same inode, a fully known target. allow-docs refuses agent shells and non-interactive terminals; docs-grant-self-authorization blocks literal allow-docs invocations (except in read-only Git commands) and guard-config-write protects the grant file.
  • A read-only gh api with a variable in its endpoint passes sensitive-dynamic-argument: gh api "repos/$R/pulls" (also with -X GET, --paginate, --jq, --template, an Accept header). It must be a GET (no other method, no -f/-F/--input field, no method-override header), every option literal, and the endpoint one double-quoted word after a literal prefix with plain $name/${name} variables, so it cannot split into options or a second endpoint. gh api -X DELETE "repos/$R/…", an unquoted repos/$R/pulls and any other dynamic gh argument stay blocked; literal gh calls are unchanged.
  • A variable the script's leading commands assign a plain literal path (D=~/.development-system/private/scratch/task; mkdir -p "$D"; cat > "$D/packet.json" <<'EOF') is read at that path by the write checks, so a heredoc into a scratch directory through $D passes and one into ~/.development-system/private/evidence or /tmp through $D is still blocked. The word stays dynamic for every other rule (rm "$D/x" is still sensitive-dynamic-argument) and for grants. Tracking stops for good at the first command that is not a top-level name=path assignment or a command that cannot assign variables (mkdir, cat, cp, git, node, …): a conditional, piped or backgrounded assignment, a compound command, a function or alias definition, arithmetic, ${D:=…}, read, export, cd and the like. zsh modifiers and subscripts ($D:h, $D[1]) are not substituted.

Policy 2.4.0: GNU parallel is inspected like xargs

  • parallel used to be a runner the guard did not open, so parallel touch ::: src/a.test.ts passed every write check. It is now unwrapped: options are skipped, the command runs up to :::/:::+, and literal operands after it are checked as that command's arguments; replacement strings ({}, {.}, {/}, ...) are filled with each operand, so parallel touch out/{.}.test.ts ::: a is a test-file-write. Arguments read from standard input or from :::: files are unknown text, exactly as for xargs, so a writer fed that way blocks. A single quoted command with spaces (parallel 'touch {}' ::: x) is shell text built at run time and is blocked as shell-dynamic-command, as is parallel with no command (parallel ::: ls). Readers pass (parallel node --check ::: a.mjs b.mjs).

Check a decision without installing:

node scripts/command-guard.mjs check --command 'git status --short' --cwd <repo>
node scripts/command-guard.mjs check --tool-json '{"tool_name":"Write","cwd":"<repo>","tool_input":{"file_path":"src/a.test.ts"}}'
node scripts/command-guard.mjs check --tool-json '{"tool_name":"Edit","cwd":"<repo>","tool_input":{"file_path":"AGENTS.md"}}'

Exit 0 means allowed, 2 means blocked; the JSON output names the rule. --no-grants evaluates as if no test-write or docs grant existed; the audit uses it so an active grant cannot make a healthy guard look broken.

Policy 2.5.0: MCP spend guard, spend CLI rule

DS 2.12.0 limits owner stops to five: incremental spend, destruction the owner did not order, new messages to real people, account-security changes and production (merge to main, production deploy). This policy enforces the parts a hook can see.

  • MCP tools (mcp__<server>__<tool>) are checked by scripts/mcp-guard.mjs against references/mcp-policy.json before any field is read as a shell command. Precedence: the named stop list (rule mcp-incremental-spend, mcp-destruction, mcp-message-to-people, mcp-account-security) wins; then generic executors are inspected (posthog exec passes only help|tools|search|info|schema|learn and call [--json] <target> where the target is one of the exact read targets in the policy and is followed by nothing or one JSON object; TikTok tool_execute is stopped, use the dedicated *_get tools; Linear merge_diff is stopped, merge through gh and the merge pass; expect playwright is stopped because its code runs with full Node.js access that no text scan can bound; drive pages with Browse execute, which runs in a restricted realm without process, require, import(), fs or child_process, or with the other expect tools; OpenCode Browse (browse) page tools pass, while secrets_refresh, secrets_run, network capture and settings are account-security stops; Convex run is stopped because a function may mutate, use runOneoffQuery; GitHub merge_pull_request is checked by the same merge pass as gh pr merge); then the exact allow list per governed server; anything else is mcp-unknown. No server is exempt and a name or verb never grants: an invented get_* tool, an unknown server, or a server whose tools were not observed when the policy was written (computer use, browser extensions, IDE, Jev MCP) is stopped. Comments and replies that publish to teammates (Vercel toolbar, Linear comments, reviews and status updates, Notion comments, Mobbin comments, GitHub issue and review comments through MCP) are message stops; the PR review workflow answers review threads with gh api, which this MCP policy does not govern; tools that return secrets (env values, Edge Config tokens, SDK keys, Convex envList/envGet) are account-security stops. Widening the lists is a new DS version, never an agent decision.
  • Interpreter programs are evaluated as before (every string may be a command). Each process call (run(, system(, exec*(, spawn*(, popen*(, posix_spawnp(, shell_exec(, ...) is also read as one command: the literals inside its own parentheses in order, with names the same program binds by name = ... or name += ... expanded (subprocess.run(['git'] + ['reset', '--hard']), base = ['git']; run(base + [...]), [*base, ...]). Every multi-word form is also read without its second word, since execvp/posix_spawnp(file, argv) repeat the file as argv[0]. Strings outside a call stay data. Not seen: values computed at run time (input, files, reflection, encoding); this guard stops accidents, not a deliberate bypass. To write text that only mentions a guarded command (a plan that names the merge command), use the Write tool, a cat heredoc or a commit message; those are data.
  • incremental-spend (command rule): vercel [global options] domains [options] buy|transfer-in and stripe with --live or a live key in its arguments. Test mode and reads pass. Not covered (declared gaps): paid wrangler products, paid EAS builds, spend inside a browser session.
  • The merge gate itself is unchanged: a merge to develop or main still needs --match-head-commit and a fresh pass from development-system pr-review-status <pr> --gate. A merge to main, a release and a production deploy are stop 5: after the gate passes they still wait for the owner's explicit production answer, which a general approval does not give.
node scripts/command-guard.mjs check --tool-json '{"tool_name":"mcp__plugin_vercel_vercel__buy_domain","tool_input":{"name":"x.com"}}'   # exit 2, mcp-incremental-spend
node scripts/command-guard.mjs check --tool-json '{"tool_name":"mcp__plugin_vercel_vercel__list_projects","tool_input":{}}'           # exit 0

Verify

Audit must prove all of the following:

  • the exact managed Codex and Claude Code hook entries exist alongside pre-existing entries;
  • the installed policy engine matches the current catalogued skill bytes;
  • a harmless command with a redirection (grep -n "x" f 2>/dev/null | head) is allowed;
  • git reset --hard is blocked, and a --tool-json Write to src/a.test.ts is blocked;
  • an MCP buy_domain call is stopped and an MCP list_projects read is allowed;
  • rollback restores the exact prior Codex hooks and Claude Code settings bytes when each file still holds the installed bytes; when a file changed after activation (Claude Code rewrote its settings, or the report gate or orchestration added hooks), it removes only the managed guard entry from that file and rewrites it as 2-space JSON, without touching Factory.

Do not claim T3 Code has an independent hook runtime: each T3 thread inherits the adapter of its Codex or Claude Code provider.

04 同仓库更多 Skills