Ekamyth Agent OS docs
Standard OS / Permissions and system calls

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.

The order a tool call is checked in Eight numbered boxes from top to bottom: 1 the hook reads the call; 2 self-protection; 3 your registered rules can be read; 4 always-refused shapes and credential access; 5 your policy, and any approval you gave; 6 your rules; 7 the remaining checks; 8 no answer, so your agent's own permission prompt applies. A dashed arrow leaves steps 1 to 7 to the right, to a box reading refused, or held at step 5. Nothing later undoes a refusal. 1The hook reads the call 2Self-protection: Agent OS's own rules and hooks 3Your registered rules can be read 4Always-refused shapes and credential access 5Your policy, and any approval you gave 6Your rules, from your rules file 7The remaining checks 8No answer from Agent OS: your agent's ownpermission prompt applies, and the call is recorded Refusedor held, at step 5.Nothing later undoes it.
The numbers match the steps below. A refusal at any step ends the call; a hold waits for you in hero inbox.

Concepts used on this page

TermWhat it means
RefusedThe call doesn't run, and nothing waits for you. Your agent is told what stopped it.
HeldThe call doesn't run until you approve it in hero inbox.
RunsAgent OS gives no answer, and the call goes on to your agent's normal permission flow.
Your policyThe tools your policy file declares, with their stakes, including entries you add with hero govern add.
Your rulesThe 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.
ApprovalYour yes to one held call, given with hero inbox approve <id> in your own terminal.
PostureHow 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

  1. The hook reads the call. If the hook can't read what your agent sent, the call may be refused.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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 test reports 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.

SituationOutcomeWhy
An always-refused shape that you approvedRefusedStep 4 runs before any approval is read, and nothing approves it.
A call you approved in hero inbox, which one of your rules forbidsRefused 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 callRefused 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 forbidsOnce 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 itHeldStep 5 holds it for you.
A call that would switch off your rules, approved or notRefusedStep 2 runs first.
A call every earlier step let through, which a rule turned into code through hero codify forbidsRefused, once enforcement is on.Step 7 can only make the outcome stricter.
A call nothing refuses or holdsRuns, after your agent's own permission promptStep 8 gives no answer.

The order on Claude Code and Codex

Claude CodeCodex
Order of the checksSteps 1 to 8Steps 1 to 8, the same
Where a call is decidedBefore the tool runsBefore 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 repairedThe repaired input runs, after your agent's own permission promptRepaired 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 refusesNo answer: Claude Code's own permission prompt appliesNo answer: Codex's own approval flow applies
Which calls reach the hookShell commands, file edits and writes, MCP tool calls, web fetch and searchShell 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.

  1. 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_CALLS and HERO_KILL can 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.
  2. Routing off. To disable routing optimization, start or restart the model gateway with HERO_ROUTE=0 set in its environment; policy checks still apply. See Turn routing off.
  3. A model Agent OS doesn't know. The call keeps that model.
  4. 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.
  5. A minimum tier you set. A valid x-hero-min-tier header wins over the automatic choices below. See Model gateway address.
  6. 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 with HERO_ROUTE_LOCAL_MODEL.
  7. 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.
  8. The chosen model is checked again. A refusal here ends the call before anything is sent.
  9. 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

ToDo thisStep it affects
Add or reword one of your rulesEdit your rules file, then run hero init <file>Step 6
Turn one rule offhero codify off <rule>, in your own terminalStep 6
Declare a tool's scope and stakeshero govern addStep 5
Let one held call runhero inbox approve <id>, in your own terminalStep 5. Steps 2, 4 and 6 still apply.
Keep a model call at or above a tierSend x-hero-min-tier from your own toolModel 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

LimitBehaviourWhat to do
Only calls that reach the hookThe 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 stepIt 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.