---
name: human-approval
description: Request human approval before performing a SAFETY-CRITICAL, IRREVERSIBLE, or SCOPE-EXPANDING action — submit a structured context (action, scope, risk, consequence) plus options, then STOP the current turn. The platform redispatches the agent after the human decides. NEVER use for routine deliverables (writing docs / generating files / summarising chats / answering questions / explaining concepts / read-only tool calls) — those are pre-authorized; just produce the output. The 5-minute-rollback litmus test applies: if the wrong outcome can be undone in <5 minutes by editing or deleting, it is NOT approval-eligible. Routine misuse (intro/explain/summarise/file-generation) burns the user's attention budget and is a contract violation. Executes via `cloud approval` CLI.
---

# Human Approval

Some actions need a human in the loop **before** they execute: production deploys, large credit spend, deleting data, scope-expanding decisions. This skill submits a structured request and **halts the current turn**. The platform stores the request, notifies the human, and **redispatches the agent** with the decision when the human responds — you don't poll, you don't re-ask in the same turn.

## When to use

- **Production-impacting** action: deploy, schema change, infra reconfig, payment send.
- **Irreversible**: delete files, drop tables, revoke keys, close accounts.
- **Scope-expanding**: the task as-stated implies more changes than the user originally agreed to.
- **High credit cost**: any operation that would spend > expected budget.
- **Authority-elevating**: granting access, changing roles, modifying ACLs.

## Not when to use

- Routine clarifying questions ("what column name do you want?") — just ask in chat.
- Choosing between two equivalent options where the user clearly didn't care — pick one and proceed.
- When the user already explicitly approved this action in the current conversation — proceed.

## Skill scope guard (v2.0.8)

The "Not when to use" list above is the **load-bearing rule**. As of
release 2.0.8 we tightened it because routine deliverables (write a
doc, summarise a chat, draft a slide deck, answer a question) were
incorrectly triggering approval gates — the user got a yellow "等待
人工确认" banner for a request as simple as "@ceo 给我介绍一下产品 PDF",
which is a deliverable request, not a scope-expansion.

The following 8 categories are **never** approval-eligible. Run them
directly and report the result in the same turn:

| Category | Why it's not approval-eligible | Use instead |
|---|---|---|
| Writing a document / generating a report / outputting PDF, DOCX, PPTX, XLSX, CSV | The user *asked for the deliverable*; gating it is anti-UX. | Call `office-artifacts` and ship. |
| Summarising a conversation / writing meeting notes | Pure synthesis from data the user already has. | Reply in chat. |
| Answering a question / explaining a concept | The user invited the answer by asking. | Reply in chat. |
| Asking the user for a preference ("Chinese or English?") | A chat question is the correct affordance. | Ask in chat — `human-approval` is overkill. |
| Choosing model parameters / temperature / sampling style | Internal agent decision; users don't have context to judge. | Decide and proceed; mention the choice in the reply. |
| Naming files / picking output paths | Internal agent decision; reversible by renaming. | Pick sensible defaults; let user override if asked. |
| Internal brainstorming / scoring multiple candidates | The user asked for the *winner*, not the deliberation. | Do the work, surface the winner. |
| Calling read-only MCP tools (search, web fetch, file read) | No side effect; trivially reversible. | Call directly. |

**The litmus test:** "**If this step turns out wrong, can I roll it
back in under 5 minutes by editing or deleting something?**"
  - If **yes** → not approval-eligible. Ship it.
  - If **no** → safety-critical / irreversible / scope-expanding → approval-eligible.

Mis-using `human-approval` for routine work burns the user's attention
budget, breaks chat flow, and signals lack of agent confidence — all
three are real costs. The role templates (CEO / engineer / marketer /
researcher / verifier) carry an explicit `operatingPrinciples` line as
of 2.0.8: "Never trigger human-approval for routine deliverables".

## CLI Reference

**Anchor required.** `POST /api/im/approvals` rejects requests with neither `taskId` nor `conversationId`, because the platform needs a target to deliver the human decision to. Every invocation MUST pass one of `--task-id` or `--conversation-id`.

```bash
# Linked to a task — the platform resumes the task on decision (preferred for marketplace / agent flows)
cloud approval request-human \
  --task-id <taskId> \
  --action "approve marketplace task completion" \
  --context "Result: scan-deps found 3 CVEs. Report attached." \
  --risk "Releases 10-credit escrow to the assignee."

# Linked to a conversation — the decision is posted back as a chat message
cloud approval request-human \
  --conversation-id <conversationId> \
  --action "delete branch feat/old-experiment" \
  --context "Last commit 2025-12-10. Merged into main. Local copy preserved." \
  --risk "Irreversible. No remote backup; force-pushed commits would be lost."

# With explicit options (multi-choice)
cloud approval request-human \
  --conversation-id <conversationId> \
  --action "deploy v1.8.2 to prod" \
  --context "All gates green, 9/9 webhook tests pass, test env stable 48h." \
  --risk "Touches payment webhook. Rollback ETA 5min via git revert + redeploy." \
  --options "deploy-now" "deploy-tomorrow-morning" "wait-for-manual-smoke-test"
```

## Workflow

1. **Summarize the action** in one sentence — what will happen, on what resource, with what permission.
2. **Provide context** — recent state, related artifacts, why this came up now.
3. **Spell out risk and consequence** — what breaks if this is wrong, what's reversible, what's not, who else is affected.
4. **Provide options** when binary approve/reject is insufficient. Options must be **mutually understandable** and **independently actionable** (each is a thing the agent can do without further clarification).
5. **Submit the approval request.** Capture the returned `approvalId`.
6. **Stop the current turn.** Don't ask follow-up questions, don't start the action, don't speculate about the answer. The platform will redispatch you when the human decides.

## Operating Rules

- **Do not proceed with the gated action in the same turn after requesting approval.** This is the load-bearing rule. The platform will redispatch the agent with the decision; running the action now defeats the gate.
- **Do not hide material risks or irreversible effects** from the approval context. The human is approving based on what you wrote — incomplete framing is worse than no gate.
- **Keep options mutually understandable and actionable.** "Approve" / "Approve with conditions" / "Reject" is fine. "Maybe" / "Let me think" is not — that's not a decision the human can choose.
- **Use this for safety-critical decisions**, not routine clarification. Asking the user "what label do you prefer?" via human-approval is overkill and burns their attention budget.
- **Link to a task** (`--task-id`) when the approval gates a task's progression. The platform resumes the task automatically when the human approves.
- If the user already explicitly approved this exact action earlier in the conversation, **skip the gate**. Repeated approval-prompts for the same authorized action feel broken.

## Output reporting

After submitting:

> Submitted approval request `<approvalId>` for "<action>". Stopping this turn. The platform will redispatch when the human decides.

When the agent is redispatched with the decision, the next turn's input includes the approval result. Don't re-issue the request — read the decision and act on it (or report rejection back to the user).

## Backing capabilities (D22 mapping)

Replaces this v1.x built-in skill: `approval-request-human`.