coolhand 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f66ea8b94e39769d66543c75987c2108397f89c93dc53748753b396ca76d921
-  data.tar.gz: 560b9ec89c71b31095b5f579bb270b295a79b87a7edbec495179f6f1b764f77e
+  metadata.gz: daed2b7ac4fe321602eb90f673cb385bd930b9ff503bf7e5d7851cbf06422617
+  data.tar.gz: 5d01a6386d142cdb31c490574191ac3867dabd30670c2a832c2aa18c7150c872
 SHA512:
-  metadata.gz: ebd806bb3744d3fd16673a98f7746b144b468a158ec855b32a4ba142cf110ff4a78b03ea1b95106b8f29d011425bbe0ec44b8f853acb87b9e4037cf87843991f
-  data.tar.gz: 3a8078f5dbe7f3a5c7a0892b391a7085d54b5a6aa1db386075e34470c89802ca0bd6bb5dc5654dffa7fcb2595da3df7b2210a52568595c5c77929e435d1a13b8
+  metadata.gz: a0681a3419c92e13fbae7a1b81c6d81b7a1cf2f088571dd44b4d2694c0ae5bf5c4c4312d7bff53ccc740833290bc931b932c1179244f004090192b0baaeb19f0
+  data.tar.gz: 9efd5e33528e0caeecc770c7286085320f9e4218f01fcf592ca82a27c96df71cf5ae52712a5a9aaeaf0702774be450bb7c3b7c71b0df8e57f56bd038f54f1b3d

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

@@ -0,0 +1,112 @@
+---
+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

@@ -0,0 +1,160 @@
+---
+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/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-30
+
+### Changed
+- **`llm_request_log_id` and `workload_id` in feedback API responses are now hashid strings, not raw integers** — the Coolhand API now returns these as hashids, matching every other external-facing identifier on the record (they previously leaked the raw integer foreign key). This gem never typed or coerced these fields (plain hashes throughout), so no code changes are required here, but if your application stores or compares `result[:llm_request_log_id]` or `result[:workload_id]` as an integer, update it to treat the value as an opaque string identifier instead. The `create_feedback`/`update_feedback` input fields (`llm_request_log_id`, `workload_hashid`) are unaffected — they still accept either a raw integer or a hashid string.
+- **`id` in feedback API responses has actually been a hashid string for some time** — flagging here since it's the same category of field; no gem-level change needed since this was never typed.
+- `BaseInterceptor.sanitize_headers` and `LoggerService#sanitize_headers` (used for the main request/response logging path and webhook forwarding, respectively) now share the same sensitive-header pattern instead of each maintaining its own list, so both paths redact consistently.
+
+### Security
+- **AWS Bedrock SigV4 session tokens (`X-Amz-Security-Token`) are now redacted before logging.** The interceptor's header sanitizer used a hardcoded list of known API-key header names (`api-key`, `x-api-key`, `x-goog-api-key`, `openai-api-key`) instead of a general pattern, so this header — present on requests signed with temporary/STS credentials, the common case for Bedrock — was forwarded to the Coolhand backend and printed in `debug_mode` unredacted. The sanitizer now redacts any header whose name matches `key`, `token`, `secret`, `signature`, or `authorization`, closing this and similar gaps for any current or future provider header.
+- **`debug_mode`'s "skipping capture" log line no longer prints the raw URL.** When a request matched `exclude_api_patterns` while `debug_mode` was on, the log line bypassed the usual URL sanitizer, so a Gemini/Vertex `?key=...` query-param API key could be printed in full. It now goes through the same URL sanitizer as every other log line.
+- **Outbound requests to the Coolhand backend now set a 5-second connect/read timeout.** Previously this call had no explicit timeout and ran inline on the same thread as the intercepted LLM request, so a slow or unreachable Coolhand endpoint (including a self-hosted `base_url`) could add Ruby's ~60s Net::HTTP default (up to ~120s total) of latency to real LLM calls made by the host app.
+
+### Removed
+- Deleted unused `BaseInterceptor` methods with no callers anywhere in the gem: `extract_response_data`, `extract_usage_metadata`, `clean_request_headers`, `clean_response_headers`. The latter two duplicated `sanitize_headers` with a narrower, case-sensitive header list and were never wired into any interceptor — dead code carrying its own security debt.
+
+### Dependencies
+- Bumped `faraday` from 2.14.2 to 2.14.3 (#73).
+
 ## [0.4.0] - 2026-06-22
 
 ### Added

data/CLAUDE.md

@@ -32,3 +32,16 @@ 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.

data/README.md

@@ -2,7 +2,9 @@
 
 [![Gem Version](https://badge.fury.io/rb/coolhand.svg)](https://badge.fury.io/rb/coolhand)
 
-Monitor and log LLM API calls from multiple providers (OpenAI, Anthropic, Google AI, Cohere, and more) to the Coolhand analytics platform.
+Monitor and log LLM API calls — OpenAI, Anthropic, Google Gemini, Cohere, and any Faraday-based or Net::HTTP client — to the Coolhand analytics platform. Supports Ruby LLM monitoring, request logging, and feedback collection.
+
+> **Scope**: Coolhand intercepts outgoing HTTP requests to configured LLM API endpoints only. It does not read, scan, or transmit your source code files.
 
 ## Installation
 
@@ -51,24 +53,7 @@ end
 
 ## Self-Hosted Deployments
 
-For compliance, data-residency, or cost reasons you can run your own Coolhand-compatible endpoint and point the SDK at it via `config.base_url`:
-
-```ruby
-Coolhand.configure do |config|
-  config.api_key  = ENV['COOLHAND_API_KEY']
-  config.base_url = ENV['COOLHAND_BASE_URL']  # e.g. "https://coolhand.internal.example.com/api"
-end
-```
-
-When `base_url` is unset the SDK defaults to `https://coolhandlabs.com/api` and behaviour is unchanged.
-
-**Accepted values:**
-- Any `https://` URL — required for production use
-- `http://localhost` or `http://127.0.0.1` — accepted for local development only
-
-**Trailing slashes** are stripped automatically, so `"https://example.com/api/"` and `"https://example.com/api"` are equivalent.
-
-The SDK raises `Coolhand::Error` at configure time if `base_url` is set to a plain `http://` URL pointing at a non-localhost host.
+Point the SDK at your own Coolhand-compatible endpoint via `config.base_url` for compliance or data-residency requirements. See [Self-Hosted Deployments →](docs/configuration.md).
 
 ## Feedback API
 
@@ -80,10 +65,10 @@ Collect feedback on LLM responses to improve model performance.
 require 'coolhand'
 
 # Create feedback for an LLM response
-feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
+feedback_service = Coolhand::FeedbackService.new
 
 feedback = feedback_service.create_feedback(
-  llm_request_log_id: 123,
+  llm_request_log_id: 'abc123def456', # hashid from a prior response; a raw integer FK also still works
   llm_provider_unique_id: 'req_xxxxxxx',
   client_unique_id: 'workorder-chat-456',
   creator_unique_id: 'user-789',
@@ -94,22 +79,7 @@ feedback = feedback_service.create_feedback(
 )
 ```
 
-**Field Guide:** All fields are optional, but here's how to get the best results:
-
-### Matching Fields
-- **`llm_request_log_id`** 🎯 *Exact Match* - ID from the Coolhand API response when the original LLM request was logged. Provides exact matching.
-- **`llm_provider_unique_id`** 🎯 *Exact Match* - The x-request-id from the LLM API response (e.g., "req_xxxxxxx")
-- **`original_output`** 🔍 *Fuzzy Match* - The original LLM response text. Provides fuzzy matching but isn't 100% reliable.
-- **`client_unique_id`** 🔗 *Your Internal Matcher* - Connect to an identifier from your system for internal matching
-
-### Quality Data
-- **`revised_output`** ⭐ *Best Signal* - End user revision of the LLM response. The highest value data for improving quality scores.
-- **`explanation`** 💬 *Medium Signal* - End user explanation of why the response was good or bad. Valuable qualitative data.
-- **`sentiment`** 🎭 *Preferred* - String sentiment: `'like'`, `'dislike'`, or `'neutral'`. Takes precedence over `like` if both are provided. The gem automatically converts `like` to `sentiment` before sending.
-- **`like`** 👍 *Low Signal (Deprecated)* - Boolean: `true` = like, `false` = dislike. Use `sentiment` instead. Conversion: `true` → `"like"`, `false` → `"dislike"`.
-- **`workload_hashid`** 🔗 *Workload Association* - Hashid of a workload to associate this feedback with.
-- **`creator_unique_id`** 👤 *User Tracking* - Unique ID to match feedback to the end user who created it
-- **`creator_type`** 🧑‍🤝‍🤖 *Creator Type* - What kind of creator submitted the feedback: `'human'`, `'agent'`, or `'unknown'`.
+For a full field reference and matching strategy, see [Feedback API →](docs/feedback.md).
 
 ## Rails Integration
 
@@ -138,7 +108,7 @@ end
 ```ruby
 class ChatController < ApplicationController
   def create_feedback
-    feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
+    feedback_service = Coolhand::FeedbackService.new
 
     feedback = feedback_service.create_feedback(
       llm_request_log_id: params[:log_id],
@@ -163,7 +133,7 @@ end
 ```ruby
 class FeedbackCollectionJob < ApplicationJob
   def perform(feedback_data)
-    feedback_service = Coolhand::FeedbackService.new(Coolhand.configuration)
+    feedback_service = Coolhand::FeedbackService.new
 
     feedback_service.create_feedback(
       llm_provider_unique_id: feedback_data[:request_id],
@@ -184,6 +154,7 @@ end
 |--------|------|---------|-------------|
 | `api_key` | String | `nil` | Your Coolhand API key. If absent, intercepted requests are skipped with a warning log rather than raising at boot time |
 | `enabled` | Boolean | `true` | Set to `false` to disable all patching and validation (e.g. `Rails.env.production?`) |
+| `capture` | Boolean | `true` | Whether to capture and forward intercepted requests. Set to `false` to monitor without forwarding, then use [`Coolhand.with_capture`](#selective-capture) to re-enable selectively |
 | `silent` | Boolean | `false` | Whether to suppress console output |
 | `intercept_addresses` | Array | `["api.openai.com", "api.anthropic.com"]` | Array of API endpoint strings to monitor |
 
@@ -217,6 +188,38 @@ puts response.dig("choices", 0, "message", "content")
 
 📖 **[Complete Anthropic Integration Guide →](docs/anthropic.md)** - Supports both official and community gems with automatic detection
 
+### Selective Capture
+
+Use `Coolhand.with_capture` and `Coolhand.without_capture` to override the global `capture` setting for a specific block of code, without changing your configuration.
+
+**Capture a specific call when capture is globally disabled:**
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = 'your_api_key_here'
+  config.capture = false  # disabled globally
+end
+
+Coolhand.with_capture do
+  response = openai_client.chat(parameters: {
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "Hello!" }],
+  })
+  # This request is captured and forwarded to Coolhand
+end
+```
+
+**Skip capture for a specific call when capture is globally enabled:**
+
+```ruby
+Coolhand.without_capture do
+  response = openai_client.chat(parameters: { ... })
+  # This request is NOT forwarded to Coolhand
+end
+```
+
+Both methods are thread-safe. Blocks nest correctly — the innermost block takes precedence, and the outer setting is restored when the block exits.
+
 ## Logging Inbound Webhooks
 
 For inbound webhooks (like audio transcripts or tool calls), the automatic interceptor won't capture them since they're incoming requests TO your application. In these cases, use the simple `forward_webhook` helper method:
@@ -311,11 +314,11 @@ The monitor works with multiple transport layers and Ruby libraries:
 
 ## How It Works
 
-Coolhand uses a unified Net::HTTP interceptor to monitor all HTTP traffic to configured LLM endpoints:
+Coolhand uses a unified Net::HTTP interceptor to capture outgoing requests to configured LLM API endpoints:
 
 ### Net::HTTP Interceptor
-- Patches Ruby's core `Net::HTTP` library using `Module#prepend`
-- Monitors **all** HTTP libraries that use Net::HTTP under the hood (which is most of them)
+- Extends Ruby's `Net::HTTP` using `Module#prepend` (a standard Ruby technique for wrapping library behavior)
+- Covers HTTP libraries that delegate to Net::HTTP under the hood (which is most of them)
 - Handles both standard requests and streaming responses via `read_body` interception
 - Thread-safe design using thread-local storage for streaming buffers
 
@@ -488,10 +491,12 @@ class Vertex::BatchCallbackProcessor < BaseService
 end
 ```
 
-## Integration Guides
+## Documentation
 
-- **[Anthropic Integration](docs/anthropic.md)** - Complete guide for both official and community Anthropic gems, including streaming, dual gem handling, and troubleshooting
-- **[ElevenLabs Integration](docs/elevenlabs.md)** - Complete guide for integrating ElevenLabs Conversational AI with webhook capture and feedback submission
+- **[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
 
 ## Security
 
@@ -511,6 +516,10 @@ end
 - **Contribute?** [Submit a pull request](https://github.com/Coolhand-Labs/coolhand-ruby/pulls)
 - **Support?** Visit [coolhandlabs.com](https://coolhandlabs.com)
 
+## About Coolhand Labs
+
+Coolhand Labs builds LLM observability and feedback tooling so teams can monitor, understand, and improve their AI applications. Learn more at [coolhandlabs.com](https://coolhandlabs.com).
+
 ## License
 
 Apache-2.0

data/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest published version of `coolhand` on RubyGems is supported with security fixes.
+Please upgrade to the latest version before reporting an issue.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Instead, report vulnerabilities privately using one of the following:
+
+- [GitHub Security Advisories](https://github.com/Coolhand-Labs/coolhand-ruby/security/advisories/new)
+  for this repository (preferred)
+- Email team@coolhandlabs.com
+
+Please include a description of the vulnerability, steps to reproduce, and the impact you believe
+it has. We aim to acknowledge reports within 3 business days and to provide a fix or mitigation
+plan within 30 days, depending on severity.

data/docs/configuration.md

@@ -0,0 +1,59 @@
+# Advanced Configuration
+
+## Self-Hosted Deployments
+
+For compliance, data-residency, or cost reasons you can run your own Coolhand-compatible endpoint and point the SDK at it via `config.base_url`:
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key  = ENV['COOLHAND_API_KEY']
+  config.base_url = ENV['COOLHAND_BASE_URL']  # e.g. "https://coolhand.internal.example.com/api"
+end
+```
+
+When `base_url` is unset the SDK defaults to `https://coolhandlabs.com/api` and behaviour is unchanged.
+
+**URL validation rules:**
+- Any `https://` URL — required for production use
+- `http://localhost` or `http://127.0.0.1` — accepted for local development only
+- Non-HTTPS remote URLs are rejected: the SDK raises `Coolhand::Error` at configure time if `base_url` is set to a plain `http://` URL pointing at a non-localhost host
+
+**Trailing slashes** are stripped automatically, so `"https://example.com/api/"` and `"https://example.com/api"` are equivalent.
+
+---
+
+## Debug Mode
+
+`config.debug_mode` is a local-development aid: it prints every prepared payload to the console instead of sending it to the Coolhand API (or your self-hosted `base_url`), so you can inspect exactly what would be logged without an API key or network access.
+
+```ruby
+Coolhand.configure do |config|
+  config.debug_mode = Rails.env.development?
+end
+```
+
+**What changes when `debug_mode` is `true`:**
+- No HTTP request is made — `create_log`, `create_feedback`, and `send_llm_request_log` all return `nil` and print the payload via `JSON.pretty_generate` instead.
+- Capture is forced on for every request, including inside a `Coolhand.without_capture` block and when `config.capture = false`. This is intentional — debug mode is meant to show you everything, not respect capture suppression — so don't leave it enabled in an environment where you rely on `without_capture` to keep specific calls out of the logs.
+- Header and URL sanitization (`[REDACTED]` API keys/tokens, redacted `key=`/`token=` query params) still applies to the printed payload, exactly as it would to a real request.
+
+Because it forces capture unconditionally and prints full request/response bodies to the console, only enable `debug_mode` in development — never in production or in an environment handling real user data.
+
+## Custom Intercept Addresses
+
+By default Coolhand captures requests to a built-in list of LLM API hosts (OpenAI, Anthropic, Google Gemini, ElevenLabs, GitHub Models, and more). To capture a custom endpoint — an internal proxy, a self-hosted model server, or a third-party gateway — override `intercept_addresses`:
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = ENV['COOLHAND_API_KEY']
+  config.intercept_addresses = [
+    'my-llm-proxy.internal',
+    'api.openai.com',      # include the defaults you still want
+    'api.anthropic.com',
+  ]
+end
+```
+
+Setting `intercept_addresses` **replaces** the default list entirely, so include any default hosts you still need.
+
+The default list can be found in `Coolhand::Configuration::DEFAULT_INTERCEPT_ADDRESSES`.

data/docs/feedback.md

@@ -0,0 +1,79 @@
+# Feedback API
+
+Collect user feedback on LLM responses to improve your AI outputs. The Feedback API lets you capture sentiment ratings, explanations, and human-corrected outputs.
+
+> **Frontend widget:** For browser-based feedback collection, see [coolhand-js](https://github.com/Coolhand-Labs/coolhand-js) — a lightweight JavaScript widget that captures actionable user feedback on any AI output.
+
+## Basic Usage
+
+```ruby
+require 'coolhand'
+
+feedback_service = Coolhand::FeedbackService.new
+
+# Positive feedback linked by log ID (most reliable)
+feedback_service.create_feedback(
+  llm_request_log_id: 'abc123def456', # hashid from a prior response; a raw integer FK also still works
+  sentiment: 'like',
+  explanation: 'Clear and accurate answer.',
+)
+
+# Negative feedback with a human correction
+feedback_service.create_feedback(
+  original_output: 'The capital of France is London.',
+  sentiment: 'dislike',
+  revised_output: 'The capital of France is Paris.',
+  explanation: 'Factually wrong.',
+)
+```
+
+---
+
+## Field Reference
+
+All fields are optional. Use at least one **Matching Field** to link feedback to its originating LLM request.
+
+### Matching Fields
+
+These fields identify which LLM request the feedback refers to. Use the most specific one available.
+
+| Field | Match type | Description |
+|---|---|---|
+| `llm_request_log_id` | Exact | Hashid returned when the original request was logged (a raw integer FK is also still accepted for backward compatibility). Most reliable. |
+| `llm_provider_unique_id` | Exact | The provider's own request ID (e.g. `x-request-id` from Anthropic or OpenAI). |
+| `client_unique_id` | Exact | Your own internal identifier for the request (e.g. a database row ID). |
+| `original_output` | Fuzzy | The raw text the LLM produced. Used for fuzzy matching when no ID is available — less reliable. |
+
+### Quality Signals
+
+| Field | Signal strength | Description |
+|---|---|---|
+| `revised_output` | ⭐ Best | The human-corrected version of the LLM output. Highest-value signal for quality improvement. |
+| `explanation` | Medium | Free-text reason the response was good or bad. |
+| `sentiment` | Low–Medium | `"like"`, `"dislike"`, or `"neutral"`. **Preferred** over the deprecated `like` boolean. |
+| `like` | Low (deprecated) | Boolean: `true` = like, `false` = dislike. Auto-converted to `sentiment` before submission. Use `sentiment` instead. |
+
+### Attribution Fields
+
+| Field | Description |
+|---|---|
+| `creator_unique_id` | ID of the user providing feedback (for per-user quality tracking). |
+| `creator_type` | Who submitted the feedback: `"human"`, `"agent"`, or `"unknown"`. |
+| `workload_hashid` | Associate feedback with a specific workload in the Coolhand dashboard. |
+
+---
+
+## Sentiment Values
+
+| Value | Meaning |
+|---|---|
+| `"like"` | The response was helpful / correct |
+| `"dislike"` | The response was unhelpful / wrong |
+| `"neutral"` | Neither good nor bad (e.g. factual but irrelevant) |
+
+The deprecated `like: bool` field is still accepted and automatically converted:
+
+| `like` (bool) | Equivalent `sentiment` |
+|---|---|
+| `true` | `"like"` |
+| `false` | `"dislike"` |

data/lib/coolhand/api_service.rb

@@ -70,6 +70,11 @@ module Coolhand
       uri = URI.parse(@api_endpoint)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = (uri.scheme == "https")
+      # Bound worst-case latency: this call happens inline in the intercepted
+      # request's path, so a slow/unreachable Coolhand backend must not hang
+      # the host app's real LLM call for Ruby's ~60s Net::HTTP defaults.
+      http.open_timeout = 5
+      http.read_timeout = 5
 
       request = Net::HTTP::Post.new(uri.request_uri)
       headers = create_request_options(payload)

data/lib/coolhand/base_interceptor.rb

@@ -5,93 +5,12 @@ module Coolhand
   module BaseInterceptor
     module_function
 
-    def extract_response_data(response)
-      case response
-      when Hash
-        response
-      when Struct
-        response.to_h
-      else
-        # Handle streaming responses - these are often enumerator objects
-        # that can't be serialized directly
-        if response.class.name.include?("Stream") || response.respond_to?(:each)
-          {
-            response_type: "streaming",
-            class: response.class.name,
-            note: "Streaming response - content captured during enumeration"
-          }
-        elsif response.respond_to?(:to_h)
-          begin
-            response.to_h
-          rescue StandardError => e
-            {
-              serialization_error: e.message,
-              class: response.class.name,
-              raw_response: response.to_s
-            }
-          end
-        else
-          # Extract content and token usage information
-          response_data = {}
-
-          # Get content
-          response_data[:content] = response.content if response.respond_to?(:content)
-
-          # Extract token usage information
-          response_data[:usage] = extract_usage_metadata(response.usage) if response.respond_to?(:usage)
-
-          # Extract model information
-          response_data[:model] = response.model if response.respond_to?(:model)
-
-          # Extract role information
-          response_data[:role] = response.role if response.respond_to?(:role)
-
-          # Extract ID if available
-          response_data[:id] = response.id if response.respond_to?(:id)
-
-          # Extract stop reason if available
-          response_data[:stop_reason] = response.stop_reason if response.respond_to?(:stop_reason)
-
-          # Add class info for debugging
-          response_data[:class] = response.class.name
-
-          response_data.empty? ? { raw_response: response.to_s, class: response.class.name } : response_data
-        end
-      end
-    end
-
-    def extract_usage_metadata(usage)
-      if usage.respond_to?(:to_h)
-        usage.to_h
-      elsif usage.is_a?(Hash)
-        usage
-      else
-        # Extract individual usage fields
-        usage_data = {}
-        usage_data[:input_tokens] = usage.input_tokens if usage.respond_to?(:input_tokens)
-        usage_data[:output_tokens] = usage.output_tokens if usage.respond_to?(:output_tokens)
-        usage_data[:total_tokens] = usage_data[:input_tokens].to_i + usage_data[:output_tokens].to_i
-        usage_data
-      end
-    end
-
-    def clean_request_headers(headers)
-      cleaned = headers.dup
-
-      # Remove sensitive headers
-      cleaned.delete("Authorization")
-      cleaned.delete("authorization")
-      cleaned.delete("x-api-key")
-      cleaned.delete("X-API-Key")
-
-      cleaned
-    end
-
-    def clean_response_headers(headers)
-      # Response headers typically don't contain sensitive data
-      # but we can filter if needed
-      headers.dup
-    end
+    # 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
 
     def sanitize_headers(headers)
       return {} if headers.nil?
@@ -122,7 +41,6 @@ module Coolhand
 
       sanitized = raw.dup
 
-      sanitized_keys = %w[openai-api-key api-key x-api-key x-goog-api-key]
       sanitized.each do |k, v|
         next if v.nil?
 
@@ -134,7 +52,7 @@ module Coolhand
           else
             "[REDACTED]"
           end
-        elsif sanitized_keys.include?(key_down)
+        elsif key_down.match?(SENSITIVE_HEADER_PATTERN)
           sanitized[k] = "[REDACTED]"
         end
       end

data/lib/coolhand/logger_service.rb

@@ -73,8 +73,9 @@ module Coolhand
         # Convert Rails HTTP_ prefix headers
         clean_key = key.to_s.gsub(/^HTTP_/, "").tr("_", "-").downcase
 
-        # Redact sensitive headers
-        clean_value = clean_key.match?(/key|token|secret|authorization|signature/i) ? "[REDACTED]" : value.to_s
+        # Redact sensitive headers (shared with BaseInterceptor so both logging
+        # paths treat the same header names as sensitive)
+        clean_value = clean_key.match?(BaseInterceptor::SENSITIVE_HEADER_PATTERN) ? "[REDACTED]" : value.to_s
         clean_headers[clean_key] = clean_value
       end
       clean_headers

data/lib/coolhand/net_http_interceptor.rb

@@ -141,7 +141,7 @@ module Coolhand
 
       matched = patterns.find { |pattern| url.include?(pattern) }
       if matched && Coolhand.configuration.debug_mode
-        Coolhand.log "🚫 Skipping capture for #{url} (matched exclude_api_pattern: \"#{matched}\")"
+        Coolhand.log "🚫 Skipping capture for #{sanitize_url(url)} (matched exclude_api_pattern: \"#{matched}\")"
       end
       !!matched
     end

data/lib/coolhand/version.rb

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

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Michael Carroll
 - Yaroslav Malyk
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-22 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -34,6 +35,8 @@ 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"
@@ -43,8 +46,11 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - docs/anthropic.md
+- docs/configuration.md
 - docs/elevenlabs.md
+- docs/feedback.md
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
 - lib/coolhand/base_interceptor.rb
@@ -70,6 +76,7 @@ metadata:
   source_code_uri: https://github.com/Coolhand-Labs/coolhand-ruby
   changelog_uri: https://github.com/Coolhand-Labs/coolhand-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -84,7 +91,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Monitor and log LLM API calls from OpenAI, Anthropic, and other providers
   to Coolhand analytics.