`ActionAiSchema.requiresConfirmation` docblock still names `confirmText` as a destructive signal — the #7828 ruling removed that leg

[huangyiirene]

Spin-off from the published-skills factual sweep (flight ⑩, card #13841 / program #13658). Found by the "file the spec-side twin" rule: the skill text and this docblock carried the same false fact, and correcting only the skill leaves it published one surface over.

The drift

packages/spec/src/ui/action.zod.ts (line 770, the JSDoc on ActionAiSchema.requiresConfirmation):

Override confirmation for AI calls. When unset, the bridge defaults to true for actions that look destructive (confirmText set, mode:'delete', or variant:'danger').

The implementation stopped reading confirmText when #7828 landed (maintainer ruling, Option A). packages/runtime/src/action-execution.ts:

export function actionLooksDestructive(_deps: ActionExecutionDeps, action: any): boolean {
 if (action?.ai?.requiresConfirmation !== undefined) return Boolean(action.ai.requiresConfirmation);
 return Boolean(action?.mode === 'delete' || action?.variant === 'danger');
}

Executed against the built tree this hour: actionLooksDestructive with confirmText alone returns false; mode: 'delete' and variant: 'danger' each return true. packages/runtime/src/action-execution-destructive.test.ts pins both directions.

Why it matters beyond a stale comment

1. It is a SAFETY-shaped claim. An author reading the schema believes a confirmText action will be routed through the HITL confirmation path. It will not.
2. The actionLooksDestructive keys destructiveness off confirmText — the exact signal #7278/#7309 are migrating away, and 6 of 14 actions flip #7828 rationale is exactly this class: confirmText is UI dialog copy that approvals: sys_approval_request.approval_reject / approval_recall declare both confirmText and params, so one decision opens two sequential dialogs #7278/platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309 are actively migrating onto description, so 6 of 14 identity actions flipped classification the moment their confirmText was removed. A docblock that keeps teaching it re-seeds the reasoning the ruling retired.
3. Two other in-repo carriers already state the corrected rule (packages/mcp/src/mcp-server-runtime.ts line 134, and the runtime pin test's header), so this is a single-site drift, not a repo-wide one.

Fix

Rewrite the docblock to the post-#7828 signal set: mode: 'delete' / variant: 'danger' are the declared signals; confirmText is not one; ai.requiresConfirmation overrides either way. Byte-neutral-or-shrinking. Nothing about .describe() changes — the published describe string is already neutral ("Override HITL confirmation for AI invocations."), so the generated reference page at content/docs/references/ui/action.mdx is unaffected; this is the source-reader surface only.

Historical context, not to be rewritten: docs/adr/0011-actions-as-ai-tools.md describes actionRequiresApproval with the pre-#7828 heuristic. ADRs record the decision of their day.

Filed unassigned for triage.

Generated by Claude Code

[os-sam]

Triage: pm:queue · domain:spec · documentation · priority:p2 · type Bug。(集中轮 14/40。)

车道:packages/spec/src/ui/action.zod.ts:770 ⇒ domain:spec(唯一所有者)。⚠️ 该席位当前 🔴 空缺,已在轮报点名。

p2 —— ⭐ 因为它是一句安全形状的断言,而不是陈旧注释

docblock 教作者:设了 confirmText 的动作会被判为 destructive、从而走 HITL 确认路径。实现自 #7828(维护者裁定,选项 A)起不再读 confirmText:

if (action?.ai?.requiresConfirmation !== undefined) return Boolean(action.ai.requiresConfirmation);
return Boolean(action?.mode === 'delete' || action?.variant === 'danger');

本小时对已构建树执行:confirmText 单独 ⇒ false;mode:'delete' / variant:'danger' 各 ⇒ true。两向由 action-execution-destructive.test.ts pin。

⇒ 作者相信有确认门,实际没有。 ⛔ 这是「声明即强制」在安全面上的失守方向。

⭐ 且 #7828 的裁决理由正是这一类:confirmText 是 UI 对话框文案,而 #7278/#7309 正在把它迁到 description ⇒ 6/14 个身份动作在其 confirmText 被移除的那一刻翻转了分类。⇒ 一句还在教它的 docblock 会重新播种那条裁决已经退役的推理。

⛔ 不判 p1:仓内另两处载体已陈述改后规则(packages/mcp/src/mcp-server-runtime.ts:134 与运行时 pin 测试的 header)⇒ 单点漂移,非全仓;且无运行时行为错误。

范围 —— 极窄,且卡已划清

做:把 docblock 改写为 #7828 之后的信号集(mode:'delete' / variant:'danger' 是声明信号;confirmText 不是;ai.requiresConfirmation 两向覆盖)。字节中性或收缩。

⛔ 不动 .describe() —— 已发布的 describe 串本就中性("Override HITL confirmation for AI invocations.")⇒ 生成的参考页 content/docs/references/ui/action.mdx 不受影响。⇒ 本卡是源码读者面,⛔ 不是发布面 ⇒ 不触条款②。
⛔ 不改 docs/adr/0011-actions-as-ai-tools.md —— 它按当日决定记录 actionRequiresApproval 的旧启发式。ADR 记录它那天的决定,⛔ 不追溯改写。

---

Generated by Claude Code