feat: Allow, Ask first or Off for each tool (#364)

[ifahimreza]

Closes #364

What

Phase 2 of the product plan. Every tool has a mode, Allow, Ask first or Off, set by the owner in Settings → Advanced → "What each tool may do". A tool set to Ask first shows the owner the change and waits under Needs your OK on the Dashboard. It runs only after the owner approves it there; a "yes" in the chat is not enough. A Recommended set applies Ask first to plugins, themes, updates, settings and deletes in one click.

Why

Most of Phase 2 already existed (per-app roles, single-tool switches, the confirm gate, Needs your OK, drafts-only). The missing piece was ASK: a change the owner, not the chat, has to approve. The decisions are in #364.

How

• Saddle_Tool_Modes (new). Like Saddle_Rehearsal, it wraps each changing saddle/* tool's execute callback at registration (wp_register_ability_args, priority 5, so rehearsal at 10 stays outermost). Until the owner approves, the tool's own code never runs. That matters for tools that sometimes skip their own preview (remove-block on a single block runs at once). Covers MCP, the REST abilities endpoint, direct calls, Pro and the integrations.
• Saddle_Approval: the request stores its tool (_saddle_tool). consume_token() refuses a confirm for an Ask-first tool until the owner approved, without spending the token, so the same token works after the approval. run_approved() marks the approved run, so the tool's own preview inside it (delete-post, the drafts-only publish gate) doesn't ask a second time. Ask-first previews carry needs_owner_approval, approve_at and instructions that say a chat yes doesn't count. gate() was split into run_confirmed() and preview(); behaviour for Allow tools is unchanged.
• Off is the existing switch (saddle_disabled_abilities). Ask first lives in saddle_ask_abilities (autoloaded, small). Both are protected options, so no tool can change them; uninstall removes them.
• R3: saddle_known_abilities records every changing tool on the site's first run (lazily, or on admin_init). A changing tool missing from it later (a new Saddle version, a plugin activated later) asks first until the owner chooses. Tools that exist when a site updates keep exactly what they do.
• Recommended set: every changing Manage-the-site tool, plus destructive tools except in-page edits (remove-block, divi-remove-module, divi-swap-image). It only tightens: Off stays Off, and it turns on "Publishing needs my OK". Never applied by itself.
• An Ask-first tool gets an optional confirm_token input when the schema is built (R4: new optional parameter only). The context names up to ten tools that ask first, in "What you are allowed to do".
• UI: each tool row has Allow / Ask first / Off (read tools: Allow / Off), a "New" tag, and a "Recommended set" row with "Use it". Needs your OK says "set to ask you first, so only you can approve it" on those requests.
• Found while building, fixed and pinned: a spent, made-up or other tool's token on an Ask-first tool fell through to the tool's code. A token now reaches the tool only if it's a live token from that same tool's own preview.

Testing

• vendor/bin/phpunit: 1532 tests, 9060 assertions, 1 skipped (PHP 8.2). New tests/tool-modes-test.php, 20 tests.
• vendor/bin/phpcs: no new findings. npm run lint:js clean. npm run test:js: 345 passed. npm run build committed.
• Real install (WordPress Playground, the built wporg zip from this branch, PHP 8.3, WP 7.1):
  • Fresh install: every tool at Allow, none new; a new key starts Read only.
  • create-post at Ask first, over MCP: preview with needs_owner_approval, nothing created; early confirm refused (saddle_awaiting_owner); owner approves under Needs your OK; same token creates the post once; reuse refused.
  • Claude Code 2.1.296, real app, delete-post at Ask first: it told the user to approve under Needs your OK. After "Yes, go ahead" in the chat, the site refused and the post stayed a draft. After the owner approved, it trashed the post. Activity: one "You approved…" line and one "Moved post Saddle — Design Quality Plan (builder-agnostic) #10 … to the trash." line.
  • Settings shows the three modes; "Use it" moved 20 tools to Ask first, turned on "Publishing needs my OK" and refreshed the switch; the Dashboard row reads "set to ask you first, so only you can approve it".
• No notices with WP_DEBUG on in the suite.

Notes for review

• Over ~400 lines (about 1,000 in includes/ and admin/src, plus tests, build and .pot). Fahim's "take whatever decision you need" covered it; flagging it anyway.
• Touches uninstall.php (two option names added to the list).
• Changelog lines under 1.6.0 (the number is Fahim's). No version bump.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}