@crediolabs/policy-synth 0.1.17 → 0.2.0

package/src/run/index.ts

@@ -18,7 +18,7 @@
 // drive the CLI (which calls into the same core directly without MCP).
 
 import { createHash } from 'node:crypto'
-import { rpc } from '@stellar/stellar-sdk'
+import { rpc, xdr } from '@stellar/stellar-sdk'
 import {
   type ErrorCode,
   type MandateSpec,
@@ -35,6 +35,11 @@ import {
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
+import {
+  type AuthorityOverlap,
+  type ContextType,
+  findAuthorityOverlaps,
+} from '../install/authority-overlap.ts'
 import {
   type BuildInstallPolicyResult,
   type BuildRevokePolicyResult,
@@ -43,7 +48,16 @@ import {
   type InstallRpcClient,
   rpcClientFromServer,
 } from '../install/build-install-policy.ts'
+import { buildMergePolicyXdr } from '../install/build-merge-policy.ts'
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts'
+import { planMergePolicy } from '../install/plan-merge-policy.ts'
+import {
+  accountRuleReaderFromServer,
+  collectObservedRules,
+  nonceLedgerKey,
+} from '../install/read-account-rules.ts'
+import { decodePredicate } from '../predicate/decode.ts'
+import { encodePredicate } from '../predicate/encode.ts'
 import type { SimulationResult } from '../verify/envelope.ts'
 import { simulatePolicy, verifyPolicy } from '../verify/index.ts'
 import {
@@ -51,10 +65,12 @@ import {
   GetInterpreterInfoInputSchema,
   type InstallPolicyInput,
   InstallPolicyInputSchema,
+  type MergePolicyInput,
+  MergePolicyInputSchema,
   NETWORK_PASSPHRASES,
   PINNED_INTERPRETER_ADDRESS_BY_NETWORK,
   PINNED_INTERPRETER_GRAMMAR_VERSION,
-  PINNED_INTERPRETER_WASM_SHA256,
+  PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK,
   type RecordTransactionInput,
   RecordTransactionInputSchema,
   type RevokePolicyInput,
@@ -95,7 +111,7 @@ export {
   PINNED_INTERPRETER_GRAMMAR_VERSION,
   PINNED_INTERPRETER_MAINNET_ADDRESS,
   PINNED_INTERPRETER_TESTNET_ADDRESS,
-  PINNED_INTERPRETER_WASM_SHA256,
+  PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK,
   PredicateLeafSchema,
   PredicateNodeSchema,
   RecordedTransactionSchema,
@@ -110,13 +126,32 @@ export {
 } from './schemas.ts'
 
 export type RunRecordTransactionInput = RecordTransactionInput
-
 export type RunSynthesizePolicyInput = SynthesizePolicyInput
-
 export type RunSimulatePolicyInput = SimulatePolicyInput
-
 export type RunVerifyPolicyInput = VerifyPolicyInput
 
+type RunToolName =
+  | 'record_transaction'
+  | 'synthesize_policy'
+  | 'simulate_policy'
+  | 'verify_policy'
+  | 'install_policy'
+  | 'revoke_policy'
+  | 'get_interpreter_info'
+
+/** Map every tool name to its canonical domain error code. Replaces a 7-way
+ *  if/else so adding a tool adds one line here rather than a new branch in
+ *  each envelope call. */
+const TOOL_ERROR_CODE: Record<RunToolName, ErrorCode> = {
+  record_transaction: 'RECORDING_FAILED',
+  synthesize_policy: 'SYNTHESIS_ERROR',
+  simulate_policy: 'SIMULATION_ERROR',
+  verify_policy: 'VERIFICATION_FAILED',
+  install_policy: 'INSTALL_BUILD_FAILED',
+  revoke_policy: 'REVOKE_BUILD_FAILED',
+  get_interpreter_info: 'RECORDING_FAILED',
+}
+
 /** `record_transaction` body - wraps `recordTransaction`. The tool input
  *  matches the core RecordInput minus the injected `fetcher` (the transport
  *  layer does not own the RPC). Returns the core ToolResponse unchanged.
@@ -316,9 +351,7 @@ export async function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true>>
  *  comes from the RPC). Both gates accept an explicit opt-in flag.
  *  Pin selection follows `input.network` (defaults to `testnet` so the
  *  pre-mainnet callers keep working unchanged). */
-export async function runInstallPolicy(
-  raw: unknown
-): Promise<ToolResponse<BuildInstallPolicyResult>> {
+export async function runInstallPolicy(raw: unknown): Promise<ToolResponse<InstallPolicyResult>> {
   const parsed = InstallPolicyInputSchema.safeParse(raw)
   if (!parsed.success) {
     return {
@@ -339,17 +372,15 @@ export async function runInstallPolicy(
   if (pinningError) {
     return { ok: false, error: pinningError }
   }
-  if (input.rpcUrl && input.rpcUrl !== expectedRpc && input.allowUnpinnedRpcUrl !== true) {
-    return {
-      ok: false,
-      error: {
-        code: 'INSTALL_BUILD_FAILED',
-        message: `install_policy: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
-        severity: 'error',
-        retryable: false,
-        remediation: { toolCall: { name: 'install_policy', args: {} } },
-      },
-    }
+  const rpcPinningError = enforceRpcPin(
+    'install_policy',
+    input.rpcUrl,
+    input.allowUnpinnedRpcUrl,
+    expectedRpc,
+    network
+  )
+  if (rpcPinningError) {
+    return { ok: false, error: rpcPinningError }
   }
   let rpcClient: InstallRpcClient
   try {
@@ -366,6 +397,27 @@ export async function runInstallPolicy(
     const predicateHash = createHash('sha256')
       .update(Buffer.from(encodedPredicate, 'base64'))
       .digest('hex')
+
+    // ---- Cross-rule authority scan ----
+    // OZ enforces only the policies of the rule the caller names, so a signer
+    // who also sits in a wider rule keeps that wider authority no matter what
+    // this predicate says. Refuse by default when the wider rule has no policy
+    // at all, because that makes this install decorative.
+    const authorityScan: AuthorityScanReport | undefined = input.skipAuthorityScan
+      ? { ran: false, skipped: true, reason: 'skipped at caller request', overlaps: [] }
+      : await scanAuthorityOverlap({
+          smartAccount: input.smartAccount,
+          interpreterAddress: expectedInterpreter,
+          rule: input.rule,
+          encodedPredicate,
+          rpcUrl: input.rpcUrl ?? expectedRpc,
+          network,
+        })
+    const overlapError = enforceAuthorityScan(authorityScan, input.allowAuthorityOverlap)
+    if (overlapError) {
+      return { ok: false, error: overlapError }
+    }
+
     const result = await buildInstallPolicyXdr({
       smartAccount: input.smartAccount,
       sourceAccount: input.sourceAccount,
@@ -377,7 +429,7 @@ export async function runInstallPolicy(
       rpc: rpcClient,
       ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
     })
-    return { ok: true, data: result }
+    return { ok: true, data: authorityScan ? { ...result, authorityScan } : result }
   } catch (e) {
     return {
       ok: false,
@@ -386,6 +438,343 @@ export async function runInstallPolicy(
   }
 }
 
+/** Default-deny on the cross-rule scan.
+ *
+ *  Refuses whenever the scan cannot establish that this policy binds the calls
+ *  it names. An unpoliced neighbour provably does not constrain them. An
+ *  opaque one, policed by a contract this tool cannot decode, is not KNOWN to,
+ *  and "not known to" is not "safe" - the same posture as the interpreter and
+ *  RPC pins. An incomplete scan is refused for the same reason: the overlap
+ *  list is then a subset of the account, so an empty list proves nothing.
+ *
+ *  `not-restricting` is reported but does NOT block. Both rules are ours and
+ *  both constrain the calls, and the conjunction remedy is offered; refusing
+ *  there would also block the legitimate act of adding a separate capability,
+ *  which OZ composes correctly as a union.
+ *
+ *  Returns a ToolError or null, matching `enforceInterpreterPin`. */
+export function enforceAuthorityScan(
+  scan: AuthorityScanReport | undefined,
+  allowOverlap: boolean | undefined
+): ToolError | null {
+  if (!scan || allowOverlap === true) return null
+
+  // Default-deny by exclusion rather than by enumeration: anything that is not
+  // the one known-safe severity blocks. Listing the blocking severities
+  // instead would mean a severity added later silently passes until someone
+  // remembers to add it here, and the safe direction is the opposite.
+  const blocking = scan.overlaps.filter((o) => o.severity !== 'not-restricting')
+  const unpoliced = blocking.filter((o) => o.severity === 'bypass').map((o) => o.ruleId)
+  const opaque = blocking.filter((o) => o.severity === 'unknown').map((o) => o.ruleId)
+  const unrecognised = blocking
+    .filter((o) => o.severity !== 'bypass' && o.severity !== 'unknown')
+    .map((o) => o.ruleId)
+
+  if (blocking.length > 0) {
+    const parts = [
+      unpoliced.length > 0 ? `rule ${unpoliced.join(', ')} has no policy attached` : '',
+      opaque.length > 0
+        ? `rule ${opaque.join(', ')} is policed by a contract this tool cannot decode`
+        : '',
+      unrecognised.length > 0
+        ? `rule ${unrecognised.join(', ')} carries an overlap this build does not recognise`
+        : '',
+    ].filter(Boolean)
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message: `install_policy: a signer of this rule can already make the same calls through another context rule, so this policy is not established to restrict them: ${parts.join('; ')}. Remove the shared signer from that rule, attach a policy this tool can read, or set allowAuthorityOverlap: true to install anyway`,
+      severity: 'error',
+      retryable: false,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+
+  // A scan that was meant to run and threw tells us nothing. Reporting it in
+  // a string field and proceeding is the same fail-open shape as an incomplete
+  // scan, and a caller that does not read `ran` cannot tell it from a clean
+  // result.
+  if (scan.ran === false && scan.skipped !== true) {
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message: `install_policy: the cross-rule authority scan could not run (${scan.reason ?? 'unknown error'}), so it cannot establish that this policy restricts anything; retry, or set allowAuthorityOverlap: true to install without that assurance`,
+      severity: 'error',
+      retryable: true,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+
+  if (scan.incomplete === true) {
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message:
+        'install_policy: the account has more context rules than the scan could account for, so the overlap result is incomplete and cannot establish that this policy restricts anything; set allowAuthorityOverlap: true to install without that assurance',
+      severity: 'error',
+      retryable: false,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+
+  return null
+}
+
+/** The install response, plus what the cross-rule scan found. The scan is
+ *  advisory data about the account, not part of the transaction, so it is
+ *  additive: a caller that ignores it gets exactly the previous shape. */
+export type InstallPolicyResult = BuildInstallPolicyResult & {
+  authorityScan?: AuthorityScanReport
+}
+
+/** What the cross-rule scan found, carried on the install response so the
+ *  review surface can show it alongside the transaction being signed.
+ *
+ *  SCOPE, and it is narrow: this answers "can a signer OF THIS RULE reach the
+ *  same calls through a different rule". A rule sharing no signer with this
+ *  one cannot be reached by this rule's signers, so it is not a way around
+ *  this policy; it is a different principal's authority, which no policy
+ *  installed here was ever going to constrain. Other rules keep their own
+ *  signers, and an account administrator can add signers or rules afterwards.
+ *
+ *  An empty `overlaps` is therefore NOT a statement that the account is safe,
+ *  only that this rule's own signers gain no unconstrained path through the
+ *  rules that exist right now. */
+export interface AuthorityScanReport {
+  /** False when the scan did not run. `reason` then says why, and the absence
+   *  of overlaps proves nothing. */
+  ran: boolean
+  /** True when the caller passed `skipAuthorityScan`. Distinguishes a
+   *  deliberate skip from a scan that tried and failed: both carry
+   *  `ran: false`, but only the failure refuses the install. Recorded rather
+   *  than omitted so the response shows that no opinion was formed, instead
+   *  of looking like a version that never had the check. */
+  skipped?: boolean
+  /** True when the account has more rules than the scan accounted for, so the
+   *  overlap list is a subset. */
+  incomplete?: boolean
+  reason?: string
+  overlaps: AuthorityOverlap[]
+}
+
+/** Read the account's other context rules and report where this install's
+ *  signers already hold authority over the same calls.
+ *
+ *  A failure to read is reported rather than thrown, and the caller-facing
+ *  decision is made by `enforceAuthorityScan`: a scan that tried and failed
+ *  tells us nothing, so it refuses rather than passing as a clean account.
+ *
+ *  The account data this trusts comes from whichever RPC answered, so a
+ *  hostile RPC could describe an account with no overlapping rules. That is
+ *  bounded by the pin already enforced above: `enforceRpcPin` returns before
+ *  this runs, so the URL is the pinned one for the network unless the caller
+ *  explicitly set `allowUnpinnedRpcUrl`. This scan deliberately does not add a
+ *  second pin check, because two places deciding the same thing drift. */
+async function scanAuthorityOverlap(args: {
+  smartAccount: string
+  interpreterAddress: string
+  rule: InstallPolicyInput['rule']
+  encodedPredicate: string
+  rpcUrl: string
+  network: Network
+}): Promise<AuthorityScanReport | undefined> {
+  try {
+    if (!args.encodedPredicate) {
+      // Not applicable rather than failed: this rule installs no interpreter
+      // predicate, so there is nothing of ours for another rule to undercut.
+      // Returning undefined keeps it out of the refusal path, which is
+      // reserved for scans that were meant to run and could not.
+      return undefined
+    }
+    const server = new rpc.Server(args.rpcUrl, { allowHttp: false })
+    const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[args.network])
+    const collected = await collectObservedRules({
+      reader,
+      smartAccount: args.smartAccount,
+      interpreterAddress: args.interpreterAddress,
+    })
+    const overlaps = findAuthorityOverlaps({
+      intended: {
+        // `add_context_rule` always creates a NEW rule, so there is no id to
+        // exclude; -1 matches nothing on the account.
+        ruleId: -1,
+        contextType: toOverlapContextType(args.rule.contextRuleType),
+        signers: args.rule.signers,
+        predicate: decodePredicate(args.encodedPredicate),
+      },
+      existing: collected.rules,
+    })
+    return { ran: true, incomplete: collected.incomplete, overlaps }
+  } catch (e) {
+    return {
+      ran: false,
+      reason: e instanceof Error ? e.message : String(e),
+      overlaps: [],
+    }
+  }
+}
+
+/** The rule draft names the callee `contract`; the analyser calls it
+ *  `address`. Same value, two vocabularies. */
+function toOverlapContextType(ct: InstallPolicyInput['rule']['contextRuleType']): ContextType {
+  switch (ct.kind) {
+    case 'call_contract':
+      return { kind: 'call_contract', address: ct.contract }
+    case 'create_contract':
+      return { kind: 'create_contract', wasmHash: ct.wasmHash }
+    default:
+      return { kind: 'default' }
+  }
+}
+
+/** The merge response: one step's transaction plus what it will cost. */
+export interface MergePolicyResult {
+  unsignedXdr: string
+  smartAccount: string
+  sourceAccount: string
+  step: 'detach' | 'reinstall'
+  call: { contract: string; fn: string; ruleId: number }
+  authNonce: string
+  authValidUntilLedger: number
+  rootInvocationXdr: string
+  /** sha256 of the merged predicate, so the caller can pin what step 2 will
+   *  install while they are still looking at step 1. */
+  mergedPredicateHash: string
+  mergedPredicateBlobBase64: string
+  warnings: string[]
+  followUp: string
+}
+
+/** `merge_policy` body - the tightening remedy for a cross-rule overlap.
+ *
+ *  Replaces a rule's predicate with the conjunction of it and a new one. This
+ *  is the action `install_policy` recommends when it reports an overlap
+ *  between two rules our interpreter polices, and it is deliberately NOT
+ *  something `install_policy` does on its own: it detaches a live policy, so
+ *  the operator has to ask for it.
+ *
+ *  Two transactions in order. `add_policy` refuses a policy already on the
+ *  rule, so the old attachment goes first, and the second transaction cannot
+ *  be simulated until the first confirms. */
+export async function runMergePolicy(raw: unknown): Promise<ToolResponse<MergePolicyResult>> {
+  const parsed = MergePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, error: validationError('install_policy', parsed.error.issues) }
+  }
+  const input: MergePolicyInput = parsed.data
+  const network: Network = input.network ?? 'testnet'
+  const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network]
+  const expectedRpc = RPC_URL_BY_NETWORK[network]
+
+  const rpcPinningError = enforceRpcPin(
+    'install_policy',
+    input.rpcUrl,
+    input.allowUnpinnedRpcUrl,
+    expectedRpc,
+    network
+  )
+  if (rpcPinningError) return { ok: false, error: rpcPinningError }
+
+  try {
+    const rpcUrl = input.rpcUrl ?? expectedRpc
+    const server = new rpc.Server(rpcUrl, { allowHttp: false })
+    const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network])
+    const collected = await collectObservedRules({
+      reader,
+      smartAccount: input.smartAccount,
+      interpreterAddress: expectedInterpreter,
+    })
+    const rule = collected.rules.find((r) => r.id === input.ruleId)
+    if (!rule) {
+      return {
+        ok: false,
+        error: {
+          code: 'INSTALL_BUILD_FAILED',
+          message: `merge_policy: rule ${input.ruleId} was not found on ${input.smartAccount}${
+            collected.incomplete
+              ? ' (the rule scan was incomplete, so it may exist but was not reached)'
+              : ''
+          }`,
+          severity: 'error',
+          retryable: false,
+          remediation: { toolCall: { name: 'install_policy', args: {} } },
+        },
+      }
+    }
+
+    const plan = planMergePolicy({
+      rule,
+      interpreterAddress: expectedInterpreter,
+      incoming: decodePredicate(input.incomingPredicateBlobBase64),
+      step: input.step,
+    })
+    if (!plan.ok) {
+      return {
+        ok: false,
+        error: {
+          code: 'INSTALL_BUILD_FAILED',
+          message: `merge_policy: ${plan.reason}`,
+          severity: 'error',
+          retryable: false,
+          remediation: { toolCall: { name: 'install_policy', args: {} } },
+        },
+      }
+    }
+
+    const encoded = encodePredicate(plan.predicate)
+
+    // The nonce is read, not assumed. OZ's `remove_policy` discards the result
+    // of `try_uninstall`, so a detach whose uninstall panicked - our
+    // `uninstall` panics MissingState when the master set has been archived -
+    // detaches the policy while leaving our nonce behind. Re-installing at 1
+    // would then be refused as a replay and the rule would sit unpoliced.
+    let installNonce = 1
+    const nonceWarnings: string[] = []
+    if (input.step === 'reinstall') {
+      const entries = await server.getLedgerEntries(
+        nonceLedgerKey(expectedInterpreter, input.smartAccount, input.ruleId)
+      )
+      const raw = entries.entries?.[0]?.val
+      const stored =
+        raw && raw.switch() === xdr.LedgerEntryType.contractData()
+          ? raw.contractData().val()
+          : undefined
+      if (stored && stored.switch() === xdr.ScValType.scvU32()) {
+        installNonce = stored.u32() + 1
+        nonceWarnings.push(
+          `the previous uninstall did not complete: rule ${input.ruleId} still holds interpreter state at nonce ${stored.u32()}, so this reinstalls at ${installNonce} rather than 1. The rule's counters were NOT reset.`
+        )
+      }
+    }
+
+    const built = await buildMergePolicyXdr({
+      smartAccount: input.smartAccount,
+      sourceAccount: input.sourceAccount,
+      networkPassphrase: NETWORK_PASSPHRASES[network],
+      ruleId: input.ruleId,
+      policyId: plan.policyId,
+      interpreterAddress: expectedInterpreter,
+      step: input.step,
+      encodedPredicate: encoded.encodedPredicate,
+      predicateHash: encoded.predicateHash,
+      installNonce,
+      ...(plan.oracleParams ? { oracleParams: plan.oracleParams } : {}),
+      rpc: rpcClientFromServer(server, NETWORK_PASSPHRASES[network]),
+      ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
+    })
+
+    return {
+      ok: true,
+      data: {
+        ...built,
+        mergedPredicateHash: encoded.predicateHash,
+        mergedPredicateBlobBase64: encoded.encodedPredicate,
+        warnings: [...plan.warnings, ...nonceWarnings],
+        followUp: plan.followUp,
+      },
+    }
+  } catch (e) {
+    return { ok: false, error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e) }
+  }
+}
+
 /** `revoke_policy` body - thin wrapper over `buildRevokePolicyXdr`.
  *  Emits an unsigned XDR for `account.remove_context_rule(ruleId)`; the
  *  smart account itself handles uninstalling each attached policy. Auth
@@ -408,17 +797,15 @@ export async function runRevokePolicy(
   const input: RevokePolicyInput = parsed.data
   const network: Network = input.network ?? 'testnet'
   const expectedRpc = RPC_URL_BY_NETWORK[network]
-  if (input.rpcUrl && input.rpcUrl !== expectedRpc && input.allowUnpinnedRpcUrl !== true) {
-    return {
-      ok: false,
-      error: {
-        code: 'REVOKE_BUILD_FAILED',
-        message: `revoke_policy: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
-        severity: 'error',
-        retryable: false,
-        remediation: { toolCall: { name: 'revoke_policy', args: {} } },
-      },
-    }
+  const rpcPinningError = enforceRpcPin(
+    'revoke_policy',
+    input.rpcUrl,
+    input.allowUnpinnedRpcUrl,
+    expectedRpc,
+    network
+  )
+  if (rpcPinningError) {
+    return { ok: false, error: rpcPinningError }
   }
   let rpcClient: InstallRpcClient
   try {
@@ -454,13 +841,18 @@ export async function runRevokePolicy(
  *  fabricating it would be a lie on a security surface; the live
  *  mismatch check is worth MORE).
  *
- *  Network-aware: `input.network` selects which interpreter pin and RPC
- *  to use. Mainnet was rolled out 2026-08-04 - the same wasm hash was
- *  uploaded to mainnet as was exercised on testnet, so a single
- *  `PINNED_INTERPRETER_WASM_SHA256` constant backs both networks
- *  (DEPLOYMENTS.md:25-27). The address differs because instance ids are
- *  network-scoped. UNAUDITED at the time of writing - see
- *  DEPLOYMENTS.md:29-32 for what is still pending. */
+ *  Network-aware: `input.network` selects the interpreter address, the RPC
+ *  and the wasm hash. The networks run different binaries - testnet carries
+ *  the selector-leaf minimum and the signer-set cap, mainnet predates both -
+ *  so the hash is read through
+ *  `PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK`. UNAUDITED at the time of
+ *  writing.
+ *
+ *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
+ *  call, the auth-digest + the answer bind to whichever RPC answered, so
+ *  a non-pinned `rpcUrl` would silently bind the caller to a host they
+ *  picked. The pin is enforced here too, with the same `allowUnpinnedRpcUrl`
+ *  opt-in as install/revoke. */
 export async function runGetInterpreterInfo(
   raw: unknown
 ): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>> {
@@ -473,6 +865,25 @@ export async function runGetInterpreterInfo(
   }
   const input: GetInterpreterInfoInput = parsed.data
   const network: Network = input.network ?? 'testnet'
+  const expectedRpc = RPC_URL_BY_NETWORK[network]
+  // Pin enforcement only matters when the live RPC call is engaged. The
+  // static-fingerprint branch is local data and a non-pinned URL never
+  // reaches the network, so the gate is conditioned on `verifyLive` to
+  // match the wire-level concern (an outbound request that returns a
+  // caller-bound value). A caller that DOES NOT verifyLive can supply any
+  // URL it likes; the field is still optional.
+  if (input.verifyLive === true) {
+    const rpcPinningError = enforceRpcPin(
+      'get_interpreter_info',
+      input.rpcUrl,
+      input.allowUnpinnedRpcUrl,
+      expectedRpc,
+      network
+    )
+    if (rpcPinningError) {
+      return { ok: false, error: rpcPinningError }
+    }
+  }
   const pinnedAddress = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network]
   try {
     let deployedGrammarVersion: number | undefined
@@ -483,7 +894,7 @@ export async function runGetInterpreterInfo(
     const info = getInterpreterInfo({
       pinnedAddress,
       pinnedGrammarVersion: PINNED_INTERPRETER_GRAMMAR_VERSION,
-      pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256,
+      pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK[network],
       network,
       ...(deployedGrammarVersion !== undefined ? { deployedGrammarVersion } : {}),
     })
@@ -514,15 +925,14 @@ function buildRpcClientFromInput(
   return rpcClientFromServer(new rpc.Server(url, { allowHttp: false }), passphrase)
 }
 
-/** Default-deny: refuse any interpreter policy whose address differs from
- *  the pinned interpreter for the selected network. An interpreter the
- *  caller controls can permit anything, so the smart account's
- *  authorization must bind to the pinned contract unless the caller
- *  explicitly opts in via `allowUnpinnedInterpreter`. OZ built-in
- *  policies are not interpreters and pass through unchanged. Returns a
- *  ToolError to surface through the run-layer envelope, or null when the
- *  policies are all pinned. The caller resolves the expected pin per
- *  network; this function stays pure so it is easy to test. */
+/** Default-deny: refuse an interpreter policy whose address differs from the
+ *  pinned interpreter for the selected network. An interpreter the caller
+ *  controls can permit anything, so the smart account's authorization must
+ *  bind to the pinned contract unless the caller opts in. OZ built-in
+ *  policies are not interpreters and pass through. Returns a ToolError to
+ *  surface through the run-layer envelope, or null when all interpreter
+ *  policies are pinned. The caller resolves the expected pin per network;
+ *  this function stays pure so it is easy to test. */
 function enforceInterpreterPin(
   policies: InstallPolicyInput['rule']['policies'],
   allowUnpinned: boolean | undefined,
@@ -543,81 +953,69 @@ function enforceInterpreterPin(
   return null
 }
 
+/** Default-deny: refuse an `rpcUrl` that is not the pinned RPC for the
+ *  selected network. The auth nonce + rootInvocation in the install/revoke
+ *  response come from whichever RPC answered, so a non-pinned RPC would
+ *  silently bind the caller to a host they picked. The same applies to
+ *  `get_interpreter_info` when `verifyLive` is true (the live grammar
+ *  version is the caller-bound value). The caller may opt in via
+ *  `allowUnpinnedRpcUrl: true`. Returns a ToolError or null when the URL is
+ *  pinned (or absent, since the default is the pinned one). */
+function enforceRpcPin(
+  toolName: 'install_policy' | 'revoke_policy' | 'get_interpreter_info',
+  rpcUrl: string | undefined,
+  allowUnpinned: boolean | undefined,
+  expectedRpc: string,
+  network: Network
+): ToolError | null {
+  if (!rpcUrl || rpcUrl === expectedRpc || allowUnpinned === true) return null
+  const code: ErrorCode =
+    toolName === 'install_policy'
+      ? 'INSTALL_BUILD_FAILED'
+      : toolName === 'revoke_policy'
+        ? 'REVOKE_BUILD_FAILED'
+        : 'RECORDING_FAILED'
+  return {
+    code,
+    message: `${toolName}: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
+    severity: 'error',
+    retryable: false,
+    remediation: { toolCall: { name: toolName, args: {} } },
+  }
+}
+
 /** Build a canonical ToolError for a Zod validation failure. The remediation
  *  hint points the agent back at the right tool with an empty arg bag - the
  *  tool name IS the machine-readable hint. */
 function validationError(
-  toolName:
-    | 'record_transaction'
-    | 'synthesize_policy'
-    | 'simulate_policy'
-    | 'verify_policy'
-    | 'install_policy'
-    | 'revoke_policy'
-    | 'get_interpreter_info',
+  toolName: RunToolName,
   issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>
 ): ToolError {
-  const code: ErrorCode =
-    toolName === 'record_transaction'
-      ? 'RECORDING_FAILED'
-      : toolName === 'synthesize_policy'
-        ? 'SYNTHESIS_ERROR'
-        : toolName === 'simulate_policy'
-          ? 'SIMULATION_ERROR'
-          : toolName === 'verify_policy'
-            ? 'VERIFICATION_FAILED'
-            : toolName === 'install_policy'
-              ? 'INSTALL_BUILD_FAILED'
-              : toolName === 'revoke_policy'
-                ? 'REVOKE_BUILD_FAILED'
-                : 'RECORDING_FAILED'
   return {
-    code,
+    code: TOOL_ERROR_CODE[toolName],
     message: `${toolName}: invalid input: ${issues
       .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
       .join('; ')}`,
     severity: 'error',
     retryable: false,
-    remediation: {
-      toolCall: { name: toolName, args: {} },
-    },
+    remediation: { toolCall: { name: toolName, args: {} } },
   }
 }
 
 /** Build a canonical ToolError for a thrown exception caught by the tool
  *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
  *  default, so we extract a string-friendly message and tag the original
- *  error in `details` for the agent to inspect. The `code` is the tool's
- *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
- *  for `synthesize_policy`) so the agent dispatches on the same code the
- *  structured ToolError would carry.
- *
- *  Exported as `_caughtError` (the leading underscore signals the test-only
- *  seam) so the suite in run/index.test.ts can drive the envelope path
- *  without standing up a full recordTransaction pipeline. */
-export function caughtError(
-  toolName:
-    | 'record_transaction'
-    | 'synthesize_policy'
-    | 'simulate_policy'
-    | 'verify_policy'
-    | 'install_policy'
-    | 'revoke_policy'
-    | 'get_interpreter_info',
-  code: ErrorCode,
-  e: unknown
-): ToolError {
-  const message = describeThrown(e, toolName)
-  const details = { thrown: safeStringify(e) }
+ *  error in `details` for the agent to inspect. Exported as a test-only seam
+ *  so the suite in run/index.test.ts can drive the envelope path without
+ *  standing up a full recordTransaction pipeline. */
+export function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError {
   return {
     code,
-    message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
+    message: `${toolName}: unhandled throw escaped core envelope: ${describeThrown(e, toolName)}`,
     severity: 'error',
     retryable: false,
-    remediation: {
-      toolCall: { name: toolName, args: {} },
-    },
-    details,
+    remediation: { toolCall: { name: toolName, args: {} } },
+    details: { thrown: safeStringify(e) },
   }
 }