feat(connector): support advisory action approval

contrib/skills/shared/oo/SKILL.md

@@ -195,12 +195,17 @@ proves its output.
    [references/file-transfer.md](references/file-transfer.md).
 6. Build payload
    Use only fields exposed by the selected contract. Prefer user-provided values
-   over defaults, samples, and placeholders. Ask one focused follow-up only when
-   a required value is missing, risky to infer, destructive, broadly shared, or
-   externally visible but ambiguous.
+   over defaults, samples, and placeholders. Ask one focused follow-up when a
+   required value is missing or risky to infer, a recipient, content or
+   destination choice is ambiguous, or authorization is insufficient under the
+   host's confirmation rules.
 7. Execute
    Execute the selected connector path through `oo`, using only the canonical
-   shape documented in the reference read at step 5.
+   shape documented in the reference read at step 5. For advisory confirmation,
+   assess the operation, context and existing user instructions using the
+   [advisory confirmation rules](references/connector-execution.md#advisory-confirmation).
+   Ask only when authorization is insufficient. An `approval_required` error
+   does not itself authorize `--approval`.
 8. Materialize
    Save outputs locally only when doing so helps the user and the selected path
    exposes an explicit artifact URL.

contrib/skills/shared/oo/references/connector-execution.md

@@ -79,9 +79,9 @@ unambiguous. Otherwise ask one focused question or confirmation. Do not use
 honor user requests to validate without executing.
 
 An explicit user instruction plus complete required payload values is sufficient
-confidence for non-destructive send, post, create, or invite actions. Ask before
-destructive actions, broad sharing, or ambiguous recipient, content, or
-destination choices.
+confidence for non-destructive send, post, create, or invite actions. For
+destructive actions or broad sharing, follow the host's confirmation rules. Ask
+when authorization, recipient, content, or destination choices remain unclear.
 
 ## Execute the connector path
 
@@ -118,6 +118,46 @@ Facts:
 - The schema returned by `oo connector schema` is the public contract used to
   build payloads and inspect the action result shape.
 
+## Advisory confirmation
+
+`errorCode: approval_required` means the server's effective policy requires
+advisory confirmation for this action. The blocked action was not executed.
+This requirement depends on the effective user, team and connection policy;
+it is not part of the static action schema. Do not reconnect, refresh the schema,
+or switch teams or connections to avoid it.
+
+Use your judgment to assess whether the user's authorization covers the concrete
+operation and input values in the conversation context. Consider the user's
+current request and any applicable standing instructions, including permission
+to proceed without further questions. If that authorization is sufficient,
+use `--approval` without asking again. If it is insufficient, ask the user to
+confirm the operation and relevant parameters. Follow the host's existing
+confirmation rules.
+
+When the confirmation requirement is already known and authorization is
+sufficient, you may include `--approval` on the initial call. After an
+`approval_required` response, apply the same judgment before retrying; the error
+itself does not supply authorization. Keep the original team, connection and
+operation parameters on retries. Never add the flag mechanically or put it in
+default command templates. It is a CLI option, not a field in the provider
+input. The CLI does not prompt or retry automatically. `--dry-run` only validates
+input and does not establish authorization.
+
+For async execution:
+
+- With `--wait`, an explicit `--approval` applies to every poll of the selected
+  result action.
+- With `--wait-result`, the flag applies to the submit action only. Its derived
+  result action does not inherit the declaration.
+- If submission succeeded but a result query requires confirmation, stderr
+  includes recovery JSON with `service`, result `action`, result-query `input`
+  and `submitExecutionId`. The task already exists. Do not submit it again.
+  Assess authorization for the result query, then resume using the recovery
+  service, action and input with `--wait` and, once authorized, `--approval`.
+  Retain the original team selection (including environment variables) and
+  `--app-id` or `--connection-name`. `submitExecutionId` identifies the original
+  submission; it is not an input parameter or a CLI option.
+
 ## Proxy a provider API request
 
 Use `oo connector proxy` only when the selected connector service supports

docs/commands.md

@@ -1164,6 +1164,9 @@ Validate input data and run one connector action.
 - Options: `-a, --action <action>` selects the action name and is required.
 - Options: `-d, --data <data>` accepts inline JSON or `@path` to a JSON file.
   `--input <data>` is an alias for `--data <data>`.
+- Options: `--approval` declares that the user has authorized this operation.
+  The caller assesses whether existing authorization covers the action and its
+  parameters in context. Ask the user only when authorization is insufficient.
 - Options: `--dry-run` validates the payload without executing the action.
 - Options: `--app-id <app-id>` selects the exact connection from search.
   It is mutually exclusive with `--connection-name`; empty IDs are rejected.
@@ -1196,7 +1199,20 @@ Validate input data and run one connector action.
 - Errors: stderr prints the HTTP status and includes the server `message`
   and `errorCode` when the failure response provides them. When the response
   carries neither, the raw response body is included (trimmed and length
-  bounded) so the failure detail is not lost.
+  bounded) so the failure detail is not lost. For `errorCode: approval_required`,
+  stderr explains that the blocked action was not executed and that it can be
+  retried with `--approval` once user authorization is satisfied. The HTTP status
+  is retained and the exit code is `1`. The CLI does not retry automatically.
+- Errors: if `--wait-result` successfully submits a task but a result query
+  returns `approval_required`, the command exits `1` and explains that the task
+  was submitted but that result query was not executed. Stderr includes recovery
+  JSON `{ service, action, input, submitExecutionId }`, where `action` and
+  `input` describe the result query. Stdout remains empty. After authorization,
+  resume that result query with `--wait --approval`, preserving the original
+  team and connection selection. Do not resubmit the task.
+- Notes: `--wait` passes an explicit `--approval` declaration on every poll of
+  the selected action. With `--wait-result`, it applies only to submission;
+  the derived result action does not inherit it.
 - Notes: the command validates the input against the selected action contract
   before executing.
 - Notes: while waiting for an async result action in text mode, interactive

docs/commands.zh-CN.md

@@ -972,7 +972,9 @@ CLI 默认记录受隐私约束的命令使用 telemetry。事件不包含 free-
 - 选项：`-a, --action <action>` 用于指定 action 名称，且为必填。
 - 选项：`-d, --data <data>` 支持直接传入 JSON，或使用 `@路径` 读取 JSON 文件。
   `--input <data>` 是 `--data <data>` 的 alias。
-- 选项：`--dry-run` 只做 payload 校验，不真正执行 action。
+- 选项：`--approval` 声明本次操作已有用户授权。调用方结合具体操作、参数、上下文
+  和用户已有指示，判断授权是否充分；不足时再询问用户。
+- 选项：`--dry-run` 只做 payload 校验，不执行 action。
 - 选项：`--app-id <app-id>` 精确选择搜索返回的连接，与 `--connection-name` 互斥，
   不接受空值。当前选择的团队必须拥有该连接，app ID 本身不会切换团队。
 - 选项：`--connection-name <connection-name>` 使用指定 connector app 连接名称
@@ -996,7 +998,16 @@ CLI 默认记录受隐私约束的命令使用 telemetry。事件不包含 free-
 - 输出：dry-run 的 JSON 输出返回 `{ dryRun, ok }`。
 - 错误：stderr 会打印 HTTP 状态；如果失败响应包含服务端 `message` 或
   `errorCode`，也会一并输出；两者都缺失时，会输出原始响应体（已去除首尾空白
-  并限制长度），以免丢失失败详情。
+  并限制长度），以免丢失失败详情。对于 `errorCode: approval_required`，
+  stderr 会说明被拦截的 action 尚未执行，满足用户授权后可用 `--approval` 重试。
+  保留 HTTP 状态，退出码为 `1`，不会自动重试。
+- 错误：`--wait-result` 成功提交任务后，如果结果查询返回 `approval_required`，
+  命令以 `1` 退出，并说明任务已提交、本次结果查询未执行。stderr 附恢复 JSON
+  `{ service, action, input, submitExecutionId }`，其中 `action` 和 `input`
+  描述结果查询，stdout 保持为空。满足授权后，保留原团队和连接选择，使用恢复参数
+  带 `--wait --approval` 继续查询，不要重新提交任务。
+- 说明：`--wait` 会将显式 `--approval` 声明传给所选 action 的每次轮询。
+  对于 `--wait-result`，声明只传给提交 action，派生结果 action 不会继承。
 - 说明：命令会在执行前根据选中 action 的 contract 校验输入。
 - 说明：text 模式下等待 async result action 时，交互式终端会在 stderr
   显示进度。JSON 输出不会混入进度文本。