sqlite_graphrag/commands/
claude_runner.rs

1//! Shared module for spawning Claude Code (`claude -p`) subprocesses.
2//!
3//! Eliminates duplication between `enrich.rs` and `ingest_claude.rs` (G02).
4//! Detects `terminal_reason: "max_turns"` in the JSON output (G03).
5//!
6//! v1.0.83 (ADR-0041): env whitelist now delegates to
7//! `crate::spawn::env_whitelist::apply_env_whitelist` so the canonical list
8//! lives in one place. `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` remain
9//! INTENTIONALLY ABSENT (defence-in-depth alongside the OAuth-only guards).
10
11use crate::errors::AppError;
12use crate::spawn::env_whitelist::apply_env_whitelist;
13use std::path::Path;
14use std::process::{Command, Stdio};
15
16/// Minimum Claude Code version required for structured JSON output.
17const MIN_CLAUDE_VERSION: &str = "2.1.0";
18
19/// Default virtual memory limit for LLM subprocesses (4 GiB).
20#[cfg(target_os = "linux")]
21const DEFAULT_SUBPROCESS_MEMORY_LIMIT_MB: u64 = 4096;
22
23// G28-C (v1.0.69): process lifecycle. The G28 gap asks for
24// `tokio::process::Command::kill_on_drop(true)`. This codebase uses
25// `std::process::Command` (synchronous) so the tokio helper is not
26// available. Equivalent defence-in-depth is provided by:
27//
28// 1. `SIGTERM` via `libc::kill` in the timeout branch of `run_claude`
29//    and `run_codex` (graceful — gives the child a chance to clean up
30//    MCP children and write logs).
31// 2. `child.kill()` (SIGKILL) if SIGTERM was ignored.
32// 3. `reaper::scan_and_kill_orphans()` at startup, which walks `/proc`
33//    and reaps any `claude`/`codex` processes that were orphaned by a
34//    previous crash.
35//
36// SIGKILL on drop is intentionally NOT used because (a) the gaps.md
37// Passo C warning flags it as risky per tokio-rs/tokio#7082, and (b)
38// the SIGTERM-then-SIGKILL pair covers the same threat model with
39// better cleanup behaviour.
40
41/// Spawns a command with a virtual memory limit via `setrlimit(RLIMIT_AS)`.
42///
43/// On Linux, applies the limit in a `pre_exec` hook before the child process
44/// starts.  On non-Linux platforms, falls back to an unlimited spawn.
45/// The limit is read from `SQLITE_GRAPHRAG_SUBPROCESS_MEMORY_LIMIT_MB`
46/// (default: 4096 MiB).
47#[cfg(target_os = "linux")]
48pub fn spawn_with_memory_limit(cmd: &mut Command) -> std::io::Result<std::process::Child> {
49    use std::os::unix::process::CommandExt;
50    let max_mb: u64 = std::env::var("SQLITE_GRAPHRAG_SUBPROCESS_MEMORY_LIMIT_MB")
51        .ok()
52        .and_then(|v| v.parse().ok())
53        .unwrap_or(DEFAULT_SUBPROCESS_MEMORY_LIMIT_MB);
54    let max_bytes = max_mb * 1024 * 1024;
55    // SAFETY: pre_exec closure runs between fork() and exec() in the
56    // single-threaded child process — no other threads exist.
57    // libc::setsid and libc::setrlimit are async-signal-safe per POSIX.1-2008 §2.4.3.
58    // RLIMIT_AS limits virtual address space, not physical RSS.
59    // setsid failure with EPERM is tolerated (process already a session leader).
60    // On setrlimit failure, Err(last_os_error()) prevents exec.
61    unsafe {
62        cmd.pre_exec(move || {
63            let sid = libc::setsid();
64            if sid == -1 {
65                let err = std::io::Error::last_os_error();
66                if err.raw_os_error() != Some(libc::EPERM) {
67                    return Err(err);
68                }
69            }
70            let limit = libc::rlimit {
71                rlim_cur: max_bytes,
72                rlim_max: max_bytes,
73            };
74            if libc::setrlimit(libc::RLIMIT_AS, &limit) != 0 {
75                return Err(std::io::Error::last_os_error());
76            }
77            Ok(())
78        });
79    }
80    tracing::debug!(
81        target: "process",
82        program = ?cmd.get_program(),
83        args = ?cmd.get_args().collect::<Vec<_>>(),
84        "spawning external process"
85    );
86    cmd.spawn()
87}
88
89/// Spawns a command without memory limits (non-Linux fallback).
90/// On Unix (macOS, FreeBSD), applies setsid for process group isolation.
91#[cfg(not(target_os = "linux"))]
92pub fn spawn_with_memory_limit(cmd: &mut Command) -> std::io::Result<std::process::Child> {
93    #[cfg(unix)]
94    {
95        use std::os::unix::process::CommandExt;
96        // SAFETY: setsid() is async-signal-safe per POSIX.1-2008 §2.4.3.
97        // Creates independent session for cascade termination.
98        unsafe {
99            cmd.pre_exec(|| {
100                let sid = libc::setsid();
101                if sid == -1 {
102                    let err = std::io::Error::last_os_error();
103                    if err.raw_os_error() != Some(libc::EPERM) {
104                        return Err(err);
105                    }
106                }
107                Ok(())
108            });
109        }
110    }
111    tracing::debug!(
112        target: "process",
113        program = ?cmd.get_program(),
114        args = ?cmd.get_args().collect::<Vec<_>>(),
115        "spawning external process"
116    );
117    cmd.spawn()
118}
119
120/// Parsed output element from `claude -p --output-format json`.
121#[derive(Debug, serde::Deserialize)]
122pub struct ClaudeOutputElement {
123    pub r#type: Option<String>,
124    pub subtype: Option<String>,
125    #[serde(default)]
126    pub is_error: bool,
127    pub structured_output: Option<serde_json::Value>,
128    pub result: Option<String>,
129    pub total_cost_usd: Option<f64>,
130    pub error: Option<String>,
131    pub terminal_reason: Option<String>,
132    #[serde(rename = "apiKeySource")]
133    pub api_key_source: Option<String>,
134}
135
136/// Result of a successful Claude invocation.
137#[derive(Debug)]
138pub struct ClaudeResult {
139    pub value: serde_json::Value,
140    pub cost_usd: f64,
141    pub is_oauth: bool,
142}
143
144/// Validates that the Claude binary meets the minimum version requirement.
145pub fn validate_claude_version(binary: &Path) -> Result<String, AppError> {
146    let resolved = which::which(binary).map_err(|_| {
147        AppError::Validation(format!(
148            "executable '{}' not found in PATH; ensure it is installed and accessible",
149            binary.display()
150        ))
151    })?;
152    let output = Command::new(&resolved)
153        .arg("--version")
154        .stdin(Stdio::null())
155        .stdout(Stdio::piped())
156        .stderr(Stdio::piped())
157        .output()
158        .map_err(AppError::Io)?;
159
160    if !output.status.success() {
161        return Err(AppError::Validation(
162            "failed to run 'claude --version'".to_string(),
163        ));
164    }
165
166    let version_str = String::from_utf8(output.stdout)
167        .map_err(|_| AppError::Validation("claude --version output is not UTF-8".to_string()))?;
168    let version = version_str.trim().to_string();
169    let numeric = version.split([' ', '(']).next().unwrap_or("").trim();
170
171    fn parse_semver(s: &str) -> Option<(u64, u64, u64)> {
172        let parts: Vec<&str> = s.splitn(3, '.').collect();
173        if parts.len() < 2 {
174            return None;
175        }
176        let major = parts[0].parse::<u64>().ok()?;
177        let minor = parts[1].parse::<u64>().ok()?;
178        let patch = parts
179            .get(2)
180            .and_then(|p| p.parse::<u64>().ok())
181            .unwrap_or(0);
182        Some((major, minor, patch))
183    }
184
185    if let (Some(actual), Some(min)) = (parse_semver(numeric), parse_semver(MIN_CLAUDE_VERSION)) {
186        if actual < min {
187            return Err(AppError::Validation(format!(
188                "Claude Code version {numeric} is below minimum required {MIN_CLAUDE_VERSION}"
189            )));
190        }
191    }
192
193    Ok(version)
194}
195
196/// Builds a `Command` for `claude -p` with least-privilege environment.
197///
198/// G28-A (v1.0.68) + OAuth-only hardening (v1.0.69, mandated by gaps.md
199/// lines 41-49): the command ALWAYS uses the OAuth flow. The flag set
200/// is the canonical one documented in gaps.md Fix A:
201///
202/// ```text
203/// claude -p "TAREFA" \
204///   --strict-mcp-config \
205///   --mcp-config '{}' \
206///   --dangerously-skip-permissions \
207///   --settings '{"hooks":{}}' \
208///   --model <X> \
209///   --max-turns <N> \
210///   --output-format json \
211///   --no-session-persistence
212/// ```
213///
214/// The combination cuts the typical 8-10 MCP process tree to zero and
215/// disables user hooks. The reaper sweep at startup (see `reaper::scan_and_kill_orphans`)
216/// is the last line of defence for any process that ignored the flags.
217///
218/// **`--bare` is FORBIDDEN** (gaps.md:49 and operator policy):
219/// `--bare` cuts MCPs but disables OAuth and demands `ANTHROPIC_API_KEY`,
220/// which is PROHIBITED in this project. We also ABORT the spawn if
221/// `ANTHROPIC_API_KEY` is set in the environment, because that is the
222/// gateway to the prohibited API-key path.
223///
224/// GitHub issue [anthropics/claude-code#10787] documents that earlier
225/// Claude Code CLI builds sometimes ignored `--strict-mcp-config` and
226/// fell back to `~/.mcp.json`. We still pass the flags as defence-in-depth
227/// and ALSO honour `SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR` so users
228/// who need belt-and-suspenders isolation can point Claude at an empty
229/// config directory (no MCP, no hooks, no settings).
230///
231/// [anthropics/claude-code#10787]: https://github.com/anthropics/claude-code/issues/10787
232pub fn build_claude_command(
233    binary: &Path,
234    prompt: &str,
235    json_schema: &str,
236    model: Option<&str>,
237    max_turns: u32,
238) -> Result<Command, crate::errors::AppError> {
239    // OAuth-only guard (gaps.md:47, ADR-0011). If `ANTHROPIC_API_KEY` is
240    // set in the environment we MUST abort — that is the API-key path
241    // which is explicitly PROHIBITED. Use the OAuth flow exclusively.
242    if let Ok(_key) = std::env::var("ANTHROPIC_API_KEY") {
243        // Return a command that will fail loudly at spawn time. We
244        // intentionally do NOT pass `--bare` (PROHIBITED) and we do NOT
245        // allow the API-key path at all. The second marker arg is the
246        // orientative hint surfaced via the diagnostic pipeline (ADR-0041).
247        let mut cmd = Command::new("false");
248        cmd.env_clear();
249        cmd.env("PATH", "/nonexistent");
250        cmd.arg("--oauth-only-violation-anthropic-api-key-set");
251        cmd.arg("--oauth-only-resolution-use-anthropic-auth-token");
252        return Ok(cmd);
253    }
254
255    let mut cmd = Command::new(binary);
256
257    // v1.0.83 (ADR-0041): env whitelist delegated to
258    // `crate::spawn::env_whitelist::apply_env_whitelist`. The single source of
259    // truth lives in `src/spawn/env_whitelist.rs`; do NOT reintroduce a
260    // local whitelist here.
261    apply_env_whitelist(&mut cmd, crate::spawn::env_whitelist::is_strict_env_clear());
262    crate::spawn::apply_cwd_isolation(&mut cmd)?;
263
264    // Canonical OAuth-only command line (gaps.md:201-208). Every flag is
265    // mandatory; do NOT pass `--bare` (PROHIBITED, gaps.md:49).
266    //
267    // GAP-META-005 (v1.0.87, ADR-0045): `--mcp-config '{}'` inline JSON is
268    // rejected by Claude Code 2.1.177 — the flag expects a filepath.
269    // Substitute the inline literal for a tempfile path containing
270    // `{"mcpServers":{}}`. The pre-flight check rejects the inline form
271    // when `mcp_config_inline_json: Some("{}")` is passed.
272    let mcp_config_path = crate::spawn::preflight::write_empty_mcp_config_tempfile()?;
273
274    cmd.arg("-p")
275        .arg(prompt)
276        .arg("--strict-mcp-config")
277        .arg("--mcp-config")
278        .arg(mcp_config_path.as_os_str())
279        .arg("--dangerously-skip-permissions")
280        .arg("--settings")
281        .arg(r#"{"hooks":{}}"#)
282        .arg("--output-format")
283        .arg("json")
284        .arg("--json-schema")
285        .arg(json_schema)
286        .arg("--max-turns")
287        .arg(max_turns.to_string())
288        .arg("--no-session-persistence");
289
290    if let Some(m) = model {
291        cmd.arg("--model").arg(m);
292    }
293
294    cmd.stdin(Stdio::null())
295        .stdout(Stdio::piped())
296        .stderr(Stdio::piped());
297
298    // GAP-META-005 (v1.0.87, ADR-0045): pre-flight validation gate runs
299    // AFTER argv is fully built so binary, argv-size, walk-up of
300    // `.mcp.json`, and `CLAUDE_CONFIG_DIR` cleanliness are all checked.
301    // Pre-flight failure is a configuration error — panic with a clear
302    // message rather than spawn a misconfigured subprocess.
303    let argv_refs: Vec<std::ffi::OsString> = cmd.get_args().map(|s| s.to_os_string()).collect();
304    let preflight_args = crate::spawn::preflight::PreFlightArgs {
305        binary_path: binary,
306        argv: &argv_refs,
307        workspace_root: std::path::Path::new("."),
308        mcp_config_inline_json: None,
309        expected_output_bytes: 65_536,
310        spawner_name: "claude_runner",
311    };
312    if let Err(e) = crate::spawn::preflight::preflight_check(&preflight_args) {
313        // v1.0.88 (BUG-6 fix, ADR-0046): propagate the structured
314        // `PreFlightError` via the `From` impl in `errors.rs` so callers
315        // receive `AppError::PreFlightFailed` (exit 16) instead of a
316        // bare `std::process::exit(16)` that discards the variant name,
317        // tracing context, and PT-BR i18n.
318        return Err(crate::errors::AppError::from(e));
319    }
320
321    Ok(cmd)
322}
323
324/// Parses `claude -p --output-format json` output array.
325///
326/// G03: detects `terminal_reason: "max_turns"` and returns a specific error
327/// instead of a generic failure message.
328pub fn parse_claude_output(stdout: &str) -> Result<ClaudeResult, AppError> {
329    let elements: Vec<ClaudeOutputElement> = serde_json::from_str(stdout).map_err(|e| {
330        AppError::Validation(format!("failed to parse claude output as JSON array: {e}"))
331    })?;
332
333    let is_oauth = elements
334        .iter()
335        .find(|e| e.r#type.as_deref() == Some("system") && e.subtype.as_deref() == Some("init"))
336        .and_then(|e| e.api_key_source.as_deref())
337        .map(|s| s == "none")
338        .unwrap_or(false);
339
340    let result_elem = elements
341        .iter()
342        .find(|e| e.r#type.as_deref() == Some("result"))
343        .ok_or_else(|| {
344            AppError::Validation("claude output missing 'result' element".to_string())
345        })?;
346
347    // G03: detect max_turns exhaustion before checking is_error
348    if result_elem.terminal_reason.as_deref() == Some("max_turns") {
349        tracing::warn!(
350            target: "claude_runner",
351            "claude -p hit max_turns limit — hooks may have consumed turns"
352        );
353        return Err(AppError::Validation(
354            "claude -p hit max_turns: hooks may be consuming turns; increase --max-turns or disable hooks".to_string(),
355        ));
356    }
357
358    if result_elem.is_error {
359        let err_msg = result_elem
360            .error
361            .as_deref()
362            .or(result_elem.result.as_deref())
363            .unwrap_or("unknown error");
364        if err_msg.contains("rate_limit") || err_msg.contains("overloaded") {
365            return Err(AppError::RateLimited {
366                detail: err_msg.to_string(),
367            });
368        }
369        if err_msg.contains("Not logged in") || err_msg.contains("authentication") {
370            tracing::warn!(
371                target: "claude_runner",
372                "Claude Code authentication failed. Re-authenticate interactively with: claude"
373            );
374        }
375        return Err(AppError::Validation(format!(
376            "claude extraction failed: {err_msg}"
377        )));
378    }
379
380    let value = if let Some(v) = result_elem.structured_output.clone() {
381        v
382    } else if let Some(text) = &result_elem.result {
383        serde_json::from_str(text).map_err(|e| {
384            AppError::Validation(format!("failed to parse claude result field as JSON: {e}"))
385        })?
386    } else {
387        return Err(AppError::Validation(
388            "claude result missing structured_output and result field".into(),
389        ));
390    };
391
392    let cost = result_elem.total_cost_usd.unwrap_or(0.0);
393    Ok(ClaudeResult {
394        value,
395        cost_usd: cost,
396        is_oauth,
397    })
398}
399
400/// Calls `claude -p` with prompt and schema, waits with timeout, and parses output.
401///
402/// G03: parses stdout even on non-zero exit to detect `terminal_reason: "max_turns"`.
403/// G28-C (v1.0.69): the child is killed explicitly on timeout to avoid
404/// leaving a `claude -p` zombie with its MCP children behind.
405pub fn run_claude(
406    binary: &Path,
407    prompt: &str,
408    json_schema: &str,
409    input_text: &str,
410    model: Option<&str>,
411    timeout_secs: u64,
412    max_turns: u32,
413) -> Result<ClaudeResult, AppError> {
414    use wait_timeout::ChildExt;
415
416    let full_prompt = format!("{prompt}\n\n{input_text}");
417    let mut cmd = build_claude_command(binary, &full_prompt, json_schema, model, max_turns)?;
418
419    let mut child = spawn_with_memory_limit(&mut cmd).map_err(|e| {
420        AppError::Io(std::io::Error::new(
421            e.kind(),
422            format!("failed to spawn claude: {e}"),
423        ))
424    })?;
425
426    let start = std::time::Instant::now();
427    let timeout = std::time::Duration::from_secs(timeout_secs);
428    let status = child.wait_timeout(timeout).map_err(AppError::Io)?;
429
430    if status.is_none() {
431        // G28-C: timeout hit — send SIGTERM to the child so the MCP
432        // children it spawned (and their npm/node tree) are also
433        // reaped. SIGTERM gives the child a chance to clean up; the
434        // reaper sweep in main.rs is the last line of defence for
435        // anything that ignored it.
436        #[cfg(unix)]
437        unsafe {
438            libc::kill(child.id() as i32, libc::SIGTERM);
439        }
440        let _ = child.kill();
441        let _ = child.wait();
442    }
443
444    match status {
445        Some(exit_status) => {
446            tracing::debug!(
447                target: "process",
448                exit_code = ?exit_status.code(),
449                elapsed_ms = start.elapsed().as_millis() as u64,
450                "external process completed"
451            );
452
453            let mut stdout_buf = Vec::new();
454            let mut stderr_buf = Vec::new();
455            if let Some(mut out) = child.stdout.take() {
456                std::io::Read::read_to_end(&mut out, &mut stdout_buf).map_err(AppError::Io)?;
457            }
458            if let Some(mut err) = child.stderr.take() {
459                std::io::Read::read_to_end(&mut err, &mut stderr_buf).map_err(AppError::Io)?;
460            }
461
462            let stdout_str = String::from_utf8(stdout_buf)
463                .map_err(|_| AppError::Validation("claude -p stdout is not valid UTF-8".into()))?;
464
465            // G03: parse stdout even on failure to detect terminal_reason
466            if !exit_status.success() {
467                if let Ok(result) = parse_claude_output(&stdout_str) {
468                    return Ok(result);
469                }
470                let stderr_str = String::from_utf8_lossy(&stderr_buf);
471                if stderr_str.contains("auth") || stderr_str.contains("login") {
472                    tracing::warn!(
473                        target: "claude_runner",
474                        "Claude Code authentication may have failed. Re-authenticate with: claude"
475                    );
476                }
477                return Err(AppError::Validation(format!(
478                    "claude -p exited with code {:?}: {}",
479                    exit_status.code(),
480                    stderr_str.trim()
481                )));
482            }
483
484            parse_claude_output(&stdout_str)
485        }
486        None => {
487            tracing::warn!(target: "claude_runner", timeout_secs, "claude -p timed out, terminating");
488            terminate_gracefully(&mut child, 3);
489            Err(AppError::Validation(format!(
490                "claude -p timed out after {timeout_secs} seconds"
491            )))
492        }
493    }
494}
495
496/// Terminates a child process gracefully: SIGTERM first, SIGKILL after grace period.
497#[cfg(unix)]
498pub fn terminate_gracefully(child: &mut std::process::Child, grace_secs: u64) {
499    use wait_timeout::ChildExt;
500    unsafe {
501        libc::kill(child.id() as i32, libc::SIGTERM);
502    }
503    match child.wait_timeout(std::time::Duration::from_secs(grace_secs)) {
504        Ok(Some(_)) => {}
505        _ => {
506            tracing::warn!(target: "process", pid = child.id(), "child ignored SIGTERM, sending SIGKILL");
507            let _ = child.kill();
508            let _ = child.wait();
509        }
510    }
511}
512
513/// Non-Unix fallback: kill immediately (Windows TerminateProcess).
514#[cfg(not(unix))]
515pub fn terminate_gracefully(child: &mut std::process::Child, _grace_secs: u64) {
516    let _ = child.kill();
517    let _ = child.wait();
518}
519
520#[cfg(test)]
521mod tests {
522    use super::*;
523
524    #[test]
525    fn parse_output_detects_max_turns() {
526        let stdout = r#"[{"type":"system","subtype":"init","apiKeySource":"none"},{"type":"result","is_error":false,"terminal_reason":"max_turns","structured_output":{"name":"t"}}]"#;
527        let err = parse_claude_output(stdout).unwrap_err();
528        assert!(
529            format!("{err}").contains("max_turns"),
530            "must detect max_turns in output"
531        );
532    }
533
534    #[test]
535    fn parse_output_extracts_structured_value() {
536        let stdout = r#"[{"type":"system","subtype":"init","apiKeySource":"none"},{"type":"result","is_error":false,"structured_output":{"key":"val"},"total_cost_usd":0.01}]"#;
537        let result = parse_claude_output(stdout).unwrap();
538        assert_eq!(result.value["key"], "val");
539        assert!((result.cost_usd - 0.01).abs() < f64::EPSILON);
540        assert!(result.is_oauth);
541    }
542
543    #[test]
544    fn parse_output_detects_rate_limit() {
545        let stdout = r#"[{"type":"result","is_error":true,"error":"rate_limit exceeded"}]"#;
546        let err = parse_claude_output(stdout).unwrap_err();
547        assert!(
548            matches!(err, AppError::RateLimited { .. }),
549            "expected AppError::RateLimited, got: {err}"
550        );
551    }
552
553    /// OAuth-only conformance test (gaps.md:41-49, v1.0.69 mandate).
554    /// Verifies that `build_claude_command` always emits the canonical
555    /// flag set and NEVER emits `--bare` or any API-key path.
556    #[test]
557    #[serial_test::serial(env)]
558    fn build_command_oauth_only_mandatory_flags() {
559        // SAFETY: this is a unit test, no concurrent env mutation
560        unsafe {
561            std::env::remove_var("ANTHROPIC_API_KEY");
562            // GAP-META-005 (v1.0.87): clear CLAUDE_CONFIG_DIR so the new
563            // pre-flight check does not exit 16 on the test host.
564            std::env::remove_var("CLAUDE_CONFIG_DIR");
565        }
566        let cmd = build_claude_command(
567            std::path::Path::new("/usr/bin/false"),
568            "test prompt",
569            "{}",
570            Some("sonnet"),
571            4,
572        )
573        .expect("preflight gate accepts valid args");
574        let args: Vec<&str> = cmd.get_args().filter_map(|a| a.to_str()).collect();
575        // Mandatory OAuth-only flags from gaps.md lines 201-208
576        assert!(args.contains(&"-p"), "must have -p");
577        assert!(
578            args.contains(&"--strict-mcp-config"),
579            "must have --strict-mcp-config (gaps.md:206)"
580        );
581        assert!(
582            args.contains(&"--mcp-config"),
583            "must have --mcp-config (gaps.md:207)"
584        );
585        assert!(
586            args.contains(&"--dangerously-skip-permissions"),
587            "must have --dangerously-skip-permissions (gaps.md:208)"
588        );
589        assert!(
590            args.contains(&"--settings"),
591            "must have --settings (gaps.md:209)"
592        );
593        assert!(
594            args.contains(&"--output-format"),
595            "must have --output-format json (gaps.md:213)"
596        );
597        assert!(args.contains(&"--json-schema"), "must have --json-schema");
598        assert!(
599            args.contains(&"--max-turns"),
600            "must have --max-turns (gaps.md:212)"
601        );
602        assert!(
603            args.contains(&"--no-session-persistence"),
604            "must have --no-session-persistence"
605        );
606        assert!(
607            args.contains(&"--model"),
608            "must have --model when model is Some"
609        );
610        // PROHIBITED flags (gaps.md:49)
611        assert!(
612            !args.contains(&"--bare"),
613            "--bare is PROHIBITED (gaps.md:49)"
614        );
615    }
616
617    /// OAuth-only guard: when `ANTHROPIC_API_KEY` is in the environment,
618    /// `build_claude_command` MUST abort the spawn (return a `false`
619    /// command), NOT silently fall back to the API-key path.
620    #[test]
621    #[serial_test::serial(env)]
622    fn build_command_aborts_when_anthropic_api_key_set() {
623        // SAFETY: unit test
624        unsafe {
625            std::env::set_var("ANTHROPIC_API_KEY", "sk-test-violation");
626            // GAP-META-005 (v1.0.87): clear CLAUDE_CONFIG_DIR so the
627            // pre-flight check (when it does run on the abort path)
628            // does not exit 16 prematurely.
629            std::env::remove_var("CLAUDE_CONFIG_DIR");
630        }
631        let cmd = build_claude_command(
632            std::path::Path::new("/usr/bin/claude"),
633            "test prompt",
634            "{}",
635            Some("sonnet"),
636            4,
637        )
638        .expect("preflight gate accepts valid args");
639        let program = cmd.get_program().to_string_lossy().to_string();
640        let args: Vec<&str> = cmd.get_args().filter_map(|a| a.to_str()).collect();
641        assert_eq!(
642            program, "false",
643            "when ANTHROPIC_API_KEY is set, build_claude_command must abort"
644        );
645        assert!(
646            args.contains(&"--oauth-only-violation-anthropic-api-key-set"),
647            "aborted command must carry violation marker"
648        );
649        unsafe {
650            std::env::remove_var("ANTHROPIC_API_KEY");
651        }
652    }
653}
sqlite_graphrag/commands/claude_runner.rs

sqlite_graphrag/commands/
claude_runner.rs
