Skip to content

What each guard hook blocks, and how to extend one without breaking your session

Guard hooks stop the mistakes that cost the most, in every coding agent that runs hooks. What each one refuses, how the exit codes work, and how to add your own safely.

Next.js on Vercel7 min readships at docs/solutions/nextjs-vercel/guard-hooks-and-how-to-extend-them.md

Tags: hooks · safety · security · tooling · claude-code · codex · cursor

Rules are advice. An agent reads them, agrees with them, and then does something else at 11pm on a long task because the context window filled up and the rule scrolled away. Hooks are different: they run in the harness, outside the model, and they cannot be reasoned around.

Your guards live in .agents/hooks/, one script each. The exact set depends on what you picked. Team mode adds two. A battery can add its own: Neon adds guard-neon-sql. env-leak-detector is one guard split into two scripts, a before half and an after half.

The design rule behind all of them is the same: a guard should refuse the small set of actions whose cost is unrecoverable, and stay out of the way for everything else. A hook that fires on ordinary work gets disabled within a week, which is worse than never having it.

One script, every agent

Every coding agent that runs hooks has its own config file, its own event names and its own payload. The guards do not care. Each entry in each config runs the same launcher, .agents/hooks/run.mjs <guard> --from <agent>. It turns that agent's payload into one shape (Claude Code's hook format), runs the guard, and answers in the agent's own format. .agents/hooks/guards.json is the table it reads: each guard's event, tools and script.

AgentHook config
Claude Code.claude/settings.json
Codex.codex/hooks.json
Cursor.cursor/hooks.json
GitHub Copilot.github/hooks/agentic-guards.json
Gemini CLI.gemini/settings.json
Antigravity.agents/hooks.json
Windsurf (Devin).devin/hooks.v1.json

A repo only has the configs for the agents it was set up for. OpenCode, JetBrains AI and Kiro run no hooks, so there the rules in AGENTS.md are all you have. Not every agent has a hook for every tool either, so a guard can cover less in one agent than in another. .agents/hooks/README.md says which guard runs where.

The mechanism, in four lines

A guard is a program. It receives a JSON payload on stdin describing the tool call, and it answers with an exit code:

  • exit 0: allow. Anything on stderr is informational.
  • exit 2: block. stderr is shown to the agent as the reason.

PreToolUse runs before the tool and can prevent it. PostToolUse runs after, so it cannot prevent anything. What it does instead is exit 2, which surfaces the problem as a blocking error on the very next turn, while the agent still has the context to fix it. Those are Claude Code's event names. The guards use them in every agent, and the launcher maps them to each agent's own.

A hook can also answer with JSON on stdout and exit 0. PreToolUse can return permissionDecision: "deny" (what guard-neon-sql does) or updatedInput to run a corrected command instead (what enforce-typecheck does). PostToolUse can return updatedToolOutput to change what the agent sees (what env-leak-detector-write does to redact live secrets).

The last two only work in Claude Code. Everywhere else the launcher turns a rewrite into a block that names the command to run instead, and output redaction does not happen, so the check before the command is what stops a leak. Build a new guard to protect by blocking. Never count on a rewrite or a redaction.

The payload the guard sees is roughly:

{
  "tool_name": "Bash",
  "cwd": "/Users/you/project",
  "tool_input": { "command": "rm -rf dist" }
}

For Edit / Write / MultiEdit, tool_input carries file_path plus content, new_string, or an edits array. The shape differs per tool, which is the first thing that catches people writing a new hook.

What the stack ships, and what each one refuses

HookEventRefuses
block-destructivePreToolUse Bashrm -rf, DROP/TRUNCATE sent to a database client, an inline script (bun -e) or curl, git push --force, git reset --hard, git clean -f, dd, and > truncating a tracked file
env-leak-detectorPreToolUse Bash, Read, GrepA credential in a command, any read or send of .env.local (cat, grep, sed, curl -d @, the Read tool), bare env, echo $DATABASE_URL unless a sed really masks it, git add .env
env-leak-detector-writePostToolUse Edit, Bash, Read, GrepA secret literal written into source, a live .env value inlined, a non-public process.env read in a "use client" file, a secret being logged. In Claude Code it also redacts live values from command and read output (updatedToolOutput)
enforce-typecheckPreToolUse BashA bare tsc. Claude Code runs bun run typecheck in its place (updatedInput). Other agents get a block that names that command
auto-lintPostToolUse EditNothing: it formats the edited file and reports what Biome could not fix
enforce-git-trackedPreToolUse Bash (team)A git commit while untracked files are loose
enforce-doc-metaPostToolUse EditA solution doc or plan missing its frontmatter
plan-gatePreToolUse Edit, Write, Bash (team)An edit or shell write under src/ with no approved or in-progress plan in docs/plans/

enforce-git-tracked and plan-gate carry modes: [team], so they are only emitted in team mode. Solo mode is one author and one clone, where neither failure exists. The other six in this table are always on.

The wrong way to add one

#!/usr/bin/env bun
// blocks any command mentioning the production database
const payload = JSON.parse(await Bun.stdin.text());
if (payload.tool_input.command.includes("prod")) {
  console.error("no");
  process.exit(2);
}

Four defects, and every one of them will hurt within a day.

It crashes on malformed input. JSON.parse throws on empty stdin, and tool_input.command throws when the tool was Read. You get to debug that while every tool call in the session is failing.

It matches too much. improve-product, reproduce, prod-preview. Users learn to ignore it, then turn it off.

The message teaches nothing. "no" says neither what was refused nor what to do instead, so the agent's next move is to try a variation.

It has no timeout. A hook that shells out and hangs hangs the session.

The right way

Copy the shape every hook in .agents/hooks/ already uses:

#!/usr/bin/env bun
import { readFileSync } from "node:fs";

const ALLOW = 0;
const BLOCK = 2;

interface Payload {
  tool_name?: string;
  cwd?: string;
  tool_input?: Record<string, unknown>;
}

function readPayload(): Payload | null {
  try {
    const raw = readFileSync(0, "utf8");
    if (raw.trim() === "") return null;
    const parsed: unknown = JSON.parse(raw);
    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
    return parsed as Payload;
  } catch {
    return null;
  }
}

/** Split a shell line so `build && rm -rf dist` is checked segment by segment. */
function segments(command: string): string[] {
  return command.split(/\|\||&&|[;\n|]/g).map((s) => s.trim()).filter((s) => s.length > 0);
}

function main(): void {
  const payload = readPayload();
  if (payload === null) {
    process.stderr.write("my-guard: unreadable hook payload, allowing.\n");
    process.exit(ALLOW);
  }
  if (payload.tool_name !== undefined && payload.tool_name !== "Bash") process.exit(ALLOW);

  const command = typeof payload.tool_input?.command === "string" ? payload.tool_input.command : "";

  for (const segment of segments(command)) {
    if (!/\bpsql\b[^\n]*\bprod\b/.test(segment)) continue;
    process.stderr.write(
      "BLOCKED by my-guard: psql against production.\n\n" +
        `Segment: ${segment}\n\n` +
        "Do this instead: run it against the branch database, or ask a human to run " +
        "the statement with a transaction they can roll back.\n",
    );
    process.exit(BLOCK);
  }

  process.exit(ALLOW);
}

main();

Five properties worth copying literally: fail open on a bad payload (a guard that bricks every call is worse than the risk it covers); check the tool name before assuming the input shape; split on shell operators so a chained command cannot smuggle anything past; name the hook and the offending segment in the message; and always say what to do instead, because a block with no alternative is a block the agent will try to work around.

Wiring it up, and proving it works

Drop the script in .agents/hooks/, say .agents/hooks/my-guard.ts. A script on its own does nothing. Wire it in three places:

  1. .agents/hooks/guards.json: an entry for my-guard with its event, its matcher and its script file. The matcher uses Claude Code's tool names, and a matcher made of plain tool names is an exact list: Edit|Write does not match MultiEdit, so name every tool you mean (Edit|Write|MultiEdit).
  2. Every hook config your repo has (the table above). Each entry calls run.mjs my-guard --from <agent> under that agent's own event and tool names. Copy an existing guard's entry in the same file and change the id.
  3. .agents/hooks/README.md: what it refuses, and which agents run it.

Then, always:

bun run verify:hooks

That script runs each guard through the launcher, in the format of every agent your repo has a hook config for, attempts each blocked action and confirms it was stopped. Add your guard's cases to scripts/verify-hooks.ts in the same change. Guards die in exactly two silent ways (a hook config loses its wiring, or a script stops parsing), and this is the only thing that notices either. Run it after any edit under .agents/hooks/ or to a hook config, and before a release.

Tightening an existing one

Say you want plan-gate to require that the edited file appears in the approved plan's ## Files section, not merely that some approved plan exists. Keep the plan body when you parse the file, then test the target path against it:

// in readPlans(), alongside title and status:
plans.push({ name, title, status, contradictory, body: text });

// in main(), replacing the "any open plan" test:
const open = plans.filter((plan) => OPEN_STATUSES.has(plan.status) && !plan.contradictory);
if (open.some((plan) => plan.body.includes(gated.path))) process.exit(ALLOW);
// otherwise block, naming the open plans that were checked

Make that change in its own commit, with the reason in the message, and re-run bun run verify:hooks. Never loosen a guard in passing during other work. A guard weakened inside an unrelated diff is a guard nobody agreed to weaken.