Git guardrails
The rules that stop a session doing something destructive to your git history — committing to a protected branch, force-pushing, or throwing away work — with a warn-only mode, per-action approval, and escape hatches for when you do mean it.
On this page
What it is
Status: shipped, ON by default. Every user's protected branches (
master/main) are guarded out of the box. Configure it, switch it to warn-only, or turn it off in Settings → Features → Git guardrails or the Dev Pipeline panel → Setup → All settings → Git guardrails (the same controls, in two discoverable places).It lives in the Dev Pipeline panel because that panel and these guardrails both exist to protect
master/mainwhile agents work — but note the rail protects every spawned agent session, not just Dev Pipeline runs.
Git guardrails is an Omniscio safety feature that stops the AI sessions Omniscio spawns from doing
dangerous git operations on your behalf — most importantly committing or pushing
directly to a protected branch (master / main). When it's on, Omniscio quietly installs
a small safety check into every session it launches, so if an agent tries a gated git
command the command is blocked before it runs and the agent is told why.
It's the built-in, one-switch version of the hand-installed PowerShell "block-master" hooks some power users run today: instead of each person wiring up their own machine, Omniscio bundles the check and turns it on for the whole session automatically.
It is a safety rail, not a security sandbox. It catches the common, honest cases — an
agent that reaches for git commit while sitting on master, or git push origin master.
A determined agent that deliberately obfuscates a command (hiding it inside $(...),
eval, an alias, or a script it writes and runs) can get around a shell-command checker.
Treat it as guardrails on a mountain road, not a locked vault.
Where to find it
Pausing it
Three temporary off-switches. Two are yours alone; the third lets a blocked agent unblock itself for a few minutes, and is deliberately narrower than the other two.
- For one agent — pause a single session for a set number of minutes. Every other session
stays guarded, so one stuck agent no longer costs the whole fleet its protection. Turn on
Until I turn it off instead of choosing minutes and that session stays unblocked — its row
reads Always — until you press Resume now. The app quietly renews it in the
background (each renewal still has the normal 4-hour limit, so a faked file can never grant
forever), and it carries over when you restart the app. Give it to an Overseer and it
belongs to that Overseer, not to one session: when the Overseer is refreshed or restarted, the
new Overseer session takes it over straight away (still one row, one Resume now). A session
that hands its work off to a fresh one passes it on too, and so does a crew lead handing its
post over: the session that takes the post gets the unlock the one before it held. Turn it on
from Settings — or, uniquely
among the pause surface, over the CLI:
POST /git-guardrails/session-pauseaccepts the install's full-trust owner token and can pause any session, its own included, for up to 240 minutes. (The~/.amc/cli-tokenfile an agent on a dev box can read IS that token, so treat this route as reachable by an agent that can read it.) The machine-wide pause and the per-repo exclusions remain Settings-only. - For your own work — the original pause window. It no longer gives every agent a free hand: since 2026-10-10 a window is honoured only for the identity it names. One opened from this panel names you, so it covers your own git work and the app's own background jobs, and every agent session stays guarded while it is open. That is the same rule the owner set for a window opened from a terminal, and it is what a window with no session named at all now gets: nothing.
- The agent unblocks itself — capped at 10 minutes, 3 times an hour, and it always posts a
note to your inbox saying which session did it and why. The note reads like the approval cards
rather than as a notice: one table whose Type row says it is a guardrail pass, then what
happened, the agent's own words as Why, and an Ends row giving the local time the pass
closes and how many of the three it has used — with the session that did it at the bottom. It
offers no Approve button, because there is nothing to approve: the pass closes on its own.
It never allows pushing to a remote, and never a destructive
git stash— both of those can damage something that isn't the agent's own work, so they still take your approval. Turn the whole thing off with Let an agent unblock itself briefly (Settings → Features → Git guardrails) and you are back to approving every time.
No pause of any kind lifts #8–#10. "Let me write to master for a while" should not also mean "let me mass-close pull requests or kill the app" — those have their own single-command overrides.
When you get asked to approve
If an agent needs something it can't grant itself — a push, or a longer window — it raises a card in your inbox naming the command it was blocked on. The card has an Approve button: one click, one confirmation, and that one session is unblocked for 20 minutes. Everything else stays guarded.
A push after the approval runs out is refused even behind a ready tag. The gate that runs at push time keeps a small record of every approval window on this machine that has run out, and a session whose own window has lapsed does not publish — a ready-to-merge tag or a recorded publish does not stand in for a live approval. A fresh window you approve clears it.
If that record cannot be read, the push is refused too. A record that exists but is damaged —
or that cannot be read at all — is treated as unknown, never as "nothing has lapsed", and an
unknown record refuses a push that has no live approval of its own. The refusal names the file
(~/.claude/.guardrail-approval-lapses.json) and gives you two ways out: approve a fresh window for
that session from the card, or repair the file (moving it aside starts an empty record, and a window
that is still expired on disk is recorded again by the next push). An agent cannot edit, move or
delete that record — it is guard state, like the approval windows themselves, so the repair is
always yours to make and a session cannot wipe the evidence against itself. A lapse the gate could not
write — a full disk, a locked file — refuses the same way, so a lapse it cannot remember never
quietly publishes.
One exception: the shared git store. When the command the agent was blocked on rewrites the
shared object store or deletes files inside a .git folder (rules #23–#26 on
part 2), your Approve is narrower than the 20 minutes: it lets that
one command through, and only if the command runs within ten minutes of your click. The next such
command asks again.
The same card also appears in the conversation, right above the message box of the session that asked, with the same Approve / Decline buttons and the agent's own stated reason. So you can answer without leaving the thread you were reading — which matters most on your phone, where the inbox and a session are two different pages. It is one approval shown twice: answer it on either screen and it disappears from both, and the waiting agent is told either way.
This covers both ways an agent can end up waiting on the guardrails: asking for a short window on itself, and asking to change a guardrails setting. Approvals about anything else stay in the inbox only — the message box is not a second inbox.
An agent can only ever ask on its own behalf. The session that gets unblocked is the one the app recorded as raising the card, not a name the agent typed — so a card can never trick you into unblocking a different agent.
If that session is replaced while your approval is still open, the approval follows the work. A window belongs to the session that asked, so when a fresh start hands that session's job to a successor — the old one is archived and a new one carries on — the window moves to the successor and keeps the expiry you gave it. It is never extended by the move, and it moves to that one successor only: every other session on the computer stays guarded. An ask you have not answered yet is not carried — that card is closed and the successor has to ask for itself, because there you answered a question about a session that is already gone.
Stop being asked. The inbox card's green Approve has a small arrow beside it. Pick Everywhere for Forever in the arrow's always-allow panel (it asks you to confirm; a shorter time limit or a narrower place works too) and every later ask is approved straight away — exactly what your click would grant: that session can push, including to GitHub, and can edit your own guard scripts until its window ends, and it can ask again to renew it. Two things still come to you: an agent the app started from outside content (an inbound email, an intake report, an automation) still gets a card — though a session you started yourself does not, even if it later reads a web page — and asks already waiting when you turn it on keep their card, so those agents are told. Remove it at Settings → CLI Control → Always-allowed actions to go back to being asked.
Always allowed: reads (git status / log / diff / show / …), moving onto a
protected branch (git switch main), creating a new branch, and git fetch.
Worktree commands: all of them go through the app (changed 2026-09-01)
While the Dev Pipeline is on for a repo, an agent working in it cannot run any git worktree
command that changes something — add, remove, move, prune, lock, unlock or repair.
Looking is untouched: git worktree list and a dry-run prune work exactly as before.
Two of those refusals fire in EVERY guarded session, Dev Pipeline or not. raw-worktree-add
(a bare git worktree add) and forced-worktree-remove (git worktree remove --force) are
deliberately branch-independent standalone rules — they read nothing from the Dev Pipeline's
worktree-lockdown switch, so turning the pipeline off does not make them go away. Only
raw-worktree-add has a sanctioned way through, and it is one the wider lockdown does not have:
AMC_ALLOW_RAW_WORKTREE_ADD=1, for a repo the create API genuinely cannot serve (it 404s, or
the server is down). The refusal message names it. It is a fallback for an unserved repo, never a
way to skip the ledger when the route would have worked. That flag lifts raw-worktree-add
only — forced-worktree-remove reads AMC_ALLOW_RAW_WORKTREE_ADD nowhere, because a forced
removal destroys a live worktree that is very likely another agent's; the way past it is the app's
own reversible POST /worktrees/:id/remove.
The reason is ownership. A worktree made or destroyed by hand is invisible to the app until a background sweep notices it, and that sweep can never recover the two things only the person who made it knew: who is working in it, and why. Closing those two gaps is exactly what the app's own create and remove routes do — they record the owner at the moment the worktree changes.
Each refusal names the replacement for the exact command that was tried:
| Instead of | The agent uses |
|---|---|
git worktree add |
POST /worktrees/create — creates it and records the owner, then provisions its dependencies in the BACKGROUND. Read the readiness block on the reply (present on BOTH a 200 and a 202): readiness.verdict is the authority, a 200 does not mean usable, and a 202 status: 'creating' carries path: null — poll GET /worktrees/create/<ledgerId> until it reports exists: true (the folder is on disk; path names it, and after a pool hand-off that is the served slot) and then ready. Never create, cd into or pin a folder before exists is true. A queued 202 carrying ledgerId: null is still a running create, not a failure — its ledger row is registered at birth, so read it back through GET /worktrees?repo=<repo>, matching your exact title on requestedTaskTitle (the ledger's raw column, not taskTitle, a display string that prefers the live owner's session name), and poll that id; never abandon or re-send on a null id. scripts/lib/scratch-worktree.mjs does this for you. Never wait for readinessWarning to clear — it hoists what is outstanding and says nothing about being finished; the permanent lean-checkout note is its own field, readinessSparseNote |
git worktree remove |
POST /worktrees/:id/remove — retires it reversibly into .trash, keeping every floor that guards WORK (uncommitted, ignored, unmerged) or a running job. A worktree's own proven owner asking to give it up is not held by the "is somebody still using this?" floors — it just answered them, and its uncommitted and git-ignored files are discarded with the folder: that is the owner's own call, no rescue copy is kept, and only the branch's commits are archived before the delete. Everyone else — a sweep, a panel removal, or a session that claimed an unowned row in the same request — is still held by both work floors |
git worktree lock / unlock |
POST /worktrees/:id/pin — which now sets the real git lock |
move / prune / repair |
nothing — the app does these itself |
Nothing an agent can do lifts the TYPED refusal. The lockdown rule is evaluated above every
escape hatch and reads no grant, so not the pause an agent can open for itself, not the
machine-wide approval window, not a repo exclusion, and not an environment flag gets a typed
git worktree mutation through. That is deliberate: the change was prompted by an agent using a
sanctioned pause to get past the earlier, narrower version of this rule.
The one way through is you. If the app genuinely cannot serve a repo, the agent asks for
approval and you get an inbox card; clicking Approve opens a short window for that one session
in which the raw commands work. It never opens by itself, and it never covers
git worktree remove --force, which destroys a live worktree that is very likely another agent's.
The same refusal is enforced a second time by the git wrapper on the agent's PATH, so a worktree
command fired from inside a script an agent wrote is caught too, not just one it typed.
That second layer is a rail, not a wall — and it is the only one covering the
script-borne case. The hook only ever sees a command the agent TYPES, so a
git worktree add buried in a script is stopped by the PATH shim alone. The shim is
coarser by construction: it stands down on AMC_DISABLE_WORKTREE_LOCKDOWN=1 (an inline
env prefix sets it). It reads the same live-grant file as the hook and applies the same
per-session, expiry-checked test, so a window that does not name the running session — or
one that has elapsed — leaves the refusal standing. Read the "not an environment flag"
guarantee above as covering the typed command; for the script-borne path, the hook is the
layer of record and the shim is an operator-disablable backstop.
A human window lifts the push rule on the shell layer too — and only the app's word does.
The shim reads grants from ~/.claude/.guardrail-session-window — one line per live human
window, <session id> <expiry>, written by the app from its live-pause reader. It matches
the session and checks the expiry, so another agent's window, an elapsed one, a self-pause
and a file that cannot be read all leave the refusal standing. An expiry past 2100-01-01 is
treated as junk, not a far-future grant.
A plaintext line is not authority. The app also writes
~/.claude/.guardrail-session-window.attest, its Ed25519 signature over the mirror's exact
bytes, and both shell deliveries honour a line only when that signature checks out and the
running app vouches for the signing key on its loopback port — so a process that writes the
mirror by hand lifts nothing. One verifier decides this for both deliveries
(scripts/lib/git-guard-window-verify.mjs, rendered into the shell function and into the
native shim), and every road fails closed: no attestation, edited bytes, a lapsed or
over-long head, a key that is not the one the id names, a bad signature, no vouch, an app
that is not running, or no node to run the check.
The app's signing key lives in memory, so a signature it wrote before a restart can no longer be vouched for — the mirror would keep naming a key the running app does not hold while the window is still live. The app therefore re-signs its own artifacts as it starts: the session-window mirror, a live machine-wide approval window (left exactly as recorded), and the excluded-repos copy with its seal. An approval a person opened survives a restart of Omniscio.
The mirror carries PER-SESSION lines only. One line per live window, each naming the
session it is for. A window that names no session mirrors NOTHING — including the app's
own Settings pause, which stamps the empty string, the person's own identity: that lifts
their git work and reaches no agent. The master-approval helper stamps a session key on
every window it opens (the opener's session id, or the empty string from a plain
terminal), so an approve-master window always falls under the residual below.
A * line is REFUSED, by both shell deliveries. Older builds mirrored the machine-wide
window as * <expiry> and both deliveries honoured it for whoever asked, making them MORE
PERMISSIVE than the hook, which fails an agent closed on that same window. Nothing emits
the line any more, so one still on disk is stale or hand-written — neither is a grant —
and the shell emitter and the native shim both skip it outright.
One asymmetry remains, deliberate and in the safe direction. The session-scoped
residual: the mirror is built from the app's OWN keyed pause map
(~/.claude/.guardrail-session-pause.json), so an approve-master window — written into
~/.claude/.master-approval.json and always stamped with a session key — earns no
mirror line at all. It lifts the HOOK for that one session and stays refused on BOTH
shell deliveries, permanently. That is the documented residual, not a mirroring delay,
and it is why the per-session card remains the reliable ask.
A repo the app does not manage gets the way out named, not a dead end. There
POST /worktrees/create answers 404, so every refusal on the path says so: the shim's two
worktree refusals and the 404 itself name both switches a raw add meets
(AMC_ALLOW_RAW_WORKTREE_ADD=1 and AMC_DISABLE_WORKTREE_LOCKDOWN — one alone fails) and
point the agent at you: add the folder as a project, or approve its
POST /git-guardrails/approval-request.
How it behaves
What it blocks
When enabled, these operations are gated in a spawned session.
Wrapping a command doesn't hide it (fixed 2026-09-03). Everything below is caught the same
way when it's handed to another interpreter to run — bash -c "…", sh -c, powershell -Command, a command piped into a shell, or a git call made from inline node -e code. Until
this was fixed those five shapes were let through, so a push to master could slip past on any
machine whose only protection was this hook. Writing about a git command is still fine: text
you print, log, or save to a file is data, and inline program code is only inspected when it
actually has a way to run something.
Nor does a change of folder that is easy to miss (fixed 2026-09-25). A cd inside ( … ),
behind builtin or command, or run by eval / Invoke-Expression, and a folder handed to
env -C, are followed like a plain cd; code fed to a shell through eval,
Invoke-Expression, a heredoc or a here-string is judged in the folder where it really runs.
Commit / write while on a protected branch — any history-changing git command (
commit,reset,rebase,merge,cherry-pick, a branch delete, …) while the checkout you share with every other session is onmasterormain.Push that targets a protected branch — e.g.
git push origin masterorgit push origin HEAD:main, from any branch.Push that would send a local-only
ready-to-mergetag to a remote — the app marks a branch "ready" with a local note (a branch description), never a pushed git tag, so aready-to-mergetag is a per-worktree relic. Pushing one — by name,refs/tags/…, a force+, or the--tags/--follow-tags/--mirrorsweep flags — leaks it to everyone on the nextgit fetch, so it's blocked. Deleting such a tag from the remote (cleanup) stays allowed.Push without a ready-to-merge tag (opt-in, default off) — when you turn on the extra "ready-to-merge gate", even a feature-branch push is refused unless the branch carries a current, SHA-bound
ready-to-mergemarker whose SHA matches the exact commit you're pushing. This enforces a "verify, then tag, then push" workflow. It coversgh pr createas well asgit push— publishing the same commits as a pull request is the same act — so an untagged branch cannot be opened as a PR either. Either escape hatch lifts both commands the same way: an approval window (a human grant lifts everything) or an excluded repo.Destructive
git stash—push/pop/drop/clear/apply/saveand baregit stash(which is an implicit push). These can silently swallow or reapply another agent's uncommitted work. Read-onlygit stash list/git stash showare allowed.Editing a file while the repo is on a protected branch — the same rule as #1, but for the agent's file-editing tools, not just shell git.
A shell command that writes a file into a protected checkout — the shell half of #6. Gating only the edit tools left an obvious way around them: a
>redirect,curl -o,tee,cp/mv, or a PowerShell write cmdlet aimed at themastercheckout. An agent's working directory is the base checkout even when its real work lives in a worktree, so a stray relative path lands inmaster— exactly how untracked junk files kept appearing in the repo root. Windows has a nastier version: inside a Bash command an unquotedC:\tmp\out.pnghas its backslashes eaten and collapses to a relative name, created right where the agent is standing. (Quote it, or use forward slashes, and it writes where you meant.)Closing pull requests destructively — closing a PR throws work away, and doing it in bulk throws it away faster than anyone can check. A loop, a pipe, a list read from a file, or simply two numbers in one command is refused outright with no override — that exact shape once nearly destroyed ~58 PRs' worth of real code, after an agent tagged 131 of them "redundant" from a heuristic. Closing one PR is allowed, but only with a marker naming that exact number, so every close is a separate deliberate act.
Killing or restarting the app from a shell — Omniscio already refuses agent-driven restarts through its own controls, but a shell command could route around them. One did: it found the app by its control port and killed it, taking 22 live sessions down with it, twice. Tidying up your own dev or test instance is untouched — only a blanket kill, or pinpointing the app by its port, is refused.
Scheduling a task that pops a console window — a scheduled task that runs a script directly draws a black window on your screen every time it fires. Omniscio ships a repair job for this, but it cannot save a one-shot task, which fires long before any repair runs. So it is caught at creation, with the one-line fix included in the message.
Which checkout counts (fixed 2026-11-10). Rules 1, 6 and 7 are about the checkout every
session on the machine reads — not about any repository whose current branch merely happens to be
named master. A repository you or an agent made for itself is not protected: a fresh
git inited scratch repo (whose default branch is master before you have even committed), a
clone made outside the checkout, and the patch road's own <repo>/.git/amc-patch-land/… clone are
all ordinary work, so committing, branching and editing inside them is allowed. git init and
git clone are judged by the repository they create — the destination you typed, resolved in
the folder the command itself runs in — and a destination inside the shared checkout, one git picks
for itself, or one the guard cannot read is still refused. The decision is made from folder paths
and git's own files, so a busy machine whose git is slow cannot turn it into a refusal; a repo
inside the shared checkout whose state cannot be read is still refused rather than guessed at.
About #7–#10 and false alarms. These run before every shell command, so they are tuned to
stay quiet. #7 looks only at write targets you typed explicitly, judges each one in the folder
its own part of the command runs in, and stands down when it cannot be certain — a path the
shell hasn't filled in yet ($TMP, ~/x, %TEMP%), a folder your environment names
(cd "$TMP"), a > that is really text inside quotes or a script body, a file the repo already
ignores, or a cd into a worktree first. The one doubt it no longer gives you: a relative write
after a folder the command works out for itself (cd "$(…)", cd -) is refused, because that
folder could be master — give the write an absolute path, or cd to a literal folder first.
#8–#10 were tuned the same way, against more than 51,000 real past commands, and every wrong
alarm found was fixed.
Each of #9 and #10 has a one-time override you can add to a single command, and #8's single-PR form has its per-PR marker. #8's bulk form deliberately has none — the whole failure mode is an agent talking itself into a batch.
Advisory vs. required
Two enforcement levels (in the Dev Pipeline panel → Setup, or Settings → Features):
- Required (hard-block) — the default. A gated command is refused; the agent sees a short explanation and can't run it.
- Advisory (warn-only) — the command is allowed, but the agent gets a warning on stderr explaining why it's risky. Useful for trying the feature without changing what actually happens.
You can also set which branch names count as protected (a comma-separated list, default
master + main), and opt into the extra ready-to-merge push gate — all from the same
section.
When an agent is blocked
The block surfaces to the agent as a short, friendly message naming the rule, the reason, and the branch/repo — plus how to override it. For example, a blocked push prints roughly:
git-guardrails BLOCKED: push-to-protected
git push targets a protected branch (master/main) directly —
pushing straight to a shared branch is gated
branch: master repo: C:/code/my-project
Never tell the user it cannot be done or make them run it. Ways forward:
1. Work on a worktree branch: POST http://127.0.0.1:19519/worktrees/create
...
The wording matters more than it looks. It used to name only a JSON file path, so a blocked
agent — with no sanctioned way to ask — would improvise and tell you to open a terminal and
run the git command yourself, or tell you it simply could not do the job. Every block now
names its roads forward — lift it itself where the rule allows, or ask you for one Approve
click — and says plainly never to tell you the action cannot be done. A rule nothing can lift
still ends with that line and points at the way forward its reason names. The machine-wide
Developer Guardrails message carries the same three roads. The message is kept deliberately
SHORT: every block lands in an agent's context, so a length ratchet
(tests/unit/lint/03/guard-message-length.test.ts) caps each refusal.
Every session also carries the same rule in its standing instructions: a refusal from a guard, hook, gate or permission check is a road, not a no — the agent takes the way forward it names, lifts it itself or asks you for one click, and never routes around it.
Overriding (escape hatches)
Two overrides short-circuit the guardrails to "allow", driven from the Git guardrails controls (Settings → Features or the Dev Pipeline panel) and stored in the exact file formats the existing PowerShell "block-master" guards already use.
Inside a Claude Code agent session the guard takes the location from your real account home,
never from a folder the program names. It asks the operating system for the account's profile,
so pointing HOME — or an AMC_MASTER_APPROVAL_FILE-style variable — at another folder gets an
agent nowhere: the hook that judges a git push resolves the approval window, the exclusion list
and the one-shot land tokens from the account-home locations every time. When you run git
yourself from a normal shell, the guard uses your own home, exactly as the app's own controls do,
so a pause you granted is always the file the hook reads. Those path variables exist only for
test and sandbox runs, and the guard ignores them inside an agent session, which is exactly where
a forged file could otherwise lift the gate. This closes the door on redirecting the read; it does
not make the files themselves unforgeable, which is the rail point below.
These override files are a RAIL, not a sandbox — be honest about what that means. The guardrails are a policy layer an agent is expected to respect, not a boundary that can hold against one that does not. Since 2026-09-25 the guard refuses an agent's write, move or delete of
~/.claude/.master-approval.json,~/.claude/.master-block-exclusions.json, the PR-push grants in~/.claude/.push-approvals.jsonand the installed bundle under~/.claude/hooks/developer-guardrails/at every enforcement level (ruleauth-artifact-write), honours a window only in the shape the app writes it — since 2026-09-26 the same for a per-session pause, the agent's self-pause (never past its 10 minutes) and the session-window mirror — and refuses a hard link to any of these files. But it judges a command by reading it: a write through a form it does not model yet (truncate, or code run by an interpreter such asperl -i) still gets through, so an agent with a shell can still forge one — an in-placesed -ityped as its own command is no longer one of them (one run throughfind -execorxargsstill is). That residual has been carried openly since the per-session pause shipped, and closing it fully needs the in-git allowlist flip, not a hook rule.Why that residual is still the right shape: opening a window is a deliberate, attributable act with a narrow sanctioned form — the app's own human-only controls, never something an agent does to itself — and an agent that writes one to get past a refusal is violating the rule regardless of whether anything stopped it. Do not read the absence of a refusal as permission.
Scoped to one agent. A window names the session it was opened for; that agent gets through and every other agent on the machine stays blocked for the window's whole life. Before this, one approval granted for one operation opened every guardrail for the whole fleet for up to four hours. A window that names a session covers only that session. A window written from outside any session names none, and every reader fails closed on that empty name — every agent session stays guarded and the window covers non-agent git work only. A window with no
sessionkey at all is machine-wide, and that is what the app's own Pause for N minutes writes.Pause the guardrails for a while — a time-boxed window (
~/.claude/.master-approval.json: its expiry, when and by whom it was granted, and for how many minutes — a file missing any of those is not a window). "Pause for N minutes" opens it (1–240, with a live countdown); "Resume" closes it. While it's active, everything is allowed — use it for a deliberate, user-authorized burst of protected-branch work. A window that NAMES a session (the app's own per-session grant, and anything an agent could write for itself) is honoured by the hook only when it carries the app's signature over that window and the running app vouches for the signing key (since 2026-11-09). A window that names nobody — your own terminal's — is unaffected: it never reached an agent anyway.Exclude a repo — a per-repo list (
~/.claude/.master-block-exclusions.json,{"repos": ["C:/path/to/repo", …]}). Add or remove a repo from the app; a listed repo (or one nested under it) is never guarded. The hook honours the list only when the app signed it (since 2026-11-09), so edit it through the app rather than by hand — a hand-written list excludes nothing. That holds in an agent's own terminal too: the app keeps a ready-to-read copy of the list in~/.claude/.guardrail-excluded-repos, so a push tomain/masterfrom an excluded repo goes through there as well (since 2026-10-14; before that, every such push raised an approval card). A missing copy keeps the push refused. In the agent's terminal the exception also checks the repository git will actually push from: a push that points an excluded folder at another repository — through--git-dir,GIT_DIR, a.gitlink file or a junction — stays refused. So list the real folder: an entry that reaches it through a junction or a Windows short name (likePROGRA~1) does not count there (since 2026-10-15). It also checks where the push goes (since 2026-10-21): a push to., to another listed folder or to someone else's repository goes through, while a push to a folder that is not listed, to one of our own organisation's GitHub repositories, to a relative path, to a remote that does not exist, or while aurl.*rewrite rule is set stays refused. The Claude Code hook still judges the folder only.Agent browser profiles (added 2026-11-06) — the guardrails refuse any agent command that opens Chrome, Edge, Chromium or Brave on a profile a real person is signed in to, because the agent would then see everything signed in to it. Some people keep a Chrome profile just for agents, for example one holding spare social-media accounts that a tool like OpenCLI drives. To let agents open that profile, go to Settings → Features → Developer Guardrails → Agent browser profiles, pick the profile and click Add profile. The list is read from Chrome's own profile list on this computer, and each choice shows the profile's Chrome name, the account signed in to it and its folder, such as "Byron · agents@example.com (Profile 17)", because several profiles can share one Chrome name. You are asked to confirm first; removing one is a single click and needs no confirmation.
- What it allows: only a plain launch of standard Chrome on that profile, such as
chrome --profile-directory="Profile 17", optionally with--new-windowand a web address. It works the same throughstart ""andStart-Process. - What stays refused: a debugging port, a different
--user-data-dir, any other switch, afile://orchrome://address, a profile that is not on the list, and Edge, Brave, Chromium, Chrome Beta or Chrome Canary on the same profile. - Only you can change the list. It lives in
~/.claude/.guardrail-agent-browser-profiles.json, which the guardrails refuse to let an agent write, there is no CLI route, and the phone and web bridge cannot reach it. Inside an agent session the guard reads the list from your real home folder, so an agent cannot point it at a list of its own. - It starts empty, so nothing changes until you add a profile. A refused agent is told that a person can list a profile here, and that an agent cannot.
- What it allows: only a plain launch of standard Chrome on that profile, such as
Every control that LOWERS the guardrail asks you first (2026-08-27). Pausing, exempting a
folder, and switching from Block to Warn only each show a confirmation that names the real
scope — "for you AND every AI session on this computer", "everything inside <path>". Tightening
back up needs no confirmation. Until then it was the other way round: the only confirmation was on
removing an exemption, i.e. the one action that RESTORES protection.
A whole drive is refused as an exemption. A listed folder exempts everything inside it, so
typing C:\ would have silently unguarded every repository on the drive while reading as one more
unremarkable row in the list. The refusal lives in the service, not just the box, so the same
answer comes back through the app, the API and an agent alike.
These two controls stay human-only. Because a machine-wide pause or a repo exclusion lowers the guardrail everywhere, the app never exposes either to the CLI control server or the mobile/web bridge. (You can still hand-edit the JSON files, or use the PowerShell helpers, exactly as before.)
An agent has its own, much narrower path — added because the strict version had a cost you were paying without seeing it: an agent you had already told to go ahead would get blocked, have no way to act, and hand the work back to you as a command to run by hand. It can now:
- Re-run one command with a
CLAUDE_ALLOW_MASTER=1prefix, when you approved that exact command in conversation. When the command actually goes through, it says so on-screen. - Open a short window for itself — 10 minutes, 12 an hour, always with an inbox note.
Neither lifts a push to a remote or a destructive stash. Those, and anything longer, still come to you as a one-click Approve card.
Some refusals cannot be lifted at all — by either path. Writing a ref in a checkout that sits
on a protected branch, deleting a protected or non-head ref, rewriting the object store or its
config, writing inside another repository's .git, and the rest of the guard's always-enforced set
are refused whatever grant is in play. The prefix is not a key to those, so when a rule like that
refuses, the guard prints only the refusal and no "allowed" line — it used to print both, which is
exactly how an agent ends up believing the override it typed had worked and trying it again
(measured 2026-10-30 on git tag, git update-ref on master, and a self-pause that answered ok).
If you see the refusal alone, the prefix did nothing: the way forward is the refusal's own list.
Every time either of these actually lets through a command a rule would have refused, the guard
writes one line to its decision log naming the rule it lifted, and the perf:status tool shows the
count for the last 24 hours in its "hook cost" block. A command no rule would have refused, and your
own approval window, are never counted.
When the app is down: the emergency restore road
Every way past a protected-branch refusal that a person opens — the approval window, the per-session pause — is written by the app, so when Omniscio will not start, nobody can open one. That is how one developer ended up double-clicking a repair script herself to put seven files on master back as they were committed (Help Desk #1894). The emergency restore road gives an agent that one repair, and nothing more.
node scripts/emergency-master-restore.mjs --owner-approved "<the person's exact words>" -- <path>...
- Only while the app is provably down. The default control port (19519) and any
AMC_CLI_PORTmust both refuse a connection, and the app's heartbeat file — at its default place and at anyDATA_DIR— must be gone (a normal quit removes it) or name an app that has exited. Anything uncertain counts as up, and an environment variable can only add a place to check, never hide the default one. A crash whose process number was reused by another program within the last day also reads as up, the same way the git door reads it. - Only after the person said yes in chat. Their words are required, and they are written to
~/.amc/emergency-master-restore.jsonlwith the session id, the repo, branch and commit, the file list and the liveness evidence before anything is touched. A log that cannot be written refuses. - Only a restore to the last commit. Each path must be a file in the last commit: no folders,
patterns, paths outside the repo,
.gitpaths, or files the commit does not have, because restoring those would delete or widen. The checkout must be the main one, on master or main. The road never commits, moves a branch or pushes. - Nothing is lost. The current bytes of every named file are saved in git's object store first,
and their object ids are in the log row, so
git cat-file blob <id>gets an edit back. - The app's git door is the second net. The restore goes through the scripts' git door, where the main-checkout index guard refuses it if an app started serving the checkout in between — once that app has written its heartbeat. The road also checks the app once more right before the restore, which covers the moment before that.
- Off switch. The
dev:bypassswitch withoff emergency-master-restorecloses the road (a person at a terminal, or a signed owner order);onre-opens it. With no switch file the road is open. - Exit codes: 0 restored, 1 git did not finish (the saved bytes are logged), 2 refused.
- If the road itself will not load, its own files are among the broken ones; a person restores them at a terminal.
Limits (v1)
- Guards the sessions Omniscio spawns, not a plain terminal Claude session you start yourself. For that, turn on the machine-wide sibling — Developer guardrails — which installs this same engine into your global Claude config so every Claude Code session on the machine is covered. It is opt-in (off by default) and shares this feature's pause and exclusion hatches.
- Doesn't guard an SSH/remote session whose remote checkout has no hook.
- It's a shell-command rail — deliberate obfuscation can evade it (see "not a sandbox").
- Script-file reading goes one level deep: it opens the script your command runs, but not a further script that script runs. Following the chain without limit would mean unpredictable disk reads before every single command.
- It recognises git however it's spelled on the command line —
git,git.exe,git.cmd, a full path likeC:\Program Files\Git\bin\git.exe, and PowerShell's& "<path>"call form all get the same rules. Look-alike tools such asgitkandgit-fooare still left alone.
Related
- Git guardrails (part 2) — the continuation of this page.
- Git guardrails (part 3) — the newest rule changes, each dated. Developer guardrails is the machine-wide sibling: the same discipline, but written into your global Claude settings so it reaches every Claude Code session Omniscio starts however it was started. A session Omniscio did not start is not gated on these git rules; it is still refused the full-trust key, the gcloud account switch and native worktree creation. The guard is one part of a longer road — the agent tool-call path covers what runs the command after the guard allows it, and how the wait is measured.
Last verified 2026-11-10