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 资源文件 3

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.
  • Claude Code uses a PreToolUse hook in its user settings, matched on Bash|Monitor|Edit|Write|MultiEdit|NotebookEdit.
  • 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.

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.0.0: quote-aware evaluation

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: 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 (~, $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, 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. 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; 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.

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"}}'

Exit 0 means allowed, 2 means blocked; the JSON output names the rule.

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;
  • 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