# Approval request card and starter field reference

Use this worksheet to present one proposed action for review. It does not grant permission, authenticate a reviewer, or enforce a policy. Pair it with the AgentApprovals MCP starter or your own approval service.

Guide: https://agentapprovals.ai/guides/approval-request-template/
Working implementation: https://agentapprovals.ai/guides/mcp-tool-approvals/

## Copy this card

Replace every bracketed value. Read the actual stored proposal through the reviewer interface before recording a decision. Keep confidential content in a protected review location.

```text
Action: [one concrete effect]
Reason: [why this effect helps the user's task]
Proposal: [service-issued ID]
Destination and scope: [exact target, account or environment, and limits]
Content or arguments: [full stored version or protected read-only view]
Review digest: [service-issued digest binding the reviewed operation]
Expires: [service-issued timestamp and time zone]
Checks: [rule version, individual results, and links to evidence]
Open questions: [uncertainties the reviewer needs to resolve]
Decision requested: [approve or reject this exact effect]
Verification: [how the service or operator will observe the result]
Recovery: [what to do if the outcome is unknown]
Current state: Pending. Do not infer approval from passing checks.
```

The agent may explain intent and uncertainty. The service supplies identifiers, checks, state, and timestamps. The authorized reviewer supplies the decision. An execution result must come from the system that performs or observes the effect.

Keep an AI-generated summary separate from the full content or arguments. A reviewer needs a trustworthy way to inspect the exact version the executor will use. Recheck mutable external conditions at execution when the operation depends on them. A content hash cannot freeze an external account, repository, or recipient.

## Use the existing Markdown export operation

In this starter, the action is `export_markdown`. The owner configures the service directory. The service generates `approved/PROPOSAL_ID.md` within it and writes the stored Markdown using exclusive creation. The agent cannot choose a replacement payload or output path at execution.

This is the input to the `request_approval` MCP tool:

```json
{
	"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"
}
```

`requestKey` must contain 1 to 80 letters, digits, underscores, or hyphens. Keep it stable when retrying the identical submission after a transport failure. Changed content needs a new key and review. Identical content with another key resolves to the original proposal, including a rejected or expired state. There is no renewal command.

`markdown` must pass the starter's named structural rules. An invalid document returns `checks_failed` with the check results instead of creating a proposal. These checks do not establish factual correctness or detect every secret.

## Read a proposal response

These are fields in the starter's proposal response, not a universal MCP schema. Read the implementation's README for setup and trust assumptions.

| Field | Meaning |
| --- | --- |
| `id` | Service-generated proposal UUID. Use it for status, export, and verification. |
| `digest` | SHA-256 of this implementation's serialized operation, rule version, and Markdown. The reviewer command requires this value. |
| `contentSha256` | SHA-256 of the Markdown bytes. Use it to compare the content with the exported bytes. |
| `rulesVersion` | The structural rule version stored with the proposal. |
| `state` | `pending`, `approved`, `rejected`, `revoked`, `expired`, `running`, `unknown`, or `exported`. |
| `expiresAt` | UTC ISO timestamp. The default deadline is one hour after submission. |
| `title` | First Markdown heading, for display. It is not a complete description of the approved content. |
| `outputFile` | Generated filename when the stored state is `exported`. Otherwise `null`. This field alone does not prove the file still exists. |

The serialized digest input is `JSON.stringify({operation:'export_markdown',rules:RULES,markdown})` in `src/gate.mjs`. Use the service-returned digest. This serialization is specific to the JavaScript implementation, not a cross-language canonicalization standard. The digest excludes destination configuration, proposal ID, and deadline. The starter trusts the owner-controlled configuration and stored state. A new operation needs its own binding design for every material argument and external precondition.

## Inspect the review record

From the extracted starter directory, the owner runs `node src/review.mjs show PROPOSAL_ID` with `AA_SERVICE_DIR` set. It returns the proposal fields plus:

| Field | Meaning |
| --- | --- |
| `markdown` | The full stored document under review. |
| `checks` | Results from checking the stored document with the current rules. |
| `events` | Ordered records containing `seq`, `time`, and `event`. `time` is Unix time in milliseconds. Sequence numbers are database-wide and may have gaps for one proposal. |

To approve, the owner uses `node src/review.mjs approve PROPOSAL_ID REVIEWED_DIGEST`. The service checks the stored state, digest, deadline, and current rules. The HTTP agent API has no approval endpoint. The CLI also supports rejection and revocation. Revocation applies to an approved proposal before execution is claimed.

Do not add `approvedBy` or `approved: true` to the request input. The tool does not accept those fields. Access to the owner CLI and database is the starter's authority boundary. It does not authenticate separate named people.

## Interpret the event history

| Event | Meaning in this starter |
| --- | --- |
| `requested` | The service stored a new pending proposal. |
| `approved`, `rejected`, `revoked` | The reviewer command recorded a permitted decision transition. |
| `expired` | A status, list, review, submission, or execution path observed that a pending or approved proposal had reached its deadline. There is no background expiry timer. |
| `claimed` | The service claimed execution and set the state to `running` before file creation. |
| `exported` | The service recorded completion of its file write. Call verification to inspect the file now. |
| `export_outcome_unknown` | The export path reported an error after claiming. Automatic retry is blocked. |
| `reconciled_exact_file` | The owner reconciled an unresolved execution after finding the exact expected file bytes. |

This is a local operational history. It does not independently authenticate the reviewer or protect against owner-level database tampering. Verification calls do not add an event to this table. Preserve their returned receipts separately if you need a record of readback checks.

## Verify and handle uncertainty

After approval, ask the agent to check `approval_status`, export the proposal ID with `export_approved_markdown`, and call `verify_export`. The verification response includes the proposal fields plus `verified` and `observedSha256`.

Only a stored `exported` state with matching file bytes returns `verified: true`. A missing or different file does not pass. Matching bytes establish equality at read time, not the document's truth or public publication.

If execution is `running` or `unknown`, stop. The owner can use `reconcile` to recognize an existing exact file. A missing or different output stays blocked for investigation. Do not resubmit under a new key to bypass rejection, expiry, or an uncertain outcome.

The starter runs cooperatively under one OS account. Protecting approval storage from an unrestricted agent requires separate permissions or a separate machine. This worksheet does not provision that separation.
