[P2] Execute ADR-0033's deletion of the unenforced `tool.requiresConfirmation` (safety-shaped, gated by nothing)

[os-zhuang]

Surfaced by the #3686 preview-claim sweep; marked honestly in #3711 (dead + authorWarn). This issue tracks the prune, which ADR-0033 already resolved but never executed.

The state

tool.requiresConfirmation (packages/spec/src/ai/tool.zod.ts:100) is read by no execution path:

Path	Behaviour
LLM tool set	cloud service-ai/src/adapters/vercel-adapter.ts:263-272 — tools reach the model as name/description/parameters only
ToolRegistry.execute	cloud tool-registry.ts:183-210 — no gate
POST /api/v1/ai/tools/:name/execute	cloud tool-routes.ts:91,105 — has() then execute()
MCP bridge	packages/mcp/src/mcp-server-runtime.ts:176 — sets destructiveHint from a hardcoded name list (:229-231), ignoring the flag

Every genuine requiresConfirmation read in all three repos is action.ai.requiresConfirmation — a different property, genuinely live (liveness/action.json, packages/runtime/src/action-execution.ts:264).

Why it is worse than inert

The authoring surface actively teaches reliance on it:

• packages/spec/src/ai/tool.form.ts:36-42 — section titled "Access & safety", description "Permissions and confirmation requirements.", helpText "Ask user to approve before executing (for destructive actions)"
• skills/objectstack-ai/SKILL.md:547 — "for destructive operations put a human in the loop — requiresConfirmation: true on the tool"
• packages/spec/docs/MCP_GUIDE.md:358, packages/spec/README.md:136

An author (or an AI) marking a destructive tool requiresConfirmation: true gets no pause, no prompt, no gate. Same class as skill.permissions (pruned in #3704) and agent visibility (#1901) — a security/safety-shaped field that lies is dropped, not carried marked.

ADR-0033 already decided this

docs/adr/0033-…:

• :31 — "The requiresConfirmation flag exists but is not enforced (the tool-call loop ignores it)"
• :60 — "We delete the unenforced requiresConfirmation placeholder on metadata tools"

The rationale stands: the draft/publish workspace is the real approval gate — AI never publishes, every metadata mutation lands as a draft a human must publish. That is the enforced HITL boundary; the flag was a placeholder for a gate that got built somewhere better.

The decision was recorded and never executed.

Scope if approved (mirrors #3704 exactly)

• packages/spec/src/ai/tool.zod.ts — the property
• packages/spec/src/ai/tool.form.ts — the field; note the "Access & safety" section's only two fields are this and the already-dead permissions, so decide whether the section goes too
• packages/spec/liveness/tool.json + the README count table
• i18n: packages/platform-objects/src/apps/translations/{en,es-ES,ja-JP,zh-CN}.metadata-forms.generated.ts — regenerate (pnpm i18n:extract), and verify the diff touches only these keys
• skills/objectstack-ai/SKILL.md:547 + MCP_GUIDE.md + README.md — replace the guidance with the real HITL path
• objectui ToolPreview.tsx — the pill
• 24 cloud *.tool.ts declarations that set it
• changeset with FROM→TO: use an action with ai.requiresConfirmation + the approval queue; for metadata mutations the draft/publish gate already applies

Open question for the owner

Prune (execute ADR-0033), or wire it — i.e. make ToolRegistry.execute and the REST route honour the flag by routing through the same HITL queue actions use? ADR-0033's reasoning argues for prune, but that ADR predates the current tool surface; if first-class metadata tools are meant to be a first-class extension point, a per-tool confirmation gate may be worth building rather than deleting.

Refs #3711, #3704, ADR-0033.

[os-zhuang]

Owner call: defer the decision, stop the bleeding now

#3740 lands the honesty half. No behaviour change — nothing read the flag before, nothing reads it now.

What stopped: the spec .describe(), the Studio form (section was titled "Access & safety", helpText "Ask user to approve before executing (for destructive actions)"), and the SKILL.md / MCP_GUIDE / README guidance all now say NOT ENFORCED and name the gate that actually works — action-level ai.requiresConfirmation + the approval queue, with AI metadata edits already covered by draft/publish. The section's other field, the already-dead permissions, got the same treatment; the section is now called "Declarative metadata (not enforced)".

What is still open — this issue stays. Prune (execute ADR-0033) vs wire it to the same HITL queue actions use. The finding that argues against a straight prune, recorded here for whoever picks this up:

ADR-0033's rationale — the draft/publish workspace is the approval gate — was sound when the only tools were metadata mutators, which is still true of cloud's 24 *.tool.ts today (17 category: 'data', 7 'utility'). But ToolCategory already declares action ("send email, create record"), integration ("External API / webhook calls") and flow — none of which a draft gate can cover. A sent email does not come back. The moment a first-class side-effect tool ships, a per-tool confirmation gate stops being a placeholder and becomes a requirement.

So the decision hinges on a product question, not a code question: are first-class metadata tools (*.tool.ts) a real third-party extension point, or platform-internal plumbing for the studio's own metadata tools? If the former, wire it; if the latter, ADR-0033's prune stands.

Nothing is time-critical now that the surface no longer lies.

[os-zhuang]

📌 裁决落地(维护者 2026-08-03):prune 成立,搁置解除

维护者对 2026-07-28 owner call 留下的产品问题给出答案:metadata tools(*.tool.ts)暂定为平台内部管线;第三方扩展面只开放 skills。

按 owner call 自己定下的判定框架——「前者 wire,后者 prune」——本单方向为 prune:执行 ADR-0033 对未实施的 tool.requiresConfirmation 的删除。要点:

• 「暂定」入档:若未来 metadata tools 开放为第三方扩展点(尤其 ToolCategory 的 action/integration/flow 类侧效工具真的发货时),per-tool 确认门从占位符变成硬需求,届时以新 ADR 重启,不受本次删除绑架——owner call 里记录的反方论据原文保留,作为那时的输入。
• 实施范围照单内清单(镜像 feat(spec)!: remove SkillSchema.permissions — it never gated anything (#3686) #3704):spec 属性 + form 字段(docs(ai): stop tool.requiresConfirmation promising a gate it does not provide (#3715) #3740 已把该 section 改为 "Declarative metadata (not enforced)",删字段后评估 section 去留)+ liveness ledger + i18n 四语 + SKILL.md/MCP_GUIDE/README 指引(指向真 HITL:action.ai.requiresConfirmation + approval queue,元数据变更走 draft/publish)+ objectui pill + cloud 24 个 *.tool.ts 声明。
• 定级:major(v17 窗口内);走 spec-property-retirement 流程,authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 门禁下不删基线行。

已排入 v17 窗口队列,位次紧随在跑的 #3207(spec 破坏性单串行纪律)。

---

Generated by Claude Code

[os-zhuang]

✅ 关单:prune 已执行,三仓核实完毕(2026-08-03)

派发前现势快查发现——本单是今天第三例「已实现未关单」(前两例 #2902/#2943、#3207/#3414):

• spec 侧已落地:ToolSchema 已 .strict(),tool.zod.ts 的墓碑自引本单(「removed … ([P2] Execute ADR-0033's deletion of the unenforced tool.requiresConfirmation (safety-shaped, gated by nothing) #3715, ADR-0033 §2)」),处方完整指向真 HITL(action.ai.requiresConfirmation + 审批队列;元数据走 draft/publish);tool.form.ts 原 "Declarative metadata (not enforced)" section 已随 POST /data/sharing/rules 绕过 SharingRuleSchema:criteria 缺失或拼错静默变成"共享该对象全部记录",与 ADR-0049 "never seeded as a permissive match-all" 直接冲突 #3896 收口整体移除。
• cloud 侧已清:24 处 *.tool.ts 声明全部不再设该键,全仓唯一命中是一条「为何不需要它」的注释(@ 5df2c69)。
• objectui 侧一处残留 → 已立 objectui#3236(ToolPreview 徽标仍读该键,「advertising the failure mode」形状,纯删代码)。

2026-08-03 维护者裁决(metadata tools 暂定平台内部管线、第三方只写 skills ⇒ prune 成立)与 owner call 的反方论据均已入档本单,供未来若开放第三方 tools 时重启确认门设计。关为 completed;残留由 objectui#3236 跟踪。

---

Generated by Claude Code