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
- 参考文档agents/openai.yaml274 B
- 参考文档references/policy.json8.3 KB
- 脚本scripts/command-guard.mjs145.2 KB
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
PreToolUseadapter, matched onBash|exec|apply_patch. - Claude Code uses a
PreToolUsehook in its user settings, matched onBash|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/nullare data.grep "git reset --hard" docsandgit commit -m "..."pass. $(…), backticks,<(…)and>(…)are evaluated recursively up tomaxSubstitutionDepth(4);$((…))is arithmetic.$(cat <<'EOF' … EOF)(the usual commit-message form) is read as its literal heredoc text unless the command can change whatcatruns, in which case it is dynamic: acatfunction (also zshfunction a cat { … }),alias,hashorenablenaming cat (also aftercommand,builtin,noglobornocorrectand their options), atrapaction naming cat or PATH or built at run time, zshautoload catorfunctions -c f cat, aPATHor zshpathassignment 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 inn = ${#path} + $#, and plain names, as ini += 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.jsdoes 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, zshset -A, also inside an option cluster such asprint -rv, …), a nameref (declare -n,local -n), or a function table entry (bashBASH_CMDS/BASH_ALIASES, zshfunctions,commands,aliases). Unquoted heredoc bodies are scanned for substitutions. A heredoc or here-string fed to a shell (orsource /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, anawkprogram orawk -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;,&,|,(,{orthen/do. They are skipped for pure-read commands (readOnlyCommands,sedwithout-i/e/w,awkwithoutsystem(/pipes/redirection). - Rule
matchvalues:command(default; canonicalname 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 -cwith 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 tosensitiveCommands(rm,dd,mkfs,diskutil,gh,terraform,pulumi,kubectl,wrangler,vercel, and git outsidereadOnlyGitSubcommands). Executed inline Git configuration (-c alias.x=…,core.pager) and program-naming variables (GIT_PAGER=…) are evaluated as commands. git-discardallowsgit checkout --ours/--theirsandgit restore --staged.test-file-writeblocks creating or modifying paths matchingtestFilePatternsinside the payloadcwd: redirections,tee,cp/mv/installdestinations,sed -itargets,git diff --output, Edit/Write/MultiEditfile_path, NotebookEditnotebook_path, and apply_patch*** Add File:/*** Update File:/*** Move to:. Deleting test files is allowed.guard-config-writeblocks writes toprotectedWriteTargets:~/.codex/hooks.json,~/.codex/config.toml,~/.claude/settings.json,~/.claude/settings.local.jsonand the installedglobal-agent-guardrailsskills (~,$HOMEand absolute spellings), plusprotectedProjectWriteTargetsinside the payloadcwd(.claude/settings.json,.claude/settings.local.json,.codex/hooks.json,.codex/config.toml, and.git/config, whose aliases run commands; usegit configinstead). Writers include redirections,tee,sponge,cp/mv/install/ln, recursivecp/rsync/dittoandtar/unzip/patchrooted above a protected path,perl/ruby -i,curl -o/-O,wget -O/-P,dd of=,ex/vi/vim/nvim/view/edfile operands (also under-R, since:w!still writes),-w/-Wlogs, 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 >, edWandf, with!,++opt,+,+cmdor>>, and inside a literal:executestring, also after\|or an escaped space, as:executeand acpo+=bmapping read them (exe "sil\ w FILE"); the+cmdrun on the opened file, with its escaped spaces, is read as an editor command itself, as ine +w!\ FILE notes.txtore +w!\ FILEwith no file after it; a+cmdnested more thanmaxSubstitutionDepthdeep is blocked) in-c,--cmdor+cmdscripts and ined,exandvim -e/-esscripts from a heredoc or here-string, andchmod/chown/chflagson a protected path or any ancestor. An editor file name expands~,$VAR,%/#and wildcards, and after:cda relative name has an unknown base. Substitution text is data. In anedscript the lines typed aftera,iorcup to.are data too (ed exits at the first error in a script), except insideg/vor afterG/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%!and1,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:setor:let &of a program or shell option (shell,shellcmdflag/shcf,shellquote/shq,makeprg, …, also cleared, since an emptyshellcmdflagruns:!notes.txtas a script) or of an expression option to a value (diffexpr,indentexpr, …; clearing one withset indentexpr=is allowed),:normalkeys that run commands (!,Q,@,"=,<C-R>) or a built:executeis 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 -Candsudo -Dmove the directory used for later relative targets; after a conditional, backgrounded, piped or branchcd,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-injectionblocks text shaped likename[$(…)]in assignments,[[ … ]],forlists 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')withsubprocessin 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 asterminal output below), conservative vimscript blocks (:make,:grep,:source,:normalkeys 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 ))afterread n) is not traced; editor settings such as.vscode/settings.jsonare not protected; editor script files (-s,-S,-u,ed < file), aSHELLprefix 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 --hardis blocked, and a--tool-jsonWrite tosrc/a.test.tsis 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
working-backwards
Define a software feature through PRFAQ and staged documents when the user requests working backwards before coding.
flow-implement
Implement a requested software change through verification, corrections, and its authorized delivery endpoint.
development-steward
Run the scheduled, read-only weekly maintenance review for the six explicitly opted-in repositories and prepare one concise private report for Check-in.
grill-with-docs
Run one recoverable interview for functional, visual, or mixed software grills; reuse equivalent answers and offer the shared HTML questionnaire.
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.
impeccable
Design or refine frontend UI using project context and a focused design playbook; also handles visual critique and polish.