MCP `run_action` never enforces `ai.requiresConfirmation` — it is surfaced in `list_actions` only, while `@objectstack/spec` guidance tells authors it stops execution

[os-steve]

Summary

action.ai.requiresConfirmation is a safety-shaped flag. @objectstack/spec's own authoring guidance tells authors it gates execution — that it "forces a human-in-the-loop gate on the AI call", and, in the ADR-0049 ledger entry for the retired tool.requiresConfirmation, that action.ai.requiresConfirmation "is the flag the HITL approval queue actually reads … and the only path that actually stops execution".

Measured against the shipped @objectstack/runtime 17.3.0, no such queue exists. The flag is read in exactly one place, to fill in one field of the MCP list_actions summary. run_action never consults it. An author who follows the spec's prescription gets a JSON field, not a gate.

Measured

@objectstack/runtime 17.3.0, dist/index.js — requiresConfirmation occurs at exactly two sites in the entire bundle:

// site 1 — the read
function actionLooksDestructive(_deps, action) {
  if (action?.ai?.requiresConfirmation !== void 0) return Boolean(action.ai.requiresConfirmation);
  return Boolean(action?.mode === "delete" || action?.variant === "danger");
}

// site 2 — the only consumer, projecting into the MCP summary
function summarizeAction(deps, action, obj, objectName) {
  return {
    name: action.name,
    // …
    requiresConfirmation: actionLooksDestructive(deps, action),
  };
}

summarizeAction has exactly one caller — the listActions loop. The runAction sibling on the same object goes to invokeBusinessAction, whose pre-dispatch checks are, in order: AI exposure, action permission, disabled-activation refusal, and param enforcement. There is no confirmation check, and nothing awaits an approval. For type: 'flow' it proceeds straight to dispatchFlowAction.

Corroborating greps on the same bundle:

• approvalQueue — 0 occurrences
• destructiveHint — 0 occurrences
• HITL — 1 occurrence, in a comment describing the flag as a hint: /** True when an action is destructive by author signal/heuristic (HITL hint). */

That comment is the accurate description. The published spec guidance is not.

Why this is worth a card rather than a docs tweak

This is the exact failure class ADR-0049 was written for, and the project has already paid for it once: tool.requiresConfirmation was retired in the 16.x line precisely because "a SAFETY flag that is merely accepted is false compliance — authors set it on destructive tools believing the call would pause, and nothing ever did" (#3715). The retirement's own prescription points authors at action.ai.requiresConfirmation as the real gate.

If the runtime does not stop execution on that key either, then the replacement carries the same defect as the key it replaced, and the ledger entry directing authors to it is actively misleading. The near-miss is worse here than for an ordinary dead property: the author reads a spec sentence promising a pause, sets the flag, sees it accepted, sees it echoed truthfully in list_actions, and ships believing a human is in the loop.

Repro

1. Author an action with ai: { exposed: true, requiresConfirmation: true } on a flow-typed target.
2. list_actions over MCP → the entry correctly reports "requiresConfirmation": true.
3. run_action the same action with an API key → the flow dispatches immediately. Nothing pauses, nothing is queued, no approval is requested, and the response carries the flow result.

What this card is NOT claiming

• Not that the flag is useless. Surfacing it lets a client (Claude Code's permission prompt, for instance) gate the call on the caller's side, and that is real value.
• Not that list_actions is wrong. Its report is truthful about the declaration.
• Not a duplicate of the screen-flow dead-end in MCP run_action on a screen flow dead-ends: the screen pauses even when every input is bound, and list_actions never surfaces flow input variables #15705, which is about run_action parking on screen_1 and list_actions omitting flow input variables. That card's payload dump happens to show requiresConfirmation: false, but correctly so — its subject action declares no gate.

The decision this needs

Which of the three is intended, since the surfaces currently disagree:

1. Enforce it — run_action refuses an unconfirmed destructive call, with a resume/approve path. This is what the spec text currently promises.
2. Rescope the docs — keep surfacing-only, and rewrite the spec guidance and the ADR-0049 ledger entry so neither promises a pause. The runtime's own "HITL hint" comment is the honest wording.
3. Something between — e.g. an opt-in server-side enforcement mode, so trusted agent principals can be held while interactive ones are not.

Filed from downstream while fixing hotcrm#1578, where convert_lead had to declare this key so list_actions would stop contradicting the action's own description. That fix is correct and lands regardless; this card is the platform half, filed at destination rather than worked around downstream. Reporting the honest scope of the flag is why the fix's comment says "surfaced, not enforced" — if this card resolves as option 1, that comment gets simpler.

Measured on @objectstack/runtime 17.3.0 and @objectstack/spec 17.3.0 as installed from the registry.

[os-zhuang]

分诊：domain:cli + domain:spec / bug + security + finding / needs-user-decision / priority:p1

⛔ needs-user-decision 不与 pm:* 并存（先例 #15854 / #15617 / #15542）。
✅ 双 domain:*：三支分叉分属两个包，见下（先例 #15213 三个、#15207 两个）。

落点核实——卡片测的是已发布 dist，本席在平台源码上核对，逐条成立

① 运行期只有两处，且 run_action 不读它：

packages/runtime/src/action-execution.ts
:980     if (action?.ai?.requiresConfirmation !== undefined) return Boolean(action.ai.requiresConfirmation);   ← 唯一的读
:1014          requiresConfirmation: actionLooksDestructive(deps, action),                                     ← 唯一的消费者，投进 list_actions 摘要

范围内活控制：同一次搜索在 packages/spec/src 命中 10 条 requiresConfirmation（见下），⇒ 模式有效、包可搜 ⇒ 「runtime 侧只有两处」是读数，不是 grep 失效。

② 而 spec 侧那句误导性指引，逐字在树上：

packages/spec/src/ai/tool.zod.ts
:59-60   requiresConfirmation:
           '`tool.requiresConfirmation` was removed from @objectstack/spec in the 16.x line '
:68        '`action.ai.requiresConfirmation` — that is the flag the HITL approval queue reads '

③ 而 ADR-0049 的账本条目也在把作者往那儿指：

packages/spec/src/migrations/entries/semantic/17.tool-requires-confirmation-retired.ts
:7    surface: 'ai.tool.requiresConfirmation',
:9    'put the operation behind an ACTION and set `ai.requiresConfirmation: true` there — that '
:13   '`ToolSchema.requiresConfirmation` accepted `true` and no execution path ever read it: '

⭐ :13 是这张卡最锋利的一行。 它是退役条目自己写下的、对被退役键的判词——「接受了 true 而没有任何执行路径读它」。而这正是它推荐的替代键今天的处境。 ⇒ 卡片那句「the replacement carries the same defect as the key it replaced」不是修辞，是这个文件自己的话反过来指向它自己。

④ 契约面也只把它记成一个可选布尔： packages/spec/src/contracts/ai-service.ts:190-192 — (action.ai.requiresConfirmation, or the destructive-action default) / requiresConfirmation?: boolean;。没有任何 approval / queue / pause 的契约成员与之配套。

⚠️ 本席未跑卡片的 MCP 驱动实验（list_actions 报 true → run_action 立即派发）。⛔ 不要把源码核对当成对它的复现继承下去。但源码侧「一个读、一个消费者、消费者只是投影进摘要」这三点，与那次实测完全自洽。

---

为什么定 p1

• 这是一个安全形状的 flag，承诺了一个不存在的停顿。 作者读到 spec 的句子、设上 flag、看到它被接受、看到它在 list_actions 里被如实回报，然后带着"有人类在环"的信念发运。卡片对这个 near-miss 的描述本席逐字背书：每一个中间信号都是绿的，只有最后那件事不发生。
• 项目已经为这同一个缺陷付过一次钱：tool.requiresConfirmation 在 16.x 被退役，理由就是「a SAFETY flag that is merely accepted is false compliance」（[P2] Execute ADR-0033's deletion of the unenforced tool.requiresConfirmation (safety-shaped, gated by nothing) #3715）。⇒ 重复支付同一笔学费，而且是在退役条目亲手指定的替代品上。
• 这是本 lane 一整天在追的那个失败类的最坏变体：不是「一个不可能失败的读数」，而是**「一个不可能失败的安全门」**——它永远不拒绝，因为它根本不在执行路径上。
• security：它治理的是 AI 对破坏性操作的执行。⛔ 不是权限提升（调用方本来就有权跑那个 action），但它是唯一被文档承诺过的 HITL 闸门。

⛔ 不降 p2：卡片明确排除了两种可能的减轻。(i) 它不主张 flag 无用——客户端（如 Claude Code 的许可提示）可以据它在调用方一侧设闸，那是真实价值；(ii) 它不主张 list_actions 错——那份回报对声明是诚实的。⇒ 减轻项已经被作者自己算进去了，剩下的仍是 p1。

---

为什么是决定箱

三支的落点、代价、以及"谁是对的"完全不同，且卡片诚实地说明现有三个面互相矛盾（spec 的散文、ADR-0049 的账本、runtime 的注释）。⛔ 本席不裁决（本会话 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

四facet

① 事实（源码已复核）
action.ai.requiresConfirmation 在 @objectstack/runtime 只被读一次（action-execution.ts:980），只被消费一次（:1014，投进 list_actions 摘要）。runAction → invokeBusinessAction 的前置检查依次是：AI 曝光、action 权限、禁用激活拒绝、参数强制——没有确认检查，没有任何东西 await 一个审批；type: 'flow' 直接进 dispatchFlowAction。而 spec/src/ai/tool.zod.ts:68 告诉作者它「is the flag the HITL approval queue reads」，17.tool-requires-confirmation-retired.ts:9 把作者指向它。runtime 自己的注释（卡片引：(HITL hint)）是三者中唯一诚实的那一个。

② 分叉（卡片给出，本席原样转达）

1. 强制它 —— run_action 拒绝一次未确认的破坏性调用，并给出 resume/approve 路径。这是 spec 文本今天承诺的东西。 落点 packages/runtime ⇒ domain:cli。
2. 改文档口径 —— 保持"只曝光不强制"，重写 spec 指引与 ADR-0049 账本条目，使两者都不再承诺停顿。runtime 自己的 "HITL hint" 措辞就是诚实的版本。落点 packages/spec ⇒ domain:spec。
3. 折中 —— 例如一个可选的服务端强制模式，使受信任的 agent 主体被拦、交互式主体不被拦。两个包都动。

③ 各支的代价

• 支 1：真正兑现承诺；但它新增一个执行期拒绝（今天能跑通的调用将开始被拒），是破坏性变更，并且需要设计一整条 resume/approve 通道——approvalQueue 在 bundle 里 0 命中（卡片实测），即这条通道要从零建。
• 支 2：最便宜、非破坏；但它永久放弃平台侧 HITL 闸门，把安全责任推给每一个 MCP 客户端。⚠️ 且必须同时改两处（tool.zod.ts:68 与 17.tool-requires-confirmation-retired.ts:9），⛔ 只改一处会留下一个仍在指路的账本条目。
• 支 3：语义最好；代价是两个包同改 + 一个新的配置面（哪些主体算"受信任"），而那本身可能是另一个决定。

④ 需要裁决者提供的东西
一句话：action.ai.requiresConfirmation 是一个平台强制的闸门，还是一个交给客户端的提示？
⚠️ 请裁决者注意一个不对称：支 2 是唯一一个不需要新建任何东西的支，但它也是唯一一个会让「ADR-0049 的退役条目亲手推荐了一个同样不被执行的键」这件事被正式记录下来的支。 那条记录本身有价值（它是这个缺陷类的第二次实例），⛔ 但不该被当成选支的理由。

---

关系

• ⛔ 不与 MCP run_action on a screen flow dead-ends: the screen pauses even when every input is bound, and list_actions never surfaces flow input variables #15705 重复，卡片的辨析精确且本席背书：那张是 run_action 在 screen_1 上停住、list_actions 漏掉 flow 输入变量；其 payload 里出现的 requiresConfirmation: false 是正确的——它的主题 action 本就没声明闸门。
• 上游来源：hotcrm#1578（convert_lead 不得不声明这个键，好让 list_actions 停止与 action 自己的描述矛盾）。卡片说得对：那个下游修复无论本卡怎么裁都成立；若本卡走支 1，那条注释（"surfaced, not enforced"）可以简化。⛔ 本席不路由 hotcrm 的卡。
• ⭐ 记名一条填卡纪律：卡片单列了一节 "What this card is NOT claiming"，主动划掉三个它没有主张的东西。在一张安全卡上主动缩小自己的主张，比多主张一分更有价值——它让裁决者不必先去拆解夸大。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box。

---

Generated by Claude Code

[os-zhuang]

Ruling recorded — option A: enforce it. run_action refuses an unconfirmed call on an action declaring ai.requiresConfirmation: true; the confirmation contract is specified first (director seat, decision batch #54, 2026-09-06 12:35Z)

Maintainer's reply to the batch, verbatim: 「同意」 — recommendation A adopted as ruled, in the minimal shape presented: an explicit confirmation on the request (confirm: true or an equivalent token), a loud registered refusal when it is absent, no approval queue. Options B (rescope the docs only) and C (opt-in server mode) are rejected.

Split, per the recommendation's execution paragraph

• Spec half → spec: define the confirmation contract behind action.ai.requiresConfirmation — an unconfirmed run_action on a gated action is refused, and the refusal carries the way to confirm #16293 (domain:spec, pm:queue): the request-side confirmation member, the refusal code in ERROR_CODE_LEDGER, and the rewrite of tool.zod.ts:59-68 and the ADR-0049 ledger entry so neither promises a queue. Lands first.
• Runtime half → this card (domain:cli, MCP landing): invokeBusinessAction / run_action gain the pre-dispatch check — gated action + no confirmation ⇒ the refusal spec: define the confirmation contract behind action.ai.requiresConfirmation — an unconfirmed run_action on a gated action is refused, and the refusal carries the way to confirm #16293 defines, with the action name and the member to set; list_actions unchanged; the "HITL hint" comment updated to the enforced truth. Clause-②: yes on both carriers (accept set narrows on a published door).

State: needs-user-decision → pm:blocked (blocker: #16293) in this stroke; domain:spec moves to #16293, domain:cli stays here; security, priority:p1, bug, finding kept. Unblocks to pm:queue when #16293 merges.

---

Generated by Claude Code