fix: ask before confirming, even in apps that cut the guide (#333)

[ifahimreza]

Closes #333
Refs #223

What

An AI app now shows the user a gated step's preview and waits for their yes before it confirms, including Claude Code, which reads only the start of Saddle's guide.

Why

Found in the #223 real-app pass. On the 1.5.1 zip, Claude Code 2.1.289 was asked to "Move the oldest draft to the trash". It got the preview and token and confirmed in the same turn without asking. The gate worked (two calls, single-use token, Activity with Undo), but the promise on the consent screen ("Deletions and overwrites will still show you a preview and ask for confirmation every time") was not kept.

Claude Code keeps the first 2,048 characters of a server's instructions (measured: its copy of Saddle's 6,912-character guide ends at character 2,048 with "… [truncated]"). The ask-first rule was at character 6,532. The preview's own text said only "To proceed, call this tool again… with confirm_token". The owner's instructions come last, so Claude Code never saw those either.

How

• Saddle_Approval::gate(): the preview's instructions say to show the summary, ask, and call with the token only after the user agrees. Every app reads this, whatever its instructions limit.
• Saddle_Context::system_context(): the write-tier line in "What you are allowed to do" carries the same rule, inside the first 2,048 characters.
• Saddle_MCP::server_instructions(): the handshake's first line tells an app that cut the guide short to call saddle/get-instructions for the rest, including the owner's instructions. It is not in system_context(), because get-instructions serves that.
• The withheld-tools line names the level as the owner sees it on AI apps ("Read only", "Edit content"), not the tier key ("read", "write"). Both test runs had Claude Code tell the user to set the app "back to write".
• Owner instructions stay last, as the guide's order says. No tool, schema or name changes, so ChatGPT's frozen tool lists are unaffected.

Changelog line written under 1.5.2; the number is yours.

Testing

• PHPUnit: Saddle_MCP_Transport_Test and Saddle_Approval_Test, 64/64, including two new tests: the first 2,048 characters of the handshake carry the ask-first rule and the pointer (with owner instructions set), and the preview tells the agent to ask. Full suite: see below.
• phpcs clean on the three changed files.
• saddle.pot regenerated: exactly the three changed strings.
• Verified with the real app. Fresh Playground, WordPress 7.1.2, PHP 8.3, the 1.5.1 zip from WordPress.org with this branch's three files on top, Claude Code 2.1.289 by key at Edit content:
  • The first turn now calls saddle-get-instructions by itself.
  • "Move the oldest draft to the trash": it quotes the preview ("Nothing has changed yet") and asks "Should I go ahead?". The post is unchanged.
  • "Yes, go ahead": the post is in the trash.
  • Before the fix, on the same site: confirmed in the same turn, by key and by sign-in.

🤖 Generated with Claude Code

---

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