# Confirm an AI agent action

**Flow key:** `ai-agent-action-confirmation`

## Outcome

An agent proposes a bounded action with inspectable arguments and consequences, and executes exactly the user-approved scope under current authorization.

## Actors

- User/approver
- AI agent
- Tool/API
- Target system
- Audit/monitoring

## Preconditions and entry points

- Only synthetic/reversible targets are available.
- Tool schemas, permissions, confirmation policy, idempotency, and rollback are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Request | `Archive stale CARBON Project drafts` | ambiguous, overbroad, conflicting, injected |
| Candidate targets | three named synthetic drafts | active item, other tenant, permission-revoked, many items |
| Tool arguments | explicit stable IDs and reason | missing, extra, malformed, model-generated display name only |
| Approval | scoped confirmation of listed IDs | partial selection, changed scope, expired confirmation, denial |
| Failure | one tool call times out after commit | rate limit, partial batch, rollback failure |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | User asks for the outcome. | Agent clarifies ambiguity and discovers only authorized candidate targets. |
| 2 | Agent presents plan/preview. | Exact actions, stable targets, consequences, uncertainty, and recovery are visible. |
| 3 | User approves a specific scope. | Confirmation binds to action, arguments, target versions, actor, and time. |
| 4 | Agent reauthorizes and executes. | Tool receives least-privilege valid arguments and stable idempotency. |
| 5 | Agent observes actual results. | Committed, failed, skipped, and uncertain outcomes are distinguished; no invented success. |
| 6 | User reviews evidence and recovery. | Audit, links, changed state, side effects, compensation, and remaining uncertainty are complete. |

## Alternate paths

- Read-only answer
- Single reversible action
- Bulk action with preview
- High-impact action with second approval
- Partial approval

## Failure and recovery paths

- Prompt injection expands scope
- Target changes after approval
- Timeout after commit
- Partial batch success
- Agent retries non-idempotent tool

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [prompt surface](../../items/ai/prompt-surface.md)
- [automated action](../../items/automation/automated-action.md)
- [permission](../../items/automation/permission.md)
- [audit](../../items/automation/audit.md)

[Back to AI and automation flows](index.md)
