harn-vm 0.10.166

//! Workspace-effect classification for tool-batch phase planning.
//!
//! The agent loop groups a tool batch into phases so that observations run
//! before the mutations they justify. That ordering is only sound if
//! "observation" means *this command does not change the workspace*.
//!
//! The obvious shortcut is to ask the command risk scanner and treat "nothing
//! alarming" as "does not write". That is wrong, and wrong in the unsafe
//! direction: the scanner answers "is this dangerous", not "does this write".
//! `rm src/foo.rs`, `mv a b`, `cp a b`, `git add -A`, `cargo build`,
//! and `make` all clear the danger scanner — none of them is catastrophic, a
//! whole-tree wipe, or an output redirect — yet every one of them mutates the
//! workspace. Classifying them as observations would let a batch run a
//! deletion before the read that was supposed to justify it.
//!
//! So the decision is an allowlist, not a denylist. A command is a read effect
//! only when every stage it runs is a program known to be read-only, nothing
//! redirects to a file, and the scanner is independently happy. Anything the
//! allowlist does not recognize is `unknown`, which keeps it out of the
//! observation phase. New read-only tooling is a one-line data edit here; the
//! cost of forgetting is a missed batching opportunity, never a reordered
//! mutation.

use serde_json::Value as JsonValue;

use crate::value::{VmError, VmValue};

use super::command_risk_scan_json;
use super::scan::{command_text, risk_labels_from_scan, security_command_analysis};

/// Risk labels that positively establish a workspace write.
///
/// Presence proves a write; absence proves nothing, which is the whole reason
/// this module does not stop here.
const WORKSPACE_WRITE_LABELS: [&str; 3] = ["catastrophic", "destructive", "write_intent"];

/// Programs whose every invocation only reads.
///
/// Deliberately excludes build and package tooling (`cargo`, `make`, `npm`,
/// `pnpm`, `go`, `pytest`): those write target directories, lockfiles, and
/// caches even when the user thinks of them as "just checking".
const READ_ONLY_PROGRAMS: &[&str] = &[
    "basename",
    "cat",
    "cksum",
    "cmp",
    "column",
    "comm",
    "cut",
    "df",
    "diff",
    "dirname",
    "du",
    "echo",
    "expr",
    "grep",
    "head",
    "id",
    "jq",
    "ls",
    "md5sum",
    "nl",
    "od",
    "pgrep",
    "printenv",
    "printf",
    "ps",
    "pwd",
    "readlink",
    "realpath",
    "seq",
    "sha1sum",
    "sha256sum",
    "stat",
    "tail",
    "tr",
    "type",
    "uname",
    "wc",
    "which",
    "whoami",
];

/// Subcommand-dispatching programs and the subcommands that only read.
///
/// `git status` reads; `git checkout` writes. The program name alone cannot
/// answer the question, so these are resolved on argv[1].
const READ_ONLY_SUBCOMMANDS: &[(&str, &[&str])] = &[(
    "git",
    &[
        "blame",
        "branch",
        "cat-file",
        "config",
        "describe",
        "diff",
        "grep",
        "log",
        "ls-files",
        "ls-tree",
        "rev-list",
        "rev-parse",
        "shortlog",
        "show",
        "show-ref",
        "status",
        "tag",
        "whatchanged",
    ],
)];

/// `git config --get x` reads; `git config x y` writes. `git branch` lists;
/// `git branch -d` deletes. `git tag` lists; `git tag v1` creates. For these,
/// a bare or explicitly-reading invocation is a read and everything else is
/// not.
fn subcommand_is_read_only(program: &str, subcommand: &str, rest: &[String]) -> bool {
    if rest.iter().any(|arg| {
        arg == "--output"
            || arg.starts_with("--output=")
            || arg == "--ext-diff"
            || arg == "--textconv"
            || arg == "--open-files-in-pager"
            || arg.starts_with("--open-files-in-pager=")
    }) {
        return false;
    }
    match (program, subcommand) {
        ("git", "config") => rest.iter().any(|arg| {
            matches!(
                arg.as_str(),
                "--get" | "--get-all" | "--get-regexp" | "--get-urlmatch" | "--list" | "-l"
            )
        }),
        ("git", "branch") | ("git", "tag") => rest.iter().all(|arg| {
            matches!(
                arg.as_str(),
                "-a" | "--all"
                    | "-l"
                    | "--list"
                    | "-v"
                    | "-vv"
                    | "--verbose"
                    | "--merged"
                    | "--no-merged"
                    | "-r"
                    | "--remotes"
                    | "--show-current"
            )
        }),
        _ => true,
    }
}

/// Some generally read-shaped programs have an explicit execution or output
/// mode. Keep those option grammars beside the allowlist instead of pretending
/// every invocation of the binary has the same effect.
fn standalone_program_is_read_only(program: &str, args: &[String]) -> bool {
    match program {
        "rg" => !args
            .iter()
            .any(|arg| arg == "--pre" || arg.starts_with("--pre=")),
        "sort" => !args.iter().any(|arg| {
            arg == "-o"
                || arg == "--output"
                || arg.starts_with("--output=")
                || arg == "--compress-program"
                || arg.starts_with("--compress-program=")
        }),
        "tree" => !args
            .iter()
            .any(|arg| arg == "-o" || arg.starts_with("--output=")),
        "sed" => sed_invocation_is_read_only(args),
        "yq" => !args.iter().any(|arg| {
            arg == "-i"
                || arg == "--inplace"
                || arg == "--split-exp"
                || arg.starts_with("--split-exp=")
                || arg == "--split-exp-file"
                || arg.starts_with("--split-exp-file=")
        }),
        _ => READ_ONLY_PROGRAMS.contains(&program),
    }
}

/// `sed -n '1,105p' file` reads; `sed -i`, a `w file` command, or an `e`
/// command writes or executes. Only a script of line-addressed print, delete,
/// quit, line-number, and list commands is a read, and only without an
/// in-place flag or a script file. Everything else stays unrecognized.
fn sed_invocation_is_read_only(args: &[String]) -> bool {
    let mut scripts: Vec<&str> = Vec::new();
    let mut expect_script = false;
    let mut first_operand_is_script = true;
    for arg in args {
        if expect_script {
            scripts.push(arg);
            expect_script = false;
            continue;
        }
        match arg.as_str() {
            "-n" | "--quiet" | "--silent" | "-E" | "-r" | "--regexp-extended" | "-s"
            | "--separate" | "-u" | "--unbuffered" | "-z" | "--null-data" | "--posix" => {}
            "-e" | "--expression" => {
                expect_script = true;
                first_operand_is_script = false;
            }
            value if value.starts_with("--expression=") => {
                scripts.push(value.strip_prefix("--expression=").unwrap_or_default());
                first_operand_is_script = false;
            }
            value if value.starts_with('-') && value.len() > 1 => return false,
            value => {
                if first_operand_is_script {
                    scripts.push(value);
                    first_operand_is_script = false;
                }
            }
        }
    }
    !expect_script
        && !scripts.is_empty()
        && scripts.iter().all(|script| sed_script_is_read_only(script))
}

/// One sed script, `;`- or newline-separated, of `[addr[,addr]]cmd` pieces
/// where each address is a line number or `$` and `cmd` is `p`, `d`, `q`, `=`,
/// or `l` with no argument.
fn sed_script_is_read_only(script: &str) -> bool {
    let address = |text: &str| -> bool {
        let text = text.trim();
        text == "$" || (!text.is_empty() && text.chars().all(|c| c.is_ascii_digit()))
    };
    let mut saw_command = false;
    for piece in script.split([';', '\n']) {
        let piece = piece.trim();
        if piece.is_empty() {
            continue;
        }
        let Some(command) = piece.chars().last() else {
            return false;
        };
        if !matches!(command, 'p' | 'd' | 'q' | '=' | 'l') {
            return false;
        }
        let addresses = piece.strip_suffix(command).unwrap_or_default().trim();
        if !addresses.is_empty() && !addresses.split(',').all(address) {
            return false;
        }
        if addresses.split(',').count() > 2 {
            return false;
        }
        saw_command = true;
    }
    saw_command
}

fn program_basename(argv0: &str) -> &str {
    argv0
        .rsplit(['/', '\\'])
        .next()
        .unwrap_or(argv0)
        .trim_end_matches(".exe")
}

/// Whether one parsed stage of a pipeline only reads.
fn stage_is_read_only(words: &[String], dynamic: &[bool]) -> bool {
    if words.is_empty() || dynamic.iter().any(|value| *value) {
        return false;
    }
    let program = program_basename(&words[0]);
    if standalone_program_is_read_only(program, &words[1..]) {
        return true;
    }
    if let Some((_, subcommands)) = READ_ONLY_SUBCOMMANDS
        .iter()
        .find(|(name, _)| *name == program)
    {
        // Skip global flags to find the subcommand (`git -C dir status`).
        let mut index = 1;
        while index < words.len() {
            let word = &words[index];
            if word == "-C" || word == "--git-dir" || word == "--work-tree" {
                index += 2;
                continue;
            }
            if word.starts_with('-') {
                index += 1;
                continue;
            }
            break;
        }
        let Some(subcommand) = words.get(index) else {
            return false;
        };
        return subcommands.contains(&subcommand.as_str())
            && subcommand_is_read_only(program, subcommand, &words[index + 1..]);
    }
    false
}

/// Workspace-effect class used by tool-batch phase planning.
///
/// `read_effect` means every stage is a recognized read-only program, so the
/// call can share an observation batch. `write_effect` means a write was
/// positively established. `unknown` covers everything else, including
/// commands that are merely unrecognized — those stay out of the observation
/// phase rather than being assumed harmless.
pub fn command_workspace_effect_json(ctx: &JsonValue) -> JsonValue {
    let command = command_text(ctx);
    if command.trim().is_empty() {
        return serde_json::json!({
            "effect": "unknown",
            "risk_labels": [],
        });
    }
    let scan = command_risk_scan_json(ctx, None);
    let labels = risk_labels_from_scan(&scan);
    if labels
        .iter()
        .any(|label| WORKSPACE_WRITE_LABELS.contains(&label.as_str()))
    {
        return serde_json::json!({
            "effect": "write_effect",
            "risk_labels": labels,
        });
    }
    let recommended = scan
        .get("recommended_action")
        .and_then(JsonValue::as_str)
        .unwrap_or("deny");
    // Consume the same typed argv/shell-AST boundary as the command safety
    // policy. The display-oriented `shell_command_groups` projection flattens
    // argv and cannot prove whether metacharacters were syntax or literals.
    let analysis = security_command_analysis(ctx);
    let parsed_any = !analysis.stages.is_empty();
    let all_resolved = !analysis.unresolved
        && analysis
            .stages
            .iter()
            .all(|stage| stage_is_read_only(&stage.argv, &stage.dynamic));
    let no_file_writes = analysis
        .redirects
        .iter()
        .all(|redirect| !redirect.writes_file());
    let effect = if recommended == "allow" && parsed_any && all_resolved && no_file_writes {
        "read_effect"
    } else {
        "unknown"
    };
    serde_json::json!({
        "effect": effect,
        "risk_labels": labels,
    })
}

pub fn command_workspace_effect_value(ctx: &VmValue) -> Result<VmValue, VmError> {
    let json = crate::llm::vm_value_to_json(ctx);
    Ok(crate::stdlib::json_to_vm_value(
        &command_workspace_effect_json(&json),
    ))
}

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

    #[test]
    fn powershell_sed_reads_resolve() {
        for command in [
            "sed -n '1,105p' src/lib.rs",
            "sed -n -e 10p -e '$p' notes.md",
            "sed -n '5,$p;$=' a.txt",
            "sed 3q README.md",
            "git status --short; sed -n '1,105p' src/lib.rs; rg -n 'raw_tool_calls|tool_calls' src/*.rs | head -90",
        ] {
            let ctx = serde_json::json!({"request": {
                "command": command,
                "shell": {"platform": "windows"},
            }});
            let analysis = security_command_analysis(&ctx);
            let scan = command_risk_scan_json(&ctx, None);
            assert!(!analysis.unresolved, "{command}: {analysis:?}");
            assert_eq!(scan["recommended_action"], "allow", "{command}: {scan}");
            assert_eq!(command_workspace_effect_json(&ctx)["effect"], "read_effect", "{command}");
        }
    }

    #[test]
    fn powershell_sed_writers_and_dynamic_scripts_are_not_reads() {
        for command in [
            "sed -i -n '1,105p' src/lib.rs",
            "sed -n '1w out.txt' src/lib.rs",
            "sed '1e date' src/lib.rs",
            "sed -n $script src/lib.rs",
            "sed -n '1,105p' src/lib.rs > out.txt",
            "sed -n '1,105p' src/lib.rs; some-unknown-tool",
        ] {
            let ctx = serde_json::json!({"request": {
                "command": command,
                "shell": {"platform": "windows"},
            }});
            assert_ne!(
                command_workspace_effect_json(&ctx)["effect"],
                "read_effect",
                "{command}"
            );
        }
    }

    #[test]
    fn cmd_preserves_single_quotes_in_sed_scripts() {
        let ctx = |command| {
            serde_json::json!({"request": {
                "command": command,
                "shell": {"id": "cmd", "platform": "windows"},
            }})
        };
        let quoted = ctx("sed -n '1,105p' src/lib.rs");
        let analysis = security_command_analysis(&quoted);
        assert!(!analysis.unresolved);
        assert_eq!(analysis.stages[0].argv[2], "'1,105p'");
        assert_eq!(
            command_risk_scan_json(&quoted, None)["recommended_action"],
            "allow"
        );
        assert_eq!(command_workspace_effect_json(&quoted)["effect"], "unknown");
        assert_eq!(
            command_workspace_effect_json(&ctx("sed -n \"1,105p\" src/lib.rs"))["effect"],
            "read_effect"
        );
    }

    #[cfg(windows)]
    #[test]
    fn windows_powershell_pipeline_chaining_stays_unresolved() {
        // The inbox PowerShell 5.1 parser rejects && with InvalidEndOfLine.
        // Tree-sitter accepts it, but must not override the native refusal.
        let ctx = serde_json::json!({"request": {
            "command": "git status --short && sed -n '1,105p' src/lib.rs",
            "shell": {"id": "powershell", "platform": "windows"},
        }});
        assert!(security_command_analysis(&ctx).unresolved);
        let scan = command_risk_scan_json(&ctx, None);
        assert_eq!(scan["recommended_action"], "require_approval");
        assert_eq!(
            scan["risk_labels"],
            serde_json::json!(["execution_semantics_unresolved"])
        );
        assert_eq!(command_workspace_effect_json(&ctx)["effect"], "unknown");
    }

    fn effect(command: &str) -> String {
        // These fixtures use POSIX quoting and operators. The Windows host
        // default can be cmd via COMSPEC, which preserves single quotes.
        let ctx = serde_json::json!({ "request": {
            "command": command,
            "shell": {"id": "sh", "platform": "unix"},
        } });
        command_workspace_effect_json(&ctx)["effect"]
            .as_str()
            .unwrap()
            .to_string()
    }

    #[test]
    fn read_only_probes_join_the_observation_phase() {
        for command in [
            "git status --short --branch",
            "git -C sub diff --stat",
            "git log --oneline -n 5",
            "ls -la src",
            "rg needle src",
            "cat Cargo.toml",
            "wc -l src/lib.rs",
        ] {
            assert_eq!(effect(command), "read_effect", "{command}");
        }
    }

    /// The regression this module exists for. Every one of these clears the
    /// danger scanner, so a risk-label proxy called them observations.
    #[test]
    fn quiet_workspace_writers_are_not_observations() {
        for command in [
            "rm src/foo.rs",
            "mv a b",
            "cp a b",
            "git add -A",
            "git commit -am wip",
            "cargo build",
            "cargo test --workspace",
            "make",
            "pnpm run lint",
            "sed -i s/a/b/ file",
        ] {
            assert_ne!(effect(command), "read_effect", "{command}");
        }
    }

    #[test]
    fn established_writes_are_write_effect() {
        for command in ["echo hi > file", "tee out.txt"] {
            assert_eq!(effect(command), "write_effect", "{command}");
        }
    }

    /// A line-range `sed` print is how agents page a file. A real agent session
    /// ran a compound read like the one below after a write, and it read as
    /// unknown, so a completion gate counted the look-around as verification.
    #[test]
    fn a_line_addressed_sed_print_is_a_read() {
        for command in [
            "sed -n '1,105p' src/lib.rs",
            "sed -n -e 10p -e '$p' notes.md",
            "sed -n '5,$p;$=' a.txt",
            "sed 3q README.md",
        ] {
            assert_eq!(effect(command), "read_effect", "{command}");
        }
    }

    /// POSIX compound syntax is analyzed identically on every host.
    #[test]
    fn a_compound_read_with_a_sed_print_is_a_read() {
        let command = "git status --short && sed -n '1,105p' scripts/lib/eval-trial-record.harn && rg -n 'raw_tool_calls|tool_calls' scripts/lib/eval-*.harn | head -90";
        assert_eq!(effect(command), "read_effect", "{command}");
    }

    /// Negative control: every way `sed` can write or run something stays out
    /// of the observation phase.
    #[test]
    fn a_sed_that_can_write_or_execute_is_not_a_read() {
        for command in [
            "sed -i s/a/b/ file",
            "sed -i.bak -n '1,5p' file",
            "sed --in-place -n 1p file",
            "sed -I '' -n 1p file",
            "sed -n '1,5w out.txt' in.txt",
            "sed -n '1w out.txt' in.txt",
            "sed 's/a/b/w out.txt' in.txt",
            "sed '1e date' in.txt",
            "sed -f script.sed in.txt",
            "sed 's/a/b/' in.txt",
            "sed -n '/needle/p' in.txt",
        ] {
            assert_ne!(effect(command), "read_effect", "{command}");
        }
    }

    #[test]
    fn unrecognized_commands_are_unknown_not_read() {
        assert_eq!(effect("some-unknown-tool --check"), "unknown");
    }

    #[test]
    fn a_pipeline_is_read_only_only_if_every_stage_is() {
        assert_eq!(effect("git status | wc -l"), "read_effect");
        assert_ne!(effect("git status | tee log.txt"), "read_effect");
    }

    #[test]
    fn workspace_effect_is_unknown_without_a_command() {
        let ctx = serde_json::json!({ "request": {} });
        assert_eq!(
            command_workspace_effect_json(&ctx)["effect"]
                .as_str()
                .unwrap(),
            "unknown"
        );
    }

    #[test]
    fn git_config_reads_only_when_it_reads() {
        assert_eq!(effect("git config --get user.name"), "read_effect");
        assert_ne!(effect("git config user.name someone"), "read_effect");
    }

    #[test]
    fn read_shaped_programs_cannot_hide_execution_or_output_modes() {
        for command in [
            "awk 'BEGIN { system(\"touch changed\") }'",
            "find . -exec touch changed ;",
            "env sh -c 'touch changed'",
            "rg --pre 'touch changed' needle .",
            "sort -o changed input",
            "sort --compress-program='touch changed' input",
            "tree -o changed",
            "yq -i '.x = 1' config.yaml",
            "yq --split-exp '.name' config.yaml",
            "uniq input changed",
            "xxd -r input.hex changed",
            "file -C magic",
            "date -s tomorrow",
            "hostname changed",
        ] {
            assert_ne!(effect(command), "read_effect", "{command}");
        }
    }

    #[test]
    fn git_read_subcommands_reject_file_output_and_external_execution() {
        for command in [
            "git diff --output=changed",
            "git log --output changed",
            "git show --ext-diff HEAD",
            "git grep --open-files-in-pager=touch needle",
            "git ls-remote --upload-pack='touch changed' .",
        ] {
            assert_ne!(effect(command), "read_effect", "{command}");
        }
    }

    #[test]
    fn nested_shell_writers_prevent_read_effect_classification() {
        for command in ["echo $(touch changed)", "printf '%s' `rm changed`"] {
            assert_ne!(effect(command), "read_effect", "{command}");
        }
    }
}