supercode-harness 0.4.6

//! Harness-owned controls that materially affect Supercode interoperability.
//!
//! This is deliberately not a generic editor for every harness preference.
//! Providers expose only controls that affect discovery, translation, peer
//! delivery, or continuation, behind one stable report/change contract.

use std::path::PathBuf;

use serde::{Deserialize, Serialize};

use crate::{
    read_claude_peer_settings, update_claude_peer_settings, ClaudeCrossSessionInbound,
    ClaudePeerSettingsError, HarnessHomes, HarnessId,
};

/// Stable report schema shared by Rust, JSON-RPC, SDKs, and UIs.
pub const HARNESS_INTEROP_SETTINGS_SCHEMA: &str = "supercode.harness-interop-settings.v1";
/// Stable key for Claude Code's native `crossSessionInbound` preference.
pub const CLAUDE_CROSS_SESSION_INBOUND_KEY: &str = "cross_session_inbound";

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
/// Native configuration layer from which a control was read.
pub enum HarnessSettingScope {
    /// User-wide harness preferences.
    User,
    /// Repository or workspace preferences.
    Project,
    /// Organization-managed policy.
    Managed,
    /// A command-line override on the running process.
    CommandLine,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// One allowed value for an interoperability control.
pub struct HarnessSettingChoice {
    /// Native serialized value.
    pub value: String,
    /// Short user-facing label.
    pub label: String,
    /// Behavioral meaning of the value.
    pub description: String,
    /// Security or interoperability consequence, when notable.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub risk: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// One harness-owned setting that Supercode can inspect or configure.
pub struct HarnessInteropControl {
    /// Stable Supercode control key.
    pub key: String,
    /// Harness-native setting key.
    pub native_key: String,
    /// Short user-facing label.
    pub label: String,
    /// Explanation of the interoperability behavior controlled.
    pub description: String,
    /// Native configuration layer inspected.
    pub scope: HarnessSettingScope,
    /// Exact native file inspected or changed.
    pub source_path: PathBuf,
    /// Value explicitly configured in that file.
    pub configured_value: Option<String>,
    /// Effective value, when precedence can be proven.
    pub effective_value: Option<String>,
    /// Whether `effective_value` is authoritative for the running process.
    pub effective_known: bool,
    /// Why the effective value is or is not known.
    pub effective_note: String,
    /// Finite values accepted by this control.
    pub choices: Vec<HarnessSettingChoice>,
    /// Whether the host may change this control.
    pub writable: bool,
    /// Whether the explicit value can be removed.
    pub resettable: bool,
    /// Whether a harness restart is required after changing it.
    pub requires_restart: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Requested change to one stable interoperability control.
pub struct HarnessSettingChange {
    /// Stable Supercode control key.
    pub key: String,
    /// `None` removes the user override and restores the harness default.
    pub value: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Concrete, reviewable remediation for an advisory.
pub struct HarnessSettingRecommendation {
    /// Short action label.
    pub label: String,
    /// Description of the native change.
    pub description: String,
    /// Security or behavior consequence the user should review.
    pub consequence: String,
    /// Machine-readable change for trusted hosts.
    pub change: HarnessSettingChange,
    /// Equivalent CLI command for transparent manual use.
    pub command: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
/// Importance of an interoperability advisory.
pub enum HarnessAdvisorySeverity {
    /// Informational only.
    Info,
    /// The current configuration can impair an intended workflow.
    Warning,
    /// Configuration prevents a supported workflow.
    Error,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Actionable finding derived from native harness configuration.
pub struct HarnessInteropAdvisory {
    /// Stable machine-readable advisory code.
    pub code: String,
    /// User-facing importance.
    pub severity: HarnessAdvisorySeverity,
    /// Short summary.
    pub title: String,
    /// Explanation of the observed interoperability impact.
    pub message: String,
    /// Stable control key responsible for the finding.
    pub setting: String,
    /// Explicit remediation with its consequence.
    pub recommendation: HarnessSettingRecommendation,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Canonical, revisioned snapshot shared across CLI, RPC, SDK, and UI.
pub struct HarnessInteropSettingsReport {
    /// Stable schema identifier.
    pub schema: String,
    /// Harness identifier.
    pub harness: String,
    /// Hash of the exact native settings bytes used to build this report.
    pub revision: String,
    /// Exposed interoperability controls.
    pub controls: Vec<HarnessInteropControl>,
    /// Findings for the current values.
    pub advisories: Vec<HarnessInteropAdvisory>,
}

#[derive(Debug, thiserror::Error)]
/// Failure while inspecting or changing harness interoperability controls.
pub enum HarnessInteropSettingsError {
    /// The harness does not currently expose an interoperability-control provider.
    #[error("`{0}` exposes no configurable Supercode interoperability controls")]
    UnsupportedHarness(String),
    /// The requested stable key is not exposed by this harness provider.
    #[error("unsupported interoperability setting `{0}`")]
    UnsupportedSetting(String),
    /// The requested value is not one of the provider's declared choices.
    #[error("invalid value `{value}` for `{key}`")]
    InvalidValue {
        /// Stable control key.
        key: String,
        /// Rejected native value.
        value: String,
    },
    /// Native Claude Code settings could not be read or safely changed.
    #[error(transparent)]
    Claude(#[from] ClaudePeerSettingsError),
}

/// Inspect the interoperability controls exposed by one harness adapter.
pub fn inspect_harness_interop_settings(
    homes: &HarnessHomes,
    harness: &str,
) -> Result<HarnessInteropSettingsReport, HarnessInteropSettingsError> {
    if harness != HarnessId::CLAUDE_CODE {
        return Err(HarnessInteropSettingsError::UnsupportedHarness(
            harness.to_string(),
        ));
    }
    let settings = read_claude_peer_settings(homes)?;
    let configured = settings
        .cross_session_inbound
        .map(|value| value.as_str().to_string());
    let choices = [
        (
            "accept",
            "Allow automatically",
            "Deliver messages from the user's other Claude Code sessions without a separate inbound approval.",
            Some("A trusted peer session can introduce instructions into this session; the receiver's configured permission mode still governs subsequent tool use."),
        ),
        (
            "hold",
            "Ask before delivery",
            "Hold messages from sessions in a different permission-mode class for review.",
            None,
        ),
        (
            "refuse",
            "Refuse automatically",
            "Do not deliver messages from sessions in a different permission-mode class.",
            None,
        ),
    ]
    .into_iter()
    .map(|(value, label, description, risk)| HarnessSettingChoice {
        value: value.into(),
        label: label.into(),
        description: description.into(),
        risk: risk.map(str::to_string),
    })
    .collect();
    let controls = vec![HarnessInteropControl {
        key: CLAUDE_CROSS_SESSION_INBOUND_KEY.into(),
        native_key: "crossSessionInbound".into(),
        label: "Messages from other sessions".into(),
        description: "How Claude Code handles messages arriving from another live Claude Code session.".into(),
        scope: HarnessSettingScope::User,
        source_path: settings.path.clone(),
        configured_value: configured.clone(),
        // Supercode can inspect the user file but cannot prove the effective
        // value of a running process after managed/project/CLI precedence.
        effective_value: None,
        effective_known: false,
        effective_note: "This is the user-level value. Managed, project, or command-line policy may override it for a particular process.".into(),
        choices,
        writable: true,
        resettable: configured.is_some(),
        requires_restart: false,
    }];
    let advisories = if settings.user_allows_automatic_delivery() {
        Vec::new()
    } else {
        vec![HarnessInteropAdvisory {
            code: "claude_cross_session_inbound_accept".into(),
            severity: HarnessAdvisorySeverity::Warning,
            title: "Claude may hold messages from other sessions".into(),
            message: "Supercode can hand a message to Claude's inbox, but Claude may hold or refuse it under the current user-level inbound policy.".into(),
            setting: CLAUDE_CROSS_SESSION_INBOUND_KEY.into(),
            recommendation: HarnessSettingRecommendation {
                label: "Allow messages from my other Claude sessions".into(),
                description: "Set Claude Code's user-level cross-session inbound policy to accept.".into(),
                consequence: "Other Claude Code sessions owned by this user can introduce instructions without a separate inbound approval. The receiving session's configured permission mode still applies.".into(),
                change: HarnessSettingChange {
                    key: CLAUDE_CROSS_SESSION_INBOUND_KEY.into(),
                    value: Some("accept".into()),
                },
                command: "supercode harness configure claude-code --cross-session-inbound accept".into(),
            },
        }]
    };
    Ok(HarnessInteropSettingsReport {
        schema: HARNESS_INTEROP_SETTINGS_SCHEMA.into(),
        harness: HarnessId::CLAUDE_CODE.into(),
        revision: settings.revision,
        controls,
        advisories,
    })
}

/// Apply a revision-checked set of changes and return the resulting snapshot.
pub fn configure_harness_interop_settings(
    homes: &HarnessHomes,
    harness: &str,
    changes: &[HarnessSettingChange],
    expected_revision: Option<&str>,
) -> Result<HarnessInteropSettingsReport, HarnessInteropSettingsError> {
    if harness != HarnessId::CLAUDE_CODE {
        return Err(HarnessInteropSettingsError::UnsupportedHarness(
            harness.to_string(),
        ));
    }
    if changes.len() != 1 || changes[0].key != CLAUDE_CROSS_SESSION_INBOUND_KEY {
        let key = changes
            .first()
            .map(|change| change.key.clone())
            .unwrap_or_else(|| "<missing>".into());
        return Err(HarnessInteropSettingsError::UnsupportedSetting(key));
    }
    let change = &changes[0];
    let value = match change.value.as_deref() {
        None => None,
        Some("accept") => Some(ClaudeCrossSessionInbound::Accept),
        Some("hold") => Some(ClaudeCrossSessionInbound::Hold),
        Some("refuse") => Some(ClaudeCrossSessionInbound::Refuse),
        Some(value) => {
            return Err(HarnessInteropSettingsError::InvalidValue {
                key: change.key.clone(),
                value: value.into(),
            })
        }
    };
    update_claude_peer_settings(homes, value, expected_revision)?;
    inspect_harness_interop_settings(homes, harness)
}