safe_chains/targets/

mod.rs

use std::path::{Path, PathBuf};

use crate::verdict::{SafetyLevel, Verdict};

pub mod agy;
pub mod claude;
pub mod codex;
pub mod copilot;
pub mod cursor;
pub mod droid;
pub mod gemini;
pub mod grok;
pub mod opencode;
pub mod qwen;

pub trait Target: Send + Sync {
    fn name(&self) -> &'static str;

    /// The harness's SHELL tool — the only tool this hook should decide about. Droid's is
    /// `Execute`, Gemini's `run_shell_command`; most are `Bash`. Defaults to `Bash`, the common
    /// case.
    fn shell_tool_name(&self) -> &'static str {
        "Bash"
    }

    /// A sample envelope this target's `parse_input` accepts, naming `tool`, or `None` when the
    /// harness's envelope carries NO tool identifier.
    ///
    /// `None` is a researched claim, not a default: it says the envelope has no field naming the
    /// tool, so the hook cannot tell a shell call from any other and must rely on its configured
    /// matcher alone. `Some` obliges the target to abstain on a foreign tool —
    /// `no_target_decides_on_a_foreign_tool` holds it to that in both directions.
    ///
    /// Test-only; each target knows its own envelope shape, and a generic one cannot stand in for
    /// nine different schemas (Copilot nests `toolArgs` as a JSON STRING, Antigravity uses
    /// `toolCall.args.commandLine`, Grok is camelCase).
    #[cfg(test)]
    fn sample_envelope(&self, _tool: &str, _command: &str) -> Option<String> {
        None
    }

    fn display_name(&self) -> &'static str;

    fn detect_paths(&self, home: &Path) -> Vec<PathBuf>;

    fn install(&self, home: &Path) -> Result<InstallOutcome, String>;

    fn hook_format(&self) -> Option<&dyn HookFormat> {
        None
    }

    /// The format that answers THIS envelope. Most harnesses send one hook event, so it is
    /// `hook_format`. Codex sends `PreToolUse` and `PermissionRequest` to the same command and
    /// expects a different answer to each, so it picks by the event the envelope names.
    fn hook_format_for(&self, _stdin: &str) -> Option<&dyn HookFormat> {
        self.hook_format()
    }

    /// Every format `hook_format_for` can return, so the contract guards that need no envelope walk
    /// all of them and a second event's format cannot ship unchecked. The foreign-tool guard is
    /// driven by `sample_envelope` and reaches only the format that envelope routes to; Codex's
    /// `PermissionRequest` tool filter has its own test in `codex.rs`.
    fn hook_formats(&self) -> Vec<&dyn HookFormat> {
        self.hook_format().into_iter().collect()
    }
}

pub trait HookFormat: Send + Sync {
    fn parse_input(&self, stdin: &str) -> Result<HookInput, ParseError>;

    fn render_response(&self, verdict: Verdict) -> HookResponse;

    /// The JSON pointer this harness reads its decision from.
    ///
    /// Deliberately has NO default: getting the field wrong fails SILENTLY — the harness ignores
    /// the unknown key and falls back to its own permissions, so a mis-wired target still lets
    /// commands run and looks like it works while never deciding anything. Requiring the
    /// declaration means a new target cannot be added without stating its contract, and
    /// `every_target_emits_its_decision_at_the_declared_field` checks every emission against it —
    /// including that the decision does NOT appear at another harness's pointer, which is what a
    /// copy-pasted target looks like.
    ///
    /// Note the leaf name alone is not the contract: Claude nests
    /// `/hookSpecificOutput/permissionDecision` while Copilot uses a flat `/permissionDecision`.
    fn decision_pointer(&self) -> &'static str;

    /// Surface explanatory context to the model on a non-approval *without*
    /// changing the permission decision (the command still flows through the
    /// tool's normal approval path, and the user's own allowlist still applies).
    ///
    /// The default abstains silently — same as today's empty deny body. A target
    /// overrides this only when its hook schema has a verified field for
    /// injecting model-visible context without a permission decision.
    fn render_context(&self, _context: &str) -> HookResponse {
        HookResponse { stdout: String::new(), exit_code: 0 }
    }

    /// How this harness's hook must handle a GATED command (one safe-chains does not auto-approve),
    /// derived from its capabilities (`docs/design/harness-capability-model.md`):
    /// - `Defer` — stay silent; the harness's own per-command human review is the check (Claude).
    /// - `Deny` — veto it; the harness has no human review and no escalate (Codex).
    /// - `Ask` — escalate to an in-the-moment human prompt (Antigravity's `ask`).
    fn gated_policy(&self) -> GatedPolicy {
        GatedPolicy::Defer
    }

    /// The hook output that VETOES a gated command, for a `Deny` harness. Default abstains (so a
    /// stray call can't fail open). The shape must be exactly what the harness supports, or a
    /// harness that "continues on malformed output" (e.g. Codex) fails open.
    fn render_deny(&self, _reason: &str) -> HookResponse {
        HookResponse { stdout: String::new(), exit_code: 0 }
    }

    /// The hook output that ESCALATES a gated command to a human prompt, for an `Ask` harness.
    /// Default abstains. (Antigravity fails CLOSED on a malformed/absent decision, so an Ask target
    /// must always emit a valid decision.)
    fn render_ask(&self, _reason: &str) -> HookResponse {
        HookResponse { stdout: String::new(), exit_code: 0 }
    }

    /// Whether the envelope's `cwd` is the directory the command runs in. `false` when the harness
    /// can run the command somewhere else without saying where (Codex's `exec_command` takes a
    /// `workdir` that its `PermissionRequest` payload leaves out), so `evaluation_dirs` refuses to
    /// resolve a relative path against it.
    fn cwd_is_the_commands(&self) -> bool {
        true
    }
}

/// The working directory nothing can be inside: a relative path resolved against it lands outside
/// every workspace, so a command whose safety rests on where its relative paths point is not
/// approved, while one that names no such path classifies as it would anywhere.
pub const UNKNOWN_WORKDIR: &str = "/nonexistent/safe-chains-unknown-workdir";

/// The (cwd, root) a command is classified under. Most harnesses send no distinct project root, so
/// the root defaults to the cwd, which engages the workspace boundary with the one directory known.
/// Where the cwd is not the command's own (`HookFormat::cwd_is_the_commands`), the reported cwd
/// stays the workspace root and the command is placed at `UNKNOWN_WORKDIR`.
pub fn evaluation_dirs(format: &dyn HookFormat, input: &HookInput) -> (Option<String>, Option<String>) {
    let root = input.root.clone().or_else(|| input.cwd.clone());
    if format.cwd_is_the_commands() { (input.cwd.clone(), root) } else { (Some(UNKNOWN_WORKDIR.to_string()), root) }
}

/// How a harness's hook handles a gated command — see `HookFormat::gated_policy`.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum GatedPolicy {
    Defer,
    Deny,
    Ask,
}

#[derive(Debug)]
pub struct ParseError {
    pub message: String,
}

impl std::fmt::Display for ParseError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for ParseError {}

pub struct HookInput {
    pub command: String,
    pub cwd: Option<String>,
    /// The project root, when the harness supplies one (HP-19) — a `*_PROJECT_DIR` env var
    /// for most, `workspace_roots` in the payload for cursor. Absent for codex/copilot.
    pub root: Option<String>,
    /// The harness's session/conversation id, when it supplies one (`session_id` for
    /// Claude/Gemini/Qwen/Droid, `sessionId` for grok, `conversation_id` for cursor). It comes from
    /// the harness's own envelope, so the agent cannot forge it — which is what makes it usable as
    /// the anchor for recognizing the session's scratchpad (see `pathctx::session_scratchpad`).
    pub session_id: Option<String>,
}

/// May a GRANT be emitted for this command?
///
/// A blank command classifies as `Allowed(Inert)` — an empty script really is inert — but rendering
/// that as `permissionDecision: "allow"` asserts "every command in this chain is safe" about ZERO
/// commands, and on the harnesses whose allow is authoritative it replaces the user's prompt.
///
/// The check lives HERE, next to the decision contract, rather than in the binary. It was in
/// `main.rs` first: the shipped hook was safe, but `render_response` is public and knew nothing
/// about blankness, so any second caller reintroduced the bug — and the integration guard passed
/// only because it drives the binary. The `hook_envelope` fuzz target found exactly that by calling
/// the format directly.
pub fn may_grant(command: &str, verdict: crate::Verdict) -> bool {
    verdict.is_allowed() && !command.trim().is_empty()
}

/// The decision for one parsed envelope: the response to emit, or `None` to abstain.
///
/// The single seam every caller goes through, so the blank-command rule cannot be bypassed by
/// reaching for `render_response` directly.
pub fn respond(format: &dyn HookFormat, command: &str, verdict: crate::Verdict) -> Option<HookResponse> {
    (may_grant(command, verdict) && within_unknown_workdir_ceiling(format, verdict)).then(|| format.render_response(verdict))
}

/// Where the command may run in a directory the hook was not told (`cwd_is_the_commands` is
/// false), a write is granted only when the unknown-folder mode judged it.
///
/// `UNKNOWN_WORKDIR` alone catches a write that NAMES a relative path, but `git commit -am x`,
/// `cargo fmt` or `cargo build` write into whatever directory they run in without naming one, and
/// classify the same wherever that is. At a folder level above `reads` (`pathctx::folder`), each
/// relative path was placed or left out by its anchor value and each such write was refused unless
/// it is accounted for, so the verdict already says what the level allows. Without that, only a
/// read is granted, which is the `reads` level.
fn within_unknown_workdir_ceiling(format: &dyn HookFormat, verdict: crate::Verdict) -> bool {
    format.cwd_is_the_commands()
        || crate::pathctx::folder::judges_writes()
        || matches!(verdict, Verdict::Allowed(level) if level <= SafetyLevel::SafeRead)
}

/// The folder level a hook judges writes at when `format` does not report the command's folder:
/// the `--unknown-folder` flag, else the user config, else `developer`. `None` when the folder is
/// known, where the dial does not apply.
pub fn unknown_folder_level(
    format: &dyn HookFormat,
    flag: Option<crate::pathctx::anchor::FolderLevel>,
) -> Option<crate::pathctx::anchor::FolderLevel> {
    (!format.cwd_is_the_commands()).then(|| flag.unwrap_or_else(|| crate::registry::folder_config::user_setting().level()))
}

/// Append `entry` to `settings[outer][event]`, creating the path when absent.
///
/// Refuses — rather than overwriting — when an existing key has the wrong TYPE. Four targets wrote
/// this by hand as `entry(k).or_insert_with(…).as_object_mut().expect("created above as an
/// object")`, and the message says why it looked safe: it reads as if the key had just been
/// created. `or_insert_with` returns the EXISTING value, so a settings file carrying
/// `"hooks": "something"` made `--setup` PANIC — and under `--auto-detect` that aborts the whole
/// run, so every target after it goes uninstalled.
///
/// Erroring beats replacing. The value is the user's, an unreadable one usually means a
/// hand-edit or a schema we don't know, and silently rewriting config we did not understand is
/// not ours to do. `install` writes only on `Ok`, so the file is left untouched either way.
pub(crate) fn append_hook_entry(
    settings: &mut serde_json::Value,
    outer: &str,
    event: &str,
    entry: serde_json::Value,
) -> Result<(), String> {
    use serde_json::json;
    // Refuse a non-object ROOT rather than replace it, for the same reason a wrong-typed inner key
    // is refused below: an unreadable value is usually a hand-edit or a schema we do not know, and
    // rewriting config we did not understand is not ours to do.
    //
    // This only ever fires on a file that EXISTS and parses to something that is not an object
    // (`[1,2,3]`, `"a string"`, `42`). Every caller turns a MISSING file into an empty object
    // before reaching here, so refusing cannot break a first-time `--setup`.
    if !settings.is_object() {
        return Err(format!("the settings file is {}, expected an object. Leaving the file unchanged.", json_kind(settings)));
    }
    let Some(obj) = settings.as_object_mut() else {
        unreachable!("just checked it is an object");
    };
    let hooks = obj.entry(outer).or_insert_with(|| json!({}));
    let Some(hooks) = hooks.as_object_mut() else {
        return Err(format!("`{outer}` is {}, expected an object. Leaving the file unchanged.", json_kind(&obj[outer])));
    };
    let slot = hooks.entry(event).or_insert_with(|| json!([]));
    if !slot.is_array() {
        return Err(format!("`{outer}.{event}` is {}, expected an array. Leaving the file unchanged.", json_kind(slot)));
    }
    let Some(arr) = slot.as_array_mut() else {
        unreachable!("just checked it is an array");
    };
    arr.push(entry);
    Ok(())
}

fn json_kind(v: &serde_json::Value) -> &'static str {
    match v {
        serde_json::Value::Null => "null",
        serde_json::Value::Bool(_) => "a boolean",
        serde_json::Value::Number(_) => "a number",
        serde_json::Value::String(_) => "a string",
        serde_json::Value::Array(_) => "an array",
        serde_json::Value::Object(_) => "an object",
    }
}

/// Read a harness project-root env var from the hook process environment (set by the
/// harness, not the agent's shell — see HARNESS-BEHAVIORS.md). Empty → `None`.
pub(crate) fn env_root(var: &str) -> Option<String> {
    std::env::var(var).ok().filter(|s| !s.is_empty())
}

pub struct HookResponse {
    pub stdout: String,
    pub exit_code: i32,
}

pub enum InstallOutcome {
    Installed { path: PathBuf },
    AlreadyConfigured { path: PathBuf },
    Skipped { reason: String },
}

impl InstallOutcome {
    pub fn message(&self, target_display: &str) -> String {
        match self {
            InstallOutcome::Installed { path } => {
                format!("{target_display}: installed → {}", path.display())
            }
            InstallOutcome::AlreadyConfigured { path } => {
                format!("{target_display}: already configured at {}", path.display())
            }
            InstallOutcome::Skipped { reason } => {
                format!("{target_display}: skipped, {reason}")
            }
        }
    }
}

pub fn registry() -> Vec<Box<dyn Target>> {
    vec![
        Box::new(claude::ClaudeTarget),
        Box::new(codex::CodexTarget),
        Box::new(agy::AntigravityTarget),
        Box::new(cursor::CursorTarget),
        Box::new(gemini::GeminiTarget),
        Box::new(grok::GrokTarget),
        Box::new(copilot::CopilotTarget),
        Box::new(qwen::QwenTarget),
        Box::new(droid::DroidTarget),
        Box::new(opencode::OpenCodeTarget),
    ]
}

pub fn find(name: &str) -> Option<Box<dyn Target>> {
    registry().into_iter().find(|t| t.name() == name)
}

pub fn detect_installed(home: &Path) -> Vec<Box<dyn Target>> {
    registry().into_iter().filter(|t| t.detect_paths(home).iter().any(|p| p.exists())).collect()
}

pub fn allow_reason(verdict: Verdict) -> &'static str {
    match verdict {
        Verdict::Allowed(SafetyLevel::SafeWrite) => "All commands in chain are safe utilities (includes file writes)",
        Verdict::Allowed(SafetyLevel::SafeRead) => "All commands in chain are safe utilities (includes code execution)",
        _ => "All commands in chain are safe utilities",
    }
}

#[cfg(test)]
mod append_hook_entry_tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn creates_the_path_when_absent() {
        let mut s = json!({});
        append_hook_entry(&mut s, "hooks", "PreToolUse", json!({"matcher": "Bash"})).unwrap();
        assert_eq!(s["hooks"]["PreToolUse"][0]["matcher"], "Bash");
    }

    #[test]
    fn appends_beside_an_existing_entry() {
        let mut s = json!({"hooks": {"PreToolUse": [{"matcher": "Other"}]}});
        append_hook_entry(&mut s, "hooks", "PreToolUse", json!({"matcher": "Bash"})).unwrap();
        let arr = s["hooks"]["PreToolUse"].as_array().unwrap();
        assert_eq!(arr.len(), 2, "the user's existing hook must survive");
        assert_eq!(arr[0]["matcher"], "Other");
    }

    /// The panic this replaced: `entry(k).or_insert_with(…).as_object_mut().expect(…)` reads as if
    /// the key was just created, but `or_insert_with` returns the EXISTING value. A settings file
    /// with `"hooks": "x"` crashed `--setup` — and under `--auto-detect` that aborted the whole run.
    #[test]
    fn refuses_a_wrong_typed_outer_key_without_panicking() {
        for wrong in [json!("a string"), json!([1, 2]), json!(7), json!(null)] {
            let mut s = json!({ "hooks": wrong });
            let before = s.clone();
            let err = append_hook_entry(&mut s, "hooks", "PreToolUse", json!({})).unwrap_err();
            assert!(err.contains("expected an object"), "unhelpful error: {err}");
            assert_eq!(s, before, "the user's value must be left alone, not replaced");
        }
    }

    #[test]
    fn refuses_a_wrong_typed_event_key_without_panicking() {
        let mut s = json!({"hooks": {"PreToolUse": "a string"}});
        let before = s.clone();
        let err = append_hook_entry(&mut s, "hooks", "PreToolUse", json!({})).unwrap_err();
        assert!(err.contains("expected an array"), "unhelpful error: {err}");
        assert_eq!(s, before, "the user's value must be left alone, not replaced");
    }

    /// A non-object ROOT is refused, not replaced.
    ///
    /// This test previously asserted the opposite, on the reasoning that "a file whose ROOT is not
    /// an object carries nothing to preserve". That is the same argument this module already
    /// rejected one level in, where a wrong-typed `hooks` value is refused because an unreadable
    /// value usually means a hand-edit or a schema we do not know. A root we cannot read is not
    /// more disposable than a key we cannot read — it is less, since it is the whole file.
    ///
    /// Refusing is safe for a first-time `--setup`: every caller turns a MISSING file into an empty
    /// object before reaching here, so this fires only for a file that exists and parses to a
    /// non-object.
    #[test]
    fn refuses_a_non_object_root_without_replacing_it() {
        for root in [json!("garbage"), json!([1, 2, 3]), json!(42), json!(null)] {
            let mut s = root.clone();
            let err = append_hook_entry(&mut s, "hooks", "PreToolUse", json!({"matcher": "Bash"}))
                .expect_err("a non-object root must be refused");
            assert!(err.contains("expected an object"), "unhelpful error: {err}");
            assert_eq!(s, root, "the user's file must be left alone, not replaced");
        }

        // An object root is still the ordinary path.
        let mut s = json!({"unrelated": true});
        append_hook_entry(&mut s, "hooks", "PreToolUse", json!({"matcher": "Bash"})).unwrap();
        assert_eq!(s["hooks"]["PreToolUse"][0]["matcher"], "Bash");
        assert_eq!(s["unrelated"], true, "unrelated keys survive");
    }
}

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

    /// No target decides on a tool that is not its shell tool.
    ///
    /// The hook is wired with a matcher (`Bash`, `Execute`, `run_shell_command`), so normally only
    /// shell calls arrive. But a matcher is configuration: it can be hand-edited, and grok is
    /// documented to auto-load `~/.claude/settings.json`, which hands Claude's hook a foreign
    /// envelope. Deciding on a `Read`/`Write`/`Edit` call grants or vetoes a tool whose semantics
    /// were never analysed — and for the ALLOW-capable targets that is a grant, issued on the
    /// strength of a `command` field the tool does not even have. Four targets did exactly that.
    ///
    /// Driven by each target's OWN `sample_envelope`, because nine harnesses have nine schemas and
    /// a generic probe silently fails to parse (which looks like a pass). A target whose envelope
    /// carries no tool identifier returns `None` and is exempt — a researched claim, recorded per
    /// target, not a default.
    #[test]
    fn no_target_decides_on_a_foreign_tool() {
        let mut failures = Vec::new();
        let mut checked = 0usize;
        for target in registry() {
            if target.hook_format().is_none() {
                continue;
            }
            let Some(shell) = target.sample_envelope(target.shell_tool_name(), "ls") else {
                continue; // envelope carries no tool identifier — cannot self-filter
            };
            let name = target.name();
            let routed = |env: &str| target.hook_format_for(env).map(|fmt| fmt.parse_input(env));
            // The shell tool must still parse, or "reject everything" would satisfy the negative
            // half and look like a working filter.
            match routed(&shell) {
                Some(Ok(_)) => {}
                Some(Err(e)) => failures.push(format!("{name}: rejected its own shell tool `{}`: {}", target.shell_tool_name(), e.message)),
                None => failures.push(format!("{name}: hook_format_for found no format for its own shell envelope")),
            }
            for foreign in ["Read", "Write", "Edit", "WebFetch"] {
                let Some(env) = target.sample_envelope(foreign, "rm -rf /") else { continue };
                checked += 1;
                if matches!(routed(&env), Some(Ok(_))) {
                    failures.push(format!("{name}: parsed a `{foreign}` envelope instead of abstaining"));
                }
            }
        }
        assert!(checked > 0, "no target was probed — the guard is vacuous");
        assert!(failures.is_empty(), "foreign-tool decisions:\n{}", failures.join("\n"));
    }
}