diff --git a/cli/migrations/agent-trace-repository/008_claude_session_auth_state.sql b/cli/migrations/agent-trace-repository/008_claude_session_auth_state.sql new file mode 100644 index 000000000..897ecb248 --- /dev/null +++ b/cli/migrations/agent-trace-repository/008_claude_session_auth_state.sql @@ -0,0 +1,8 @@ +CREATE TABLE IF NOT EXISTS claude_session_auth_state ( + session_id TEXT PRIMARY KEY, + provider TEXT NOT NULL CHECK (provider IN ('anthropic', 'aws_bedrock', 'google_vertex', 'microsoft_foundry', 'custom_gateway', 'unknown')), + billing_mode TEXT NOT NULL CHECK (billing_mode IN ('api_key', 'subscription', 'cloud_provider', 'unknown')), + auth_env_key TEXT CHECK (auth_env_key IS NULL OR auth_env_key IN ('claude_code_use_bedrock', 'claude_code_use_vertex', 'claude_code_use_foundry', 'anthropic_auth_token', 'anthropic_api_key', 'claude_code_oauth_token')), + confidence TEXT NOT NULL CHECK (confidence IN ('inferred', 'unknown')), + observed_at_ms INTEGER NOT NULL CHECK (observed_at_ms >= 0) +); diff --git a/cli/src/services/agent_trace_db/mod.rs b/cli/src/services/agent_trace_db/mod.rs index ed50c7e9e..5b78626a1 100644 --- a/cli/src/services/agent_trace_db/mod.rs +++ b/cli/src/services/agent_trace_db/mod.rs @@ -3,6 +3,7 @@ use turso::Value as TursoValue; use crate::services::{ db::{DbSpec, TursoDb}, + hooks::claude_auth_detection::{AuthEnvKey, AuthProvider, BillingMode, DetectionConfidence}, patch::{parse_patch, ParseError, ParsedPatch}, structured_patch::{derive_claude_structured_patch, ClaudeStructuredPatchDerivationResult}, }; @@ -132,6 +133,38 @@ FROM claude_model_state WHERE session_id = ?1 AND agent_id = ?2 LIMIT 1"; +/// Change-only: an identical classification leaves the row, including +/// `observed_at_ms`, untouched. `auth_env_key` is nullable, so it compares with `IS NOT`. +pub const UPSERT_CLAUDE_SESSION_AUTH_STATE_SQL: &str = "INSERT INTO claude_session_auth_state ( + session_id, + provider, + billing_mode, + auth_env_key, + confidence, + observed_at_ms +) VALUES (?1, ?2, ?3, ?4, ?5, ?6) +ON CONFLICT (session_id) DO UPDATE SET + provider = excluded.provider, + billing_mode = excluded.billing_mode, + auth_env_key = excluded.auth_env_key, + confidence = excluded.confidence, + observed_at_ms = excluded.observed_at_ms +WHERE excluded.provider <> claude_session_auth_state.provider + OR excluded.billing_mode <> claude_session_auth_state.billing_mode + OR excluded.auth_env_key IS NOT claude_session_auth_state.auth_env_key + OR excluded.confidence <> claude_session_auth_state.confidence"; + +pub const SELECT_CLAUDE_SESSION_AUTH_STATE_SQL: &str = "SELECT + session_id, + provider, + billing_mode, + auth_env_key, + confidence, + observed_at_ms +FROM claude_session_auth_state +WHERE session_id = ?1 +LIMIT 1"; + const CONVERSATION_TEXT_EVENT_OPERATION_NAME: &str = "insert conversation text event"; const CONVERSATION_TEXT_EVENT_RETRY_HINT: &str = "retry after the database lock clears; if the issue persists, stop other SCE processes using this database and rerun the command"; @@ -179,6 +212,22 @@ pub struct ClaudeModelStateObservation { pub observed_at_ms: i64, } +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct ClaudeSessionAuthState { + pub session_id: String, + pub provider: AuthProvider, + pub billing_mode: BillingMode, + pub auth_env_key: Option, + pub confidence: DetectionConfidence, + pub observed_at_ms: i64, +} + +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum ClaudeSessionAuthStateUpsertOutcome { + Upserted { rows_changed: u64 }, + SkippedMissingMigration, +} + #[derive(Clone, Debug, Eq, PartialEq)] pub struct DiffTracePatchRow { pub id: i64, @@ -426,6 +475,71 @@ fn claude_model_state_observation_from_turso( }) } +async fn upsert_claude_session_auth_state_with( + db: &TursoDb, + input: ClaudeSessionAuthState, +) -> Result { + db.execute( + UPSERT_CLAUDE_SESSION_AUTH_STATE_SQL, + ( + input.session_id, + input.provider.as_str(), + input.billing_mode.as_str(), + input.auth_env_key.map(AuthEnvKey::as_str), + input.confidence.as_str(), + input.observed_at_ms, + ), + ) + .await +} + +async fn claude_session_auth_state_by_session_with( + db: &TursoDb, + session_id: &str, +) -> Result> { + let rows = db + .query_map( + SELECT_CLAUDE_SESSION_AUTH_STATE_SQL, + (session_id,), + claude_session_auth_state_from_turso, + ) + .await?; + + Ok(rows.into_iter().next()) +} + +fn claude_session_auth_state_from_turso(row: &turso::Row) -> Result { + Ok(ClaudeSessionAuthState { + session_id: row + .get(0) + .context("failed to read claude_session_auth_state.session_id")?, + provider: AuthProvider::from_str( + row.get::(1) + .context("failed to read claude_session_auth_state.provider")? + .as_str(), + )?, + billing_mode: BillingMode::from_str( + row.get::(2) + .context("failed to read claude_session_auth_state.billing_mode")? + .as_str(), + )?, + auth_env_key: row + .get::>(3) + .context("failed to read claude_session_auth_state.auth_env_key")? + .as_deref() + .map(AuthEnvKey::from_str) + .transpose()?, + confidence: DetectionConfidence::from_str( + row.get::(4) + .context("failed to read claude_session_auth_state.confidence")? + .as_str(), + )?, + observed_at_ms: row + .get(5) + .context("failed to read claude_session_auth_state.observed_at_ms")?, + }) +} + async fn insert_messages_with( db: &TursoDb, inputs: Vec, diff --git a/cli/src/services/agent_trace_db/repository.rs b/cli/src/services/agent_trace_db/repository.rs index a19e3d48b..1042a41c8 100644 --- a/cli/src/services/agent_trace_db/repository.rs +++ b/cli/src/services/agent_trace_db/repository.rs @@ -12,7 +12,8 @@ use super::{ diff_trace_patches_before_commit_with, insert_agent_trace_with, insert_conversation_text_event_with, insert_diff_trace_with, insert_messages_with, insert_parts_with, insert_post_commit_patch_intersection_with, recent_diff_trace_patches_with, - upsert_claude_model_state_with, AgentTraceInsert, ClaudeModelStateObservation, + upsert_claude_model_state_with, upsert_claude_session_auth_state_with, AgentTraceInsert, + ClaudeModelStateObservation, ClaudeSessionAuthState, ClaudeSessionAuthStateUpsertOutcome, CommitTimeCutoff, DiffTraceInsert, InsertMessageInsert, InsertPartInsert, PostCommitPatchIntersectionInsert, RecentDiffTracePatches, }; @@ -23,6 +24,9 @@ const SELECT_REPOSITORY_METADATA_SQL: &str = "SELECT repository_id, source_instance_id FROM repository_metadata WHERE id = 1"; const SELECT_SQLITE_OBJECT_SQL: &str = "SELECT name FROM sqlite_master WHERE type = ?1 AND name = ?2 LIMIT 1"; +const SELECT_APPLIED_MIGRATION_IDS_SQL: &str = "SELECT id FROM __sce_migrations"; +const HOOK_RUNTIME_OPTIONAL_MIGRATION_ID: &str = "008_claude_session_auth_state"; +const SELECT_MIGRATION_APPLIED_SQL: &str = "SELECT id FROM __sce_migrations WHERE id = ?1 LIMIT 1"; const RECORD_REPOSITORY_SCHEMA_MIGRATION_SQL: &str = "INSERT OR IGNORE INTO __sce_migrations (id) VALUES ('001_repository_schema')"; const REQUIRED_REPOSITORY_SCHEMA_TABLES: &[&str] = &[ @@ -246,7 +250,56 @@ impl RepositoryAgentTraceDb { .await } + /// Hook-runtime readiness: strict parity, or strict parity minus exactly + /// [`HOOK_RUNTIME_OPTIONAL_MIGRATION_ID`], so hooks keep working until + /// `sce setup` applies that migration. Setup, repair, and doctor stay strict. + pub async fn ensure_schema_ready_for_hook_runtime(&self) -> Result<()> { + let strict = self.ensure_schema_ready_for_hooks().await; + if strict.is_err() + && self + .ledger_lacks_only_hook_runtime_optional_migration() + .await? + { + return Ok(()); + } + strict + } + + async fn ledger_lacks_only_hook_runtime_optional_migration(&self) -> Result { + if !self + .sqlite_object_exists("table", "__sce_migrations") + .await? + { + return Ok(false); + } + let mut applied_ids = self + .query_map(SELECT_APPLIED_MIGRATION_IDS_SQL, (), |row| { + row.get::(0).map_err(Into::into) + }) + .await?; + applied_ids.sort_unstable(); + let mut expected_ids = generated_migrations::AGENT_TRACE_REPOSITORY_MIGRATIONS + .iter() + .map(|(id, _)| *id) + .filter(|id| *id != HOOK_RUNTIME_OPTIONAL_MIGRATION_ID) + .collect::>(); + expected_ids.sort_unstable(); + Ok(applied_ids == expected_ids) + } + pub async fn repair_missing_repository_schema_migration_metadata(&self) -> Result<()> { + self.record_repository_schema_migration_metadata().await?; + self.ensure_schema_ready_for_hooks().await + } + + pub async fn repair_missing_repository_schema_migration_metadata_for_hook_runtime( + &self, + ) -> Result<()> { + self.record_repository_schema_migration_metadata().await?; + self.ensure_schema_ready_for_hook_runtime().await + } + + async fn record_repository_schema_migration_metadata(&self) -> Result<()> { for table in REQUIRED_REPOSITORY_SCHEMA_TABLES { if !self.sqlite_object_exists("table", table).await? { anyhow::bail!( @@ -258,7 +311,7 @@ impl RepositoryAgentTraceDb { self.execute(RECORD_REPOSITORY_SCHEMA_MIGRATION_SQL, ()) .await?; - self.ensure_schema_ready_for_hooks().await + Ok(()) } async fn sqlite_object_exists(&self, object_type: &str, name: &str) -> Result { @@ -370,6 +423,45 @@ impl RepositoryAgentTraceDb { super::claude_model_state_by_session_and_agent_with(self, session_id, agent_id).await } + /// Skips without writing when the hook-runtime-optional migration that + /// creates `claude_session_auth_state` has not been applied yet. + pub async fn upsert_claude_session_auth_state( + &self, + input: ClaudeSessionAuthState, + ) -> Result { + if !self + .migration_applied(HOOK_RUNTIME_OPTIONAL_MIGRATION_ID) + .await? + { + return Ok(ClaudeSessionAuthStateUpsertOutcome::SkippedMissingMigration); + } + let rows_changed = upsert_claude_session_auth_state_with(self, input).await?; + Ok(ClaudeSessionAuthStateUpsertOutcome::Upserted { rows_changed }) + } + + #[cfg_attr( + not(test), + expect( + dead_code, + reason = "latest-state read interface has no production reader until a future export change" + ) + )] + pub async fn claude_session_auth_state_by_session( + &self, + session_id: &str, + ) -> Result> { + super::claude_session_auth_state_by_session_with(self, session_id).await + } + + async fn migration_applied(&self, migration_id: &str) -> Result { + let rows = self + .query_map(SELECT_MIGRATION_APPLIED_SQL, (migration_id,), |row| { + row.get::(0).map_err(Into::into) + }) + .await?; + Ok(!rows.is_empty()) + } + pub async fn recent_diff_trace_patches( &self, cutoff_time_ms: i64, diff --git a/cli/src/services/agent_trace_storage/mod.rs b/cli/src/services/agent_trace_storage/mod.rs index 02b99c673..a10dac6b0 100644 --- a/cli/src/services/agent_trace_storage/mod.rs +++ b/cli/src/services/agent_trace_storage/mod.rs @@ -161,8 +161,8 @@ async fn open_repository_db_for_hook_runtime( ) -> Result<(RepositoryAgentTraceDb, RepositoryMetadata)> { let db = RepositoryAgentTraceDb::open_for_hooks_without_migrations_at(db_path).await?; - if db.ensure_schema_ready_for_hooks().await.is_err() { - db.repair_missing_repository_schema_migration_metadata() + if db.ensure_schema_ready_for_hook_runtime().await.is_err() { + db.repair_missing_repository_schema_migration_metadata_for_hook_runtime() .await?; } @@ -230,8 +230,14 @@ mod tests { use crate::services::agent_trace_db::repository::{ ExistingRepositoryDbError, RepositoryAgentTraceDb, }; - use crate::services::agent_trace_db::AgentTraceInsert; + use crate::services::agent_trace_db::{ + AgentTraceInsert, ClaudeModelStateObservation, ClaudeSessionAuthState, + ClaudeSessionAuthStateUpsertOutcome, DiffTraceInsert, ObservationKind, + }; use crate::services::db::{DatabaseKind, DbSpec, TursoDb}; + use crate::services::hooks::claude_auth_detection::{ + AuthEnvKey, AuthProvider, BillingMode, DetectionConfidence, + }; const COMMIT_PATCH_ID_MIGRATION: &str = "007_commit_patch_id"; const PRE_COMMIT_PATCH_ID_REPOSITORY_ID: &str = "commit-patch-id-repo"; @@ -260,6 +266,31 @@ mod tests { const KIND: DatabaseKind = DatabaseKind::AgentTrace; } + const CLAUDE_SESSION_AUTH_STATE_MIGRATION: &str = "008_claude_session_auth_state"; + const PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID: &str = "claude-session-auth-repo"; + + struct Pre008RepositoryAgentTraceDbSpec; + + impl DbSpec for Pre008RepositoryAgentTraceDbSpec { + fn db_name() -> &'static str { + "pre-008 repository Agent Trace DB" + } + + fn db_path() -> anyhow::Result { + anyhow::bail!("pre-008 fixture uses explicit paths") + } + + fn migrations() -> &'static [(&'static str, &'static str)] { + let position = AGENT_TRACE_REPOSITORY_MIGRATIONS + .iter() + .position(|(id, _)| *id == CLAUDE_SESSION_AUTH_STATE_MIGRATION) + .expect("Claude session auth state migration is embedded"); + &AGENT_TRACE_REPOSITORY_MIGRATIONS[..position] + } + + const KIND: DatabaseKind = DatabaseKind::AgentTrace; + } + type AgentTraceRow = ( i64, String, @@ -514,4 +545,483 @@ mod tests { "state root must stay empty: {entries:?}" ); } + + async fn create_pre_claude_session_auth_db(path: &Path) { + let db = TursoDb::::new_at(path) + .await + .expect("pre-008 database"); + db.execute( + "INSERT INTO repository_metadata (id, repository_id, source_instance_id) VALUES (1, ?1, 'pre-008-source-instance')", + (PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID,), + ) + .await + .expect("seed metadata"); + } + + async fn create_current_db(path: &Path) -> RepositoryAgentTraceDb { + let (db, _metadata) = + open_repository_db_concurrently_safe(path, PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID) + .await + .expect("setup open"); + db + } + + async fn claude_session_auth_state_table_exists(db: &RepositoryAgentTraceDb) -> bool { + !db.query_map( + "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'claude_session_auth_state'", + (), + |row| row.get::(0).map_err(Into::into), + ) + .await + .expect("sqlite_master lookup") + .is_empty() + } + + async fn assert_hook_runtime_rejects(path: &Path, expected_problem: &str) { + let Err(error) = + open_repository_db_for_hook_runtime(path, PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID).await + else { + panic!("hook runtime must reject a ledger with {expected_problem}"); + }; + let message = format!("{error:#}"); + assert!(message.contains("Run 'sce setup'."), "{message}"); + assert!(message.contains(expected_problem), "{message}"); + } + + #[test] + fn agent_trace_repository_migrations_end_with_claude_session_auth_state() { + let ids: Vec<&str> = AGENT_TRACE_REPOSITORY_MIGRATIONS + .iter() + .map(|(id, _)| *id) + .collect(); + assert_eq!( + ids, + vec![ + "001_repository_schema", + "002_repository_source_instance_id", + "003_claude_model_state", + "004_mutation_trace_protocol", + "005_mutation_scope_provenance", + "006_mutation_trace_health_invariant", + COMMIT_PATCH_ID_MIGRATION, + CLAUDE_SESSION_AUTH_STATE_MIGRATION, + ] + ); + } + + #[tokio::test(flavor = "multi_thread")] + async fn agent_trace_repository_migrations_create_constrained_claude_session_auth_state() { + let dir = tempfile::tempdir().expect("temp dir"); + let db = create_current_db(&dir.path().join("agent-trace.db")).await; + + let columns = db + .query_map("PRAGMA table_info(claude_session_auth_state)", (), |row| { + Ok(( + row.get::(1)?, + row.get::(3)?, + row.get::(5)?, + )) + }) + .await + .expect("claude_session_auth_state table info"); + assert_eq!( + columns, + vec![ + (String::from("session_id"), 0, 1), + (String::from("provider"), 1, 0), + (String::from("billing_mode"), 1, 0), + (String::from("auth_env_key"), 0, 0), + (String::from("confidence"), 1, 0), + (String::from("observed_at_ms"), 1, 0), + ] + ); + + db.execute( + "INSERT INTO claude_session_auth_state (session_id, provider, billing_mode, auth_env_key, confidence, observed_at_ms) VALUES ('claude:valid', 'aws_bedrock', 'cloud_provider', 'claude_code_use_bedrock', 'inferred', 0)", + (), + ) + .await + .expect("valid row"); + db.execute( + "INSERT INTO claude_session_auth_state (session_id, provider, billing_mode, auth_env_key, confidence, observed_at_ms) VALUES ('claude:unknown', 'unknown', 'unknown', NULL, 'unknown', 5)", + (), + ) + .await + .expect("unknown row with no env key"); + + for (column, invalid_row) in [ + ( + "provider", + "('claude:bad', 'openai', 'unknown', NULL, 'unknown', 1)", + ), + ( + "billing_mode", + "('claude:bad', 'unknown', 'free', NULL, 'unknown', 1)", + ), + ( + "auth_env_key", + "('claude:bad', 'unknown', 'unknown', 'anthropic_base_url', 'unknown', 1)", + ), + ( + "confidence", + "('claude:bad', 'unknown', 'unknown', NULL, 'verified', 1)", + ), + ( + "observed_at_ms", + "('claude:bad', 'unknown', 'unknown', NULL, 'unknown', -1)", + ), + ] { + let insert = format!( + "INSERT INTO claude_session_auth_state (session_id, provider, billing_mode, auth_env_key, confidence, observed_at_ms) VALUES {invalid_row}" + ); + assert!( + db.execute(&insert, ()).await.is_err(), + "invalid {column} must be rejected" + ); + } + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_schema_compat_hook_runtime_opens_pre_008_database() { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + create_pre_claude_session_auth_db(&path).await; + + let (db, metadata) = + open_repository_db_for_hook_runtime(&path, PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID) + .await + .expect("hook runtime opens pre-008 database"); + + assert_eq!( + metadata.repository_id, + PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID + ); + assert!(!applied_migration_ids(&db) + .await + .iter() + .any(|id| id == CLAUDE_SESSION_AUTH_STATE_MIGRATION)); + assert!(!claude_session_auth_state_table_exists(&db).await); + + let observation = ClaudeModelStateObservation { + session_id: String::from("claude:pre-008-session"), + agent_id: String::new(), + model_id: String::from("claude-opus-5-5"), + observation_kind: ObservationKind::SessionStart, + source: String::from("startup"), + observed_at_ms: 3, + }; + db.upsert_claude_model_state(observation.clone()) + .await + .expect("model state persists on pre-008 database"); + assert_eq!( + db.claude_model_state_by_session_and_agent("claude:pre-008-session", "") + .await + .expect("model state read"), + Some(observation) + ); + db.insert_diff_trace(DiffTraceInsert { + time_ms: 4, + session_id: "claude:pre-008-session", + patch: "diff --git a/f b/f\n", + model_id: None, + tool_name: "claude", + tool_version: None, + payload_type: "claude_post_tool_use", + }) + .await + .expect("diff trace persists on pre-008 database"); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_schema_compat_hook_runtime_opens_current_database() { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + create_current_db(&path).await; + + let (db, _metadata) = + open_repository_db_for_hook_runtime(&path, PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID) + .await + .expect("hook runtime opens current database"); + assert_eq!(applied_migration_ids(&db).await, expected_migration_ids()); + assert!(claude_session_auth_state_table_exists(&db).await); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_schema_compat_setup_applies_008_to_pre_008_database() { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + create_pre_claude_session_auth_db(&path).await; + + let db = create_current_db(&path).await; + + assert_eq!(applied_migration_ids(&db).await, expected_migration_ids()); + assert!(claude_session_auth_state_table_exists(&db).await); + db.ensure_schema_ready_for_hooks() + .await + .expect("upgraded schema passes strict readiness"); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_schema_compat_doctor_rejects_pre_008_database_before_setup() { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + create_pre_claude_session_auth_db(&path).await; + + let Err(doctor_error) = + RepositoryAgentTraceDb::open_existing_schema_ready_at(&path, || {}).await + else { + panic!("doctor readiness must reject a pre-008 database"); + }; + assert!(matches!( + doctor_error, + ExistingRepositoryDbError::IncompatibleSchema(_) + )); + assert!(doctor_error + .to_string() + .contains(CLAUDE_SESSION_AUTH_STATE_MIGRATION)); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_schema_compat_hook_runtime_rejects_other_missing_migration() { + for removed in [ + vec![COMMIT_PATCH_ID_MIGRATION], + vec![ + COMMIT_PATCH_ID_MIGRATION, + CLAUDE_SESSION_AUTH_STATE_MIGRATION, + ], + ] { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + let db = create_current_db(&path).await; + for id in &removed { + db.execute("DELETE FROM __sce_migrations WHERE id = ?1", (*id,)) + .await + .expect("remove ledger row"); + } + drop(db); + + assert_hook_runtime_rejects(&path, COMMIT_PATCH_ID_MIGRATION).await; + } + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_schema_compat_hook_runtime_rejects_unexpected_migration() { + for remove_optional in [false, true] { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + let db = create_current_db(&path).await; + if remove_optional { + db.execute( + "DELETE FROM __sce_migrations WHERE id = ?1", + (CLAUDE_SESSION_AUTH_STATE_MIGRATION,), + ) + .await + .expect("remove optional ledger row"); + } + db.execute( + "INSERT INTO __sce_migrations (id) VALUES ('999_unexpected_future')", + (), + ) + .await + .expect("insert unexpected ledger row"); + drop(db); + + assert_hook_runtime_rejects(&path, "999_unexpected_future").await; + } + } + + fn bedrock_auth_state(session_id: &str, observed_at_ms: i64) -> ClaudeSessionAuthState { + ClaudeSessionAuthState { + session_id: String::from(session_id), + provider: AuthProvider::AwsBedrock, + billing_mode: BillingMode::CloudProvider, + auth_env_key: Some(AuthEnvKey::ClaudeCodeUseBedrock), + confidence: DetectionConfidence::Inferred, + observed_at_ms, + } + } + + fn unknown_auth_state(session_id: &str, observed_at_ms: i64) -> ClaudeSessionAuthState { + ClaudeSessionAuthState { + session_id: String::from(session_id), + provider: AuthProvider::Unknown, + billing_mode: BillingMode::Unknown, + auth_env_key: None, + confidence: DetectionConfidence::Unknown, + observed_at_ms, + } + } + + async fn claude_session_auth_state_row_count(db: &RepositoryAgentTraceDb) -> i64 { + db.query_map( + "SELECT COUNT(*) FROM claude_session_auth_state", + (), + |row| row.get::(0).map_err(Into::into), + ) + .await + .expect("row count")[0] + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_state_identical_replay_leaves_row_unchanged() { + let dir = tempfile::tempdir().expect("temp dir"); + let db = create_current_db(&dir.path().join("agent-trace.db")).await; + + for state in [ + bedrock_auth_state("claude:replay", 10), + unknown_auth_state("claude:replay-unknown", 10), + ] { + let session_id = state.session_id.clone(); + assert_eq!( + db.upsert_claude_session_auth_state(state.clone()) + .await + .expect("first upsert"), + ClaudeSessionAuthStateUpsertOutcome::Upserted { rows_changed: 1 } + ); + + let mut replay = state.clone(); + replay.observed_at_ms = 20; + assert_eq!( + db.upsert_claude_session_auth_state(replay) + .await + .expect("replay upsert"), + ClaudeSessionAuthStateUpsertOutcome::Upserted { rows_changed: 0 } + ); + + assert_eq!( + db.claude_session_auth_state_by_session(&session_id) + .await + .expect("read"), + Some(state) + ); + } + assert_eq!(claude_session_auth_state_row_count(&db).await, 2); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_state_changed_classification_updates_row_in_place() { + let dir = tempfile::tempdir().expect("temp dir"); + let db = create_current_db(&dir.path().join("agent-trace.db")).await; + + db.upsert_claude_session_auth_state(bedrock_auth_state("claude:change", 10)) + .await + .expect("initial upsert"); + + let api_key = ClaudeSessionAuthState { + session_id: String::from("claude:change"), + provider: AuthProvider::Anthropic, + billing_mode: BillingMode::ApiKey, + auth_env_key: Some(AuthEnvKey::AnthropicApiKey), + confidence: DetectionConfidence::Inferred, + observed_at_ms: 20, + }; + assert_eq!( + db.upsert_claude_session_auth_state(api_key.clone()) + .await + .expect("changed upsert"), + ClaudeSessionAuthStateUpsertOutcome::Upserted { rows_changed: 1 } + ); + assert_eq!( + db.claude_session_auth_state_by_session("claude:change") + .await + .expect("read after change"), + Some(api_key) + ); + + let unknown = unknown_auth_state("claude:change", 30); + assert_eq!( + db.upsert_claude_session_auth_state(unknown.clone()) + .await + .expect("env key cleared upsert"), + ClaudeSessionAuthStateUpsertOutcome::Upserted { rows_changed: 1 } + ); + assert_eq!( + db.claude_session_auth_state_by_session("claude:change") + .await + .expect("read after clearing env key"), + Some(unknown) + ); + assert_eq!(claude_session_auth_state_row_count(&db).await, 1); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_state_read_returns_only_exact_session() { + let dir = tempfile::tempdir().expect("temp dir"); + let db = create_current_db(&dir.path().join("agent-trace.db")).await; + + let first = bedrock_auth_state("claude:session-a", 10); + let second = unknown_auth_state("claude:session-b", 11); + db.upsert_claude_session_auth_state(first.clone()) + .await + .expect("first session upsert"); + db.upsert_claude_session_auth_state(second.clone()) + .await + .expect("second session upsert"); + + assert_eq!( + db.claude_session_auth_state_by_session("claude:session-a") + .await + .expect("read a"), + Some(first) + ); + assert_eq!( + db.claude_session_auth_state_by_session("claude:session-b") + .await + .expect("read b"), + Some(second) + ); + for absent in ["claude:session", "session-a", "claude:session-c"] { + assert_eq!( + db.claude_session_auth_state_by_session(absent) + .await + .expect("read absent"), + None + ); + } + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_state_read_rejects_unknown_stored_value() { + let dir = tempfile::tempdir().expect("temp dir"); + let db = create_current_db(&dir.path().join("agent-trace.db")).await; + db.execute("DROP TABLE claude_session_auth_state", ()) + .await + .expect("drop constrained table"); + db.execute( + "CREATE TABLE claude_session_auth_state (session_id TEXT PRIMARY KEY, provider TEXT NOT NULL, billing_mode TEXT NOT NULL, auth_env_key TEXT, confidence TEXT NOT NULL, observed_at_ms INTEGER NOT NULL)", + (), + ) + .await + .expect("unconstrained table"); + db.execute( + "INSERT INTO claude_session_auth_state VALUES ('claude:bad', 'openai', 'unknown', NULL, 'unknown', 1)", + (), + ) + .await + .expect("insert unknown provider"); + + assert!(db + .claude_session_auth_state_by_session("claude:bad") + .await + .is_err()); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_session_auth_state_upsert_skips_pre_008_database() { + let dir = tempfile::tempdir().expect("temp dir"); + let path = dir.path().join("agent-trace.db"); + create_pre_claude_session_auth_db(&path).await; + let (db, _metadata) = + open_repository_db_for_hook_runtime(&path, PRE_CLAUDE_SESSION_AUTH_REPOSITORY_ID) + .await + .expect("hook runtime opens pre-008 database"); + + assert_eq!( + db.upsert_claude_session_auth_state(bedrock_auth_state("claude:pre-008", 10)) + .await + .expect("skipped upsert is not an error"), + ClaudeSessionAuthStateUpsertOutcome::SkippedMissingMigration + ); + assert!(!claude_session_auth_state_table_exists(&db).await); + } } diff --git a/cli/src/services/hooks/claude_auth_detection.rs b/cli/src/services/hooks/claude_auth_detection.rs new file mode 100644 index 000000000..d323a2ffb --- /dev/null +++ b/cli/src/services/hooks/claude_auth_detection.rs @@ -0,0 +1,524 @@ +use anyhow::Result; + +const CLAUDE_CODE_USE_BEDROCK: &str = "CLAUDE_CODE_USE_BEDROCK"; +const CLAUDE_CODE_USE_VERTEX: &str = "CLAUDE_CODE_USE_VERTEX"; +const CLAUDE_CODE_USE_FOUNDRY: &str = "CLAUDE_CODE_USE_FOUNDRY"; +const ANTHROPIC_AUTH_TOKEN: &str = "ANTHROPIC_AUTH_TOKEN"; +const ANTHROPIC_API_KEY: &str = "ANTHROPIC_API_KEY"; +const CLAUDE_CODE_OAUTH_TOKEN: &str = "CLAUDE_CODE_OAUTH_TOKEN"; +const ANTHROPIC_BASE_URL: &str = "ANTHROPIC_BASE_URL"; +const DEFAULT_ANTHROPIC_BASE_URL: &str = "https://api.anthropic.com"; + +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum AuthProvider { + Anthropic, + AwsBedrock, + GoogleVertex, + MicrosoftFoundry, + CustomGateway, + Unknown, +} + +impl AuthProvider { + pub fn as_str(self) -> &'static str { + match self { + Self::Anthropic => "anthropic", + Self::AwsBedrock => "aws_bedrock", + Self::GoogleVertex => "google_vertex", + Self::MicrosoftFoundry => "microsoft_foundry", + Self::CustomGateway => "custom_gateway", + Self::Unknown => "unknown", + } + } + + pub fn from_str(value: &str) -> Result { + match value { + "anthropic" => Ok(Self::Anthropic), + "aws_bedrock" => Ok(Self::AwsBedrock), + "google_vertex" => Ok(Self::GoogleVertex), + "microsoft_foundry" => Ok(Self::MicrosoftFoundry), + "custom_gateway" => Ok(Self::CustomGateway), + "unknown" => Ok(Self::Unknown), + other => anyhow::bail!("invalid Claude auth provider: {other}"), + } + } +} + +/// `Subscription` is a valid stored value, but no environment-only signal can +/// establish it, so the detector never returns it. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum BillingMode { + ApiKey, + Subscription, + CloudProvider, + Unknown, +} + +impl BillingMode { + pub fn as_str(self) -> &'static str { + match self { + Self::ApiKey => "api_key", + Self::Subscription => "subscription", + Self::CloudProvider => "cloud_provider", + Self::Unknown => "unknown", + } + } + + pub fn from_str(value: &str) -> Result { + match value { + "api_key" => Ok(Self::ApiKey), + "subscription" => Ok(Self::Subscription), + "cloud_provider" => Ok(Self::CloudProvider), + "unknown" => Ok(Self::Unknown), + other => anyhow::bail!("invalid Claude billing mode: {other}"), + } + } +} + +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum AuthEnvKey { + ClaudeCodeUseBedrock, + ClaudeCodeUseVertex, + ClaudeCodeUseFoundry, + AnthropicAuthToken, + AnthropicApiKey, + ClaudeCodeOauthToken, +} + +impl AuthEnvKey { + pub fn as_str(self) -> &'static str { + match self { + Self::ClaudeCodeUseBedrock => "claude_code_use_bedrock", + Self::ClaudeCodeUseVertex => "claude_code_use_vertex", + Self::ClaudeCodeUseFoundry => "claude_code_use_foundry", + Self::AnthropicAuthToken => "anthropic_auth_token", + Self::AnthropicApiKey => "anthropic_api_key", + Self::ClaudeCodeOauthToken => "claude_code_oauth_token", + } + } + + pub fn from_str(value: &str) -> Result { + match value { + "claude_code_use_bedrock" => Ok(Self::ClaudeCodeUseBedrock), + "claude_code_use_vertex" => Ok(Self::ClaudeCodeUseVertex), + "claude_code_use_foundry" => Ok(Self::ClaudeCodeUseFoundry), + "anthropic_auth_token" => Ok(Self::AnthropicAuthToken), + "anthropic_api_key" => Ok(Self::AnthropicApiKey), + "claude_code_oauth_token" => Ok(Self::ClaudeCodeOauthToken), + other => anyhow::bail!("invalid Claude auth env key: {other}"), + } + } +} + +/// Environment variables describe configuration, not proof of authentication, +/// so there is no verified level. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum DetectionConfidence { + Inferred, + Unknown, +} + +impl DetectionConfidence { + pub fn as_str(self) -> &'static str { + match self { + Self::Inferred => "inferred", + Self::Unknown => "unknown", + } + } + + pub fn from_str(value: &str) -> Result { + match value { + "inferred" => Ok(Self::Inferred), + "unknown" => Ok(Self::Unknown), + other => anyhow::bail!("invalid Claude auth detection confidence: {other}"), + } + } +} + +/// Presence of each documented authentication signal; never holds values. +#[allow( + clippy::struct_excessive_bools, + reason = "each field is an independent signal-presence flag" +)] +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +pub struct ClaudeAuthSignals { + pub use_bedrock: bool, + pub use_vertex: bool, + pub use_foundry: bool, + pub anthropic_auth_token: bool, + pub anthropic_api_key: bool, + pub claude_code_oauth_token: bool, + pub custom_base_url: bool, +} + +impl ClaudeAuthSignals { + /// Each looked-up value is dropped immediately after its presence check. + pub fn from_env_lookup(lookup: F) -> Self + where + F: Fn(&str) -> Option, + { + let truthy = |name: &str| lookup(name).is_some_and(|value| is_truthy_flag(&value)); + let non_empty = |name: &str| lookup(name).is_some_and(|value| !value.trim().is_empty()); + + Self { + use_bedrock: truthy(CLAUDE_CODE_USE_BEDROCK), + use_vertex: truthy(CLAUDE_CODE_USE_VERTEX), + use_foundry: truthy(CLAUDE_CODE_USE_FOUNDRY), + anthropic_auth_token: non_empty(ANTHROPIC_AUTH_TOKEN), + anthropic_api_key: non_empty(ANTHROPIC_API_KEY), + claude_code_oauth_token: non_empty(CLAUDE_CODE_OAUTH_TOKEN), + custom_base_url: lookup(ANTHROPIC_BASE_URL) + .is_some_and(|value| is_custom_base_url(&value)), + } + } +} + +fn is_truthy_flag(value: &str) -> bool { + let value = value.trim(); + value == "1" || value.eq_ignore_ascii_case("true") +} + +fn is_custom_base_url(value: &str) -> bool { + let value = value.trim().trim_end_matches('/'); + !value.is_empty() && !value.eq_ignore_ascii_case(DEFAULT_ANTHROPIC_BASE_URL) +} + +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct ClaudeAuthDetection { + pub provider: AuthProvider, + pub billing_mode: BillingMode, + pub auth_env_key: Option, + pub confidence: DetectionConfidence, +} + +impl ClaudeAuthDetection { + const UNKNOWN: Self = Self { + provider: AuthProvider::Unknown, + billing_mode: BillingMode::Unknown, + auth_env_key: None, + confidence: DetectionConfidence::Unknown, + }; + + fn inferred( + provider: AuthProvider, + billing_mode: BillingMode, + auth_env_key: AuthEnvKey, + ) -> Self { + Self { + provider, + billing_mode, + auth_env_key: Some(auth_env_key), + confidence: DetectionConfidence::Inferred, + } + } +} + +/// Applies Claude Code's documented precedence: cloud-provider flags, then +/// `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, and `CLAUDE_CODE_OAUTH_TOKEN`. +/// More than one cloud flag is a provider conflict and classifies as unknown. +pub fn detect_claude_auth(signals: ClaudeAuthSignals) -> ClaudeAuthDetection { + let cloud_flags = [ + ( + signals.use_bedrock, + AuthProvider::AwsBedrock, + AuthEnvKey::ClaudeCodeUseBedrock, + ), + ( + signals.use_vertex, + AuthProvider::GoogleVertex, + AuthEnvKey::ClaudeCodeUseVertex, + ), + ( + signals.use_foundry, + AuthProvider::MicrosoftFoundry, + AuthEnvKey::ClaudeCodeUseFoundry, + ), + ]; + let mut set_cloud_flags = cloud_flags.iter().filter(|(set, _, _)| *set); + match (set_cloud_flags.next(), set_cloud_flags.next()) { + (Some(_), Some(_)) => return ClaudeAuthDetection::UNKNOWN, + (Some(&(_, provider, key)), None) => { + return ClaudeAuthDetection::inferred(provider, BillingMode::CloudProvider, key); + } + (None, _) => {} + } + + let anthropic_or_gateway = if signals.custom_base_url { + AuthProvider::CustomGateway + } else { + AuthProvider::Anthropic + }; + + if signals.anthropic_auth_token { + return ClaudeAuthDetection::inferred( + anthropic_or_gateway, + BillingMode::Unknown, + AuthEnvKey::AnthropicAuthToken, + ); + } + + if signals.anthropic_api_key { + let billing_mode = if signals.custom_base_url { + BillingMode::Unknown + } else { + BillingMode::ApiKey + }; + return ClaudeAuthDetection::inferred( + anthropic_or_gateway, + billing_mode, + AuthEnvKey::AnthropicApiKey, + ); + } + + if signals.claude_code_oauth_token { + return ClaudeAuthDetection::inferred( + AuthProvider::Anthropic, + BillingMode::Unknown, + AuthEnvKey::ClaudeCodeOauthToken, + ); + } + + ClaudeAuthDetection::UNKNOWN +} + +#[cfg(test)] +mod tests { + use std::collections::HashMap; + + use super::{ + detect_claude_auth, AuthEnvKey, AuthProvider, BillingMode, ClaudeAuthDetection, + ClaudeAuthSignals, DetectionConfidence, + }; + + fn detect(vars: &[(&str, &str)]) -> ClaudeAuthDetection { + let env: HashMap = vars + .iter() + .map(|(name, value)| ((*name).to_string(), (*value).to_string())) + .collect(); + detect_claude_auth(ClaudeAuthSignals::from_env_lookup(|name| { + env.get(name).cloned() + })) + } + + fn inferred( + provider: AuthProvider, + billing_mode: BillingMode, + key: AuthEnvKey, + ) -> ClaudeAuthDetection { + ClaudeAuthDetection { + provider, + billing_mode, + auth_env_key: Some(key), + confidence: DetectionConfidence::Inferred, + } + } + + const ALL_ANTHROPIC_CREDENTIALS: [(&str, &str); 4] = [ + ("ANTHROPIC_AUTH_TOKEN", "token"), + ("ANTHROPIC_API_KEY", "key"), + ("CLAUDE_CODE_OAUTH_TOKEN", "oauth"), + ("ANTHROPIC_BASE_URL", "https://gateway.example.com"), + ]; + + #[test] + fn each_cloud_flag_yields_its_provider_with_cloud_billing() { + let cases = [ + ( + "CLAUDE_CODE_USE_BEDROCK", + AuthProvider::AwsBedrock, + AuthEnvKey::ClaudeCodeUseBedrock, + ), + ( + "CLAUDE_CODE_USE_VERTEX", + AuthProvider::GoogleVertex, + AuthEnvKey::ClaudeCodeUseVertex, + ), + ( + "CLAUDE_CODE_USE_FOUNDRY", + AuthProvider::MicrosoftFoundry, + AuthEnvKey::ClaudeCodeUseFoundry, + ), + ]; + for (flag, provider, key) in cases { + let expected = inferred(provider, BillingMode::CloudProvider, key); + assert_eq!(detect(&[(flag, "1")]), expected, "{flag}=1"); + assert_eq!(detect(&[(flag, "TRUE")]), expected, "{flag}=TRUE"); + + let mut vars = ALL_ANTHROPIC_CREDENTIALS.to_vec(); + vars.push((flag, "true")); + assert_eq!(detect(&vars), expected, "{flag} over Anthropic credentials"); + } + } + + #[test] + fn falsy_cloud_flag_is_not_a_signal() { + for value in ["0", "false", "", "yes"] { + assert_eq!( + detect(&[("CLAUDE_CODE_USE_BEDROCK", value)]), + ClaudeAuthDetection::UNKNOWN, + "CLAUDE_CODE_USE_BEDROCK={value:?}" + ); + } + } + + #[test] + fn multiple_cloud_flags_are_a_provider_conflict() { + assert_eq!( + detect(&[ + ("CLAUDE_CODE_USE_BEDROCK", "1"), + ("CLAUDE_CODE_USE_VERTEX", "1"), + ("ANTHROPIC_API_KEY", "key"), + ]), + ClaudeAuthDetection::UNKNOWN + ); + } + + #[test] + fn auth_token_takes_precedence_over_api_key_with_unknown_billing() { + assert_eq!( + detect(&[ + ("ANTHROPIC_AUTH_TOKEN", "token"), + ("ANTHROPIC_API_KEY", "key"), + ("CLAUDE_CODE_OAUTH_TOKEN", "oauth"), + ]), + inferred( + AuthProvider::Anthropic, + BillingMode::Unknown, + AuthEnvKey::AnthropicAuthToken + ) + ); + } + + #[test] + fn api_key_without_custom_base_url_is_inferred_api_key_billing() { + let expected = inferred( + AuthProvider::Anthropic, + BillingMode::ApiKey, + AuthEnvKey::AnthropicApiKey, + ); + assert_eq!(detect(&[("ANTHROPIC_API_KEY", "key")]), expected); + assert_eq!( + detect(&[ + ("ANTHROPIC_API_KEY", "key"), + ("CLAUDE_CODE_OAUTH_TOKEN", "oauth"), + ("ANTHROPIC_BASE_URL", " https://API.anthropic.com/ "), + ]), + expected + ); + } + + #[test] + fn custom_base_url_classifies_either_credential_as_custom_gateway() { + let base_url = ("ANTHROPIC_BASE_URL", "https://gateway.example.com"); + assert_eq!( + detect(&[("ANTHROPIC_AUTH_TOKEN", "token"), base_url]), + inferred( + AuthProvider::CustomGateway, + BillingMode::Unknown, + AuthEnvKey::AnthropicAuthToken + ) + ); + assert_eq!( + detect(&[("ANTHROPIC_API_KEY", "key"), base_url]), + inferred( + AuthProvider::CustomGateway, + BillingMode::Unknown, + AuthEnvKey::AnthropicApiKey + ) + ); + } + + #[test] + fn oauth_token_alone_is_anthropic_with_unknown_billing() { + let expected = inferred( + AuthProvider::Anthropic, + BillingMode::Unknown, + AuthEnvKey::ClaudeCodeOauthToken, + ); + assert_eq!(detect(&[("CLAUDE_CODE_OAUTH_TOKEN", "oauth")]), expected); + assert_eq!( + detect(&[ + ("CLAUDE_CODE_OAUTH_TOKEN", "oauth"), + ("ANTHROPIC_BASE_URL", "https://gateway.example.com"), + ]), + expected + ); + } + + #[test] + fn missing_or_empty_configuration_is_unknown() { + assert_eq!(detect(&[]), ClaudeAuthDetection::UNKNOWN); + assert_eq!( + detect(&[ + ("ANTHROPIC_AUTH_TOKEN", ""), + ("ANTHROPIC_API_KEY", " "), + ("CLAUDE_CODE_OAUTH_TOKEN", ""), + ("ANTHROPIC_BASE_URL", "https://gateway.example.com"), + ]), + ClaudeAuthDetection::UNKNOWN + ); + } + + #[test] + fn detector_never_returns_subscription_billing_for_any_signal_combination() { + for bits in 0u8..128 { + let signals = ClaudeAuthSignals { + use_bedrock: bits & 1 != 0, + use_vertex: bits & 2 != 0, + use_foundry: bits & 4 != 0, + anthropic_auth_token: bits & 8 != 0, + anthropic_api_key: bits & 16 != 0, + claude_code_oauth_token: bits & 32 != 0, + custom_base_url: bits & 64 != 0, + }; + let detection = detect_claude_auth(signals); + assert_ne!(detection.billing_mode, BillingMode::Subscription); + assert_eq!( + detection.auth_env_key.is_some(), + detection.confidence == DetectionConfidence::Inferred + ); + } + } + + #[test] + fn string_mapping_round_trips_and_rejects_unknown_values() { + for provider in [ + AuthProvider::Anthropic, + AuthProvider::AwsBedrock, + AuthProvider::GoogleVertex, + AuthProvider::MicrosoftFoundry, + AuthProvider::CustomGateway, + AuthProvider::Unknown, + ] { + assert_eq!(AuthProvider::from_str(provider.as_str()).unwrap(), provider); + } + for mode in [ + BillingMode::ApiKey, + BillingMode::Subscription, + BillingMode::CloudProvider, + BillingMode::Unknown, + ] { + assert_eq!(BillingMode::from_str(mode.as_str()).unwrap(), mode); + } + for key in [ + AuthEnvKey::ClaudeCodeUseBedrock, + AuthEnvKey::ClaudeCodeUseVertex, + AuthEnvKey::ClaudeCodeUseFoundry, + AuthEnvKey::AnthropicAuthToken, + AuthEnvKey::AnthropicApiKey, + AuthEnvKey::ClaudeCodeOauthToken, + ] { + assert_eq!(AuthEnvKey::from_str(key.as_str()).unwrap(), key); + } + for confidence in [DetectionConfidence::Inferred, DetectionConfidence::Unknown] { + assert_eq!( + DetectionConfidence::from_str(confidence.as_str()).unwrap(), + confidence + ); + } + assert!(AuthProvider::from_str("verified").is_err()); + assert!(BillingMode::from_str("API_KEY").is_err()); + assert!(AuthEnvKey::from_str("anthropic_base_url").is_err()); + assert!(DetectionConfidence::from_str("verified").is_err()); + } +} diff --git a/cli/src/services/hooks/claude_model_state.rs b/cli/src/services/hooks/claude_model_state.rs index 42f2730df..3e3f17b15 100644 --- a/cli/src/services/hooks/claude_model_state.rs +++ b/cli/src/services/hooks/claude_model_state.rs @@ -4,8 +4,11 @@ use anyhow::{anyhow, Context, Result}; use serde_json::Value; use crate::services::agent_trace_db::repository::RepositoryAgentTraceDb; -use crate::services::agent_trace_db::{ClaudeModelStateObservation, ObservationKind}; +use crate::services::agent_trace_db::{ + ClaudeModelStateObservation, ClaudeSessionAuthState, ObservationKind, +}; +use super::claude_auth_detection::{detect_claude_auth, ClaudeAuthSignals}; use super::{ current_unix_time_ms, normalize_claude_model_id, prefixed_diff_trace_session_id, read_hook_stdin, CLAUDE_TOOL_NAME, @@ -16,6 +19,14 @@ const POST_MODEL_SWITCH_EVENT: &str = "PostModelSwitch"; const ERROR_EVENT: &str = "sce.hooks.claude_model_state.error"; const DB_OPEN_FAILED_EVENT: &str = "sce.hooks.claude_model_state.agent_trace_db_open_failed"; const DB_WRITE_FAILED_EVENT: &str = "sce.hooks.claude_model_state.agent_trace_db_write_failed"; +const AUTH_DB_WRITE_FAILED_EVENT: &str = + "sce.hooks.claude_model_state.auth_state_agent_trace_db_write_failed"; + +#[derive(Default)] +struct ClaudeModelStatePayload { + observation: Option, + session_start_session_id: Option, +} struct BridgeInheritanceCandidate { session: String, @@ -71,6 +82,7 @@ where logger, observed_at_ms, super::open_agent_trace_db_for_hook_runtime, + |name| std::env::var(name).ok(), ) .await } @@ -79,16 +91,19 @@ async fn run_claude_model_state_from_payload_with< L: crate::services::observability::traits::Logger, F, O, + E, >( repository_root: &Path, stdin_payload: &str, logger: Option<&L>, observed_at_ms: F, open_db: O, + env_lookup: E, ) -> String where F: FnOnce() -> Result, O: std::ops::AsyncFnOnce(&Path, &'static str) -> Result, + E: Fn(&str) -> Option, { let session_id = fail_open_session_id(stdin_payload); let observed_at_ms = match observed_at_ms() { @@ -106,8 +121,11 @@ where } }; - let observation = match parse_claude_model_state_payload(stdin_payload, observed_at_ms) { - Ok(observation) => observation, + let ClaudeModelStatePayload { + observation, + session_start_session_id, + } = match parse_claude_model_state_payload(stdin_payload, observed_at_ms) { + Ok(payload) => payload, Err(error) => { log_fail_open(logger, ERROR_EVENT, &error, session_id.as_deref()); return String::new(); @@ -125,7 +143,9 @@ where } else { None }; - if observation.is_none() && bridge_candidate.is_none() { + let auth_state = session_start_session_id + .map(|session_id| claude_session_auth_state(session_id, env_lookup, observed_at_ms)); + if observation.is_none() && bridge_candidate.is_none() && auth_state.is_none() { return String::new(); } @@ -150,33 +170,53 @@ where } }; - let observation = if let Some(observation) = observation { - observation - } else { - let candidate = bridge_candidate - .expect("bridge candidate must exist when no direct observation exists"); - let Some(model_id) = newest_bridge_chain_model(&db, &candidate.transcript_path).await - else { - return String::new(); - }; + let observation = match (observation, bridge_candidate) { + (Some(observation), _) => Some(observation), + (None, Some(candidate)) => newest_bridge_chain_model(&db, &candidate.transcript_path) + .await + .map(|model_id| ClaudeModelStateObservation { + session_id: candidate.session, + agent_id: candidate.agent, + model_id, + observation_kind: ObservationKind::SessionStart, + source: String::from("bridge_inherited"), + observed_at_ms, + }), + (None, None) => None, + }; - ClaudeModelStateObservation { - session_id: candidate.session, - agent_id: candidate.agent, - model_id, - observation_kind: ObservationKind::SessionStart, - source: String::from("bridge_inherited"), - observed_at_ms, + if let Some(observation) = observation { + if let Err(error) = persist_claude_model_state(&db, observation).await { + log_fail_open(logger, DB_WRITE_FAILED_EVENT, &error, session_id.as_deref()); } - }; + } - if let Err(error) = persist_claude_model_state(&db, observation).await { - log_fail_open(logger, DB_WRITE_FAILED_EVENT, &error, session_id.as_deref()); + if let Some(auth_state) = auth_state { + persist_claude_session_auth_state(&db, auth_state, logger).await; } String::new() } +fn claude_session_auth_state( + session_id: String, + env_lookup: E, + observed_at_ms: i64, +) -> ClaudeSessionAuthState +where + E: Fn(&str) -> Option, +{ + let detection = detect_claude_auth(ClaudeAuthSignals::from_env_lookup(env_lookup)); + ClaudeSessionAuthState { + session_id, + provider: detection.provider, + billing_mode: detection.billing_mode, + auth_env_key: detection.auth_env_key, + confidence: detection.confidence, + observed_at_ms, + } +} + fn bridge_inheritance_candidate(stdin_payload: &str) -> Result> { let parsed: Value = serde_json::from_str(stdin_payload) .context("Invalid Claude model-state payload from STDIN: expected valid JSON.")?; @@ -263,10 +303,30 @@ async fn persist_claude_model_state( Ok(()) } +async fn persist_claude_session_auth_state( + db: &RepositoryAgentTraceDb, + auth_state: ClaudeSessionAuthState, + logger: Option<&L>, +) { + let session_id = auth_state.session_id.clone(); + if let Err(error) = db + .upsert_claude_session_auth_state(auth_state) + .await + .context("Failed to persist Claude session auth state.") + { + log_fail_open( + logger, + AUTH_DB_WRITE_FAILED_EVENT, + &error, + Some(&session_id), + ); + } +} + fn parse_claude_model_state_payload( stdin_payload: &str, observed_at_ms: i64, -) -> Result> { +) -> Result { let parsed: Value = serde_json::from_str(stdin_payload) .context("Invalid Claude model-state payload from STDIN: expected valid JSON.")?; let payload = parsed.as_object().ok_or_else(|| { @@ -277,7 +337,7 @@ fn parse_claude_model_state_payload( let observation_kind = match event_name.as_str() { SESSION_START_EVENT => ObservationKind::SessionStart, POST_MODEL_SWITCH_EVENT => ObservationKind::PostModelSwitch, - _ => return Ok(None), + _ => return Ok(ClaudeModelStatePayload::default()), }; let session_id = prefixed_diff_trace_session_id( @@ -288,33 +348,38 @@ fn parse_claude_model_state_payload( match observation_kind { ObservationKind::SessionStart => { - let Some(model_id) = optional_model_id(payload, "model")? else { - return Ok(None); - }; + let model_id = optional_model_id(payload, "model")?; let source = required_non_empty_string(payload, "source")?; - - Ok(Some(ClaudeModelStateObservation { - session_id, + let observation = model_id.map(|model_id| ClaudeModelStateObservation { + session_id: session_id.clone(), agent_id, model_id, observation_kind, source, observed_at_ms, - })) + }); + + Ok(ClaudeModelStatePayload { + observation, + session_start_session_id: Some(session_id), + }) } ObservationKind::PostModelSwitch => { let _from_model = required_model_id(payload, "from_model")?; let to_model = required_model_id(payload, "to_model")?; let source = required_non_empty_string(payload, "source")?; - Ok(Some(ClaudeModelStateObservation { - session_id, - agent_id, - model_id: to_model, - observation_kind, - source, - observed_at_ms, - })) + Ok(ClaudeModelStatePayload { + observation: Some(ClaudeModelStateObservation { + session_id, + agent_id, + model_id: to_model, + observation_kind, + source, + observed_at_ms, + }), + session_start_session_id: None, + }) } } } @@ -414,3 +479,487 @@ fn log_fail_open( log.error(event_id, &format!("{error:#}"), &[], session_id); } } + +#[cfg(test)] +mod tests { + use std::collections::HashMap; + use std::path::{Path, PathBuf}; + use std::sync::Mutex; + + use anyhow::anyhow; + + use super::{ + run_claude_model_state_from_payload_with, AUTH_DB_WRITE_FAILED_EVENT, DB_OPEN_FAILED_EVENT, + }; + use crate::services::agent_trace_db::repository::RepositoryAgentTraceDb; + use crate::services::agent_trace_db::{ + ClaudeModelStateObservation, ClaudeSessionAuthState, ObservationKind, + }; + use crate::services::error::CliError; + use crate::services::hooks::claude_auth_detection::{ + AuthEnvKey, AuthProvider, BillingMode, DetectionConfidence, + }; + use crate::services::observability::traits::Logger; + + const SESSION_ID: &str = "cc_session-1"; + + #[derive(Default)] + struct RecordingLogger { + entries: Mutex)>>, + } + + impl RecordingLogger { + fn record(&self, event_id: &str, message: &str, session_id: Option<&str>) { + self.entries.lock().unwrap().push(( + event_id.to_string(), + message.to_string(), + session_id.map(str::to_string), + )); + } + + fn entries(&self) -> Vec<(String, String, Option)> { + self.entries.lock().unwrap().clone() + } + + fn event_ids(&self) -> Vec { + self.entries() + .into_iter() + .map(|(event_id, _, _)| event_id) + .collect() + } + } + + impl Logger for RecordingLogger { + fn info(&self, event_id: &str, message: &str, _: &[(&str, &str)], session: Option<&str>) { + self.record(event_id, message, session); + } + fn debug(&self, event_id: &str, message: &str, _: &[(&str, &str)], session: Option<&str>) { + self.record(event_id, message, session); + } + fn warn(&self, event_id: &str, message: &str, _: &[(&str, &str)], session: Option<&str>) { + self.record(event_id, message, session); + } + fn error(&self, event_id: &str, message: &str, _: &[(&str, &str)], session: Option<&str>) { + self.record(event_id, message, session); + } + fn log_cli_error(&self, error: &CliError, session_id: Option<&str>) { + self.record("cli_error", &error.to_string(), session_id); + } + } + + struct Fixture { + _dir: tempfile::TempDir, + db_path: PathBuf, + logger: RecordingLogger, + } + + impl Fixture { + async fn new() -> Self { + let dir = tempfile::tempdir().expect("temp dir"); + let db_path = dir.path().join("agent-trace.db"); + drop( + RepositoryAgentTraceDb::new_at(&db_path) + .await + .expect("current database"), + ); + Self { + _dir: dir, + db_path, + logger: RecordingLogger::default(), + } + } + + async fn run(&self, payload: &str, observed_at_ms: i64, env: &[(&str, &str)]) -> String { + let db_path = self.db_path.clone(); + run_with( + &self.db_path, + payload, + observed_at_ms, + env, + &self.logger, + async move |_: &Path, _: &'static str| { + RepositoryAgentTraceDb::new_at(&db_path).await + }, + ) + .await + } + + async fn db(&self) -> RepositoryAgentTraceDb { + RepositoryAgentTraceDb::new_at(&self.db_path) + .await + .expect("reopen database") + } + + async fn auth_state(&self) -> Option { + self.db() + .await + .claude_session_auth_state_by_session(SESSION_ID) + .await + .expect("auth state read") + } + + async fn model_state(&self) -> Option { + self.db() + .await + .claude_model_state_by_session_and_agent(SESSION_ID, "") + .await + .expect("model state read") + } + + async fn dump_rows(&self, sql: &str) -> Vec { + self.db() + .await + .query_map(sql, (), |row| row.get::(0).map_err(Into::into)) + .await + .expect("row dump") + } + } + + async fn run_with( + db_path: &Path, + payload: &str, + observed_at_ms: i64, + env: &[(&str, &str)], + logger: &RecordingLogger, + open_db: O, + ) -> String + where + O: std::ops::AsyncFnOnce(&Path, &'static str) -> anyhow::Result, + { + let vars: HashMap = env + .iter() + .map(|(name, value)| ((*name).to_string(), (*value).to_string())) + .collect(); + run_claude_model_state_from_payload_with( + db_path.parent().expect("db parent"), + payload, + Some(logger), + || Ok(observed_at_ms), + open_db, + |name| vars.get(name).cloned(), + ) + .await + } + + fn session_start(source: &str, model: Option<&str>) -> String { + let mut payload = serde_json::json!({ + "hook_event_name": "SessionStart", + "session_id": "session-1", + "source": source, + }); + if let Some(model) = model { + payload["model"] = serde_json::Value::from(model); + } + payload.to_string() + } + + fn post_model_switch() -> String { + serde_json::json!({ + "hook_event_name": "PostModelSwitch", + "session_id": "session-1", + "source": "user", + "from_model": "claude-sonnet-5-5", + "to_model": "claude-opus-5-5", + }) + .to_string() + } + + fn auth_state( + provider: AuthProvider, + billing_mode: BillingMode, + auth_env_key: Option, + confidence: DetectionConfidence, + observed_at_ms: i64, + ) -> ClaudeSessionAuthState { + ClaudeSessionAuthState { + session_id: SESSION_ID.to_string(), + provider, + billing_mode, + auth_env_key, + confidence, + observed_at_ms, + } + } + + fn api_key_auth(observed_at_ms: i64) -> ClaudeSessionAuthState { + auth_state( + AuthProvider::Anthropic, + BillingMode::ApiKey, + Some(AuthEnvKey::AnthropicApiKey), + DetectionConfidence::Inferred, + observed_at_ms, + ) + } + + const API_KEY_ENV: &[(&str, &str)] = &[("ANTHROPIC_API_KEY", "key")]; + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_startup_stores_auth_and_unchanged_model_state() { + let fixture = Fixture::new().await; + + let stdout = fixture + .run( + &session_start("startup", Some("claude-opus-5-5")), + 10, + API_KEY_ENV, + ) + .await; + + assert_eq!(stdout, ""); + assert_eq!(fixture.auth_state().await, Some(api_key_auth(10))); + assert_eq!( + fixture.model_state().await, + Some(ClaudeModelStateObservation { + session_id: SESSION_ID.to_string(), + agent_id: String::new(), + model_id: String::from("claude/claude-opus-5-5"), + observation_kind: ObservationKind::SessionStart, + source: String::from("startup"), + observed_at_ms: 10, + }) + ); + assert!(fixture.logger.entries().is_empty()); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_resume_with_changed_auth_updates_row() { + let fixture = Fixture::new().await; + fixture + .run( + &session_start("startup", Some("claude-opus-5-5")), + 10, + API_KEY_ENV, + ) + .await; + + let stdout = fixture + .run( + &session_start("resume", Some("claude-opus-5-5")), + 20, + &[ + ("CLAUDE_CODE_USE_BEDROCK", "1"), + ("ANTHROPIC_API_KEY", "key"), + ], + ) + .await; + + assert_eq!(stdout, ""); + assert_eq!( + fixture.auth_state().await, + Some(auth_state( + AuthProvider::AwsBedrock, + BillingMode::CloudProvider, + Some(AuthEnvKey::ClaudeCodeUseBedrock), + DetectionConfidence::Inferred, + 20, + )) + ); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_resume_without_auth_change_leaves_row_unchanged() { + let fixture = Fixture::new().await; + fixture + .run( + &session_start("startup", Some("claude-opus-5-5")), + 10, + API_KEY_ENV, + ) + .await; + let model_state = fixture.model_state().await; + + let stdout = fixture + .run(&session_start("resume", None), 20, API_KEY_ENV) + .await; + + assert_eq!(stdout, ""); + assert_eq!(fixture.auth_state().await, Some(api_key_auth(10))); + assert_eq!(fixture.model_state().await, model_state); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_duplicate_session_start_keeps_single_unchanged_auth_row() { + let fixture = Fixture::new().await; + let payload = session_start("startup", Some("claude-opus-5-5")); + + assert_eq!(fixture.run(&payload, 10, API_KEY_ENV).await, ""); + assert_eq!(fixture.run(&payload, 10, API_KEY_ENV).await, ""); + assert_eq!(fixture.run(&payload, 15, API_KEY_ENV).await, ""); + + assert_eq!(fixture.auth_state().await, Some(api_key_auth(10))); + assert_eq!( + fixture + .dump_rows("SELECT session_id FROM claude_session_auth_state") + .await, + vec![SESSION_ID.to_string()] + ); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_model_less_session_start_stores_auth_only() { + let fixture = Fixture::new().await; + + let stdout = fixture.run(&session_start("clear", None), 10, &[]).await; + + assert_eq!(stdout, ""); + assert_eq!( + fixture.auth_state().await, + Some(auth_state( + AuthProvider::Unknown, + BillingMode::Unknown, + None, + DetectionConfidence::Unknown, + 10, + )) + ); + assert_eq!(fixture.model_state().await, None); + assert!(fixture.logger.entries().is_empty()); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_post_model_switch_ignores_auth() { + let fixture = Fixture::new().await; + + let stdout = fixture.run(&post_model_switch(), 10, API_KEY_ENV).await; + + assert_eq!(stdout, ""); + assert_eq!(fixture.auth_state().await, None); + assert_eq!( + fixture.model_state().await, + Some(ClaudeModelStateObservation { + session_id: SESSION_ID.to_string(), + agent_id: String::new(), + model_id: String::from("claude/claude-opus-5-5"), + observation_kind: ObservationKind::PostModelSwitch, + source: String::from("user"), + observed_at_ms: 10, + }) + ); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_db_open_failure_fails_open_with_empty_stdout() { + let fixture = Fixture::new().await; + + let stdout = run_with( + &fixture.db_path, + &session_start("startup", None), + 10, + API_KEY_ENV, + &fixture.logger, + async |_: &Path, _: &'static str| -> anyhow::Result { + Err(anyhow!("open failed")) + }, + ) + .await; + + assert_eq!(stdout, ""); + assert_eq!(fixture.logger.event_ids(), vec![DB_OPEN_FAILED_EVENT]); + assert_eq!(fixture.auth_state().await, None); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_model_state_auth_write_failure_does_not_block_model_state() { + let fixture = Fixture::new().await; + fixture + .db() + .await + .execute("DROP TABLE claude_session_auth_state", ()) + .await + .expect("drop auth table"); + + let stdout = fixture + .run( + &session_start("startup", Some("claude-opus-5-5")), + 10, + API_KEY_ENV, + ) + .await; + + assert_eq!(stdout, ""); + assert!(fixture.model_state().await.is_some()); + let entries = fixture.logger.entries(); + assert_eq!(entries.len(), 1, "{entries:?}"); + assert_eq!(entries[0].0, AUTH_DB_WRITE_FAILED_EVENT); + assert_eq!(entries[0].2.as_deref(), Some(SESSION_ID)); + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_auth_state_no_secret_values_reach_rows_logs_or_stdout() { + const SENTINELS: &[&str] = &[ + "sentinel-auth-token-7f3a", + "sentinel-api-key-91c2", + "sentinel-oauth-token-4d8e", + ]; + let env = [ + ("ANTHROPIC_AUTH_TOKEN", SENTINELS[0]), + ("ANTHROPIC_API_KEY", SENTINELS[1]), + ("CLAUDE_CODE_OAUTH_TOKEN", SENTINELS[2]), + ]; + let fixture = Fixture::new().await; + + let mut stdout = fixture + .run(&session_start("startup", Some("claude-opus-5-5")), 10, &env) + .await; + stdout.push_str(&fixture.run(&session_start("resume", None), 20, &env).await); + fixture + .db() + .await + .execute("DROP TABLE claude_session_auth_state", ()) + .await + .expect("drop auth table"); + stdout.push_str(&fixture.run(&session_start("resume", None), 30, &env).await); + + let mut haystack = fixture + .dump_rows( + "SELECT session_id || '|' || agent_id || '|' || model_id || '|' || observation_kind || '|' || source FROM claude_model_state", + ) + .await; + haystack.extend(fixture.logger.entries().into_iter().flat_map( + |(event_id, message, session_id)| [event_id, message, session_id.unwrap_or_default()], + )); + assert!( + fixture + .logger + .event_ids() + .iter() + .any(|event_id| event_id == AUTH_DB_WRITE_FAILED_EVENT), + "auth write failure must produce log output to inspect" + ); + haystack.push(stdout.clone()); + + assert_eq!(stdout, ""); + for sentinel in SENTINELS { + for text in &haystack { + assert!(!text.contains(sentinel), "{sentinel} leaked into {text}"); + } + } + } + + #[tokio::test(flavor = "multi_thread")] + async fn claude_auth_state_no_secret_values_in_stored_auth_row() { + const SENTINEL: &str = "sentinel-api-key-91c2"; + let fixture = Fixture::new().await; + + fixture + .run( + &session_start("startup", None), + 10, + &[("ANTHROPIC_API_KEY", SENTINEL)], + ) + .await; + + let rows = fixture + .dump_rows( + "SELECT session_id || '|' || provider || '|' || billing_mode || '|' || COALESCE(auth_env_key, '') || '|' || confidence || '|' || observed_at_ms FROM claude_session_auth_state", + ) + .await; + assert_eq!( + rows, + vec![format!( + "{SESSION_ID}|anthropic|api_key|anthropic_api_key|inferred|10" + )] + ); + assert!(rows.iter().all(|row| !row.contains(SENTINEL))); + } +} diff --git a/cli/src/services/hooks/mod.rs b/cli/src/services/hooks/mod.rs index d621f00a0..f071b9fc4 100644 --- a/cli/src/services/hooks/mod.rs +++ b/cli/src/services/hooks/mod.rs @@ -1,5 +1,6 @@ use anyhow::Context; +pub(crate) mod claude_auth_detection; mod claude_transforms; mod commit_hooks; mod commit_patch_id; diff --git a/context/cli/agent-trace-storage.md b/context/cli/agent-trace-storage.md index bbfaf237e..e10060fc2 100644 --- a/context/cli/agent-trace-storage.md +++ b/context/cli/agent-trace-storage.md @@ -17,7 +17,7 @@ Module at `cli/src/services/agent_trace_storage/` (T04 of the `repository-scoped 3. DB open splits by caller through `agent_trace_db::repository::RepositoryAgentTraceDb`, sharing steps 1–2 through an internal `open_storage_with` helper parameterized by the DB-opener; both resolver paths await async database operations: - Setup/lifecycle (`resolve_agent_trace_storage{,_at_state_root}`): a bounded concurrent-safe fast-path-then-migrate sequence — `open_without_migrations_at` + `ensure_schema_ready_for_hooks()` + `verify_or_initialize_repository_metadata(repository_id)`, falling back to migration-running `new_at` plus the same metadata validation. Directory creation rides on `TursoDb` parent-dir `create_dir_all`. If concurrent first open leaves all repository schema tables present but the one-file baseline migration record missing, the repository adapter records that missing metadata before rechecking readiness; otherwise the resolver retries the open/migrate sequence for a bounded window while SQLite/Turso locks clear. - Maintenance (`resolve_existing_agent_trace_storage_for_maintenance` + `RepositoryAgentTraceDb::open_verified_existing_at`, used only by snapshot-ref reconciliation): a non-creating read-only Turso open (`TursoDb::open_existing_without_migrations_at`, multiprocess WAL preserved) that never creates the DB file or parent directory, never migrates, never calls the migration-metadata repair, and never runs `verify_or_initialize_repository_metadata`. It verifies schema readiness, metadata presence, `repository_id` equality, and a valid `source_instance_id` before returning, with typed `ExistingRepositoryDbError` (`Missing`, `Unreadable`, `IncompatibleSchema`, `MissingMetadata`, `RepositoryMismatch`). Plain `sce doctor` shares the open via `RepositoryAgentTraceDb::open_existing_schema_ready_at`. See [mutation-trace-ref-reconciliation.md](mutation-trace-ref-reconciliation.md). - - Hook runtime (`resolve_agent_trace_storage_for_hook_runtime{,_at_state_root}`): `open_for_hooks_without_migrations_at` + `ensure_schema_ready_for_hooks()`, applying the same narrow concurrent-first-open metadata repair on failure but never falling back to `new_at`/migrations. A missing or baseline-only (pre-`002`) database fails with `ensure_schema_ready_for_hooks`'s existing `Run 'sce setup'.` guidance. Once readiness passes, `verify_or_initialize_repository_metadata(repository_id)` initializes `source_instance_id` when needed, matching setup's result for an already-set-up repository. `sce hooks` command call sites use this path via `open_agent_trace_db_for_hook_runtime` in `cli/src/services/hooks/mod.rs`. + - Hook runtime (`resolve_agent_trace_storage_for_hook_runtime{,_at_state_root}`): `open_for_hooks_without_migrations_at` + `ensure_schema_ready_for_hook_runtime()` (strict parity, or strict parity minus exactly `008_claude_session_auth_state`), applying the same narrow concurrent-first-open metadata repair on failure but never falling back to `new_at`/migrations. A missing or baseline-only (pre-`002`) database, any other migration gap, or an unexpected ID fails with the existing `Run 'sce setup'.` guidance. Once readiness passes, `verify_or_initialize_repository_metadata(repository_id)` initializes `source_instance_id` when needed, matching setup's result for an already-set-up repository. `sce hooks` command call sites use this path via `open_agent_trace_db_for_hook_runtime` in `cli/src/services/hooks/mod.rs`. ## Never-touch on-disk boundary diff --git a/context/context-map.md b/context/context-map.md index 14fa28a40..850ee1d83 100644 --- a/context/context-map.md +++ b/context/context-map.md @@ -96,8 +96,9 @@ Feature/domain context: - `context/sce/agent-trace-db-write-contention-evidence.md` (measured Agent Trace DB write-contention behavior under the busy-timeout/outer-retry/contention-deadline contract: the `lock_contention_tests.rs` suite with its lock-budget boundary, strict N=2–4 in-process and real-hook gates and N=8 stress characterization, policy history from 500 / 1250 to the current 1000 / 2250 defaults, the supported-load failure that motivated the tuning, before-vs-after comparison, and the bounded-policy exhaustion failure mode) - `context/sce/auth-db.md` (encrypted `AuthDb = EncryptedTursoDb` adapter, canonical `/sce/auth.db` path, build-time generated `AUTH_MIGRATIONS` from `cli/migrations/auth/`, auth credential schema and updated-at trigger baseline, lifecycle setup/doctor integration, async encrypted token-storage persistence through a Result-valued Tokio OnceCell, and `SCE_AUTH_DB_ENCRYPTION_KEY`/OS credential-store key handling) - `context/sce/telemetry-credential.md` (telemetry-only OpenBao credential: typed Control Plane issuance client, save-on-issue, single-row encrypted `auth.db` storage that never mints on lookup, deterministic auth-login `telemetry_provisioning` status/message rendering with secret-free unavailable warnings, production issue-and-save after WorkOS persistence on fresh/valid-stored/renewed paths, logout deletion alongside WorkOS credentials, issuing-token identity binding with session-ownership checks, repository-to-workspace enrollment bindings, local deletion not revoking the OpenBao token, and its use as the managed OTLP bearer source, the hidden `telemetry-headers` helper and its OS-user trust boundary with no endpoint-pinning claim, and Claude-native telemetry setup, removal of SCE-owned settings on global-config withdrawal, rotation, logout, conflict handling, and override limits) -- `context/sce/agent-trace-db.md` (implemented Agent Trace database adapter: the sole repository-scoped `RepositoryAgentTraceDb` backed by the fresh multi-statement baseline schema plus additive `source_instance_id`, `claude_model_state`, mutation-trace, and `007_commit_patch_id` (nullable `agent_traces.commit_patch_id`, setup-only upgrade) migrations, with `repository_metadata` carrying both `repository_id` and a concurrency-safe atomic-claim `source_instance_id` (physical database identity, independent of `repository_id`), narrow concurrent-first-open repair for missing one-file baseline migration metadata after all required schema tables exist, no trace-table `checkout_id` columns, repository-level typed insert helpers for diff traces, post-commit intersections, Agent Trace rows, messages, parts, and the non-exported exact-scope Claude model-state register, repository-level recent diff-trace reads without checkout filtering (the inclusive-window reader plus the commit-time-bounded `recent_diff_trace_patches_before_commit` post-commit reader) including persisted hunk-model plus canonical touched-line-session enrichment for structured rows, async on-demand command/hook initialization with no daemon/background service, and the never-touch on-disk boundary for any pre-migration checkout-scoped/global DB files; the checkout-scoped `AgentTraceDb` adapter, its `agent_trace_db_path()`/`agent_trace_db_path_for_checkout()` helpers, and the 15-file `cli/migrations/agent-trace/` chain were removed by the `retire-legacy-agent-trace-db` plan; active hook writers/readers and Agent Trace setup/lifecycle resolve repository storage through `agent_trace_storage`) -- `context/sce/agent-trace-db-schema.md` (per-table columns, lookup indexes, and `updated_at` triggers of the repository-scoped Agent Trace database, including the nullable `agent_traces.commit_patch_id` column) +- `context/sce/agent-trace-db.md` (implemented Agent Trace database adapter: the sole repository-scoped `RepositoryAgentTraceDb` backed by the fresh multi-statement baseline schema plus additive `source_instance_id`, `claude_model_state`, mutation-trace, and `007_commit_patch_id` (nullable `agent_traces.commit_patch_id`, setup-only upgrade), and `008_claude_session_auth_state` (local-only auth-state table; the single migration the hook runtime tolerates as missing) migrations, with `repository_metadata` carrying both `repository_id` and a concurrency-safe atomic-claim `source_instance_id` (physical database identity, independent of `repository_id`), narrow concurrent-first-open repair for missing one-file baseline migration metadata after all required schema tables exist, no trace-table `checkout_id` columns, repository-level typed insert helpers for diff traces, post-commit intersections, Agent Trace rows, messages, parts, and the non-exported exact-scope Claude model-state register, repository-level recent diff-trace reads without checkout filtering (the inclusive-window reader plus the commit-time-bounded `recent_diff_trace_patches_before_commit` post-commit reader) including persisted hunk-model plus canonical touched-line-session enrichment for structured rows, async on-demand command/hook initialization with no daemon/background service, and the never-touch on-disk boundary for any pre-migration checkout-scoped/global DB files; the checkout-scoped `AgentTraceDb` adapter, its `agent_trace_db_path()`/`agent_trace_db_path_for_checkout()` helpers, and the 15-file `cli/migrations/agent-trace/` chain were removed by the `retire-legacy-agent-trace-db` plan; active hook writers/readers and Agent Trace setup/lifecycle resolve repository storage through `agent_trace_storage`) +- `context/sce/claude-session-auth-state.md` (pure Claude auth/billing detector in `cli/src/services/hooks/claude_auth_detection.rs`: environment-presence signals, documented precedence, classification table, `inferred`/`unknown` confidence, the configuration-versus-billing distinction, and `/login`/`apiKeyHelper` limitations; plus the typed change-only `claude_session_auth_state` upsert/read interface that skips on a pre-`008` ledger, and its `sce hooks claude-model-state` integration that stores the classification on every valid `SessionStart`; local-only, with no export reader) +- `context/sce/agent-trace-db-schema.md` (per-table columns, lookup indexes, and `updated_at` triggers of the repository-scoped Agent Trace database, including the nullable `agent_traces.commit_patch_id` column and the `claude_session_auth_state` table) - `context/sce/agent-trace-export-readers.md` (implemented `AgentTraceExportReader<'a>` in `cli/src/services/agent_trace_export/mod.rs`: the read-only async local export boundary over `RepositoryAgentTraceDb` — `read_messages_after`/`read_parts_after`/`read_agent_traces_after`, each cursor/limit/JS-safe-integer validated, materialized into owned camelCase `serde::Serialize` DTOs, with `agent_traces` rows carrying an always-present nullable `commitPatchId`; composes directly with `ResolvedAgentTraceStorage` without owning `source_instance_id`; `diff_traces` has no reader; no local sync cursor, no `agent-trace-sync.db`, no Turso Sync, no ETL, no DWH) - `context/sce/agent-trace-core-schema-migrations.md` (historical reference for removed local DB schema bootstrap behavior; T03 now implements the actual local DB with migrations) - `context/sce/agent-trace-retry-queue-observability.md` (inactive local-hook retry path plus historical retry/metrics reference) diff --git a/context/glossary.md b/context/glossary.md index 7f93e90f1..3545cb4b4 100644 --- a/context/glossary.md +++ b/context/glossary.md @@ -1,5 +1,5 @@ # Glossary -- CLI execution terminology: [command dispatch, runtime dependencies and telemetry](cli/execution-glossary.md). Auth mode, policy layer (user/repository), effective access policy, setup repository access preferences, and the `auth.disabled_by_config` rejection: [effective access policy](cli/access-policy.md). Setup login step and `auth.setup_login_required`: [setup login](sce/setup-repo-local-config-bootstrap.md#setup-login). +- CLI execution terminology: [command dispatch, runtime dependencies and telemetry](cli/execution-glossary.md). Auth mode, policy layer (user/repository), effective access policy, setup repository access preferences, and the `auth.disabled_by_config` rejection: [effective access policy](cli/access-policy.md). Setup login step and `auth.setup_login_required`: [setup login](sce/setup-repo-local-config-bootstrap.md#setup-login). `Claude session auth state` (local-only latest-state `claude_session_auth_state` row per `cc_` holding Claude Code's configured auth provider, billing mode, selected auth env key name, and `inferred`/`unknown` confidence, derived from environment-variable presence; configuration, not verified authentication or actual billing): [Claude session auth state](sce/claude-session-auth-state.md). - `pkl-check-generated`: Flake app exposed as `nix run .#pkl-check-generated`; canonical ephemeral-generation check that rejects committed target/schema/mirror outputs, evaluates exact workflow metadata, the generated artifact contract, semantic layout/path/inventory/content/parity/observational checks, and the optional-workflow manifest's content against the catalog, requires the shared helper-composition rule and SCE-scoped workflow prohibitions, enforces ordered catalog-derived OpenCode skill permissions plus explicit-permission artifact integrity, rejects stale sibling-package references or unresolved internalization tokens in workflow entrypoint `SKILL.md` documents, proves contract failures through checked-in negative fixtures, and delegates deterministic generation plus payload/input inventories to the generated-input producer while preserving its established inventory report. - `repo-level verification preference`: Current repository guidance that contributor-facing validation/check flows should prefer `nix flake check`; direct Cargo verification commands are secondary and used only when explicitly requested or for narrow targeted debugging, while `cargo fmt` remains the explicit autofix path. Required quick checks after each completed task in this repo are `nix run .#pkl-check-generated` and `nix flake check`. - disposable plan lifecycle: Policy where `context/plans/` holds active execution artifacts only; completed plans are disposable and durable outcomes must be reflected in current-state context files and/or `context/decisions/`. @@ -82,7 +82,7 @@ - `telemetry credential`: Telemetry-only OpenBao token and accessor issued by the Control Plane `POST /auth/telemetry/credential`, stored as one fixed row in the encrypted auth DB `telemetry_credentials` table by `cli/src/services/telemetry_credential_storage.rs`, returned only while unexpired, removed by `sce auth logout`, not revoked server-side by local deletion, and used as the sole bearer secret for managed OTLP export (never the accessor); see `context/sce/telemetry-credential.md`. - `sce.hook span`: The single root-of-process managed trace span a Claude-invoked SCE hook exports in place of `sce.command`, carrying `sce.agent=claude`, the hook event, tool name, outcome, and the Claude `session_id`/`tool_use_id` as correlation-only attributes. It is parented on a valid Claude-provided `TRACEPARENT` (the `claude_code.interaction` span, so it sits beside `claude_code.tool`) and is otherwise an independent root. Its only exported children are `sce.mutation_scope` (one per adapter seam call) and, beneath it, `sce.git_snapshot` and `sce.persistence`, each emitted only when that operation actually runs and carrying only `sce.outcome`. Admission is Claude-only (Claude-only hook subcommands by argv; shared hook subcommands and `sce policy bash` only with `CLAUDECODE` and `CLAUDE_PROJECT_DIR` present); see `context/sce/cli-observability-contract.md`. - `AuthDbLifecycle`: Lifecycle provider in `cli/src/services/auth_db/lifecycle.rs` that implements `ServiceLifecycle` for encrypted auth DB setup/doctor integration. `diagnose` collects auth DB path health problems, `fix` bootstraps missing auth DB parent directory, and `setup` calls `AuthDb::new()`. Registered as `LifecycleProviderId::AuthDb` in the shared lifecycle catalog. -- `agent trace DB adapter`: Modules under `cli/src/services/agent_trace_db/` that define the sole repository-scoped `RepositoryAgentTraceDb = TursoDb` adapter (the checkout-scoped `AgentTraceDb`/`AgentTraceDbSpec` adapter and its 15-file migration chain were removed by the `retire-legacy-agent-trace-db` plan). The repository adapter uses the `agent-trace-repository` migration set (fresh baseline schema plus additive `source_instance_id` and `claude_model_state` migrations) with `repository_metadata`, repository-level `diff_traces`, `post_commit_patch_intersections`, `agent_traces`, `messages`, and `parts` tables, no row-level `checkout_id`, typed parameterized insert helpers, the non-exported `claude_model_state` latest-locally-observed register with exact `(session_id, agent_id)` reads and guarded writes, and chronological recent `diff_traces` query/parse support. `AgentTraceDbLifecycle` initializes/checks repository-scoped storage through `agent_trace_storage`. +- `agent trace DB adapter`: Modules under `cli/src/services/agent_trace_db/` that define the sole repository-scoped `RepositoryAgentTraceDb = TursoDb` adapter (the checkout-scoped `AgentTraceDb`/`AgentTraceDbSpec` adapter and its 15-file migration chain were removed by the `retire-legacy-agent-trace-db` plan). The repository adapter uses the `agent-trace-repository` migration set (fresh baseline schema plus additive `source_instance_id`, `claude_model_state`, mutation-trace, `commit_patch_id`, and `claude_session_auth_state` migrations) with `repository_metadata`, repository-level `diff_traces`, `post_commit_patch_intersections`, `agent_traces`, `messages`, and `parts` tables, no row-level `checkout_id`, typed parameterized insert helpers, the non-exported `claude_model_state` latest-locally-observed register with exact `(session_id, agent_id)` reads and guarded writes, the local-only `Claude session auth state` register, and chronological recent `diff_traces` query/parse support. `AgentTraceDbLifecycle` initializes/checks repository-scoped storage through `agent_trace_storage`. - `post-commit Agent Trace auto-sync readiness`: The doctor report fact that explains whether the enabled post-commit trigger is ready without invoking it. Doctor compares the installed `post-commit` hook's SCE managed block using the same currency semantics as setup and resolves config-file-only `agent_trace.auto_sync` with source metadata. JSON states are `ready`, `disabled`, `not_ready`, and `not_applicable`; `disabled` covers both the explicit opt-out and an access policy that disallows background cloud operations, and is healthy, while existing hook problems continue to own overall readiness and remediation. See [automatic Agent Trace synchronization](cli/agent-trace-auto-sync.md) and [doctor human text](sce/doctor-human-text-contract.md). - `structured patch service`: Pure synchronous Rust service in `cli/src/services/structured_patch.rs` that derives supported structured editor hook payloads into canonical `ParsedPatch` values. The current implemented source is Claude `PostToolUse` payloads for `Write` creates and `Edit` structured patches; wired into `sce hooks diff-trace` for Claude payload classification at intake and into `RepositoryAgentTraceDb::recent_diff_trace_patches` for post-commit structured payload parsing, where persisted row `model_id` is assigned to every hunk and persisted canonical row `session_id` to every touched line before downstream reconstruction. - `MutationLineage` / `causal mutation-lineage attribution`: `cli/src/services/mutation_trace/lineage.rs` is a pure module holding, per repo path, a vector of `(content, LineProvenance)` where `LineProvenance` is `Unknown`, `MutationAi { scope_id }`, or `MutationNonAi`. `MutationLineage::apply(patch, origin)` advances it one reconstructed tree transition at a time, applying hunks structurally: context lines carry provenance forward, removed lines are deleted permanently, added lines take only the introducing `TransitionOrigin` (`MutationAi` for healthy untainted `AiExclusive`, `MutationNonAi` for any other recorded event, `Unobserved` → `Unknown` for gap reloads and the latest-tree→commit-tree tail); a structurally inconsistent transition is a `LineageError` and the caller reloads that file to an all-`Unknown` baseline. Historical mutation patches are never matched independently against the committed patch — that earlier `MutationPatchEvidence` / strict-matcher model let stale evidence resurrect and is removed. `attribution.rs` now only supplies the `patch_for_locations` helpers; lineage projects every committed line, and deleted or renamed-away tracked paths stay tracked as absent files. The store supplies events through an exact-worktree-scoped `mutation-event page` ordered by descending 8-byte big-endian revision, continued with an exclusive revision cursor, capped at 32 rows; plus `latest_mutation_event_revision` for the revision ceiling (a snapshot bound, not proof an event preceded the commit). The `bounded mutation-history consumer` (`resolve_bounded_mutation_attribution` in `cli/src/services/mutation_trace/runtime/mutation_attribution.rs`) loads the newest ≤128 eligible events at or below the ceiling through `MutationEventPageSource` + `TreeReadSource` (`diff_trees` + `file_at_tree`) seams, replays them oldest-to-newest from a conservative baseline through the tail into `commit_tree`, then projects surviving provenance onto the committed patch. Removed lines are projected separately, through a non-resetting replay anchored at the exact first-parent tree (see `effective remover`), and the commit and parent trees are resolved from the captured commit OID, not `HEAD`. It is current-worktree-only and the generic replay is timestamp-independent; the production post-commit event source additionally requires each event's `created_at` before the trusted [commit-time cutoff](cli/mutation-trace-agent-attribution.md#commit-time-cutoff), filtered in SQL before the window limit. It owns `MAX_MUTATION_ATTRIBUTION_EVENTS = 128` (event 128 may contribute, 129 is never loaded), tracks database (`loaded_pages`/`loaded_rows`) apart from Git (`inspected_events`/`reconstructed_events`/`gap_resets`) work, and records a `mutation-attribution barrier` on any page-query or reconstruction/tail failure while still returning conservative results. See [mutation-trace store](cli/mutation-trace-store.md) and [mutation-trace Agent Trace attribution](cli/mutation-trace-agent-attribution.md). @@ -248,7 +248,7 @@ - `conversation-trace mixed batch`: Rust `sce hooks conversation-trace` STDIN contract accepting `{ payloads: [{ type: "message" | "message.part", ... }] }` with top-level `type` ignored and malformed-item skipping. See `context/sce/agent-trace-hooks-command-routing.md` and `context/sce/agent-trace-db.md`. - `conversation-trace raw Claude event path`: Claude hook event classification via `hook_event_name` routing (`UserPromptSubmit`/`Stop`/`PostToolUse`) that produces normalized `message` + `message.part` items. See `context/sce/agent-trace-hooks-command-routing.md`. - `agent-trace plugin conversation-trace handoff seam`: OpenCode plugin (`config/lib/agent-trace-plugin/`) mixed-batch envelope construction for `sce hooks conversation-trace`. See `context/sce/opencode-agent-trace-plugin-runtime.md`. -- `sce hooks claude-model-state`: Claude lifecycle hook command that accepts raw `SessionStart` and `PostModelSwitch` JSON, records normalized model observations in the local exact-scope `claude_model_state` register through the no-migration repository hook path, and best-effort seeds a model-less `SessionStart` from its bridge-linked chain using the same shared newest-chain-observation selection rule as the `diff-trace` state-miss path (bounded leading-record reads, one exact-scope state read per chain member, winner by greatest `observed_at_ms`) and `source="bridge_inherited"`. In practice this `SessionStart` attempt cannot read its own lazily created transcript, so `bridge session correlation` for a cleared session is carried by the `diff-trace` state-miss path (see `Claude diff-trace attribution`); the `SessionStart` attempt is kept for the case Claude ever creates transcripts eagerly. Missing discovery/state and all other intake, clock, DB-open, DB-read, or DB-write failures remain fail-open with empty stdout while logging failures. `SessionStart` is synchronous relative to Claude execution; `PostModelSwitch` is asynchronous, so local write completion—not Claude causal event order—determines state visibility. It writes no stdout; the Claude session login notice is owned by the `sce-info` hooks module (see [access policy: enforcement](cli/access-policy.md#enforcement)). See [Agent Trace hook routing](sce/agent-trace-hooks-command-routing.md). +- `sce hooks claude-model-state`: Claude lifecycle hook command that accepts raw `SessionStart` and `PostModelSwitch` JSON, records normalized model observations in the local exact-scope `claude_model_state` register through the no-migration repository hook path, and best-effort seeds a model-less `SessionStart` from its bridge-linked chain using the same shared newest-chain-observation selection rule as the `diff-trace` state-miss path (bounded leading-record reads, one exact-scope state read per chain member, winner by greatest `observed_at_ms`) and `source="bridge_inherited"`. In practice this `SessionStart` attempt cannot read its own lazily created transcript, so `bridge session correlation` for a cleared session is carried by the `diff-trace` state-miss path (see `Claude diff-trace attribution`); the `SessionStart` attempt is kept for the case Claude ever creates transcripts eagerly. Missing discovery/state and all other intake, clock, DB-open, DB-read, or DB-write failures remain fail-open with empty stdout while logging failures. `SessionStart` is synchronous relative to Claude execution; `PostModelSwitch` is asynchronous, so local write completion—not Claude causal event order—determines state visibility. On every valid `SessionStart` it also stores the `Claude session auth state` classification independently of model-state persistence; `PostModelSwitch` is ignored for auth. It writes no stdout; the Claude session login notice is owned by the `sce-info` hooks module (see [access policy: enforcement](cli/access-policy.md#enforcement)). See [Agent Trace hook routing](sce/agent-trace-hooks-command-routing.md). - `agent-trace plugin secondary diff persistence ownership`: Current runtime contract where `buildTrace` no longer writes diff-trace artifacts or database rows directly; extracted diff payloads are forwarded to CLI `diff-trace` intake and the Rust hook runtime owns AgentTraceDb insertion without any `context/tmp` artifact fallback. - `messages table (Agent Trace DB)`: Agent Trace DB table created by migration `008_create_messages.sql`; stores session-scoped parent messages with columns `session_id`, `message_id`, `role` (`user`/`assistant` via CHECK constraint), `generated_at_unix_ms`, `created_at`, and `updated_at`. Message body text belongs to `parts.text`, not the parent `messages` row. Has a unique index on `(session_id, message_id)` for duplicate-ignore parent message inserts and a compound index on `(session_id, generated_at_unix_ms, id)` for chronological session message retrieval. No foreign keys to any other table. - `musl static Linux release`: The Linux binary release targets (`x86_64-unknown-linux-musl` and `aarch64-unknown-linux-musl`) compile against musl libc and link fully statically. The resulting binary has no runtime libc dependency and zero `/nix/store/` references in ELF metadata, strings, or dynamic-linker fields, satisfying the native portability audit. The musl targets replace the previous glibc-linked `*-unknown-linux-gnu` targets; macOS (`aarch64-apple-darwin`) is unchanged. Introduced in the `musl-static-linux-release` plan. diff --git a/context/plans/claude-auth-billing-observations.md b/context/plans/claude-auth-billing-observations.md new file mode 100644 index 000000000..38e4446a4 --- /dev/null +++ b/context/plans/claude-auth-billing-observations.md @@ -0,0 +1,234 @@ +# Plan: claude-auth-billing-observations + +## Change summary + +Extend the existing `sce hooks claude-model-state` hook so every valid Claude +`SessionStart` (all sources: `startup`, `resume`, `clear`, `compact`, with or +without `model`) also classifies Claude Code's configured authentication +provider, billing mode, selected authentication environment key, and detection +confidence from the presence of documented environment variables, and stores the +current classification for the session in the existing repository-scoped Agent +Trace DB (`RepositoryAgentTraceDb`). The Agent Trace DB is the source of truth; +no new hook, database, service, event store, or telemetry pipeline is +introduced. Model-selection and `claude_model_state` behavior are preserved +unchanged, and `PostModelSwitch` is ignored for auth. + +Environment variables describe configuration, not proof of successful +authentication or actual billing, so every recognized signal is `Inferred` and +the absence of any usable signal is `Unknown`. Persistence is one latest-state +row per canonical `claude:`, written by a single atomic upsert that +changes the row only when the classification changes. No historical transition +log is kept: the request names no concrete downstream consumer of transitions, +and the latest-state shape mirrors the existing `claude_model_state` register. + +Migration `008_claude_session_auth_state` is additive. Today hook readiness +(`open_repository_db_for_hook_runtime` → `ensure_schema_ready_for_hooks` → +`TursoDb::migration_metadata_problems`) requires exact ledger parity, so a new +migration would make every repository hook fail open until `sce setup` reruns. +The setup fast path (`open_repository_db_concurrently_safe`) uses the same +strict check to decide whether to run migrations, so the strict check itself +must not change. Instead, the hook-runtime open path alone uses a narrow +readiness variant that accepts either the full ledger or the full ledger minus +exactly `008_claude_session_auth_state`; the auth write is skipped when `008` is +not applied. Setup, the concurrent-first-open repair recheck, and doctor keep +strict parity, so setup still applies `008` and doctor still reports the schema +as not ready until setup reruns. Unexpected-ID (downgrade) handling is +unchanged. + +Exporter, `sce sync`, control-plane, warehouse, and web changes are not +implemented. Observations stay local until a future export change. + +## Acceptance criteria + +How this plan is proven complete. Each criterion is observable and names the +check that proves it. `/validate` runs these checks; no task in the stack +performs final validation. + +- [x] AC1: The pure detector maps each documented signal to the expected provider, billing mode, typed env key, and `Inferred` confidence, and never returns a verified confidence or `Subscription` billing: Bedrock/Vertex/Foundry flags yield their provider with `CloudProvider` billing and take precedence over Anthropic credentials; `ANTHROPIC_AUTH_TOKEN` takes precedence over `ANTHROPIC_API_KEY` and yields `Unknown` billing (never `ApiKey`); `ANTHROPIC_API_KEY` without a custom base URL yields `Anthropic` with `ApiKey` billing; a custom `ANTHROPIC_BASE_URL` with either credential yields `CustomGateway` with `Unknown` billing; `CLAUDE_CODE_OAUTH_TOKEN` alone yields `Anthropic` with `Unknown` billing; more than one cloud flag, or no signal, yields `Unknown` provider, billing, and confidence with no env key. + - Validate: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_detection` +- [x] AC2: Migration `008_claude_session_auth_state` creates `claude_session_auth_state` keyed by `session_id` with `CHECK`-constrained enum columns and non-negative `observed_at_ms`, and has no column capable of holding a credential value or hash; migrations 001–007 are unchanged. + - Validate: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml agent_trace_repository_migrations`; `git diff --exit-code -- cli/migrations/agent-trace-repository/00[1-7]_*.sql` +- [x] AC3: Repeated identical upserts leave one unchanged row (including `observed_at_ms`); a changed classification updates the row in place; the latest-state read returns the exact canonical session's row and never another session's. + - Validate: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_session_auth_state` +- [x] AC4: On a pre-`008` repository DB, existing hooks (including `claude-model-state` model writes, `diff-trace`, and `conversation-trace`) still persist and the auth write is skipped without error; setup applies `008` on that DB; doctor still reports the schema not ready before setup; a DB missing any other migration, or carrying an unexpected migration ID, is still rejected by the hook runtime. + - Validate: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_session_auth_schema_compat` +- [x] AC5: `sce hooks claude-model-state` on `SessionStart` (startup and resume, with and without `model`) stores the auth classification under `claude:`, changes it only when the classification changes across resumes and duplicate executions, leaves `claude_model_state` writes identical to current behavior, ignores `PostModelSwitch` for auth, and returns empty stdout on every path including DB-open and write failures. + - Validate: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_model_state` +- [x] AC6: Sentinel credential values supplied to the hook appear in no DB row, no captured log output, and no hook stdout. + - Validate: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_state_no_secret` +- [x] AC7: Durable context documents detection rules and limitations, the table schema, hook integration, migration-008 compatibility, and that the data stays local until a future `sce sync`/warehouse export change, without specifying downstream routes, cursors, object layouts, or warehouse schemas. + - Validate: inspect `context/sce/claude-session-auth-state.md`, `context/sce/agent-trace-db.md`, `context/sce/agent-trace-db-schema.md`, and `context/context-map.md`. + +### Full validation + +Repository-wide checks `/validate` runs after the last task, regardless of +which criterion they map to. + +- `nix run .#pkl-check-generated` +- `nix flake check` + +### Context sync + +- `context/sce/claude-session-auth-state.md` (new: detection rules and limitations, schema, hook integration, migration compatibility, local-only status) +- `context/sce/agent-trace-db.md` (migration list, adapter methods, hook-runtime readiness variant, migration-008 note) +- `context/sce/agent-trace-db-schema.md` (new table columns) +- `context/sce/agent-trace-export-readers.md` (new table is local-only with no reader method) +- `context/context-map.md` and `context/glossary.md` (new entry and terms) + +## Task context synchronization lifecycle + +Persist this field in every plan; this is durable plan state, not chat state: + +- **Task context synchronization:** every task carries `pending | synced | blocked`. + A completed task must be `synced` before another task can start or the plan can + finish. +- For `blocked`, record **Blocker**, **Required action**, and **Retry condition** + beside the status. Never infer `synced` from conversation history; write every + lifecycle transition to the plan file. + +## Constraints and non-goals + +- **In scope:** a new pure detection module next to `cli/src/services/hooks/claude_model_state.rs`; `cli/migrations/agent-trace-repository/008_claude_session_auth_state.sql`; typed payload/SQL in `cli/src/services/agent_trace_db/mod.rs` and methods in `repository.rs`; the hook-runtime readiness path in `cli/src/services/agent_trace_storage/mod.rs`; `claude_model_state.rs`; tests that enumerate the repository migration list; durable context files listed under Context sync. +- **Out of scope:** `AgentTraceExportReader`, `sce sync`, control-plane ingestion, S3, ClickHouse, `packages/warehouse`, web UI, and any design of them; new hook registrations or Pkl hook config changes; `PostModelSwitch` auth handling; reading Claude credential files, keychain, `apiKeyHelper`, or settings files; historical transition logging; historical backfill; other agents (OpenCode, Codex, Pi); unrelated refactoring of `claude_model_state.rs`. +- **Constraints:** static dispatch, no `dyn`/`Box`, no new dependencies, typed enums for classification with string mapping only at the SQL boundary, existing `anyhow::Result` conventions in the DB and hook layers with no new error abstraction, rustdoc-only comments, no credential values or hashes in logs/rows/telemetry, hooks never migrate and always fail open with empty stdout, strict ledger parity unchanged for setup, repair, and doctor. +- **Non-goal:** a generic migration-compatibility framework, a generic session-metadata store or event store, a second hook, or any new telemetry/export path. + +## Assumptions + +- Precedence follows the Claude Code authentication documentation: cloud-provider flags (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`) → `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → `CLAUDE_CODE_OAUTH_TOKEN` → interactive `/login` credentials (not observable, so `Unknown`). More than one cloud flag set is a provider conflict and classifies as `Unknown`. +- A cloud flag counts as set only for truthy values (`1`/`true`, case-insensitive); credential variables count as set when present and non-empty. Only presence/truthiness is read; values are never retained beyond the check. +- Classification table (all recognized signals are `Inferred`; environment variables describe authentication configuration, not actual billing): + + | Selected signal | Provider | Billing mode | Auth env key | + |---|---|---|---| + | `CLAUDE_CODE_USE_BEDROCK` | `AwsBedrock` | `CloudProvider` | `ClaudeCodeUseBedrock` | + | `CLAUDE_CODE_USE_VERTEX` | `GoogleVertex` | `CloudProvider` | `ClaudeCodeUseVertex` | + | `CLAUDE_CODE_USE_FOUNDRY` | `MicrosoftFoundry` | `CloudProvider` | `ClaudeCodeUseFoundry` | + | `ANTHROPIC_AUTH_TOKEN`, no custom base URL | `Anthropic` | `Unknown` | `AnthropicAuthToken` | + | `ANTHROPIC_AUTH_TOKEN`, custom base URL | `CustomGateway` | `Unknown` | `AnthropicAuthToken` | + | `ANTHROPIC_API_KEY`, no custom base URL | `Anthropic` | `ApiKey` | `AnthropicApiKey` | + | `ANTHROPIC_API_KEY`, custom base URL | `CustomGateway` | `Unknown` | `AnthropicApiKey` | + | `CLAUDE_CODE_OAUTH_TOKEN` | `Anthropic` | `Unknown` | `ClaudeCodeOauthToken` | + | No signal, or more than one cloud flag | `Unknown` | `Unknown` | none (confidence `Unknown`) | + + `ANTHROPIC_AUTH_TOKEN` may authenticate against a proxy or gateway, so it never implies API-key billing; OAuth authentication never implies a paid subscription. `ANTHROPIC_BASE_URL` is a classification input without an `AuthEnvKey` variant because it is not a credential. +- `BillingMode::Subscription` is retained in the enum, string mapping, and `CHECK` constraint, but no environment-only signal produces it; the detector cannot establish subscription billing from the permitted inputs. +- `DetectionConfidence` has only `Inferred` and `Unknown`: no permitted input can verify authentication, so a `Verified` variant would be dead code. It can be added when a verifying source exists. +- The hook reads the environment it inherits from Claude Code (which includes `settings.json` `env` values); the detector takes an explicit input struct so tests never mutate process environment. +- Persistence is `INSERT ... ON CONFLICT (session_id) DO UPDATE SET ... WHERE` any classification column differs, so identical replays are no-ops (leaving `observed_at_ms` as the time the current classification was first observed), changes update in place, and no read-before-write or explicit transaction is needed. +- The hook-runtime readiness variant lives in the repository adapter as one named constant for the single optional migration ID, not a general mechanism; the auth write checks the migration ledger for `008` and skips when absent. When a future migration lands, the constant is revisited rather than extended into a list. +- The canonical session ID comes from the existing `prefixed_diff_trace_session_id(CLAUDE_TOOL_NAME, raw)`; repository isolation comes from the per-repository DB file, so no repository column is added. Auth configuration is process-level, so the key has no `agent_id`. + +## Task stack + +- [x] T01: `Add pure Claude auth and billing detector` (status:done) + - Task ID: T01 + - Scope: In — `AuthProvider`, `BillingMode`, `AuthEnvKey`, `DetectionConfidence` (`Inferred`, `Unknown`) enums with stable snake_case string mapping; an explicit input struct of signal presence; a pure deterministic `detect_claude_auth` function implementing the documented precedence; a constructor building the input from an env-lookup closure without retaining values; unit tests covering every row of the classification table: each cloud flag and its precedence over Anthropic credentials, `ANTHROPIC_AUTH_TOKEN` precedence over `ANTHROPIC_API_KEY` and `Unknown` billing (not `ApiKey`), `ANTHROPIC_API_KEY` as inferred `ApiKey`, custom-gateway classification for both credentials, OAuth-only as `Unknown` billing (not `Subscription`), provider conflict, and missing configuration. Out — persistence, hook wiring. + - Dependencies: none + - Done when: the detector and enums compile with no `dyn`/`Box`/new deps, hold no credential value fields, never return a verified confidence or `Subscription` billing, and all unit tests pass. + - Verify: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_detection` + - Completed: 2026-11-20 + - Files changed: `cli/src/services/hooks/claude_auth_detection.rs` (new), `cli/src/services/hooks/mod.rs` + - Result: Added private `hooks::claude_auth_detection` with `AuthProvider`, `BillingMode`, `AuthEnvKey`, `DetectionConfidence` (`Inferred`, `Unknown`) and `as_str`/`from_str` snake_case mapping; `ClaudeAuthSignals` (presence-only bools) built by `from_env_lookup` closure; `ClaudeAuthDetection` result; `detect_claude_auth` implementing the documented precedence and provider-conflict rule. 10 unit tests cover every classification-table row, falsy flags, empty credentials, an exhaustive no-`Subscription` sweep over all signal combinations, and string round-trips. No `dyn`/`Box`, no new dependencies, no value-holding fields. + - Verify outcome: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_detection` passed (10 passed, 0 failed); `clippy --all-targets` passed; `cargo fmt --check` passed after formatting. + - Deviations/assumptions: A custom base URL means `ANTHROPIC_BASE_URL` is non-empty and not `https://api.anthropic.com` (trimmed, trailing `/` stripped, case-insensitive). Because the binary crate denies warnings and the module is unused until T03/T04, its `mod` declaration carries `#[cfg_attr(not(test), expect(dead_code, ...))]`, which must be removed when the module is wired in. + - Context impact: localized — new internal module with no runtime wiring; durable context for detection rules is owned by T05. + - Context synchronization: synced + +- [x] T02: `Add migration 008 with hook-runtime compatibility for pre-008 databases` (status:done) + - Task ID: T02 + - Scope: In — `008_claude_session_auth_state.sql` creating `claude_session_auth_state (session_id TEXT PRIMARY KEY, provider, billing_mode, auth_env_key NULLable, confidence, observed_at_ms INTEGER NOT NULL CHECK (>= 0))` with `CHECK` constraints on enum columns; a hook-runtime readiness method on `RepositoryAgentTraceDb` that accepts the full ledger or the full ledger minus exactly `008_claude_session_auth_state`; switching only `open_repository_db_for_hook_runtime` to it; updating tests that enumerate `AGENT_TRACE_REPOSITORY_MIGRATIONS`; tests on pre-`008` and current DBs proving hooks open, setup applies `008`, doctor reports not-ready before setup, and missing-other or unexpected IDs are still rejected. Out — auth read/write helpers, setup fast path, repair recheck, doctor readiness semantics, migrations 001–007. + - Dependencies: none + - Done when: existing hook paths open a pre-`008` DB, setup and doctor keep strict parity, unrelated migration gaps still fail readiness, and the targeted tests pass. + - Verify: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml agent_trace_repository_migrations`; `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_session_auth_schema_compat`; `git diff --exit-code -- cli/migrations/agent-trace-repository/00[1-7]_*.sql` + - Completed: 2026-11-20 + - Files changed: `cli/migrations/agent-trace-repository/008_claude_session_auth_state.sql` (new), `cli/src/services/agent_trace_db/repository.rs`, `cli/src/services/agent_trace_storage/mod.rs` + - Result: Added migration `008_claude_session_auth_state` creating `claude_session_auth_state` (`session_id TEXT PRIMARY KEY`, `CHECK`-constrained `provider`/`billing_mode`/`confidence`, nullable `CHECK`-constrained `auth_env_key`, `observed_at_ms INTEGER NOT NULL CHECK (>= 0)`). Added `HOOK_RUNTIME_OPTIONAL_MIGRATION_ID` and `RepositoryAgentTraceDb::ensure_schema_ready_for_hook_runtime` (strict parity, or applied set equal to expected set minus exactly `008`); split the legacy `001` metadata repair into a shared record step plus strict (`repair_missing_repository_schema_migration_metadata`) and hook-runtime (`..._for_hook_runtime`) rechecks; only `open_repository_db_for_hook_runtime` uses the hook-runtime variants. Setup fast path, repair recheck, and doctor (`open_existing_schema_ready_at`) keep strict parity. 8 new tests: migration list and table constraints (`agent_trace_repository_migrations_*`), and pre-`008` hook open with model-state and diff-trace writes, current-DB hook open, setup applying `008`, doctor rejecting pre-`008`, and hook rejection for other missing migrations and unexpected IDs (`claude_session_auth_schema_compat_*`). + - Verify outcome: `agent_trace_repository_migrations` passed (2 passed); `claude_session_auth_schema_compat` passed (6 passed); `git diff --exit-code` on migrations 001–007 passed; full CLI suite passed (871 passed, 0 failed); `clippy --all-targets` clean; `cargo fmt` applied. + - Deviations/assumptions: No pre-existing test hardcoded the migration list (the build script discovers migrations), so the enumeration test is new; existing pre-007 slicing fixtures work unchanged. + - Context impact: localized — new repository migration and a hook-runtime-only readiness variant; durable context (`agent-trace-db.md`, `agent-trace-db-schema.md`, new `claude-session-auth-state.md`) is owned by T05. + - Context synchronization: synced + +- [x] T03: `Add Claude session auth state upsert and read interface` (status:done) + - Task ID: T03 + - Scope: In — typed `ClaudeSessionAuthState` payload using the T01 enums; parameterized atomic change-only upsert SQL; `RepositoryAgentTraceDb::upsert_claude_session_auth_state` that returns a skipped outcome when `008` is not in the ledger; `claude_session_auth_state_by_session(session_id)` returning the typed row or none; row-to-enum parsing that rejects unknown stored values; tests for identical replay no-op, change update, session isolation, read, and pre-`008` skip. Out — hook wiring, export reader, history. + - Dependencies: T01, T02 + - Done when: helpers follow the existing `claude_model_state` delegation pattern, the write is a single statement without explicit transaction or prior read of the row, and targeted tests pass. + - Verify: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_session_auth_state` + - Completed: 2026-11-20 + - Files changed: `cli/src/services/agent_trace_db/mod.rs`, `cli/src/services/agent_trace_db/repository.rs`, `cli/src/services/agent_trace_storage/mod.rs`, `cli/src/services/hooks/mod.rs` + - Result: Added `ClaudeSessionAuthState` (T01 enums, nullable `auth_env_key`) and `ClaudeSessionAuthStateUpsertOutcome` (`Upserted { rows_changed }`, `SkippedMissingMigration`); `UPSERT_CLAUDE_SESSION_AUTH_STATE_SQL` (`INSERT ... ON CONFLICT (session_id) DO UPDATE ... WHERE` provider/billing_mode/confidence `<>` or `auth_env_key IS NOT` the stored value) and `SELECT_CLAUDE_SESSION_AUTH_STATE_SQL`; `upsert_claude_session_auth_state_with` / `claude_session_auth_state_by_session_with` / row parser using the T01 `from_str` mappings (unknown stored values error). `RepositoryAgentTraceDb::upsert_claude_session_auth_state` checks the `__sce_migrations` ledger for `HOOK_RUNTIME_OPTIONAL_MIGRATION_ID` and returns `SkippedMissingMigration` when absent, otherwise runs the single upsert statement (no transaction, no prior row read); `claude_session_auth_state_by_session` delegates to the read helper. `hooks::claude_auth_detection` is now `pub(crate)`. 5 new tests: identical replay no-op (including `observed_at_ms`, for both a keyed and a null-key row), in-place change including clearing `auth_env_key`, exact-session isolation, unknown stored value rejection, and pre-`008` skip. + - Verify outcome: `claude_session_auth_state` passed (7 passed, including 2 T02 migration tests matching the filter); full CLI suite passed (876 passed, 0 failed); `clippy --all-targets` clean; `cargo fmt --check` passed. + - Deviations/assumptions: Tests live in the `agent_trace_storage` test module to reuse the current and pre-`008` DB fixtures. The two public adapter methods carry `#[cfg_attr(not(test), expect(dead_code, ...))]` until T04 wires the hook; remove those attributes (and the T01 module-level one) in T04. `expect` seeds liveness, so the helpers they call need no attribute. + - Context impact: localized — new typed persistence helpers for the T02 table with no runtime wiring; durable context is owned by T05. + - Context synchronization: synced + +- [x] T04: `Store auth state from every claude-model-state SessionStart` (status:done) + - Task ID: T04 + - Scope: In — `claude_model_state.rs`: derive the canonical `claude:` session ID for any valid `SessionStart` from the already parsed payload fields (reusing existing helpers, no second parse path), detect from the inherited environment, and open the DB when an auth candidate, model observation, or bridge candidate exists instead of returning early on model-less events; run the auth upsert independently of model-state persistence so either failing does not affect the other; a dedicated fail-open log event for auth write failures carrying only the session ID and error; tests for startup, resume with change, resume without change, duplicate execution, model-less `SessionStart`, `PostModelSwitch` ignored, DB-open failure, unchanged `claude_model_state` rows, empty stdout, and sentinel credential values absent from rows, logs, and stdout. Out — Pkl hook config, `PostModelSwitch` auth, other hooks, unrelated refactoring. + - Dependencies: T03 + - Done when: existing `claude_model_state` tests pass unchanged, new hook tests pass, and hook stdout stays empty on every path. + - Verify: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_model_state`; `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_state_no_secret` + - Completed: 2026-11-20 + - Files changed: `cli/src/services/hooks/claude_model_state.rs`, `cli/src/services/hooks/mod.rs`, `cli/src/services/agent_trace_db/repository.rs` + - Result: `parse_claude_model_state_payload` now returns `ClaudeModelStatePayload { observation, session_start_session_id }`; every valid `SessionStart` (requires `session_id` and `source`; `model` optional) yields the canonical session ID from the existing `prefixed_diff_trace_session_id` path, with no second parse. `run_claude_model_state_from_payload_with` takes an env-lookup closure (production: `std::env::var`), builds `ClaudeSessionAuthState` via `detect_claude_auth(ClaudeAuthSignals::from_env_lookup(..))`, and opens the DB when an auth candidate, model observation, or bridge candidate exists. Model-state persistence (direct or bridge-inherited) and the auth upsert run independently after the open; auth write failures log `sce.hooks.claude_model_state.auth_state_agent_trace_db_write_failed` with only the canonical session ID and error. `PostModelSwitch` yields no auth candidate. Removed the T01 module-level and T03 upsert `expect(dead_code)` attributes; `claude_session_auth_state_by_session` keeps its `expect` with an updated reason (no production reader until a future export change). 10 new hook tests: startup stores auth plus an unchanged model row, resume with change, resume without change, duplicate execution, model-less `SessionStart`, `PostModelSwitch` ignored, DB-open failure, auth write failure not blocking model state, and two `claude_auth_state_no_secret_*` sentinel tests over rows, logs, and stdout. + - Verify outcome: `claude_model_state` passed (12 passed: 10 new plus 2 pre-existing, unchanged); `claude_auth_state_no_secret` passed (2 passed); full CLI suite passed (886 passed, 0 failed); `clippy --all-targets` clean; `cargo fmt --check` passed. + - Deviations/assumptions: The canonical Claude session ID produced by `prefixed_diff_trace_session_id(CLAUDE_TOOL_NAME, raw)` is `cc_`, not the literal `claude:` used in the plan text; the existing helper is authoritative and T05 should document `cc_`. A model-less `SessionStart` missing `source` now fails in the payload parse instead of the bridge-candidate parse, with the same fail-open outcome (error log, no writes). Auth `observed_at_ms` uses the hook observation time. + - Context impact: localized — runtime wiring of the existing hook to the T03 persistence helpers, with a new fail-open log event; durable context is owned by T05. + - Context synchronization: synced + +- [x] T05: `Document Claude session auth state` (status:done) + - Task ID: T05 + - Scope: In — new `context/sce/claude-session-auth-state.md` covering detection rules, precedence, the classification table, the distinction between authentication configuration and actual billing (environment signals are `Inferred` configuration evidence; neither `ANTHROPIC_AUTH_TOKEN` nor OAuth implies a billing mode), confidence semantics, limitations (`/login` and `apiKeyHelper` not observable), table schema, hook integration, migration-008 compatibility, and that the data is local-only until a future `sce sync`/warehouse export change; updates to `agent-trace-db.md`, `agent-trace-db-schema.md`, `agent-trace-export-readers.md`, `context-map.md`, and `glossary.md`. Out — code changes; any design of export routes, cursors, storage layouts, or warehouse schemas. + - Dependencies: T04 + - Done when: context files accurately describe the implemented code and mention future export only as unplanned follow-up work. + - Verify: inspect the listed context files against `claude_model_state.rs`, the migration, `repository.rs`, and `agent_trace_storage/mod.rs`. + - Completed: 2026-11-20 + - Files changed: `context/sce/claude-session-auth-state.md`, `context/sce/agent-trace-export-readers.md`, `context/glossary.md` + - Result: Earlier task syncs had already written the detector, configuration-versus-billing, limitations, persistence, and hook-integration sections plus the `agent-trace-db.md`, `agent-trace-db-schema.md`, and `context-map.md` entries. This task added `Migration-008 compatibility` and `Local-only status` sections to `claude-session-auth-state.md` (future export named only as unplanned follow-up, with no route, cursor, or schema), listed `claude_session_auth_state` as local-only with no reader method in `agent-trace-export-readers.md`, and added a `Claude session auth state` glossary term while updating the `agent trace DB adapter` and `sce hooks claude-model-state` entries. + - Verify outcome: Manual inspection passed: the documented table columns and `CHECK` sets match `008_claude_session_auth_state.sql`; `HOOK_RUNTIME_OPTIONAL_MIGRATION_ID`, `ensure_schema_ready_for_hook_runtime`, `upsert_claude_session_auth_state` (`SkippedMissingMigration`), and `claude_session_auth_state_by_session` match `repository.rs`/`mod.rs`; `open_repository_db_for_hook_runtime` matches `agent_trace_storage/mod.rs`; the `auth_state_agent_trace_db_write_failed` log event and the `std::env::var` lookup match `claude_model_state.rs`. No code changed. + - Deviations/assumptions: Context documents the canonical session ID as `cc_` (per the T04 deviation) rather than the plan's `claude:`. + - Context impact: localized — documentation only, in the context files T05 owns. + - Context synchronization: synced + +## Open questions + +- With no env signals, interactive `/login` subscription users (credentials in the keychain or credential file) always classify as `Unknown`, because reading credential storage is not allowed. Is that coverage acceptable, or should the value of the data be confirmed before shipping? +- Sessions using `apiKeyHelper` cannot be identified, because it lives in settings rather than the environment. Acceptable, or should settings inspection be approved? + +## Validation Report + +**Status:** validated +**Date:** 2026-11-20 + +### Commands run + +- `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_detection` -> exit 0 (10 passed, 0 failed) +- `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml agent_trace_repository_migrations` -> exit 0 (2 passed, 0 failed) +- `git diff --exit-code -- cli/migrations/agent-trace-repository/00[1-7]_*.sql` -> exit 0 (no changes; also exit 0 against `main`) +- `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_session_auth_state` -> exit 0 (7 passed, 0 failed) +- `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_session_auth_schema_compat` -> exit 0 (6 passed, 0 failed) +- `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_model_state` -> exit 0 (12 passed, 0 failed) +- `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml claude_auth_state_no_secret` -> exit 0 (2 passed, 0 failed) +- `nix run .#pkl-check-generated` -> exit 0 (ephemeral Pkl generation passed: 145 files) +- `nix flake check` -> exit 0 (all 5 checks passed: build, clippy, fmt, tests, setup-schema-upgrade-check) + +### Success-criteria verification + +- [x] AC1: Pure detector maps every documented signal with `Inferred` confidence, never verified or `Subscription` -> `claude_auth_detection` 10 passed, covering every classification-table row and an exhaustive no-`Subscription` sweep +- [x] AC2: Migration `008` creates the constrained `claude_session_auth_state` table with no credential column; 001–007 unchanged -> `agent_trace_repository_migrations` 2 passed; `git diff --exit-code` on 001–007 clean (working tree and vs `main`) +- [x] AC3: Identical upserts are no-ops, changes update in place, reads are session-exact -> `claude_session_auth_state` 7 passed +- [x] AC4: Pre-`008` DBs keep hooks working with auth skipped; setup applies `008`; doctor not ready; other gaps and unexpected IDs rejected -> `claude_session_auth_schema_compat` 6 passed +- [x] AC5: `SessionStart` stores change-only auth state, model-state writes unchanged, `PostModelSwitch` ignored, empty stdout on every path -> `claude_model_state` 12 passed (10 new, 2 pre-existing unchanged) +- [x] AC6: Sentinel credentials absent from rows, logs, and stdout -> `claude_auth_state_no_secret` 2 passed +- [x] AC7: Durable context documents detection, schema, hook integration, migration-008 compatibility, and local-only status without export design -> inspected `context/sce/claude-session-auth-state.md` (Detector, Configuration is not billing, Limitations, Persistence, Hook integration, Migration-008 compatibility, Local-only status sections; export named only as unplanned follow-up with no route, cursor, or schema), `context/sce/agent-trace-db.md` (hook-runtime readiness variant and `HOOK_RUNTIME_OPTIONAL_MIGRATION_ID`), `context/sce/agent-trace-db-schema.md` (migration `008` table), and `context/context-map.md` (entries for all three) + +### Failed checks and follow-ups + +- None. + +### Residual risks + +- The canonical session key is `cc_` (from `prefixed_diff_trace_session_id`), not the literal `claude:` in the plan text; tests and context follow the implemented `cc_` form. +- Interactive `/login` and `apiKeyHelper` users always classify as `Unknown` (see Open questions); the data's value for those sessions is unconfirmed. +- T05 context edits (`context/glossary.md`, `context/sce/agent-trace-export-readers.md`, `context/sce/claude-session-auth-state.md`) are uncommitted in the working tree. diff --git a/context/sce/agent-trace-db-schema.md b/context/sce/agent-trace-db-schema.md index 3eb4726bf..12728bf93 100644 --- a/context/sce/agent-trace-db-schema.md +++ b/context/sce/agent-trace-db-schema.md @@ -41,6 +41,15 @@ Migration `007_commit_patch_id` adds: - `commit_patch_id TEXT` (nullable) — optional Git patch ID of the original commit; `NULL` for rows created before the migration or when no fingerprint is available. +Migration `008_claude_session_auth_state` creates `claude_session_auth_state`: + +- `session_id TEXT PRIMARY KEY` — canonical `cc_` +- `provider TEXT NOT NULL CHECK (IN 'anthropic', 'aws_bedrock', 'google_vertex', 'microsoft_foundry', 'custom_gateway', 'unknown')` +- `billing_mode TEXT NOT NULL CHECK (IN 'api_key', 'subscription', 'cloud_provider', 'unknown')` +- `auth_env_key TEXT` (nullable) `CHECK (NULL OR IN 'claude_code_use_bedrock', 'claude_code_use_vertex', 'claude_code_use_foundry', 'anthropic_auth_token', 'anthropic_api_key', 'claude_code_oauth_token')` — names the selected variable, never its value +- `confidence TEXT NOT NULL CHECK (IN 'inferred', 'unknown')` +- `observed_at_ms INTEGER NOT NULL CHECK (observed_at_ms >= 0)` + The `messages` migration creates: - `id INTEGER PRIMARY KEY` diff --git a/context/sce/agent-trace-db.md b/context/sce/agent-trace-db.md index 101d0a88f..5cb8fbdab 100644 --- a/context/sce/agent-trace-db.md +++ b/context/sce/agent-trace-db.md @@ -13,6 +13,7 @@ - `ObservationKind`: the two persisted lifecycle values `SessionStart` (`session_start`) and `PostModelSwitch` (`post_model_switch`). - `upsert_claude_model_state()`: guarded latest-locally-observed register write. Strictly older observations are ignored; equal timestamps prefer `PostModelSwitch`, then use deterministic model/source lexical tie-breaks for same-kind observations, making identical replays no-ops. - `claude_model_state_by_session_and_agent()`: exact `(session_id, agent_id)` lookup returning the typed observation or no row; it does not broaden the scope to another agent. +- `ClaudeSessionAuthState` / `upsert_claude_session_auth_state()` / `claude_session_auth_state_by_session()`: latest-state Claude session auth classification register keyed by canonical `session_id`. The upsert returns `ClaudeSessionAuthStateUpsertOutcome::SkippedMissingMigration` without writing on a pre-`008` ledger. Otherwise it is a single change-only statement, so identical replays are no-ops. See [claude-session-auth-state.md](claude-session-auth-state.md#persistence). - `insert_diff_trace()`: domain-specific insert helper using parameterized SQL. - `RecentDiffTracePatches`: parsed recent `diff_traces` query result containing valid parsed patches plus skipped-row reports. - `recent_diff_trace_patches(cutoff_time_ms, end_time_ms)`: chronological `diff_traces` read helper for rows in the inclusive window `time_ms >= cutoff_time_ms AND time_ms <= end_time_ms`; parses raw patch text through `parse_patch` and skips malformed rows without failing the query. @@ -42,7 +43,7 @@ pub type RepositoryAgentTraceDb = TursoDb; Repository persistence, readiness checks, transactions, and migration operations are native async methods inherited from `TursoDb`. Hook, lifecycle, mutation-trace, and sync callers await them on the application runtime before returning or advancing their cursor. The async migration changes no SQL, schema, WAL, encryption, or retry policy. -This adapter has no canonical `DbSpec::db_path()`; callers must resolve `/sce/repos//agent-trace.db` first and use explicit-path `TursoDb` constructors. Its migration list is `generated_migrations::AGENT_TRACE_REPOSITORY_MIGRATIONS`: the fresh multi-statement baseline `cli/migrations/agent-trace-repository/001_repository_schema.sql` plus the additive `002_repository_source_instance_id.sql` (adds `repository_metadata.source_instance_id`), `003_claude_model_state.sql` (adds the non-exported Claude model-state register), `004_mutation_trace_protocol.sql`, `005_mutation_scope_provenance.sql`, and `006_mutation_trace_health_invariant.sql` (the mutation-cursor protocol tables, the scope-provenance table, and the health-invariant rebuild; see [mutation-trace store](../cli/mutation-trace-store.md) and [mutation-scope provenance](../cli/mutation-scope-provenance.md)), plus `007_commit_patch_id.sql` (adds the nullable `agent_traces.commit_patch_id` column). The baseline schema includes `repository_metadata` plus the existing repository-level Agent Trace tables, indexes, and triggers, and intentionally has no `checkout_id` columns on trace tables. `RepositoryAgentTraceDb::verify_or_initialize_repository_metadata(repository_id) -> Result` inserts the singleton metadata row on first initialization, errors if an existing DB stores a different repository ID, and atomically claims `source_instance_id` for this physical database via `UPDATE ... WHERE source_instance_id = ''` (a losing racer's generated candidate is discarded and an already-valid stored value is never overwritten), returning the typed `RepositoryMetadata { repository_id, source_instance_id }`. `source_instance_id` is generated by application code (`generate_source_instance_id()`, UUID v4) and validated with `is_valid_source_instance_id()` (non-empty once trimmed); it is never derived from `repository_id`, remote URL, checkout ID, filesystem path, hostname, or user/workspace identity, and stays stable across reopen and repeated `sce setup` runs. `RepositoryAgentTraceDb::repair_missing_repository_schema_migration_metadata()` is a narrow concurrent-first-open repair seam: it never creates trace tables, but if every required repository schema table already exists and only the one-file baseline migration record is missing, it records `001_repository_schema` and rechecks readiness. +This adapter has no canonical `DbSpec::db_path()`; callers must resolve `/sce/repos//agent-trace.db` first and use explicit-path `TursoDb` constructors. Its migration list is `generated_migrations::AGENT_TRACE_REPOSITORY_MIGRATIONS`: the fresh multi-statement baseline `cli/migrations/agent-trace-repository/001_repository_schema.sql` plus the additive `002_repository_source_instance_id.sql` (adds `repository_metadata.source_instance_id`), `003_claude_model_state.sql` (adds the non-exported Claude model-state register), `004_mutation_trace_protocol.sql`, `005_mutation_scope_provenance.sql`, and `006_mutation_trace_health_invariant.sql` (the mutation-cursor protocol tables, the scope-provenance table, and the health-invariant rebuild; see [mutation-trace store](../cli/mutation-trace-store.md) and [mutation-scope provenance](../cli/mutation-scope-provenance.md)), plus `007_commit_patch_id.sql` (adds the nullable `agent_traces.commit_patch_id` column) and `008_claude_session_auth_state.sql` (adds the local-only `claude_session_auth_state` table). The baseline schema includes `repository_metadata` plus the existing repository-level Agent Trace tables, indexes, and triggers, and intentionally has no `checkout_id` columns on trace tables. `RepositoryAgentTraceDb::verify_or_initialize_repository_metadata(repository_id) -> Result` inserts the singleton metadata row on first initialization, errors if an existing DB stores a different repository ID, and atomically claims `source_instance_id` for this physical database via `UPDATE ... WHERE source_instance_id = ''` (a losing racer's generated candidate is discarded and an already-valid stored value is never overwritten), returning the typed `RepositoryMetadata { repository_id, source_instance_id }`. `source_instance_id` is generated by application code (`generate_source_instance_id()`, UUID v4) and validated with `is_valid_source_instance_id()` (non-empty once trimmed); it is never derived from `repository_id`, remote URL, checkout ID, filesystem path, hostname, or user/workspace identity, and stays stable across reopen and repeated `sce setup` runs. `RepositoryAgentTraceDb::repair_missing_repository_schema_migration_metadata()` is a narrow concurrent-first-open repair seam: it never creates trace tables, but if every required repository schema table already exists and only the one-file baseline migration record is missing, it records `001_repository_schema` and rechecks readiness. `RepositoryAgentTraceDb` exposes repository-level write helpers for the current row families by delegating to the same typed insert payloads and parameterized SQL used by the checkout-scoped adapter: `insert_diff_trace`, `insert_post_commit_patch_intersection`, `insert_agent_trace`, `insert_messages`, `insert_parts`, and `insert_conversation_text_event`. It also exposes `recent_diff_trace_patches(cutoff_time_ms, end_time_ms)` by delegating to the shared recent diff-trace query/parser helper (chronological inclusive window, no checkout filter), and `recent_diff_trace_patches_before_commit(lower_time_ms, cutoff)`, which uses the same parser with the commit-time-bounded query described in [Recent patch reads](#recent-patch-reads). These methods preserve the existing row shapes and do not add checkout provenance columns or checkout-scoped write/query APIs. @@ -91,6 +92,7 @@ SCE creates one Agent Trace DB per logical Git repository on demand through setu - `003_claude_model_state.sql` (migration ID `003_claude_model_state`) — additive `claude_model_state` table keyed by `(session_id, agent_id)`, storing `model_id`, constrained `observation_kind`, `source`, and non-negative `observed_at_ms`. The repository adapter's guarded upsert treats it as a best-effort latest-locally-observed register: older observations do not replace newer ones, equal-time `PostModelSwitch` wins over `SessionStart`, and same-kind ties use deterministic model/source ordering. This table is local attribution state outside the Agent Trace export streams and has no sync cursor. Repositories created before this migration must rerun `sce setup` so the setup lifecycle applies migration `003_claude_model_state`; hook paths do not migrate. - `004_mutation_trace_protocol`, `005_mutation_scope_provenance` (insert-once `mutation_trace_scope_provenance`) and `006_mutation_trace_health_invariant` (rebuilds the worktree/event tables with the `tainted`/`failure_kind` `CHECK`) — mutation-trace tables; see [mutation-trace-store.md](../cli/mutation-trace-store.md) and [mutation-scope-provenance.md](../cli/mutation-scope-provenance.md). - `007_commit_patch_id.sql` (migration ID `007_commit_patch_id`) — additive `ALTER TABLE agent_traces ADD COLUMN commit_patch_id TEXT`. Existing rows keep their IDs, URLs, and `trace_json` unchanged and read `commit_patch_id IS NULL`; there is no historical backfill. The column holds an optional Git patch-equivalence fingerprint for the original commit, never a unique commit identity. +- `008_claude_session_auth_state.sql` (migration ID `008_claude_session_auth_state`) — additive `claude_session_auth_state` table keyed by `session_id` with `CHECK`-constrained enum columns and no credential-bearing column (see [agent-trace-db-schema.md](agent-trace-db-schema.md)). Local attribution state outside the export streams with no sync cursor. The former checkout-scoped `AGENT_TRACE_MIGRATIONS` constant and its 15-file `cli/migrations/agent-trace/` chain (`001_create_diff_traces` … `015_add_diff_traces_payload_type`) were removed by the `retire-legacy-agent-trace-db` plan; `build.rs` auto-discovers migration directories, so deleting the directory dropped the constant on regeneration. The repository schema captures the same tables/columns/indexes/triggers that the old incremental chain produced. @@ -102,14 +104,18 @@ Repositories created before `003_claude_model_state` must rerun `sce setup` to a Repositories created before `007_commit_patch_id` must rerun `sce setup`, whose setup/lifecycle storage path falls back to `RepositoryAgentTraceDb::new_at` and applies the additive column; repeated setup is idempotent. Because hook readiness requires exact migration-ledger parity, an upgraded CLI fails open on every repository hook write and `sce doctor` reports `AgentTraceDbSchemaNotReady` until setup reruns; hooks never migrate and surface `Run 'sce setup'.` instead. Downgrade is not supported transparently: an older CLI binary sees `007_commit_patch_id` as an unexpected ledger entry and reports the schema as not ready. +### Migration-008 compatibility note + +`008_claude_session_auth_state` is the single hook-runtime-optional migration. On a pre-`008` database the hook runtime still opens and existing hook writes persist; `sce setup` applies `008` through the strict setup path, and `sce doctor` keeps reporting `AgentTraceDbSchemaNotReady` until it does. A ledger missing any other migration, or carrying an unexpected ID, is still rejected by the hook runtime. When a later migration lands, the optional constant is revisited rather than extended into a list. + The shared `TursoDb` runner records applied IDs in the database-local `__sce_migrations` table. Migration SQL is executed with `execute_batch`, so the one-file repository baseline can contain multiple statements while still recording one migration ID. Repository-scoped storage resolution first resolves `agent_trace.repository_id` / `agent_trace.repository_remote` through config, then splits by caller into two resolution paths in `agent_trace_storage`, both sharing the same identity setup and returning the same `ResolvedAgentTraceStorage { metadata: RepositoryMetadata, .. } `: - **Setup/lifecycle** (`resolve_agent_trace_storage(...)`): tries `RepositoryAgentTraceDb::open_without_migrations_at(path)` + `ensure_schema_ready_for_hooks()` + repository metadata validation first. If the repository DB has not been initialized, metadata is absent, or migrations are incomplete, it falls back to migration-running `RepositoryAgentTraceDb::new_at(path)` and validates/seeds `repository_metadata.repository_id` before returning. This is the only path that may run migration `002` (or any migration). It retries the fast-path/migration sequence for a bounded window during concurrent first opens; if another opener completed the one-file schema but the baseline migration record is missing, the repository adapter records that metadata only after verifying all required repository schema tables already exist. When the fallback also fails, the error context includes the fast-path failure reason (`(fast-path attempt: {fast_error})`) so both failure causes are visible in diagnostics. -- **Hook runtime** (`resolve_agent_trace_storage_for_hook_runtime(...)`): opens with `RepositoryAgentTraceDb::open_for_hooks_without_migrations_at(path)` and never falls back to `new_at`/migrations. If `ensure_schema_ready_for_hooks()` fails, it applies only the same narrow concurrent-first-open migration-metadata repair the setup path uses, then re-checks readiness; a missing database or a baseline-only (pre-`002`) database surfaces the existing `Run 'sce setup'.` guidance instead of migrating. Once readiness passes, it calls the same `verify_or_initialize_repository_metadata(repository_id)` to initialize `source_instance_id` when needed. That method reads the `repository_metadata` row first: when the row already holds the matching `repository_id` and a valid `source_instance_id`, it returns without any write statement, so an initialized open never needs the writer lock and succeeds while another connection holds `BEGIN IMMEDIATE`; a mismatch still errors without writing. Only a missing row or an empty/invalid `source_instance_id` runs the idempotent seed insert and atomic claim, then re-reads. `sce hooks conversation-trace`/`diff-trace`/`commit-msg` (and any other high-frequency hook caller) use this path exclusively via `open_agent_trace_db_for_hook_runtime` in `cli/src/services/hooks/mod.rs`. +- **Hook runtime** (`resolve_agent_trace_storage_for_hook_runtime(...)`): opens with `RepositoryAgentTraceDb::open_for_hooks_without_migrations_at(path)` and never falls back to `new_at`/migrations. If `ensure_schema_ready_for_hook_runtime()` fails, it applies only the same narrow concurrent-first-open migration-metadata repair the setup path uses (`repair_missing_repository_schema_migration_metadata_for_hook_runtime()`), then re-checks hook-runtime readiness; a missing database or a baseline-only (pre-`002`) database surfaces the existing `Run 'sce setup'.` guidance instead of migrating. Once readiness passes, it calls the same `verify_or_initialize_repository_metadata(repository_id)` to initialize `source_instance_id` when needed. That method reads the `repository_metadata` row first: when the row already holds the matching `repository_id` and a valid `source_instance_id`, it returns without any write statement, so an initialized open never needs the writer lock and succeeds while another connection holds `BEGIN IMMEDIATE`; a mismatch still errors without writing. Only a missing row or an empty/invalid `source_instance_id` runs the idempotent seed insert and atomic claim, then re-reads. `sce hooks conversation-trace`/`diff-trace`/`commit-msg` (and any other high-frequency hook caller) use this path exclusively via `open_agent_trace_db_for_hook_runtime` in `cli/src/services/hooks/mod.rs`. -Normal readiness for both paths is based on exact migration metadata parity with `AGENT_TRACE_REPOSITORY_MIGRATIONS`; table introspection is used only by the narrow concurrent-first-open metadata repair seam. +Setup, doctor, and the concurrent-first-open repair recheck require exact migration metadata parity with `AGENT_TRACE_REPOSITORY_MIGRATIONS`. Only the hook-runtime open path uses `ensure_schema_ready_for_hook_runtime()`, which also accepts the full ledger minus exactly `HOOK_RUNTIME_OPTIONAL_MIGRATION_ID` (`008_claude_session_auth_state`); any other missing ID or any unexpected ID still fails. Table introspection is used only by the narrow concurrent-first-open metadata repair seam. Per-table columns, lookup indexes, and `updated_at` triggers produced by the migration set are listed in [agent-trace-db-schema.md](agent-trace-db-schema.md). @@ -147,7 +153,7 @@ Post-commit intersection rows are written by the active `post-commit` hook flow - No `context/tmp` artifact is written for conversation traces. - The generated OpenCode agent-trace plugin sends mixed-batch envelopes for conversation traces with `tool_name: "opencode"`: regular `message` and `message.part` events each carry one per-item `type`, while diff-backed `message` events send one envelope containing the synthetic parent message item plus patch part items. Pi sends `tool_name: "pi"` in its message-end and synthetic patch envelopes. -`sce hooks session-model` is no longer a supported command route, generated Claude settings no longer produce `SessionStart` model-attribution events, and the Agent Trace DB adapter no longer exposes a `session_models` API or fresh-schema table. `sce hooks claude-model-state` is the separate Claude-specific lifecycle intake; it writes only the non-exported `claude_model_state` register and does not restore the generic session-model route. See [agent-trace-hooks-command-routing.md](agent-trace-hooks-command-routing.md). +`sce hooks session-model` is no longer a supported command route, generated Claude settings no longer produce `SessionStart` model-attribution events, and the Agent Trace DB adapter no longer exposes a `session_models` API or fresh-schema table. `sce hooks claude-model-state` is the separate Claude-specific lifecycle intake; it writes the non-exported `claude_model_state` register and, on every valid `SessionStart`, the local-only `claude_session_auth_state` row ([claude-session-auth-state.md](claude-session-auth-state.md#hook-integration)), and does not restore the generic session-model route. See [agent-trace-hooks-command-routing.md](agent-trace-hooks-command-routing.md). `sce hooks codex`'s `UserPromptSubmit` and `Stop` arms are each a second, independent writer into `messages` and `parts`, calling the shared `insert_conversation_text_event` atomic primitive (see above) rather than the plain `insert_messages`/`insert_parts` calls — not a Codex-specific adapter, since the primitive itself is schema-agnostic and reusable. They store `cx_`-prefixed session IDs and a deterministic `cx::user`/`cx::assistant` message ID rather than a generated UUID. Its `PostToolUse(apply_patch)` arm is likewise a second, independent writer into `diff_traces`, reusing `insert_diff_trace` with `tool_name = "codex"`, `tool_version = NULL`, and `payload_type = "patch"` — not a new adapter, and no schema migration. See [codex-integration-runtime.md](codex-integration-runtime.md). diff --git a/context/sce/agent-trace-export-readers.md b/context/sce/agent-trace-export-readers.md index 98ba01411..8a7272eb7 100644 --- a/context/sce/agent-trace-export-readers.md +++ b/context/sce/agent-trace-export-readers.md @@ -37,7 +37,7 @@ Three async methods, one per remote sync stream, sharing one shape: `(cursor: i6 SELECT ... FROM WHERE id > ?1 ORDER BY id ASC LIMIT ?2 ``` -against `messages`, `parts`, and `agent_traces` respectively (`read_messages_after`, `read_parts_after`, `read_agent_traces_after`). `diff_traces` is a local-only capture stream with no reader method. `cursor` is the last server-accepted `id` for that stream; the reader makes no gap or contiguity assumption about IDs. `claude_model_state` is local attribution state outside these three reader methods and has no reader method or sync cursor. `agent_traces.trace_json` is returned raw and unmodified — no patch parsing, no JSON reparsing. +against `messages`, `parts`, and `agent_traces` respectively (`read_messages_after`, `read_parts_after`, `read_agent_traces_after`). `diff_traces` is a local-only capture stream with no reader method. `cursor` is the last server-accepted `id` for that stream; the reader makes no gap or contiguity assumption about IDs. `claude_model_state` and `claude_session_auth_state` (see [claude-session-auth-state.md](claude-session-auth-state.md#local-only-status)) are local attribution state outside these three reader methods and have no reader method or sync cursor. `agent_traces.trace_json` is returned raw and unmodified — no patch parsing, no JSON reparsing. Every call validates, before executing any query: diff --git a/context/sce/agent-trace-hooks-command-routing.md b/context/sce/agent-trace-hooks-command-routing.md index 23dc54497..75da7608a 100644 --- a/context/sce/agent-trace-hooks-command-routing.md +++ b/context/sce/agent-trace-hooks-command-routing.md @@ -130,7 +130,7 @@ Interactive `sce setup` persists the independent confirmations at `agent_trace.a - Current valid-payload success output reports deterministic mixed-batch accounting: `conversation-trace hook persisted mixed payload batch to AgentTraceDb: attempted=, persisted_messages=, persisted_parts=, skipped=.` The hook does not persist `context/tmp` artifacts. - Fail-open output for conversation-trace intake failures is `conversation-trace hook intake failed open; error logged.` so hook callers do not receive app-level classified errors or non-zero exits for intake failures. - The generated OpenCode agent-trace plugin emits this mixed-batch shape for conversation-trace handoff with `tool_name: "opencode"`: ordinary message/part events produce one-item mixed envelopes, completed question-tool parts produce `message.part` items with `part_type: "question"`, and diff-backed message events produce one envelope containing the synthetic parent `message` item plus patch `message.part` items. The Pi extension uses the same shape with `tool_name: "pi"`. -- `sce hooks claude-model-state` is a local-only lifecycle intake for raw Claude `SessionStart` and `PostModelSwitch` events. It is silent; the Claude session login notice is owned by the `sce-info` hooks module ([access policy: enforcement](../cli/access-policy.md#enforcement)). A model-bearing `SessionStart` writes normalized `claude/` state, while a `PostModelSwitch` validates `from_model` and `to_model` but writes normalized `to_model`; both use canonical `cc_` plus exact optional `agent_id` scope (`""` for the main conversation). Missing or null `agent_id` means the main scope; a present string is trimmed and must remain non-empty, so malformed empty or non-string values fail open without a state write. Current Claude sources include `command`, `picker`, `sdk`, `auto`, and `resume`; SCE accepts any non-empty source string and stores it opaquely. A model-less `SessionStart` first attempts bounded, local-only bridge-session correlation through the event's `transcript_path`: it reads only leading records for the `bridgeSessionId`, then resolves the model through the same single newest-chain-observation selection rule the `diff-trace` state-miss path uses — bounded leading-record reads of sibling `.jsonl` transcripts sharing that `bridgeSessionId`, one exact-scope `(cc_, "")` read per member, winner by greatest `observed_at_ms` with a deterministic session-ID tie-break — and seeds the current session with that model as `source="bridge_inherited"` when a chain observation exists. There is no separate SessionStart selection rule and no most-recently-modified-sibling pick. Missing or malformed discovery inputs, no chain observation, filesystem races, and DB reads fail open to the existing no-op. In practice this `SessionStart` attempt fires before Claude has created the session's transcript file, so it reads nothing and always no-ops; bridge inheritance for a cleared session is actually carried by the `diff-trace` state-miss path above, and this attempt is kept only for the case Claude ever creates transcripts eagerly. The command uses the existing guarded latest-locally-observed register and local SCE observation time. The command reads and writes directly through the no-migration hook-runtime repository DB path before returning, does not migrate, sync, or access the network, and returns zero stdout bytes with logger-only fail-open diagnostics for input, clock, DB-open, DB-read, and DB-write failures. Claude's SessionStart invocation is synchronous relative to Claude execution, while PostModelSwitch is asynchronous; overlapping hooks and bridge/model-switch races are accepted and local observation time does not prove Claude causal ordering. Generated Claude settings register both lifecycle events for this command, while the existing five SCE registrations remain unchanged. Claude Code 2.1.250 and 2.1.251 compatibility smoke passed with an unknown PostModelSwitch registration, so installation remains unconditional with no raised minimum or capability gate. +- `sce hooks claude-model-state` is a local-only lifecycle intake for raw Claude `SessionStart` and `PostModelSwitch` events. It is silent; the Claude session login notice is owned by the `sce-info` hooks module ([access policy: enforcement](../cli/access-policy.md#enforcement)). A model-bearing `SessionStart` writes normalized `claude/` state, while a `PostModelSwitch` validates `from_model` and `to_model` but writes normalized `to_model`; both use canonical `cc_` plus exact optional `agent_id` scope (`""` for the main conversation). Missing or null `agent_id` means the main scope; a present string is trimmed and must remain non-empty, so malformed empty or non-string values fail open without a state write. Current Claude sources include `command`, `picker`, `sdk`, `auto`, and `resume`; SCE accepts any non-empty source string and stores it opaquely. A model-less `SessionStart` first attempts bounded, local-only bridge-session correlation through the event's `transcript_path`: it reads only leading records for the `bridgeSessionId`, then resolves the model through the same single newest-chain-observation selection rule the `diff-trace` state-miss path uses — bounded leading-record reads of sibling `.jsonl` transcripts sharing that `bridgeSessionId`, one exact-scope `(cc_, "")` read per member, winner by greatest `observed_at_ms` with a deterministic session-ID tie-break — and seeds the current session with that model as `source="bridge_inherited"` when a chain observation exists. There is no separate SessionStart selection rule and no most-recently-modified-sibling pick. Missing or malformed discovery inputs, no chain observation, filesystem races, and DB reads fail open to the existing no-op. In practice this `SessionStart` attempt fires before Claude has created the session's transcript file, so it reads nothing and always no-ops; bridge inheritance for a cleared session is actually carried by the `diff-trace` state-miss path above, and this attempt is kept only for the case Claude ever creates transcripts eagerly. The command uses the existing guarded latest-locally-observed register and local SCE observation time. Independently of model state, every valid `SessionStart` (any source, with or without `model`) also classifies the inherited environment's Claude auth configuration and upserts it under `cc_` in the local-only `claude_session_auth_state` table; `PostModelSwitch` is ignored for auth, and an auth write failure is logged under its own fail-open event without affecting the model-state write (see [claude-session-auth-state.md](claude-session-auth-state.md#hook-integration)). The command reads and writes directly through the no-migration hook-runtime repository DB path before returning, does not migrate, sync, or access the network, and returns zero stdout bytes with logger-only fail-open diagnostics for input, clock, DB-open, DB-read, and DB-write failures. Claude's SessionStart invocation is synchronous relative to Claude execution, while PostModelSwitch is asynchronous; overlapping hooks and bridge/model-switch races are accepted and local observation time does not prove Claude causal ordering. Generated Claude settings register both lifecycle events for this command, while the existing five SCE registrations remain unchanged. Claude Code 2.1.250 and 2.1.251 compatibility smoke passed with an unknown PostModelSwitch registration, so installation remains unconditional with no raised minimum or capability gate. - `session-model` is no longer a supported `sce hooks` subcommand and generated Claude settings no longer produce the retired generic session-model route. The `session_models` DB API/table and generic fallback are removed from active code; upgraded databases may still contain the retired table, but runtime paths no longer read or write it. The separate `sce hooks claude-model-state` command is a Claude-specific local register, and `diff-trace` consults its exact `(cc_, agent_id)` state after direct and transcript attribution fail, then — for a main-session-scope raw structured payload only — the newest observation across the transcript's bridge-linked chain, seeding a `source="bridge_inherited"` row for the current session; this remains Claude-specific and does not restore the generic abstraction. - `sce hooks codex` is a separate single dispatcher subcommand (not routed through `diff-trace`/`conversation-trace`), classifying raw Codex hook JSON internally instead. Its `UserPromptSubmit` and `Stop` arms are each a second writer into the same `messages`/`parts` tables, calling the shared `insert_conversation_text_event` atomic primitive rather than the plain `insert_messages`/`insert_parts` calls described above. Its `PostToolUse(apply_patch)` arm is a second, independent writer into `diff_traces` via the existing `insert_diff_trace`, carrying `tool_name = "codex"` and the same `cx_`-prefixed `session_id`; it is independent of the concrete Codex mutation-scope adapter. Apply_patch persistence requires a trimmed non-empty session, preserves reported model IDs without fabricating a provider prefix, and returns empty stdout on every non-policy success or fail-open path. Before persistence it resolves source and move-destination paths independently from the event `cwd` against the canonical Git root: valid `..` components and absolute-inside paths are accepted, missing Add File targets are allowed through their nearest existing prefix, and outside or symlink-escaping mappings are rejected. The existing Codex command resolves that Git root at invocation time and invokes the installed helper with quoted paths, so root and nested cwd (including spaced repository paths) share one entrypoint; its root-resolution failure remains silent and fail-open where designed. The Codex setup/doctor boundary is separate from evidence intake: `.codex/hooks.json` is merged through the shared structural `codex_hook_config` service, which preserves valid user handlers and recognizes the generated helper path plus either the `sce hooks codex` or `sce hooks codex-mutation-scope` command contract, attributing each handler to whichever it matches and merging the two contracts' registrations independently. The mutation-scope `PreToolUse`/`PostToolUse` registrations use matcher `^(Bash|apply_patch)$`; `Stop`/`Interrupt`/`SubagentStop`/`SessionEnd` are unmatched and feed the generic mutation-scope ingress ([../cli/mutation-scope-hook-ingress.md](../cli/mutation-scope-hook-ingress.md)). - `sce hooks mutation-scope` (hidden) is a separate single ingress (not routed through `diff-trace`/`conversation-trace`) that drives the mutation-scope runtime rather than writing conversation/diff evidence. It reads one normalized JSON lifecycle object from STDIN via the shared `read_hook_stdin`, strictly parses it into exactly `start`/`advance`/`close`/`flush`/`abandon`, and translates it into one `RuntimeBoundary` (`start`/`advance`/`close` → `Start`/`Advance`/`Close`; `flush` → `Flush`) passed to `mutation_trace::runtime::coordinate(...)`, or a direct `mutation_trace::runtime::abandon_scope(...)` call for `abandon`. `scope_id`/`event_id`/`actor_kind` (`claude_code`/`codex`/`opencode`/`pi`) are forwarded verbatim — no trim, prefix, hash, UUID, or timestamp — because `EventId` equality is the runtime's replay/idempotency key; `start` alone additionally accepts an optional `provenance` object (non-blank `session_id`, optional `model_id`) forwarded the same way as `RuntimeBoundary::Start`'s `StartProvenance` and, when the runtime's admission-bounded rule allows it, durably registered before the protocol commits — a row may only be created while the durable scope is still `NeverSeen`, so a `start` replayed against an already-admitted scope that has no provenance still succeeds and still persists none, while an existing row is validated on every provenance-carrying `start` and a differing `session_id` remains a hard conflict — while `advance`/`close`/`flush`/`abandon` reject the key; any `worktree_id` key is a hard rejection (worktree identity is derived by the runtime from the invoking checkout). DB acquisition is lazy: a `FnOnce` provider closure reusing `open_agent_trace_db_for_hook_runtime` is passed into `coordinate()`/`abandon_scope()` so it runs inside the runtime's protected-worktree ordering, never before. **Non-fail-open intake contract, distinct from `diff-trace`/`conversation-trace`:** a lost lifecycle boundary can change which scope stays live and therefore alter attribution, so the dispatch arm is unwrapped like `pre-commit` (no `Ok(...)` fail-open shim) and there is no dropped-boundary / `exit 0` branch. Results are classified by durable completion — a malformed payload or any pre-completion `CoordinateError`/`AbandonScopeError` returns `CliError`/non-zero; `CoordinateError::MarkerClearAfterCommit` and `AbandonScopeError::MarkerClearAfterCompletion` are the two carried-outcome success variants (the durable transition already succeeded and only the trailing external-taint marker cleanup failed), reported as empty-stdout `Ok` with the failure logged via `sce.hooks.mutation_scope.marker_clear_after_durable_completion` and the transition **not** retried. Every successful execution emits empty stdout with no serialized outcome/revision/worktree/scope state. It writes `mutation_trace_*` rows only — never `diff_traces`, `post_commit_patch_intersections`, or `agent_traces`. A first Claude Code adapter driver now consumes it in-process (see below); the Codex adapter also consumes it in-process, while OpenCode and Pi still have no lifecycle adapter. See [mutation-scope-hook-ingress.md](../cli/mutation-scope-hook-ingress.md) for the full contract. diff --git a/context/sce/claude-session-auth-state.md b/context/sce/claude-session-auth-state.md new file mode 100644 index 000000000..9be8611f0 --- /dev/null +++ b/context/sce/claude-session-auth-state.md @@ -0,0 +1,155 @@ +# Claude Session Auth State + +## Status + +The pure detector lives in `cli/src/services/hooks/claude_auth_detection.rs` +(`pub(crate)`). Migration `008_claude_session_auth_state` and a typed +persistence interface on `RepositoryAgentTraceDb` back it (see +[Persistence](#persistence)), and `sce hooks claude-model-state` writes the +classification on every valid `SessionStart` (see +[Hook integration](#hook-integration)). The latest-state read +`claude_session_auth_state_by_session` has no production reader, so it keeps +`#[cfg_attr(not(test), expect(dead_code, ...))]`. The data stays local; no +export reader or `sce sync` path reads it. +Plan: [`claude-auth-billing-observations`](../plans/claude-auth-billing-observations.md). + +## Detector + +`detect_claude_auth(ClaudeAuthSignals) -> ClaudeAuthDetection` is pure and +deterministic. It classifies Claude Code's *configured* authentication from the +presence of documented environment variables. + +- `ClaudeAuthSignals` holds only presence booleans and never stores values. + `ClaudeAuthSignals::from_env_lookup(Fn(&str) -> Option)` builds it and + drops each looked-up value right after its check, so tests inject a closure + instead of changing the process environment. +- A cloud flag (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, + `CLAUDE_CODE_USE_FOUNDRY`) counts only when it is `1` or `true` (any case, + trimmed). +- A credential variable (`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, + `CLAUDE_CODE_OAUTH_TOKEN`) counts when it is present and non-blank. +- `ANTHROPIC_BASE_URL` counts as a custom gateway when it is non-blank and not + `https://api.anthropic.com`. The comparison trims whitespace, strips a trailing + `/`, and ignores case. The base URL feeds classification but is not a + credential, so it has no `AuthEnvKey` variant. + +### Precedence and classification + +Cloud flags are checked first, then `ANTHROPIC_AUTH_TOKEN`, then `ANTHROPIC_API_KEY`, +then `CLAUDE_CODE_OAUTH_TOKEN`. Credentials from interactive `/login` cannot be +observed. + +| Selected signal | Provider | Billing mode | Auth env key | +|---|---|---|---| +| `CLAUDE_CODE_USE_BEDROCK` | `aws_bedrock` | `cloud_provider` | `claude_code_use_bedrock` | +| `CLAUDE_CODE_USE_VERTEX` | `google_vertex` | `cloud_provider` | `claude_code_use_vertex` | +| `CLAUDE_CODE_USE_FOUNDRY` | `microsoft_foundry` | `cloud_provider` | `claude_code_use_foundry` | +| `ANTHROPIC_AUTH_TOKEN`, default base URL | `anthropic` | `unknown` | `anthropic_auth_token` | +| `ANTHROPIC_AUTH_TOKEN`, custom base URL | `custom_gateway` | `unknown` | `anthropic_auth_token` | +| `ANTHROPIC_API_KEY`, default base URL | `anthropic` | `api_key` | `anthropic_api_key` | +| `ANTHROPIC_API_KEY`, custom base URL | `custom_gateway` | `unknown` | `anthropic_api_key` | +| `CLAUDE_CODE_OAUTH_TOKEN` | `anthropic` | `unknown` | `claude_code_oauth_token` | +| No signal, or more than one cloud flag | `unknown` | `unknown` | none | + +Every recognized signal yields confidence `inferred`. No signal, or a provider +conflict, yields confidence `unknown`. The strings shown are the stable +`as_str`/`from_str` mappings of `AuthProvider`, `BillingMode`, `AuthEnvKey`, and +`DetectionConfidence`. `from_str` rejects any other value. + +## Configuration is not billing + +Environment variables describe how authentication is configured. They do not +prove that authentication succeeded or show what is actually billed. + +- `ANTHROPIC_AUTH_TOKEN` may authenticate against a proxy or gateway, so it + never implies `api_key` billing. +- OAuth never implies a paid subscription. `BillingMode::Subscription` exists as + a valid stored value, but the detector never returns it. +- `DetectionConfidence` has no verified level, because none of the permitted + inputs can verify authentication. + +## Limitations + +- Interactive `/login` users with no environment signal always classify as + `unknown`, because the detector does not read credential files, the keychain, + or settings. +- `apiKeyHelper` is configured in settings rather than the environment, so the + detector cannot see it. + +## Persistence + +`cli/src/services/agent_trace_db/` stores one latest-state row per canonical +`cc_` in `claude_session_auth_state`. The columns are listed in +[agent-trace-db-schema.md](agent-trace-db-schema.md). + +- `ClaudeSessionAuthState` holds the session ID, the four detector enums + (`auth_env_key` optional), and `observed_at_ms`. It has no field that can + hold a credential value. Enums are mapped to strings only at the SQL boundary. +- `RepositoryAgentTraceDb::upsert_claude_session_auth_state` first looks up + `008_claude_session_auth_state` in the `__sce_migrations` ledger. If it is + absent, it returns `ClaudeSessionAuthStateUpsertOutcome::SkippedMissingMigration` + without writing. This is the counterpart of the hook-runtime readiness that + tolerates a pre-`008` ledger (see + [agent-trace-db.md](agent-trace-db.md#migration-008-compatibility-note)). +- Otherwise it runs one `INSERT ... ON CONFLICT (session_id) DO UPDATE ... WHERE` + statement that changes the row only when `provider`, `billing_mode`, + `confidence`, or `auth_env_key` (compared null-safely with `IS NOT`) differs. + There is no explicit transaction and no read of the row first. It returns + `Upserted { rows_changed }`, where `0` means an identical replay that left the + row untouched. So `observed_at_ms` is when the current classification was + first seen. A changed classification updates the row in place, and no history + is kept. +- `claude_session_auth_state_by_session(session_id)` returns the exact session's + typed row or `None`. Parsing uses the detector `from_str` mappings, so an + unknown stored value is an error, not a silent fallback. + +## Hook integration + +`cli/src/services/hooks/claude_model_state.rs` stores the classification from +the existing `sce hooks claude-model-state` hook. No hook registration was +added. + +- Every valid `SessionStart` (any `source`, with or without `model`) is an auth + candidate. The payload parse that already produces the model observation also + returns the canonical `cc_` from `prefixed_diff_trace_session_id`. + A `SessionStart` missing `session_id` or `source` fails open with no writes. +- `PostModelSwitch` and other events never produce an auth candidate. +- The hook classifies the environment it inherits from Claude Code, through + `ClaudeAuthSignals::from_env_lookup(std::env::var)`. Tests inject a lookup + closure into `run_claude_model_state_from_payload_with`. The row's + `observed_at_ms` is the hook's observation time. +- The hook opens the DB through the no-migration hook-runtime path when an auth + candidate, a model observation, or a bridge candidate exists, so a model-less + `SessionStart` now opens it. +- Model-state persistence and the auth upsert run independently, so a failure in + one does not affect the other. An auth write failure logs + `sce.hooks.claude_model_state.auth_state_agent_trace_db_write_failed` with only + the canonical session ID and the error. On a pre-`008` ledger the upsert skips + silently. +- Stdout stays empty on every path. Credential values are never stored, logged, + or printed, because only presence reaches the detector. + +## Migration-008 compatibility + +`008_claude_session_auth_state` is the only migration the hook runtime tolerates +as missing (`HOOK_RUNTIME_OPTIONAL_MIGRATION_ID` in +`cli/src/services/agent_trace_db/repository.rs`). + +- On a pre-`008` database, `ensure_schema_ready_for_hook_runtime` still passes, + so existing hooks (`claude-model-state` model writes, `diff-trace`, + `conversation-trace`) keep persisting, and the auth upsert returns + `SkippedMissingMigration`. +- `sce setup` applies `008` through the strict setup path. `sce doctor` and the + concurrent-first-open repair recheck keep strict ledger parity, so doctor + reports `AgentTraceDbSchemaNotReady` until setup reruns. +- A ledger missing any other migration, or carrying an unexpected ID, is still + rejected by the hook runtime. + +See [agent-trace-db.md](agent-trace-db.md#migration-008-compatibility-note). + +## Local-only status + +The table is local attribution state. `AgentTraceExportReader` has no method +for it, `sce sync` does not send it, and no control-plane or warehouse code +reads it. Exporting it is unplanned follow-up work for a future `sce sync` or +warehouse change; this document does not define its route, cursor, or schema.