Agent-Safe Write Path Checklist (v1)

Use this to harden one real business action (refund, deploy, close account, change billing, rotate keys) so it can be executed by an agent without turning your product into an incident generator.

1) Pick the action
- Name a business action, not a database mutation (e.g., issue_refund, rotate_api_key, cancel_subscription).
- Write down the irreversible side effects (money movement, data deletion, notifications, access changes).

2) Define the contract
- Required inputs only; avoid “update blob” payloads.
- Add a mandatory reason field and a request_id for correlation.
- Decide sync vs async: if async, return action_id + status.

3) Add server-side invariants
- Idempotency support for any side-effecting call.
- Validation: strict schema, reject unknown fields.
- Limits: policy-enforced caps (amount, scope, frequency) configurable by admins.
- Two-step commit for destructive actions: propose -> approve -> execute.

4) Identity and authorization
- Create a first-class service identity type (agent/bot), owned by a team.
- Scope tokens to the single action (and minimum read scopes needed).
- Prefer short-lived credentials; document rotation.
- Add an emergency kill switch for that service identity.

5) Policy layer (don’t bury rules in prompts)
- Centralize allow/deny decisions in a rules component.
- Make approvals policy-driven (by action type, amount, target, environment).
- Log the policy decision and which rule fired.

6) Auditability and provenance
- Log: who/what initiated, inputs, outputs, timestamps, request_id, action_id.
- Emit an event for downstream systems (webhook/event bus).
- Ensure logs are tamper-evident in practice (restricted write access, retention).

7) Safe failure modes
- Timeouts and retries must not duplicate effects (idempotency again).
- Clear error taxonomy: validation error vs auth error vs policy deny.
- Rate limits per service identity.

8) Red-team the integration path
- Assume prompt injection succeeds in the read layer.
- Verify the write layer still blocks unsafe tool calls.
- Test: unexpected fields, extreme values, repeated requests, wrong tenant, wrong environment.

9) Ship the docs like it’s a product
- One page: action description, parameters, examples, error codes, audit behavior.
- Provide a reference implementation snippet (curl + one SDK).

10) Operationalize
- Add dashboards/alerts for action volume spikes and policy denies.
- Run an incident tabletop: “agent issued 100 refunds” or “agent rotated prod keys.”
- Schedule a quarterly permission review of service identities and scopes.

If you can’t confidently pass steps 3–6 for one action, you’re not ready for agents doing real work. Build the write path first.