Guardrails: block risky commands before your agent runs them.

A deny list is the half anyone can ship

Every tool that runs shell commands for you can be handed a list of commands to refuse. That list is a commodity, and writing it is not the hard part. The hard part is that the list you write from imagination protects you against the disasters you can picture, and the one that has already cost your team a day is usually not on it.

Harbor starts from what your team has already written down. The command that cost somebody a day is usually named somewhere afterwards, in a rule or in a deny entry added to a repo’s settings. Harbor reads those, with the package scripts and tools your repos use, and puts the guardrails they point at in front of you. You still decide which ones refuse.

Hooks or CLAUDE.md: which enforces a rule?

A hook does. CLAUDE.md, AGENTS.md and Cursor rules are context: the agent reads them along with everything else in its window, and nothing stops it acting against a line it read. A PreToolUse hook runs before the tool call itself, outside the model, and can refuse the call whatever the agent decided.

So the two do different jobs. A rules file is where you say how your team works (which agent reads which rules file), and harbor init and harbor bind send the committed ones to Review as proposed rules. A guardrail is for the short list of things that must not happen even once: force-pushing a shared branch, deleting a source tree, resetting a database. Harbor’s guardrails run in the hook it installs for each agent, and the refusal goes back to the model as the reason its call was stopped, so the agent learns the rule at the moment it matters instead of somewhere in a long file.

Claude Code has its own deny list, permissions.deny in .claude/settings.json, and it is worth keeping. Harbor reads those entries to suggest guardrails. What a Harbor guardrail adds is the same rule in Codex, Cursor and Copilot as well, on every machine on the team, a reason and a safer command in the refusal, and a count of how often it fired.

How do I stop Claude Code from running a command?

Turn on a guardrail for it, and the PreToolUse hook Harbor installed refuses the call before it runs, in Claude Code and in Codex, Cursor and Copilot too. Three steps:

1. Turn it on

   In the web app, open Guardrails. If the command is in the library, press Add and it blocks. If it is not, New guardrail takes the program, its subcommand and its flags, and starts in Observe until you move it to Block.

2. Let it arrive

   A machine where an agent is working fetches the new rule in the background, at most every 30 seconds, and refuses from its next tool call after that. Nothing to restart.

3. Check it

   In the repo, harbor check "git push --force" prints which guardrail stops the command and what the agent will read. The hook examples for Claude Code, Codex, Cursor and Copilot below walk through a force push, rm -rf and a database reset.

Start from the library

Guardrails live in the web app, on Guardrails, in two parts. On now is every guardrail your team has turned on: the command, what the agent is told when it is stopped, how often it has fired, and whether it observes, holds or blocks. Library is the ready-made ones on shelves by tool: Git, GitHub, Databases, Docker, Cloud and releases, Files, MCP servers.

Suggested for you comes first, and it holds only the commands your team has already asked for:

• a rule in your team’s knowledge that names the command
• a package script in a bound repo that runs it
• a Bash(…) deny entry in a repo’s committed .claude/settings.json
• a tool your repos use, such as Docker, Terraform or a published npm package

A deny entry that names a command no ready-made guardrail covers is still suggested, as its own guardrail titled This repo’s Claude settings deny … with the command it denies. An MCP guardrail is never suggested here. Which MCP servers a person installed lives in their own agent config, not in a repo, so those guardrails sit on the MCP servers shelf only.

Prisma’s commands are not on the shelves. They are still built in, and a rule, a deny entry or a package script that names one still puts it under Suggested for you.

Add turns a row on at block, and the toast that confirms it says so and offers Undo: Blocking git push --force. Each machine refuses it from its next sync. The row says On, in Block where it stands rather than moving. Open a row for what the agent is told, what it is offered instead and why it is suggested; a suggestion you do not want goes with Not for us.

Once a guardrail is on, a machine where an agent is working picks it up within about a minute, and on the first turn of the next session Claude Code and Codex tell the developer, once: Your team now stops … in this repo. Why: … A rule that changes what happens to somebody’s next command should not be something they learn from its first refusal. The line says what this machine will actually do, so it has four forms:

A guardrail that moves from counting to stopping is said again, because it is a different fact about the next command. Past three new ones the session names three and says how many more come next time. In a folder outside any repo, in this repo reads in folders outside a repo. Cursor and Copilot have nowhere to show the line, so their sessions do not use it up. The line names command and file guardrails only. A guardrail on an MCP tool is not announced, and neither is a rule somebody wrote into their own guardrails.json, which they already know about.

Three rungs: observe, hold, block

A rule observes, holds or blocks. Observing resolves the command, counts what the matcher would have caught, and stays silent. Blocking returns a refusal to the agent instead of letting the tool call run.

Holding means a person confirms each call. In Claude Code the agent pauses on Claude Code’s own permission prompt, with the rule’s reason beside it, and the person at the keyboard approves or denies. Codex and Cursor cannot pause on this event: Codex accepts only a refusal there, and Cursor lets an “ask” through with no prompt at all. So on those two, on Copilot and on Devin, a held call is refused, with a code a person can use to let that one call run. A hold that quietly let the call through on every host but one would be the failure this whole ladder exists to avoid.

The wording follows the host. Claude Code’s prompt ends Held by the git-push-force guardrail. It runs only if you approve it here. followed by the harbor dispute line for a rule that is wrong. Everywhere else the refusal says Held by the git-push-force guardrail. A person must confirm this call, and this agent cannot pause to ask them. and then gives the code.

There is no warn rung. A warning needs a channel that reaches the agent without stopping it, and this event has no dependable one on every host. The value is still in the database enum, unreachable.

A rule is bound to the command, not to how it was spelled

A guardrail is not a pattern over the text somebody typed. The hook resolves the command first, then compares the resolved { program, argv } against the rule. That is the difference between a product and a regex, and it is worth being concrete about what resolving buys.

• The program is its own name. terraform, /usr/local/bin/terraform and ./bin/terraform are one program, so a rule written the obvious way catches the spelling nobody thought to write down.
• Shells are entered, not judged on their wrapper. bash -c "rm -rf build" is read as the command inside it rather than as a run of /bin/bash, and a grouping paren or a $(…) in front of a real command does not hide it.
• Script indirection is followed. An npm run that reaches a destructive command two package manifests away resolves to the command, which is precisely the invocation a pattern over the typed string never sees.
• Operands are classified, not just counted. Deleting a build directory and deleting a source tree are the same command with different targets, and a rule can say it cares about one and not the other. The worst target in a call decides the call.

The matcher itself is a small predicate rather than a language: program, leading subcommand words, flags that must all be present, flags where any will do, flags that must be absent, a token the operands have to follow, and a minimum number of operands. That last one is the difference between git checkout -b feat/x and git checkout -- src/index.ts, one of which is how you start work and the other of which destroys it.

Everything that has to be true before a command is refused

Four things. Two are switches somebody sets on purpose: the rule is off until somebody turns it on, and refusals are on until somebody turns them off on their machine. The other two say where Harbor works at all. Any one machine can opt out of refusals with one line.

One thing lets a single call through when all four are true: a person’s harbor allow-once, with the code from the refusal and a reason. It lifts that one call, once, and the reason goes on the rule’s record. The lift waits 10 minutes for the agent to try again. A refusal’s code can be lifted or disputed for 24 hours after it was printed.

Somebody who switches a team rule down on their own machine, by setting it to observe in guardrails.json, is not doing it in secret. The rule’s row under On now shows off for 1 person, a count and never a name, once that machine has reported the rule firing.

Watching needs neither switch. An observing rule counts on every machine it reaches, in every folder Harbor works in, refusals switched off or not, because gating the counter on the switch that authorises stopping people would leave a team with no way to see how often a rule would fire before anybody is refused. The one thing that stops the counting is a developer pausing capture, below.

What a refusal says

The refusal does not go to a log. It goes back to the model as the reason its tool call was rejected, which is what makes a team’s rule reach the thing that was about to act. This is the shipped rm-recursive rule, armed in a machine’s own guardrails.json, refusing one path. Added from the library instead, it opens with the library’s sentence, This deletes the whole tree for good. Nothing goes to a trash folder, so uncommitted work in it has no other copy., and the note under the remedy is the library’s wording too:

This deletes the named trees recursively and permanently. `rm -rf` does not move anything to a trash directory, so whatever here is untracked or uncommitted has no copy anywhere else.

Run this instead:

    D=$(mktemp -d) && mv packages/api/src/legacy "$D" && echo "moved to $D"

Takes them out of the working tree exactly as `rm -rf` would, but into a temp directory whose path it prints - so if this was the wrong path, it is one `mv` from being undone.

Blocked by the rm-recursive guardrail.

Code KZRNG5. If this one call should run, ask the person to type `harbor allow-once KZRNG5 --because "why"` in their own terminal, then try again. If the rule is wrong, `harbor dispute KZRNG5 "why"` tells its author.

A person can still run it in their own terminal.

The remedy is above everything else on purpose. A model acts on the first actionable line it finds, so the replacement command comes before any way past the rule. The way past is written for the person and goes last, and the agent cannot take it: the hook refuses an agent’s own call to harbor allow-once or harbor dispute. The refusal does not name the switch that turns refusals off on a machine. The agent is the one reading it, so harbor doctor tells the person instead.

Paths from the call are substituted into the remedy and each one is shell-quoted, which is a safety property rather than a nicety: those strings came off a command line an agent composed, and interpolating them raw would let a path turn a remedy we wrote into a command we did not, in the one message an agent is most likely to run verbatim. A remedy template with nothing to fill it renders nothing at all, because a line that looks runnable and fails is worse than no line.

A refused MCP tool call gets the same message. The ready-made MCP guardrails carry no remedy, so theirs says what the tool does and who stopped it, with nothing to run instead. If your team has a sanctioned route, write it on the rule as the remedy.

Every path through the hook fails open. An error inside it is a silent allow, never a blocked tool call. A check that has not decided within 4 seconds lets the call go ahead and prints one line on stderr: Harbor’s guardrail check on this tool call did not finish within 4 s, so the call went ahead without it. Run harbor doctor to see why. The process exits zero, refusals included, with one exception: Devin refuses on exit code 2, so under Devin a refusal exits 2 with the reason on stderr. A guardrail that could wedge a session would be removed within a week, and then there would be no guardrails.

Hook examples for Claude Code, Codex, Cursor and Copilot

You do not write a hook to get these. harbor init registers one script, session-toolcontext.mjs in ~/.harbor/bin, on each agent’s pre-tool event, and every guardrail on this page runs inside it. Turning a guardrail on changes what that script refuses; it never touches the agent’s config again.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__.*|exec|edit|write|read|grep",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/.harbor/bin/session-toolcontext.mjs",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "This overwrites the remote branch, and commits other people pushed to it are dropped.\n\nBlocked by the git-push-force guardrail.\n\nCode FW28VD. If this one call should run, ask the person to type `harbor allow-once FW28VD --because \"why\"` in their own terminal, then try again. If the rule is wrong, `harbor dispute FW28VD \"why\"` tells its author.\n\nA person can still run it in their own terminal."
  }
}

git-push-force (block): it is refused.

The agent would read:

    This overwrites the remote branch, and commits other people pushed to it are dropped.

    Blocked by the git-push-force guardrail.

    A person can still run it in their own terminal.

{
  "rules": [
    { "id": "git-push-force", "mode": "block" },
    { "id": "rm-recursive", "mode": "block" },
    {
      "id": "prisma-migrate-reset",
      "mode": "block",
      "why": "This drops the whole database and rebuilds it from the migrations. Every row in it is lost."
    }
  ]
}

This drops the whole database and rebuilds it from the migrations. Every row in it is lost.

Blocked by the prisma-migrate-reset guardrail.

Code MM7HK7. If this one call should run, ask the person to type `harbor allow-once MM7HK7 --because "why"` in their own terminal, then try again. If the rule is wrong, `harbor dispute MM7HK7 "why"` tells its author.

A person can still run it in their own terminal.

Writing your own, and arming it

Rules are written and armed in the web app, on Guardrails: curating which commands may be refused is administration. The CLI has four commands for the machine side, and none of them turns a rule on:

• harbor check "<cmd>" says which guardrail stops a command here and what the agent would read. It runs nothing and sends nothing.
• harbor guardrail test [rule] counts how often each rule would have fired over this machine’s agent history. --share sends the two counts.
• harbor allow-once <code> --because "<why>" lets the one call a guardrail just refused run once, with your reason on the rule’s record.
• harbor dispute <code> "<why>" tells a rule’s author it refused something it should not.

1. Describe the command

   New guardrail first asks what kind of thing it catches: a command, a file write or an MCP tool. A command takes the program, its leading subcommand words and its flags. An MCP tool takes the tool’s name, an optional server and a box for only SQL that writes. Or start from a rule: Enforce this on a rule in Knowledge drafts the matcher from what the rule says and opens the form with it, saying what the draft catches and asking you to check it catches what the rule means before you save. A guardrail drafted from a Space’s rule is filed in that Space.

2. Give it something to run instead

   Optional, and worth the two minutes. Whatever authors it owes it one check: that the command it names actually exists in the repo it names. An unreal remedy is worse than none, because it spends the one moment the agent is listening on a line that will fail.

3. Arm it

   A rule you write starts in Observe: the button says Create in Observe. Moving it to Hold or Block is its own action on its own route, not a field on a general edit, because changing what a rule says and changing what it does are separate decisions. It needs knowledge.curate, the same capability that edits and archives a published rule (the route asks for it by name); see spaces and access for who holds it.

How a rule reaches a machine

harbor init fetches the workspace’s rules once and writes them to a file on the machine. After that, while an agent works, the hook that checks each tool call starts a refresh in the background, at most every 30 seconds. The check itself reads only the file. A tool call never waits on a fetch, which has two consequences worth stating separately: an offline laptop keeps enforcing whatever it last heard, and our backend’s latency is never in front of one of your Bash calls. The call in hand is judged by the rules already on disk, and the next one by the refreshed set. A machine where no agent is working fetches nothing.

A guardrail in a Space refuses only in the repos bound to that Space, and the row in the web app carries the Space’s name. One with no Space applies in every repo.

{ "rules": [{ "id": "rm-recursive", "mode": "observe" }] }

The person at the keyboard is holding the consequences of both decisions, so the local file wins. A rule somebody cannot switch off on their own machine is a rule they uninstall the tool over. The override is one field: it does not delete the rule, and the rule keeps counting after it stops refusing.

What a machine sends, and when

Two things on their own, and two more only when a person runs a command. Only the first carries commands, and only the ones a repo’s committed files already name.

A CLI older than 0.5.14 still records a ready-made guardrail’s matches before anybody turns it on. The server drops every observation for a guardrail the workspace never made, so none of them land; upgrading stops the recording on the machine as well.

Where it watches

Bash calls, the file tools (write, edit, multi-edit and notebook edit), and MCP tool calls. The second arm exists because of an obvious hole in the first one. An agent refused rm -rf packages/backend/src could open those files and save them empty without any guardrail code running at all, and that was true from the day the ladder shipped. The third closes the same kind of hole for MCP servers: before it, the GitHub MCP server’s merge_pull_request went through whatever your team had said about gh pr merge. Every ready-made file or MCP guardrail is off until somebody turns it on, at which point the same two switches apply, unchanged.

An MCP rule names the tool exactly as its server declares it, such as merge_pull_request, and can also name the server. Claude Code and Codex send the call as mcp__server__tool, so a server in the rule is checked there. Copilot sends server-tool from the CLI and mcp_server_tool from VS Code, and the server is checked there too. Cursor sends MCP:tool with no server, so on Cursor the tool name alone decides. The ready-made MCP guardrails name no server, so each one catches its tool on any server. A rule on gh pr merge still covers the shell only: the MCP route needs its own rule.

One argument can be checked: only SQL that writes. It lets a plain SELECT, EXPLAIN or SHOW through and catches the rest. A second statement after a semicolon counts as a write, and so do WITH (it can wrap a DELETE), SELECT … INTO (it creates a table), EXPLAIN ANALYZE (it runs what it explains) and SQL it cannot read. A call with no sql or query argument does not match. The SQL is read on the machine and never sent. This checks what the agent sends. It is not a database permission: a SELECT can still call a function that changes data, and a read-only database role is the real boundary.

On all three arms the counting is gated on capture and the refusing is not, and the difference is the ethics of the feature rather than an implementation detail. A count is a record of what somebody ran, written down, so harbor off --capture stops it: a counter that kept counting through that would be exactly the thing you asked us to stop. A refusal records nothing. Until 0.5.8 one switch governed both, and a developer who paused capture for privacy also switched off the rules their team had set, with no way to find out.

You need a CLI that can refuse

A rule armed in the web app refuses nothing on a machine whose CLI is too old to enforce it, and every caption on this page would still be true while the product was a lie. The floor is harborloop 0.4.3. Earlier published versions carry the wire but match by spelling rather than by command, which means a rule on terraform would miss ./bin/terraform apply: refusing some spellings of a command and not others is not a guardrail, and the page would be describing something you do not have.

Guardrails on MCP tool calls need 0.5.18 or later. An older CLI never registers its hook on an MCP call, so a rule on one refuses nothing there. harbor update installs the latest release and re-runs init, which registers the hook for MCP calls on Claude Code and Cursor. Codex already sends every tool call to it. On Copilot, every guardrail needs 0.6.7, the first release that wires it, and so does Devin, which runs Claude Code’s hooks but names its tools its own way. A repo wired with harbor init --repo needs that command run again, and its .claude/settings.json committed again, to pick up the MCP matcher.

Hold, allow-once and dispute need 0.5.21 or later. An older CLI reads a rule at Hold as observing, so it refuses nothing there.

harbor update

harbor doctor checks the version against what is published and warns when you are behind, naming the command that fixes it. Be precise about what that line does and does not know: it compares you against the latest release, not against a guardrail floor. The honest test is therefore the simple one, which is to be current, and it covers every floor on this page.