From 903e41b6dcd08a698ab7109af446bf5485f2873e Mon Sep 17 00:00:00 2001
From: sususu <suchangshan@foxmail.com>
Date: Mon, 3 Aug 2026 15:25:17 +0800
Subject: [PATCH] docs(claude): clarify exact fingerprint baseline

---
 config.example.yaml                              | 16 ++++++++--------
 internal/config/config_types.go                  | 10 +++++-----
 .../executor/helps/claude_device_profile.go      |  4 ++--
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/config.example.yaml b/config.example.yaml
index 1a69a04de..9b7dd4435 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -432,14 +432,14 @@ nonstream-keepalive-interval: 0
 # anything else is dropped so the outgoing set stays one a real client could produce.
 # Other Anthropic-compatible upstreams still forward caller betas verbatim.
 #
-# Default headers for Claude API requests. Update when Claude Code releases new versions.
-# Unconfirmed clients use this minimum CLI baseline; verified native Claude Code CLI,
-# sdk-cli, and VSCode requests preserve or may upgrade their real software fingerprint. In legacy mode,
-# user-agent/package-version/runtime-version/timeout are used as fallbacks
-# when the client omits them, while OS/arch remain runtime-derived. When
-# stabilize-device-profile is enabled, OS/arch stay pinned to the baseline values below,
-# while user-agent/package-version/runtime-version seed per-subclient software fingerprints
-# that can still upgrade independently for verified CLI and VSCode entrypoints.
+# Default headers for Claude API requests. Update only after measuring a new Claude Code release.
+# Unconfirmed clients use this CLI baseline. Verified native Claude Code CLI, sdk-cli,
+# and VSCode requests preserve their measured entrypoint and software shape only when the
+# Claude Code version, package version, and runtime version exactly match this configured
+# baseline; unmeasured versions fall back to it. In legacy mode, timeout is a fallback and
+# verified native OS/arch values remain client-supplied. When stabilize-device-profile is
+# enabled, OS/arch are pinned to the values below and cached profiles remain constrained to
+# the same exact software baseline rather than learning newer client versions.
 # claude-header-defaults:
 #   user-agent: "claude-cli/2.1.220 (external, cli)"
 #   package-version: "0.94.0"
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index e03653ff8..198750a21 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -95,11 +95,11 @@ func defaultPluginInstanceConfigNode() *yaml.Node {
 	}
 }
 
-// ClaudeHeaderDefaults configures default header values injected into Claude API requests.
-// In legacy mode, UserAgent/PackageVersion/RuntimeVersion/Timeout act as fallbacks when
-// the client omits them, while OS/Arch remain runtime-derived. When stabilized device
-// profiles are enabled, OS/Arch become the pinned platform baseline, while
-// UserAgent/PackageVersion/RuntimeVersion seed the upgradeable software fingerprint.
+// ClaudeHeaderDefaults configures the measured Claude Code software baseline.
+// Verified native requests preserve their entrypoint and software shape only when their
+// Claude Code, package, and runtime versions exactly match this baseline; unmeasured
+// versions use the configured values. Timeout remains a fallback. Stabilized profiles
+// also pin OS and Arch and never learn newer software versions automatically.
 type ClaudeHeaderDefaults struct {
 	UserAgent              string `yaml:"user-agent" json:"user-agent"`
 	PackageVersion         string `yaml:"package-version" json:"package-version"`
diff --git a/internal/runtime/executor/helps/claude_device_profile.go b/internal/runtime/executor/helps/claude_device_profile.go
index 95f5b6798..f56bf9988 100644
--- a/internal/runtime/executor/helps/claude_device_profile.go
+++ b/internal/runtime/executor/helps/claude_device_profile.go
@@ -234,8 +234,8 @@ func pinClaudeDeviceProfilePlatform(profile, baseline ClaudeDeviceProfile) Claud
 	return profile
 }
 
-// normalizeClaudeDeviceProfile keeps stabilized profiles pinned to the current
-// baseline platform and enforces the baseline software fingerprint as a floor.
+// normalizeClaudeDeviceProfile pins stabilized profiles to the configured platform
+// and replaces any software tuple that does not exactly match the measured baseline.
 func normalizeClaudeDeviceProfile(profile, baseline ClaudeDeviceProfile) ClaudeDeviceProfile {
 	profile = pinClaudeDeviceProfilePlatform(profile, baseline)
 	if !meetsClaudeDeviceProfileBaseline(profile, baseline) {