Guides›When a request needs approval

When a request needs approval#

What does an agent do with exit 3?

The vault needs a person to approve this exact request: a Gmail send, a GitHub delete, a production run, any use of a protected credential. You get exit 3 (approval_required), the ask block, an approval id, a link, a binding code (6 characters from an alphabet with no 0, O, 1, I, L or U) and expiresAt.

1. Tell the human, in one message, what you are trying to do, then the block. For example:

   I want to send the reply to Sam from gmail-personal.
   Needs you in the vault: approve a request
   Open: https://app.mehen.dev/w/acme/a/apr_7Hq2
   Tick the binding code K7Q2MX, then read the whole request before you approve.
   Valid until 17:12 (58 minutes). I will wait.

   Who decides is fixed by the workspace, not by you: your own machine's request goes to your owner; a guest's or a team's machine asking for a shared credential is decided by a manager of the project or an owner or admin; a protected environment with four-eyes needs a manager of every project that requires it, other than your owner. When next.say names who to send the link to, relay that. Approvals has the whole rule.

2. Do not claim the request is safe, and do not paste the email body as if it were the approval. The approval page leads with a decision card (who asked, what it is, the countdown and the code tick) and shows the request beneath it. The human decides there, with their passkey.

3. Wait: mehen wait apr_... (or vault_wait) long-polls until the human decides.

4. If approved, repeat exactly the same request from the same machine: the same item, method, URL, Content-Type, Content-Encoding, forwarded headers and body bytes. The vault finds the grant by the request itself, so any change is a different request and asks for a new approval. You may add --approval apr_... (or approval in vault_fetch), as mehen wait suggests. For mehen run, repeat it from the same worktree at the same commit with the same command line and variables.

5. A grant is for what was asked. A relayed request asks for one use within ten minutes, and a protected run for one use within an hour; the human may shorten the window or reduce the uses, never increase them. An undecided approval expires after an hour.

6. If denied (denied, exit 5) or expired, stop and ask the human what they want instead. Do not retry in a loop.

Keep it readable#

Because the human decides on what the page shows, keep bodies that need approval small and readable: plain JSON or form fields, uncompressed, no padding, no large attachments. The vault refuses to ask for approval of a compressed body, a body over 64 KiB or more than 16 KiB of forwarded headers (mode_refused). A body that is not UTF-8 text is shown only as a byte count, so the human cannot inspect it. mehen check tells you beforehand whether a request will need approval.

Production runs#

A protected environment such as prod only runs when you type --env prod literally, the machine is allowed protected environments, its owner holds the protected right on the project, and a human approves the run. The approval page shows the project, environment, command arguments, variable names and which variables receive real values or placeholders. The request digest also binds the submitted remote, worktree and commit, but this page does not display those fields. Check the CLI's resolved context before requesting approval. The approval covers the whole command line: the same command with other arguments needs a new approval. A command line over 4096 characters, or with one argument over 1024, cannot be approved (mode_refused); put it in a script and run that.