feat(spec)!: remove tool.requiresConfirmation — a safety flag nothing enforced (#3715, ADR-0033 §2) (#3876)

ToolSchema.requiresConfirmation accepted `true` and no execution path ever read
it: not the LLM tool set, not ToolRegistry.execute, not POST
/ai/tools/:name/execute, and not the MCP bridge (hardcoded destructive-name
list). Setting it on a destructive tool produced NO pause.

For an ordinary dead property that is untidy. For a SAFETY property it is false
compliance — the case ADR-0049 exists for. Made worse by the near-miss:
action.ai.requiresConfirmation has the same name and DOES work, so the mistake
reads as correct in review. ADR-0033 §2 already resolved to delete it.

Migration — FROM `requiresConfirmation: true` on a tool, TO an action carrying
`ai.requiresConfirmation: true`, the flag the HITL approval queue actually reads.
For AI metadata mutations nothing changes: the ADR-0033 draft/publish workspace
is the gate.

ToolSchema is now .strict(), which is load-bearing rather than tidying. Removing
a key from a non-strict schema swaps one silent no-op for another — zod strips it
wordlessly and the safety flag goes on meaning nothing. The retired key now
REJECTS with the FROM -> TO prescription attached, via a TOOL_RETIRED_KEY_GUIDANCE
map wired through a $ZodErrorMap (house pattern: ObjectCapabilities, tenancy).
Typos on a tool definition are now located parse errors too.

Also removed: the Studio form row; its four generated locale bundles, which still
promised "Ask user to approve before executing (for destructive actions)" — a
translated false promise nothing would have caught; the liveness-ledger entry
(tool dead 5 -> 4); and the generated reference-doc row. A follow-up commit fixed
the skills/objectstack-ai defineTool example that check:skill-examples caught,
and disambiguated the MCP capability-descriptor field of the same name.

Author: os-zhuang

.changeset/tool-requires-confirmation-removed.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/spec": minor
+"@objectstack/platform-objects": patch
+---
+
+feat(spec)!: remove `tool.requiresConfirmation` — a safety flag nothing enforced (#3715, ADR-0033 §2)
+
+`ToolSchema.requiresConfirmation` accepted `true` and no execution path ever read
+it. Not the LLM tool set (a tool reaches the model as name/description/parameters
+only), not `ToolRegistry.execute`, not `POST /ai/tools/:name/execute`, and not the
+MCP bridge — which derives `destructiveHint` from a hardcoded name list. Setting
+it on a destructive tool produced **no pause**.
+
+For an ordinary dead property that is untidy. For a **safety** property it is
+false compliance, which is the case ADR-0049 exists for: an author gates a
+destructive tool, sees the flag accepted, and ships believing a human is in the
+loop. It is made worse by the near-miss — `action.ai.requiresConfirmation` has
+the same name and **does** work, so the mistake reads as correct in review.
+ADR-0033 §2 already resolved to delete this one.
+
+## Migration
+
+- **FROM:** `requiresConfirmation: true` on a tool definition
+- **TO:** put the operation behind an action and set `ai.requiresConfirmation:
+  true` there — that is the flag the HITL approval queue reads
+  (`packages/runtime/src/action-execution.ts`) and the only path that actually
+  stops execution.
+- For AI *metadata* mutations there is nothing to migrate: the ADR-0033
+  draft/publish workspace is the gate — nothing is live until a human publishes.
+
+**`ToolSchema` is now `.strict()`.** This is load-bearing, not tidying. Removing a
+key from a non-strict schema swaps one silent no-op for another: zod strips the
+key wordlessly, the author keeps writing it, and the safety flag goes on meaning
+nothing — the "silent strip" ADR-0032 / #1535 closed for objects. The retired key
+now **rejects**, and the error carries the FROM → TO above, because a parse error
+is the one channel every consumer bumping `@objectstack/spec` is guaranteed to
+hit.
+
+Strictness applies to *all* unknown keys on a tool definition, so a typo
+(`buildIn`, `catagory`) is now a located parse error instead of a silently
+dropped field.
+
+Also removed: the Studio form row, its four generated locale bundles (the
+`en`/`zh-CN`/`ja-JP`/`es-ES` strings still promised *"Ask user to approve before
+executing (for destructive actions)"* — a translated false promise), the
+liveness-ledger entry, and the generated reference-doc row.
+
+objectui's `ToolPreview.tsx` reads the field via `!!d.requiresConfirmation`, so it
+degrades to "not shown" with no error; removing that badge is a follow-up in that
+repo.

content/docs/references/ai/tool.mdx

@@ -40,7 +40,6 @@ AI tool definition. [READ-ONLY PROJECTION — not an execution entry point] Auth
 | **parameters** | `Record<string, any>` | ✅ | JSON Schema for tool parameters |
 | **outputSchema** | `Record<string, any>` | optional | [EXPERIMENTAL — not enforced] JSON Schema for tool output. Keys are folded into the tool description only; outputs are not validated (liveness #1878/#1893). |
 | **objectName** | `string` | optional | Target object name (snake_case) |
-| **requiresConfirmation** | `boolean` | ✅ | [EXPERIMENTAL — not enforced] Require user confirmation before execution. NOTHING pauses on this flag (#3715) — use the action-level `ai.requiresConfirmation` + approval queue for a real gate. |
 | **permissions** | `string[]` | optional | Required permission-set capabilities |
 | **active** | `boolean` | ✅ | Whether the tool is enabled |
 | **builtIn** | `boolean` | ✅ | Platform built-in tool flag |

packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts

@@ -1693,10 +1693,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
         label: "Output Schema",
         helpText: "Output schema for validation (optional)"
       },
-      requiresConfirmation: {
-        label: "Requires Confirmation",
-        helpText: "Ask user to approve before executing (for destructive actions)"
-      },
       permissions: {
         label: "Permissions",
         helpText: "Required permissions to use this tool"

packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts

@@ -1693,10 +1693,6 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
         label: "Esquema de salida",
         helpText: "Esquema de salida para validación (opcional)"
       },
-      requiresConfirmation: {
-        label: "Requiere confirmación",
-        helpText: "Pide aprobación al usuario antes de ejecutar (para acciones destructivas)"
-      },
       permissions: {
         label: "Permisos",
         helpText: "Permisos necesarios para usar esta herramienta"

packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts

@@ -1693,10 +1693,6 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
         label: "出力スキーマ",
         helpText: "検証用出力スキーマ（任意）"
       },
-      requiresConfirmation: {
-        label: "確認が必要",
-        helpText: "実行前にユーザー承認を求める（破壊的アクション用）"
-      },
       permissions: {
         label: "権限",
         helpText: "このツールの使用に必要な権限"

packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts

@@ -1693,10 +1693,6 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
         label: "输出 Schema",
         helpText: "用于校验的输出结构（可选）"
       },
-      requiresConfirmation: {
-        label: "需要确认",
-        helpText: "在执行前请求用户确认（用于破坏性操作）"
-      },
       permissions: {
         label: "权限",
         helpText: "使用此工具所需的权限"

packages/spec/README.md

@@ -133,9 +133,11 @@ export const objectStackMCP = MCPServerConfigSchema.parse({
       ],
       handler: 'flows.create_record',
       sideEffects: 'write',
-      // NOTE: declarative only — nothing pauses on this flag (#3715). A real
-      // human-in-the-loop gate is `ai.requiresConfirmation` on the underlying
-      // action (+ the approval queue), or `approval: 'always'` on an MCP binding.
+      // NOTE: an MCP capability-descriptor hint — surfaced to the client, but
+      // nothing server-side pauses on it. (The `ToolSchema` field of the same
+      // name was removed in 16.x — #3715, ADR-0033 §2.) A real human-in-the-loop
+      // gate is `ai.requiresConfirmation` on the underlying action (+ the
+      // approval queue), or `approval: 'always'` on an MCP binding.
       requiresConfirmation: true,
     },
     {

packages/spec/docs/MCP_GUIDE.md

@@ -359,8 +359,11 @@ For operations with side effects, gate them with something that is enforced:
 `approval: 'always'` on the MCP tool binding, or `ai.requiresConfirmation` on
 the underlying **action** (+ the HITL approval queue).
 
-> ⚠️ `requiresConfirmation` on the **tool definition** is declared but read by
-> no execution path — it produces no pause (#3715).
+> ⚠️ The `requiresConfirmation` in these examples is an **MCP capability
+> descriptor** hint — surfaced to the client in `list_actions` so it *may* ask,
+> but nothing server-side pauses on it. Distinct from the `ToolSchema` field of
+> the same name, which was REMOVED in the 16.x line (#3715, ADR-0033 §2)
+> precisely because a safety flag no path enforces is false compliance.
 
 ### 4. Security
 

packages/spec/liveness/README.md

@@ -376,7 +376,7 @@ EOF
 | permission | 32 | – | 0 | – | CRUD/FLS/RLS live; dead `contextVariables` REMOVED (ADR-0105 D11 — RLS resolves only the `current_user.*` built-ins plus runtime-staged `rlsMembership` sets) |
 | position | 4 | – | – | – | (role's ADR-0090 successor) fully live |
 | agent | 13 | 5 | 1 | – | dead `tenantId` + `planning.strategy`/`allowReplan` REMOVED (#2377) — only `planning.maxIterations` live; autonomy tier experimental; `knowledge` CORRECTED to dead 2026-07 — `search_knowledge` takes `sourceIds` from the LLM's tool-call args, never from the agent record (#1878 §3 recheck) |
-| tool | 5 | 1 | 5 | – | the whole authoring surface is inert: `permissions` (not permission-gated), plus `category`/`requiresConfirmation`/`active`/`builtIn` CORRECTED to dead 2026-07 (#3686 sweep). ⚠️ `requiresConfirmation` is SAFETY-shaped and unenforced on every path — ADR-0033 already resolved to delete it |
+| tool | 5 | 1 | 4 | – | the whole authoring surface is inert: `permissions` (not permission-gated), plus `category`/`active`/`builtIn` CORRECTED to dead 2026-07 (#3686 sweep). `requiresConfirmation` REMOVED (#3715, ADR-0033 §2) — SAFETY-shaped and unenforced on every path, so it was false compliance, not merely dead; ToolSchema is now `.strict()` so the retired key REJECTS with the FROM → TO prescription instead of being silently stripped |
 | skill | 8 | – | 1 | – | `permissions` REMOVED 2026-07 (never gated anything — owner call was prune, #3704); `triggerPhrases` CORRECTED to dead — phrases are never matched against user messages; activation is `triggerConditions` + the agent's `skills[]` + explicit /skill-name pinning (#3686 sweep) |
 | dataset | 19 | – | 0 | – | `measures.certified` (declared-but-unenforced governance flag) REMOVED in 16.0 (#2377) |
 | page | 16 | – | – | 1 | fully live + one planned |

packages/spec/liveness/tool.json

@@ -38,13 +38,6 @@
       "authorHint": "Display-only — no runtime groups, filters or routes tools by category.",
       "note": "RE-VERIFIED 2026-07 (#3686 preview-claim sweep): the prior `live` verdict cited only a metadata-admin PREVIEW panel, which echoes what the author typed."
     },
-    "requiresConfirmation": {
-      "status": "dead",
-      "evidence": "zero reads off any TOOL definition in any repo; every requiresConfirmation read is action.ai.requiresConfirmation (a different, live property). Ignored by the LLM tool set (vercel-adapter.ts:263-272), ToolRegistry.execute (tool-registry.ts:183-210), POST /ai/tools/:name/execute (tool-routes.ts:91,105) and the MCP bridge (framework packages/mcp/src/mcp-server-runtime.ts:176, which uses a hardcoded destructive-name list)",
-      "authorWarn": true,
-      "authorHint": "NOT ENFORCED — nothing pauses for confirmation on this flag, on any path. To gate a destructive operation, put it behind an action with `ai.requiresConfirmation` + the HITL approval queue, which is the only path that actually stops execution.",
-      "note": "RE-VERIFIED 2026-07 (#3686 preview-claim sweep): the prior `live` verdict cited only a metadata-admin PREVIEW panel, which echoes what the author typed. SAFETY-SHAPED: tool.form.ts:36-42 places it in a section titled 'Access & safety' with helpText 'Ask user to approve before executing (for destructive actions)', and skills/objectstack-ai/SKILL.md:547 tells authors to rely on it — so the authoring surface actively teaches a guarantee nothing delivers. ADR-0033 (:31, :60) already recorded it as never-enforced and resolved to DELETE the placeholder (the draft/publish workspace is the real approval gate); that deletion was never executed. OWNER CALL 2026-07: the prune-or-wire decision is DEFERRED (#3715), but the false promise stops now — the spec `.describe()`, the Studio form section (formerly titled \"Access & safety\", whose copy told authors to use it for destructive operations) and the SKILL.md / MCP_GUIDE / README guidance all now say NOT ENFORCED and point at the action-level gate."
-    },
     "permissions": {
       "status": "dead",
       "evidence": "tool.form.ts only; not on AIToolDefinition, no consumer",