Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
//! Registered local Agent discovery with diagnostic-only executable versions.
//!
//! The public result contains only registered non-secret facts and an opaque discovery
//! descriptor. Secret bytes stay in a zeroizing value and can be reread only through the exact
//! descriptor during Preview/Apply.
use std::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf};
use hiroute_domain::{
AgentConfigDocumentV1, AgentKindV1, CanonicalDigest, ConfigLayerV1, ProtectedSecret,
SupportedAgentInstallationV1,
};
use serde::{Deserialize, Serialize};
use serde_json::json;
use thiserror::Error;
use zeroize::Zeroizing;
use super::executable::{ExecutableObservationV1, ExecutableProbe, executable_probe};
use super::filesystem_config::{
CLAUDE_AUTH_ENVIRONMENT_FIELDS, ClaudeSettingsSubset, ClaudeSource, ObservedClaudeSettings,
claude_user_change_is_applied, managed_settings_paths, render_claude_user_change,
same_layer_secret_conflict,
};
use super::managed_launch::ManagedClaudeLaunchPreflightV1;
use super::registration::ClaudeRegistrationIndexV1;
use super::{
AGENT_SCAN_OBSERVATION_SCHEMA_V1, AgentDiscoveryOutcomeV1, AgentReportOnlyReasonV1,
AgentScanObservationV1, ConfigObservationV1, resolve_agent_observation,
};
#[path = "filesystem/claude_settings.rs"]
mod claude_settings;
#[path = "dsh_native.rs"]
mod dsh_native;
#[path = "claude_observation.rs"]
mod main_observation;
#[path = "opencode_scanner.rs"]
mod opencode_scanner;
#[path = "pi_native.rs"]
mod pi_native;
#[path = "qoder_discovery.rs"]
mod qoder_discovery;
pub use pi_native::PiDefaultModel;
#[path = "settings_discovery.rs"]
mod settings_discovery;
pub const FILESYSTEM_AGENT_SCANNER_ID_V1: &str = "builtin.agent-filesystem";
pub const FILESYSTEM_AGENT_SCANNER_VERSION_V1: &str = "1";
/// Opaque, non-secret source descriptor safe for Preview output and change-digest binding.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DiscoveredCredentialRefV1 {
pub source: String,
pub scanner_id: String,
pub scanner_version: String,
pub discovered_source_ref: String,
pub field_selector: String,
pub observed_revision: u64,
}
/// Registry-projected Claude configuration. The URL and model are emitted only after exact
/// Connector Registry and ModelData matching.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RegisteredClaudeConfigurationV1 {
pub connection_option_id: String,
pub endpoint_profile_id: String,
pub endpoint_profile_revision: u64,
#[serde(skip_serializing_if = "Option::is_none")]
pub model_configuration_id: Option<String>,
pub base_url: String,
pub observed_model_id: String,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub provider_model_alias_hints: BTreeMap<String, String>,
pub configuration_revision: u64,
}
/// Content-free remediation fact for an owner file whose group/other bits are too broad. The
/// source reference is resolved only inside the scanner; no filesystem path or file bytes cross
/// the Local Control boundary.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PermissionHardeningRequiredV1 {
pub scanner_id: String,
pub scanner_version: String,
pub discovered_source_ref: String,
pub observed_identity: CanonicalDigest,
pub observed_revision: u64,
pub display_path: String,
pub required_mode: u32,
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PermissionHardeningOutcomeV1 {
Hardened,
AlreadyHardened,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FilesystemAgentDiscoveryV1 {
pub outcome: AgentDiscoveryOutcomeV1,
/// Independent, redacted configuration facet. Executable trust remains authoritative for
/// `outcome`; a safe read-only configuration can still be recognized when execution is
/// unavailable or untrusted.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub configuration_issue: Option<AgentReportOnlyReasonV1>,
#[serde(skip_serializing_if = "Option::is_none")]
pub claude_configuration: Option<RegisteredClaudeConfigurationV1>,
#[serde(skip_serializing_if = "Option::is_none")]
pub discovered_credential: Option<DiscoveredCredentialRefV1>,
#[serde(skip_serializing_if = "Option::is_none")]
pub permission_hardening: Option<PermissionHardeningRequiredV1>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub managed_launch: Option<ManagedClaudeLaunchPreflightV1>,
}
/// Exact local paths and the three explicitly registered process variables. This value is not
/// serializable or Debug so a process token cannot accidentally enter diagnostics.
#[derive(Clone)]
pub struct AgentFilesystemLayoutV1 {
/// Separately installed CLI target. Desktop checks never substitute this path for the
/// application-owned engine selected by the native host.
pub codex_executable: PathBuf,
/// Codex Desktop's application-owned engine, supplied by the native host after resolving the
/// installed bundle through the operating system. `None` means that surface is unavailable.
pub codex_desktop_executable: Option<PathBuf>,
pub claude_executable: PathBuf,
pub qoder_executable: PathBuf,
pub pi_executable: PathBuf,
pub pi_config_root: PathBuf,
pub opencode_executable: PathBuf,
pub opencode_context: Option<super::OpenCodeNativeContext>,
pub dsh_executable: PathBuf,
pub dsh_config_root: PathBuf,
pub qoder_home: PathBuf,
pub qoder_config_root: PathBuf,
pub codex_user_config: PathBuf,
/// Subscription discovery only; never changes native settings or Worker history.
pub codex_subscription_auth_override: Option<PathBuf>,
pub claude_launch_settings: Option<PathBuf>,
pub claude_project_settings: Vec<PathBuf>,
pub claude_user_settings: PathBuf,
pub claude_managed_settings: Vec<PathBuf>,
process_environment: BTreeMap<String, Zeroizing<String>>,
process_environment_presence: BTreeSet<String>,
}
impl AgentFilesystemLayoutV1 {
pub fn from_process(home: &Path, project: &Path) -> Self {
let claude_home = std::env::var_os("CLAUDE_CONFIG_DIR")
.filter(|value| !value.is_empty())
.map(PathBuf::from)
.unwrap_or_else(|| home.join(".claude"));
let process_environment = [
"ANTHROPIC_BASE_URL",
"ANTHROPIC_MODEL",
"ANTHROPIC_DEFAULT_OPUS_MODEL",
"ANTHROPIC_DEFAULT_SONNET_MODEL",
"ANTHROPIC_DEFAULT_HAIKU_MODEL",
"ANTHROPIC_SMALL_FAST_MODEL",
]
.into_iter()
.chain(hiroute_domain::CLAUDE_CONTEXT_CONFLICT_ENVIRONMENT)
.filter_map(|name| {
std::env::var(name)
.ok()
.map(|value| (name.to_owned(), Zeroizing::new(value)))
})
.collect();
let process_environment_presence = hiroute_domain::MANAGED_CLAUDE_ENVIRONMENT_REMOVALS_V1
.into_iter()
.filter(|name| std::env::var_os(name).is_some())
.map(str::to_owned)
.collect();
Self {
codex_executable: PathBuf::from("codex"),
codex_desktop_executable: None,
claude_executable: PathBuf::from("claude"),
qoder_executable: PathBuf::from("qoder"),
pi_executable: PathBuf::from("pi"),
dsh_executable: PathBuf::from("dsh"),
opencode_executable: PathBuf::from("opencode"),
opencode_context: super::OpenCodeNativeContext::from_environment(home).ok(),
dsh_config_root: std::env::var_os("DSH_HOME")
.filter(|v| !v.is_empty())
.map(PathBuf::from)
.unwrap_or_else(|| home.join(".dsh")),
pi_config_root: std::env::var_os("PI_CODING_AGENT_DIR")
.filter(|v| !v.is_empty())
.map(PathBuf::from)
.unwrap_or_else(|| home.join(".pi/agent")),
qoder_home: home.to_owned(),
qoder_config_root: std::env::var_os("QODER_CONFIG_DIR")
.filter(|value| !value.is_empty())
.map(PathBuf::from)
.unwrap_or_else(|| home.join(".qoder")),
codex_user_config: codex_config_path(home, std::env::var_os("CODEX_HOME").as_deref()),
codex_subscription_auth_override: std::env::var_os("HIROUTE_CODEX_AUTH_SOURCE")
.map(PathBuf::from),
claude_launch_settings: None,
claude_project_settings: vec![
project.join(".claude/settings.local.json"),
project.join(".claude/settings.json"),
],
claude_user_settings: claude_home.join("settings.json"),
claude_managed_settings: managed_settings_paths(),
process_environment,
process_environment_presence,
}
}
#[cfg(test)]
fn with_process_value(mut self, name: &str, value: &str) -> Self {
self.process_environment
.insert(name.to_owned(), Zeroizing::new(value.to_owned()));
self.process_environment_presence.insert(name.to_owned());
self
}
}
#[derive(Clone)]
pub struct FilesystemAgentScannerV1 {
pi_collaboration_cli:
std::sync::Arc<std::sync::Mutex<Option<(PathBuf, hiroute_domain::CanonicalDigest)>>>,
dsh_collaboration_cli: std::sync::Arc<std::sync::Mutex<Option<(PathBuf, CanonicalDigest)>>>,
pub(super) layout: AgentFilesystemLayoutV1,
opencode_model_target: PathBuf,
registry: ClaudeRegistrationIndexV1,
legacy_recovery_version: Option<String>,
legacy_process_format: bool,
#[cfg(any(unix, windows))]
codex_ingress: std::sync::Arc<std::sync::Mutex<Option<super::CodexIngressEvidence>>>,
#[cfg(any(unix, windows))]
claude_ingress: std::sync::Arc<std::sync::Mutex<Option<super::ClaudeIngressEvidence>>>,
#[cfg(any(unix, windows))]
opencode_collaboration: std::sync::Arc<std::sync::Mutex<super::opencode_probe::ProofCache>>,
#[cfg(any(unix, windows))]
qoder_collaboration: std::sync::Arc<std::sync::Mutex<super::qoder_probe::QoderProofCache>>,
}
impl FilesystemAgentScannerV1 {
fn located_codex_engine(&self) -> Result<Option<PathBuf>, super::executable::ProbeFailure> {
let mut first_failure = None;
for candidate in self
.layout
.codex_desktop_executable
.iter()
.chain(std::iter::once(&self.layout.codex_executable))
{
match super::executable::resolve(candidate) {
Ok(Some(path)) => return Ok(Some(path)),
Ok(None) => {}
Err(error) => {
first_failure.get_or_insert(error);
}
};
}
match first_failure {
Some(error) => Err(error),
None => Ok(None),
}
}
pub(super) fn claude_observations(
&self,
) -> Result<Vec<ObservedClaudeSettings>, AgentFilesystemScanError> {
let observations = self
.claude_sources()
.iter()
.map(|source| {
source.read(
&self.layout.process_environment,
&self.layout.process_environment_presence,
)
})
.collect::<Result<Vec<_>, _>>()?;
Ok(main_observation::resolve_project_local_fields(
&self.layout,
&observations,
))
}
pub fn new(mut layout: AgentFilesystemLayoutV1, registry: ClaudeRegistrationIndexV1) -> Self {
layout.codex_user_config = super::canonical_codex_config_path(&layout.codex_user_config);
let opencode_model_target = layout
.opencode_context
.as_ref()
.map(|context| context.model_target())
.unwrap_or_default();
Self {
layout,
opencode_model_target,
registry,
legacy_recovery_version: None,
legacy_process_format: false,
#[cfg(any(unix, windows))]
codex_ingress: Default::default(),
#[cfg(any(unix, windows))]
claude_ingress: Default::default(),
#[cfg(any(unix, windows))]
qoder_collaboration: Default::default(),
#[cfg(any(unix, windows))]
opencode_collaboration: Default::default(),
pi_collaboration_cli: Default::default(),
dsh_collaboration_cli: Default::default(),
}
}
/// Attach backend evidence from an explicit native check whose file effect was restored.
/// Scanning remains read-only; an expired/changed binary automatically loses this evidence.
#[cfg(any(unix, windows))]
pub fn with_codex_ingress_evidence(mut self, evidence: super::CodexIngressEvidence) -> Self {
self.codex_ingress = std::sync::Arc::new(std::sync::Mutex::new(Some(evidence)));
self
}
/// Only an explicitly admitted check calls this; discovery never performs the challenge.
#[cfg(any(unix, windows))]
pub fn check_codex_native_authentication(&self) -> Result<(), super::NativeIngressProbeError> {
let engine = self
.located_codex_engine()
.map_err(|_| super::native_ingress_probe::fail("Codex engine location"))?
.ok_or_else(|| super::native_ingress_probe::fail("Codex engine location"))?;
let evidence = super::CodexNativeIngressProbe::bind()?.run_ephemeral(&engine)?;
let mut cache = self
.codex_ingress
.lock()
.map_err(|_| super::native_ingress_probe::cache_error())?;
*cache = Some(evidence);
Ok(())
}
/// Only an explicitly admitted check calls this; discovery never launches Claude.
#[cfg(any(unix, windows))]
pub fn check_claude_native_authentication(&self) -> Result<(), super::NativeIngressProbeError> {
let evidence = super::ClaudeNativeIngressProbe::run(&self.layout.claude_executable)?;
let mut cache = self
.claude_ingress
.lock()
.map_err(|_| super::native_ingress_probe::cache_error())?;
*cache = Some(evidence);
Ok(())
}
#[cfg(any(unix, windows))]
pub fn check_codex_collaboration(
&self,
cli: &std::path::Path,
) -> Result<(), super::NativeIngressProbeError> {
let evidence = super::CodexNativeIngressProbe::bind()?
.run_collaboration(&self.layout.codex_executable, cli)?;
*self
.codex_ingress
.lock()
.map_err(|_| super::native_ingress_probe::cache_error())? = Some(evidence);
Ok(())
}
#[cfg(any(unix, windows))]
pub fn check_claude_collaboration(
&self,
cli: &std::path::Path,
) -> Result<(), super::NativeIngressProbeError> {
let evidence = super::ClaudeNativeIngressProbe::run_collaboration(
&self.layout.claude_executable,
cli,
)?;
*self
.claude_ingress
.lock()
.map_err(|_| super::native_ingress_probe::cache_error())? = Some(evidence);
Ok(())
}
#[cfg(any(unix, windows))]
pub fn attach_claude_collaboration_evidence(
&self,
executable: &std::path::Path,
installation: &mut SupportedAgentInstallationV1,
) {
if let Ok(cache) = self.claude_ingress.lock()
&& let Some(evidence) = cache.as_ref()
{
evidence.attach_collaboration(executable, installation);
}
}
/// Read-only verifier for a pre-version-neutral successful Operation. The old label is
/// supplied by that immutable Operation, never by current client output. All physical
/// identity, permissions, configuration and native evidence are still sampled normally.
pub fn matches_legacy_claude_observation(
&self,
recorded_version: &str,
expected: &CanonicalDigest,
) -> bool {
let mut recovery = self.clone();
recovery.legacy_recovery_version = Some(recorded_version.to_owned());
[false, true].into_iter().any(|legacy_process_format| {
recovery.legacy_process_format = legacy_process_format;
recovery.scan().into_iter().any(|found| {
matches!(found.outcome, AgentDiscoveryOutcomeV1::Supported { installation }
if installation.profile.kind == AgentKindV1::ClaudeCode && &installation.observation_digest == expected)
&& found.managed_launch.is_some_and(|preflight| preflight.is_launchable())
})
})
}
pub fn scan(&self) -> Vec<FilesystemAgentDiscoveryV1> {
let mut results = vec![
self.scan_codex(),
self.qoder_settings_discovery(false),
self.pi_settings_discovery(),
self.dsh_settings_discovery(),
self.opencode_settings_discovery(),
];
match executable_probe(&self.layout.claude_executable) {
ExecutableProbe::Installed(executable) => {
results.push(self.scan_claude(Some(executable), None, false));
}
other => {
let report = probe_report("agent_claude_default", AgentKindV1::ClaudeCode, other);
results.push(self.scan_claude(None, Some(report.outcome), false));
}
}
results.sort_by(|left, right| {
outcome_agent_id(&left.outcome).cmp(outcome_agent_id(&right.outcome))
});
for result in &mut results {
if let AgentDiscoveryOutcomeV1::Supported { installation } = &mut result.outcome {
let binary = match installation.profile.kind {
AgentKindV1::Codex => {
super::observed_capabilities::attach_target_file_capabilities(
installation,
&self.layout.codex_user_config,
);
self.located_codex_engine()
.ok()
.flatten()
.unwrap_or_else(|| self.layout.codex_executable.clone())
}
AgentKindV1::ClaudeCode => {
super::observed_capabilities::attach_file_capabilities(
installation,
&self.layout.claude_executable,
&self.layout.claude_user_settings,
);
self.layout.claude_executable.clone()
}
AgentKindV1::Qoder
| AgentKindV1::Pi
| AgentKindV1::DeepseekHarness
| AgentKindV1::OpenCode
| AgentKindV1::Hermes => continue,
};
#[cfg(any(unix, windows))]
if installation.profile.kind == AgentKindV1::Codex
&& let Ok(cache) = self.codex_ingress.lock()
&& let Some(evidence) = cache.as_ref()
{
evidence.attach(installation);
}
#[cfg(any(unix, windows))]
if installation.profile.kind == AgentKindV1::ClaudeCode
&& let Ok(cache) = self.claude_ingress.lock()
&& let Some(evidence) = cache.as_ref()
{
evidence.attach(&binary, installation);
}
}
}
results
}
fn scan_codex(&self) -> FilesystemAgentDiscoveryV1 {
match self.located_codex_engine() {
Ok(Some(_)) => {
let mut observation = base_observation(
"agent_codex_default",
AgentKindV1::Codex,
"not-probed".to_owned(),
);
match super::sample_codex_configuration(&super::CodexConfigurationScope::user_file(
self.layout.codex_user_config.clone(),
)) {
Ok(sample) => {
observation.config = sample.observations;
FilesystemAgentDiscoveryV1 {
outcome: resolve_agent_observation(observation),
configuration_issue: None,
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch: None,
}
}
Err(error) => report_only_agent(
"agent_codex_default",
AgentKindV1::Codex,
"not-probed".to_owned(),
error.report_reason(),
),
}
}
Ok(None) => probe_report(
"agent_codex_default",
AgentKindV1::Codex,
ExecutableProbe::NotFound,
),
Err(reason) => probe_report(
"agent_codex_default",
AgentKindV1::Codex,
ExecutableProbe::Unknown(reason),
),
}
}
pub fn read_discovered_secret(
&self,
descriptor: &DiscoveredCredentialRefV1,
) -> Result<ProtectedSecret, AgentFilesystemScanError> {
if descriptor.field_selector == "opencode.api-key" {
return self.read_opencode_secret(descriptor);
}
if descriptor.field_selector == "pi.api-key" {
return self.read_pi_secret(descriptor);
}
if descriptor.field_selector == "dsh.api-key" {
return self.read_dsh_secret(descriptor);
}
validate_descriptor(descriptor)?;
let source = self
.claude_sources()
.into_iter()
.find(|source| source.source_ref() == descriptor.discovered_source_ref)
.ok_or(AgentFilesystemScanError::SourceUnavailable)?;
let (token, revision) = source.read_auth_field(
descriptor
.field_selector
.strip_prefix("env.")
.ok_or(AgentFilesystemScanError::InvalidDescriptor)?,
&self.layout.process_environment,
&self.layout.process_environment_presence,
)?;
if revision != descriptor.observed_revision {
return Err(AgentFilesystemScanError::SourceChanged);
}
ProtectedSecret::new(token.as_bytes().to_vec())
.map_err(|_| AgentFilesystemScanError::SourceUnavailable)
}
/// Applies only the scanner-issued 0600 remediation. The implementation opens with
/// `O_NOFOLLOW`, rechecks the exact regular-file identity on the descriptor, and never reads
/// or writes file content.
pub fn harden_discovered_permissions(
&self,
finding: &PermissionHardeningRequiredV1,
) -> Result<PermissionHardeningOutcomeV1, AgentFilesystemScanError> {
validate_hardening_finding(finding)?;
let source = self
.claude_sources()
.into_iter()
.find(|source| source.source_ref() == finding.discovered_source_ref)
.ok_or(AgentFilesystemScanError::SourceUnavailable)?;
source.harden_permissions(finding)
}
/// Exact native Codex target selected by this scanner, including CODEX_HOME resolution.
/// Backend composition uses this path; public requests cannot choose an arbitrary target.
pub fn codex_user_config_target(&self) -> PathBuf {
self.layout.codex_user_config.clone()
}
pub fn codex_profile_config_target(&self) -> PathBuf {
self.layout
.codex_user_config
.with_file_name("hiroute.config.toml")
}
/// Exact engine selected for one Codex surface. This is target location only: callers must
/// never turn a version, digest, or installation proof into product admission.
pub fn codex_engine_target(
&self,
surface: hiroute_domain::AgentModelSurfaceV2,
) -> Option<PathBuf> {
match surface {
hiroute_domain::AgentModelSurfaceV2::CodexCli => {
Some(self.layout.codex_executable.clone())
}
hiroute_domain::AgentModelSurfaceV2::CodexDesktop => {
self.layout.codex_desktop_executable.clone()
}
hiroute_domain::AgentModelSurfaceV2::ClaudeCli
| hiroute_domain::AgentModelSurfaceV2::QoderCli
| hiroute_domain::AgentModelSurfaceV2::PiCli
| hiroute_domain::AgentModelSurfaceV2::DshCli
| hiroute_domain::AgentModelSurfaceV2::OpenCodeCli
| hiroute_domain::AgentModelSurfaceV2::HermesCli => None,
}
}
/// Actual independently launchable surfaces. This is a location fact only; it never runs a
/// version, digest, identity, or installation admission probe.
pub fn available_model_surfaces(
&self,
agent_id: &str,
) -> BTreeSet<hiroute_domain::AgentModelSurfaceV2> {
let available = |path: &Path| matches!(super::executable::resolve(path), Ok(Some(_)));
match agent_id {
"agent_codex_default" => {
let mut surfaces = BTreeSet::new();
if self
.layout
.codex_desktop_executable
.as_deref()
.is_some_and(available)
{
surfaces.insert(hiroute_domain::AgentModelSurfaceV2::CodexDesktop);
}
if available(&self.layout.codex_executable) {
surfaces.insert(hiroute_domain::AgentModelSurfaceV2::CodexCli);
}
surfaces
}
"agent_claude_default" if available(&self.layout.claude_executable) => {
[hiroute_domain::AgentModelSurfaceV2::ClaudeCli]
.into_iter()
.collect()
}
"agent_opencode_default" if self.opencode_executable_target().is_some() => {
[hiroute_domain::AgentModelSurfaceV2::OpenCodeCli].into()
}
"agent_dsh_default" if self.dsh_executable_target().is_some() => {
[hiroute_domain::AgentModelSurfaceV2::DshCli].into()
}
"agent_pi_default" if self.pi_executable_target().is_some() => {
[hiroute_domain::AgentModelSurfaceV2::PiCli].into()
}
"agent_qoder_default" if self.qoder_executable_target().is_some() => {
[hiroute_domain::AgentModelSurfaceV2::QoderCli]
.into_iter()
.collect()
}
_ => BTreeSet::new(),
}
}
pub fn codex_catalog_summary(
&self,
) -> Result<super::CodexCatalogSummaryV1, super::CodexCatalogError> {
let scope =
super::CodexConfigurationScope::user_file(self.layout.codex_user_config.clone());
let explicit_model = super::sample_codex_configuration(&scope)
.map_err(|_| super::CodexCatalogError::InvalidCatalog)?
.source_document
.get("model")
.and_then(toml_edit::Item::as_str)
.map(str::to_owned);
super::sample_codex_catalog_summary(&scope, explicit_model.as_deref())
}
/// Returns the exact user-level native target owned by the Claude integration adapter.
/// The path never crosses a public wire contract; Local Control uses it only for the
/// recoverable external effect selected by the registered Claude profile.
pub fn claude_user_settings_target(&self) -> PathBuf {
self.layout.claude_user_settings.clone()
}
fn scan_claude(
&self,
executable: Option<ExecutableObservationV1>,
executable_outcome: Option<AgentDiscoveryOutcomeV1>,
for_settings: bool,
) -> FilesystemAgentDiscoveryV1 {
let version = executable
.as_ref()
.map(|value| value.version.clone())
.unwrap_or_default();
let version = self
.legacy_recovery_version
.as_ref()
.unwrap_or(&version)
.clone();
// Settings writes bind the actual executable and target file, not the native
// endpoint/model registration used by ordinary account discovery. A user may
// switch an otherwise runnable Claude installation from an unknown provider.
let preserve_executable_outcome = executable_outcome.is_some() || for_settings;
let configuration_failure_outcome = |reason: AgentReportOnlyReasonV1| {
executable_outcome.clone().unwrap_or_else(|| {
report_only_agent(
"agent_claude_default",
AgentKindV1::ClaudeCode,
version.clone(),
reason.clone(),
)
.outcome
})
};
let mut observations = Vec::new();
for source in self.claude_sources() {
match source.read(
&self.layout.process_environment,
&self.layout.process_environment_presence,
) {
Ok(mut observed) => {
if self.legacy_process_format {
super::filesystem_config::recover_pre_context_process_digest(&mut observed);
}
observations.push(observed);
}
Err(error) => {
return FilesystemAgentDiscoveryV1 {
outcome: configuration_failure_outcome(error.report_reason()),
configuration_issue: Some(error.report_reason()),
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch: None,
};
}
}
}
let main_observations =
main_observation::resolve_project_local_fields(&self.layout, &observations);
let (observed_outcome, main_conflict) =
main_observation::main_claude_observation_with_format(
&version,
&main_observations,
self.legacy_recovery_version.is_some(),
);
let mut outcome = executable_outcome.unwrap_or(observed_outcome);
let managed_launch = if let Some(executable) = executable.as_ref() {
let profile = match &outcome {
AgentDiscoveryOutcomeV1::Supported { installation } => {
installation.profile.managed_launch.as_ref()
}
AgentDiscoveryOutcomeV1::ReportOnly { .. } => None,
};
let Some(profile) = profile else {
return FilesystemAgentDiscoveryV1 {
outcome,
configuration_issue: None,
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch: None,
};
};
Some(ManagedClaudeLaunchPreflightV1::from_observations(
executable.canonical_path.clone(),
profile,
&observations,
))
} else {
None
};
if let (Some(preflight), AgentDiscoveryOutcomeV1::Supported { installation }) =
(&managed_launch, &mut outcome)
{
let mut preflight_value =
serde_json::to_value(preflight).expect("serializable preflight");
if let Some(version) = &self.legacy_recovery_version {
preflight_value["exact_version"] = serde_json::json!(version);
}
installation.observation_digest = CanonicalDigest::of(&(
"hiroute.managed-launch-observation/v1",
&installation.observation_digest,
preflight_value,
))
.unwrap_or_else(|_| CanonicalDigest::of_bytes(b"invalid-managed-launch-observation"));
}
if main_conflict {
return FilesystemAgentDiscoveryV1 {
outcome,
configuration_issue: Some(AgentReportOnlyReasonV1::ConflictingEffectiveConfig),
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch,
};
}
// Worker preflight above consumes the original layers; main fields use native local overrides.
let observations = main_observations;
let endpoint = select_effective(&observations, |settings| settings.env.base_url.as_deref());
let model = select_effective(&observations, |settings| settings.env.model.as_deref());
let secret = select_effective_source(&observations, |settings| {
settings
.env
.present_environment_fields
.contains("ANTHROPIC_AUTH_TOKEN")
});
let default_opus_model = select_effective(&observations, |settings| {
settings.env.default_opus_model.as_deref()
});
let (Some(endpoint), Some(model)) = (endpoint, model) else {
return FilesystemAgentDiscoveryV1 {
outcome,
configuration_issue: None,
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch,
};
};
if !valid_observed_model(model.0) {
if !preserve_executable_outcome {
outcome = report_only_agent(
"agent_claude_default",
AgentKindV1::ClaudeCode,
version.clone(),
AgentReportOnlyReasonV1::UnregisteredModel,
)
.outcome;
}
return FilesystemAgentDiscoveryV1 {
outcome,
configuration_issue: Some(AgentReportOnlyReasonV1::UnregisteredModel),
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch,
};
}
let model_candidates =
registered_model_candidates(model.0, default_opus_model.map(|(value, _)| value));
let Some(registered) = self.registry.resolve(endpoint.0, &model_candidates) else {
let reason = if self.registry.has_endpoint(endpoint.0) {
AgentReportOnlyReasonV1::UnregisteredModel
} else {
AgentReportOnlyReasonV1::UnregisteredEndpoint
};
if !preserve_executable_outcome {
outcome = report_only_agent(
"agent_claude_default",
AgentKindV1::ClaudeCode,
version.clone(),
reason.clone(),
)
.outcome;
}
return FilesystemAgentDiscoveryV1 {
outcome,
configuration_issue: Some(reason),
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch,
};
};
let configuration_revision = endpoint.1.revision.max(model.1.revision);
let resolved_model_id = registered
.resolved_upstream_model_id
.clone()
.unwrap_or_else(|| model.0.to_owned());
let mut provider_model_alias_hints: BTreeMap<String, String> = default_opus_model
.map(|(value, _)| [("default_opus_model".to_owned(), value.to_owned())].into())
.unwrap_or_default();
if resolved_model_id != model.0 {
provider_model_alias_hints.insert("configured_model".to_owned(), model.0.to_owned());
}
let discovered_credential = secret.map(discovered_credential);
FilesystemAgentDiscoveryV1 {
outcome,
configuration_issue: None,
claude_configuration: Some(RegisteredClaudeConfigurationV1 {
connection_option_id: registered.connection_option_id.clone(),
endpoint_profile_id: registered.endpoint_profile_id.clone(),
endpoint_profile_revision: registered.endpoint_profile_revision,
model_configuration_id: registered.model_configuration_id.clone(),
base_url: registered.base_url.clone(),
observed_model_id: resolved_model_id,
provider_model_alias_hints,
configuration_revision,
}),
discovered_credential,
permission_hardening: None,
managed_launch,
}
}
pub(super) fn claude_sources(&self) -> Vec<ClaudeSource> {
let mut sources = vec![ClaudeSource::Process];
if let Some(path) = &self.layout.claude_launch_settings {
sources.push(ClaudeSource::File(ConfigLayerV1::Launch, path.clone()));
}
sources.extend(
self.layout
.claude_project_settings
.iter()
// Launching from HOME makes .claude/settings.json the user settings file,
// not an independent project override of the fields we just installed.
.filter(|path| !same_claude_settings_file(path, &self.layout.claude_user_settings))
.cloned()
.map(|path| ClaudeSource::File(ConfigLayerV1::Project, path)),
);
sources.push(ClaudeSource::File(
ConfigLayerV1::User,
self.layout.claude_user_settings.clone(),
));
sources.extend(
self.layout
.claude_managed_settings
.iter()
.cloned()
.map(|path| ClaudeSource::File(ConfigLayerV1::Managed, path)),
);
sources
}
}
fn same_claude_settings_file(left: &Path, right: &Path) -> bool {
left == right
|| matches!((left.canonicalize(), right.canonicalize()), (Ok(left), Ok(right)) if left == right)
}
fn discovered_credential(source: &ObservedClaudeSettings) -> DiscoveredCredentialRefV1 {
DiscoveredCredentialRefV1 {
source: "discovered_config".to_owned(),
scanner_id: FILESYSTEM_AGENT_SCANNER_ID_V1.to_owned(),
scanner_version: FILESYSTEM_AGENT_SCANNER_VERSION_V1.to_owned(),
discovered_source_ref: source.source_ref.clone(),
field_selector: "env.ANTHROPIC_AUTH_TOKEN".to_owned(),
observed_revision: source.revision,
}
}
fn registered_model_candidates(primary: &str, alias_hint: Option<&str>) -> Vec<String> {
let mut candidates = Vec::new();
for candidate in [Some(primary), alias_hint].into_iter().flatten() {
if !candidates.iter().any(|existing| existing == candidate) {
candidates.push(candidate.to_owned());
}
// Some provider-facing Claude aliases append a context selector such as `[1m]`. The
// suffix is accepted only when its stripped value matches an exact catalog upstream model
// below; this never expands the release catalog or guesses an unregistered model.
if let Some((canonical, suffix)) = candidate.rsplit_once('[')
&& suffix.ends_with(']')
&& !canonical.is_empty()
&& !candidates.iter().any(|existing| existing == canonical)
{
candidates.push(canonical.to_owned());
}
}
candidates
}
fn valid_observed_model(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 256
&& !value.contains("..")
&& !value.contains("//")
&& !value.chars().any(char::is_control)
}
fn select_effective<'a>(
values: &'a [ObservedClaudeSettings],
field: impl Fn(&'a ClaudeSettingsSubset) -> Option<&'a str>,
) -> Option<(&'a str, &'a ObservedClaudeSettings)> {
values
.iter()
.filter_map(|value| field(&value.settings).map(|field| (field, value)))
.min_by_key(|(_, value)| value.layer.precedence_for(AgentKindV1::ClaudeCode))
}
fn select_effective_source<'a>(
values: &'a [ObservedClaudeSettings],
field: impl Fn(&'a ClaudeSettingsSubset) -> bool,
) -> Option<&'a ObservedClaudeSettings> {
values
.iter()
.filter(|value| field(&value.settings))
.min_by_key(|value| value.layer.precedence_for(AgentKindV1::ClaudeCode))
}
fn validate_descriptor(
descriptor: &DiscoveredCredentialRefV1,
) -> Result<(), AgentFilesystemScanError> {
if descriptor.source != "discovered_config"
|| descriptor.scanner_id != FILESYSTEM_AGENT_SCANNER_ID_V1
|| descriptor.scanner_version != FILESYSTEM_AGENT_SCANNER_VERSION_V1
|| !matches!(
descriptor.field_selector.as_str(),
"env.ANTHROPIC_AUTH_TOKEN" | "env.ANTHROPIC_API_KEY"
)
|| descriptor.observed_revision == 0
{
return Err(AgentFilesystemScanError::InvalidDescriptor);
}
Ok(())
}
fn validate_hardening_finding(
finding: &PermissionHardeningRequiredV1,
) -> Result<(), AgentFilesystemScanError> {
if finding.scanner_id != FILESYSTEM_AGENT_SCANNER_ID_V1
|| finding.scanner_version != FILESYSTEM_AGENT_SCANNER_VERSION_V1
|| !finding
.discovered_source_ref
.starts_with("claude/settings/")
|| finding.observed_revision == 0
|| finding.required_mode != 0o600
|| CanonicalDigest::parse(finding.observed_identity.as_str().to_owned()).is_err()
{
return Err(AgentFilesystemScanError::InvalidDescriptor);
}
Ok(())
}
fn base_observation(agent_id: &str, kind: AgentKindV1, version: String) -> AgentScanObservationV1 {
AgentScanObservationV1 {
schema: AGENT_SCAN_OBSERVATION_SCHEMA_V1.to_owned(),
agent_id: agent_id.to_owned(),
kind,
version,
config: Vec::new(),
}
}
fn report_only_agent(
agent_id: &str,
kind: AgentKindV1,
version: String,
reason: AgentReportOnlyReasonV1,
) -> FilesystemAgentDiscoveryV1 {
let observation_digest = CanonicalDigest::of_bytes(
format!("agent-report-only\0{agent_id}\0{version}\0{reason:?}").as_bytes(),
);
FilesystemAgentDiscoveryV1 {
outcome: AgentDiscoveryOutcomeV1::ReportOnly {
agent_id: agent_id.to_owned(),
kind,
version,
reason,
observation_digest,
},
configuration_issue: None,
claude_configuration: None,
discovered_credential: None,
permission_hardening: None,
managed_launch: None,
}
}
fn outcome_agent_id(outcome: &AgentDiscoveryOutcomeV1) -> &str {
match outcome {
AgentDiscoveryOutcomeV1::Supported { installation } => &installation.agent_id,
AgentDiscoveryOutcomeV1::ReportOnly { agent_id, .. } => agent_id,
}
}
#[derive(Debug, Error)]
pub enum AgentFilesystemScanError {
#[error("Agent configuration is a symlink")]
SymlinkConfig,
#[error("Agent configuration is owned by another user")]
WrongOwner,
#[error("Agent configuration permissions expose protected values")]
UnsafePermissions,
#[error("Agent configuration is invalid")]
InvalidConfig,
#[error("Agent configuration exceeds the scanner bound")]
ConfigTooLarge,
#[error("discovered source is unavailable")]
SourceUnavailable,
#[error("discovered source changed")]
SourceChanged,
#[error("discovered source descriptor is invalid")]
InvalidDescriptor,
#[error("Release registry is invalid")]
InvalidRegistry,
#[error("Agent configuration I/O failed")]
Io(#[from] std::io::Error),
}
impl AgentFilesystemScanError {
fn report_reason(&self) -> AgentReportOnlyReasonV1 {
match self {
Self::SymlinkConfig => AgentReportOnlyReasonV1::SymlinkConfig,
Self::WrongOwner => AgentReportOnlyReasonV1::WrongOwner,
Self::UnsafePermissions => AgentReportOnlyReasonV1::UnsafeConfigPermissions,
_ => AgentReportOnlyReasonV1::ConfigUnavailable,
}
}
}
#[cfg(test)]
#[path = "filesystem_tests.rs"]
mod tests;
fn probe_report(
agent_id: &str,
kind: AgentKindV1,
result: ExecutableProbe,
) -> FilesystemAgentDiscoveryV1 {
let reason = match result {
ExecutableProbe::NotFound => AgentReportOnlyReasonV1::NotFoundInScope,
ExecutableProbe::Unknown(reason) => match reason {
super::executable::ProbeFailure::NotExecutable => {
AgentReportOnlyReasonV1::ExecutableNotRunnable
}
super::executable::ProbeFailure::TimedOut => {
AgentReportOnlyReasonV1::ExecutableProbeTimedOut
}
_ => AgentReportOnlyReasonV1::ExecutableProbeUnavailable,
},
ExecutableProbe::Installed(_) => unreachable!("installed handled by native scanner"),
};
report_only_agent(agent_id, kind, String::new(), reason)
}
pub(super) fn codex_config_path(home: &Path, configured: Option<&std::ffi::OsStr>) -> PathBuf {
configured
.filter(|value| !value.is_empty())
.map(PathBuf::from)
.unwrap_or_else(|| home.join(".codex"))
.join("config.toml")
}