feat(security): UnsignedTx.secondLlmRequired scaffold for Inv #12.5 (#501)

Inv #12.5 (skill-side, issue #501) marks a curated list of op classes
where the second-LLM check is a precondition of `confirmed: true`,
not opt-in. The skill-side rule lives in vaultpilot-skill v9+; this
PR is the MCP-side scaffold so future hard-trigger op producers can
flip a flag at build time and have the existing verification block
surface a mandatory ⚠ line.

What ships:

- New `secondLlmRequired?: boolean` on `UnsignedTx`. Default absent
  / false. Documentation comment lists today's hard-trigger op
  classes (all currently deferred or not built):
    - EIP-7702 setCode (#481)
    - Permit2 batch grants (#453)
    - Opaque-facet bridges (#451)
    - Approval-management N-candidate selection (Inv #13)
    - Safe enableModule / setGuard / threshold changes
- `renderVerificationBlock` reads the flag and emits a single
  ⚠ line below the hash:
    ⚠ SECOND-LLM CHECK REQUIRED — call get_verification_artifact(handle)
    and relay the pasteableBlock to the user BEFORE 'send' (Inv #12.5
    hard-trigger op).
- 3 tests pinning the behavior: omitted when absent/false, emitted
  when true, composes cleanly with recipient + tokenClass warnings.

What does NOT ship:

- No producer wires the flag yet (every hard-trigger op class is
  itself deferred). The flag is dormant scaffold.
- No enforcement layer below the rendered ⚠. The MCP can't tell
  whether the agent actually ran the second-LLM check — same self-
  attestation gap as `userDecision: "send"`.

Trust note (in the field doc):
The flag is a workflow signal, not a cryptographic primitive.
Closing the agent-side honesty gap requires infrastructure that
doesn't exist today (provider-signed LLM responses, TEE attestation,
or zkML proofs of NN inference). Discussed in the PR thread for
this issue.

Coordinated with skill v9 release (lifts §16 unconditional 7702
refusal + adds Inv #12.5 hard-trigger language); MCP-side
`EXPECTED_SKILL_SHA256` bump happens in the skill-coordination PR,
not this one.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: szhygulin

src/signing/render-verification.ts

@@ -161,7 +161,13 @@ function formatDecoder(v: TxVerification): string {
 export function renderVerificationBlock(
   tx: Pick<
     UnsignedTx,
-    "chain" | "to" | "value" | "data" | "recipient" | "tokenClass"
+    | "chain"
+    | "to"
+    | "value"
+    | "data"
+    | "recipient"
+    | "tokenClass"
+    | "secondLlmRequired"
   > & {
     verification: TxVerification;
   },
@@ -200,6 +206,22 @@ export function renderVerificationBlock(
   for (const w of tx.tokenClass?.warnings ?? []) {
     lines.push(`  ⚠ ${w}`);
   }
+  // Inv #12.5 hard-trigger ops (issue #501) — second-LLM check is a
+  // precondition of `confirmed: true`, not opt-in. The renderer
+  // surfaces a single mandatory line; the agent reads it and is
+  // expected to call `get_verification_artifact({ handle })` and
+  // relay the `pasteableBlock` BEFORE asking the user to reply
+  // 'send'. Producers (e.g. future `prepare_eip7702_authorization`
+  // / Permit2 batch / opaque-facet bridges) set the flag at build
+  // time. Today no producer wires it — pure scaffold for when
+  // hard-trigger op classes ship.
+  if (tx.secondLlmRequired === true) {
+    lines.push(
+      "  ⚠ SECOND-LLM CHECK REQUIRED — call get_verification_artifact(handle) " +
+        "and relay the pasteableBlock to the user BEFORE 'send' (Inv #12.5 " +
+        "hard-trigger op).",
+    );
+  }
   return lines.join("\n");
 }
 

src/types/index.ts

@@ -1309,6 +1309,35 @@ export interface UnsignedTx {
    * signing. Absent for ops that don't bind to a durable identifier.
    */
   durableBindings?: import("../security/durable-binding.js").DurableBinding[];
+  /**
+   * Set to `true` when the prepared op falls into the Inv #12.5
+   * "hard-trigger ops list" (issue #501) — op classes where the
+   * second-LLM check is a precondition of `confirmed: true`, not
+   * an opt-in side offer. The verification renderer surfaces a
+   * `⚠ SECOND-LLM CHECK REQUIRED` line so the agent knows to call
+   * `get_verification_artifact({ handle })` and relay the
+   * `pasteableBlock` BEFORE asking the user to reply 'send'.
+   *
+   * Today's hard-trigger ops list (none currently shipped on this
+   * server — the flag is scaffold for when they land):
+   *   - EIP-7702 setCode (#481, deferred)
+   *   - Permit2 batch grants (#453, gated on Inv #1b/#2b)
+   *   - Opaque-facet bridges (#451, deferred — Wormhole / Mayan /
+   *     NEAR Intents / Across V3 with non-EVM destinations)
+   *   - Approval-management N-candidate selection (Inv #13 territory)
+   *   - Safe enableModule / setGuard / threshold changes
+   *
+   * Trust note: this is a workflow flag, not a cryptographic
+   * primitive. The agent could ignore it or self-attest the second-
+   * LLM check happened — same self-attestation gap as
+   * `userDecision: "send"`. Closing the gap requires infrastructure
+   * that doesn't exist today (provider-signed responses, TEE
+   * attestation, or zkML — discussed in the PR thread for #501).
+   * The flag is the smallest scaffold that lets future hard-trigger
+   * op classes hook into the existing verification block without
+   * a coordinated schema change at flag-add time.
+   */
+  secondLlmRequired?: boolean;
 }
 
 /** Shape of ~/.vaultpilot-mcp/config.json. */

test/second-llm-required-flag.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Inv #12.5 hard-trigger flag (issue #501) — `secondLlmRequired` on
+ * `UnsignedTx` causes the verification renderer to surface a
+ * mandatory `⚠ SECOND-LLM CHECK REQUIRED` line so the agent knows
+ * to call `get_verification_artifact` and relay the `pasteableBlock`
+ * before the user's 'send' reply.
+ *
+ * No producer wires the flag yet — pure scaffold for when hard-
+ * trigger op classes ship (#481 EIP-7702, #453 Permit2 batch, #451
+ * opaque-facet bridges, future Safe enableModule / setGuard, etc.).
+ */
+import { describe, it, expect } from "vitest";
+import { CONTRACTS } from "../src/config/contracts.js";
+
+const HEX_DATA =
+  "0xa9059cbb0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000042b1d8d3a3f0000";
+
+const baseTx = {
+  chain: "ethereum" as const,
+  to: CONTRACTS.ethereum.tokens.USDC as `0x${string}`,
+  value: "0",
+  data: HEX_DATA as `0x${string}`,
+  verification: {
+    payloadHash: "0xdeadbeef" as `0x${string}`,
+    payloadHashShort: "deadbeef",
+    comparisonString: "ignored",
+    humanDecode: {
+      functionName: "transfer" as const,
+      args: [],
+      source: "none" as const,
+    },
+  },
+};
+
+describe("renderVerificationBlock — secondLlmRequired surfaces a ⚠ line", () => {
+  it("omits the line when secondLlmRequired is absent or false (default for plain prepares)", async () => {
+    const { renderVerificationBlock } = await import(
+      "../src/signing/render-verification.js"
+    );
+    const omitted = renderVerificationBlock({ ...baseTx });
+    const explicitFalse = renderVerificationBlock({
+      ...baseTx,
+      secondLlmRequired: false,
+    });
+    expect(omitted).not.toMatch(/SECOND-LLM CHECK REQUIRED/);
+    expect(explicitFalse).not.toMatch(/SECOND-LLM CHECK REQUIRED/);
+  });
+
+  it("emits the ⚠ line when secondLlmRequired is true", async () => {
+    const { renderVerificationBlock } = await import(
+      "../src/signing/render-verification.js"
+    );
+    const block = renderVerificationBlock({
+      ...baseTx,
+      secondLlmRequired: true,
+    });
+    expect(block).toMatch(/⚠ SECOND-LLM CHECK REQUIRED/);
+    expect(block).toMatch(/get_verification_artifact/);
+    expect(block).toMatch(/Inv #12\.5/);
+    // Surfaces below the hash line so the agent reads it at the
+    // same scan position as other ⚠ warnings (recipient + token-
+    // class), where the user's attention lands before 'send'.
+    const hashIdx = block.indexOf("Hash:");
+    const warnIdx = block.indexOf("⚠ SECOND-LLM CHECK REQUIRED");
+    expect(warnIdx).toBeGreaterThan(hashIdx);
+  });
+
+  it("composes with other ⚠ warnings (recipient + tokenClass + secondLlmRequired all surface together)", async () => {
+    const { renderVerificationBlock } = await import(
+      "../src/signing/render-verification.js"
+    );
+    const block = renderVerificationBlock({
+      ...baseTx,
+      to: CONTRACTS.ethereum.lido.stETH as `0x${string}`,
+      recipient: {
+        source: "literal",
+        warnings: [
+          "contacts file failed verification — recipient label not checked",
+        ],
+      },
+      tokenClass: {
+        flags: ["rebasing"],
+        warnings: ["stETH is rebasing — recipient may receive 1-2 wei less."],
+      },
+      secondLlmRequired: true,
+    });
+    expect(block).toMatch(/⚠ contacts file failed verification/);
+    expect(block).toMatch(/⚠ stETH is rebasing/);
+    expect(block).toMatch(/⚠ SECOND-LLM CHECK REQUIRED/);
+  });
+});