add options F (ctx.once) and G (ToolBuilder) for footgun prevention

F and G address a different axis from A-E. A-E are about dual-path
(old client vs new). F and G are about the MRTR footgun: code above
the inputResponses guard runs on every retry, so a DB write there
executes N times for N-round elicitation.

F (ctx.once): idempotency guard inside the monolithic handler.
Opt-in, one line per side-effect. Makes safe code visually distinct
from unsafe code; doesn't eliminate the footgun, makes it reviewable.

G (ToolBuilder): Marcelo's step decomposition. incompleteStep may
return IncompleteResult or data; endStep runs exactly once when all
steps complete. No 'above the guard' zone because the SDK's
step-tracking is the guard. Boilerplate: two function defs +
.build() to replace the 3-line check.

Both depend on requestState integrity - real SDK MUST HMAC-sign the
blob or the client can forge step-done markers. Demos use plain
base64 for clarity.

Author: felixweinberger

examples/README-mrtr-dual-path.md

@@ -25,22 +25,39 @@ you choose to carry SSE infra." The rows collapse for E, which is the argument f
 
 ## Options
 
-|                                                                  | Author writes                   | SDK does                       | Hidden re-entry                             | Old client gets                                      |
-| ---------------------------------------------------------------- | ------------------------------- | ------------------------------ | ------------------------------------------- | ---------------------------------------------------- |
-| [A](./server/src/mrtr-dual-path/optionAShimMrtrCanonical.ts)     | MRTR-native only                | Emulates retry loop over SSE   | Yes, but safe (guard is explicit in source) | Full elicitation                                     |
-| [B](./server/src/mrtr-dual-path/optionBShimAwaitCanonical.ts)    | `await elicit()` only           | Exception → `IncompleteResult` | Yes, **unsafe** (invisible in source)       | Full elicitation                                     |
-| [C](./server/src/mrtr-dual-path/optionCExplicitVersionBranch.ts) | One handler, `if (mrtr)` branch | Version accessor               | No                                          | Full elicitation                                     |
-| [D](./server/src/mrtr-dual-path/optionDDualRegistration.ts)      | Two handlers                    | Picks by version               | No                                          | Full elicitation                                     |
-| [E](./server/src/mrtr-dual-path/optionEDegradeOnly.ts)           | MRTR-native only                | Nothing                        | No                                          | Result with default, or error — tool author's choice |
+|                                                                  | Author writes                   | SDK does                       | Hidden re-entry                             | Old client gets                                        |
+| ---------------------------------------------------------------- | ------------------------------- | ------------------------------ | ------------------------------------------- | ------------------------------------------------------ |
+| [A](./server/src/mrtr-dual-path/optionAShimMrtrCanonical.ts)     | MRTR-native only                | Emulates retry loop over SSE   | Yes, but safe (guard is explicit in source) | Full elicitation                                       |
+| [B](./server/src/mrtr-dual-path/optionBShimAwaitCanonical.ts)    | `await elicit()` only           | Exception → `IncompleteResult` | Yes, **unsafe** (invisible in source)       | Full elicitation                                       |
+| [C](./server/src/mrtr-dual-path/optionCExplicitVersionBranch.ts) | One handler, `if (mrtr)` branch | Version accessor               | No                                          | Full elicitation                                       |
+| [D](./server/src/mrtr-dual-path/optionDDualRegistration.ts)      | Two handlers                    | Picks by version               | No                                          | Full elicitation                                       |
+| [E](./server/src/mrtr-dual-path/optionEDegradeOnly.ts)           | MRTR-native only                | Nothing                        | No                                          | Result with default, or error — tool author's choice   |
+| [F](./server/src/mrtr-dual-path/optionFCtxOnce.ts)               | MRTR-native + `ctx.once` wraps  | `once()` guard in requestState | No                                          | (same as E — F/G are orthogonal to the dual-path axis) |
+| [G](./server/src/mrtr-dual-path/optionGToolBuilder.ts)           | Step functions + `.build()`     | Step-tracking in requestState  | No                                          | (same as E)                                            |
 
 "Hidden re-entry" = the handler function is invoked more than once for a single logical tool call, and the author can't tell from the source text. A is safe because MRTR-native code has the re-entry guard (`if (!prefs) return`) visible in the source even though the _loop_ is
 hidden. B is unsafe because `await elicit()` looks like a suspension point but is actually a re-entry point on MRTR sessions — see the `auditLog` landmine in that file.
 
+## Footgun prevention (F, G)
+
+A–E are about the dual-path axis (old client vs new). F and G are about a different axis: even in a pure-MRTR world, the naive handler shape has a footgun. Code above the `if (!prefs)` guard runs on every retry. If that code is a DB write or HTTP POST, it executes N times for
+N-round elicitation. The guard is present in A/E but nothing _enforces_ putting side-effects below it — safety depends on the developer knowing the convention. The analogy raised in SDK-WG review: the naive MRTR handler is de-facto GOTO — re-entry jumps to the top, and the state
+machine progression is implicit in the `inputResponses` checks.
+
+**F (`ctx.once`)** keeps the monolithic handler but wraps side-effects in an idempotency guard. `ctx.once('audit', () => auditLog(...))` checks `requestState` — if the key is already marked executed, skip. Opt-in: an unwrapped mutation still fires twice. The footgun isn't
+eliminated; it's made _visually distinct_ from safe code, which is reviewable.
+
+**G (`ToolBuilder`)** decomposes the handler into named step functions. `incompleteStep` may return `IncompleteResult` or data; `endStep` receives everything and runs exactly once. There is no "above the guard" zone because there is no guard — the SDK's step-tracking is the
+guard. Side-effects go in `endStep`; it's structurally unreachable until all elicitations complete. Boilerplate: two function definitions + `.build()` to replace A/E's 3-line check. Worth it at 3+ rounds; overkill for single-question tools where F is lighter.
+
+Both F and G depend on `requestState` integrity. The demos use plain base64 JSON; a real SDK MUST HMAC-sign the blob, because otherwise the client can forge step-done / once-executed markers and skip the guards. Per-session key derived from `initialize` keeps it stateless.
+Without signing, the safety story is advisory.
+
 ## Client impact
 
-None. All five options present identical wire behaviour to each client version. A 2025-11 client sees either a standard `elicitation/create` over SSE (A/B/C/D) or a plain `CallToolResult` (E — either a real result with a default, or an error, tool author's choice). All vanilla
-2025-11 shapes. A 2026-06 client sees `IncompleteResult` in every case. The server's internal choice doesn't leak. This is the cleanest argument against per-feature `-mrtr` capability flags: there's nothing for them to signal, because the client's behaviour is already fully
-determined by `protocolVersion` plus the existing `elicitation`/`sampling` capabilities.
+None. All seven options present identical wire behaviour to each client version (F and G are the same as E on the wire — the footgun-prevention is server-internal). A 2025-11 client sees either a standard `elicitation/create` over SSE (A/B/C/D) or a plain `CallToolResult` (E —
+either a real result with a default, or an error, tool author's choice). All vanilla 2025-11 shapes. A 2026-06 client sees `IncompleteResult` in every case. The server's internal choice doesn't leak. This is the cleanest argument against per-feature `-mrtr` capability flags:
+there's nothing for them to signal, because the client's behaviour is already fully determined by `protocolVersion` plus the existing `elicitation`/`sampling` capabilities.
 
 For the reverse direction — new client SDK connecting to an old server — see `examples/client/src/mrtr-dual-path/`. Split into two files to make the boundary explicit: [`clientDualPath.ts`](./client/src/mrtr-dual-path/clientDualPath.ts) is ~55 lines of what the app developer
 writes (one `handleElicitation` function, one registration, one tool call); [`sdkLib.ts`](./client/src/mrtr-dual-path/sdkLib.ts) is the retry loop + `IncompleteResult` parsing the SDK would ship. The app file is small on purpose — the delta from today's client code is zero.
@@ -62,6 +79,9 @@ the dual-path burden on the tool author rather than the SDK.
 
 **A vs C/D** is about who owns the SSE fallback. A: SDK owns it, author writes once. C/D: author owns it, writes twice. A is less code for authors but more magic; C/D is more code for authors but no magic.
 
+**F vs G** is the footgun-prevention trade. F is minimal — one line per side-effect, composes with any handler shape (A, E, or raw MRTR). G is structural — the step decomposition makes double-execution impossible for `endStep`, but costs two function definitions per tool. Neither
+replaces A–E; they layer on top. The likely SDK answer is: ship F as a primitive on the MRTR context, ship G as an opt-in builder, recommend G for multi-round tools and F for single-question tools with one side-effect.
+
 ## Running
 
 All demos use `DEMO_PROTOCOL_VERSION` to simulate the negotiated version, since the real SDK doesn't surface it to handlers yet. Server demos run from `examples/server`:

examples/server/src/mrtr-dual-path/optionFCtxOnce.ts

@@ -0,0 +1,85 @@
+/**
+ * Option F: ctx.once — idempotency guard inside the monolithic handler.
+ *
+ * Same MRTR-native shape as A/E, but side-effects get wrapped in
+ * `ctx.once(key, fn)`. The guard lives in `requestState` — on retry,
+ * keys marked executed skip their fn. Makes the hazard *visible* at
+ * the call site without restructuring the handler.
+ *
+ * Opt-in: an unwrapped `db.write()` above the guard still fires twice.
+ * The footgun isn't eliminated — it's made reviewable. `ctx.once('x', …)`
+ * reads differently from a bare call; a reviewer can grep for effects
+ * that aren't wrapped.
+ *
+ * When to reach for this over G (ToolBuilder): single elicitation, one
+ * or two side-effects, handler fits in ten lines. When the step count
+ * hits 3+, the ToolBuilder boilerplate pays for itself.
+ *
+ * Run: DEMO_PROTOCOL_VERSION=2026-06 pnpm tsx src/mrtr-dual-path/optionFCtxOnce.ts
+ */
+
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+
+import { acceptedContent, elicitForm, MrtrCtx, readMrtr, wrap } from './shims.js';
+
+type Units = 'metric' | 'imperial';
+
+function lookupWeather(location: string, units: Units): string {
+    const temp = units === 'metric' ? '22°C' : '72°F';
+    return `Weather in ${location}: ${temp}, partly cloudy.`;
+}
+
+// The side-effect the footgun is about. In Option B this was commented
+// out; here it's live, because the guard makes it safe.
+let auditCount = 0;
+function auditLog(location: string): void {
+    auditCount++;
+    console.error(`[audit] lookup requested for ${location} (count=${auditCount})`);
+}
+
+const server = new McpServer({ name: 'mrtr-option-f', version: '0.0.0' });
+
+server.registerTool(
+    'weather',
+    {
+        description: 'Weather lookup (Option F: ctx.once idempotency guard)',
+        inputSchema: z.object({ location: z.string(), _mrtr: z.unknown().optional() })
+    },
+    async ({ location, _mrtr }): Promise<CallToolResult> => {
+        const ctx = new MrtrCtx(readMrtr({ _mrtr }));
+
+        // ───────────────────────────────────────────────────────────────────
+        // This is the hazard line. In A/E it would run on every retry.
+        // Here it runs once — `ctx.once` checks requestState, skips on retry.
+        // A reviewer sees `ctx.once` and knows the author considered
+        // re-entry. A bare `auditLog(location)` would be the red flag.
+        // ───────────────────────────────────────────────────────────────────
+        ctx.once('audit', () => auditLog(location));
+
+        const prefs = acceptedContent<{ units: Units }>(ctx.inputResponses, 'units');
+        if (!prefs) {
+            // `ctx.incomplete()` encodes the executed-keys set into
+            // requestState so the `once` guard holds across retry.
+            return wrap(
+                ctx.incomplete({
+                    units: elicitForm({
+                        message: 'Which units?',
+                        requestedSchema: {
+                            type: 'object',
+                            properties: { units: { type: 'string', enum: ['metric', 'imperial'], title: 'Units' } },
+                            required: ['units']
+                        }
+                    })
+                })
+            );
+        }
+
+        return { content: [{ type: 'text', text: lookupWeather(location, prefs.units) }] };
+    }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[option-F] ready');

examples/server/src/mrtr-dual-path/optionGToolBuilder.ts

@@ -0,0 +1,106 @@
+/**
+ * Option G: ToolBuilder — Marcelo's explicit step decomposition.
+ *
+ * The monolithic handler becomes a sequence of named step functions.
+ * `incompleteStep` may return `IncompleteResult` (needs more input) or
+ * a data object (satisfied, pass to next step). `endStep` receives
+ * everything and runs exactly once — it's structurally unreachable
+ * until every prior step has returned data.
+ *
+ * The footgun is eliminated by code shape, not discipline. There is
+ * no "above the guard" zone because there is no guard — the SDK's
+ * step-tracking (via `requestState`) is the guard. Side-effects go
+ * in `endStep`; anything in an `incompleteStep` is documented as
+ * must-be-idempotent, and the return-type split makes the distinction
+ * visible at the function signature level.
+ *
+ * Boilerplate: two function definitions + `.build()` to replace
+ * A/E's 3-line `if (!prefs) return`. Worth it at 3+ rounds or when
+ * the side-effect story matters. Overkill for a single-question tool.
+ *
+ * Run: DEMO_PROTOCOL_VERSION=2026-06 pnpm tsx src/mrtr-dual-path/optionGToolBuilder.ts
+ */
+
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+
+import { acceptedContent, elicitForm, readMrtr, ToolBuilder, wrap } from './shims.js';
+
+type Units = 'metric' | 'imperial';
+
+function lookupWeather(location: string, units: Units): string {
+    const temp = units === 'metric' ? '22°C' : '72°F';
+    return `Weather in ${location}: ${temp}, partly cloudy.`;
+}
+
+let auditCount = 0;
+function auditLog(location: string): void {
+    auditCount++;
+    console.error(`[audit] lookup requested for ${location} (count=${auditCount})`);
+}
+
+const server = new McpServer({ name: 'mrtr-option-g', version: '0.0.0' });
+
+// ───────────────────────────────────────────────────────────────────────────
+// Step 1: ask for units. Returns IncompleteResult if not yet provided,
+// or `{ units }` to pass forward. MUST be idempotent — it can re-run
+// if requestState is tampered with (demo doesn't sign) or if the step
+// before it isn't the most-recently-completed one. No side-effects here.
+// ───────────────────────────────────────────────────────────────────────────
+
+const askUnits = (_args: { location: string }, inputs: Parameters<typeof acceptedContent>[0]) => {
+    const prefs = acceptedContent<{ units: Units }>(inputs, 'units');
+    if (!prefs) {
+        return {
+            inputRequests: {
+                units: elicitForm({
+                    message: 'Which units?',
+                    requestedSchema: {
+                        type: 'object',
+                        properties: { units: { type: 'string', enum: ['metric', 'imperial'], title: 'Units' } },
+                        required: ['units']
+                    }
+                })
+            }
+        };
+    }
+    return { units: prefs.units };
+};
+
+// ───────────────────────────────────────────────────────────────────────────
+// End step: has everything, does the work. Runs exactly once. This is
+// where side-effects live — the SDK guarantees this function is not
+// reached until `askUnits` (and any other incompleteSteps) have all
+// returned data. The `auditLog` call here fires once regardless of how
+// many MRTR rounds it took to collect the inputs.
+// ───────────────────────────────────────────────────────────────────────────
+
+const fetchWeather = ({ location }: { location: string }, collected: Record<string, unknown>): CallToolResult => {
+    auditLog(location);
+    const units = collected.units as Units;
+    return { content: [{ type: 'text', text: lookupWeather(location, units) }] };
+};
+
+// ───────────────────────────────────────────────────────────────────────────
+// Assembly. Steps are named (not ordinal) so reordering during
+// development doesn't silently remap data. The builder is the
+// MRTR-native handler; everything from A/E's dual-path discussion
+// still applies (wrap in sseRetryShim for top-left, degrade for
+// bottom-left). The footgun-prevention is orthogonal to that axis.
+// ───────────────────────────────────────────────────────────────────────────
+
+const weatherHandler = new ToolBuilder<{ location: string }>().incompleteStep('askUnits', askUnits).endStep(fetchWeather).build();
+
+server.registerTool(
+    'weather',
+    {
+        description: 'Weather lookup (Option G: ToolBuilder step decomposition)',
+        inputSchema: z.object({ location: z.string(), _mrtr: z.unknown().optional() })
+    },
+    async ({ location, _mrtr }) => wrap(await weatherHandler({ location }, readMrtr({ _mrtr }), undefined as never))
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[option-G] ready');