- name
SKILL.md
技能檔案保留在發布者的儲存庫中。
在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add phuryn/product-engineering --skill guardrail-hooks -a cursor -y在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add phuryn/product-engineering --skill guardrail-hooks -a claude-code -y在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add phuryn/product-engineering --skill guardrail-hooks -a codex -y在終端機中貼上複製的指令。它會將這個 SKILL.md 安裝到對應的代理中。
npx skills add phuryn/product-engineering --skill guardrail-hooks -a grok -y在 Grok Bot 聊天中傳送複製的訊息。Bot 會從 GitHub 取得這個 SKILL.md,並加入你所有 Bot 共用的技能中。
Install this skill: https://github.com/phuryn/product-engineering/tree/HEAD/agent-harness/skills/guardrail-hooks來自發布者
Make rules that depend on memory at decisive moments into code paths. Prose loses that contest to everything else the agent has read. Apply the agent-instructions skill for the principle, evidence and test question in its prose-vs-code reference. This skill covers choosing the code path, writing a hook without noise, and two hooks to adapt.
Choose the smallest code path that holds the rule. A permission rule beats a hook. A refusal inside your own tool beats both, because it holds for every agent and every human running it.
For instruction-file rules held by code, state enforcement and its limits. For example: “Bash is held by a hook; MCP tools and browser clicks are not covered, so the rule still binds there”.
Each rule came from a receipt.
.delete_post(), never a CLI string a docstring might quote. scripts/block_wrong_identity.py matches per command segment and only on commit for --author. It allows git log --author=<address> and tests whose JSON merely contains the address.python cleanup.py. Open local scripts the command runs, and heredoc bodies fed to an interpreter, and scan them with the code rules. A delete can be callable from any inline script.ask forces a human prompt even in auto mode, and denies in non-interactive runs where nobody can answer. deny refuses and tells the agent why. Exit 2 refuses and is the one form Claude Code, Codex and Cursor all honor. Address the agent in the reason too: “Agent: never approve this on the owner's behalf”. A prompt it can talk the owner through is a formality.2026-10-25). A message clears a block only when it names the action and its specifics, such as the branch of a force push (permission-modes docs, read 2026-10-25). The verb alone is insufficient. A prompt forced by an ask rule or hook needs the click whatever was said. If the owner answered on a side page, ask for the go in conversation, naming the action and target."onFailure": "block" (Claude Code 2.1.295 or later) and use exit 2, never 1, to block. Watch the first run for a hook error notice. A mistyped settings path means the hook never runs and nothing else says so.The scripts use standard-library Python and read and write UTF-8 explicitly. On Windows, Python otherwise decodes the pipe with the ANSI code page. Configure them in a top-level CONFIG block, a JSON file or environment variables. They read tool_input.command for Claude Code and Codex, or top-level command for Cursor's beforeShellExecution.
Block an address that must never author a commit, and still allow searching for it.
Install for Claude Code:
.claude/hooks/ for one project, committed, or ~/.claude/hooks/ for every project on your machine; cloud sessions don't read it.-c/-e and echoed code too, also list a code rule's pattern under command_rules; it then asks when a command only names the call, such as a grep for it. Run python .claude/hooks/test_hooks.py, or python ~/.claude/hooks/test_hooks.py for a machine-wide install.args) passes the path as one argument with no shell to mangle it:{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "python",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block_wrong_identity.py"], "onFailure": "block" },
{ "type": "command", "command": "python",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/guard_one_way_doors.py"], "onFailure": "block" }
]
}
]
}
}
In ~/.claude/settings.json, give the absolute path with forward slashes; there is no project directory. Use python3 where python is Python 2 or missing.
4. Check both hooks in /hooks, then run the canaries. Ask the agent to run true guard-canary, then true user.email=<an address you blocked>. true does nothing, so nothing runs whether or not the hooks are wired. The one-way-door guard answers its canary whatever its rules: a prompt labelled [settings] (ask mode) or a refusal naming the canary (deny or block mode) means it fired; decline the prompt. The identity hook refuses the second by its text, which also proves it holds an address. Anything else means that hook is not wired, or, for the identity hook, has no address. Never test a guard with a real one-way door: when the hook is not wired, it runs.
Use block mode and trust each Codex hook after every edit. Wire the same scripts in .codex/hooks.json and set mode to block. Codex parses ask but doesn't support it yet: it marks the run failed and lets the call through (read 2026-10-24). Trust each hook in /hooks, then again after every edit.
Register Cursor hooks on beforeShellExecution in block mode. Or adapt the output to its {"permission": ...} shape. Read references/hook-contract.md for details.
Shell-form hooks run through Git Bash, which eats backslashes. Use forward slashes or exec form.
tool_input paths before matching segments. They arrive with backslashes even under Git Bash. Use path.replace("\\", "/") before matching a segment such as /src/, or the check silently never matches.2026-10-24); run a current version and set onFailure.2026-10-24.windows-agent-shell skill for the remaining Windows traps.Recheck vendor facts before relying on them, or every few months. Every vendor fact here is dated; hooks change monthly.
claude --version, then read https://code.claude.com/docs/en/hooks.md (append .md for the raw page). Check exit codes, permissionDecision values, onFailure and Windows notes. Correct references/hook-contract.md and its dates.ask before keeping its block advice. Read https://developers.openai.com/codex/hooks; if supported, the guard's block advice for Codex can go.ask and their input shape. Read https://cursor.com/docs/agent/hooks.python .claude/hooks/test_hooks.py, or python ~/.claude/hooks/test_hooks.py machine-wide), then both canaries, as Install step 4 does. A test proves the script; only the live canaries prove the wiring.Each rule's origin, the case that taught it, is in receipts.md beside this file; read it when a rule's edge is unclear.
The hook asks or blocks on a sample that must trigger and stays silent on look-alikes. The debug log shows it fired on the canaries in a real session.
An agent keeps breaking a rule ('it did it again', 'make this impossible', 'add a hook', 'my hook didn't fire'): make it a hook, permission rule or script.
---name: guardrail-hooksdescription: An agent keeps breaking a rule ('it did it again', 'make this impossible', 'add a hook', 'my hook didn't…---# agent-harness/skills/guardrail-hooks/SKILL.md常見問題
從發布者下載 agent-harness/skills/guardrail-hooks/SKILL.md,或複製路徑後開啟儲存庫。PlugMCP 只收錄這項技能,不代管檔案。
發布者將它存放在 https://github.com/phuryn/product-engineering。
Claude、Cursor、Codex 和 Grok Build 可以讀取你從發布者儲存庫加入的 SKILL.md。在聊天中傳送技能的 GitHub 資料夾連結,Grok Bot 就會安裝它。
scripts/test_hooks.py does this, testing the guards in its own folder: run the copy beside the hooks you installed, and replace its cases when you replace the rules.PreToolUse fires on tool calls only, not files the user @-mentions. A Bash matcher doesn't cover an MCP tool or browser doing the same thing. Codex's docs say some tool paths opt out of hooks entirely. A hook is a guardrail, not a sandbox.Stop. continue: false from a Stop hook stops the agent and takes precedence over event-specific “continue” decisions. This lets a spend fuse beat /goal, itself a Stop hook (precedence confirmed in docs, read 2026-10-24). A blocking Stop hook must check stop_hook_active; Claude Code ends the turn after 8 consecutive continuations anyway.