hero inbox
Lists the actions Ekamyth Agent OS is holding for your decision, and approves or denies them.
What hero inbox does
It answers one question: what is my agent waiting on me for? Each held action shows what was asked for, why it was held, which agent asked, and when it's denied if you do nothing. You approve or deny each one by its id.
- Use it when your agent says an action is waiting for your approval, or
hero governshows⚠ needs approval. - Use something else when a call was refused by one of your rules or by the always-refused list. A refusal cannot be approved in
hero inbox; the default hook does not queue secret-read or catastrophic-shape refusals, and any such rows already in the inbox remain unapprovable. Seehero govern. - Alias:
--details <id>is the same asshow <id>. - Reads or changes: the list and
showdecide nothing; opening the inbox records any hold that has expired.approveanddenydecide a hold, and only from your own terminal.
Synopsis for hero inbox
hero inbox
hero inbox show <id> [--json]
hero inbox --details <id> [--json]
hero inbox approve <id>
hero inbox deny <id>
hero inbox help | --help | -h
hero help inbox
Subcommands of hero inbox
| Subcommand | What it does | Reads or changes |
|---|---|---|
| (none) | Lists pending holds, the most serious first. | Reads |
show <id> | One hold in full, pending or already decided, including every line of a multi-line target, so you can read it before you decide. --details <id> is the same. Only the first id counts. | Reads |
approve <id> | Approves a hold. Your agent can then make that exact call once, within 15 minutes. | Changes |
deny <id> | Denies a hold. | Changes |
help | This command's help. Same as --help. | Reads |
Arguments for hero inbox
| Argument | Type | Required | Default | What it does |
|---|---|---|---|---|
<id> | Hold id, such as ap-0 | Yes, for show, approve and deny | None | The hold to act on. The id comes from hero inbox, and your agent is told it when the call is held. |
--json | Flag | No | Off | With show: the hold as one line of JSON. On any refusal: the refusal as JSON. The list refuses it. With approve and deny, success and failure messages stay text. |
How holds reach hero inbox
When your agent tries to send, post or delete through a connected tool, such as sending an email or posting to Slack, Agent OS stops the call at the hook and holds it. The agent gets a refusal with the hold's id and the command for you to run. A search through the same tool isn't held.
You approve or deny in your own terminal. Typing the verb and the exact id is the confirmation; nothing else asks. A governed agent can't approve its own hold, and neither can a script with no terminal. After you approve, the agent can make that exact call once, within 15 minutes: the same tool, target and input. After that, or after 15 minutes, a new request has to be held and approved again. A hold you don't decide expires after 24 hours and is never approved. Every decision and expiry is recorded. For the full path, see How Governance decides.
Some holds can't be approved at all, even from your own terminal: tools on the policy's dangerous list, and on the default posture, secret reads and always-refused shapes.
hero inbox does.Get started with hero inbox
Before you start: Agent OS is installed and hero setup has run. With nothing held, you'll see no pending approvals.
See what's held.
hero inboxYou should see each pending hold, or
no pending approvals. See Example output.Read one hold in full. Use an id from step 1.
hero inbox show ap-0You should see its reason, the agent that asked, when it auto-denies, and its full target. See Example 1.
Decide it, in your own terminal.
approvewill:- Let your agent make that exact call once, within 15 minutes. It can't be taken back.
denywill:- Refuse the held call.
hero inbox approve ap-0The format from the product's code is in Example 2.
Check it's gone.
hero inboxThe hold is no longer listed.
Example output of hero inbox
Nothing held
Output from version 0.1.36rc13. Trimmed where you see …
no pending approvals — held high-stakes actions appear here (stale = auto-deny)
Four holds
Output from version 0.1.36rc13. Trimmed where you see …
On your terminal, a hold's top two lines wrap at word boundaries to fit the screen, from 80 to 120 columns, and continue four spaces further in. The hold id and requested by are never split across lines. The line that says what approving releases is printed whole.
How to read hero inbox output
| Line | What it means | What to do |
|---|---|---|
| 1. Pending approvals | How many holds are waiting. | Decide each one. |
| 2. Hold | Its stakes, its id, the tool, and the target. Values such as an email address show masked, with a fingerprint. Then the reason it was held and a recommendation. | To read the target in full, run hero inbox show <id>. |
| 2. "authenticated autonomy grant required" | The reason printed for a hold. No command issues such a grant. | Decide with approve or deny. |
| 3. Timing and source | How long ago it was held, how long until it's denied by default, the policy that held it, and which agent asked: hook:claude for Claude Code, hook:codex for Codex. | Decide before it auto-denies, or let it. |
| 4. What approving releases | In plain words, what your agent does if you approve. | Read it before you approve. |
| 5. Decide | The commands to decide, and to see a hold in full. | Run them in your own terminal. |
More hero inbox examples
Example 1. To read a hold in full
hero inbox show ap-0
Example output. The format is the command's; the numbers are examples.
ap-0 pending · CRITICAL · mcp__gmail__send_email
shape none of the catastrophic shapes (held by the reason below)
reason critical-stakes, authenticated autonomy grant required
rule builder@v0 · requested by hook:claude
recommend deny
held 5m ago · auto-deny in 23h
target 1 line, in full (control characters shown as escapes):
1 <email> sha256:da458b4e563956ba9c7c184ff6987f49ec835b2c7a211f59465f34c94133f2c8
decide:
hero inbox approve ap-0
hero inbox deny ap-0
shape says whether the target matched one of the always-refused shapes. target prints every line, with control characters shown as escapes, so nothing is hidden in it.
For a hold that's already decided, held ends with · decided by <who>, and the footer says already <status> — nothing to decide, consent used — submit a new request for approval or consent expired — submit a new request for approval.
Example 2. To approve a hold
This command will:
- Let your agent make that exact call once, within 15 minutes. It can't be taken back.
hero inbox approve ap-0
Example output. The format is the command's; the numbers are examples.
approved ap-0: Claude wants to send an email (mcp__gmail__send_email) to <email> sha256:df8b4d77df5ba75fb495bfa8b5deceba58379b48a0d3b2f974ef9342804a8cea (held: critical-stakes, authenticated autonomy grant required)
approved: mcp__gmail__send_email → <email> sha256:df8b4d77df5ba75fb495bfa8b5deceba58379b48a0d3b2f974ef9342804a8cea (held → decided, recorded)
The first line says what you released. The second confirms the decision was recorded. If it also says evidence unavailable — decision saved, attestation failed, the decision still stands.
Example 3. To deny a hold
hero inbox deny ap-1
The output has the same two-line form, ending (held → decided, recorded).
Example 4. What your agent sees when a call is held
Example output. The format is the command's; the numbers are examples. This is the refusal the hook returns to Claude Code.
refused govern needs-approval: critical-stakes, authenticated autonomy grant required
reason unauthorized
governing_rule builder@v0
remedy hero inbox approve ap-0 — ask the human to run this in their own terminal (a governed agent cannot)
approving ap-0: Claude wants to send an email (mcp__gmail__send_email) to nobody@example.invalid sha256:df8b4d77df5ba75fb495bfa8b5deceba58379b48a0d3b2f974ef9342804a8cea (held: critical-stakes, authenticated autonomy grant required)
Example 5. To read a hold in a script
hero inbox show ap-0 --json
It prints one line of JSON with keys sorted, including id, status, stakes, action_type, target, reason, recommendation, requested_by, held_seconds, auto_deny_in_seconds, decided_by and decide, which holds the approve and deny commands.
Exit codes and errors for hero inbox
| Code | Meaning | What to do |
|---|---|---|
0 | The list or the hold was printed, or the decision was made and recorded. | Nothing. |
1 | A decision didn't happen, for example because no hold with that id is pending. | Run hero inbox for current ids. |
2 | Refused: an unknown flag or subcommand, a missing id, an unknown id for show, or a decision attempted from inside an agent session or with no terminal. | See the errors below. |
3 | The inbox couldn't be read or saved. A damaged inbox is never shown as an empty one. | Email support at the address in your welcome email, with the output you saw. |
130 | Stopped with Ctrl-C. | Run it again. |
| Error | Cause | Fix |
|---|---|---|
{"refused": true, "reason": "unknown_flag", "governing_rule": "hero inbox declares verbs: approve, deny, show, help", "remedy": "hero inbox --help"} | hero inbox --json. The list has no JSON form. | Use hero inbox show <id> --json for one hold. |
inbox approve needs the id of the held action, or the same for deny and show | No id was given. | Copy an id from hero inbox. |
no held action with id <id> | show was given an id that doesn't exist. | Copy an id from hero inbox. |
no pending item <id> | approve or deny was given an id that isn't pending, for example because it was already decided or auto-denied. | Run hero inbox. |
inbox has no flag '<flag>' | An unknown flag. | Check the synopsis. |
inbox has no verb '<word>' | An unknown subcommand. | Check the synopsis. |
'<tool>' is hard-block / dangerous — cannot be overridden | The tool is on your policy's dangerous list. Exit 1. | Run the action yourself, if you want it. |
secret reads and catastrophic shapes are not allowable [not-allowable] | The hold is a secret read or an always-refused shape. Exit 1. | Run the action yourself, if you want it. |
<id> does not match the current record — approval refused, nothing was released; run `hero inbox` and decide the current row | The hold changed after you listed it. Exit 1. | Run hero inbox and decide the current row. |
hero inbox failed at runtime (<reason>) | See exit code 3. | Email support at the address in your welcome email, with the output you saw. |
refused `hero inbox approve <id>` lets a held action run, and approving is human-only, and it was launched from inside a Claude Code session, not from your terminal. A governed agent cannot approve its own held action | The command ran inside an agent session. | Run it yourself in your own terminal. |
Files and environment for hero inbox
None you need to set.
Limits of hero inbox
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| What's held on the default posture | Sends, posts and deletes through connected tools. A git push, curl POST, scp, gh pr create, npm publish or web fetch with a query string isn't held: it runs and is recorded. | No | To stop a specific action now, use your agent's own permission settings (Claude Code permissions, Codex approval mode). Destructive actions on the always-refused list are refused regardless. |
| How a hold reaches your agent | The call is refused with the hold's id, not paused. After you approve, the agent has to make the same call again within 15 minutes. | No | Tell your agent to try again after you approve. |
| Auto-deny | 24 hours after the hold. The hold expires and is never approved. | No option changes it. | Decide before then. |
--json on the list | Refused, exit 2. | No | Use show <id> --json. |
| The Portal | Approving is in the terminal. | No | Use hero inbox approve or deny. |
| Harmless commands held | Simple read-only commands, such as ls and pwd, can be held. So can a harmless command that only mentions a dangerous one, such as a search for the text rm -rf. | No | Approve it here, or rephrase the command. |
| Monitor's count | Monitor's pending-approvals count can differ from hero inbox. | No | Trust hero inbox. |
| Scripts | approve and deny are refused with no terminal. | No | Decide holds yourself, in a terminal. |
Commands related to hero inbox
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.