portage-ucp 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36c3a77e9f625761b827d1e925d54217b7bff302f4a7a60540d4a8c5d1794fb9
-  data.tar.gz: 05a86e2740a327c63bb0e06aa450e2aa5207aa60ce637575133483ed8df4698b
+  metadata.gz: 11276545531e50962e8e16e8d1c966853adfa8ddb8c1aa3851f7fa89a494b33e
+  data.tar.gz: 7421a957575b40d55200ce54e70335bec9a7c7a735cd0941eb2e1bdec0bdd535
 SHA512:
-  metadata.gz: d0d4746f829e60009463ee2748ba5c46ff6f3932b5a345f3f26d94e437a5132b39002945bf19abe1ee3d02c46e1760b52afa6910a15531df494c4e39dcca7787
-  data.tar.gz: 60898e67d72f545c24970415775506be4930336a4f325be61714cef0f810547f77b79951f7b48e3fb32b72cdd9adb9669b4f3af4f872be0a4bcb7ea60b325bf5
+  metadata.gz: 52d85b70ca4e16311c318331bb0ca161c82ff9f833e4d08b5c3e262550ecaeccf334aaf35cf5e39f5a351e3a5aa58ed0a508615003c1da6d54d728a9dc34eda9
+  data.tar.gz: 05e158b1864ae760e08ddb3ab76080a1effd59bfa475ebd64e23f0f2e30f6ff87b4afe44eef0112ca5dda0a6e579e64532df396743cab582373f90e44805b089

data/CHANGELOG.md

@@ -6,6 +6,56 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-14
+
+- Added `Adapter#create_payment_enrollment(idempotency_key:)` /
+  `#get_payment_enrollment(enrollment_id:)`, advertised as a new
+  `app.portage-ucp.payment_enrollment` capability — a Portage extension, not
+  part of the UCP spec. Starts a card-on-file enrollment without the card
+  ever touching this process: `#create_payment_enrollment` returns a
+  gateway-hosted `setup_url`, and the caller polls `#get_payment_enrollment`
+  until `status` leaves `"pending"` and a `payment_token` appears.
+  Implemented in `ReferenceAdapter` as a worked example (docs/plans/agentic-payments.md
+  Phase 1).
+- Made the idempotency dedup store pluggable — `Support::Idempotency` now
+  takes a `store:` (defaulting to the existing in-memory behavior via the new
+  `MemoryStore`), with a `FileStore` alternative for dedup that survives a
+  process restart.
+- Added a durable `Support::TransactionLog`, wired into
+  `Dispatcher#complete_checkout` dispatch — a transaction is reserved before
+  dispatch and marked settled/failed after, so a crash mid-charge leaves a
+  diagnosable record instead of silence.
+- Extended `TransactionLog` to also record policy decisions and confirmation
+  outcomes on the same transaction record `PolicyGuard`/`Confirmer` gate.
+- Added `PolicyGuard`, wired into `Dispatcher` just before `complete_checkout`
+  dispatch — enforces `Policy`'s per-transaction/rolling caps, velocity, and
+  merchant allowlist (docs/plans/agentic-payments.md Phase 2). Configured via
+  `portage-cli`'s `portage policy show/set`.
+- Added per-token enrollment scopes to `Policy` — a merchant/max-amount/
+  currency scope can be bound to a token at enrollment time and is checked by
+  `PolicyGuard` keyed by the same `token_ref` derived from the token at
+  charge time.
+- Added a `Confirmer` interface, wired into `Dispatcher` right after
+  `PolicyGuard.check!` passes and before `complete_checkout` dispatch.
+  `Confirmer::Terminal` blocks the process on stdin and fails closed on
+  anything but an explicit `"y"` (no answer, `"n"`, or EOF all deny);
+  `Confirmer::AutoApprove` is for specs/conformance kits (docs/plans/agentic-payments.md
+  Phase 3).
+- Added a durable `Support::OrderLedger`, wired into the `complete_checkout`
+  settle path — written after the transaction record is already complete, so
+  a failed snapshot write surfaces without flipping an already-settled charge
+  to failed.
+- `Mcp::Server.call_tool` now extracts `ucp-agent.profile` from `_meta` the
+  same way it already does `correlation_id` from `traceparent`, logging/
+  forwarding it as `agent_profile` through every transport (http, stdio,
+  loopback) and `Client::Session`. Additive only — `Dispatcher` accepts and
+  threads it without yet acting on it.
+- Added `Adapter#lookup_catalog(ids:)`, advertised alongside `search_catalog`
+  — fetches several known product ids in one round trip instead of one
+  `get_product` call per id. Implemented in `Shopify::Adapter` via the Admin
+  API's `nodes(ids:)` field, reusing the same `Mapper.product` shape
+  `get_product`/`search_catalog` already use.
+
 ## [0.4.0] - 2026-08-28
 
 - Added `Adapter#reorder(order_id:, idempotency_key:)`, advertised as a new

data/README.md

@@ -25,6 +25,10 @@ in this gem.
 | `Portage::Ucp::Rack::WebhookEndpoint` | HMAC-verified inbound order-lifecycle webhooks. |
 | `Portage::Ucp::SchemaValidator` | Validates data against UCP's own vendored JSON Schemas/OpenRPC docs, offline. |
 | `Portage::Ucp::Resolver` / `exe/portage-ucp-check` | Probes any store's homepage/`.well-known/ucp` and recommends the matching adapter gem. |
+| `Portage::Ucp::Support::TransactionLog` | Durable pre/post-dispatch record of every `complete_checkout` call — reserved before dispatch, marked settled/failed after, so a crash mid-charge is diagnosable rather than silently lost. |
+| `Portage::Ucp::Support::OrderLedger` | Durable snapshot written after settlement, alongside (not instead of) the transaction record — a failed snapshot write surfaces without flipping an already-settled charge to failed. |
+| `Portage::Ucp::Confirmer` | Gate run just before `complete_checkout` dispatch, after `PolicyGuard`. `Confirmer::Terminal` blocks on stdin and fails closed on anything but an explicit `"y"`; `Confirmer::AutoApprove` is for specs/conformance kits that need a real `confirm!` without blocking. |
+| `Portage::Ucp::PolicyGuard` / `Portage::Ucp::Policy` | Per-transaction/rolling/velocity caps and a merchant allowlist, checked before `complete_checkout` dispatch; configured via `portage-cli`'s `portage policy show/set`. |
 
 Security defaults are all locked down, not permissive-by-omission —
 `UnconfiguredAuthenticator` rejects every mutating call until you configure a real

data/lib/portage/ucp/adapter.rb

@@ -10,6 +10,11 @@ module Portage
       # get_cart/get_checkout/get_order.
       # @return [Portage::Ucp::ProductDetail, nil]
       def get_product(product_id:) = not_implemented
+      # Batch fetch — same result shape as search_catalog, for a caller that
+      # already has a set of product ids (e.g. hydrating a cart/order) and
+      # wants one round trip instead of N #get_product calls.
+      # @return [Portage::Ucp::CatalogSearchResult]
+      def lookup_catalog(product_ids:) = not_implemented
 
       # --- Cart (dev.ucp.shopping.cart) ---
       # Full-replacement semantics, matching UCP's real cart methods: create/
@@ -123,6 +128,18 @@ module Portage
       # @return [Portage::Ucp::Identity] linked profile for an exchanged OAuth token
       def link_identity(oauth_token:) = not_implemented
 
+      # --- Payment Enrollment (app.portage-ucp.payment_enrollment — Portage
+      # extension, not part of the UCP spec) ---
+      # Starts a card-on-file enrollment. Card data never touches this
+      # process: #create_payment_enrollment returns a `setup_url` for a
+      # gateway-hosted page where the human enters their card, and the
+      # caller polls #get_payment_enrollment until `status` leaves
+      # "pending". See docs/plans/agentic-payments.md Phase 1.
+      # @return [Portage::Ucp::PaymentEnrollment]
+      def create_payment_enrollment(idempotency_key:) = not_implemented
+      # @return [Portage::Ucp::PaymentEnrollment, nil] nil if the enrollment isn't found
+      def get_payment_enrollment(enrollment_id:) = not_implemented
+
       private
 
       def not_implemented

data/lib/portage/ucp/capabilities/catalog.rb

@@ -4,7 +4,8 @@ module Portage
       CATALOG = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.catalog",
         version: "1",
-        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product }
+        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product,
+                   "lookup_catalog" => :lookup_catalog }
       )
     end
   end

data/lib/portage/ucp/capabilities/identity_linking.rb

@@ -7,7 +7,8 @@ module Portage
         actions: { "link_identity" => :link_identity }
       )
 
-      ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, REORDER].freeze
+      ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, REORDER,
+             PAYMENT_ENROLLMENT].freeze
     end
   end
 end

data/lib/portage/ucp/capabilities/payment_enrollment.rb

@@ -0,0 +1,17 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec (no ucp.dev
+      # reverse-domain meaning to borrow), same posture as Capabilities::REORDER.
+      # Advertised only if the adapter overrides Adapter#create_payment_enrollment
+      # — an adapter with no real gateway support for it simply never shows it
+      # in the manifest (see docs/plans/agentic-payments.md Phase 1).
+      PAYMENT_ENROLLMENT = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.payment_enrollment",
+        version: "1",
+        actions: { "create_payment_enrollment" => :create_payment_enrollment,
+                  "get_payment_enrollment" => :get_payment_enrollment }
+      )
+    end
+  end
+end

data/lib/portage/ucp/confirmer.rb

@@ -0,0 +1,74 @@
+require "timeout"
+
+module Portage
+  module Ucp
+    # Phase 3 (docs/plans/agentic-payments.md) — the last gate before a
+    # payment-completing dispatch, run by Dispatcher right after PolicyGuard
+    # passes. Transport-agnostic by design: Dispatcher only ever calls
+    # `#confirm!(amount:, currency:, merchant:, idempotency_key:)` on
+    # whatever object it's given, so a future WhatsApp/Slack confirmer is a
+    # separate gem implementing the same method, no core change required.
+    # `idempotency_key` rides along even though this phase's Terminal
+    # implementation ignores it — an async transport needs it to bind a
+    # reply back to the request that asked.
+    module Confirmer
+      # Blocks the CLI process on stdin: "Approve? [y/N]". Fail-closed — no
+      # answer within `timeout_seconds` denies, same as an explicit "n",
+      # never leaves a payment pending on an agent that's still waiting.
+      # Checkout staleness while the operator was thinking isn't handled
+      # here: the confirmed amount is re-validated by nothing in this class,
+      # but the adapter call `call_adapter` makes right after this passes
+      # hits the real backend, which is the thing that'd reject a checkout
+      # that expired mid-wait — no separate re-check needed.
+      class Terminal
+        DEFAULT_TIMEOUT_SECONDS = 120
+
+        def initialize(timeout_seconds: DEFAULT_TIMEOUT_SECONDS, input: $stdin, output: $stdout)
+          @timeout_seconds = timeout_seconds
+          @input = input
+          @output = output
+        end
+
+        # @raise [Portage::Ucp::ConfirmationDeniedError] on "n", timeout, or
+        #   EOF (stdin closed out from under a headless run) — anything that
+        #   isn't an explicit "y" denies.
+        # @return [Hash] `{approved: true}` on "y".
+        def confirm!(amount:, currency:, merchant:, idempotency_key:)
+          @output.print("Approve payment of #{amount} #{currency} to #{merchant.inspect}? [y/N] ")
+          @output.flush
+
+          answer = read_with_timeout
+          return { approved: true } if answer&.strip&.downcase == "y"
+
+          deny!(answer.nil? ? :timeout : :denied, idempotency_key)
+        end
+
+        private
+
+        def read_with_timeout
+          Timeout.timeout(@timeout_seconds) { @input.gets }
+        rescue Timeout::Error
+          nil
+        end
+
+        def deny!(reason, idempotency_key)
+          message = reason == :timeout ? "confirmation timed out after #{@timeout_seconds}s" : "confirmation denied"
+          raise Portage::Ucp::ConfirmationDeniedError.new(
+            message, reason: reason, decision: { approved: false, reason: reason, idempotency_key: idempotency_key }
+          )
+        end
+      end
+
+      # Always approves. For adapter conformance suites and Dispatcher specs
+      # that need a real `confirm!` call to return without blocking on
+      # stdin — never wire this into a real Dispatcher: confirmation
+      # defaulting to *on* is the thing that makes Phase 1's permanently-
+      # spendable stored token safe (see plan, "No arm step").
+      class AutoApprove
+        def confirm!(**)
+          { approved: true }
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/dispatcher.rb

@@ -4,10 +4,42 @@ module Portage
     # through the CapabilityRegistry to the backing Adapter method, and wraps
     # the result as MCP's dual content/structuredContent output (see §5).
     class Dispatcher
-      def initialize(adapter:, registry: CapabilityRegistry.default, logger: Portage::Ucp.configuration.logger)
+      # The one action that moves money — see docs/plans/agentic-payments.md
+      # Phase 0. Gated by name, not capability, since `complete_checkout` is
+      # the only `dev.ucp.shopping.checkout` action that dispatches a charge.
+      PAYMENT_COMPLETING_ACTION = "complete_checkout".freeze
+
+      # @param shop [String, nil] identifies which store this Dispatcher
+      #   instance is completing charges for, threaded straight onto the
+      #   transaction log record — Dispatcher/Adapter have no shared notion
+      #   of shop identity today, so this is nil unless the caller passes one.
+      # @param transaction_log [Support::TransactionLog] reserve/commit
+      #   ledger for `complete_checkout` calls (Phase 0). Injectable so specs
+      #   don't write to the real `~/.portage/transactions.json`.
+      # @param policy [Policy] Phase 2 policy config PolicyGuard.check! reads
+      #   caps/velocity/allowlist/token-scope from. Injectable for the same
+      #   reason as `transaction_log` — defaulting to `Policy.load` would
+      #   have every spec read the real `~/.portage/policy.json`.
+      # @param confirmer [#confirm!] Phase 3 gate, run after PolicyGuard
+      #   passes, before dispatch. Defaults to `Confirmer::Terminal.new`
+      #   (blocks on stdin) — confirmation is on by default per the plan;
+      #   specs and conformance suites inject `Confirmer::AutoApprove.new`
+      #   instead so a run never blocks waiting on a human.
+      # @param order_ledger [Support::OrderLedger] settled-order snapshot
+      #   store (Phase 1, docs/plans/order-ledger.md). Injectable for the
+      #   same reason as `transaction_log` — defaults to the real
+      #   `~/.portage/orders.json`.
+      def initialize(adapter:, registry: CapabilityRegistry.default, logger: Portage::Ucp.configuration.logger,
+                     shop: nil, transaction_log: Support::TransactionLog.new, policy: Policy.load,
+                     confirmer: Confirmer::Terminal.new, order_ledger: Support::OrderLedger.new)
         @adapter = adapter
         @registry = registry
         @logger = logger
+        @shop = shop
+        @transaction_log = transaction_log
+        @policy = policy
+        @confirmer = confirmer
+        @order_ledger = order_ledger
       end
 
       # @param correlation_id [String, nil] threaded through to the adapter
@@ -18,7 +50,13 @@ module Portage
       #   Dispatcher.call is also the conformance kit's
       #   (lib/portage/ucp/rspec.rb) and specs' direct entry point, outside
       #   any MCP request (§23).
-      def call(capability:, action:, arguments: {}, correlation_id: nil)
+      # @param agent_profile [String, nil] caller-supplied `ucp-agent.profile`
+      #   hint from `_meta` (see Mcp::Server.agent_profile_for). Dispatcher
+      #   has no direct Observability.log call of its own to thread this
+      #   into — accepted here purely so callers that already pass
+      #   correlation_id: have a matching, equally optional slot; existing
+      #   callers that omit it are unaffected.
+      def call(capability:, action:, arguments: {}, correlation_id: nil, agent_profile: nil)
         capability_definition = @registry.find(capability)
         raise UnknownCapabilityError, capability if capability_definition.nil?
 
@@ -29,12 +67,119 @@ module Portage
 
         Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
 
-        result = call_adapter(method_name, arguments, correlation_id)
+        result = if action == PAYMENT_COMPLETING_ACTION
+                   call_and_log_transaction(method_name, arguments, correlation_id)
+                 else
+                   call_adapter(method_name, arguments, correlation_id)
+                 end
         wrap(capability, result)
       end
 
       private
 
+      # Reserve-then-commit around the one action that dispatches a charge:
+      # the `pending` record lands *before* `call_adapter` runs, so a crash
+      # during the adapter's own gateway round-trip leaves that record
+      # behind rather than nothing. `amount`/`currency` are unknown at
+      # reserve time (see TransactionLog#reserve) and filled in from the
+      # settled Checkout on success; a raised error settles the record
+      # `failed` before re-raising, never left dangling `pending`.
+      #
+      # PolicyGuard.check! (Phase 2), then the Confirmer (Phase 3), run
+      # after reserve, before dispatch — both need `amount`/`currency` to
+      # check the spend cap / show the operator a prompt, which means
+      # fetching the checkout via `@adapter.get_checkout` up front rather
+      # than waiting for the settled result `call_adapter` would otherwise
+      # provide after the charge already happened. A block or a deny never
+      # reaches `call_adapter` at all; a pass is recorded immediately so it
+      # survives a crash during the adapter round-trip, same reasoning as
+      # `reserve`.
+      def call_and_log_transaction(method_name, arguments, correlation_id)
+        idempotency_key = arguments.fetch(:idempotency_key)
+        token_ref = payment_token_ref(arguments[:payment_token])
+
+        result = settle(method_name, arguments, correlation_id, idempotency_key, token_ref)
+
+        # Snapshot AFTER `complete` inside `settle` above, never before/
+        # interleaved — opposite of `reserve`'s pre-dispatch posture.
+        # Deliberately OUTSIDE `settle`'s rescue: the money has already
+        # moved by this point, so if this write raises it must surface only
+        # after the transaction record is durably `complete` — a lost local
+        # history write must never flip a settled charge to `failed` or
+        # leave the transaction record ambiguous. Not every completed
+        # checkout produces an order (e.g. cart-only flows), so skip
+        # silently when absent.
+        @order_ledger.record(idempotency_key: idempotency_key, order: result.order) if result.order
+        result
+      end
+
+      def settle(method_name, arguments, correlation_id, idempotency_key, token_ref)
+        @transaction_log.reserve(idempotency_key: idempotency_key, shop: @shop,
+                                 checkout_id: arguments[:checkout_id], payment_token_ref: token_ref)
+
+        checkout = @adapter.get_checkout(checkout_id: arguments[:checkout_id])
+        gate!(idempotency_key, checkout, token_ref)
+
+        result = call_adapter(method_name, arguments, correlation_id)
+
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "complete",
+                                  amount: settled_amount(result), currency: settled_currency(result))
+        result
+      rescue StandardError
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "failed")
+        raise
+      end
+
+      # PolicyGuard (Phase 2) then Confirmer (Phase 3), in that order — both
+      # gate the same dispatch, and each phase records its own outcome on
+      # the transaction record as soon as it passes, per `reserve`'s
+      # crash-survives-as-evidence reasoning above.
+      def gate!(idempotency_key, checkout, token_ref)
+        decision = policy_check!(idempotency_key, checkout, token_ref)
+        @transaction_log.record_decision(idempotency_key: idempotency_key, policy_decision: decision)
+
+        confirmation = confirmation_check!(idempotency_key, checkout)
+        @transaction_log.record_confirmation(idempotency_key: idempotency_key, confirmation_outcome: confirmation)
+      end
+
+      def policy_check!(idempotency_key, checkout, token_ref)
+        Portage::Ucp::PolicyGuard.check!(amount: settled_amount(checkout), currency: settled_currency(checkout),
+                                         merchant: @shop, token_ref: token_ref, policy: @policy,
+                                         transaction_log: @transaction_log)
+      rescue Portage::Ucp::PolicyViolationError => e
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "failed", policy_decision: e.decision)
+        raise
+      end
+
+      def confirmation_check!(idempotency_key, checkout)
+        @confirmer.confirm!(amount: settled_amount(checkout), currency: settled_currency(checkout),
+                            merchant: @shop, idempotency_key: idempotency_key)
+      rescue Portage::Ucp::ConfirmationDeniedError => e
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "failed", confirmation_outcome: e.decision)
+        raise
+      end
+
+      # Never persists the payment token itself (single-use, still sensitive
+      # even though PaymentTokenGuard has already ruled out a raw PAN) — only
+      # a one-way reference an operator can correlate against, not replay.
+      def payment_token_ref(payment_token)
+        Support::TokenRef.for(payment_token)
+      end
+
+      def settled_amount(result)
+        return nil unless result.respond_to?(:totals)
+
+        # `Total#amount` is a bare integer minor-unit amount (the parent
+        # object's `currency` applies), not a Money struct — see
+        # value_objects.rb's Total/Item comments.
+        total = Array(result.totals).find { |t| t.type == "total" }
+        total&.amount
+      end
+
+      def settled_currency(result)
+        result.respond_to?(:currency) ? result.currency : nil
+      end
+
       def call_adapter(method_name, arguments, correlation_id)
         unless @adapter.is_a?(Portage::Ucp::Support::CheckoutState)
           return @adapter.public_send(method_name, **arguments)

data/lib/portage/ucp/errors.rb

@@ -38,5 +38,40 @@ module Portage
     # UCP's freeform "rate_limited" error code, same convention as
     # ConflictError above.
     class UpstreamThrottledError < Error; end
+
+    # Raised by PolicyGuard.check! (docs/plans/agentic-payments.md Phase 2)
+    # when a payment-completing dispatch fails a locally-configured guard —
+    # spend cap, velocity limit, merchant allowlist, or per-token scope.
+    # `reason` is a stable snake_case symbol (not just the message) so a
+    # caller can branch on *why* without parsing prose, matching
+    # OutOfStockError/ConflictError's freeform-error-code convention above.
+    # `decision` carries the same shape PolicyGuard.check! returns on
+    # success, so Dispatcher can persist "blocked, here's why" onto the
+    # Phase 0 transaction record the same way it persists a passing decision.
+    class PolicyViolationError < Error
+      attr_reader :reason, :decision
+
+      def initialize(message, reason:, decision:)
+        super(message)
+        @reason = reason
+        @decision = decision
+      end
+    end
+
+    # Raised by a Confirmer (docs/plans/agentic-payments.md Phase 3) when a
+    # payment-completing dispatch isn't approved — explicit "n", a timeout,
+    # or an async transport's own deny. Same reason/decision shape as
+    # PolicyViolationError above, for the same reasons: a stable symbol to
+    # branch on, and a decision Dispatcher persists onto the Phase 0
+    # transaction record via `confirmation_outcome`.
+    class ConfirmationDeniedError < Error
+      attr_reader :reason, :decision
+
+      def initialize(message, reason:, decision:)
+        super(message)
+        @reason = reason
+        @decision = decision
+      end
+    end
   end
 end

data/lib/portage/ucp/mcp/server.rb

@@ -50,23 +50,27 @@ module Portage
         def self.call_tool(context:, capability:, action_name:, mutating:, kwargs:)
           server_context = kwargs.delete(:server_context)
           correlation_id = correlation_id_for(server_context)
-          Portage::Ucp::Observability.log(context.logger, "tool_call_received", capability: capability.name,
-                                                                                action: action_name,
-                                                                                correlation_id: correlation_id)
+          agent_profile = agent_profile_for(server_context)
+          log_tool_event(context.logger, "tool_call_received", correlation_id, agent_profile,
+                         capability: capability.name, action: action_name)
 
           rejection = authorize(context.authenticator, server_context, mutating: mutating) ||
                       rate_limit(context.rate_limiter, server_context, capability.name, mutating: mutating)
           return rejection if rejection
 
-          Portage::Ucp::Observability.log(context.logger, "tool_called", capability: capability.name,
-                                                                         action: action_name, arguments: kwargs,
-                                                                         correlation_id: correlation_id)
+          log_tool_event(context.logger, "tool_called", correlation_id, agent_profile,
+                         capability: capability.name, action: action_name, arguments: kwargs)
 
           result = context.dispatcher.call(capability: capability.name, action: action_name, arguments: kwargs,
-                                           correlation_id: correlation_id)
+                                           correlation_id: correlation_id, agent_profile: agent_profile)
           ::MCP::Tool::Response.new(result[:content], structured_content: result[:structuredContent])
         end
 
+        def self.log_tool_event(logger, event, correlation_id, agent_profile, **fields)
+          Portage::Ucp::Observability.log(logger, event, correlation_id: correlation_id, agent_profile: agent_profile,
+                                                         **fields)
+        end
+
         # Per-request correlation only (§23): `Context` above is built once per
         # process in `.build`, and mcp 0.25.0's Streamable HTTP transport is
         # explicitly stateful/multi-session, so memoizing an id there would
@@ -91,6 +95,15 @@ module Portage
           traceparent.is_a?(String) && TRACEPARENT_FORMAT.match?(traceparent) ? traceparent : SecureRandom.uuid
         end
 
+        # Same `_meta` path as `traceparent` above, but for the caller-supplied
+        # `ucp-agent.profile` hint — no format validation, since (unlike
+        # traceparent) nothing here parses or trusts its shape, it's just
+        # threaded through for observability/policy consumers to interpret.
+        def self.agent_profile_for(server_context)
+          meta = server_context[:_meta] if server_context.respond_to?(:[])
+          meta && (meta["ucp-agent.profile"] || meta[:"ucp-agent.profile"])
+        end
+
         def self.authorize(authenticator, server_context, mutating:)
           return unless mutating
 

data/lib/portage/ucp/policy.rb

@@ -0,0 +1,79 @@
+require "json"
+require "fileutils"
+
+module Portage
+  module Ucp
+    # Local policy config for PolicyGuard (docs/plans/agentic-payments.md
+    # Phase 2). File format is deliberately private/internal — `portage-ucp`
+    # is a published gem, so PolicyGuard.check!'s keyword API is the stable
+    # surface, not this schema, which can change across releases.
+    #
+    # Absent file, or an absent field within it, means "no restriction" for
+    # that check — a fresh install doesn't block dispatch just because no
+    # policy was ever configured. That's a deliberate default-permissive
+    # choice: PolicyGuard.check! and Phase 3's Confirmer are two independent
+    # layers, and confirmation defaults to *on* (Phase 1), so an unconfigured
+    # policy isn't the only thing standing between an agent and a charge.
+    #
+    # A corrupt file is not the same as an absent one — that's data damage,
+    # not "nothing configured" — so JSON parse errors raise rather than
+    # silently falling back to permissive defaults.
+    class Policy
+      PATH = File.join(Dir.home, ".portage", "policy.json").freeze
+
+      def self.load(path: PATH)
+        new(path: path, data: read(path))
+      end
+
+      def initialize(path: PATH, data: {})
+        @path = path
+        @data = data
+      end
+
+      def per_transaction_cap = @data["per_transaction_cap"]
+      def rolling_cap = @data["rolling_cap"]
+      def velocity = @data["velocity"]
+      def merchant_allowlist = Array(@data["merchant_allowlist"])
+      def token_scope(token_ref) = (@data["token_scopes"] || {})[token_ref]
+
+      # @param token_ref [String] from Support::TokenRef.for — bound at
+      #   enrollment time (portage-cli's PaymentMethods#enroll), not per-call.
+      def set_token_scope(token_ref, scope)
+        @data["token_scopes"] ||= {}
+        @data["token_scopes"][token_ref] = scope
+        write
+        scope
+      end
+
+      def set(key, value)
+        @data[key.to_s] = value
+        write
+        value
+      end
+
+      def to_h = @data.dup
+
+      def self.read(path)
+        return {} unless File.readable?(path)
+
+        raw = File.read(path)
+        return {} if raw.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+      private_class_method :read
+
+      private
+
+      # Same "raise, don't swallow" convention as TransactionLog — a lost
+      # write here means a cap/allowlist/scope change silently didn't take,
+      # which is worse than the write never having been attempted.
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.pretty_generate(@data))
+        File.chmod(0o600, @path)
+      end
+    end
+  end
+end