feat(mcp)!: tools that decide a merge ask the person through the client

[vriesdemichael]

Implements #620 as decided in the preparation: tools that decide a merge ask the person through the MCP client, and --yolo goes.

What changes

• Every tool is listed.
  • merge_pull_request, enable_auto_merge, disable_auto_merge, submit_pr_review, set_build_status and create_tag ask the person to confirm each call in the client before they run.
  • update_pull_request asks whenever a call sets the draft flag. Live-verified on 10.4.3: a draft cannot merge or have auto-merge set, and making one a draft cancels its auto-merge. A title-only update leaves the flag alone, so it runs without asking.
• The confirmation is an elicitation with one required, unticked checkbox naming the target ("Merge feat: implement CLI commands for project, repo, browse, and commit/ref #42 into main"). The tool acts only on an accept.
  • A 2026-07-28 client gets it as an input request (multi round-trip). go-sdk sends it itself to a handshake-era client.
  • A client that cannot show one gets -32021 MissingRequiredClientCapability with {"requiredCapabilities":{"elicitation":{"form":{}}}}, whatever revision it speaks, and nothing reaches Bitbucket.
• An answer accepts only the call it was asked about.
  • The request state is HMAC-signed with a per-process key and decoded strictly. It binds the tool, a digest of the scoped arguments, a 10-minute expiry, and a nonce used once. Tampered, re-encoded, cross-argument, replayed and state-less answers are refused.
  • A merge and an auto-merge are held to the pull request version the person was shown. One pushed to meanwhile gets Bitbucket's 409 instead of merging.
  • A decline or cancel that arrives after the expiry still stands. Only a late accept is refused, with a request to ask again.
• Why the confirmation is in the handler. It is one wrapper that askingSpec applies, not code in the middleware, because go-sdk's bridge for handshake-era clients sits below the middleware.
• Flags.
  • --read-only exposes only the read-only tools.
  • --yolo and --allow-writes are accepted, do nothing, and warn from the deprecation registry until v6.
  • bb ai mcp tools reports asks (always, never, when-setting-draft), prints a header row, and takes --read-only.
  • --safe-only, safe and exposure are deprecated the same way (ADR-084).
• Hints. Every tool declares all four hints and a title, as the spec defines them, independent of asking. openWorldHint is false, since one Data Center instance is a closed domain; the code notes to flip it if bb ever serves Cloud.
• Server. It advertises tools and nothing else: no deprecated logging, no listChanged. It sends instructions.
• Audit. Records gain confirmation (accepted, declined, cancelled, unavailable). Any call the confirmation stops is status: denied, including one whose answer cannot be used, and one decision is one record.
• Records.
  • ADR-098 records the decision and amends ADR-039, 061 and 062.
  • amended_by may now be a list, since ADR-039 is amended twice.
  • ADR-067 and AGENTS.md list the renamed and new guards.

Also fixed: a project key or slug could steer a request to another endpoint

Keys and slugs were written into request paths unescaped. Against 10.4.3, add_pr_comment with repo: "payments/pull-requests/7/merge?version=3#" POSTed to the merge endpoint, and Bitbucket merged the pull request. That is a tool that never asks doing what the asking tools exist to hold back.

ValidateRepository now refuses a key or slug containing / \ ? # %, whitespace or control characters, or equal to . or ... No real key or slug does. The services that build a path themselves escape each segment. This is its own commit, fix(repo), so it can be cherry-picked.

Tests

• Unit, both protocol eras:
  • accept, decline, cancel and an unticked box;
  • -32021 and its data shape;
  • update_pull_request asking only when draft is set;
  • the form's shape;
  • forged, altered, re-encoded, cross-argument and replayed states;
  • late answers (a decline stands, an accept is refused);
  • a nonce kept to the last second its state is valid;
  • one audit record per decision, and denied for an unusable answer;
  • injected slugs refused before any request.
• Guards, each broken first to see it fail:
  • TestToolsThatAskAreTheOnesThatDecideAMerge
  • TestReadOnlyToolsDoNotAsk
  • TestEveryToolDeclaresItsHintsAndTitle
  • each confirmation fix above
• Live:
  • every tool that asks is listed, refused with -32021 for a client that cannot ask, and refused on decline, with every value read back unchanged;
  • the merge question names the target and the quoted title, and merges on accept;
  • a draft is refused before anyone is asked;
  • a pull request pushed to while the question is open is neither merged nor has auto-merge set: Bitbucket's stale-version 409 is asserted, and dropping the pin makes the pull request merge at once;
  • a title-only update of a draft runs without asking, and the pull request stays a draft;
  • the --read-only listing;
  • the conformance sweep with an accepting client.

Refs #620

🤖 Generated with Claude Code

[vriesdemichael]

This piece reads too technical. What doea it mean for a user.
Adoption of a more modern permission system with elicitation.
Defaults to what previously was yolo mode (with the elicitation for permission on the client side instead of the server side). The non permissive option is opt in instead of the default.

Also this document has wonky encoding, fix while you are at it.

[vriesdemichael]

Make this timeless, don't give an update on what was, but state it as it is now