rho-coding-agent 1.38.1

//! Build argv for `claude -p` subagent runs.

use std::ffi::OsString;
use std::path::{Path, PathBuf};
use std::sync::LazyLock;

use rho_providers::{model::ReasoningLevelSet, reasoning::ReasoningLevel};

use crate::{agent::PromptPolicy, permission::PermissionMode};

/// File name for the materialized system prompt inside a run directory.
pub(crate) const SYSTEM_PROMPT_FILE_NAME: &str = "system-prompt.txt";

/// Claude Code `--permission-mode` values Rho will set on `claude -p`.
///
/// This is not Rho's [`PermissionMode`]. The names collide across products;
/// each variant is a deliberate Claude CLI contract:
/// - [`Self::Plan`] — Rho Plan (investigation / plan scaffolding)
/// - [`Self::BypassPermissions`] — Rho Bypass ("just run", no Claude prompts)
/// - [`Self::DontAsk`] — headless no-tools one-shots (advisor); never prompt,
///   never inject plan scaffolding, deny anything not already allowed
///
/// Claude classifier `auto` is intentionally absent because Rho's classifier
/// mode needs its own approval handler.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum ClaudePermissionMode {
    /// Claude `--permission-mode plan`.
    Plan,
    /// Claude `--permission-mode bypassPermissions`.
    BypassPermissions,
    /// Claude `--permission-mode dontAsk`. Headless runs that must not prompt.
    DontAsk,
}

impl ClaudePermissionMode {
    pub(crate) const fn as_cli_flag(self) -> &'static str {
        match self {
            Self::Plan => "plan",
            Self::BypassPermissions => "bypassPermissions",
            Self::DontAsk => "dontAsk",
        }
    }
}

/// Inputs needed to construct a Claude CLI spawn.
///
/// Model, tools, and inherit config come from the bound runtime contract, not
/// from re-interpreting parent provider/model config.
#[derive(Clone, Debug)]
pub(crate) struct ClaudeSpawnRequest {
    /// Agent system prompt policy. Spawn needs no other definition field, so a
    /// mismatched runtime cannot reach here.
    pub(crate) system_prompt: PromptPolicy,
    /// Claude `--model` value. `None` means omit the flag (Claude inherit).
    pub(crate) model: Option<String>,
    /// Full Claude tool entries from the definition (`Read`, `Bash(git *)`, …).
    pub(crate) tools: Vec<String>,
    pub(crate) inherit_claude_config: bool,
    /// Claude CLI permission mode. Not Rho's permission mode.
    pub(crate) permission_mode: ClaudePermissionMode,
    pub(crate) cwd: PathBuf,
    /// Soft turn cap emitted as `--max-turns`. Claude's flag is undocumented
    /// surface; callers should treat rejection of the flag as a hard error.
    pub(crate) max_turns: u64,
    /// Claude `--effort` value from definition `reasoning:`. `None` omits the flag.
    pub(crate) effort: Option<&'static str>,
    /// Whether the run leaves a resumable Claude session behind.
    pub(crate) session_persistence: SessionPersistence,
    /// Stdin framing. Delegated sessions use stream-json so parents can send
    /// follow-up turns; one-shot keeps plain text.
    pub(crate) input_format: ClaudeInputFormat,
}

/// How the Claude child reads its stdin prompt bytes.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum ClaudeInputFormat {
    /// Default `-p` text prompt. Stdin is closed after one write.
    Text,
    /// NDJSON user turns (`--input-format stream-json`). Stdin stays open for
    /// parent course-corrections until the drain closes it after a result.
    StreamJson,
}

/// Whether a `claude -p` run is worth keeping in Claude's session store.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum SessionPersistence {
    /// Keep the session so `claude --resume <id>` works. Delegated agent runs
    /// publish that id in their status file.
    Keep,
    /// Discard it. Rho's own one-shot calls have no resumable identity and
    /// would otherwise fill the user's session list with single-turn runs.
    Discard,
}

/// How the agent system prompt is applied on the Claude CLI.
///
/// Prompt text is never placed on argv. Session code writes a private file in
/// the run directory and passes `--system-prompt-file` /
/// `--append-system-prompt-file` (verified Claude Code flags).
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) enum SystemPromptPlan {
    /// Empty `PromptPolicy::Extend`: leave Claude's default system prompt alone.
    Omit,
    /// `PromptPolicy::Replace` body. Parser requires nonempty text.
    Replace(String),
    /// Nonempty `PromptPolicy::Extend` body appended to Claude's default.
    Extend(String),
}

impl SystemPromptPlan {
    pub(crate) fn file_flag(&self) -> Option<&'static str> {
        match self {
            Self::Omit => None,
            Self::Replace(_) => Some("--system-prompt-file"),
            Self::Extend(_) => Some("--append-system-prompt-file"),
        }
    }

    /// Flag that carries the prompt text on argv instead of in a file. Only
    /// safe for Rho's own constant prompts; see [`inline_prompt_args`].
    pub(crate) fn argv_flag(&self) -> Option<&'static str> {
        match self {
            Self::Omit => None,
            Self::Replace(_) => Some("--system-prompt"),
            Self::Extend(_) => Some("--append-system-prompt"),
        }
    }

    pub(crate) fn text(&self) -> Option<&str> {
        match self {
            Self::Omit => None,
            Self::Replace(text) | Self::Extend(text) => Some(text.as_str()),
        }
    }
}

/// The full spawn contract: argv is the only carrier of flag decisions, so
/// tests and production read the same values.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct ClaudeSpawnPlan {
    /// Argv without system-prompt flags. Call [`finalize_spawn_args`] to attach
    /// a materialized prompt file path when needed.
    pub(crate) args: Vec<String>,
    pub(crate) cwd: PathBuf,
    pub(crate) system_prompt: SystemPromptPlan,
}

#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub(crate) enum ClaudeSpawnError {
    #[error(
        "claude-cli agents cannot run in Auto or Supervised permission mode: \
claude -p cannot prompt for approval. Switch to Plan or Bypass, or change the agent."
    )]
    SupervisedUnsupported,
}

/// Failures while writing the private system-prompt file for a run.
#[derive(Debug, thiserror::Error)]
pub(crate) enum ClaudeSpawnMaterializeError {
    #[error("claude code: could not write system prompt file `{}`: {source}", crate::paths::display(.path))]
    Write {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },
}

/// Map Rho permission mode onto a Claude CLI permission mode.
///
/// Rho Bypass means "do not gate capabilities," so it maps to Claude
/// `bypassPermissions`, not Claude `auto` (classifier) or `dontAsk`
/// (allowlist-only deny). Callers that need `dontAsk` (no-tools one-shots) set
/// [`ClaudePermissionMode::DontAsk`] on the spawn request directly. Auto and
/// Supervised have no safe non-interactive counterpart, so spawn is refused.
pub(crate) fn map_permission_mode(
    mode: PermissionMode,
) -> Result<ClaudePermissionMode, ClaudeSpawnError> {
    match mode {
        PermissionMode::Bypass => Ok(ClaudePermissionMode::BypassPermissions),
        PermissionMode::Plan => Ok(ClaudePermissionMode::Plan),
        PermissionMode::Auto | PermissionMode::Supervised => {
            Err(ClaudeSpawnError::SupervisedUnsupported)
        }
    }
}

/// Map Rho `reasoning:` onto Claude `--effort`.
///
/// Claude accepts `low`, `medium`, `high`, `xhigh`, and `max`. Rho `off` and
/// `minimal` have no Claude counterpart, so they return `None` and callers
/// reject them at parse/bind time. Omit the field entirely to inherit Claude's
/// default effort.
pub(crate) fn claude_effort_flag(level: ReasoningLevel) -> Option<&'static str> {
    match level {
        ReasoningLevel::Off | ReasoningLevel::Minimal => None,
        ReasoningLevel::Low => Some("low"),
        ReasoningLevel::Medium => Some("medium"),
        ReasoningLevel::High => Some("high"),
        ReasoningLevel::Xhigh => Some("xhigh"),
        ReasoningLevel::Max => Some("max"),
    }
}

/// Reasoning levels a Claude run can actually be asked for, derived from
/// [`claude_effort_flag`] so the mapping is stated once.
pub(crate) static CLAUDE_EFFORT_LEVELS: LazyLock<ReasoningLevelSet> = LazyLock::new(|| {
    ReasoningLevelSet::new(
        ReasoningLevel::ALL
            .into_iter()
            .filter(|level| claude_effort_flag(*level).is_some())
            .collect(),
    )
});

/// Build argv for a Claude spawn. Infallible once the request carries a
/// resolved [`ClaudePermissionMode`] (Supervised is refused earlier by
/// [`map_permission_mode`]).
pub(crate) fn build_spawn_plan(request: &ClaudeSpawnRequest) -> ClaudeSpawnPlan {
    let permission_mode = request.permission_mode.as_cli_flag();
    let system_prompt = system_prompt_plan(&request.system_prompt);
    let setting_sources = if request.inherit_claude_config {
        "user,project,local"
    } else {
        "project"
    };

    // `--tools` controls availability from Claude's built-in set (base names).
    // `--allowedTools` carries every declared non-Task entry (bare names and
    // patterns) as separate argv items. Task is always denied so nested Claude
    // agents stay off.
    let tool_base_names = tool_base_names(&request.tools);
    let allowed_tool_entries = allowed_tool_entries(&request.tools);

    let mut args = vec![
        "-p".into(),
        "--output-format".into(),
        "stream-json".into(),
        "--verbose".into(),
        "--include-partial-messages".into(),
        "--permission-mode".into(),
        permission_mode.into(),
        "--disallowedTools".into(),
        "Task".into(),
        "--setting-sources".into(),
        setting_sources.into(),
        "--strict-mcp-config".into(),
    ];
    if matches!(request.input_format, ClaudeInputFormat::StreamJson) {
        // Keep stdin open for parent course-corrections. The drain encodes the
        // initial prompt and later parent messages as stream-json user turns.
        args.push("--input-format".into());
        args.push("stream-json".into());
    }
    // Bound model is already byte-for-byte; do not resolve aliases here.
    if let Some(model) = &request.model {
        args.push("--model".into());
        args.push(model.clone());
    }
    if let Some(effort) = request.effort {
        args.push("--effort".into());
        args.push(effort.into());
    }
    args.push("--max-turns".into());
    args.push(request.max_turns.to_string());

    match request.session_persistence {
        SessionPersistence::Discard => args.push("--no-session-persistence".into()),
        SessionPersistence::Keep => {}
    }

    // Always set `--tools`, including the explicit empty set, so Claude does
    // not inherit ambient built-in tool availability from user config.
    args.push("--tools".into());
    if tool_base_names.is_empty() {
        args.push(String::new());
    } else {
        // Base names are delimiter-safe (alphanumeric / _ / - only).
        args.push(tool_base_names.join(","));
    }

    if !allowed_tool_entries.is_empty() {
        // Variadic form: one argv element per entry so internal spaces such as
        // `Bash(git *)` round-trip. Commas inside a pattern are rejected at
        // parse time because the CLI also accepts comma-separated lists.
        args.push("--allowedTools".into());
        args.extend(allowed_tool_entries.iter().cloned());
    }

    ClaudeSpawnPlan {
        args,
        cwd: request.cwd.clone(),
        system_prompt,
    }
}

/// Write the system prompt (when present) next to the run status file and return
/// final argv. The prompt file is kept as a run artifact for diagnosis.
///
/// Claude Code accepts `--system-prompt-file` / `--append-system-prompt-file`
/// (verified via `claude --help` / missing-argument responses). Passing a path
/// keeps multiline prompt bytes out of shell/cmd argv while preserving exact
/// Replace vs Extend semantics. User prompt stays on stdin.
///
/// Args stay as [`OsString`] so native paths are not forced through lossy UTF-8
/// conversion. The path token is appended via [`Path::into_os_string`].
pub(crate) fn finalize_spawn_args(
    plan: &ClaudeSpawnPlan,
    output_file: &Path,
) -> Result<Vec<OsString>, ClaudeSpawnMaterializeError> {
    let mut args: Vec<OsString> = plan.args.iter().map(OsString::from).collect();
    let Some(flag) = plan.system_prompt.file_flag() else {
        return Ok(args);
    };
    let text = plan
        .system_prompt
        .text()
        .expect("file flag implies prompt text");
    let path = system_prompt_path(output_file);
    crate::config_writer::write_bytes_atomically(&path, text.as_bytes()).map_err(|source| {
        ClaudeSpawnMaterializeError::Write {
            path: path.clone(),
            source,
        }
    })?;
    args.push(OsString::from(flag));
    // Keep the native OsString path (no to_string_lossy). Exact private bytes
    // already live in the prompt file; argv only carries the path token.
    args.push(path.into_os_string());
    Ok(args)
}

/// Final argv with the system prompt carried on the command line.
///
/// Use only when the prompt is one of Rho's own constants. Argv is readable by
/// other processes, so any prompt built from user or workspace text must go
/// through [`finalize_spawn_args`] and its private file instead.
pub(crate) fn inline_prompt_args(plan: &ClaudeSpawnPlan) -> Vec<OsString> {
    let mut args: Vec<OsString> = plan.args.iter().map(OsString::from).collect();
    let Some(flag) = plan.system_prompt.argv_flag() else {
        return args;
    };
    let text = plan
        .system_prompt
        .text()
        .expect("argv flag implies prompt text");
    args.push(OsString::from(flag));
    args.push(OsString::from(text));
    args
}

fn system_prompt_plan(prompt: &PromptPolicy) -> SystemPromptPlan {
    match prompt {
        PromptPolicy::Replace(text) => SystemPromptPlan::Replace(text.clone()),
        PromptPolicy::Extend(text) if text.is_empty() => SystemPromptPlan::Omit,
        PromptPolicy::Extend(text) => SystemPromptPlan::Extend(text.clone()),
    }
}

/// Base Claude tool names for `--tools` availability.
fn tool_base_names(tools: &[String]) -> Vec<String> {
    let mut names = Vec::new();
    for tool in tools {
        let base = tool_base_name(tool);
        if base.eq_ignore_ascii_case("Task") {
            // Task is always denied separately; never make it available.
            continue;
        }
        if !names.iter().any(|existing| existing == base) {
            names.push(base.to_string());
        }
    }
    names
}

/// Every declared non-Task tool entry for `--allowedTools` (bare + patterns).
fn allowed_tool_entries(tools: &[String]) -> Vec<String> {
    tools
        .iter()
        .filter(|tool| !tool_base_name(tool).eq_ignore_ascii_case("Task"))
        .cloned()
        .collect()
}

fn tool_base_name(tool: &str) -> &str {
    tool.split_once('(').map_or(tool, |(base, _)| base)
}

/// True when stderr/stdout looks like Claude rejected `--max-turns`.
pub(crate) fn looks_like_max_turns_unsupported(text: &str) -> bool {
    let lower = text.to_ascii_lowercase();
    lower.contains("max-turns")
        && (lower.contains("unknown")
            || lower.contains("unexpected")
            || lower.contains("unrecognized")
            || lower.contains("invalid"))
}

pub(crate) fn log_path(output_file: &Path) -> PathBuf {
    output_file.with_file_name(crate::subagent::LOG_FILE_NAME)
}

pub(crate) fn system_prompt_path(output_file: &Path) -> PathBuf {
    output_file.with_file_name(SYSTEM_PROMPT_FILE_NAME)
}

#[cfg(test)]
#[path = "spawn_tests.rs"]
mod tests;