hero enforce
Lists every rule Ekamyth Agent OS knows, where it came from, and what it's doing on Claude Code and on Codex.
What hero enforce does
It answers one question: what is my rule actually doing? For each rule it shows its source, whether it's mechanical or judgment, and its state on each agent, with the last time a hook fired it. It blocks once enforcement is on. hero enforce show gives one rule in full, ending with what to run next.
- Use it when you've added or changed rules, or want to check a rule before you rely on it.
- Use something else when you want to register a file's rules (
hero init), see recent decisions (hero govern), or turn a rule on or off (Turn one rule off or back on). - Alias: none.
- Reads or changes: reads only. It never arms or disarms a rule.
Turn one rule off or back on
Turning a rule off or on is done with hero codify, which still works alongside hero enforce. It has two verbs for this:
- Off. Turns one of your rules off, so it no longer runs at the tool call. You name the rule by its id, as
hero enforcelists it. You can add the start of the rule's content fingerprint, so the command acts only if the rule is still the one you looked at. - On. Turns that rule back on, so it's checked as code again. It blocks once enforcement is on.
hero codify off <rule>
hero codify on <rule>
Only you can do this, from your own terminal. When your agent tries it, the hooks refuse. Check the result with hero enforce show <rule>.
Inside your agent, /hero:codify is the old name for /hero:enforce.
Synopsis for hero enforce
hero enforce [status | list] [--surface claude | codex] [--status <state>] [--json]
hero enforce show <rule> [--json]
hero enforce history <rule> [--json]
hero enforce --help
Run with no subcommand, it behaves as status.
Subcommands of hero enforce
| Subcommand | What it does | Reads or changes |
|---|---|---|
status | One summary, then one row per rule. This is the default. | Reads |
list | The same view as status. | Reads |
show <rule> | Everything about one rule, ending with what to run next. | Reads |
history <rule> | One rule that's no longer current, such as a retired rule. A current rule's id is refused here; use show. | Reads |
Arguments for hero enforce
Arguments for status and list
| Argument | Type | Required | Default | What it does |
|---|---|---|---|---|
--surface <agent> | claude or codex | No | Both | Shows one agent's column only. |
--status <state> | For the CODIFY column: active, compiled, pending, failed, not-eligible, retry-scheduled, unknown. For the agent columns: code, judgment, broken, not-enforced | No | All rules | Shows only rules in that state. An agent-column value matches a rule if any agent shown is in that state: code is ENFORCED AS CODE, judgment is ENFORCED BY JUDGMENT, broken is BROKEN and not-enforced is Not enforced yet. With --surface, only that agent is checked. |
--json | Flag | No | Off | The same view as one machine-readable document, sorted by key. With --surface or --status, it adds the filter used. |
Arguments for show and history
| Argument | Type | Required | Default | What it does |
|---|---|---|---|---|
<rule> | Rule id | Yes | None | A rule id as hero enforce lists it, such as never-push-to-main. |
--json | Flag | No | Off | The rule and the summary, as JSON. |
How hero enforce gets its answer
It reads the rules registered with Agent OS, from hero setup and hero init, and the CLAUDE.md and AGENTS.md in the folder you run it from. It checks each agent's setup: whether Agent OS's hooks are wired and, on Codex, trusted by Codex. It reads the record of when a hook last fired each rule, and how many recorded decisions your rules have. For the full path, see How Governance works.
Get started with hero enforce
Before you start: Agent OS is installed and hero setup has run. With no rules registered, you'll see a line saying discovery found no rules.
See every rule.
hero enforceYou should see a summary line, a line per agent, and one row per rule. See Example output.
See one rule in full. Use an id from step 1; this example uses never-push-to-main.
hero enforce show never-push-to-mainYou should see its words, source, kind, state on each agent and last fire. See Example 1.
See only Codex.
hero enforce --surface codexYou should see the same rows with only the Codex column.
Nothing here changes your work, so there's nothing to undo.
Example output of hero enforce
Output from version 0.1.36rc13. Trimmed where you see …
On a wide terminal, the table adds SOURCE, CLASS and LAST FIRE columns.
How to read hero enforce output
| Line | What it means | What to do |
|---|---|---|
| 1. Header | The folder it read rules from, and where Agent OS keeps registered rules. | Run it from the project you care about. |
| 2. Summary | How many rules there are, by state: ENFORCED AS CODE, ENFORCED BY JUDGMENT, Not enforced yet and BROKEN. A rule shown as ENFORCED AS CODE is checked as code at the tool call; it blocks once enforcement is on, which hero setup turns on. For a judgment rule, Not enforced yet means no code check, which is how judgment rules work; memory puts it in your agent's context. hero init prints different labels for now: Enforced and Broken — no seam. | Check any rule that isn't ENFORCED AS CODE with hero enforce show. |
| 3. Class | How many rules are mechanical (decidable as code), judgment (needs a model's judgment) or hybrid (a mix). | The class describes the rule type; read the Claude Code and Codex columns for its state on each agent. |
| 4. Codify | Whether each rule has been compiled into generated code. A rule in one of the shapes Agent OS can check as code is checked as code at the hook while this reads pending. It blocks once enforcement is on. | Read the agent columns for what a rule is doing, not this line. |
| 5. Claude Code, Codex | Whether Agent OS's hooks are wired in each agent, and on Codex trusted by Codex, with that agent's counts. not protected yet means the hooks aren't wired. | If an agent reads not protected yet, run hero setup, as the line says. |
| 6. Receipts | How many recorded decisions your rules have, counted the same way as hero attest rules. | See hero attest rules for each rule's receipts. |
| 7. Guidance note | Judgment rules aren't checked as code, by design. Agent OS's memory puts the ones that apply in your agent's context, as guidance. The note and the Not enforced yet and Not enforced labels mean there's no code check at the tool call for those rules. | To have a rule checked as code, reword it into one of the shapes Agent OS can check as code. |
| 8. Rule table | One row per rule: its id, its codify state, and its state on Claude Code and on Codex. | Use the id with hero enforce show. |
| 9. Rule detail | The rule's source file, its kind, and the last time a hook fired it. never seen by a hook means no tool call has hit it yet. | It updates when one of your agent's tool calls hits the rule. |
| 10. Per-rule notes | Internal notes the view prints under each rule, such as fixed-source snapshot; first proof receipt pending. | Ignore them. See Limits. |
| 11. Unknown until, warnings | Facts the view couldn't read on this build. The text view shows the first few warnings, shortened, and says how many more there are. | For every warning in full, run hero enforce --json. |
| 12. Next | Other ways to look at the same rules. | Pick one. |
With no rules registered and no CLAUDE.md or AGENTS.md in the folder, the summary reads rules UNKNOWN — discovery produced zero rules — refusing to report an empty corpus as truth. It isn't an all-clear. Run it from your project, or register rules with hero init.
More hero enforce examples
Example 1. To see one rule in full
hero enforce show never-push-to-main
Example output. The format is the command's; the numbers are examples.
enforce — never-push-to-main
text Never push to main.
source CLAUDE.md (provenance: claude.md:root, agents.md:root)
class mechanical (codify mode: code)
codify pending — mechanical rule; no compile attempt recorded
evidence: no road receipt for this rule
Claude Code ENFORCED AS CODE — first_proof_receipt_pending
fixed-source snapshot; first proof receipt pending
Codex ENFORCED AS CODE — first_proof_receipt_pending
fixed-source snapshot; first proof receipt pending
last fire deny on Codex (literal code binder) at 2026-11-04 07:14 (user-rule
receipts) — recorded decision: denied_literal
receipts 3 enforcement(s) · attest #2 · attest #21 · attest #41 (same
reader as `hero attest rules`)
next hero codify promote never-push-to-main --by example-user
Read the Claude Code and Codex lines for what the rule is doing on each agent, and last fire for its most recent recorded decision. On a customer install, the next step, hero codify promote, ends in a refusal. You don't need it: the Claude Code and Codex lines already show what the rule is doing.
Example 2. To see one agent
hero enforce --surface claude
The same view with only the Claude Code column.
Example 3. To list only rules in one state
hero enforce --status pending
The table heading says showing <n> of <total> (--status pending).
Example 4. To use the view in a script
hero enforce --json
Each rule carries its state on each agent under modes, for example "modes": {"claude": {"mode": "ENFORCED AS CODE", …}, "codex": {"mode": "ENFORCED AS CODE", …}}. Each rule also has rule_id, text, source, class, state, codify, last_fire (null when no hook has fired it), receipts and next. With no rules found, every count is null. show <rule> --json prints {"schema": …, "rule": …, "summary": …}.
Exit codes and errors for hero enforce
| Code | Meaning | What to do |
|---|---|---|
0 | The view was printed, including the rules UNKNOWN state and any warnings. It doesn't mean every rule is enforced. | Read it. |
1 | A registered rule contradicts its own record, so the view can't be printed truthfully. | Email support at the address in your welcome email. |
2 | Refused: unknown flag, value or subcommand, or a missing or unknown rule id. | Check the synopsis and the errors below. |
3 | The rules couldn't be read in time. It prints Couldn't read your rules in time because this machine is busy. Nothing changed. Run it again. | Run it again. |
A refusal prints four lines, refused, reason, governing_rule and remedy, or one JSON object with --json:
refused enforce has no verb 'on' — hero enforce only shows rules; it never arms or disarms
reason unknown_verb
governing_rule arming is its own door: hero codify enforce on|off
remedy hero codify enforce on
| Error | Cause | Fix |
|---|---|---|
enforce has no flag '<flag>' | A flag other than --json, --surface or --status. | Use one of those. |
enforce --surface has no value '<value>', or the same for --status | A value not in the list. | Use a value from the arguments. |
enforce --surface needs a value, or the same for --status | The flag was given with no value. | Add a value. |
enforce show needs exactly one rule id | show or history was given no id, or more than one. | Give one id. |
no rule '<id>' in the registry view | No rule has that id. For history, a current rule's id gives this too. | Copy an id from hero enforce. For a current rule, use show. |
enforce has no verb 'off' — hero enforce only shows rules; it never arms or disarms | on or off was used. | Use hero codify enforce on or off, from your own terminal. |
registry load failed: <reason>, as a warning | Agent OS's registered rules can't be read. The view still prints, and exits 0. | Email support at the address in your welcome email. |
rule registry is incoherent — cannot render honestly: <reason> | See exit code 1. | Email support at the address in your welcome email. |
Files and environment for hero enforce
| Name | Kind | Purpose |
|---|---|---|
CLAUDE.md, AGENTS.md | Files, read, in the folder you run it from | Your rules files. Their rules are listed with the registered ones. |
HERO_HOME | Environment variable | Root of Agent OS's files. Default ~/.hero. |
Limits of hero enforce
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Codify line and per-rule notes | Can read pending or first proof receipt pending for a rule that is already checked as code at the hook. | No | Read the agent columns. |
| Internal notes in the output | Some lines print internal notes, such as an internal reference number and history storage migration pending. | No | Ignore them. |
| Source of a rule in two files | The source column can name a different file from the one named when the rule fires. | No | No action is required for attribution alone when the count and credited rule agree. |
ENFORCED BY JUDGMENT | No rule reaches this state on a customer install. | No | Nothing to do. Judgment rules aren't checked as code; memory puts the ones that apply in your agent's context. |
The --status list in --help | Names values that are refused: armed, shadow, llm, native, off. | No | Use the values under Arguments. |
| On Codex | Running hero enforce makes the Codex app contact github.com. | No | See Privacy limits. |
| Rules listed but not enforced | A rule found only by hero setup, or one in a user-level file (~/.claude/CLAUDE.md or ~/.codex/AGENTS.md), is listed but not enforced on this release. | No | Put the rule in the project's CLAUDE.md or AGENTS.md and run hero init on it. |
| A folder rule ending in a period | For - Never change files under docs/legal., the view shows ENFORCED AS CODE, but the period is read as part of the folder name and the rule blocks nothing. | No | Write the rule with no period after the folder name, then run hero init on the file. |
| BROKEN on an agent whose hooks aren't approved | A rule can read BROKEN for an agent whose Agent OS hooks aren't approved yet, even after it blocked a call on the other agent. | No | Approve the hooks in that agent, or run hero setup. |
| "Not armed" at session start | At session start your agent can be told a rule is not armed while it is blocking calls. The rule is still enforced. | No | Trust hero enforce; it shows the rule's real state. |
| Monitor | Monitor's rule coverage and its Enforce table can show 0 for rules that hero enforce lists, or that have already stopped calls. | No | Trust hero enforce and hero govern status. |
| Where it looks for rules | The folder you run it from, plus registered rules. Run from elsewhere, a project's rules can read differently. | No | Run it from your project. |
Commands related to hero enforce
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.