docs(ai): stop tool.requiresConfirmation promising a gate it does not provide (#3715) - #3740
Merged
os-zhuang merged 1 commit intoJul 28, 2026
Merged
Conversation
… provide (#3715) The flag is read by no execution path (LLM tool set, ToolRegistry.execute, the REST execute route, the MCP bridge — verified in #3711), while the authoring surface actively taught reliance on it: a form section titled "Access & safety" with helpText "Ask user to approve before executing (for destructive actions)", plus SKILL.md / MCP_GUIDE / README all recommending it for destructive work. Owner call: DEFER the prune-or-wire decision (#3715), stop the false promise now. The shape is likely needed once side-effect tools exist — ToolCategory already anticipates `action` (send email / create record), `integration` (external API) and `flow`, none of which the ADR-0033 draft/publish gate covers; that ADR's "the draft is the approval gate" reasoning held when the only tools were metadata mutators. - spec describe: [EXPERIMENTAL — not enforced] + pointer to the real gate - form: section renamed "Declarative metadata (not enforced)"; both fields (this + the already-dead `permissions`) name the enforced alternative - SKILL.md / MCP_GUIDE.md / README.md: point at action-level ai.requiresConfirmation + the approval queue, and note that AI metadata edits are already gated by draft/publish - ledger note records the deferral - regenerated docs + the four i18n bundles (diff verified: only the tool form's label/description/helpText keys moved) No behaviour change. 6710 spec tests; liveness/docs/api-surface/skill-docs/ skill-examples/i18n/role-word all green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 104 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Owner call on #3715: defer the prune-or-wire decision, stop the false promise now. No behaviour change — nothing read the flag before, nothing reads it now.
Why defer rather than prune
ADR-0033 already resolved to delete this placeholder, on the reasoning that the draft/publish workspace is the real approval gate (AI never publishes; a human clicks Publish). That reasoning was sound when the only tools were metadata mutators — and it still describes cloud's 24
*.tool.tstoday, all of which declarecategory: 'data'(17) or'utility'(7).But the declared tool surface anticipates more.
ToolCategory(packages/spec/src/ai/tool.zod.ts:17-25) includes:action— "Side-effect actions (send email, create record)"integration— "External API / webhook calls"flow— "Trigger a visual flow"So the moment a first-class side-effect tool exists, a per-tool confirmation gate stops being a placeholder and becomes a requirement — and removing the shape now means re-adding it later (the cost the
field-encryptionprecedent exists to avoid). Hence: keep the shape, kill the promise, decide when the tool surface's role is settled.What changed (promise only)
.describe()[EXPERIMENTAL — not enforced]+ "NOTHING pauses on this flag (#3715) — use the action-levelai.requiresConfirmation+ approval queue"ai.requiresConfirmation+ approval queue; AI metadata edits are already gated by draft/publish."skills/objectstack-ai/SKILL.md:547requiresConfirmation: trueon the tool"MCP_GUIDE.md,packages/spec/README.mdapproval: 'always'/ action-levelai.requiresConfirmationThe section's other field,
permissions(alreadydeadin the ledger), got the same treatment — it was sitting under the same "Access & safety" banner making the same implicit promise.Verification
6710 spec tests ·
check:liveness/check:docs/check:api-surface/check:skill-docs/check:skill-examples/check:i18n/check:role-wordall green.The four i18n bundles were regenerated (the form copy changed) and the diff verified line-by-line: only the tool form's
label/description/helpTextkeys moved — no unrelated block was rewritten, which a fulli18n:extractcan otherwise do.Refs #3715, #3711, ADR-0033.
🤖 Generated with Claude Code