theway-core 0.1.21

//! Permission evaluator for tool calls.
//!
//! v1 scope (issue #4 part 1): a stateless classifier with two outcomes — `Allow` or `Deny`.
//! Dangerous bash patterns are short-circuited to `Deny` with a reason. A `Prompt` outcome
//! that asks the user for confirmation is the obvious follow-up; we leave the enum shape
//! ready for it but ship without a UI for now so this module can land independently of any
//! TUI work.
//!
//! Wire-up: callers build a [`PermissionPolicy`], pass it into a `before_tool_call` hook (see
//! [`PermissionPolicy::as_before_tool_call`]), and the agent loop will receive
//! `BeforeToolCallResult { block: true, reason }` for any denied call. The synthesized tool
//! result the loop generates is exactly the reason string — so the LLM sees a clear
//! "denied: <pattern>" message and can adjust.
//!
//! Rule shape: most rules are simple substring regex (`sudo`, `curl|sh`, `mkfs`…). The few
//! cases where regex is insufficient — most notably `rm` with recursive + force flags in any
//! permutation of short / long / separated forms — live as small token-aware predicates. A
//! single complicated regex would either miss flag splits or accept a malformed shell line
//! and create false positives; the permission layer must close, not minimize.

use std::sync::Arc;

use regex::RegexSet;

use crate::types::*;

/// Outcome of evaluating a tool call.
#[derive(Debug, Clone)]
pub enum PermissionDecision {
    Allow,
    Deny { reason: String },
}

/// Category of the operation being evaluated. Lets a single policy fan out classification
/// logic per category instead of conflating the bash danger classifier with persistent
/// agent self-modification (which has a larger blast radius than a one-shot tool call).
///
/// New categories should be added sparingly — each adds a permission surface the user has
/// to reason about. Today:
///
/// - [`Self::Tool`] is the default for all existing tool calls; behavior unchanged.
/// - [`Self::ControlPlaneWrite`] covers persistent agent self-modification (dynamic
///   trigger rule create/remove/enable/disable, skill install/uninstall, hook
///   install/uninstall). The rule body becomes a future agent prompt, so a writer should
///   apply at least the same scrutiny as a one-shot bash invocation — and often more.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PermissionCategory {
    /// Default for stateless tool calls (read/write/edit/bash/grep/etc).
    Tool,
    /// Persistent agent self-modification — trigger rule writes, skill writes, hook
    /// writes. Tools-MCP and CLI-TUI opt their writers into this category; runtime
    /// defaults to [`PermissionDecision::Allow`] so adding the category is non-breaking.
    ControlPlaneWrite,
}

/// One rule in the dangerous-bash corpus. Cheap predicates run before the regex set so the
/// expensive case (`RegexSet::matches`) only fires when no targeted classifier already
/// fired.
struct PredicateRule {
    label: &'static str,
    check: fn(&str) -> bool,
}

/// Permission evaluator. Bash tool calls are matched against a corpus of dangerous patterns;
/// everything else is allowed. Patterns come in two flavors: regex substring matches (the
/// majority) and token-aware predicates (for cases like `rm` flag permutations that regex
/// cannot cleanly express).
#[derive(Clone)]
pub struct PermissionPolicy {
    bash_tool_names: Vec<String>,
    predicate_rules: Arc<Vec<PredicateRule>>,
    danger_set: Arc<RegexSet>,
    danger_labels: Arc<Vec<&'static str>>,
}

impl PermissionPolicy {
    /// Default policy — bash tool name set + the canonical dangerous-bash corpus.
    pub fn default_for_coding_agent() -> Self {
        Self::new(vec!["bash".into()], default_danger_patterns())
    }

    /// Build a policy with custom shell tool names and danger patterns.
    pub fn new(
        bash_tool_names: Vec<String>,
        danger_patterns: Vec<(&'static str, &'static str)>,
    ) -> Self {
        let labels: Vec<&'static str> = danger_patterns.iter().map(|(l, _)| *l).collect();
        let regexes: Vec<&'static str> = danger_patterns.iter().map(|(_, r)| *r).collect();
        let set = RegexSet::new(&regexes).expect("danger patterns must compile");
        Self {
            bash_tool_names,
            predicate_rules: Arc::new(default_predicate_rules()),
            danger_set: Arc::new(set),
            danger_labels: Arc::new(labels),
        }
    }

    /// Evaluate a single tool call against the policy in the default [`PermissionCategory::Tool`]
    /// category. Preserved for backwards compatibility — new callers that want to evaluate
    /// a non-default category should use [`Self::evaluate_with_category`].
    pub fn evaluate(&self, tool_name: &str, args: &serde_json::Value) -> PermissionDecision {
        self.evaluate_with_category(PermissionCategory::Tool, tool_name, args)
    }

    /// Evaluate a single tool call against the policy in the given category. Pure function — no IO.
    ///
    /// Runtime ships a permissive default for [`PermissionCategory::ControlPlaneWrite`]
    /// (returns `Allow` unconditionally) so adding the category is non-breaking; downstream
    /// crates wire a category-specific classifier when they opt their writers in.
    pub fn evaluate_with_category(
        &self,
        category: PermissionCategory,
        tool_name: &str,
        args: &serde_json::Value,
    ) -> PermissionDecision {
        if category == PermissionCategory::ControlPlaneWrite {
            // Default policy in runtime: no classifier wired yet. Tools-MCP / CLI-TUI's
            // follow-up PRs add the danger classifier + Prompt path here.
            return PermissionDecision::Allow;
        }
        if !self.bash_tool_names.iter().any(|n| n == tool_name) {
            return PermissionDecision::Allow;
        }
        // Bash commands carry their shell text in one of a few common fields. Look for the
        // first non-empty string we can match against.
        let cmd = extract_shell_command(args);
        let Some(cmd) = cmd else {
            // Empty / un-parseable bash call — allow; the tool itself will error.
            return PermissionDecision::Allow;
        };
        // Predicate rules run first: they're targeted at cases regex cannot cleanly cover.
        for rule in self.predicate_rules.iter() {
            if (rule.check)(&cmd) {
                return PermissionDecision::Deny {
                    reason: format!("denied by permission policy: {}", rule.label),
                };
            }
        }
        let matches: Vec<usize> = self.danger_set.matches(&cmd).into_iter().collect();
        if matches.is_empty() {
            return PermissionDecision::Allow;
        }
        let label = self
            .danger_labels
            .get(matches[0])
            .copied()
            .unwrap_or("dangerous shell command");
        PermissionDecision::Deny {
            reason: format!("denied by permission policy: {label}"),
        }
    }

    /// Convert this policy into a `BeforeToolCallHook` ready to assign to
    /// [`crate::agent::AgentOptions::before_tool_call`].
    pub fn as_before_tool_call(self) -> BeforeToolCallHook {
        let policy = Arc::new(self);
        Arc::new(move |ctx: BeforeToolCallContext, _cancel| {
            let policy = policy.clone();
            Box::pin(async move {
                match policy.evaluate(&ctx.tool_call.name, &ctx.args) {
                    PermissionDecision::Allow => BeforeToolCallResult::default(),
                    PermissionDecision::Deny { reason } => BeforeToolCallResult {
                        block: true,
                        reason: Some(reason),
                        prompt: None,
                    },
                }
            })
        })
    }
}

impl Default for PermissionPolicy {
    fn default() -> Self {
        Self::default_for_coding_agent()
    }
}

/// Try to extract the shell command from a bash tool call's argument JSON. Tools accept
/// slightly different field names, so try `command`, `cmd`, `bash`, `script` in order.
fn extract_shell_command(args: &serde_json::Value) -> Option<String> {
    for key in ["command", "cmd", "bash", "script"] {
        if let Some(v) = args.get(key).and_then(|v| v.as_str()) {
            if !v.trim().is_empty() {
                return Some(v.to_string());
            }
        }
    }
    // Fallback: if args is itself a string, treat it as the command.
    if let Some(s) = args.as_str() {
        if !s.trim().is_empty() {
            return Some(s.to_string());
        }
    }
    None
}

/// The canonical "this almost certainly causes harm" corpus. Patterns are anchored *loosely*
/// (substring match within the full command), so flag ordering for the non-`rm` rules does
/// not matter. `rm` cases live separately in [`default_predicate_rules`] because flag
/// permutations defeat a single-regex approach.
///
/// Each entry is `(label, regex)`. The label appears in the deny reason so the user (and the
/// LLM) sees which rule fired.
fn default_danger_patterns() -> Vec<(&'static str, &'static str)> {
    vec![
        ("sudo invocation", r"\bsudo\b"),
        (
            "curl/wget piped into shell",
            r"\b(curl|wget)\b[^|]*\|\s*(bash|sh|zsh|fish)\b",
        ),
        (
            "dd writing to a block device",
            r"\bdd\b[^\n]*\bof=/dev/(disk|sd[a-z]|nvme|hd[a-z])",
        ),
        ("mkfs / format command", r"\bmkfs(\.|\s)"),
        ("chmod 777 on absolute path", r"\bchmod\b\s+777\s+/"),
        (
            "shutdown / reboot / halt",
            r"\b(shutdown|reboot|halt|poweroff)\b",
        ),
        (
            "git push --force on main/master",
            r"\bgit\s+push\s+(--force|-f)\b[^\n]*\b(main|master)\b",
        ),
        ("piping into eval", r"\|\s*eval\b"),
        (":(){:|:&};: forkbomb", r":\(\)\s*\{\s*:\|:&\s*\}\s*;\s*:"),
    ]
}

/// Token-aware predicates for rules where regex alone is fragile. Currently only `rm` with
/// recursive + force flags; intentionally small so the cost of running every predicate on
/// every bash invocation stays negligible.
fn default_predicate_rules() -> Vec<PredicateRule> {
    vec![
        PredicateRule {
            label: "rm recursive+force on absolute path",
            check: rm_recursive_force_on_absolute_target,
        },
        PredicateRule {
            label: "rm recursive+force on $HOME or ~",
            check: rm_recursive_force_on_home_target,
        },
    ]
}

/// Returns true when `cmd` contains an `rm` invocation that bears both a recursive flag
/// (`-r`, `-R`, `--recursive`) and a force flag (`-f`, `--force`) — combined, separated, or
/// long-form, in any order — and targets `/` or any absolute path starting with `/`.
///
/// Walks every shell-token cluster after the first `rm` reachable through `;`, `&&`, `||`,
/// `|`. Each operand passes through [`normalize_operand`] before the target check so
/// `rm -rf "/etc"`, `rm -rf '${HOME}'`, and `rm -rf "$HOME/projects"` are not silently
/// allowed by quoting. False positives on contrived `rm` invocations are preferable to false
/// negatives on dangerous ones; the classifier is intentionally conservative.
fn rm_recursive_force_on_absolute_target(cmd: &str) -> bool {
    rm_dangerous_with(cmd, |operand| operand == "/" || operand.starts_with('/'))
}

fn rm_recursive_force_on_home_target(cmd: &str) -> bool {
    rm_dangerous_with(cmd, |operand| {
        operand == "~"
            || operand.starts_with("~/")
            || operand == "$HOME"
            || operand.starts_with("$HOME/")
    })
}

fn rm_dangerous_with(cmd: &str, target_matches: fn(&str) -> bool) -> bool {
    for clause in split_shell_clauses(cmd) {
        let tokens: Vec<&str> = clause.split_whitespace().collect();
        let Some(first) = tokens.first() else {
            continue;
        };
        // Strip leading path so `rm`, `/bin/rm`, `./rm` all classify.
        let prog = first.rsplit('/').next().unwrap_or(first);
        if prog != "rm" {
            continue;
        }
        let mut has_recursive = false;
        let mut has_force = false;
        let mut operands: Vec<String> = Vec::new();
        for tok in tokens.iter().skip(1) {
            if let Some(long) = tok.strip_prefix("--") {
                match long {
                    "recursive" => has_recursive = true,
                    "force" => has_force = true,
                    "" => continue, // `--` end-of-options marker; remaining tokens are operands
                    _ => {}
                }
            } else if let Some(short) = tok.strip_prefix('-') {
                if short.is_empty() {
                    // bare `-` operand (stdin or path-by-convention) — treat as operand
                    operands.push(normalize_operand(tok));
                } else {
                    if short.contains('r') || short.contains('R') {
                        has_recursive = true;
                    }
                    if short.contains('f') {
                        has_force = true;
                    }
                }
            } else {
                operands.push(normalize_operand(tok));
            }
        }
        if !(has_recursive && has_force) {
            continue;
        }
        if operands.iter().any(|op| target_matches(op.as_str())) {
            return true;
        }
    }
    false
}

/// Normalize a single shell token before the target predicate sees it. Strips one balanced
/// layer of single or double quotes and rewrites `${HOME}` (with optional suffix) to
/// `$HOME` form. We deliberately stop short of full shell expansion — that would require a
/// real parser — but these two transforms cover every quoting-based bypass the 2026-05-22
/// review flagged (`rm -rf "/etc"`, `rm -rf '$HOME/projects'`, `rm -rf "${HOME}/projects"`).
fn normalize_operand(raw: &str) -> String {
    let unquoted = strip_one_layer_of_quotes(raw);
    rewrite_brace_home(&unquoted)
}

fn strip_one_layer_of_quotes(raw: &str) -> String {
    if raw.len() >= 2 {
        let bytes = raw.as_bytes();
        let first = bytes[0];
        let last = bytes[raw.len() - 1];
        if (first == b'"' && last == b'"') || (first == b'\'' && last == b'\'') {
            return raw[1..raw.len() - 1].to_string();
        }
    }
    raw.to_string()
}

fn rewrite_brace_home(raw: &str) -> String {
    if let Some(rest) = raw.strip_prefix("${HOME}") {
        return format!("$HOME{rest}");
    }
    raw.to_string()
}

/// Split a shell command line on `;`, `&&`, `||`, `|`. We keep this dumb on purpose — we
/// don't try to honor quotes or escapes; the predicate caller will run on each clause and
/// the worst-case shape (a quoted `;` inside a string) just produces an extra clause we
/// still scan honestly.
fn split_shell_clauses(cmd: &str) -> Vec<&str> {
    let mut out = Vec::new();
    let bytes = cmd.as_bytes();
    let mut start = 0usize;
    let mut i = 0usize;
    while i < bytes.len() {
        let b = bytes[i];
        if b == b';' {
            out.push(cmd[start..i].trim());
            start = i + 1;
            i += 1;
        } else if i + 1 < bytes.len()
            && ((b == b'&' && bytes[i + 1] == b'&') || (b == b'|' && bytes[i + 1] == b'|'))
        {
            out.push(cmd[start..i].trim());
            start = i + 2;
            i += 2;
        } else if b == b'|' {
            out.push(cmd[start..i].trim());
            start = i + 1;
            i += 1;
        } else {
            i += 1;
        }
    }
    if start <= bytes.len() {
        out.push(cmd[start..].trim());
    }
    out.into_iter().filter(|s| !s.is_empty()).collect()
}

#[cfg(test)]
mod permission_external_tests {
    tests_bridge_macro::tests_bridge!("agent/permission");
}

#[cfg(test)]
mod permission_linecov_tests {
    tests_bridge_macro::tests_bridge!("agent/permission/linecov");
}