It is 09:33 and the coding agent has finished the change for work item ORD-2187. Its six files pass lint, the type check and the affected tests. Now it records the work as a commit.
Suppose that, instead of naming the six files, it runs git add -A, and the working folder also holds a .env file with a database key that the developer used for a local test. That file should be listed in .gitignore. Suppose the line is missing: that is the first mistake, and it is the kind of mistake a team cannot rule out by being careful.
The key is now staged. If the commit goes through, the key is in the history of the branch. Once the branch is pushed it is on the repository host, where the only safe repair is to rotate the key.
Two questions decide what happens next. Which check stops the commit? And which of those checks could a person simply skip?
Times and durations on this page are illustrative.
An agent hook guides the agent. A git hook guards the developer machine. Only the server enforces. Use all three, and know which one is the gate.
The rule for this stage follows from that sentence. A check that must hold for every change belongs on the server. Checks on the developer machine are there to give the same answer sooner, and they must never be the only place a rule lives.
1. The agent's own hook did not see the commit#
The first place a check could run is inside the agent. In the code change stage the harness (the software that runs and controls the agent) ran a script after each edit. It can also run one before a tool call.
The model asks to run a shell command; the harness has not started it yet; a script reads the command text and may refuse it. In Claude Code this moment is the PreToolUse event. If the script exits with code 2, the harness cancels the command and hands the script's standard error to the model as the reason, so the model can correct itself.
A second tool works at the same moment without a script. A deny rule is a line in the agent's settings, such as Bash(git push --force *), that makes the harness refuse any matching tool call. The model cannot argue with it. In Claude Code, deny rules are checked before allow rules, so a narrow allow cannot re-open a broad deny.
It is tempting to stop here. The agent made the commit, so a check inside the agent seems like the right place. Two things break that idea.
First, Acme's only PreToolUse hook is the push guard, guard-push.sh, whose filter matches git push; nothing filters on git commit, so at 09:33 no agent hook script starts. A team may add one (an example on Hook events), but it would not remove the second reason.
The second reason is deeper. An agent hook and a deny rule both match command text. Claude Code documents that a rule for git push stops git push origin main but not git -C . push origin main, a full path to git, or the same command inside sh -c.
Neither layer exists when the developer commits in a terminal, or when a script outside the agent runs git. This layer is a guide: it is fast and it explains itself to the model, but it covers only what the agent does, in the spellings it was written for.
2. The git hook catches it, for everyone who has not skipped it#
The second place is git itself. Git fires its own events around a commit, whoever runs the command: a person, a script or an agent. The pre-commit event runs before the commit is created, and a script there can refuse it with any non-zero exit. Acme's pre-commit script checks format, lint, file size and secrets in the staged content.
In the opening case, this is the layer that stops the commit. The secret scan finds the key in .env and exits non-zero. Git refuses the commit and prints why.
That output returns to the model as the result of its shell command, so the model unstages .env and commits the six files again. The key never enters history. The corrected state has one more step: a separate change adds .env to .gitignore, so the next git add -A does not stage it at all.
This layer covers people and scripts that the agent layer never sees. Its weakness is that it runs on a machine its user controls. git commit --no-verify skips pre-commit and commit-msg; git push --no-verify skips pre-push.
A clone also does not copy hooks, so a developer who never ran git config core.hooksPath .githooks has none. A hook that takes too long trains people to add --no-verify, which is why git hooks should stay under about ten seconds.
Git offers several moments, and each suits a different job: pre-commit for fast checks on the staged files, commit-msg for the message format and the Refs: line, pre-push once per push for checks on the whole batch, and post-commit only for records, because it runs after the commit exists and cannot block. The facts, one tested script and ten more uses for each are on Hook events: pre-commit, commit-msg, pre-push.
3. Only the server cannot be skipped#
Suppose the developer, in a hurry, had committed by hand with --no-verify. The key is in local history, and a push with the same flag skips the pre-push hook too. What remains is the third layer: the repository host.
On GitHub, push protection rejects a push that contains a secret in a format it recognizes. A database password in a format it does not recognize goes through. A secret scanner run as a required check still keeps the change out of main, but by then the key is already on the host, and it must be rotated.
That case shows both sides of the server layer. It is the only layer that a developer cannot switch off from their own machine: branch rules refuse a direct push to main, required checks must pass before a merge, and code owners must approve changes to the paths they own. Only the actors on a rule's bypass list can get past it.
But its feedback arrives after the push, when the agent has moved on and the change has become something other people can see. The two earlier layers exist so that most problems never get that far.
Diagram: Three layers at the commit · guide, guard, gate
Read left to right. The same checks appear three times on purpose. The first two layers give fast feedback and can be skipped. The third cannot, and is the only one to rely on.
- Guide · inside the agent
- Hook before shell command: Fires before the agent runs a matching command, such as a push. It can cancel the command and explain why.
- Deny rules: Settings that make the harness refuse an action: a force push, an edit to a gate file.
- Sandbox: Operating-system limits on files and network for the agent's shell, whatever the command text says.
- Guard · developer machine
- Git hook before commit: pre-commit runs the secret scan and the formatter; commit-msg checks the message. For people and scripts as well as the agent.
- Git hook before push: Runs the affected tests and the local review. A finding stops the push unless the developer overrides it; it never blocks when the review cannot run. Feedback, not a verdict.
- Gate · repository host
- Push protection: The host scans the commits in a push as it arrives and rejects the push if it contains a known secret format.
- Branch rules: No direct push to main. Required checks must pass. A pull_request workflow runs as the pull request wrote it, so code owners on the workflow files keep a pull request from rewriting its own judge.
- Code owners for gate files: A named owner must approve any change to the files that define the checks.
Read the diagram from left to right. Some checks appear in more than one layer on purpose: a secret is looked for by the agent layer, by the git hook and by the host. The repetition is the design. Each layer catches what slipped past the one before, and only the right-hand column holds when somebody skips the others.
| Layer | Runs where | Who can skip it | Role |
|---|---|---|---|
Agent hook and deny rules (PreToolUse on the shell tool) | Inside the coding agent | Anyone not using the agent, and some spellings of a command | Guide. Stops the agent early and explains why, so it can correct itself. |
Git hook (pre-commit, commit-msg, pre-push) | The developer machine | Anyone with --no-verify, or a clone without the hooks installed | Guard. Catches the same things for people and scripts outside the agent. |
| Server rule (branch rules, required checks, code owners, push protection) | The repository host | Only the actors on the rule's bypass list | Gate. The only layer you may rely on. |
The first two layers exist to save time. The third exists to be right.
4. Approaches weighed#
With the three layers in view, the usual ways to protect this stage read as choices about which layers to use. Each one buys something and costs something.
| Approach | What it buys | What goes wrong | Use it when |
|---|---|---|---|
| A. Agent hook only | The agent learns the rule at the moment it breaks it | A text pattern for git push misses other spellings of the same command. A script that calls git internally is invisible. | Never alone |
| B. Deny rules in agent settings | The harness refuses the command; the model cannot argue | Same blind spot for unusual spellings. Too broad a rule blocks normal work. | With A, for the short list of never-allowed commands |
| C. Git hooks only | Works for people and agents | Skippable. Slow hooks train people to skip them. | As the second layer, kept under 10 seconds |
| D. Server rules only | Cannot be skipped from a developer machine | Feedback arrives late, after the push. The agent has already moved on. | As the third layer, always |
| E. Sandbox the agent's shell | Limits files and network at the operating-system level, whatever the command text says | Some tools do not run inside it. Setup work per platform. | Unattended agents, CI agents |
Recommended default: A and B for fast feedback, C for people, D as the gate, E for any agent that runs without a person watching. A sandbox is the answer to the spelling problem in section 1: it limits what a command can reach, not what it looks like.
5. What to check, and at which layer#
Three kinds of mistake are expensive at this stage: a secret that enters history, a gate file that changes without its owner knowing, and a large unrelated change that rides along. Gate files are the files that decide how other changes are judged or what an agent loads and may do. At Acme they are everything under .github/ (workflows and lanes.yml), CODEOWNERS, CLAUDE.md, everything under .claude/, .mcp.json, and everything under .githooks/, agents/ and ci/.
| Check | Agent layer | Git hook | Server |
|---|---|---|---|
| Secrets in the diff | Yes | Yes | Yes, for formats push protection recognizes; a scanner as a required check for the rest |
| Gate files changed | Deny rules stop edits to the most sensitive ones | Warn | The branch rule requires approval from the code owners of those paths; the lane check, which runs from the base branch, makes the change red |
| Commit size over a line limit | Ask the agent to split it | No | Raise the pull request to the red lane |
| Commit message links a work item | Yes | Yes (commit-msg) | Optional check |
| Tests passed | Already done at the stop hook | No | Required checks |
Read the table by its last column. Every row has a server answer, and that answer is the one that holds. The other columns decide how soon the developer and the agent hear about the problem.
6. The agent layer, as configuration#
The sketch below is the agent layer for this stage, in the project's committed .claude/settings.json. It demonstrates two mechanisms side by side: a PreToolUse hook whose if filter starts the push guard only for push commands, and deny rules that refuse a force push and edits to three groups of gate files. A working setup proves that the agent is stopped early in the ordinary case. It does not prove that the rules cannot be bypassed; section 8 lists how they can be.
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{ "type": "command", "if": "Bash(git push *)",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-push.sh",
"timeout": 30 }]
}]
},
"permissions": {
"deny": ["Bash(git push --force *)", "Bash(git push -f *)",
"Edit(./.github/**)", "Edit(./CODEOWNERS)",
"Edit(./.claude/**)"]
}
}
The matcher narrows the hook to the shell tool, and the if field narrows it further with one permission-style pattern, so the script does not start for every command. To block, guard-push.sh exits with code 2 and writes the reason to standard error. The harness cancels the command and gives the reason to the model.
This deny list is early feedback, and it is deliberately partial. It names two spellings of a force push and three of the eight gate-file groups. The other groups, such as agents/ and ci/, are changed as ordinary work in red-lane pull requests with their owners, so refusing every edit would block legitimate changes.
In Claude Code, an Edit deny rule also covers the file commands it recognizes in the shell, such as sed and tee, and the targets of redirections such as > file. It does not cover a script that opens files itself. The protection for all eight groups is the server rule in section 5.
7. The commit of #4812, step by step#
With the layers in place, here is what actually happened at 09:33, when the agent named its six files and nothing went wrong. What enters: six edited files for ORD-2187, with the affected tests green. What must leave: one commit on the branch feat/order-delivery-note that holds those six files and nothing else, with a message that names the work item.
| Time | What happens | Who acts | Result |
|---|---|---|---|
| 09:33 | git add for the six files, then git commit | The model, through the shell tool | The harness fires PreToolUse. The if filter matches a push only, so no agent hook script starts. |
| 09:33 | The pre-commit git hook runs | Git starts the script in .githooks/ | Format, lint, secret scan and file size on the six staged files. All pass in about two seconds. |
| 09:33 | The commit-msg git hook runs | Git | The message has the Refs: line. Pass. |
| 09:33 | The commit 8c1f0a4 is created | Git | One commit, six files, on the local branch |
| 09:34 | The developer runs the team's ship skill (a skill is a file of instructions for one kind of task). It calls git push. | The developer, then the model | The harness starts guard-push.sh: not a force push, not a protected branch. Allowed. |
The push itself, and the pre-push git hook, belong to the next stage.
The commit message:
feat(orders): add delivery_note to the order API
Refs: ORD-2187
The staged files, as git diff --cached --name-status printed them before the commit. This is what the developer or the agent can check before committing: six paths, and no file that does not belong to the change.
M api/openapi/orders.yaml
A db/migrations/2026_11_17_0931_add_delivery_note_to_orders.sql
M services/orders/handlers/create_order.py
M services/orders/models.py
M services/orders/serializers.py
M services/orders/tests/test_create_order.py
The same stage could have ended in two other ways. Both are labelled "suppose": they did not happen to #4812.
| Outcome | What happened | What happens next |
|---|---|---|
| It passes | This is what happened at 09:33. Six files, no secret, a valid message. | The commit exists. The change goes to the push and the pull request. |
| A check stops it and the agent fixes it by itself | Suppose the opening case: git add -A stages .env with a database key. The pre-commit hook finds the key and refuses the commit. | The model reads the message, unstages .env and commits again. The key never enters history. A separate change adds .env to .gitignore. |
| A check stops it and a person must decide | Suppose the agent wants a new CI step for the migration and tries to edit a file under .github/workflows/. That is a gate file. The deny rule in the agent settings refuses the edit. | The agent reports it and leaves the file alone. The owner of the gate files decides, in a separate pull request. |
8. Limits you should know#
| Limit | Why it matters |
|---|---|
| Pattern rules match text | A rule for git push matches it, including inside a chained command. git -C . push, a full path to git, or a shell wrapper is not matched. For a hard allow or deny, Claude Code's documentation points to the permission system rather than hooks, and to the sandbox for limits that do not depend on the command text. |
The if filter is best-effort | When a command contains $(), backticks or a variable, a pattern that names more than the command, such as the push pattern above, starts the script anyway; when Claude Code cannot split a command, it starts the script regardless. So guard-push.sh must read the command itself and allow what is not a push. |
| Deny wins over allow | A broad deny cannot be re-opened by a narrow allow. Keep the deny list short and exact. |
| The agent must not edit its own gates | A check defined by files that a pull request can change can be changed by the pull request it judges. Either the check runs from the base branch, as the lane check does, or its files are gate files whose owners must approve any change, as with the review workflow on Review. Otherwise the fastest way to pass a check is to change the check. Test this: open a pull request that disables the policy and confirm it cannot merge. |
| Bypass modes exist | A developer can start the agent with permission prompts skipped. Deny rules still apply in that mode, and an organization can disable the mode through managed settings. |
9. Side questions#
| Question | Short answer |
|---|---|
| Should the agent be allowed to push at all? | To its own branch, yes. To a protected branch, never; the server rule refuses it anyway, unless the pusher is on its bypass list. |
| Who is the commit author? | Whoever git's user.name and user.email name in that environment, normally the developer who ran the agent. Keep a trailer that names the agent, so volume and defect rates can be measured later. Claude Code adds one to its commits by default; the attribution setting changes or hides it. |
| One commit or many? | Ask for small commits that each pass the affected tests. A reviewer, human or agent, reads small commits better. |
The commit at 09:33 is clean, and every check on the machine agreed. Yet nothing at this stage knows that two of the six files, the API contract and the migration, are high-risk paths that need their owners.
The local hooks do not compute a lane, because a lane is a rule the developer must not be able to skip. The server computes it when the pull request opens. That is the pattern of this whole stage: the machine answers early, the server answers for certain, and a team that confuses the two has a gate that anyone can walk around.
Next: at 09:34 the ship skill pushes the branch and opens pull request #4812, and the change stops being private. The pull request.