coolhand 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daed2b7ac4fe321602eb90f673cb385bd930b9ff503bf7e5d7851cbf06422617
-  data.tar.gz: 5d01a6386d142cdb31c490574191ac3867dabd30670c2a832c2aa18c7150c872
+  metadata.gz: 25393afdf95625b624ca2910cb3017685705529e9628a5d15cb3bdffdf122d52
+  data.tar.gz: 3e478c3b8494d5fef5bc87896fbf69cb9f93d088029b9a9745563c9a789b4473
 SHA512:
-  metadata.gz: a0681a3419c92e13fbae7a1b81c6d81b7a1cf2f088571dd44b4d2694c0ae5bf5c4c4312d7bff53ccc740833290bc931b932c1179244f004090192b0baaeb19f0
-  data.tar.gz: 9efd5e33528e0caeecc770c7286085320f9e4218f01fcf592ca82a27c96df71cf5ae52712a5a9aaeaf0702774be450bb7c3b7c71b0df8e57f56bd038f54f1b3d
+  metadata.gz: ad635f9377f6cb81967fc24b0c2aa9f9938c41e308c6b98511ee0139b9938e01ea766baf72a085700866c69ac50207da11e29f04d30a94ad3b487d3e22243d9e
+  data.tar.gz: d6ef0baf4e37d29b36a0d7a2d6a41822f551a0a753a2dc963c0da9eed60b90bf29b5f0015caa8a628c6f340ec9cb2b3ef2c83ecb9b59fbcec909d70f396603df

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-08-02
+
+### Added
+- **`Coolhand::Vertex::BatchResultProcessor.new` accepts an optional `model:` keyword** (falls back to a `"model"` key in `batch_info` when omitted) to populate the `model` field on batch-result logs — included only when one of those is available and non-blank, and omitted from the payload entirely otherwise (#76).
+- **`Coolhand::BaseInterceptor.send_complete_request_log` accepts optional `source_api:`/`model:` keywords**, for synthetic/batch log types (like the Vertex processor above) that aren't backed by a real intercepted HTTP request (#76).
+
+### Changed
+- **Vertex batch results with a missing or malformed job resource name or unparseable `startTime`/`endTime` are no longer logged at all.** Previously the processor still sent a request log using whatever was in `batch_info["name"]` (even if blank), just with a broken URL. It now validates these fields and skips the log entirely — with a `Rails.logger.error` explaining why — rather than sending something unusable (#76).
+- **A batch whose `endTime` precedes its `startTime` (e.g. clock skew) is still logged**, with `duration_ms` clamped to `0` and a warning logged, rather than dropped — unlike the missing/malformed cases above, the request/response content itself is still valid here (#76).
+- **A Vertex batch result item that isn't a `Hash` with a `"request"` and/or `"response"` key is now rejected and logged as an error**, instead of being sent as a log with `nil` request/response bodies (#76).
+- **The published gem no longer packages `.claude/`, `.idea/`, or `CLAUDE.md`** — these are repo/agent tooling, not part of the library.
+
+### Security
+- **A webhook processing error no longer leaves the request authenticated by default.** `Coolhand::WebhookInterceptor#intercept_batch_request` previously logged and swallowed *any* exception (a malformed webhook secret, a non-Hash JSON payload, a bug in `process_event`), returning normally without halting the Rails `before_action` chain — so the controller action still ran for a request whose signature was never confirmed valid. It now calls `head :unauthorized` in that rescue, matching the existing invalid-signature path, and validates the parsed webhook payload is a `Hash` before use.
+- **A blank or whitespace-only OpenAI webhook secret is no longer usable as the HMAC key.** `Coolhand::OpenAi::WebhookValidator` previously only rejected `nil`/`false`, so `webhook_secret = ""` (e.g. an unset `ENV` var with a blank default) silently signed and verified requests with an empty key — a much weaker, easy-to-guess bypass than the already-known "secret not configured" path. It now uses the same `Coolhand.required_field?` blank-check used elsewhere in the gem.
+- **`Cookie`/`Set-Cookie` headers are now redacted**, alongside the existing key/token/secret/signature/authorization patterns. Forwarding a Rails session cookie (a bearer credential) to Coolhand — e.g. via `LoggerService#forward_webhook(headers: request.headers)`, the pattern this gem's own docs show — was previously possible.
+- **`BaseInterceptor.sanitize_url` now redacts a broader set of credential-shaped query parameters** (`sig`, `credential`, `password`, `auth`, in addition to the existing `key`/`token`/`secret`), matching the pattern-based approach already used for headers instead of a small exact-match list. This covers AWS SigV4 (`X-Amz-Signature`, `X-Amz-Credential`) and Google Cloud (`X-Goog-Signature`, `X-Goog-Credential`) presigned-URL parameters that were previously logged in full.
+- **A failure capturing an intercepted request's body (e.g. an already-consumed `body_stream`) no longer prevents the real request from being attempted.** The capture happened before any error handling was in place, so an exception there escaped `NetHttpInterceptor#request` entirely — the host app's actual LLM call never happened. It's now rescued, logged, and treated as "body unavailable," and the real request still proceeds.
+- **Streamed response bodies are no longer buffered into a thread-local for requests this gem never intercepted.** `ResponseInterceptor#read_body` previously buffered every block-form `read_body` call process-wide, regardless of whether the enclosing request matched `intercept_addresses` — an unbounded memory growth path on any thread that streams large non-LLM responses (file downloads, etc.). Buffering now only happens while a `NetHttpInterceptor#request` call is actively capturing.
+- **A request made from inside another intercepted request's streaming callback no longer corrupts the outer request's logged response body.** The per-thread stream buffer is now saved and restored around each intercepted request instead of unconditionally cleared, so nested/reentrant LLM calls (e.g. a second provider call triggered from a chunk handler) no longer mix one request's content into another's log entry.
+- **Coolhand's own request to its backend API is no longer re-intercepted and re-logged.** If a self-hosted `base_url` or custom `intercept_addresses` entry happens to match Coolhand's own API host, the log-shipping request itself would previously be captured and logged like any other request — which itself gets logged, recursively, without bound. It's now wrapped in `Coolhand.without_capture`.
+- `Coolhand::OpenAi::WebhookValidator#webhook_secret` is no longer a public reader (it's only used internally) — reduces the chance of the raw secret ending up in error-tracker breadcrumbs or view-rendered controller state.
+- `YAML.load_file` → `YAML.safe_load_file` for the gem's own bundled default-addresses/patterns YAML files — defense-in-depth against unsafe deserialization, consistent with modern Psych defaults.
+- Added missing `require "openssl"` (`WebhookValidator`) and `require "stringio"` (`NetHttpInterceptor`) instead of relying on both being transitively loaded by something else first.
+
+### Fixed
+- **Vertex batch result logging** — `Coolhand::Vertex::BatchResultProcessor` now sends a fully-qualified URL (`https://aiplatform.googleapis.com/v1/<resource name>`) instead of the bare Vertex job resource name, plus explicit `source_api` and `model` values, all inside `raw_request`. The Coolhand API treats `raw_request` as free-form JSON, so this improves the data available to its classification without depending on new top-level payload fields being accepted. Also fixed: `timestamp`/`completed_at` are now sent as proper ISO 8601 strings instead of raw `Time` objects, and the URL is now run through the same `sanitize_url` helper used by every other logging path in the gem, for consistency (a Vertex batch URL can't actually carry a redactable query string today, so this is defense-in-depth rather than a fix for a live leak) (#76).
+- **`require "coolhand"` no longer requires `faraday`.** The gem hasn't used Faraday directly since the 0.4.0 unified `NetHttpInterceptor`, but a stale top-level `require "faraday"` meant loading the gem could raise `LoadError` for anyone without faraday installed — it was never a declared dependency. If your app relied on `require "coolhand"` transitively loading Faraday, require it yourself.
+- `Coolhand::Vertex::BatchResultProcessor`, `Coolhand::OpenAi::BatchResultProcessor`, and `Coolhand::OpenAi::WebhookValidator` can now each be required independently (e.g. `require "coolhand/vertex/batch_result_processor"`) without first requiring `"coolhand"` — previously this could raise `NameError` depending on load order.
+- `Coolhand::BaseInterceptor.send_complete_request_log` now runs `request_headers`/`response_headers` through `sanitize_headers` itself, rather than trusting every caller to have pre-sanitized them. `NetHttpInterceptor` already sanitized before calling it (`sanitize_headers` is idempotent, so no behavior change there); this closes the gap for any future caller that forgets.
+- `Coolhand::Vertex::BatchResultProcessor#handle_failed_batch` no longer raises `NoMethodError` when a failed batch's `error` field is missing or not a Hash — it now logs the batch-failure message either way instead of falling through to the generic "failed to process" catch-all.
+- **README's "Request Flow" section corrected** — it previously claimed data is sent to the Coolhand API "asynchronously in a background thread" with "zero performance impact"; it's actually sent inline, after the original response is available, bounded by the 5-second timeout described in 0.5.0's Security section.
+
 ## [0.5.0] - 2026-07-30
 
 ### Changed

data/README.md

@@ -39,14 +39,14 @@ end
 # ✅ OpenAI SDK calls
 # ✅ Anthropic API calls
 # ✅ Direct HTTP requests to AI APIs
-# ✅ ANY library making AI API calls via Faraday
+# ✅ Any library making AI API calls via Faraday's default adapter
 
 # NO code changes needed in your existing services!
 ```
 
 **✨ Why Automatic Monitoring:**
 - 🚫 **Zero refactoring** - No code changes to existing services
-- 📊 **Complete coverage** - Monitors ALL AI libraries using Faraday automatically
+- 📊 **Complete coverage** - Monitors AI libraries using Net::HTTP or Faraday's default adapter automatically
 - 🔒 **Security built-in** - Automatic credential sanitization
 - ⚡ **Performance optimized** - Negligible overhead via async logging
 - 🛡️ **Future-proof** - Automatically captures new AI calls added by your team
@@ -297,19 +297,25 @@ The filtering is automatic and applies to all monitored API calls and webhook lo
 
 The monitor works with multiple transport layers and Ruby libraries:
 
-**Faraday-based libraries:**
+**Faraday-based libraries** (via Faraday's default `net_http` adapter — a non-Net::HTTP adapter such as `faraday-typhoeus` is not covered):
 - OpenAI Ruby SDK
 - ruby-anthropic gem (community Anthropic gem)
 - ruby-openai gem
 - LangChain.rb
-- Direct Faraday requests
-- Any other Faraday-based HTTP client
+- Direct Faraday requests using the default adapter
 
 **Native HTTP libraries:**
 - Official Anthropic Ruby SDK (using Net::HTTP)
 - GitHub Models SDK / any client using `models.github.ai`
 - Any library using Net::HTTP directly
 
+**Other providers monitored out of the box:**
+- Google Gemini (`generativelanguage.googleapis.com`)
+- Google Vertex AI (`aiplatform.googleapis.com`) — see the [Vertex AI batch result logging guide](docs/vertex.md) for async batch jobs
+- AWS Bedrock (OpenAI-compatible endpoint)
+- Cloudflare AI Gateway
+- OpenRouter
+
 **Universal Coverage**: Since most Ruby HTTP libraries use Net::HTTP under the hood, Coolhand's single interceptor provides comprehensive monitoring without needing library-specific integrations.
 
 ## How It Works
@@ -325,11 +331,11 @@ Coolhand uses a unified Net::HTTP interceptor to capture outgoing requests to co
 ### Request Flow
 When a request matches configured LLM endpoints:
 
-1. The original request executes normally with zero performance impact
+1. The original request executes normally
 2. Request and response data (body, headers, status) are captured by the interceptor
 3. For streaming requests, the complete accumulated response is captured (not individual chunks)
-4. Data is sent to the Coolhand API asynchronously in a background thread
-5. Your application continues without interruption
+4. Data is sent to the Coolhand API inline, after the original response is available (bounded by a 5-second connect/read timeout so a slow or unreachable Coolhand backend can't hang your request indefinitely)
+5. Your application continues once the log is sent (or times out) — the original request/response is never blocked on Coolhand being reachable
 
 For non-matching endpoints, requests pass through unchanged.
 
@@ -395,108 +401,14 @@ The monitor handles errors gracefully:
 - Invalid API keys will be reported but won't crash your app
 - Network issues are handled with appropriate error messages
 
-
-## Batch webhook handler (OpenAI)
-
-Automatically handle OpenAI batch event logs (batch.completed, batch.failed, batch.expired, batch.cancelled)
-by intercepting webhook requests and enqueuing your batch result processor.
-
-Usage:
-- Include the interceptor in your controller:
-  include Coolhand::WebhookInterceptor
-- Add the before_action to validate and populate @validator payload:
-  before_action :intercept_batch_request, only: :openai
-- Ensure you skip CSRF for the webhook endpoint:
-  skip_before_action :verify_authenticity_token
-- Override the webhook_secret method to return your OpenAI webhook secret
-
-Minimal example (only key lines shown):
-
-```ruby
-# app/controllers/webhooks/batch_api_requests_controller.rb
-# ...existing code...
-include Coolhand::WebhookInterceptor
-
-skip_before_action :verify_authenticity_token
-before_action :intercept_batch_request, only: :openai
-
-def openai
-  event = JSON.parse(@validator.payload)
-  case event["type"]
-  when "batch.completed", "batch.failed", "batch.expired", "batch.cancelled"
-    batch_id = event.dig("data", "id")
-    batch_request = BatchApiRequest.find_by(provider: "openai", provider_batch_id: batch_id)
-
-    if batch_request
-      OpenAi::BatchResultProcessor.perform_async(batch_request.id)
-      Rails.logger.info("Queued batch result processing for BatchApiRequest #{batch_request.id}")
-    else
-      Rails.logger.warn("Could not find BatchApiRequest for OpenAI batch ID: #{batch_id}")
-    end
-  else
-    Rails.logger.info("Unhandled OpenAI webhook event type: #{event["type"]}")
-  end
-
-  head :ok
-rescue JSON::ParserError
-  head :bad_request
-rescue StandardError => e
-  Rails.logger.error("OpenAI webhook error: #{e.message}")
-  head :internal_server_error
-end
-
-def webhook_secret
-  Rails.application.credentials.openai_webhook_secret
-end
-# ...existing code...
-```
-
-## Batch webhook handler (Vertex)
-
-Automatically handle Vertex batch event logs.
-
-Usage:
-- call Coolhand::Vertex::BatchResultProcessor service with batch_info and download batch results
-
-Minimal example (only key lines shown):
-
-```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:).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
-```
-
 ## Documentation
 
 - **[Configuration](docs/configuration.md)** — Self-hosted deployments, base_url rules, debug mode, custom intercept addresses
 - **[Feedback API](docs/feedback.md)** — Full field reference, matching strategies, sentiment values
 - **[Anthropic Integration](docs/anthropic.md)** — Official and community Anthropic Ruby gems, streaming, dual gem handling, and troubleshooting
 - **[ElevenLabs Integration](docs/elevenlabs.md)** — Webhook capture, feedback submission, and Rails integration
+- **[OpenAI Batch Webhook Handler](docs/openai.md)** — Handle OpenAI batch job completion events via webhook interception
+- **[Google Vertex AI Batch Result Logging](docs/vertex.md)** — Log completed Vertex AI batch prediction job results
 
 ## Security
 

data/docs/openai.md

@@ -0,0 +1,60 @@
+# OpenAI Batch Webhook Handler
+
+Automatically handle OpenAI batch event logs (`batch.completed`, `batch.failed`, `batch.expired`, `batch.cancelled`) by intercepting webhook requests and logging completed batch results to Coolhand.
+
+For monitoring regular (non-batch) OpenAI API calls, see the [OpenAI client example](../README.md#with-openai-ruby-client) in the main README — no extra setup is required beyond `Coolhand.configure`.
+
+Requires Rails — `Coolhand::WebhookInterceptor` and `Coolhand::OpenAi::BatchResultProcessor` log via `Rails.logger` internally. `config.capture = false` and `Coolhand.without_capture` do not suppress these logs: unlike the passive Net::HTTP interceptor, `intercept_batch_request` dispatching to `Coolhand::OpenAi::BatchResultProcessor` is an explicit, deliberate act, so it always sends.
+
+## Usage
+
+- Add the `openai` gem to your Gemfile — `Coolhand::OpenAi::BatchResultProcessor` needs it to download batch result files.
+- Include the interceptor in your controller: `include Coolhand::WebhookInterceptor`
+- Add the `before_action` to validate and populate the `@validator` payload: `before_action :intercept_batch_request, only: :openai`
+- Ensure you skip CSRF for the webhook endpoint: `skip_before_action :verify_authenticity_token`
+- Override the `webhook_secret` method to return your OpenAI webhook secret
+
+`intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` **synchronously**, inline in the `before_action` — that part requires no code in your controller action. It downloads two JSONL files from OpenAI and sends one request log per batch item, so a large batch can take long enough to trip your webhook endpoint's timeout (and OpenAI's retry behavior); consider that when sizing batches. The example below shows a controller action doing additional, app-specific work on top of that (e.g. updating your own `BatchApiRequest` record and enqueuing your own background job), which is optional.
+
+## Minimal example
+
+Only the key lines are shown — wire this into your own controller and background job setup.
+
+```ruby
+# app/controllers/webhooks/batch_api_requests_controller.rb
+# ...existing code...
+include Coolhand::WebhookInterceptor
+
+skip_before_action :verify_authenticity_token
+before_action :intercept_batch_request, only: :openai
+
+def openai
+  event = JSON.parse(@validator.payload)
+  case event["type"]
+  when "batch.completed", "batch.failed", "batch.expired", "batch.cancelled"
+    batch_id = event.dig("data", "id")
+    batch_request = BatchApiRequest.find_by(provider: "openai", provider_batch_id: batch_id)
+
+    if batch_request
+      MyApp::BatchResultJob.perform_async(batch_request.id)
+      Rails.logger.info("Queued batch result processing for BatchApiRequest #{batch_request.id}")
+    else
+      Rails.logger.warn("Could not find BatchApiRequest for OpenAI batch ID: #{batch_id}")
+    end
+  else
+    Rails.logger.info("Unhandled OpenAI webhook event type: #{event["type"]}")
+  end
+
+  head :ok
+rescue JSON::ParserError
+  head :bad_request
+rescue StandardError => e
+  Rails.logger.error("OpenAI webhook error: #{e.message}")
+  head :internal_server_error
+end
+
+def webhook_secret
+  Rails.application.credentials.openai_webhook_secret
+end
+# ...existing code...
+```

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

@@ -92,7 +92,13 @@ 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)

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?
@@ -69,15 +70,22 @@ 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)
+        if n.match?(SENSITIVE_QUERY_PARAM_PATTERN)
           redacted = true
           [n, "[REDACTED]"]
         else
@@ -96,23 +104,25 @@ module Coolhand
     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

@@ -6,11 +6,11 @@ require "uri"
 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
 

data/lib/coolhand/net_http_interceptor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 module Coolhand
   module NetHttpInterceptor
     include BaseInterceptor
@@ -7,7 +9,12 @@ module Coolhand
     # Response streaming interceptor nested under NetHttpInterceptor
     module ResponseInterceptor
       def read_body(dest = nil, &block)
-        return super unless block
+        # Only buffer while a #request call below is actively capturing —
+        # otherwise every block-form read_body in the process (including
+        # ones on responses this gem never intercepted) accumulates into a
+        # thread-local that's never freed, which is an unbounded memory
+        # leak on any thread that streams large non-LLM responses.
+        return super unless block && Thread.current[:coolhand_capturing_stream]
 
         super do |chunk|
           Thread.current[:coolhand_stream_buffer] ||= +""
@@ -49,8 +56,16 @@ module Coolhand
       return super unless should_capture?
 
       # Capture body before setting the guard — if this raises we skip logging cleanly
-      # and the guard is never set, so there is no leak.
-      captured_body = capture_request_body(req, body)
+      # and the guard is never set, so there is no leak. A failure here (e.g. an
+      # already-consumed body_stream) must never prevent the real request below
+      # from being attempted — this gem must never be the reason the host
+      # app's actual LLM call doesn't happen.
+      captured_body = begin
+        capture_request_body(req, body)
+      rescue StandardError => e
+        Coolhand.log "❌ Error capturing request body: #{e.message}"
+        nil
+      end
 
       active[self] = true
       start_time = Time.now
@@ -59,7 +74,14 @@ module Coolhand
       status_code = nil
       response_body = nil
 
+      # Save/restore rather than just nil-ing: a request made from inside
+      # this request's own streaming block (nested interception) would
+      # otherwise clobber this request's in-progress buffer with its own
+      # chunks, mixing one request's content into another's log.
+      previous_stream_buffer = Thread.current[:coolhand_stream_buffer]
+      previous_capturing_stream = Thread.current[:coolhand_capturing_stream]
       Thread.current[:coolhand_stream_buffer] = nil
+      Thread.current[:coolhand_capturing_stream] = true
 
       begin
         response = super
@@ -73,7 +95,8 @@ module Coolhand
         raise
       ensure
         active.delete(self)
-        Thread.current[:coolhand_stream_buffer] = nil
+        Thread.current[:coolhand_stream_buffer] = previous_stream_buffer
+        Thread.current[:coolhand_capturing_stream] = previous_capturing_stream
         end_time = Time.now
         duration_ms = ((end_time - start_time) * 1000).round(2)
 

data/lib/coolhand/open_ai/batch_result_processor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../coolhand"
+
 module Coolhand
   module OpenAi
     class BatchResultProcessor

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "openssl"
+
 module Coolhand
   module OpenAi
     class WebhookValidator
-      attr_reader :request, :errors, :payload, :webhook_secret
+      attr_reader :request, :errors, :payload
 
       def initialize(request, webhook_secret)
         @request = request
@@ -16,7 +18,7 @@ module Coolhand
         @payload = request.raw_post || request.body.read
 
         return false unless payload_valid?
-        return validate_in_non_production_env unless webhook_secret
+        return validate_in_non_production_env unless Coolhand.required_field?(webhook_secret)
 
         secret_bytes = extract_secret_bytes
         webhook_signature, webhook_timestamp, webhook_id = extract_webhook_headers
@@ -32,6 +34,8 @@ module Coolhand
 
       private
 
+      attr_reader :webhook_secret
+
       def payload_valid?
         return true if @payload
 

data/lib/coolhand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coolhand
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "../../coolhand"
+
 module Coolhand
   module Vertex
     class BatchResultProcessor
-      attr_reader :batch_info
+      # Global endpoint, not the job's region-specific one — matches the
+      # "aiplatform.googleapis.com" entry in default_intercept_addresses.yml
+      # so backend URL-shape classification stays consistent with the rest
+      # of the gem's Vertex traffic. The URL this produces always contains
+      # "/batchPredictionJobs/", which is also the default client-side
+      # exclude_api_patterns entry — that's harmless here since this class
+      # sends via BaseInterceptor/ApiService directly and never goes through
+      # NetHttpInterceptor's intercept/exclude filtering.
+      VERTEX_API_BASE_URL = "https://aiplatform.googleapis.com/v1/"
+      SOURCE_API = "vertex"
+      VALID_NAME_PATTERN = %r{\Aprojects/[^/?#\s]+/locations/[^/?#\s]+/batchPredictionJobs/[^/?#\s]+\z}
+
+      attr_reader :batch_info, :model
 
-      def initialize(batch_info:)
+      def initialize(batch_info:, model: nil)
         @batch_info = batch_info
+        @model = model
       end
 
       def call(batch_results = [])
@@ -16,7 +31,7 @@ module Coolhand
         when "JOB_STATE_PENDING", "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
           Rails.logger.info("[Interceptor] Vertex batch #{batch_info} still processing")
         when "JOB_STATE_SUCCEEDED"
-          batch_results.each { |batch_item| process_completed_batch(batch_item) }
+          process_completed_batch(batch_results)
         when "JOB_STATE_FAILED"
           handle_failed_batch
         else
@@ -28,56 +43,98 @@ module Coolhand
 
       private
 
-      def process_completed_batch(batch_item)
-        send_complete_request_log(request_id: SecureRandom.hex(16),
+      def process_completed_batch(batch_results)
+        name = batch_info["name"].to_s.sub(%r{\A/+}, "")
+        unless name.match?(VALID_NAME_PATTERN)
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a missing or " \
+                             "invalid job resource name (#{batch_info['name'].inspect}); skipping request log")
+          return
+        end
+
+        begin
+          start_time = Time.iso8601(batch_info["startTime"])
+          end_time   = Time.iso8601(batch_info["endTime"])
+        rescue TypeError, ArgumentError
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a missing or " \
+                             "invalid startTime/endTime; skipping request log")
+          return
+        end
+
+        if end_time < start_time
+          Rails.logger.warn("[Interceptor] Vertex batch #{batch_info['displayName']} has an endTime before " \
+                            "its startTime; sending request log(s) with duration_ms clamped to 0")
+          end_time = start_time
+        end
+
+        duration_ms = ((end_time - start_time) * 1000).to_i
+        url = "#{VERTEX_API_BASE_URL}#{name}"
+        resolved = resolved_model
+
+        sent = batch_results.count do |batch_item|
+          send_item_log(batch_item, url: url, model: resolved, start_time: start_time, end_time: end_time,
+            duration_ms: duration_ms)
+        end
+
+        # "Sent" here means dispatched to BaseInterceptor without a local
+        # error (e.g. a malformed batch_item) — BaseInterceptor swallows any
+        # downstream delivery failure itself, so this can't confirm the
+        # Coolhand API actually received the log.
+        if sent == batch_results.size
+          Rails.logger.info("[Interceptor] Dispatched #{sent} result(s) for Vertex batch " \
+                            "#{batch_info['displayName']} for logging")
+        else
+          Rails.logger.warn("[Interceptor] Dispatched #{sent}/#{batch_results.size} result(s) for Vertex " \
+                            "batch #{batch_info['displayName']} for logging — " \
+                            "#{batch_results.size - sent} item(s) were malformed and skipped")
+        end
+      end
+
+      def send_item_log(batch_item, url:, model:, start_time:, end_time:, duration_ms:)
+        unless batch_item.is_a?(Hash) && (batch_item.key?("request") || batch_item.key?("response"))
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a malformed result " \
+                             "item (#{batch_item.class}); skipping request log")
+          return false
+        end
+
+        BaseInterceptor.send_complete_request_log(
+          request_id: SecureRandom.hex(16),
           method: "POST",
-          url: batch_info["name"],
+          url: url,
+          source_api: SOURCE_API,
+          model: model,
+          request_headers: {},
           request_body: batch_item["request"],
+          response_headers: {},
           response_body: batch_item["response"],
           status_code: 200,
-          start_time: batch_info["startTime"],
-          end_time: batch_info["endTime"])
-
-        Rails.logger.info("[Interceptor] Successfully processed Vertex batch #{batch_info['displayName']}")
+          start_time: start_time,
+          end_time: end_time,
+          duration_ms: duration_ms,
+          is_streaming: false
+        )
+        true
       rescue StandardError => e
         Rails.logger.error("[Interceptor] Failed to send request log: #{e.message}")
+        false
       end
 
-      def send_complete_request_log(request_id:, method:, url:, request_body:, response_body:, status_code:,
-        start_time:, end_time:)
-        start_time = Time.iso8601(start_time)
-        end_time   = Time.iso8601(end_time)
-        duration_ms = ((end_time - start_time) * 1000).to_i
+      def resolved_model
+        candidate = [model, batch_info["model"]].find { |c| Coolhand.required_field?(c) }&.to_s&.strip
+        return if candidate.nil?
 
-        request_data = {
-          raw_request: {
-            id: request_id,
-            timestamp: start_time,
-            method: method.to_s.downcase,
-            url: url,
-            headers: {},
-            request_body: request_body,
-            response_headers: {},
-            response_body: response_body,
-            status_code: status_code,
-            duration_ms: duration_ms,
-            completed_at: end_time,
-            is_streaming: false
-          }
-        }
-
-        api_service = Coolhand::ApiService.new
-        api_service.send_llm_request_log(request_data)
-
-        Coolhand.log "📤 Sent complete request/response log for #{request_id} (duration: #{duration_ms}ms)"
-      rescue StandardError => e
-        Coolhand.log "❌ Error sending complete request log: #{e.message}"
+        # Only normalize genuine Vertex model resource paths (e.g.
+        # "publishers/google/models/gemini-2.0-flash" or
+        # "projects/P/locations/L/models/M@1") down to their bare id. A
+        # caller-supplied `model:` might itself be a provider-qualified slug
+        # that happens to contain a slash (e.g. "meta-llama/Llama-3") —
+        # leave anything that isn't a resource path untouched.
+        candidate.match?(%r{\A(publishers|projects)/}) ? candidate.split("/").last : candidate
       end
 
       # TODO: implement API to handle failed batch results and display errors on dashboard page
       def handle_failed_batch
-        Rails.logger.error("[Interceptor] Vertex batch for #{batch_info['displayName']} " \
-                           "failed: #{batch_info['error']['message']}")
+        message = batch_info["error"].is_a?(Hash) ? batch_info["error"]["message"] : batch_info["error"]
+        Rails.logger.error("[Interceptor] Vertex batch for #{batch_info['displayName']} failed: #{message}")
       end
     end
   end

data/lib/coolhand/webhook_interceptor.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "open_ai/webhook_validator"
+require_relative "open_ai/batch_result_processor"
+
 module Coolhand
   module WebhookInterceptor
     def intercept_batch_request
@@ -14,10 +17,18 @@ module Coolhand
       end
 
       payload = JSON.parse(@validator.payload)
+      raise TypeError, "webhook payload must be a JSON object, got #{payload.class}" unless payload.is_a?(Hash)
 
       process_event(payload)
     rescue StandardError => e
+      # Fail closed: any error here (malformed payload, a bug in
+      # process_event/BatchResultProcessor, etc.) must still halt the
+      # before_action chain. Falling through without calling `head` would
+      # let the controller action run for a request whose webhook
+      # signature was never confirmed valid.
       Rails.logger.error("[Interceptor] Failed to intercept batch request: #{e.message}")
+      head :unauthorized
+      false
     end
 
     def webhook_secret

data/lib/coolhand.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require "uri"
-require "faraday"
 require "securerandom"
 require "json"
 require "base64"
+require "time"
 
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -26,23 +26,20 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.2'
 description: Automatically intercept and log LLM requests from Ruby applications.
-  Supports OpenAI, official Anthropic gem, ruby-anthropic gem, and other Faraday-based
-  libraries. Features dual interceptor architecture, streaming support, thread-safe
-  operation, and automatic duplicate request prevention.
+  Supports OpenAI, official Anthropic gem, ruby-anthropic gem, Google Gemini, Google
+  Vertex AI, AWS Bedrock, OpenRouter, and any other library using Net::HTTP (directly,
+  or via Faraday's default adapter). Features a single unified Net::HTTP interceptor,
+  streaming support, thread-safe operation, and automatic duplicate request prevention.
 email:
 - mc@coolhandlabs.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/skills/loop-review/SKILL.md"
-- ".claude/skills/prep-release/SKILL.md"
-- ".idea/coolhand-ruby.iml"
 - ".rspec"
 - ".rubocop.yml"
 - ".simplecov"
 - CHANGELOG.md
-- CLAUDE.md
 - LICENSE
 - README.md
 - Rakefile
@@ -51,6 +48,8 @@ files:
 - docs/configuration.md
 - docs/elevenlabs.md
 - docs/feedback.md
+- docs/openai.md
+- docs/vertex.md
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
 - lib/coolhand/base_interceptor.rb

data/.claude/skills/loop-review/SKILL.md

@@ -1,112 +0,0 @@
----
-name: loop-review
-description: |
-  Iteratively runs code review against the current diff, applies fixes, and
-  re-reviews until a round comes back clean (or a safety cap is hit). Use
-  when the user types /loop-review, asks to "loop the review", "review
-  until clean", "keep reviewing and fixing until nothing's left", or wants
-  a self-healing code review cycle instead of a single one-shot pass.
-user_invocable: true
-version: 0.3.0
----
-
-# Loop Review
-
-This skill runs `/code-review` repeatedly against the working diff, applies
-fixes between rounds, and re-reviews until a round finds nothing new or a
-safety cap is reached. Use it after a merge, a large diff, or whenever a
-single review pass isn't enough to converge on a clean state.
-
-## Scope
-
-Default scope is the diff between the current branch and its merge-base
-with the repo's base branch (`git diff $(git merge-base origin/main
-HEAD)...HEAD`, or `origin/main` substituted with whatever base branch
-applies). If `$ARGUMENTS` names a path or a narrower scope, review only
-that instead of the full diff.
-
-This skill is deliberately diff-scoped. For a whole-package audit before a
-release (full-codebase security red-team, docs review, everything since
-the last tag) use `/prep-release` instead.
-
-`$ARGUMENTS` may also contain:
-- An effort level to pass through to `/code-review` (`low`/`medium`/
-  `high`/`high→max`/`ultra`). Default: `medium`.
-- A round cap override, e.g. `--max-rounds 3`. Default: 5.
-
-## The round loop
-
-1. Invoke `/code-review <effort> --fix` (via the `Skill` tool) against the
-   current scope.
-2. **Dry round (0 findings) → converged.** Stop and move to verification.
-3. **Findings found and fixed** → do not declare victory yet. Run another
-   round to confirm the fixes didn't introduce a regression and that
-   nothing was missed.
-4. **No-progress detection**: if two consecutive rounds return the same
-   non-empty set of findings, `--fix` isn't resolving them mechanically
-   (likely a design/architecture call that needs a human). Stop looping,
-   list the stuck findings, and hand them to the user instead of retrying
-   forever.
-5. **Safety cap**: if the round cap is reached without converging or
-   getting stuck, stop and report the remaining findings — don't loop
-   silently past the cap.
-
-Each round's fixes should stay reviewable: don't squash multiple rounds
-into one silent edit. Note per-round changes in the final summary so the
-user can inspect them with `git diff`.
-
-## Review criteria
-
-Beyond whatever `/code-review` already checks for correctness bugs and
-reuse/simplification/efficiency, every round in a Ruby gem repo like this
-one should also flag:
-
-- **Ruby idiom / DRY**: semantic, expressive naming; no duplicated logic
-  that should be extracted into a shared method; idiomatic use of
-  Ruby/Enumerable over manual loops where it reads better; no needless
-  boilerplate.
-- **Gem publishing discipline**: don't break public interfaces unless
-  necessary.
-  - If a break is necessary, it must come with: a `CHANGELOG.md` entry in
-    Keep a Changelog format (this repo already follows that format — match
-    the style of existing entries, e.g. plain-English migration notes like
-    the `0.5.0` entry) and a version bump in `lib/coolhand/version.rb` that
-    matches SemVer (patch = fix, minor = backward-compatible addition,
-    minor = breaking change while pre-1.0, consistent with this repo's own
-    versioning history).
-  - Check the optional-provider-dependency rule from this repo's
-    `CLAUDE.md`: provider SDK `require`s (`openai`, `anthropic`,
-    `google-generativeai`, etc.) must stay scoped to the file that uses
-    them and lazy-loaded, never added to `lib/coolhand.rb` or the gemspec
-    as a hard dependency.
-- **Security**: injection risks, unsafe deserialization, secrets or
-  credentials logged or committed, unvalidated input crossing a trust
-  boundary, and anything touching how API keys/tokens are handled,
-  stored, or transmitted.
-
-## Post-loop verification
-
-Once the loop converges (or stops early per the rules above), run the
-project's lint/test command and include the result in the final summary.
-For this repo that's `bundle exec rake` (runs `rspec` then `rubocop`, per
-the `Rakefile`). If a fix round changed something outside this repo's
-usual toolchain, discover the right command instead of assuming.
-
-## Rationalizations to resist
-
-- *"The first round already looked clean, I don't need a confirming
-  round."* A fix round can introduce its own regression. Always re-review
-  after applying fixes before declaring convergence.
-- *"Rubocop passed, so the review is done."* Lint passing is not the same
-  as the review being clean — lint doesn't check the criteria above
-  (interface breakage, changelog/version discipline, security). Run both.
-- *"This finding keeps coming back, I'll just keep re-running --fix and
-  it'll eventually take."* If the same non-empty finding set repeats
-  across two rounds, `--fix` isn't going to resolve it. Stop and surface
-  it — looping past that point just burns rounds for no gain.
-
-## Safety
-
-- Never force-push or amend existing commits as part of this loop.
-- The skill only edits the working tree; committing and pushing stays with
-  the user.

data/.claude/skills/prep-release/SKILL.md

@@ -1,160 +0,0 @@
----
-name: prep-release
-description: |
-  Prepares this gem for a release: runs the full test suite, updates and
-  cleans up the docs (README, CHANGELOG, docs/*.md) to reflect every change
-  since the last tag, bumps the version if that hasn't already been done,
-  and red-teams the whole package for security - not just this release's
-  diff. Never tags or pushes. Use when the user types /prep-release, asks
-  to "prep a release", "get ready to cut a release", "release checklist",
-  or wants a pre-release audit before tagging/publishing a new version.
-user_invocable: true
-version: 0.2.0
----
-
-# Prep Release
-
-Three phases, run in order. This is a whole-package audit, not a diff
-review — do not scope any phase to just what changed since the last
-commit. For an iterative diff-scoped review during normal development, use
-`/loop-review` instead; this skill is for the release boundary.
-
-## Phase 1: Run all tests
-
-Run `bundle exec rake` (`rspec` then `rubocop`, per the `Rakefile`). If a
-fix round changed something outside this repo's usual toolchain, discover
-the right command instead of assuming. All specs must pass and RuboCop
-must report zero offenses before continuing — a release doesn't ship on a
-red build. If either fails, stop here and report the failures; fixing
-genuine bugs takes priority over Phase 2/3 work.
-
-Then judge coverage on quality, not just the SimpleCov percentage the rake
-run reports (written to `coverage/`):
-
-1. **Find the gaps.** List files/lines SimpleCov marks uncovered. Weight
-   by risk: an uncovered error-handling branch or security check
-   (signature/header validation) matters more than an uncovered
-   `attr_reader`.
-2. **Audit existing tests for meaningfulness, not just count.** Flag tests
-   that only assert a stub returns what it was stubbed to return without
-   exercising real conditional logic in the subject under test; missing
-   negative/error-path cases (invalid input, malformed provider responses,
-   network failure); missing domain edge cases (empty batch results,
-   duplicate-request prevention, concurrent access, streaming vs
-   non-streaming shapes).
-3. **Recommend, don't pad.** Propose specific specs for the highest-risk
-   gaps, named by `file:describe/context`. Don't add tests purely to move
-   the percentage — a test with no failure mode it would catch adds
-   maintenance cost without adding signal.
-
-## Phase 2: Update and clean the docs
-
-1. Find the last release tag: `git describe --tags --abbrev=0`.
-2. Diff everything since that tag: `git log <last-tag>..HEAD --oneline` and
-   `git diff <last-tag>..HEAD -- lib/` to see every behavioral change, not
-   just the most recent commit.
-3. For each change, check it's reflected in:
-   - `CHANGELOG.md` — every notable change since the last tag needs an
-     entry under `[Unreleased]` (or a new version heading), in Keep a
-     Changelog format matching this repo's existing entries (see past
-     entries for style — plain-English migration notes for anything
-     behavior-affecting).
-   - `README.md` / `docs/*.md` — any new config option, public method, or
-     behavior change needs the relevant section updated. Follow this
-     repo's docs philosophy from `CLAUDE.md`: the README stays a scannable
-     landing page (basic config/feedback snippets only); anything needing
-     more than one code block belongs in `docs/`.
-4. **Clean, don't just append.** Look for docs that are now stale,
-   contradictory, or redundant given the accumulated changes since the
-   last tag — consolidate/rewrite rather than layering a new paragraph on
-   top of an outdated one. Remove docs for anything removed from the gem.
-5. **Bump the version if it hasn't already been done.** Check whether
-   `lib/coolhand/version.rb` was already bumped for the changes
-   accumulated since the last tag (e.g. by an earlier commit on this
-   branch) — if so, leave it. If not, determine the SemVer bump this
-   repo's convention implies (patch = fix, minor = backward-compatible
-   addition or breaking change while pre-1.0), write it to
-   `lib/coolhand/version.rb`, turn the `[Unreleased]` CHANGELOG heading
-   into `## [X.Y.Z] - <today's date>`, and run `bundle install` so
-   `Gemfile.lock`'s `coolhand (X.Y.Z)` line matches. State the version and
-   bump rationale in the wrap-up summary so the user can override it if
-   they'd have picked differently — don't ask before writing it, since
-   this is a mechanical, reversible edit gated by Phase 1's green build.
-
-## Phase 3: Red-team the whole package
-
-Adversarially review the entire `lib/` tree (not just this release's
-diff) for security issues. This gem intercepts outgoing LLM API traffic
-and logs it to Coolhand, so hunt specifically for:
-
-- **Credential/secret leakage**: does any interceptor, logger, or error
-  handler write an API key, bearer token, or provider auth header value
-  into a log line, exception message, or the payload sent to Coolhand?
-  Check every header-sanitization path actually strips what it claims to
-  (e.g. `WebhookValidator`, provider header redaction) rather than
-  sanitizing a differently-cased or differently-named header.
-- **Webhook/signature validation**: can `WebhookValidator#valid?` (or
-  equivalent) be bypassed — timing-unsafe comparison instead of a
-  constant-time compare, an environment where an empty/missing signature
-  is treated as valid, or a fallback path meant for development that's
-  reachable in production.
-- **SSRF / address matching**: the default and configurable intercept
-  address lists — can a crafted URL (redirect, unicode homograph,
-  userinfo trick, subdomain confusion) match or evade the intended
-  host-matching logic in a way that intercepts (or fails to intercept)
-  the wrong destination?
-- **ReDoS**: any regex built from configurable or user-influenced input
-  (intercept patterns, header names) — check for catastrophic backtracking
-  shapes (nested quantifiers, overlapping alternation).
-- **Thread safety**: this gem documents thread-safe operation and
-  duplicate-request prevention — look for unsynchronized shared mutable
-  state (class-level `@@` vars, memoized `@client` on a shared instance)
-  that a concurrent request could race on.
-- **Unsafe deserialization**: any `JSON.parse` without checking for
-  `Marshal.load`/`YAML.load` (unsafe) usage, and any parsing of
-  webhook/batch-result payloads that trusts attacker-controlled shape
-  without validation.
-- **Fail-open vs fail-closed**: when Coolhand's API is unreachable, rate
-  limited, or returns malformed data, does the gem fail open in a way that
-  silently drops security-relevant logging, or fail in a way that breaks
-  the host application's actual LLM call (the interceptor must never break
-  the underlying request)?
-
-For each finding, report file, line, a concrete failure scenario, and
-severity. Apply safe, mechanical, low-risk fixes directly (e.g. a missing
-header-redaction pattern, a missing timeout). Flag but do not silently
-apply anything that's a behavior/architecture decision (e.g. changing a
-fail-open security default, adding replay protection, moving synchronous
-work to a background thread) — surface these to the user for a decision,
-the same "hand it to a human" rule `/loop-review` uses for stuck findings.
-
-## Wrap-up
-
-Report one consolidated summary: test/lint result, coverage-quality gaps
-plus recommended specs, docs updated, the version (bumped or already
-current, and why), and security findings split into fixed vs.
-flagged-for-decision.
-
-## Safety
-
-- Bumping `lib/coolhand/version.rb`, finalizing the CHANGELOG heading, and
-  running `bundle install` for the lockfile are all in scope and don't need
-  a stop-and-ask — they're mechanical, reversible, and gated on Phase 1
-  already being green.
-- Never create or push a git tag, never push commits, and never run
-  `rake release`, `gem push`, or anything else that publishes the gem or
-  touches the remote. Tagging and publishing are the user's action once
-  they've reviewed this skill's report, not something this skill does.
-
-## Rationalizations to resist
-
-- *"The diff since the last tag is small, I'll skip the red-team."* Small
-  diffs can still sit on top of latent issues in code nobody's touched
-  recently — that's exactly what "whole package, not just the diff" means.
-- *"Tests pass, so coverage is fine."* Passing tests and meaningful
-  coverage are different questions. A red build blocks release; a green
-  build with hollow tests doesn't guarantee anything.
-- *"Docs are close enough, I'll skip the cleanup pass."* Accumulated
-  changes since the last tag are exactly when docs drift from behavior —
-  this phase exists because per-PR doc updates miss the cross-cutting
-  view.

data/.idea/coolhand-ruby.iml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module version="4">
-  <component name="ModuleRunConfigurationManager">
-    <shared />
-  </component>
-</module>

data/CLAUDE.md

@@ -1,47 +0,0 @@
-# Development Guidelines
-
-## Optional Provider Dependencies
-
-Coolhand supports multiple LLM providers (OpenAI, Anthropic, Google Gemini, etc.). These provider gems should **never** be required at gem load time, as clients may not use all providers and shouldn't be forced to install unnecessary dependencies.
-
-**Rule**: Any require for provider SDKs (openai, anthropic, google-generativeai, etc.) must be:
-1. Placed in the file where it's actually used (not in the main coolhand.rb)
-2. Only executed when that provider's functionality is accessed
-3. Not declared as a hard dependency in coolhand-ruby.gemspec
-
-Example pattern:
-```ruby
-# ❌ DON'T: In lib/coolhand.rb (loads unconditionally)
-require "openai"
-
-# ✅ DO: In lib/coolhand/open_ai/batch_result_processor.rb (only when needed)
-require "openai"
-
-module Coolhand
-  module OpenAi
-    class BatchResultProcessor
-      def client
-        @client ||= OpenAI::Client.new
-      end
-    end
-  end
-end
-```
-
-This ensures:
-- Gem loads cleanly regardless of what providers are installed
-- Apps using path gems (local development) don't break from missing optional dependencies
-- Users only need gems for providers they actually use
-
-## README and docs philosophy
-
-The README is a landing page — install, quick start, what it supports, where to go next. Keep it scannable. When in doubt, link rather than expand.
-
-**Three rules:**
-- **Config**: the basic `Coolhand.configure` snippet belongs in the README. Anything requiring more than one code block (self-hosted `base_url`, custom intercept addresses) goes in `docs/configuration.md`.
-- **Feedback**: the basic `create_feedback` snippet belongs in the README. The full field table, matching strategies, and sentiment conversion details go in `docs/feedback.md`.
-- **Integrations**: each integration gets its own `docs/<name>.md` file. The README links to them from the Documentation section.
-
-**Align with coolhand-node.** When adding a section that exists in the Node README, match its structure and tone. The two READMEs should feel like siblings.
-
-**Discoverability (SEO / AEO).** Write headings, the package description, and the supported-libraries list with search engines and AI agents in mind: use full provider/framework names (e.g. "OpenAI", "Anthropic", "Google Gemini", "Cohere") rather than abbreviations. The goal is that searches for "Ruby LLM monitoring", "Anthropic Ruby logging", or "OpenAI Ruby observability" surface this gem.