Repository navigation
Releases
v0.0.12
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.12/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.12/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
Release 0.0.12
Pregate v0.0.12, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.12, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
If you installed Pregate globally, with install.sh, install.ps1, npm i -g pregate, or npx pregate, update that installation so the hooks use 0.0.12. Run pregate update. It installs this engine and prepares a review for each enabled project that still pins an older one. Approve that review before the project runs on 0.0.12. A hook keeps using the engine the project already pinned until that review is approved.
This release adds checks you turn on yourself. A new methodology is not part of an existing preset. Select it with pregate pack enable. Pregate still enforces a project only where someone ran pregate enable. A directory that was never enabled, and a checkout that was disabled, block nothing. No rule was removed or downgraded.
Opt-in, and only where the project is enabled
Global hooks stay installed. They do not enforce a directory with no enable record.
The methodologies in this release are architecture/structure, node/operations, maintainability/proxies, typescript/compiler, and typescript/checked. Enable one with pregate pack enable, for example pregate pack enable architecture/structure. The rules run only where pregate enable is in effect. Approving the methodology does not start enforcement in a directory that was never enabled, or in a checkout that was disabled.
Presets that already select typescript/strict-types or typescript/discipline do not gain typescript/compiler or typescript/checked. human-maintainability stays 1.0.0 and does not include maintainability/proxies.
Architecture structure
Architecture pack 1.4.0 adds architecture/structure (#129).
ARCH-CYCLE-001 denies an edit that creates or enlarges a TypeScript or JavaScript import cycle. An existing cycle may stay.
ARCH-FILE-001 caps a file at 400 code lines by default. ARCH-EXPORT-001 caps public exports at 20 by default. An existing excess may stay when the edit does not raise it.
ARCH-HERIT-001 warns when a class extends chain is deeper than 3.
The engine metric vocabulary adds file.lines, file.publicExports, and heritage.depth. A metric may set ratchet: "no-increase", which grandfathers an existing excess even when the preset ratchet is strict. diff accepts count: "import-cycles".
forbidden-path reports a reviewed path that matches params.globs. No Node pack rule is bound to that primitive yet.
Node operations
The node pack is 1.4.0. node/operations is preview (#128). It adds thirteen checks from the Node.js invariant triage. They run only after pregate pack enable node/operations.
Five are fitness evidence:
NODE-LOCK-001is the Node.js side of coreCORE-INV-050: a committed lockfile, andnpm ci,pnpm install --frozen-lockfile, oryarn install --immutablein CI. It is not a shell gate.NODE-ENVFILE-001requires.envin.gitignoreand a committed.env.example. It stays fitness because the Node pack has not boundforbidden-path.NODE-PIN-001requires a readable Node.js pin. The pack already reads.nvmrc,.node-version,.tool-versions,engines.node, andvolta.node.NODE-SCRIPTS-001requires--ignore-scriptsor a reviewed install-script allowlist.NODE-EDGE-001is the edge-header evidence when headers are not in the process.
Eight are syntax proxies, each with a fidelity label: a graceful close on SIGTERM and SIGINT, HTTP timeouts and a body limit, /health and /ready, a startup process.env schema parse, Helmet or equivalent headers, a request id plus pino or winston, wrapped async route handlers, and logger arguments named like secrets.
A handler for uncaughtException or unhandledRejection must process.exit or rethrow. That requirement stays NODE-UNCAUGHT-001 in node/internals 1.2.0 (node/process/no-uncaught-exception-empty 1.1.0). It is not a second id. SQL injection, XSS, CORS, source secrets, fetch timeouts, and stack traces stay in vibe-proof. Empty catch stays clean-code/CC-ER-002. Import cycles stay with the architecture pack.
Maintainability proxies
Maintainability pack 1.3.0 adds maintainability/proxies (#130). The methodology is preview. Enable it with pregate pack enable maintainability/proxies. The coverage map is packs/maintainability/PROXIES.md. These rules run only where pregate enable has turned the project on.
MAINT-MAGIC-001warns on a numeric literal outside the allowlist.MAINT-TEST-001looks for a domain sibling or a mirrored test.MAINT-ADR-001looks for an ADR path in the same diff as a configured architecture file.MAINT-TODO-001looks for an issue reference on TODO and FIXME, beside the owner check.MAINT-FLAG-001warns when a configured risky path does not import a feature-flag module.MAINT-CHURN-001warns when a file that already changes often also grows.MAINT-AND-001warns on function names that use the wordsAndorThen.
God-module size and import cycles stay with the architecture pack.
TypeScript compiler and checked edits
TypeScript pack 1.4.0 adds typescript/compiler and typescript/checked (#131). They run only where the project enables those methodologies.
TS-CFG-001 reads a merged tsconfig, including extends, for one strict contract: strict, noUncheckedIndexedAccess, noImplicitOverride, noImplicitReturns, noFallthroughCasesInSwitch, forceConsistentCasingInFileNames, verbatimModuleSyntax, a target of ES2022 or newer, and moduleResolution of bundler, node16, or nodenext. strict: true is one finding, not eight. skipLibCheck and exactOptionalPropertyTypes warn and do not deny. tsc --noEmit and eslint stay on core/CORE-INV-056. The pack does not add a fitness command.
The other new rules are same-file or count proxies: type-only imports, prefer-const, I interface prefixes, a parser between JSON.parse or .json() and a typed use, readonly exported arrays, a copy before sort or reverse on a parameter, { cause } on a rethrow, a reason on @ts-expect-error and @ts-ignore, and separate no-increase ratchets for any and non-null !.
Boolean parameters and boolean property bags are one family in the senior pack. SR-FLAG-001 matches a boolean parameter. Senior pack 1.3.0 adds SR-FLAG-002, a low-fidelity warning that counts two or more boolean fields on one exported type. The TypeScript pack does not declare a second copy. The two rules do not match the same syntax. SR-FLAG-002 is part of senior/fowler, so a project that already selected that methodology gets the rule when the updated pack is reviewed. It is not its own methodology. A project that never selected senior/fowler does not start enforcing it.
Antigravity Auto still asks
Antigravity 1.5.7 made Auto the default agent mode where that mode is available, including agy -p, and Default where it is not (#126). Auto is not always-proceed and not Turbo.
An interactive session whose saved agentMode is auto, accept-edits, plan, or "" still receives force_ask for a literal pregate approve. strict still asks. A --settings overlay that sets neither toolPermission nor permissionPreset leaves that decision to the saved file.
On agy 1.5.9, --mode=auto reported the enable-auto-permission-preset rollout off and continued in Default. In that session a hook deny still blocked a contract write, including under --dangerously-skip-permissions. Headless -p did not apply pregate approve. A checkout that was never enabled, and one disabled with pregate disable, still got an empty hook reply.
On Windows the ancestor walk asks for one process at a time and still reads CommandLine only for an agy process. A snapshot of every process could pass the query deadline and was then treated as unreadable, which dropped force_ask.
Grok fails closed when the pre hook does not answer
The shared PreToolUse hook sets failClosed: true (#127, #45). Grok Build 1.0.71 and newer denies the tool when that hook crashes or times out inside a directory pregate enable covers. The Unix and Windows launchers decide that before either starts the engine.
A directory that was never enabled, and a checkout that was disabled, exits 0 with empty stdout when the engine is missing, crashes, or would hang. That includes a machine where another project is enabled. The pre hook does not print the disabled notice. pregate status still names the scope. A worktree disable and a project disable are not enforced.
An enforced checkout whose .git is a directory is recognized without starting git, so the timed hook does not pay for that process.
Grok 1.0.70 ignores the unknown field and keeps its fail-open crash. An allow stays empty stdout and exit 0. On Grok 1.0.77 that allow still lets the tool run. Stop, SessionStart, and project Claude hooks do not set the field.
What this release does not establish
- No rule was disabled, downgraded, or removed. Timeouts, thresholds, and the committed latency baselines are unchanged. The macOS latency gate still fails by runner noise at times.
- The new methodologies stay off until `pregate pack enabl...
v0.0.11
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.11/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.11/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
Release 0.0.11
Pregate v0.0.11, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.11, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
If you installed Pregate globally, with install.sh, install.ps1, npm i -g pregate, or npx pregate, update that installation so the hooks use 0.0.11. Run pregate update. It installs this engine and prepares a review for each enabled project that still pins an older one. Approve that review before the project runs on 0.0.11. A hook keeps using the engine the project already pinned until that review is approved.
This release is about where Pregate gets in the way, and where it should stay quiet. It checks a project only after someone ran pregate enable there. Turning it off is per checkout, or for the whole project. Everyday development commands run inside a project you enabled. A long session fails closed when its records or the engine are incomplete, instead of reading without a bound. No rule was removed or downgraded. Eleven core heuristics that were blocking judgments now start as advice.
It checks only a project you turned on
Global hooks stay installed. They do not enforce a directory that has no enable record. Pre-command and pre-edit exit 0 there: a write, a hook switch, git commit --no-verify, and a change to harness settings such as ~/.claude/settings.json all go through. SessionStart may still print one line. A pending review, a pending batch, another project this session already reached, the home directory, and a parent past a .git boundary do not turn enforcement on. A committed .pregate/preset.json is not consent.
That is the fix for a global hook denying python3 and bash script paths in a repository that was never enabled (#106).
Turning a checkout off
pregate disable is a human command. With no extra flag it disables the current worktree, the checkout of the current branch, and withdraws the repository consent other worktrees were inheriting. A checkout that was enabled by name stays enforced. A worktree added afterwards is not enforced until someone enables it.
pregate disable --project disables the whole repository, including worktrees that were enabled by name. After either command, pre-command and pre-edit block nothing in that scope. That includes pregate approve --yes, pregate enable, a hook switch, and a write to harness settings. The hook may print one line that Pregate is disabled. It does not deny. pregate status says whether the worktree, the project, or both are disabled, and a worktree disable names the branch. A write that lands in a different worktree that is still enabled is still that worktree's write. pregate enable turns protection back on.
Everyday commands in a project you enabled
Inside an enabled project, these run:
- Registry reads, such as
npm viewandpnpm view. - Package installs, such as
pnpm install,npm ci,bun install, andyarn. git init.dockeranddocker compose.- Build, test, and dev runners, such as
next build,tsc,vitest run,pnpm test,pnpm dev, andnpm run.
The package.json script or Makefile recipe they launch is still scanned. A script that edits gated source or runs a pregate control command is denied, and the message names the write target or the word that triggered it. An unknown npm or pnpm subcommand is denied by name.
A literal git config read is allowed, including git config --get core.hooksPath, and the same query inside sh -c, eval, pwsh -Command, and cmd /c (#114). Writes, --no-get, -c core.hooksPath=, and GIT_CONFIG_* stay denied.
A literal cat of the installed skill file is allowed. A denial is recorded when the directory has a preset, so pregate issue draft --last can find it. A denial in a directory with no preset does not tell the agent to run that command (#106, #114, #116).
One agent can start another
A harness that already has Pregate hooks may launch another. Global hooks come from pregate setup. Project hooks for Claude Code, Codex, Cursor, and agy come from pregate project hooks --harness <id>. claude -p, codex exec, opencode run, agy, grok, and cursor-agent are allowed, including a prompt that mentions pregate. claude and claude-code are the same installation, as are agy and antigravity, cursor, cursor-agent and agent, and opencode and opencode-ai.
Flags that skip permissions, --no-hooks, a HOME= override, hook settings, and hooks or plugin subcommands stay denied. Launching a harness that is not gated is denied with that harness's name and the command that gates it.
Driving a browser or a desktop
orca, orca-dev, orca-ide, agent-browser, and agent-desktop may inspect or drive a browser or a desktop, with consent on or off, including through npx and bunx (#112, #113). orca console, orca network, orca status, orca tab, orca screenshot, and orca skills get are drive commands. Read-only inventory is allowed on the same paths, including orca ports (#118). The launcher is read for control commands only. A screenshot path inside the project is still an ordinary write.
Launching an agent stays denied: orca agent launch, orca worktree create --agent, orca automations run, and a terminal whose command starts a harness. orca agent hooks off is a hook switch. An orca verb that is none of these, when the launcher is inside a project, is denied, and the message names the tool and the verb.
node -e, node -p, and bun -e allow a closed read-only program: a for…of over string literals, require or import of a JSON path that starts with ./, ../, or / and ends with .json, and console.log (#118). Writes, child processes, eval, and any other require stay denied.
Approving a review from the harness
A literal pregate approve <code>, or pregate approve --yes with an optional --digest, works again from the harness shell on Claude Code, Codex, Grok, Cursor, OpenCode, and agy, including a ! line. It does not need a terminal. An agent could run that command. The approval log records a non-terminal confirmation (via: "yes") instead of making it impossible. A bare approve still asks for y on a terminal. enable, disable, init, promote, pack, and the other --yes commands stay on a human terminal.
In an interactive Claude Code parent session, that literal command returns permissionDecision: "ask". Accept runs it. Reject runs nothing. A subagent, dontAsk, bypassPermissions, a remote session, and CI do not ask. An interactive agy session returns {"decision":"force_ask","reason"} with the same summary. Skip-permissions, always-proceed, Turbo, print mode, a child conversation, and CI do not ask. Codex, Cursor, Grok, and OpenCode keep the allow. The approval log stays via: "yes", because the approve process cannot tell a click from a command the agent ran itself.
Setting PREGATE_UNATTENDED_APPROVAL, PREGATE_TESTING, PREGATE_TEST_ANSWER, or PREGATE_ACCEPT_CONTRACT on a command is still denied. The cause is approval, not hook-switch (#105). The text says an agent cannot grant itself approval and points at the human terminal, including the exact command. It does not suggest a rule adaptation. A command that really installs, removes, or switches off Pregate stays hook-switch.
Some core rules advise instead of blocking
Eleven of the 64 core requirements are reading-quality judgments rather than provable product conditions. Their default severity is warn: cohesion-and-coupling, observable-contract, stable-dependencies, collaborator-knowledge, composition, domain-language, sufficient-simplicity, clear-code, predictable-names, abstraction-level, and least-power. Their identity, fixtures, and traceability stay in the core. A reviewed promote raises one when a project justifies its bound. Every other core rule stays deny and enforce.
Twenty-four requirement statements gained a scope note that keeps the original request text as their prefix. A committed lock that records each resolved version satisfies the pin, and an exact manifest pin does too. A risky feature, for the flag requirement, is one that is hard to reverse after release.
A long session fails closed
A session read keeps at most the newest 1,024 events and says how many older events were left out. Nothing is deleted. A denial outside that window no longer counts. A new violation still denies.
A snapshot is not published when the dirty-tree walk cannot read a directory. That failure is state-io for the whole snapshot. An unreadable file ends that directory's walk and keeps what was already read.
An unhandled rejection exits 1 and prints pregate: <message>. The launcher denies that exit. It is not a silent allow.
Fitness verifier diagnostics redact token-shaped text before the receipt is written. writeAtomic removes its temporary file when the write fails. When a supervised engine passes its deadline, the supervisor sends SIGKILL and waits until that process has exited before it returns the deny.
An unsafe session id is refused before admission writes a checkpoint. Consent is read once per hook call, and the rest of the call reuses that answer.
For people who build this tree...
v0.0.10
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.10/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.10/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
Release 0.0.10
Pregate v0.0.10, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.10, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
This release is a correctness pass on the engine you already have. No rule was removed or downgraded. Two gaps are closed: a lock that names a primitive the engine does not evaluate fails closed, instead of quietly skipping that rule, and the shell guard no longer treats a file path or an npm script whose name contains a hook word as a bypass.
A mistyped primitive fails closed
analyze used to skip a rule whose primitive was outside the seven it evaluates. A mistyped or hand-edited lock could make that rule vanish, with no finding and no error. Unknown primitives now throw.
Four primitives stay skipped there on purpose, because another part of the engine handles them: layer-edge and banned-import in the import checks, placement in placement(), and fitness in the fitness gate. The vocabulary lives in named constants (EVALUATED_PRIMITIVES, IMPORT_PRIMITIVES, NODE_PRIMITIVES) shared by the places that used to repeat the names.
A path is not a hook bypass
The shell guard's hook-word list adds generic disable and bypass flags: --no-hooks, --disable-hooks, --skip-hooks, --bypass-hooks, and the same words with a hyphen or an underscore. Each one matches a whole argument, including --flag=value, so a renamed bypass flag is still caught. The same stems without the leading dashes are a hook switch only when they are arguments of a harness command.
A path or an npm script whose name merely contains those words is an ordinary command again. src/disable-hooks.ts and npm run disable-hooks are not a bypass. The verbatim flags that were already denied stay denied.
A malformed hook flag is named
pregate hook accepts hook <event> and hook <event> --harness <id>. A --harness without a known harness, or an extra operand, is reported on stderr and evaluated with the default adapter. It is no longer a silent misroute to the wrong harness.
For people who build this tree
bun run clean removes dist/ and every *.bun-build scratch copy bun build --compile can leave in the working directory, including a hidden .name.bun-build and a bare .bun-build.
bun run test:unit and bun run test:e2e split the suite. Files named e2e.test.ts or *.e2e.test.ts are the compiled-binary half. Every other test file is the fast half.
bun test no longer writes user state into the real home when a test file forgets its own isolation. The preload gives every unset HOME, USERPROFILE, XDG_*_HOME, CODEX_HOME, GROK_HOME, and CLAUDE_CONFIG_DIR a throwaway directory. A test that sets one of those itself still wins.
The repository's own CI jobs read PREGATE_ACCEPT_CONTRACT from the repository variable, as the published CI template already does. A pull request still cannot set that digest.
src/inertia.ts is now src/admission.ts. The module holds the same admission constants. Only the import sites moved.
What this release does not establish
- No rule was disabled, downgraded, or removed. Timeouts, thresholds, and the committed latency baselines are unchanged. The macOS latency gate still fails by runner noise at times.
- The four primitives handled outside
analyzeare still skipped there on purpose. An unknown primitive fails the check. It does not become a finding of that rule. - A hook bypass that is neither a whole argument nor a bare stem on a harness command is outside this list. Refresh the list when a harness ships a new hooks flag.
- The full suite does not run on macOS in CI. macOS runs the latency and release-build jobs there, and the suite on the maintainer's machine.
The changelog lists every change.
v0.0.9
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.9/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.9/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
Release 0.0.9
Pregate v0.0.9, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.9, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
This release makes the first review of a new project one approval, and it keeps approval in a person's terminal. A project that already uses ArkGate can import that layer map without being judged twice. Project Cursor hooks answer preToolUse in Cursor's own permission object, and a workspace that also has project Claude hooks records one evaluation per tool call. Advisor mode says when a file was not checked. Pack matchers that fired on the wrong shape are narrower, and a Go sh -c call whose script is a variable is reported.
One approval for a new project
guide --preview on a project with no contract now prepares one digest. It holds the contract, the layer map derived from folder names, and the rules compile can make from AGENTS.md, CLAUDE.md, and .cursorrules, together with the detected scope and the selected packs.
--layers <layers.json>replaces the derived map when noark.config.jsonis present.- Repeatable
--compile <proposals.json>adds rules the agent completed with examples. - After a contract exists, those two flags are refused.
layers apply,compile apply, andimport arkgateeach prepare their own review.
pregate import arkgate --preview reads ark.config.json and proposes the layer map plus coexist.arkgate. A layer rule ArkGate already enforces is listed in ownedByArkgate and is not evaluated again. A key the ArkGate schema does not name is rejected. On a new project the guide detects that file and includes the import; a hand-written layer file is not the map that review uses. The shell guard allows the preview when every word is literal and the command carries no --yes or --digest.
Test apps under packages/<name>/test/ stay inside the owning package. SvelteKit's packages/kit/test/apps/async has its own manifest and a nested package that owns @sveltejs/kit. That split used to make guide --preview throw, and the message claimed a contract had been kept when none existed. A nested owner anywhere else still needs an explicit scope. guide --json reports that scope error and exits 1. guide --preview --packs <ns,ns> names the packs the review keeps.
Approval stays in a separate terminal
A harness ! line cannot approve. Claude Code, Codex, Grok, agy, OpenCode, and Cursor ! lines have no terminal. A detached pregate approve with piped stdin still refuses before /dev/tty. The refusal names the project root and the command to run in Terminal or iTerm, or in a new PowerShell window on Windows. On agy 1.5.6 that ! line was refused because stdin is not a terminal. The earlier note covered only 1.2.17. The approval code stays withheld when stdout is not a terminal. The line that tells the human which command to type stays visible.
Codex can attach a pty to exec_command, and write_stdin types into that pty with no further PreToolUse. The Pre hook sees only the command. A non-literal script, including bash -c 'while read l; do eval "$l"; done', is denied as shell-write before that child starts, so there is no terminal for write_stdin to type pregate approve into. script, tmux, and screen stay denied.
When an approval applies and Git cannot commit it, the message keeps the last lines of Git's stderr. A pre-commit hook's reason is that text. The message also prints the command that commits once the hook can succeed. Hooks are not skipped.
A clean checkout of a branch that already exists
A plain git switch <branch> or git checkout <branch> of one existing branch on a clean worktree is allowed. The files that differ arrive with that branch. A protected path among them is still denied. A dirty worktree, --force, --discard-changes, --detach, a new branch, a commit or tag, a path checkout (git checkout -- <file>), and any change under .pregate/ stay denied.
Advisor mode says when a file was not checked
import("m").Type<Args> and the same form nested, qualified, or used as typeof import("m") were syntax errors in .ts, .d.ts, and .tsx. An audit of a file that used them exited incomplete, and advisor mode reported the file as clean. Those type queries now parse. A file that still does not parse is PREGATE WARN syntax in advisor mode. Enforce still denies it. Malformed type arguments stay syntax errors.
An import that cannot be resolved is no longer an unconditional deny. In advisor mode it blocks only when an enforced static rule would be skipped. Otherwise the call warns (PREGATE WARN unresolvable-import) that the file was not checked, because no enforced rule applies to it. Shadow still blocks every unresolved import, because integrity stays enforced there. Enforce stays fail-closed.
Cursor answers preToolUse in its own words
Project .cursor/hooks.json answers native preToolUse with Cursor's permission object, at exit 0. Allow is {"permission":"allow"}. Deny is {"permission":"deny","user_message","agent_message"}. preToolUse sets failClosed: true. A missing or empty pinned engine exits 2 and names pregate prepare. The command does not fall back to a global launcher or to pregate on PATH.
sessionStart stays in the file for the local IDE. Hosted cloud agents do not run sessionStart. They judge writes on preToolUse alone.
When both of those project files are present, the project Claude command exports PREGATE_PROJECT_HOOK=1. On a Cursor payload that hook exits 0 with no output when the native file owns the same event, and it records nothing. Pregate records one evaluation per tool_use_id. A global Claude registration does not set the marker and still evaluates.
Narrower pack matchers
Fifteen bundled rules reported shapes that were not the sink they name. The matchers now read the module specifier, the Supabase call, the JSX element, or the local binding, and a test.skip() inside a runtime if in a test is allowed. Packs: supabase 1.2.1, nextjs 1.4.1, react 1.2.1, testing 1.2.2. No rule was disabled or downgraded. The findings were measured on engine 0.0.8.
security-audit/SA-GO-SHELL-001 now reports exec.Command("sh", "-c", cmd) and exec.CommandContext when the script is a variable, including bash, /bin/sh, and /bin/bash. A script built with fmt.Sprintf or + stays reported. A constant script and a direct exec.Command("git", "status") stay quiet. The security-audit pack is 1.0.1. strings.Join, a shell name held in a variable, and a renamed os/exec import remain outside the check.
JS-EVAL-001 flags a bracket call of the string literal eval on window, such as window["eval"], and a later call of a local initialized to eval. Direct eval, window.eval, and (0, eval) stay flagged. A bracket call on any other object, the string eval outside a call, and a method named eval are not. The javascript pack is 1.2.2.
pregate scan recommends the Vue pack from dependencies, devDependencies, peerDependencies, and a .vue file in primary source. A server app often lists vue only as a devDependency. react in devDependencies recommends the React pack for the same reason. A devDependency still does not select Svelte, Next.js, Astro, Hono, Express, NestJS, or TanStack Query. vue-router and eslint-plugin-vue do not select Vue.
What this release does not establish
- Launcher end-to-end tests cover the Cursor
preToolUsepayloads, the missing pinned engine, and the one-evaluation pair. Livecursorandcursor-agent2026.11.11 sessions, hosted cloud runs, Windows Cursor sessions, and Cursor's trust prompt were not run in a live Cursor binary on the CI or development machine. - Another pty allocator, or an obfuscation the lexer does not read as a non-literal script, can still give a child a terminal. A terminal prints the approval code. The CI ratchet remains the boundary outside the machine.
- A nested package owner outside
packages/<name>/test/still cannot be one include/exclude scope. The preview names it and changes nothing. - Advisor mode still blocks an unresolved import when an enforced static rule would have judged that file. Shadow and enforce still deny it.
- The Go shell check does not follow
strings.Join, a shell name held in a variable, or a renamedos/execimport. - No rule was disabled or downgraded. The macOS latency gate and the Windows archive pack timeout are unchanged. The macOS gate still fails by runner noise at times.
- The full suite does not run on macOS in CI. macOS runs the latency and release-build jobs there, and the suite on the maintainer's machine.
The changelog lists every change. Guarantees and limits records the pty limit this release names.
v0.0.8
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.8/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.8/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
Release 0.0.8
Pregate v0.0.8, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.8, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
This release teaches Pregate the harnesses people actually use, and it lets a project carry its own hooks. OpenCode joins as the sixth harness. Cursor, Codex, Claude Code and Antigravity can register hooks inside the repository, so a cloud agent or a teammate does not depend on a file in someone's home directory. A Claude Code subagent hears the project's briefing when it starts. The shell guard stops blocking a project's own test and syntax commands, and it lets the agent read the skill file Pregate installed.
A project can carry its own hooks
pregate project setup merges Claude Code hooks into the project's .claude/settings.json. They run the reviewed project launcher and the engine the lock pins. They do not fall back to a launcher on PATH, and they do not write the home directory or grant consent. pregate doctor reports that project scope, and it reports workspace trust separately from policy consent.
The same idea, one command per harness:
- Claude Code.
pregate project hooks --harness claude-coderegisters PreToolUse, Stop, SubagentStop and SessionStart through$CLAUDE_PROJECT_DIR. - Codex.
pregate project hooks --harness codexregisters the Codex hooks in.codex/hooks.json, including SubagentStart and SubagentStop. Codex still needs the human to trust the project and review the hooks with/hooks. A later change to the definition removes the gate until that review is done again. - Cursor.
pregate project hooks --harness cursorregisterspreToolUse,stopandsessionStartin.cursor/hooks.json. Cursor's cloud agents load that file from the repository. An MCP tool is judged by the paths it names: a protected file is denied, a file in scope is sent back to the file tool, and a call that names no local path is left alone. - Antigravity.
pregate project hooks --harness agyregisters PreToolUse, PostInvocation, Stop and SessionStart in.agents/hooks.json.
Each command keeps every hook it does not own, and a second run changes no byte. They all go through the same review and approval as a contract change.
OpenCode
OpenCode has no hook process of its own. pregate setup installs a small plugin and lists it in OpenCode's plugins array. The plugin does not decide anything. It asks the same engine the other harnesses use, and it throws the engine's deny so that one call fails.
On Windows the plugin starts pregate.cmd, which is the launcher the rest of Pregate installs there. An earlier build looked for the Unix launcher and then reported that Pregate could not evaluate.
A project with no .pregate/preset.json stays inert. The plugin ignores read-only tools. OpenCode's code-mode tool, whose nested calls no hook can see, is denied in an enabled project.
Subagents hear the contract
A Claude Code subagent used to start with only the task its parent wrote. It learned of a rule when a write was denied. The registration now answers SubagentStart with the same briefing the session received. The briefing grants nothing: every write is still checked. Run pregate update to add the event to an existing registration.
A Codex child gets bounded contract context, keeps the parent's baseline, and is checked when it finishes. The parent's Stop remains the backstop.
A Grok subagent stop is that child's own session. The payload names the child session and no agent id, so the gate judges the files of that session. A shutdown stop stays ignored.
Antigravity, after the tool returns
Antigravity can now deliver a warning or a halt after a tool call, and a session start message. A task's send_input is treated as a write. Reading or killing a task is not. Settings under ~/.gemini/antigravity, ~/.gemini/antigravity-cli and the global plugin stay protected, including when the path is spelled with Windows backslashes.
The shell guard and the project's own programs
Since 0.0.5, a script that node, bun or deno ran was scanned for write sinks, and the list included import and require. Every real file matched, so node tests/index.js, bun src/main.ts and node --check were denied in an enabled project. In the first session trial this stopped the test or the syntax check.
Two limits now apply. A script that still has the text it had when the session began is the project's program and is not read for write sinks. A script the session changed is read by the rules for a file: an import is a sink only when it names a module that writes files or starts programs. Control commands stay denied.
The same trial showed a second stop. Codex loads the Pregate skill with cat of the installed SKILL.md, and that read was denied as a protected path. One session then abandoned its task. A literal cat of that one skill file is now allowed. A write to the skill folder, a read of any other file there, and a skill folder that links into Pregate's own state stay denied.
A trial with real sessions
The first run of the session trial is published: 48 sessions, Claude Code and Codex, twelve tasks on three public repositories, with and without the gate. Neither arm left a new finding, so the run shows no prevented defect. It shows the cost: seventeen denials in the gated arm, seven of them true, eight false and two unclear. Seven of the false ones were the script scan above, fixed after the run. The page is session-trial.md.
The precision measurement was run again after the rule fixes: 5,508 findings, where 0.0.7 recorded 8,951. Labels written by an agent are counted apart from labels written by the maintainer.
What this release does not establish
- No OpenCode session was captured with a model. The plugin's deny, advice, briefing and Stop were tested without one. Whether a thrown message reaches the model is not yet shown.
- The interactive trust prompt, cloud agents, and a real Windows session were not run for every harness that gained project hooks. What was run, and on which version, is in the changelog.
- Codex project hooks gate a session only after the human trusts the project and reviews the hooks. A later edit of the hook definition turns the gate off until that review is repeated.
- Grok still does not honor a Stop block, on the 1.0.80 measurement. The child session is judged; the CLI may not stop.
- The macOS latency gate is unchanged. It still fails by runner noise at times. The Windows latency job on this release passed.
- The full suite does not run on macOS in CI. macOS runs the latency and release-build jobs there, and the suite on the maintainer's machine.
The changelog lists every change. Guarantees and limits records the shell-guard limits this release adds.
v0.0.7
Release 0.0.7
Pregate v0.0.7, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.7, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
This is a small release. It adds one command and one guide. No rule, no pack and no contract format changed, and the hooks decide as they did in 0.0.6.
A launcher the project owns
pregate project launcher --preview prepares a launcher inside the project, at .pregate/bin/pregate (on Windows, pregate.cmd and project-launcher.ps1). It goes through the same review and approval as a contract change.
- The launcher runs the engine that the project's lock pins, from the user cache. It never falls back to a launcher on
PATH. - A hook call with a missing or empty cached engine denies, and names the reason.
- The command needs a valid engine pin and that engine in the cache;
pregate prepareputs it there. pregate installkeeps this launcher. It removes only the launcher that 0.1.0 committed at the same path.
This is the first step toward a project that does not depend on a machine-wide setup. The harness registrations still come from pregate setup; nothing in this release moves them into the project.
Maintenance, rebuild and rollback
Maintenance, reproducible build and rollback says who releases Pregate, how to build a tag from a clean checkout, how a published archive is verified, and how a pinned project is upgraded and rolled back.
An end-to-end test runs the upgrade and the rollback on every CI run, with two real engines that differ only in version: the upgrade changes the pin and no rule, both engines deny the same edit for the same rule, and reverting the upgrade commit restores the first committed contract.
The page states what a rebuild does not prove. Two local builds of one commit were identical. A local build of v0.0.5 did not match the published archive.
How the project tests itself
- CI takes about half the time. The Linux job ran the whole suite twice, once inside a fresh clone that the job already is. The Windows job ran four suites twice in one serial job that took 29 to 45 minutes against a 45-minute limit. Each suite now runs once, and Windows runs in three parallel jobs. On the runs measured, the Linux job went from 39 to 19 minutes and the slowest Windows job from 29–45 to 14 minutes.
- The suites start fewer and cheaper processes. 3% of the tests used 83% of the Windows time, and the cost was process starts. Suites that ran the engine from source run the compiled engine, and about 40 files share one engine build per test process. No assertion changed.
- Hook latency is also read against the last release. The hosted macOS runner's own speed varied 3.4 times over 60 runs, and the regression gate compares with a fixed number: it failed on unchanged code, and on a fast runner a hook three times slower would have passed. The latency jobs now also time the last release's engine and the current one in turn on the same runner and report the ratio. That reading informs; it fails nothing yet.
- Deadline tests bound the mechanism, not the machine. Three tests put their bound on the life of the process the deadline ends, not on the whole command. No timeout was raised.
What this release does not establish
- The project launcher is one piece. No harness was run end to end from a project with no machine-wide setup.
- The ratio against the last release has no limit yet. Its spread on hosted runners is being collected; the fixed latency gate is unchanged and still fails by runner noise at times.
- The deadline tests were not validated on a low-memory Windows machine.
- The full suite does not run on macOS in CI. macOS runs the latency and release-build jobs there, and the suite on the maintainer's machine.
The changelog lists every change. Guarantees and limits did not change.
v0.0.6
Release 0.0.6
Pregate v0.0.6, core 0.0.1. macOS ARM64 stays the stable platform. Linux and Windows archives stay experimental until native validation is recorded.
Install 0.0.6, then review the project update it prepares (pregate update --project --preview) and approve that exact digest. A global update prepares that review for each enabled project whose lock still pins an older engine.
0.0.5 added the path from an instruction file to rules. This release is what the first trial of that path on a production repository changed. The trial is published as a case study, with what it measured and what it did not.
No folder outside the layer rules
A file in no layer is unrestricted. With a partial layer map, code moved to an uncovered folder imported anything and the check stayed quiet, while the same import from a declared layer was reported.
pregate layers apply <map.json> --preview --completerefuses a map that leaves a source file in scope in no layer, or under which a folder created later would be in none, and names the folders.- A catch-all layer such as
src/**closes the gap. The most specific layer path still wins, so it takes only the files no other layer names. - Partial maps are unchanged, and so are the engine and the contract format. Completeness is a property of the map, and it is opt-in.
Rules from prose, with their exceptions
- A
compile applyproposal can state where the code is allowed withexcept, a list of globs. The drafted rule ignores those paths, and the engine proves it before staging: the failing code placed under each excepted path must pass. - A first layer map, or new layers beside existing ones, no longer prints
WARNING: this may weaken protectionwhen the new globs share a path prefix. A new glob that can take a file from a layer that already had it still warns.
In the trial, one rule made from a statement about money was exact as a pattern and broader than the statement: 5 of 15 sampled findings were money, and 8 were hours, a coordinate or a percentage. A rule like that needs a path scope or stays in advisor mode. The case study has the sample.
A large file no longer stalls analysis
One vendored 1.9 MB, 68,000-line JavaScript bundle made an audit run for more than ten minutes. Three questions with one answer per node were asked again for every candidate. Each is now answered once per node, and findings are unchanged.
| On an Apple M5 Pro, engine run from source | Before | After |
|---|---|---|
| Check of that file, 194 rules | not finished at 120 s | 7.2 s |
| Audit of the 13,499-file repository | not finished at 600 s | 86 s |
Clearer first run and audit
- First-run instructions name one command,
pregate guide --preview. It already proposed advisor mode for a new project; the setup notice,status, the setup messages, the README and the skill no longer add--enforcement advisor. An end-to-end test covers the path: no mode flag, an advisor finding that does not block the write, promotion, then the same edit denied. - The human output of
pregate auditends with a line that states the exit code of that run and what it means.Exit 2is an incomplete audit, not a count of violations, and the line names the cause. Exit codes are unchanged.
Routine commands work in an enabled project
Since 0.0.5 the shell guard refused commands an agent runs all the time in a project with an approved contract. A measurement of 101 routine commands through the real pre hook found 32 refusals. This release leaves 10.
| Refused in 0.0.5 | Why | Now |
|---|---|---|
cd src, type, read, wait, umask on macOS |
A shell builtin was looked up on PATH, and macOS ships /usr/bin/cd and its siblings as scripts with a computed command name |
A builtin is never looked up |
bun test in a project with a test directory |
Read as Bun running a script named test |
A Bun subcommand is not a script file |
pregate layers, pregate compile |
Not on the list of commands an agent may run, although the skill tells the agent to run them | Allowed when they read or prepare a review; no form that applies one is |
npm install, npm test, npx |
npm is a Node script and was read like a project script |
An installed tool outside every project is read for control commands only |
The last row is a trade. A script planted in a PATH folder outside the project is no longer refused before it writes; Stop, the pre-commit check and the CI ratchet judge the tree it leaves. A script on PATH inside a project, such as node_modules/.bin, is still read whole. Guarantees and limits states it.
Still refused, and listed in Shell guard friction with the corpus, the method and a labeled sample from one real session: a read-only project script that imports a file-system module (bun scripts/report.ts, python3 scripts/count.py), a script named through a variable, and a script whose text names a control command in prose. No anti-evasion rule was added.
Two gaps found by a real run against the installed agents
The end-to-end runner was run against the installed Claude Code 2.1.322, Codex 0.167.0, Cursor 2026.11.05, Grok 1.0.80 and Antigravity (agy) 1.5.3. It found two cases where a forbidden edit was written. Both are fixed, and the multi-harness notes record the run.
- Antigravity 1.5.3 edits are gated again. agy 1.5.3 renamed its edit tools, the registered matcher named only the older ones, and no pre hook ran. Stop still blocked the turn. Run
pregate setupagain after the update to register the new matcher. - A hung pinned engine no longer fails open for a project below the session's folder. With the session started in a parent folder and the edit in a nested enabled project, a pinned engine that hung let the write through.
Also in this release
- The architecture notes state the CI latency gate as it runs: the 150 ms budget belongs to the reference machine, and CI fails on a regression against each platform's baseline.
- Windows CI: every temporary directory cleanup in the suites waits out the lock Windows keeps on a just-run engine, and a test with no deadline of its own gets 20 s there.
What this release does not establish
-
No live agent session was measured. The case study has no count of edits stopped before a pull request.
-
One rule's findings were sampled. There is no false-positive rate.
-
The latency in the case study is the pre-check command run from source, not the registered hook with the compiled engine.
-
The friction measurement is a hand-assembled corpus on one macOS machine. It is not a rate for any real session, and the result depends on which tools a machine has as scripts.
The changelog lists every change. Guarantees and limits changed in one place: a script found on PATH.
v0.0.5
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.5/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.5/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
v0.0.4
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.4/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.4/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.
v0.0.3
Install on macOS or Linux:
curl -fsSL https://github.com/pedroknigge/pregate/releases/download/v0.0.3/install.sh | sh
Install on Windows PowerShell:
irm https://github.com/pedroknigge/pregate/releases/download/v0.0.3/install.ps1 | iex
Each archive and SHA256SUMS has a Sigstore bundle (.bundle) from cosign sign-blob (GitHub OIDC) and a GitHub artifact attestation. Verification steps are in docs/guides/installation.md.