coolhand 0.5.0 → 0.6.0

data/docs/template-search.md

@@ -0,0 +1,218 @@
+# Reading Templates (Search + Get)
+
+`Coolhand::TemplateService` reads back the LLM request templates your logs are matched against.
+It wraps two read-only endpoints:
+
+| method | endpoint |
+|---|---|
+| `search_templates` | `GET /api/v2/llm_request_templates` |
+| `get_template` | `GET /api/v2/llm_request_templates/{id}` |
+
+Both require your **private** API key. The public key is write-only on this API and is rejected
+exactly like an invalid one.
+
+```ruby
+require "coolhand"
+
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_PRIVATE_API_KEY")
+end
+
+templates = Coolhand.template_service
+
+result = templates.search_templates(search: "summar", status: "published")
+result.templates.each { |template| puts "#{template[:name]} (#{template[:log_count]} logs)" }
+
+detail = templates.get_template(result.templates.first[:id])
+puts detail[:user_prompt_pattern]
+```
+
+## What this is not
+
+This is **not** a port of the `search_templates` MCP tool, and the two do not agree:
+
+- `log_count` here counts only directly-collected client logs — the same records
+  `GET /api/v2/llm_request_logs?template_id=…` returns. Evals, bakeoff comparisons and synthetic
+  logs are excluded, so this number is often lower than the MCP tool's.
+- Templates whose workload has been archived are **returned** here, not hidden, so the list agrees
+  with `get_template`, which can always fetch such a template by id. Narrow with `workload_id`
+  instead.
+
+Template *creation, update and deprecation* stay on the MCP surface. This REST surface is
+read-only, and there is no version-history sub-resource.
+
+## `search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil, include_system: nil, page: nil, per: nil)`
+
+Search is a *parameter* on the list endpoint rather than a route of its own, so this is one method
+rather than a list/search pair.
+
+All filters are optional keyword arguments, and their names are the wire names — Ruby's convention
+and this API's already agree, so there is no second spelling to translate through.
+
+| keyword | type | notes |
+|---|---|---|
+| `search` | String | Case-insensitive **literal** substring match on the template name. `%` and `_` are escaped server-side and match themselves — do not escape them again. |
+| `workload_id` | String | Workload hashid. One that does not decode, or that belongs to another client, is a `422` rather than an empty list. |
+| `status` | String | `"draft"`, `"published"` or `"failure"`. Any other non-empty value is a `422` from the server; empty is treated as no filter. |
+| `include_deprecated` | Boolean | Include templates with a non-null `deprecated_at`. Defaults to `false` server-side. |
+| `include_system` | Boolean | Include the `Unmatched` / `Ignored API Calls` buckets. Defaults to `false` server-side. |
+| `page` | Integer | 1-based. |
+| `per` | Integer | Default 25, max 100, both enforced server-side. |
+
+Two things it deliberately does **not** do:
+
+- **There is no `client_id` keyword.** The client is always derived from the authenticating API key
+  and cannot be supplied, so passing one raises `ArgumentError` rather than reaching the wire.
+- **`status` is not checked against a client-side allowlist.** The API definition enumerates the
+  values on the *query parameter*, but leaves the `status` field on the *response* an unconstrained
+  string. Sending an unrecognised value gets you the server's `422`; a status the server gains
+  later works without a gem release.
+
+`per_page` is accepted on the wire as an alias for `per`. This gem only ever sends `per` — one knob
+is enough.
+
+### Return value
+
+A `Coolhand::TemplateSearchResult` — a `Struct`, so `#templates`, `#pagination`, `#to_h` and
+pattern matching all work:
+
+```ruby
+result = Coolhand.template_service.search_templates(include_system: true)
+
+result.templates   # => [{ id: "kp9npvc8qq2q", name: "Unmatched", ... }, ...]
+result.pagination  # => #<struct Coolhand::Pagination current_page=1, ...>
+```
+
+**Rows are plain Hashes with Symbol keys**, the same shape `create_feedback` and `create_log`
+already return. They are handed back exactly as the API rendered them rather than being copied into
+a value object, so a field the server adds later reaches you instead of being silently dropped on
+the way through. That is also why there is no `system_template?` predicate: read the wire field,
+`template[:system_template]`.
+
+Rows are ordered newest first (`created_at DESC`, with a primary-key tiebreaker so paging is stable
+across requests). Each carries:
+
+| field | type | notes |
+|---|---|---|
+| `:id` | String | Hashid, never the integer primary key. |
+| `:name` | String | Never null, but may be blank on a draft. |
+| `:status` | String or nil | `draft` / `published` / `failure`. |
+| `:version` | String or nil | |
+| `:group` | String or nil | `chat`, `user_prompt`, `user_prompt_with_system_prompt`, `embedding`, `other`. |
+| `:workload_id` | String | Workload hashid; never null. |
+| `:workload_name` | String | Never null. |
+| `:system_template` | Boolean | True for the `Unmatched` / `Ignored API Calls` buckets. |
+| `:deprecated_at` | String or nil | ISO-8601 UTC. Non-null means the template has been superseded. |
+| `:log_count` | Integer | Directly-collected client logs only — see [What this is not](#what-this-is-not). |
+| `:created_at` | String | ISO-8601 UTC. |
+| `:updated_at` | String | ISO-8601 UTC. |
+
+**Prompt patterns are not in the list.** They come from `get_template` only.
+
+`pagination` is a `Coolhand::Pagination` built from the endpoint's `X-Page`, `X-Per-Page`,
+`X-Total-Count` and `X-Total-Pages` response headers — never from the size of the array, which only
+ever describes the page in hand. Unlike `/llm_request_logs` there is no `include_total` opt-out
+here; the headers are always sent.
+
+| field | type |
+|---|---|
+| `current_page` | Integer |
+| `per_page` | Integer |
+| `total_count` | Integer |
+| `total_pages` | Integer |
+| `has_next_page` | Boolean |
+| `has_prev_page` | Boolean |
+
+### System templates and the empty default list
+
+Every Coolhand client is created with two system buckets, `Unmatched` and `Ignored API Calls`. They
+are hidden unless you pass `include_system: true`, so a client with no templates of its own gets an
+empty array rather than those two rows. `Unmatched` is what you inspect when logs are misrouting:
+
+```ruby
+unmatched = Coolhand.template_service
+                    .search_templates(include_system: true, search: "unmatched")
+                    .templates
+                    .first
+
+puts unmatched[:log_count]
+```
+
+## `get_template(id)`
+
+`id` is the template hashid — the `:id` field from `search_templates`.
+
+Returns a Hash with every list field above, **plus** the full untruncated regexes the list omits:
+
+| field | type |
+|---|---|
+| `:user_prompt_pattern` | String or nil |
+| `:system_prompt_pattern` | String or nil |
+
+Unlike the list, this filters on nothing but client ownership: a deprecated or system template is
+reachable by id with **no opt-in flag**, because inspecting one of those is the usual reason to
+fetch a template directly.
+
+## Errors
+
+The write methods in this gem (`create_feedback`, `create_log`, `send_llm_request_log`) log a
+failure and return `nil` — instrumentation must never be the reason a host app falls over. **The
+read methods are the opposite and raise**, because a caller that asked for data has to be able to
+tell a `404` from a timeout from a genuinely empty result.
+
+| raised | when |
+|---|---|
+| `Coolhand::HttpError` | The server answered with a non-2xx status. `#status` is the HTTP status code and `#body` the response body. |
+| `Coolhand::Error` | No API key configured, a transport failure, a body that is not valid JSON, or a blank `id` passed to `get_template`. |
+
+`Coolhand::HttpError` is a `Coolhand::Error`, so `rescue Coolhand::Error` catches both.
+
+**Branch on `#status`, never on the message:**
+
+```ruby
+begin
+  result = Coolhand.template_service.search_templates
+rescue Coolhand::HttpError => e
+  case e.status
+  when 401 then warn "Private API key required — the public key cannot read"
+  when 422 then warn "Bad filter: #{e.body}"
+  when 504 then warn "Timed out aggregating log_count — narrow the query and retry"
+  else raise
+  end
+end
+```
+
+| status | meaning |
+|---|---|
+| `401` | Missing, invalid, or public API key. |
+| `404` | `get_template` only. Unknown id, **or** one belonging to another client — existence is not disclosed, so this is never a `403`. |
+| `422` | Unrecognised `status`, or a `workload_id` that does not decode or belongs to another client. |
+| `504` | See below. |
+
+### `504` is expected, and retryable
+
+`log_count` aggregates over `llm_request_logs`, so its cost scales with how many logs the matched
+templates hold — the `Unmatched` bucket can hold every log that never matched a template. Every
+query behind these responses is bounded by a 10-second statement timeout, and exceeding it returns
+`504` rather than hanging. It reaches you as an `HttpError` with `status == 504`, not folded into a
+generic server error, precisely so you can narrow and retry:
+
+```ruby
+templates = Coolhand.template_service
+
+begin
+  templates.search_templates(include_system: true)
+rescue Coolhand::HttpError => e
+  raise unless e.status == 504
+
+  # Narrow the aggregate: one workload at a time, smaller pages.
+  templates.search_templates(include_system: true, workload_id: workload_id, per: 10)
+end
+```
+
+This is also why the read path waits far longer than the write path before giving up. A write
+times out after 5 seconds because it runs inline in your app's own request. A read allows 60: the
+server bounds each *statement* behind a response at 10 seconds, but one response runs several, so
+a slow-but-working `include_system=true` call measured 7-15 seconds against a development database
+while returning `200` every time. Giving up sooner would report a working endpoint as a transport
+failure, and would pre-empt the `504` you are meant to see and retry.

data/docs/vertex.md

@@ -0,0 +1,54 @@
+# Google Vertex AI Batch Result Logging
+
+Log completed Google Vertex AI batch prediction job results the same way regular synchronous calls are logged. Unlike the [OpenAI batch handler](openai.md), this is not webhook-driven — you call `Coolhand::Vertex::BatchResultProcessor` directly from your own batch-job callback/polling code.
+
+For monitoring regular (non-batch) Vertex AI calls, no extra setup is required beyond `Coolhand.configure` — `aiplatform.googleapis.com` is intercepted by default.
+
+Requires Rails — `Coolhand::Vertex::BatchResultProcessor` logs via `Rails.logger` internally. `config.capture = false` and `Coolhand.without_capture` do not suppress these logs: unlike the passive Net::HTTP interceptor, calling this processor is an explicit, deliberate act, so it always sends.
+
+## Usage
+
+```ruby
+require "coolhand/vertex/batch_result_processor"
+```
+
+- Call the `Coolhand::Vertex::BatchResultProcessor` service with `batch_info` and the downloaded batch results.
+- Optionally pass `model:` to populate the logged `model` field. It falls back to a `"model"` key in `batch_info` if present, and is omitted from the payload entirely when neither is available. If the value (from either source) looks like a Vertex model resource path (`publishers/<publisher>/models/<id>` or `projects/<project>/locations/<location>/models/<id>`), it's normalized down to just the trailing id/version before being logged; any other string is sent as-is.
+- `batch_info["name"]` must be the exact Vertex job resource name (`projects/<project>/locations/<location>/batchPredictionJobs/<job-id>`), and `batch_info["startTime"]`/`["endTime"]` must be valid ISO 8601 timestamps — a batch with a missing or malformed resource name or timestamps is skipped entirely (logged as an error) rather than sent with a broken URL.
+- If `endTime` precedes `startTime` (e.g. clock skew), the batch is still logged — `duration_ms` is clamped to `0` and a warning is logged — rather than dropping the results.
+- Each element of the `batch_results` array passed to `.call` must be a `Hash` with a `"request"` and/or `"response"` key (the request/response body to log for that item — either key alone is accepted). Any other shape is treated as malformed and skipped, with the skip counted in a `Rails.logger.warn` summary rather than raised.
+
+## Minimal example
+
+Only the key lines are shown — wire this into your own batch callback service.
+
+```ruby
+class Vertex::BatchCallbackProcessor < BaseService
+  option :batch_request, model: BatchApiRequest
+  option :batch_info
+
+  def call
+    case batch_info["state"]
+    when "JOB_STATE_PENDING"
+      nil
+    when "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
+      batch_request.update!(status: "processing")
+
+      Coolhand::Vertex::BatchResultProcessor.new(batch_info:).call
+    when "JOB_STATE_SUCCEEDED"
+      output_file_id = batch_info["outputInfo"]["gcsOutputDirectory"]
+      results = download_batch_results(output_file_id)
+      results.each { |batch_item| process_batch_result(batch_item) }
+
+      batch_request.update!(status: "completed", completed_at: Time.current, output_file_id:)
+
+      Coolhand::Vertex::BatchResultProcessor.new(batch_info:, model: batch_request.llm_model).call(results)
+
+      # Clean up GCS files after successful processing
+      cleanup_gcs_files(output_file_id)
+    when "JOB_STATE_FAILED"
+      handle_failed_batch(batch_info["error"]["message"])
+    end
+  end
+end
+```

data/lib/coolhand/api_service.rb

@@ -4,9 +4,19 @@ require "net/http"
 require "uri"
 require "json"
 require_relative "collector"
+require_relative "errors"
+require_relative "read_requests"
 
 module Coolhand
   class ApiService
+    # The GET half of this class. See Coolhand::ReadRequests for why reads raise where writes
+    # log and return nil.
+    include ReadRequests
+
+    # Caps how much of a failed response body is interpolated into a log line or an exception
+    # message. Without it an oversized body from a proxy or gateway becomes the message.
+    ERROR_BODY_LIMIT = 2000
+
     attr_reader :api_endpoint
 
     def initialize(endpoint = "v2/llm_request_logs")
@@ -77,12 +87,7 @@ module Coolhand
       http.read_timeout = 5
 
       request = Net::HTTP::Post.new(uri.request_uri)
-      headers = create_request_options(payload)
-      headers.each do |key, value|
-        # Ensure header values are UTF-8 encoded
-        encoded_value = value.is_a?(String) ? value.dup.force_encoding("UTF-8") : value
-        request[key] = encoded_value
-      end
+      apply_headers(request, create_request_options(payload))
 
       # Clean payload and ensure UTF-8 encoding before JSON generation
       cleaned_payload = sanitize_payload_for_json(payload)
@@ -92,21 +97,20 @@ module Coolhand
       request.body = json_body.force_encoding("UTF-8")
 
       begin
-        response = http.request(request)
+        # This request goes through the same patched Net::HTTP as the host
+        # app's real LLM calls. Without this, a base_url/intercept_addresses
+        # configuration that also matches Coolhand's own API host would
+        # re-intercept this log-shipping call, generating a second log
+        # request that itself gets intercepted, and so on — unbounded
+        # request amplification.
+        response = Coolhand.without_capture { http.request(request) }
 
         if response.is_a?(Net::HTTPSuccess)
           result = JSON.parse(response.body, symbolize_names: true)
           log success_message
           result
         else
-          body = response.body.force_encoding("UTF-8") if response.body
-          # Only show first part of HTML error pages
-          error_msg = if body&.include?("<!DOCTYPE html>")
-            "#{body[0..200]}... [HTML error page truncated]"
-          else
-            body
-          end
-          log "❌ Request failed: #{response.code} - #{error_msg}"
+          log "❌ Request failed: #{response.code} - #{format_error_body(response.body)}"
           nil
         end
       rescue StandardError => e
@@ -204,6 +208,26 @@ module Coolhand
 
     private
 
+    # Shared by the write path's failure log and the read path's raised message, so a large
+    # response body never dumps a whole document into either. An HTML error page (a proxy's 502,
+    # say) is cut short hard; anything else keeps enough to diagnose from and no more.
+    def format_error_body(body)
+      return nil if body.nil?
+
+      text = body.dup.force_encoding("UTF-8")
+      return "#{text[0..200]}... [HTML error page truncated]" if text.include?("<!DOCTYPE html>")
+      return text if text.length <= ERROR_BODY_LIMIT
+
+      "#{text[0, ERROR_BODY_LIMIT]}... [truncated]"
+    end
+
+    def apply_headers(request, headers)
+      headers.each do |key, value|
+        # Net::HTTP rejects header values that are not UTF-8.
+        request[key] = value.is_a?(String) ? value.dup.force_encoding("UTF-8") : value
+      end
+    end
+
     def missing_api_key?
       return false if Coolhand.required_field?(api_key)
 
@@ -275,8 +299,24 @@ module Coolhand
       return if silent
 
       puts "\n🎉 LOGGING OpenAI API Call #{@api_endpoint}"
-      puts captured_data
+
+      if debug_mode?
+        puts captured_data
+      else
+        puts request_body_summary(captured_data)
+      end
+
       puts "📤 Sending to: #{@api_endpoint}"
     end
+
+    def request_body_summary(captured_data)
+      return "captured_data: (unavailable)" unless captured_data.is_a?(Hash)
+
+      id = captured_data[:id] || captured_data["id"] || "N/A"
+      body = captured_data[:request_body] || captured_data["request_body"]
+      "id: #{id}, request_body: #{body.to_json.bytesize} bytes"
+    rescue StandardError
+      "captured_data: (unavailable)"
+    end
   end
 end

data/lib/coolhand/base_interceptor.rb

@@ -7,10 +7,11 @@ module Coolhand
 
     # Matches any header whose *name* signals sensitive content, regardless of
     # provider — covers known keys (x-api-key, x-goog-api-key, openai-api-key),
-    # AWS SigV4 session tokens (x-amz-security-token), and future/unknown
-    # providers using a similarly-named header. Shared with LoggerService so
-    # the two logging paths (interceptor + webhook forwarding) stay consistent.
-    SENSITIVE_HEADER_PATTERN = /key|token|secret|signature|authorization/i
+    # AWS SigV4 session tokens (x-amz-security-token), session/CSRF cookies
+    # (cookie, set-cookie), and future/unknown providers using a
+    # similarly-named header. Shared with LoggerService so the two logging
+    # paths (interceptor + webhook forwarding) stay consistent.
+    SENSITIVE_HEADER_PATTERN = /key|token|secret|signature|authorization|cookie/i
 
     def sanitize_headers(headers)
       return {} if headers.nil?
@@ -22,7 +23,9 @@ module Coolhand
         begin
           headers.to_hash.transform_keys(&:to_s).transform_values { |v| normalize_header_value(v) }
         rescue StandardError
-          # fall through to other enumeration strategies
+          # Deliberately fails closed to an empty hash rather than trying each_header/each on
+          # this object next — an object whose own to_hash raises is untrustworthy enough that
+          # guessing at another enumeration strategy isn't worth the risk of a second failure.
           nil
         end
       elsif headers.respond_to?(:each_header)
@@ -69,50 +72,67 @@ module Coolhand
       end
     end
 
+    # Matches query param *names* that signal sensitive content, the same way
+    # SENSITIVE_HEADER_PATTERN does for headers — covers exact params this
+    # gem already knew about (key/token/secret) as well as presigned-URL
+    # credential params used by AWS (X-Amz-Signature, X-Amz-Credential,
+    # X-Amz-Security-Token) and Google Cloud (X-Goog-Signature,
+    # X-Goog-Credential) storage APIs.
+    SENSITIVE_QUERY_PARAM_PATTERN = /key|token|secret|sig|credential|password|auth/i
+
     def sanitize_url(url)
       uri = URI.parse(url)
-      return url unless uri.query
-
-      sensitive = %w[key api_key apikey token access_token secret]
-      params = URI.decode_www_form(uri.query)
-      redacted = false
-      params.map! do |n, v|
-        if sensitive.include?(n.downcase)
-          redacted = true
-          [n, "[REDACTED]"]
-        else
-          [n, v]
-        end
+      modified = false
+
+      if uri.userinfo
+        # URI userinfo syntax disallows "[" / "]", so this can't reuse the [REDACTED]
+        # placeholder used elsewhere.
+        uri.userinfo = "REDACTED"
+        modified = true
       end
 
-      if redacted
-        uri.query = URI.encode_www_form(params)
-        uri.to_s
-      else
-        url
+      if uri.query
+        params = URI.decode_www_form(uri.query)
+        redacted_query = false
+        params.map! do |n, v|
+          if n.match?(SENSITIVE_QUERY_PARAM_PATTERN)
+            redacted_query = true
+            [n, "[REDACTED]"]
+          else
+            [n, v]
+          end
+        end
+        if redacted_query
+          uri.query = URI.encode_www_form(params)
+          modified = true
+        end
       end
+
+      modified ? uri.to_s : url
     rescue URI::InvalidURIError
       url
     end
 
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
-      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:)
-      request_data = {
-        raw_request: {
-          id: request_id,
-          timestamp: start_time.iso8601,
-          method: method.to_s.downcase,
-          url: sanitize_url(url),
-          headers: request_headers,
-          request_body: request_body,
-          response_headers: response_headers,
-          response_body: response_body,
-          status_code: status_code,
-          duration_ms: duration_ms,
-          completed_at: end_time.iso8601,
-          is_streaming: is_streaming
-        }
+      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil)
+      raw_request = {
+        id: request_id,
+        timestamp: start_time.iso8601,
+        method: method.to_s.downcase,
+        url: sanitize_url(url),
+        headers: sanitize_headers(request_headers),
+        request_body: request_body,
+        response_headers: sanitize_headers(response_headers),
+        response_body: response_body,
+        status_code: status_code,
+        duration_ms: duration_ms,
+        completed_at: end_time.iso8601,
+        is_streaming: is_streaming
       }
+      raw_request[:source_api] = source_api if Coolhand.required_field?(source_api)
+      raw_request[:model] = model if Coolhand.required_field?(model)
+
+      request_data = { raw_request: raw_request }
 
       api_service = Coolhand::ApiService.new
       api_service.send_llm_request_log(request_data)

data/lib/coolhand/configuration.rb

@@ -3,22 +3,34 @@
 require "yaml"
 require "uri"
 
+require_relative "open_ai/webhook_id_store"
+
 module Coolhand
   # Handles all configuration settings for the gem.
   class Configuration
-    DEFAULT_EXCLUDE_API_PATTERNS = YAML.load_file(
+    DEFAULT_EXCLUDE_API_PATTERNS = YAML.safe_load_file(
       File.join(__dir__, "default_exclude_api_patterns.yml")
     ).freeze
 
-    DEFAULT_INTERCEPT_ADDRESSES = YAML.load_file(
+    DEFAULT_INTERCEPT_ADDRESSES = YAML.safe_load_file(
       File.join(__dir__, "default_intercept_addresses.yml")
     ).freeze
 
+    DEFAULT_INTERCEPT_PATH_PATTERNS = YAML.safe_load_file(
+      File.join(__dir__, "default_intercept_path_patterns.yml")
+    ).freeze
+
     BASE_URL_ERROR_MSG = "base_url must use https:// (or http://localhost / http://127.0.0.1 for local dev)"
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
 
-    attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled
-    attr_reader :intercept_addresses, :base_url
+    # 1 MB — generous for real chat/completion payloads, small enough to stop
+    # a multi-MB file upload from being logged in full when its content-type
+    # happens to look JSON-ish (or is unset).
+    DEFAULT_MAX_CAPTURED_BODY_BYTES = 1_000_000
+
+    attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled,
+      :max_captured_body_bytes, :webhook_replay_tolerance_seconds, :webhook_id_store
+    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url
 
     def initialize
       # Set defaults
@@ -26,20 +38,41 @@ module Coolhand
       @api_key = nil
       @silent = false
       @intercept_addresses = DEFAULT_INTERCEPT_ADDRESSES.dup
+      @intercept_path_patterns = DEFAULT_INTERCEPT_PATH_PATTERNS.dup
       self.base_url = "https://coolhandlabs.com/api"
       @debug_mode = false
       @capture = true
       @exclude_api_patterns = DEFAULT_EXCLUDE_API_PATTERNS.dup
       @enabled = true
+      @max_captured_body_bytes = DEFAULT_MAX_CAPTURED_BODY_BYTES
+      @webhook_replay_tolerance_seconds = 300
+      @webhook_id_store = Coolhand::OpenAi::WebhookIdStore.new
     end
 
-    # Custom setter that preserves defaults when nil/empty array is provided
+    # intercept_addresses is a required allow-list: NetHttpInterceptor#intercept? only
+    # captures a request whose URL matches an entry here, so an empty list would mean
+    # "never capture anything" (validate! deliberately rejects that). Unlike
+    # exclude_api_patterns, `= []` is not a supported way to disable it — use
+    # config.enabled = false or config.capture = false to disable capture entirely.
+    # nil/empty here is treated as "leave the current value alone" rather than cleared.
     def intercept_addresses=(value)
-      return if value.nil? || (value.is_a?(Array) && value.empty?)
+      if value.nil? || (value.is_a?(Array) && value.empty?)
+        Coolhand.log "⚠️  Coolhand: intercept_addresses = #{value.inspect} is ignored " \
+                     "(would disable capture entirely) — keeping the current value. " \
+                     "Use config.enabled = false or config.capture = false to disable capture."
+        return
+      end
 
       @intercept_addresses = value.is_a?(Array) ? value : [value]
     end
 
+    # Custom setter that preserves defaults when nil/empty array is provided
+    def intercept_path_patterns=(value)
+      return if value.nil? || (value.is_a?(Array) && value.empty?)
+
+      @intercept_path_patterns = value.is_a?(Array) ? value : [value]
+    end
+
     def base_url=(value)
       stripped = value&.sub(%r{/+\z}, "")
       raise Error, BASE_URL_ERROR_MSG unless stripped.nil? || valid_base_url?(stripped)

data/lib/coolhand/default_exclude_api_patterns.yml

@@ -1,6 +1,7 @@
 # Coolhand default exclude API patterns
-# These substrings are matched against request URLs after the intercept_addresses
-# allow-list passes. Matching URLs are skipped and not forwarded as llm_request_logs.
+# These substrings are matched against the request's path (not the full URL or
+# query string). A request whose path matches is skipped and not forwarded as
+# an llm_request_log, regardless of whether it would otherwise match intercept_addresses.
 #
 # Users can extend defaults:   c.exclude_api_patterns << "/myOperationalPath/"
 # Users can override entirely: c.exclude_api_patterns = ["/only_this/"]

data/lib/coolhand/default_intercept_addresses.yml

@@ -1,9 +1,15 @@
 # Coolhand default intercept addresses
-# These substrings are matched against request URLs to decide whether a request
-# should be captured and forwarded as an llm_request_log.
+# These are matched against the request's parsed host (exact match, or a
+# dot-boundary suffix match, case-insensitive) to decide whether a request
+# should be captured and forwarded as an llm_request_log. A single "*" in an
+# entry matches exactly one host label — e.g. "bedrock-runtime.*.amazonaws.com"
+# matches "bedrock-runtime.us-east-1.amazonaws.com" but nothing else.
 #
 # Users can extend defaults:   c.intercept_addresses << "my.custom.api.com"
 # Users can override entirely: c.intercept_addresses = ["only.this.com"]
+# This list cannot be emptied — it's required (unlike exclude_api_patterns, which
+# can be disabled with `= []`). To disable capture entirely, use
+# c.enabled = false or c.capture = false instead.
 
 - "api.openai.com"
 - "api.anthropic.com"
@@ -11,9 +17,8 @@
 - "generativelanguage.googleapis.com"
 - "models.github.ai"
 - "models.inference.ai.azure.com"
-- ":generateContent"
-- ":streamGenerateContent"
 - "aiplatform.googleapis.com"
 - "gateway.ai.cloudflare.com"
-- "bedrock-runtime"
+- "bedrock-runtime.*.amazonaws.com"
 - "openrouter.ai"
+- "opencode.ai"

data/lib/coolhand/default_intercept_path_patterns.yml

@@ -0,0 +1,12 @@
+# Colon-action path suffixes from Google's API Discovery convention
+# (e.g. ".../v1beta/models/gemini-pro:generateContent"). These have no host
+# component of their own, so — unlike intercept_addresses — they are only
+# ever matched against the *path* of requests whose host is already
+# googleapis.com or a googleapis.com subdomain. They can never match on
+# their own against an unrelated/attacker-controlled host.
+#
+# Users can extend defaults:   c.intercept_path_patterns << ":myAction"
+# Users can override entirely: c.intercept_path_patterns = [":onlyThis"]
+
+- ":generateContent"
+- ":streamGenerateContent"