feat: Add requireConfirmation elicitation helper for write gating

[egorpavlikhin]

Summary

• New src/helpers/requireConfirmation.ts — single shared helper for write-gating tool calls. Resolves through three branches: OCTOPUS_SKIP_ELICITATION=true env override, client elicitation capability (elicitation/create), or fallback to a confirm arg on the tool's own schema.
• Returns a discriminated ConfirmationResult so callers can tell an explicit user "no" (declined / cancelled) apart from "the user was never asked" (confirmationRequired). Without this distinction the LLM can mistake the no-elicitation fallback for a real cancellation, or — worse — retry blindly with confirm: true.
• Wires the helper into create_release and deploy_release. The confirmationRequired branch returns isError: true with directive prose so the LLM stops and asks the user instead of treating it as a user cancellation.
• Documents the pattern in CLAUDE.md next to the existing MCP SDK guidance.

Refs AIF-356.

Scope notes

• The Linear issue declares wiring as out-of-scope; per direct user instruction, create_release and deploy_release are wired here. Other write tools (run_runbook, submit_interruption, non-GET execute) remain out of scope and will land per-tool.
• Existing server.tool(...) deprecated form is kept on the wired tools to minimize diff. Migrating those to registerTool is a separate cleanup.
• Stacked on egorp/task-resources — merge the parent first.

Test plan

• npm run build clean
• npm run lint clean
• npm test — 21 new helper unit tests cover all three branches plus the new reason discriminator (envSkip / accepted / fallbackConfirm / declined / cancelled / confirmationRequired). All 58 non-integration tests pass; the 13 *.integration.test.ts failures are pre-existing and need a live Octopus at localhost:8065.
• Manual sanity in a real client:
  • Claude Code (advertises elicitation): create_release → Accept / Decline / Cancel each surface the right outcome; deploy_release likewise.
  • A client without elicitation: omitting confirm returns confirmationRequired with isError: true; passing confirm: true proceeds; passing confirm: false cancels.
  • OCTOPUS_SKIP_ELICITATION=true in server env bypasses the prompt entirely.

🤖 Generated with Claude Code

[egorpavlikhin]

Works in Cursor that supports elicitation. Claude Desktop skips elicitation but I tried to harden the response it gets from the MCP so it goes back and asks the user.

[akirayamamoto]

I wonder if we should consider simplifying this a bit.

The native MCP elicitation path feels like the strongest part of the PR. When the client supports it, the user gets a real confirmation UI and the server can handle accept, decline, and cancel cleanly. That seems like a useful UX guardrail.

I am less sure about the confirm: true fallback. Since it is just another tool argument, an agent can technically pass it without actually asking the user first. The response text tells the agent not to do that, but the server still has to trust the model to follow the instruction. That may give us more code and a bit of a false sense of safety, without really preventing the bypass we care about.

Could we consider a simpler model?

• Use native MCP elicitation when the client supports it.
• For clients without elicitation, keep write tools available by default rather than adding the confirm: true fallback. That keeps the UX predictable and avoids implying the fallback provides stronger protection than it really does.
• Consider whether it is worth adding an environment flag to disable write tools. It may help some operators, but it could also reduce confidence in the MCP server if it makes write operations feel unusually risky.
• Document this as a UX guardrail rather than a security boundary.

That would keep the useful native-confirmation path while avoiding the less reliable fallback machinery around confirm: true.

Take the next couple of points with a grain of salt, since they came out of a quick Codex review rather than a deep pass.

One implementation detail that may still be worth checking if we keep the native elicitation path: the helper should probably make sure the client supports the specific elicitation mode we send. If a client advertises elicitation but only supports a different mode, I think we should avoid sending a form-mode request to it.

I also think the deployment confirmation text is worth revisiting if these prompts stay. The current prompt includes the project, release, environment, tenants, and space, but not some of the modifiers that can materially change the deployment, such as scheduled run time, skipped steps, machine filters, prompted variables, or deployment-freeze overrides. If the confirmation is meant to help the user make a decision, it should probably summarize the important parts of the operation being approved.

Approving from my side, and happy to let you decide how to proceed.