Action policies
A standard says what the code must be. An action policy says what the agent may do: which shell commands, file edits, reads, web fetches and MCP tool calls it may run on its own, which a person confirms first, and which are refused. It is decided before the action, in the agent’s own permission hook, on the developer’s computer, in milliseconds. Policies live next to your standards, with the same identity, scope, owner, exceptions and rollout stages. CLI 0.24.0 and later.
A policy
Section titled “A policy”apiVersion: groundrule.dev/v1alpha1kind: ActionPolicymetadata: id: ACT-001 title: Never force-push category: gitspec: severity: blocker effect: deny intent: A force-push rewrites history other people have; a person decides when that is worth it. requirement: Do not force-push. Ask the developer to do it, or push to a new branch. when: actions: [shell] commands: - "git push --force*" - "git push -f*" agent: summary: Never force-push; ask the developer, or push to a new branch.Put it in .groundrule/standards/ next to your standards (the standards globs in the configuration load both kinds), in a pack, or write it in the dashboard with Rules → New action policy. Four fields are required: metadata.id, metadata.title, spec.severity, spec.requirement, and spec.when with at least one field.
Fields
Section titled “Fields”The envelope is the one standards have, so a policy is rolled out, owned and excepted the same way. The body is different: an effect and what it matches, instead of checks.
| Field | Required | Values | Meaning |
|---|---|---|---|
metadata.id |
yes | ACT-001 style |
Same identifier space as standards, so exceptions and adoptions name both the same way. |
metadata.title, status, version, owner, category, labels |
title | As for standards | |
spec.severity |
yes | blocker, warning, advisory, info |
How much a breach matters, for evidence and agent files. It does not change the decision. |
spec.effect |
no | allow, ask, deny |
What the hook answers when the policy matches. Default ask. |
spec.when |
yes | see below | What the policy matches. At least one field. |
spec.scope |
no | As for standards | repositories and tags narrow where the policy applies; paths and exclude apply to the file of an edit or read, never to commands. |
spec.requirement |
yes | text | What the agent must or must not do, and what to do instead. The agent reads it as the reason. |
spec.intent |
no | text | Why the policy exists. |
spec.agent |
no | instruction, summary |
Whether and how it is listed in agent files, under What you may not do alone. |
spec.exceptions, references, compliance, rollout |
no | As for standards |
Every listed field narrows the match; within a field, any pattern matches.
| Field | Matched against | For |
|---|---|---|
actions |
the kind of operation: shell, edit, read, fetch, mcp, other |
every kind |
commands |
each segment of a shell command, split on &&, ||, ;, | and newlines and trimmed, so git status && git push -f is caught. A pattern that itself contains a pipe or a chain, such as curl *|*sh, is matched against the whole command line. * matches anything, spaces and slashes included; ? matches one character. Case-sensitive. |
shell |
paths |
the repository-relative path of the file, as a glob (dot files included); outside the repository, the absolute path | edit, read |
hosts |
the host of the URL, as a glob, for example *.internal |
fetch |
servers |
the MCP server’s name, as a glob | mcp |
tools |
the tool name as the agent reports it (Bash, Edit, mcp__github__create_issue, apply_patch…) and, for MCP, the tool’s own name |
every kind |
How a decision is made
Section titled “How a decision is made”- The agent is about to run a tool. Its before-tool hook runs
groundrule hook <agent> --before-toolwith the tool’s name and arguments. - The CLI loads the policies in effect: the repository’s own, its packs, or the workspace rulebook in a connected repository (a copy fetched in the last ten minutes is reused, so a tool call never waits on the network twice).
- Every active policy whose
scopefits the repository and whosewhenmatches the action is collected. The strictest effect wins: deny over ask over allow. - An active exception for a policy in
.groundrule/exceptions.yaml(standard: ACT-001, withpathsapplying to the file of an edit or read) lifts it, and the agent is told which exception applied. - From the workspace, the policy’s stage applies: Observe and Teach take no decision (Teach still reaches agent files), Advise gives the agent the reason as context and takes no decision, Enforce decides. A local policy decides.
- The agent gets the decision and the reason: the policies by ID and title, what they require, and how to proceed.
Groundrule: this action is not allowed here. Do it another way, or ask the developer.- ACT-001 Never force-push (blocker): Never force-push; ask the developer, or push to a new branch.If the policy is wrong for this repository, say so; a time-boxed exception is written by the team in .groundrule/exceptions.yaml. Never work around it.When nothing matches, the hook answers nothing and the agent’s own permission flow applies. When anything goes wrong (no configuration, an unreadable file, bad input), the hook also answers nothing: a wrong deny would stop a developer mid-task, so the default is ask, the matching is literal, and silence is the failure mode. The evaluation takes well under 50 ms once Node has started. The hook command pins the exact CLI version, which groundrule hooks fetches into npx’s cache when it installs, so a tool call waits about a second, not for a download; the agent gives the hook 30 seconds in case the cache is cold on a slow connection, because a hook that times out lets the call through. For Claude Code and Codex the hook is attached only to the tools a policy can decide (shell, edits, reads, web fetches and MCP calls), so search and navigation tools are never slowed; a policy that names another tool in when.tools needs that matcher widened by hand in the settings file.
What each agent supports
Section titled “What each agent supports”groundrule hooks installs the before-tool hook next to the stop hook (Check when the agent finishes). Not every agent can ask, and not every agent reports every kind of tool.
| Action | Claude Code | Codex | Cursor | Copilot CLI | Copilot cloud agent |
|---|---|---|---|---|---|
| shell | allow, ask, deny | allow, deny (ask is delivered as deny) | allow, ask, deny | allow, ask, deny | allow, deny (ask is treated as deny) |
| edit | allow, ask, deny | where the tool is apply_patch, Edit or Write |
not supported: Cursor has no decision before an edit | allow, ask, deny | allow, deny |
| read | allow, ask, deny | advisory | allow, deny (ask is delivered as deny) | allow, ask, deny | allow, deny |
| fetch | allow, ask, deny | advisory | advisory | allow, ask, deny | allow, deny |
| mcp | allow, ask, deny | advisory | allow, ask, deny | allow, ask, deny | allow, deny |
Ask is delivered as deny where an agent cannot ask: an author who chose ask wanted a person in the loop, so the hook refuses with a reason that says the developer should run it, rather than silently letting it run. Advisory means the hook runs and the reason is written to the agent’s hook log, but the agent reports the tool in a shape the hook cannot decide on. npx @groundrule/cli doctor prints how many policies apply and which agents have the hook.
In agent files
Section titled “In agent files”Policies with agent.instruction: true (the default) are rendered into AGENTS.md, CLAUDE.md, Cursor rules and Copilot instructions in a section What you may not do alone, one line each with never, ask first or allowed. An agent without the hook still knows; an agent with it can plan around them. groundrule check ignores policies: they have no check and never produce findings.
The bundled pack
Section titled “The bundled pack”groundrule:packs/agent-actions ships ten policies to start from. Add it to extends in .groundrule/config.yaml, or turn it on under Packs in the dashboard.
| ID | Title | Effect | Matches |
|---|---|---|---|
ACT-001 |
Never force-push | deny | git push --force, -f |
ACT-002 |
Ask before rewriting or discarding git history | ask | git reset --hard, rebase, clean -f, checkout --, restore, branch -D |
ACT-003 |
Never bypass hooks or checks | deny | --no-verify, core.hooksPath, commit.gpgsign false |
ACT-004 |
Never pipe a download into a shell | deny | curl …| sh, wget …| bash and the like |
ACT-005 |
Ask before publishing a package or a release | ask | npm/pnpm/yarn/cargo/twine/poetry/gem/mvn/gradle publish, docker push, gh release create |
ACT-006 |
Ask before changing infrastructure | ask | terraform/tofu/pulumi apply or destroy, kubectl apply/delete/rollout/scale, helm install/upgrade/uninstall, cloud deletes |
ACT-007 |
Ask before using elevated privileges | ask | sudo, doas, su |
ACT-008 |
Never delete outside the repository | deny | rm -rf of the root, the home directory, a parent directory or system paths |
ACT-009 |
Never read or edit secret files | deny | .env files (except .env.example), private keys, keystores, .netrc, .npmrc, credential files |
ACT-010 |
Ask before editing CI workflows and pipeline files | ask | .github/workflows/**, .gitlab-ci.yml, .circleci/**, Jenkinsfile, and others |
What the workspace learns
Section titled “What the workspace learns”In a repository with platform: in its config, when the computer is signed in, an ask or deny sends one small report to the workspace after the agent has its answer, with a two-second timeout and every failure ignored, as the check reports do.
| In the report | Never in the report |
|---|---|
| The repository’s name, the agent, a SHA-256 hash of its session id | The command, the file path, the URL, the tool’s arguments |
The kind of action (shell, edit, read, fetch, mcp, other) and the decision (ask or deny) |
The agent’s prompt or output, what you typed |
| The IDs and effects of the policies that matched | Your name or email (the token says who uploaded, as for scans) |
The Dashboard’s Where violations are stopped panel shows them as stopped before the action: refused and asked counts, and the policies behind them. reports: none under platform: turns these reports off together with the check reports. Allowed actions, and actions no policy matched, are never reported.
Related
Section titled “Related”- Check when the agent finishes: installing the hooks
- The rule format: the shared envelope
- Overrides and exceptions: lifting a policy for a path, for a time
- Rollout stages
- RFC 0017 in the open-source repository: the design and the alternatives considered