oneharness-core 0.3.0

Reusable engine behind the oneharness CLI: harness registry, hook rendering/installation, and harness config sync.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

//! The normalized permission/approval mode — one vocabulary across every
//! harness's own approval system.
//!
//! Each harness spells autonomy differently (Claude Code's `--permission-mode`,
//! Codex's `--sandbox`, Qwen's `--approval-mode`, Goose's `GOOSE_MODE`, …).
//! [`PermissionMode`] is oneharness's single ordered spectrum; the registry
//! ([`crate::domain::harness`]) maps each value to the selected harness's native
//! mechanism (argv flags and/or environment), and declares which modes a harness
//! can actually honor in a *headless* run via [`ModeHeadless`]. This module is
//! pure data + parsing; the mapping and the spawn live in the harness registry
//! and the command/io layers.

use serde::{Deserialize, Serialize};

/// The unified approval mode, from least to most autonomy. A harness may not
/// support every value (see [`crate::domain::harness::HarnessSpec::mode`]); the
/// command layer refuses an unsupported one before spawning, never silently
/// downgrading it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PermissionMode {
    /// No mutations — the agent may read but not edit files or run commands —
    /// *without* the plan workflow: it just does whatever read-only work the task
    /// allows. Mapped to each harness's strongest per-run no-mutation enforcement
    /// (Codex's read-only sandbox, Claude's deny rules, Copilot's `--deny-tool`,
    /// Cursor's `ask` mode). The enforced counterpart to [`Self::Plan`].
    ReadOnly,
    /// Read and propose only — like [`Self::ReadOnly`], but additionally engages
    /// the harness's *plan* workflow: research the task and write a plan rather
    /// than act. Supported only where a native plan mode exists (Claude/Qwen/
    /// Cursor/Copilot, OpenCode's `plan` agent); harnesses with no plan workflow
    /// (Codex, Goose, Crush) reject it — use [`Self::ReadOnly`] for those.
    Plan,
    /// The harness's normal ask flow, mapped to its cleanest *non-interactive*
    /// variant so a headless run never blocks waiting for input (Claude's
    /// `dontAsk` deny-and-continue, Goose's fail-closed `approve`, Copilot's
    /// auto-deny). Where no such variant exists the harness's [`ModeHeadless`]
    /// is [`ModeHeadless::Hangs`].
    Default,
    /// Auto-approve file edits, still gate shell/commands. (Claude's
    /// `acceptEdits`, Qwen's `auto-edit`.)
    Edit,
    /// Auto-approve operations the harness deems safe (a classifier), gate the
    /// risky ones. (Claude's `auto`, Qwen's `auto`, Goose's `smart_approve`.)
    Auto,
    /// Approve everything — no prompts, no gating. The headless default, because
    /// an unattended agent otherwise hangs on the first approval. Every harness
    /// supports it. (Claude's `bypassPermissions`, Codex's
    /// `--dangerously-bypass-approvals-and-sandbox`, Qwen/Crush `--yolo`, …)
    Bypass,
}

impl PermissionMode {
    /// Every mode, in spectrum order. The source of truth for `--help`, the
    /// `--mode` value parser, and `oneharness list`.
    pub const ALL: [PermissionMode; 6] = [
        PermissionMode::ReadOnly,
        PermissionMode::Plan,
        PermissionMode::Default,
        PermissionMode::Edit,
        PermissionMode::Auto,
        PermissionMode::Bypass,
    ];

    /// The CLI / JSON token for this mode (kebab-case, matching `Serialize`).
    pub fn as_str(self) -> &'static str {
        match self {
            PermissionMode::ReadOnly => "read-only",
            PermissionMode::Plan => "plan",
            PermissionMode::Default => "default",
            PermissionMode::Edit => "edit",
            PermissionMode::Auto => "auto",
            PermissionMode::Bypass => "bypass",
        }
    }

    /// Parse a `--mode` / `ONEHARNESS_MODE` token, with a loud error listing the
    /// valid values (the same contract as an unknown config value).
    pub fn parse(s: &str) -> Result<Self, String> {
        PermissionMode::ALL
            .into_iter()
            .find(|m| m.as_str() == s)
            .ok_or_else(|| format!("must be one of {}, got `{s}`", Self::valid_list()))
    }

    /// Comma-joined valid tokens, for error messages and help.
    pub fn valid_list() -> String {
        PermissionMode::ALL
            .iter()
            .map(|m| m.as_str())
            .collect::<Vec<_>>()
            .join(", ")
    }

    /// The legacy boolean `bypass`: `true` is [`PermissionMode::Bypass`], `false`
    /// the [`PermissionMode::Default`] ask flow. Lets the old `--bypass` /
    /// `--no-bypass` flags and `bypass =` config map onto the mode spectrum.
    pub fn from_bypass(bypass: bool) -> Self {
        if bypass {
            PermissionMode::Bypass
        } else {
            PermissionMode::Default
        }
    }

    /// Whether this is the all-approving bypass mode (kept so the report's
    /// back-compat `bypass_permissions` boolean stays derivable from the mode).
    pub fn is_bypass(self) -> bool {
        matches!(self, PermissionMode::Bypass)
    }
}

/// How a harness honors one [`PermissionMode`] in a *headless* run — the
/// classification that lets oneharness refuse a hang instead of waiting it out.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum ModeHeadless {
    /// Never blocks: the harness denies-and-continues, fails closed, or runs
    /// fully autonomously. Safe to spawn unattended.
    Clean,
    /// May block on an interactive approval prompt that a headless run cannot
    /// answer (the harness has no clean non-interactive variant of this mode).
    /// The command layer refuses this combination unless `--permit-prompts` is
    /// set, turning a silent hang into a loud, immediate error.
    Hangs,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_round_trips_every_mode() {
        for m in PermissionMode::ALL {
            assert_eq!(PermissionMode::parse(m.as_str()).unwrap(), m);
        }
    }

    #[test]
    fn parse_rejects_unknown_with_a_listing() {
        let err = PermissionMode::parse("yolo").unwrap_err();
        assert!(err.contains("yolo"), "{err}");
        assert!(err.contains("bypass"), "lists valid values: {err}");
    }

    #[test]
    fn bypass_bridge_maps_both_ways() {
        assert_eq!(PermissionMode::from_bypass(true), PermissionMode::Bypass);
        assert_eq!(PermissionMode::from_bypass(false), PermissionMode::Default);
        assert!(PermissionMode::Bypass.is_bypass());
        assert!(!PermissionMode::Default.is_bypass());
    }

    #[test]
    fn serializes_as_kebab_tokens() {
        let json = serde_json::to_string(&PermissionMode::Bypass).unwrap();
        assert_eq!(json, "\"bypass\"");
        let parsed: PermissionMode = serde_json::from_str("\"plan\"").unwrap();
        assert_eq!(parsed, PermissionMode::Plan);
    }
}