@crediolabs/policy-builder-mcp 1.0.0 → 1.1.0

package/dist/src/schemas.d.ts

@@ -274,6 +274,7 @@ export declare const SynthesizePolicyToolShape: {
         }>;
         sourceAccount: z.ZodString;
     }, z.ZodTypeAny, "passthrough">>>;
+    readonly transactionHash: z.ZodOptional<z.ZodString>;
     readonly network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;
     readonly userResponses: z.ZodOptional<z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
@@ -308,8 +309,9 @@ export declare const SynthesizePolicyToolShape: {
     readonly explain: z.ZodOptional<z.ZodBoolean>;
 };
 export declare const SimulatePolicyToolShape: {
-    readonly predicate: z.ZodType<unknown, z.ZodTypeDef, unknown>;
-    readonly permitTx: z.ZodObject<{
+    readonly predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    readonly encodedPredicate: z.ZodOptional<z.ZodString>;
+    readonly permitTx: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
         signers: z.ZodArray<z.ZodString, "many">;
         invocations: z.ZodArray<z.ZodType<unknown, z.ZodTypeDef, unknown>, "many">;
@@ -567,12 +569,29 @@ export declare const SimulatePolicyToolShape: {
             thresholdUsed: number;
         }>;
         sourceAccount: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    readonly transactionHash: z.ZodOptional<z.ZodString>;
+    readonly network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly userResponses: z.ZodOptional<z.ZodObject<{
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+        limitAmount: z.ZodOptional<z.ZodString>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }>>;
     readonly validUntilLedger: z.ZodOptional<z.ZodNumber>;
 };
 export declare const VerifyPolicyToolShape: {
-    readonly predicate: z.ZodType<unknown, z.ZodTypeDef, unknown>;
-    readonly permitTx: z.ZodObject<{
+    readonly predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    readonly encodedPredicate: z.ZodOptional<z.ZodString>;
+    readonly permitTx: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
         signers: z.ZodArray<z.ZodString, "many">;
         invocations: z.ZodArray<z.ZodType<unknown, z.ZodTypeDef, unknown>, "many">;
@@ -830,7 +849,23 @@ export declare const VerifyPolicyToolShape: {
             thresholdUsed: number;
         }>;
         sourceAccount: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    readonly transactionHash: z.ZodOptional<z.ZodString>;
+    readonly network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly userResponses: z.ZodOptional<z.ZodObject<{
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+        limitAmount: z.ZodOptional<z.ZodString>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }>>;
     readonly validUntilLedger: z.ZodOptional<z.ZodNumber>;
 };
 export type { GetInterpreterInfoInput, InstallPolicyInput, RevokePolicyInput, SimulatePolicyInput, VerifyPolicyInput, } from '@crediolabs/policy-synth/run';
@@ -891,7 +926,67 @@ export declare const InstallPolicyToolShape: {
      *  "not checked" rather than "nothing found". */
     readonly existingRules: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
     readonly rule: z.ZodOptional<z.ZodUnknown>;
+    readonly fromPredicate: z.ZodOptional<z.ZodObject<{
+        encodedPredicate: z.ZodString;
+        signers: z.ZodArray<z.ZodString, "many">;
+        name: z.ZodOptional<z.ZodString>;
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        signers: string[];
+        encodedPredicate: string;
+        name?: string | undefined;
+        validUntilLedger?: number | undefined;
+    }, {
+        signers: string[];
+        encodedPredicate: string;
+        name?: string | undefined;
+        validUntilLedger?: number | undefined;
+    }>>;
+    readonly fromHash: z.ZodOptional<z.ZodObject<{
+        transactionHash: z.ZodString;
+        signers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        userResponses: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            limitAmount: z.ZodOptional<z.ZodString>;
+            swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        }, {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        transactionHash: string;
+        signers?: string[] | undefined;
+        userResponses?: {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        } | undefined;
+    }, {
+        transactionHash: string;
+        signers?: string[] | undefined;
+        userResponses?: {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        } | undefined;
+    }>>;
     readonly installNonce: z.ZodOptional<z.ZodNumber>;
+    readonly spendingLimit: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        periodLedgers: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        periodLedgers: number;
+    }, {
+        amount: string;
+        periodLedgers: number;
+    }>>;
+    readonly allowUnboundedAmount: z.ZodOptional<z.ZodBoolean>;
     readonly interpreterAddress: z.ZodOptional<z.ZodString>;
     readonly smartAccount: z.ZodOptional<z.ZodString>;
     readonly sourceAccount: z.ZodOptional<z.ZodString>;

package/dist/src/schemas.js

@@ -42,7 +42,12 @@ export const RecordTransactionToolShape = {
  *  re-validates against the strict schema. */
 export const SynthesizePolicyToolShape = {
     source: z.literal('recording').optional(),
+    // Supply EITHER `recordedTx` (the whole recording) OR `transactionHash`. An agent
+    // should prefer the hash: it cannot copy a multi-thousand-character recording back out
+    // of its own transcript without losing fields, and the server can re-record
+    // from the hash deterministically.
     recordedTx: RecordedTransactionSchema.optional(),
+    transactionHash: z.string().optional(),
     network: NetworkSchema.optional(),
     userResponses: ComposeUserResponsesSchema.optional(),
     confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
@@ -60,8 +65,21 @@ export const SynthesizePolicyToolShape = {
  *  (from `synthesize_policy` under `explain`) plus the recording it was
  *  synthesised from. */
 const PolicyCheckToolShape = {
-    predicate: PredicateNodeSchema,
-    permitTx: RecordedTransactionSchema,
+    // Supply EITHER `transactionHash` OR both `predicate` and `permitTx`. The tree comes
+    // back from `synthesize_policy` only under `explain`, so a caller who did not
+    // ask for it has nothing to pass and would skip the check - and this IS the
+    // check. `transactionHash` lets the server rebuild both from the transaction.
+    predicate: PredicateNodeSchema.optional(),
+    // The canonical encoding `declare_policy` and `synthesize_policy` both
+    // return. One opaque string, where the tree is what callers mistype.
+    encodedPredicate: z.string().optional(),
+    permitTx: RecordedTransactionSchema.optional(),
+    transactionHash: z.string().optional(),
+    network: NetworkSchema.optional(),
+    // Needed with `transactionHash`: the predicate is lowered against the account it will
+    // be installed on.
+    smartAccount: z.string().optional(),
+    userResponses: ComposeUserResponsesSchema.optional(),
     validUntilLedger: z.number().int().positive().optional(),
 };
 export const SimulatePolicyToolShape = { ...PolicyCheckToolShape };
@@ -127,8 +145,46 @@ export const InstallPolicyToolShape = {
      *  authority scan; omitting them returns `authorityScan: null`, which means
      *  "not checked" rather than "nothing found". */
     existingRules: z.array(z.unknown()).optional(),
+    // Supply EITHER `rule` (the whole ContextRuleDraft) OR `fromHash`. Same
+    // reason as `synthesize_policy`: a draft nests i128 strings, a signer array
+    // and a policy array, and an agent retyping it out of its own transcript
+    // loses their types. `fromHash` re-derives the draft server-side from the
+    // recording, so the install runs against the rule the synthesizer produced.
     rule: z.unknown().optional(),
+    // Install a predicate you already hold - the base64 string `declare_policy`
+    // returns - naming the keys it governs as plain account addresses. Without
+    // this there is no route from `declare_policy` to here.
+    fromPredicate: z
+        .object({
+        encodedPredicate: z.string(),
+        signers: z.array(z.string()),
+        name: z.string().optional(),
+        validUntilLedger: z.number().int().positive().optional(),
+    })
+        .optional(),
+    fromHash: z
+        .object({
+        transactionHash: z.string(),
+        // The keys the rule governs, as plain Stellar addresses. Synthesis does
+        // not choose them, and a rule governing no key is refused on chain.
+        signers: z.array(z.string()).optional(),
+        userResponses: ComposeUserResponsesSchema.optional(),
+    })
+        .optional(),
     installNonce: z.number().int().positive().optional(),
+    // A ROLLING TOTAL beside the per-call predicate, as an OpenZeppelin
+    // spending_limit on the same rule. Both must permit. This is the only way to
+    // express "N per day": the interpreter is handed one call and keeps no state.
+    spendingLimit: z
+        .object({
+        amount: z.string(),
+        periodLedgers: z.number().int().positive(),
+    })
+        .optional(),
+    // Opt-in to installing a rule that bounds no amount when the recording showed
+    // a spend. Default-deny: such a rule installs and verifies cleanly and caps
+    // nothing.
+    allowUnboundedAmount: z.boolean().optional(),
     interpreterAddress: z.string().optional(),
 };
 /** Flat ZodRawShape for `revoke_policy`. */

package/dist/src/server.js

@@ -22,18 +22,22 @@ const toCallToolResult = (res) => mcpResultFromCore(res);
 /** Build a fresh, stateless MCP server. The caller owns the returned object
  *  and connects it to a single transport (stdio or Streamable HTTP). */
 export function createMcpServer() {
-    const server = new McpServer({ name: 'policy-builder-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer(
+    // Kept in step with package.json by `server-version.test.ts`. It was
+    // hardcoded once already and reported 0.0.0 to every client; a literal is
+    // fine, a literal nothing checks is not.
+    { name: 'policy-builder-mcp', version: '1.1.0' }, { capabilities: { tools: {} } });
     registerTools(server);
     return server;
 }
 /** Idempotent registration of the T1 tool set on the given server. */
 export function registerTools(server) {
     server.tool('record_transaction', 'Decode a Soroban transaction (on-chain hash OR base64 envelope XDR) into a RecordedTransaction. Returns a machine-readable ToolError on validation failure.', RecordTransactionToolShape, (args) => runRecordTransaction(args).then(toCallToolResult));
-    server.tool('synthesize_policy', 'Synthesize a ProposedPolicy from a RecordedTransaction (`source: recording`).', SynthesizePolicyToolShape, (args) => runSynthesizePolicy(args).then(toCallToolResult));
-    server.tool('simulate_policy', 'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass the `predicate` returned by `synthesize_policy` under `explain`.', SimulatePolicyToolShape, (args) => toCallToolResult(runSimulatePolicy(args)));
-    server.tool('verify_policy', 'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose.', VerifyPolicyToolShape, (args) => toCallToolResult(runVerifyPolicy(args)));
+    server.tool('synthesize_policy', 'Synthesize a ProposedPolicy from a recorded transaction (`source: recording`). Pass `transactionHash` and `network` to have the server re-record and synthesize in one step - prefer this over copying a `recordedTx` payload back out of a previous tool result, which loses fields. `recordedTx` remains accepted for programmatic callers holding the object.', SynthesizePolicyToolShape, (args) => runSynthesizePolicy(args).then(toCallToolResult));
+    server.tool('simulate_policy', 'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass `transactionHash` with `smartAccount` and the server records and synthesizes the predicate itself; or pass a predicate together with the call to check it against. For a predicate you already hold, pass `encodedPredicate` (the base64 string `declare_policy` and `synthesize_policy` return) rather than retyping the `predicate` tree.', SimulatePolicyToolShape, (args) => runSimulatePolicy(args).then(toCallToolResult));
+    server.tool('verify_policy', 'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose. Pass `transactionHash` with `smartAccount` and the server rebuilds the predicate and the recording itself; For a predicate you already hold - a DECLARED one has no recording behind it, so re-synthesizing would check something else - pass `encodedPredicate` (the base64 string) with `transactionHash`. Retyping the `predicate` tree is the error-prone path; do not take it, and never skip this check because the tree was not to hand.', VerifyPolicyToolShape, (args) => runVerifyPolicy(args).then(toCallToolResult));
     server.tool('declare_policy', "Build an interpreter predicate from a DECLARED constraint - the method to pin, and optionally the contract, a per-call amount cap, a recipient allowlist, and a minimum-output ratio (a swap slippage floor, bounding the output argument against the call's own input). Use this when there is no transaction to record, or when `record_transaction` refuses a contract it does not recognise. Returns the predicate tree, its canonical encoding and hash, ready for `install_policy`. `warnings` names any argument index that was GUESSED rather than supplied - a bound on the wrong argument constrains nothing while looking correct, so read them. There is no rolling spend window and no approval threshold: neither is expressible in grammar 4, and both belong to the OpenZeppelin account layer.", DeclarePolicyToolShape, (args) => Promise.resolve(runDeclarePolicy(args)).then(toCallToolResult));
-    server.tool('install_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. The response carries an `authorityScan`: every rule already on the account that a signer of this install could name INSTEAD, including an unpoliced one against which the predicate never runs - a predicate only constrains a key when the policed rule is the only rule that key is on. The account is READ over RPC to build it; pass `existingRules` to supply them yourself instead (useful offline). `authorityScan: null` means NOT CHECKED - the read failed, or it could not account for every live rule - and must never be read as "nothing found". The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). Only CALL 1 is emitted; the interpreter `install` follow-up needs the rule id the account assigns in call 1 and is documented in `followUp` in the response.', InstallPolicyToolShape, (args) => runInstallPolicy(args).then(toCallToolResult));
+    server.tool('install_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. Name the rule ONE of three ways. `fromPredicate: { encodedPredicate, signers }` installs a predicate you already hold - the base64 string `declare_policy` returns - and scopes the rule to whatever contract that predicate pins. `fromHash: { transactionHash, signers }` - with `fromHash` the server re-synthesizes the rule from the recording itself, and `signers` (plain G.../C... addresses) names the keys the rule governs. Naming them is required: synthesis reads a transaction and cannot decide which keys a rule binds, and a rule that governs no key is refused on chain. `rule` is the full ContextRuleDraft and is for programmatic callers only - retyping it loses the types of `validUntilLedger`, `signers` and `policies`. In BOTH handle forms `signers` is a list of plain Stellar account addresses (G...): a delegated signer is an account, NOT a deployed signer contract, and nothing needs to be deployed to name one. The response carries an `authorityScan`: every rule already on the account that a signer of this install could name INSTEAD, including an unpoliced one against which the predicate never runs - a predicate only constrains a key when the policed rule is the only rule that key is on. The account is READ over RPC to build it; pass `existingRules` to supply them yourself instead (useful offline). `authorityScan: null` means NOT CHECKED - the read failed, or it could not account for every live rule - and must never be read as "nothing found". The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). `installNonce` defaults to 1, which is correct for a fresh rule - do not ask the caller for it. If the recorded call spends an amount and no `limitAmount` is given, the install is REFUSED: such a rule would constrain everything about the call except how much it moves, and it would install and verify cleanly while capping nothing. Supply `fromHash.userResponses.limitAmount`, or `allowUnboundedAmount: true` to do it deliberately. For a ROLLING TOTAL - "at most N per day" - pass `spendingLimit: { amount, periodLedgers }`. It attaches an OpenZeppelin `spending_limit` beside the predicate on the same rule, and both must permit. A predicate alone CANNOT express a rolling total: the interpreter is handed one call and keeps no state, so a per-call cap of N authorises N again on the very next call. The window counts LEDGERS (about five seconds each), and the rule must be scoped to the token contract whose transfers it meters. One transaction is all it takes: the smart account calls the interpreter `install` itself while running `add_context_rule`, so once this XDR is signed and submitted the rule is live and the predicate is enforced. The rule id the account assigned is in the transaction result. Do not tell the caller a second call is outstanding.', InstallPolicyToolShape, (args) => runInstallPolicy(args).then(toCallToolResult));
     server.tool('revoke_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.remove_context_rule(ruleId)` that removes a policy rule from the given smart account. The smart account handles uninstalling each attached policy itself. Auth is master-only - the source account MUST be the master signer set; delegated signers cannot uninstall.', RevokePolicyToolShape, (args) => runRevokePolicy(args).then(toCallToolResult));
     server.tool('get_interpreter_info', 'Read-only fingerprint lookup for the policy interpreter contract: returns the pinned address, grammar version, and wasm sha256 (from the pinned constants + SELF_VERSION). When `verifyLive=true`, performs an additional `grammar_version()` RPC call against the pinned address and reports whether the deployed contract matches the pin - a live mismatch check is more useful than a fabricated audit field.', GetInterpreterInfoToolShape, (args) => runGetInterpreterInfo(args).then(toCallToolResult));
 }

package/dist-cjs/src/schemas.d.ts

@@ -274,6 +274,7 @@ export declare const SynthesizePolicyToolShape: {
         }>;
         sourceAccount: z.ZodString;
     }, z.ZodTypeAny, "passthrough">>>;
+    readonly transactionHash: z.ZodOptional<z.ZodString>;
     readonly network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;
     readonly userResponses: z.ZodOptional<z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
@@ -308,8 +309,9 @@ export declare const SynthesizePolicyToolShape: {
     readonly explain: z.ZodOptional<z.ZodBoolean>;
 };
 export declare const SimulatePolicyToolShape: {
-    readonly predicate: z.ZodType<unknown, z.ZodTypeDef, unknown>;
-    readonly permitTx: z.ZodObject<{
+    readonly predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    readonly encodedPredicate: z.ZodOptional<z.ZodString>;
+    readonly permitTx: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
         signers: z.ZodArray<z.ZodString, "many">;
         invocations: z.ZodArray<z.ZodType<unknown, z.ZodTypeDef, unknown>, "many">;
@@ -567,12 +569,29 @@ export declare const SimulatePolicyToolShape: {
             thresholdUsed: number;
         }>;
         sourceAccount: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    readonly transactionHash: z.ZodOptional<z.ZodString>;
+    readonly network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly userResponses: z.ZodOptional<z.ZodObject<{
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+        limitAmount: z.ZodOptional<z.ZodString>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }>>;
     readonly validUntilLedger: z.ZodOptional<z.ZodNumber>;
 };
 export declare const VerifyPolicyToolShape: {
-    readonly predicate: z.ZodType<unknown, z.ZodTypeDef, unknown>;
-    readonly permitTx: z.ZodObject<{
+    readonly predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    readonly encodedPredicate: z.ZodOptional<z.ZodString>;
+    readonly permitTx: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
         signers: z.ZodArray<z.ZodString, "many">;
         invocations: z.ZodArray<z.ZodType<unknown, z.ZodTypeDef, unknown>, "many">;
@@ -830,7 +849,23 @@ export declare const VerifyPolicyToolShape: {
             thresholdUsed: number;
         }>;
         sourceAccount: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    readonly transactionHash: z.ZodOptional<z.ZodString>;
+    readonly network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly userResponses: z.ZodOptional<z.ZodObject<{
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+        limitAmount: z.ZodOptional<z.ZodString>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }, {
+        limitAmount?: string | undefined;
+        validUntilLedger?: number | undefined;
+        swapRecipientAllowlist?: string[] | undefined;
+    }>>;
     readonly validUntilLedger: z.ZodOptional<z.ZodNumber>;
 };
 export type { GetInterpreterInfoInput, InstallPolicyInput, RevokePolicyInput, SimulatePolicyInput, VerifyPolicyInput, } from '@crediolabs/policy-synth/run';
@@ -891,7 +926,67 @@ export declare const InstallPolicyToolShape: {
      *  "not checked" rather than "nothing found". */
     readonly existingRules: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
     readonly rule: z.ZodOptional<z.ZodUnknown>;
+    readonly fromPredicate: z.ZodOptional<z.ZodObject<{
+        encodedPredicate: z.ZodString;
+        signers: z.ZodArray<z.ZodString, "many">;
+        name: z.ZodOptional<z.ZodString>;
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        signers: string[];
+        encodedPredicate: string;
+        name?: string | undefined;
+        validUntilLedger?: number | undefined;
+    }, {
+        signers: string[];
+        encodedPredicate: string;
+        name?: string | undefined;
+        validUntilLedger?: number | undefined;
+    }>>;
+    readonly fromHash: z.ZodOptional<z.ZodObject<{
+        transactionHash: z.ZodString;
+        signers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        userResponses: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            limitAmount: z.ZodOptional<z.ZodString>;
+            swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        }, {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        transactionHash: string;
+        signers?: string[] | undefined;
+        userResponses?: {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        } | undefined;
+    }, {
+        transactionHash: string;
+        signers?: string[] | undefined;
+        userResponses?: {
+            limitAmount?: string | undefined;
+            validUntilLedger?: number | undefined;
+            swapRecipientAllowlist?: string[] | undefined;
+        } | undefined;
+    }>>;
     readonly installNonce: z.ZodOptional<z.ZodNumber>;
+    readonly spendingLimit: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        periodLedgers: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        periodLedgers: number;
+    }, {
+        amount: string;
+        periodLedgers: number;
+    }>>;
+    readonly allowUnboundedAmount: z.ZodOptional<z.ZodBoolean>;
     readonly interpreterAddress: z.ZodOptional<z.ZodString>;
     readonly smartAccount: z.ZodOptional<z.ZodString>;
     readonly sourceAccount: z.ZodOptional<z.ZodString>;

package/dist-cjs/src/schemas.js

@@ -50,7 +50,12 @@ exports.RecordTransactionToolShape = {
  *  re-validates against the strict schema. */
 exports.SynthesizePolicyToolShape = {
     source: zod_1.z.literal('recording').optional(),
+    // Supply EITHER `recordedTx` (the whole recording) OR `transactionHash`. An agent
+    // should prefer the hash: it cannot copy a multi-thousand-character recording back out
+    // of its own transcript without losing fields, and the server can re-record
+    // from the hash deterministically.
     recordedTx: run_1.RecordedTransactionSchema.optional(),
+    transactionHash: zod_1.z.string().optional(),
     network: run_1.NetworkSchema.optional(),
     userResponses: run_1.ComposeUserResponsesSchema.optional(),
     confidenceOverride: zod_1.z.object({ threshold: zod_1.z.number().min(0).max(1) }).optional(),
@@ -68,8 +73,21 @@ exports.SynthesizePolicyToolShape = {
  *  (from `synthesize_policy` under `explain`) plus the recording it was
  *  synthesised from. */
 const PolicyCheckToolShape = {
-    predicate: run_1.PredicateNodeSchema,
-    permitTx: run_1.RecordedTransactionSchema,
+    // Supply EITHER `transactionHash` OR both `predicate` and `permitTx`. The tree comes
+    // back from `synthesize_policy` only under `explain`, so a caller who did not
+    // ask for it has nothing to pass and would skip the check - and this IS the
+    // check. `transactionHash` lets the server rebuild both from the transaction.
+    predicate: run_1.PredicateNodeSchema.optional(),
+    // The canonical encoding `declare_policy` and `synthesize_policy` both
+    // return. One opaque string, where the tree is what callers mistype.
+    encodedPredicate: zod_1.z.string().optional(),
+    permitTx: run_1.RecordedTransactionSchema.optional(),
+    transactionHash: zod_1.z.string().optional(),
+    network: run_1.NetworkSchema.optional(),
+    // Needed with `transactionHash`: the predicate is lowered against the account it will
+    // be installed on.
+    smartAccount: zod_1.z.string().optional(),
+    userResponses: run_1.ComposeUserResponsesSchema.optional(),
     validUntilLedger: zod_1.z.number().int().positive().optional(),
 };
 exports.SimulatePolicyToolShape = { ...PolicyCheckToolShape };
@@ -135,8 +153,46 @@ exports.InstallPolicyToolShape = {
      *  authority scan; omitting them returns `authorityScan: null`, which means
      *  "not checked" rather than "nothing found". */
     existingRules: zod_1.z.array(zod_1.z.unknown()).optional(),
+    // Supply EITHER `rule` (the whole ContextRuleDraft) OR `fromHash`. Same
+    // reason as `synthesize_policy`: a draft nests i128 strings, a signer array
+    // and a policy array, and an agent retyping it out of its own transcript
+    // loses their types. `fromHash` re-derives the draft server-side from the
+    // recording, so the install runs against the rule the synthesizer produced.
     rule: zod_1.z.unknown().optional(),
+    // Install a predicate you already hold - the base64 string `declare_policy`
+    // returns - naming the keys it governs as plain account addresses. Without
+    // this there is no route from `declare_policy` to here.
+    fromPredicate: zod_1.z
+        .object({
+        encodedPredicate: zod_1.z.string(),
+        signers: zod_1.z.array(zod_1.z.string()),
+        name: zod_1.z.string().optional(),
+        validUntilLedger: zod_1.z.number().int().positive().optional(),
+    })
+        .optional(),
+    fromHash: zod_1.z
+        .object({
+        transactionHash: zod_1.z.string(),
+        // The keys the rule governs, as plain Stellar addresses. Synthesis does
+        // not choose them, and a rule governing no key is refused on chain.
+        signers: zod_1.z.array(zod_1.z.string()).optional(),
+        userResponses: run_1.ComposeUserResponsesSchema.optional(),
+    })
+        .optional(),
     installNonce: zod_1.z.number().int().positive().optional(),
+    // A ROLLING TOTAL beside the per-call predicate, as an OpenZeppelin
+    // spending_limit on the same rule. Both must permit. This is the only way to
+    // express "N per day": the interpreter is handed one call and keeps no state.
+    spendingLimit: zod_1.z
+        .object({
+        amount: zod_1.z.string(),
+        periodLedgers: zod_1.z.number().int().positive(),
+    })
+        .optional(),
+    // Opt-in to installing a rule that bounds no amount when the recording showed
+    // a spend. Default-deny: such a rule installs and verifies cleanly and caps
+    // nothing.
+    allowUnboundedAmount: zod_1.z.boolean().optional(),
     interpreterAddress: zod_1.z.string().optional(),
 };
 /** Flat ZodRawShape for `revoke_policy`. */

package/dist-cjs/src/server.js

@@ -26,18 +26,22 @@ const toCallToolResult = (res) => (0, result_ts_1.mcpResultFromCore)(res);
 /** Build a fresh, stateless MCP server. The caller owns the returned object
  *  and connects it to a single transport (stdio or Streamable HTTP). */
 function createMcpServer() {
-    const server = new mcp_js_1.McpServer({ name: 'policy-builder-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+    const server = new mcp_js_1.McpServer(
+    // Kept in step with package.json by `server-version.test.ts`. It was
+    // hardcoded once already and reported 0.0.0 to every client; a literal is
+    // fine, a literal nothing checks is not.
+    { name: 'policy-builder-mcp', version: '1.1.0' }, { capabilities: { tools: {} } });
     registerTools(server);
     return server;
 }
 /** Idempotent registration of the T1 tool set on the given server. */
 function registerTools(server) {
     server.tool('record_transaction', 'Decode a Soroban transaction (on-chain hash OR base64 envelope XDR) into a RecordedTransaction. Returns a machine-readable ToolError on validation failure.', schemas_ts_1.RecordTransactionToolShape, (args) => (0, run_1.runRecordTransaction)(args).then(toCallToolResult));
-    server.tool('synthesize_policy', 'Synthesize a ProposedPolicy from a RecordedTransaction (`source: recording`).', schemas_ts_1.SynthesizePolicyToolShape, (args) => (0, run_1.runSynthesizePolicy)(args).then(toCallToolResult));
-    server.tool('simulate_policy', 'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass the `predicate` returned by `synthesize_policy` under `explain`.', schemas_ts_1.SimulatePolicyToolShape, (args) => toCallToolResult((0, run_1.runSimulatePolicy)(args)));
-    server.tool('verify_policy', 'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose.', schemas_ts_1.VerifyPolicyToolShape, (args) => toCallToolResult((0, run_1.runVerifyPolicy)(args)));
+    server.tool('synthesize_policy', 'Synthesize a ProposedPolicy from a recorded transaction (`source: recording`). Pass `transactionHash` and `network` to have the server re-record and synthesize in one step - prefer this over copying a `recordedTx` payload back out of a previous tool result, which loses fields. `recordedTx` remains accepted for programmatic callers holding the object.', schemas_ts_1.SynthesizePolicyToolShape, (args) => (0, run_1.runSynthesizePolicy)(args).then(toCallToolResult));
+    server.tool('simulate_policy', 'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass `transactionHash` with `smartAccount` and the server records and synthesizes the predicate itself; or pass a predicate together with the call to check it against. For a predicate you already hold, pass `encodedPredicate` (the base64 string `declare_policy` and `synthesize_policy` return) rather than retyping the `predicate` tree.', schemas_ts_1.SimulatePolicyToolShape, (args) => (0, run_1.runSimulatePolicy)(args).then(toCallToolResult));
+    server.tool('verify_policy', 'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose. Pass `transactionHash` with `smartAccount` and the server rebuilds the predicate and the recording itself; For a predicate you already hold - a DECLARED one has no recording behind it, so re-synthesizing would check something else - pass `encodedPredicate` (the base64 string) with `transactionHash`. Retyping the `predicate` tree is the error-prone path; do not take it, and never skip this check because the tree was not to hand.', schemas_ts_1.VerifyPolicyToolShape, (args) => (0, run_1.runVerifyPolicy)(args).then(toCallToolResult));
     server.tool('declare_policy', "Build an interpreter predicate from a DECLARED constraint - the method to pin, and optionally the contract, a per-call amount cap, a recipient allowlist, and a minimum-output ratio (a swap slippage floor, bounding the output argument against the call's own input). Use this when there is no transaction to record, or when `record_transaction` refuses a contract it does not recognise. Returns the predicate tree, its canonical encoding and hash, ready for `install_policy`. `warnings` names any argument index that was GUESSED rather than supplied - a bound on the wrong argument constrains nothing while looking correct, so read them. There is no rolling spend window and no approval threshold: neither is expressible in grammar 4, and both belong to the OpenZeppelin account layer.", schemas_ts_1.DeclarePolicyToolShape, (args) => Promise.resolve((0, run_1.runDeclarePolicy)(args)).then(toCallToolResult));
-    server.tool('install_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. The response carries an `authorityScan`: every rule already on the account that a signer of this install could name INSTEAD, including an unpoliced one against which the predicate never runs - a predicate only constrains a key when the policed rule is the only rule that key is on. The account is READ over RPC to build it; pass `existingRules` to supply them yourself instead (useful offline). `authorityScan: null` means NOT CHECKED - the read failed, or it could not account for every live rule - and must never be read as "nothing found". The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). Only CALL 1 is emitted; the interpreter `install` follow-up needs the rule id the account assigns in call 1 and is documented in `followUp` in the response.', schemas_ts_1.InstallPolicyToolShape, (args) => (0, run_1.runInstallPolicy)(args).then(toCallToolResult));
+    server.tool('install_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. Name the rule ONE of three ways. `fromPredicate: { encodedPredicate, signers }` installs a predicate you already hold - the base64 string `declare_policy` returns - and scopes the rule to whatever contract that predicate pins. `fromHash: { transactionHash, signers }` - with `fromHash` the server re-synthesizes the rule from the recording itself, and `signers` (plain G.../C... addresses) names the keys the rule governs. Naming them is required: synthesis reads a transaction and cannot decide which keys a rule binds, and a rule that governs no key is refused on chain. `rule` is the full ContextRuleDraft and is for programmatic callers only - retyping it loses the types of `validUntilLedger`, `signers` and `policies`. In BOTH handle forms `signers` is a list of plain Stellar account addresses (G...): a delegated signer is an account, NOT a deployed signer contract, and nothing needs to be deployed to name one. The response carries an `authorityScan`: every rule already on the account that a signer of this install could name INSTEAD, including an unpoliced one against which the predicate never runs - a predicate only constrains a key when the policed rule is the only rule that key is on. The account is READ over RPC to build it; pass `existingRules` to supply them yourself instead (useful offline). `authorityScan: null` means NOT CHECKED - the read failed, or it could not account for every live rule - and must never be read as "nothing found". The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). `installNonce` defaults to 1, which is correct for a fresh rule - do not ask the caller for it. If the recorded call spends an amount and no `limitAmount` is given, the install is REFUSED: such a rule would constrain everything about the call except how much it moves, and it would install and verify cleanly while capping nothing. Supply `fromHash.userResponses.limitAmount`, or `allowUnboundedAmount: true` to do it deliberately. For a ROLLING TOTAL - "at most N per day" - pass `spendingLimit: { amount, periodLedgers }`. It attaches an OpenZeppelin `spending_limit` beside the predicate on the same rule, and both must permit. A predicate alone CANNOT express a rolling total: the interpreter is handed one call and keeps no state, so a per-call cap of N authorises N again on the very next call. The window counts LEDGERS (about five seconds each), and the rule must be scoped to the token contract whose transfers it meters. One transaction is all it takes: the smart account calls the interpreter `install` itself while running `add_context_rule`, so once this XDR is signed and submitted the rule is live and the predicate is enforced. The rule id the account assigned is in the transaction result. Do not tell the caller a second call is outstanding.', schemas_ts_1.InstallPolicyToolShape, (args) => (0, run_1.runInstallPolicy)(args).then(toCallToolResult));
     server.tool('revoke_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.remove_context_rule(ruleId)` that removes a policy rule from the given smart account. The smart account handles uninstalling each attached policy itself. Auth is master-only - the source account MUST be the master signer set; delegated signers cannot uninstall.', schemas_ts_1.RevokePolicyToolShape, (args) => (0, run_1.runRevokePolicy)(args).then(toCallToolResult));
     server.tool('get_interpreter_info', 'Read-only fingerprint lookup for the policy interpreter contract: returns the pinned address, grammar version, and wasm sha256 (from the pinned constants + SELF_VERSION). When `verifyLive=true`, performs an additional `grammar_version()` RPC call against the pinned address and reports whether the deployed contract matches the pin - a live mismatch check is more useful than a fabricated audit field.', schemas_ts_1.GetInterpreterInfoToolShape, (args) => (0, run_1.runGetInterpreterInfo)(args).then(toCallToolResult));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-builder-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "description": "MCP server exposing the OZ policy-synth core (record_transaction + synthesize_policy) over stdio and Streamable HTTP transports.",
   "type": "module",
@@ -63,7 +63,7 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@crediolabs/policy-synth": "1.0.0",
+    "@crediolabs/policy-synth": "1.1.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@stellar/stellar-sdk": "14.4.0",
     "zod": "3.25.76"

package/src/schemas.ts

@@ -70,7 +70,12 @@ export const RecordTransactionToolShape = {
  *  re-validates against the strict schema. */
 export const SynthesizePolicyToolShape = {
   source: z.literal('recording').optional(),
+  // Supply EITHER `recordedTx` (the whole recording) OR `transactionHash`. An agent
+  // should prefer the hash: it cannot copy a multi-thousand-character recording back out
+  // of its own transcript without losing fields, and the server can re-record
+  // from the hash deterministically.
   recordedTx: RecordedTransactionSchema.optional(),
+  transactionHash: z.string().optional(),
   network: NetworkSchema.optional(),
   userResponses: ComposeUserResponsesSchema.optional(),
   confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
@@ -89,8 +94,21 @@ export const SynthesizePolicyToolShape = {
  *  (from `synthesize_policy` under `explain`) plus the recording it was
  *  synthesised from. */
 const PolicyCheckToolShape = {
-  predicate: PredicateNodeSchema,
-  permitTx: RecordedTransactionSchema,
+  // Supply EITHER `transactionHash` OR both `predicate` and `permitTx`. The tree comes
+  // back from `synthesize_policy` only under `explain`, so a caller who did not
+  // ask for it has nothing to pass and would skip the check - and this IS the
+  // check. `transactionHash` lets the server rebuild both from the transaction.
+  predicate: PredicateNodeSchema.optional(),
+  // The canonical encoding `declare_policy` and `synthesize_policy` both
+  // return. One opaque string, where the tree is what callers mistype.
+  encodedPredicate: z.string().optional(),
+  permitTx: RecordedTransactionSchema.optional(),
+  transactionHash: z.string().optional(),
+  network: NetworkSchema.optional(),
+  // Needed with `transactionHash`: the predicate is lowered against the account it will
+  // be installed on.
+  smartAccount: z.string().optional(),
+  userResponses: ComposeUserResponsesSchema.optional(),
   validUntilLedger: z.number().int().positive().optional(),
 } as const
 
@@ -168,8 +186,46 @@ export const InstallPolicyToolShape = {
    *  authority scan; omitting them returns `authorityScan: null`, which means
    *  "not checked" rather than "nothing found". */
   existingRules: z.array(z.unknown()).optional(),
+  // Supply EITHER `rule` (the whole ContextRuleDraft) OR `fromHash`. Same
+  // reason as `synthesize_policy`: a draft nests i128 strings, a signer array
+  // and a policy array, and an agent retyping it out of its own transcript
+  // loses their types. `fromHash` re-derives the draft server-side from the
+  // recording, so the install runs against the rule the synthesizer produced.
   rule: z.unknown().optional(),
+  // Install a predicate you already hold - the base64 string `declare_policy`
+  // returns - naming the keys it governs as plain account addresses. Without
+  // this there is no route from `declare_policy` to here.
+  fromPredicate: z
+    .object({
+      encodedPredicate: z.string(),
+      signers: z.array(z.string()),
+      name: z.string().optional(),
+      validUntilLedger: z.number().int().positive().optional(),
+    })
+    .optional(),
+  fromHash: z
+    .object({
+      transactionHash: z.string(),
+      // The keys the rule governs, as plain Stellar addresses. Synthesis does
+      // not choose them, and a rule governing no key is refused on chain.
+      signers: z.array(z.string()).optional(),
+      userResponses: ComposeUserResponsesSchema.optional(),
+    })
+    .optional(),
   installNonce: z.number().int().positive().optional(),
+  // A ROLLING TOTAL beside the per-call predicate, as an OpenZeppelin
+  // spending_limit on the same rule. Both must permit. This is the only way to
+  // express "N per day": the interpreter is handed one call and keeps no state.
+  spendingLimit: z
+    .object({
+      amount: z.string(),
+      periodLedgers: z.number().int().positive(),
+    })
+    .optional(),
+  // Opt-in to installing a rule that bounds no amount when the recording showed
+  // a spend. Default-deny: such a rule installs and verifies cleanly and caps
+  // nothing.
+  allowUnboundedAmount: z.boolean().optional(),
   interpreterAddress: z.string().optional(),
 } as const
 

package/src/server.ts

@@ -48,7 +48,10 @@ const toCallToolResult = <T>(
  *  and connects it to a single transport (stdio or Streamable HTTP). */
 export function createMcpServer(): McpServer {
   const server = new McpServer(
-    { name: 'policy-builder-mcp', version: '1.0.0' },
+    // Kept in step with package.json by `server-version.test.ts`. It was
+    // hardcoded once already and reported 0.0.0 to every client; a literal is
+    // fine, a literal nothing checks is not.
+    { name: 'policy-builder-mcp', version: '1.1.0' },
     { capabilities: { tools: {} } }
   )
   registerTools(server)
@@ -66,23 +69,23 @@ export function registerTools(server: McpServer): void {
 
   server.tool(
     'synthesize_policy',
-    'Synthesize a ProposedPolicy from a RecordedTransaction (`source: recording`).',
+    'Synthesize a ProposedPolicy from a recorded transaction (`source: recording`). Pass `transactionHash` and `network` to have the server re-record and synthesize in one step - prefer this over copying a `recordedTx` payload back out of a previous tool result, which loses fields. `recordedTx` remains accepted for programmatic callers holding the object.',
     SynthesizePolicyToolShape,
     (args) => runSynthesizePolicy(args).then(toCallToolResult)
   )
 
   server.tool(
     'simulate_policy',
-    'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass the `predicate` returned by `synthesize_policy` under `explain`.',
+    'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass `transactionHash` with `smartAccount` and the server records and synthesizes the predicate itself; or pass a predicate together with the call to check it against. For a predicate you already hold, pass `encodedPredicate` (the base64 string `declare_policy` and `synthesize_policy` return) rather than retyping the `predicate` tree.',
     SimulatePolicyToolShape,
-    (args) => toCallToolResult(runSimulatePolicy(args))
+    (args) => runSimulatePolicy(args).then(toCallToolResult)
   )
 
   server.tool(
     'verify_policy',
-    'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose.',
+    'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose. Pass `transactionHash` with `smartAccount` and the server rebuilds the predicate and the recording itself; For a predicate you already hold - a DECLARED one has no recording behind it, so re-synthesizing would check something else - pass `encodedPredicate` (the base64 string) with `transactionHash`. Retyping the `predicate` tree is the error-prone path; do not take it, and never skip this check because the tree was not to hand.',
     VerifyPolicyToolShape,
-    (args) => toCallToolResult(runVerifyPolicy(args))
+    (args) => runVerifyPolicy(args).then(toCallToolResult)
   )
 
   server.tool(
@@ -94,7 +97,7 @@ export function registerTools(server: McpServer): void {
 
   server.tool(
     'install_policy',
-    'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. The response carries an `authorityScan`: every rule already on the account that a signer of this install could name INSTEAD, including an unpoliced one against which the predicate never runs - a predicate only constrains a key when the policed rule is the only rule that key is on. The account is READ over RPC to build it; pass `existingRules` to supply them yourself instead (useful offline). `authorityScan: null` means NOT CHECKED - the read failed, or it could not account for every live rule - and must never be read as "nothing found". The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). Only CALL 1 is emitted; the interpreter `install` follow-up needs the rule id the account assigns in call 1 and is documented in `followUp` in the response.',
+    'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. Name the rule ONE of three ways. `fromPredicate: { encodedPredicate, signers }` installs a predicate you already hold - the base64 string `declare_policy` returns - and scopes the rule to whatever contract that predicate pins. `fromHash: { transactionHash, signers }` - with `fromHash` the server re-synthesizes the rule from the recording itself, and `signers` (plain G.../C... addresses) names the keys the rule governs. Naming them is required: synthesis reads a transaction and cannot decide which keys a rule binds, and a rule that governs no key is refused on chain. `rule` is the full ContextRuleDraft and is for programmatic callers only - retyping it loses the types of `validUntilLedger`, `signers` and `policies`. In BOTH handle forms `signers` is a list of plain Stellar account addresses (G...): a delegated signer is an account, NOT a deployed signer contract, and nothing needs to be deployed to name one. The response carries an `authorityScan`: every rule already on the account that a signer of this install could name INSTEAD, including an unpoliced one against which the predicate never runs - a predicate only constrains a key when the policed rule is the only rule that key is on. The account is READ over RPC to build it; pass `existingRules` to supply them yourself instead (useful offline). `authorityScan: null` means NOT CHECKED - the read failed, or it could not account for every live rule - and must never be read as "nothing found". The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). `installNonce` defaults to 1, which is correct for a fresh rule - do not ask the caller for it. If the recorded call spends an amount and no `limitAmount` is given, the install is REFUSED: such a rule would constrain everything about the call except how much it moves, and it would install and verify cleanly while capping nothing. Supply `fromHash.userResponses.limitAmount`, or `allowUnboundedAmount: true` to do it deliberately. For a ROLLING TOTAL - "at most N per day" - pass `spendingLimit: { amount, periodLedgers }`. It attaches an OpenZeppelin `spending_limit` beside the predicate on the same rule, and both must permit. A predicate alone CANNOT express a rolling total: the interpreter is handed one call and keeps no state, so a per-call cap of N authorises N again on the very next call. The window counts LEDGERS (about five seconds each), and the rule must be scoped to the token contract whose transfers it meters. One transaction is all it takes: the smart account calls the interpreter `install` itself while running `add_context_rule`, so once this XDR is signed and submitted the rule is live and the predicate is enforced. The rule id the account assigned is in the transaction result. Do not tell the caller a second call is outstanding.',
     InstallPolicyToolShape,
     (args) => runInstallPolicy(args).then(toCallToolResult)
   )