car_server_core/coder/

policy.rs

//! The coder's inspector chain — policy hardening for host tool execution.
//!
//! Every tool call the coder makes passes through a frozen chain before
//! dispatch; first Deny wins. Contract checks use the same chain by default. An
//! explicit contract credential opt-in selects a twin chain that omits only
//! [`DenyCredentialAccess`]; the model-facing chain never does. CAR's built-ins
//! run first, followed by the operator's additive rules from `<CAR_HOME>/policies/`
//! and `<worktree>/.car/policies/`. The checks are deliberately conservative
//! token/substring matchers, not a shell parser — they block the unambiguous
//! footguns. The one exception in shape is
//! [`DenyForgePublication`], which pairs a read-only *allowlist* for the forge
//! CLIs (`gh`, `glab`, `hub`) with a small publication blacklist, because the
//! set of read-only `gh` subcommands is finite and the set of mutating ones is
//! not. This is hardening, not a sandbox — a shell alias or a script wrapping
//! the binary still gets through; the real gates are
//! contract confirmation and merge approval (see `coder::` module docs). Prefix
//! command carriers are unwrapped recursively so the command they launch still
//! reaches each applicable inspector.

use std::collections::{BTreeSet, HashMap};
use std::path::{Component, Path, PathBuf};
use std::sync::Arc;

use car_ir::Action;
use car_policy::{InspectionResult, Inspector, InspectorChain, PolicyEngine, PolicyRules};
use car_state::StateStore;
use serde_json::Value;

fn coder_inspector_chain_for(worktree: &Path, deny_credentials: bool) -> InspectorChain {
    let mut chain = InspectorChain::new()
        .with(Box::new(DenyShellFunctionDeclaration))
        .with(Box::new(DenyGitRemoteMutation))
        .with(Box::new(DenyForgePublication))
        .with(Box::new(DenyHistoryRewrite))
        .with(Box::new(DenyPrivilegeEscalation));
    if deny_credentials {
        chain = chain.with(Box::new(DenyCredentialAccess));
    }
    chain
        .with(Box::new(DenyEnvironmentRepair))
        .with(Box::new(DenyDestructiveOutsideWorktree {
            worktree: worktree.to_path_buf(),
        }))
        .with(Box::new(DenyPathEscape {
            worktree: worktree.to_path_buf(),
        }))
}

/// Build the standard coder chain for model-proposed tool calls.
pub fn coder_inspector_chain(worktree: &Path) -> InspectorChain {
    coder_inspector_chain_for(worktree, true)
}

/// Build the contract-check chain used only by an explicit credential opt-in.
///
/// Its order and contents match [`coder_inspector_chain`] except that
/// [`DenyCredentialAccess`] is absent. Destructive commands, path escape,
/// publication, privilege escalation, environment repair, and project policy
/// remain enforced.
pub(super) fn credentialed_contract_inspector_chain(worktree: &Path) -> InspectorChain {
    coder_inspector_chain_for(worktree, false)
}

/// Build the standard coder chain plus every operator-authored policy that
/// governs this session.
///
/// The source order deliberately matches `car_policy::tool_gate`: machine-wide
/// rules first, then rules committed with the project. All current rule kinds
/// are prohibitions, so merging cannot relax a built-in or an earlier rule.
/// Built-ins remain ahead of the declarative inspector because first-Deny-wins
/// decides which actionable reason the model sees.
///
/// Tool names stay exact. A policy for a surface-specific tool the coder does
/// not expose (for example Claude Code's `WebFetch`) is loaded but has nothing
/// to match; CAR does not guess aliases between tools with different schemas.
/// Stateful `trace_rule` is also deliberately excluded: the shared loader
/// rejects it as unenforced instead of silently claiming it took effect.
/// The chain, plus the tools the operator's rules forbid **outright**.
///
/// Both come from one load of the policy files. The denied set is returned
/// rather than left inside the chain because it answers a question dispatch
/// cannot: which tools should never have been offered to the model in the first
/// place. See [`car_policy::PolicyEngine::blanket_denied_tools`].
pub struct CoderPolicy {
    pub chain: InspectorChain,
    pub credentialed_contract_chain: InspectorChain,
    pub denied_tools: BTreeSet<String>,
}

pub fn coder_inspector_chain_with_project_policies(
    worktree: &Path,
) -> Result<CoderPolicy, car_policy::PolicyLoadError> {
    let dirs = [
        car_home::root_or_relative().join("policies"),
        worktree.join(".car").join("policies"),
    ];
    coder_inspector_chain_from_policy_dirs(worktree, &dirs)
}

fn coder_inspector_chain_from_policy_dirs(
    worktree: &Path,
    dirs: &[PathBuf],
) -> Result<CoderPolicy, car_policy::PolicyLoadError> {
    let mut rules = PolicyRules::default();
    for dir in dirs {
        rules.merge(car_policy::load_policy_dir(dir)?);
    }

    let mut engine = PolicyEngine::new();
    rules.apply(&mut engine);
    // Read before the engine moves into the inspector. Both chains share this
    // engine so operator-authored rate limits retain one session-wide window;
    // the credential opt-in removes one built-in and nothing else.
    let denied_tools = engine.blanket_denied_tools();
    let engine = Arc::new(engine);
    let state = Arc::new(StateStore::new());
    let project_policy = || {
        Box::new(ProjectPolicyInspector {
            engine: Arc::clone(&engine),
            state: Arc::clone(&state),
        }) as Box<dyn Inspector>
    };
    Ok(CoderPolicy {
        chain: coder_inspector_chain(worktree).with(project_policy()),
        credentialed_contract_chain: credentialed_contract_inspector_chain(worktree)
            .with(project_policy()),
        denied_tools,
    })
}

/// Adapter from the declarative `PolicyEngine` to the coder's dispatch-time
/// inspector seam. One instance lives for the session, so rate-limit windows
/// cover the whole run rather than resetting for every tool call.
struct ProjectPolicyInspector {
    engine: Arc<PolicyEngine>,
    state: Arc<StateStore>,
}

impl Inspector for ProjectPolicyInspector {
    fn name(&self) -> &'static str {
        "project_policy"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        // Action is non-exhaustive outside car-ir; use its constructor so a new
        // field cannot make this adapter silently construct a stale shape.
        let mut action = Action::tool_call(tool);
        action.id = "coder-policy-check".to_string();
        action.parameters = params
            .as_object()
            .map(|m| {
                m.iter()
                    .map(|(key, value)| (key.clone(), value.clone()))
                    .collect::<HashMap<_, _>>()
            })
            .unwrap_or_default();

        match self.engine.check(&action, &self.state).into_iter().next() {
            Some(violation) => InspectionResult::Deny(format!(
                "operator policy '{}': {}",
                violation.policy_name, violation.reason
            )),
            None => InspectionResult::Allow,
        }
    }
}

/// Governed host execution is deliberately narrower than the legacy coder:
/// direct shell reads and directory changes must remain under the selected
/// repository. Toolchains may still load their own executables and libraries;
/// this gate prevents the model from naming host files as command operands.
struct DenyGovernedShellPathEscape {
    worktree: PathBuf,
    /// `OLDPWD` is inspectable only when the child inherits the repository
    /// root itself. Any other value would make a variable-prefixed operand an
    /// off-repository path.
    oldpwd_is_worktree: bool,
    /// An inherited target directory is a second governed read root. Cargo's
    /// config-file target is deliberately absent here: `$CARGO_TARGET_DIR`
    /// expands to nothing unless the environment variable itself is pinned.
    cargo_target_dir: Option<PathBuf>,
}

impl DenyGovernedShellPathEscape {
    fn new(worktree: &Path) -> Self {
        let inherited_path = |name: &str| {
            std::env::var_os(name).and_then(|value| {
                let path = PathBuf::from(value);
                (!path.as_os_str().is_empty()).then(|| {
                    if path.is_absolute() {
                        path
                    } else {
                        worktree.join(path)
                    }
                })
            })
        };
        let oldpwd_is_worktree = inherited_path("OLDPWD").is_some_and(|oldpwd| {
            match (oldpwd.canonicalize(), worktree.canonicalize()) {
                (Ok(oldpwd), Ok(worktree)) => oldpwd == worktree,
                _ => false,
            }
        });
        Self {
            worktree: worktree.to_path_buf(),
            oldpwd_is_worktree,
            cargo_target_dir: inherited_path("CARGO_TARGET_DIR"),
        }
    }
}

const READ_OR_CHDIR_VERBS: &[&str] = &[
    "cat", "head", "tail", "less", "more", "grep", "egrep", "fgrep", "rg", "sed", "awk", "find",
    "ls", "stat", "wc", "strings", "readlink", "realpath", "cd", "type",
];

/// Advance the byte index past whitespace in an inline program.
fn skip_program_whitespace(program: &str, index: &mut usize) {
    while let Some(ch) = program[*index..].chars().next() {
        if !ch.is_whitespace() {
            break;
        }
        *index += ch.len_utf8();
    }
}

/// Consume one sed address at the current byte index. The path-looking text in
/// `/regex/` remains program syntax; only the command that follows the address
/// may introduce an r/R/w/W file operand.
fn consume_sed_address(program: &str, index: &mut usize) -> bool {
    let Some(first) = program[*index..].chars().next() else {
        return false;
    };
    match first {
        '0'..='9' => {
            while let Some(ch) = program[*index..].chars().next() {
                if !ch.is_ascii_digit() {
                    break;
                }
                *index += ch.len_utf8();
            }
            true
        }
        '$' => {
            *index += 1;
            true
        }
        '/' => {
            *index += 1;
            let mut escaped = false;
            while let Some(ch) = program[*index..].chars().next() {
                *index += ch.len_utf8();
                if escaped {
                    escaped = false;
                } else if ch == '\\' {
                    escaped = true;
                } else if ch == '/' {
                    return true;
                }
            }
            true
        }
        // GNU/BSD sed alternate regex address: \%regex% (the character after
        // the backslash is the delimiter).
        '\\' => {
            *index += 1;
            let Some(delimiter) = program[*index..].chars().next() else {
                return true;
            };
            *index += delimiter.len_utf8();
            let mut escaped = false;
            while let Some(ch) = program[*index..].chars().next() {
                *index += ch.len_utf8();
                if escaped {
                    escaped = false;
                } else if ch == '\\' {
                    escaped = true;
                } else if ch == delimiter {
                    return true;
                }
            }
            true
        }
        _ => false,
    }
}

/// Consume one delimiter-terminated sed field, honoring escaped delimiters.
fn consume_sed_delimited_field(statement: &str, index: &mut usize, delimiter: char) -> bool {
    let mut escaped = false;
    while let Some(ch) = statement[*index..].chars().next() {
        *index += ch.len_utf8();
        if escaped {
            escaped = false;
        } else if ch == '\\' {
            escaped = true;
        } else if ch == delimiter {
            return true;
        }
    }
    false
}

fn sed_line_end(program: &str, index: usize) -> usize {
    program[index..]
        .find('\n')
        .map_or(program.len(), |offset| index + offset)
}

fn skip_to_sed_separator(program: &str, index: &mut usize) {
    while let Some(ch) = program[*index..].chars().next() {
        if matches!(ch, ';' | '\n' | '{' | '}') {
            break;
        }
        *index += ch.len_utf8();
    }
}

/// File operands embedded in one inline sed program. The program is walked as
/// sed syntax rather than split blindly: separators inside regex,
/// substitutions, or transliterations do not hide a later file operand or
/// become a false command. GNU sed's `e` command and substitution flag execute
/// a shell and are refused outright.
fn sed_program_paths(program: &str) -> Result<Vec<String>, String> {
    let mut paths = Vec::new();
    let mut index = 0;
    while index < program.len() {
        skip_program_whitespace(program, &mut index);
        while let Some(separator) = program[index..].chars().next() {
            if !matches!(separator, ';' | '{' | '}') {
                break;
            }
            index += separator.len_utf8();
            skip_program_whitespace(program, &mut index);
        }
        if index == program.len() {
            break;
        }

        loop {
            if !consume_sed_address(program, &mut index) {
                break;
            }
            skip_program_whitespace(program, &mut index);
            if program[index..].starts_with(',') || program[index..].starts_with('~') {
                index += 1;
                skip_program_whitespace(program, &mut index);
                continue;
            }
            break;
        }
        skip_program_whitespace(program, &mut index);
        if program[index..].starts_with('!') {
            index += 1;
            skip_program_whitespace(program, &mut index);
        }
        let Some(command) = program[index..].chars().next() else {
            break;
        };
        index += command.len_utf8();
        match command {
            'r' | 'R' | 'w' | 'W' => {
                // sed accepts both `w FILE` and `wFILE`. These commands consume
                // the remainder of their line as the filename.
                let end = sed_line_end(program, index);
                let operand = program[index..end].trim();
                if !operand.is_empty() {
                    paths.push(operand.to_string());
                }
                index = end;
            }
            's' => {
                let Some(delimiter) = program[index..].chars().next() else {
                    break;
                };
                index += delimiter.len_utf8();
                if !consume_sed_delimited_field(program, &mut index, delimiter)
                    || !consume_sed_delimited_field(program, &mut index, delimiter)
                {
                    continue;
                }
                while let Some(flag) = program[index..].chars().next() {
                    match flag {
                        'e' => {
                            return Err(
                                "sed shell execution through the e flag is not allowed in a governed session"
                                    .to_string(),
                            )
                        }
                        'w' => {
                            index += flag.len_utf8();
                            let end = sed_line_end(program, index);
                            let operand = program[index..end].trim();
                            if !operand.is_empty() {
                                paths.push(operand.to_string());
                            }
                            index = end;
                            break;
                        }
                        ';' | '\n' | '{' | '}' => break,
                        ch if ch.is_whitespace()
                            || ch.is_ascii_digit()
                            || matches!(ch, 'g' | 'i' | 'I' | 'm' | 'M' | 'p') =>
                        {
                            index += ch.len_utf8();
                        }
                        _ => {
                            // Malformed/unknown flags cannot safely be parsed
                            // as another command. Skip to the next separator.
                            skip_to_sed_separator(program, &mut index);
                            break;
                        }
                    }
                }
            }
            'y' => {
                // Transliteration has two delimiter-terminated fields, either
                // of which may contain characters that otherwise separate
                // commands (for example `y/a/;/`).
                let Some(delimiter) = program[index..].chars().next() else {
                    break;
                };
                index += delimiter.len_utf8();
                if !consume_sed_delimited_field(program, &mut index, delimiter)
                    || !consume_sed_delimited_field(program, &mut index, delimiter)
                {
                    continue;
                }
            }
            'e' => return Err(
                "sed shell execution through the e command is not allowed in a governed session"
                    .to_string(),
            ),
            // These commands consume text or a filename-like label through the
            // end of the physical program line. Do not reinterpret its bytes as
            // more commands.
            'a' | 'c' | 'i' | '#' => index = sed_line_end(program, index),
            // Labels and optional numeric arguments run until a separator.
            ':' | 'b' | 'l' | 'q' | 'Q' | 't' | 'T' | 'v' => {
                skip_to_sed_separator(program, &mut index)
            }
            _ => {}
        }
    }
    Ok(paths)
}

fn awk_program_tokens(program: &str) -> Vec<String> {
    fn finish(token: &mut String, result: &mut Vec<String>) {
        if !token.is_empty() {
            result.push(std::mem::take(token));
        }
    }

    let mut result = Vec::new();
    let mut token = String::new();
    let mut quote = None;
    let mut escaped = false;
    let mut chars = program.chars().peekable();
    while let Some(ch) = chars.next() {
        if let Some(delimiter) = quote {
            if escaped {
                token.push(ch);
                escaped = false;
            } else if ch == '\\' {
                #[cfg(windows)]
                {
                    // A Windows absolute path inside an awk string uses `\` as
                    // its separator. Preserve it unless it quotes awk syntax;
                    // dropping it turns `C:\outside` into a harmless-looking
                    // relative token and makes the path gate fail open.
                    if chars
                        .peek()
                        .is_some_and(|next| *next != delimiter && *next != '\\')
                    {
                        token.push(ch);
                    } else {
                        escaped = true;
                    }
                }
                #[cfg(not(windows))]
                {
                    escaped = true;
                }
            } else if ch == delimiter {
                quote = None;
                finish(&mut token, &mut result);
            } else {
                token.push(ch);
            }
            continue;
        }
        match ch {
            '"' | '\'' => {
                finish(&mut token, &mut result);
                quote = Some(ch);
            }
            ch if ch.is_whitespace() => finish(&mut token, &mut result),
            '<' | '>' | '|' => {
                finish(&mut token, &mut result);
                let mut operator = ch.to_string();
                if (ch == '>' && chars.peek() == Some(&'>'))
                    || (ch == '|' && chars.peek() == Some(&'&'))
                {
                    let joined = chars.next().expect("peeked operator suffix");
                    operator.push(joined);
                }
                result.push(operator);
            }
            ';' | '{' | '}' | '(' | ')' | ',' => {
                finish(&mut token, &mut result);
                result.push(ch.to_string());
            }
            _ => token.push(ch),
        }
    }
    finish(&mut token, &mut result);
    result
}

/// File operands embedded in one inline awk program. `getline` reads only when
/// paired with `<`; print/printf write only through `>` or `>>`. General shell
/// execution through `system()` or a command pipe is refused outright so the
/// inner command cannot bypass the rest of the governed inspector chain.
fn awk_program_paths(program: &str) -> Result<Vec<String>, String> {
    let tokens = awk_program_tokens(program);
    if tokens
        .windows(2)
        .any(|pair| pair[0] == "system" && pair[1] == "(")
    {
        return Err("awk system() is not allowed in a governed session".to_string());
    }
    for (index, token) in tokens.iter().enumerate() {
        if !matches!(token.as_str(), "|" | "|&") {
            continue;
        }
        let start = tokens[..index]
            .iter()
            .rposition(|candidate| matches!(candidate.as_str(), ";" | "{" | "}"))
            .map_or(0, |position| position + 1);
        let end = tokens[index + 1..]
            .iter()
            .position(|candidate| matches!(candidate.as_str(), ";" | "{" | "}"))
            .map_or(tokens.len(), |offset| index + 1 + offset);
        if tokens[start..index]
            .iter()
            .any(|candidate| matches!(candidate.as_str(), "print" | "printf"))
            || tokens[index + 1..end]
                .iter()
                .any(|candidate| candidate == "getline")
        {
            return Err("awk command pipes are not allowed in a governed session".to_string());
        }
    }

    let mut paths = Vec::new();
    for (index, token) in tokens.iter().enumerate() {
        let wanted = match token.as_str() {
            "getline" => &["<"][..],
            "print" | "printf" => &[">", ">>"][..],
            _ => continue,
        };
        let end = tokens[index + 1..]
            .iter()
            .position(|candidate| matches!(candidate.as_str(), ";" | "{" | "}"))
            .map_or(tokens.len(), |offset| index + 1 + offset);
        let Some(operator) = tokens[index + 1..end]
            .iter()
            .position(|candidate| wanted.contains(&candidate.as_str()))
            .map(|offset| index + 1 + offset)
        else {
            continue;
        };
        if let Some(path) = tokens[operator + 1..end]
            .iter()
            .find(|candidate| candidate.as_str() != "(")
        {
            paths.push(path.clone());
        }
    }
    Ok(paths)
}

fn inline_program_paths(verb: &str, program: &str) -> Result<Vec<String>, String> {
    match verb {
        "sed" => sed_program_paths(program),
        "awk" => awk_program_paths(program),
        _ => Ok(Vec::new()),
    }
}

fn append_inline_program_paths(
    verb: &str,
    program: &str,
    paths: &mut Vec<String>,
) -> Result<(), String> {
    paths.extend(inline_program_paths(verb, program)?);
    Ok(())
}

/// Record a sed/awk script file, refusing sources whose contents arrive over a
/// shell channel or whose path is produced by word expansion. The governed
/// tokenizer cannot resolve heredoc, pipe, here-string, parameter, command,
/// process, or brace expansion before the shell runs, so accepting one as an
/// ordinary path would skip embedded file-I/O and shell-execution checks.
fn has_brace_expansion_comma(source: &str) -> bool {
    let mut braces = Vec::new();
    let mut escaped = false;
    for ch in source.chars() {
        if escaped {
            escaped = false;
            continue;
        }
        match ch {
            '\\' => escaped = true,
            '{' => braces.push(false),
            ',' => {
                if let Some(brace) = braces.last_mut() {
                    *brace = true;
                }
            }
            '}' if braces.pop().is_some_and(|has_comma| has_comma) => return true,
            _ => {}
        }
    }
    false
}

fn reject_shell_fed_program_source(verb: &str, source: &str) -> Result<(), String> {
    // `./-` is intentionally different from `-`: it names a literal
    // repository file and has the same governed-path posture as `script.sed`.
    let is_program_channel = source.is_empty()
        || source == "-"
        || source == "/dev/stdin"
        || source
            .strip_prefix("/dev/fd/")
            .is_some_and(|fd| !fd.is_empty())
        || source
            .strip_prefix("/proc/self/fd/")
            .is_some_and(|fd| !fd.is_empty())
        || source.starts_with("<(")
        || source.starts_with(">(")
        || source.contains('$')
        || source.contains('`')
        || has_brace_expansion_comma(source);
    if is_program_channel {
        return Err(format!(
            "{verb} script source '{source}' cannot be inspected in a governed session"
        ));
    }
    Ok(())
}

fn append_program_source_path(
    verb: &str,
    source: &str,
    paths: &mut Vec<String>,
) -> Result<(), String> {
    reject_shell_fed_program_source(verb, source)?;
    paths.push(source.to_string());
    Ok(())
}

/// Inspect every standalone script-file option by its own token position.
///
/// This is intentionally independent of preceding options: an empty quoted
/// `-e ''` operand must not let sequential argument consumption hide a later
/// `-f -`. Normal literal sources are collected by the full parser below; this
/// pass only rejects sources whose bytes the shell supplies at execution time.
fn reject_shell_fed_program_file_operands(verb: &str, args: &[String]) -> Result<(), String> {
    for (index, arg) in args.iter().enumerate() {
        if arg == "--" {
            break;
        }
        let is_file_option = matches!(
            (verb, arg.as_str()),
            ("sed", "-f" | "--file") | ("awk", "-f" | "-E" | "--file")
        );
        if is_file_option {
            let source = args.get(index + 1).map_or("", String::as_str);
            reject_shell_fed_program_source(verb, source)?;
        }
    }
    Ok(())
}

/// Arguments that can name files for a governed read command.
///
/// Most verbs use every non-option operand. `sed` and `awk` are different: the
/// first positional operand is a program, and regex addresses commonly begin
/// with `/`, so treating it as a path turns `sed -n '/pub fn/p' src/lib.rs`
/// into an attempted read of `/pub`. Their `-f` operands are real program
/// files and remain governed; shell-fed `-f` channels are refused because their
/// programs cannot be associated safely with the command. `-e` operands are
/// inline programs whose embedded file I/O is extracted and whose
/// command-execution forms are refused.
fn governed_path_arguments(verb: &str, tokens: &[String]) -> Result<Vec<String>, String> {
    let Some(verb_index) = shell_verb_index(tokens) else {
        return Ok(Vec::new());
    };
    let args = &tokens[verb_index + 1..];
    if !matches!(verb, "sed" | "awk") {
        return Ok(args
            .iter()
            .filter(|arg| !arg.starts_with('-'))
            .cloned()
            .collect());
    }

    reject_shell_fed_program_file_operands(verb, args)?;

    let mut paths = Vec::new();
    let mut explicit_program = false;
    let mut positional_program_seen = false;
    let mut options = true;
    let mut index = 0;
    while index < args.len() {
        let arg = args[index].as_str();
        if options && arg == "--" {
            options = false;
            index += 1;
            continue;
        }
        if options && arg.starts_with('-') && arg != "-" {
            match (verb, arg) {
                ("sed", "-e" | "--expression") | ("awk", "-e" | "--source") => {
                    explicit_program = true;
                    if let Some(program) = args.get(index + 1) {
                        append_inline_program_paths(verb, program, &mut paths)?;
                    }
                    index += 2;
                    continue;
                }
                ("sed", "-f" | "--file") | ("awk", "-f" | "-E" | "--file") => {
                    explicit_program = true;
                    if let Some(source) = args.get(index + 1) {
                        append_program_source_path(verb, source, &mut paths)?;
                    }
                    index += 2;
                    continue;
                }
                ("awk", "-F" | "-v") => {
                    index += 2; // field separator / variable assignment
                    continue;
                }
                _ => {}
            }
            if let Some(source) = arg.strip_prefix("--file=") {
                explicit_program = true;
                append_program_source_path(verb, source, &mut paths)?;
                index += 1;
                continue;
            }
            if let Some(program) = arg
                .strip_prefix("--expression=")
                .or_else(|| arg.strip_prefix("--source="))
            {
                explicit_program = true;
                append_inline_program_paths(verb, program, &mut paths)?;
                index += 1;
                continue;
            }

            if verb == "sed" && !arg.starts_with("--") {
                // sed permits no-operand flags to be bundled before the final
                // option that consumes a program or script file: -ne and -nf.
                // In-place editing also accepts an attached backup suffix
                // (-i.bak), whose remainder is not another option.
                let cluster = &arg[1..];
                let mut cursor = 0;
                let mut handled = true;
                while let Some(option) = cluster[cursor..].chars().next() {
                    cursor += option.len_utf8();
                    match option {
                        'n' | 'E' | 'r' | 's' | 'u' | 'z' => {}
                        'e' | 'f' => {
                            explicit_program = true;
                            let attached = &cluster[cursor..];
                            if option == 'e' {
                                if attached.is_empty() {
                                    if let Some(program) = args.get(index + 1) {
                                        append_inline_program_paths("sed", program, &mut paths)?;
                                    }
                                    index += 2;
                                } else {
                                    append_inline_program_paths("sed", attached, &mut paths)?;
                                    index += 1;
                                }
                            } else if attached.is_empty() {
                                if let Some(source) = args.get(index + 1) {
                                    append_program_source_path("sed", source, &mut paths)?;
                                }
                                index += 2;
                            } else {
                                append_program_source_path("sed", attached, &mut paths)?;
                                index += 1;
                            }
                            break;
                        }
                        'i' => {
                            // Everything after i is the backup suffix. The next
                            // argument is still the positional sed program.
                            index += 1;
                            break;
                        }
                        _ => {
                            handled = false;
                            break;
                        }
                    }
                }
                if handled {
                    if cursor == cluster.len()
                        && !matches!(cluster.chars().last(), Some('e' | 'f' | 'i'))
                    {
                        index += 1;
                    }
                    continue;
                }
            }

            let attached_file_source = arg
                .strip_prefix("-f")
                .filter(|source| !source.is_empty())
                .or_else(|| {
                    if verb == "awk" {
                        arg.strip_prefix("-E").filter(|source| !source.is_empty())
                    } else {
                        None
                    }
                });
            if let Some(source) = attached_file_source {
                explicit_program = true;
                append_program_source_path(verb, source, &mut paths)?;
            } else if let Some(program) = arg.strip_prefix("-e").filter(|p| !p.is_empty()) {
                explicit_program = true;
                append_inline_program_paths(verb, program, &mut paths)?;
            }
            index += 1;
            continue;
        }

        if !explicit_program && !positional_program_seen {
            positional_program_seen = true;
            append_inline_program_paths(verb, arg, &mut paths)?;
        } else {
            paths.push(arg.to_string());
        }
        index += 1;
    }
    Ok(paths)
}

/// Remove physical line continuations before either policy tokenizer splits
/// commands at newlines. A shell removes backslash-newline (and the CRLF form)
/// before tokenization, so leaving the pair intact fabricates a command boundary
/// where the shell sees none and can move an outside path into verb position.
fn join_shell_line_continuations(command: &str) -> String {
    let mut logical = String::with_capacity(command.len());
    let mut chars = command.chars().peekable();
    while let Some(ch) = chars.next() {
        if ch == '\\' {
            if chars.peek() == Some(&'\n') {
                chars.next();
                continue;
            }
            if chars.peek() == Some(&'\r') {
                let mut lookahead = chars.clone();
                if lookahead.next() == Some('\r') && lookahead.next() == Some('\n') {
                    chars.next();
                    chars.next();
                    continue;
                }
            }
        }
        logical.push(ch);
    }
    logical
}

#[derive(Debug, PartialEq, Eq)]
enum ShellDeclarationToken {
    Word { text: String, quoted: bool },
    OpenParen,
    CloseParen,
    OpenBrace,
    CloseBrace,
    CommandBoundary,
}

/// Lex only the shell syntax needed to recognize a function declaration.
/// Quotes and escapes stay attached to their word so declaration-shaped text
/// inside a string cannot become syntax. An unquoted `#` at the start of a word
/// consumes a comment through the next newline.
fn shell_declaration_tokens(command: &str) -> Vec<ShellDeclarationToken> {
    fn finish_word(tokens: &mut Vec<ShellDeclarationToken>, word: &mut String, quoted: &mut bool) {
        if !word.is_empty() || *quoted {
            tokens.push(ShellDeclarationToken::Word {
                text: std::mem::take(word),
                quoted: std::mem::take(quoted),
            });
        }
    }

    let mut tokens = Vec::new();
    let mut word = String::new();
    let mut word_quoted = false;
    let logical_command = join_shell_line_continuations(command);
    let segmented_command = split_shell_case_arm_bodies(&logical_command);
    let mut chars = segmented_command.chars().peekable();
    while let Some(ch) = chars.next() {
        match ch {
            '\\' => {
                word_quoted = true;
                if let Some(escaped) = chars.next() {
                    word.push(escaped);
                }
            }
            '\'' | '"' => {
                word_quoted = true;
                let delimiter = ch;
                while let Some(quoted) = chars.next() {
                    if quoted == delimiter {
                        break;
                    }
                    if delimiter == '"' && quoted == '\\' {
                        if let Some(escaped) = chars.next() {
                            word.push(escaped);
                        }
                    } else {
                        word.push(quoted);
                    }
                }
            }
            '#' if word.is_empty() => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                for comment in chars.by_ref() {
                    if comment == '\n' {
                        tokens.push(ShellDeclarationToken::CommandBoundary);
                        break;
                    }
                }
            }
            '\n' | '\r' => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                tokens.push(ShellDeclarationToken::CommandBoundary);
            }
            ch if ch.is_whitespace() => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
            }
            ';' | '；' | '|' | '&' => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                tokens.push(ShellDeclarationToken::CommandBoundary);
                if chars.peek() == Some(&ch) {
                    chars.next();
                }
            }
            '(' => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                tokens.push(ShellDeclarationToken::OpenParen);
            }
            ')' => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                tokens.push(ShellDeclarationToken::CloseParen);
            }
            '{' => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                tokens.push(ShellDeclarationToken::OpenBrace);
            }
            '}' => {
                finish_word(&mut tokens, &mut word, &mut word_quoted);
                tokens.push(ShellDeclarationToken::CloseBrace);
            }
            _ => word.push(ch),
        }
    }
    finish_word(&mut tokens, &mut word, &mut word_quoted);
    tokens
}

/// Whether an unquoted shell function declaration appears in `command`.
///
/// Both declaration families are covered: the `function name { ... }` keyword
/// form and the POSIX/name form `name() { ... }`, including zsh's `:(){ ... }`
/// spelling. The declaration must begin where a command may begin; ordinary
/// arguments such as `echo "f() { ... }"` remain data.
pub(crate) fn contains_shell_function_declaration(command: &str) -> bool {
    use ShellDeclarationToken::*;

    let tokens = shell_declaration_tokens(command);
    let mut command_position = true;
    let mut index = 0;
    while index < tokens.len() {
        if command_position {
            let posix_declaration = matches!(tokens.get(index), Some(Word { text, .. }) if !text.is_empty())
                && matches!(tokens.get(index + 1), Some(OpenParen))
                && matches!(tokens.get(index + 2), Some(CloseParen))
                && matches!(tokens.get(index + 3), Some(OpenBrace));
            let keyword_declaration = matches!(
                tokens.get(index),
                Some(Word { text, quoted: false }) if text == "function"
            ) && matches!(tokens.get(index + 1), Some(Word { text, .. }) if !text.is_empty())
                && (matches!(tokens.get(index + 2), Some(OpenBrace))
                    || (matches!(tokens.get(index + 2), Some(OpenParen))
                        && matches!(tokens.get(index + 3), Some(CloseParen))
                        && matches!(tokens.get(index + 4), Some(OpenBrace))));
            if posix_declaration || keyword_declaration {
                return true;
            }
        }

        match &tokens[index] {
            CommandBoundary | OpenBrace | OpenParen => command_position = true,
            Word {
                text,
                quoted: false,
            } if matches!(
                text.as_str(),
                "if" | "then" | "elif" | "else" | "while" | "until" | "do" | "time" | "!"
            ) =>
            {
                command_position = true
            }
            _ => command_position = false,
        }
        index += 1;
    }
    false
}

/// A function declaration gives a model a persistent shell-language primitive
/// whose body is opaque to later command-policy checks. The incident that
/// motivated this gate was the classic `:(){ :|:& };:` fork bomb: by the time
/// process limits react, the shared host is already unavailable. Coding models
/// therefore cannot declare shell functions; a human can run an intentionally
/// reviewed declaration outside the model-facing shell.
struct DenyShellFunctionDeclaration;

impl Inspector for DenyShellFunctionDeclaration {
    fn name(&self) -> &'static str {
        "coder.deny_shell_function_declaration"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(command) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        if contains_shell_function_declaration(&command) {
            InspectionResult::Deny(
                "shell function declarations require explicit human approval and cannot be run by a coding model"
                    .into(),
            )
        } else {
            InspectionResult::Allow
        }
    }
}

#[derive(Clone, Copy)]
enum CaseScanPhase {
    Header { subject_seen: bool },
    Pattern,
    Body,
}

fn shell_word_keeps_command_position(word: &str) -> bool {
    matches!(
        word,
        "{" | "}"
            | "if"
            | "then"
            | "elif"
            | "else"
            | "fi"
            | "for"
            | "do"
            | "done"
            | "while"
            | "until"
            | "function"
            | "time"
            | "!"
    )
}

fn finish_case_scan_word(
    token: &mut String,
    token_started: &mut bool,
    token_quoted: &mut bool,
    cases: &mut Vec<CaseScanPhase>,
    command_position: &mut bool,
) {
    if !std::mem::take(token_started) {
        return;
    }
    let word = std::mem::take(token);
    let quoted = std::mem::take(token_quoted);
    match cases.last().copied() {
        Some(CaseScanPhase::Header { subject_seen }) => {
            if subject_seen && !quoted && word == "in" {
                *cases.last_mut().expect("case header exists") = CaseScanPhase::Pattern;
                *command_position = true;
            } else if !subject_seen {
                *cases.last_mut().expect("case header exists") =
                    CaseScanPhase::Header { subject_seen: true };
            }
        }
        Some(CaseScanPhase::Pattern) => {
            if !quoted && word == "esac" && *command_position {
                cases.pop();
                *command_position = false;
            }
        }
        Some(CaseScanPhase::Body) | None => {
            if !quoted && word == "esac" && *command_position && !cases.is_empty() {
                cases.pop();
                *command_position = false;
            } else if !quoted && word == "case" && *command_position {
                cases.push(CaseScanPhase::Header {
                    subject_seen: false,
                });
                *command_position = false;
            } else {
                *command_position =
                    !quoted && *command_position && shell_word_keeps_command_position(&word);
            }
        }
    }
}

/// Insert a command boundary after each unquoted `case` arm pattern. Shell
/// terminators already split the body from the next arm, but the opening `)`
/// otherwise leaves `case x in x) sudo …` in one policy segment and lets `x)`
/// take the verb slot. The small state machine is quote-aware, follows nested
/// cases, and recognizes all three arm terminators (`;;`, `;&`, and `;;&`).
fn split_shell_case_arm_bodies(command: &str) -> String {
    let mut output = String::with_capacity(command.len());
    let mut token = String::new();
    let mut token_started = false;
    let mut token_quoted = false;
    let mut quote = None;
    let mut nested_parentheses = 0usize;
    let mut cases = Vec::new();
    let mut command_position = true;
    let mut chars = command.chars().peekable();

    while let Some(ch) = chars.next() {
        output.push(ch);
        if let Some(delimiter) = quote {
            if ch == delimiter {
                quote = None;
            } else if delimiter == '"' && ch == '\\' {
                if let Some(escaped) = chars.next() {
                    output.push(escaped);
                    token.push(escaped);
                    token_started = true;
                }
            } else {
                token.push(ch);
                token_started = true;
            }
            continue;
        }
        if nested_parentheses > 0 {
            token.push(ch);
            token_started = true;
            match ch {
                '\\' => {
                    if let Some(escaped) = chars.next() {
                        output.push(escaped);
                        token.push(escaped);
                    }
                }
                '\'' | '"' => {
                    quote = Some(ch);
                    token_quoted = true;
                }
                '(' => nested_parentheses += 1,
                ')' => nested_parentheses -= 1,
                _ => {}
            }
            continue;
        }

        match ch {
            '\\' => {
                if let Some(escaped) = chars.next() {
                    output.push(escaped);
                    token.push(escaped);
                    token_started = true;
                    token_quoted = true;
                }
            }
            '\'' | '"' => {
                quote = Some(ch);
                token_started = true;
                token_quoted = true;
            }
            ch if ch.is_whitespace() => {
                finish_case_scan_word(
                    &mut token,
                    &mut token_started,
                    &mut token_quoted,
                    &mut cases,
                    &mut command_position,
                );
                if matches!(ch, '\n' | '\r') {
                    command_position = true;
                }
            }
            ')' if matches!(cases.last(), Some(CaseScanPhase::Pattern)) => {
                let case_depth = cases.len();
                finish_case_scan_word(
                    &mut token,
                    &mut token_started,
                    &mut token_quoted,
                    &mut cases,
                    &mut command_position,
                );
                // An unspaced `esac)` pops the case while finishing `esac`; its
                // `)` closes the surrounding subshell rather than a new arm.
                if cases.len() == case_depth {
                    *cases.last_mut().expect("case pattern remains") = CaseScanPhase::Body;
                    command_position = true;
                    output.push('\n');
                }
            }
            ';' => {
                finish_case_scan_word(
                    &mut token,
                    &mut token_started,
                    &mut token_quoted,
                    &mut cases,
                    &mut command_position,
                );
                let mut arm_terminator = false;
                if chars.peek() == Some(&';') {
                    output.push(chars.next().expect("peeked second semicolon"));
                    arm_terminator = true;
                    if chars.peek() == Some(&'&') {
                        output.push(chars.next().expect("peeked case terminator ampersand"));
                    }
                } else if chars.peek() == Some(&'&') {
                    output.push(chars.next().expect("peeked case terminator ampersand"));
                    arm_terminator = true;
                }
                if arm_terminator && matches!(cases.last(), Some(CaseScanPhase::Body)) {
                    *cases.last_mut().expect("case body exists") = CaseScanPhase::Pattern;
                }
                command_position = true;
            }
            '|' | '&' => {
                finish_case_scan_word(
                    &mut token,
                    &mut token_started,
                    &mut token_quoted,
                    &mut cases,
                    &mut command_position,
                );
                if chars.peek() == Some(&ch) {
                    output.push(chars.next().expect("peeked shell operator"));
                }
                if !matches!(cases.last(), Some(CaseScanPhase::Pattern)) {
                    command_position = true;
                }
            }
            '(' if token
                .chars()
                .last()
                .is_some_and(|prefix| matches!(prefix, '$' | '<' | '>'))
                || (matches!(cases.last(), Some(CaseScanPhase::Pattern))
                    && token
                        .chars()
                        .last()
                        .is_some_and(|prefix| matches!(prefix, '@' | '+' | '?' | '*' | '!'))) =>
            {
                token.push(ch);
                token_started = true;
                nested_parentheses = 1;
            }
            '(' => {
                finish_case_scan_word(
                    &mut token,
                    &mut token_started,
                    &mut token_quoted,
                    &mut cases,
                    &mut command_position,
                );
                if !matches!(cases.last(), Some(CaseScanPhase::Pattern)) {
                    command_position = true;
                }
            }
            ')' => {
                finish_case_scan_word(
                    &mut token,
                    &mut token_started,
                    &mut token_quoted,
                    &mut cases,
                    &mut command_position,
                );
                command_position = false;
            }
            '{' | '}'
                if !token_started
                    && chars.peek().is_none_or(|next| {
                        next.is_whitespace() || matches!(next, ';' | '；' | '|' | '&')
                    }) =>
            {
                command_position = true;
            }
            _ => {
                token.push(ch);
                token_started = true;
            }
        }
    }
    finish_case_scan_word(
        &mut token,
        &mut token_started,
        &mut token_quoted,
        &mut cases,
        &mut command_position,
    );
    output
}

/// Tokenize governed read commands while retaining quoted programs as one
/// argument. The general policy lexer intentionally splits quoted whitespace
/// conservatively, but doing that here changes one `sed` script into several
/// apparent operands and recreates the path false positive this gate avoids.
/// An empty quote attached to another token is retained as an empty following
/// operand so `-f""` cannot silently consume the next argument as its source.
fn governed_shell_segments(command: &str) -> Vec<Vec<String>> {
    fn finish_token(
        token: &mut String,
        started: &mut bool,
        attached_empty: &mut bool,
        tokens: &mut Vec<String>,
    ) {
        if std::mem::take(started) {
            tokens.push(std::mem::take(token));
            if std::mem::take(attached_empty) {
                tokens.push(String::new());
            }
        }
    }
    fn finish_segment(
        token: &mut String,
        started: &mut bool,
        attached_empty: &mut bool,
        tokens: &mut Vec<String>,
        result: &mut Vec<Vec<String>>,
    ) {
        finish_token(token, started, attached_empty, tokens);
        if !tokens.is_empty() {
            result.push(std::mem::take(tokens));
        }
    }

    let mut result = Vec::new();
    let mut tokens = Vec::new();
    let mut token = String::new();
    let mut token_started = false;
    let mut attached_empty = false;
    let mut quote = None;
    let mut arithmetic_depth = 0usize;
    let logical_command = split_shell_case_arm_bodies(&join_shell_line_continuations(command));
    let mut chars = logical_command.chars().peekable();
    while let Some(ch) = chars.next() {
        // `((...))` and `$((...))` are arithmetic, not subshells. Retain the
        // whole expression as a token so nested arithmetic parentheses never
        // fabricate shell-command segments.
        if arithmetic_depth > 0 {
            token.push(ch);
            token_started = true;
            attached_empty = false;
            match ch {
                '(' => arithmetic_depth += 1,
                ')' => arithmetic_depth -= 1,
                _ => {}
            }
            continue;
        }
        if let Some((delimiter, start_len, was_attached)) = quote {
            if ch == delimiter {
                quote = None;
                if was_attached && token.len() == start_len {
                    attached_empty = true;
                }
            } else if delimiter == '"' && ch == '\\' {
                // In double quotes the shell removes a backslash only before
                // $, `, ", and \. Single quotes preserve every backslash.
                if chars
                    .peek()
                    .is_some_and(|next| matches!(next, '$' | '`' | '"' | '\\'))
                {
                    token.push(chars.next().expect("peeked escaped character"));
                } else {
                    token.push(ch);
                }
                attached_empty = false;
            } else {
                token.push(ch);
                attached_empty = false;
            }
            continue;
        }
        match ch {
            // Outside quotes, the shell removes a backslash and treats the
            // following byte literally before argv reaches the command. Keep
            // that byte in this token so `\-`, `\/etc`, escaped whitespace,
            // and escaped separators reach the same policy checks as the
            // argument the command actually receives. Quoted backslashes are
            // handled above according to the quote kind because sed/awk
            // programs depend on escapes that the shell preserves.
            '\\' => {
                #[cfg(windows)]
                {
                    // `shell` is cmd.exe on Windows, where backslash is a path
                    // separator rather than POSIX quote removal. Erasing it
                    // converts `C:\outside` into `C:outside` and bypasses the
                    // governed-root check.
                    token.push(ch);
                }
                #[cfg(not(windows))]
                {
                    if let Some(escaped) = chars.next() {
                        token.push(escaped);
                    } else {
                        token.push(ch);
                    }
                }
                token_started = true;
                attached_empty = false;
            }
            '\'' | '"' => {
                quote = Some((ch, token.len(), token_started));
                token_started = true;
            }
            // A shell newline starts a new command exactly like `;`. Handle it
            // before generic whitespace or the next line becomes an argument
            // to the first verb and can bypass that line's path gate.
            '\n' | '\r' => finish_segment(
                &mut token,
                &mut token_started,
                &mut attached_empty,
                &mut tokens,
                &mut result,
            ),
            // A standalone brace is shell grammar, not a command. Split at it
            // while quote state is still available so `function f { PWD=...`
            // starts a fresh assignment-bearing segment without mistaking
            // quoted braces or ordinary words such as `a{b}` for syntax.
            '{' | '}'
                if !token_started
                    && chars.peek().is_none_or(|next| {
                        next.is_whitespace() || matches!(next, ';' | '；' | '|' | '&')
                    }) =>
            {
                finish_segment(
                    &mut token,
                    &mut token_started,
                    &mut attached_empty,
                    &mut tokens,
                    &mut result,
                )
            }
            ch if ch.is_whitespace() => finish_token(
                &mut token,
                &mut token_started,
                &mut attached_empty,
                &mut tokens,
            ),
            ';' | '；' | '|' | '&' => {
                finish_segment(
                    &mut token,
                    &mut token_started,
                    &mut attached_empty,
                    &mut tokens,
                    &mut result,
                );
                if matches!(ch, '|' | '&') && chars.peek() == Some(&ch) {
                    chars.next();
                }
            }
            // Keep a process-substitution opener attached to its redirect.
            // The sed/awk source gate recognizes `<(` and `>(` as dynamic,
            // uninspectable program sources; splitting off the parenthesis
            // would erase that stronger denial before the body is segmented.
            '(' if matches!(token.chars().last(), Some('<' | '>')) => {
                token.push(ch);
                token_started = true;
                attached_empty = false;
            }
            '(' if chars.peek() == Some(&'(') => {
                token.push(ch);
                token.push(chars.next().expect("peeked arithmetic parenthesis"));
                token_started = true;
                attached_empty = false;
                arithmetic_depth = 2;
            }
            // A grouping subshell, including a command-substitution body,
            // starts and ends a command segment. Quoted parentheses remain
            // arguments because quote handling above consumes them first.
            '(' | ')' => finish_segment(
                &mut token,
                &mut token_started,
                &mut attached_empty,
                &mut tokens,
                &mut result,
            ),
            _ => {
                token.push(ch);
                token_started = true;
                attached_empty = false;
            }
        }
    }
    finish_segment(
        &mut token,
        &mut token_started,
        &mut attached_empty,
        &mut tokens,
        &mut result,
    );
    result
}

/// A command that launches the remaining arguments without changing their
/// meaning. Each carrier owns a different option grammar, so keep the arity in
/// one table rather than guessing that every option is a flag.
#[derive(Clone, Copy)]
struct CommandCarrier {
    name: &'static str,
    short_value_options: &'static [char],
    long_value_options: &'static [&'static str],
    leading_operands: usize,
    assignments: bool,
}

const COMMAND_CARRIERS: &[CommandCarrier] = &[
    CommandCarrier {
        name: "env",
        short_value_options: &['a', 'C', 'S', 'u'],
        long_value_options: &["--argv0", "--chdir", "--split-string", "--unset"],
        leading_operands: 0,
        assignments: true,
    },
    CommandCarrier {
        name: "command",
        short_value_options: &[],
        long_value_options: &[],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "exec",
        short_value_options: &['a'],
        long_value_options: &[],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "nohup",
        short_value_options: &[],
        long_value_options: &[],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "time",
        short_value_options: &['f', 'o'],
        long_value_options: &["--format", "--output"],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "nice",
        short_value_options: &['n'],
        long_value_options: &["--adjustment"],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "caffeinate",
        short_value_options: &['t', 'w'],
        long_value_options: &[],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "script",
        short_value_options: &['B', 'F', 'I', 'O', 'T', 'c', 'm', 't'],
        long_value_options: &[
            "--command",
            "--log-in",
            "--log-io",
            "--log-out",
            "--log-timing",
            "--logging-format",
        ],
        // BSD script accepts `file [command ...]`; the file is the carrier's
        // operand, not the launched command.
        leading_operands: 1,
        assignments: false,
    },
    CommandCarrier {
        name: "xargs",
        short_value_options: &['E', 'I', 'J', 'L', 'P', 'R', 'S', 'a', 'd', 'n', 's'],
        long_value_options: &[
            "--arg-file",
            "--delimiter",
            "--eof",
            "--max-args",
            "--max-chars",
            "--max-lines",
            "--max-procs",
            "--replace",
        ],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "builtin",
        short_value_options: &[],
        long_value_options: &[],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        // BusyBox dispatches its first non-option operand as an applet. Expose
        // that applet to the same inspectors as a standalone command.
        name: "busybox",
        short_value_options: &[],
        long_value_options: &[],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "sudo",
        short_value_options: &['C', 'D', 'R', 'T', 'a', 'g', 'h', 'p', 'r', 't', 'u'],
        long_value_options: &[
            "--auth-type",
            "--chdir",
            "--chroot",
            "--close-from",
            "--command-timeout",
            "--group",
            "--host",
            "--prompt",
            "--role",
            "--type",
            "--user",
        ],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "ionice",
        short_value_options: &['P', 'c', 'n', 'p', 'u'],
        long_value_options: &["--class", "--classdata", "--pgid", "--pid", "--uid"],
        leading_operands: 0,
        assignments: false,
    },
    CommandCarrier {
        name: "timeout",
        short_value_options: &['k', 's'],
        long_value_options: &["--kill-after", "--signal"],
        // The duration belongs to timeout; the next operand is the command.
        leading_operands: 1,
        assignments: false,
    },
];

fn executable_name(raw: &str) -> String {
    let lower = raw.to_ascii_lowercase();
    let name = Path::new(&lower)
        .file_name()
        .and_then(|name| name.to_str())
        .unwrap_or(&lower);
    name.strip_suffix(".exe").unwrap_or(name).to_string()
}

#[derive(Clone, Copy)]
struct ShellAssignmentParts<'a> {
    name: &'a str,
    subscript: Option<&'a str>,
    value: &'a str,
}

fn shell_assignment_parts(token: &str) -> Option<ShellAssignmentParts<'_>> {
    let name_length = shell_name_len(token);
    if name_length == 0 {
        return None;
    }
    let name = &token[..name_length];
    let remainder = &token[name_length..];
    let (subscript, operator) = if remainder.starts_with('[') {
        let mut depth = 0usize;
        let mut close = None;
        for (index, ch) in remainder.char_indices() {
            match ch {
                '[' => depth += 1,
                ']' => {
                    depth = depth.checked_sub(1)?;
                    if depth == 0 {
                        close = Some(index);
                        break;
                    }
                }
                _ => {}
            }
        }
        let close = close?;
        (Some(&remainder[1..close]), &remainder[close + 1..])
    } else {
        (None, remainder)
    };
    // Shell append assignments have the same name and safety implications as
    // ordinary assignments; `+=` is the operator after either a scalar name or
    // an array subscript.
    let value = operator
        .strip_prefix("+=")
        .or_else(|| operator.strip_prefix('='))?;
    Some(ShellAssignmentParts {
        name,
        subscript,
        value,
    })
}

fn shell_subscript_contains_command_substitution(subscript: &str) -> bool {
    if subscript.contains('`') {
        return true;
    }
    let mut cursor = 0usize;
    while let Some(relative) = subscript[cursor..].find("$(") {
        let start = cursor + relative;
        // `$((...))` is arithmetic expansion, not command substitution. Keep
        // scanning its contents because they may themselves contain `$(...)`.
        if subscript[start + 2..].starts_with('(') {
            cursor = start + 3;
        } else {
            return true;
        }
    }
    false
}

/// Why an array-assignment subscript found in the raw command cannot be trusted
/// to reach the tokenised assignment check intact.
#[derive(Clone, Copy, PartialEq, Eq)]
enum SubscriptFlaw {
    /// The subscript runs a command, so its value cannot be inspected at all.
    CommandSubstitution,
    /// The subscript holds characters the deliberately small tokenizer splits
    /// on or rewrites, so `NAME[subscript]=value` never reaches
    /// `shell_assignment_parts` as a single assignment token.
    BreaksTokenization,
}

/// Classify a raw subscript. A command substitution cannot be inspected at all;
/// whitespace, a shell separator, a quote, or a backslash escape hides the
/// assignment from the tokenised path in exactly the same way. One rule covers
/// both rather than a special case per spelling.
fn subscript_flaw(subscript: &str) -> Option<SubscriptFlaw> {
    if shell_subscript_contains_command_substitution(subscript) {
        return Some(SubscriptFlaw::CommandSubstitution);
    }
    subscript
        .chars()
        .any(|ch| ch.is_whitespace() || matches!(ch, ';' | '；' | '|' | '&' | '\'' | '"' | '\\'))
        .then_some(SubscriptFlaw::BreaksTokenization)
}

/// Find the array-assignment subscripts in the raw command that the tokenised
/// assignment check cannot see intact. Single-quoted text is inert and is
/// skipped. A candidate must begin at a shell word boundary and have a closing
/// bracket followed immediately by `=` or `+=`.
fn uninspectable_assignment_subscripts(command: &str) -> Vec<(&str, SubscriptFlaw)> {
    let bytes = command.as_bytes();
    let mut found = Vec::new();
    let mut index = 0usize;
    let mut quote = None;
    let mut word_boundary = true;
    while index < bytes.len() {
        let byte = bytes[index];
        if let Some(delimiter) = quote {
            if byte == delimiter {
                quote = None;
            } else if delimiter == b'"' && byte == b'\\' {
                index += usize::from(index + 1 < bytes.len());
            }
            index += 1;
            continue;
        }
        match byte {
            b'\\' => {
                index += 1 + usize::from(index + 1 < bytes.len());
                word_boundary = false;
            }
            b'\'' | b'"' => {
                quote = Some(byte);
                word_boundary = false;
                index += 1;
            }
            b' ' | b'\t' | b'\r' | b'\n' | b';' | b'|' | b'&' | b'(' => {
                word_boundary = true;
                index += 1;
            }
            b'_' | b'a'..=b'z' | b'A'..=b'Z' if word_boundary => {
                let name_start = index;
                index += 1;
                while index < bytes.len()
                    && matches!(bytes[index], b'_' | b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9')
                {
                    index += 1;
                }
                if bytes.get(index) == Some(&b'[') {
                    let subscript_start = index + 1;
                    let mut close_search = subscript_start;
                    while let Some(relative) = command[close_search..].find(']') {
                        let close = close_search + relative;
                        let after = &command[close + 1..];
                        if after.starts_with('=') || after.starts_with("+=") {
                            let subscript = &command[subscript_start..close];
                            if let Some(flaw) = subscript_flaw(subscript) {
                                found.push((&command[name_start..index], flaw));
                            }
                            break;
                        }
                        close_search = close + 1;
                    }
                }
                word_boundary = false;
            }
            _ => {
                word_boundary = false;
                index += 1;
            }
        }
    }
    found
}

fn shell_assignment(token: &str) -> bool {
    shell_assignment_parts(token).is_some()
}

/// Shell grammar words that introduce, separate, or decorate compound
/// commands. They are syntax, never the executable verb whose presence ends
/// the leading-assignment region.
fn compound_command_keyword(token: &str) -> bool {
    matches!(
        token,
        "{" | "}"
            | "if"
            | "then"
            | "elif"
            | "else"
            | "fi"
            | "for"
            | "do"
            | "done"
            | "while"
            | "until"
            | "case"
            | "esac"
            | "function"
            | "time"
            | "!"
    )
}

/// Locate the executable after leading assignments and compound-command
/// syntax. `time` still enters the carrier parser so its value-taking options
/// are consumed before the timed command is inspected; assignment scanning
/// independently treats it as syntax. Keeping this classification shared
/// prevents the path, carrier, and general shell-policy passes from disagreeing
/// about the verb.
///
/// A function declaration — `function NAME { … }` or POSIX `NAME() { … }` —
/// declares a name; it does not run it. The head sits where a verb would, so
/// without this it takes the verb slot and hides the body's real command from
/// every per-verb inspector.
fn shell_verb_index(tokens: &[String]) -> Option<usize> {
    let mut index = 0;
    while let Some(token) = tokens.get(index) {
        if token == "function" {
            // The keyword consumes exactly the following word, the name.
            index += 2;
            continue;
        }
        if let Some(span) = posix_function_head(&tokens[index..]) {
            index += span;
            continue;
        }
        if shell_assignment(token) {
            index += 1;
            continue;
        }
        if compound_command_keyword(token) && token != "time" {
            index += 1;
            continue;
        }
        return Some(index);
    }
    None
}

/// Length, in tokens, of a POSIX `NAME() { … }` declaration head at the front
/// of `tokens` — or `None` when this is not one.
///
/// Neither tokenizer keeps the head in one piece, and they disagree about how
/// it splits, so four shapes reach here: `NAME()`, `NAME(){`, `NAME` + `()`,
/// and `NAME` + `(` + `)`. Joining the candidate tokens collapses all four.
///
/// The body's opening brace is REQUIRED, either glued to the head or as the
/// next token. Without it `grep '()' file` joins to `grep()` as well — both
/// tokenizers drop quotes — and the real verb would be skipped, turning a
/// checked command into an unchecked one. Note also that only a head with a
/// NAME matches: a bare `(` stays an ordinary token, so this does not reach
/// inside a `( … )` subshell, which remains a separate open gap.
fn posix_function_head(tokens: &[String]) -> Option<usize> {
    for span in 1..=3.min(tokens.len()) {
        let joined: String = tokens[..span].concat();
        let Some(name) = joined
            .strip_suffix("(){")
            .or_else(|| joined.strip_suffix("()"))
        else {
            continue;
        };
        if name.is_empty()
            || !name
                .chars()
                .all(|c| c.is_alphanumeric() || matches!(c, '_' | '-' | '.'))
        {
            continue;
        }
        if joined.ends_with('{') || tokens.get(span).is_some_and(|next| next == "{") {
            return Some(span);
        }
    }
    None
}

/// Leading assignments in one tokenised command, plus the first command in a
/// one-line `case` arm. Semicolon/newline separators and standalone braces are
/// already separate segments; a case pattern's closing `)` is the remaining
/// shell boundary retained inside a segment.
fn leading_shell_assignments(command: &[String]) -> Vec<&str> {
    fn collect<'a>(command: &'a [String], start: usize, found: &mut Vec<&'a str>) {
        for token in &command[start..] {
            if compound_command_keyword(token) {
                continue;
            }
            if shell_assignment(token) {
                found.push(token);
                continue;
            }
            break;
        }
    }

    let mut found = Vec::new();
    collect(command, 0, &mut found);

    let case_header = command.first().is_some_and(|token| token == "case");
    let case_arm = command.first().is_some_and(|token| token.ends_with(')'));
    if case_header || case_arm {
        for (index, token) in command.iter().enumerate() {
            if token.ends_with(')') && !token.contains("$(") {
                collect(command, index + 1, &mut found);
            }
        }
    }
    found
}

fn carrier_option_consumes_next(spec: CommandCarrier, option: &str) -> bool {
    if spec.long_value_options.contains(&option) {
        return true;
    }
    if option.starts_with("--") {
        return false;
    }

    let mut options = option.strip_prefix('-').unwrap_or("").chars().peekable();
    while let Some(option) = options.next() {
        if spec.short_value_options.contains(&option) {
            // A value attached in the same token consumes the rest of the
            // cluster; only a final value-taking option consumes argv[i + 1].
            return options.peek().is_none();
        }
    }
    false
}

struct CarrierInvocation<'a> {
    command: &'a [String],
    assignments: Vec<&'a str>,
}

/// Return the command portion of one carrier invocation. `None` means the verb
/// is not a carrier; an empty `command` means it is a valid carrier-only
/// invocation. Assignments are returned separately so governed sessions can
/// inspect the environment that changes the launched command's meaning.
fn carrier_command<'a>(
    tokens: &'a [String],
    verb_index: usize,
    verb: &str,
) -> Option<CarrierInvocation<'a>> {
    let spec = *COMMAND_CARRIERS.iter().find(|spec| spec.name == verb)?;
    let args = &tokens[verb_index + 1..];
    // `command -v/-V` queries the shell's command table; it does not launch
    // the named operand. Treat it as a terminal carrier invocation so asking
    // whether (for example) sudo exists does not trigger sudo's policy.
    if verb == "command"
        && args
            .iter()
            .take_while(|arg| arg.as_str() != "--")
            .any(|arg| {
                arg.strip_prefix('-')
                    .filter(|short| !short.starts_with('-'))
                    .is_some_and(|short| short.contains('v') || short.contains('V'))
            })
    {
        return Some(CarrierInvocation {
            command: &[],
            assignments: Vec::new(),
        });
    }
    let mut index = 0;
    let mut options = true;
    let mut assignments = Vec::new();
    while index < args.len() {
        let arg = args[index].as_str();
        if options && arg == "--" {
            options = false;
            index += 1;
            continue;
        }
        if options && arg.starts_with('-') && arg != "-" {
            let consumes_next = !arg.contains('=') && carrier_option_consumes_next(spec, arg);
            index += 1 + usize::from(consumes_next && index + 1 < args.len());
            continue;
        }
        if spec.assignments && shell_assignment(arg) {
            assignments.push(arg);
            index += 1;
            continue;
        }
        break;
    }
    index = (index + spec.leading_operands).min(args.len());
    Some(CarrierInvocation {
        command: &args[index..],
        assignments,
    })
}

/// Find a command-string flag in a short-option cluster, stopping when an
/// option consumes the rest of that token (or the following argument).
fn has_short_command_flag(args: &[String], wanted: char, value_options: &[char]) -> bool {
    let mut index = 0;
    while index < args.len() {
        let arg = args[index].as_str();
        if arg == "--" || !arg.starts_with('-') || arg == "-" {
            break;
        }
        let Some(short) = arg
            .strip_prefix('-')
            .filter(|short| !short.starts_with('-'))
        else {
            index += 1;
            continue;
        };
        let mut options = short.chars().peekable();
        while let Some(option) = options.next() {
            if option == wanted {
                return true;
            }
            if value_options.contains(&option) {
                if options.peek().is_none() {
                    index += 1;
                }
                break;
            }
        }
        index += 1;
    }
    false
}

fn shell_has_script_operand(args: &[String]) -> bool {
    let mut index = 0;
    while index < args.len() {
        let arg = args[index].as_str();
        if arg == "--" {
            return index + 1 < args.len();
        }
        if !arg.starts_with('-') || arg == "-" {
            return true;
        }
        let consumes_next = matches!(arg, "-O" | "-o" | "--init-file" | "--rcfile");
        index += 1 + usize::from(consumes_next && index + 1 < args.len());
    }
    false
}

fn nested_command_carrier(verb: &str, args: &[String]) -> bool {
    if verb == "eval" {
        return true;
    }
    // env -S asks env to split one opaque argv item into a fresh command line.
    // Deny it like an interpreter command string rather than pretending the
    // split can be reproduced by this deliberately small tokenizer.
    if verb == "env" {
        return has_short_command_flag(args, 'S', &['a', 'C', 'S', 'u'])
            || args
                .iter()
                .any(|arg| arg == "--split-string" || arg.starts_with("--split-string="));
    }
    if matches!(
        verb,
        "bash" | "sh" | "zsh" | "dash" | "ksh" | "fish" | "ash"
    ) {
        return has_short_command_flag(args, 'c', &['O', 'o'])
            || (verb == "fish"
                && (has_short_command_flag(args, 'C', &['C'])
                    || args.iter().any(|arg| {
                        matches!(arg.as_str(), "--command" | "--init-command")
                            || arg.starts_with("--command=")
                            || arg.starts_with("--init-command=")
                    })))
            || !shell_has_script_operand(args);
    }
    if verb == "script" {
        return has_short_command_flag(args, 'c', &['B', 'F', 'I', 'O', 'T', 'c', 'm', 't'])
            || args
                .iter()
                .any(|arg| arg == "--command" || arg.starts_with("--command="));
    }
    if verb == "perl" {
        // Perl's -E is -e with optional features enabled. Stop at options such
        // as -M whose attached module name is an argument, not more flags.
        const PERL_VALUE_OPTIONS: &[char] =
            &['0', 'C', 'D', 'F', 'I', 'M', 'V', 'd', 'i', 'l', 'm', 'x'];
        return has_short_command_flag(args, 'e', PERL_VALUE_OPTIONS)
            || has_short_command_flag(args, 'E', PERL_VALUE_OPTIONS);
    }
    if matches!(verb, "ruby" | "node" | "osascript") {
        let value_options: &[char] = match verb {
            "ruby" => &['0', 'C', 'E', 'F', 'I', 'S', 'i', 'r', 'x'],
            "node" => &['C', 'r'],
            "osascript" => &['l'],
            _ => unreachable!("matched interpreter"),
        };
        return has_short_command_flag(args, 'e', value_options)
            || (verb == "node"
                && args
                    .iter()
                    .any(|arg| arg == "--eval" || arg.starts_with("--eval=")));
    }
    if verb == "python"
        || verb == "py"
        || verb == "python3"
        || verb
            .strip_prefix("python3.")
            .is_some_and(|minor| minor.chars().all(|ch| ch.is_ascii_digit()))
    {
        return has_short_command_flag(args, 'c', &['W', 'X', 'Q', 'm']);
    }
    false
}

struct LeadingShellVariable<'a> {
    /// Parameter-expansion syntax between the variable name and `}`. Even for
    /// an allowlisted name, modifiers can transform the known value and are
    /// therefore not inspectable by this deliberately small parser.
    modifier: &'a str,
    /// Empty for a bare variable operand; otherwise begins with `/`.
    suffix: &'a str,
}

fn shell_name_len(value: &str) -> usize {
    let mut chars = value.char_indices();
    let Some((_, first)) = chars.next() else {
        return 0;
    };
    if first != '_' && !first.is_ascii_alphabetic() {
        return 0;
    }
    chars
        .take_while(|(_, ch)| *ch == '_' || ch.is_ascii_alphanumeric())
        .last()
        .map_or(first.len_utf8(), |(index, ch)| index + ch.len_utf8())
}

/// Recognize a shell variable that controls the beginning of a path operand.
/// Exact dollar-named repository entries are handled as a narrow literal
/// exception by [`variable_operand_denial`].
fn leading_shell_variable(candidate: &str) -> Option<LeadingShellVariable<'_>> {
    if let Some(rest) = candidate.strip_prefix("${") {
        let length = shell_name_len(rest);
        if length == 0 {
            return None;
        }
        let mut depth = 1usize;
        let mut close = None;
        let mut index = length;
        while index < rest.len() {
            if rest[index..].starts_with("${") {
                depth += 1;
                index += 2;
                continue;
            }
            let ch = rest[index..].chars().next().expect("index is in bounds");
            if ch == '}' {
                depth -= 1;
                if depth == 0 {
                    close = Some(index);
                    break;
                }
            }
            index += ch.len_utf8();
        }
        let close = close?;
        let suffix = &rest[close + 1..];
        if !suffix.is_empty() && !suffix.starts_with('/') {
            return None;
        }
        return Some(LeadingShellVariable {
            modifier: &rest[length..close],
            suffix,
        });
    }

    let rest = candidate.strip_prefix('$')?;
    let length = shell_name_len(rest);
    if length == 0 {
        return None;
    }
    let suffix = &rest[length..];
    if !suffix.is_empty() && !suffix.starts_with('/') {
        return None;
    }
    Some(LeadingShellVariable {
        modifier: "",
        suffix,
    })
}

#[derive(Clone, Copy)]
struct ShellVariableReference<'a> {
    name: &'a str,
    start: usize,
    end: usize,
}

/// Parse every parameter expansion in a prospective path. Only plain `$NAME`
/// and `${NAME}` forms are inspectable. Positional/special parameters, command
/// substitution, malformed braces, and modifier expansions all fail closed.
fn shell_variable_references(candidate: &str) -> Result<Vec<ShellVariableReference<'_>>, ()> {
    let mut references = Vec::new();
    let mut cursor = 0;
    while let Some(relative) = candidate[cursor..].find('$') {
        let start = cursor + relative;
        let after_dollar = start + 1;
        let rest = &candidate[after_dollar..];
        if let Some(braced) = rest.strip_prefix('{') {
            let length = shell_name_len(braced);
            if length == 0 || !braced[length..].starts_with('}') {
                return Err(());
            }
            let end = after_dollar + 1 + length + 1;
            references.push(ShellVariableReference {
                name: &braced[..length],
                start,
                end,
            });
            cursor = end;
        } else {
            let length = shell_name_len(rest);
            if length == 0 {
                return Err(());
            }
            let end = after_dollar + length;
            references.push(ShellVariableReference {
                name: &rest[..length],
                start,
                end,
            });
            cursor = end;
        }
    }
    Ok(references)
}

fn resolved_shell_variable<'a>(
    gate: &'a DenyGovernedShellPathEscape,
    name: &str,
) -> Option<&'a Path> {
    match name {
        "PWD" => Some(gate.worktree.as_path()),
        "OLDPWD" if gate.oldpwd_is_worktree => Some(gate.worktree.as_path()),
        "CARGO_TARGET_DIR" => gate.cargo_target_dir.as_deref(),
        _ => None,
    }
}

/// Deny any uninspectable variable in a path operand, whether it is leading or
/// follows a fixed path segment. Known variables are expanded from values
/// pinned when the gate is constructed, then the resulting path is checked.
fn variable_operand_denial(
    gate: &DenyGovernedShellPathEscape,
    verb: &str,
    candidate: &str,
) -> Option<String> {
    if !candidate.contains('$') {
        return None;
    }

    // The tokenizer intentionally forgets shell quoting. Preserve only the
    // existing exact-dollar-name exception; suffix variables are expansions.
    if let Some(operand) = leading_shell_variable(candidate) {
        if operand.suffix.is_empty()
            && operand.modifier.is_empty()
            && gate.worktree.join(candidate).exists()
            && stays_under(&gate.worktree, candidate)
        {
            return None;
        }
    }

    let references = match shell_variable_references(candidate) {
        Ok(references) if !references.is_empty() => references,
        _ => {
            return Some(format!(
                "'{verb}' variable operand cannot be inspected: '{candidate}'"
            ));
        }
    };
    #[cfg(windows)]
    let safe_relative_prefix = references.first().is_some_and(|reference| {
        reference.start > 0
            && !Path::new(&candidate[..reference.start]).is_absolute()
            && !candidate[..reference.start].contains("..")
            && !candidate.contains("..")
    });
    let mut expanded = String::with_capacity(candidate.len());
    let mut copied = 0;
    for reference in references {
        let Some(value) = resolved_shell_variable(gate, reference.name) else {
            return Some(format!(
                "'{verb}' variable operand cannot be inspected: '{candidate}'"
            ));
        };
        expanded.push_str(&candidate[copied..reference.start]);
        expanded.push_str(&value.to_string_lossy());
        copied = reference.end;
    }
    expanded.push_str(&candidate[copied..]);

    #[cfg(windows)]
    if safe_relative_prefix {
        // `src/$PWD` remains a relative (if usually nonsensical) operand after
        // expansion. Windows path parsing otherwise treats the embedded drive
        // prefix as a new root and reports an escape that the shell cannot make.
        return None;
    }

    let expanded_path = Path::new(&expanded);
    let stays_governed = if expanded_path.is_absolute() {
        stays_under(&gate.worktree, &expanded)
            || gate
                .cargo_target_dir
                .as_deref()
                .is_some_and(|root| stays_under(root, &expanded))
    } else {
        stays_under(&gate.worktree, &expanded)
    };
    if stays_governed {
        None
    } else {
        Some(format!(
            "'{verb}' variable path '{candidate}' resolves outside its governed root"
        ))
    }
}

fn governed_operand_prefix_variables(segment: &[String]) -> BTreeSet<String> {
    let mut names = BTreeSet::new();
    let mut command = segment;
    while let Some(verb_index) = shell_verb_index(command) {
        let verb = executable_name(&command[verb_index]);
        if READ_OR_CHDIR_VERBS.contains(&verb.as_str()) {
            if let Ok(paths) = governed_path_arguments(&verb, command) {
                for path in paths {
                    let candidate = path
                        .trim_matches(|c: char| matches!(c, '"' | '\'' | '(' | ')' | ',' | ';'));
                    if let Ok(references) = shell_variable_references(candidate) {
                        if let Some(reference) = references.first().filter(|item| item.start == 0) {
                            names.insert(reference.name.to_string());
                        }
                    }
                }
            }
        }
        let Some(invocation) = carrier_command(command, verb_index, &verb) else {
            break;
        };
        if invocation.command.is_empty() {
            break;
        }
        command = invocation.command;
    }
    names
}

fn shell_root_escape(candidate: &str) -> bool {
    ["HOME", "TMPDIR"].iter().any(|name| {
        let unbraced = format!("${name}");
        let unbraced_match = candidate.strip_prefix(&unbraced).is_some_and(|suffix| {
            suffix
                .chars()
                .next()
                .is_none_or(|ch| ch != '_' && !ch.is_ascii_alphanumeric())
        });
        let braced = format!("${{{name}");
        let braced_match = candidate.strip_prefix(&braced).is_some_and(|suffix| {
            suffix
                .chars()
                .next()
                .is_some_and(|ch| ch != '_' && !ch.is_ascii_alphanumeric())
        });
        unbraced_match || braced_match
    })
}

fn execution_redirecting_variable(name: &str) -> bool {
    matches!(
        name,
        "BASH_ENV"
            | "ENV"
            | "PATH"
            | "LD_PRELOAD"
            | "PYTHONPATH"
            | "PERL5LIB"
            | "RUBYLIB"
            | "NODE_OPTIONS"
            | "CARGO_HOME"
            | "RUSTUP_HOME"
            | "GIT_EXEC_PATH"
            | "GIT_SSH_COMMAND"
    ) || name.starts_with("DYLD_")
}

fn command_opens_editor(verb: &str, args: &[String]) -> bool {
    (verb == "git"
        && args.iter().any(|arg| {
            matches!(
                arg.as_str(),
                "add" | "commit" | "config" | "merge" | "rebase" | "tag"
            )
        }))
        || matches!(verb, "crontab" | "vipw" | "vigr" | "visudo")
}

fn assignment_value_names_path(value: &str) -> bool {
    value.contains('/')
        || value.contains('\\')
        || value.starts_with('~')
        || shell_root_escape(value)
        || value.contains("..")
        || (value.as_bytes().get(1) == Some(&b':')
            && value
                .as_bytes()
                .first()
                .is_some_and(u8::is_ascii_alphabetic))
}

fn effective_command(mut command: &[String]) -> Option<(String, &[String])> {
    loop {
        let verb_index = shell_verb_index(command)?;
        let current_verb = executable_name(&command[verb_index]);
        let args = &command[verb_index + 1..];
        let Some(invocation) = carrier_command(command, verb_index, &current_verb) else {
            return Some((current_verb, args));
        };
        if invocation.command.is_empty() {
            return Some((current_verb, args));
        }
        command = invocation.command;
    }
}

struct AssignmentBuiltinOperands<'a> {
    assignments: Vec<&'a str>,
    removed_names: Vec<&'a str>,
}

/// Extract assignments handled by shell builtins rather than by the shell's
/// leading-assignment grammar. These builtins mutate the current shell, so a
/// later command segment observes the assigned value just as it would for a
/// bare assignment-only segment.
fn assignment_builtin_operands<'a>(
    command: &'a [String],
    verb_index: usize,
    verb: &str,
) -> AssignmentBuiltinOperands<'a> {
    let args = &command[verb_index + 1..];
    let assignment_builtin = matches!(
        verb,
        "export" | "readonly" | "declare" | "typeset" | "local"
    );
    let assignments = if assignment_builtin {
        args.iter()
            .map(String::as_str)
            .filter(|arg| shell_assignment(arg))
            .collect()
    } else {
        Vec::new()
    };

    let removes_export_attribute = verb == "export"
        && args
            .iter()
            .take_while(|arg| arg.as_str() != "--")
            .filter_map(|arg| arg.strip_prefix('-'))
            .any(|options| !options.starts_with('-') && options.contains('n'));
    let removes_variables = verb == "unset" || removes_export_attribute;
    let removed_names = if removes_variables {
        args.iter()
            .skip_while(|arg| arg.starts_with('-') && arg.as_str() != "--")
            .filter(|arg| arg.as_str() != "--")
            .map(String::as_str)
            .filter(|arg| shell_name_len(arg) == arg.len())
            .collect()
    } else {
        Vec::new()
    };

    AssignmentBuiltinOperands {
        assignments,
        removed_names,
    }
}

fn assignment_name_denial(
    name: &str,
    opens_editor: bool,
    operand_prefix_variables: &BTreeSet<String>,
) -> Option<String> {
    if execution_redirecting_variable(name) || (matches!(name, "EDITOR" | "VISUAL") && opens_editor)
    {
        return Some(format!(
            "environment assignment '{name}' may redirect executable code in a governed session"
        ));
    }
    if matches!(
        name,
        "PWD" | "OLDPWD" | "CARGO_TARGET_DIR" | "HOME" | "TMPDIR" | "IFS" | "PATH"
    ) || operand_prefix_variables.contains(name)
    {
        return Some(format!(
            "environment assignment '{name}' may change a governed path operand"
        ));
    }
    None
}

fn assignment_denial(
    worktree: &Path,
    command: &[String],
    operand_prefix_variables: &BTreeSet<String>,
) -> Option<String> {
    let opens_editor =
        effective_command(command).is_some_and(|(verb, args)| command_opens_editor(&verb, args));
    let mut current = command;
    loop {
        // Assignment-only segments have no verb, but their assignments still
        // affect later shell segments and must not disappear from inspection.
        let verb_index = shell_verb_index(current).unwrap_or(current.len());
        let invocation = if verb_index < current.len() {
            let current_verb = executable_name(&current[verb_index]);
            carrier_command(current, verb_index, &current_verb)
        } else {
            None
        };
        let carrier_assignments = invocation
            .as_ref()
            .into_iter()
            .flat_map(|invocation| invocation.assignments.iter().copied());
        let builtin_operands = if verb_index < current.len() {
            assignment_builtin_operands(current, verb_index, &executable_name(&current[verb_index]))
        } else {
            AssignmentBuiltinOperands {
                assignments: Vec::new(),
                removed_names: Vec::new(),
            }
        };
        let assignments = leading_shell_assignments(current)
            .into_iter()
            .chain(carrier_assignments)
            .chain(builtin_operands.assignments);
        for assignment in assignments {
            let Some(parts) = shell_assignment_parts(assignment) else {
                continue;
            };
            if parts
                .subscript
                .is_some_and(shell_subscript_contains_command_substitution)
            {
                return Some(format!(
                    "environment assignment '{}' has a subscript that cannot be inspected",
                    parts.name
                ));
            }
            if let Some(reason) =
                assignment_name_denial(parts.name, opens_editor, operand_prefix_variables)
            {
                return Some(reason);
            }
            if assignment_value_names_path(parts.value) && !stays_under(worktree, parts.value) {
                return Some(format!(
                    "environment assignment '{}' names path '{}' outside the governed repository",
                    parts.name, parts.value
                ));
            }
        }
        for name in builtin_operands.removed_names {
            if let Some(reason) =
                assignment_name_denial(name, opens_editor, operand_prefix_variables)
            {
                return Some(reason);
            }
        }
        let Some(invocation) = invocation else {
            break;
        };
        if invocation.command.is_empty() {
            break;
        }
        current = invocation.command;
    }
    None
}

/// Apply the assignment rules to an array-element assignment whose subscript
/// the tokenised path never sees. A command substitution is uninspectable
/// outright; otherwise the base name still gets the protected-name and
/// path-prefix checks it would have had if the subscript had survived
/// tokenisation, because bash assigns element 0 of a scalar to the scalar
/// itself whatever whitespace the subscript carries.
fn uninspectable_subscript_denial(
    command: &str,
    segments: &[Vec<String>],
    operand_prefix_variables: &BTreeSet<String>,
) -> Option<String> {
    let candidates = uninspectable_assignment_subscripts(command);
    if candidates.is_empty() {
        return None;
    }
    let opens_editor = segments.iter().any(|segment| {
        effective_command(segment).is_some_and(|(verb, args)| command_opens_editor(&verb, args))
    });
    for (name, flaw) in candidates {
        match flaw {
            SubscriptFlaw::CommandSubstitution => {
                return Some(format!(
                    "environment assignment '{name}' has a subscript that cannot be inspected"
                ));
            }
            SubscriptFlaw::BreaksTokenization => {
                if let Some(reason) =
                    assignment_name_denial(name, opens_editor, operand_prefix_variables)
                {
                    return Some(reason);
                }
            }
        }
    }
    None
}

impl Inspector for DenyGovernedShellPathEscape {
    fn name(&self) -> &'static str {
        "governed_host.deny_shell_path_escape"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        let segments = governed_shell_segments(&cmd);
        let mut future_operand_prefix_variables = vec![BTreeSet::new(); segments.len()];
        let mut suffix_variables = BTreeSet::new();
        for (index, segment) in segments.iter().enumerate().rev() {
            suffix_variables.extend(governed_operand_prefix_variables(segment));
            future_operand_prefix_variables[index] = suffix_variables.clone();
        }
        // `suffix_variables` now holds every variable used as a path prefix
        // anywhere in the command. A subscript that breaks tokenisation also
        // destroys the segment the assignment belonged to, so the whole-command
        // set is the only honest one to check it against.
        if let Some(reason) = uninspectable_subscript_denial(&cmd, &segments, &suffix_variables) {
            return InspectionResult::Deny(reason);
        }
        for (index, seg) in segments.into_iter().enumerate() {
            if let Some(reason) = assignment_denial(
                &self.worktree,
                &seg,
                &future_operand_prefix_variables[index],
            ) {
                return InspectionResult::Deny(reason);
            }
            let mut command = seg.as_slice();
            while let Some(verb_index) = shell_verb_index(command) {
                let v = executable_name(&command[verb_index]);
                let args = &command[verb_index + 1..];
                if v == "busybox"
                    && args
                        .iter()
                        .any(|arg| arg == "--install" || arg.starts_with("--install="))
                {
                    return InspectionResult::Deny(
                        "busybox --install may write outside the governed repository".into(),
                    );
                }
                if nested_command_carrier(&v, args) {
                    return InspectionResult::Deny(format!(
                        "nested shell command through '{v}' cannot be inspected in a governed session"
                    ));
                }
                if READ_OR_CHDIR_VERBS.contains(&v.as_str()) {
                    let governed_args = match governed_path_arguments(&v, command) {
                        Ok(paths) => paths,
                        Err(reason) => return InspectionResult::Deny(reason),
                    };
                    for arg in governed_args {
                        let candidate = arg.trim_matches(|c: char| {
                            matches!(c, '"' | '\'' | '(' | ')' | ',' | ';')
                        });
                        if let Some(reason) = variable_operand_denial(self, &v, candidate) {
                            return InspectionResult::Deny(reason);
                        }
                        let names_path = candidate.starts_with('~')
                            || shell_root_escape(candidate)
                            || is_abs_or_traversal(candidate)
                            || self.worktree.join(candidate).exists();
                        if names_path && !stays_under(&self.worktree, candidate) {
                            return InspectionResult::Deny(format!(
                                "'{v}' path '{candidate}' resolves outside the governed repository"
                            ));
                        }
                    }
                }

                let Some(invocation) = carrier_command(command, verb_index, &v) else {
                    break;
                };
                if invocation.command.is_empty() {
                    break;
                }
                command = invocation.command;
            }
        }
        InspectionResult::Allow
    }
}

/// Unlike the general coder, governed host mode does not permit file-tool
/// reads outside the selected repository either.
struct DenyGovernedFilePathEscape {
    worktree: PathBuf,
}

impl Inspector for DenyGovernedFilePathEscape {
    fn name(&self) -> &'static str {
        "governed_host.deny_file_path_escape"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        if !matches!(
            tool,
            "read_file" | "write_file" | "edit_file" | "grep_files"
        ) {
            return InspectionResult::Allow;
        }
        let Some(path) = params.get("path").and_then(Value::as_str) else {
            return InspectionResult::Allow;
        };
        if stays_under(&self.worktree, path) {
            InspectionResult::Allow
        } else {
            InspectionResult::Deny(format!(
                "file access to '{path}' resolves outside the governed repository"
            ))
        }
    }
}

/// Host hardening for the governed supervised assistant. Unlike a coder
/// worktree, this workflow may perform one explicitly approved normal push;
/// remote reconfiguration, force pushes, history rewrite, credential access,
/// and path escape remain unconditional denials.
pub fn governed_host_inspector_chain(worktree: &Path) -> InspectorChain {
    InspectorChain::new()
        .with(Box::new(DenyShellFunctionDeclaration))
        .with(Box::new(DenyGuiShellAutomation))
        .with(Box::new(DenyForcePushAndRemoteReconfiguration))
        .with(Box::new(DenyBroadGitStage))
        .with(Box::new(DenyHistoryRewrite))
        .with(Box::new(DenyPrivilegeEscalation))
        .with(Box::new(DenyCredentialAccess))
        .with(Box::new(DenyEnvironmentRepair))
        .with(Box::new(DenyDestructiveOutsideWorktree {
            worktree: worktree.to_path_buf(),
        }))
        .with(Box::new(DenyGovernedShellPathEscape::new(worktree)))
        .with(Box::new(DenyGovernedFilePathEscape {
            worktree: worktree.to_path_buf(),
        }))
}

/// A governed engineering session has a first-class host shell. Driving a
/// terminal (or a PowerShell window) through desktop automation would bypass
/// repository scoping, action classification, gate checks, and receipts.
struct DenyGuiShellAutomation;

impl Inspector for DenyGuiShellAutomation {
    fn name(&self) -> &'static str {
        "governed_host.deny_gui_shell_automation"
    }

    fn inspect(&self, tool: &str, _params: &Value) -> InspectionResult {
        if matches!(tool, "run_applescript" | "run_powershell") {
            InspectionResult::Deny(
                "desktop-driven shell execution is not allowed; use the governed shell tool".into(),
            )
        } else {
            InspectionResult::Allow
        }
    }
}

/// Preserve unrelated dirty-checkout changes by requiring explicit paths at
/// the staging boundary. Targeted `git add path` remains available.
struct DenyBroadGitStage;

impl Inspector for DenyBroadGitStage {
    fn name(&self) -> &'static str {
        "governed_host.deny_broad_git_stage"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            if verb(&seg) != Some("git") {
                continue;
            }
            let add = seg.iter().position(|token| token == "add");
            if let Some(index) = add {
                if seg
                    .iter()
                    .skip(index + 1)
                    .any(|token| matches!(token.as_str(), "." | "-A" | "--all" | "-u" | "--update"))
                {
                    return InspectionResult::Deny(
                        "broad git staging is not allowed; name only the files changed for this task"
                            .into(),
                    );
                }
            }
            if seg.iter().any(|token| token == "commit")
                && seg.iter().any(|token| {
                    token == "--all"
                        || token
                            .strip_prefix('-')
                            .filter(|short| !short.starts_with('-'))
                            .is_some_and(|short| short.contains('a'))
                })
            {
                return InspectionResult::Deny(
                    "git commit -a is not allowed; stage only explicit task files".into(),
                );
            }
        }
        InspectionResult::Allow
    }
}

/// Lexically resolve `candidate` against `root` and decide whether it stays
/// under `root`. Purely lexical (`..` popping) — symlinks inside the worktree
/// are out of scope here, consistent with the hardening-not-sandbox stance.
pub(crate) fn stays_under(root: &Path, candidate: &str) -> bool {
    // Shells expand leading `~`/`~user` and HOME/TMPDIR references before
    // invoking the command. Do not reinterpret those spellings as literal
    // directories under the repo; direct file tools use this helper too and
    // must keep the same boundary.
    if candidate.starts_with('~') || shell_root_escape(candidate) {
        return false;
    }
    // A variable-shaped path is not safely repository-relative merely because
    // its dollar sign is a legal filename byte. Preserve only an exact,
    // already-existing literal entry such as `$HOME_fixture`; slash-prefixed
    // suffixes and absent bare names are shell expansion, not repo paths.
    if let Some(variable) = leading_shell_variable(candidate) {
        if !variable.suffix.is_empty()
            || !variable.modifier.is_empty()
            || !root.join(candidate).exists()
        {
            return false;
        }
    }
    let p = Path::new(candidate);
    let joined = if p.is_absolute() {
        p.to_path_buf()
    } else {
        root.join(p)
    };
    // Existing paths get a filesystem-authoritative check first. This closes
    // the symlink escape (`repo/link -> /outside`, then `read_file link/x`)
    // that a purely lexical `..` clamp cannot see. Prospective writes fall
    // through to the lexical check; their nearest existing ancestor is also
    // checked by the governed RepositoryScope before host binding.
    if joined.exists() {
        if let (Ok(real_root), Ok(real_candidate)) = (root.canonicalize(), joined.canonicalize()) {
            return path_starts_with(&real_candidate, &real_root);
        }
        return false;
    }
    if let Ok(real_root) = root.canonicalize() {
        let mut ancestor = joined.as_path();
        while !ancestor.exists() {
            let Some(parent) = ancestor.parent() else {
                return false;
            };
            ancestor = parent;
        }
        match ancestor.canonicalize() {
            Ok(real_ancestor) if path_starts_with(&real_ancestor, &real_root) => {}
            _ => return false,
        }
    }
    let mut stack: Vec<Component> = Vec::new();
    for c in joined.components() {
        match c {
            Component::CurDir => {}
            Component::ParentDir => {
                if stack.pop().is_none() {
                    return false;
                }
            }
            other => stack.push(other),
        }
    }
    let normalized: PathBuf = stack.iter().collect();
    path_starts_with(&normalized, root)
}

/// Component-boundary prefix test. On Unix this is `Path::starts_with`. On
/// Windows it additionally strips the `\\?\` verbatim prefix (which
/// `Path::canonicalize` adds to the worktree root but a model-supplied absolute
/// path lacks) and folds case (NTFS is case-insensitive), so a legitimate
/// absolute write inside the worktree isn't spuriously denied.
#[cfg(not(windows))]
fn path_starts_with(path: &Path, base: &Path) -> bool {
    path.starts_with(base)
}

#[cfg(windows)]
fn path_starts_with(path: &Path, base: &Path) -> bool {
    fn key(p: &Path) -> String {
        let s = p.to_string_lossy().into_owned();
        let s = if let Some(r) = s.strip_prefix(r"\\?\UNC\") {
            format!(r"\\{r}")
        } else if let Some(r) = s.strip_prefix(r"\\?\") {
            r.to_string()
        } else {
            s
        };
        s.replace('/', "\\").to_ascii_lowercase()
    }
    let base_key = key(base);
    let base_trim = base_key.trim_end_matches('\\');
    let path_key = key(path);
    path_key == base_trim || path_key.starts_with(&format!("{base_trim}\\"))
}

/// True when a shell argument names an absolute path (POSIX `/…`, Windows
/// `C:\…` / `\\server\…`) or contains a `..` traversal — i.e. the argument may
/// point outside the worktree and must be checked against [`stays_under`].
/// The old code tested only `starts_with('/')`, which never matches a Windows
/// absolute path, so `del C:\…` slipped past the destructive-op guard.
fn is_abs_or_traversal(arg: &str) -> bool {
    arg.starts_with('/')
        || arg.starts_with('\\')
        || arg.contains("..")
        || Path::new(arg).is_absolute()
}

/// True for a Windows `cmd` switch like `/q`, `/s`, `/f` — a leading `/`
/// followed by one or two alphanumerics and nothing else. Distinguished from a
/// POSIX absolute path (`/etc`, `/wt/...`), which is longer or contains another
/// separator. Only ever true on Windows, so Unix argument handling (where a
/// leading `/` is always a path) is unchanged.
fn is_windows_switch(arg: &str) -> bool {
    #[cfg(not(windows))]
    {
        let _ = arg;
        false
    }
    #[cfg(windows)]
    {
        arg.strip_prefix('/')
            .map(|rest| {
                (1..=2).contains(&rest.len()) && rest.chars().all(|c| c.is_ascii_alphanumeric())
            })
            .unwrap_or(false)
    }
}

/// Split a shell command into segments at unquoted-ish separators and each
/// segment into whitespace tokens. Naive on purpose (no quote handling): a
/// quoted `";"` may split a segment too eagerly, which only ever makes the
/// chain MORE likely to deny — never less. Carrier invocations additionally
/// yield each recursively launched command, while retaining the outer command
/// so a rule that governs the carrier itself (notably `sudo`) still fires.
fn segments(command: &str) -> Vec<Vec<String>> {
    let outer: Vec<Vec<String>> =
        split_shell_case_arm_bodies(&join_shell_line_continuations(command))
            .replace("&&", "\n")
            .replace("||", "\n")
            .replace(['；', ';', '|'], "\n")
            .lines()
            .map(|seg| {
                seg.split_whitespace()
                    .map(|t| t.trim_matches(|c| c == '"' || c == '\'').to_string())
                    .filter(|t| !t.is_empty())
                    .collect::<Vec<_>>()
            })
            .filter(|toks: &Vec<String>| !toks.is_empty())
            .collect();

    let mut expanded = Vec::new();
    for segment in outer {
        expanded.push(segment.clone());
        let mut command = segment.as_slice();
        while let Some(verb_index) = shell_verb_index(command) {
            let v = executable_name(&command[verb_index]);
            let Some(invocation) = carrier_command(command, verb_index, &v) else {
                break;
            };
            if invocation.command.is_empty() {
                break;
            }
            expanded.push(invocation.command.to_vec());
            command = invocation.command;
        }
    }
    expanded
}

/// First non-env-assignment token of a segment (`FOO=bar cmd …` → `cmd`).
fn verb(tokens: &[String]) -> Option<&str> {
    shell_verb_index(tokens).map(|index| tokens[index].as_str())
}

fn shell_command(tool: &str, params: &Value) -> Option<String> {
    if tool != "shell" {
        return None;
    }
    params
        .get("command")
        .and_then(Value::as_str)
        .map(str::to_string)
}

/// `git push`, `git remote add/set-url`, `git fetch --force` — the coder's
/// output leaves the machine only via the approved merge branch.
struct DenyGitRemoteMutation;

impl Inspector for DenyGitRemoteMutation {
    fn name(&self) -> &'static str {
        "coder.deny_git_remote_mutation"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            let is_git = verb(&seg) == Some("git");
            if !is_git {
                continue;
            }
            if seg.iter().any(|t| t == "push") {
                return InspectionResult::Deny(
                    "git push is not allowed from a coder session — results are delivered \
                     via the approved local branch"
                        .into(),
                );
            }
            if seg.iter().any(|t| t == "remote")
                && seg
                    .iter()
                    .any(|t| t == "add" || t == "set-url" || t == "remove")
            {
                return InspectionResult::Deny("mutating git remotes is not allowed".into());
            }
        }
        InspectionResult::Allow
    }
}

/// Publication by any route other than the approved merge branch. `git push`
/// is denied above, but a forge CLI reaches the world without touching git:
/// `gh pr create` opens a pull request, `gh release create` ships a release,
/// `gh api --method DELETE` edits branch protection, and `gh auth token`
/// prints the credential that does all three. The property the coder's gates
/// claim is "work leaves the worktree only through `coder.approve_merge`", and
/// one extra binary was enough to break it (car#1074).
///
/// Shape, deliberately mixed. For the forge CLIs (`gh`, `glab`, `hub`) this is
/// an **allowlist**: the read-only subcommands are a small finite set while the
/// mutating ones are not, so a `gh` verb nobody has vetted arrives denied. For
/// package registries it is a short **blacklist** of publish subcommands,
/// because the surrounding verbs (`npm`, `cargo`, `docker`) are ordinary build
/// tools a task legitimately runs. An unparseable forge invocation falls to
/// Deny, which is the safe side — the model gets a reason, not a silent push.
///
/// Out of scope on purpose: `aws`, `kubectl`, `terraform`, `gcloud`. Those are
/// cloud/infra mutation rather than publishing *this repo's work*, the blast
/// radius of a false denial is larger, and the honest fix for them is an
/// allowlist over network-reaching verbs (car#1074 option 2) rather than one
/// more name on a blacklist. A shell alias or a script that wraps `gh` still
/// reaches the binary — hardening, not a sandbox. Prefix carriers are unwrapped
/// by [`segments`], but aliases and wrapper scripts remain outside this
/// matcher's reach.
struct DenyForgePublication;

/// Forge CLIs: anything not on [`FORGE_READS`] is denied.
const FORGE_VERBS: &[&str] = &["gh", "glab", "hub"];

/// (group, allowed subcommands) for a forge CLI. An empty subcommand list
/// allows the whole group.
const FORGE_READS: &[(&str, &[&str])] = &[
    ("pr", &["view", "list", "diff", "checks", "status"]),
    ("mr", &["view", "list", "diff", "checks", "status"]),
    ("issue", &["view", "list"]),
    ("repo", &["view"]),
    ("run", &["view", "list", "watch"]),
    ("release", &["view", "list"]),
    ("workflow", &["view", "list"]),
    ("label", &["list"]),
    ("cache", &["list"]),
    ("gist", &["view", "list"]),
    ("auth", &["status"]),
    ("search", &[]),
    ("status", &[]),
    ("version", &[]),
];

/// Global flags that take a separate value, so the value isn't mistaken for
/// the subcommand group (`gh --repo o/r pr view` → group `pr`, not `o/r`).
const FORGE_VALUE_FLAGS: &[&str] = &["-r", "--repo", "--hostname"];

/// Registry/artifact publication, matched as (verb, first operand).
const PUBLICATION_COMMANDS: &[(&str, &[&str])] = &[
    ("npm", &["publish"]),
    ("pnpm", &["publish"]),
    ("yarn", &["publish"]),
    ("cargo", &["publish"]),
    ("gem", &["push"]),
    ("twine", &["upload"]),
    ("docker", &["push", "login"]),
];

impl Inspector for DenyForgePublication {
    fn name(&self) -> &'static str {
        "coder.deny_forge_publication"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            let Some(v) = verb(&seg) else { continue };
            // Match on the program NAME, as `DenyEnvironmentRepair` does:
            // `/opt/homebrew/bin/gh` is the same action as the bare verb.
            let v = Path::new(&v.to_ascii_lowercase())
                .file_name()
                .map(|f| f.to_string_lossy().into_owned())
                .unwrap_or_default();
            let v = v.strip_suffix(".exe").unwrap_or(&v).to_string();
            let args: Vec<String> = seg.iter().skip(1).map(|a| a.to_ascii_lowercase()).collect();

            if FORGE_VERBS.contains(&v.as_str()) {
                if let Some(reason) = forge_denial(&v, &args) {
                    return InspectionResult::Deny(reason);
                }
                continue;
            }

            for (mgr, subs) in PUBLICATION_COMMANDS {
                if v != *mgr {
                    continue;
                }
                if leading_operands(&args).iter().any(|sub| subs.contains(sub)) {
                    return InspectionResult::Deny(format!(
                        "'{mgr}' publication is not allowed from a coder session — results \
                         leave the worktree only through the approved merge branch"
                    ));
                }
            }
        }
        InspectionResult::Allow
    }
}

/// Positional operands of a forge invocation, in order, with the values of the
/// known value-taking global flags skipped.
fn forge_operands(args: &[String]) -> Vec<&str> {
    let mut operands = Vec::new();
    let mut skip_value = false;
    for arg in args {
        if std::mem::take(&mut skip_value) {
            continue;
        }
        if FORGE_VALUE_FLAGS.contains(&arg.as_str()) {
            skip_value = true;
            continue;
        }
        if arg.starts_with('-') {
            continue;
        }
        operands.push(arg.as_str());
    }
    operands
}

/// The leading positional operands of a command, enough to find a subcommand
/// that ordinary leading tokens have pushed out of first place.
///
/// Reading only the FIRST operand missed three everyday spellings, each of
/// which reaches a registry:
///
/// - `cargo +stable publish` — the rustup toolchain selector is an operand
/// - `docker image push img` — the canonical modern form, subcommand in a group
/// - `npm --workspace x publish` — the flag's VALUE lands in first place
///
/// A `+toolchain` selector is dropped outright, and the next two operands are
/// returned so a group + subcommand pair is visible.
///
/// The trade-off is deliberate and worth stating: scanning two operands can
/// over-match a flag value (`cargo build --features publish` would be denied).
/// This half of the chain is a deny-list over registries, so it is defence in
/// depth rather than the boundary — a false positive is a red check with an
/// explicit reason, while a false negative publishes a package.
fn leading_operands(args: &[String]) -> Vec<&str> {
    args.iter()
        .map(String::as_str)
        .filter(|a| !a.starts_with('-') && !a.starts_with('+'))
        .take(2)
        .collect()
}

/// `Some(reason)` when this forge invocation is not on the read-only
/// allowlist. Everything unrecognised — a new subcommand, a group with no
/// subcommand, an argument shape this matcher cannot read — comes back denied.
fn forge_denial(verb: &str, args: &[String]) -> Option<String> {
    const BLOCKED: &str = "publishing from a coder session is not allowed — the runtime opens \
                           the pull request after `coder.approve_merge`";

    // `--version`/`--help` are flags, not operands, so read them off the raw
    // argument list before operand filtering drops them.
    //
    // `-h` is NOT in this set, and must not be. It was, and it made the whole
    // inspector an allow-all: pflag consumes the next token as a string flag's
    // value even when it starts with a dash, so `gh release create v9 --notes -h`
    // and `gh pr create --title -h --body b --head x --base main` both reached
    // this and returned None before the group was ever read. The premise was
    // wrong on its own terms too — in `gh auth status`, `-h` is `--hostname`.
    //
    // Matching only the long forms costs a coder nothing: `gh --help` still
    // works, and a denied `-h` is one retry away from the spelling that does.
    if args
        .iter()
        .any(|a| matches!(a.as_str(), "--version" | "--help"))
    {
        return None;
    }
    let operands = forge_operands(args);
    let Some(group) = operands.first().copied() else {
        return None; // bare `gh` prints usage
    };

    // `gh api` defaults to GET; an explicit non-GET method, or a field/input
    // flag (which implicitly switches it to POST), makes it a write.
    if group == "api" {
        // Every one of these must match the ATTACHED forms too. pflag accepts
        // `-XPOST` and `--field=k=v` exactly as it accepts the separated
        // spellings, so a matcher that only reads two-token pairs and exact
        // flag names lets `gh api -XPOST repos/O/R/pulls --input=-` straight
        // through — a pull request opened past the gate.
        let is_write_method = |v: &str| !v.is_empty() && v != "get";
        let explicit_method = args
            .windows(2)
            .any(|pair| matches!(pair[0].as_str(), "--method" | "-x") && is_write_method(&pair[1]))
            || args.iter().any(|a| {
                a.strip_prefix("--method=")
                    .or_else(|| a.strip_prefix("-x"))
                    .is_some_and(is_write_method)
            });
        // NB: args are lowercased, so `-f` covers `gh api -F` too.
        let field_flag = |a: &String| {
            matches!(a.as_str(), "-f" | "--field" | "--raw-field" | "--input")
                || a.starts_with("--field=")
                || a.starts_with("--raw-field=")
                || a.starts_with("--input=")
                || a.starts_with("-f")
        };
        // A field alone is not a write: read-only GraphQL REQUIRES `-f query=`,
        // and denying that while allowing `--field=query=mutation{…}` had the
        // detector inverted on the single endpoint where it matters most. What
        // makes a GraphQL call a write is the operation, not the flag shape.
        let graphql = operands.get(1).is_some_and(|o| *o == "graphql");
        let mutating_graphql = graphql
            && args
                .iter()
                .any(|a| a.contains("mutation") || a.contains("deletion"));
        let implicit_post = !graphql && args.iter().any(field_flag);
        return (explicit_method || implicit_post || mutating_graphql)
            .then(|| format!("'{verb} api' with a write method is not allowed — {BLOCKED}"));
    }

    // `gh auth status` is a read — except with `-t`/`--show-token`, which
    // PRINTS THE TOKEN. #1074 named `gh auth token` as the credential leak and
    // this allowlist quietly kept the other spelling of it. With the token in
    // hand the whole forge matcher is moot: `curl -X POST -H "Authorization:
    // bearer $T" .../pulls` has verb `curl` and is inspected by nothing.
    if group == "auth"
        && args
            .iter()
            .any(|a| a == "-t" || a == "--show-token" || a.starts_with("--show-token="))
    {
        return Some(format!(
            "'{verb} auth status --show-token' prints the forge credential — {BLOCKED}"
        ));
    }

    let Some((_, subs)) = FORGE_READS.iter().find(|(g, _)| *g == group) else {
        return Some(format!("'{verb} {group}' is not allowed — {BLOCKED}"));
    };
    if subs.is_empty() {
        return None;
    }
    match operands.get(1).copied() {
        Some(sub) if subs.contains(&sub) => None,
        Some(sub) => Some(format!("'{verb} {group} {sub}' is not allowed — {BLOCKED}")),
        // `gh pr` alone only prints usage, but a missing subcommand is exactly
        // the parse ambiguity to fail closed on.
        None => Some(format!(
            "'{verb} {group}' without a read-only subcommand is not allowed — {BLOCKED}"
        )),
    }
}

/// The governed assistant may perform an approved ordinary push, but never a
/// force push or remote-configuration mutation.
struct DenyForcePushAndRemoteReconfiguration;

impl Inspector for DenyForcePushAndRemoteReconfiguration {
    fn name(&self) -> &'static str {
        "governed_host.deny_force_push_and_remote_reconfiguration"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            if verb(&seg) != Some("git") {
                continue;
            }
            let push = seg.iter().any(|token| token == "push");
            let forced = seg.iter().any(|token| {
                token == "--force"
                    || token == "-f"
                    || token.starts_with("--force-with-lease")
                    || token.starts_with('+')
            });
            if push && forced {
                return InspectionResult::Deny("force-push is never allowed".into());
            }
            if seg.iter().any(|token| token == "remote")
                && seg.iter().any(|token| {
                    token == "add" || token == "set-url" || token == "remove" || token == "rename"
                })
            {
                return InspectionResult::Deny(
                    "mutating git remote configuration is not allowed".into(),
                );
            }
        }
        InspectionResult::Allow
    }
}

/// `git rebase/reset --hard/filter-branch` — the worktree HEAD is detached;
/// history rewrite is never needed and only ever destroys evidence.
struct DenyHistoryRewrite;

impl Inspector for DenyHistoryRewrite {
    fn name(&self) -> &'static str {
        "coder.deny_history_rewrite"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            if verb(&seg) != Some("git") {
                continue;
            }
            if seg.iter().any(|t| t == "rebase" || t == "filter-branch") {
                return InspectionResult::Deny("git history rewrite is not allowed".into());
            }
            if seg.iter().any(|t| t == "reset") && seg.iter().any(|t| t == "--hard") {
                return InspectionResult::Deny("git reset --hard is not allowed".into());
            }
            if seg.iter().any(|t| t == "worktree") && seg.iter().any(|t| t == "remove") {
                return InspectionResult::Deny(
                    "removing worktrees is the runtime's job, not the agent's".into(),
                );
            }
        }
        InspectionResult::Allow
    }
}

/// `sudo`/`doas`/service managers — the coder runs with user privileges, full
/// stop.
struct DenyPrivilegeEscalation;

const PRIVILEGE_VERBS: &[&str] = &[
    // POSIX
    "sudo",
    "doas",
    "su",
    "launchctl",
    "systemctl", //
    // Windows privilege elevation / service control.
    "runas",
    "sc",
    "psexec",
];

impl Inspector for DenyPrivilegeEscalation {
    fn name(&self) -> &'static str {
        "coder.deny_privilege_escalation"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            if let Some(v) = verb(&seg) {
                if PRIVILEGE_VERBS.contains(&v.to_ascii_lowercase().as_str()) {
                    return InspectionResult::Deny(format!(
                        "'{v}' is not allowed in a coder session"
                    ));
                }
            }
        }
        InspectionResult::Allow
    }
}

/// Reads of key stores and credential directories, via shell or file tools.
struct DenyCredentialAccess;

const CREDENTIAL_PATH_MARKERS: [&str; 6] = [
    "/.ssh",
    "/.aws",
    "/.gnupg",
    "/.kube",
    "/.car/secrets",
    "/.netrc",
];

impl Inspector for DenyCredentialAccess {
    fn name(&self) -> &'static str {
        "coder.deny_credential_access"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let haystacks: Vec<String> = if let Some(cmd) = shell_command(tool, params) {
            if cmd.contains("find-generic-password") || cmd.contains("find-internet-password") {
                return InspectionResult::Deny("keychain access is not allowed".into());
            }
            // Windows Credential Manager / DPAPI vault tooling.
            let cmd_lower = cmd.to_ascii_lowercase();
            if cmd_lower.contains("cmdkey") || cmd_lower.contains("vaultcmd") {
                return InspectionResult::Deny(
                    "Windows Credential Manager access is not allowed".into(),
                );
            }
            let sensitive_env = [
                "_key",
                "_token",
                "_secret",
                "_password",
                "openai_",
                "anthropic_",
                "azure_client_",
                "github_token",
                "connection_string",
            ];
            if sensitive_env
                .iter()
                .any(|marker| cmd_lower.contains(marker))
            {
                return InspectionResult::Deny(
                    "reading or expanding credential environment variables is not allowed".into(),
                );
            }
            for seg in segments(&cmd) {
                let Some(command) = verb(&seg).map(|value| value.to_ascii_lowercase()) else {
                    continue;
                };
                if command == "env" && seg.len() == 1
                    || command == "printenv"
                    || command == "set" && seg.len() == 1
                {
                    return InspectionResult::Deny(
                        "dumping the process environment is not allowed".into(),
                    );
                }
            }
            vec![cmd]
        } else if matches!(
            tool,
            "read_file" | "write_file" | "edit_file" | "grep_files"
        ) {
            params
                .get("path")
                .and_then(Value::as_str)
                .map(|p| vec![p.to_string()])
                .unwrap_or_default()
        } else {
            return InspectionResult::Allow;
        };
        for hay in &haystacks {
            // Normalize Windows separators and the various home spellings
            // ("~/.ssh", "$HOME/.ssh", "%USERPROFILE%\.ssh") into the same
            // forward-slash marker space as POSIX absolute paths.
            let hay = hay.replace('\\', "/");
            let hay = hay
                .replace("~/", "/HOME/.")
                .replace("$HOME/", "/HOME/.")
                .replace("%USERPROFILE%/", "/HOME/.")
                .replace("%HOMEPATH%/", "/HOME/.");
            let hay = hay.replace("/HOME/..", "/."); // "~/.ssh" → "/.ssh"
            for marker in CREDENTIAL_PATH_MARKERS {
                if hay.contains(marker) {
                    return InspectionResult::Deny(format!(
                        "access to credential path matching '{marker}' is not allowed"
                    ));
                }
            }
        }
        InspectionResult::Allow
    }
}

/// Destructive shell verbs aimed outside the worktree (absolute paths, `..`
/// escapes, `~`).
struct DenyDestructiveOutsideWorktree {
    worktree: PathBuf,
}

const DESTRUCTIVE_VERBS: &[&str] = &[
    // POSIX
    "rm", "rmdir", "mv", "cp", "chmod", "chown", "truncate", "dd", //
    // Windows `cmd.exe` (the coder shell runs `cmd /C` there) — without these
    // the destructive-outside-worktree guard did nothing on Windows.
    "del", "erase", "rd", "move", "copy", "format", "ren", "rename",
];

impl Inspector for DenyDestructiveOutsideWorktree {
    fn name(&self) -> &'static str {
        "coder.deny_destructive_outside_worktree"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            let Some(v) = verb(&seg) else { continue };
            // Case-insensitive: `cmd.exe` verbs are case-insensitive (DEL/del).
            let v_lower = v.to_ascii_lowercase();
            if !DESTRUCTIVE_VERBS.contains(&v_lower.as_str()) {
                continue;
            }
            // Skip flag-like args: POSIX `-x` and Windows `/x` (e.g. `del /q`).
            for arg in seg
                .iter()
                .skip(1)
                .filter(|a| !a.starts_with('-') && !is_windows_switch(a))
            {
                if arg.starts_with('~') {
                    return InspectionResult::Deny(format!(
                        "'{v}' on a home-relative path ('{arg}') is not allowed"
                    ));
                }
                if is_abs_or_traversal(arg) && !stays_under(&self.worktree, arg) {
                    return InspectionResult::Deny(format!(
                        "'{v}' outside the worktree ('{arg}') is not allowed"
                    ));
                }
            }
        }
        InspectionResult::Allow
    }
}

/// Environment repair — installing packages, creating interpreters, or dropping
/// an interpreter shim. The coder's job is the code; the runtime re-runs the
/// outcome contract in the correct environment to decide done, so a session that
/// "fixes" its interpreter is burning turns on a verdict it cannot change.
///
/// This used to live as ~140 words of prose in the coder system prompt — an
/// enumerated blacklist a model could reason its way around. As an inspector it
/// is enforced, and the model gets a denial *with a reason* instead, which the
/// loop already knows how to handle.
///
/// Deliberately scoped to what is mechanically decidable. `conftest.py`,
/// `pyproject.toml`, `tox.ini`, and `setup.cfg` are NOT denied: editing them is
/// often the actual task, and no matcher can separate "add a fixture" from
/// "change how tests run". Those stay a matter of judgment in the prompt.
/// `sitecustomize.py` has no legitimate task purpose and is denied.
struct DenyEnvironmentRepair;

/// Package-manager invocations that MUTATE the environment. Matched as
/// (verb, subcommand); a read-only subcommand (`pip list`, `pip show`) passes,
/// so a coder can still inspect what is installed.
const PACKAGE_MUTATIONS: &[(&str, &[&str])] = &[
    ("pip", &["install", "uninstall"]),
    ("pip3", &["install", "uninstall"]),
    ("conda", &["install", "remove", "uninstall", "update"]),
    ("poetry", &["add", "remove", "install", "update"]),
    ("uv", &["add", "remove", "sync"]),
    ("easy_install", &[]),
];

/// Interpreter/test-runner shims a coder has no task reason to author.
const SHIM_FILES: &[&str] = &["sitecustomize.py", "usercustomize.py"];

impl Inspector for DenyEnvironmentRepair {
    fn name(&self) -> &'static str {
        "coder.deny_environment_repair"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        if matches!(tool, "write_file" | "edit_file") {
            let path = params.get("path").and_then(Value::as_str).unwrap_or("");
            let base = Path::new(path)
                .file_name()
                .map(|f| f.to_string_lossy().to_ascii_lowercase())
                .unwrap_or_default();
            if SHIM_FILES.contains(&base.as_str()) {
                return InspectionResult::Deny(format!(
                    "writing '{base}' changes how the interpreter loads, not what your code \
                     does — the runtime re-runs the contract in the correct environment"
                ));
            }
            return InspectionResult::Allow;
        }

        let Some(cmd) = shell_command(tool, params) else {
            return InspectionResult::Allow;
        };
        for seg in segments(&cmd) {
            let Some(v) = verb(&seg) else { continue };
            // Match on the program NAME, not the path it was invoked by:
            // `/usr/bin/python3.11 -m pip install` and `.venv/bin/pip install`
            // are the same action as the bare verb.
            let v = Path::new(&v.to_ascii_lowercase())
                .file_name()
                .map(|f| f.to_string_lossy().into_owned())
                .unwrap_or_default();
            let v = v.strip_suffix(".exe").unwrap_or(&v).to_string();
            let args: Vec<String> = seg.iter().skip(1).map(|a| a.to_ascii_lowercase()).collect();

            // `python -m pip install …` / `python -m venv …` — the verb is the
            // interpreter, so look past `-m` for the real module.
            let module = args
                .iter()
                .position(|a| a == "-m")
                .and_then(|i| args.get(i + 1))
                .cloned();
            let (effective, effective_args): (String, Vec<String>) = match module {
                Some(m) if v.starts_with("python") || v.starts_with("py") => {
                    let rest = args
                        .iter()
                        .skip_while(|a| **a != m)
                        .skip(1)
                        .cloned()
                        .collect();
                    (m, rest)
                }
                _ => (v.clone(), args.clone()),
            };

            if effective == "venv" || effective == "virtualenv" {
                return InspectionResult::Deny(
                    "creating an interpreter is environment repair, not part of the task — \
                     the runtime re-runs the contract in the correct environment"
                        .into(),
                );
            }
            for (mgr, subs) in PACKAGE_MUTATIONS {
                if effective != *mgr {
                    continue;
                }
                let mutates = subs.is_empty()
                    || effective_args.iter().any(|a| subs.contains(&a.as_str()))
                    // `uv pip install …` nests one level deeper.
                    || (effective == "uv" && effective_args.iter().any(|a| a == "install"));
                if mutates {
                    return InspectionResult::Deny(format!(
                        "'{mgr}' package mutation is environment repair, not part of the task \
                         — the runtime re-runs the contract in the correct environment"
                    ));
                }
            }
        }
        InspectionResult::Allow
    }
}

/// File-tool writes whose path resolves outside the worktree. (The executor
/// also clamps; defense in depth so a future executor change can't silently
/// drop the rule.)
struct DenyPathEscape {
    worktree: PathBuf,
}

impl Inspector for DenyPathEscape {
    fn name(&self) -> &'static str {
        "coder.deny_path_escape"
    }

    fn inspect(&self, tool: &str, params: &Value) -> InspectionResult {
        if !matches!(tool, "write_file" | "edit_file") {
            return InspectionResult::Allow;
        }
        let Some(path) = params.get("path").and_then(Value::as_str) else {
            return InspectionResult::Allow; // missing param fails in the tool itself
        };
        if stays_under(&self.worktree, path) {
            InspectionResult::Allow
        } else {
            InspectionResult::Deny(format!("write to '{path}' resolves outside the worktree"))
        }
    }
}

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

    fn chain() -> InspectorChain {
        coder_inspector_chain(Path::new("/wt"))
    }

    fn denied(tool: &str, params: Value) -> bool {
        chain().check(tool, &params).is_some()
    }

    fn sh(cmd: &str) -> Value {
        json!({ "command": cmd })
    }

    fn write_policy(dir: &Path, body: &str) {
        std::fs::create_dir_all(dir).unwrap();
        std::fs::write(dir.join("rules.toml"), body).unwrap();
    }

    #[test]
    fn coder_chain_merges_machine_and_project_deny_rules() {
        let root = tempfile::tempdir().unwrap();
        let repo = root.path().join("repo");
        let machine = root.path().join("machine-policies");
        let project = repo.join(".car").join("policies");
        std::fs::create_dir_all(&repo).unwrap();
        write_policy(&machine, "deny_tool = [\"write_file\"]\n");
        write_policy(&project, "deny_keyword = [\"DO NOT RUN\"]\n");

        let policy =
            coder_inspector_chain_from_policy_dirs(&repo, &[machine.clone(), project.clone()])
                .unwrap();
        // The blanket deny is also readable back for tool-list assembly; the
        // keyword rule is argument-dependent and correctly is not.
        assert_eq!(
            policy.denied_tools.iter().cloned().collect::<Vec<_>>(),
            vec!["write_file".to_string()]
        );
        let chain = policy.chain;
        assert!(chain
            .check("write_file", &json!({"path": "x", "content": "ok"}))
            .is_some());
        assert!(chain
            .check("shell", &json!({"command": "echo DO NOT RUN"}))
            .is_some());
        assert!(chain.check("read_file", &json!({"path": "x"})).is_none());
    }

    #[test]
    fn built_in_denial_reason_wins_before_project_policy() {
        let root = tempfile::tempdir().unwrap();
        let policies = root.path().join("policies");
        write_policy(&policies, "deny_tool = [\"shell\"]\n");
        let chain = coder_inspector_chain_from_policy_dirs(root.path(), &[policies])
            .unwrap()
            .chain;

        let reason = chain
            .check("shell", &sh("git push origin main"))
            .expect("both rules deny");
        assert!(
            reason.contains("git push"),
            "built-in reason must win: {reason}"
        );
        assert!(
            !reason.contains("operator policy"),
            "wrong precedence: {reason}"
        );
    }

    #[test]
    fn coder_chain_denies_shell_function_declarations() {
        for command in [
            ":(){ :|:& };:",
            "function f { printf harmless; }",
            "f() { printf harmless; }",
            "(f() { printf harmless; })",
            "case x in x) f() { printf harmless; };; esac",
        ] {
            let reason = chain()
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("function declaration must be denied: {command}"));
            assert!(
                reason.contains("shell function declaration"),
                "unexpected denial for {command}: {reason}"
            );
        }
    }

    #[test]
    fn coder_chain_allows_function_declaration_text_inside_quotes() {
        for command in [
            "printf '%s\\n' ':(){ :|:& };:'",
            "echo \"function f { printf harmless; }\"",
            "grep 'f() { printf harmless; }' README.md",
        ] {
            assert!(
                chain().check("shell", &sh(command)).is_none(),
                "quoted declaration text must stay inert: {command}"
            );
        }
    }

    #[test]
    fn malformed_or_unenforced_policy_refuses_chain_construction() {
        let root = tempfile::tempdir().unwrap();
        let malformed = root.path().join("malformed");
        write_policy(&malformed, "deny_tool = [not valid TOML\n");
        assert!(coder_inspector_chain_from_policy_dirs(root.path(), &[malformed]).is_err());

        let trace = root.path().join("trace");
        write_policy(
            &trace,
            "[[trace_rule]]\nkind = \"never\"\ntool = \"deploy\"\n",
        );
        let err = coder_inspector_chain_from_policy_dirs(root.path(), &[trace])
            .err()
            .expect("trace rules are deliberately unenforced");
        assert!(err.to_string().contains("not enforced"), "{err}");
    }

    #[test]
    fn denies_package_mutation_and_interpreter_creation() {
        for cmd in [
            "pip install requests",
            "pip3 uninstall -y six",
            "python -m pip install --upgrade pip",
            "/usr/bin/python3.11 -m pip install pytest",
            "conda install numpy",
            "poetry add httpx",
            "uv pip install ruff",
            "python -m venv .venv",
            "virtualenv env",
            "easy_install foo",
            "cd /wt && pip install -e .",
        ] {
            assert!(denied("shell", sh(cmd)), "should be denied: {cmd}");
        }
    }

    #[test]
    fn allows_read_only_package_queries_and_real_test_runs() {
        // Inspecting the environment is fine; only mutation is env repair. And
        // the contract's own verify command must never be caught by this rule.
        for cmd in [
            "pip list",
            "pip show pytest",
            "python -m pytest -q tests/test_x.py",
            "/wt/.venv/bin/python -m pytest -q tests/test_x.py",
            "cargo test -p car-engine",
            "npm test",
        ] {
            assert!(!denied("shell", sh(cmd)), "should be allowed: {cmd}");
        }
    }

    #[test]
    fn denies_interpreter_shims_but_not_ordinary_test_config() {
        assert!(denied(
            "write_file",
            json!({ "path": "sitecustomize.py", "content": "x" })
        ));
        assert!(denied(
            "write_file",
            json!({ "path": "src/usercustomize.py", "content": "x" })
        ));
        // Editing test config is often the actual task — no matcher can tell
        // "add a fixture" from "change how tests run", so it stays judgment.
        for path in ["conftest.py", "pyproject.toml", "tox.ini", "setup.cfg"] {
            assert!(
                !denied("write_file", json!({ "path": path, "content": "x" })),
                "must stay allowed: {path}"
            );
        }
    }

    #[test]
    fn git_push_and_remote_mutation_denied() {
        assert!(denied("shell", sh("git push origin main")));
        assert!(denied("shell", sh("cargo test && git push --force")));
        assert!(denied("shell", sh("git remote add evil https://x")));
        assert!(denied("shell", sh("git remote set-url origin https://x")));
        // Reading remotes and committing are fine.
        assert!(!denied("shell", sh("git remote -v")));
        assert!(!denied("shell", sh("git commit -m 'x'")));
        assert!(!denied("shell", sh("git status && git diff")));
        // "push" in a non-git segment is fine.
        assert!(!denied("shell", sh("echo push")));
    }

    /// car#1074: `git push` was denied and `gh pr create` was not, so a coder
    /// session could publish its work without passing `coder.approve_merge`.
    #[test]
    fn forge_publication_denied_but_reads_allowed() {
        for cmd in [
            "gh pr create --fill",
            "gh pr merge --admin",
            "gh api --method DELETE /repos/o/r/branches/main/protection",
            "gh api -X POST /repos/o/r/issues",
            "gh api repos/o/r/issues -f title=x",
            "gh release create v9.9.9 ./x",
            "gh auth token",
            "gh repo fork",
            "glab mr create",
            "npm publish",
            "cargo publish",
            "docker push img",
            "docker login ghcr.io",
            "cargo test && gh pr create",
            "/opt/homebrew/bin/gh pr create --fill",
            // --- Adversarial shapes (review of #1076). Every one of these was
            // a working bypass; without them here they regress silently. ---
            //
            // `-h` was in the help allow-all, so ANY command carrying it was
            // waved through before its group was read. pflag takes the next
            // token as a string flag's value even when it starts with a dash.
            "gh release create v9.9.9 --notes -h",
            "gh pr create --title -h --body b --head mybranch --base main",
            // `-t`/`--show-token` PRINTS the credential. #1074 named
            // `gh auth token`; this is the same leak by another spelling, and
            // it sat on the read allowlist.
            "gh auth status -t",
            "gh auth status --show-token",
            // Attached-value forms. pflag parses these exactly like the
            // separated spellings the matcher already knew.
            "gh api -XPOST repos/o/r/pulls --input=-",
            "gh api -XPOST repos/o/r/pulls --field=title=x",
            "gh api --method=post repos/o/r/pulls",
            "gh api repos/o/r/issues --raw-field=title=x",
            // A GraphQL mutation, whatever flag shape carries it.
            "gh api graphql --field=query=mutation{createpullrequest}",
            // Leading operands that shifted the subcommand out of first place.
            "cargo +stable publish",
            "docker image push img",
            "npm --workspace x publish",
        ] {
            assert!(denied("shell", sh(cmd)), "should be denied: {cmd}");
        }

        // Reading the forge is how a coder checks CI on its own branch.
        for cmd in [
            "gh pr view 12",
            "gh pr checks",
            "gh pr diff 12",
            "gh issue list",
            "gh run view 5",
            "gh run watch 5",
            "gh api repos/o/r",
            "gh api --method GET /repos/o/r",
            "gh --repo o/r pr view 12",
            "gh auth status",
            "gh --version",
            "/opt/homebrew/bin/gh pr list",
            // Verb position only, as elsewhere in this chain.
            "echo gh pr create",
            // Ordinary build verbs keep their non-publish subcommands.
            "cargo test -p car-engine",
            "npm run build",
            "docker build -t img .",
            // Read-only GraphQL REQUIRES `-f query=`. Denying it while the
            // attached mutation form passed had the detector inverted on the
            // one endpoint where it matters most.
            "gh api graphql -f query=query{viewer{login}}",
        ] {
            assert!(!denied("shell", sh(cmd)), "should be allowed: {cmd}");
        }
    }

    /// The governed assistant is designed to reach production: `governance.rs`
    /// scores `gh run` / `az pipelines` as CI evidence and an approved
    /// `git push` as remote-main evidence. The forge guard is coder-only, and
    /// that carve-out is pinned here rather than by a comment.
    #[test]
    fn governed_host_still_allows_ci_reads_and_approved_push() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for command in [
            "gh run list",
            "az pipelines runs list",
            "git push origin HEAD:main",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "governed host must still allow {command}"
            );
        }
    }

    #[test]
    fn governed_host_allows_only_normal_push_shape() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        assert!(chain
            .check("shell", &sh("git push origin HEAD:main"))
            .is_none());
        for command in [
            "git push --force origin main",
            "git push --force-with-lease origin main",
            "git push origin +HEAD:main",
            "git remote set-url origin https://evil",
            "git rebase -i HEAD~2",
            "git add .",
            "git add -A",
            "git commit -am fix",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_some(),
                "must deny {command}"
            );
        }
    }

    #[test]
    fn governed_host_denies_direct_reads_outside_repository() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside.txt");
        std::fs::create_dir(&repo).unwrap();
        std::fs::write(&outside, "secret").unwrap();
        let chain = governed_host_inspector_chain(&repo);

        assert!(chain
            .check("read_file", &json!({"path": outside}))
            .is_some());
        assert!(chain
            .check("shell", &sh(&format!("cat {}", outside.display())))
            .is_some());
        assert!(chain.check("shell", &sh("cd ..")).is_some());
        assert!(chain.check("shell", &sh(r"cat \../outside.txt")).is_some());
        for path in [
            "~/notes.txt",
            "$HOME/notes.txt",
            "${HOME}/notes.txt",
            "${HOME:-/tmp}/notes.txt",
            "${HOME:=/tmp}/notes.txt",
            "$TMPDIR/notes.txt",
            "${TMPDIR}/notes.txt",
            "${TMPDIR:-/tmp}/notes.txt",
        ] {
            assert!(
                chain.check("read_file", &json!({"path": path})).is_some(),
                "expanded shell root must be denied by read_file: {path}"
            );
        }
        for command in [
            "cat ~/notes.txt",
            "cat ~someone/notes.txt",
            "cat $HOME/notes.txt",
            "cat ${HOME}/notes.txt",
            "cat ${HOME:-/tmp}/notes.txt",
            "cat ${HOME:=/tmp}/notes.txt",
            "cat $TMPDIR/notes.txt",
            "cat ${TMPDIR}/notes.txt",
            "cat ${TMPDIR:=/tmp}/notes.txt",
            "sed -f ~/evil.sed file",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_some(),
                "home-relative path must be denied: {command}"
            );
        }
        assert!(chain.check("shell", &sh("cat src/lib.rs")).is_none());

        #[cfg(unix)]
        {
            std::os::unix::fs::symlink(&outside, repo.join("escape")).unwrap();
            assert!(chain
                .check("read_file", &json!({"path": "escape"}))
                .is_some());
            assert!(chain.check("shell", &sh("cat escape")).is_some());
        }
    }

    #[test]
    fn governed_host_denies_uninspectable_variable_operands() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let cargo_target = temp.path().join("cargo-target");
        std::fs::create_dir_all(repo.join("src")).unwrap();
        std::fs::create_dir_all(cargo_target.join("debug")).unwrap();
        std::fs::write(repo.join("src/x"), "x\n").unwrap();
        std::fs::write(repo.join("src/lib.rs"), "pub fn control() {}\n").unwrap();
        std::fs::write(repo.join("$HOME_fixture"), "literal\n").unwrap();
        let chain = governed_host_inspector_chain(&repo);

        for command in [
            "cat $NOPE/etc/hosts",
            "cat ${NOPE}/x",
            "cat ${NOPE:-${PWD}}/x",
            "cat $NOPE",
            "cat $MISSING_fixture",
            "cat $HOME_fixture/inside",
            "cat ${HOME_fixture}/inside",
            "cat ${PWD%repo}/x",
            "cat $1/etc/hosts",
            "cat ${1}",
            "cat $@",
            "cat $*",
            "cat $?",
            "cat $-",
            "cat $$",
            "cat $!",
            "cat src/$x",
            "cat src/${x}/file",
            "cat src/deeper/$x",
            "cat src/file$x",
            "cat src/$1",
            "cat $PWD/src/$x",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("variable operand must be denied: {command}"));
            assert!(
                reason.contains("variable operand cannot be inspected"),
                "unexpected variable denial for {command}: {reason}"
            );
        }

        for command in [
            "cat $PWD/src/x",
            "cat ${PWD}/src/x",
            "cat src/$PWD",
            "cat src/${PWD}/x",
            "cat src/lib.rs",
            "cat $HOME_fixture",
            "env RUST_LOG=debug cargo test",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "resolvable or repo-prefixed control must stay allowed: {command}"
            );
        }

        // Pin the two conditional allowlist entries without mutating the
        // process-wide environment that parallel tests share.
        let path_gate = DenyGovernedShellPathEscape {
            worktree: repo.clone(),
            oldpwd_is_worktree: true,
            cargo_target_dir: Some(cargo_target.clone()),
        };
        for command in [
            "cat $OLDPWD/src/x",
            "cat $CARGO_TARGET_DIR/debug/output",
            "cat src/$OLDPWD/x",
            "cat src/$CARGO_TARGET_DIR/output",
        ] {
            assert!(
                matches!(
                    path_gate.inspect("shell", &sh(command)),
                    InspectionResult::Allow
                ),
                "pinned variable root must stay allowed: {command}"
            );
        }
        assert!(matches!(
            path_gate.inspect("shell", &sh("cat $CARGO_TARGET_DIR/../outside")),
            InspectionResult::Deny(reason)
                if reason.contains("resolves outside its governed root")
        ));
    }

    #[test]
    fn governed_host_gates_every_shell_command_segment() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside.txt");
        std::fs::create_dir(&repo).unwrap();
        std::fs::write(&outside, "secret").unwrap();
        let chain = governed_host_inspector_chain(&repo);

        for separator in ["\n", "\r\n", ";", "&&", "||"] {
            let command = format!("printf harmless{separator}cat {}", outside.display());
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "the command after separator {separator:?} must be path-gated"
            );
        }
    }

    #[test]
    fn governed_host_inspects_case_arm_body_verbs() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for (command, bare) in [
            ("case x in x) sudo ls;; esac", "sudo ls"),
            ("case x in x) cat /etc/passwd;; esac", "cat /etc/passwd"),
            ("case x in x) PWD=/etc;; esac", "PWD=/etc"),
            ("case \"\" in x) sudo ls;; esac", "sudo ls"),
            ("case \"$(printf in)\" in x) sudo ls;; esac", "sudo ls"),
            ("case $(printf in) in x) sudo ls;; esac", "sudo ls"),
        ] {
            let expected = chain
                .check("shell", &sh(bare))
                .unwrap_or_else(|| panic!("bare command must deny: {bare}"));
            let actual = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("case arm body must deny: {command}"));
            assert_eq!(actual, expected, "case arm must preserve the bare reason");
        }
    }

    #[test]
    fn governed_host_inspects_nested_case_arm_body_verbs() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        let bare = "sudo ls";
        let expected = chain
            .check("shell", &sh(bare))
            .expect("bare sudo must deny");
        for command in [
            "case x in x) case y in y) sudo ls;; esac;; esac",
            "{ case x in x) sudo ls;; esac; }",
            "if true; then case x in x) sudo ls;; esac; fi",
            "(case x in x) sudo ls;; esac)",
        ] {
            let actual = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("nested or wrapped case arm body must deny: {command}"));
            assert_eq!(
                actual, expected,
                "nested or wrapped case must preserve the bare reason"
            );
        }
    }

    #[test]
    fn governed_host_inspects_multiple_case_arms_and_patterns() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        let expected = chain
            .check("shell", &sh("sudo ls"))
            .expect("bare sudo must deny");
        for command in [
            "case x in a) ls src;; b) sudo ls;; esac",
            "case x in a|b) sudo ls;; esac",
            "case x in a) ls src;& b) sudo ls;; esac",
            "case x in a) ls src;;& b) sudo ls;; esac",
        ] {
            let actual = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("later case arm body must deny: {command}"));
            assert_eq!(actual, expected, "case arm must preserve the bare reason");
        }

        for command in [
            "echo \"x)\"",
            "echo ')'",
            "echo case x in x) sudo ls",
            "case x in \"x)\") ls src;; esac",
            "case x in x\\)) ls src;; esac",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "quoted closing parenthesis must stay inert: {command}"
            );
        }
    }

    #[test]
    fn governed_host_joins_continued_lines_before_path_gating() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside.txt");
        std::fs::create_dir_all(repo.join("src")).unwrap();
        std::fs::write(repo.join("src/lib.rs"), "pub fn example() {}\n").unwrap();
        std::fs::write(&outside, "secret").unwrap();
        let chain = governed_host_inspector_chain(&repo);

        for verb in ["cat", "rm"] {
            let command = format!("{verb} \\\n{}", outside.display());
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "a continued {verb} path must remain governed: {command:?}"
            );
        }
        assert!(
            chain
                .check("shell", &sh("sed -n '/pub fn/p' \\\n  src/lib.rs"))
                .is_none(),
            "a continued repository-local sed operand must remain allowed"
        );
    }

    #[test]
    fn governed_host_gates_paths_embedded_in_sed_and_awk_programs() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside.txt");
        std::fs::create_dir(&repo).unwrap();
        std::fs::write(repo.join("file"), "x\n").unwrap();
        std::fs::write(repo.join("script.sed"), "p\n").unwrap();
        std::fs::write(&outside, "secret").unwrap();
        let chain = governed_host_inspector_chain(&repo);
        let outside = outside.display();

        for command in [
            format!("sed 'r {outside}' file"),
            format!("sed -n 'R {outside}' file"),
            format!("sed -e '1w {outside}' file"),
            format!("sed '/x/W {outside}' file"),
            format!("awk '{{ getline < \"{outside}\" }}' file"),
            format!("awk '{{ getline line < \"{outside}\" }}' file"),
            format!("awk '{{ print $0 > \"{outside}\" }}' file"),
            format!("awk '{{ print $0 > (\"{outside}\") }}' file"),
            format!("awk '{{ printf \"%s\", $0 >> \"{outside}\" }}' file"),
            // Substitution w flags write a file, including after another flag
            // or an address and a second substitution command.
            format!("sed -n 's/x/y/w {outside}' file"),
            format!("sed -n '/x/s//y/gw {outside}' file"),
            format!("sed -n 's/x/;/w {outside}' file"),
            format!("sed -n 's;x;y;w {outside}' file"),
            format!("sed -n 's/x/{{/w {outside}' file"),
            // r/R/w/W accept the filename immediately after the command.
            format!("sed -n 'r{outside}' file"),
            format!("sed -n 'R{outside}' file"),
            format!("sed -n 'w{outside}' file"),
            format!("sed -n 'W{outside}' file"),
            // Bundled options must preserve the operand-taking final option.
            format!("sed -nf {outside} file"),
            format!("sed -ne 'r {outside}' file"),
            format!("sed -i.bak 's/x/y/' {outside}"),
            // Inline command execution is denied rather than treated as an
            // opaque program that bypasses the governed inspector chain.
            format!("awk 'BEGIN {{ system(\"cat {outside}\") }}'"),
            format!("awk 'BEGIN {{ \"cat {outside}\" | getline line }}'"),
            format!("awk 'BEGIN {{ \"cat {outside}\" |& getline line }}'"),
            format!("awk '{{ print $0 | \"cat > {outside}\" }}' file"),
            format!("awk '{{ printf \"%s\", $0 | \"cat > {outside}\" }}' file"),
            format!("sed -n '1e cat {outside}' file"),
            "sed -n 's/x/y/e' file".to_string(),
        ] {
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "dangerous embedded operand or command execution must be denied: {command}"
            );
        }

        for separator in ["\n", "\r\n"] {
            let command = format!("printf harmless{separator}sed -n 's/x/y/w {outside}' file");
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "a sed write after {separator:?} must remain governed"
            );
        }
        for continuation in ["\\\n", "\\\r\n"] {
            let command = format!("sed -n 's/x/y/w {continuation}{outside}' file");
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "a continued sed write must remain governed: {command:?}"
            );
        }

        for command in [
            "sed 'r file' file",
            "sed -e '1w generated.txt' file",
            "awk '{ getline < \"file\" }' file",
            "awk '{ print $0 > \"generated.txt\" }' file",
            "sed -nf script.sed file",
            "sed -ne '/x/p' file",
            "sed -i.bak 's/x/y/' file",
            "sed 'y/x/;/' file",
            "sed ':example; /x/p' file",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "repository-relative embedded file operand must remain allowed: {command}"
            );
        }
    }

    #[test]
    fn governed_host_denies_shell_fed_sed_and_awk_programs() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside.txt");
        std::fs::create_dir(&repo).unwrap();
        std::fs::write(repo.join("file"), "x\n").unwrap();
        std::fs::write(&outside, "secret").unwrap();
        let chain = governed_host_inspector_chain(&repo);
        let outside = outside.display();

        for command in [
            // Heredoc-fed stdin, including the /dev/stdin spelling.
            format!("sed -f - file <<'EOF'\nw {outside}\nEOF"),
            format!("awk -f /dev/stdin file <<'EOF'\n{{ print > \"{outside}\" }}\nEOF"),
            // Here-string and pipe-fed stdin.
            format!("sed -f - file <<< 'w {outside}'"),
            format!("printf 'w {outside}\\n' | sed -f - file"),
            // A shell expands process substitution to /dev/fd/N; direct fd
            // spellings must be refused for the same reason.
            format!("sed -f <(printf 'w {outside}\\n') file"),
            format!("awk -f /dev/fd/0 file <<'EOF'\n{{ print > \"{outside}\" }}\nEOF"),
            "awk -f /proc/self/fd/0 file".to_string(),
            // Empty inline-program padding must not make the parser consume
            // the following -f option as the -e program.
            format!("sed -e '' -f - file <<'EOF'\nw {outside}\nEOF"),
            format!("awk -e '' -f - file <<'EOF'\n{{ print > \"{outside}\" }}\nEOF"),
            // Empty and shell-computed -f sources cannot be inspected as
            // literal repository paths.
            "sed -f '' file".to_string(),
            "sed -f\"\" file".to_string(),
            "sed -f $(printf -) file".to_string(),
            "awk -f `printf -` file".to_string(),
            "sed -f >(printf p) file".to_string(),
            // Backslash quote removal happens before argv reaches sed/awk.
            r"sed -f \- file".to_string(),
            r"awk -f \- file".to_string(),
            "busybox awk -f - file".to_string(),
            r"sed --file=\- file".to_string(),
            // Brace and parameter expansion can turn a source that looks
            // repository-relative here into stdin when the shell executes it.
            "sed -f {-,} file".to_string(),
            "x=-; sed -f $x file".to_string(),
            "x=-; sed -f \"$x\" file".to_string(),
        ] {
            let reason = chain
                .check("shell", &sh(&command))
                .unwrap_or_else(|| panic!("shell-fed program must be denied: {command}"));
            assert!(
                reason.contains("script source") && reason.contains("cannot be inspected"),
                "program channels must not be misclassified as governed paths: {reason}"
            );
        }
    }

    #[test]
    fn governed_host_denies_nested_shell_command_carriers() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for command in [
            "eval 'sed -f - file'",
            "bash -c 'sed -f - file'",
            "sh -c 'cat /etc/passwd'",
            "zsh -c 'awk -f - file'",
            "dash -c 'cat /etc/passwd'",
            "ksh -c 'cat /etc/passwd'",
            "fish -c 'cat /etc/passwd'",
            "busybox sh -c 'cat /etc/passwd'",
            "busybox ash -c 'cat /etc/passwd'",
            "perl -e 'open F, q(/etc/passwd)'",
            "perl -E 'say qx(cat /etc/passwd)'",
            "perl -wE 'say qx(cat /etc/passwd)'",
            "python3 -c 'open(\"/etc/passwd\").read()'",
            "python3.14 -c 'open(\"/etc/passwd\").read()'",
            "ruby -e 'puts File.read(\"/etc/passwd\")'",
            "node -e 'require(\"fs\").readFileSync(\"/etc/passwd\")'",
            "osascript -e 'do shell script \"cat /etc/passwd\"'",
            "script -c 'cat /etc/passwd'",
            "bash -lc 'cat /etc/passwd'",
            "MODE=check /bin/bash --noprofile -c 'cat /etc/passwd'",
            "env -S 'cat /etc/passwd'",
            "bash",
            "nice bash",
            "nohup bash",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("nested shell carrier must be denied: {command}"));
            assert!(
                reason.contains("nested shell command"),
                "unexpected nested-shell denial reason: {reason}"
            );
        }
        assert!(chain.check("shell", &sh("echo eval")).is_none());
        assert!(chain.check("shell", &sh("bash script.sh")).is_none());
        assert!(chain
            .check("shell", &sh("nice bash scripts/check.sh"))
            .is_none());
        assert!(chain.check("shell", &sh("python3 script.py")).is_none());
        assert!(chain.check("shell", &sh("python3 -E script.py")).is_none());
        assert!(chain
            .check("shell", &sh("ruby -E UTF-8 script.rb"))
            .is_none());
        assert!(chain.check("shell", &sh("node script.js")).is_none());
        assert!(chain
            .check("shell", &sh("perl -MExtUtils::MakeMaker scripts/build.pl"))
            .is_none());
        assert!(chain.check("shell", &sh("command -v sudo")).is_none());
    }

    #[test]
    fn compound_command_keywords_do_not_take_the_verb_slot() {
        for keyword in [
            "{", "}", "if", "then", "elif", "else", "fi", "for", "do", "done", "while", "until",
            "case", "esac", "function", "time", "!",
        ] {
            assert!(
                compound_command_keyword(keyword),
                "shell grammar word must not be classified as a verb: {keyword}"
            );
        }
        for control in ["echo", "a{b}", "{2,}", "important", "timer"] {
            assert!(
                !compound_command_keyword(control),
                "ordinary word must remain a possible verb: {control}"
            );
        }
    }

    #[test]
    fn governed_host_denies_assignments_inside_compound_commands() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for (command, bare_assignment) in [
            ("{ PWD=/etc; }", "PWD=/etc"),
            ("if HOME=/tmp; then :; fi", "HOME=/tmp"),
            ("if false; then :; elif PATH=/tmp; then :; fi", "PATH=/tmp"),
            ("if false; then :; else IFS=:; fi", "IFS=:"),
            ("for i in 1; do PWD=/etc; done", "PWD=/etc"),
            ("while HOME=/tmp; do break; done", "HOME=/tmp"),
            ("until HOME=/tmp; false; do break; done", "HOME=/tmp"),
            ("case x in x) IFS=:;; esac", "IFS=:"),
            // `function f { PWD=/etc; }; f` moved to
            // `governed_host_function_declarations_deny_categorically`: since
            // the fork-bomb guard (#1608) a declaration is refused outright,
            // not inspected for its body's assignment.
            ("time PATH=/tmp true", "PATH=/tmp"),
            ("! HOME=/tmp", "HOME=/tmp"),
        ] {
            let expected = chain
                .check("shell", &sh(bare_assignment))
                .unwrap_or_else(|| {
                    panic!("bare protected assignment must deny: {bare_assignment}")
                });
            let actual = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("compound assignment must deny: {command}"));
            assert_eq!(
                actual, expected,
                "compound syntax must preserve the existing assignment reason: {command}"
            );
        }
    }

    #[test]
    fn governed_host_denies_compound_assignments_after_shell_separators() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for command in [
            "{ true; PWD=/etc; }",
            "{ true && PATH=/tmp; }",
            "{ false || HOME=/tmp; }",
            "{ printf x | IFS=:; }",
            "{ true\nPWD=/etc\n}",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("separated compound assignment must deny: {command:?}"));
            assert!(
                reason.contains("environment assignment"),
                "unexpected assignment reason for {command:?}: {reason}"
            );
        }
    }

    #[test]
    fn governed_host_compound_syntax_controls_stay_allowed() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for command in [
            "echo '{ PWD=/etc; }'",
            "echo '{'",
            "cargo test 'a{b}'",
            "grep -E '{2,}' src/lib.rs",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "quoted or embedded brace must not become shell grammar: {command}"
            );
        }
    }

    #[test]
    fn governed_host_compound_paths_preserve_later_prefix_checks() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for command in [
            "source=repo-local; if true; then cat $source/file; fi",
            "source=repo-local; { cat $source/file; }",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("compound path-prefix assignment must deny: {command}"));
            assert_eq!(
                reason,
                "environment assignment 'source' may change a governed path operand"
            );
        }
    }

    /// Every compound-command form that used to put shell grammar in the verb
    /// slot. Wrapping must not change any inspector's verdict.
    ///
    /// Function declarations are deliberately NOT in this list: since the
    /// fork-bomb guard (`DenyShellFunctionDeclaration`, #1608) every
    /// declaration is refused outright before body inspection, so those forms
    /// no longer behave as transparent wrappings. They are pinned separately
    /// by [`function_declaration_wrappings`] and
    /// `governed_host_function_declarations_deny_categorically`.
    fn compound_wrappings(bare: &str) -> Vec<String> {
        vec![
            format!("{{ {bare}; }}"),
            format!("if true; then {bare}; fi"),
            format!("if false; then :; else {bare}; fi"),
            format!("for i in 1; do {bare}; done"),
            format!("while true; do {bare}; done"),
            format!("until false; do {bare}; done"),
            format!("! {bare}"),
        ]
    }

    /// Every function-declaration spelling that used to hide its body from the
    /// per-verb inspectors. All are refused categorically by the declaration
    /// guard, whatever the body contains.
    fn function_declaration_wrappings(bare: &str) -> Vec<String> {
        vec![
            format!("function wrapped {{ {bare}; }}; wrapped"),
            // All three POSIX declaration spellings: the tokenizers split the
            // head differently for each, so each is a distinct code path.
            format!("wrapped() {{ {bare}; }}; wrapped"),
            format!("wrapped () {{ {bare}; }}; wrapped"),
            format!("wrapped(){{ {bare}; }}; wrapped"),
        ]
    }

    #[test]
    fn governed_host_function_declarations_deny_categorically() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        // Whatever the body holds — innocent, a protected assignment, or a
        // command every inspector would refuse anyway — a declaration is
        // refused before body inspection. This pins the resolution between
        // this branch's verb-slot fix and the fork-bomb guard (#1608): if a
        // refactor ever removes the categorical guard, these turn into body
        // inspections and the expected reason changes, which must be a
        // deliberate decision rather than an accident.
        for bare in ["ls src", "PWD=/etc", "sudo ls", "cat /etc/passwd"] {
            for wrapped in function_declaration_wrappings(bare) {
                let reason = chain
                    .check("shell", &sh(&wrapped))
                    .unwrap_or_else(|| panic!("declaration must deny: {wrapped}"));
                assert_eq!(
                    reason,
                    "shell function declarations require explicit human approval and cannot be run by a coding model",
                    "declaration must be refused categorically: {wrapped}"
                );
            }
        }
    }

    #[test]
    fn shell_verb_index_skips_the_declared_function_name() {
        let tokens =
            |line: &str| -> Vec<String> { line.split_whitespace().map(str::to_string).collect() };
        let declaration = tokens("function wrapped { sudo ls");
        assert_eq!(
            verb(&declaration),
            Some("sudo"),
            "the declared name must not hide the body's verb"
        );
        // `function` only consumes the word that immediately follows it.
        let ordinary = tokens("grep function src/lib.rs");
        assert_eq!(verb(&ordinary), Some("grep"));
        // The four token shapes a POSIX declaration head arrives in.
        for head in [
            "f() { sudo ls",
            "f(){ sudo ls",
            "f () { sudo ls",
            "f ( ) { sudo ls",
        ] {
            assert_eq!(
                verb(&tokens(head)),
                Some("sudo"),
                "POSIX declaration head must not hide the body's verb: {head}"
            );
        }
        // A quoted `()` argument joins to the same text but has no body brace,
        // so the real verb must survive.
        for ordinary in [
            "grep () file",
            "grep ()",
            "echo f()",
            "grep main() src",
            "cargo test foo()",
            "python -c f()",
        ] {
            let parsed = tokens(ordinary);
            assert_eq!(
                verb(&parsed),
                ordinary.split_whitespace().next(),
                "a parenthesised argument is not a declaration head: {ordinary}"
            );
        }
        // A bare subshell paren carries no name, so it is not a declaration
        // head. Asserted on the head parser rather than on the verdict, so
        // closing the separate `( … )` gap later does not go red here.
        assert!(
            posix_function_head(&tokens("( sudo ls )")).is_none(),
            "a bare subshell paren is not a function declaration head"
        );
        let timed = tokens("time { cargo build");
        assert_eq!(verb(&timed), Some("time"));
    }

    #[test]
    fn governed_host_inspects_verbs_inside_compound_commands() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        // One representative per inspector class the shared verb index feeds.
        for bare in [
            // DenyGovernedShellPathEscape — absolute path outside the worktree.
            "cat /etc/passwd",
            // DenyGovernedShellPathEscape — relative escape.
            "cat ../outside/file",
            // DenyGovernedShellPathEscape — a second read verb.
            "head -1 /etc/passwd",
            // DenyPrivilegeEscalation.
            "sudo ls",
            // DenyForcePushAndRemoteReconfiguration, both halves.
            "git push --force origin main",
            "git remote set-url origin http://evil",
            // DenyBroadGitStage.
            "git add -A",
            // DenyHistoryRewrite.
            "git rebase -i HEAD~3",
            // DenyDestructiveOutsideWorktree.
            "rm -rf /Users/other",
            // Uninspectable variable operand.
            "cat $f",
            "wc -l \"$f\"",
        ] {
            let expected = chain
                .check("shell", &sh(bare))
                .unwrap_or_else(|| panic!("bare command must deny: {bare}"));
            for wrapped in compound_wrappings(bare) {
                let actual = chain
                    .check("shell", &sh(&wrapped))
                    .unwrap_or_else(|| panic!("compound command must deny: {wrapped}"));
                assert_eq!(
                    actual, expected,
                    "compound syntax must preserve the bare verdict for {bare:?}: {wrapped:?}"
                );
            }
        }
    }

    #[test]
    fn governed_host_inspects_loop_body_variable_operands() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        // The everyday loop idioms. An unresolvable `$f` operand is denied in
        // the bare command, so the loop body denies it identically — the loop
        // header binding `f` is not a value this tokenizer can resolve.
        for (loop_form, bare) in [
            ("for f in src/*.rs; do cat $f; done", "cat $f"),
            ("while read -r f; do cat $f; done", "cat $f"),
            ("for f in src/*.rs; do wc -l \"$f\"; done", "wc -l \"$f\""),
        ] {
            let expected = chain
                .check("shell", &sh(bare))
                .unwrap_or_else(|| panic!("bare command must deny: {bare}"));
            let actual = chain
                .check("shell", &sh(loop_form))
                .unwrap_or_else(|| panic!("loop body must deny: {loop_form}"));
            assert_eq!(
                actual, expected,
                "loop body must preserve the bare verdict: {loop_form}"
            );
            assert!(
                expected.contains("variable operand cannot be inspected"),
                "unexpected reason for {bare}: {expected}"
            );
        }
    }

    #[test]
    fn governed_host_compound_verb_controls_stay_allowed() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for bare in ["ls src", "wc -l src/lib.rs", "cargo test"] {
            assert!(
                chain.check("shell", &sh(bare)).is_none(),
                "control must stay allowed bare: {bare}"
            );
            for wrapped in compound_wrappings(bare) {
                assert!(
                    chain.check("shell", &sh(&wrapped)).is_none(),
                    "compound syntax must not invent a denial: {wrapped}"
                );
            }
        }
        for command in [
            "{ cargo build; cargo test; }",
            "time { cargo build; }",
            "find . -name x -exec echo {} \\;",
            "xargs -I{} cat {}",
            "echo a{b,c}",
            // Parenthesised arguments. Both tokenizers drop the quotes, so
            // these reach the head parser looking much like a declaration.
            "echo \"f()\"",
            "grep 'main()' src",
            "cargo test 'foo()'",
            "grep '()' src/lib.rs",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "brace-bearing control must stay allowed: {command}"
            );
        }
        // `python -c "f()"` is refused as a nested shell carrier. The control
        // is that the head parser does not change WHICH reason it gets.
        let reason = chain
            .check("shell", &sh("python -c \"f()\""))
            .expect("an inline python program is a nested shell carrier");
        assert!(
            reason.contains("nested shell command through 'python'"),
            "parenthesised argument must not cost python its verb: {reason}"
        );
    }

    #[test]
    fn governed_host_inspects_command_environment_assignments() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside");
        std::fs::create_dir_all(repo.join("target")).unwrap();
        std::fs::create_dir_all(&outside).unwrap();
        let chain = governed_host_inspector_chain(&repo);

        for name in [
            "BASH_ENV",
            "ENV",
            "PATH",
            "LD_PRELOAD",
            "DYLD_INSERT_LIBRARIES",
            "PYTHONPATH",
            "PERL5LIB",
            "RUBYLIB",
            "NODE_OPTIONS",
            "CARGO_HOME",
            "RUSTUP_HOME",
            "GIT_EXEC_PATH",
            "GIT_SSH_COMMAND",
        ] {
            let command = format!("env {name}=repo-local cargo test");
            let reason = chain
                .check("shell", &sh(&command))
                .unwrap_or_else(|| panic!("redirecting assignment must be denied: {command}"));
            assert!(reason.contains("redirect executable code"), "{reason}");
        }

        for command in [
            "BASH_ENV=repo-local bash script.sh".to_string(),
            format!("env CACHE_DIR={} cargo test", outside.display()),
            "env EDITOR=repo-editor git commit".to_string(),
            "VISUAL=repo-editor git rebase --interactive main".to_string(),
            "env CARGO_TARGET_DIR=target cargo test".to_string(),
        ] {
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "unsafe assignment must be denied: {command}"
            );
        }

        for command in [
            "env RUST_LOG=debug cargo test".to_string(),
            "RUST_LOG=debug".to_string(),
            "RUST_LOG[0]=debug; cargo test".to_string(),
            "RUST_LOG[$index]=debug; cargo test".to_string(),
            "RUST_LOG[$((1+1))]=debug; cargo test".to_string(),
            // A whitespace subscript is uninspectable, not forbidden: an
            // unprotected name stays allowed through every spelling.
            "RUST_LOG[ 0 ]=debug; cargo test".to_string(),
            "RUST_LOG[0 ]=debug; cargo test".to_string(),
            "RUST_LOG[ 0]=debug; cargo test".to_string(),
            "RUST_LOG[\t0]=debug; cargo test".to_string(),
            "RUST_LOG[ 0 ]+=,debug; cargo test".to_string(),
            "cargo test 'a[0]'".to_string(),
            "CACHE_KIND=local".to_string(),
            "env EDITOR=vim cargo test".to_string(),
        ] {
            assert!(
                chain.check("shell", &sh(&command)).is_none(),
                "plain assignment must stay allowed: {command}"
            );
        }

        for command in [
            "PWD=repo-local",
            "OLDPWD=repo-local",
            "CARGO_TARGET_DIR=target",
            "HOME=repo-local",
            "TMPDIR=tmp",
            "IFS=: ",
            "PATH=bin",
            "PWD=/etc; cat $PWD/passwd",
            "PWD[0]=/etc; cat $PWD/passwd",
            "PWD[0]+=/x",
            // bash accepts whitespace inside a subscript and still assigns the
            // scalar, so every spelling the tokenizer splits apart must be
            // denied on the base name.
            "PWD[ 0 ]=/etc; cat $PWD/passwd",
            "PWD[0 ]=/etc; cat $PWD/passwd",
            "PWD[ 0]=/etc; cat $PWD/passwd",
            "PWD[\t0]=/etc; cat $PWD/passwd",
            "PWD[\t0]+=/x",
            "env PWD[0]=/etc cat $PWD/passwd",
            "source=../../outside; cat $source/file",
            "source[0]=repo-local; cat $source/file",
            "env input=../../outside cat $input/file",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("path-changing assignment must be denied: {command}"));
            assert!(
                reason.contains("environment assignment"),
                "unexpected assignment denial for {command}: {reason}"
            );
        }
    }

    #[test]
    fn governed_host_inspects_assignments_inside_subshells() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));

        for command in [
            "(PWD=/etc; cat $PWD/passwd)",
            "( PWD=/etc; cat $PWD/passwd )",
            "(printf harmless; (PWD=/etc; cat $PWD/passwd))",
            "printf harmless $(PWD=/etc; cat $PWD/passwd)",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("subshell assignment must be denied: {command}"));
            assert_eq!(
                reason, "environment assignment 'PWD' may change a governed path operand",
                "unexpected subshell-assignment denial for {command}"
            );
        }

        let reason = chain
            .check("shell", &sh("(cat /etc/passwd)"))
            .expect("a governed verb inside a subshell must still be inspected");
        assert!(
            reason.contains("outside the governed repository"),
            "unexpected subshell-path denial: {reason}"
        );

        for command in [
            "echo \"(a=b)\"",
            "grep -E \"(x|y)\" file",
            "find . ( -name a -o -name b )",
            "((count += 1))",
            "((total = (count + 1) * 2))",
            "echo $((1 + (2 * 3)))",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "quoted parentheses, find expressions, and arithmetic must stay allowed: {command}"
            );
        }
    }

    #[test]
    fn governed_host_inspects_assignment_builtins() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));

        for command in [
            "export PWD=/etc; cat $PWD/passwd",
            "readonly PWD=/etc; cat $PWD/passwd",
            "declare PWD=/etc; cat $PWD/passwd",
            "typeset PWD=/etc; cat $PWD/passwd",
            "local PWD=/etc; cat $PWD/passwd",
            "export PWD[1]=/etc; cat $PWD/passwd",
            "export PWD[ 1 ]=/etc; cat $PWD/passwd",
            "declare -a PWD[\t0]=/etc; cat $PWD/passwd",
            "readonly PWD[1]=/etc; cat $PWD/passwd",
            "declare PATH[0]=/tmp; cargo test",
            "declare -a arr[0]=/etc",
            "typeset HOME[0]=/tmp; cargo test",
            "local PWD[1]=/etc; cat $PWD/passwd",
            "unset PWD",
            "export -n PWD",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("assignment builtin must be denied: {command}"));
            assert!(
                reason.contains("environment assignment"),
                "unexpected assignment-builtin denial for {command}: {reason}"
            );
        }

        for builtin in ["export", "readonly", "declare", "typeset", "local"] {
            for assignment in ["source=repo-local", "source[0]=repo-local"] {
                let command = format!("{builtin} {assignment}; cat $source/file");
                let reason = chain.check("shell", &sh(&command)).unwrap_or_else(|| {
                    panic!("later operand-prefix assignment must be denied: {command}")
                });
                assert!(reason.contains("environment assignment"), "{reason}");
            }
        }

        for command in [
            "PWD+=/../../../etc; cat $PWD/passwd",
            "env PWD+=/../../../etc cat $PWD/passwd",
            "export PWD+=/../../../etc; cat $PWD/passwd",
            "readonly PWD+=/../../../etc; cat $PWD/passwd",
            "declare PATH+=/../../../bin; cargo test",
            "typeset PWD+=/../../../etc; cat $PWD/passwd",
            "local PWD+=/../../../etc; cat $PWD/passwd",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("append assignment must be denied: {command}"));
            assert!(
                reason.contains("environment assignment"),
                "unexpected append-assignment denial for {command}: {reason}"
            );
        }

        for command in [
            "RUST_LOG[$(id)]=debug; cargo test",
            "RUST_LOG[$(printf 0)]=debug; cargo test",
            "env RUST_LOG[$(id)]=debug cargo test",
            "export RUST_LOG[$(id)]=debug; cargo test",
            "readonly RUST_LOG[`printf 0`]=debug; cargo test",
            "declare RUST_LOG[$(id)]=debug; cargo test",
            "typeset RUST_LOG[$(id)]=debug; cargo test",
            "local RUST_LOG[$(id)]=debug; cargo test",
        ] {
            let reason = chain.check("shell", &sh(command)).unwrap_or_else(|| {
                panic!("command-substitution subscript must be denied: {command}")
            });
            assert!(reason.contains("cannot be inspected"), "{reason}");
        }

        for command in [
            "export RUST_LOG=debug; cargo test",
            "export RUST_LOG+=,debug; cargo test",
            "export RUST_LOG[0]=debug; cargo test",
            "export RUST_LOG[ 0 ]=debug; cargo test",
            "declare RUST_LOG[\t0]=debug; cargo test",
            "declare RUST_LOG[$index]=debug; cargo test",
            "typeset RUST_LOG[$((1+1))]=debug; cargo test",
            "echo 'RUST_LOG[$(id)]=debug'",
            "local x=1",
            "unset RUST_LOG",
            "export -n RUST_LOG",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "harmless assignment builtin must stay allowed: {command}"
            );
        }
    }

    #[test]
    fn governed_host_denies_busybox_install_mode() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        for command in [
            "busybox --install",
            "busybox --install -s",
            "busybox --install=/tmp/bin",
        ] {
            let reason = chain
                .check("shell", &sh(command))
                .unwrap_or_else(|| panic!("busybox install must be denied: {command}"));
            assert!(reason.contains("busybox --install"), "{reason}");
        }
        assert!(chain
            .check("shell", &sh("busybox grep foo src/input.txt"))
            .is_none());
    }

    #[test]
    fn governed_host_unwraps_prefix_command_carriers() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        let outside = temp.path().join("outside.txt");
        std::fs::create_dir_all(repo.join("src")).unwrap();
        std::fs::write(repo.join("src/input.txt"), "foo\n").unwrap();
        std::fs::write(&outside, "secret\n").unwrap();
        let chain = governed_host_inspector_chain(&repo);
        let path_gate = DenyGovernedShellPathEscape::new(&repo);
        let outside = outside.display();

        for command in [
            format!("env FOO=1 bash -c 'cat {outside}'"),
            format!("env -i -u FOO FOO=1 cat {outside}"),
            format!("command -p cat {outside}"),
            format!("exec -a reader cat {outside}"),
            format!("nohup -- cat {outside}"),
            format!("time -f '%E' cat {outside}"),
            format!("nice --adjustment 5 cat {outside}"),
            format!("caffeinate -t 1 cat {outside}"),
            format!("script -q transcript cat {outside}"),
            format!("xargs -0P 2 cat {outside}"),
            "builtin eval 'cat /etc/passwd'".to_string(),
            format!("sudo -u root cat {outside}"),
            format!("ionice -c 2 cat {outside}"),
            format!("timeout --signal TERM 5 cat {outside}"),
            format!("env -i time nice -n 1 cat {outside}"),
        ] {
            assert!(
                chain.check("shell", &sh(&command)).is_some(),
                "carrier must not hide the governed command: {command}"
            );
        }

        // A carrier with no command adds no denial in the path gate. The full
        // chain separately (and intentionally) denies bare `env` because it
        // dumps all environment variables.
        assert!(matches!(
            path_gate.inspect("shell", &sh("env")),
            InspectionResult::Allow
        ));
        for command in [
            "time cargo build",
            "xargs -0 grep foo src/input.txt",
            "busybox grep foo src/input.txt",
        ] {
            assert!(
                chain.check("shell", &sh(command)).is_none(),
                "safe carrier control must stay allowed: {command}"
            );
        }
    }

    #[test]
    fn prefix_carriers_do_not_bypass_other_shell_inspectors() {
        for command in [
            "env FOO=1 git push origin main",
            "command gh pr create --fill",
            "time cargo publish",
            "nice -n 1 pip install requests",
        ] {
            assert!(
                denied("shell", sh(command)),
                "must deny carried command: {command}"
            );
        }
    }

    #[test]
    fn governed_host_distinguishes_sed_and_awk_programs_from_paths() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("repo");
        std::fs::create_dir_all(repo.join("src")).unwrap();
        std::fs::write(repo.join("src/lib.rs"), "pub fn example() {}\n").unwrap();
        std::fs::write(repo.join("file.rs"), "pub fn example() {}\n").unwrap();
        std::fs::write(repo.join("file"), "x\n").unwrap();
        std::fs::write(repo.join("script.sed"), "p\n").unwrap();
        std::fs::write(repo.join("-"), "p\n").unwrap();
        #[cfg(unix)]
        {
            // The name `\-` is deliberate: a backslash is an ordinary filename
            // byte on unix, and the policy must resolve the shell-escaped
            // operand `\-` to this file. `Path::join` reads a leading backslash
            // as a path separator, so build the path by pushing instead.
            let mut escaped_dash = repo.clone();
            escaped_dash.push(r"\-");
            std::fs::write(escaped_dash, "p\n").unwrap();
        }
        let chain = governed_host_inspector_chain(&repo);

        assert!(
            chain
                .check("shell", &sh("sed -n /pub fn/p file.rs"))
                .is_none(),
            "a sed address is a program, not the absolute path /pub"
        );
        assert!(
            chain
                .check("shell", &sh("sed -n '/pub fn/p' src/lib.rs"))
                .is_none(),
            "a quoted sed address is a program, not the absolute path /pub"
        );
        assert!(
            chain
                .check("shell", &sh("sed -e '/pub fn/p' src/lib.rs"))
                .is_none(),
            "a sed -e operand is an inline program, not a path"
        );
        assert!(
            chain
                .check("shell", &sh("sed -n '/pub \\/etc/p' src/lib.rs"))
                .is_none(),
            "quoted whitespace must not split one sed program into path operands"
        );
        assert!(
            chain.check("shell", &sh("awk /pub/ file.rs")).is_none(),
            "an awk pattern is a program, not the absolute path /pub"
        );
        assert!(
            chain.check("shell", &sh("awk '/x/{print}' file")).is_none(),
            "an awk pattern-action is a program, not a path"
        );
        assert!(
            chain
                .check("shell", &sh("awk '/x/ { print \"/etc\" }' file"))
                .is_none(),
            "a quoted awk program remains one non-path argument"
        );
        assert!(
            chain.check("shell", &sh("sed -n p /etc/passwd")).is_some(),
            "sed input files remain governed"
        );
        assert!(
            chain.check("shell", &sh("sed -f /etc/evil")).is_some(),
            "sed -f names a script file and must remain governed"
        );
        assert!(
            chain.check("shell", &sh("awk -E/path file")).is_some(),
            "an attached awk -E script path must remain governed"
        );
        assert!(
            chain
                .check("shell", &sh("sed -f script.sed file"))
                .is_none(),
            "a literal repository script must remain allowed"
        );
        assert!(
            chain
                .check("shell", &sh("sed -e '' -f script.sed file"))
                .is_none(),
            "empty -e padding must not deny a literal repository script"
        );
        assert!(
            chain.check("shell", &sh("sed -f ./- file")).is_none(),
            "./- is a literal repository path, not sed's stdin marker"
        );
        #[cfg(unix)]
        {
            for command in [r"sed -f '\-' file", r#"sed -f "\-" file"#] {
                assert!(
                    chain.check("shell", &sh(command)).is_none(),
                    "a backslash preserved by shell quotes remains a repository filename: {command}"
                );
            }
        }
    }

    #[test]
    fn governed_host_denies_gui_shell_automation() {
        let chain = governed_host_inspector_chain(Path::new("/wt"));
        assert!(chain
            .check(
                "run_applescript",
                &json!({"script": "tell application \"Terminal\" to do script \"az deploy\""})
            )
            .is_some());
        assert!(chain
            .check("run_powershell", &json!({"script": "az deploy"}))
            .is_some());
    }

    #[test]
    fn history_rewrite_denied() {
        assert!(denied("shell", sh("git rebase -i HEAD~3")));
        assert!(denied("shell", sh("git reset --hard HEAD~1")));
        assert!(denied("shell", sh("git filter-branch --all")));
        assert!(denied("shell", sh("git worktree remove /wt")));
        assert!(!denied("shell", sh("git reset HEAD file.txt"))); // soft reset ok
    }

    #[test]
    fn privilege_escalation_denied() {
        assert!(denied("shell", sh("sudo rm -rf /tmp/x")));
        assert!(denied("shell", sh("doas pkg_add x")));
        assert!(denied("shell", sh("FOO=1 sudo make install")));
        assert!(denied("shell", sh("launchctl unload foo")));
        assert!(!denied("shell", sh("echo sudo"))); // verb position only
    }

    #[test]
    fn credential_access_denied_for_shell_and_file_tools() {
        assert!(denied("shell", sh("cat ~/.ssh/id_rsa")));
        assert!(denied("shell", sh("cat $HOME/.aws/credentials")));
        assert!(denied("shell", sh("security find-generic-password -s x")));
        assert!(denied("read_file", json!({"path": "/Users/u/.ssh/id_rsa"})));
        assert!(denied("read_file", json!({"path": "~/.netrc"})));
        assert!(!denied("read_file", json!({"path": "src/main.rs"})));
        // ".ssh" as a repo-relative dir name is unfortunate but stays denied —
        // conservative beats clever here.
    }

    #[test]
    fn destructive_ops_scoped_to_worktree() {
        assert!(denied("shell", sh("rm -rf /etc")));
        assert!(denied("shell", sh("rm -rf ../other-checkout")));
        assert!(denied("shell", sh("mv target ~/elsewhere")));
        assert!(denied("shell", sh("chmod 777 /usr/local/bin/x")));
        // Inside the worktree: fine, relative or absolute.
        assert!(!denied("shell", sh("rm -rf target/debug")));
        assert!(!denied("shell", sh("rm /wt/scratch.txt")));
        assert!(!denied("shell", sh("cp a.txt b.txt")));
    }

    #[test]
    fn write_path_escape_denied_but_reads_allowed() {
        assert!(denied(
            "write_file",
            json!({"path": "/etc/hosts", "content": "x"})
        ));
        assert!(denied("edit_file", json!({"path": "../outside.txt"})));
        assert!(!denied(
            "write_file",
            json!({"path": "src/new.rs", "content": "x"})
        ));
        assert!(!denied(
            "write_file",
            json!({"path": "/wt/src/new.rs", "content": "x"})
        ));
        // Reads outside the worktree are allowed (context gathering) unless
        // they hit credential markers.
        assert!(!denied(
            "read_file",
            json!({"path": "/usr/include/stdio.h"})
        ));
    }

    #[test]
    fn stays_under_is_lexical_and_strict() {
        let root = Path::new("/wt");
        assert!(stays_under(root, "src/x.rs"));
        assert!(stays_under(root, "a/../b.txt"));
        assert!(stays_under(root, "/wt/deep/file"));
        assert!(!stays_under(root, "../escape"));
        assert!(!stays_under(root, "a/../../escape"));
        assert!(!stays_under(root, "/etc/passwd"));
        assert!(!stays_under(root, "/wtevil/file")); // prefix, not component, match
        assert!(!stays_under(root, "~"));
        assert!(!stays_under(root, "~/outside"));
        assert!(!stays_under(root, "~someone/outside"));
        assert!(!stays_under(root, "$HOME"));
        assert!(!stays_under(root, "$HOME/outside"));
        assert!(!stays_under(root, "${HOME}/outside"));
        assert!(!stays_under(root, "${HOME:-/tmp}/outside"));
        assert!(!stays_under(root, "${HOME:=/tmp}/outside"));
        assert!(!stays_under(root, "$TMPDIR/outside"));
        assert!(!stays_under(root, "${TMPDIR}/outside"));
        assert!(!stays_under(root, "${TMPDIR:-/tmp}/outside"));
        assert!(!stays_under(root, "${TMPDIR:=/tmp}/outside"));
        assert!(!stays_under(root, "$HOME_fixture"));
        assert!(!stays_under(root, "${HOME_fixture}/inside"));
        assert!(stays_under(root, "src/$x"));
        assert!(stays_under(root, "src/~fixture"));

        let temp = tempfile::tempdir().unwrap();
        std::fs::write(temp.path().join("$HOME_fixture"), "literal").unwrap();
        assert!(stays_under(temp.path(), "$HOME_fixture"));
    }

    #[cfg(windows)]
    #[test]
    fn windows_destructive_and_privilege_denied() {
        let chain = coder_inspector_chain(Path::new(r"C:\wt"));
        let denied = |cmd: &str| chain.check("shell", &sh(cmd)).is_some();
        // `cmd.exe` destructive verbs aimed outside the worktree.
        assert!(denied(r"del C:\Windows\System32\drivers\etc\hosts"));
        assert!(denied(r"rd /s /q C:\Windows"));
        assert!(denied(r"del /q C:\Users\victim\file")); // `/q` switch is skipped
        assert!(denied(r"move C:\wt\keep.txt C:\Users\public\stolen.txt"));
        // Windows privilege elevation.
        assert!(denied("runas /user:Administrator cmd"));
        assert!(denied("sc stop windefend"));
        // Inside the worktree: allowed (absolute or relative).
        assert!(!denied(r"del C:\wt\target\debug\app.exe"));
        assert!(!denied(r"del build\out.txt"));
        assert!(!denied("dir")); // non-destructive verb untouched
    }

    #[cfg(windows)]
    #[test]
    fn windows_credential_access_denied() {
        let chain = coder_inspector_chain(Path::new(r"C:\wt"));
        assert!(chain
            .check("shell", &sh(r"type %USERPROFILE%\.ssh\id_rsa"))
            .is_some());
        assert!(chain.check("shell", &sh("cmdkey /list")).is_some());
        assert!(chain
            .check(
                "read_file",
                &json!({"path": r"C:\Users\u\.aws\credentials"})
            )
            .is_some());
        // A normal source read is fine.
        assert!(chain
            .check("read_file", &json!({"path": r"C:\wt\src\main.rs"}))
            .is_none());
    }

    #[cfg(windows)]
    #[test]
    fn stays_under_handles_verbatim_prefix_and_case() {
        // A canonicalized worktree carries the `\\?\` verbatim prefix; a plain
        // absolute candidate inside it (any case) must still count as inside,
        // and NTFS case-insensitivity is honoured.
        let root = Path::new(r"\\?\C:\wt");
        assert!(stays_under(root, r"C:\WT\src\main.rs"));
        assert!(stays_under(root, r"c:\wt\src\main.rs"));
        assert!(!stays_under(root, r"C:\other\x"));
        assert!(!stays_under(root, r"C:\wtevil\x")); // prefix, not component
    }
}