diff --git a/README.md b/README.md index 23b2082..aab7e00 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,29 @@ -# chock-cursor-plugins +

+ chock logo +

+ +

chock-cursor-plugins

+ +

Chock policies as Cursor plugins — guard policies ship a real beforeShellExecution deny hook.

+ +

[![Generated-only](https://github.com/open-coder-ai/chock-cursor-plugins/actions/workflows/generated-only.yml/badge.svg)](https://github.com/open-coder-ai/chock-cursor-plugins/actions/workflows/generated-only.yml) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![Contribute upstream](https://img.shields.io/badge/contribute-chock--catalog-8957e5)](https://github.com/open-coder-ai/chock-catalog) -Chock policies packaged as installable plugins for **Cursor**. Guard policies ship a real -`beforeShellExecution` hook, so a matched destructive command is **denied in the editor -before it runs** — witnessed blocking on a real Cursor install (2026-08-24), with benign -commands in the same session still allowed. +

-Animated replay: an agent runs terraform destroy and the chock guard denies it before it runs (Cursor, permission deny) +

+ Chock's demo: an agent runs a destructive command and a guard plugin denies it before it executes +

-**This repository is generated.** Every file is compiled from policy sources in -[chock-catalog](https://github.com/open-coder-ai/chock-catalog) by -[chock](https://github.com/open-coder-ai/chock). Pull requests here are closed with a -pointer to the catalog — review belongs where the source is. +An agent running in your editor can already touch your shell, your git history, and your CI +config. You want it to move fast without being the reason a stray `terraform destroy` +actually happens. Telling it to be careful in a prompt is not a guarantee; a plugin that can +refuse the command is closer to one — a matched destructive command is denied in the editor +before it runs, witnessed on a real Cursor install (2026-08-24), with benign commands in the +same session still allowed. ## Install @@ -27,50 +36,34 @@ Cursor reads this repository as a plugin marketplace via `.cursor-plugin/marketp # copy cursor// to ~/.cursor/plugins/local// and reload Cursor ``` -## What a plugin actually does — read this before installing - -- **Guard policies** ship the hook, a guard script and a stdlib-only adapter, and are - **session-enforced**: the hook returns Cursor's `permission: "deny"` response and the - command is refused. This needs `python3` and a usable `bash` on PATH; without them - Cursor allows the command silently — the hook **fails OPEN**, and every guard's - description says so verbatim. On Windows, disable the `python3` Microsoft Store alias - or install Python. -- **Advisory policies** are a skill the client reads; nothing stops a violation. - -See **[PLUGINS.md](PLUGINS.md)** for every policy, its version and its posture — generated -from the packages themselves, so it cannot drift from what is published. - -**A plugin is not the same as adopting Chock.** A plugin governs one person's session in -one editor. Repo-wide enforcement — git hooks and a CI gate a session cannot skip — comes -from installing Chock in the repository: - -```bash -pip install chock -chock init && chock sync --ci -``` +## What you get -## Layout +Guard policies ship the hook, a guard script, and a stdlib-only adapter, and are +session-enforced: the hook returns Cursor's `permission: "deny"` response and the command is +refused. This needs `python3` and a usable `bash` on PATH — without them the hook fails +**open**, and every guard's description says so verbatim. Advisory policies are a skill the +client reads; nothing stops a violation. See **[PLUGINS.md](PLUGINS.md)** for the full list: +each policy, its version, and whether it enforces or advises in this client. -``` -cursor// Cursor plugin packages (.cursor-plugin/plugin.json; - hooks/hooks.json where the policy has a guard) -.cursor-plugin/marketplace.json the index Cursor reads -``` +## Generated from chock-catalog -## Trust +Every file here is compiled from policy sources in +[chock-catalog](https://github.com/open-coder-ai/chock-catalog) by +[chock](https://github.com/open-coder-ai/chock). Pull requests against this repository are +closed automatically — open them against the catalog instead. - **Generated only:** CI regenerates from the pinned catalog and fails on any difference. -- **Byte-identical guards:** guard scripts and the hook adapter are verbatim copies of - their framework sources — a plugin cannot quietly behave differently from a repo install. -- **Best-effort, not a boundary:** guards are pattern-based filters. See +- **Byte-identical guards:** guard scripts and the hook adapter are verbatim copies of their + framework sources. +- **Best-effort, not a boundary:** guards are pattern-based filters; see [SECURITY.md](https://github.com/open-coder-ai/chock/blob/main/SECURITY.md). - **Tested upstream, and gated:** every policy ships an eval suite (`base//evals/suite.yaml`) in the catalog, and the publish workflow runs `chock check` and `chock check --only evals` before packaging anything — a policy whose evals fail cannot reach this repository. The tests live in the catalog because the policy source does; this repository is compiled output. -- **This README is the exception:** it is the one file the publisher never writes, so it - alone sits outside the generated-only guarantee. Everything else here regenerates. +- This README is the exception: the one hand-written file in this repository, so it alone + sits outside the generated-only guarantee. ### Verify it yourself @@ -95,14 +88,8 @@ checked without rebuilding the rest. **If you are listing these plugins in a marketplace,** pin both a tag and the full commit SHA. The tag names the release; the SHA is what holds the reviewed bytes still. - ## Contributing -Pull requests that change packages here are closed automatically, and not because the -change is unwelcome: every package is compiled from the catalog, so an edit here would be -overwritten at the next publish and would carry none of a policy's checks. What is welcome, -and where it goes: - | You want to | Go to | | :--- | :--- | | Fix or add a policy | [chock-catalog](https://github.com/open-coder-ai/chock-catalog/blob/main/CONTRIBUTING.md) — it reaches every client from there, including this one | @@ -110,20 +97,17 @@ and where it goes: | Report a bug in how packages are generated | [chock](https://github.com/open-coder-ai/chock/issues/new/choose), where the emitter lives | | Fix this README | here — it is the one hand-written file in the repository | -## Part of the open-coder-ai family - -Everything under [open-coder-ai](https://github.com/open-coder-ai) is built on one rule: a claim must match a -mechanism. Where this repository sits among the others: - -| Repository | What it is | -| :--- | :--- | -| [chock](https://github.com/open-coder-ai/chock) | The framework: write a policy once, enforce it on git hooks, CI, and every agent | -| [chock-catalog](https://github.com/open-coder-ai/chock-catalog) | The policies, each graded by what it actually enforces | -| [agentseam](https://github.com/open-coder-ai/agentseam) | The primitives layer under chock: one handler API over every agent's hooks, with a capability matrix that carries its provenance | -| [context-report](https://github.com/open-coder-ai/context-report) | A signed report format for whether a plugin, hook, skill or `AGENTS.md` actually works | -| [chock-threat-intel](https://github.com/open-coder-ai/chock-threat-intel) | A weekly, human-reviewed threat digest scored against the catalog | -| [chock-claude-plugins](https://github.com/open-coder-ai/chock-claude-plugins) · [copilot](https://github.com/open-coder-ai/chock-copilot-plugins) · [codex](https://github.com/open-coder-ai/chock-codex-plugins) | The same catalog compiled for the other clients; generated only, like this one | -| [chock-quickstart](https://github.com/open-coder-ai/chock-quickstart) · [chock-example](https://github.com/open-coder-ai/chock-example) | Template repositories: exactly what `chock init` leaves behind, and a working adoption with one policy per layer | +## Part of open-coder-ai + +| | | +|---|---| +| [agentseam](https://github.com/open-coder-ai/agentseam) | the primitives — one handler API and a verified capability matrix across 16 agents | +| [chock](https://github.com/open-coder-ai/chock) | the compiler — one policy into git hooks, CI gates and native pre-tool hooks | +| [chock-catalog](https://github.com/open-coder-ai/chock-catalog) | the policies — 39, each labelled enforced or advisory, with replayed evals | +| [context-report](https://github.com/open-coder-ai/context-report) | the evidence — a signed report of whether an agent artifact actually works | +| [chock-threat-intel](https://github.com/open-coder-ai/chock-threat-intel) | the threat ledger the catalog's policies answer to | +| chock-{claude,cursor,copilot,codex}-plugins | the catalog, packaged for each agent's plugin format (generated) | +| chock-quickstart · chock-example | template repos: what `chock init` leaves behind, and a full adoption | ## License