ralph/agent/args.rs
1//! CLI argument structs for agent configuration.
2//!
3//! Responsibilities:
4//! - Define CLI argument structs with clap derive macros for agent-related flags.
5//! - Keep fields as raw CLI shapes (Strings, bools, Options).
6//!
7//! Not handled here:
8//! - Parsing or validation logic (see `super::parse`).
9//! - Override resolution (see `super::resolve`).
10//! - RepoPrompt flag resolution (see `super::repoprompt`).
11//!
12//! Invariants/assumptions:
13//! - All structs use `clap::Args` derive for CLI integration.
14//! - `RepoPromptMode` is imported from the repoprompt module.
15
16use clap::Args;
17
18use super::repoprompt::RepoPromptMode;
19
20/// CLI arguments for runner CLI overrides.
21#[derive(Args, Clone, Debug, Default)]
22pub struct RunnerCliArgs {
23 /// Desired runner output format (stream-json, json, text). Ralph execution requires stream-json.
24 #[arg(long)]
25 pub output_format: Option<String>,
26
27 /// Desired verbosity (quiet, normal, verbose). Only some runners support this.
28 #[arg(long)]
29 pub verbosity: Option<String>,
30
31 /// Desired approval mode (default, auto-edits, yolo, safe). Default is yolo.
32 #[arg(long)]
33 pub approval_mode: Option<String>,
34
35 /// Desired sandbox mode (default, enabled, disabled). Only some runners support this.
36 #[arg(long)]
37 pub sandbox: Option<String>,
38
39 /// Desired plan/read-only mode (default, enabled, disabled). Only Cursor currently supports this.
40 #[arg(long)]
41 pub plan_mode: Option<String>,
42
43 /// Policy for unsupported options (ignore, warn, error). Default is warn.
44 #[arg(long)]
45 pub unsupported_option_policy: Option<String>,
46}
47
48/// CLI arguments for agent configuration.
49///
50/// Used by `task` and `scan` commands.
51#[derive(Args, Clone, Debug, Default)]
52pub struct AgentArgs {
53 /// Runner override for this invocation (codex, opencode, gemini, claude, cursor).
54 /// Overrides task.agent and config.
55 #[arg(long)]
56 pub runner: Option<String>,
57
58 /// Model override for this invocation. Overrides task.agent and config.
59 /// Allowed: gpt-5.4, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.3, gpt-5.2-codex, gpt-5.2, zai-coding-plan/glm-4.7, gemini-3-pro-preview, gemini-3-flash-preview, sonnet, opus, kimi-for-coding
60 /// (codex supports only gpt-5.4/gpt-5.3-codex/gpt-5.3-codex-spark/gpt-5.3/gpt-5.2-codex/gpt-5.2; opencode/gemini/claude/cursor/kimi/pi accept arbitrary model ids).
61 #[arg(long)]
62 pub model: Option<String>,
63
64 /// Codex reasoning effort override (low, medium, high, xhigh).
65 /// Ignored for other runners.
66 #[arg(short = 'e', long)]
67 pub effort: Option<String>,
68
69 /// RepoPrompt mode (tools, plan, off). Alias: -rp.
70 #[arg(long = "repo-prompt", value_enum, value_name = "MODE")]
71 pub repo_prompt: Option<RepoPromptMode>,
72
73 #[command(flatten)]
74 pub runner_cli: RunnerCliArgs,
75}
76
77/// Extended agent arguments for run commands (includes phases).
78#[derive(Args, Clone, Debug, Default)]
79pub struct RunAgentArgs {
80 /// Named configuration profile to apply before resolving task/CLI overrides.
81 /// Examples: quick, thorough, quick-fix
82 #[arg(long, value_name = "NAME")]
83 pub profile: Option<String>,
84
85 /// Runner override for this invocation (codex, opencode, gemini, claude, cursor).
86 /// Overrides task.agent and config.
87 #[arg(long)]
88 pub runner: Option<String>,
89
90 /// Model override for this invocation. Overrides task.agent and config.
91 /// Allowed: gpt-5.4, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.3, gpt-5.2-codex, gpt-5.2, zai-coding-plan/glm-4.7, gemini-3-pro-preview, gemini-3-flash-preview, sonnet, opus, kimi-for-coding
92 /// (codex supports only gpt-5.4/gpt-5.3-codex/gpt-5.3-codex-spark/gpt-5.3/gpt-5.2-codex/gpt-5.2; opencode/gemini/claude/cursor/kimi/pi accept arbitrary model ids).
93 #[arg(long)]
94 pub model: Option<String>,
95
96 /// Codex reasoning effort override (low, medium, high, xhigh).
97 /// Ignored for other runners.
98 #[arg(short = 'e', long)]
99 pub effort: Option<String>,
100
101 #[command(flatten)]
102 pub runner_cli: RunnerCliArgs,
103
104 /// Execution shape:
105 /// - 1 => single-pass execution (no mandated planning step)
106 /// - 2 => two-pass execution (plan then implement)
107 /// - 3 => three-pass execution (plan, implement+CI, review+complete)
108 ///
109 /// If omitted, defaults to config `agent.phases`.
110 #[arg(long, value_parser = clap::value_parser!(u8).range(1..=3))]
111 pub phases: Option<u8>,
112
113 /// Quick mode: skip planning phase and run single-pass execution.
114 ///
115 /// Equivalent to --phases=1. Cannot be used with --phases.
116 #[arg(long, conflicts_with = "phases")]
117 pub quick: bool,
118
119 /// RepoPrompt mode (tools, plan, off). Alias: -rp.
120 #[arg(long = "repo-prompt", value_enum, value_name = "MODE")]
121 pub repo_prompt: Option<RepoPromptMode>,
122
123 /// Git revert mode for automatic error handling (ask, enabled, disabled).
124 #[arg(long, value_parser = ["ask", "enabled", "disabled"])]
125 pub git_revert_mode: Option<String>,
126
127 /// Enable automatic git commit and push after successful runs.
128 #[arg(long, conflicts_with = "git_commit_push_off")]
129 pub git_commit_push_on: bool,
130
131 /// Disable automatic git commit and push after successful runs.
132 #[arg(long, conflicts_with = "git_commit_push_on")]
133 pub git_commit_push_off: bool,
134
135 /// Include draft tasks when selecting what to run.
136 #[arg(long)]
137 pub include_draft: bool,
138
139 /// Enable desktop notification on task completion (overrides config).
140 #[arg(long, conflicts_with = "no_notify")]
141 pub notify: bool,
142
143 /// Disable desktop notification on task completion (overrides config).
144 #[arg(long, conflicts_with = "notify")]
145 pub no_notify: bool,
146
147 /// Enable desktop notification on task failure (overrides config).
148 #[arg(long, conflicts_with = "no_notify_fail")]
149 pub notify_fail: bool,
150
151 /// Disable desktop notification on task failure (overrides config).
152 #[arg(long, conflicts_with = "notify_fail")]
153 pub no_notify_fail: bool,
154
155 /// Enable sound alert with notification (requires --notify or config enabled).
156 #[arg(long)]
157 pub notify_sound: bool,
158
159 /// Enable strict LFS validation before commit (fail if filters misconfigured).
160 #[arg(long)]
161 pub lfs_check: bool,
162
163 /// Disable progress indicators and celebrations.
164 #[arg(long)]
165 pub no_progress: bool,
166
167 // Phase 1 overrides
168 /// Runner override for Phase 1 (planning).
169 #[arg(long, value_name = "RUNNER")]
170 pub runner_phase1: Option<String>,
171
172 /// Model override for Phase 1 (planning).
173 #[arg(long, value_name = "MODEL")]
174 pub model_phase1: Option<String>,
175
176 /// Reasoning effort override for Phase 1 (planning).
177 #[arg(long, value_name = "EFFORT")]
178 pub effort_phase1: Option<String>,
179
180 // Phase 2 overrides
181 /// Runner override for Phase 2 (implementation).
182 #[arg(long, value_name = "RUNNER")]
183 pub runner_phase2: Option<String>,
184
185 /// Model override for Phase 2 (implementation).
186 #[arg(long, value_name = "MODEL")]
187 pub model_phase2: Option<String>,
188
189 /// Reasoning effort override for Phase 2 (implementation).
190 #[arg(long, value_name = "EFFORT")]
191 pub effort_phase2: Option<String>,
192
193 // Phase 3 overrides
194 /// Runner override for Phase 3 (review).
195 #[arg(long, value_name = "RUNNER")]
196 pub runner_phase3: Option<String>,
197
198 /// Model override for Phase 3 (review).
199 #[arg(long, value_name = "MODEL")]
200 pub model_phase3: Option<String>,
201
202 /// Reasoning effort override for Phase 3 (review).
203 #[arg(long, value_name = "EFFORT")]
204 pub effort_phase3: Option<String>,
205}