Skip to content
Open the dashboard
Developer docs

Action policies

DevelopersEngineering leadsSecurity9 min read

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.

apiVersion: groundrule.dev/v1alpha1
kind: ActionPolicy
metadata:
id: ACT-001
title: Never force-push
category: git
spec:
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.

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
  1. The agent is about to run a tool. Its before-tool hook runs groundrule hook <agent> --before-tool with the tool’s name and arguments.
  2. 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).
  3. Every active policy whose scope fits the repository and whose when matches the action is collected. The strictest effect wins: deny over ask over allow.
  4. An active exception for a policy in .groundrule/exceptions.yaml (standard: ACT-001, with paths applying to the file of an edit or read) lifts it, and the agent is told which exception applied.
  5. 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.
  6. 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.

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.

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.

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

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.