The order checks run in
When your agent's tool call reaches the Ekamyth Agent OS hook, its checks run in a fixed order, and the strictest outcome wins. This page gives that order, and the order routing follows for a model call.
In what order does Agent OS check a tool call?
A tool call that reaches the hook is checked in this order: whether it would switch off Agent OS's own protections, then the always-refused shapes, then your policy and any approval you gave, then your rules, then the remaining checks. A refusal at any step stops the call, and nothing after it can let the call through. A hold stops the call until you decide. If nothing refuses or holds it, Agent OS gives no answer at all, so the call goes on to your agent's own permission prompt, exactly as it would without Agent OS.
The order is the same on Claude Code and Codex. For what reaches the hook in the first place, see What the hook sees.
hero inbox.Concepts used on this page
| Term | What it means |
|---|---|
| Refused | The call doesn't run, and nothing waits for you. Your agent is told what stopped it. |
| Held | The call doesn't run until you approve it in hero inbox. |
| Runs | Agent OS gives no answer, and the call goes on to your agent's normal permission flow. |
| Your policy | The tools your policy file declares, with their stakes, including entries you add with hero govern add. |
| Your rules | The rules in your rules file that hero enforce shows as ENFORCED AS CODE (hero init shows the same rules as Enforced). They block once enforcement is on. |
| Approval | Your yes to one held call, given with hero inbox approve <id> in your own terminal. |
| Posture | How Agent OS treats calls your rules don't cover, including calls your policy declares but doesn't enforce. See The default rules. |
The order for a tool call, step by step
- The hook reads the call. If the hook can't read what your agent sent, the call may be refused.
- Self-protection. A call that would switch off, loosen or remove Agent OS's own rules, hooks or settings is refused. This runs first, whatever your rules or approvals say. If the check itself fails, the call is refused. See Your agent can't switch off its own rules.
- Your rules must load. If Agent OS can't read your rules, it refuses tool calls until it can, whether or not enforcement is on. The refusal says how to fix it.
- Always-refused shapes and credential access. A call in one of the always-refused shapes, or a shell command that reads or writes a credential, is refused. Claude Code's built-in Read, Grep, Write and Edit tools are checked less closely; see Governance limits. Nothing approves it, including an approval in
hero inbox. See Always refused. - Your policy, and any approval you gave. Agent OS checks the call against your policy: whether the tool is permitted, whether it's on your policy's dangerous list, and its stakes. A call that needs approval is held, unless you already approved this exact call in
hero inbox; then it goes on, once. On the default posture, a call your policy declares but doesn't enforce goes on and is recorded, and sends, posts and deletes through connected tools are still held. - Your rules. The call is checked as code against your rules, even when step 5 let the call go on, and even when you approved it. Once enforcement is on, a call that matches one of your rules is refused. Then, on the default posture, a call that step 5 would hold, and one of your rules forbids, is refused by your rule instead, and nothing is added to
hero inbox. The refusal names your rule and adds what your policy would have done. - The remaining checks. Checks that can repair the call's input before it runs, and fact checks against facts you recorded. Then any rule Agent OS checks as code through
hero codify. Once enforcement is on, these can refuse a call or ask for your approval. They never let through a call refused above. - The default. If nothing refused or held the call, Agent OS gives no answer. Agent OS returns no explicit "allow" to your agent, so the agent's own permission checks still apply.
hero govern testreports ALLOW for an authorized call, and OBSERVED when the observe setting lets a call proceed despite the policy decision.
Which check wins when two disagree
A refusal wins over a hold, and a hold wins over running. The table shows the cases that come up most.
| Situation | Outcome | Why |
|---|---|---|
| An always-refused shape that you approved | Refused | Step 4 runs before any approval is read, and nothing approves it. |
A call you approved in hero inbox, which one of your rules forbids | Refused by your rule, once enforcement is on. | Your approval lifts the hold at step 5. Your rules still run at step 6. |
A tool you declared with hero govern add, and a rule in your rules file that forbids the call | Refused by your rule, once enforcement is on. | On the default posture, a declared entry is recorded, not enforced. Once enforcement is on, your rule refuses it. |
| A send through a connected tool, which one of your rules forbids | Once enforcement is on: refused by your rule, with no hold created. | Once enforcement is on, on the default posture, your rule's refusal replaces the hold. The refusal also says the call would have been held. |
| A send through a connected tool, with no rule against it | Held | Step 5 holds it for you. |
| A call that would switch off your rules, approved or not | Refused | Step 2 runs first. |
A call every earlier step let through, which a rule turned into code through hero codify forbids | Refused, once enforcement is on. | Step 7 can only make the outcome stricter. |
| A call nothing refuses or holds | Runs, after your agent's own permission prompt | Step 8 gives no answer. |
The order on Claude Code and Codex
| Claude Code | Codex | |
|---|---|---|
| Order of the checks | Steps 1 to 8 | Steps 1 to 8, the same |
| Where a call is decided | Before the tool runs | Before the tool runs, and again when Codex asks for permission. The same checks run both times. A call you approved in hero inbox isn't held again, unless more than about a minute passes before it runs on Codex; then approve it once more. |
| A call that would be repaired | The repaired input runs, after your agent's own permission prompt | Repaired before the tool runs. When Codex asks for permission, a call that still needs a repair is refused with hero: tool call denied (repair_required). |
| The default, when nothing refuses | No answer: Claude Code's own permission prompt applies | No answer: Codex's own approval flow applies |
| Which calls reach the hook | Shell commands, file edits and writes, MCP tool calls, web fetch and search | Shell commands. Codex doesn't send file edits or most MCP calls to the hook reliably. |
The order for a model call
Model calls don't reach the hook. They go through the model gateway, which decides which model serves each one.
- Refusals before anything is sent. If you have a data policy, it is checked first. Then the model gateway checks the model your agent asked for: a provider that isn't allowed (the allowed providers are anthropic, openai, gemini, ollama and azure unless you change
HERO_ALLOW_PROVIDERS), a model on the block list,HERO_MAX_CALLSandHERO_KILLcan each refuse the call. Nothing is sent. A budget limit refuses later, when the call is sent, after the model is chosen. See Stop or undo Agent OS. - Routing off. To disable routing optimization, start or restart the model gateway with
HERO_ROUTE=0set in its environment; policy checks still apply. See Turn routing off. - A model Agent OS doesn't know. The call keeps that model.
- Model availability. A model that isn't available is never chosen. If availability can't be read, the call keeps the model your agent asked for.
- A minimum tier you set. A valid
x-hero-min-tierheader wins over the automatic choices below. See Model gateway address. - The kind of work. The kind of work the call is, and the evidence for it, decide whether the call can move to a smaller model from the same provider. Routing never moves a call to a larger model to save money. To keep a call alive (the prompt is too big for the model, or the model is at its usage cap), it may serve a larger one; the receipt says so and no saving is counted. A call moves to another provider only in two cases you set up yourself: when you ask for the model
auto, and when you set a local model withHERO_ROUTE_LOCAL_MODEL. - The request must fit. If the chosen model can't take the request as it is, the call keeps the model your agent asked for.
- The chosen model is checked again. A refusal here ends the call before anything is sent.
- The call goes to your provider, with your own key or sign-in. If a moved call fails before its answer starts, it can be replayed once on the model your agent asked for.
If routing itself fails at any point, the call keeps the model your agent asked for. When two steps disagree, a refusal before routing wins, routing off keeps your model, and your minimum tier wins over a move. Any doubt keeps the model your agent asked for. To see what happened to each call, run hero route.
Codex: the same order. Calls made on your Codex sign-in have more reasons to keep the model your agent asked for.
What you can change in the order's outcome
| To | Do this | Step it affects |
|---|---|---|
| Add or reword one of your rules | Edit your rules file, then run hero init <file> | Step 6 |
| Turn one rule off | hero codify off <rule>, in your own terminal | Step 6 |
| Declare a tool's scope and stakes | hero govern add | Step 5 |
| Let one held call run | hero inbox approve <id>, in your own terminal | Step 5. Steps 2, 4 and 6 still apply. |
| Keep a model call at or above a tier | Send x-hero-min-tier from your own tool | Model call step 5 |
Nothing you change alters the order itself.
See the order for yourself
# What your policy would do with one tool call, without making it
hero govern test "Bash:git push origin main"
# What was refused, held and allowed, refusals and holds first
hero govern
# What's held for you
hero inbox
# What routing did with each model call
hero route
hero govern test decides the call as the hook would, without recording it or adding a hold, and without running rules turned into code through hero codify. To read each output, see hero govern, hero inbox and hero route.
Limits of the check order, and next steps
| Limit | Behaviour | What to do |
|---|---|---|
| Only calls that reach the hook | The order applies to the tool calls your agent sends to the hook. What a script does after your agent starts it isn't checked. | See What the hook sees. |
hero govern test skips a step | It doesn't run rules turned into code through hero codify, so once enforcement is on, a call it shows as running can still be refused at step 7. | No command tests a call against every step. hero govern test is a dry run of self-protection, your policy and your exact-match rules. See what each rule is doing with hero enforce. |
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.