Skip to main content

codewhale_runtime/
runtime_policy.rs

1//! Normalization for Runtime mode and permission-posture wires.
2//!
3//! Older clients can still send mode aliases and the legacy `auto_approve`
4//! bit. New callers send a named posture. Keep those inputs readable, but
5//! persist and execute one contract: Plan / Work plus Ask /
6//! Accept Edits / Auto-Review / Full Access.
7
8use anyhow::{Result, bail};
9
10use codewhale_config::AppMode;
11use codewhale_execpolicy::ApprovalMode;
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub struct RuntimePolicyProjection {
15    pub mode: AppMode,
16    pub permission: ApprovalMode,
17}
18
19/// The wire spelling of one approval posture: what a thread or task request
20/// names in its `permission_posture` field.
21///
22/// `Never` is a managed-policy value the product surface does not carry, so it
23/// reads as Ask — exactly as [`RuntimePolicyProjection::permission_wire`] has
24/// always spelled it.
25#[must_use]
26pub fn approval_wire(mode: ApprovalMode) -> &'static str {
27    match mode {
28        ApprovalMode::Auto => "auto_review",
29        ApprovalMode::Bypass => "full_access",
30        ApprovalMode::AcceptEdits => "accept_edits",
31        ApprovalMode::Suggest | ApprovalMode::Never => "ask",
32    }
33}
34
35impl RuntimePolicyProjection {
36    /// Read a persisted compatibility shape. Unknown historical values fail
37    /// closed to Act + Ask unless the old bypass bit is explicitly present.
38    #[must_use]
39    pub fn from_persisted(
40        mode: &str,
41        permission_posture: Option<&str>,
42        auto_approve: bool,
43    ) -> Self {
44        let parsed_mode = parse_runtime_mode(mode).unwrap_or(AppMode::Agent);
45        let permission = permission_posture
46            .and_then(ApprovalMode::from_config_value)
47            .filter(|permission| *permission != ApprovalMode::Never)
48            .unwrap_or_else(|| {
49                if AppMode::is_legacy_bypass_alias(mode) || auto_approve {
50                    ApprovalMode::Bypass
51                } else {
52                    ApprovalMode::Suggest
53                }
54            });
55        Self {
56            mode: parsed_mode,
57            permission,
58        }
59    }
60
61    /// Validate and normalize a new Runtime request. Legacy aliases are
62    /// accepted as one-way inputs, but only current values are persisted.
63    pub fn from_request(
64        mode: &str,
65        permission_posture: Option<&str>,
66        auto_approve: Option<bool>,
67    ) -> Result<Self> {
68        let parsed_mode = parse_runtime_mode(mode).ok_or_else(|| {
69            anyhow::anyhow!("unsupported Runtime mode {mode:?}; expected plan or agent")
70        })?;
71        if AppMode::is_retired_operate_alias(mode) {
72            static OPERATE_RETIRED_NOTICE: std::sync::Once = std::sync::Once::new();
73            OPERATE_RETIRED_NOTICE.call_once(|| {
74                tracing::warn!(
75                    target: "runtime_policy",
76                    "Runtime mode {mode:?} is retired: Operate is no longer a mode, so this runs as agent with the default permission posture; use /fleet for parallel agents"
77                );
78            });
79        }
80        let permission = match permission_posture {
81            Some(value) => ApprovalMode::from_config_value(value).ok_or_else(|| {
82                anyhow::anyhow!(
83                    "unsupported permission posture {value:?}; expected ask, accept-edits, auto-review, or full-access"
84                )
85            })?,
86            None if AppMode::is_legacy_bypass_alias(mode) || auto_approve.unwrap_or(false) => ApprovalMode::Bypass,
87            None => ApprovalMode::AcceptEdits,
88        };
89        if permission == ApprovalMode::Never {
90            bail!("permission posture 'never' is not part of the Runtime product contract");
91        }
92        Ok(Self {
93            mode: parsed_mode,
94            permission,
95        })
96    }
97
98    #[must_use]
99    pub fn mode_setting(self) -> &'static str {
100        self.mode.as_setting()
101    }
102
103    #[must_use]
104    pub fn permission_wire(self) -> &'static str {
105        approval_wire(self.permission)
106    }
107
108    #[must_use]
109    pub fn auto_approve(self) -> bool {
110        self.permission == ApprovalMode::Bypass
111    }
112}
113
114#[must_use]
115pub fn parse_runtime_mode(value: &str) -> Option<AppMode> {
116    match value.trim().to_ascii_lowercase().as_str() {
117        "normal" => Some(AppMode::Agent),
118        other => AppMode::parse(other),
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125
126    #[test]
127    fn approval_wire_spells_every_product_posture() {
128        assert_eq!(approval_wire(ApprovalMode::Suggest), "ask");
129        assert_eq!(approval_wire(ApprovalMode::Auto), "auto_review");
130        assert_eq!(approval_wire(ApprovalMode::Bypass), "full_access");
131        // `Never` is a managed-policy value the product surface does not carry.
132        assert_eq!(approval_wire(ApprovalMode::Never), "ask");
133    }
134
135    #[test]
136    fn legacy_inputs_project_to_current_mode_and_permission_wires() {
137        for alias in ["normal", "agent", "auto"] {
138            let policy = RuntimePolicyProjection::from_persisted(alias, None, false);
139            assert_eq!(policy.mode_setting(), "agent", "{alias}");
140            assert_eq!(policy.permission_wire(), "ask", "{alias}");
141        }
142        for alias in ["yolo", "bypass"] {
143            let policy = RuntimePolicyProjection::from_persisted(alias, None, false);
144            assert_eq!(policy.mode_setting(), "agent", "{alias}");
145            assert_eq!(policy.permission_wire(), "full_access", "{alias}");
146        }
147    }
148
149    #[test]
150    fn named_posture_is_normalized_and_authoritative() {
151        let auto = RuntimePolicyProjection::from_request("operate", Some("auto-review"), None)
152            .expect("compat permission");
153        assert_eq!(auto.mode_setting(), "agent");
154        assert_eq!(auto.permission_wire(), "auto_review");
155        assert_eq!(auto.permission, ApprovalMode::Auto);
156        assert!(!auto.auto_approve());
157
158        let full = RuntimePolicyProjection::from_request("act", Some("full_access"), None)
159            .expect("current permission wire");
160        assert_eq!(full.permission_wire(), "full_access");
161        assert_eq!(full.permission, ApprovalMode::Bypass);
162        assert!(full.auto_approve());
163
164        let ask = RuntimePolicyProjection::from_request("yolo", Some("ask"), Some(true))
165            .expect("named posture overrides legacy flags");
166        assert_eq!(ask.mode_setting(), "agent");
167        assert_eq!(ask.permission_wire(), "ask");
168        assert_eq!(ask.permission, ApprovalMode::Suggest);
169        assert!(!ask.auto_approve());
170    }
171
172    #[test]
173    fn invalid_or_never_postures_are_rejected() {
174        assert!(RuntimePolicyProjection::from_request("act", Some("owner"), None).is_err());
175        assert!(RuntimePolicyProjection::from_request("act", Some("never"), None).is_err());
176    }
177}