# Action rule reference

Hard decisions require an explicit structured rule. Matching is case-insensitive.

## Rule forms

- `action:<tag>` matches a normalized action tag.
- `tool:<name>` matches the exact canonical Hook tool name.
- `command-prefix:<text>` matches the literal beginning of a Bash command after whitespace trimming.

Supported action tags:

- `read`
- `write` or `write_workspace`
- `delete`
- `destructive`
- `install_local`
- `network`
- `publish`
- `external` or `external_side_effect`
- `unknown`

## Precedence

Rules are evaluated in this order:

1. `authorization.forbidden`
2. `must_and_must_not.must_not`
3. `authorization.requires_user`
4. `authorization.allowed`

A forbidden or must-not match wins over an allow match. `requires_user`
denies the pending action and asks the Agent to obtain one explicit user
answer. Guard does not consume approval from chat and does not own
authorization state. After approval, Intent Loop must publish a higher
`contract_version` that moves the exact bounded rule to `allowed`; for a
TaskContractLite fallback, the user or Agent edits the reviewed fallback so its
content-derived reference changes. Retrying the unchanged contract asks again.
An allow rule never auto-approves a native Codex permission request.
`authorization.allowed` is a positive match list, not a closed allowlist.
Actions absent from it continue unless a matching `forbidden`, `must_not`, or
`requires_user` rule applies. A high-risk action still receives a semantic
reminder when an unstructured constraint is present; an allow match does not
silence that reminder.

In `shadow` mode, a pending-tool would-block or would-ask result becomes a
non-blocking reminder. A missing-evidence Stop is recorded silently and does
not continue or block the turn. Only `balanced` enforces structured action
rules and requests bounded completion verification.

## Local install classification

The classifier recognizes listed direct install, add, dependency-changing
update, upgrade, audit-fix, rebuild, sync, and execution verbs for common
package managers and environment provisioners, including:

- pip, `python -m pip`, uv, pipx, poetry, pipenv;
- npm, npx, pnpm, yarn, bun, bunx;
- cargo, go, gem, bundle, dotnet tool;
- conda, mamba, winget, choco, scoop, brew, apt, dnf, and yum;
- PowerShell `Install-Package` and `Install-Module`.

Searches such as `rg "pip install"` and normal commands such as `node --test` do not match install_local.

The parser splits unquoted shell segments and inspects the leading executable
plus the documented direct verb forms. This list is not a claim of complete
package-manager grammar. It is not a complete PowerShell, cmd.exe, or POSIX
shell interpreter. Commands hidden behind arbitrary scripts, aliases, eval,
encoded payloads, unsupported manager verbs, or unsupported wrappers may not
be recognized.

Version 0.2.2 injects objective, primary-object, delivery-surface, scope, and
must fields as bounded Agent context, but it does not derive path-aware gates
from them. Cost is not a TaskContractLite field in 0.2.2. Hard decisions use
the structured rule forms above.

## Natural-language constraints

A sentence such as "do not install locally" remains a semantic reminder. To enforce the same already-explicit boundary, use:

    "authorization": {
      "forbidden": ["action:install_local"]
    }

Do not translate ambiguous natural language into a structured rule without confirming the intended authorization boundary.
`contract validate` rejects a reserved structured prefix with an unsupported
action tag, such as `action:install-local`; use the documented underscore form.