Skip to content

v0.0.11

Choose a tag to compare

@github-actions github-actions released this 16 Nov 12:59
· 11 commits to main since this release
8fa32fc

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 view and pnpm view.
  • Package installs, such as pnpm install, npm ci, bun install, and yarn.
  • git init.
  • docker and docker compose.
  • Build, test, and dev runners, such as next build, tsc, vitest run, pnpm test, pnpm dev, and npm 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

.env and .env.* are listed in .gitignore.

The test Git sandbox keeps its identity in the sandbox home. It no longer exports GIT_CONFIG_GLOBAL, so a test that sets its own HOME does not inherit an identity that commits the contract. The upgrade and rollback test records how long the restored engine took. The expected verdict is unchanged.

The macOS native job runs on the fixed macos-26 image. The check name stays native (macos-15, darwin-arm64).

What this release does not establish

  • No rule was disabled, downgraded, or removed. The eleven heuristics start at warn. A reviewed promotion can still raise one. Timeouts, thresholds, and the committed latency baselines are unchanged. The macOS latency gate still fails by runner noise at times.
  • A directory that was never enabled is not checked. Stop, the pre-commit check, and the CI ratchet still judge a tree that an unchecked command leaves behind, once the project is enabled and those checks run.
  • pregate disable is not a guarantee against another process of the same user. It is a recorded choice. The hook honors it and prints one line.
  • A literal in-harness pregate approve can be typed by an agent. The approval log says so. Claude Code and agy ask first only in an interactive parent session.
  • The closed node -e grammar is a list. A write through a name the list does not hold stays unseen here.
  • 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.