# Docs How chock works and how to use it: plugins for your agent, or hooks in your repo. Chock turns guardrail policies into hooks your AI coding agent runs. There are two ways in. The plugin path builds one plugin for one agent from the policies you pick. The repo path wires a repository's own hooks, git hooks and CI, so every clone carries the policies. > Ask the user before running any command on this page: each one changes how their agent or repository behaves. ## Two paths - [Plugin path](https://chock.sh/docs/quickstart/plugin/index.md): The install command builds one plugin for one agent from a selection. It changes nothing in your repository. - [Repo path](https://chock.sh/docs/quickstart/repo/index.md): chock init and chock sync wire a repository's agent hooks, git hooks and CI. ### Plugin path Ask the user before running the commands below: pipx install chock Pick policies on the builder. It gives you a share code and the command for your agent. The command takes this form (ask the user before running it): chock install --selection --client --apply chock install --selection --client [Quickstart: plugin](https://chock.sh/docs/quickstart/plugin/index.md) ### Repo path Ask the user before running the commands below: pipx install chock cd /path/to/your/project chock init . chock add protect-main-branch chock sync --repo . [Quickstart: repo](https://chock.sh/docs/quickstart/repo/index.md) ## What a label means Every policy carries one label per agent. These are the engine's label words: | Label | Meaning | | --- | --- | | blocks | The agent refuses the action. | | asks | The agent stops and asks you. | | warns | The action goes ahead, with a warning. | | advisory | The agent reads the text, and nothing stops a violation. | ## Grades and what they rest on Agentseam grades what each agent can enforce before a tool runs. The evidence caps the grade: a row that rests on vendor docs never reads enforceable. Counts at the pinned agentseam release: - Best-effort: 16 agents - Enforceable: 1 agents - None: 10 agents ### Basis of each row - Live-run: 1 agents - Live-run-partial: 3 agents - Third-party-install: 1 agents - Vendor-docs: 21 agents - Vendor-source: 1 agents ## Tested and documented Tested means a person saw chock refuse an action in that agent, with that install method, and the engine's list of live tests records the date and method. Documented means the claim rests on the vendor's docs or source. The engine's list of live tests at this commit has 10 rows. From the engine docs: [docs/concepts.md](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/concepts.md) ## Policy The unit of governance. A **policy** is a self-contained folder under `.agents/policies//` that says "here is a rule, and here is how it's enforced and proven." Every policy has a `manifest.yaml` manifest; depending on its type it also carries a script, a gate, and evals. ## Gate A hook's `hook.gate` in `manifest.yaml` selects a deterministic **kind** (`content_regex`, `forbidden_ref`, `dependency_allowlist`, `test_integrity`, `script` for a check the policy's own program makes, or `egress_allowlist` at the gateway), its `params`, the events it runs on (`on: [commit|push|tool_use|tool_call]`), its `action` (`block` by default, or `ask` or `warn`), and the message shown when it fires. `tool_call` gates any tool by name. `chock compile` flattens it to `gate.json`, which the vendored `.chock/bin/gate.py` runner enforces at git-hook time. See [Gate DSL](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/spec/gate-dsl.md). ## Enforcement surface *Where* a compiled control runs. Chock models nine: `ambient-rule`, `git-hook`, `ci-gate`, `pre-tool-use`, `stop`, `agent-hooks`, `managed-setting`, `gateway`, `mcp-gateway`. Different agents support different surfaces, `gateway` is modeled but not emitted yet, and some surfaces need an explicit installer before they enforce anything — see [Enforcement Surfaces](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/enforcement-surfaces.md). From the engine docs: [docs/coverage-levels.md](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/coverage-levels.md) ## The levels For each policy × agent, the compiler records one of eight levels in `.chock/coverage.json`. The first four come from the **in-agent ladder** — agentseam's own honest, per-agent vocabulary (`agentseam.matrix.enforcement_level`, owner decision #9) for an installed, in-agent pre-execution control, plus one level of chock's own — because a hook that fails OPEN on a crash is a materially weaker promise than one that fails closed, and an adopter deciding on trust needs to see the difference. | Level | Meaning | | :--- | :--- | | **`enforced`** | An installed, hard, pre-execution in-agent control that fails CLOSED — a crashed hook still blocks. | | **`enforceable`** | Installed and blocks, and CAN be told to fail closed, but does not by default — what an adopter may claim depends on how the hook was installed. | | **`fail-to-ask`** | Installed and blocks, and when the control itself cannot decide the action does **not** proceed unattended — it is put to a human. The host may still fail open if the hook never runs at all, which is why this sits below `enforceable`. **Chock does not earn this level today**; see below. | | **`best-effort`** | Installed and blocks, but fails OPEN — a crashed hook silently allows. claude_code's PreToolUse is this tier today. | | **`enforced-at-commit`** | The policy emitted a git-hook (installed automatically) or a CI gate whose workflow `install-ci` has actually written — hard at commit time or over the PR's commit range, advisory in-agent. Chock's own commit-time mechanism, outside agentseam's per-agent-hook model. | | **`advisory`** | Only the ambient rule applies — compiled prose the agent is asked to follow. Also outside agentseam's model: an ambient rule is not a lifecycle hook of any kind. | | **`none`** | Nothing the policy emitted reaches this agent. | | **`disabled`** | The policy is listed in `policies.disabled` and produces no artifacts or hooks. | --- Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).