---

name: common-agent-guardrails description: Define deterministic guardrails for agent tool calls — protected paths, test-file locks during bug fixes, post-edit formatters, production approval gates, secret deny rules. Use when writing or reviewing a hook policy, or moving an always-do-X rule out of prose into enforcement. metadata: triggers: files: - "guardrails.yaml" - "hooks.json" - ".claude/settings.json" - "/hooks/*.py" - "/hooks/*.js" keywords: - guardrail - protected path - block edit - approval gate - hook policy - pretooluse

Agent Guardrail Standard

Priority: P1 (HIGH)

A rule that must always hold belongs in a hook, not in a prompt. Prompts persuade; hooks decide.

1. What Belongs in a Guardrail

• Absolute compliance only: encode a rule here when a single violation is unacceptable, not when it is merely preferred.
• Deterministic check: the decision must be computable from tool name, arguments, and repo state — never from model judgment.
• Paired with a skill: the skill teaches the rule, the guardrail enforces it. Ship both or the rule decays.

2. Required Guardrail Classes

Class	Trigger	Decision
Protected paths	edit to generated, vendored, or frozen files	block
Secret deny	edit or read of .env*, .ssh/, credentials*.json|yaml, identity files	block
Test lock	test-file edit while a bug-fix workflow is active	block
Formatter	after any accepted edit	run, then report
Production action	deploy, migration, or destructive command against production	ask named owner
Scope fence	writes outside the declared task scope	ask

3. Decision Semantics

• Exit 0: allow, stay silent. Reserve stdout for the formatter class.
• Exit 2: block. Print the rule violated and the sanctioned alternative on stderr, never a generic denial.
• Any other exit: ask a human. Use it when the check is inconclusive, not as a soft block.
• Fail closed on production classes: if the guardrail cannot evaluate, treat production actions as blocked.

4. Test Lock During Bug Fixes

• Write the failing test first; the agent proves the bug reproduces before touching production code.
• Lock every test path for the duration of the fix so the proof cannot be weakened into passing.
• Unlock only when the fix is verified, or when the operator states the test itself is the defect.

5. Placement and Ownership

• Team level: repository-tracked config, reviewed in pull requests like code.
• Organization level: managed settings the project cannot override; use for secret deny and production gates.
• Log every decision: timestamp, rule, tool, target, and outcome. An unlogged block is unauditable.
• Version the policy: a guardrail change is a control change and needs the same review as the control it enforces.

Anti-Patterns

• No prompt-only rules: If it must always hold, enforce it in a hook.
• No broad path globs: Name the protected directories, not the whole repo.
• No silent blocks: Print the rule and the allowed alternative.
• No agent self-approval: A human role authorizes production actions.
• No guardrail without a skill: Pair enforcement with the rule that explains it.
• No unlogged decisions: Record every block and ask.

Red Flags

• Stop if "just this once, disable the hook": Re-run with the sanctioned path or escalate to the policy owner.
• Stop if the fix edits the failing test: Restore the test and fix the production code.
• Stop if a production command runs with no named authorizer: Block and request sign-off.

References

• Guardrail Policy Template
• Runtime Adapters

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• exit 2 blocks
• protected paths
• test lock
• approval gate
• fail closed
• log the block decision