All writing
2026-11-15·6 min

Guardrails That Read Agent Commands Must Refuse What They Cannot Read

I built hooks that stop a coding agent from opening unreviewed pull requests or merging unchecked code. Review rounds got past them with ordinary shell. What failed, the rule that held, and the fix of mine that reopened the hole.

A coding agent with a shell can open a pull request, merge it and move on. If review matters, something has to stop it from skipping that step, and a prompt that says "always open a draft" is a request, not a control. So I put the rule in a hook: a small program Claude Code runs before every shell command the agent issues, which can refuse the command.

The hooks enforce four things. A pull request is opened only as a draft. A merge goes ahead only when the pull request has left draft and, for a pull request from the same repository, GitHub's view of its head matches the branch tip. The files that define these rules cannot be changed through the agent's edit tools until a person unlocks them. And branches the agent creates with git checkout, switch, branch or worktree carry a configured prefix. They ship as the fabric-gates plugin in agentic-fabric, with the tests referenced below.

The first version read the command text

The first gates searched the command for the words that mattered: "gh pr create" without "--draft", or "gh pr merge" followed by a pull request number. That handled what an agent usually types. Then I put each version through review rounds whose job was to get past it, and every round did, with ordinary shell:

  • Run it through another program: bash -c '...', eval, or a prefix such as caffeinate or find -exec.
  • Hide it in shell structure: a brace group, an if or for block, or a heredoc on the same line.
  • Check one thing and run another: a second merge chained after a checked one, or a flag's value mistaken for the pull request number.
  • Build the words at run time: cre''ate, cre${x}ate, {create,}, or a variable as the program name.

Each fix added a pattern, and the next round found a form the pattern did not cover. This is the same failure as a keyword list used as a security control. The list of ways to write a shell command is open-ended, so a gate that tries to recognise the bad ones is always one form behind.

The rule that held: one plain form, refuse the rest

I turned the problem around. The gate now checks a command only when it is a single plain invocation, parsed with shell-style quoting rules and with every flag value accounted for. Any other command that would run the pull request subcommand is refused with a short instruction: run it on its own. The gate no longer needs to understand every shell construct. It needs to understand one, and say no to everything else.

  1. The agent issues a shell command; the gate hook runs before it.
  2. A command that does not create or merge a pull request, including one that only mentions it in a message, runs unchanged.
  3. A command that does must be one plain invocation; any other form is refused with 'run it on its own'.
  4. A plain invocation is checked against the rules: a draft to create, a ready pull request at the branch tip to merge.
  5. If the hook fails, the command is refused rather than allowed.
The gate understands one form and refuses every other form that could act. A hook that crashes, times out or cannot read its input refuses too.
  • Chains, pipes, subshells, brace groups and control flow around the command are refused.
  • Command substitution, heredocs, here-strings and environment prefixes are refused.
  • A word built by expansion, such as cre${x}ate or {create,}, is refused; $ and braces elsewhere, as in gh pr view "$N", are not affected.
  • Creating or merging a pull request through the raw API, and a gh alias that expands to it, are refused.
  • A mention inside ordinary data, such as a commit message, is allowed, unless the same command also uses a heredoc or substitution.

The cost is visible. An agent now runs git push and the pull request command as two steps, and passes a pull request body from a file instead of a heredoc. An unknown flag is refused until the gate learns it. Every refusal says why, and most say what to do instead, so the agent usually recovers without a person stepping in.

The fix that reopened the hole

The strict rule had one irritating side effect: writing notes that merely mentioned these commands through a quoted heredoc was refused. I relaxed it so that quoted heredoc text counted as data. The next review got 13 executable forms past the gates, among them a heredoc marker inside quotes, a heredoc piped to bash, and a heredoc captured into a variable. Telling data from code inside shell text is the problem the rule was built to avoid.

I reverted to refusing every heredoc in such a command. The lesson I took: loosening a security control to remove friction is a security change. It needs the same adversarial review as the control itself, and the earlier attack cases have to be run again against it.

How the evidence was produced

  • The reviewer did not stop at the gate's decision. Each command the gate allowed was run against a stand-in gh that logged what was actually called, so a bypass meant a logged pull request without a draft flag, not a theory.
  • Every bypass became a regression test, checked to fail on the version it beat and to pass on the fix.
  • Everyday commands that must keep working are tests too, so tightening the gate cannot quietly break normal use.
  • The reviews that found the hardest cases were run by a model from a different family than the one that wrote the gates. Its blind spots did not match mine.

Fail closed means checking how the hook fails

A gate that crashes should block, not wave the command through. Claude Code supports this with onFailure set to block, and on version 2.1.301 a hook that exited with an error or timed out did block the call. A hook that printed malformed output and exited normally did not: the command ran. So each gate also catches its own errors and turns them into a refusal, including a missing jq, an unreadable payload and a command over 20,000 characters. The repository includes a script that reproduces these cases.

What these gates do not stop

The gates see the agent's tool calls, not its intent. They do not stop a shell alias, function or script that runs gh, a gh alias created before the gate was installed, a program the gate does not know that runs a command given as a string, writes to protected files through the shell, or the merge of a commit other than the one that was reviewed (pin that with --match-head-commit). The web interface and curl or another HTTP client bypass them entirely. They are the fast local layer. Repository rules on the server, a required review and a required check, are the backstop and should be on regardless.

Takeaway for anyone building agent guardrails: decide the one form you will accept, parse it completely, refuse everything else that could act, and state what the gate cannot see. Test the refusals with commands that actually run, and treat every relaxation as a new attack surface.

agentic-fabric on GitHub: the fabric-gates plugin, its tests and the decision record (opens in a new tab)Decision record: why the gates accept only the plain form (opens in a new tab)