GateGuard change safety
GateGuard is a hook-driven safety layer for agent actions. It checks proposed file changes and shell commands, asks for facts that make the action reviewable, and records safe or blocked outcomes across supported hosts. Its role in the wider hook system is described in Hooks, memory, and host events, while the surrounding skill and language rules are described in Skills, contexts, and language rules.
Gate flow
GateGuard turns a tool event into a risk-aware decision. It uses the current turn, the target, and session state so that the first action receives scrutiny while a justified retry can proceed.
Tool events
The PreToolUse gate receives Edit, Write, MultiEdit, NotebookEdit, Bash, and PowerShell events. It normalizes these host tool names before it selects the file-change or shell path, which lets the same safety model run across supported hosts. NotebookEdit uses the notebook path as its target. MultiEdit applies the decision separately to each file. scripts/…/gateguard-fact-force.js• L2323-2360 skills/…/SKILL.md• L47-55
The hook returns either the original action or a host denial with a reason. A denial tells the agent which facts to provide and to retry the same action. scripts/…/gateguard-fact-force.js• L1953-1966 scripts/…/gateguard-fact-force.js• L2080-2095
This diagram shows the main decision path from an incoming action to an allowed action, a fact request, or a recorded outcome.
flowchart TD
A[Tool event] --> B{Supported action?}
B -->|File change| C[Collect target and turn evidence]
B -->|Bash or PowerShell| D[Classify command risk]
B -->|Other| E[Allow unchanged]
C --> F{Prior evidence or safe exception?}
F -->|Yes| G[Allow with context]
F -->|No| H[Request facts]
D --> I{Destructive?}
I -->|Yes, first attempt| H
I -->|No or checked retry| J[Allow unchanged]
H --> K[Record decision]
G --> K
J --> K
References: scripts/…/gateguard-fact-force.js• L2323-2426 scripts/…/gateguard-fact-force.js• L2498-2551
Change profiles
A change profile is a small risk summary for one target. It identifies the language when supported, whether the change may affect a public surface or data, and whether an edit is only a comment or whitespace change. The profile lets the gate ask only the facts that fit the proposed change. Unknown, oversized, unsupported, sensitive, hard-linked, and NotebookEdit cases stay on the full-question path rather than receiving a low-risk label. scripts/…/gateguard-change-profile.js• L8-27 scripts/…/gateguard-change-profile.js• L401-455 skills/…/SKILL.md• L93-136
The profile changes the facts GateGuard requests. A code change can require importers, callers, public API, data-schema, and optional external-contract facts. When a change does not touch a public surface or data, the gate can replace broad questions with local call-site facts. A comment-only edit can pass without a first-touch denial, but the next behavior change to the file is checked. scripts/…/gateguard-target-class.js• L188-220 scripts/…/gateguard-fact-force.js• L2389-2397 skills/…/SKILL.md• L57-75
References: scripts/…/gateguard-change-profile.js• L438-455 scripts/…/gateguard-target-class.js• L188-220 scripts/…/gateguard-fact-force.js• L2210-2247
Evidence collection
Evidence collection links the proposed action to facts already found in the current turn. This reduces repeated questions without treating a file-name lookup or an unseen parallel result as proof.
Search evidence
Prior-search credit applies when a recognized search found the target in a useful scope during the current human turn before the edit. The search rules account for path scope, filters, command type, target class, and whether the result is complete and unambiguous. A Read is not search evidence. When a search is close but does not qualify, the hook can explain why it failed to count. scripts/…/gateguard-search-evidence.js• L20-69 scripts/…/gateguard-fact-force.js• L2106-2137 skills/…/SKILL.md• L331-359
Sensitive and hard-linked targets do not accept prior-search credit. They also bypass comment-only, sibling, denial-cap, and subagent convenience rules. These targets keep the first-touch denial because an apparently related search is not enough protection for them. scripts/…/gateguard-fact-force.js• L2181-2207 scripts/…/gateguard-fact-force.js• L2375-2422 skills/…/SKILL.md• L291-329
References: scripts/…/gateguard-search-evidence.js• L72-103 scripts/…/gateguard-search-evidence.js• L175-220 scripts/…/gateguard-fact-force.js• L2106-2137
Target classes
GateGuard classifies targets by their role in the project. The class selects the kind of evidence that best exposes risk instead of asking every target the same questions.
| Target class | Main concern |
|---|---|
| Instruction | Which host loads it and what agent behavior it changes |
| Test | What behavior it covers and which module it exercises |
| Prose | Whether it replaces or duplicates existing guidance |
| Config | Which process reads it and what effect the change has |
| Code | Which callers, public surfaces, and data formats depend on it |
The class is based on the project-relative target path. Code uses the change profile to narrow or expand its questions, while the other classes use fixed evidence needs. scripts/…/gateguard-target-class.js• L31-69 scripts/…/gateguard-target-class.js• L177-220
References: scripts/…/gateguard-target-class.js• L33-69 scripts/…/gateguard-target-class.js• L151-181 scripts/…/gateguard-target-class.js• L177-220
Risk classification
GateGuard separates ordinary change review from actions that can destroy or rewrite data. This keeps routine read-only inspection usable while placing a stronger fact check before irreversible work.
Destructive commands
The shell gate checks Bash and PowerShell commands for destructive behavior. It covers shell-agnostic actions such as risky Git operations and SQL changes, plus PowerShell-specific destructive forms. It also examines nested command bodies and known wrappers so that a dangerous action does not become safe only because it is quoted or nested. Extra destructive patterns can extend the built-in set. scripts/…/gateguard-fact-force.js• L1392-1410 scripts/…/gateguard-fact-force.js• L1225-1389 skills/…/SKILL.md• L191-199
On the first destructive attempt, the hook asks for three facts: the files or data affected, a one-line rollback procedure, and the user’s current instruction quoted exactly. A retry of the same checked command can proceed after the facts are presented. Read-only Git inspection does not consume the routine shell check. scripts/…/gateguard-fact-force.js• L2029-2040 scripts/…/gateguard-fact-force.js• L2498-2516
References: scripts/…/gateguard-fact-force.js• L1392-1410 scripts/…/gateguard-fact-force.js• L1862-1928 scripts/…/gateguard-fact-force.js• L2498-2551
Routine shell actions
The first non-read-only Bash or PowerShell command in a session receives a lighter context check. The agent states the current request and what the command verifies or produces. Read-only inspection commands pass before that check and are counted separately. Operators can disable this routine check while the destructive check remains active. scripts/…/gateguard-fact-force.js• L2043-2054 scripts/…/gateguard-fact-force.js• L2519-2551 skills/…/SKILL.md• L201-219
References: scripts/…/gateguard-fact-force.js• L229-231 scripts/…/gateguard-fact-force.js• L2519-2551
Decision state
GateGuard keeps bounded state for each session so that a fact request has meaning across retries. The state tracks checked targets and action outcomes, then expires after an idle period or is trimmed when it grows too large. Session-keyed state expires after eight idle hours. Project-keyed fallback state expires after thirty idle minutes. scripts/…/gateguard-fact-force.js• L91-105 scripts/…/gateguard-fact-force.js• L1447-1501 skills/…/SKILL.md• L221-223
First-touch outcomes
The first meaningful action for a target follows an ordered set of paths. Exemptions and prior evidence can avoid a denial. Sensitive and hard-linked targets skip those convenience paths and receive the full check.
- Credit: earlier search evidence satisfies the check.
- Trivial: the edit changes only comments or whitespace.
- Sibling: a new file in the same directory already shares a gate in the turn.
- Deny: the agent must present facts before retrying.
- Cap: the session denial limit allows progress without another denial.
- Pass: the target was already checked or a narrow exemption applies.
Multi-edit requests apply this decision per target and can therefore be partly applied when calls run in parallel. A correlated same-file batch can receive a sibling denial, but the lock does not make edits to different files transactional. The denial message warns the agent to re-read files before it builds on a partially applied batch. scripts/…/gateguard-fact-force.js• L1931-1945 scripts/…/gateguard-fact-force.js• L2381-2495 skills/…/SKILL.md• L225-251
References: scripts/…/gateguard-fact-force.js• L1676-1743 scripts/…/gateguard-fact-force.js• L1931-1945 scripts/…/gateguard-fact-force.js• L2381-2495
Session state
State is isolated by a session key when the host provides one. If the host does not provide one, GateGuard falls back to a project key. Checked targets use canonical paths, so relative and absolute spellings of the same target share one first-touch decision. State writes merge concurrent observations and publish complete files, which prevents a partial state file from becoming the source of a permanent retry loop. scripts/…/gateguard-fact-force.js• L1447-1477 scripts/…/gateguard-fact-force.js• L1518-1576 scripts/…/gateguard-fact-force.js• L2098-2104 skills/…/SKILL.md• L534-541
References: scripts/…/gateguard-fact-force.js• L91-103 scripts/…/gateguard-fact-force.js• L1447-1501 scripts/…/gateguard-fact-force.js• L1518-1576
Decision reporting
GateGuard can emit privacy-limited decision metrics for review of how the gate behaves in real sessions. Metrics are opt-in and use codes, a short session digest, tool names, decision types, question IDs, and change-profile flags rather than paths, commands, or file contents. scripts/…/gateguard-fact-force.js• L2261-2315 scripts/…/gateguard-metrics.js• L7-83
Metrics files
Metrics are appended as validated JSON lines in the GateGuard state directory. The file rotates after its size limit, and write failures do not stop the protected action. scripts/…/gateguard-metrics.js• L85-132
References: scripts/…/gateguard-metrics.js• L7-14 scripts/…/gateguard-metrics.js• L56-83 scripts/…/gateguard-metrics.js• L85-121
Report summaries
scripts/gateguard-report.js reads the current and rotated metrics files, skips malformed lines, and builds total and per-session summaries. The report shows decision counts, denial classes and reasons, near-miss share, first-touch outcome rates, routine read-only passes, and the most common questions. It supports plain text for people and JSON for downstream tools. scripts/gateguard-report.js• L54-83 scripts/gateguard-report.js• L97-145 scripts/gateguard-report.js• L186-215
References: scripts/gateguard-report.js• L8-23 scripts/gateguard-report.js• L97-145 scripts/gateguard-report.js• L157-183
Effectiveness evaluation
The development-only effectiveness harness measures whether the gate improves agent work rather than only counting denials. It runs controlled Claude sessions against scenario workspaces, compares gate variants, grades the resulting workspace, and preserves enough output to resume or audit a run. The published comparison reports a 2.25-point average quality gap between gated and ungated work across two tasks. docker/…/run.js• L14-29 docker/…/lib.js• L278-300 skills/…/SKILL.md• L35-45
Evaluation arms
The harness compares these conditions:
| Arm | Purpose |
|---|---|
| Off | Baseline without GateGuard |
| Gate | Normal candidate gate |
| Minus-target | Gate without the scenario’s target questions |
| Placebo | Gate with a placebo question change |
| Main | Gate from the main reference when selected |
The comparison separates the effect of having a gate from the effect of asking the right question. Each run uses fresh materialized trees and can resume from recorded trial results. docker/…/arms.js• L7-16 docker/…/run.js• L143-177
References: docker/…/arms.js• L7-16 docker/…/arms.js• L95-103 docker/…/run.js• L165-215
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the change-profile flags, target question selection, and metrics profile fields aligned. A new risk signal is otherwise invisible in either the prompt or the report.
- Keep destructive rule IDs stable across Bash and PowerShell. Governance and reports use those decisions as evidence.
- Keep the supported tool set aligned across the hook normalizer, host hook matchers, and effectiveness arm settings.
- Keep metrics decision names aligned with the report’s denial and first-touch groups. A new decision can be recorded but omitted from summaries.
- Keep retry and session-state behavior aligned when changing denial paths. A mismatch can turn a valid retry into a repeat denial or allow an unreviewed action.
- Keep the documented environment controls aligned with the gate order. Exempt globs intentionally override sensitive and hard-link checks, while the denial cap does not.
- Keep the full-question fallback aligned with new file types, size limits, NotebookEdit, and external-contract settings. A new path can otherwise receive weaker evidence than intended.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| State cannot be read or written | GateGuard allows the action and emits a state warning to avoid a permanent retry loop | Check the configured state directory and its permissions |
| A multi-edit batch is denied part way through | Other files in the batch may already be changed | Re-read the named target and its siblings before continuing |
| A destructive command is hidden in a nested or wrapped shell body | An incomplete classifier could allow the risky action | Keep nested-body scanning and Bash-compatible classification active for both Bash and PowerShell |
| Metrics contain malformed or partial lines | The report skips those lines and understates activity | Treat skipped-line counts as a data-quality signal |
| Two effectiveness workers use one output directory | The run is rejected by the output lock | Give each worker a separate output directory |
Key files
| File | Why to read it |
|---|---|
| skills/…/SKILL.md | Describes the gate contract, question selection, session controls, and operator-facing behavior. |
| scripts/…/gateguard-fact-force.js | Main event gate. It connects target review, shell risk checks, state, denials, retries, and metrics. |
| scripts/…/gateguard-change-profile.js | Defines the high-level risk facts for supported file changes. |
| scripts/…/gateguard-target-class.js | Defines target roles and the evidence questions for each role. |
| scripts/…/gateguard-search-evidence.js | Defines when earlier search work counts as evidence. |
| scripts/…/gateguard-metrics.js | Defines the privacy-limited metrics contract and file format. |
| scripts/gateguard-report.js | Turns decision metrics into total and per-session reports. |
| docker/…/arms.js | Defines the comparison conditions used to measure gate value. |
| docker/…/run.js | Runs, resumes, and summarizes controlled effectiveness trials. |