Your agent finishes a handoff note and asks, “Approve export?” You still need to know which version it will save, where the file will go, and whether anything else happens afterward.
Give the reviewer a short request card backed by the exact stored proposal. Show the action, destination, full content, checks, and deadline. Record the person’s decision separately, then verify the result after execution.
Download the approval request card and field reference. It is an editable review worksheet, not an approval service. Use the MCP starter when you need working checks, stored decisions, and file export.
Start with the decision you need
Write a sentence that names the effect. For the starter’s local file operation, use:
Approve saving this exact handoff note as a new Markdown file in the owner’s configured export directory. This action does not send the note or publish it.
Then show the proposal ID, generated filename, full note, and deadline from the service. A title or summary helps someone find the request. It cannot replace the content they are approving.
The MCP tools specification recommends confirmation prompts and the ability to deny invocations, while leaving the interface design to applications. The card below is our design for that interface. It is not an MCP-defined approval object.
Fill the request card from the stored proposal
Copy this card into your review interface or an internal review note. Replace every bracketed value before asking for a decision.
Action: Save one reviewed Markdown document.
Proposal: [service-issued proposal ID]
Destination: [owner's configured directory]/approved/[proposal ID].md
Content: [full stored document, or a protected read-only view of it]
Review digest: [digest returned by the service]
Expires: [service-issued timestamp, including time zone]
Checks: [rule version and individual results]
Open questions: [specific uncertainties, or "none identified"]
Decision requested: Approve or reject this version for local export.
After export: Read the file and compare it with the stored content.
Current state: Pending. No approval or export is claimed.
Read the proposal through the trusted reviewer interface before deciding. In the starter, review.mjs show displays the stored Markdown, digest, deadline, checks, and event history. The destination directory comes from the owner’s service configuration. The filename comes from the proposal ID.
Keep sensitive documents in an access-controlled review location. Do not paste tokens, private customer data, or unrestricted document links into a public issue to make the card convenient.
For another operation, replace the file-specific fields with its actual effect. An email request needs the recipients and final message. A deployment request needs the target environment and exact release. These are suggestions for new integrations; the file-export starter does not implement those actions.
Separate the draft, the decision, and the result
Keep these records distinct in your implementation:
- Store the proposalThe agent submits one exact version.
- Inspect the requestThe person reads the content and scope.
- Record the decisionThe reviewer interface approves or rejects that version.
- Verify the effectAfter an approved export, read the actual file.
For the existing starter, the agent submits only these arguments to request_approval:
{
"requestKey": "handoff-v1",
"markdown": "# Project handoff\n\n## Summary\nPrepare the handoff for review.\n\n## Details\nExport one local Markdown file after approval.\n\n## Verification\nCompare the exported bytes with this stored version.\n"
}
The service supplies id, digest, contentSha256, rulesVersion, state, expiresAt, title, and outputFile. On a new pending request, outputFile is null. The agent does not submit an approved flag or an approver identity.
The two hashes answer different questions. contentSha256 identifies the Markdown bytes. digest also covers the operation and rule version in this starter. Use the service’s digest when reviewing a proposal. Neither hash is a secret credential or proof that the document is correct.
For timeouts before you receive an ID, retry the identical request key and document. Changing the document requires a new request key and review. A new key with identical content returns the original proposal, including a rejected or expired state. It does not renew permission.
When the reviewer says no
Imagine the reviewer rejects the handoff because it omits the rollback owner, then asks for that detail. A request to revise permits work on a new draft; it does not approve export. If the reviewer simply says to stop, stop rather than repeatedly submitting variations.
In the starter, the owner records rejection from their own terminal, with AA_SERVICE_DIR configured as in the setup instructions. From the extracted approval-mcp/ directory, replace the placeholders with the pending proposal’s ID and the digest shown by show:
node src/review.mjs show PROPOSAL_ID
node src/review.mjs reject PROPOSAL_ID REVIEWED_DIGEST
Read the full stored document before recording the decision. These are owner commands, not steps for the agent to perform. The CLI records the rejected state; it has no field for a rejection reason. Give the agent the requested changes separately and keep that explanation with the private review record.
Here is what happens next with this starter:
| Submission or action | Result |
|---|---|
| Export the rejected proposal | Blocked with execution_blocked_rejected |
| Submit identical Markdown with a new key | Returns the same rejected proposal |
| Submit changed Markdown with the original key | Fails with request_key_content_changed |
| Submit a previously unsubmitted revision with a new key | Creates a separate pending proposal; the old one stays rejected |
| Export that pending revision | Blocked until it receives its own approval |
For the imagined rollback-owner correction, the reviewer could send this instruction:
Revise the handoff to name the rollback owner I supplied. Check the revised Markdown, submit it with a new request key, and show me the new proposal ID, digest, full document and a short change summary. Stop for review. Do not export, run reviewer commands, or change unrelated content to get around the rejection.
The change summary helps the person find the correction; review the full new document as well. The service compares bytes and state. It cannot decide whether a change addresses the reviewer’s concern. Cosmetic edits can produce different bytes, so they are not evidence that the rejection was resolved.
On 9 November 2026, we checked the public starter archive against the reviewed package and exercised these cases on macOS with Node 24.22.1. The check invoked the reviewer CLI programmatically in disposable state, then called the underlying gate. Both export attempts were blocked and the output directory stayed empty. This was a local implementation check, not a human decision or a Codex/Claude Code session. The commands operate the existing starter; no download changes are required.
Keep evidence beside each claim
Before submitting the card, assign each statement to its source:
| Statement on the card | Source to use |
|---|---|
| Why this note is useful | Agent explanation, subject to review |
| The required sections are present | Individual checker results |
| These are the bytes under review | Stored proposal and service-generated hashes |
| The person approved this version | Decision recorded through the reviewer interface |
| The file exists and matches | Export verification that reads the actual file |
The download includes a reference for the starter’s fields and event records. Its events identify requested, approved, claimed, exported, and blocked or recovery paths. They do not record an independently authenticated person’s identity, and they are not a tamper-proof audit log.
If you need named approvers, add a trusted authentication and authorization mechanism. An agent-supplied approvedBy string does not establish that person’s identity or authority.
Check the card before you use it
Run a small acceptance exercise against your integration:
- Submit the example document and inspect it through the reviewer interface. Confirm that the complete content, destination, deadline, and hashes match the card.
- Try exporting while the request is pending. The starter must block the call and create no output file.
- Change the document under the same request key. The starter must reject the changed request instead of replacing the version under review.
- Have the person approve the displayed proposal and digest. Resume the agent, export that ID, and call
verify_export. - Compare the reported hash with the approved content hash. Report success only when
verifiedis true. If the state or verification blocks progress, stop and inspect the result.
For expiry and ambiguous outcomes, follow the lifecycle guide. In the starter, approval expires one hour after submission. Expiry is checked before execution is claimed. A deadline does not cancel an action that already started.
These request, changed-content, and export behaviors are covered by the starter’s local tests. The card itself is a new review aid. We have not measured whether it improves human review accuracy or speed. The separate Codex pilot reached a pending proposal; a completed human-approved host session is not evidence for this article.
Keep the card connected to enforcement
Use the card to explain a decision, and enforce that decision in the execution path. OWASP’s transaction authorization guidance recommends showing significant transaction data, enforcing authorization on the server, and checking it before execution. It also discusses invalidating authorization when transaction data changes. We apply those ideas to agent requests here; this template is not an OWASP certification.
The local starter is a cooperative workflow under one OS account. An unrestricted agent with the owner’s filesystem access can bypass its reviewer interface. A Markdown card cannot fix that boundary. The starter’s setup instructions explain the separation required before making a stronger enforcement claim.
Updated 9 November 2026. Added owner rejection commands, observed request-state results and a bounded revision example. The request card and starter downloads are unchanged.