Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
713 KB
Raw Blame
//! `ai-memory install-hooks` — install lifecycle-hook configuration for
//! the chosen agent CLI.
//!
//! Two modes:
//!
//! - **Default (print):** renders the JSON/TOML/TypeScript snippet the
//!   user should merge into their agent CLI's settings file, plus the
//!   absolute paths to the vendored shell scripts. Nothing is written to
//!   disk.
//!
//! - **`--apply` (recommended):** performs an atomic in-place merge into
//!   the target config file. A timestamped backup (`.bak-<unix-ts>`) is
//!   written next to the file before any mutation. Re-runs are
//!   idempotent — a second `--apply` with unchanged content is a no-op
//!   and produces no backup.

use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result};

use crate::cli::{
    AgentChoice, CaptureModeArg, HookInstallScope, InstallHooksArgs, McpClient, ProjectStrategyArg,
};
use crate::commands::apply_shared::{
    ApplyOutcome, PrivateBackup, apply_atomic, apply_atomic_with_backup, mutate_json, mutate_toml,
};
use crate::commands::install_mcp;
use crate::commands::openclaw_plugin;
use crate::commands::path_util::{home_dir, strip_windows_verbatim_prefix};
use crate::commands::render_shared::{
    ANTIGRAVITY_LIFECYCLE_EVENTS, ANTIGRAVITY_TOOL_EVENTS, CODEX_PROFILE, COMMAND_CODE_PROFILE,
    COPILOT_CLI_PROFILE, CURSOR_PROFILE, DSH_EVENTS, GEMINI_PROFILE, HermesHookSet,
    KIMI_CODE_EVENTS, KIRO_CLI_V2_EVENTS, KIRO_CLI_V3_EVENTS, POOL_EVENTS,
    build_antigravity_payload_with_data_dir, build_claude_code_payload_with_data_dir,
    build_devin_payload_with_data_dir, build_dsh_hooks_payload, build_grok_payload_with_data_dir,
    build_kiro_cli_v2_hooks_value, build_kiro_cli_v3_hooks_value,
    build_pool_settings_yaml_with_data_dir, build_profile_payload_for_agent,
    hook_embedded_exe_path, hook_script_for_claude_code, hook_script_for_current_platform,
    kimi_code_hook_commands, local_hook_policy_v1_supported, ts_auth_headers_fn,
    ts_capture_policy_v1, ts_string_literal, ts_timeout_signal, yaml_single_quote,
};
use crate::commands::uninstall::hook_command_is_ours;
use crate::config::{Config, DEFAULT_SERVER_URL};

const CLAUDE_PROMPT_EVENT: &str = "UserPromptSubmit";

/// Claude Code's settings file — hooks live under `hooks`.
/// `$CLAUDE_CONFIG_DIR/settings.json` when the var is set, else
/// `~/.claude/settings.json`.
pub(crate) fn claude_settings_path() -> anyhow::Result<std::path::PathBuf> {
    claude_settings_path_in(std::env::var_os("CLAUDE_CONFIG_DIR"))
}

/// The env value comes in as a parameter so tests can exercise both
/// branches without mutating process env (mirrors
/// `install_mcp::kimi_code_home`).
pub(crate) fn claude_settings_path_in(
    env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    if let Some(dir) = crate::commands::path_util::claude_config_dir(env_override) {
        return Ok(dir.join("settings.json"));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.claude/settings.json")?
        .join(".claude")
        .join("settings.json"))
}

/// The Claude Code settings file this invocation renders for or writes. An
/// explicit `--config-file` wins; `--scope project` targets the checkout's
/// `.claude/settings.local.json`; otherwise the user-level file.
pub(crate) fn claude_settings_target(args: &InstallHooksArgs) -> Result<PathBuf> {
    if let Some(path) = &args.config_file {
        return Ok(path.clone());
    }
    match args.scope {
        HookInstallScope::Global => claude_settings_path(),
        HookInstallScope::Project => {
            let cwd = std::env::current_dir().context(
                "could not resolve current dir for the project-scoped Claude Code settings",
            )?;
            Ok(project_claude_settings_local(&cwd))
        }
    }
}

/// The `.claude/settings.local.json` Claude Code reads for a session launched
/// in `cwd` (code.claude.com/docs/en/settings, "Where Claude Code looks for
/// each file"): at the git repository root even when launched in a
/// subdirectory (the *main* checkout's root from a linked worktree), but in
/// the launch directory itself outside a repository, on Windows, and when the
/// repository root is the home directory. `CLAUDE_CONFIG_DIR` relocates only
/// the user-level files, so it plays no part here.
pub(crate) fn project_claude_settings_local(cwd: &Path) -> PathBuf {
    project_claude_settings_local_for(cwd, cfg!(windows), home_dir().as_deref())
}

/// [`project_claude_settings_local`] with the platform and home directory
/// injected, so the Windows and home-repository rules are testable anywhere.
fn project_claude_settings_local_for(cwd: &Path, is_windows: bool, home: Option<&Path>) -> PathBuf {
    let base = if is_windows {
        cwd.to_path_buf()
    } else {
        match ai_memory_consolidate::discover_main_repo_root(cwd) {
            Ok(root) if !home.is_some_and(|home| same_directory(&root, home)) => root,
            _ => cwd.to_path_buf(),
        }
    };
    base.join(".claude").join("settings.local.json")
}

/// Whether two paths name the same directory. libgit2 reports the repository
/// root resolved while the home path may not be (`/var` vs `/private/var` on
/// macOS), so a lexical mismatch falls back to comparing resolved paths; the
/// result only picks a directory and is never stored.
fn same_directory(a: &Path, b: &Path) -> bool {
    a == b
        || matches!(
            (fs::canonicalize(a), fs::canonicalize(b)),
            (Ok(a), Ok(b)) if a == b
        )
}

/// Where an update to a project `.claude/settings.local.json` keeps the prior
/// file: under the data dir, never in the checkout. Claude Code's ignore rule
/// covers only that file name, so a sibling `.bak-<ts>` would show up in
/// `git status` carrying the full hook commands.
pub(crate) fn project_settings_backup(data_dir: &Path, settings: &Path) -> PrivateBackup {
    PrivateBackup {
        dir: data_dir.join("backups").join("claude-settings-local"),
        stem: project_settings_backup_stem(settings),
    }
}

/// A file-name stem naming the checkout `settings` sits in (see
/// [`super::apply_shared::checkout_backup_stem`]).
fn project_settings_backup_stem(settings: &Path) -> String {
    super::apply_shared::checkout_backup_stem(
        settings.parent().and_then(Path::parent).unwrap_or(settings),
    )
}

/// The `hooks` table of a Claude-shaped settings document (`hooks` → event →
/// entries) when at least one entry in it is ours; `None` means the document
/// is not an ai-memory install. Every "is this file one of ours" question
/// goes through here so the walk cannot drift between callers.
fn ai_memory_claude_hooks(
    document: &serde_json::Value,
) -> Option<&serde_json::Map<String, serde_json::Value>> {
    let hooks = document.get("hooks")?.as_object()?;
    hooks
        .values()
        .filter_map(serde_json::Value::as_array)
        .flatten()
        .any(is_ai_memory_hook_entry)
        .then_some(hooks)
}

/// Whether a parsed Claude-shaped settings document carries an ai-memory hook.
/// `upgrade` and the `run` auto-wire use it to tell a `--scope project`
/// install apart from a user-level one: both stage the same scripts, so the
/// staged dir alone no longer says which file was written.
pub(crate) fn document_carries_ai_memory_hooks(document: &serde_json::Value) -> bool {
    ai_memory_claude_hooks(document).is_some()
}

/// [`document_carries_ai_memory_hooks`] over raw file content; unparsable
/// content is not an install.
pub(crate) fn settings_carry_ai_memory_hooks(content: &str) -> bool {
    serde_json::from_str::<serde_json::Value>(content)
        .ok()
        .is_some_and(|document| document_carries_ai_memory_hooks(&document))
}

/// [`settings_carry_ai_memory_hooks`] over a file; a missing or unreadable
/// file is not an install.
pub(crate) fn settings_file_carries_ai_memory_hooks(path: &Path) -> bool {
    fs::read_to_string(path)
        .ok()
        .is_some_and(|content| settings_carry_ai_memory_hooks(&content))
}

/// Read bound for [`hooks_file_delivers_ai_memory_event`]: it runs on the hook
/// hot path, so a runaway settings file costs at most this much.
const MAX_PLUGIN_DEDUP_SETTINGS_BYTES: u64 = 4 * 1024 * 1024;

/// Where the event map sits in a hooks file a plugin event is checked against.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum HooksFileShape {
    /// Claude-shaped: `{"hooks": {"SessionStart": [...]}}` (Claude Code
    /// `settings.json`, Droid `settings.json`).
    HooksKey,
    /// The event map itself with no wrapper (Droid `hooks.json`).
    EventMap,
}

/// Whether the hooks file at `path` registers an ai-memory hook that fires on
/// every occurrence of `event` (`SessionStart`, ...). A plugin's copy of an
/// event is dropped only when such a hook delivers that same event, so an
/// older install that wires fewer events still gets the rest from the plugin,
/// and a hook narrowed by a `matcher` does not suppress the plugin for what
/// it would not match. A missing, unreadable or malformed file registers
/// nothing.
pub(crate) fn hooks_file_delivers_ai_memory_event(
    path: &Path,
    shape: HooksFileShape,
    event: &str,
) -> bool {
    use std::io::Read as _;
    let Ok(file) = fs::File::open(path) else {
        return false;
    };
    let mut raw = String::new();
    if file
        .take(MAX_PLUGIN_DEDUP_SETTINGS_BYTES)
        .read_to_string(&mut raw)
        .is_err()
    {
        return false;
    }
    let Ok(document) = serde_json::from_str::<serde_json::Value>(&raw) else {
        return false;
    };
    let event_map = match shape {
        HooksFileShape::HooksKey => document.get("hooks"),
        HooksFileShape::EventMap => Some(&document),
    };
    event_map
        .and_then(|map| map.get(event))
        .and_then(serde_json::Value::as_array)
        .is_some_and(|entries| {
            entries
                .iter()
                .any(|entry| is_ai_memory_hook_entry(entry) && matcher_catches_all(entry))
        })
}

/// A hook entry with no `matcher`, an empty one or `*` fires on every
/// occurrence of its event; any other matcher (one tool, one session source)
/// selects a subset, and the plugin must still deliver the rest.
fn matcher_catches_all(entry: &serde_json::Value) -> bool {
    match entry.get("matcher") {
        None | Some(serde_json::Value::Null) => true,
        Some(serde_json::Value::String(matcher)) => matches!(matcher.trim(), "" | "*"),
        Some(_) => false,
    }
}

/// Re-copy the Claude Code hook scripts into the stable staging dir the
/// installed hook commands point at, without touching any settings file.
/// `upgrade` uses it when the only Claude Code install is `--scope project`,
/// so a platform whose hook commands run these scripts gets the new ones.
/// Native-hook commands call the absolute `ai-memory` binary instead, which
/// the upgrade replaces in place. Either way the project files themselves are
/// not rewritten: a change to the hook commands reaches a checkout only when
/// `install-hooks --scope project --apply` is re-run there.
pub(crate) fn restage_claude_code_scripts(
    data_dir: &Path,
    hooks_dir: Option<&Path>,
) -> Result<PathBuf> {
    let hooks_dir = resolve_hooks_dir(hooks_dir, AgentChoice::ClaudeCode, data_dir)?;
    stage_hook_scripts(&hooks_dir, "claude-code", data_dir)
}

/// Codex's hooks file — `$CODEX_HOME/hooks.json` when the var is set, else
/// `~/.codex/hooks.json`.
///
/// `CODEX_HOME` relocates Codex's whole config home, so hooks written to the
/// default path are simply never loaded by a Codex configured that way: capture
/// silently does nothing, with a successful-looking install. ai-memory already
/// honors the variable when it resolves that Codex's transcripts
/// (`ManagedHarness::Codex` in `ai-memory-workstream`), so ignoring it here left
/// one half of the same install pointing somewhere the other half did not.
pub(crate) fn codex_hooks_path(
    env: &crate::config::RuntimeEnv,
) -> anyhow::Result<std::path::PathBuf> {
    codex_hooks_path_in(env.var_os("CODEX_HOME"))
}

/// The env value comes in as a parameter so tests can exercise both branches
/// without mutating process env (mirrors [`claude_settings_path_in`]).
fn codex_hooks_path_in(
    env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir.join("hooks.json"));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.codex/hooks.json")?
        .join(".codex")
        .join("hooks.json"))
}

/// `~/.commandcode/settings.json`.
pub(crate) fn command_code_settings_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.commandcode/settings.json")?
        .join(".commandcode")
        .join("settings.json"))
}

/// `$COPILOT_HOME/hooks/ai-memory.json` when set, else
/// `~/.copilot/hooks/ai-memory.json` — GitHub Copilot CLI user-level
/// lifecycle hooks (#1040).
pub(crate) fn copilot_cli_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    copilot_cli_hooks_path_in(std::env::var_os("COPILOT_HOME"))
}

/// [`copilot_cli_hooks_path`] with the `COPILOT_HOME` value passed in. Resolves
/// through the same config dir as `install-mcp --client copilot-cli`
/// ([`install_mcp::copilot_home_in`]), so the two halves of one install agree.
pub(crate) fn copilot_cli_hooks_path_in(
    env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    Ok(install_mcp::copilot_home_in(env_override)?
        .join("hooks")
        .join("ai-memory.json"))
}

/// `~/.cursor/hooks.json`.
pub(crate) fn cursor_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.cursor/hooks.json")?
        .join(".cursor")
        .join("hooks.json"))
}

/// True when `~/.cursor/hooks.json` already registers a native ai-memory hook
/// declared `--agent cursor`.
///
/// The Cursor CLI also runs the commands in Claude Code's settings, so on a
/// host with both installs every Cursor event reaches `ai-memory hook` twice:
/// once as `--agent cursor` and once as `--agent claude-code` carrying
/// `cursor_version`. The hook uses this to drop the second copy (#721).
/// Unreadable or malformed files count as "not installed" so the Claude Code
/// path keeps capturing Cursor sessions on hosts without Cursor's own hooks.
pub(crate) fn cursor_native_hooks_installed() -> bool {
    cursor_hooks_path().is_ok_and(|path| cursor_native_hooks_installed_in(&path))
}

const MAX_CURSOR_HOOKS_BYTES: u64 = 1024 * 1024;

pub(crate) fn cursor_native_hooks_installed_in(path: &Path) -> bool {
    use std::io::Read as _;
    let Ok(file) = fs::File::open(path) else {
        return false;
    };
    let mut raw = String::new();
    if file
        .take(MAX_CURSOR_HOOKS_BYTES)
        .read_to_string(&mut raw)
        .is_err()
    {
        return false;
    }
    let Ok(root) = serde_json::from_str::<serde_json::Value>(&raw) else {
        return false;
    };
    root.get("hooks")
        .and_then(serde_json::Value::as_object)
        .is_some_and(|hooks| {
            hooks
                .values()
                .filter_map(serde_json::Value::as_array)
                .flatten()
                .any(|entry| is_ai_memory_hook_entry(entry) && declares_cursor_agent(entry))
        })
}

fn declares_cursor_agent(entry: &serde_json::Value) -> bool {
    if let Some(args) = entry.get("args").and_then(serde_json::Value::as_array) {
        return args
            .windows(2)
            .any(|pair| pair[0] == "--agent" && pair[1] == "cursor");
    }
    entry
        .get("command")
        .and_then(serde_json::Value::as_str)
        .is_some_and(|command| {
            let tokens: Vec<&str> = command
                .split_whitespace()
                .map(|t| t.trim_matches(['"', '\'']))
                .collect();
            tokens
                .windows(2)
                .any(|pair| pair[0] == "--agent" && pair[1] == "cursor")
                || tokens.contains(&"--agent=cursor")
                || command.contains("agent=cursor")
        })
}

/// `~/.gemini/settings.json`.
pub(crate) fn gemini_settings_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.gemini/settings.json")?
        .join(".gemini")
        .join("settings.json"))
}

/// `~/.gemini/config/hooks.json` — Antigravity CLI lifecycle hooks.
pub(crate) fn antigravity_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.gemini/config/hooks.json")?
        .join(".gemini")
        .join("config")
        .join("hooks.json"))
}

/// `~/.grok/hooks/ai-memory.json` — Grok Build CLI lifecycle hooks.
pub(crate) fn grok_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    grok_hooks_path_in(std::env::var_os("GROK_HOME"))
}

/// [`grok_hooks_path`] with the `GROK_HOME` value passed in.
fn grok_hooks_path_in(
    env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    Ok(install_mcp::grok_home_in(env_override)?
        .join("hooks")
        .join("ai-memory.json"))
}

/// `~/.factory/hooks.json` — Factory Droid's user-level lifecycle hooks
/// (#1240), the event map itself with no wrapper key.
pub(crate) fn droid_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(install_mcp::factory_home(
        &home_dir().context("could not locate $HOME for ~/.factory/hooks.json")?,
    )
    .join("hooks.json"))
}

/// `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json` — Meta Muse Code's user
/// settings, whose `hooks` key holds its lifecycle hooks. `XDG_CONFIG_HOME`
/// comes from the captured environment (invariant #1).
pub(crate) fn muse_settings_path(
    env: &crate::config::RuntimeEnv,
) -> anyhow::Result<std::path::PathBuf> {
    install_mcp::muse_settings_path_in(env.var_os("XDG_CONFIG_HOME"), home_dir())
}

/// `~/.codebuddy/settings.json` — Tencent CodeBuddy Code's user settings.
/// The root `hooks` block is Claude Code's nested shape (#1299).
pub(crate) fn codebuddy_settings_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.codebuddy/settings.json")?
        .join(".codebuddy")
        .join("settings.json"))
}

/// `~/.bob/settings/settings.json` — IBM Bob's global settings shared by the
/// IDE and Bob Shell. The root `hooks` block uses nested event groups.
pub(crate) fn ibm_bob_settings_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.bob/settings/settings.json")?
        .join(".bob")
        .join("settings")
        .join("settings.json"))
}

/// `~/.qwen/settings.json` — Qwen Code's user settings. MCP servers and
/// lifecycle hooks share this file (`mcpServers` and `hooks`).
pub(crate) fn qwen_code_settings_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.qwen/settings.json")?
        .join(".qwen")
        .join("settings.json"))
}

/// `~/.qoder/settings.json` shared by Qoder CLI and IDE.
pub(crate) fn qoder_settings_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.qoder/settings.json")?
        .join(".qoder")
        .join("settings.json"))
}

/// `~/.config/zero/hooks.json` — Zero's user-level lifecycle hook config
/// (issue #156). Zero resolves it under `$XDG_CONFIG_HOME` falling back to
/// `~/.config`; like the OpenCode plugin path below we target the default
/// location and `--config-file` covers non-default XDG setups.
pub(crate) fn zero_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.config/zero/hooks.json")?
        .join(".config")
        .join("zero")
        .join("hooks.json"))
}

/// `~/.zcode/cli/config.json` — ZCode's user-scope config. The root
/// `hooks` block lives in the same file `install-mcp --client zcode`
/// registers MCP servers in; user scope runs headless with no trust
/// gate, while ZCode's workspace scopes (`.zcode/config.json`,
/// `zcode.json`) are trust-gated and off by default, so they are never
/// targeted (#512).
pub(crate) fn zcode_config_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.zcode/cli/config.json")?
        .join(".zcode")
        .join("cli")
        .join("config.json"))
}

/// `~/.devin/hooks.v1.json` — Devin CLI lifecycle hooks (default target).
pub(crate) fn devin_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.devin/hooks.v1.json")?
        .join(".devin")
        .join("hooks.v1.json"))
}

/// `~/.devin/config.json` — Devin CLI lifecycle hooks (alternative target under `hooks` key).
pub(crate) fn devin_config_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.devin/config.json")?
        .join(".devin")
        .join("config.json"))
}

/// `~/.config/opencode/plugins/ai-memory.ts` — OpenCode's plugin file.
pub(crate) fn opencode_plugin_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.config/opencode")?
        .join(".config")
        .join("opencode")
        .join("plugins")
        .join("ai-memory.ts"))
}

/// OMP lifecycle extension at `<agent dir>/extensions/ai-memory-omp.ts`. The
/// agent dir is OMP's own ([`ai_memory_workstream::omp_agent_dir`]):
/// `~/.omp/profiles/<name>/agent` for a named profile (`--profile`, then
/// `OMP_PROFILE`, then `PI_PROFILE`), else `$PI_CODING_AGENT_DIR`, else
/// `~/.omp/agent`, with `~/.omp` renamed by `PI_CONFIG_DIR`. XDG never moves
/// it: OMP only relocates sessions there.
///
/// OMP loads extensions only from that directory, so an extension written
/// anywhere else is never loaded: capture silently does nothing, with a
/// successful-looking install. Session import resolves OMP transcripts through
/// the same agent dir, so both halves of an install agree on it.
pub(crate) fn omp_extension_path(profile: Option<&str>) -> anyhow::Result<std::path::PathBuf> {
    omp_extension_path_with(profile, &|name| std::env::var_os(name))
}

/// The env comes in as a parameter so tests can exercise every branch without
/// mutating process env (mirrors [`codex_hooks_path_in`]).
fn omp_extension_path_with(
    profile: Option<&str>,
    env: &dyn Fn(&str) -> Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    let home = home_dir().context("could not locate $HOME for ~/.omp")?;
    Ok(ai_memory_workstream::omp_agent_dir(&home, profile, env)?
        .join("extensions")
        .join("ai-memory-omp.ts"))
}

/// `$PI_CODING_AGENT_DIR/extensions/ai-memory-pi.ts` when the var is set, else
/// `~/.pi/agent/extensions/ai-memory-pi.ts` — Pi lifecycle + MCP bridge extension.
///
/// `PI_CODING_AGENT_DIR` relocates Pi's whole agent config home
/// (`~/.pi/agent`), so extensions written to the default path are never
/// loaded by a Pi configured that way: capture silently does nothing, with a
/// successful-looking install. ai-memory already honors the variable when it
/// resolves Pi transcripts (`ManagedHarness::Pi` in `ai-memory-workstream`),
/// so ignoring it here left one half of the same install pointing somewhere
/// the other half did not.
pub(crate) fn pi_extension_path() -> anyhow::Result<std::path::PathBuf> {
    pi_extension_path_in(std::env::var_os("PI_CODING_AGENT_DIR"))
}

/// The env value comes in as a parameter so tests can exercise both branches
/// without mutating process env (mirrors [`codex_hooks_path_in`]).
fn pi_extension_path_in(
    env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir.join("extensions").join("ai-memory-pi.ts"));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.pi/agent/extensions")?
        .join(".pi")
        .join("agent")
        .join("extensions")
        .join("ai-memory-pi.ts"))
}

/// `$KIMI_CODE_HOME/config.toml` when set and not blank, else
/// `~/.kimi-code/config.toml`.
/// Kimi Code keeps hooks as `[[hooks]]` entries inside the same
/// config.toml that stores the user's providers/model, so the apply
/// path merges TOML-aware instead of rewriting the file.
pub(crate) fn kimi_code_config_path() -> anyhow::Result<std::path::PathBuf> {
    kimi_code_config_path_in(std::env::var_os("KIMI_CODE_HOME"))
}

/// The env value comes in as a parameter so tests can exercise both
/// branches without mutating process env (mirrors
/// `install_mcp::kimi_code_home`).
fn kimi_code_config_path_in(
    env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir.join("config.toml"));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.kimi-code/config.toml")?
        .join(".kimi-code")
        .join("config.toml"))
}

/// `$KIRO_HOME/agents` when set, else `~/.kiro/agents`. The Kiro CLI v2
/// engine embeds hooks inside per-agent config JSONs in this directory;
/// there is no global v2 hook surface, and the built-in default agent
/// has no file on disk. `KIRO_HOME` relocation is honored by the real
/// binary (verified against kiro-cli 2.16.0: settings are written under
/// `$KIRO_HOME` when set).
pub(crate) fn kiro_cli_agents_dir() -> anyhow::Result<std::path::PathBuf> {
    kiro_cli_home_join(std::env::var_os("KIRO_HOME"), "agents")
}

/// `$KIRO_HOME/hooks/ai-memory.json` when set, else
/// `~/.kiro/hooks/ai-memory.json`. Kiro v3 loads each standalone JSON file in
/// this directory; using one ai-memory-owned file avoids mutating unrelated
/// registrations.
pub(crate) fn kiro_cli_v3_hooks_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(kiro_cli_home_join(std::env::var_os("KIRO_HOME"), "hooks")?.join("ai-memory.json"))
}

/// The env value comes in as a parameter so tests can exercise both
/// branches without mutating process env (mirrors
/// `kimi_code_config_path_in`).
fn kiro_cli_home_join(
    env_override: Option<std::ffi::OsString>,
    child: &str,
) -> anyhow::Result<std::path::PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir.join(child));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.kiro")?
        .join(".kiro")
        .join(child))
}

/// Run the `install-hooks` subcommand.
///
/// # Errors
/// Returns an error if the hook script directory cannot be located.
pub fn run(config: &Config, args: InstallHooksArgs) -> Result<()> {
    if args.scope == HookInstallScope::Project && args.agent != AgentChoice::ClaudeCode {
        anyhow::bail!(
            "`--scope project` is only supported for `--agent claude-code`; ai-memory writes no \
             project-local hook file for {}",
            args.agent.kind().as_str()
        );
    }
    run_with_opencode_dialect_and_mcp_path(config, args, None, None)
}

pub(crate) fn run_with_opencode_dialect(
    config: &Config,
    args: InstallHooksArgs,
    dialect: Option<ai_memory_workstream::OpenCodeDialect>,
) -> Result<()> {
    run_with_opencode_dialect_and_mcp_path(config, args, dialect, None)
}

pub(crate) fn run_with_opencode_dialect_and_mcp_path(
    config: &Config,
    mut args: InstallHooksArgs,
    dialect: Option<ai_memory_workstream::OpenCodeDialect>,
    mcp_config_path: Option<&Path>,
) -> Result<()> {
    let child_env = super::run::EffectiveChildEnv::from_runtime(&config.runtime_env);
    args.agent = match (args.agent, dialect) {
        (AgentChoice::OpenCode, Some(ai_memory_workstream::OpenCodeDialect::V1)) => {
            AgentChoice::OpenCode
        }
        (AgentChoice::OpenCode, Some(ai_memory_workstream::OpenCodeDialect::V2)) => {
            AgentChoice::OpenCode2
        }
        (agent, None) => super::opencode_dialect::resolve_agent(agent, &child_env)?,
        (agent, Some(_)) => agent,
    };
    let needs_inferred_url = args.server_url.is_none() && !config.server_url_configured();
    let needs_inferred_token = args.auth_token.is_none() && config.auth.bearer_token.is_none();
    let inferred = if needs_inferred_url || needs_inferred_token {
        infer_installed_mcp_config(args.agent, mcp_config_path)?
    } else {
        None
    };
    let server_url = effective_hook_server_url(config, &args, inferred.as_ref());
    // A token read from `[auth].bearer_token_file` may be persisted to the
    // hook credential files below, but never rendered into the agent config
    // or a printed snippet: that file exists to keep it out of them. Only an
    // inline token (flag, `AI_MEMORY_AUTH_TOKEN`, `[auth].bearer_token`, or one
    // inferred from an existing entry) may fall back to the inline form.
    let token_file = config.auth.token_file_path();
    let renderable_token = args
        .auth_token
        .clone()
        .or_else(|| config.auth.renderable_bearer_token().map(str::to_owned))
        .or_else(|| {
            inferred
                .as_ref()
                .filter(|_| token_file.is_none())
                .and_then(|mcp| mcp.auth_token.clone())
        });
    let auth_token_owned = renderable_token
        .clone()
        .or_else(|| token_file.and(config.auth.bearer_token.clone()));
    // #552: persist the bearer under the data dir (0600) and keep it OUT of
    // the rendered config. Before this it went onto every hook's command line —
    // as `--auth-token <token>` for native hooks, as an `AI_MEMORY_AUTH_TOKEN=`
    // shell prefix for the script hooks — so it was readable through
    // `/proc/<pid>/cmdline` by any local user for as long as each hook ran, on
    // every tool call.
    //
    // Only `--apply` persists: a printed snippet is the operator's to place, and
    // writing a credential as a side effect of a dry run would be a surprise.
    let persisted = if args.apply
        && let Some(token) = auth_token_owned.as_deref()
    {
        // A failure here must NOT abort the whole install (#743-audit F5). The
        // common case is a docker-wrapper run where `data_dir` is `/data`, a
        // named volume the container user cannot write — and which the HOST
        // hooks would not read from anyway (they look under the host's
        // `~/.local/share/ai-memory`). Aborting left the operator with no hooks
        // and no capture. Fall back to embedding the credential the pre-#552 way
        // (into the rendered hook config/env) so the hooks still authenticate,
        // and warn loudly about the reduced protection and how to get the secure
        // path back.
        match crate::config::store_hook_auth_token(&config.data_dir, token) {
            Ok(()) => true,
            // A project-local file sits inside a checkout where a commit could
            // publish it, so the inline fallback is refused there outright.
            Err(e) if args.scope == HookInstallScope::Project => {
                return Err(anyhow::Error::new(e).context(format!(
                    "could not persist the hook auth token under {}; refusing to embed it in the \
                     project-local .claude/settings.local.json instead. Install with a writable \
                     host data dir (e.g. `AI_MEMORY_DATA_DIR=$HOME/.local/share/ai-memory` for \
                     the docker wrapper) or a native `ai-memory` binary, or use `--scope global`",
                    config.data_dir.display()
                )));
            }
            Err(e) if renderable_token.is_none() => {
                eprintln!(
                    "[ai-memory] warning: could not persist the hook auth token under {} ({e}). \
                     The token comes from [auth].bearer_token_file and is never embedded in an \
                     agent config, so these hooks will not authenticate until the data dir is \
                     writable and `install-hooks --apply` is re-run.",
                    config.data_dir.display()
                );
                false
            }
            Err(e) => {
                eprintln!(
                    "[ai-memory] warning: could not persist the hook auth token under {} ({e}); \
                     embedding it in the rendered hook config instead so capture still works. \
                     The token is then readable in that file / process argv. To keep it out \
                     (recommended), install with a writable host data dir — e.g. \
                     `AI_MEMORY_DATA_DIR=$HOME/.local/share/ai-memory` for the docker wrapper — \
                     or a native `ai-memory` binary.",
                    config.data_dir.display()
                );
                false
            }
        }
    } else {
        false
    };
    // Renderers take `Option<&str>` and omit the credential entirely when it is
    // `None`, so one decision here covers every agent instead of twenty edits.
    let auth = if persisted {
        None
    } else {
        renderable_token.as_deref()
    };
    // P1.8 multi-user attribution: `--as-user` is metadata only — the
    // token stamped into the hook env block is whatever the operator
    // passed via `--auth-token` (typically a native key from
    // `ai-memory api-key add`). We surface the username to stderr so the
    // operator can confirm which identity their writes will attribute
    // to. Mismatch between `--as-user` and the actual token's owner is
    // the operator's concern; we don't reach back to the server to
    // verify (keeps install-hooks offline-capable).
    //
    // Validate against the resolved token, not the rendered one. `auth` is
    // deliberately `None` on the #552 secure path — the token was persisted
    // under the data dir for the hooks to read — so passing it here made
    // `--apply --as-user X --auth-token T` bail on the very combination
    // docs/users.md recommends, with a message saying the token was absent.
    validate_as_user(args.as_user.as_deref(), auth_token_owned.as_deref())?;
    if let Some(user) = args.as_user.as_deref().filter(|s| !s.trim().is_empty()) {
        eprintln!("[ai-memory] hooks installing for user: {user}");
    }
    let generated = matches!(
        args.agent,
        AgentChoice::OpenCode
            | AgentChoice::OpenCode2
            | AgentChoice::Omp
            | AgentChoice::Pi
            | AgentChoice::Openclaw
    );
    if generated || local_hook_policy_v1_supported() {
        eprintln!(
            "[ai-memory] capture-policy capability v1 enforced by this selected integration; re-run --apply to refresh existing installs."
        );
    } else {
        eprintln!(
            "[ai-memory] selected shell/PowerShell compatibility path does not enforce capture-policy v1; use a native platform selection or generated integration."
        );
    }
    // Assistant capture requires a native client-side sanitizer. No
    // silent fallback: bail so an operator on a script-fallback platform or a
    // different agent is told the flag has no effect instead of installing a
    // command whose capture would be silently dropped.
    if args.capture_assistant && !capture_assistant_allowed(args.agent) {
        anyhow::bail!(
            "--capture-assistant requires --agent claude-code, codex, or opencode2 on a native hook platform \
             (PosixNative/WindowsNative). The current selection uses the script fallback or a \
             different agent, where the opt-in cannot take effect. Remove --capture-assistant or \
             switch to a supported native install."
        );
    }
    if (args.no_capture_prompts || args.capture_prompts)
        && !prompt_capture_options_allowed(args.agent)
    {
        anyhow::bail!(
            "--no-capture-prompts and --capture-prompts require --agent claude-code. Other \
             agents may use their prompt hook to deliver handoff context, so removing it could \
             break cross-agent continuity."
        );
    }
    // Codex's default hooks file depends on CODEX_HOME. Resolve it from the
    // captured environment once, into `args` like the project strategy below,
    // so every reader of the existing install and the writer agree on it.
    if args.apply && args.agent == AgentChoice::Codex && args.config_file.is_none() {
        args.config_file = Some(codex_hooks_path(&config.runtime_env)?);
    }
    // Muse's settings file follows XDG_CONFIG_HOME, resolved the same way.
    if args.apply && args.agent == AgentChoice::Muse && args.config_file.is_none() {
        args.config_file = Some(muse_settings_path(&config.runtime_env)?);
    }
    // Preserve an existing `--capture-assistant` opt-in on a bare re-apply. There
    // is no negative flag, so a re-run without `--capture-assistant` (notably the
    // `ai-memory run` auto-wire, which always passes it off) must NOT silently
    // downgrade a user who had enabled assistant capture. An explicit
    // `--capture-assistant` still forces it on; this only fills in the unset case
    // from what is already installed. Gated to the agents where assistant capture
    // is allowed (Claude Code, Codex), whose configs share the nested-hooks shape.
    if args.apply
        && !args.capture_assistant
        && capture_assistant_allowed(args.agent)
        && existing_capture_assistant_opt_in(&args)
    {
        args.capture_assistant = true;
    }
    if args.apply {
        // #446: settle the capture failure mode before any agent-specific
        // work, and say which mode is in force. A protection the operator
        // cannot see is one they cannot trust.
        let capture_mode = persist_capture_mode(&config.data_dir, args.capture_mode)?;
        println!("capture mode: {capture_mode}");
        if capture_mode == "allowlist" {
            println!("  repositories without a .ai-memory.toml marker emit no lifecycle events");
            // The gate runs inside the native hook binary (immediately before
            // the spool write) and, since #661, inside the generated
            // TypeScript integrations' shared `capturePolicy` (before any
            // POST). The only install left that reaches the server with no
            // gate at all is the raw script fallback: it POSTs directly and
            // never runs either enforcement point. Saying nothing would leave
            // an operator trusting a protection this install does not have —
            // the exact failure #446 is about.
            if !generated && !local_hook_policy_v1_supported() {
                println!(
                    "  WARNING: this install uses script hooks, which POST directly and \
                     cannot enforce the mode. Allowlist is stored but NOT in force here."
                );
            }
        }
        // Preserve a project-strategy an earlier `--apply` baked when this run
        // did not pass `--project-strategy`. Without this, a bare re-apply —
        // notably the auto-refresh in `ai-memory upgrade` — re-renders the hook
        // commands with no strategy and silently reverts a `repo-root` install
        // to `basename`. An explicit `--project-strategy` (including `basename`)
        // is honored as-is, so an intentional downgrade still works. Resolving
        // into `args` here means every downstream renderer picks it up with no
        // per-agent plumbing.
        args.project_strategy = install_project_strategy(&args);
        return match args.agent {
            AgentChoice::OpenCode => {
                apply_to_opencode_plugin(&server_url, auth, &args, &capture_mode)
            }
            AgentChoice::OpenCode2 => {
                apply_to_opencode2_plugin(&server_url, auth, &args, &capture_mode)
            }
            AgentChoice::Pi => apply_to_pi_extension(&server_url, auth, &args, &capture_mode),
            AgentChoice::Omp => apply_to_omp_extension(&server_url, auth, &args, &capture_mode),
            AgentChoice::ClaudeCode => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_claude_code_settings(
                    &hooks_dir,
                    &server_url,
                    auth,
                    &config.data_dir,
                    &args,
                )
            }
            AgentChoice::Codex => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_codex_settings(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::CommandCode => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_command_code_settings(
                    &hooks_dir,
                    &server_url,
                    auth,
                    &config.data_dir,
                    &args,
                )
            }
            AgentChoice::Cursor => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_cursor_settings(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::GeminiCli => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_gemini_settings(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::AntigravityCli => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_antigravity_settings(
                    &hooks_dir,
                    &server_url,
                    auth,
                    &config.data_dir,
                    &args,
                )
            }
            AgentChoice::Grok => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_grok_settings(&hooks_dir, &server_url, auth, &config.data_dir, &args)?;
                let hook_file = match &args.config_file {
                    Some(path) => path.clone(),
                    None => grok_hooks_path()?,
                };
                crate::commands::install_skills::install_grok_companions_after_hooks(&hook_file)
            }
            AgentChoice::Zero => apply_to_zero_hooks(&server_url, auth, &config.data_dir, &args),
            AgentChoice::Zcode => apply_to_zcode_hooks(&server_url, auth, &config.data_dir, &args),
            // Nothing to write or stage: the block invokes the native `hook`
            // subcommand, and `~/.hermes/config.yaml` is a YAML file the
            // operator also edits (and Hermes itself gates hooks behind an
            // acceptance prompt). `--apply` prints the same ready-to-paste
            // block a preview does.
            AgentChoice::Hermes => render_hermes(
                &server_url,
                auth,
                &config.data_dir,
                args.project_strategy.and_then(ProjectStrategyArg::baked),
                hermes_plugin_dir(&config.runtime_env).as_deref(),
            ),
            AgentChoice::Devin => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_devin_settings(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Openclaw => {
                openclaw_plugin::apply(&server_url, auth, &args, &capture_mode)
            }
            AgentChoice::KimiCode => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_kimi_code_config(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::KiroCli => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_kiro_cli_agent_configs(
                    &hooks_dir,
                    &server_url,
                    auth,
                    &config.data_dir,
                    &args,
                )
            }
            AgentChoice::KiroCliV3 => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_kiro_cli_v3_hooks(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Pool => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_pool(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::CopilotCli => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_copilot_cli_hooks(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Droid => {
                let path = match &args.config_file {
                    Some(path) => path.clone(),
                    None => droid_hooks_path()?,
                };
                apply_to_droid_hooks(&path, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Muse => {
                let path = args
                    .config_file
                    .clone()
                    .context("internal: the Muse settings path is resolved before apply")?;
                apply_to_muse_settings(&path, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::CodeBuddy => {
                let path = match &args.config_file {
                    Some(path) => path.clone(),
                    None => codebuddy_settings_path()?,
                };
                apply_to_codebuddy_settings(&path, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::IbmBob => {
                let path = match &args.config_file {
                    Some(path) => path.clone(),
                    None => ibm_bob_settings_path()?,
                };
                apply_to_ibm_bob_settings(&path, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Dsh => {
                let hooks_dir =
                    resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
                apply_to_dsh(&hooks_dir, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Cline => {
                apply_to_cline_hooks(&server_url, auth, &config.data_dir, &args, &capture_mode)
            }
            AgentChoice::QwenCode => {
                let path = match &args.config_file {
                    Some(path) => path.clone(),
                    None => qwen_code_settings_path()?,
                };
                apply_to_qwen_code_settings(&path, &server_url, auth, &config.data_dir, &args)
            }
            AgentChoice::Qoder => {
                let path = match &args.config_file {
                    Some(path) => path.clone(),
                    None => qoder_settings_path()?,
                };
                apply_to_qoder_settings(&path, &server_url, auth, &config.data_dir, &args)
            }
        };
    }
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    // Preview must bake the same `CAPTURE_MODE` the next `--apply` would
    // persist (#661) — resolved read-only so a bare preview never writes.
    let preview_capture_mode = resolve_capture_mode(&config.data_dir, args.capture_mode);
    match args.agent {
        AgentChoice::OpenCode => {
            render_opencode_plugin(&server_url, auth, strategy, &preview_capture_mode)
        }
        AgentChoice::OpenCode2 => render_opencode2_plugin(
            &server_url,
            auth,
            strategy,
            &preview_capture_mode,
            args.capture_assistant,
        ),
        AgentChoice::Pi => render_pi_extension(&server_url, auth, strategy, &preview_capture_mode),
        AgentChoice::Omp => render_omp_extension(
            &server_url,
            auth,
            strategy,
            args.profile.as_deref(),
            &preview_capture_mode,
        ),
        AgentChoice::ClaudeCode => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            let settings_path = claude_settings_target(&args)?;
            render_claude_code(
                &hooks_dir,
                &server_url,
                auth,
                &config.data_dir,
                strategy,
                ClaudeRenderTarget {
                    settings_path: &settings_path,
                    scope: args.scope,
                },
                ClaudeCaptureScope {
                    assistant: args.capture_assistant,
                    prompts: install_claude_prompt_capture(&args),
                },
            )
        }
        AgentChoice::Codex => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_agent(
                "codex",
                &hooks_dir,
                &server_url,
                auth,
                strategy,
                &[CODEX_PROFILE.events],
            )
        }
        AgentChoice::CommandCode => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_agent(
                "command-code",
                &hooks_dir,
                &server_url,
                auth,
                strategy,
                &[COMMAND_CODE_PROFILE.events],
            )
        }
        AgentChoice::Cursor => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_agent(
                "cursor",
                &hooks_dir,
                &server_url,
                auth,
                strategy,
                &[CURSOR_PROFILE.events],
            )
        }
        AgentChoice::GeminiCli => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_agent(
                "gemini-cli",
                &hooks_dir,
                &server_url,
                auth,
                strategy,
                &[GEMINI_PROFILE.events],
            )
        }
        AgentChoice::AntigravityCli => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_agent(
                "antigravity-cli",
                &hooks_dir,
                &server_url,
                auth,
                strategy,
                &[&ANTIGRAVITY_TOOL_EVENTS, &ANTIGRAVITY_LIFECYCLE_EVENTS],
            )
        }
        AgentChoice::Grok => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_grok(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::Zero => render_zero(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::Zcode => render_zcode(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::Hermes => render_hermes(
            &server_url,
            auth,
            &config.data_dir,
            strategy,
            hermes_plugin_dir(&config.runtime_env).as_deref(),
        ),
        AgentChoice::Devin => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_devin(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::Openclaw => {
            openclaw_plugin::render(&server_url, auth, strategy, &preview_capture_mode);
            Ok(())
        }
        AgentChoice::KimiCode => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_kimi_code(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::KiroCli => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_kiro_cli(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::KiroCliV3 => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_kiro_cli_v3(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::Pool => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_pool(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::CopilotCli => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_agent(
                "copilot-cli",
                &hooks_dir,
                &server_url,
                auth,
                strategy,
                &[COPILOT_CLI_PROFILE.events],
            )
        }
        AgentChoice::Droid => render_droid(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::Muse => render_muse(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::CodeBuddy => render_codebuddy(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::IbmBob => render_ibm_bob(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::Dsh => {
            let hooks_dir =
                resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
            render_dsh(&hooks_dir, &server_url, auth, &config.data_dir, strategy)
        }
        AgentChoice::Cline => render_cline_hooks(
            &server_url,
            auth,
            &config.data_dir,
            &args,
            &preview_capture_mode,
        ),
        AgentChoice::QwenCode => render_qwen_code(&server_url, auth, &config.data_dir, strategy),
        AgentChoice::Qoder => render_qoder(&server_url, auth, &config.data_dir, strategy),
    }
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
struct InferredMcpConfig {
    hook_server_url: Option<String>,
    auth_token: Option<String>,
}

/// The project-strategy to install for `args`: the explicit `--project-strategy`
/// when one was given, otherwise the strategy an earlier `--apply` baked into
/// the agent's existing config (so a bare re-apply preserves it instead of
/// reverting to basename). `None` means "bake nothing", unchanged from before.
fn install_project_strategy(args: &InstallHooksArgs) -> Option<ProjectStrategyArg> {
    if args.project_strategy.is_some() {
        return args.project_strategy;
    }
    // Kiro v2 can update several agent configs in one run. Each config may
    // carry a different previously-baked strategy, so recover it per target in
    // `apply_to_kiro_cli_agent_configs` instead of choosing one globally.
    if args.agent == AgentChoice::KiroCli {
        return None;
    }
    existing_agent_config(args)
        .as_deref()
        .and_then(|existing| baked_project_strategy(args.agent, existing))
}

/// The capture failure mode (#446) currently in force: an explicit
/// `--capture-mode` flag wins, otherwise the value stored under `data_dir`
/// from an earlier `--apply`, otherwise the historical `denylist` default.
/// Read-only — used by both [`persist_capture_mode`] and the print-only
/// preview path so a preview's baked `CAPTURE_MODE` matches what the next
/// `--apply` would actually persist (#661).
fn resolve_capture_mode(data_dir: &Path, requested: Option<CaptureModeArg>) -> String {
    let Some(requested) = requested else {
        let path = data_dir.join(crate::commands::hook::CAPTURE_MODE_FILE);
        return match fs::read_to_string(&path) {
            Ok(text) if text.trim().eq_ignore_ascii_case("allowlist") => "allowlist".to_string(),
            _ => "denylist".to_string(),
        };
    };
    match requested {
        CaptureModeArg::Allowlist => "allowlist".to_string(),
        CaptureModeArg::Denylist => "denylist".to_string(),
    }
}

/// Settle and persist the capture failure mode (#446), returning the mode now
/// in force.
///
/// An explicit flag writes the file. Omitting the flag *reads* the stored
/// value rather than defaulting to it, so a bare `--apply` — including the
/// auto-refresh inside `ai-memory upgrade` — can never quietly downgrade an
/// existing opt-in back to capture-by-default.
fn persist_capture_mode(data_dir: &Path, requested: Option<CaptureModeArg>) -> Result<String> {
    let value = resolve_capture_mode(data_dir, requested);
    if requested.is_some() {
        let path = data_dir.join(crate::commands::hook::CAPTURE_MODE_FILE);
        fs::create_dir_all(data_dir)
            .with_context(|| format!("creating data dir {}", data_dir.display()))?;
        // Atomically, because every reader maps an unrecognised value onto
        // `denylist`: a torn write would not corrupt the opt-in, it would
        // silently revert it to capture-by-default (`CONTRIBUTING.md`,
        // "Atomic file writes only").
        ai_memory_wiki::write_atomic(&path, format!("{value}\n").as_bytes())
            .with_context(|| format!("writing {}", path.display()))?;
    }
    Ok(value)
}

/// Whether the Claude Code install should include its prompt-capture hook.
/// Explicit flags win. A bare apply preserves the state of an existing
/// ai-memory install so `upgrade` cannot silently restore a privacy opt-out.
fn install_claude_prompt_capture(args: &InstallHooksArgs) -> bool {
    if args.no_capture_prompts {
        return false;
    }
    if args.capture_prompts || !args.apply {
        return true;
    }
    existing_agent_config(args)
        .as_deref()
        .and_then(baked_claude_prompt_capture)
        .unwrap_or(true)
}

/// Recover prompt-capture state only from hook entries owned by ai-memory.
/// `None` means this is not an existing ai-memory Claude Code install.
fn baked_claude_prompt_capture(existing: &str) -> Option<bool> {
    let document: serde_json::Value = serde_json::from_str(existing).ok()?;
    let hooks = ai_memory_claude_hooks(&document)?;
    Some(
        hooks
            .get(CLAUDE_PROMPT_EVENT)
            .and_then(serde_json::Value::as_array)
            .is_some_and(|entries| entries.iter().any(is_ai_memory_hook_entry)),
    )
}

/// Whether the currently-installed config for this agent already bakes the
/// `--capture-assistant` opt-in. Used to preserve that opt-in across a bare
/// re-apply (e.g. `ai-memory run` auto-wire) instead of dropping it. Only the
/// agents where assistant capture is supported reach here.
fn existing_capture_assistant_opt_in(args: &InstallHooksArgs) -> bool {
    existing_agent_config(args)
        .as_deref()
        .and_then(baked_capture_assistant)
        .unwrap_or(false)
}

/// `Some(true|false)` when `existing` is a recognizable ai-memory install and
/// whether its Stop command carries `--capture-assistant`; `None` when it is not
/// an ai-memory install at all (so there is nothing to preserve).
fn baked_capture_assistant(existing: &str) -> Option<bool> {
    if existing
        .contains("// Auto-generated by `ai-memory install-hooks --agent opencode2 --apply`.")
    {
        return Some(existing.contains("const CAPTURE_ASSISTANT = true;"));
    }
    let document: serde_json::Value = serde_json::from_str(existing).ok()?;
    let hooks = document.get("hooks")?.as_object()?;
    let mut saw_ai_memory = false;
    let mut has_marker = false;
    for entries in hooks.values().filter_map(serde_json::Value::as_array) {
        for entry in entries {
            // Nested (`hooks:[{command}]`) or flat (`{command}`) shape.
            let nested = entry.get("hooks").and_then(serde_json::Value::as_array);
            let hook_entries: Vec<&serde_json::Value> = match nested {
                Some(inner) => inner.iter().collect(),
                None => vec![entry],
            };
            for hook_entry in hook_entries {
                let Some(command) = hook_entry.get("command").and_then(|c| c.as_str()) else {
                    continue;
                };
                let args = hook_entry.get("args").and_then(serde_json::Value::as_array);
                let recognizer = args.map_or_else(
                    || command.to_owned(),
                    |args| {
                        let suffix = args
                            .iter()
                            .filter_map(serde_json::Value::as_str)
                            .collect::<Vec<_>>()
                            .join(" ");
                        format!("{command} {suffix}")
                    },
                );
                if hook_command_is_ours(&recognizer) {
                    saw_ai_memory = true;
                    let args_have_marker = args.is_some_and(|args| {
                        args.iter()
                            .any(|arg| arg.as_str() == Some("--capture-assistant"))
                    });
                    if command.contains("--capture-assistant") || args_have_marker {
                        has_marker = true;
                    }
                }
            }
        }
    }
    saw_ai_memory.then_some(has_marker)
}

/// Read the config file `--apply` will update for the selected agent.
fn existing_agent_config(args: &InstallHooksArgs) -> Option<String> {
    let path = if let Some(path) = &args.config_file {
        if args.agent == AgentChoice::Openclaw {
            path.join(openclaw_plugin::ENTRYPOINT_TS)
        } else {
            path.clone()
        }
    } else {
        match args.agent {
            AgentChoice::ClaudeCode => claude_settings_target(args).ok()?,
            // `run` resolves it into `args.config_file` before any caller.
            AgentChoice::Codex => return None,
            AgentChoice::CommandCode => command_code_settings_path().ok()?,
            AgentChoice::Cursor => cursor_hooks_path().ok()?,
            AgentChoice::GeminiCli => gemini_settings_path().ok()?,
            AgentChoice::OpenCode => opencode_plugin_path().ok()?,
            AgentChoice::OpenCode2 => opencode2_plugin_path().ok()?,
            AgentChoice::Pi => pi_extension_path().ok()?,
            AgentChoice::Omp => omp_extension_path(args.profile.as_deref()).ok()?,
            AgentChoice::Openclaw => openclaw_plugin::default_plugin_dir()
                .ok()?
                .join(openclaw_plugin::ENTRYPOINT_TS),
            AgentChoice::AntigravityCli => antigravity_hooks_path().ok()?,
            AgentChoice::Grok => grok_hooks_path().ok()?,
            AgentChoice::Zero => zero_hooks_path().ok()?,
            AgentChoice::Zcode => zcode_config_path().ok()?,
            // Hermes' hook config is `~/.hermes/config.yaml`, which ai-memory
            // never writes, so there is no install-owned file to recover a
            // baked project strategy from.
            AgentChoice::Hermes => return None,
            AgentChoice::Devin => devin_hooks_path().ok()?,
            AgentChoice::KimiCode => kimi_code_config_path().ok()?,
            AgentChoice::KiroCli => return None,
            // Pool's hook config is per-repo (`.poolside/settings.yaml`), not a
            // user-global file the installer could re-read a baked strategy from.
            AgentChoice::Pool => return None,
            AgentChoice::KiroCliV3 => kiro_cli_v3_hooks_path().ok()?,
            AgentChoice::CopilotCli => copilot_cli_hooks_path().ok()?,
            AgentChoice::Droid => droid_hooks_path().ok()?,
            // `run` resolves it into `args.config_file` before any caller.
            AgentChoice::Muse => return None,
            AgentChoice::CodeBuddy => codebuddy_settings_path().ok()?,
            AgentChoice::IbmBob => ibm_bob_settings_path().ok()?,
            // DSH's hook config is the generated `hooks.json` under the
            // data dir; it carries no baked strategy worth re-reading
            // (same reason Pool returns None).
            AgentChoice::Dsh => return None,
            // Cline hook files are generated independently and carry no
            // shared settings document from which to recover a strategy.
            AgentChoice::Cline => return None,
            AgentChoice::QwenCode => qwen_code_settings_path().ok()?,
            AgentChoice::Qoder => qoder_settings_path().ok()?,
        }
    };
    std::fs::read_to_string(path).ok()
}

/// Whether a generated TypeScript integration carries the ownership banner and
/// agent constant used by the installer and uninstaller.
pub(crate) fn generated_integration_content_is_owned(agent: AgentChoice, existing: &str) -> bool {
    let (name, agent_constant) = match agent {
        AgentChoice::OpenCode => ("opencode", "open-code"),
        AgentChoice::OpenCode2 => ("opencode2", "opencode2"),
        AgentChoice::Pi => ("pi", "pi"),
        AgentChoice::Omp => ("omp", "omp"),
        AgentChoice::Openclaw => ("openclaw", "openclaw"),
        _ => return false,
    };
    let banner = format!("// Auto-generated by `ai-memory install-hooks --agent {name} --apply`.");
    existing.lines().next() == Some(banner.as_str())
        && existing.contains(&format!("const AGENT = \"{agent_constant}\";"))
}

/// Recover a strategy only from configuration entries ai-memory owns. Shared
/// JSON/TOML config files may contain unrelated hooks, while generated
/// TypeScript files carry an explicit ownership header.
fn baked_project_strategy(agent: AgentChoice, existing: &str) -> Option<ProjectStrategyArg> {
    match agent {
        AgentChoice::OpenCode
        | AgentChoice::OpenCode2
        | AgentChoice::Pi
        | AgentChoice::Omp
        | AgentChoice::Openclaw => {
            let marker = match agent {
                AgentChoice::OpenCode => "--agent opencode --apply`.",
                AgentChoice::OpenCode2 => "--agent opencode2 --apply`.",
                AgentChoice::Pi => "--agent pi --apply`.",
                AgentChoice::Omp => "--agent omp --apply`.",
                AgentChoice::Openclaw => "--agent openclaw --apply`.",
                _ => return None,
            };
            existing
                .lines()
                .next()
                .filter(|line| {
                    line.starts_with("// Auto-generated by `ai-memory install-hooks ")
                        && line.ends_with(marker)
                })
                .and_then(|_| project_strategy_from_text(existing))
        }
        AgentChoice::KimiCode => {
            let document: toml_edit::DocumentMut = existing.parse().ok()?;
            document
                .get("hooks")
                .and_then(toml_edit::Item::as_array_of_tables)
                .and_then(|hooks| {
                    hooks.iter().find_map(|entry| {
                        if !is_ai_memory_toml_hook_entry(entry) {
                            return None;
                        }
                        entry
                            .get("command")
                            .and_then(|item| item.as_str())
                            .and_then(project_strategy_from_text)
                    })
                })
        }
        AgentChoice::KiroCliV3 => {
            let root: serde_json::Value = serde_json::from_str(existing).ok()?;
            root.get("hooks")
                .and_then(serde_json::Value::as_array)
                .and_then(|hooks| {
                    hooks.iter().find_map(|entry| {
                        is_ai_memory_kiro_v3_hook_entry(entry)
                            .then(|| {
                                entry
                                    .pointer("/action/command")
                                    .and_then(serde_json::Value::as_str)
                                    .and_then(project_strategy_from_text)
                            })
                            .flatten()
                    })
                })
        }
        _ => serde_json::from_str(existing)
            .ok()
            .as_ref()
            .and_then(project_strategy_from_json),
    }
}

fn project_strategy_from_json(value: &serde_json::Value) -> Option<ProjectStrategyArg> {
    if is_ai_memory_hook_entry(value) {
        if let Some(strategy) = value
            .get("command")
            .and_then(|command| command.as_str())
            .and_then(project_strategy_from_text)
        {
            return Some(strategy);
        }
        if let Some(args) = value.get("args").and_then(|args| args.as_array()) {
            let args: Vec<&str> = args.iter().filter_map(|arg| arg.as_str()).collect();
            for (index, arg) in args.iter().enumerate() {
                if let Some(value) = arg.strip_prefix("--project-strategy=")
                    && is_repo_root_strategy(value)
                {
                    return Some(ProjectStrategyArg::RepoRoot);
                }
                if *arg == "--project-strategy"
                    && args
                        .get(index + 1)
                        .is_some_and(|value| is_repo_root_strategy(value))
                {
                    return Some(ProjectStrategyArg::RepoRoot);
                }
            }
        }
    }

    match value {
        serde_json::Value::Array(values) => values.iter().find_map(project_strategy_from_json),
        serde_json::Value::Object(values) => values.values().find_map(project_strategy_from_json),
        _ => None,
    }
}

/// Only `repo-root` is baked (`basename` removes the marker), so it is the sole
/// value recovered from legacy shell commands and generated source.
fn project_strategy_from_text(existing: &str) -> Option<ProjectStrategyArg> {
    for marker in [
        "AI_MEMORY_PROJECT_STRATEGY=",
        "--project-strategy=",
        "--project-strategy ",
        "const DEFAULT_PROJECT_STRATEGY =",
    ] {
        for rest in existing.split(marker).skip(1) {
            let token: String = rest
                .trim_start_matches(|character: char| {
                    character.is_ascii_whitespace() || matches!(character, '\'' | '"')
                })
                .chars()
                .take_while(|character| {
                    character.is_ascii_alphanumeric() || matches!(character, '-' | '_')
                })
                .collect();
            if is_repo_root_strategy(&token) {
                return Some(ProjectStrategyArg::RepoRoot);
            }
        }
    }
    None
}

fn is_repo_root_strategy(value: &str) -> bool {
    matches!(value, "repo-root" | "repo_root")
}

/// Reject `--as-user X` without a usable `--auth-token`. P1.8
/// metadata flag — without a token, the hook scripts would still
/// authenticate anonymously (or as root if the operator reused the
/// config bearer), so the `--as-user X` label would be misleading.
/// Trims whitespace; empty / whitespace-only `--as-user` is treated
/// as not-set so an accidental `--as-user ""` doesn't bail.
///
/// # Errors
/// Returns an error when `as_user` is set but `auth_token` is `None`
/// (or whitespace-only). The error message names the user so
/// operators see which arg they meant to pair with `--auth-token`.
fn validate_as_user(as_user: Option<&str>, auth_token: Option<&str>) -> Result<()> {
    let Some(user) = as_user.map(str::trim).filter(|s| !s.is_empty()) else {
        return Ok(());
    };
    if auth_token.map(str::trim).is_none_or(str::is_empty) {
        anyhow::bail!(
            "--as-user '{user}' requires --auth-token \
             (issue one with `ai-memory api-key add --username {user} --label <label>`)"
        );
    }
    Ok(())
}

fn effective_hook_server_url(
    config: &Config,
    args: &InstallHooksArgs,
    inferred: Option<&InferredMcpConfig>,
) -> String {
    let raw = if let Some(url) = &args.server_url {
        url.clone()
    } else if config.server_url_configured() {
        config.server_url.clone()
    } else if let Some(url) = inferred.and_then(|mcp| mcp.hook_server_url.clone()) {
        url
    } else if config.server_url_derived_from_bind {
        // Nothing chose a URL and no existing entry names one: reach the
        // server this config's `bind` starts (#1269).
        config.server_url.clone()
    } else {
        return DEFAULT_SERVER_URL.to_string();
    };
    apply_base_path_to_hook_url(&normalise_hook_server_url(&raw), &config.base_path)
}

fn normalise_hook_server_url(url: &str) -> String {
    url.trim().trim_end_matches('/').to_string()
}

/// Thread `Config::base_path` into the URL baked into hook commands so
/// the native hook subcommand (`ai-memory hook`) and the POSIX
/// `.sh`/`.ps1` scripts POST to `<origin><base>/hook` instead of
/// 404'ing under a reverse proxy.
///
/// Skip when the resolved URL already carries a path component — that
/// means the operator put the prefix into `AI_MEMORY_SERVER_URL`
/// directly (`http://host:49374/wiki`) and we'd double it otherwise.
fn apply_base_path_to_hook_url(url: &str, base_path: &str) -> String {
    let (origin, existing_path) = crate::http_client::split_origin_and_path(url);
    if !existing_path.is_empty() {
        return url.to_string();
    }
    let prefix = ai_memory_web::normalize_prefix(base_path);
    if prefix.is_empty() {
        origin
    } else {
        format!("{origin}{prefix}")
    }
}

/// The first readable TOML MCP config among `paths` that registers ai-memory.
fn infer_first_toml_mcp_config(
    paths: impl IntoIterator<Item = PathBuf>,
) -> Option<InferredMcpConfig> {
    paths.into_iter().find_map(|path| {
        fs::read_to_string(path)
            .ok()
            .and_then(|content| infer_toml_mcp_config(&content))
    })
}

fn infer_installed_mcp_config(
    agent: AgentChoice,
    config_path: Option<&Path>,
) -> Result<Option<InferredMcpConfig>> {
    let Some(client) = mcp_client_for_agent(agent) else {
        return Ok(None);
    };
    let path = match config_path {
        Some(path) => path.to_path_buf(),
        None => install_mcp::mcp_config_path(client)?,
    };
    if agent == AgentChoice::Grok {
        let cwd = std::env::current_dir()
            .context("could not resolve current dir for Grok project configuration")?;
        let repo_root = ai_memory_consolidate::discover_repo_root(&cwd).ok();
        if let Some(project_config) = find_grok_project_overlay(&cwd, repo_root.as_deref(), &path) {
            anyhow::bail!(
                "Grok project configuration {} may override GROK_HOME; pass explicit --server-url and --auth-token rather than inferring MCP settings",
                project_config.display()
            );
        }
    }
    if matches!(client, McpClient::Codex) {
        // An entry written before `install-mcp` honored CODEX_HOME still sits
        // in ~/.codex/config.toml; keep inferring from it until it is rewritten.
        let legacy = home_dir().map(|home| home.join(".codex").join("config.toml"));
        return Ok(infer_first_toml_mcp_config(
            std::iter::once(path).chain(legacy),
        ));
    }
    let Ok(content) = fs::read_to_string(path) else {
        return Ok(None);
    };
    match client {
        McpClient::ClaudeCode => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        // Codex uses `http_headers`; Grok uses `headers`. The shared TOML
        // inferencer accepts both.
        McpClient::Codex => Ok(infer_toml_mcp_config(&content)),
        McpClient::CommandCode | McpClient::CopilotCli | McpClient::IbmBob => Ok(
            infer_json_mcp_config(&content, &["mcpServers", "ai-memory"], "url"),
        ),
        // `install-mcp --client droid` writes the bearer as the
        // `${AI_MEMORY_AUTH_TOKEN}` reference Droid expands, not the token,
        // so only the URL is inferred from it.
        McpClient::Droid => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )
        .map(|inferred| InferredMcpConfig {
            auth_token: None,
            ..inferred
        })),
        McpClient::Grok => infer_grok_mcp_config(&content),
        McpClient::OpenCode | McpClient::OpenCode2 => infer_opencode_mcp_config(&content, client),
        McpClient::Cursor => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        McpClient::GeminiCli | McpClient::QwenCode => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "httpUrl",
        )),
        McpClient::Openclaw => Ok(infer_json_mcp_config(
            &content,
            &["mcp", "servers", "ai-memory"],
            "url",
        )),
        McpClient::Omp => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        McpClient::Zero => Ok(infer_json_mcp_config(
            &content,
            &["mcp", "servers", "ai-memory"],
            "url",
        )),
        McpClient::Zcode => Ok(infer_json_mcp_config(
            &content,
            &["mcp", "servers", "ai-memory"],
            "url",
        )),
        McpClient::Pi => Ok(None),
        // DeepSeek Harness has no fixed MCP config file, and Hermes' is YAML
        // ai-memory never writes; no AgentChoice counterpart routes either
        // here, so this arm only satisfies exhaustiveness.
        McpClient::Dsh | McpClient::Hermes => Ok(None),
        McpClient::AntigravityCli => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "serverUrl",
        )),
        McpClient::Devin => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        McpClient::KimiCode | McpClient::KiroCli => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        McpClient::ClaudeDesktop => Ok(None),
        // MCP-only client: no AgentChoice counterpart routes here.
        McpClient::Swival => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        // MCP-only client: no AgentChoice counterpart routes here.
        // Reachable only if a future install_hooks flow targets VS
        // Code Copilot directly.
        McpClient::VsCodeCopilot => Ok(infer_json_mcp_config(
            &content,
            &["servers", "ai-memory"],
            "url",
        )),
        // MCP-only client: no AgentChoice counterpart routes here.
        McpClient::Zed => Ok(infer_json_mcp_config(
            &content,
            &["context_servers", "ai-memory"],
            "url",
        )),
        McpClient::Muse => Ok(infer_muse_mcp_config(&content)),
        McpClient::Qoder => Ok(infer_muse_mcp_config(&content)),
        // MCP-only client: no AgentChoice counterpart routes here. Prime
        // Agent 0.10 has no lifecycle hooks, and its entry names the token
        // variable rather than carrying a bearer, so only the URL is there.
        McpClient::PrimeAgent => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory"],
            "url",
        )),
        McpClient::Cline => Ok(infer_json_mcp_config(
            &content,
            &["mcpServers", "ai-memory", "transport"],
            "url",
        )),
        McpClient::Freebuff => Ok(None),
    }
}

/// Grok loads project settings from every directory between the repository
/// root and CWD. Outside a repository, only the active directory is relevant.
fn grok_project_overlay_paths(cwd: &Path, repo_root: Option<&Path>) -> Vec<PathBuf> {
    let start = repo_root
        .filter(|root| cwd.starts_with(root))
        .unwrap_or(cwd);
    let mut directories = Vec::new();
    let mut current = cwd;
    loop {
        directories.push(current.to_path_buf());
        if current == start {
            break;
        }
        let Some(parent) = current.parent() else {
            break;
        };
        current = parent;
    }
    directories.reverse();
    directories
        .into_iter()
        .map(|directory| directory.join(".grok").join("config.toml"))
        .collect()
}

/// The first existing project overlay, skipping the user config itself. Run
/// from `$HOME` with the default `GROK_HOME`, `<cwd>/.grok/config.toml` *is*
/// `$GROK_HOME/config.toml`, and Grok reads it once, as the user layer: `grok
/// inspect` (Grok 1.0.67) lists it under `User:` with `Project: (none)`. With
/// `GROK_HOME` elsewhere the same file is a project layer, and it still counts.
fn find_grok_project_overlay(
    cwd: &Path,
    repo_root: Option<&Path>,
    user_config: &Path,
) -> Option<PathBuf> {
    grok_project_overlay_paths(cwd, repo_root)
        .into_iter()
        .find(|path| path.exists() && !is_same_existing_file(path, user_config))
}

fn is_same_existing_file(left: &Path, right: &Path) -> bool {
    match (left.canonicalize(), right.canonicalize()) {
        (Ok(left), Ok(right)) => left == right,
        _ => false,
    }
}

pub(crate) fn mcp_client_for_agent(agent: AgentChoice) -> Option<McpClient> {
    match agent {
        AgentChoice::ClaudeCode => Some(McpClient::ClaudeCode),
        AgentChoice::Codex => Some(McpClient::Codex),
        AgentChoice::CommandCode => Some(McpClient::CommandCode),
        AgentChoice::Cursor => Some(McpClient::Cursor),
        AgentChoice::GeminiCli => Some(McpClient::GeminiCli),
        AgentChoice::OpenCode => Some(McpClient::OpenCode),
        AgentChoice::OpenCode2 => Some(McpClient::OpenCode2),
        AgentChoice::Omp => Some(McpClient::Omp),
        AgentChoice::Openclaw => Some(McpClient::Openclaw),
        AgentChoice::AntigravityCli => Some(McpClient::AntigravityCli),
        AgentChoice::Zero => Some(McpClient::Zero),
        AgentChoice::Grok => Some(McpClient::Grok),
        AgentChoice::Devin => Some(McpClient::Devin),
        AgentChoice::KimiCode => Some(McpClient::KimiCode),
        // Pi bridges MCP through its generated extension, not a native
        // mcp.json the installer can scrape.
        AgentChoice::Pi => None,
        AgentChoice::KiroCli | AgentChoice::KiroCliV3 => Some(McpClient::KiroCli),
        // No first-party Pool MCP installer ships yet, so there is no
        // config file to infer a server URL or token from.
        AgentChoice::Pool => None,
        // The ZCode MCP client ships with #511; until that lands there is
        // no `McpClient::Zcode` whose config the installer could scrape a
        // server URL or token from.
        AgentChoice::Zcode => None,
        // `install-mcp --client hermes` is print-only: ai-memory never writes
        // `~/.hermes/config.yaml`, so there is no entry of its own to infer a
        // server URL or token from.
        AgentChoice::Hermes => None,
        AgentChoice::CopilotCli => Some(McpClient::CopilotCli),
        AgentChoice::Droid => Some(McpClient::Droid),
        AgentChoice::Muse => Some(McpClient::Muse),
        // No first-party CodeBuddy MCP installer in this change.
        AgentChoice::CodeBuddy => None,
        AgentChoice::IbmBob => Some(McpClient::IbmBob),
        // DSH has no fixed MCP config file to scrape a server URL or token
        // from (install-mcp --client dsh is print-only), so pass explicit
        // --server-url / --auth-token instead.
        AgentChoice::Dsh => None,
        AgentChoice::Cline => Some(McpClient::Cline),
        AgentChoice::QwenCode => Some(McpClient::QwenCode),
        AgentChoice::Qoder => Some(McpClient::Qoder),
    }
}

/// The hook config `--apply` writes for an agent that `ai-memory run`
/// auto-wires, with the relocation variables read through `env` rather than
/// ai-memory's own environment. It is the default each installer picks when no
/// `--config-file` is given; for Kiro CLI v2 that default is the agents
/// directory whose configs receive the hooks, not a single file.
///
/// # Errors
/// When `$HOME` cannot be located, or for an agent `run` does not auto-wire.
pub(crate) fn hook_config_target_with(
    agent: AgentChoice,
    env: &dyn Fn(&str) -> Option<std::ffi::OsString>,
) -> Result<PathBuf> {
    match agent {
        AgentChoice::ClaudeCode => claude_settings_path_in(env("CLAUDE_CONFIG_DIR")),
        AgentChoice::Codex => codex_hooks_path_in(env("CODEX_HOME")),
        AgentChoice::OpenCode => opencode_plugin_path(),
        AgentChoice::OpenCode2 => opencode2_plugin_path(),
        AgentChoice::Pi => pi_extension_path_in(env("PI_CODING_AGENT_DIR")),
        AgentChoice::Omp => omp_extension_path_with(None, env),
        AgentChoice::KimiCode => kimi_code_config_path_in(env("KIMI_CODE_HOME")),
        AgentChoice::CommandCode => command_code_settings_path(),
        AgentChoice::KiroCli => kiro_cli_home_join(env("KIRO_HOME"), "agents"),
        AgentChoice::KiroCliV3 => {
            Ok(kiro_cli_home_join(env("KIRO_HOME"), "hooks")?.join("ai-memory.json"))
        }
        AgentChoice::Grok => grok_hooks_path_in(env("GROK_HOME")),
        AgentChoice::AntigravityCli => antigravity_hooks_path(),
        AgentChoice::CopilotCli => copilot_cli_hooks_path_in(env("COPILOT_HOME")),
        AgentChoice::Cline => cline_hooks_path_in(env("HOME")),
        other => anyhow::bail!(
            "{} is not auto-wired by `ai-memory run`",
            other.kind().as_str()
        ),
    }
}

fn infer_opencode_mcp_config(
    content: &str,
    selected: McpClient,
) -> Result<Option<InferredMcpConfig>> {
    Ok(
        install_mcp::infer_owned_opencode_mcp_config(content, selected)?.map(|inferred| {
            InferredMcpConfig {
                hook_server_url: hook_server_url_from_mcp_url(&inferred.mcp_url),
                auth_token: inferred.auth_token,
            }
        }),
    )
}

fn json_value_at_path<'a>(
    root: &'a serde_json::Value,
    entry_path: &[&str],
) -> Option<&'a serde_json::Value> {
    entry_path
        .iter()
        .try_fold(root, |entry, key| entry.get(*key))
}

fn infer_json_mcp_config(
    content: &str,
    entry_path: &[&str],
    url_key: &str,
) -> Option<InferredMcpConfig> {
    let root: serde_json::Value = serde_json::from_str(content).ok()?;
    let entry = json_value_at_path(&root, entry_path)?;
    let hook_server_url = entry
        .get(url_key)
        .and_then(|v| v.as_str())
        .and_then(hook_server_url_from_mcp_url);
    let auth_token = entry
        .get("headers")
        .and_then(|headers| headers.get("Authorization"))
        .and_then(|v| v.as_str())
        .and_then(bearer_token_from_header);
    Some(InferredMcpConfig {
        hook_server_url,
        auth_token,
    })
}

/// Infer the hook server URL and bearer from Muse's `ai-memory` entry, under
/// `mcpServers` or the legacy `mcp_servers`. The entry `install-mcp --client
/// muse` writes is the stdio bridge, whose upstream is its `--server-url`
/// argument and whose token, when one was given explicitly, is the literal
/// `env.AI_MEMORY_AUTH_TOKEN`; an older streamable-HTTP entry carries `url`
/// and an `Authorization` header instead. A `${...}` reference is never taken
/// for a token.
fn infer_muse_mcp_config(content: &str) -> Option<InferredMcpConfig> {
    let root: serde_json::Value = serde_json::from_str(content).ok()?;
    let entry = ["mcpServers", "mcp_servers"]
        .iter()
        .find_map(|key| root.get(*key)?.get("ai-memory"))?;
    let hook_server_url = entry
        .get("url")
        .and_then(serde_json::Value::as_str)
        .or_else(|| install_mcp::bridge_entry_url(entry))
        .and_then(hook_server_url_from_mcp_url);
    let auth_token = entry
        .get("headers")
        .and_then(|headers| headers.get("Authorization"))
        .and_then(serde_json::Value::as_str)
        .and_then(bearer_token_from_header)
        .or_else(|| {
            entry
                .pointer("/env/AI_MEMORY_AUTH_TOKEN")
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned)
        })
        .filter(|token| !token.trim().is_empty() && !token.contains("${"));
    Some(InferredMcpConfig {
        hook_server_url,
        auth_token,
    })
}

/// Infer hook server URL + bearer from a TOML `[mcp_servers.ai-memory]`
/// entry (Codex `http_headers` or Grok `headers`).
fn infer_toml_mcp_config(content: &str) -> Option<InferredMcpConfig> {
    let doc: toml_edit::DocumentMut = content.parse().ok()?;
    // `toml_edit::Item`'s `Index` impl panics on missing keys, so this
    // walks the table chain with `.get()` instead. A user with
    // `[mcp_servers.context7]` but no `[mcp_servers.ai-memory]` is a
    // perfectly valid hooks-only Codex/Grok setup (issue #53) — return None
    // rather than abort the whole install with a stack trace.
    let server = doc.get("mcp_servers")?.get("ai-memory")?;

    let hook_server_url = server
        .get("url")
        .and_then(|v| v.as_str())
        .and_then(hook_server_url_from_mcp_url);
    let auth_token = server
        .get("http_headers")
        .and_then(|h| h.get("Authorization"))
        .or_else(|| server.get("headers").and_then(|h| h.get("Authorization")))
        .and_then(|v| v.as_str())
        .and_then(bearer_token_from_header);
    if hook_server_url.is_none() && auth_token.is_none() {
        return None;
    }
    Some(InferredMcpConfig {
        hook_server_url,
        auth_token,
    })
}

/// Infer Grok's TOML entry after resolving its supported `${VAR}` and
/// `${VAR:-default}` placeholders. Refuse missing variables so generated hook
/// commands never contain a literal placeholder.
fn infer_grok_mcp_config(content: &str) -> Result<Option<InferredMcpConfig>> {
    let doc: toml_edit::DocumentMut = match content.parse() {
        Ok(doc) => doc,
        Err(_) => return Ok(None),
    };
    let Some(server) = doc
        .get("mcp_servers")
        .and_then(|servers| servers.get("ai-memory"))
    else {
        return Ok(None);
    };
    let hook_server_url = server
        .get("url")
        .and_then(|value| value.as_str())
        .map(expand_grok_placeholders)
        .transpose()?
        .as_deref()
        .and_then(hook_server_url_from_mcp_url);
    let auth_token = server
        .get("headers")
        .and_then(|headers| headers.get("Authorization"))
        .and_then(|value| value.as_str())
        .map(expand_grok_placeholders)
        .transpose()?
        .as_deref()
        .and_then(bearer_token_from_header);
    if hook_server_url.is_none() && auth_token.is_none() {
        return Ok(None);
    }
    Ok(Some(InferredMcpConfig {
        hook_server_url,
        auth_token,
    }))
}

fn expand_grok_placeholders(value: &str) -> Result<String> {
    expand_grok_placeholders_with(value, |name| std::env::var(name).ok())
}

fn expand_grok_placeholders_with(
    value: &str,
    lookup: impl Fn(&str) -> Option<String>,
) -> Result<String> {
    let mut output = String::with_capacity(value.len());
    let mut remaining = value;
    while let Some(start) = remaining.find("${") {
        output.push_str(&remaining[..start]);
        let after_start = &remaining[start + 2..];
        let end = after_start
            .find('}')
            .context("unterminated Grok ${...} placeholder")?;
        let expression = &after_start[..end];
        let (name, default) = expression
            .split_once(":-")
            .map_or((expression, None), |(name, default)| (name, Some(default)));
        if name.is_empty()
            || !name.chars().enumerate().all(|(index, ch)| {
                ch == '_' || ch.is_ascii_alphanumeric() && (index > 0 || ch.is_ascii_alphabetic())
            })
        {
            anyhow::bail!("invalid Grok environment placeholder `${{{expression}}}`");
        }
        let replacement = lookup(name)
            .filter(|value| !value.is_empty())
            .or_else(|| default.map(ToOwned::to_owned))
            .with_context(|| format!("Grok MCP placeholder `${{{name}}}` is unset; pass explicit --server-url and --auth-token"))?;
        output.push_str(&replacement);
        remaining = &after_start[end + 1..];
    }
    output.push_str(remaining);
    Ok(output)
}

fn hook_server_url_from_mcp_url(url: &str) -> Option<String> {
    // Drop query/fragment BEFORE the `/mcp` peel: Kimi Code's
    // `?flavor=moonshot` marker must never leak into hook URLs (and it
    // would stop the suffix from matching).
    let base = url
        .trim()
        .split(['?', '#'])
        .next()
        .unwrap_or_default()
        .trim_end_matches('/');
    if base.is_empty() {
        return None;
    }
    Some(base.strip_suffix("/mcp").unwrap_or(base).to_string())
}

fn bearer_token_from_header(header: &str) -> Option<String> {
    header
        .trim()
        .strip_prefix("Bearer ")
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(ToOwned::to_owned)
}

/// True if a hook-array entry belongs to ai-memory — i.e. some command handler
/// inside it is one of our legacy command strings or one of our exec-form native
/// hook handlers. Used to replace our own entries on re-apply while preserving
/// hooks that other tools registered under the same event.
fn is_ai_memory_hook_entry(entry: &serde_json::Value) -> bool {
    fn mentions_ai_memory(value: &serde_json::Value) -> bool {
        let Some(command) = value.get("command").and_then(|c| c.as_str()) else {
            return false;
        };
        let lower = command.to_ascii_lowercase();
        let args = value.get("args").and_then(|a| a.as_array());
        let Some(args) = args else {
            return hook_command_is_ours(command);
        };
        let tokens: Vec<&str> = args.iter().filter_map(|v| v.as_str()).collect();
        // Exec form: require both an ai-memory-ish executable and our hook argv
        // signature so unrelated helpers such as `ai-memory-helper.exe` are not
        // removed just because their executable name contains ai-memory.
        (lower.contains("ai-memory") || lower.contains("ai_memory"))
            && tokens.contains(&"hook")
            && tokens.contains(&"--event")
            && tokens.contains(&"--agent")
            && tokens.contains(&"--server-url")
    }
    // Flat shape (Cursor): `{ "type":"command", "command":"…" }`.
    // Nested shape (Claude Code / Codex / Gemini):
    // `{ "matcher":"", "hooks":[ {"command":"…"} ] }`.
    mentions_ai_memory(entry)
        || entry
            .get("hooks")
            .and_then(|h| h.as_array())
            .is_some_and(|inner| inner.iter().any(mentions_ai_memory))
}

/// Overlay our hook entries for one event onto the user's existing array
/// for that event: drop any prior ai-memory entries (so re-running
/// `install-hooks` never duplicates them) and append ours, while keeping
/// every third-party hook registered under the same event. Replaces a
/// blind `map.insert(event, value)`, which discarded co-located hooks
/// from other tools (e.g. a context-mode SessionStart hook).
fn overlay_event_hooks(
    map: &mut serde_json::Map<String, serde_json::Value>,
    event: &str,
    our_value: &serde_json::Value,
) {
    let mut entries: Vec<serde_json::Value> = map
        .get(event)
        .and_then(|v| v.as_array())
        .map(|existing| {
            existing
                .iter()
                .filter_map(|entry| {
                    let mut entry = entry.clone();
                    // A nested group can hold a user's hook next to ours
                    // (a shared matcher): drop only our inner commands, and
                    // the group only when nothing else is left in it.
                    if let Some(inner) = entry.get_mut("hooks").and_then(|h| h.as_array_mut()) {
                        let before = inner.len();
                        inner.retain(|hook| !is_ai_memory_hook_entry(hook));
                        return (inner.len() == before || !inner.is_empty()).then_some(entry);
                    }
                    (!is_ai_memory_hook_entry(&entry)).then_some(entry)
                })
                .collect()
        })
        .unwrap_or_default();
    if let Some(ours) = our_value.as_array() {
        entries.extend(ours.iter().cloned());
    }
    map.insert(event.to_string(), serde_json::Value::Array(entries));
}

/// Remove only ai-memory's entries for one event. Delete the event key when
/// no third-party hooks remain so a rendered opt-out stays minimal.
fn remove_ai_memory_event_hooks(map: &mut serde_json::Map<String, serde_json::Value>, event: &str) {
    overlay_event_hooks(map, event, &serde_json::Value::Array(Vec::new()));
    if map
        .get(event)
        .and_then(serde_json::Value::as_array)
        .is_some_and(Vec::is_empty)
    {
        map.remove(event);
    }
}

fn overlay_kiro_cli_event_hooks(
    map: &mut serde_json::Map<String, serde_json::Value>,
    event: &str,
    our_value: &serde_json::Value,
) {
    let mut entries: Vec<serde_json::Value> = map
        .get(event)
        .and_then(|value| value.as_array())
        .map(|existing| {
            existing
                .iter()
                .filter(|entry| {
                    !entry
                        .get("command")
                        .and_then(serde_json::Value::as_str)
                        .is_some_and(is_ai_memory_kiro_hook_command)
                })
                .cloned()
                .collect()
        })
        .unwrap_or_default();
    if let Some(ours) = our_value.as_array() {
        entries.extend(ours.iter().cloned());
    }
    map.insert(event.to_string(), serde_json::Value::Array(entries));
}

/// Whether `--capture-assistant` may take effect for this agent + platform
/// (#196, #743): Claude Code, Codex and OpenCode 2 on a native hook platform.
/// OpenCode 2 forwards completed text through the same native Stop sanitizer.
/// Any other agent or a script-fallback
/// platform cannot honor the opt-in, so the installer bails instead of enabling
/// it silently.
fn capture_assistant_allowed(agent: AgentChoice) -> bool {
    matches!(
        agent,
        AgentChoice::ClaudeCode | AgentChoice::Codex | AgentChoice::OpenCode2
    ) && local_hook_policy_v1_supported()
}

fn prompt_capture_options_allowed(agent: AgentChoice) -> bool {
    agent == AgentChoice::ClaudeCode
}

fn configure_claude_prompt_capture(
    mut payload: serde_json::Value,
    capture_prompts: bool,
) -> serde_json::Value {
    if !capture_prompts
        && let Some(hooks) = payload
            .get_mut("hooks")
            .and_then(serde_json::Value::as_object_mut)
    {
        hooks.remove(CLAUDE_PROMPT_EVENT);
    }
    payload
}

/// Mutate the Claude Code settings file in place: replace the hook entries
/// ai-memory cares about (`CLAUDE_CODE_EVENTS`); preserve every other hook the
/// user has wired up to other tools.
fn apply_to_claude_code_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "claude-code", data_dir)?;
    apply_to_claude_code_settings_with_staged(&staged, server_url, auth_token, data_dir, args)
}

#[cfg(test)]
fn apply_to_claude_code_settings_in(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    staging_data_local: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts_in(hooks_dir, "claude-code", staging_data_local)?;
    let command_dir = staged_command_dir(&staged, "claude-code");
    let capture_prompts = install_claude_prompt_capture(args);
    let payload = configure_claude_prompt_capture(
        crate::commands::render_shared::build_claude_code_script_payload_for_test(
            &command_dir,
            server_url,
            auth_token,
            Some(data_dir),
            args.project_strategy.and_then(ProjectStrategyArg::baked),
            args.capture_assistant,
        ),
        capture_prompts,
    );
    apply_to_claude_code_settings_with_payload(payload, args, data_dir, capture_prompts)
}

fn apply_to_claude_code_settings_with_staged(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let command_dir = staged_command_dir(staged, "claude-code");
    let capture_prompts = install_claude_prompt_capture(args);
    let payload = configure_claude_prompt_capture(
        build_claude_code_payload_with_data_dir(
            &command_dir,
            server_url,
            auth_token,
            Some(data_dir),
            args.project_strategy.and_then(ProjectStrategyArg::baked),
            args.capture_assistant,
        ),
        capture_prompts,
    );
    apply_to_claude_code_settings_with_payload(payload, args, data_dir, capture_prompts)
}

fn apply_to_claude_code_settings_with_payload(
    payload: serde_json::Value,
    args: &InstallHooksArgs,
    data_dir: &Path,
    capture_prompts: bool,
) -> Result<()> {
    let path = claude_settings_target(args)?;
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: build_claude_code_payload didn't return a hooks object")?
        .clone();
    let private_backup =
        (args.scope == HookInstallScope::Project).then(|| project_settings_backup(data_dir, &path));
    let outcome = apply_atomic_with_backup(&path, private_backup.as_ref(), |existing| {
        mutate_json(existing, |root| {
            // Get-or-create the top-level `hooks` table, then merge our
            // event keys in via `overlay_event_hooks`: our entries replace
            // any prior ai-memory entries, while hooks the user (or another
            // tool) wired under the same event — or under a non-overlapping
            // event name (e.g. a hand-written "Notification" hook) — survive.
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in settings.json but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            if !capture_prompts {
                remove_ai_memory_event_hooks(hooks, CLAUDE_PROMPT_EVENT);
            }
            Ok(())
        })
    })?;
    let backup_note = match &private_backup {
        Some(backup) => format!("backup written under {}", backup.dir.display()),
        None => "backup written next to it".to_string(),
    };
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => &backup_note,
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    // Claude Code runs the hooks of both scopes. Identical handlers dedupe, but
    // installs that differ (capture flags, project strategy) capture twice.
    if args.config_file.is_none()
        && let Some(other) = match args.scope {
            HookInstallScope::Project => claude_settings_path().ok(),
            HookInstallScope::Global => std::env::current_dir()
                .ok()
                .map(|cwd| project_claude_settings_local(&cwd)),
        }
        && other != path
        && settings_file_carries_ai_memory_hooks(&other)
    {
        eprintln!(
            "[ai-memory] note: {} also carries ai-memory hooks; Claude Code runs both, so keep \
             one scope or install both with the same flags.",
            other.display()
        );
    }
    // Claude Code adds `**/.claude/settings.local.json` to the global git
    // excludes only when it creates the file itself; a file ai-memory created
    // has no such guarantee, and its hook commands carry machine-specific
    // paths nobody wants committed.
    if args.scope == HookInstallScope::Project
        && ai_memory_consolidate::path_is_git_ignored(&path) == Some(false)
    {
        eprintln!(
            "[ai-memory] warning: {} is not ignored by git. Add `**/.claude/settings.local.json` \
             to this repository's .gitignore (or your global excludes) so the machine-specific \
             hook commands are never committed.",
            path.display()
        );
    }
    Ok(())
}

/// Mutate `~/.grok/hooks/ai-memory.json` so Grok Build CLI fires the ai-memory
/// lifecycle hooks. Grok's hook config is structurally identical to Claude
/// Code's nested hook JSON and uses the same CamelCase event names, but
/// its script bundle carries `agent=grok` and skips destructive SessionStart
/// handoff fetches. We merge into a dedicated `ai-memory.json` (Grok discovers
/// every `~/.grok/hooks/*.json`), so a pre-existing third-party hook file is
/// left untouched.
fn apply_to_grok_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => grok_hooks_path()?,
    };
    let staged = stage_hook_scripts(hooks_dir, "grok", data_dir)?;
    let command_dir = staged_command_dir(&staged, "grok");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = build_grok_payload_with_data_dir(
        &command_dir,
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: build_grok_payload didn't return a hooks object")?
        .clone();
    let outcome = apply_atomic(&path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in ai-memory.json but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

/// Mutate Devin's hook config (either `~/.devin/hooks.v1.json` or `~/.devin/config.json` hooks key).
/// Devin uses the same nested hook JSON shape as Claude Code/Grok, but with DEVIN_EVENTS
/// (PostCompaction instead of PreCompact, no subagent events). SessionStart injects
/// the handoff via hookSpecificOutput.additionalContext.
fn apply_to_devin_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "devin", data_dir)?;
    apply_to_devin_settings_with_staged(&staged, server_url, auth_token, data_dir, args)
}

#[cfg(test)]
fn apply_to_devin_settings_in(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    staging_data_local: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts_in(hooks_dir, "devin", staging_data_local)?;
    apply_to_devin_settings_with_staged(&staged, server_url, auth_token, data_dir, args)
}

fn apply_to_devin_settings_with_staged(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => devin_hooks_path()?,
    };
    let command_dir = staged_command_dir(staged, "devin");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = build_devin_payload_with_data_dir(
        &command_dir,
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: build_devin_payload didn't return a hooks object")?
        .clone();
    let outcome = apply_atomic(&path, |existing| {
        // For hooks.v1.json, the entire file IS the hooks object
        // For config.json hooks key, we merge into the hooks object
        if path.file_name() == Some("hooks.v1.json".as_ref()) {
            mutate_json(existing, |root| {
                for (event, value) in &our_hooks {
                    overlay_event_hooks(root, event, value);
                }
                Ok(())
            })
        } else {
            mutate_json(existing, |root| {
                let hooks = root
                    .entry("hooks")
                    .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                    .as_object_mut()
                    .context("`hooks` is present in config.json but not an object")?;
                for (event, value) in &our_hooks {
                    overlay_event_hooks(hooks, event, value);
                }
                Ok(())
            })
        }
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

/// Mutate `~/.commandcode/settings.json` so Command Code fires the stable
/// four-event lifecycle integration. Command Code's schema requires the outer
/// `matcher` to be omitted for SessionStart and Stop, so its profile must not
/// reuse the otherwise similar Claude/Codex payload byte-for-byte.
fn apply_to_command_code_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "command-code", data_dir)?;
    apply_to_command_code_settings_with_staged(&staged, server_url, auth_token, data_dir, args)
}

#[cfg(test)]
fn apply_to_command_code_settings_in(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    staging_data_local: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts_in(hooks_dir, "command-code", staging_data_local)?;
    let command_dir = staged_command_dir(&staged, "command-code");
    let payload = crate::commands::render_shared::build_profile_script_payload_for_test(
        &COMMAND_CODE_PROFILE,
        &command_dir,
        server_url,
        auth_token,
        "command-code",
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
    );
    apply_to_command_code_settings_with_payload(payload, args)
}

fn apply_to_command_code_settings_with_staged(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let command_dir = staged_command_dir(staged, "command-code");
    let payload = build_profile_payload_for_agent(
        &COMMAND_CODE_PROFILE,
        &command_dir,
        server_url,
        auth_token,
        "command-code",
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
        // Command Code is refused by `capture_assistant_allowed`; never bake it.
        false,
    );
    apply_to_command_code_settings_with_payload(payload, args)
}

fn apply_to_command_code_settings_with_payload(
    payload: serde_json::Value,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(path) => path.clone(),
        None => command_code_settings_path()?,
    };
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: Command Code payload did not return a hooks object")?
        .clone();
    let outcome = apply_atomic(&path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in settings.json but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

/// Mutate `~/.copilot/hooks/ai-memory.json` (creating it if absent) so
/// Copilot CLI fires the ai-memory scripts on every lifecycle event. The file
/// is Copilot's standalone hook format: `{"version": 1, "hooks": {...}}` with
/// flat, matcher-less entries (`COPILOT_CLI_PROFILE`, #1040).
fn apply_to_copilot_cli_hooks(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "copilot-cli", data_dir)?;
    apply_to_copilot_cli_hooks_with_staged(&staged, server_url, auth_token, data_dir, args)
}

#[cfg(test)]
fn apply_to_copilot_cli_hooks_in(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    staging_data_local: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts_in(hooks_dir, "copilot-cli", staging_data_local)?;
    let command_dir = staged_command_dir(&staged, "copilot-cli");
    let payload = crate::commands::render_shared::build_profile_script_payload_for_test(
        &COPILOT_CLI_PROFILE,
        &command_dir,
        server_url,
        auth_token,
        "copilot-cli",
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
    );
    apply_to_copilot_cli_hooks_with_payload(payload, args)
}

fn apply_to_copilot_cli_hooks_with_staged(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let command_dir = staged_command_dir(staged, "copilot-cli");
    let payload = build_profile_payload_for_agent(
        &COPILOT_CLI_PROFILE,
        &command_dir,
        server_url,
        auth_token,
        "copilot-cli",
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
        // Copilot CLI is refused by `capture_assistant_allowed`; never bake it.
        false,
    );
    apply_to_copilot_cli_hooks_with_payload(payload, args)
}

fn apply_to_copilot_cli_hooks_with_payload(
    payload: serde_json::Value,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(path) => path.clone(),
        None => copilot_cli_hooks_path()?,
    };
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: Copilot CLI payload did not return a hooks object")?
        .clone();
    let outcome = apply_atomic(&path, |existing| {
        mutate_json(existing, |root| {
            // Copilot CLI hook files are versioned ("version": 1), like
            // Cursor's hooks.json — overwrite unconditionally.
            root.insert("version".into(), serde_json::json!(1));
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in the hooks file but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

/// Mutate `~/.codex/hooks.json` (creating it if absent) so Codex's
/// lifecycle hook runner fires the ai-memory scripts on every
/// session/prompt/tool event.
///
/// Codex's hook config is structurally identical to Claude Code's
/// (verified against `openai/codex/codex-rs/config/src/hooks_tests.rs`):
///
///   { "hooks": {
///       "SessionStart": [
///         { "matcher": "",
///           "hooks": [ {"type":"command", "command":"..."} ]
///         }
///       ], ...
///   } }
///
/// Codex looks for hooks in `~/.codex/hooks.json` by default (or
/// wherever `hooks = "./relative-path.json"` in config.toml points).
/// We write the standalone file and don't touch config.toml — Codex
/// picks it up automatically.
///
/// Trust note: Codex refuses to RUN new hooks until the user accepts
/// them in the TUI ("Trust all and continue") or sets
/// `--dangerously-bypass-hook-trust`. We print a reminder.
fn apply_to_codex_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "codex", data_dir)?;
    apply_to_codex_settings_with_staged(&staged, server_url, auth_token, data_dir, args)
}

#[cfg(test)]
fn apply_to_codex_settings_in(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    staging_data_local: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts_in(hooks_dir, "codex", staging_data_local)?;
    let command_dir = staged_command_dir(&staged, "codex");
    let payload = crate::commands::render_shared::build_profile_script_payload_for_test(
        &super::render_shared::CODEX_PROFILE,
        &command_dir,
        server_url,
        auth_token,
        "codex",
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
    );
    apply_to_codex_settings_with_payload(payload, args)
}

fn apply_to_codex_settings_with_staged(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let command_dir = staged_command_dir(staged, "codex");
    let payload = build_profile_payload_for_agent(
        &super::render_shared::CODEX_PROFILE,
        &command_dir,
        server_url,
        auth_token,
        "codex",
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
        // Codex Stop carries last_assistant_message (#743); bake the opt-in when
        // asked. `capture_assistant_allowed` already gated it, so this only bakes
        // on a native path.
        args.capture_assistant,
    );
    apply_to_codex_settings_with_payload(payload, args)
}

fn apply_to_codex_settings_with_payload(
    payload: serde_json::Value,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = args
        .config_file
        .clone()
        .context("internal: the Codex hooks path is resolved before apply")?;
    let outcome = merge_codex_payload(payload, &path)?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    // First-time trust reminder. Codex's TUI flags new/changed
    // hooks on startup; users must explicitly trust them before
    // they fire.
    if !matches!(outcome, ApplyOutcome::NoOp) {
        println!();
        println!("Codex requires explicit trust for new hooks. Next time you start `codex`:");
        println!("  → the TUI will surface 'Hooks need review' for each new event");
        println!("  → choose 'Trust all and continue' (or trust individually)");
        println!("To bypass the prompt for automated installs, start with");
        println!("`codex --dangerously-bypass-hook-trust` (review hook scripts first).");
    }
    Ok(())
}

#[cfg(test)]
fn merge_codex_hooks(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
    capture_assistant: bool,
) -> Result<ApplyOutcome> {
    // Build the Codex-flavoured payload. The JSON shape is identical
    // to Claude Code's matcher + nested hooks form — the event list
    // differs only by the Claude-Code-only subagent events.
    let payload = build_profile_payload_for_agent(
        &super::render_shared::CODEX_PROFILE,
        staged,
        server_url,
        auth_token,
        "codex",
        Some(data_dir),
        project_strategy,
        capture_assistant,
    );
    merge_codex_payload(payload, config_path)
}

fn merge_codex_payload(payload: serde_json::Value, config_path: &Path) -> Result<ApplyOutcome> {
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: payload builder didn't return a hooks object")?
        .clone();
    apply_atomic(config_path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in hooks.json but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })
}

/// Mutate `~/.cursor/hooks.json` (creating it if absent) so Cursor's
/// agent fires the ai-memory scripts on lifecycle events.
///
/// Cursor's hook schema (per <https://cursor.com/docs/agent/hooks>) is
/// *flatter* than Claude Code's / Codex's:
///
///   { "version": 1,
///     "hooks": {
///       "sessionStart": [
///         { "type": "command", "command": "...", "matcher": "" }
///       ]
///     }
///   }
///
/// — no inner `hooks: [...]` array, camelCase event names, plus a
/// required top-level `version: 1` key. We use `CURSOR_PROFILE`
/// (HookShape::Flat) to produce the right payload, then merge into
/// the existing file (preserving any non-overlapping events the
/// user has wired up to other tools).
fn apply_to_cursor_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => cursor_hooks_path()?,
    };
    let staged = stage_hook_scripts(hooks_dir, "cursor", data_dir)?;
    let command_dir = staged_command_dir(&staged, "cursor");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let outcome = merge_cursor_hooks(
        &command_dir,
        server_url,
        auth_token,
        data_dir,
        strategy,
        &path,
    )?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    warn_unrecognized_ai_memory_hooks(&path);
    Ok(())
}

/// Warn about hook entries that mention ai-memory but are not recognised as
/// ours, e.g. a wrapper shim that injects `cwd` before calling the binary.
/// `install-hooks` keeps those beside the native entries it adds, so every
/// event would then be captured twice (#721). Best effort: never fails apply.
fn warn_unrecognized_ai_memory_hooks(path: &Path) {
    let Ok(raw) = fs::read_to_string(path) else {
        return;
    };
    let Ok(root) = serde_json::from_str::<serde_json::Value>(&raw) else {
        return;
    };
    for (event, command) in unrecognized_ai_memory_hook_entries(&root) {
        eprintln!(
            "# warning: {} `{event}` hook `{command}` mentions ai-memory but is not an \
             ai-memory hook entry, so it was kept beside the native one and the event \
             may be captured twice. Remove it if it wraps ai-memory.",
            path.display()
        );
    }
}

fn unrecognized_ai_memory_hook_entries(root: &serde_json::Value) -> Vec<(String, String)> {
    let Some(hooks) = root.get("hooks").and_then(serde_json::Value::as_object) else {
        return Vec::new();
    };
    let mut found = Vec::new();
    for (event, entries) in hooks {
        let Some(entries) = entries.as_array() else {
            continue;
        };
        for entry in entries.iter().filter(|e| !is_ai_memory_hook_entry(e)) {
            let handlers = entry
                .get("hooks")
                .and_then(serde_json::Value::as_array)
                .map_or_else(|| vec![entry], |inner| inner.iter().collect());
            for handler in handlers {
                let Some(command) = handler.get("command").and_then(serde_json::Value::as_str)
                else {
                    continue;
                };
                let lower = command.to_ascii_lowercase();
                if lower.contains("ai-memory") || lower.contains("ai_memory") {
                    found.push((event.clone(), command.to_string()));
                }
            }
        }
    }
    found
}

fn merge_cursor_hooks(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<ApplyOutcome> {
    let payload = build_profile_payload_for_agent(
        &CURSOR_PROFILE,
        staged,
        server_url,
        auth_token,
        "cursor",
        Some(data_dir),
        project_strategy,
        false,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: payload builder didn't return a hooks object")?
        .clone();
    apply_atomic(config_path, |existing| {
        mutate_json(existing, |root| {
            // Cursor requires "version": 1 at the top level.
            // Overwrite unconditionally — the schema is versioned
            // so future Cursor releases can bump this; we'll bump
            // here too when that happens.
            root.insert("version".into(), serde_json::json!(1));
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in hooks.json but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })
}

/// Mutate `~/.gemini/settings.json` so Gemini CLI fires the ai-memory
/// scripts on its (Gemini-specific) lifecycle events.
///
/// Gemini's schema (per <https://geminicli.com/docs/hooks/reference>)
/// is the same nested shape as Claude Code's (`matcher` +
/// `hooks: [{type, command}]`), but the event vocabulary differs:
///
///   - `BeforeTool` / `AfterTool`  (ai-memory: `pre-tool-use` / `post-tool-use`)
///   - `PreCompress`               (ai-memory: `pre-compact`)
///   - `SessionStart` / `SessionEnd` line up with Claude Code's
///   - No `UserPromptSubmit` / `Stop` equivalents — skipped
///
/// Like Claude Code, Gemini doesn't honour an `env` field at the
/// inner-hook level, so the env vars get inlined into the command
/// string by the shared payload builder.
fn apply_to_gemini_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => gemini_settings_path()?,
    };
    let staged = stage_hook_scripts(hooks_dir, "gemini-cli", data_dir)?;
    let command_dir = staged_command_dir(&staged, "gemini-cli");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let outcome = merge_gemini_hooks(
        &command_dir,
        server_url,
        auth_token,
        data_dir,
        strategy,
        &path,
    )?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

fn merge_gemini_hooks(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<ApplyOutcome> {
    let payload = build_profile_payload_for_agent(
        &GEMINI_PROFILE,
        staged,
        server_url,
        auth_token,
        "gemini-cli",
        Some(data_dir),
        project_strategy,
        false,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: payload builder didn't return a hooks object")?
        .clone();
    apply_atomic(config_path, |existing| {
        mutate_json(existing, |root| {
            // Gemini's settings.json mixes MCP servers, hooks, and
            // other config under one document. Get-or-create the
            // `hooks` table; overlay our events; preserve siblings.
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in settings.json but not an object")?;
            for (event, value) in &our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })
}

/// Mutate `~/.gemini/config/hooks.json` so Antigravity CLI (`agy`)
/// fires the ai-memory scripts on its lifecycle events.
///
/// Antigravity CLI uses a named-groups format where hook groups are
/// top-level keys (e.g. `"ai-memory"`) containing event arrays. Tool
/// events (`PreToolUse`, `PostToolUse`) use nested shape with matcher;
/// lifecycle events (`SessionStart`, `PreInvocation`, `Stop`) use flat shape.
///
/// Config file: `~/.gemini/config/hooks.json`
fn apply_to_antigravity_settings(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => antigravity_hooks_path()?,
    };
    let staged = stage_hook_scripts(hooks_dir, "antigravity-cli", data_dir)?;
    let command_dir = staged_command_dir(&staged, "antigravity-cli");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let outcome = merge_antigravity_hooks(
        &command_dir,
        server_url,
        auth_token,
        data_dir,
        strategy,
        &path,
    )?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    println!();
    print!("{ANTIGRAVITY_FINALIZATION_GUIDANCE}");
    Ok(())
}

const ANTIGRAVITY_FINALIZATION_GUIDANCE: &str = "\
Antigravity has no conversation-end event. Each finished turn refreshes the\n\
session summary and its handoff, which a new session in this project picks up\n\
once the conversation has been quiet for 10 minutes. To close a conversation\n\
now, hand its baton over at once and queue opt-in SessionEnd consolidation,\n\
run `ai-memory finalize-session --agent antigravity-cli`.\n";

fn merge_antigravity_hooks(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<ApplyOutcome> {
    let payload = build_antigravity_payload_with_data_dir(
        staged,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let our_group = payload
        .get("ai-memory")
        .and_then(|v| v.as_object())
        .context("internal: build_antigravity_payload didn't return an ai-memory group")?
        .clone();
    apply_atomic(config_path, |existing| {
        mutate_json(existing, |root| {
            // Get-or-create the "ai-memory" named group; overlay
            // our events. Other named groups survive untouched.
            let group = root
                .entry("ai-memory")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`ai-memory` is present in hooks.json but not an object")?;
            for (event, value) in &our_group {
                overlay_event_hooks(group, event, value);
            }
            Ok(())
        })
    })
}

/// Mutate Kimi Code's `config.toml` (`$KIMI_CODE_HOME/config.toml` when
/// the var is set, else `~/.kimi-code/config.toml`) so Kimi Code fires
/// the ai-memory scripts on its lifecycle events.
///
/// Kimi Code stores hooks as `[[hooks]]` array-of-tables entries inside
/// the SAME config.toml that carries the user's providers and model,
/// and any unknown key on a hook entry makes the whole config fail to
/// load. The merge is therefore TOML-aware via `toml_edit` (the rest of
/// the document is preserved as parsed) and each entry carries exactly
/// `event` + `command` — `matcher` omitted (Kimi Code matches
/// everything) and `timeout` omitted (30s default).
fn apply_to_kimi_code_config(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => kimi_code_config_path()?,
    };
    let staged = stage_hook_scripts(hooks_dir, "kimi-code", data_dir)?;
    let command_dir = staged_command_dir(&staged, "kimi-code");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let outcome = merge_kimi_code_hooks(
        &command_dir,
        server_url,
        auth_token,
        data_dir,
        strategy,
        &path,
    )?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

fn merge_kimi_code_hooks(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<ApplyOutcome> {
    let commands = kimi_code_hook_commands(
        staged,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    apply_atomic(config_path, |existing| {
        mutate_toml(existing, |doc| upsert_kimi_code_hooks(doc, &commands))
    })
}

/// Insert or refresh ai-memory's `[[hooks]]` entries: drop any prior
/// entry whose command references our staged scripts (so re-runs update
/// in place instead of duplicating), append the fresh set, and leave
/// every third-party `[[hooks]]` entry — and every other table in
/// config.toml — untouched.
fn upsert_kimi_code_hooks(
    doc: &mut toml_edit::DocumentMut,
    commands: &[(&str, String)],
) -> Result<()> {
    use toml_edit::{ArrayOfTables, Item, Table, value};

    if doc.get("hooks").is_none() {
        doc.insert("hooks", Item::ArrayOfTables(ArrayOfTables::new()));
    }
    let hooks = doc
        .get_mut("hooks")
        .and_then(Item::as_array_of_tables_mut)
        .context("`hooks` is present in config.toml but not an array of tables")?;

    let stale: Vec<usize> = hooks
        .iter()
        .enumerate()
        .filter_map(|(i, entry)| is_ai_memory_toml_hook_entry(entry).then_some(i))
        .collect();
    for i in stale.into_iter().rev() {
        hooks.remove(i);
    }
    for (event, command) in commands {
        let mut entry = Table::new();
        entry["event"] = value(*event);
        entry["command"] = value(command);
        hooks.push(entry);
    }
    Ok(())
}

/// True if a `[[hooks]]` table belongs to ai-memory. Keep the ownership
/// signature shared with JSON hook overlays and uninstall so string commands
/// from other tools are not removed during re-apply.
fn is_ai_memory_toml_hook_entry(entry: &toml_edit::Table) -> bool {
    let Some(command) = entry.get("command").and_then(|c| c.as_str()) else {
        return false;
    };
    hook_command_is_ours(command)
}

/// Merge ai-memory's camelCase hook entries into every existing Kiro CLI
/// v2 agent config (`~/.kiro/agents/*.json`, or the single file passed
/// via `--config-file`).
///
/// The v2 engine has no global hook surface: hooks fire only for the
/// agent config that is active, so the installer updates each config the
/// user already has. It never invents one — a fabricated agent config
/// would not be the active agent (the built-in default has no file on
/// disk), so hooks in it would never fire and the install would look
/// successful while capturing nothing.
fn apply_to_kiro_cli_agent_configs(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    // Resolve targets before staging anything so a missing-agent-config
    // bail leaves no half-done install behind.
    let targets: Vec<PathBuf> = match &args.config_file {
        Some(p) => {
            anyhow::ensure!(
                p.is_file(),
                "{} does not exist. Kiro CLI v2 hooks live inside an existing agent config; \
                 create one first (`kiro-cli agent create`) and re-run. For Kiro v3, select \
                 the explicit `--agent kiro-cli-v3` standalone-hook target instead.",
                p.display()
            );
            vec![p.clone()]
        }
        None => list_kiro_cli_agent_configs(&kiro_cli_agents_dir()?)?,
    };
    anyhow::ensure!(
        !targets.is_empty(),
        "no Kiro CLI agent configs found in {}. The v2 engine only fires hooks defined in an \
         agent config and the built-in default agent has no file on disk, so create an agent \
         first (`kiro-cli agent create`, then `kiro-cli agent set-default <name>`) and re-run. \
         For Kiro v3, select the explicit `--agent kiro-cli-v3` standalone-hook target instead.",
        kiro_cli_agents_dir()?.display()
    );
    let prepared = preflight_kiro_cli_agent_configs(
        targets,
        hooks_dir,
        server_url,
        auth_token,
        data_dir,
        args.project_strategy,
    )?;

    let staged = stage_hook_scripts(hooks_dir, "kiro-cli", data_dir)?;
    let command_dir = staged_command_dir(&staged, "kiro-cli");
    for (path, strategy) in prepared {
        let outcome = merge_kiro_cli_agent_hooks(
            &command_dir,
            server_url,
            auth_token,
            data_dir,
            strategy.and_then(ProjectStrategyArg::baked),
            &path,
        )?;
        println!(
            "✓ {} {} ({})",
            outcome.verb(),
            path.display(),
            match outcome {
                ApplyOutcome::Created => "new file",
                ApplyOutcome::Updated => "backup written next to it",
                ApplyOutcome::NoOp => "already up to date",
            }
        );
    }
    Ok(())
}

/// Parse and validate every Kiro v2 target before staging scripts or writing
/// any config. The strategy is recovered per file because Kiro can update
/// several independently-configured agents in one invocation.
fn preflight_kiro_cli_agent_configs(
    targets: Vec<PathBuf>,
    command_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    explicit_strategy: Option<ProjectStrategyArg>,
) -> Result<Vec<(PathBuf, Option<ProjectStrategyArg>)>> {
    let mut prepared = Vec::with_capacity(targets.len());
    for path in targets {
        let existing =
            fs::read_to_string(&path).with_context(|| format!("reading {}", path.display()))?;
        let strategy =
            explicit_strategy.or_else(|| baked_project_strategy(AgentChoice::KiroCli, &existing));
        render_kiro_cli_agent_hooks(
            &existing,
            command_dir,
            server_url,
            auth_token,
            data_dir,
            strategy.and_then(ProjectStrategyArg::baked),
            &path,
        )?;
        prepared.push((path, strategy));
    }
    Ok(prepared)
}

/// Merge ai-memory's v2 hook entries into one Kiro agent config,
/// preserving every third-party entry under the same triggers and every
/// non-hook field of the agent definition.
fn merge_kiro_cli_agent_hooks(
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<ApplyOutcome> {
    apply_atomic(config_path, |existing| {
        render_kiro_cli_agent_hooks(
            existing,
            staged,
            server_url,
            auth_token,
            data_dir,
            project_strategy,
            config_path,
        )
    })
}

fn render_kiro_cli_agent_hooks(
    existing: &str,
    staged: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<String> {
    let our_hooks = build_kiro_cli_v2_hooks_value(
        staged,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    mutate_json(existing, |root| {
        let hooks = root
            .entry("hooks")
            .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
            .as_object_mut()
            .with_context(|| {
                format!(
                    "`hooks` in {} is present but not an object",
                    config_path.display()
                )
            })?;
        for (event, value) in &our_hooks {
            overlay_kiro_cli_event_hooks(hooks, event, value);
        }
        Ok(())
    })
}

fn apply_to_kiro_cli_v3_hooks(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(path) => path.clone(),
        None => kiro_cli_v3_hooks_path()?,
    };
    let existing = match fs::read_to_string(&path) {
        Ok(existing) => existing,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => String::new(),
        Err(error) => return Err(error).with_context(|| format!("reading {}", path.display())),
    };
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);

    // Validate before staging scripts so an incompatible registration file
    // cannot leave a partial installation behind.
    render_kiro_cli_v3_hooks(
        &existing, hooks_dir, server_url, auth_token, data_dir, strategy, &path,
    )?;

    let staged = stage_hook_scripts(hooks_dir, "kiro-cli", data_dir)?;
    let command_dir = staged_command_dir(&staged, "kiro-cli");
    let outcome = merge_kiro_cli_v3_hooks(
        &command_dir,
        server_url,
        auth_token,
        data_dir,
        strategy,
        &path,
    )?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    Ok(())
}

fn merge_kiro_cli_v3_hooks(
    command_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<ApplyOutcome> {
    apply_atomic(config_path, |existing| {
        render_kiro_cli_v3_hooks(
            existing,
            command_dir,
            server_url,
            auth_token,
            data_dir,
            project_strategy,
            config_path,
        )
    })
}

fn render_kiro_cli_v3_hooks(
    existing: &str,
    command_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    config_path: &Path,
) -> Result<String> {
    let desired = build_kiro_cli_v3_hooks_value(
        command_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let desired_hooks = desired
        .get("hooks")
        .and_then(serde_json::Value::as_array)
        .expect("static Kiro v3 hook payload has a hooks array")
        .clone();

    mutate_json(existing, |root| {
        match root.get("version") {
            Some(serde_json::Value::String(version)) if version == "v1" => {}
            Some(serde_json::Value::String(version)) => anyhow::bail!(
                "unsupported Kiro hook schema version `{version}` in {}; expected `v1`",
                config_path.display()
            ),
            Some(_) => anyhow::bail!(
                "`version` in {} is present but not a string",
                config_path.display()
            ),
            None => {
                root.insert(
                    "version".to_string(),
                    serde_json::Value::String("v1".to_string()),
                );
            }
        }

        let hooks = root
            .entry("hooks")
            .or_insert_with(|| serde_json::Value::Array(Vec::new()))
            .as_array_mut()
            .with_context(|| {
                format!(
                    "`hooks` in {} is present but not an array",
                    config_path.display()
                )
            })?;

        for entry in hooks.iter() {
            if let Some(name) = entry.get("name").and_then(serde_json::Value::as_str)
                && kiro_cli_v3_hook_name_is_reserved(name)
                && !is_ai_memory_kiro_v3_hook_entry(entry)
            {
                anyhow::bail!(
                    "Kiro v3 hook `{name}` in {} uses ai-memory's reserved name but is not an \
                     ai-memory hook; rename it before installing",
                    config_path.display()
                );
            }
        }
        hooks.retain(|entry| !is_ai_memory_kiro_v3_hook_entry(entry));
        hooks.extend(desired_hooks);
        Ok(())
    })
}

fn kiro_cli_v3_hook_name_is_reserved(name: &str) -> bool {
    KIRO_CLI_V3_EVENTS.iter().any(|(_, script)| {
        script
            .strip_suffix(".sh")
            .is_some_and(|stem| name == format!("ai-memory-{stem}"))
    })
}

pub(crate) fn is_ai_memory_kiro_v3_hook_entry(entry: &serde_json::Value) -> bool {
    let Some(name) = entry.get("name").and_then(serde_json::Value::as_str) else {
        return false;
    };
    let Some(trigger) = entry.get("trigger").and_then(serde_json::Value::as_str) else {
        return false;
    };
    let known_pair = KIRO_CLI_V3_EVENTS.iter().any(|(expected_trigger, script)| {
        *expected_trigger == trigger
            && script
                .strip_suffix(".sh")
                .is_some_and(|stem| name == format!("ai-memory-{stem}"))
    });
    known_pair
        && entry
            .pointer("/action/type")
            .and_then(serde_json::Value::as_str)
            == Some("command")
        && entry
            .pointer("/action/command")
            .and_then(serde_json::Value::as_str)
            .is_some_and(is_ai_memory_kiro_hook_command)
}

/// Every `*.json` agent config in the Kiro CLI global agents directory,
/// sorted for deterministic apply order. A missing directory is an empty
/// list, not an error — the caller decides how to report it.
pub(crate) fn list_kiro_cli_agent_configs(dir: &Path) -> Result<Vec<PathBuf>> {
    let entries = match fs::read_dir(dir) {
        Ok(entries) => entries,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(error) => {
            return Err(error).with_context(|| format!("reading {}", dir.display()));
        }
    };
    let mut configs = Vec::new();
    for entry in entries {
        let entry = entry.with_context(|| format!("reading entry in {}", dir.display()))?;
        let path = entry.path();
        let metadata = fs::metadata(&path)
            .with_context(|| format!("reading metadata for {}", path.display()))?;
        if metadata.is_file() && path.extension().and_then(|e| e.to_str()) == Some("json") {
            configs.push(path);
        }
    }
    configs.sort();
    Ok(configs)
}

pub(crate) fn is_ai_memory_kiro_hook_command(command: &str) -> bool {
    let lower = command.to_ascii_lowercase();
    let generated_script =
        lower.contains("/hooks/kiro-cli/") || lower.contains("\\hooks\\kiro-cli\\");
    let ai_memory_executable = lower.contains("ai-memory") || lower.contains("ai_memory");
    let native_hook = ai_memory_executable
        && lower.contains(" hook ")
        && lower.contains("--agent kiro-cli")
        && lower.contains("--server-url");
    (generated_script || native_hook)
        && KIRO_CLI_V2_EVENTS.iter().any(|(_, script)| {
            let stem = script.trim_end_matches(".sh");
            lower.contains(script)
                || lower.contains(&format!("{stem}.ps1"))
                || lower.contains(&format!("--event {stem}"))
        })
}

/// Generate an OpenCode plugin at `~/.config/opencode/plugins/ai-memory.ts`.
///
/// OpenCode's integration surface is a TypeScript plugin, not a JSON
/// hook table. The plugin posts normalized lifecycle payloads directly
/// to `/hook` and injects pending handoffs through
/// `experimental.chat.system.transform`, because plugin shell stdout is
/// not prepended to the model context the way Claude Code hook stdout is.
fn apply_to_opencode_plugin(
    server_url: &str,
    auth_token: Option<&str>,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => opencode_plugin_path()?,
    };
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let body = build_opencode_plugin(server_url, auth_token, strategy, capture_mode);

    let outcome = apply_atomic(&path, move |_existing| Ok(body.clone()))?;
    remove_incompatible_opencode_plugin(&path, AgentChoice::OpenCode)?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new plugin file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    if !matches!(outcome, ApplyOutcome::NoOp) {
        println!();
        println!("OpenCode auto-loads plugins from ~/.config/opencode/plugins/ on next start.");
        println!("If you're already inside an `opencode` session, restart it for the");
        println!("new plugin to take effect.");
    }
    Ok(())
}

fn opencode_plugin_content_is_owned(content: &str, agent: AgentChoice) -> bool {
    match agent {
        AgentChoice::OpenCode => {
            content.starts_with(
                "// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.",
            ) && content.contains("const AGENT = \"open-code\";")
        }
        AgentChoice::OpenCode2 => {
            content.starts_with(
                "// Auto-generated by `ai-memory install-hooks --agent opencode2 --apply`.",
            ) && content.contains("const AGENT = \"opencode2\";")
        }
        _ => false,
    }
}

fn remove_incompatible_opencode_plugin(path: &Path, installed: AgentChoice) -> Result<()> {
    remove_incompatible_opencode_plugin_with(path, installed, |_| Ok(()))
}

fn remove_incompatible_opencode_plugin_with(
    path: &Path,
    installed: AgentChoice,
    after_quarantine: impl FnOnce(&Path) -> Result<()>,
) -> Result<()> {
    let (installed_name, sibling_name) = match installed {
        AgentChoice::OpenCode => ("ai-memory.ts", "ai-memory-opencode2.ts"),
        AgentChoice::OpenCode2 => ("ai-memory-opencode2.ts", "ai-memory.ts"),
        _ => return Ok(()),
    };
    if path.file_name().and_then(|name| name.to_str()) != Some(installed_name) {
        return Ok(());
    }
    let Some(parent) = path.parent() else {
        return Ok(());
    };
    let sibling = parent.join(sibling_name);
    let incompatible = match installed {
        AgentChoice::OpenCode => AgentChoice::OpenCode2,
        AgentChoice::OpenCode2 => AgentChoice::OpenCode,
        _ => return Ok(()),
    };
    if sibling == path || !sibling.exists() {
        return Ok(());
    }
    let quarantine = parent.join(format!(
        ".ai-memory-opencode-quarantine-{}",
        uuid::Uuid::new_v4().simple()
    ));
    fs::rename(&sibling, &quarantine).with_context(|| {
        format!(
            "quarantining incompatible plugin {} before ownership verification",
            sibling.display()
        )
    })?;
    if let Err(error) = after_quarantine(&sibling) {
        restore_quarantined_opencode_plugin(&quarantine, &sibling)?;
        return Err(error);
    }
    let content = fs::read_to_string(&quarantine);
    if content
        .as_deref()
        .is_ok_and(|content| opencode_plugin_content_is_owned(content, incompatible))
    {
        fs::remove_file(&quarantine).with_context(|| {
            format!(
                "removing quarantined generated plugin {}",
                quarantine.display()
            )
        })?;
        println!(
            "✓ removed incompatible generated plugin {}",
            sibling.display()
        );
        return Ok(());
    }
    restore_quarantined_opencode_plugin(&quarantine, &sibling)?;
    Ok(())
}

fn restore_quarantined_opencode_plugin(quarantine: &Path, sibling: &Path) -> Result<()> {
    restore_quarantined_opencode_plugin_with(quarantine, sibling, || Ok(()))
}

fn restore_quarantined_opencode_plugin_with(
    quarantine: &Path,
    sibling: &Path,
    before_restore: impl FnOnce() -> Result<()>,
) -> Result<()> {
    match fs::symlink_metadata(sibling) {
        Ok(_) => {
            warn_opencode_plugin_restore_conflict(quarantine, sibling);
            return Ok(());
        }
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
        Err(error) => {
            return Err(error).with_context(|| {
                format!(
                    "checking {} before restoring user plugin; original preserved at {}",
                    sibling.display(),
                    quarantine.display()
                )
            });
        }
    }
    before_restore()?;
    match fs::hard_link(quarantine, sibling) {
        Ok(()) => fs::remove_file(quarantine).with_context(|| {
            format!(
                "restored user plugin {} but could not remove its quarantine {}; both copies were preserved",
                sibling.display(),
                quarantine.display()
            )
        }),
        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
            warn_opencode_plugin_restore_conflict(quarantine, sibling);
            Ok(())
        }
        Err(error) => Err(error).with_context(|| {
            format!(
                "restoring user plugin {} without replacing concurrent content; original preserved at {}",
                sibling.display(),
                quarantine.display()
            )
        }),
    }
}

fn warn_opencode_plugin_restore_conflict(quarantine: &Path, sibling: &Path) {
    eprintln!(
        "[ai-memory] warning: {} changed during cleanup; preserved both it and the quarantined prior file {}",
        sibling.display(),
        quarantine.display()
    );
}

fn render_opencode_plugin(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
) -> Result<()> {
    println!("// OpenCode plugin — write to ~/.config/opencode/plugins/ai-memory.ts");
    println!("// Or re-run with `--apply` to install it automatically.");
    println!("// Restart OpenCode after changing plugins; config is loaded at startup.");
    println!();
    println!(
        "{}",
        build_opencode_plugin(server_url, auth_token, project_strategy, capture_mode)
    );
    Ok(())
}

/// `~/.config/opencode/plugins/ai-memory-opencode2.ts` — the OpenCode 2.0
/// beta plugin file. The beta shares v1's config dir and session store but
/// not its plugin API, so this is a distinct file from `ai-memory.ts`
/// (uninstall keys each file to its own banner + agent constant).
pub(crate) fn opencode2_plugin_path() -> anyhow::Result<std::path::PathBuf> {
    Ok(home_dir()
        .context("could not locate $HOME for ~/.config/opencode")?
        .join(".config")
        .join("opencode")
        .join("plugins")
        .join("ai-memory-opencode2.ts"))
}

/// Generate an OpenCode V2 plugin at
/// `~/.config/opencode/plugins/ai-memory-opencode2.ts`.
///
/// The V2 plugin API (`{ id, setup }` with `ctx.session.hook` /
/// `ctx.tool.hook` / `ctx.event.subscribe`) is incompatible with V1's function
/// plugin, so V2 gets its own file. After a successful canonical write, an
/// incompatible sibling is removed only when its exact ai-memory ownership
/// markers match.
fn apply_to_opencode2_plugin(
    server_url: &str,
    auth_token: Option<&str>,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => opencode2_plugin_path()?,
    };
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let body = build_opencode2_plugin(
        server_url,
        auth_token,
        strategy,
        capture_mode,
        args.capture_assistant,
    )?;

    let outcome = apply_atomic(&path, move |_existing| Ok(body.clone()))?;
    remove_incompatible_opencode_plugin(&path, AgentChoice::OpenCode2)?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new plugin file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    if !matches!(outcome, ApplyOutcome::NoOp) {
        println!();
        println!("OpenCode 2 auto-loads plugins from ~/.config/opencode/plugins/ on next start.");
        println!("If you're already inside an `opencode2` session, restart it for the");
        println!("new plugin to take effect.");
    }
    Ok(())
}

fn render_opencode2_plugin(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
    capture_assistant: bool,
) -> Result<()> {
    println!("// OpenCode V2 plugin — write to ~/.config/opencode/plugins/ai-memory-opencode2.ts");
    println!("// Or re-run with `--apply` to install it automatically.");
    println!("// Restart OpenCode V2 after changing plugins; config is loaded at startup.");
    println!();
    println!(
        "{}",
        build_opencode2_plugin(
            server_url,
            auth_token,
            project_strategy,
            capture_mode,
            capture_assistant
        )?
    );
    Ok(())
}

/// Build the beta plugin from the v1 template. The capture prelude (hook
/// queue + spooling, marker resolution, capture policy, session maps,
/// `/hook` + `/handoff` helpers) is host-independent and reused verbatim;
/// only the host binding is rewritten for the V2 API. Anchors are plain
/// rendered-TS constants like the spool patch's: a template edit that moves
/// them fails loudly here instead of shipping a half-v1 plugin.
fn build_opencode2_plugin(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
    capture_assistant: bool,
) -> Result<String> {
    let v1 = build_opencode_plugin(server_url, auth_token, project_strategy, capture_mode);
    const BANNER_V1: &str =
        "// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.";
    const BANNER_V2: &str =
        "// Auto-generated by `ai-memory install-hooks --agent opencode2 --apply`.";
    const AGENT_V1: &str = "const AGENT = \"open-code\";";
    const AGENT_V2: &str = "const AGENT = \"opencode2\";";
    // Start of the v1 host binding through end of file. Everything before
    // this line (including the spooled delivery path) is shared.
    const V1_BINDING_ANCHOR: &str =
        "\nexport const AiMemoryHooks: Plugin = async ({ directory }) => {";
    // `replacen` silently keeps the v1 text when its anchor moves, which
    // would ship a half-v1 plugin — fail loudly instead, like the spool
    // patch's anchors do.
    let out = replace_opencode_anchor(&v1, BANNER_V1, BANNER_V2, "banner")?;
    let out = replace_opencode_anchor(&out, AGENT_V1, AGENT_V2, "agent constant")?;
    let Some(binding_at) = out.find(V1_BINDING_ANCHOR) else {
        anyhow::bail!("opencode2 template drifted: v1 host binding anchor not found");
    };
    let prelude = &out[..binding_at];
    let (imports, state) = prelude
        .split_once("const SERVER =")
        .context("missing OpenCode capture prelude")?;
    let rebuilt = replace_opencode_anchor(
        imports,
        "import type { Plugin } from \"@opencode-ai/plugin\";",
        "import type { Plugin } from \"@opencode/plugin\";",
        "plugin import",
    )?;
    let mut rebuilt = replace_opencode_anchor(
        &rebuilt,
        "import { execFileSync } from \"node:child_process\";",
        "import { execFileSync, spawn } from \"node:child_process\";",
        "child_process import",
    )?;
    rebuilt.push_str("import { randomBytes } from \"node:crypto\";\n");
    rebuilt.push_str("const AiMemoryOpencode2: Plugin.Plugin = {\n  id: \"ai-memory-opencode2\",\n  setup: async (ctx) => {\n");
    // Only the assistant-capture opt-in bakes this host's executable path;
    // without it the generated file stays portable between machines. Bake the
    // path as invoked, like every other native hook config: a canonicalized
    // one pins the target behind a versioned symlink or junction.
    let native_hook = if capture_assistant {
        let exe = hook_embedded_exe_path();
        ts_string_literal(&strip_windows_verbatim_prefix(&exe.to_string_lossy()))
    } else {
        "undefined".to_string()
    };
    rebuilt.push_str(&format!(
        "const CAPTURE_ASSISTANT = {capture_assistant};\nconst NATIVE_HOOK: string | undefined = {native_hook};\n"
    ));
    rebuilt.push_str(&format!(
        "const NATIVE_PROJECT_STRATEGY: string | undefined = {};\n",
        project_strategy
            .map(ts_string_literal)
            .unwrap_or_else(|| "undefined".to_string())
    ));
    // A module is shared by location graphs; queues and session ownership are not.
    rebuilt.push_str("const SERVER =");
    // Cache an empty successful response, but retry an unavailable server on a
    // later context hook. The v1 helper historically conflated both outcomes.
    let state = replace_opencode_anchor(
        state,
        "return text.length > 0 ? text : undefined;",
        "return text;",
        "handoff result",
    )?;
    // Mint at event creation, not only on failure: move events must remain
    // idempotent when an acknowledged delivery is later replayed from disk.
    let state = replace_opencode_anchor(
        &state,
        "url.searchParams.set(\"event\", event);\n  url.searchParams.set(\"agent\", AGENT);",
        "url.searchParams.set(\"event\", event);\n  url.searchParams.set(\"agent\", AGENT);\n  url.searchParams.set(\"ingest_key\", randomBytes(16).toString(\"hex\"));",
        "hook ingest key",
    )?;
    rebuilt.push_str(&state);
    rebuilt.push_str(OPENCODE2_BINDING);
    Ok(rebuilt)
}

fn replace_opencode_anchor(haystack: &str, from: &str, to: &str, what: &str) -> Result<String> {
    if haystack.matches(from).count() != 1 {
        anyhow::bail!("opencode2 template drifted: v1 {what} anchor not found exactly once");
    }
    Ok(haystack.replacen(from, to, 1))
}

/// V2 host binding for the shared capture prelude, written against
/// `@opencode/[email protected]`; every event it handles is still emitted by
/// OpenCode 2.0.14. Lifecycle envelopes carry `{ type, data, location }`.
/// Handoff injection moved from v1's removed
/// `experimental.chat.system.transform` to the `context` hook, which edits
/// the outgoing model call without persisting into history — guarded to
/// claim once per session and retain the result on every model continuation.
const OPENCODE2_BINDING: &str = r#"
    const directory = ctx.location.directory;
    type SessionID = Parameters<typeof ctx.session.get>[0]["sessionID"];
    type SessionInfo = Awaited<ReturnType<typeof ctx.session.get>>;
    const sessions = new Map<SessionID, Promise<SessionInfo>>();
    const assistantText = new Map<SessionID, string>();
    // Stops listening on unload. Deliveries keep `hookAbort` until the queued
    // events have had their drain budget.
    const unload = new AbortController();

    async function sessionInfo(id: SessionID): Promise<SessionInfo> {
      let pending = sessions.get(id);
      if (!pending) {
        pending = ctx.session.get({ sessionID: id }, { signal: unload.signal });
        sessions.set(id, pending);
        pending.catch(() => sessions.delete(id));
      }
      return pending;
    }

    // `agent_id` marks a subagent session (#755); a root session has none.
    function subagentMarker(session: SessionInfo | undefined): { agent_id?: SessionID } {
      return session?.parentID ? { agent_id: session.parentID } : {};
    }

    function hookPayload(id: SessionID, session: SessionInfo) {
      return { sessionID: id, cwd: session.location.directory, ...subagentMarker(session) };
    }

    function forgetSession(id: SessionID): void {
      sessions.delete(id);
      assistantText.delete(id);
      handoffFetches.delete(id);
    }

    async function ensureSession(id: SessionID): Promise<SessionInfo | undefined> {
      const session = await sessionInfo(id);
      // The public event stream can reach multiple loaded location plugins.
      // Hooks and cleanup belong exclusively to the current location owner.
      if (session.location.directory !== directory) {
        sessions.delete(id);
        return undefined;
      }
      startSession(id, session.location.directory, { title: session.title, ...subagentMarker(session) });
      return session;
    }

    // Assistant text uses the native privacy boundary before it can reach disk
    // or the wire. Only the explicit client/server double opt-in enables it.
    async function postStop(id: SessionID): Promise<void> {
      const session = await ensureSession(id);
      if (!session) return;
      const text = assistantText.get(id);
      assistantText.delete(id);
      const payload = { ...hookPayload(id, session), turn_checkpoint: !session.parentID };
      if (!NATIVE_HOOK || !text) {
        postHook("stop", payload);
        return;
      }
      await requestHookDrain();
      if (unload.signal.aborted) return;
      await new Promise<void>((resolve) => {
        const args = ["--data-dir", dirname(hookSpoolDir()), "hook", "--agent", AGENT,
          "--event", "stop", "--server-url", SERVER, "--capture-assistant",
          "--capture-mode", CAPTURE_MODE];
        if (NATIVE_PROJECT_STRATEGY) args.push("--project-strategy", NATIVE_PROJECT_STRATEGY);
        const child = spawn(NATIVE_HOOK, args, {
          stdio: ["pipe", "ignore", "pipe"],
          windowsHide: true,
          env: { ...process.env, AI_MEMORY_AUTH_TOKEN: resolveToken() ?? "" },
          timeout: 5000,
          signal: unload.signal,
        });
        child.stderr.resume();
        child.stdin.on("error", () => {});
        child.on("error", (error) => {
          if (unload.signal.aborted) return resolve();
          // The hook never ran (moved or missing binary): keep the turn's
          // Stop and checkpoint, without the assistant text.
          console.warn("ai-memory assistant capture failed", error.message);
          postHook("stop", payload);
          resolve();
        });
        child.on("close", (code) => {
          if (code !== 0 && !unload.signal.aborted) console.warn("ai-memory assistant capture exited", code);
          resolve();
        });
        child.stdin.end(JSON.stringify({ ...payload, last_assistant_message: text }));
      });
    }

    const eventTask = (async () => {
      try {
        for await (const event of ctx.event.subscribe({ signal: unload.signal })) {
          try {
            if (event.type === "session.created") {
              await ensureSession(event.data.sessionID);
            } else if (event.type === "session.text.ended" && CAPTURE_ASSISTANT) {
              if (!(await ensureSession(event.data.sessionID))) continue;
              // Bound in-memory buffering too; the native hook owns sanitizing
              // and the smaller stored excerpt limit.
              if (Buffer.byteLength(event.data.text, "utf8") <= 65536) {
                assistantText.set(event.data.sessionID, event.data.text);
              } else {
                assistantText.delete(event.data.sessionID);
              }
            } else if (event.type === "session.execution.succeeded" ||
                       event.type === "session.execution.failed" ||
                       event.type === "session.execution.interrupted") {
              await postStop(event.data.sessionID);
            } else if (event.type === "session.deleted") {
              const id = event.data.sessionID;
              const session = await sessions.get(id)?.catch(() => undefined);
              endSession(id, directory, undefined, subagentMarker(session));
              forgetSession(id);
            } else if (event.type === "session.moved") {
              const id = event.data.sessionID;
              const previousCwd = sessionCwds.get(id);
              const previous = await sessions.get(id)?.catch(() => undefined);
              // Only the old owner emits the explicit transition. Replayed
              // moves keep their ingest key, and stale ordinary events cannot
              // silently rebind a live session in the store.
              if (previousCwd === directory && event.data.location.directory !== previousCwd) {
                postHook("session-start", {
                  sessionID: id,
                  cwd: event.data.location.directory,
                  session_moved: true,
                  session_moved_from_cwd: previousCwd,
                  ...subagentMarker(previous),
                });
              }
              forgetSession(id);
              startedSessions.delete(id);
              sessionCwds.delete(id);
            } else if (event.type === "session.compaction.started") {
              recapFetches.delete(event.data.sessionID);
              const session = await ensureSession(event.data.sessionID);
              if (!session) continue;
              postPreCompact(event.data.sessionID, session.location.directory);
            }
          } catch (error) {
            if (!unload.signal.aborted) console.warn("ai-memory event capture failed", error);
          }
        }
      } catch (error) {
        if (!unload.signal.aborted) console.warn("ai-memory event stream failed", error);
      }
    })();
    const promptRegistration = await ctx.session.hook("prompt", async (event) => {
      const session = await ensureSession(event.sessionID);
      if (!session) return;
      assistantText.delete(event.sessionID);
      postHook("user-prompt", {
        ...hookPayload(event.sessionID, session),
        messageID: event.messageID,
        prompt: event.prompt.text,
      });
      if (!session.parentID && RELOAD_TRIGGER.test(event.prompt.text)) {
        recapFetches.set(event.sessionID, fetchRecap(session.location.directory, event.sessionID));
      }
    });
    const contextRegistration = await ctx.session.hook("context", async (event) => {
      const id = event.sessionID;
      const session = await ensureSession(id);
      if (!session || session.parentID) return;
      let pending = handoffFetches.get(id);
      if (!pending) {
        // The handoff endpoint establishes scope directly. Do not wait for an
        // offline capture backlog on the model's request path.
        pending = fetchHandoff(session.location.directory, id);
        handoffFetches.set(id, pending);
      }
      const handoff = await pending;
      if (handoff === undefined) handoffFetches.delete(id);
      if (handoff) {
        event.system.push({ type: "text", text: handoff });
      }
      const recap = await recapFetches.get(id);
      if (recap) {
        event.system.push({ type: "text", text: recap });
      }
    });
    const beforeRegistration = await ctx.tool.hook("execute.before", async (event) => {
      const session = await ensureSession(event.sessionID);
      if (!session) return;
      postHook("pre-tool-use", {
        ...hookPayload(event.sessionID, session),
        tool: event.tool,
        callID: event.id,
        args: event.input,
      });
    });
    const afterRegistration = await ctx.tool.hook("execute.after", async (event) => {
      const session = await ensureSession(event.sessionID);
      if (!session) return;
      postHook("post-tool-use", {
        ...hookPayload(event.sessionID, session),
        tool: event.tool,
        callID: event.id,
        args: event.input,
        output: event.status === "error" ? event.error.message
          : event.result.content ?? event.result.output,
        metadata: event.status === "error" ? undefined : event.result.metadata,
      });
    });
    return async () => {
      unload.abort();
      await Promise.race([eventTask, disposeDrainTimeout()]);
      for (const registration of [
        promptRegistration,
        contextRegistration,
        beforeRegistration,
        afterRegistration,
      ]) {
        try {
          await registration.dispose();
        } catch (_e) {
          // Unload is best-effort; a dead host has nothing to unregister.
        }
      }
      // Dispose is an unload, not a shutdown: OpenCode evicts idle location
      // services and reloads this plugin while its sessions stay alive, so
      // ending them here would freeze live sessions (a later SessionStart
      // cannot reopen an ended session) and fabricate a baton and summary
      // page per eviction (#1074). Real ends arrive as `session.deleted`, and
      // each completed root turn already published its checkpoint and baton.
      await drainHookQueueForDispose();
      // Whatever is still in flight after the budget fails over to the spool.
      hookAbort.abort();
    };
  },
};

export default AiMemoryOpencode2;
"#;
/// `findSettingsMarker` mirrors the native `find_settings_marker` (`marker.rs`)
/// and the shell `ai_memory_find_settings_marker` (`hooks/_lib.sh`), #668:
/// the same ancestor walk and HOME/`.git` boundary as `findMarker`, but a
/// marker that declares nothing beyond `[capture]` is transparent — the walk
/// skips it and continues to the next ancestor. That keeps a nested
/// capture-only marker (e.g. one that only sets `ignore_paths`) from
/// shadowing an outer marker's `workspace`/`project`/etc, without changing
/// `[capture]`/`ignore_paths` resolution itself (that stays on `findMarker`,
/// the nearest marker, in the separate capture-policy template). The
/// boundary walk is duplicated from `findMarker` rather than shared, on
/// purpose: `findMarker` stays untouched, well-exercised, nearest-marker
/// behavior for every other caller.
pub(crate) const TS_FIND_SETTINGS_MARKER: &str = r#"function declaresSettings(text: string): boolean {
  for (const key of ["workspace", "project", "project_strategy", "drop_subagent_captures", "identity", "identity_style"]) {
    if (tomlKey(text, key) !== undefined) return true;
  }
  if (/^\s*aliases\s*=/m.test(text)) return true;
  if (/^\s*server\s*=/m.test(text)) return true;
  for (const key of ["default_global", "inject_on_session_start", "inject_on_subagent_start", "max_chars", "contribute", "consume", "deliver_on_session_start"]) {
    if (tomlFlag(text, key) !== undefined) return true;
  }
  return false;
}

function findSettingsMarker(cwd: string | undefined): string | undefined {
  if (!cwd) return undefined;
  let dir = resolve(cwd);
  const home = homedir();
  let boundary: string | undefined;
  if (home && (dir === home || dir.startsWith(home.endsWith(sep) ? home : home + sep))) {
    boundary = home;
  } else if (home) {
    let probe = dir;
    while (probe && probe !== dirname(probe)) {
      if (existsSync(join(probe, ".git"))) {
        boundary = probe;
        break;
      }
      probe = dirname(probe);
    }
    boundary ??= dir;
  }
  while (dir && dir !== dirname(dir)) {
    const marker = join(dir, ".ai-memory.toml");
    if (existsSync(marker)) {
      try {
        const text = marker === join(home, ".ai-memory.toml")
          ? readHomeRouteText(marker)
          : readFileSync(marker, "utf8");
        if (declaresSettings(text)) return marker;
      } catch (_e) {
        return marker;
      }
    }
    if (boundary && dir === boundary) return undefined;
    dir = dirname(dir);
  }
  return undefined;
}"#;

/// Emit the `applyMarkerParams` TypeScript function shared by generated
/// integrations.
///
/// An install-time default applies only when no marker pins a
/// `project_strategy` (#128). A marker's explicit `project` or `identity` and
/// operator-home routing keep precedence; otherwise a valid remote supplies its
/// canonical path name even when `repo-root` is configured. `repoRootProject`
/// handles the host-side fallback only when no valid remote exists.
///
/// Scope/settings resolution walks past a capture-only marker to the nearest
/// ancestor marker that declares a setting (#668) via `findSettingsMarker`,
/// emitted alongside this function. `discover_local_identity` controls whether
/// an ordinary local marker may inspect git identity; aliases still request it,
/// and operator-home routes always discover identity for route matching.
pub(crate) fn ts_apply_marker_params(
    default_strategy: Option<&str>,
    discover_local_identity: bool,
) -> String {
    let default_line = default_strategy.map_or_else(String::new, |default| {
        format!(
            "const DEFAULT_PROJECT_STRATEGY = {};\n",
            ts_string_literal(default)
        )
    });
    let apply_default = default_strategy.map_or(
        "",
        |_| "if (!projectStrategy) projectStrategy = DEFAULT_PROJECT_STRATEGY;",
    );
    let apply_identity = if discover_local_identity {
        "const remoteIdentity = applyIdentityParams(url, cwd, explicitIdentity, project, identityStyle, aliases);"
    } else {
        "const remoteIdentity = aliases ? applyIdentityParams(url, cwd, undefined, project, identityStyle, aliases) : false;"
    };
    let body = r#"function applyMarkerParams(url: URL, cwd: string | undefined): boolean {
  const managedRun = process.env.AI_MEMORY_RUN_ID;
  if (managedRun) url.searchParams.set("managed_run", managedRun);
  if (!cwd) return true;
  url.searchParams.set("cwd", cwd);
  let workspace: string | undefined;
  let project: string | undefined;
  let projectStrategy: string | undefined;
  let dropSubagent: string | undefined;
  let defaultGlobal: string | undefined;
  let briefing: string | undefined;
  let briefingBudget: string | undefined;
  let profileContribute: string | undefined;
  let profileConsume: string | undefined;
  let handoffOff = false;
  let explicitIdentity: string | undefined;
  let identityStyle: string | undefined;
  let aliases: string | undefined;
  let projectSource: "marker" | "repo-root" | undefined;
  let routed = false;
  let marker = findSettingsMarker(cwd);
  if (!marker || marker === join(homedir(), ".ai-memory.toml")) {
    const homeMarker = join(homedir(), ".ai-memory.toml");
    if (existsSync(homeMarker)) {
      try {
        const body = readHomeRouteText(homeMarker);
        const routeIdentity = discoverRemoteIdentity(cwd);
        const route = homeRoute(body, cwd, routeIdentity);
        dropSubagent = tomlKey(body, "drop_subagent_captures");
        defaultGlobal = tomlFlag(body, "default_global");
        briefing = tomlFlag(body, "inject_on_session_start");
        briefingBudget = tomlFlag(body, "max_chars");
        profileContribute = profileFlag(tomlFlag(body, "contribute"));
        profileConsume = profileFlag(tomlFlag(body, "consume"));
        handoffOff = profileFlag(tomlFlag(body, "deliver_on_session_start")) === "0";
        if (route) {
          routed = true;
          workspace = route.workspace;
          project = route.project;
          projectSource = "marker";
          identityStyle = route.style;
          aliases = routeIdentity ? route.aliases : undefined;
          if (routeIdentity) {
            url.searchParams.set("identity", routeIdentity);
            url.searchParams.set("identity_src", "git_remote");
            url.searchParams.set("identity_style", identityStyleParam(identityStyle));
          }
          marker = undefined;
        } else marker = homeMarker;
      } catch (_e) {
        return false;
      }
    }
  }
  if (marker) {
    try {
      const body = readFileSync(marker, "utf8");
      workspace = tomlKey(body, "workspace");
      project = tomlKey(body, "project");
      if (project) projectSource = "marker";
      projectStrategy = tomlKey(body, "project_strategy");
      dropSubagent = tomlKey(body, "drop_subagent_captures");
      defaultGlobal = tomlFlag(body, "default_global");
      briefing = tomlFlag(body, "inject_on_session_start");
      briefingBudget = tomlFlag(body, "max_chars");
      profileContribute = profileFlag(tomlFlag(body, "contribute"));
      profileConsume = profileFlag(tomlFlag(body, "consume"));
      handoffOff = profileFlag(tomlFlag(body, "deliver_on_session_start")) === "0";
      explicitIdentity = tomlKey(body, "identity");
      identityStyle = tomlKey(body, "identity_style");
      aliases = markerAliases(body);
    } catch (_e) {
      return false;
    }
  }
  if (!routed) {
    __APPLY_IDENTITY__
    if (aliases) url.searchParams.set("aliases", project && remoteIdentity ? aliases : "invalid");
  } else if (aliases) {
    url.searchParams.set("aliases", aliases);
  }
  __DEFAULT_LINE__
  if (!project && (projectStrategy === "repo-root" || projectStrategy === "repo_root")) {
    const repoProject = repoRootProject(cwd);
    if (repoProject) {
      project = repoProject;
      projectSource = "repo-root";
    }
  }
  if (workspace) url.searchParams.set("workspace", workspace);
  if (project) url.searchParams.set("project", project);
  if (projectSource) url.searchParams.set("project_src", projectSource);
  if (projectStrategy) url.searchParams.set("project_strategy", projectStrategy);
  if (dropSubagent) url.searchParams.set("drop_subagent", dropSubagent);
  if (defaultGlobal) url.searchParams.set("default_global", defaultGlobal);
  if (briefing) url.searchParams.set("briefing", briefing);
  if (briefingBudget) url.searchParams.set("briefing_budget", briefingBudget);
  if (profileContribute) url.searchParams.set("profile_contribute", profileContribute);
  if (profileConsume) url.searchParams.set("profile_consume", profileConsume);
  if (handoffOff) url.searchParams.set("handoff", "0");
  return true;
}"#
    .replace("__DEFAULT_LINE__", apply_default)
    .replace("__APPLY_IDENTITY__", apply_identity);
    format!(
        "{default_line}{TS_TOML_FLAG}\n{TS_FIND_SETTINGS_MARKER}\n{TS_IDENTITY}\n{TS_HOME_ROUTES}\n{body}"
    )
}

/// Repository identity for the TypeScript plugins (#708): a port of
/// `normalize_remote_url` in `ai-memory-core::repository_identity`, checked
/// against the shared `fixtures/remote_identity_cases.json`, and
/// `applyIdentityParams`, which mirrors `repository_identity` in
/// `hook_capture.rs` — an explicit marker `identity` is sent; a declared
/// `project` outranks the remote and routes by name, so git is not consulted;
/// otherwise the `upstream` remote, else `origin`. Normalising here keeps
/// credentials embedded in a remote URL on the host.
pub(crate) const TS_IDENTITY: &str = r#"function markerAliases(text: string): string | undefined {
  let inTable = false;
  const declarations: string[] = [];
  for (const line of text.split(/\r?\n/)) {
    const trimmed = line.trim();
    if (trimmed.startsWith("[")) inTable = true;
    if (/^aliases\s*=/.test(trimmed)) {
      if (inTable) return "invalid";
      declarations.push(trimmed);
    }
  }
  if (declarations.length === 0) return undefined;
  if (declarations.length !== 1) return "invalid";
  const match = /^aliases\s*=\s*\[([^\]]*)\]\s*$/.exec(declarations[0]);
  if (!match) return "invalid";
  const aliases: string[] = [];
  if (!match[1].trim()) return undefined;
  const parts = match[1].split(",");
  if (parts.length > 16) return "invalid";
  for (const raw of parts) {
    if (raw.includes("\\")) return "invalid";
    const item = /^\s*"([^"]*)"\s*$/.exec(raw);
    if (!item) return "invalid";
    const alias = item[1].trim();
    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(alias) || Buffer.byteLength(alias, "utf8") > 128) return "invalid";
    if (!aliases.includes(alias)) {
      aliases.push(alias);
    }
  }
  return JSON.stringify(aliases);
}

function normalizeRemote(raw: string): string | undefined {
  const trimmed = raw.trim();
  if (!trimmed) return undefined;
  let scheme: string | undefined;
  let rest = trimmed;
  const idx = trimmed.indexOf("://");
  if (idx >= 0) {
    scheme = trimmed.slice(0, idx).toLowerCase();
    rest = trimmed.slice(idx + 3);
  }
  if (scheme === "file") return undefined;
  let pathStart = rest.indexOf("/");
  if (pathStart < 0) pathStart = rest.length;
  const at = rest.slice(0, pathStart).lastIndexOf("@");
  const hp = at >= 0 ? rest.slice(at + 1) : rest;
  let host: string;
  let path: string;
  if (scheme !== undefined) {
    const slash = hp.indexOf("/");
    host = slash >= 0 ? hp.slice(0, slash) : hp;
    path = slash >= 0 ? hp.slice(slash + 1) : "";
    const colon = host.lastIndexOf(":");
    if (colon >= 0 && /^[0-9]*$/.test(host.slice(colon + 1))) host = host.slice(0, colon);
    if (!host || !path) return undefined;
  } else {
    const colon = hp.indexOf(":");
    if (colon < 0) return undefined;
    const slash = hp.indexOf("/");
    if (slash >= 0 && slash < colon) return undefined;
    host = hp.slice(0, colon);
    path = hp.slice(colon + 1);
    if (host.length <= 1 || !path) return undefined;
    if (path.includes("\\")) return undefined;
  }
  let id = `${host}/${path}`.toLowerCase().replace(/\/+$/, "");
  if (id.endsWith(".git")) id = id.slice(0, -4);
  id = id.replace(/\/+$/, "").replace(/\/\/+/g, "/");
  return id && id.includes("/") ? id : undefined;
}

function identityStyleParam(style: string | undefined): "path" | "host_path" {
  return style?.trim() === "host_path" ? "host_path" : "path";
}

function discoverRemoteIdentity(cwd: string | undefined): string | undefined {
  if (!cwd) return undefined;
  for (const name of ["upstream", "origin"]) {
    try {
      const remote = execFileSync("git", ["-C", cwd, "config", "--get", `remote.${name}.url`], {
        encoding: "utf8",
        stdio: ["ignore", "pipe", "ignore"],
        windowsHide: true,
      });
      const identity = normalizeRemote(remote);
      if (identity) return identity;
    } catch (_e) {
    }
  }
  return undefined;
}

function validNormalizedIdentity(value: string): boolean {
  const host = value.split("/", 1)[0];
  return /^[a-z0-9.-]+(?:\/[a-z0-9._-]+)+$/.test(value) && value === value.toLowerCase() && !host.startsWith(".") && !host.endsWith(".");
}

function applyIdentityParams(
  url: URL,
  cwd: string | undefined,
  explicit: string | undefined,
  project: string | undefined,
  style: string | undefined,
  aliases: string | undefined,
): boolean {
  const declared = explicit?.trim();
  if (!aliases && declared) {
    url.searchParams.set("identity", declared.toLowerCase());
    url.searchParams.set("identity_src", "explicit");
    return false;
  }
  if ((project?.trim() && !aliases) || !cwd) return false;
  const identity = discoverRemoteIdentity(cwd);
  if (identity) {
    url.searchParams.set("identity", identity);
    url.searchParams.set("identity_src", "git_remote");
    url.searchParams.set("identity_style", identityStyleParam(style));
    return true;
  }
  return false;
}"#;

/// `tomlFlag` mirrors the native hook's `parse_toml_flag`: unlike `tomlKey`
/// (quoted strings only) it also accepts a bare token (`default_global =
/// true`, `max_chars = 4000`), so section-style marker keys work whether or
/// not the operator quotes the value. Emitted next to `applyMarkerParams`
/// in every generated TypeScript integration.
pub(crate) const TS_HOME_ROUTES: &str = r##"type HomeRoute = { workspace: string; project: string; style?: string; aliases?: string };
type RoutePath = { root: string; parts: string[] };

function readHomeRouteText(file: string): string {
  const expected = statSync(file).size;
  if (expected > 65536) throw new Error("invalid home routes");
  const fd = openSync(file, "r");
  try {
    const bytes = Buffer.allocUnsafe(expected + 1);
    let count = 0;
    while (count < bytes.length) {
      const read = readSync(fd, bytes, count, bytes.length - count, count);
      if (read === 0) break;
      count += read;
    }
    if (count !== expected || count > 65536 || statSync(file).size !== expected) throw new Error("invalid home routes");
    return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, count));
  } finally {
    closeSync(fd);
  }
}

function routePathParts(raw: string, home: string, bounded = true): RoutePath | undefined {
  if (!raw || (bounded && Buffer.byteLength(raw, "utf8") > 512)) return undefined;
  const homeRelative = raw.startsWith("~/");
  if (homeRelative) {
    let depth = 0;
    for (const part of raw.slice(2).replace(/\\/g, "/").split("/")) {
      if (!part || part === ".") continue;
      if (part === "..") { if (depth === 0) return undefined; depth--; } else depth++;
    }
  }
  let value = homeRelative ? home.replace(/[\\/]+$/, "") + "/" + raw.slice(2) : raw;
  value = value.replace(/\\/g, "/");
  let root = "";
  let rest = "";
  if (value.startsWith("//")) {
    const parts = value.slice(2).split("/").filter(Boolean);
    if (parts.length < 2) return undefined;
    root = `unc:${parts.shift()!.toLowerCase()}/${parts.shift()!.toLowerCase()}`;
    rest = parts.join("/");
  } else if (/^[A-Za-z]:\//.test(value)) {
    root = `drive:${value[0].toLowerCase()}`;
    rest = value.slice(3);
  } else if (value.startsWith("/")) {
    root = "posix";
    rest = value.slice(1);
  } else return undefined;
  const parts: string[] = [];
  for (const part of rest.split("/")) {
    if (!part || part === ".") continue;
    if (part === "..") parts.pop(); else parts.push(root === "posix" ? part : part.toLowerCase());
  }
  return parts.length ? { root, parts } : undefined;
}

function homeRoute(text: string, cwd: string, identity: string | undefined): HomeRoute | undefined {
  if (Buffer.byteLength(text, "utf8") > 65536) throw new Error("invalid home routes");
  if (!/^\s*(?:\[routes|routes\s*=|routes\.|route_)/m.test(text)) return undefined;
  const entries: Array<{ kind: string; selector: string; fields: Record<string, string> }> = [];
  const rawSeen = new Set<string>();
  let current: typeof entries[number] | undefined;
  for (const line of text.split(/\r?\n/)) {
    const trimmed = line.trim();
    const header = /^\[routes\.(identity|path)\."([^"\\]+)"\]$/.exec(trimmed);
    if (header) {
      if (entries.length >= 64 || Buffer.byteLength(header[2], "utf8") > 512 || rawSeen.has(header[2])) throw new Error("invalid home routes");
      rawSeen.add(header[2]);
      current = { kind: header[1], selector: header[2], fields: {} };
      entries.push(current);
      continue;
    }
    if (trimmed.startsWith("[routes") || trimmed.startsWith("routes.") || /^routes\s*=/.test(trimmed) || (!current && trimmed.startsWith("route_"))) throw new Error("invalid home routes");
    if (trimmed.startsWith("[")) { current = undefined; continue; }
    if (!current) {
      if (/^(workspace|project|project_strategy|drop_subagent_captures|identity|identity_style|server)\s*=/.test(trimmed) && !/^[A-Za-z0-9_]+\s*=\s*"[^"]*"$/.test(trimmed)) throw new Error("invalid home routes");
      continue;
    }
    if (!trimmed || trimmed.startsWith("#")) continue;
    const field = /^(route_workspace|route_project|route_identity_style|route_aliases)\s*=\s*(.*)$/.exec(trimmed);
    if (!field || current.fields[field[1]] !== undefined || field[2].includes("\\")) throw new Error("invalid home routes");
    current.fields[field[1]] = field[2];
  }
  const parsed: Array<{ kind: string; selector: string; route: HomeRoute; path?: RoutePath }> = [];
  const normalizedPaths = new Set<string>();
  for (const entry of entries) {
    const str = (name: string) => {
      const value = /^"([^"\\]+)"$/.exec(entry.fields[name] ?? "")?.[1];
      return value && Buffer.byteLength(value, "utf8") <= 512 ? value : undefined;
    };
    const workspace = str("route_workspace");
    const project = str("route_project");
    if (!workspace || !project || Buffer.byteLength(workspace, "utf8") > 512 || Buffer.byteLength(project, "utf8") > 512 || !/^[a-z0-9][a-z0-9._-]*$/.test(workspace) || !/^[a-z0-9][a-z0-9._-]*$/.test(project)) throw new Error("invalid home routes");
    const style = entry.fields.route_identity_style === undefined ? undefined : str("route_identity_style");
    if (style !== undefined && style !== "path" && style !== "host_path") throw new Error("invalid home routes");
    let aliases: string | undefined;
    if (entry.fields.route_aliases !== undefined) {
      if (!/^\[[^\]]*\]$/.test(entry.fields.route_aliases) || Buffer.byteLength(entry.fields.route_aliases, "utf8") > 512) throw new Error("invalid home routes");
      aliases = markerAliases(`aliases = ${entry.fields.route_aliases}`);
      if (aliases === "invalid") throw new Error("invalid home routes");
    }
    if (entry.kind === "identity" && !validNormalizedIdentity(entry.selector)) throw new Error("invalid home routes");
    const path = entry.kind === "path" ? routePathParts(entry.selector, homedir()) : undefined;
    if (entry.kind === "path") {
      if (!path) throw new Error("invalid home routes");
      const key = `${path.root}/${path.parts.join("/")}`;
      if (normalizedPaths.has(key)) throw new Error("invalid home routes");
      normalizedPaths.add(key);
    }
    parsed.push({ kind: entry.kind, selector: entry.selector, route: { workspace, project, style, aliases }, path });
  }
  const exact = parsed.find((entry) => entry.kind === "identity" && entry.selector === identity);
  if (exact) return exact.route;
  const target = routePathParts(cwd, homedir(), false);
  if (!target) return undefined;
  const matches = parsed.filter((entry) => entry.kind === "path" && entry.path?.root === target.root && entry.path.parts.length <= target.parts.length && entry.path.parts.every((part, index) => part === target.parts[index]));
  matches.sort((a, b) => b.path!.parts.length - a.path!.parts.length);
  return matches[0]?.route;
}"##;

pub(crate) const TS_TOML_FLAG: &str = r#"function tomlFlag(text: string, key: string): string | undefined {
  const re = new RegExp(`^\\s*${key}\\s*=\\s*(?:"([^"]*)"|([^#\\s]+))`);
  for (const line of text.split(/\r?\n/)) {
    const match = re.exec(line);
    if (match) return match[1] ?? match[2];
  }
  return undefined;
}
// A resolved marker's `[profile]` flag as the explicit value the hook sends:
// "0" for a falsy value, "1" for anything else, an absent key included.
// Parity with `profile_flag_value` in hook_capture.rs.
function profileFlag(value: string | undefined): string {
  return value !== undefined && ["0", "false", "no", "off"].includes(value.trim().toLowerCase()) ? "0" : "1";
}"#;

/// `repoRootProject`, shared by every generated TypeScript integration: the
/// project is named after the git repository that owns `cwd` (the main
/// checkout, so linked worktrees share it).
///
/// `applyMarkerParams` calls it on every captured event, and two synchronous
/// git spawns cost tens of milliseconds of host event loop each time, so the
/// answer is memoized per `cwd` for as long as the generated state lives: the
/// host process for the module-level integrations, one `setup()` instance for
/// OpenCode 2. A miss (not a repo, git absent) is cached too; a directory
/// that becomes a repo later resolves after the plugin reloads.
///
/// `windowsHide` keeps each spawn from flashing a console window when the
/// host has none (OpenCode 2 runs plugins in a console-less background
/// service), the TS counterpart of the native drain's `CREATE_NO_WINDOW`.
pub(crate) const TS_REPO_ROOT_PROJECT: &str = r#"const repoProjectCache = new Map<string, string | undefined>();

function repoRootProject(cwd: string | undefined): string | undefined {
  if (!cwd) return undefined;
  if (repoProjectCache.has(cwd)) return repoProjectCache.get(cwd);
  const project = gitRepoProject(cwd);
  repoProjectCache.set(cwd, project);
  return project;
}

function gitRepoProject(cwd: string): string | undefined {
  try {
    const inside = execFileSync("git", ["-C", cwd, "rev-parse", "--is-inside-work-tree"], {
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
      windowsHide: true,
    }).trim();
    if (inside !== "true") return undefined;
    const common = execFileSync("git", ["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], {
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
      windowsHide: true,
    }).trim();
    if (!common) return undefined;
    const root = dirname(common);
    if (!root || root === dirname(root)) return undefined;
    return basename(root);
  } catch (_e) {
    return undefined;
  }
}"#;

/// Post-process a generated TypeScript integration so failed hook
/// deliveries SPOOL instead of vanishing (#580). The shell hooks have
/// spooled since day one; the TS plugins fire-and-forgot, so a laptop
/// off the server's network lost whole sessions of capture. Entries are
/// written in the CLI spool's exact on-disk contract
/// (`{ms:013}-{pid}-{seq:016x}.json`, `SpoolEntry` fields, 0700 dir /
/// 0600 files, tmp+rename) so `ai-memory hook-drain` and the shell
/// hooks' piggyback drain deliver them too; the plugin also drains its
/// own spool on first use and after any queue flush. An `ingest_key`
/// is minted at spool time, so a double drain (plugin + CLI) dedupes
/// server-side instead of double-ingesting.
///
/// Implemented as a transformation over the rendered source (rather
/// than another copy of the template) so all TS integrations share one
/// audited implementation; it fails loudly if the delivery block it
/// patches ever drifts.
fn add_hook_spooling(source: String) -> Result<String> {
    const FETCH_BLOCK: &str = r#"      try {
        await fetch(item.url, {
          proxy: false,
          method: "POST",
          headers: { "Content-Type": "application/json", ...authHeaders() },
          body: JSON.stringify(item.payload),
          signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS),
        }).catch(() => undefined);
      } catch (_e) {
        // Best-effort capture. Hooks must never block the agent.
      }"#;
    const FETCH_REPLACEMENT: &str = r#"      try {
        const resp = await fetch(item.url, {
          proxy: false,
          redirect: "error",
          method: "POST",
          headers: { "Content-Type": "application/json", ...authHeaders() },
          body: JSON.stringify(item.payload),
          signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS),
        }).catch(() => undefined);
        // Unreachable server, 5xx or a transient 4xx (408, 425, 429): keep the
        // event on disk for a later drain (#580). Any other 4xx is permanent -
        // spooling it would retry a rejection forever. A redirect rejects
        // above and spools too: following it would count a gateway's login
        // page as a delivery, and a 307 would replay the event to that host.
        if (!resp || hookStatusRetryable(resp.status)) spoolFailedHook(item.url, item.payload);
      } catch (_e) {
        try { spoolFailedHook(item.url, item.payload); } catch (_e2) {}
      }"#;
    const ENQUEUE_ANCHOR: &str = "function enqueueHook(";
    let runtime = crate::commands::render_shared::ts_spool_runtime();
    let resolve_fn = crate::commands::render_shared::ts_resolve_token_fn();
    if !source.contains(FETCH_BLOCK) {
        anyhow::bail!(
            "TS integration template drifted: the hook delivery block the \
             spool patch targets was not found"
        );
    }
    if source.matches(ENQUEUE_ANCHOR).count() != 1 {
        anyhow::bail!("TS integration template drifted: enqueueHook anchor not unique");
    }
    let mut out = source.replacen(FETCH_BLOCK, FETCH_REPLACEMENT, 1);
    out = out.replacen(
        ENQUEUE_ANCHOR,
        &format!("{resolve_fn}{runtime}{ENQUEUE_ANCHOR}"),
        1,
    );
    // Drain the offline spool alongside every queue flush, and extend the
    // imports the runtime needs.
    let drain_anchor =
        "async function drainHookQueue(): Promise<void> {\n  if (hookDraining) return;";
    if out.matches(drain_anchor).count() != 1 {
        anyhow::bail!("TS integration template drifted: drainHookQueue anchor not unique");
    }
    out = out.replacen(
        drain_anchor,
        "async function drainHookQueue(): Promise<void> {\n  if (hookDraining) return;\n  requestSpoolDrain();",
        1,
    );
    let import_anchor = "import { closeSync, existsSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, statSync } from \"node:fs\";";
    if out.matches(import_anchor).count() != 1 {
        anyhow::bail!("TS integration template drifted: node:fs import anchor not unique");
    }
    out = out.replacen(
        import_anchor,
        "import { closeSync, existsSync, mkdirSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from \"node:fs\";",
        1,
    );
    Ok(out)
}

fn build_opencode_plugin(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
) -> String {
    let token_line = auth_token
        .map(|t| format!("const TOKEN: string | null = {};\n", ts_string_literal(t)))
        .unwrap_or_else(|| "const TOKEN: string | null = null;\n".to_string());
    let apply_marker_params = ts_apply_marker_params(project_strategy, true);
    let capture_policy = ts_capture_policy_v1(capture_mode);
    let timeout_signal = ts_timeout_signal();
    let auth_headers = ts_auth_headers_fn();
    let body = format!(
        r#"// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.
// Edit by re-running the command, not by hand — install-hooks
// will overwrite this file (with a `.bak-<ts>` backup) on each
// re-run.

import type {{ Plugin }} from "@opencode-ai/plugin";
import {{ execFileSync }} from "node:child_process";
import {{ closeSync, existsSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, statSync }} from "node:fs";
import {{ basename, dirname, join, resolve, sep }} from "node:path";
import {{ homedir }} from "node:os";

const SERVER = {server_literal}.replace(/\/+$/, "");
const AGENT = "open-code";
{token_line}
{capture_policy}

{timeout_signal}
{auth_headers}
const HOOK_QUEUE_MAX = 100;
const HOOK_FLUSH_INTERVAL_MS = 2000;
const HOOK_FLUSH_THRESHOLD = 20;
const HOOK_INTER_REQUEST_DELAY_MS = 50;
const HOOK_REQUEST_TIMEOUT_MS = 2000;
const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;
const HOOK_IMMEDIATE_EVENTS = new Set(["session-start", "stop", "session-end", "pre-compact"]);

type HookQueueItem = {{ event: string; url: URL; payload: Record<string, unknown> }};
const hookQueue: HookQueueItem[] = [];
let hookFlushTimer: ReturnType<typeof setTimeout> | undefined;
let hookDraining = false;
let hookDrainPromise: Promise<void> | undefined;

function sleep(ms: number): Promise<void> {{
  return new Promise((resolve) => setTimeout(resolve, ms));
}}

function scheduleHookFlush(): void {{
  if (hookFlushTimer) return;
  hookFlushTimer = setTimeout(() => {{
    hookFlushTimer = undefined;
    void requestHookDrain();
  }}, HOOK_FLUSH_INTERVAL_MS);
  hookFlushTimer.unref?.();
}}

function requestHookDrain(): Promise<void> {{
  if (!hookDrainPromise) {{
    hookDrainPromise = drainHookQueue().finally(() => {{
      hookDrainPromise = undefined;
      if (hookQueue.length > 0) void requestHookDrain();
    }});
  }}
  return hookDrainPromise;
}}

function disposeDrainTimeout(): Promise<void> {{
  return new Promise((resolve) => {{
    const timer = setTimeout(resolve, HOOK_DISPOSE_DRAIN_BUDGET_MS);
    timer.unref?.();
  }});
}}

async function drainHookQueueForDispose(): Promise<void> {{
  await Promise.race([requestHookDrain(), disposeDrainTimeout()]);
}}

function enqueueHook(event: string, url: URL, payload: Record<string, unknown>): void {{
  if (hookQueue.length >= HOOK_QUEUE_MAX) hookQueue.shift();
  hookQueue.push({{ event, url, payload }});
  if (HOOK_IMMEDIATE_EVENTS.has(event) || hookQueue.length >= HOOK_FLUSH_THRESHOLD) {{
    void requestHookDrain();
  }} else {{
    scheduleHookFlush();
  }}
}}

async function drainHookQueue(): Promise<void> {{
  if (hookDraining) return;
  hookDraining = true;
  if (hookFlushTimer) {{
    clearTimeout(hookFlushTimer);
    hookFlushTimer = undefined;
  }}
  try {{
    while (hookQueue.length > 0) {{
      const item = hookQueue.shift();
      if (!item) break;
      try {{
        await fetch(item.url, {{
          proxy: false,
          method: "POST",
          headers: {{ "Content-Type": "application/json", ...authHeaders() }},
          body: JSON.stringify(item.payload),
          signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS),
        }}).catch(() => undefined);
      }} catch (_e) {{
        // Best-effort capture. Hooks must never block the agent.
      }}
      if (hookQueue.length > 0 && !hookAbort.signal.aborted) await sleep(HOOK_INTER_REQUEST_DELAY_MS);
    }}
  }} finally {{
    hookDraining = false;
  }}
}}

function findMarker(cwd: string | undefined): string | undefined {{
  if (!cwd) return undefined;
  let dir = resolve(cwd);
  const home = homedir();
  let boundary: string | undefined;
  if (home && (dir === home || dir.startsWith(home.endsWith(sep) ? home : home + sep))) {{
    boundary = home;
  }} else if (home) {{
    let probe = dir;
    while (probe && probe !== dirname(probe)) {{
      if (existsSync(join(probe, ".git"))) {{
        boundary = probe;
        break;
      }}
      probe = dirname(probe);
    }}
    boundary ??= dir;
  }}
  while (dir && dir !== dirname(dir)) {{
    const marker = join(dir, ".ai-memory.toml");
    if (existsSync(marker)) return marker;
    if (boundary && dir === boundary) return undefined;
    dir = dirname(dir);
  }}
  return undefined;
}}

function tomlKey(text: string, key: string): string | undefined {{
  const re = new RegExp(`^\\s*${{key}}\\s*=\\s*"([^"]*)"`);
  for (const line of text.split(/\r?\n/)) {{
    const match = re.exec(line);
    if (match) return match[1];
  }}
  return undefined;
}}


{TS_REPO_ROOT_PROJECT}
{apply_marker_params}

function sessionID(input: unknown): string | undefined {{
  const value = input as any;
  return value?.sessionID ?? value?.sessionId ?? value?.session_id ?? value?.info?.id;
}}

function textFromParts(parts: unknown): string {{
  if (!Array.isArray(parts)) return "";
  return parts
    .map((part: any) => {{
      if (part?.type === "text" && typeof part.text === "string") return part.text;
      if (part?.type === "subtask" && typeof part.prompt === "string") return part.prompt;
      if (part?.type === "file" && typeof part.filename === "string") return `[file: ${{part.filename}}]`;
      return "";
    }})
    .filter(Boolean)
    .join("\n\n")
    .trim();
}}

const sessionCwds = new Map<string, string>();
const startedSessions = new Set<string>();
// A subagent session's parent, from the session info OpenCode publishes.
const sessionParents = new Map<string, string>();
const handoffFetches = new Map<string, Promise<string | undefined>>();
// "reload context": the session's compaction recap, kept until its next
// compaction like the handoff it sits beside.
const RELOAD_TRIGGER = {reload_trigger};
const recapFetches = new Map<string, Promise<string | undefined>>();
const preCompactLast = new Map<string, number>();

function cwdFor(id: string | undefined, directory: string): string {{
  return (id && sessionCwds.get(id)) || directory;
}}

function rememberCwd(id: string | undefined, cwd: string | undefined): void {{
  if (id && cwd) sessionCwds.set(id, cwd);
}}

function rememberParent(id: string | undefined, parentID: unknown): void {{
  // A root session has no parentID; only a real string marks a child (#755).
  if (id && typeof parentID === "string" && parentID) sessionParents.set(id, parentID);
}}

function startSession(id: string | undefined, cwd: string, extra: Record<string, unknown> = {{}}): void {{
  if (!id || startedSessions.has(id)) return;
  startedSessions.add(id);
  rememberCwd(id, cwd);
  // Generated integrations inject through fetchHandoff below. In managed mode
  // a queued SessionStart response is not model-visible and must not consume
  // the workstream context before that synchronous fetch receives it.
  if (!process.env.AI_MEMORY_RUN_ID) {{
    postHook("session-start", {{ sessionID: id, cwd, ...extra }});
  }}
}}

function endSession(id: string | undefined, directory: string, cwd?: string, extra: Record<string, unknown> = {{}}): void {{
  if (!id || !startedSessions.delete(id)) return;
  const resolvedCwd = cwd || cwdFor(id, directory);
  // Every close path marks a subagent's end, the dispose at exit included:
  // an unmarked end leaves the next session a sub-task baton (#755).
  const parent = sessionParents.get(id);
  postHook("session-end", {{ sessionID: id, cwd: resolvedCwd, ...(parent ? {{ agent_id: parent }} : {{}}), ...extra }});
  sessionCwds.delete(id);
  sessionParents.delete(id);
  handoffFetches.delete(id);
  recapFetches.delete(id);
  preCompactLast.delete(id);
}}

function postPreCompact(id: string | undefined, directory: string): void {{
  startSession(id, cwdFor(id, directory));
  const key = id || "unknown";
  const now = Date.now();
  const last = preCompactLast.get(key) ?? 0;
  if (now - last < 1000) return;
  preCompactLast.set(key, now);
  postHook("pre-compact", {{ sessionID: id, cwd: cwdFor(id, directory) }});
}}

function postHook(event: string, payload: Record<string, unknown>): void {{
  const url = new URL(`${{SERVER}}/hook`);
  url.searchParams.set("event", event);
  url.searchParams.set("agent", AGENT);
  if (!applyMarkerParams(url, typeof payload.cwd === "string" ? payload.cwd : undefined)) return;
  const policy = capturePolicy(payload, typeof payload.cwd === "string" ? payload.cwd : undefined);
  if (policy.disposition === "drop") return;
  try {{
    enqueueHook(event, url, policy.payload);
  }} catch (_e) {{
    // Best-effort capture. Hooks must never block the agent.
  }}
}}

async function fetchHandoff(cwd: string, id: string | undefined): Promise<string | undefined> {{
  // The GET claims the newest open handoff in whatever project the server
  // resolves; with no directory that is its default or last active project,
  // so another repository's baton could be consumed. Leave it open instead.
  if (!cwd) return undefined;
  if (captureServerRouted(cwd)) return undefined;
  // An allowlist build captures only marked repositories, and the native hook
  // returns before its handoff GET for any other (`hook.rs`). Do the same: the
  // server resolves the directory into a project to look the baton up, so a
  // request from an unmarked one leaves an empty project behind.
  if (CAPTURE_MODE === "allowlist" && !findMarker(cwd)) return undefined;
  const url = new URL(`${{SERVER}}/handoff`);
  url.searchParams.set("agent", AGENT);
  url.searchParams.set("cwd", cwd);
  if (id) url.searchParams.set("session_id", id);
  if (!applyMarkerParams(url, cwd)) return undefined;
  try {{
    // The body goes into the system prompt, so a redirect is refused: a
    // gateway's login page must never arrive as the handoff.
    const response = await fetch(url, {{
      proxy: false,
      redirect: "error",
      headers: authHeaders(),
      signal: timeoutSignal(1000),
    }});
    if (!response.ok) return undefined;
    const text = (await response.text()).trim();
    return text.length > 0 ? text : undefined;
  }} catch (_e) {{
    return undefined;
  }}
}}

async function fetchRecap(cwd: string, id: string): Promise<string | undefined> {{
  if (captureServerRouted(cwd)) return undefined;
  // Same rule as the handoff fetch: no request for a repository an allowlist
  // build does not capture.
  if (CAPTURE_MODE === "allowlist" && !findMarker(cwd)) return undefined;
  const url = new URL(`${{SERVER}}/recap`);
  url.searchParams.set("agent", AGENT);
  url.searchParams.set("session_id", id);
  if (!applyMarkerParams(url, cwd)) return undefined;
  try {{
    const response = await fetch(url, {{
      proxy: false,
      redirect: "error",
      headers: authHeaders(),
      signal: timeoutSignal(1000),
    }});
    if (!response.ok) return undefined;
    const recap = (await response.text()).trim();
    return recap || undefined;
  }} catch (_e) {{
    return undefined;
  }}
}}

export const AiMemoryHooks: Plugin = async ({{ directory }}) => {{
  return {{
    dispose: async () => {{
      for (const id of Array.from(startedSessions)) {{
        endSession(id, directory);
      }}
      await drainHookQueueForDispose();
    }},
    event: async (input) => {{
      const event = (input as any).event;
      const properties = event?.properties ?? {{}};
      if (event?.type === "session.created") {{
        const info = properties.info ?? {{}};
        const id = properties.sessionID ?? info.id;
        const cwd = info.directory ?? directory;
        // A `task` subagent runs in a child session created with its
        // parent's id (OpenCode `tool/task.ts`).
        rememberParent(id, info.parentID);
        startSession(id, cwd, {{
          title: info.title,
          projectID: info.projectID,
          // A subagent session carries a parentID; forward it as the `agent_id`
          // subagent marker so `drop_subagent_captures` can recognize (and drop)
          // OpenCode subagent sessions too (#755). A root session has no
          // parentID — never mark it, or every session looks like a subagent.
          ...(typeof info.parentID === "string" && info.parentID
            ? {{ agent_id: info.parentID }}
            : {{}}),
        }});
      }}
      if (event?.type === "session.updated") {{
        // A child the task tool resumes by `task_id` in a later process has no
        // `session.created` here, but every prompt publishes `session.updated`
        // before its model call (OpenCode `session/prompt.ts`).
        const info = properties.info ?? {{}};
        rememberParent(properties.sessionID ?? info.id, info.parentID);
      }}
      if (event?.type === "session.idle") {{
        const id = properties.sessionID;
        startSession(id, cwdFor(id, directory));
        postHook("stop", {{ sessionID: id, cwd: cwdFor(id, directory) }});
      }}
      if (event?.type === "session.deleted") {{
        const info = properties.info ?? {{}};
        const id = properties.sessionID ?? info.id;
        // The marker has to ride the end event too: the router refuses to hand
        // a baton to the next session only when a child session's `session-end`
        // identifies itself, and it reads the top-level key alone (#755).
        endSession(id, directory, info.directory, typeof info.parentID === "string" && info.parentID
          ? {{ agent_id: info.parentID }}
          : {{}});
      }}
      if (event?.type === "session.compacted") {{
        const id = properties.sessionID;
        postPreCompact(id, directory);
        if (id) recapFetches.delete(id);
      }}
    }},
    "chat.message": async (input, output) => {{
      const id = sessionID(input);
      const cwd = cwdFor(id, directory);
      startSession(id, cwd, {{ agent: (input as any).agent, model: (input as any).model }});
      postHook("user-prompt", {{
        sessionID: id,
        cwd,
        agent: (input as any).agent,
        model: (input as any).model,
        messageID: (input as any).messageID,
        prompt: textFromParts((output as any).parts),
      }});
      const prompt = textFromParts((output as any).parts);
      if (id && RELOAD_TRIGGER.test(prompt)) recapFetches.set(id, fetchRecap(cwd, id));
    }},
    "tool.execute.before": async (input, output) => {{
      const id = sessionID(input);
      startSession(id, cwdFor(id, directory));
      postHook("pre-tool-use", {{
        sessionID: id,
        cwd: cwdFor(id, directory),
        tool: (input as any).tool,
        callID: (input as any).callID,
        args: (output as any).args,
      }});
    }},
    "tool.execute.after": async (input, output) => {{
      const id = sessionID(input);
      startSession(id, cwdFor(id, directory));
      postHook("post-tool-use", {{
        sessionID: id,
        cwd: cwdFor(id, directory),
        tool: (input as any).tool,
        callID: (input as any).callID,
        args: (input as any).args,
        title: (output as any).title,
        output: (output as any).output,
        metadata: (output as any).metadata,
      }});
    }},
    "experimental.session.compacting": async (input) => {{
      const id = sessionID(input);
      postPreCompact(id, directory);
      if (id) recapFetches.delete(id);
    }},
    "experimental.chat.system.transform": async (input, output) => {{
      const id = sessionID(input);
      if (!id) return;
      startSession(id, cwdFor(id, directory));
      // A subagent must not claim the handoff waiting for the user's next
      // session. The OpenCode 2 `context` hook skips a child session the same way.
      if (sessionParents.has(id)) return;
      let pending = handoffFetches.get(id);
      if (!pending) {{
        pending = fetchHandoff(cwdFor(id, directory), id);
        handoffFetches.set(id, pending);
      }}
      const handoff = await pending;
      if (handoff) (output as any).system.push(handoff);
      const recap = await recapFetches.get(id);
      if (recap) (output as any).system.push(recap);
    }},
  }};
}};

export default AiMemoryHooks;
"#,
        server_literal = ts_string_literal(server_url),
        token_line = token_line,
        reload_trigger = ai_memory_core::compaction_recap::RELOAD_TRIGGER_JS_REGEX,
    );
    // Anchors are compile-time constants over this same file's template;
    // a mismatch is a template edit that forgot the spool patch.
    add_hook_spooling(body).expect("generated TS integration lost its hook-spool anchors")
}

/// The extensions directory Pi and OMP would share, when `this_agent`'s
/// extension at `this_path` sits beside the other agent's under `env`.
///
/// Agent-distinct filenames stop the two installs from overwriting each
/// other, but they do not make sharing a directory safe. OMP discovers
/// **every** direct `*.ts` under its extensions directory, so with both
/// files present each agent loads both extensions, and since the Pi
/// extension is the OMP one with `const AGENT` swapped, and neither guards
/// on its host, every lifecycle event is captured twice under two different
/// agent identities.
///
/// That is not a regression this installer can fix by itself: both agents
/// honour the same `PI_CODING_AGENT_DIR`, so the collision is upstream. What
/// it can do is refuse to be silent about it, and name the two ways out.
/// `env` is a parameter because `ai-memory run` resolves the other agent
/// through its launch environment, not ai-memory's own.
pub(crate) fn shared_extensions_dir(
    this_agent: AgentChoice,
    this_path: &Path,
    env: &dyn Fn(&str) -> Option<std::ffi::OsString>,
) -> Option<PathBuf> {
    let other = match this_agent {
        AgentChoice::Pi => AgentChoice::Omp,
        AgentChoice::Omp => AgentChoice::Pi,
        _ => return None,
    };
    let other_path = hook_config_target_with(other, env).ok()?;
    let dir = this_path.parent()?;
    (other_path.parent() == Some(dir)).then(|| dir.to_path_buf())
}

/// Print the Pi/OMP double-capture warning for `dir`; see
/// [`shared_extensions_dir`].
pub(crate) fn warn_agents_share_extensions_dir(dir: &Path) {
    eprintln!(
        "warning: Pi and OMP both resolve to {}, an agent dir they share\n\
         \x20 (PI_CODING_AGENT_DIR, or OMP's PI_CONFIG_DIR).\n\
         \x20 Each agent loads every *.ts in that directory, so installing both\n\
         \x20 captures each event twice, once as `pi` and once as `omp`.\n\
         \x20 Give them separate homes, or move OMP to a named profile, which\n\
         \x20 ignores PI_CODING_AGENT_DIR (OMP_PROFILE=<name>, or `--profile <name>`\n\
         \x20 on both `omp` and `ai-memory install-hooks --agent omp`).",
        dir.display()
    );
}

fn warn_if_agents_share_extensions_dir(this_agent: AgentChoice, this_path: &Path) {
    if let Some(dir) = shared_extensions_dir(this_agent, this_path, &|name| std::env::var_os(name))
    {
        warn_agents_share_extensions_dir(&dir);
    }
}

/// Remove a pre-rename `ai-memory.ts` sitting beside the new agent-distinct
/// file, so the agent does not load both.
///
/// **Only removes a file this tool generated.** `uninstall` gates every
/// delete behind `generated_file_is_ours`, and `removal.rs` asserts that a
/// user-owned file which merely happens to be named `ai-memory.ts` survives
/// (`uninstall_omp_extension_deletes_only_generated_file`). An unconditional
/// delete here would let `install-hooks --apply` destroy exactly what
/// `uninstall` refuses to touch — a worse outcome than the stale file,
/// because it is silent and hits a path the operator did not ask to modify.
///
/// The marker is the generated banner plus the agent constant, matching the
/// pair `generated_file_is_ours` checks.
///
/// `agent` scopes the match to the caller's own agent. Pi and OMP can share
/// one extensions directory (both honour `PI_CODING_AGENT_DIR`), and a
/// legacy `ai-memory.ts` there belongs to whichever installed last. Removing
/// the *other* agent's file would silently stop its capture until the
/// operator happened to reinstall it.
fn remove_legacy_extension(new_path: &Path, agent: &str) {
    let legacy = new_path.with_file_name("ai-memory.ts");
    if legacy == new_path || !legacy.exists() {
        return;
    }
    let Ok(content) = std::fs::read_to_string(&legacy) else {
        return;
    };
    let banner = format!("Auto-generated by `ai-memory install-hooks --agent {agent} --apply`");
    let agent_const = format!("const AGENT = \"{agent}\";");
    let ours = content.contains(&banner) && content.contains(&agent_const);
    if !ours {
        println!(
            "note: left {} in place — it was not generated by this agent's \
             installer. Remove it yourself if the agent should stop loading it.",
            legacy.display()
        );
        return;
    }
    match std::fs::remove_file(&legacy) {
        Ok(()) => println!("✓ Removed superseded extension {}", legacy.display()),
        Err(e) => eprintln!(
            "[ai-memory] warning: could not remove superseded extension {}: {e}",
            legacy.display()
        ),
    }
}

/// Generate an Oh My Pi extension at `<agent dir>/extensions/ai-memory-omp.ts`
/// (see [`omp_extension_path`]).
///
/// OMP discovers direct `*.ts` / `*.js` files under its agent dir's
/// `extensions/` at startup, so no separate settings merge is needed. The extension uses OMP's
/// lifecycle API for capture and `before_agent_start` for handoff injection.
fn apply_to_omp_extension(
    server_url: &str,
    auth_token: Option<&str>,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Result<()> {
    let path = resolve_omp_extension_path(args)?;
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let body = build_omp_extension(server_url, auth_token, strategy, capture_mode);

    let outcome = apply_atomic(&path, move |_existing| Ok(body.clone()))?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new extension file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );

    warn_if_agents_share_extensions_dir(AgentChoice::Omp, &path);
    remove_legacy_extension(&path, "omp");

    if !matches!(outcome, ApplyOutcome::NoOp) {
        println!();
        println!(
            "OMP auto-loads direct TypeScript extensions from {} on next start.",
            path.parent().unwrap_or(&path).display()
        );
        println!("If you're already inside an `omp` session, restart it for the");
        println!("new extension to take effect.");
    }
    Ok(())
}

/// Where `--apply` would write the OMP extension. Without a `$HOME` the hint
/// still names the layout, rooted at a literal `~`.
fn omp_extension_hint_with(
    profile: Option<&str>,
    env: &dyn Fn(&str) -> Option<std::ffi::OsString>,
) -> Result<String> {
    let home = home_dir().unwrap_or_else(|| PathBuf::from("~"));
    Ok(ai_memory_workstream::omp_agent_dir(&home, profile, env)?
        .join("extensions")
        .join("ai-memory-omp.ts")
        .display()
        .to_string())
}

/// Where `--apply` would write the Pi extension; see [`omp_extension_hint_with`].
fn pi_extension_hint_in(env_override: Option<std::ffi::OsString>) -> String {
    pi_extension_path_in(env_override).map_or_else(
        |_| "~/.pi/agent/extensions/ai-memory-pi.ts".to_string(),
        |p| p.display().to_string(),
    )
}

fn render_omp_extension(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    profile: Option<&str>,
    capture_mode: &str,
) -> Result<()> {
    println!(
        "// Oh My Pi / OMP extension — write to {}",
        omp_extension_hint_with(profile, &|name| std::env::var_os(name))?
    );
    println!("// Or re-run with `--apply` to install it automatically.");
    println!("// Restart OMP after changing extensions; config is loaded at startup.");
    println!();
    println!(
        "{}",
        build_omp_extension(server_url, auth_token, project_strategy, capture_mode)
    );
    Ok(())
}

fn resolve_omp_extension_path(args: &InstallHooksArgs) -> Result<PathBuf> {
    if let Some(p) = &args.config_file {
        return Ok(p.clone());
    }
    omp_extension_path(args.profile.as_deref())
}

fn apply_to_pi_extension(
    server_url: &str,
    auth_token: Option<&str>,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Result<()> {
    let path = resolve_pi_extension_path(args)?;
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let body = build_pi_extension(server_url, auth_token, strategy, capture_mode);

    let outcome = apply_atomic(&path, move |_existing| Ok(body.clone()))?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new Pi extension file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );

    warn_if_agents_share_extensions_dir(AgentChoice::Pi, &path);
    remove_legacy_extension(&path, "pi");

    if !matches!(outcome, ApplyOutcome::NoOp) {
        println!();
        println!("Pi loads TypeScript extensions from ~/.pi/agent/extensions/ on next start.");
        println!("Restart Pi for lifecycle capture and MCP tools to take effect.");
    }
    Ok(())
}

fn render_pi_extension(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
) -> Result<()> {
    println!(
        "// Pi extension — write to {}",
        pi_extension_hint_in(std::env::var_os("PI_CODING_AGENT_DIR"))
    );
    println!("// Or re-run with `--apply` to install it automatically.");
    println!("// Restart Pi after changing extensions; MCP tools are bridged by this file.");
    println!();
    println!(
        "{}",
        build_pi_extension(server_url, auth_token, project_strategy, capture_mode)
    );
    Ok(())
}

fn resolve_pi_extension_path(args: &InstallHooksArgs) -> Result<PathBuf> {
    if let Some(p) = &args.config_file {
        return Ok(p.clone());
    }
    pi_extension_path()
}

fn build_pi_extension(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
) -> String {
    let lifecycle = build_omp_extension(server_url, auth_token, project_strategy, capture_mode)
        .replace("install-hooks --agent omp --apply", "install-hooks --agent pi --apply")
        .replace("const AGENT = \"omp\";", "const AGENT = \"pi\";")
        .replace(
            r#"
  api.on("session.compacting", (_event: any, ctx: any) => {
    postPreCompact(ctx);
  });
"#,
            "\n",
        )
        .replace(
            "export default function AiMemoryExtension(api: any): void {",
            &format!(
                "{}\nexport default function AiMemoryExtension(pi: any): void {{\n  try {{ void bootstrapMcpBridge(pi); }} catch (_e) {{}}",
                pi_mcp_bridge_source()
            ),
        )
        .replace("api.on(\"", "pi.on(\"");
    debug_assert!(!lifecycle.contains(".omp"));
    lifecycle
}

fn pi_mcp_bridge_source() -> &'static str {
    r#"
// ---- MCP bridge ------------------------------------------------------------
// Pi forwards tool schemas to whichever provider it runs on, and Moonshot
// rejects any `$ref` (#1157). The moonshot dialect inlines every reference,
// which every provider accepts; it changes nothing but `tools/list`.
const MCP_SERVER = `${deriveMcpServer(SERVER)}?flavor=moonshot`;
const MCP_REQUEST_TIMEOUT_MS = 10000;
let mcpRequestId = 0;

function deriveMcpServer(server: string): string {
  const trimmed = server.replace(/\/+$/, "");
  return trimmed.endsWith("/mcp") ? trimmed : `${trimmed}/mcp`;
}

function mcpSessionId(ctx: any): string | undefined {
  const id = sessionID(ctx) ?? ctx?.sessionId ?? ctx?.sessionID ?? ctx?.session?.id;
  return typeof id === "string" && id.length > 0 ? id : undefined;
}

function mcpSignal(signal?: AbortSignal): AbortSignal | undefined {
  const timeout = timeoutSignal(MCP_REQUEST_TIMEOUT_MS);
  if (!signal) return timeout;
  if (!timeout) return signal;
  const anyFactory = (AbortSignal as unknown as { any?: (signals: AbortSignal[]) => AbortSignal }).any;
  return anyFactory ? anyFactory([signal, timeout]) : timeout;
}

function mcpHeaders(ctx?: any): Record<string, string> {
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    ...authHeaders(),
  };
  const session = mcpSessionId(ctx);
  if (session) {
    headers["X-Memory-Actor-Session-Id"] = session;
    headers["Mcp-Session-Id"] = session;
  }
  return headers;
}

async function mcpRpc(method: string, params?: unknown, ctx?: any, signal?: AbortSignal): Promise<any> {
  const id = ++mcpRequestId;
  // Like the hook client, the bridge never follows a redirect: a 307 or 308
  // would replay the request body and session headers to the redirect target.
  const response = await fetch(MCP_SERVER, {
    proxy: false,
    redirect: "error",
    method: "POST",
    headers: mcpHeaders(ctx),
    body: JSON.stringify({ jsonrpc: "2.0", id, method, params: params ?? {} }),
    signal: mcpSignal(signal),
  });
  if (!response.ok) throw new Error(`ai-memory MCP ${method} failed: HTTP ${response.status}`);
  const payload = await response.json();
  if (payload?.error) throw new Error(`ai-memory MCP ${method} failed: ${payload.error.message ?? JSON.stringify(payload.error)}`);
  if (payload?.result?.isError) throw new Error(`ai-memory MCP ${method} returned isError`);
  return payload?.result;
}

async function mcpNotify(method: string, params?: unknown, ctx?: any, signal?: AbortSignal): Promise<void> {
  const response = await fetch(MCP_SERVER, {
    proxy: false,
    redirect: "error",
    method: "POST",
    headers: mcpHeaders(ctx),
    body: JSON.stringify({ jsonrpc: "2.0", method, params: params ?? {} }),
    signal: mcpSignal(signal),
  });
  if (!response.ok) throw new Error(`ai-memory MCP notification ${method} failed: HTTP ${response.status}`);
}

function toolInputSchema(tool: any): any {
  return tool?.inputSchema ?? { type: "object", additionalProperties: true };
}

async function bootstrapMcpBridge(pi: any): Promise<void> {
  try {
    await mcpRpc("initialize", {
      protocolVersion: "2025-03-26",
      capabilities: {},
      clientInfo: { name: "ai-memory-pi-extension", version: "0.0.0" },
    });
    try { await mcpNotify("notifications/initialized"); } catch (_e) {}
    const listed = await mcpRpc("tools/list");
    for (const tool of listed?.tools ?? []) {
      try {
        pi.registerTool({
          name: tool.name,
          label: tool.name,
          description: tool.description,
          parameters: toolInputSchema(tool),
          execute: async (_toolCallId: string, params: unknown, signal?: AbortSignal, _onUpdate?: unknown, ctx?: any) => {
            const result = await mcpRpc("tools/call", { name: tool.name, arguments: params ?? {} }, ctx, signal);
            return { content: result?.content ?? [], details: result };
          },
        });
      } catch (_e) {
        // Duplicate registration or tool-shape mismatch must not break lifecycle capture.
      }
    }
  } catch (_e) {
    // MCP bridge is best-effort; extension load and lifecycle capture must survive.
  }
}
"#
}

fn build_omp_extension(
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    capture_mode: &str,
) -> String {
    let token_line = auth_token
        .map(|t| format!("const TOKEN: string | null = {};\n", ts_string_literal(t)))
        .unwrap_or_else(|| "const TOKEN: string | null = null;\n".to_string());
    let apply_marker_params = ts_apply_marker_params(project_strategy, true);
    let capture_policy = ts_capture_policy_v1(capture_mode);
    let timeout_signal = ts_timeout_signal();
    let auth_headers = ts_auth_headers_fn();
    let body = format!(
        r#"// Auto-generated by `ai-memory install-hooks --agent omp --apply`.
// Edit by re-running the command, not by hand — install-hooks
// will overwrite this file (with a `.bak-<ts>` backup) on each
// re-run.

import {{ execFileSync }} from "node:child_process";
import {{ closeSync, existsSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, statSync }} from "node:fs";
import {{ basename, dirname, join, resolve, sep }} from "node:path";
import {{ homedir }} from "node:os";

const SERVER = {server_literal}.replace(/\/+$/, "");
const AGENT = "omp";
{token_line}
{capture_policy}

{timeout_signal}
{auth_headers}
const HOOK_QUEUE_MAX = 100;
const HOOK_FLUSH_INTERVAL_MS = 2000;
const HOOK_FLUSH_THRESHOLD = 20;
const HOOK_INTER_REQUEST_DELAY_MS = 50;
const HOOK_REQUEST_TIMEOUT_MS = 2000;
const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;
const HOOK_IMMEDIATE_EVENTS = new Set(["session-start", "stop", "session-end", "pre-compact"]);

type HookQueueItem = {{ event: string; url: URL; payload: Record<string, unknown> }};
const hookQueue: HookQueueItem[] = [];
let hookFlushTimer: ReturnType<typeof setTimeout> | undefined;
let hookDraining = false;
let hookDrainPromise: Promise<void> | undefined;

function sleep(ms: number): Promise<void> {{
  return new Promise((resolve) => setTimeout(resolve, ms));
}}

function scheduleHookFlush(): void {{
  if (hookFlushTimer) return;
  hookFlushTimer = setTimeout(() => {{
    hookFlushTimer = undefined;
    void requestHookDrain();
  }}, HOOK_FLUSH_INTERVAL_MS);
  hookFlushTimer.unref?.();
}}

function requestHookDrain(): Promise<void> {{
  if (!hookDrainPromise) {{
    hookDrainPromise = drainHookQueue().finally(() => {{
      hookDrainPromise = undefined;
      if (hookQueue.length > 0) void requestHookDrain();
    }});
  }}
  return hookDrainPromise;
}}

function disposeDrainTimeout(): Promise<void> {{
  return new Promise((resolve) => {{
    const timer = setTimeout(resolve, HOOK_DISPOSE_DRAIN_BUDGET_MS);
    timer.unref?.();
  }});
}}

async function drainHookQueueForDispose(): Promise<void> {{
  await Promise.race([requestHookDrain(), disposeDrainTimeout()]);
}}

function enqueueHook(event: string, url: URL, payload: Record<string, unknown>): void {{
  if (hookQueue.length >= HOOK_QUEUE_MAX) hookQueue.shift();
  hookQueue.push({{ event, url, payload }});
  if (HOOK_IMMEDIATE_EVENTS.has(event) || hookQueue.length >= HOOK_FLUSH_THRESHOLD) {{
    void requestHookDrain();
  }} else {{
    scheduleHookFlush();
  }}
}}

async function drainHookQueue(): Promise<void> {{
  if (hookDraining) return;
  hookDraining = true;
  if (hookFlushTimer) {{
    clearTimeout(hookFlushTimer);
    hookFlushTimer = undefined;
  }}
  try {{
    while (hookQueue.length > 0) {{
      const item = hookQueue.shift();
      if (!item) break;
      try {{
        await fetch(item.url, {{
          proxy: false,
          method: "POST",
          headers: {{ "Content-Type": "application/json", ...authHeaders() }},
          body: JSON.stringify(item.payload),
          signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS),
        }}).catch(() => undefined);
      }} catch (_e) {{
        // Best-effort capture. Hooks must never block the agent.
      }}
      if (hookQueue.length > 0 && !hookAbort.signal.aborted) await sleep(HOOK_INTER_REQUEST_DELAY_MS);
    }}
  }} finally {{
    hookDraining = false;
  }}
}}

function findMarker(cwd: string | undefined): string | undefined {{
  if (!cwd) return undefined;
  let dir = resolve(cwd);
  const home = homedir();
  let boundary: string | undefined;
  if (home && (dir === home || dir.startsWith(home.endsWith(sep) ? home : home + sep))) {{
    boundary = home;
  }} else if (home) {{
    let probe = dir;
    while (probe && probe !== dirname(probe)) {{
      if (existsSync(join(probe, ".git"))) {{
        boundary = probe;
        break;
      }}
      probe = dirname(probe);
    }}
    boundary ??= dir;
  }}
  while (dir && dir !== dirname(dir)) {{
    const marker = join(dir, ".ai-memory.toml");
    if (existsSync(marker)) return marker;
    if (boundary && dir === boundary) return undefined;
    dir = dirname(dir);
  }}
  return undefined;
}}

function tomlKey(text: string, key: string): string | undefined {{
  const re = new RegExp(`^\\s*${{key}}\\s*=\\s*"([^"]*)"`);
  for (const line of text.split(/\r?\n/)) {{
    const match = re.exec(line);
    if (match) return match[1];
  }}
  return undefined;
}}


{TS_REPO_ROOT_PROJECT}
{apply_marker_params}

function sessionID(ctx: any): string | undefined {{
  const id = ctx?.sessionManager?.getSessionId?.();
  return typeof id === "string" && id.length > 0 ? id : undefined;
}}

// OMP rebinds this extension into every subagent session (task tool, eval
// `agent()`, `/tan` clones) and reports the agent a session runs as
// `ctx.agent`. An advisor's tool calls reach the session they advise with
// `kind: "sub"` under that session's id, so only a session's own lifecycle
// events record it. Pi reports no `ctx.agent`, so every Pi session stays
// top-level. https://github.com/can1357/oh-my-pi/blob/main/docs/extensions.md
const subagentSessions = new Map<string, string>();

function noteSubagent(ctx: any): void {{
  const id = sessionID(ctx);
  const agent = ctx?.agent;
  if (!id || agent?.kind !== "sub") return;
  subagentSessions.set(id, typeof agent.id === "string" && agent.id ? agent.id : "sub");
}}

function modelName(model: any): string | undefined {{
  const name = model?.id ?? model?.name ?? model?.model;
  return typeof name === "string" && name.length > 0 ? name : undefined;
}}

function sessionPayload(ctx: any): Record<string, unknown> {{
  const id = sessionID(ctx);
  const agentID = id ? subagentSessions.get(id) : undefined;
  return {{
    sessionID: id,
    cwd: ctx?.cwd,
    model: modelName(ctx?.model),
    // `agent_id` marks a subagent session; a top-level one has none.
    ...(agentID ? {{ agent_id: agentID }} : {{}}),
  }};
}}

function stringify(value: unknown): string {{
  if (value === null || value === undefined) return "";
  if (typeof value === "string") return value;
  try {{
    return JSON.stringify(value);
  }} catch (_e) {{
    return String(value);
  }}
}}

function contentToText(content: unknown): string {{
  if (content === null || content === undefined) return "";
  if (!Array.isArray(content)) return stringify(content);
  return content
    .map((part: any) => {{
      if (typeof part?.text === "string") return part.text;
      if (typeof part?.content === "string") return part.content;
      if (typeof part?.type === "string") return `[${{part.type}}]`;
      return stringify(part);
    }})
    .filter(Boolean)
    .join("\n\n")
    .trim();
}}

const startedSessions = new Set<string>();
const handoffChecked = new Set<string>();
const preCompactLast = new Map<string, number>();

function startSession(ctx: any, extra: Record<string, unknown> = {{}}): void {{
  const id = sessionID(ctx);
  if (!id || startedSessions.has(id)) return;
  startedSessions.add(id);
  // Generated integrations inject through fetchHandoff below. In managed mode
  // a queued SessionStart response is not model-visible and must not consume
  // the workstream context before that synchronous fetch receives it.
  if (!process.env.AI_MEMORY_RUN_ID) {{
    postHook("session-start", {{ ...sessionPayload(ctx), ...extra }});
  }}
}}

function postPreCompact(ctx: any): void {{
  startSession(ctx);
  const key = sessionID(ctx) || "unknown";
  const now = Date.now();
  const last = preCompactLast.get(key) ?? 0;
  if (now - last < 1000) return;
  preCompactLast.set(key, now);
  postHook("pre-compact", sessionPayload(ctx));
}}

function postHook(event: string, payload: Record<string, unknown>): void {{
  const url = new URL(`${{SERVER}}/hook`);
  url.searchParams.set("event", event);
  url.searchParams.set("agent", AGENT);
  if (!applyMarkerParams(url, typeof payload.cwd === "string" ? payload.cwd : undefined)) return;
  const policy = capturePolicy(payload, typeof payload.cwd === "string" ? payload.cwd : undefined);
  if (policy.disposition === "drop") return;
  try {{
    enqueueHook(event, url, policy.payload);
  }} catch (_e) {{
    // Best-effort capture. Hooks must never block the agent.
  }}
}}

async function fetchHandoff(cwd: string, id: string | undefined): Promise<string | undefined> {{
  // The GET claims the newest open handoff in whatever project the server
  // resolves; with no directory that is its default or last active project,
  // so another repository's baton could be consumed. Leave it open instead.
  if (!cwd) return undefined;
  if (captureServerRouted(cwd)) return undefined;
  // An allowlist build captures only marked repositories, and the native hook
  // returns before its handoff GET for any other (`hook.rs`). Do the same: the
  // server resolves the directory into a project to look the baton up, so a
  // request from an unmarked one leaves an empty project behind.
  if (CAPTURE_MODE === "allowlist" && !findMarker(cwd)) return undefined;
  const url = new URL(`${{SERVER}}/handoff`);
  url.searchParams.set("agent", AGENT);
  url.searchParams.set("cwd", cwd);
  if (id) url.searchParams.set("session_id", id);
  if (!applyMarkerParams(url, cwd)) return undefined;
  try {{
    // The body becomes the agent's context, so a redirect is refused: a
    // gateway's login page must never arrive as the handoff.
    const response = await fetch(url, {{
      proxy: false,
      redirect: "error",
      headers: authHeaders(),
      signal: timeoutSignal(1000),
    }});
    if (!response.ok) return undefined;
    const text = (await response.text()).trim();
    return text.length > 0 ? text : undefined;
  }} catch (_e) {{
    return undefined;
  }}
}}

export default function AiMemoryExtension(api: any): void {{
  api.on("session_start", (_event: any, ctx: any) => {{
    noteSubagent(ctx);
    startSession(ctx);
  }});

  api.on("before_agent_start", async (event: any, ctx: any) => {{
    noteSubagent(ctx);
    startSession(ctx);
    postHook("user-prompt", {{
      ...sessionPayload(ctx),
      prompt: event?.prompt,
      imageCount: Array.isArray(event?.images) ? event.images.length : undefined,
    }});

    const id = sessionID(ctx);
    // The baton belongs to the next top-level session, never to a subagent.
    if (!id || subagentSessions.has(id) || handoffChecked.has(id)) return;
    handoffChecked.add(id);
    const handoff = await fetchHandoff(ctx?.cwd ?? "", id);
    if (!handoff) return;
    return {{
      message: {{
        customType: "ai-memory-handoff",
        content: handoff,
        display: false,
        attribution: "agent",
      }},
    }};
  }});

  api.on("tool_call", (event: any, ctx: any) => {{
    startSession(ctx);
    postHook("pre-tool-use", {{
      ...sessionPayload(ctx),
      tool: event?.toolName,
      callID: event?.toolCallId,
      args: event?.input,
    }});
  }});

  api.on("tool_result", (event: any, ctx: any) => {{
    startSession(ctx);
    postHook("post-tool-use", {{
      ...sessionPayload(ctx),
      tool: event?.toolName,
      callID: event?.toolCallId,
      args: event?.input,
      output: contentToText(event?.content),
      details: event?.details,
      isError: event?.isError,
    }});
  }});

  api.on("session_before_compact", (_event: any, ctx: any) => {{
    postPreCompact(ctx);
  }});

  api.on("session_compact", (_event: any, ctx: any) => {{
    postPreCompact(ctx);
  }});

  api.on("session.compacting", (_event: any, ctx: any) => {{
    postPreCompact(ctx);
  }});

  api.on("agent_end", (_event: any, ctx: any) => {{
    startSession(ctx);
    postHook("stop", sessionPayload(ctx));
  }});

  api.on("session_shutdown", async (_event: any, ctx: any) => {{
    noteSubagent(ctx);
    startSession(ctx);
    postHook("session-end", sessionPayload(ctx));
    await drainHookQueueForDispose();
  }});
}}
"#,
        server_literal = ts_string_literal(server_url),
        token_line = token_line,
    );
    // Anchors are compile-time constants over this same file's template;
    // a mismatch is a template edit that forgot the spool patch.
    add_hook_spooling(body).expect("generated TS integration lost its hook-spool anchors")
}

fn render_agent(
    label: &str,
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    event_lists: &[&[(&str, &str)]],
) -> Result<()> {
    print!(
        "{}",
        render_agent_output(
            label,
            hooks_dir,
            server_url,
            auth_token,
            project_strategy,
            event_lists,
        )
    );
    Ok(())
}

fn render_agent_output(
    label: &str,
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    project_strategy: Option<&str>,
    event_lists: &[&[(&str, &str)]],
) -> String {
    let mut out = String::new();
    out.push_str(&format!(
        "# {label} hook scripts (manual install — wire each to the matching event)\n"
    ));
    out.push_str(&format!("# Hook scripts: {}\n", hooks_dir.display()));
    out.push_str(&format!("# AI-memory server URL: {server_url}\n"));
    if auth_token.is_some() {
        out.push_str("# Auth: set AI_MEMORY_AUTH_TOKEN in each hook's environment to the\n");
        out.push_str("#       value passed via --auth-token (omitted from this printout).\n");
    } else {
        out.push_str("# Auth: server requires no bearer token. To require one, generate a\n");
        out.push_str("#       token with `ai-memory generate-auth-token` and pass it via\n");
        out.push_str("#       --auth-token here AND set AI_MEMORY_AUTH_TOKEN on the server.\n");
    }
    out.push('\n');
    for events in event_lists {
        for (_, script) in *events {
            let script = hook_script_for_current_platform(script);
            out.push_str(&format!(
                "- {}\n",
                hooks_dir.join(script.as_ref()).display()
            ));
        }
    }
    out.push('\n');
    out.push_str("Set AI_MEMORY_HOOK_URL in each hook's environment to override the default.\n");
    if let Some(instruction) = manual_agent_project_strategy_instruction(project_strategy) {
        out.push_str(&instruction);
        out.push('\n');
    }
    if label == "antigravity-cli" {
        out.push('\n');
        out.push_str(ANTIGRAVITY_FINALIZATION_GUIDANCE);
    }
    out
}

fn manual_agent_project_strategy_instruction(project_strategy: Option<&str>) -> Option<String> {
    project_strategy.map(|strategy| {
        format!(
            "Set AI_MEMORY_PROJECT_STRATEGY={strategy} in each hook's environment to use the requested project strategy."
        )
    })
}

/// Copy the bundled hook scripts to a stable user-global location
/// and return that location. The path the agent's config file
/// references is THIS path, not the source bundle's path.
///
/// Why this matters:
///
/// - **Project-portability.** The previous behaviour wrote the
///   repo-relative path (e.g. `/mnt/data/Projects/ai-memory/hooks/
///   claude-code/session-start.sh`) into the agent's settings.
///   Any agent CLI started from a different project — or in a
///   filesystem sandbox that didn't whitelist that path — failed
///   the SessionStart hook with "No such file or directory".
///
/// - **Docker-image upgrades.** Users who installed via the docker
///   image had paths under `/usr/local/share/ai-memory/hooks/`
///   baked into their settings — paths only valid INSIDE the
///   container. Staging copies the scripts OUT to the host's
///   `~/.local/share/ai-memory/hooks/` so the host-side agent can
///   actually reach them.
///
/// - **Updates.** When a new docker image ships with updated hook
///   scripts, the user re-runs `install-hooks --apply` and the
///   stage step overwrites the previous copies. No special
///   `update-hooks` command, no version-tracking dance.
///
/// Errors propagate when source is missing, the staging dir
/// can't be created, or any file copy fails.
fn stage_hook_scripts(source_dir: &Path, agent_label: &str, data_dir: &Path) -> Result<PathBuf> {
    stage_hook_scripts_in(
        source_dir,
        agent_label,
        &hook_staging_root(data_dir, ai_memory_wiki::backup::running_in_container()),
    )
}

/// Where hook scripts are staged — which is also the path written into
/// the agent's settings, so it must be reachable by the process that
/// EXECUTES the hooks: the host-side agent CLI.
///
/// - **Native installs**: the resolved data dir (`--data-dir` /
///   `AI_MEMORY_DATA_DIR` / platform default), per #554.
/// - **Inside a container** (the docker wrapper): the server data dir is
///   a volume (`/data`) the host cannot execute from — staging there
///   wrote container-only paths into the host's settings and every hook
///   failed silently (#581). The wrapper binds `$HOME:$HOME` and reads
///   staged hooks from `~/.local/share/ai-memory/hooks` (its
///   `HOOKS_STAGE_DIR` contract), so the home-based default is the
///   host-reachable location there.
pub(crate) fn hook_staging_root(data_dir: &Path, in_container: bool) -> PathBuf {
    if in_container {
        dirs::data_local_dir()
            .map(|d| d.join("ai-memory"))
            .unwrap_or_else(|| data_dir.to_path_buf())
    } else {
        data_dir.to_path_buf()
    }
}

fn stage_hook_scripts_in(source_dir: &Path, agent_label: &str, data_dir: &Path) -> Result<PathBuf> {
    // `<data_dir>/hooks/<agent>`, not `<platform default>/ai-memory/hooks/…`.
    // Byte-identical for a default install, since `default_data_dir()` *is*
    // `data_local_dir()/ai-memory` — but it now follows `--data-dir` and
    // `AI_MEMORY_DATA_DIR` instead of populating a directory the operator is
    // not using (#554).
    let dest_root = data_dir.join("hooks").join(agent_label);

    fs::create_dir_all(&dest_root)
        .with_context(|| format!("creating staging dir {}", dest_root.display()))?;

    // When `resolve_hooks_dir` falls through to the data-local
    // candidate (e.g. docker `setup-agent` already extracted the
    // bundle into ~/.local/share/ai-memory/hooks/<agent>/, or a prior
    // install left scripts in place), the source dir IS the
    // destination dir. The wipe-then-copy flow below would delete the
    // very scripts we mean to install before reading them, leaving 0
    // copied and a settings.json pointing at an empty directory
    // (issue #52). Detect that case via canonical paths and verify
    // the existing layout in place instead of touching it.
    let same_path = same_canonical_dir(source_dir, &dest_root);

    if !same_path {
        // Wipe any previously-staged scripts that the current bundle
        // no longer ships. Idempotent re-runs against an old install
        // shouldn't leave stale entries pointed at by nothing.
        if let Ok(entries) = fs::read_dir(&dest_root) {
            for entry in entries.flatten() {
                let p = entry.path();
                if p.is_file() && is_hook_script_file(&p) {
                    fs::remove_file(&p).ok();
                }
            }
        }
    }

    let mut count = 0_usize;
    for entry in fs::read_dir(source_dir)
        .with_context(|| format!("reading source bundle {}", source_dir.display()))?
    {
        let entry = entry?;
        let from = entry.path();
        if !from.is_file() || !is_hook_script_file(&from) {
            continue;
        }
        if !same_path {
            copy_hook_file(&from, &dest_root)?;
        }
        count += 1;
    }

    if !same_path {
        copy_support_hook_scripts(source_dir, &dest_root)?;

        // Stage the shared `_lib.sh` helper alongside the event scripts so
        // they can `. "$(dirname "$0")/_lib.sh"` without depending on the
        // user's PATH or repo layout. The helper lives ONCE in
        // `hooks/_lib.sh` (one parent up from the agent-specific dir) —
        // staging it here is what keeps every agent's runtime view
        // consistent with the source of truth.
        if let Some(shared) = source_dir.parent().map(|p| p.join("_lib.sh"))
            && shared.is_file()
        {
            copy_hook_file(&shared, &dest_root)?;
        }
    }

    if count == 0 {
        anyhow::bail!(
            "no hook scripts found at {}.\n\
             Refusing to install — pointing the agent's settings at an empty \
             directory would silently disable all capture. Either pass \
             `--hooks-dir <path>` to point at a populated source tree, or run \
             `ai-memory setup-agent --agent <name>` first to extract the \
             bundled scripts.",
            source_dir.display()
        );
    }

    let verb = if same_path { "verified" } else { "staged" };
    eprintln!("✓ {verb} {count} hook script(s) → {}", dest_root.display());
    Ok(dest_root)
}

/// `true` when `a` and `b` resolve to the same directory after symlink
/// canonicalization. Falls back to literal `==` if either canonicalize
/// call fails (e.g. dest hasn't been created yet on Windows, network
/// FS quirks). The caller has already `create_dir_all`'d both ends
/// in the staging flow, so the fast path almost always wins.
fn same_canonical_dir(a: &Path, b: &Path) -> bool {
    match (a.canonicalize(), b.canonicalize()) {
        (Ok(ca), Ok(cb)) => ca == cb,
        _ => a == b,
    }
}

/// Copy `from` onto `to`, replacing a read-only `to` left by an earlier
/// staging run. Package stores (Nix) ship hook sources as 0444, `fs::copy`
/// carries that mode over, and a second copy onto the read-only destination
/// fails with `PermissionDenied`. Only that failure removes the stale copy
/// and retries, so a writable destination is overwritten exactly as before.
pub(crate) fn copy_replacing(from: &Path, to: &Path) -> Result<()> {
    let context = || format!("copying {} → {}", from.display(), to.display());
    match fs::copy(from, to) {
        Ok(_) => Ok(()),
        Err(err) if err.kind() == std::io::ErrorKind::PermissionDenied && to.is_file() => {
            fs::remove_file(to)
                .with_context(|| format!("removing read-only staged copy {}", to.display()))?;
            fs::copy(from, to).with_context(context)?;
            Ok(())
        }
        Err(err) => Err(err).with_context(context),
    }
}

/// Copy a single hook file (event script or shared `_lib.sh`) into the
/// staging dir, preserving the executable bit on Unix. Centralised so
/// the script bulk-copy and the `_lib.sh` companion follow the same
/// rules without duplicating permission-handling.
fn copy_hook_file(from: &Path, dest_root: &Path) -> Result<()> {
    let to = dest_root.join(from.file_name().context("bad source file name")?);
    copy_replacing(from, &to)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = fs::metadata(&to)?.permissions();
        perms.set_mode(0o755);
        fs::set_permissions(&to, perms)?;
    }
    Ok(())
}

/// Copy the optional `lib/` support directory (currently PowerShell
/// helpers for Windows hook parity) alongside the event scripts.
/// No-op when the source bundle doesn't ship it.
fn copy_support_hook_scripts(source_dir: &Path, dest_root: &Path) -> Result<()> {
    let Some(source_hooks_root) = source_dir.parent() else {
        return Ok(());
    };
    let source_lib = source_hooks_root.join("lib");
    if !source_lib.is_dir() {
        return Ok(());
    }
    let Some(dest_hooks_root) = dest_root.parent() else {
        return Ok(());
    };
    let dest_lib = dest_hooks_root.join("lib");
    fs::create_dir_all(&dest_lib)
        .with_context(|| format!("creating hook support dir {}", dest_lib.display()))?;
    for entry in fs::read_dir(&source_lib)
        .with_context(|| format!("reading hook support dir {}", source_lib.display()))?
    {
        let entry = entry?;
        let from = entry.path();
        if !from.is_file() || from.extension().and_then(|s| s.to_str()) != Some("ps1") {
            continue;
        }
        let to = dest_lib.join(from.file_name().context("bad support file name")?);
        copy_replacing(&from, &to)?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mut perms = fs::metadata(&to)?.permissions();
            perms.set_mode(0o644);
            let _ = fs::set_permissions(&to, perms);
        }
    }
    Ok(())
}

fn staged_command_dir(staged: &Path, agent_label: &str) -> PathBuf {
    match std::env::var("AI_MEMORY_HOOKS_HOST_ROOT") {
        Ok(root) if !root.trim().is_empty() => PathBuf::from(root).join(agent_label),
        _ => staged.to_path_buf(),
    }
}

fn is_hook_script_file(path: &Path) -> bool {
    matches!(
        path.extension().and_then(|s| s.to_str()),
        Some("sh" | "ps1")
    )
}

fn resolve_hooks_dir(
    explicit: Option<&Path>,
    agent: AgentChoice,
    data_dir: &Path,
) -> Result<PathBuf> {
    let Some(sub) = agent.script_hook_subdir() else {
        anyhow::bail!("{agent:?} uses a generated integration, not a hook script directory")
    };
    if let Some(p) = explicit {
        let path = p.join(sub);
        if path.is_dir() {
            return Ok(path);
        }
        anyhow::bail!("hooks directory {} does not exist", path.display());
    }

    // Probe candidates in order. The first dir that exists wins.
    let candidates = hook_source_candidates(
        sub,
        repo_root_guess(),
        exe_dir_guess(),
        Some(data_dir.to_path_buf()),
    );
    for path in &candidates {
        if !path.as_os_str().is_empty() && path.is_dir() {
            return Ok(path.clone());
        }
    }
    anyhow::bail!(
        "could not locate hooks directory. Tried: {candidates:?}. \
         Pass --hooks-dir <directory containing {sub}/> to point at the bundle explicitly.",
    );
}

fn hook_source_candidates(
    sub: &str,
    repo_root: Option<PathBuf>,
    exe_dir: Option<PathBuf>,
    data_dir: Option<PathBuf>,
) -> Vec<PathBuf> {
    let mut candidates = Vec::with_capacity(6);
    // Cargo-run from the repo.
    if let Some(root) = repo_root {
        candidates.push(root.join(crate::install_layout::HOOKS_DIR_NAME).join(sub));
    }
    // Release tarball (macOS/Windows/Linux archive): the `hooks/` bundle
    // ships in the same directory as the binary, so it's reachable without
    // `--source` (issue #107).
    if let Some(dir) = exe_dir.as_ref() {
        candidates.push(dir.join(crate::install_layout::HOOKS_DIR_NAME).join(sub));
    }
    // Standard Unix prefix layout: binary at `<prefix>/bin/ai-memory`,
    // hooks installed under `<prefix>/share/ai-memory/hooks/<sub>` (Nix,
    // Homebrew, /opt/local, custom prefix installs).
    if let Some(dir) = exe_dir.as_ref()
        && dir.file_name().is_some_and(|name| name == "bin")
        && let Some(prefix) = dir.parent()
    {
        candidates.push(
            prefix
                .join("share")
                .join("ai-memory")
                .join(crate::install_layout::HOOKS_DIR_NAME)
                .join(sub),
        );
    }
    // Docker image lays them out under /usr/local/share/ai-memory/.
    candidates.push(PathBuf::from(format!(
        "/usr/local/share/ai-memory/hooks/{sub}"
    )));
    // Native Linux packages install hook sources under /usr/share.
    candidates.push(PathBuf::from(format!("/usr/share/ai-memory/hooks/{sub}")));
    // Local install honourable mention: the bundle a previous `--apply`, or
    // docker `setup-agent`, staged under the data dir actually in use.
    if let Some(dir) = data_dir {
        candidates.push(dir.join("hooks").join(sub));
    }
    candidates
}

fn repo_root_guess() -> Option<PathBuf> {
    repo_root_from_exe(&current_exe_resolved()?)
}

/// When the binary lives under target/{debug,release}/<name>, the
/// workspace root is two parents up.
fn repo_root_from_exe(exe: &Path) -> Option<PathBuf> {
    Some(exe.parent()?.parent()?.parent()?.to_path_buf())
}

/// Directory the running binary lives in. The release tarball ships the
/// `hooks/` bundle right next to the binary, so a no-`--source`
/// `install-hooks` finds it there (issue #107).
fn exe_dir_guess() -> Option<PathBuf> {
    Some(current_exe_resolved()?.parent()?.to_path_buf())
}

/// Path of the running binary with symlinks resolved.
///
/// Both guesses above are relative to where the binary *lives*, not to how
/// it was invoked. `~/.local/bin/ai-memory -> <repo>/target/release/ai-memory`
/// is the layout the quick start suggests, and without this the repo-root
/// guess walks up from the link's own directory to `$HOME` while the tarball
/// guess stops at `~/.local/bin` — leaving the bundled `hooks/` unreachable
/// from every candidate, whatever the cwd (issue #546).
fn current_exe_resolved() -> Option<PathBuf> {
    std::env::current_exe().ok().map(resolve_exe_path)
}

/// Canonicalise an executable path, keeping the original when the target
/// cannot be resolved (deleted binary, or a filesystem that refuses).
fn resolve_exe_path(exe: PathBuf) -> PathBuf {
    fs::canonicalize(&exe).unwrap_or(exe)
}

// CLAUDE_CODE_EVENTS + build_claude_code_payload now live in
// `super::render_shared`, shared with `setup-agent`.

/// Which optional capture surfaces the generated Claude Code settings should
/// include.
///
/// Grouped rather than passed as two positional bools: at the call site
/// `true, false` said nothing about which surface was which, and the pair is
/// exactly the privacy-relevant part of this install — worth naming.
#[derive(Debug, Clone, Copy)]
struct ClaudeCaptureScope {
    /// Include the assistant-message capture hook (double opt-in, off by
    /// default).
    assistant: bool,
    /// Include the `UserPromptSubmit` hook. When false the entry is omitted
    /// entirely, so the agent never emits prompt text at all.
    prompts: bool,
}

/// The settings file a Claude Code preview is rendered for, and the scope that
/// chose it.
struct ClaudeRenderTarget<'a> {
    settings_path: &'a Path,
    scope: HookInstallScope,
}

fn render_claude_code(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    target: ClaudeRenderTarget<'_>,
    capture: ClaudeCaptureScope,
) -> Result<()> {
    let ClaudeRenderTarget {
        settings_path,
        scope,
    } = target;
    let ClaudeCaptureScope {
        assistant: capture_assistant,
        prompts: capture_prompts,
    } = capture;
    // A preview never persists the bearer (#552), so it would land inline in
    // the snippet — and project scope tells the operator to paste that snippet
    // into a checkout. Withhold it there; `--apply` persists it instead.
    let token_withheld = scope == HookInstallScope::Project && auth_token.is_some();
    let auth_token = if token_withheld { None } else { auth_token };
    // Soft check: warn (don't bail) if a script is missing. The user
    // may be running this command inside docker against a host path
    // that exists only on the host's filesystem — bailing would
    // sabotage the docker-only flow `setup-agent` enables.
    for (event, script) in super::render_shared::CLAUDE_CODE_EVENTS {
        if !capture_prompts && event == CLAUDE_PROMPT_EVENT {
            continue;
        }
        let script = hook_script_for_claude_code(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    let payload = configure_claude_prompt_capture(
        build_claude_code_payload_with_data_dir(
            hooks_dir,
            server_url,
            auth_token,
            Some(data_dir),
            project_strategy,
            capture_assistant,
        ),
        capture_prompts,
    );
    let serialized =
        serde_json::to_string_pretty(&payload).context("serializing claude code hook config")?;
    println!(
        "# Claude Code hook config — merge into {}",
        settings_path.display()
    );
    println!("# Hook scripts: {}", hooks_dir.display());
    println!("# AI-memory server URL: {server_url}");
    if token_withheld {
        println!("# Auth: a bearer token is configured but NOT embedded below: this file"); // lgtm [rust/cleartext-logging]
        println!("#       lives inside a checkout. Re-run with --apply, which persists the");
        println!(
            "#       token under {} (0600) where the hooks read it.",
            data_dir.display()
        );
    } else if auth_token.is_some() {
        println!("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");
        println!(
            "#       Treat {} as sensitive (chmod 600).",
            settings_path.display()
        );
    }
    println!();
    println!("{serialized}");
    Ok(())
}

fn render_grok(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    // Soft check (same rationale as render_claude_code): warn, don't bail,
    // so the docker host-path flow still works.
    for (_, script) in super::render_shared::GROK_EVENTS {
        let script = hook_script_for_claude_code(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    let payload = build_grok_payload_with_data_dir(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized =
        serde_json::to_string_pretty(&payload).context("serializing grok hook config")?;
    let config_path = grok_hooks_path()?;
    println!(
        "# Grok Build CLI hook config — write to {}",
        config_path.display()
    );
    println!("# Hook scripts: {}", hooks_dir.display());
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");
        println!(
            "#       Treat {} as sensitive (chmod 600).",
            config_path.display()
        );
    }
    println!("# NOTE: Grok ignores hook stdout on SessionStart — capture works,");
    println!("#       but that event does not inject the handoff. The first");
    println!("#       PostToolUse injects additionalContext. --apply also writes");
    println!("#       $GROK_HOME/rules/ai-memory-handoff.md so the first turn");
    println!("#       calls memory_handoff_list (PostToolUse then claims it).");
    println!();
    println!("{serialized}");
    Ok(())
}

/// Merge ai-memory's lifecycle hooks into Zero's user-level
/// `~/.config/zero/hooks.json` (issue #156). Zero executes hook entries
/// directly (`command` + `args`, JSON payload on stdin) — no scripts to
/// stage, no shell. Only entries whose `id` carries the `ai-memory-`
/// prefix are replaced, so third-party hooks in the same file survive
/// re-installs and version upgrades. The file-level `enabled` flag is
/// preserved when the file already exists (a user who disabled hooks
/// globally keeps that choice — we warn instead of overriding).
fn apply_to_zero_hooks(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => zero_hooks_path()?,
    };
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_zero_hooks_config(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_array())
        .context("internal: build_zero_hooks_config didn't return a hooks array")?
        .clone();
    let mut hooks_disabled = false;
    let outcome = apply_atomic(&path, |existing| {
        mutate_json(existing, |root| {
            hooks_disabled = root.get("enabled").and_then(|v| v.as_bool()) == Some(false);
            if !root.contains_key("enabled") {
                root.insert("enabled".into(), serde_json::Value::Bool(true));
            }
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Array(Vec::new()))
                .as_array_mut()
                .context("`hooks` is present in hooks.json but not an array")?;
            hooks.retain(|hook| {
                !hook
                    .get("id")
                    .and_then(|v| v.as_str())
                    .is_some_and(|id| id.starts_with("ai-memory-"))
            });
            hooks.extend(our_hooks.iter().cloned());
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    if hooks_disabled {
        eprintln!(
            "# warning: this hooks.json sets \"enabled\": false at the top level, \
             so Zero will not run ANY hooks (including ai-memory's) until you \
             re-enable them."
        );
    }
    print!("{}", zero_install_notes(data_dir.display()));
    Ok(())
}

/// Caveats printed after both the Zero dry-run and `--apply` (#1172).
/// Zero runs hook commands inside its execution sandbox, which by
/// default denies all network (loopback included), keeps `/` read-only
/// outside the workspace and temp, and kills a hook's detached children
/// when it exits. Only the user's global Zero config can relax that, and
/// ai-memory must not edit it, so the note names the keys instead.
pub(crate) fn zero_install_notes(data_dir: impl std::fmt::Display) -> String {
    format!(
        "# NOTE: Zero discards sessionStart hook stdout — capture works, but\n\
         #       handoff injection does not. Recover a prior session's handoff\n\
         #       via the MCP `memory_handoff_accept` tool.\n\
         # NOTE: Zero runs hooks inside its sandbox, which by default blocks all\n\
         #       network (127.0.0.1 too) and writes outside the workspace, so\n\
         #       events stay in the hook spool instead of reaching the server.\n\
         #       To deliver live, set in the global ~/.config/zero/config.json:\n\
         #         \"sandbox\": {{\"network\": \"allow\",\n\
         #                     \"additionalWriteRoots\": [\"{}\"]}}\n\
         #       (network allow applies to every Zero shell command), or\n\
         #       \"sandbox\": {{\"enabled\": false}}. With network allowed,\n\
         #       sessionEnd delivers in-process (the sandbox kills detached\n\
         #       drainers). Otherwise run `ai-memory hook-drain` from a\n\
         #       normal shell to deliver spooled events.\n",
        data_dir
    )
}

/// Print Zero's hooks.json to stdout (dry-run counterpart of
/// [`apply_to_zero_hooks`]).
fn render_zero(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_zero_hooks_config(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized =
        serde_json::to_string_pretty(&payload).context("serializing zero hook config")?;
    println!("# Zero hook config — merge into ~/.config/zero/hooks.json");
    println!("# ($XDG_CONFIG_HOME/zero/hooks.json on non-default XDG setups), or");
    println!("# re-run with --apply to merge it in place, preserving other hooks.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: token embedded in each hook's args below.");
        println!("#       Treat hooks.json as sensitive (chmod 600).");
    }
    print!("{}", zero_install_notes(data_dir.display()));
    println!();
    println!("{serialized}");
    Ok(())
}

/// Whether a hook entry in ZCode's `hooks.events` map is one ai-memory
/// wrote. Our entries carry a `statusMessage` starting with `ai-memory`
/// — the only schema-documented free-form key, so ownership is marked
/// without emitting keys ZCode would drop.
fn is_our_zcode_hook(hook: &serde_json::Value) -> bool {
    hook.get("statusMessage")
        .and_then(|v| v.as_str())
        .is_some_and(|msg| msg.starts_with("ai-memory"))
}

/// Withdraw ai-memory's own hook entries from every matcher group in
/// `groups`, leaving each group, and anyone else's hooks inside it, in
/// place.
fn strip_our_zcode_hook_entries(groups: &mut [serde_json::Value]) {
    for group in groups.iter_mut() {
        if let Some(hooks) = group
            .as_object_mut()
            .and_then(|group| group.get_mut("hooks"))
            .and_then(|v| v.as_array_mut())
        {
            hooks.retain(|hook| !is_our_zcode_hook(hook));
        }
    }
}

/// Same, for a `hooks.events` slot of unknown shape. Returns how many
/// entries were withdrawn so the caller can report them; a slot that is
/// not an array is left untouched and counts zero.
fn strip_our_zcode_hooks(slot: &mut serde_json::Value) -> usize {
    let Some(groups) = slot.as_array_mut() else {
        return 0;
    };
    let before = zcode_hook_count(groups);
    strip_our_zcode_hook_entries(groups);
    before.saturating_sub(zcode_hook_count(groups))
}

/// Total hook entries across every matcher group in `groups`, ignoring
/// groups whose `hooks` is absent or not an array.
fn zcode_hook_count(groups: &[serde_json::Value]) -> usize {
    groups
        .iter()
        .filter_map(|group| group.get("hooks").and_then(|v| v.as_array()))
        .map(|hooks| hooks.len())
        .sum()
}

/// True when a `hooks.events` entry cannot run anything: no matcher groups
/// at all, no group carrying a non-empty `hooks` array, or a value that is
/// not a matcher-group array in the first place. Such a key is pure
/// downside under ZCode's strict validation, since it runs nothing and can
/// cost the user every other hook in the block.
///
/// Deliberately narrower than "a key ai-memory does not write": several of
/// those are real ZCode events this tool skips on purpose (see
/// `PermissionRequest` in `render_shared`), and a key still running
/// someone's hook is their working config, not a leftover. Reporting on
/// that set would be a false-positive generator.
fn zcode_event_runs_nothing(slot: &serde_json::Value) -> bool {
    match slot.as_array() {
        Some(groups) => zcode_hook_count(groups) == 0,
        None => true,
    }
}

/// Merge ai-memory hooks into the root `hooks` block of ZCode's
/// user-scope `~/.zcode/cli/config.json` (#512). Sibling config keys
/// (`model`, `provider`, `mcp.servers`, …) always survive: the merge
/// touches only `hooks.enabled` (defaulted, never flipped),
/// `hooks.maxOutputBytes` (set only when absent), and `hooks.events`,
/// replaces entries ai-memory owns (idempotent re-apply), and never
/// removes a hook it did not write. Entries it owns are withdrawn
/// wherever they sit, including under event keys this version no longer
/// writes; event keys themselves are never deleted, only reported when
/// ai-memory withdrew entries from them, or when they are left unable to
/// run anything (#600). The one thing it does
/// discard is a matcher group left holding an empty `hooks` array under a
/// key it writes, which drops a caller's own empty group along with the
/// ones its withdrawal emptied.
fn apply_to_zcode_hooks(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let path = match &args.config_file {
        Some(p) => p.clone(),
        None => zcode_config_path()?,
    };
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_zcode_hooks_config(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_events = payload
        .get("events")
        .and_then(|v| v.as_object())
        .context("internal: build_zcode_hooks_config didn't return an events map")?
        .clone();
    let mut hooks_disabled = false;
    let mut stale: Vec<(String, usize, bool)> = Vec::new();
    let outcome = apply_atomic(&path, |existing| {
        mutate_json(existing, |root| {
            // `hooks` sits beside sibling config keys that must survive.
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::json!({}))
                .as_object_mut()
                .context("`hooks` is present in the ZCode config but not an object")?;
            hooks_disabled = hooks.get("enabled").and_then(|v| v.as_bool()) == Some(false);
            if !hooks.contains_key("enabled") {
                hooks.insert("enabled".into(), serde_json::Value::Bool(true));
            }
            // Raise the stdout ceiling above ZCode's 32 KiB default so a
            // fetched handoff is not truncated mid-JSON before injection.
            // Only when the user has not chosen their own value: the key
            // is block-level and would also bound third-party hooks.
            if !hooks.contains_key("maxOutputBytes")
                && let Some(ceiling) = payload.get("maxOutputBytes")
            {
                hooks.insert("maxOutputBytes".into(), ceiling.clone());
            }
            let events = hooks
                .entry("events")
                .or_insert_with(|| serde_json::json!({}))
                .as_object_mut()
                .context("`hooks.events` is present in the ZCode config but not an object")?;
            for (event, ours) in &our_events {
                let ours = ours
                    .as_array()
                    .context("internal: zcode event payload is not a matcher-group array")?;
                let slot = events
                    .entry(event.clone())
                    .or_insert_with(|| serde_json::Value::Array(Vec::new()));
                let slot = slot.as_array_mut().context(
                    "`hooks.events.{event}` is present in the ZCode config but not an array",
                )?;
                strip_our_zcode_hook_entries(slot);
                slot.retain(|group| match group.get("hooks") {
                    Some(serde_json::Value::Array(hooks)) => !hooks.is_empty(),
                    _ => true,
                });
                slot.extend(ours.iter().cloned());
            }
            // ai-memory writes only the six keys in `ZCODE_EVENTS`, but its
            // own entries can sit under other keys too (a config carried
            // over from another agent, or hand-edited). Those are ours to
            // withdraw; the keys themselves are not, so every one is left
            // in place. What makes a leftover dangerous is ZCode strict-
            // validating this map: one key it does not recognize and it
            // rejects the ENTIRE hooks block, ai-memory's included, so
            // capture dies while the file still matches byte for byte and
            // apply reports it as up to date (#600). Collect the keys that
            // can no longer run anything and say so after the write.
            for (event, slot) in events.iter_mut() {
                if our_events.contains_key(event) {
                    continue;
                }
                let withdrawn = strip_our_zcode_hooks(slot);
                let runs_nothing = zcode_event_runs_nothing(slot);
                if withdrawn > 0 || runs_nothing {
                    stale.push((event.clone(), withdrawn, runs_nothing));
                }
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            // Only claim the install is current when nothing turned up
            // that can stop ZCode loading it. Saying "already up to date"
            // over a block ZCode rejects is the whole of #600, and the
            // notes explaining it go to stderr, so a redirected stdout
            // would otherwise carry the reassurance and none of the cause.
            ApplyOutcome::NoOp if stale.is_empty() => "already up to date",
            ApplyOutcome::NoOp => "unchanged; see the notes below",
        }
    );
    if hooks_disabled {
        eprintln!(
            "# warning: this config sets \"enabled\": false inside `hooks`, \
             so ZCode will not run ANY hooks (including ai-memory's) until \
             you re-enable them."
        );
    }
    if !stale.is_empty() {
        // The report above goes to stdout and these go to stderr; stdout
        // block-buffers when redirected, so without this the two arrive out
        // of order in a log or in CI.
        let _ = std::io::stdout().flush();
    }
    for (event, withdrawn, runs_nothing) in &stale {
        if *withdrawn > 0 {
            // A withdrawal is positive evidence ai-memory once lived under
            // this key, so the risk here is not hypothetical.
            eprintln!(
                "# warning: withdrew {withdrawn} ai-memory hook(s) from \
                 `hooks.events.{event}`, a key ai-memory does not write. The \
                 key itself was left as found, but ZCode validates this map \
                 strictly and rejects the ENTIRE hooks block, ai-memory's \
                 included, over one key it does not recognize, which leaves \
                 capture silently dead. If ZCode reports `hookCount: 0`, \
                 remove that key from {}.",
                path.display()
            );
        } else if *runs_nothing {
            eprintln!(
                // Only the provenance claim degrades between the two
                // tiers; the consequence is identical, so state it at full
                // strength. "If ZCode does not recognize it" keeps this
                // honest about keys ZCode does accept, such as an empty
                // `Notification`.
                "# note: `hooks.events.{event}` runs nothing, and ai-memory \
                 does not write that key. If ZCode does not recognize it, \
                 ZCode rejects the ENTIRE hooks block, ai-memory's included, \
                 and capture is dead while this file looks correct. If ZCode \
                 reports `hookCount: 0`, remove that key from {}.",
                path.display()
            );
        }
    }
    println!("# NOTE: ZCode injects SessionStart stdout as model context, so the");
    println!("#       prior session's handoff is delivered automatically.");
    println!("# NOTE: ZCode fires `Stop` at the end of every turn and has no");
    println!("#       SessionEnd — close sessions with");
    println!("#       `ai-memory finalize-session --agent zcode`.");
    Ok(())
}

/// Print ZCode's `hooks` block to stdout (dry-run counterpart of
/// [`apply_to_zcode_hooks`]).
fn render_zcode(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_zcode_hooks_config(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized =
        serde_json::to_string_pretty(&payload).context("serializing zcode hook config")?;
    println!("# ZCode (z.ai) hooks config — merge the `hooks` block into");
    println!("# ~/.zcode/cli/config.json (the same file `install-mcp --client");
    println!("# zcode` registers MCP servers in), or re-run with --apply to");
    println!("# merge it in place, preserving the rest of the config.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook's args");
        println!("#       so a hand-placed config works as-is — treat it as");
        println!("#       sensitive (chmod 600). NOTE: `--apply` does NOT embed the");
        println!("#       token; it persists it to <data-dir>/auth-token (0600) and");
        println!("#       writes token-less args, so the applied config differs from");
        println!("#       this snippet by design (#552, #600).");
    }
    println!("# NOTE: ZCode injects SessionStart stdout as model context, so the");
    println!("#       prior session's handoff is delivered automatically.");
    println!("# NOTE: ZCode fires `Stop` at the end of every turn and has no");
    println!("#       SessionEnd — close sessions with");
    println!("#       `ai-memory finalize-session --agent zcode`.");
    println!();
    println!("{serialized}");
    Ok(())
}

/// Where the community ai-memory memory-provider plugin for Hermes installs
/// itself: `$HERMES_HOME/plugins/ai-memory`, with `HERMES_HOME` defaulting to
/// `~/.hermes` as Hermes and the plugin's installer both resolve it. Both
/// variables come from the captured environment (invariant #1).
pub(crate) fn hermes_plugin_dir(env: &crate::config::RuntimeEnv) -> Option<PathBuf> {
    hermes_plugin_dir_in(env.var_os("HERMES_HOME"), env.home_dir().map(PathBuf::from))
}

fn hermes_plugin_dir_in(
    hermes_home: Option<std::ffi::OsString>,
    home: Option<PathBuf>,
) -> Option<PathBuf> {
    crate::commands::path_util::agent_config_home(hermes_home)
        .or_else(|| home.map(|home| home.join(".hermes")))
        .map(|hermes_home| hermes_home.join("plugins").join("ai-memory"))
}

/// The plugin posts prompts and session ends and claims the handoff itself,
/// so where it is installed the hooks wire the tool events alone. A plain
/// directory check, so the same machine always renders the same block.
pub(crate) fn hermes_hook_set(plugin_dir: Option<&Path>) -> HermesHookSet {
    if plugin_dir.is_some_and(Path::is_dir) {
        HermesHookSet::ToolsOnly
    } else {
        HermesHookSet::Full
    }
}

/// `install-hooks --agent hermes`: print the ready-to-paste `hooks:` block for
/// `~/.hermes/config.yaml`.
///
/// ai-memory deliberately does not write that file. It is YAML the operator
/// also edits (comments, other hooks) and would have to be spliced, and Hermes
/// gates user hooks behind its own acceptance prompt (`hooks_auto_accept`
/// asks before registering one), so entries appearing silently would fight
/// both. There is nothing to stage either: the block invokes the native `hook`
/// subcommand, not a `.sh` bundle.
fn render_hermes(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    plugin_dir: Option<&Path>,
) -> Result<()> {
    print!(
        "{}",
        render_hermes_output(
            server_url,
            auth_token,
            data_dir,
            project_strategy,
            plugin_dir
        )
    );
    Ok(())
}

fn render_hermes_output(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
    plugin_dir: Option<&Path>,
) -> String {
    let hook_set = hermes_hook_set(plugin_dir);
    let block = super::render_shared::build_hermes_hooks_yaml(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
        hook_set,
    );
    let mut out = String::new();
    out.push_str("# Hermes Agent hooks config — merge the `hooks:` block below\n");
    out.push_str("# into ~/.hermes/config.yaml and let Hermes accept it when it\n");
    out.push_str("# prompts (or set `hooks_auto_accept: true`). ai-memory does not\n");
    out.push_str("# write that file: it is YAML you also edit, and it would have to\n");
    out.push_str("# be spliced. Restart Hermes (and its gateway) to load it.\n");
    out.push_str(&format!("# AI-memory server URL: {server_url}\n"));
    if auth_token.is_some() {
        out.push_str("# Auth: this snippet embeds the token in each hook command —\n");
        out.push_str("#       treat ~/.hermes/config.yaml as sensitive (chmod 600).\n");
    }
    out.push_str(&hermes_hook_set_notes(hook_set, plugin_dir));
    out.push_str("# NOTE: each `command` is a bare argv line. Hermes splits it with\n");
    out.push_str("#       shlex.split and runs it without a shell, so the generated\n");
    out.push_str("#       command invokes the ai-memory binary directly.\n");
    out.push('\n');
    out.push_str(&block);
    out
}

/// The comment lines that say which Hermes events the block wires and why.
/// Shared with `setup-agent`, which renders the same block.
pub(crate) fn hermes_hook_set_notes(hook_set: HermesHookSet, plugin_dir: Option<&Path>) -> String {
    let plugin = plugin_dir.map_or_else(
        || "$HERMES_HOME/plugins/ai-memory".to_owned(),
        |dir| dir.display().to_string(),
    );
    match hook_set {
        HermesHookSet::ToolsOnly => format!(
            "# NOTE: only the two tool events are wired. The ai-memory\n\
             #       memory-provider plugin is installed at {plugin}\n\
             #       and already captures prompts, ends sessions and claims\n\
             #       the handoff; wiring those here too would capture every\n\
             #       prompt twice and race the plugin for the handoff.\n\
             # NOTE: only that directory is checked. A plugin disabled with\n\
             #       `hermes plugins disable` but left there still selects\n\
             #       this block; wire the lifecycle by hand in that case.\n"
        ),
        HermesHookSet::Full => format!(
            "# NOTE: tool events plus the session lifecycle. pre_llm_call\n\
             #       captures each prompt and brings the pending handoff into\n\
             #       the next turn, including after a resumed native session;\n\
             #       on_session_end marks a turn\n\
             #       (Hermes fires it after every turn) and on_session_finalize\n\
             #       ends the session.\n\
             # NOTE: a gateway session that expires idle is never finalized;\n\
             #       close it with `ai-memory finalize-session --agent hermes`.\n\
             # NOTE: if you install the ai-memory memory-provider plugin\n\
             #       ({plugin}), keep only pre_tool_call and\n\
             #       post_tool_call: the plugin covers the rest. A plugin\n\
             #       under another profile's HERMES_HOME is not seen here;\n\
             #       run this with that HERMES_HOME set to check it.\n"
        ),
    }
}

/// Merge ai-memory's entries into Droid's `hooks.json` (#1240), keeping
/// every other entry in it, idempotently.
///
/// Droid reads the `hooks` key of the `settings.json` beside it only while
/// `hooks.json` is absent, so creating the file over hooks kept there would
/// switch them off without a word. That case is refused with the two ways
/// out; an existing `hooks.json` is already the file Droid reads.
fn apply_to_droid_hooks(
    path: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    if !path.exists() {
        let settings = path.with_file_name("settings.json");
        if droid_settings_hold_hooks(&settings)? {
            anyhow::bail!(
                "{settings} keeps Droid hooks under its `hooks` key, and Droid reads those only \
                 while {path} does not exist, so creating {path} would switch them off. Either \
                 move that `hooks` object into {path} (the file holds the event map itself, \
                 with no `hooks` wrapper) and re-run this command, or add the entries \
                 `ai-memory install-hooks --agent droid` prints (without --apply) under \
                 the `hooks` key of {settings} yourself.",
                settings = settings.display(),
                path = path.display(),
            );
        }
    }
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_droid_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(|v| v.as_object())
        .context("internal: build_droid_hooks_payload didn't return a hooks object")?;
    let outcome = apply_atomic(path, |existing| {
        mutate_json(existing, |root| {
            for (event, value) in our_hooks {
                overlay_event_hooks(root, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    print!("{DROID_INSTALL_NOTES}");
    Ok(())
}

const DROID_INSTALL_NOTES: &str = "\
# NOTE: Droid adds SessionStart stdout to the session as context, so the
#       prior session's handoff is delivered automatically, and its own
#       SessionEnd closes the session.
# NOTE: start a new droid session for it to load the new hooks.
";

/// Whether Droid's `settings.json` holds hook entries under `hooks`, the
/// ones Droid reads while no `hooks.json` sits beside it. Parsed as JSONC
/// since a settings file may carry comments; one that cannot be parsed is
/// refused rather than guessed at.
fn droid_settings_hold_hooks(settings: &Path) -> Result<bool> {
    let text = match fs::read_to_string(settings) {
        Ok(text) => text,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(false),
        Err(e) => return Err(e).with_context(|| format!("reading {}", settings.display())),
    };
    let root: serde_json::Value = jsonc_parser::parse_to_ast(
        &text,
        &jsonc_parser::CollectOptions::default(),
        &jsonc_parser::ParseOptions::default(),
    )
    .map_err(|e| {
        anyhow::anyhow!(
            "parsing {} to check whether Droid hooks live there: {e}",
            settings.display()
        )
    })?
    .value
    .map_or(serde_json::Value::Null, Into::into);
    Ok(match root.get("hooks") {
        None | Some(serde_json::Value::Null) => false,
        Some(serde_json::Value::Object(hooks)) => !hooks.is_empty(),
        Some(_) => true,
    })
}

/// Print Droid's `hooks.json` event map (dry-run counterpart of
/// [`apply_to_droid_hooks`]).
fn render_droid(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_droid_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized =
        serde_json::to_string_pretty(&payload["hooks"]).context("serializing droid hook config")?;
    println!("# Factory Droid CLI hook config — merge into ~/.factory/hooks.json (the");
    println!("# file is this event map itself), or re-run with --apply to merge it in");
    println!("# place. If you keep hooks under the `hooks` key of ~/.factory/settings.json");
    println!("# instead, add these entries there: Droid reads settings.json hooks only");
    println!("# while hooks.json does not exist.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook command —");
        println!("#       treat the file as sensitive (chmod 600). `--apply` stores it");
        println!("#       under the data dir instead.");
    }
    print!("{DROID_INSTALL_NOTES}");
    println!();
    println!("{serialized}");
    Ok(())
}

/// Merge ai-memory's entries into the `hooks` key of CodeBuddy's
/// `settings.json`, keeping every other key and every other hook,
/// idempotently.
fn apply_to_codebuddy_settings(
    path: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_codebuddy_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: build_codebuddy_hooks_payload didn't return a hooks object")?;
    let outcome = apply_atomic(path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in the CodeBuddy settings.json but not an object")?;
            for (event, value) in our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    print!("{CODEBUDDY_INSTALL_NOTES}");
    Ok(())
}

const CODEBUDDY_INSTALL_NOTES: &str = "\
# NOTE: CodeBuddy appends SessionStart stdout (`hookSpecificOutput.additionalContext`)
#       to the session, so the prior session's handoff is delivered automatically.
# NOTE: start a new codebuddy session for it to load the new hooks.
";

/// Print the `hooks` block for `~/.codebuddy/settings.json` (dry-run
/// counterpart of [`apply_to_codebuddy_settings`]).
fn render_codebuddy(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_codebuddy_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized = serde_json::to_string_pretty(&payload["hooks"])
        .context("serializing codebuddy hook config")?;
    println!("# CodeBuddy Code hook config — merge under the `hooks` key of");
    println!("# ~/.codebuddy/settings.json, or re-run with --apply to merge it in");
    println!("# place.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook command —");
        println!("#       treat settings.json as sensitive (chmod 600). `--apply` stores it");
        println!("#       under the data dir instead.");
    }
    print!("{CODEBUDDY_INSTALL_NOTES}");
    println!();
    println!("{serialized}");
    Ok(())
}

fn apply_to_qoder_settings(
    path: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let payload = super::render_shared::build_qoder_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        args.project_strategy.and_then(ProjectStrategyArg::baked),
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: build_qoder_hooks_payload did not return a hooks object")?;
    let outcome = apply_atomic(path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in Qoder settings.json but not an object")?;
            for (event, value) in our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    print!("{QODER_INSTALL_NOTES}");
    Ok(())
}

const QODER_INSTALL_NOTES: &str = "\
# NOTE: Qoder injects SessionStart `hookSpecificOutput.additionalContext`, so
#       the prior session's handoff is delivered automatically.
# NOTE: restart Qoder after changing hooks; hook configuration is not hot-reloaded.
";

fn render_qoder(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_qoder_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized =
        serde_json::to_string_pretty(&payload["hooks"]).context("serializing Qoder hook config")?;
    println!("# Qoder hook config — merge under the `hooks` key of");
    println!("# ~/.qoder/settings.json, or re-run with --apply to merge it in place.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook command —");
        println!(
            "#       treat settings.json as sensitive. `--apply` stores it under the data dir instead."
        );
    }
    print!("{QODER_INSTALL_NOTES}");
    println!();
    println!("{serialized}");
    Ok(())
}

/// Merge ai-memory's entries into IBM Bob's global settings, preserving every
/// unrelated setting and hook. Bob IDE and Bob Shell both read this file.
fn apply_to_ibm_bob_settings(
    path: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_ibm_bob_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: IBM Bob payload did not return a hooks object")?;
    let outcome = apply_atomic(path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in IBM Bob settings.json but not an object")?;
            for (event, value) in our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    print!("{IBM_BOB_INSTALL_NOTES}");
    Ok(())
}

const IBM_BOB_INSTALL_NOTES: &str = "\
# NOTE: IBM Bob injects plain SessionStart stdout into the model context, so
#       the prior session's handoff is delivered automatically.
# NOTE: Bob exposes Stop but no SessionEnd; close a finished session with
#       `ai-memory finalize-session --agent ibm-bob`.
# NOTE: start a new Bob session for it to load the new hooks.
";

/// Print the `hooks` block for IBM Bob's global settings (dry-run counterpart
/// of [`apply_to_ibm_bob_settings`]).
fn render_ibm_bob(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_ibm_bob_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized = serde_json::to_string_pretty(&payload["hooks"])
        .context("serializing IBM Bob hook config")?;
    println!("# IBM Bob hook config — merge under the `hooks` key of");
    println!("# ~/.bob/settings/settings.json, or re-run with --apply to merge it in place.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook command —");
        println!("#       treat settings.json as sensitive (chmod 600). `--apply` stores it");
        println!("#       under the data dir instead.");
    }
    print!("{IBM_BOB_INSTALL_NOTES}");
    println!();
    println!("{serialized}");
    Ok(())
}

/// Merge ai-memory's entries into the `hooks` key of Qwen Code's
/// `settings.json`, keeping every other key and every other hook,
/// idempotently.
fn apply_to_qwen_code_settings(
    path: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_qwen_code_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: build_qwen_code_hooks_payload didn't return a hooks object")?;
    let outcome = apply_atomic(path, |existing| {
        mutate_json(existing, |root| {
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in the Qwen Code settings.json but not an object")?;
            for (event, value) in our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    print!("{QWEN_CODE_INSTALL_NOTES}");
    Ok(())
}

const QWEN_CODE_INSTALL_NOTES: &str = "\
# NOTE: Qwen Code injects SessionStart stdout (`hookSpecificOutput.additionalContext`)
#       into the session, so the prior session's handoff is delivered automatically.
# NOTE: start a new qwen session for it to load the new hooks.
";

/// Print the `hooks` block for `~/.qwen/settings.json` (dry-run counterpart
/// of [`apply_to_qwen_code_settings`]).
fn render_qwen_code(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_qwen_code_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized = serde_json::to_string_pretty(&payload["hooks"])
        .context("serializing qwen-code hook config")?;
    println!("# Qwen Code hook config — merge under the `hooks` key of");
    println!("# ~/.qwen/settings.json, or re-run with --apply to merge it in");
    println!("# place. MCP servers share this file under `mcpServers`.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook command —");
        println!("#       treat settings.json as sensitive (chmod 600). `--apply` stores it");
        println!("#       under the data dir instead.");
    }
    print!("{QWEN_CODE_INSTALL_NOTES}");
    println!();
    println!("{serialized}");
    Ok(())
}

/// Merge ai-memory's entries into the `hooks` key of Muse's `settings.json`,
/// keeping `schema_version`, every unknown key and every other hook in it,
/// idempotently, with a backup next to the file on change. Muse fails every
/// command at startup when the file has no `schema_version`, so a new file
/// gets `"schema_version": 1`; an existing value is never rewritten.
fn apply_to_muse_settings(
    path: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = super::render_shared::build_muse_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let our_hooks = payload
        .get("hooks")
        .and_then(serde_json::Value::as_object)
        .context("internal: build_muse_hooks_payload didn't return a hooks object")?;
    let outcome = apply_atomic(path, |existing| {
        mutate_json(existing, |root| {
            root.entry("schema_version")
                .or_insert_with(|| serde_json::Value::from(1));
            let hooks = root
                .entry("hooks")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`hooks` is present in the Muse settings.json but not an object")?;
            for (event, value) in our_hooks {
                overlay_event_hooks(hooks, event, value);
            }
            Ok(())
        })
    })?;
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    print!("{MUSE_INSTALL_NOTES}");
    Ok(())
}

const MUSE_INSTALL_NOTES: &str = "\
# NOTE: Muse adds SessionStart's additionalContext to the session, so the
#       prior session's handoff is delivered automatically, and its own
#       SessionEnd closes the session.
# NOTE: Muse runs hooks with a cleared environment, so the server URL and
#       data dir are baked into each command; re-run this command after
#       changing either. Start a new muse session to load the new hooks.
";

/// Print the `hooks` block for Muse's `settings.json` (dry-run counterpart of
/// [`apply_to_muse_settings`]).
fn render_muse(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    let payload = super::render_shared::build_muse_hooks_payload(
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let mut snippet = serde_json::Map::new();
    snippet.insert("schema_version".into(), serde_json::Value::from(1));
    snippet.insert("hooks".into(), payload["hooks"].clone());
    let serialized = serde_json::to_string_pretty(&serde_json::Value::Object(snippet))
        .context("serializing Muse hook config")?;
    println!("# Meta Muse Code hook config — merge the `hooks` entries into");
    println!("# ${{XDG_CONFIG_HOME:-~/.config}}/muse/settings.json, or re-run with --apply");
    println!("# to merge them in place. Keep \"schema_version\": 1: without it every");
    println!("# muse command fails at startup.");
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: this printed snippet embeds the token in each hook command —");
        println!("#       treat the file as sensitive (chmod 600). `--apply` stores it");
        println!("#       under the data dir instead.");
    }
    print!("{MUSE_INSTALL_NOTES}");
    println!();
    println!("{serialized}");
    Ok(())
}

fn render_devin(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    // Soft check (same rationale as render_claude_code): warn, don't bail,
    // so the docker host-path flow still works.
    for (_, script) in super::render_shared::DEVIN_EVENTS {
        let script = hook_script_for_claude_code(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    let payload = build_devin_payload_with_data_dir(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let serialized =
        serde_json::to_string_pretty(&payload).context("serializing devin hook config")?;
    println!(
        "# Devin CLI hook config — write to ~/.devin/hooks.v1.json or ~/.devin/config.json hooks key"
    );
    println!("# Hook scripts: {}", hooks_dir.display());
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");
        println!(
            "#       Treat ~/.devin/hooks.v1.json or ~/.devin/config.json as sensitive (chmod 600)."
        );
    }
    println!(
        "# NOTE: Devin consumes the handoff via hookSpecificOutput.additionalContext on SessionStart."
    );
    println!();
    println!("{serialized}");
    Ok(())
}

/// Print Kimi Code's `[[hooks]]` TOML fragment to stdout (dry-run
/// counterpart of [`apply_to_kimi_code_config`]). Rendered through the
/// same upsert path the apply mode uses, so the printout is byte-for-
/// byte what `--apply` would append to config.toml.
fn render_kimi_code(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    // Soft check (same rationale as render_claude_code): warn, don't bail,
    // so the docker host-path flow still works.
    for (_, script) in KIMI_CODE_EVENTS {
        let script = hook_script_for_current_platform(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    let commands = kimi_code_hook_commands(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let mut doc = toml_edit::DocumentMut::new();
    upsert_kimi_code_hooks(&mut doc, &commands)?;
    println!("# Kimi Code hook config — merge into $KIMI_CODE_HOME/config.toml");
    println!("# (~/.kimi-code/config.toml when KIMI_CODE_HOME is unset), or re-run");
    println!("# with --apply to merge it in place, preserving providers/model and");
    println!("# any third-party [[hooks]] entries already in the file.");
    println!("# Hook scripts: {}", hooks_dir.display());
    println!("# AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");
        println!("#       Treat config.toml as sensitive (chmod 600).");
    }
    println!();
    print!("{doc}");
    Ok(())
}

fn render_kiro_cli(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    // Soft check (same rationale as render_claude_code): warn, don't bail,
    // so the docker host-path flow still works.
    for (_, script) in KIRO_CLI_V2_EVENTS {
        let script = hook_script_for_current_platform(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    let hooks = build_kiro_cli_v2_hooks_value(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    println!("// Kiro CLI v2-engine hooks — merge the \"hooks\" object into each");
    println!("// agent config under $KIRO_HOME/agents (~/.kiro/agents when unset),");
    println!("// or re-run with --apply to merge into every existing agent config,");
    println!("// preserving third-party hook entries. The v2 engine fires hooks");
    println!("// only for the active agent config; the built-in default agent has");
    println!("// no file, so create one first (`kiro-cli agent create`). Do not reuse");
    println!("// this v2 registration for v3; use `--agent kiro-cli-v3` instead.");
    println!("// Hook scripts: {}", hooks_dir.display());
    println!("// AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("// Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");
        println!("//       Treat agent configs as sensitive (chmod 600).");
    }
    println!();
    println!(
        "{}",
        serde_json::to_string_pretty(&serde_json::json!({ "hooks": hooks }))
            .expect("static hook payload serializes")
    );
    Ok(())
}

fn render_kiro_cli_v3(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    for (_, script) in KIRO_CLI_V3_EVENTS {
        let abs = hooks_dir.join(hook_script_for_current_platform(script).as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. If this command is running \
                 inside docker against a host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    let payload = build_kiro_cli_v3_hooks_value(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    println!("// Kiro CLI v3 hooks — write this document to");
    println!("// $KIRO_HOME/hooks/ai-memory.json (~/.kiro/hooks/ai-memory.json when unset),");
    println!("// or re-run with --apply for an atomic, idempotent merge.");
    println!("// Hook scripts: {}", hooks_dir.display());
    println!("// AI-memory server URL: {server_url}");
    if auth_token.is_some() {
        println!("// Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");
        println!("//       Treat the hook file as sensitive (chmod 600).");
    }
    println!();
    println!(
        "{}",
        serde_json::to_string_pretty(&payload).expect("static hook payload serializes")
    );
    Ok(())
}

/// Print Pool's `.poolside/settings.yaml` `hooks:` block to stdout. Pool's
/// hook config lives at the root of each repository the agent runs in, so
/// there is no user-global file for an atomic merge — the snippet is pasted
/// per project. `--apply` still stages the scripts to the stable user-global
/// location first so the printed commands reference paths that outlive the
/// source checkout / docker image (see [`apply_to_pool`]).
fn render_pool(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    // Soft check (same rationale as render_claude_code): warn, don't bail,
    // so the docker host-path flow still works.
    for (_, script) in POOL_EVENTS {
        let script = hook_script_for_current_platform(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    print!(
        "{}",
        render_pool_output(
            hooks_dir,
            server_url,
            auth_token,
            data_dir,
            project_strategy
        )
    );
    Ok(())
}

fn render_pool_output(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> String {
    let snippet = build_pool_settings_yaml_with_data_dir(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let mut out = String::new();
    out.push_str("# Pool (Poolside Agent CLI) hook config — merge into the repo-root\n");
    out.push_str("# .poolside/settings.yaml of each project Pool runs in. ai-memory\n");
    out.push_str("# does not write committed project files, so paste this snippet manually\n");
    out.push_str("# (re-run with --apply first to stage the scripts to a stable path).\n");
    out.push_str(&format!("# Hook scripts: {}\n", hooks_dir.display()));
    out.push_str(&format!("# AI-memory server URL: {server_url}\n"));
    if auth_token.is_some() {
        out.push_str("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.\n");
        out.push_str("#       Treat .poolside/settings.yaml as sensitive (chmod 600).\n");
    }
    out.push_str("# NOTE: Pool's SessionStart stdout injection is not demonstrated —\n");
    out.push_str("#       capture works, but handoff injection does not. Recover a prior\n");
    out.push_str("#       session's handoff via the MCP `memory_handoff_accept` tool.\n");
    out.push_str("# NOTE: Pool has no true session-end event; `Stop` is a turn boundary.\n");
    out.push_str(
        "#       Close a finished session with `ai-memory finalize-session --agent pool`.\n",
    );
    out.push('\n');
    out.push_str(&snippet);
    out
}

/// `--apply` for Pool: stage the hook scripts to the stable user-global
/// location (the same step every other script agent's apply performs), then
/// print the ready-to-paste snippet pointing at the staged copies. The
/// project-local `.poolside/settings.yaml` itself is deliberately NOT
/// written: install-hooks is a user-scoped operation and must not mutate
/// files inside the user's repositories.
fn apply_to_pool(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "pool", data_dir)?;
    let command_dir = staged_command_dir(&staged, "pool");
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    print!(
        "{}",
        render_pool_output(&command_dir, server_url, auth_token, data_dir, strategy)
    );
    Ok(())
}

pub(crate) const CLINE_HOOK_EVENTS: [(&str, &str); 9] = [
    ("TaskStart", "session-start"),
    ("TaskResume", "session-start"),
    ("UserPromptSubmit", "user-prompt"),
    ("PreToolUse", "pre-tool-use"),
    ("PostToolUse", "post-tool-use"),
    ("TaskComplete", "stop"),
    ("TaskCancel", "stop"),
    ("TaskError", "stop"),
    ("SessionShutdown", "session-end"),
];

pub(crate) fn cline_hooks_path_in(home: Option<std::ffi::OsString>) -> Result<PathBuf> {
    let home = home
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
        .or_else(home_dir)
        .context("could not locate $HOME for ~/.cline/hooks")?;
    Ok(home.join(".cline").join("hooks"))
}

fn cline_hooks_target(args: &InstallHooksArgs) -> Result<PathBuf> {
    if let Some(path) = &args.config_file {
        return Ok(path.clone());
    }
    match args.scope {
        HookInstallScope::Global => cline_hooks_path_in(std::env::var_os("HOME")),
        HookInstallScope::Project => Ok(std::env::current_dir()
            .context("could not resolve current dir for project Cline hooks")?
            .join(".cline")
            .join("hooks")),
    }
}

fn posix_single_quote(value: &str) -> String {
    format!("'{}'", value.replace('\'', "'\"'\"'"))
}

fn powershell_single_quote(value: &str) -> String {
    format!("'{}'", value.replace('\'', "''"))
}

fn cline_hook_argv(
    event: &str,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Vec<String> {
    let mut argv = vec![
        "ai-memory".to_string(),
        "--data-dir".to_string(),
        data_dir.to_string_lossy().into_owned(),
        "hook".to_string(),
        "--event".to_string(),
        event.to_string(),
        "--agent".to_string(),
        "cline".to_string(),
        "--server-url".to_string(),
        server_url.to_string(),
        "--capture-mode".to_string(),
        capture_mode.to_string(),
    ];
    if let Some(token) = auth_token {
        argv.extend(["--auth-token".to_string(), token.to_string()]);
    }
    if let Some(strategy) = args.project_strategy.and_then(ProjectStrategyArg::baked) {
        argv.extend(["--project-strategy".to_string(), strategy.to_string()]);
    }
    argv
}

fn render_cline_hook_script(argv: &[String], windows: bool) -> String {
    if windows {
        let command = argv
            .iter()
            .map(|word| powershell_single_quote(word))
            .collect::<Vec<_>>()
            .join(" ");
        format!(
            "# Generated by ai-memory install-hooks --agent cline.\n\
             $ProgressPreference = 'SilentlyContinue'\n\
             & {command}\n\
             exit $LASTEXITCODE\n"
        )
    } else {
        let command = argv
            .iter()
            .map(|word| posix_single_quote(word))
            .collect::<Vec<_>>()
            .join(" ");
        format!(
            "#!/bin/sh\n# Generated by ai-memory install-hooks --agent cline.\nexec {command}\n"
        )
    }
}

fn render_cline_hooks(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Result<()> {
    let target = cline_hooks_target(args)?;
    let extension = if cfg!(windows) { "ps1" } else { "sh" };
    println!("# Cline CLI hook files ({})", target.display());
    println!("# Restart Cline after installing. Cline's yolo mode disables hooks.");
    println!("# TaskStart/TaskResume run detached, so accept pending handoffs through MCP.");
    if auth_token.is_some() {
        println!(
            "# The applied files contain the bearer token and are owner-only; preview redacts it."
        );
    }
    for (name, event) in CLINE_HOOK_EVENTS {
        let preview_token = auth_token.map(|_| "<redacted>");
        let argv = cline_hook_argv(
            event,
            server_url,
            preview_token,
            data_dir,
            args,
            capture_mode,
        );
        println!(
            "\n# {}.{}\n{}",
            name,
            extension,
            render_cline_hook_script(&argv, cfg!(windows))
        );
    }
    Ok(())
}

fn apply_to_cline_hooks(
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
    capture_mode: &str,
) -> Result<()> {
    let target = cline_hooks_target(args)?;
    fs::create_dir_all(&target)
        .with_context(|| format!("creating Cline hooks directory {}", target.display()))?;
    let extension = if cfg!(windows) { "ps1" } else { "sh" };
    let mut rendered = Vec::with_capacity(CLINE_HOOK_EVENTS.len());
    for (name, event) in CLINE_HOOK_EVENTS {
        let path = target.join(format!("{name}.{extension}"));
        if fs::symlink_metadata(&path).is_ok_and(|metadata| metadata.file_type().is_symlink()) {
            anyhow::bail!(
                "refusing to replace symlinked Cline hook {}",
                path.display()
            );
        }
        let argv = cline_hook_argv(event, server_url, auth_token, data_dir, args, capture_mode);
        let content = render_cline_hook_script(&argv, cfg!(windows));
        match fs::read_to_string(&path) {
            Ok(existing)
                if !existing.contains("Generated by ai-memory install-hooks --agent cline") =>
            {
                anyhow::bail!(
                    "refusing to replace user-owned Cline hook {}; move it aside or combine it manually",
                    path.display()
                );
            }
            Ok(_) => {}
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(error) => {
                return Err(error).with_context(|| format!("reading {}", path.display()));
            }
        }
        rendered.push((name, path, content));
    }

    for (name, path, content) in rendered {
        let backup = PrivateBackup {
            dir: data_dir.join("backups").join("cline-hooks"),
            stem: format!("cline-{name}"),
        };
        let outcome = apply_atomic_with_backup(&path, Some(&backup), |existing| {
            if !existing.is_empty()
                && !existing.contains("Generated by ai-memory install-hooks --agent cline")
            {
                anyhow::bail!(
                    "refusing to replace user-owned Cline hook {}; move it aside or combine it manually",
                    path.display()
                );
            }
            Ok(content.clone())
        })?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            fs::set_permissions(&path, fs::Permissions::from_mode(0o700))?;
        }
        eprintln!("✓ {} {}", outcome.verb(), path.display());
    }
    println!("Restart Cline so it reloads the hook directory.");
    println!("Cline yolo mode disables hooks; lifecycle capture is unavailable in that mode.");
    Ok(())
}

/// Print DSH's generated Claude Code `hooks.json` plus the Cordis patch
/// fragment that points the official `@deepseek-ai/dsh-hooks-claude-code`
/// bridge at it. DSH has no fixed agent config file, so merging the patch
/// into `$DSH_HOME/profiles/<profile>/cordis.patch.yml` is the operator's
/// step; `--apply` stages the scripts and materializes the `hooks.json`
/// first (see [`apply_to_dsh`]).
fn render_dsh(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> Result<()> {
    // Soft check (same rationale as render_claude_code): warn, don't bail,
    // so the docker host-path flow still works.
    for (_, script) in DSH_EVENTS {
        let script = hook_script_for_current_platform(script);
        let abs = hooks_dir.join(script.as_ref());
        if !abs.exists() {
            eprintln!(
                "# warning: {} not present on this filesystem. \
                 If this command is running inside docker against a \
                 host path, you can ignore this; otherwise extract \
                 the scripts first with `ai-memory setup-agent`.",
                abs.display()
            );
        }
    }
    print!(
        "{}",
        render_dsh_output(
            hooks_dir,
            server_url,
            auth_token,
            data_dir,
            project_strategy
        )
    );
    Ok(())
}

fn render_dsh_output(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    project_strategy: Option<&str>,
) -> String {
    let payload = build_dsh_hooks_payload(
        hooks_dir,
        server_url,
        auth_token,
        Some(data_dir),
        project_strategy,
    );
    let mut out = String::new();
    out.push_str("# DeepSeek Harness (DSH) hook config - DSH has no fixed agent\n");
    out.push_str("# config file. ai-memory stages the hook scripts and generates a\n");
    out.push_str("# Claude Code `hooks.json`; the official\n");
    out.push_str("# `@deepseek-ai/dsh-hooks-claude-code` bridge reads it via its\n");
    out.push_str("# `configPath`. Re-run with --apply first to stage the scripts\n");
    out.push_str("# and materialize the hooks.json at a stable path.\n");
    out.push_str(&format!("# Hook scripts: {}\n", hooks_dir.display()));
    out.push_str(&format!("# AI-memory server URL: {server_url}\n"));
    if auth_token.is_some() {
        out.push_str("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.\n");
        out.push_str("#       Treat the hook config as sensitive (chmod 600).\n");
    }
    out.push_str("# NOTE: the bridge delivers exactly these seven events - no\n");
    out.push_str("#       PreCompact or SessionEnd, and SessionStart runs detached,\n");
    out.push_str("#       so capture works but handoff injection does not. Recover a\n");
    out.push_str("#       prior session's handoff via the MCP `memory_handoff_accept`\n");
    out.push_str("#       tool, and close a finished session with\n");
    out.push_str("#       `ai-memory finalize-session --agent dsh`.\n");
    out.push('\n');
    out.push_str(&serde_json::to_string_pretty(&payload).expect("static hook payload serializes"));
    out.push_str("\n\n");
    out.push_str(&dsh_bridge_patch_fragment(hooks_dir));
    out
}

/// `--apply` for DSH: stage the hook scripts to the stable user-global
/// location, materialize the generated `hooks.json` next to them, then print
/// the Cordis patch fragment pointing the bridge at that file. DSH's
/// `$DSH_HOME/profiles/<profile>/cordis.patch.yml` is a hand-maintained YAML
/// patch layer (it can hold `!!js` expressions and unrelated plugin rows), so
/// the merge is deliberately left to the operator - the same reason
/// `install-mcp --client dsh` refuses to write MCP config.
fn apply_to_dsh(
    hooks_dir: &Path,
    server_url: &str,
    auth_token: Option<&str>,
    data_dir: &Path,
    args: &InstallHooksArgs,
) -> Result<()> {
    let staged = stage_hook_scripts(hooks_dir, "dsh", data_dir)?;
    let command_dir = staged_command_dir(&staged, "dsh");
    fs::create_dir_all(&command_dir)
        .with_context(|| format!("creating hook staging dir {}", command_dir.display()))?;
    let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);
    let payload = build_dsh_hooks_payload(
        &command_dir,
        server_url,
        auth_token,
        Some(data_dir),
        strategy,
    );
    let hooks_json = command_dir.join("hooks.json");
    write_private_dsh_config(
        &hooks_json,
        serde_json::to_string_pretty(&payload)
            .expect("static hook payload serializes")
            .as_bytes(),
    )?;
    eprintln!("✓ wrote DSH hook config → {}", hooks_json.display());
    print!("{}", dsh_bridge_patch_fragment(&command_dir));
    Ok(())
}

/// DSH's generated hook config can embed the server bearer. Keep it private
/// from the first byte and refuse a final-component symlink instead of
/// following an attacker-controlled target.
fn write_private_dsh_config(path: &Path, content: &[u8]) -> Result<()> {
    let mut options = fs::OpenOptions::new();
    options.write(true).create(true).truncate(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt as _;
        options.mode(0o600).custom_flags(libc::O_NOFOLLOW);
    }

    let mut file = options
        .open(path)
        .with_context(|| format!("opening private DSH hook config {}", path.display()))?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt as _;
        file.set_permissions(fs::Permissions::from_mode(0o600))
            .with_context(|| format!("securing DSH hook config {}", path.display()))?;
    }
    file.write_all(content)
        .with_context(|| format!("writing {}", path.display()))?;
    file.sync_all()
        .with_context(|| format!("syncing {}", path.display()))
}

/// The Cordis patch-list fragment that mounts the
/// `@deepseek-ai/dsh-hooks-claude-code` bridge with `configPath` pointing at
/// the generated `hooks.json` in `command_dir`. Shared by `install-hooks`
/// and `setup-agent`.
pub(crate) fn dsh_bridge_patch_fragment(command_dir: &Path) -> String {
    let config_path = command_dir.join("hooks.json");
    let mut out = String::new();
    out.push_str("# DeepSeek Harness (DSH) - merge the entry below into the DSH\n");
    out.push_str("# profile patch at $DSH_HOME/profiles/<profile>/cordis.patch.yml,\n");
    out.push_str("# then reload or restart the profile (the web profile reloads live).\n");
    out.push_str("#\n");
    out.push_str("# The bridge runs the staged ai-memory hooks; a new top-level\n");
    out.push_str("# - insert: item is fine - patch row order carries no load semantics.\n");
    out.push_str("- insert:\n");
    out.push_str("    - id: ai-memory-hooks\n");
    out.push_str("      name: '@deepseek-ai/dsh-hooks-claude-code'\n");
    out.push_str("      config:\n");
    out.push_str(&format!(
        "        configPath: {}\n",
        yaml_single_quote(&config_path.to_string_lossy())
    ));
    out
}

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

    /// The marker-presence admit gate the shared `ts_capture_policy_v1`
    /// template bakes into `capturePolicy` (#661). Under allowlist a
    /// repository with no `.ai-memory.toml` marker must emit nothing —
    /// mirroring `repository_admits_capture` in
    /// `ai-memory-hooks::capture_policy`, the gate hook.rs's native path
    /// runs before any per-event disposition. Keyed on `findMarker(cwd)`
    /// presence rather than `config.state`, so a marker with an empty
    /// `[capture]` section — `state` is "inactive" either way — still admits
    /// capture.
    const CAPTURE_ADMIT_GATE_TS: &str = "const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === \"allowlist\" && !markerPresent) return { disposition: \"drop\", payload };";

    /// #446's binding requirement: "a protection that disappears on upgrade
    /// without saying so is worse than no protection". A bare `--apply` — what
    /// `ai-memory upgrade` runs — must leave an existing opt-in alone.
    #[test]
    fn bare_apply_preserves_an_existing_allowlist_optin() {
        let tmp = tempfile::tempdir().unwrap();
        let mode = persist_capture_mode(tmp.path(), Some(CaptureModeArg::Allowlist)).unwrap();
        assert_eq!(mode, "allowlist");

        // The upgrade path: no flag at all.
        let after = persist_capture_mode(tmp.path(), None).unwrap();
        assert_eq!(
            after, "allowlist",
            "a bare re-apply must not revert the opt-in"
        );
        assert_eq!(
            fs::read_to_string(tmp.path().join(crate::commands::hook::CAPTURE_MODE_FILE))
                .unwrap()
                .trim(),
            "allowlist"
        );
    }

    /// #446's opt-in is stored as a bare word, and every reader maps anything
    /// it does not recognise onto `denylist` — the *less* private mode. That
    /// fallback is deliberate and tested
    /// (`hook.rs`: `unreadable_or_unknown_mode_falls_back_to_denylist_not_allowlist`);
    /// what must never happen is the truncated file that triggers it. An
    /// in-place write truncates before it writes, so a crash, a full disk or a
    /// killed `upgrade` mid-write leaves exactly that — and the next hook run
    /// reads it as capture-by-default, silently undoing the opt-in the doc
    /// comment on `persist_capture_mode` promises to preserve.
    ///
    /// Replacement rather than truncation is the property that rules the window
    /// out, and it is observable: a rename gives the path a new inode, an
    /// in-place rewrite keeps the old one. This fails against `fs::write`.
    #[cfg(unix)]
    #[test]
    fn rewriting_the_capture_mode_replaces_the_file_rather_than_truncating_it() {
        use std::os::unix::fs::MetadataExt;

        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join(crate::commands::hook::CAPTURE_MODE_FILE);

        persist_capture_mode(tmp.path(), Some(CaptureModeArg::Allowlist)).unwrap();
        let before = fs::metadata(&path).unwrap().ino();

        persist_capture_mode(tmp.path(), Some(CaptureModeArg::Denylist)).unwrap();
        let after = fs::metadata(&path).unwrap().ino();

        assert_ne!(
            before, after,
            "the capture mode must be replaced by rename, not rewritten in \
             place: an in-place write is observable truncated, and a truncated \
             file reads back as denylist"
        );

        let leftovers: Vec<String> = fs::read_dir(tmp.path())
            .unwrap()
            .flatten()
            .map(|entry| entry.file_name().to_string_lossy().into_owned())
            .filter(|name| name.starts_with(".ai-memory-tmp."))
            .collect();
        assert!(
            leftovers.is_empty(),
            "the staging tempfile must not survive the write: {leftovers:?}"
        );
    }

    #[test]
    fn absent_file_reports_the_historical_default() {
        let tmp = tempfile::tempdir().unwrap();
        assert_eq!(persist_capture_mode(tmp.path(), None).unwrap(), "denylist");
    }

    #[test]
    fn explicit_denylist_downgrades_an_earlier_optin() {
        // The opt-in must be reversible, or operators cannot undo a mistake.
        let tmp = tempfile::tempdir().unwrap();
        persist_capture_mode(tmp.path(), Some(CaptureModeArg::Allowlist)).unwrap();
        assert_eq!(
            persist_capture_mode(tmp.path(), Some(CaptureModeArg::Denylist)).unwrap(),
            "denylist"
        );
        assert_eq!(persist_capture_mode(tmp.path(), None).unwrap(), "denylist");
    }
    use crate::cli::ProjectStrategyArg;
    use crate::commands::render_shared::KIRO_CLI_V2_SESSION_START_MAX_OUTPUT;
    use std::collections::BTreeMap;
    use std::fs;
    #[cfg(any(unix, windows))]
    use std::process::Command;
    use tempfile::TempDir;

    #[test]
    fn capture_assistant_allowed_only_for_supported_native_agents() {
        use crate::cli::AgentChoice::*;
        // Every agent that cannot honor the opt-in is rejected regardless of
        // platform (#196): the installer must bail rather than enable it silently.
        for agent in [
            CommandCode,
            Cursor,
            GeminiCli,
            OpenCode,
            Pi,
            Omp,
            Openclaw,
            AntigravityCli,
            Grok,
            Zero,
            Devin,
            KimiCode,
            KiroCli,
            KiroCliV3,
            Pool,
            Zcode,
            CopilotCli,
        ] {
            assert!(
                !capture_assistant_allowed(agent),
                "{agent:?} must not allow --capture-assistant"
            );
        }
        // Claude Code and Codex (#743) both carry last_assistant_message on Stop
        // and track the native-platform gate exactly.
        assert_eq!(
            capture_assistant_allowed(ClaudeCode),
            local_hook_policy_v1_supported()
        );
        assert_eq!(
            capture_assistant_allowed(Codex),
            local_hook_policy_v1_supported()
        );
        assert_eq!(
            capture_assistant_allowed(OpenCode2),
            local_hook_policy_v1_supported()
        );
    }

    #[test]
    fn prompt_capture_options_are_claude_code_only() {
        use crate::cli::AgentChoice::*;
        assert!(prompt_capture_options_allowed(ClaudeCode));
        for agent in [
            Codex,
            CommandCode,
            Cursor,
            GeminiCli,
            OpenCode,
            Pi,
            Omp,
            Openclaw,
            AntigravityCli,
            Grok,
            Zero,
            Devin,
            KimiCode,
            KiroCli,
            KiroCliV3,
            Pool,
            Zcode,
        ] {
            assert!(!prompt_capture_options_allowed(agent), "{agent:?}");
        }
    }

    #[test]
    fn baked_prompt_capture_reads_only_owned_claude_hooks() {
        let enabled = serde_json::json!({
            "hooks": {
                "SessionStart": [{ "hooks": [{ "command": "ai-memory hook --event session-start --agent claude-code --server-url http://h" }] }],
                "UserPromptSubmit": [{ "hooks": [{ "command": "ai-memory hook --event user-prompt --agent claude-code --server-url http://h" }] }]
            }
        });
        assert_eq!(
            baked_claude_prompt_capture(&enabled.to_string()),
            Some(true)
        );

        let disabled = serde_json::json!({
            "hooks": {
                "SessionStart": [{ "hooks": [{ "command": "ai-memory hook --event session-start --agent claude-code --server-url http://h" }] }],
                "UserPromptSubmit": [{ "hooks": [{ "command": "third-party prompt guard" }] }]
            }
        });
        assert_eq!(
            baked_claude_prompt_capture(&disabled.to_string()),
            Some(false)
        );

        let unrelated = serde_json::json!({
            "hooks": {
                "UserPromptSubmit": [{ "hooks": [{ "command": "third-party prompt guard" }] }]
            }
        });
        assert_eq!(baked_claude_prompt_capture(&unrelated.to_string()), None);
    }

    #[cfg(unix)]
    fn bash_program_for_installer_test() -> Option<std::path::PathBuf> {
        Some(std::path::PathBuf::from("bash"))
    }

    #[cfg(windows)]
    fn bash_program_for_installer_test() -> Option<std::path::PathBuf> {
        let mut candidates = Vec::new();
        if let Some(root) = std::env::var_os("EXEPATH") {
            let root = std::path::PathBuf::from(root);
            candidates.push(root.join("bin").join("bash.exe"));
            candidates.push(root.join("usr").join("bin").join("bash.exe"));
        }
        for env_key in ["ProgramFiles", "ProgramW6432", "ProgramFiles(x86)"] {
            if let Some(root) = std::env::var_os(env_key) {
                let root = std::path::PathBuf::from(root).join("Git");
                candidates.push(root.join("bin").join("bash.exe"));
                candidates.push(root.join("usr").join("bin").join("bash.exe"));
            }
        }
        candidates.sort();
        candidates.dedup();
        let found = candidates.into_iter().find(|candidate| candidate.is_file());
        if found.is_none() {
            eprintln!("skipping installer shell contract: Git for Windows bash.exe was not found");
        }
        found
    }

    #[test]
    fn overlay_event_hooks_preserves_third_party_and_replaces_own() {
        // Regression for issue #80: install-hooks must MERGE into the event
        // array, not replace it. A third-party SessionStart hook (e.g.
        // context-mode) must survive while our own stale entry is swapped
        // for the fresh one.
        let mut hooks = serde_json::Map::new();
        hooks.insert(
            "SessionStart".into(),
            serde_json::json!([
                { "hooks": [ { "type": "command", "command": "node context-mode-cache-heal.mjs" } ] },
                { "matcher": "", "hooks": [ { "type": "command", "command": "/old/ai-memory.exe hook --event session-start --agent claude-code --server-url http://old" } ] }
            ]),
        );
        let ours = serde_json::json!([
            { "matcher": "", "hooks": [ { "type": "command", "command": "/new/.cargo/bin/ai-memory.exe hook --event session-start --agent claude-code --server-url http://new" } ] }
        ]);
        overlay_event_hooks(&mut hooks, "SessionStart", &ours);

        let arr = hooks["SessionStart"].as_array().unwrap();
        assert_eq!(
            arr.len(),
            2,
            "third-party + our single fresh entry: {arr:?}"
        );
        let joined = serde_json::to_string(arr).unwrap();
        assert!(
            joined.contains("context-mode-cache-heal"),
            "third-party hook must survive"
        );
        assert!(
            !joined.contains("/old/ai-memory.exe"),
            "stale ai-memory entry must be replaced"
        );
        assert!(
            joined.contains("/new/.cargo/bin/ai-memory.exe"),
            "fresh ai-memory entry must be present"
        );
    }

    #[test]
    fn command_code_apply_uses_only_stable_events_and_preserves_user_settings() {
        let source = TempDir::new().unwrap();
        stub_scripts(
            source.path(),
            &[
                "session-start.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "stop.sh",
            ],
        );
        let staging_root = TempDir::new().unwrap();
        // A real data dir ends in `ai-memory`; the entry-matching below keys
        // off that, so inject a realistic one rather than a bare temp path.
        let staging = staging_root.path().join("ai-memory");
        let config_dir = TempDir::new().unwrap();
        let config_path = config_dir.path().join("settings.json");
        fs::write(
            &config_path,
            serde_json::json!({
                "theme": "dark",
                "hooks": {
                    "SessionStart": [{
                        "hooks": [{"type": "command", "command": "third-party"}]
                    }]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::CommandCode,
            config_file: Some(config_path.clone()),
            ..default_hook_args()
        };

        apply_to_command_code_settings_in(
            source.path(),
            "http://memory:49374",
            Some("token"),
            config_dir.path(),
            &staging,
            &args,
        )
        .unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_command_code_settings_in(
            source.path(),
            "http://memory:49374",
            Some("token"),
            config_dir.path(),
            &staging,
            &args,
        )
        .unwrap();
        let second = fs::read_to_string(&config_path).unwrap();
        assert_eq!(first, second, "re-apply must be idempotent");

        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(value["theme"], "dark");
        let hooks = value["hooks"].as_object().unwrap();
        for event in ["SessionStart", "PreToolUse", "PostToolUse", "Stop"] {
            let entries = hooks[event].as_array().unwrap();
            let ours = entries
                .iter()
                .find(|entry| serde_json::to_string(entry).unwrap().contains("ai-memory"))
                .unwrap_or_else(|| panic!("missing ai-memory entry for {event}"));
            assert!(ours.get("matcher").is_none(), "event: {event}");
        }
        assert_eq!(
            hooks["SessionStart"]
                .as_array()
                .unwrap()
                .iter()
                .filter(|entry| serde_json::to_string(entry)
                    .unwrap()
                    .contains("third-party"))
                .count(),
            1,
            "third-party hook must survive"
        );
        assert_eq!(hooks.len(), COMMAND_CODE_PROFILE.events.len());
    }

    #[test]
    fn copilot_cli_apply_uses_claude_compatible_events_and_preserves_user_settings() {
        let source = TempDir::new().unwrap();
        stub_scripts(
            source.path(),
            &[
                "session-start.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
                "session-end.sh",
                "subagent-start.sh",
                "subagent-stop.sh",
            ],
        );
        let staging_root = TempDir::new().unwrap();
        let staging = staging_root.path().join("ai-memory");
        let config_dir = TempDir::new().unwrap();
        let config_path = config_dir.path().join("ai-memory.json");
        fs::write(
            &config_path,
            serde_json::json!({
                "hooks": {
                    "SessionStart": [{"type": "command", "command": "third-party"}]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::CopilotCli,
            config_file: Some(config_path.clone()),
            ..default_hook_args()
        };

        apply_to_copilot_cli_hooks_in(
            source.path(),
            "http://memory:49374",
            Some("token"),
            config_dir.path(),
            &staging,
            &args,
        )
        .unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_copilot_cli_hooks_in(
            source.path(),
            "http://memory:49374",
            Some("token"),
            config_dir.path(),
            &staging,
            &args,
        )
        .unwrap();
        let second = fs::read_to_string(&config_path).unwrap();
        assert_eq!(first, second, "re-apply must be idempotent");

        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(value["version"], 1, "Copilot CLI requires version: 1");
        let hooks = value["hooks"].as_object().unwrap();
        for (event, _) in COPILOT_CLI_PROFILE.events {
            let entries = hooks[*event].as_array().unwrap();
            let ours = entries
                .iter()
                .find(|entry| serde_json::to_string(entry).unwrap().contains("ai-memory"))
                .unwrap_or_else(|| panic!("missing ai-memory entry for {event}"));
            // Flat entry: the handler sits directly in the event array.
            assert_eq!(ours["type"], "command", "event: {event}");
            assert!(ours["command"].is_string(), "event: {event}");
            assert!(ours.get("hooks").is_none(), "event: {event}");
            assert!(
                ours.get("matcher").is_none(),
                "Copilot CLI rejects matcher on several events, so it must never be present \
                 (event: {event})"
            );
        }
        assert_eq!(
            hooks["SessionStart"]
                .as_array()
                .unwrap()
                .iter()
                .filter(|entry| serde_json::to_string(entry)
                    .unwrap()
                    .contains("third-party"))
                .count(),
            1,
            "third-party hook must survive"
        );
        // PostToolUseFailure reuses post-tool-use.sh, same script as
        // PostToolUse, but is still its own distinct event key.
        assert_eq!(hooks["PostToolUseFailure"], hooks["PostToolUse"].clone());
    }

    #[test]
    fn overlay_event_hooks_inserts_when_event_absent() {
        let mut hooks = serde_json::Map::new();
        let ours = serde_json::json!([
            { "matcher": "", "hooks": [ { "type": "command", "command": "ai-memory.exe hook --event stop --agent claude-code --server-url http://h" } ] }
        ]);
        overlay_event_hooks(&mut hooks, "Stop", &ours);
        assert_eq!(hooks["Stop"].as_array().unwrap().len(), 1);
    }

    /// A user hook added to the same matcher group as ours (what Claude
    /// Code's /hooks UI does for a matching matcher) survives a re-apply:
    /// only our inner command is replaced, as `uninstall` already does.
    #[test]
    fn overlay_event_hooks_keeps_third_party_hook_sharing_our_matcher_group() {
        let mut hooks = serde_json::Map::new();
        hooks.insert(
            "SessionStart".into(),
            serde_json::json!([
                { "matcher": "", "hooks": [
                    { "type": "command", "command": "/old/ai-memory hook --event session-start --agent claude-code --server-url http://old" },
                    { "type": "command", "command": "node my-own-hook.mjs" }
                ] }
            ]),
        );
        let ours = serde_json::json!([
            { "matcher": "", "hooks": [ { "type": "command", "command": "/new/ai-memory hook --event session-start --agent claude-code --server-url http://new" } ] }
        ]);
        overlay_event_hooks(&mut hooks, "SessionStart", &ours);
        overlay_event_hooks(&mut hooks, "SessionStart", &ours);
        let joined = serde_json::to_string(&hooks["SessionStart"]).unwrap();
        assert!(joined.contains("my-own-hook.mjs"), "{joined}");
        assert!(!joined.contains("/old/ai-memory"), "{joined}");
        assert_eq!(joined.matches("/new/ai-memory").count(), 1, "{joined}");

        remove_ai_memory_event_hooks(&mut hooks, "SessionStart");
        let joined = serde_json::to_string(&hooks["SessionStart"]).unwrap();
        assert!(joined.contains("my-own-hook.mjs"), "{joined}");
        assert!(!joined.contains("ai-memory"), "{joined}");
    }

    #[test]
    fn overlay_event_hooks_is_idempotent_on_reapply() {
        // Re-applying must not accumulate duplicate ai-memory entries.
        let mut hooks = serde_json::Map::new();
        let ours = serde_json::json!([
            { "matcher": "", "hooks": [ { "type": "command", "command": "ai-memory.exe hook --event pre-tool-use --agent claude-code --server-url http://h" } ] }
        ]);
        overlay_event_hooks(&mut hooks, "PreToolUse", &ours);
        overlay_event_hooks(&mut hooks, "PreToolUse", &ours);
        assert_eq!(
            hooks["PreToolUse"].as_array().unwrap().len(),
            1,
            "no duplicates on re-apply"
        );
    }

    #[test]
    fn is_ai_memory_hook_entry_detects_nested_flat_and_skips_third_party() {
        // Nested (Claude Code / Codex / Gemini)
        assert!(is_ai_memory_hook_entry(&serde_json::json!(
            { "matcher": "", "hooks": [ { "type": "command", "command": "ai-memory.exe hook --event session-start --agent claude-code --server-url http://h" } ] }
        )));
        // Flat (Cursor) + shell form
        assert!(is_ai_memory_hook_entry(&serde_json::json!(
            { "type": "command", "command": "bash -c 'AI_MEMORY_HOOK_URL=x /c/x/ai-memory/hooks/pre.sh'" }
        )));
        // Claude Code exec form
        assert!(is_ai_memory_hook_entry(&serde_json::json!(
            { "matcher": "", "hooks": [ { "type": "command", "command": "C:\\bin\\ai-memory.exe", "args": ["hook", "--event", "session-start", "--agent", "claude-code", "--server-url", "http://h"] } ] }
        )));
        // Third-party must NOT be flagged
        assert!(!is_ai_memory_hook_entry(&serde_json::json!(
            { "hooks": [ { "type": "command", "command": "node context-mode-cache-heal.mjs" } ] }
        )));
        assert!(!is_ai_memory_hook_entry(&serde_json::json!(
            { "hooks": [ { "type": "command", "command": "C:\\bin\\third-party.exe", "args": ["hook", "--event", "session-start", "--agent", "claude-code", "--server-url", "http://h"] } ] }
        )));
        assert!(!is_ai_memory_hook_entry(&serde_json::json!(
            { "hooks": [ { "type": "command", "command": "C:\\bin\\ai-memory-helper.exe", "args": ["--check", "project"] } ] }
        )));
        // A third-party string command may use the same executable name, but
        // without either ai-memory hook signature it must not be replaced.
        assert!(!is_ai_memory_hook_entry(&serde_json::json!(
            { "hooks": [ { "type": "command", "command": "/opt/alphaone/bin/ai-memory boot --quiet --limit 10 --budget-tokens 4096" } ] }
        )));
        // Legacy script commands can use any path, so the exact env marker is
        // the ownership signal rather than the script basename.
        assert!(is_ai_memory_hook_entry(&serde_json::json!(
            { "hooks": [ { "type": "command", "command": "AI_MEMORY_HOOK_URL=http://h /custom/session-start.sh" } ] }
        )));
    }

    #[test]
    fn overlay_event_hooks_preserves_third_party_string_command_and_replaces_legacy() {
        let third_party =
            "/opt/alphaone/bin/ai-memory boot --quiet --limit 10 --budget-tokens 4096";
        let legacy = "AI_MEMORY_HOOK_URL=http://old /custom/session-start.sh";
        let mut hooks = serde_json::Map::new();
        hooks.insert(
            "SessionStart".into(),
            serde_json::json!([
                { "matcher": "", "hooks": [ { "type": "command", "command": third_party } ] },
                { "matcher": "", "hooks": [ { "type": "command", "command": legacy } ] }
            ]),
        );
        let ours = serde_json::json!([
            { "matcher": "", "hooks": [ { "type": "command", "command": "AI_MEMORY_HOOK_URL=http://new /fresh/session-start.sh" } ] }
        ]);

        overlay_event_hooks(&mut hooks, "SessionStart", &ours);

        let commands: Vec<&str> = hooks["SessionStart"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|entry| {
                entry
                    .pointer("/hooks/0/command")
                    .and_then(serde_json::Value::as_str)
            })
            .collect();
        assert_eq!(
            commands,
            [
                third_party,
                "AI_MEMORY_HOOK_URL=http://new /fresh/session-start.sh"
            ]
        );
        assert!(!commands.contains(&legacy), "legacy entry must be replaced");
    }

    fn stub_scripts(dir: &Path, names: &[&str]) {
        for name in names {
            let p = dir.join(name);
            fs::write(&p, "#!/bin/sh\n").unwrap();
            #[cfg(unix)]
            {
                use std::os::unix::fs::PermissionsExt;
                let mut perms = fs::metadata(&p).unwrap().permissions();
                perms.set_mode(0o755);
                fs::set_permissions(&p, perms).unwrap();
            }
        }
    }

    fn droid_args(config_file: &Path) -> InstallHooksArgs {
        InstallHooksArgs {
            agent: AgentChoice::Droid,
            config_file: Some(config_file.to_path_buf()),
            ..default_hook_args()
        }
    }

    /// `install-hooks --agent codebuddy --apply` merges native `--agent
    /// codebuddy` commands under the `hooks` key of `settings.json`, keeps
    /// sibling keys and third-party hooks, and a re-apply changes nothing.
    #[test]
    fn codebuddy_apply_merges_native_hooks_under_the_settings_hooks_key() {
        let home = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let settings = home.path().join("settings.json");
        fs::write(
            &settings,
            serde_json::json!({
                "model": "deepseek-v4.1-flash",
                "hooks": {
                    "PreToolUse": [{
                        "matcher": "Bash",
                        "hooks": [{"type": "command", "command": "/usr/local/bin/guard.sh"}]
                    }]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::CodeBuddy,
            config_file: Some(settings.clone()),
            ..default_hook_args()
        };

        apply_to_codebuddy_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        let first = fs::read_to_string(&settings).unwrap();
        apply_to_codebuddy_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        assert_eq!(
            first,
            fs::read_to_string(&settings).unwrap(),
            "re-apply is a no-op"
        );

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["model"], "deepseek-v4.1-flash");
        for (event, script) in super::super::render_shared::CODEBUDDY_EVENTS {
            let entries = root["hooks"][event].as_array().unwrap();
            let ours: Vec<_> = entries
                .iter()
                .filter(|entry| is_ai_memory_hook_entry(entry))
                .collect();
            assert_eq!(ours.len(), 1, "{event}: exactly one ai-memory entry");
            assert_eq!(ours[0]["matcher"], "", "{event}");
            let command = ours[0]["hooks"][0]["command"].as_str().unwrap();
            let stem = script.trim_end_matches(".sh");
            assert!(
                command.contains(&format!(
                    " hook --event {stem} --agent codebuddy --server-url "
                )),
                "{event}: {command}"
            );
            assert!(
                !command.contains(".sh"),
                "{event}: no script bundle: {command}"
            );
        }
        assert!(root["hooks"].get("SubagentStart").is_none());
        assert!(root["hooks"].get("PostToolUseFailure").is_none());
        let pre = root["hooks"]["PreToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["hooks"][0]["command"], "/usr/local/bin/guard.sh");
    }

    /// `install-hooks --agent qwen-code --apply` merges native `--agent
    /// qwen-code` commands under the `hooks` key of `settings.json`, keeps
    /// sibling keys and third-party hooks, and a re-apply changes nothing.
    #[test]
    fn qwen_code_apply_merges_native_hooks_under_the_settings_hooks_key() {
        let home = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let settings = home.path().join("settings.json");
        fs::write(
            &settings,
            serde_json::json!({
                "model": "qwen3-coder-plus",
                "hooks": {
                    "PreToolUse": [{
                        "matcher": "write_file",
                        "hooks": [{"type": "command", "command": "/usr/local/bin/guard.sh"}]
                    }]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::QwenCode,
            config_file: Some(settings.clone()),
            ..default_hook_args()
        };

        apply_to_qwen_code_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        let first = fs::read_to_string(&settings).unwrap();
        apply_to_qwen_code_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        assert_eq!(
            first,
            fs::read_to_string(&settings).unwrap(),
            "re-apply is a no-op"
        );

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["model"], "qwen3-coder-plus");
        for (event, script) in super::super::render_shared::QWEN_CODE_EVENTS {
            let entries = root["hooks"][event].as_array().unwrap();
            let ours: Vec<_> = entries
                .iter()
                .filter(|entry| is_ai_memory_hook_entry(entry))
                .collect();
            assert_eq!(ours.len(), 1, "{event}: exactly one ai-memory entry");
            assert_eq!(ours[0]["matcher"], "", "{event}");
            let command = ours[0]["hooks"][0]["command"].as_str().unwrap();
            let stem = script.trim_end_matches(".sh");
            assert!(
                command.contains(&format!(
                    " hook --event {stem} --agent qwen-code --server-url "
                )),
                "{event}: {command}"
            );
            assert!(
                !command.contains(".sh"),
                "{event}: no script bundle: {command}"
            );
        }
        let pre = root["hooks"]["PreToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["hooks"][0]["command"], "/usr/local/bin/guard.sh");
    }

    #[test]
    fn qoder_apply_merges_native_hooks_and_preserves_shared_settings() {
        let home = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let settings = home.path().join("settings.json");
        fs::write(
            &settings,
            serde_json::json!({
                "model": "qwen3-coder-plus",
                "mcpServers": {"other": {"command": "other-server"}},
                "hooks": {
                    "PreToolUse": [{
                        "matcher": "Write",
                        "hooks": [{"type": "command", "command": "/usr/local/bin/guard.sh"}]
                    }]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Qoder,
            config_file: Some(settings.clone()),
            ..default_hook_args()
        };

        apply_to_qoder_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        let first = fs::read_to_string(&settings).unwrap();
        apply_to_qoder_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        assert_eq!(first, fs::read_to_string(&settings).unwrap());

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["model"], "qwen3-coder-plus");
        assert_eq!(root["mcpServers"]["other"]["command"], "other-server");
        for (event, script) in super::super::render_shared::QODER_EVENTS {
            let entries = root["hooks"][event].as_array().unwrap();
            let ours: Vec<_> = entries
                .iter()
                .filter(|entry| is_ai_memory_hook_entry(entry))
                .collect();
            assert_eq!(ours.len(), 1, "{event}: exactly one ai-memory entry");
            assert_eq!(ours[0]["matcher"], "", "{event}");
            let command = ours[0]["hooks"][0]["command"].as_str().unwrap();
            let stem = script.trim_end_matches(".sh");
            assert!(
                command.contains(&format!(" hook --event {stem} --agent qoder --server-url ")),
                "{event}: {command}"
            );
            assert!(!command.contains(".sh"), "{event}: {command}");
        }
        let pre = root["hooks"]["PreToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["hooks"][0]["command"], "/usr/local/bin/guard.sh");
    }

    /// IBM Bob shares one global settings file between the IDE and Shell.
    /// Install only their common event vocabulary, preserve unrelated content,
    /// omit unsupported matchers, and make repeated installation a no-op.
    #[test]
    fn ibm_bob_apply_merges_common_native_hooks_and_is_idempotent() {
        let home = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let settings = home.path().join("settings.json");
        fs::write(
            &settings,
            serde_json::json!({
                "theme": "dark",
                "hooks": {
                    "PreToolUse": [{
                        "hooks": [{"type": "command", "command": "/usr/local/bin/guard.sh"}]
                    }],
                    "PreCompact": [{
                        "hooks": [{"type": "command", "command": "/usr/local/bin/archive.sh"}]
                    }]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::IbmBob,
            config_file: Some(settings.clone()),
            ..default_hook_args()
        };

        apply_to_ibm_bob_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        let first = fs::read_to_string(&settings).unwrap();
        apply_to_ibm_bob_settings(&settings, "http://memory:49374", None, data.path(), &args)
            .unwrap();
        assert_eq!(first, fs::read_to_string(&settings).unwrap());

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["theme"], "dark");
        for (event, script) in super::super::render_shared::IBM_BOB_EVENTS {
            let entries = root["hooks"][event].as_array().unwrap();
            let ours: Vec<_> = entries
                .iter()
                .filter(|entry| is_ai_memory_hook_entry(entry))
                .collect();
            assert_eq!(ours.len(), 1, "{event}");
            assert!(ours[0].get("matcher").is_none(), "{event}");
            let command = ours[0]["hooks"][0]["command"].as_str().unwrap();
            assert!(
                command.contains(&format!(
                    " hook --event {} --agent ibm-bob --server-url ",
                    script.trim_end_matches(".sh")
                )),
                "{event}: {command}"
            );
        }
        assert_eq!(
            root["hooks"]["PreCompact"][0]["hooks"][0]["command"],
            "/usr/local/bin/archive.sh"
        );
        let pre = root["hooks"]["PreToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["hooks"][0]["command"], "/usr/local/bin/guard.sh");
    }

    /// `install-hooks --agent droid --apply` merges native `--agent droid`
    /// commands into `hooks.json` (the bare event map), keeps every
    /// third-party entry, and a re-apply changes nothing (#1240).
    #[test]
    fn droid_apply_merges_native_hooks_and_is_idempotent() {
        let factory = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let hooks_json = factory.path().join("hooks.json");
        fs::write(
            &hooks_json,
            serde_json::json!({
                "PreToolUse": [{
                    "matcher": "Execute",
                    "hooks": [{"type": "command", "command": "/usr/local/bin/guard.sh", "timeout": 5}]
                }],
                "Notification": [{"hooks": [{"type": "command", "command": "notify-send hi"}]}]
            })
            .to_string(),
        )
        .unwrap();
        let args = droid_args(&hooks_json);

        apply_to_droid_hooks(&hooks_json, "http://memory:49374", None, data.path(), &args).unwrap();
        let first = fs::read_to_string(&hooks_json).unwrap();
        apply_to_droid_hooks(&hooks_json, "http://memory:49374", None, data.path(), &args).unwrap();
        assert_eq!(
            first,
            fs::read_to_string(&hooks_json).unwrap(),
            "re-apply is a no-op"
        );
        let backups = fs::read_dir(factory.path())
            .unwrap()
            .filter(|entry| {
                entry
                    .as_ref()
                    .unwrap()
                    .file_name()
                    .to_string_lossy()
                    .contains(".bak-")
            })
            .count();
        assert_eq!(backups, 1, "only the first apply changed the file");

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert!(root.get("hooks").is_none(), "hooks.json has no wrapper key");
        for (event, script) in super::super::render_shared::DROID_EVENTS {
            let entries = root[event].as_array().unwrap();
            let ours: Vec<_> = entries
                .iter()
                .filter(|e| is_ai_memory_hook_entry(e))
                .collect();
            assert_eq!(ours.len(), 1, "{event}: exactly one ai-memory entry");
            assert_eq!(ours[0]["matcher"], "", "{event}");
            let command = ours[0]["hooks"][0]["command"].as_str().unwrap();
            let stem = script.trim_end_matches(".sh");
            assert!(
                command.contains(&format!(" hook --event {stem} --agent droid --server-url ")),
                "{event}: {command}"
            );
            assert!(
                !command.contains(".sh"),
                "{event}: no script bundle: {command}"
            );
        }
        assert!(root.get("SubagentStop").is_none());
        // Third-party entries survive, in their own events and beside ours.
        assert_eq!(
            root["Notification"][0]["hooks"][0]["command"],
            "notify-send hi"
        );
        let pre = root["PreToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["matcher"], "Execute");
        assert_eq!(pre[0]["hooks"][0]["command"], "/usr/local/bin/guard.sh");
    }

    fn muse_args(config_file: &Path) -> InstallHooksArgs {
        InstallHooksArgs {
            agent: AgentChoice::Muse,
            config_file: Some(config_file.to_path_buf()),
            ..default_hook_args()
        }
    }

    /// `install-hooks --agent muse --apply` merges native `--agent muse`
    /// commands under the `hooks` key of Muse's `settings.json`: one
    /// catch-all (`matcher: ""`) group per event with a timeout in seconds,
    /// `schema_version` and every unknown key kept, third-party hooks kept,
    /// and a re-apply changes nothing.
    #[test]
    fn muse_apply_merges_native_hooks_into_settings_and_is_idempotent() {
        let muse = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let settings = muse.path().join("settings.json");
        fs::write(
            &settings,
            serde_json::json!({
                "schema_version": 1,
                "theme": "dark",
                "mcpServers": {"x": {"type": "stdio", "command": "x", "mode": "optional"}},
                "hooks": {
                    "PreToolUse": [{
                        "matcher": "bash",
                        "hooks": [{"type": "command", "command": "/usr/local/bin/guard.sh", "timeout": 5}]
                    }],
                    "Notification": [{"hooks": [{"type": "command", "command": "notify-send hi"}]}]
                }
            })
            .to_string(),
        )
        .unwrap();
        let args = muse_args(&settings);

        apply_to_muse_settings(&settings, "http://memory:49374", None, data.path(), &args).unwrap();
        let first = fs::read_to_string(&settings).unwrap();
        apply_to_muse_settings(&settings, "http://memory:49374", None, data.path(), &args).unwrap();
        assert_eq!(
            first,
            fs::read_to_string(&settings).unwrap(),
            "re-apply is a no-op"
        );
        let backups = fs::read_dir(muse.path())
            .unwrap()
            .filter(|entry| {
                entry
                    .as_ref()
                    .unwrap()
                    .file_name()
                    .to_string_lossy()
                    .contains(".bak-")
            })
            .count();
        assert_eq!(backups, 1, "only the first apply changed the file");

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["schema_version"], 1);
        assert_eq!(root["theme"], "dark");
        assert_eq!(root["mcpServers"]["x"]["command"], "x");
        let hooks = &root["hooks"];
        for (event, script) in super::super::render_shared::MUSE_EVENTS {
            let entries = hooks[event].as_array().unwrap();
            let ours: Vec<_> = entries
                .iter()
                .filter(|e| is_ai_memory_hook_entry(e))
                .collect();
            assert_eq!(ours.len(), 1, "{event}: exactly one ai-memory entry");
            assert_eq!(ours[0]["matcher"], "", "{event}");
            let handler = &ours[0]["hooks"][0];
            assert_eq!(handler["type"], "command", "{event}");
            assert_eq!(
                handler["timeout"],
                super::super::render_shared::MUSE_HOOK_TIMEOUT_SECS,
                "{event}"
            );
            let command = handler["command"].as_str().unwrap();
            let stem = script.trim_end_matches(".sh");
            assert!(
                command.contains(&format!(" hook --event {stem} --agent muse --server-url ")),
                "{event}: {command}"
            );
            assert!(
                command.contains("--data-dir"),
                "{event}: Muse clears the hook environment, so the data dir is baked in: {command}"
            );
            assert!(
                !command.contains(".sh"),
                "{event}: no script bundle: {command}"
            );
        }
        assert!(hooks.get("SubagentStart").is_none());
        assert!(hooks.get("SubagentStop").is_none());
        assert_eq!(
            hooks["Notification"][0]["hooks"][0]["command"],
            "notify-send hi"
        );
        let pre = hooks["PreToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["matcher"], "bash");
        assert_eq!(pre[0]["hooks"][0]["command"], "/usr/local/bin/guard.sh");
    }

    /// A new settings file gets `"schema_version": 1` (without it every
    /// muse command fails at startup); an existing value is never rewritten;
    /// a non-object `hooks` is refused.
    #[test]
    fn muse_apply_creates_schema_version_and_never_rewrites_it() {
        let muse = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let fresh = muse.path().join("fresh").join("settings.json");
        apply_to_muse_settings(
            &fresh,
            "http://memory:49374",
            None,
            data.path(),
            &muse_args(&fresh),
        )
        .unwrap();
        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&fresh).unwrap()).unwrap();
        assert_eq!(root["schema_version"], 1);

        let future = muse.path().join("future.json");
        fs::write(&future, r#"{"schema_version":2}"#).unwrap();
        apply_to_muse_settings(
            &future,
            "http://memory:49374",
            None,
            data.path(),
            &muse_args(&future),
        )
        .unwrap();
        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&future).unwrap()).unwrap();
        assert_eq!(root["schema_version"], 2);

        let broken = muse.path().join("broken.json");
        fs::write(&broken, r#"{"schema_version":1,"hooks":[]}"#).unwrap();
        assert!(
            apply_to_muse_settings(
                &broken,
                "http://memory:49374",
                None,
                data.path(),
                &muse_args(&broken)
            )
            .is_err()
        );
        assert_eq!(
            fs::read_to_string(&broken).unwrap(),
            r#"{"schema_version":1,"hooks":[]}"#
        );
    }

    /// The default Muse settings path comes from the captured environment:
    /// `XDG_CONFIG_HOME` when it is absolute.
    #[test]
    fn muse_settings_path_reads_xdg_config_home_from_the_runtime_env() {
        // Absolute on the host platform: a Unix-style root is relative on
        // Windows, where it would rightly be ignored.
        let xdg = if cfg!(windows) {
            r"C:\xdg-from-env"
        } else {
            "/xdg-from-env"
        };
        let env =
            crate::config::RuntimeEnv::with_process_env_for_tests(&[("XDG_CONFIG_HOME", xdg)]);
        assert_eq!(
            muse_settings_path(&env).unwrap(),
            Path::new(xdg).join("muse").join("settings.json")
        );
    }

    /// `install-hooks --agent muse` infers the server and an explicit token
    /// from the bridge entry `install-mcp --client muse` writes, under either
    /// server map, and from an older streamable-HTTP entry; a `${...}`
    /// reference is never taken for a token.
    #[test]
    fn muse_mcp_inference_reads_the_bridge_entry_under_either_map() {
        let bridge = |key: &str, token: &str| {
            serde_json::json!({
                "schema_version": 1,
                key: {"ai-memory": {
                    "type": "stdio",
                    "command": "ai-memory",
                    "args": ["mcp-bridge", "--agent", "muse", "--server-url", "http://memory:49374/mcp"],
                    "env": {"AI_MEMORY_AUTH_TOKEN": token},
                    "mode": "optional"
                }}
            })
            .to_string()
        };
        for key in ["mcpServers", "mcp_servers"] {
            let inferred = infer_muse_mcp_config(&bridge(key, "tok")).unwrap();
            assert_eq!(
                inferred.hook_server_url.as_deref(),
                Some("http://memory:49374"),
                "{key}"
            );
            assert_eq!(inferred.auth_token.as_deref(), Some("tok"), "{key}");
        }
        let reference =
            infer_muse_mcp_config(&bridge("mcpServers", "${AI_MEMORY_AUTH_TOKEN}")).unwrap();
        assert_eq!(reference.auth_token, None);
        let legacy = serde_json::json!({"mcp_servers": {"ai-memory": {
            "transport": "streamable_http",
            "url": "http://old:49374/mcp",
            "headers": {"Authorization": "Bearer old-token"}
        }}})
        .to_string();
        let inferred = infer_muse_mcp_config(&legacy).unwrap();
        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("http://old:49374")
        );
        assert_eq!(inferred.auth_token.as_deref(), Some("old-token"));
        assert!(infer_muse_mcp_config(r#"{"mcpServers":{}}"#).is_none());
        assert_eq!(
            mcp_client_for_agent(AgentChoice::Muse),
            Some(McpClient::Muse)
        );
    }

    /// Droid reads `settings.json`'s `hooks` only while `hooks.json` is
    /// absent, so creating `hooks.json` over them is refused and leaves both
    /// files untouched. Settings without hooks (the control), and a
    /// `hooks.json` that already exists, proceed.
    #[test]
    fn droid_apply_refuses_to_create_hooks_json_over_settings_hooks() {
        let data = TempDir::new().unwrap();
        for settings in [
            r#"{"model": "x", "hooks": {"Stop": [{"hooks": [{"type": "command", "command": "mine"}]}]}}"#,
            // JSONC with comments still counts.
            "{\n  // user hooks\n  \"hooks\": {\"Stop\": []},\n}\n",
            r#"{"hooks": "unexpected"}"#,
        ] {
            let factory = TempDir::new().unwrap();
            let hooks_json = factory.path().join("hooks.json");
            let settings_json = factory.path().join("settings.json");
            fs::write(&settings_json, settings).unwrap();
            let error = apply_to_droid_hooks(
                &hooks_json,
                "http://memory:49374",
                None,
                data.path(),
                &droid_args(&hooks_json),
            )
            .unwrap_err()
            .to_string();
            assert!(
                !hooks_json.exists(),
                "{settings}: hooks.json must not be created"
            );
            assert_eq!(fs::read_to_string(&settings_json).unwrap(), settings);
            assert!(error.contains("settings.json"), "{error}");
            assert!(error.contains("hooks.json"), "{error}");
            assert!(error.contains("--agent droid"), "{error}");
        }

        // Unparsable settings cannot prove the absence of hooks.
        let factory = TempDir::new().unwrap();
        let hooks_json = factory.path().join("hooks.json");
        fs::write(factory.path().join("settings.json"), "{ not json").unwrap();
        assert!(
            apply_to_droid_hooks(
                &hooks_json,
                "http://memory:49374",
                None,
                data.path(),
                &droid_args(&hooks_json)
            )
            .is_err()
        );
        assert!(!hooks_json.exists());

        // Controls: no hooks in settings.json, or an empty `hooks` object.
        for settings in [
            r#"{"model": "x"}"#,
            r#"{"hooks": {}}"#,
            r#"{"hooks": null}"#,
        ] {
            let factory = TempDir::new().unwrap();
            let hooks_json = factory.path().join("hooks.json");
            fs::write(factory.path().join("settings.json"), settings).unwrap();
            apply_to_droid_hooks(
                &hooks_json,
                "http://memory:49374",
                None,
                data.path(),
                &droid_args(&hooks_json),
            )
            .unwrap();
            assert!(hooks_json.exists(), "{settings}");
        }

        // An existing hooks.json is already what Droid reads.
        let factory = TempDir::new().unwrap();
        let hooks_json = factory.path().join("hooks.json");
        fs::write(&hooks_json, "{}").unwrap();
        fs::write(
            factory.path().join("settings.json"),
            r#"{"hooks": {"Stop": [{"hooks": [{"type": "command", "command": "mine"}]}]}}"#,
        )
        .unwrap();
        apply_to_droid_hooks(
            &hooks_json,
            "http://memory:49374",
            None,
            data.path(),
            &droid_args(&hooks_json),
        )
        .unwrap();
        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&hooks_json).unwrap()).unwrap();
        assert!(root["SessionStart"].is_array());
    }

    /// `install-mcp --client droid` writes the bearer as a
    /// `${AI_MEMORY_AUTH_TOKEN}` reference; inferring hook settings from it
    /// keeps the URL and never takes that reference for a token.
    #[test]
    fn droid_mcp_inference_keeps_url_and_drops_the_env_reference() {
        let dir = TempDir::new().unwrap();
        let mcp = dir.path().join("mcp.json");
        fs::write(
            &mcp,
            serde_json::json!({"mcpServers": {"ai-memory": {
                "type": "http",
                "url": "http://memory:49374/mcp",
                "headers": {"Authorization": "Bearer ${AI_MEMORY_AUTH_TOKEN}"}
            }}})
            .to_string(),
        )
        .unwrap();
        let inferred = infer_installed_mcp_config(AgentChoice::Droid, Some(&mcp))
            .unwrap()
            .unwrap();
        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("http://memory:49374")
        );
        assert_eq!(inferred.auth_token, None);
        assert_eq!(
            mcp_client_for_agent(AgentChoice::Droid),
            Some(McpClient::Droid)
        );
    }

    fn default_hook_args() -> InstallHooksArgs {
        InstallHooksArgs {
            profile: None,
            agent: AgentChoice::OpenCode,
            capture_assistant: false,
            no_capture_prompts: false,
            capture_mode: None,
            capture_prompts: false,
            hooks_dir: None,
            server_url: None,
            auth_token: None,
            as_user: None,
            apply: true,
            config_file: None,
            scope: HookInstallScope::Global,
            project_strategy: Some(ProjectStrategyArg::Basename),
        }
    }

    #[test]
    fn cline_apply_writes_native_event_hooks_without_overwriting_user_files() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join("cline-hooks");
        let data = tmp.path().join("data");
        let mut args = default_hook_args();
        args.agent = AgentChoice::Cline;
        args.config_file = Some(target.clone());
        args.project_strategy = Some(ProjectStrategyArg::RepoRoot);

        apply_to_cline_hooks(
            "https://memory.example",
            Some("tok'en"),
            &data,
            &args,
            "allowlist",
        )
        .unwrap();

        let extension = if cfg!(windows) { "ps1" } else { "sh" };
        for (name, event) in CLINE_HOOK_EVENTS {
            let path = target.join(format!("{name}.{extension}"));
            let content = fs::read_to_string(&path).unwrap();
            assert!(content.contains("--agent"));
            assert!(content.contains("cline"));
            assert!(content.contains(event));
            assert!(content.contains("https://memory.example"));
            assert!(content.contains("allowlist"));
            assert!(content.contains("repo-root"));
            assert!(content.contains("--auth-token"));
            assert!(!content.contains("<redacted>"));
            #[cfg(unix)]
            {
                use std::os::unix::fs::PermissionsExt;
                assert_eq!(
                    fs::metadata(path).unwrap().permissions().mode() & 0o777,
                    0o700
                );
            }
        }

        let first = target.join(format!("TaskStart.{extension}"));
        fs::remove_file(&first).unwrap();
        let owned = target.join(format!("TaskResume.{extension}"));
        fs::write(&owned, "user-owned hook\n").unwrap();
        let error = apply_to_cline_hooks("https://memory.example", None, &data, &args, "denylist")
            .unwrap_err();
        assert!(error.to_string().contains("refusing to replace user-owned"));
        assert_eq!(fs::read_to_string(owned).unwrap(), "user-owned hook\n");
        assert!(!first.exists(), "preflight must prevent a partial rewrite");
    }

    #[test]
    fn cline_script_quoting_is_shell_specific_and_literal() {
        let argv = vec!["ai-memory".to_string(), "a'b $HOME".to_string()];
        let sh = render_cline_hook_script(&argv, false);
        assert!(sh.contains("'a'\"'\"'b $HOME'"), "{sh}");
        let ps = render_cline_hook_script(&argv, true);
        assert!(ps.contains("'a''b $HOME'"), "{ps}");
    }

    #[cfg(unix)]
    #[test]
    fn cline_apply_refuses_a_symlinked_hook_without_touching_its_target() {
        use std::os::unix::fs::symlink;

        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join("cline-hooks");
        let data = tmp.path().join("data");
        fs::create_dir_all(&target).unwrap();
        let victim = tmp.path().join("victim");
        fs::write(&victim, "keep me\n").unwrap();
        symlink(&victim, target.join("TaskStart.sh")).unwrap();

        let mut args = default_hook_args();
        args.agent = AgentChoice::Cline;
        args.config_file = Some(target);
        let error = apply_to_cline_hooks(
            "https://memory.example",
            Some("secret"),
            &data,
            &args,
            "denylist",
        )
        .unwrap_err();

        assert!(error.to_string().contains("refusing to replace symlinked"));
        assert_eq!(fs::read_to_string(victim).unwrap(), "keep me\n");
    }

    #[test]
    fn cline_hook_target_follows_supplied_home() {
        let home = if cfg!(windows) {
            std::ffi::OsString::from(r"C:\Users\alice")
        } else {
            std::ffi::OsString::from("/home/alice")
        };
        assert_eq!(
            hook_config_target_with(AgentChoice::Cline, &|name| {
                (name == "HOME").then(|| home.clone())
            })
            .unwrap(),
            PathBuf::from(home).join(".cline").join("hooks")
        );
    }

    // ── #issue project-strategy preservation on re-apply ─────────────

    #[test]
    fn project_strategy_from_text_reads_every_form() {
        // Shell env prefix (Claude Code / POSIX script hooks).
        assert_eq!(
            project_strategy_from_text(
                "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/s.sh"
            ),
            Some(ProjectStrategyArg::RepoRoot)
        );
        // PowerShell form.
        assert_eq!(
            project_strategy_from_text("$env:AI_MEMORY_PROJECT_STRATEGY='repo-root'; & /x/s.ps1"),
            Some(ProjectStrategyArg::RepoRoot)
        );
        // Native flag, both spellings.
        assert_eq!(
            project_strategy_from_text("ai-memory hook --project-strategy repo-root run"),
            Some(ProjectStrategyArg::RepoRoot)
        );
        assert_eq!(
            project_strategy_from_text("ai-memory hook --project-strategy=repo_root"),
            Some(ProjectStrategyArg::RepoRoot)
        );
        assert_eq!(
            project_strategy_from_text("const DEFAULT_PROJECT_STRATEGY = \"repo-root\";"),
            Some(ProjectStrategyArg::RepoRoot)
        );
    }

    #[test]
    fn baked_project_strategy_reads_owned_json_for_every_json_agent() {
        let existing = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    { "hooks": [{
                        "command": "third-party",
                        "args": ["--project-strategy", "repo-root"]
                    }]},
                    { "hooks": [{
                        "command": "/bin/ai-memory",
                        "args": [
                            "hook", "--event", "session-start", "--agent", "claude-code",
                            "--server-url", "http://h", "--project-strategy", "repo-root"
                        ]
                    }]}
                ]
            }
        })
        .to_string();
        for agent in [
            AgentChoice::ClaudeCode,
            AgentChoice::Codex,
            AgentChoice::Cursor,
            AgentChoice::GeminiCli,
            AgentChoice::AntigravityCli,
            AgentChoice::Grok,
            AgentChoice::Zero,
            AgentChoice::Devin,
        ] {
            assert_eq!(
                baked_project_strategy(agent, &existing),
                Some(ProjectStrategyArg::RepoRoot),
                "{agent:?}"
            );
        }
    }

    #[test]
    fn baked_project_strategy_ignores_unowned_json_entry() {
        let existing = serde_json::json!({
            "hooks": {
                "SessionStart": [{ "hooks": [{
                    "command": "third-party",
                    "args": ["--project-strategy", "repo-root"]
                }]}]
            }
        })
        .to_string();
        assert_eq!(
            baked_project_strategy(AgentChoice::ClaudeCode, &existing),
            None
        );
    }

    #[test]
    fn baked_project_strategy_reads_owned_kimi_toml_only() {
        let existing = r#"
[[hooks]]
event = "UserPromptSubmit"
command = "third-party --project-strategy repo-root"

[[hooks]]
event = "UserPromptSubmit"
command = "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/ai-memory/session-start.sh"
"#;
        assert_eq!(
            baked_project_strategy(AgentChoice::KimiCode, existing),
            Some(ProjectStrategyArg::RepoRoot)
        );
    }

    #[test]
    fn baked_project_strategy_reads_every_owned_generated_integration() {
        for (agent, name) in [
            (AgentChoice::OpenCode, "opencode"),
            (AgentChoice::OpenCode2, "opencode2"),
            (AgentChoice::Pi, "pi"),
            (AgentChoice::Omp, "omp"),
            (AgentChoice::Openclaw, "openclaw"),
        ] {
            let existing = format!(
                "// Auto-generated by `ai-memory install-hooks --agent {name} --apply`.\n\
                 const DEFAULT_PROJECT_STRATEGY = \"repo-root\";\n"
            );
            assert_eq!(
                baked_project_strategy(agent, &existing),
                Some(ProjectStrategyArg::RepoRoot),
                "{agent:?}"
            );
        }

        let unowned = "// user extension\nconst DEFAULT_PROJECT_STRATEGY = \"repo-root\";\n";
        assert_eq!(baked_project_strategy(AgentChoice::OpenCode, unowned), None);
    }

    #[test]
    fn install_project_strategy_preserves_baked_when_flag_absent() {
        let tmp = TempDir::new().unwrap();
        let cfg = tmp.path().join("settings.json");
        std::fs::write(
            &cfg,
            serde_json::json!({
                "hooks": { "SessionStart": [{ "hooks": [{
                    "command": "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/ai-memory/session-start.sh"
                }]}] }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            config_file: Some(cfg),
            project_strategy: None,
            ..default_hook_args()
        };
        // A bare re-apply (e.g. `ai-memory upgrade`) must keep repo-root.
        assert_eq!(
            install_project_strategy(&args),
            Some(ProjectStrategyArg::RepoRoot)
        );
    }

    #[test]
    fn install_project_strategy_explicit_basename_overrides_existing() {
        let tmp = TempDir::new().unwrap();
        let cfg = tmp.path().join("settings.json");
        std::fs::write(
            &cfg,
            serde_json::json!({
                "hooks": { "SessionStart": [{ "hooks": [{
                    "command": "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/ai-memory/session-start.sh"
                }]}] }
            })
            .to_string(),
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            config_file: Some(cfg),
            project_strategy: Some(ProjectStrategyArg::Basename),
            ..default_hook_args()
        };
        // Explicit basename is honored, not overridden by the baked repo-root.
        assert_eq!(
            install_project_strategy(&args),
            Some(ProjectStrategyArg::Basename)
        );
    }

    #[test]
    fn install_project_strategy_none_when_target_absent() {
        let tmp = TempDir::new().unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            config_file: Some(tmp.path().join("nope.json")),
            project_strategy: None,
            ..default_hook_args()
        };
        assert_eq!(install_project_strategy(&args), None);
    }

    #[test]
    fn install_project_strategy_reads_openclaw_entrypoint_below_config_dir() {
        let tmp = TempDir::new().unwrap();
        let entrypoint = tmp.path().join(openclaw_plugin::ENTRYPOINT_TS);
        std::fs::write(
            entrypoint,
            "// Auto-generated by `ai-memory install-hooks --agent openclaw --apply`.\n\
             const DEFAULT_PROJECT_STRATEGY = \"repo-root\";\n",
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Openclaw,
            config_file: Some(tmp.path().to_path_buf()),
            project_strategy: None,
            ..default_hook_args()
        };
        assert_eq!(
            install_project_strategy(&args),
            Some(ProjectStrategyArg::RepoRoot)
        );
    }

    // ── P1.8 validate_as_user ────────────────────────────────────────

    /// No `--as-user` at all → always OK.
    #[test]
    fn validate_as_user_passes_when_not_set() {
        assert!(validate_as_user(None, None).is_ok());
        assert!(validate_as_user(None, Some("tok")).is_ok());
    }

    /// Empty / whitespace-only `--as-user` is treated as not-set.
    /// Defensive: an accidental `--as-user ""` shouldn't bail.
    #[test]
    fn validate_as_user_treats_blank_as_unset() {
        assert!(validate_as_user(Some(""), None).is_ok());
        assert!(validate_as_user(Some("   "), None).is_ok());
    }

    /// `--as-user` with no `--auth-token` is the error case the v0.8
    /// docs warn about — without a token the hook scripts authenticate
    /// anonymously / as root, making the `--as-user X` label misleading.
    #[test]
    fn validate_as_user_bails_without_auth_token() {
        let err = validate_as_user(Some("alice"), None).unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("--as-user 'alice'") && msg.contains("--auth-token"),
            "error must name both flags: {msg}"
        );
        // Empty auth token is treated the same as missing.
        assert!(validate_as_user(Some("alice"), Some("")).is_err());
        assert!(validate_as_user(Some("alice"), Some("   ")).is_err());
    }

    /// `--as-user X --auth-token <something>` passes — the install
    /// proceeds with X as metadata and the supplied token as the
    /// bearer.
    #[test]
    fn validate_as_user_passes_with_both_flags() {
        assert!(validate_as_user(Some("alice"), Some("some-token")).is_ok());
    }

    #[test]
    fn manual_agent_render_mentions_repo_root_project_strategy() {
        let temp = TempDir::new().unwrap();
        stub_scripts(temp.path(), &["session-start.sh"]);
        for agent in ["codex", "cursor", "gemini-cli", "antigravity-cli"] {
            let output = render_agent_output(
                agent,
                temp.path(),
                "http://127.0.0.1:49374",
                None,
                Some("repo-root"),
                &[CODEX_PROFILE.events],
            );
            assert!(
                output.contains("AI_MEMORY_PROJECT_STRATEGY=repo-root"),
                "{agent} manual output must tell users to set the strategy env: {output}"
            );
        }
    }

    #[test]
    fn manual_agent_render_omits_project_strategy_by_default() {
        let temp = TempDir::new().unwrap();
        stub_scripts(temp.path(), &["session-start.sh"]);
        let output = render_agent_output(
            "codex",
            temp.path(),
            "http://127.0.0.1:49374",
            None,
            None,
            &[CODEX_PROFILE.events],
        );
        assert!(!output.contains("AI_MEMORY_PROJECT_STRATEGY"));
    }

    #[test]
    fn antigravity_manual_render_explains_explicit_finalization() {
        let temp = TempDir::new().unwrap();
        stub_scripts(
            temp.path(),
            &["session-start.sh", "pre-invocation.sh", "stop.sh"],
        );
        let output = render_agent_output(
            "antigravity-cli",
            temp.path(),
            "http://127.0.0.1:49374",
            None,
            None,
            &[&ANTIGRAVITY_LIFECYCLE_EVENTS],
        );

        assert!(output.contains("Antigravity has no conversation-end event"));
        assert!(output.contains("quiet for 10 minutes"));
        assert!(
            output.contains("ai-memory finalize-session --agent antigravity-cli"),
            "Antigravity install output must expose the supported finalizer: {output}"
        );
    }

    #[test]
    fn manual_agent_render_uses_agent_profile_not_physical_bundle_listing() {
        let temp = TempDir::new().unwrap();
        stub_scripts(
            temp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "stop.sh",
                "subagent-start.sh",
                "subagent-stop.sh",
            ],
        );

        let gemini = render_agent_output(
            "gemini-cli",
            temp.path(),
            "http://127.0.0.1:49374",
            None,
            None,
            &[GEMINI_PROFILE.events],
        );
        assert!(gemini.contains("session-start"));
        assert!(gemini.contains("session-end"));
        assert!(
            !gemini.contains("user-prompt-submit")
                && !gemini.contains("subagent-start")
                && !gemini.contains("subagent-stop"),
            "Gemini manual output must omit scripts outside Gemini's hook vocabulary: {gemini}"
        );

        let codex = render_agent_output(
            "codex",
            temp.path(),
            "http://127.0.0.1:49374",
            None,
            None,
            &[CODEX_PROFILE.events],
        );
        assert!(codex.contains("stop"));
        assert!(codex.contains("session-end"));
        assert!(
            !codex.contains("subagent-start") && !codex.contains("subagent-stop"),
            "Codex manual output must omit scripts outside Codex's hook vocabulary: {codex}"
        );
    }

    #[test]
    fn hook_server_url_defaults_to_configured_server_url() {
        let config = Config {
            server_url: "http://192.168.0.90:49374/".into(),
            ..Config::default()
        };
        let args = default_hook_args();

        assert_eq!(
            effective_hook_server_url(&config, &args, None),
            "http://192.168.0.90:49374"
        );
    }

    #[test]
    fn hook_server_url_explicit_flag_wins_over_config() {
        let config = Config {
            server_url: "http://homelab:49374".into(),
            ..Config::default()
        };
        let mut args = default_hook_args();
        args.server_url = Some("http://explicit:49374/".into());

        assert_eq!(
            effective_hook_server_url(&config, &args, None),
            "http://explicit:49374"
        );
    }

    /// Regression (found 2026-07-12 during Devin real-acceptance A/B
    /// testing): an explicit `--server-url` that happens to equal the
    /// compiled-in `DEFAULT_SERVER_URL` must still win over a configured
    /// (env/config.toml) server_url pointing somewhere else. Before the
    /// `Option<String>` fix, `args.server_url` was a plain `String` with
    /// `default_value_t = DEFAULT_SERVER_URL`, so clap couldn't
    /// distinguish "operator explicitly typed the default value" from
    /// "operator passed nothing at all" — both produced the same string,
    /// so this exact case silently fell through to `AI_MEMORY_SERVER_URL`
    /// / config.toml instead of honouring the explicit flag.
    #[test]
    fn hook_server_url_explicit_flag_matching_compiled_default_still_wins() {
        let config = Config {
            server_url: "http://127.0.0.1:49375".into(),
            ..Config::default()
        };
        let mut args = default_hook_args();
        args.server_url = Some(DEFAULT_SERVER_URL.to_string());

        assert_eq!(
            effective_hook_server_url(&config, &args, None),
            DEFAULT_SERVER_URL,
            "an explicit --server-url matching the compiled default must not be \
             silently overridden by a differently-configured server_url"
        );
    }

    /// Post-audit P1 — the new `ai-memory hook` subcommand (#84) builds
    /// its request URL by hand, skipping `Config::load` for latency. PR
    /// #82 made thin-client commands respect `AI_MEMORY_BASE_PATH` via
    /// `ServerEndpoint::build_url`, but the hook subcommand doesn't go
    /// through there — so a deployment under `--base-path /wiki` with
    /// the base set via env (not the URL path) had `ai-memory status`
    /// working and `ai-memory hook` 404'ing. Fix: install-hooks bakes
    /// the prefix into the URL it embeds, so hook.rs uses what it's
    /// given and stays unchanged.
    #[test]
    fn hook_server_url_threads_base_path_when_url_has_no_path() {
        let config = Config {
            server_url: "http://homelab:49374".into(),
            base_path: "/wiki".into(),
            ..Config::default()
        };
        let args = default_hook_args();
        assert_eq!(
            effective_hook_server_url(&config, &args, None),
            "http://homelab:49374/wiki",
            "URL baked into the hook command must carry the base-path so \
             `ai-memory hook` POSTs to /wiki/hook (not /hook)"
        );
    }

    /// If the operator already put the prefix into the URL itself, do
    /// NOT append `base_path` on top — that would double the prefix to
    /// `/wiki/wiki`.
    #[test]
    fn hook_server_url_does_not_double_base_path_when_already_in_url() {
        let config = Config {
            server_url: "http://homelab:49374/wiki".into(),
            base_path: "/wiki".into(),
            ..Config::default()
        };
        let args = default_hook_args();
        assert_eq!(
            effective_hook_server_url(&config, &args, None),
            "http://homelab:49374/wiki"
        );
    }

    #[test]
    fn hook_server_url_falls_back_to_existing_mcp_entry() {
        let config = Config::default();
        let args = default_hook_args();
        let inferred = InferredMcpConfig {
            hook_server_url: Some("http://homelab:49374".into()),
            auth_token: Some("tok".into()),
        };

        assert_eq!(
            effective_hook_server_url(&config, &args, Some(&inferred)),
            "http://homelab:49374"
        );
    }

    /// #1269: with only a custom `bind`, hooks reach the server that bind
    /// starts; an existing MCP entry still wins over the derived URL.
    #[test]
    fn hook_server_url_uses_a_bind_derived_url_after_an_existing_entry() {
        let config = Config {
            server_url: "http://127.0.0.1:49921".into(),
            server_url_derived_from_bind: true,
            ..Config::default()
        };
        let args = default_hook_args();
        assert_eq!(
            effective_hook_server_url(&config, &args, None),
            "http://127.0.0.1:49921"
        );
        let inferred = InferredMcpConfig {
            hook_server_url: Some("http://homelab:49374".into()),
            auth_token: None,
        };
        assert_eq!(
            effective_hook_server_url(&config, &args, Some(&inferred)),
            "http://homelab:49374"
        );
        assert_eq!(
            effective_hook_server_url(&Config::default(), &args, None),
            DEFAULT_SERVER_URL,
            "nothing derived and nothing inferred keeps the default"
        );
    }

    #[test]
    fn resolve_hooks_dir_uses_grok_bundle_for_grok() {
        let tmp = TempDir::new().unwrap();
        fs::create_dir_all(tmp.path().join("grok")).unwrap();
        fs::create_dir_all(tmp.path().join("claude-code")).unwrap();

        let resolved = resolve_hooks_dir(Some(tmp.path()), AgentChoice::Grok, tmp.path()).unwrap();
        assert_eq!(resolved, tmp.path().join("grok"));
    }

    #[test]
    fn resolve_hooks_dir_uses_pool_bundle_for_pool() {
        let tmp = TempDir::new().unwrap();
        fs::create_dir_all(tmp.path().join("pool")).unwrap();
        fs::create_dir_all(tmp.path().join("claude-code")).unwrap();

        let resolved = resolve_hooks_dir(Some(tmp.path()), AgentChoice::Pool, tmp.path()).unwrap();
        assert_eq!(resolved, tmp.path().join("pool"));
    }

    #[test]
    fn pool_settings_yaml_covers_all_events_with_bounded_entries() {
        let snippet = super::super::render_shared::build_pool_settings_yaml_with_data_dir(
            Path::new("/staging/pool"),
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Some(Path::new("/data")),
            Some("repo-root"),
        );
        assert!(snippet.starts_with("hooks:\n"), "snippet: {snippet}");
        for (event, script) in POOL_EVENTS {
            assert!(
                snippet.contains(&format!("  {event}:\n")),
                "missing {event} in: {snippet}"
            );
            let stem = script.strip_suffix(".sh").unwrap();
            assert!(
                snippet.contains(&format!("- name: ai-memory-{stem}\n")),
                "missing name for {event} in: {snippet}"
            );
        }
        assert_eq!(
            snippet.matches("matcher: \"*\"").count(),
            POOL_EVENTS.len(),
            "one wildcard matcher per event"
        );
        assert_eq!(
            snippet.matches("timeout: 20").count(),
            POOL_EVENTS.len(),
            "one bounded timeout per event"
        );
        // Every command is a YAML single-quoted scalar so the embedded POSIX
        // quoting survives; the auth token rides inside the command.
        assert_eq!(
            snippet.matches("command: '").count(),
            POOL_EVENTS.len(),
            "one single-quoted command per event"
        );
        assert!(snippet.contains("tok-test"), "auth token must be embedded");
    }

    #[test]
    fn render_pool_output_states_manual_paste_and_finalize_path() {
        let out = render_pool_output(
            Path::new("/staging/pool"),
            "http://127.0.0.1:49374",
            None,
            Path::new("/data"),
            None,
        );
        assert!(out.contains(".poolside/settings.yaml"));
        assert!(out.contains("does not write committed project files"));
        assert!(out.contains("finalize-session --agent pool"));
        assert!(out.contains("memory_handoff_accept"));
        assert!(out.contains("hooks:\n"));
        // No token was passed, so none of the auth caution lines render.
        assert!(!out.contains("AI_MEMORY_AUTH_TOKEN embedded"));
    }

    #[test]
    fn render_dsh_output_covers_all_bridge_events_and_states_manual_paste() {
        let out = render_dsh_output(
            Path::new("/staging/dsh"),
            "http://127.0.0.1:49374",
            None,
            Path::new("/data"),
            None,
        );
        // The Claude Code hooks.json document is embedded for the bridge.
        assert!(out.contains("\"hooks\""));
        for (event, _script) in DSH_EVENTS {
            assert!(
                out.contains(&format!("\"{event}\"")),
                "missing {event} in: {out}"
            );
        }
        // The seven bridge events, no more (keyed JSON, so the prose
        // mentions of the omitted events in the guidance do not match).
        assert!(!out.contains("\"PreCompact\""), "no PreCompact: {out}");
        assert!(!out.contains("\"SessionEnd\""), "no SessionEnd: {out}");
        // Manual merge guidance + the finalize/close path.
        assert!(out.contains("cordis.patch.yml"));
        assert!(out.contains("finalize-session --agent dsh"));
        assert!(out.contains("memory_handoff_accept"));
        assert!(out.contains("@deepseek-ai/dsh-hooks-claude-code"));
        assert!(out.contains("configPath"));
        // No token was passed, so none of the auth caution lines render.
        assert!(!out.contains("AI_MEMORY_AUTH_TOKEN embedded"));
    }

    #[test]
    fn dsh_bridge_patch_fragment_quotes_the_config_path() {
        let out = dsh_bridge_patch_fragment(Path::new("/tmp/ai memory/hooks/dsh"));
        assert!(out.contains("- insert:\n"));
        assert!(out.contains("    - id: ai-memory-hooks\n"));
        assert!(out.contains("name: '@deepseek-ai/dsh-hooks-claude-code'"));
        // A path with spaces must stay a single quoted YAML scalar (the
        // separator follows the host platform, hence Path::join).
        let expected = Path::new("/tmp/ai memory/hooks/dsh")
            .join("hooks.json")
            .display()
            .to_string();
        assert!(
            out.contains(&format!("configPath: '{expected}'")),
            "expected quoted configPath in: {out}"
        );
    }

    #[test]
    fn apply_to_dsh_stages_scripts_and_writes_hooks_json() {
        let root = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        // Mirror the repo layout: `hooks/_lib.sh` one level above the
        // `hooks/dsh` agent bundle, so staging copies the shared helper
        // alongside the event scripts.
        let source = root.path().join("hooks").join("dsh");
        fs::create_dir_all(&source).unwrap();
        let scripts = DSH_EVENTS
            .iter()
            .map(|(_, script)| *script)
            .collect::<Vec<_>>();
        stub_scripts(&source, &scripts);
        fs::write(root.path().join("hooks").join("_lib.sh"), "#!/bin/sh\n").unwrap();
        let mut args = default_hook_args();
        args.agent = AgentChoice::Dsh;
        apply_to_dsh(&source, "http://127.0.0.1:49374", None, data.path(), &args)
            .expect("apply_to_dsh succeeds");

        let staged = data.path().join("hooks").join("dsh");
        assert!(staged.join("session-start.sh").is_file(), "scripts staged");
        assert!(
            staged.join("_lib.sh").is_file(),
            "the shared _lib.sh helper is staged alongside"
        );
        let hooks_json = staged.join("hooks.json");
        assert!(hooks_json.is_file(), "hooks.json materialized");
        let doc: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&hooks_json).unwrap())
                .expect("hooks.json parses");
        let hooks = doc.get("hooks").expect("hooks key").as_object().unwrap();
        assert_eq!(hooks.len(), DSH_EVENTS.len(), "one entry per bridge event");
        for (event, _script) in DSH_EVENTS {
            assert!(hooks.contains_key(event), "missing {event}");
        }
    }

    #[test]
    fn powershell_fallback_drops_raw_dsh_assistant_output() {
        let helper = fs::read_to_string(
            Path::new(env!("CARGO_MANIFEST_DIR")).join("../../hooks/lib/ai-memory-hook.ps1"),
        )
        .unwrap();
        assert!(
            helper.contains(
                "($Agent -eq \"claude-code\" -or $Agent -eq \"dsh\") -and $Event -eq \"stop\""
            ),
            "DSH must share the raw Stop-field refusal with Claude Code"
        );
    }

    #[cfg(unix)]
    #[test]
    fn apply_to_dsh_keeps_an_embedded_bearer_owner_only() {
        use std::os::unix::fs::PermissionsExt as _;

        let root = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let source = root.path().join("hooks").join("dsh");
        fs::create_dir_all(&source).unwrap();
        let scripts = DSH_EVENTS
            .iter()
            .map(|(_, script)| *script)
            .collect::<Vec<_>>();
        stub_scripts(&source, &scripts);
        fs::write(root.path().join("hooks").join("_lib.sh"), "#!/bin/sh\n").unwrap();

        let staged = data.path().join("hooks").join("dsh");
        fs::create_dir_all(&staged).unwrap();
        let hooks_json = staged.join("hooks.json");
        fs::write(&hooks_json, "{}").unwrap();
        fs::set_permissions(&hooks_json, fs::Permissions::from_mode(0o644)).unwrap();

        let mut args = default_hook_args();
        args.agent = AgentChoice::Dsh;
        apply_to_dsh(
            &source,
            "http://127.0.0.1:49374",
            Some("private-bearer"),
            data.path(),
            &args,
        )
        .expect("apply_to_dsh succeeds");

        assert_eq!(
            fs::metadata(&hooks_json).unwrap().permissions().mode() & 0o777,
            0o600
        );
        let content = fs::read_to_string(hooks_json).unwrap();
        assert!(content.contains("private-bearer"));
    }

    #[cfg(unix)]
    #[test]
    fn apply_to_dsh_refuses_a_symlinked_hook_config() {
        use std::os::unix::fs::symlink;

        let root = TempDir::new().unwrap();
        let data = TempDir::new().unwrap();
        let source = root.path().join("hooks").join("dsh");
        fs::create_dir_all(&source).unwrap();
        let scripts = DSH_EVENTS
            .iter()
            .map(|(_, script)| *script)
            .collect::<Vec<_>>();
        stub_scripts(&source, &scripts);
        fs::write(root.path().join("hooks").join("_lib.sh"), "#!/bin/sh\n").unwrap();

        let staged = data.path().join("hooks").join("dsh");
        fs::create_dir_all(&staged).unwrap();
        let target = data.path().join("foreign.json");
        fs::write(&target, "untouched").unwrap();
        symlink(&target, staged.join("hooks.json")).unwrap();

        let mut args = default_hook_args();
        args.agent = AgentChoice::Dsh;
        let error = apply_to_dsh(
            &source,
            "http://127.0.0.1:49374",
            Some("private-bearer"),
            data.path(),
            &args,
        )
        .expect_err("a final symlink must be refused");

        assert!(
            error
                .to_string()
                .contains("opening private DSH hook config")
        );
        assert_eq!(fs::read_to_string(target).unwrap(), "untouched");
    }

    /// Without the community plugin, Hermes' output wires the whole lifecycle
    /// natively and still states the manual paste step (ai-memory does not
    /// write `~/.hermes/config.yaml`).
    #[test]
    fn render_hermes_output_wires_the_lifecycle_without_the_plugin() {
        let tmp = tempfile::tempdir().unwrap();
        let plugin = tmp.path().join(".hermes").join("plugins").join("ai-memory");
        let out = render_hermes_output(
            "http://127.0.0.1:49374",
            None,
            Path::new("/data"),
            None,
            Some(&plugin),
        );
        assert!(out.contains("~/.hermes/config.yaml"));
        assert!(out.contains("ai-memory does not"));
        assert!(out.contains("hooks:\n"));
        assert!(out.contains("--agent hermes"));
        assert!(out.contains("without a shell"));
        for event in [
            "pre_tool_call:",
            "post_tool_call:",
            "on_session_start:",
            "pre_llm_call:",
            "on_session_end:",
            "on_session_finalize:",
        ] {
            assert!(out.contains(event), "missing {event}");
        }
        assert!(out.contains("--event session-end "));
        assert!(out.contains("--event user-prompt-submit "));
        assert!(out.contains("finalize-session --agent hermes"));
        // The operator learns what to drop if the plugin arrives later.
        assert!(out.contains(&plugin.display().to_string()));
        // The check cannot see a plugin installed under another profile.
        assert!(out.contains("another profile's HERMES_HOME"));
        // No token was passed, so the auth caution line stays out.
        assert!(!out.contains("chmod 600"));
    }

    /// With the community plugin installed, only the tool events are wired:
    /// the plugin already posts prompts and session ends and claims the
    /// handoff, so a second lifecycle path would double both.
    #[test]
    fn render_hermes_output_keeps_tool_events_only_beside_the_plugin() {
        let tmp = tempfile::tempdir().unwrap();
        let plugin = tmp.path().join(".hermes").join("plugins").join("ai-memory");
        fs::create_dir_all(&plugin).unwrap();
        let out = render_hermes_output(
            "http://127.0.0.1:49374",
            None,
            Path::new("/data"),
            None,
            Some(&plugin),
        );
        assert!(out.contains("pre_tool_call:"));
        assert!(out.contains("post_tool_call:"));
        for event in [
            "on_session_start:",
            "pre_llm_call:",
            "on_session_end:",
            "on_session_finalize:",
        ] {
            assert!(!out.contains(event), "{event} belongs to the plugin");
        }
        assert!(!out.contains("--event session-end"));
        assert!(!out.contains("--event user-prompt-submit"));
        assert!(out.contains("memory-provider plugin is installed at"));
        assert!(out.contains(&plugin.display().to_string()));
        // A disabled plugin left in place cannot be told apart.
        assert!(out.contains("hermes plugins disable"));
    }

    #[test]
    fn hermes_plugin_dir_follows_hermes_home_then_the_home_default() {
        let home = PathBuf::from("/home/alice");
        assert_eq!(
            hermes_plugin_dir_in(None, Some(home.clone())),
            Some(home.join(".hermes").join("plugins").join("ai-memory"))
        );
        assert_eq!(
            hermes_plugin_dir_in(Some("/srv/hermes".into()), Some(home.clone())),
            Some(
                PathBuf::from("/srv/hermes")
                    .join("plugins")
                    .join("ai-memory")
            )
        );
        // A blank HERMES_HOME is an unset expansion, not the filesystem root.
        assert_eq!(
            hermes_plugin_dir_in(Some("  ".into()), Some(home.clone())),
            Some(home.join(".hermes").join("plugins").join("ai-memory"))
        );
        assert_eq!(hermes_plugin_dir_in(None, None), None);
        // A file of that name is not an installed plugin.
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("ai-memory");
        fs::write(&file, "").unwrap();
        assert_eq!(hermes_hook_set(Some(&file)), HermesHookSet::Full);
        assert_eq!(hermes_hook_set(None), HermesHookSet::Full);
        assert_eq!(hermes_hook_set(Some(tmp.path())), HermesHookSet::ToolsOnly);
    }

    // Issue #156: Zero hook install writes exec-form entries into Zero's
    // hooks.json shape and merges around third-party hooks by id prefix.
    #[test]
    fn zero_hooks_config_covers_all_events_in_exec_form() {
        let payload = super::super::render_shared::build_zero_hooks_config(
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Some(Path::new("/data")),
            Some("repo-root"),
        );
        assert_eq!(payload["enabled"], serde_json::json!(true));
        let hooks = payload["hooks"].as_array().unwrap();
        assert_eq!(hooks.len(), 6, "one entry per Zero lifecycle event");
        let events: Vec<&str> = hooks.iter().map(|h| h["event"].as_str().unwrap()).collect();
        for zero_event in [
            "sessionStart",
            "sessionEnd",
            "beforeTool",
            "afterTool",
            "specialistStart",
            "specialistStop",
        ] {
            assert!(events.contains(&zero_event), "missing {zero_event}");
        }
        for hook in hooks {
            let id = hook["id"].as_str().unwrap();
            assert!(id.starts_with("ai-memory-"), "ownership prefix: {id}");
            assert!(hook["enabled"].as_bool().unwrap());
            let args: Vec<&str> = hook["args"]
                .as_array()
                .unwrap()
                .iter()
                .map(|a| a.as_str().unwrap())
                .collect();
            // Exec form: the native hook subcommand with agent + auth +
            // strategy — never a shell string.
            assert!(args.contains(&"hook"), "{args:?}");
            assert!(
                args.contains(&"--agent") && args.contains(&"zero"),
                "{args:?}"
            );
            assert!(args.contains(&"--auth-token") && args.contains(&"tok-test"));
            assert!(args.contains(&"--project-strategy") && args.contains(&"repo-root"));
            assert!(args.contains(&"--data-dir") && args.contains(&"/data"));
        }
    }

    #[test]
    fn zero_apply_merges_around_third_party_hooks_and_preserves_disabled_flag() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("hooks.json");
        fs::write(
            &path,
            r#"{"enabled": false, "hooks": [
                {"id": "my-custom-hook", "event": "beforeTool",
                 "command": "/usr/bin/true", "args": [], "enabled": true},
                {"id": "ai-memory-session-start", "event": "sessionStart",
                 "command": "/old/ai-memory", "args": [], "enabled": true}
            ]}"#,
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Zero,
            capture_assistant: false,
            config_file: Some(path.clone()),
            ..default_hook_args()
        };

        apply_to_zero_hooks("http://127.0.0.1:49374", None, Path::new("/data"), &args).unwrap();

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&path).unwrap()).unwrap();
        assert_eq!(
            root["enabled"],
            serde_json::json!(false),
            "a user-disabled hooks file must stay disabled (we warn instead)"
        );
        let hooks = root["hooks"].as_array().unwrap();
        assert!(
            hooks
                .iter()
                .any(|h| h["id"] == serde_json::json!("my-custom-hook")),
            "third-party hooks must survive the merge"
        );
        let ours: Vec<&serde_json::Value> = hooks
            .iter()
            .filter(|h| {
                h["id"]
                    .as_str()
                    .is_some_and(|id| id.starts_with("ai-memory-"))
            })
            .collect();
        assert_eq!(
            ours.len(),
            6,
            "stale ai-memory entries replaced, not duplicated"
        );
        assert!(
            ours.iter()
                .all(|h| h["command"] != serde_json::json!("/old/ai-memory")),
            "the stale command path must be replaced"
        );
    }

    // Issue #1172: Zero runs hooks in its sandbox (no network, read-only
    // `/`), so the install note must say how events get delivered.
    #[test]
    fn zero_install_notes_explain_the_hook_sandbox() {
        let notes = zero_install_notes(Path::new("/data/ai-memory").display());
        assert!(notes.contains("sessionStart"), "{notes}");
        assert!(notes.contains("sandbox"), "{notes}");
        assert!(notes.contains("~/.config/zero/config.json"), "{notes}");
        assert!(notes.contains(r#""network": "allow""#), "{notes}");
        assert!(
            notes.contains(r#""additionalWriteRoots": ["/data/ai-memory"]"#),
            "{notes}"
        );
        assert!(notes.contains(r#""enabled": false"#), "{notes}");
        assert!(notes.contains("hook-drain"), "{notes}");
        assert!(notes.contains("sessionEnd delivers in-process"), "{notes}");
        assert!(notes.lines().all(|l| l.starts_with('#')), "{notes}");
    }

    #[test]
    fn zcode_hooks_config_covers_all_events_with_strict_entries() {
        let payload = super::super::render_shared::build_zcode_hooks_config(
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Some(Path::new("/data")),
            Some("repo-root"),
        );
        assert_eq!(payload["enabled"], serde_json::json!(true));
        // Raised above ZCode's 32 KiB default so a fetched handoff is not
        // truncated before injection.
        assert_eq!(payload["maxOutputBytes"], serde_json::json!(65536));
        let events = payload["events"].as_object().unwrap();
        assert_eq!(
            events.len(),
            super::super::render_shared::ZCODE_EVENTS.len(),
            "one entry per documented ZCode trigger"
        );
        for (zcode_event, our_event) in super::super::render_shared::ZCODE_EVENTS {
            let groups = events[zcode_event].as_array().unwrap();
            assert_eq!(groups.len(), 1, "{zcode_event}: one matcher group");
            let hooks = groups[0]["hooks"].as_array().unwrap();
            assert_eq!(hooks.len(), 1, "{zcode_event}: one hook entry");
            let hook = &hooks[0];
            // Exec form: `type: "process"` spawns command + args with no
            // shell, so every key must be from ZCode's documented schema —
            // undocumented keys make it drop the entry.
            assert_eq!(hook["type"], serde_json::json!("process"), "{zcode_event}");
            assert_eq!(
                hook["statusMessage"].as_str().unwrap(),
                "ai-memory capture",
                "{zcode_event}: ownership marker"
            );
            assert_eq!(hook["timeoutMs"], serde_json::json!(10_000));
            for key in hook.as_object().unwrap().keys() {
                assert!(
                    matches!(
                        key.as_str(),
                        "type" | "command" | "args" | "enabled" | "timeoutMs" | "statusMessage"
                    ),
                    "{zcode_event}: undocumented hook key {key}"
                );
            }
            let args: Vec<&str> = hook["args"]
                .as_array()
                .unwrap()
                .iter()
                .map(|a| a.as_str().unwrap())
                .collect();
            assert!(args.contains(&"hook"), "{args:?}");
            assert!(
                args.contains(&"--event") && args.contains(&our_event),
                "{args:?}"
            );
            assert!(
                args.contains(&"--agent") && args.contains(&"zcode"),
                "{args:?}"
            );
            assert!(args.contains(&"--server-url") && args.contains(&"http://127.0.0.1:49374"));
            assert!(args.contains(&"--auth-token") && args.contains(&"tok-test"));
            assert!(args.contains(&"--data-dir") && args.contains(&"/data"));
            assert!(args.contains(&"--project-strategy") && args.contains(&"repo-root"));
        }
        // PostToolUseFailure fires instead of PostToolUse when the tool
        // throws; the loop above already proved it forwards onto the same
        // `post-tool-use` channel as its success sibling.
        assert!(events.contains_key("PostToolUseFailure"));
    }

    #[test]
    fn zcode_apply_preserves_siblings_and_is_idempotent() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("config.json");
        fs::write(
            &path,
            r#"{
  "theme": "dark",
  "model": {"main": "zai/glm-5.1"},
  "mcp": {"servers": {"other": {"type": "http", "url": "https://other.example/mcp"}}},
  "hooks": {
    "enabled": true,
    "events": {
      "SessionStart": [
        {"matcher": "Bash", "hooks": [
          {"type": "process", "command": "/usr/bin/true", "args": [], "enabled": true}
        ]},
        {"hooks": [
          {"type": "process", "command": "/old/ai-memory", "args": [],
           "enabled": true, "statusMessage": "ai-memory capture"}
        ]}
      ]
    }
  }
}"#,
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Zcode,
            capture_assistant: false,
            config_file: Some(path.clone()),
            ..default_hook_args()
        };

        apply_to_zcode_hooks(
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Path::new("/data"),
            &args,
        )
        .unwrap();
        let first = fs::read_to_string(&path).unwrap();
        apply_to_zcode_hooks(
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Path::new("/data"),
            &args,
        )
        .unwrap();
        let second = fs::read_to_string(&path).unwrap();

        assert_eq!(first, second, "re-apply must be a no-op");
        let root: serde_json::Value = serde_json::from_str(&second).unwrap();
        // Sibling config keys survive: hooks share the file with the model
        // and MCP registration (#511).
        assert_eq!(root["theme"], serde_json::json!("dark"));
        assert_eq!(root["model"]["main"], serde_json::json!("zai/glm-5.1"));
        assert_eq!(
            root["mcp"]["servers"]["other"]["url"],
            serde_json::json!("https://other.example/mcp")
        );
        // The handoff-injection stdout ceiling lands with the hooks block.
        assert_eq!(root["hooks"]["maxOutputBytes"], serde_json::json!(65536));
        let session_start = root["hooks"]["events"]["SessionStart"].as_array().unwrap();
        assert_eq!(
            session_start.len(),
            2,
            "the third-party matcher group must survive the merge"
        );
        let third_party = &session_start[0];
        assert_eq!(
            third_party["matcher"],
            serde_json::json!("Bash"),
            "third-party matcher groups are preserved untouched"
        );
        assert_eq!(
            third_party["hooks"][0]["command"],
            serde_json::json!("/usr/bin/true")
        );
        let ours = &session_start[1];
        assert_eq!(
            ours["hooks"][0]["command"],
            super::super::render_shared::build_zcode_hooks_config(
                "http://127.0.0.1:49374",
                Some("tok-test"),
                Some(Path::new("/data")),
                None
            )["events"]["SessionStart"][0]["hooks"][0]["command"],
            "the stale ai-memory command path must be replaced"
        );
        for (zcode_event, _) in super::super::render_shared::ZCODE_EVENTS {
            assert!(
                root["hooks"]["events"][zcode_event].is_array(),
                "missing {zcode_event}"
            );
        }
    }
    #[test]
    fn zcode_apply_withdraws_our_hooks_from_foreign_keys_and_keeps_the_rest() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("config.json");
        // Keys outside `ZCODE_EVENTS`. ZCode rejects the whole block over
        // ones it does not recognize, which is how #600 stayed invisible.
        // `SessionEnd` runs nothing, `PreCompact` holds only our entry, and
        // `Notification` mixes our entry with a hook we did not write.
        fs::write(
            &path,
            r#"{
  "hooks": {
    "enabled": true,
    "events": {
      "SessionEnd": [],
      "PreCompact": [
        {"hooks": [
          {"type": "process", "command": "/old/ai-memory", "args": [],
           "enabled": true, "statusMessage": "ai-memory capture"}
        ]}
      ],
      "Notification": [
        {"hooks": [
          {"type": "process", "command": "/old/ai-memory", "args": [],
           "enabled": true, "statusMessage": "ai-memory capture"},
          {"type": "process", "command": "/usr/bin/true", "args": [], "enabled": true}
        ]}
      ]
    }
  }
}"#,
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Zcode,
            capture_assistant: false,
            config_file: Some(path.clone()),
            ..default_hook_args()
        };

        apply_to_zcode_hooks(
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Path::new("/data"),
            &args,
        )
        .unwrap();

        let first = fs::read_to_string(&path).unwrap();
        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        let events = root["hooks"]["events"].as_object().unwrap();

        // Event keys are never deleted: they are not ai-memory's to remove.
        assert!(events.contains_key("SessionEnd"));
        assert!(events.contains_key("PreCompact"));
        // Our own stale entry is withdrawn wherever it sits.
        assert_eq!(
            events["PreCompact"][0]["hooks"].as_array().unwrap().len(),
            0,
            "our entry under a key we no longer write must be withdrawn"
        );
        // The mixed group is the only case where the ownership filter
        // decides anything: the foreign hook survives, ours does not.
        let notification = events["Notification"][0]["hooks"].as_array().unwrap();
        assert_eq!(notification.len(), 1, "the hook we did not write must stay");
        assert_eq!(
            notification[0]["command"],
            serde_json::json!("/usr/bin/true")
        );
        for (zcode_event, _) in super::super::render_shared::ZCODE_EVENTS {
            assert!(
                root["hooks"]["events"][zcode_event].is_array(),
                "missing {zcode_event}"
            );
        }

        // Re-apply is still a no-op once the withdrawal has happened.
        apply_to_zcode_hooks(
            "http://127.0.0.1:49374",
            Some("tok-test"),
            Path::new("/data"),
            &args,
        )
        .unwrap();
        assert_eq!(first, fs::read_to_string(&path).unwrap());
    }

    #[test]
    fn zcode_event_runs_nothing_covers_degenerate_matcher_groups() {
        // Each of these leaves the key present but unable to run anything,
        // which is what makes ZCode reject the block while the file still
        // looks settled (#600).
        for shape in [
            serde_json::json!([]),
            serde_json::json!([{}]),
            serde_json::json!([{"matcher": "*"}]),
            serde_json::json!([{"hooks": []}]),
            serde_json::json!([{"hooks": null}]),
        ] {
            assert!(
                zcode_event_runs_nothing(&shape),
                "expected {shape} to run nothing"
            );
        }
        assert!(!zcode_event_runs_nothing(&serde_json::json!([
            {"hooks": [{"type": "process", "command": "/usr/bin/true"}]}
        ])));
        // A value that is not a matcher-group array cannot run hooks either,
        // and is doubly invalid to ZCode. It is left unmodified, but it is
        // still reported: staying quiet about it is the #600 failure.
        assert!(zcode_event_runs_nothing(&serde_json::json!(42)));
    }

    #[test]
    fn zcode_apply_flags_a_user_disabled_hooks_block() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("config.json");
        fs::write(&path, r#"{"hooks": {"enabled": false, "events": {}}}"#).unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Zcode,
            capture_assistant: false,
            config_file: Some(path.clone()),
            ..default_hook_args()
        };

        apply_to_zcode_hooks("http://127.0.0.1:49374", None, Path::new("/data"), &args).unwrap();

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&path).unwrap()).unwrap();
        assert_eq!(
            root["hooks"]["enabled"],
            serde_json::json!(false),
            "a user-disabled hooks block must stay disabled (we warn instead)"
        );
        assert_eq!(
            root["hooks"]["events"].as_object().unwrap().len(),
            super::super::render_shared::ZCODE_EVENTS.len()
        );
    }

    #[test]
    fn zcode_apply_respects_a_user_chosen_output_ceiling() {
        // `maxOutputBytes` is block-level and would also bound third-party
        // hooks, so a value the user chose is never overwritten.
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("config.json");
        fs::write(
            &path,
            r#"{"hooks": {"enabled": true, "maxOutputBytes": 4096, "events": {}}}"#,
        )
        .unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Zcode,
            capture_assistant: false,
            config_file: Some(path.clone()),
            ..default_hook_args()
        };

        apply_to_zcode_hooks("http://127.0.0.1:49374", None, Path::new("/data"), &args).unwrap();

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&path).unwrap()).unwrap();
        assert_eq!(root["hooks"]["maxOutputBytes"], serde_json::json!(4096));
    }

    #[test]
    fn resolve_hooks_dir_uses_devin_bundle_for_devin() {
        let tmp = TempDir::new().unwrap();
        fs::create_dir_all(tmp.path().join("devin")).unwrap();
        fs::create_dir_all(tmp.path().join("claude-code")).unwrap();

        let resolved = resolve_hooks_dir(Some(tmp.path()), AgentChoice::Devin, tmp.path()).unwrap();
        assert_eq!(resolved, tmp.path().join("devin"));
    }

    #[test]
    fn opencode_mcp_inference_supplies_hook_origin_and_token() {
        let inferred = infer_opencode_mcp_config(
            r#"{
              "mcp": {
                "ai-memory": {
                  "type": "remote",
                  "url": "http://homelab:49374/mcp",
                  "enabled": true,
                  "headers": { "Authorization": "Bearer secret-token" }
                }
              }
            }"#,
            McpClient::OpenCode,
        )
        .unwrap()
        .unwrap();

        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("http://homelab:49374")
        );
        assert_eq!(inferred.auth_token.as_deref(), Some("secret-token"));
    }

    #[test]
    fn opencode_mcp_inference_follows_owned_entries_across_major_transitions() {
        for (selected, content) in [
            (
                McpClient::OpenCode2,
                r#"{"mcp":{"ai-memory":{"type":"remote","url":"http://v1-host:49374/mcp","enabled":true,"headers":{"Authorization":"Bearer v1-token"}}}}"#,
            ),
            (
                McpClient::OpenCode,
                r#"{"mcp":{"servers":{"ai-memory":{"type":"remote","url":"http://v2-host:49374/mcp","oauth":false,"headers":{"Authorization":"Bearer v2-token"}}}}}"#,
            ),
        ] {
            let inferred = infer_opencode_mcp_config(content, selected)
                .unwrap()
                .unwrap();
            let expected = if selected == McpClient::OpenCode2 {
                ("http://v1-host:49374", "v1-token")
            } else {
                ("http://v2-host:49374", "v2-token")
            };
            assert_eq!(inferred.hook_server_url.as_deref(), Some(expected.0));
            assert_eq!(inferred.auth_token.as_deref(), Some(expected.1));
        }
    }

    #[test]
    fn opencode_hook_install_reuses_owned_mcp_settings_across_major_transitions() {
        for (agent, dialect, mcp_content, plugin_name, expected_server, expected_token) in [
            (
                AgentChoice::OpenCode2,
                ai_memory_workstream::OpenCodeDialect::V2,
                r#"{"mcp":{"ai-memory":{"type":"remote","url":"http://v1-host:49374/mcp","enabled":true,"headers":{"Authorization":"Bearer v1-token"}}}}"#,
                "ai-memory-opencode2.ts",
                "http://v1-host:49374",
                "v1-token",
            ),
            (
                AgentChoice::OpenCode,
                ai_memory_workstream::OpenCodeDialect::V1,
                r#"{"mcp":{"servers":{"ai-memory":{"type":"remote","url":"http://v2-host:49374/mcp","oauth":false,"headers":{"Authorization":"Bearer v2-token"}}}}}"#,
                "ai-memory.ts",
                "http://v2-host:49374",
                "v2-token",
            ),
        ] {
            let temp = tempfile::tempdir().unwrap();
            let mcp = temp.path().join("opencode.json");
            let plugin = temp.path().join(plugin_name);
            fs::write(&mcp, mcp_content).unwrap();
            let config = Config {
                data_dir: temp.path().join("data"),
                ..Config::default()
            };
            let mut args = default_hook_args();
            args.agent = agent;
            args.apply = true;
            args.config_file = Some(plugin.clone());
            args.server_url = None;
            args.auth_token = None;

            run_with_opencode_dialect_and_mcp_path(&config, args, Some(dialect), Some(&mcp))
                .unwrap();

            assert!(
                fs::read_to_string(plugin)
                    .unwrap()
                    .contains(expected_server)
            );
            assert_eq!(
                crate::config::read_hook_auth_token(&config.data_dir).as_deref(),
                Some(expected_token)
            );
        }
    }

    #[test]
    fn opencode_mcp_inference_accepts_matching_owned_entries() {
        let inferred = infer_opencode_mcp_config(
            r#"{"mcp":{"ai-memory":{"type":"remote","url":"http://same-host:49374/mcp","enabled":true,"headers":{"Authorization":"Bearer same-token"}},"servers":{"ai-memory":{"type":"remote","url":"http://same-host:49374/mcp","oauth":false,"headers":{"Authorization":"Bearer same-token"}}}}}"#,
            McpClient::OpenCode2,
        )
        .unwrap()
        .unwrap();
        assert_eq!(
            inferred,
            InferredMcpConfig {
                hook_server_url: Some("http://same-host:49374".to_string()),
                auth_token: Some("same-token".to_string()),
            }
        );
    }

    #[test]
    fn opencode_mcp_inference_rejects_conflicting_owned_entries() {
        let error = infer_opencode_mcp_config(
            r#"{"mcp":{"ai-memory":{"type":"remote","url":"http://v1-host:49374/mcp","enabled":true},"servers":{"ai-memory":{"type":"remote","url":"http://v2-host:49374/mcp","oauth":false}}}}"#,
            McpClient::OpenCode2,
        )
        .unwrap_err();
        assert!(
            error
                .to_string()
                .contains("conflicting generated OpenCode MCP entries")
        );
    }

    #[test]
    fn opencode_mcp_inference_ignores_user_owned_entries() {
        let inferred = infer_opencode_mcp_config(
            r#"{"mcp":{"ai-memory":{"type":"remote","url":"http://user-host:49374/mcp","enabled":true,"headers":{"Authorization":"Bearer user-token","X-User":"route"}}}}"#,
            McpClient::OpenCode,
        )
        .unwrap();
        assert_eq!(inferred, None);
    }

    /// Inferring the hook URL from Kimi Code's flavored mcp.json entry
    /// must yield the bare origin — hooks POST to `<origin>/hook`.
    #[test]
    fn kimi_code_mcp_inference_strips_flavor_query_and_mcp_path() {
        let inferred = infer_json_mcp_config(
            r#"{
              "mcpServers": {
                "ai-memory": {
                  "url": "http://homelab:49374/mcp?flavor=moonshot",
                  "headers": { "Authorization": "Bearer secret-token" }
                }
              }
            }"#,
            &["mcpServers", "ai-memory"],
            "url",
        )
        .unwrap();

        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("http://homelab:49374")
        );
        assert_eq!(inferred.auth_token.as_deref(), Some("secret-token"));
    }

    #[test]
    fn hook_server_url_from_mcp_url_strips_query_and_suffix() {
        for (input, expected) in [
            ("http://homelab:49374/mcp", Some("http://homelab:49374")),
            ("http://homelab:49374", Some("http://homelab:49374")),
            ("http://homelab:49374/", Some("http://homelab:49374")),
            (
                "http://homelab:49374/mcp?flavor=moonshot",
                Some("http://homelab:49374"),
            ),
            (
                "http://homelab:49374/mcp/?flavor=moonshot",
                Some("http://homelab:49374"),
            ),
            // Reverse-proxy prefix survives; hooks POST under it.
            (
                "http://homelab:49374/wiki/mcp",
                Some("http://homelab:49374/wiki"),
            ),
            (
                "http://homelab:49374/wiki/mcp?flavor=moonshot",
                Some("http://homelab:49374/wiki"),
            ),
            ("", None),
            ("   ", None),
        ] {
            assert_eq!(
                hook_server_url_from_mcp_url(input).as_deref(),
                expected,
                "input: {input:?}"
            );
        }
    }

    #[test]
    fn codex_mcp_inference_accepts_block_form_config() {
        let inferred = infer_toml_mcp_config(
            r#"[mcp_servers.ai-memory]
url = "http://homelab:49374/mcp"

[mcp_servers.ai-memory.http_headers]
Authorization = "Bearer secret-token"
"#,
        )
        .unwrap();

        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("http://homelab:49374")
        );
        assert_eq!(inferred.auth_token.as_deref(), Some("secret-token"));
    }

    /// With CODEX_HOME set, the MCP entry may still live in the legacy
    /// ~/.codex/config.toml from before install-mcp honored the variable.
    #[test]
    fn codex_mcp_inference_prefers_the_relocated_config_then_the_legacy_one() {
        let dir = tempfile::tempdir().unwrap();
        let relocated = dir.path().join("relocated.toml");
        let legacy = dir.path().join("legacy.toml");
        let entry = |url: &str| {
            format!(
                "[mcp_servers.ai-memory]\nurl = \"{url}/mcp\"\n\n\
                 [mcp_servers.ai-memory.http_headers]\nAuthorization = \"Bearer t\"\n"
            )
        };
        let candidates = || [relocated.clone(), legacy.clone()];

        assert!(infer_first_toml_mcp_config(candidates()).is_none());

        std::fs::write(&legacy, entry("http://legacy:49374")).unwrap();
        assert_eq!(
            infer_first_toml_mcp_config(candidates())
                .and_then(|inferred| inferred.hook_server_url)
                .as_deref(),
            Some("http://legacy:49374"),
            "a missing relocated config falls back to the legacy entry"
        );

        std::fs::write(&relocated, "[mcp_servers.other]\nurl = \"http://x\"\n").unwrap();
        assert_eq!(
            infer_first_toml_mcp_config(candidates())
                .and_then(|inferred| inferred.hook_server_url)
                .as_deref(),
            Some("http://legacy:49374"),
            "a relocated config without ai-memory still falls back"
        );

        std::fs::write(&relocated, entry("http://relocated:49374")).unwrap();
        assert_eq!(
            infer_first_toml_mcp_config(candidates())
                .and_then(|inferred| inferred.hook_server_url)
                .as_deref(),
            Some("http://relocated:49374"),
            "the relocated entry wins once it exists"
        );
    }

    #[test]
    fn grok_mcp_inference_accepts_headers_key() {
        let inferred = infer_toml_mcp_config(
            r#"[mcp_servers.ai-memory]
url = "http://homelab:49374/mcp"
enabled = true

[mcp_servers.ai-memory.headers]
Authorization = "Bearer secret-token"
"#,
        )
        .unwrap();

        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("http://homelab:49374")
        );
        assert_eq!(inferred.auth_token.as_deref(), Some("secret-token"));
    }

    /// Regression for issue #53 — `install-hooks --agent codex` used to
    /// panic with "index not found" when `~/.codex/config.toml` had an
    /// `[mcp_servers]` table populated with *other* servers (context7,
    /// node_repl, …) but no ai-memory entry. A perfectly valid setup —
    /// ai-memory can live in Codex via hooks only without being an MCP
    /// server — must return None, not abort the whole install.
    #[test]
    fn codex_mcp_inference_returns_none_when_ai_memory_entry_missing() {
        let inferred = infer_toml_mcp_config(
            r#"[mcp_servers.context7]
url = "http://localhost:9000/mcp"

[mcp_servers.node_repl]
command = "npx"
args = ["node-repl"]
"#,
        );
        assert!(
            inferred.is_none(),
            "missing [mcp_servers.ai-memory] must yield None, got {inferred:?}"
        );
    }

    /// Same regression class — no `[mcp_servers]` table at all means
    /// the user is on a hooks-only / fresh config; we should return
    /// None rather than panic on the first index.
    #[test]
    fn codex_mcp_inference_returns_none_when_no_mcp_servers_table() {
        let inferred = infer_toml_mcp_config(
            r#"# fresh codex config
model = "gpt-5"
"#,
        );
        assert!(inferred.is_none());
    }

    /// And the empty-file edge case the parser still accepts.
    #[test]
    fn codex_mcp_inference_returns_none_for_empty_doc() {
        assert!(infer_toml_mcp_config("").is_none());
    }

    /// An ai-memory entry that exists but ships neither a `url` nor an
    /// `Authorization` header still falls back to None (caller infers
    /// from defaults). Distinguishes "config absent" from "config
    /// present but unhelpful" — both yield None, neither panics.
    #[test]
    fn codex_mcp_inference_returns_none_for_bare_ai_memory_entry() {
        let inferred = infer_toml_mcp_config(
            r#"[mcp_servers.ai-memory]
# intentionally empty — no url, no headers.
"#,
        );
        assert!(inferred.is_none());
    }

    /// A `session-start.sh` that wraps the handoff in Claude Code's
    /// `hookSpecificOutput` envelope must have a PowerShell peer that asks for
    /// the same envelope. Bare text does not start with "{", so the harness
    /// logs "Hook output does not start with {, treating as plain text" and the
    /// handoff arrives unstructured — the exact failure the POSIX half was
    /// written to avoid. Enumerated rather than listed, so the next bundle
    /// cannot ship uncovered.
    #[test]
    fn a_posix_session_start_envelope_has_a_powershell_peer() {
        let hooks_root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("hooks");
        let mut checked = 0usize;
        for entry in fs::read_dir(&hooks_root).expect("hooks dir") {
            let dir = entry.expect("hooks entry").path();
            if !dir.is_dir() || dir.file_name().and_then(|n| n.to_str()) == Some("lib") {
                continue;
            }
            let posix = dir.join("session-start.sh");
            let shell = dir.join("session-start.ps1");
            if !posix.is_file() || !shell.is_file() {
                continue;
            }
            let posix_src = fs::read_to_string(&posix).expect("read session-start.sh");
            if !posix_src.contains("hookSpecificOutput") {
                continue;
            }
            let shell_src = fs::read_to_string(&shell).expect("read session-start.ps1");
            assert!(
                shell_src.contains("-SessionStartEnvelope"),
                "{} emits a hookSpecificOutput envelope but its PowerShell peer does not request one",
                posix.display()
            );
            checked += 1;
        }
        assert!(
            checked >= 3,
            "expected at least the claude-code, command-code and devin bundles to emit the envelope, found {checked}"
        );
    }

    #[test]
    fn bundled_posix_and_powershell_hooks_stay_in_parity() {
        let hooks_root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("hooks");
        assert!(
            hooks_root.join("lib").join("ai-memory-hook.ps1").is_file(),
            "PowerShell hooks require the shared lib helper"
        );

        // Enumerate the bundles instead of listing them: a hardcoded
        // list silently skips whatever agent lands next, which is how
        // `command-code` and `kiro-cli` shipped uncovered. `lib/` holds
        // the shared PowerShell helper, not an agent bundle.
        let mut agent_dirs: Vec<String> = fs::read_dir(&hooks_root)
            .unwrap_or_else(|e| panic!("failed to read {}: {e}", hooks_root.display()))
            .map(|entry| entry.unwrap().path())
            .filter(|path| path.is_dir())
            .filter_map(|path| path.file_name()?.to_str().map(str::to_string))
            .filter(|name| name != "lib")
            .collect();
        agent_dirs.sort();
        assert!(
            !agent_dirs.is_empty(),
            "no agent hook bundles found under {}",
            hooks_root.display()
        );

        for agent_dir in agent_dirs {
            let agent_dir = agent_dir.as_str();
            let dir = hooks_root.join(agent_dir);
            let mut sh = BTreeMap::new();
            let mut ps1 = BTreeMap::new();
            for entry in fs::read_dir(&dir).unwrap_or_else(|e| {
                panic!("failed to read bundled hook dir {}: {e}", dir.display())
            }) {
                let path = entry.unwrap().path();
                if !path.is_file() {
                    continue;
                }
                let Some(stem) = path.file_stem().and_then(|s| s.to_str()) else {
                    continue;
                };
                match path.extension().and_then(|s| s.to_str()) {
                    Some("sh") => {
                        sh.insert(stem.to_string(), extract_sh_hook_metadata(&path));
                    }
                    Some("ps1") => {
                        ps1.insert(stem.to_string(), extract_ps1_hook_metadata(&path));
                    }
                    _ => {}
                }
            }
            assert_eq!(
                sh.keys().collect::<Vec<_>>(),
                ps1.keys().collect::<Vec<_>>(),
                "{agent_dir}: every .sh hook must have a .ps1 peer"
            );
            for (stem, sh_meta) in sh {
                assert_eq!(
                    Some(sh_meta),
                    ps1.remove(&stem),
                    "{agent_dir}/{stem}: .sh and .ps1 must post the same event/agent"
                );
            }
        }
    }

    fn extract_sh_hook_metadata(path: &Path) -> (String, String) {
        let text = fs::read_to_string(path).unwrap();
        let marker = "hook?event=";
        let start = text
            .find(marker)
            .unwrap_or_else(|| panic!("{} missing hook endpoint", path.display()))
            + marker.len();
        let rest = &text[start..];
        let event = rest
            .split('&')
            .next()
            .unwrap_or_else(|| panic!("{} missing event", path.display()))
            .to_string();
        let agent_marker = "&agent=";
        let agent_start = rest
            .find(agent_marker)
            .unwrap_or_else(|| panic!("{} missing agent", path.display()))
            + agent_marker.len();
        let agent = rest[agent_start..]
            .split(['"', '\'', ' ', '\n', '\r', '$'])
            .next()
            .unwrap_or_else(|| panic!("{} missing agent value", path.display()))
            .to_string();
        (event, agent)
    }

    #[test]
    fn devin_bundle_has_no_subagent_scripts() {
        let hooks_root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("hooks");
        let devin_dir = hooks_root.join("devin");

        for entry in fs::read_dir(&devin_dir).unwrap() {
            let path = entry.unwrap().path();
            if !path.is_file() {
                continue;
            }
            let stem = path
                .file_stem()
                .and_then(|s| s.to_str())
                .unwrap_or("unknown");
            assert!(
                !stem.contains("subagent"),
                "Devin bundle should not contain subagent scripts, found: {}",
                path.display()
            );
        }
    }

    #[test]
    fn devin_bundle_has_post_compaction_not_pre_compact() {
        let hooks_root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("hooks");
        let devin_dir = hooks_root.join("devin");

        assert!(
            devin_dir.join("post-compaction.sh").is_file(),
            "Devin bundle must have post-compaction.sh"
        );
        assert!(
            devin_dir.join("post-compaction.ps1").is_file(),
            "Devin bundle must have post-compaction.ps1"
        );
        assert!(
            !devin_dir.join("pre-compact.sh").exists(),
            "Devin bundle should not have pre-compact.sh"
        );
        assert!(
            !devin_dir.join("pre-compact.ps1").exists(),
            "Devin bundle should not have pre-compact.ps1"
        );
    }

    fn extract_ps1_hook_metadata(path: &Path) -> (String, String) {
        let text = fs::read_to_string(path).unwrap();
        let line = text
            .lines()
            .find(|line| line.contains("Invoke-AiMemoryHook"))
            .unwrap_or_else(|| panic!("{} missing Invoke-AiMemoryHook", path.display()));
        (
            extract_ps1_arg(line, "Event", path),
            extract_ps1_arg(line, "Agent", path),
        )
    }

    fn extract_ps1_arg(line: &str, name: &str, path: &Path) -> String {
        let marker = format!("-{name} \"");
        let start = line
            .find(&marker)
            .unwrap_or_else(|| panic!("{} missing {name} argument", path.display()))
            + marker.len();
        line[start..]
            .split('"')
            .next()
            .unwrap_or_else(|| panic!("{} missing {name} value", path.display()))
            .to_string()
    }

    // ----------------------------------------------------------------
    // Shared `_lib.sh` staging
    // ----------------------------------------------------------------

    /// `stage_hook_scripts` copies the parent dir's `_lib.sh` alongside
    /// the agent's event scripts so the runtime layout doesn't depend
    /// on the source-tree shape. This is the only piece of evidence we
    /// have that the marker-file walk-up helper actually ships — the
    /// scripts themselves source it with `. "$(dirname "$0")/_lib.sh"`
    /// and a missing helper would surface as a runtime "command not
    /// found" much further from the cause.
    /// #581: inside the docker wrapper the server data dir is a volume
    /// the host cannot execute from; staging must fall back to the
    /// home-based path the wrapper bind-mounts and reads. Natively, the
    /// resolved data dir keeps winning (#554/#573).
    #[test]
    fn staging_root_leaves_the_container_volume_for_home() {
        let data = Path::new("/data");
        assert_eq!(
            hook_staging_root(data, false),
            PathBuf::from("/data"),
            "native installs stage under the resolved data dir"
        );
        let in_container = hook_staging_root(data, true);
        assert_ne!(
            in_container,
            PathBuf::from("/data"),
            "container staging must not target the volume"
        );
        assert_eq!(
            in_container,
            dirs::data_local_dir().unwrap().join("ai-memory"),
            "container staging targets the wrapper's bind-mounted home contract"
        );
    }

    #[test]
    fn stage_hook_scripts_copies_shared_lib_sh() {
        // Distinct agent_label per test: `stage_hook_scripts` writes
        // under `dirs::data_local_dir()/.../hooks/<agent_label>` and
        // the test binary runs cases in parallel, so two tests using
        // the same label race on the same staging dir.
        let tmp = TempDir::new().unwrap();
        let bundle = tmp.path().join("hooks");
        let agent_src = bundle.join("stage-shared-lib");
        fs::create_dir_all(&agent_src).unwrap();
        fs::write(bundle.join("_lib.sh"), "# shared helper\n").unwrap();
        stub_scripts(&agent_src, &["session-start.sh", "post-tool-use.sh"]);

        let data_dir = tmp.path().join("data");
        let staged = stage_hook_scripts_in(&agent_src, "stage-shared-lib", &data_dir).unwrap();
        assert!(staged.join("session-start.sh").exists());
        assert!(staged.join("post-tool-use.sh").exists());
        assert!(
            staged.join("_lib.sh").exists(),
            "_lib.sh must be staged alongside event scripts",
        );

        let lib = fs::read_to_string(staged.join("_lib.sh")).unwrap();
        assert!(
            lib.contains("shared helper"),
            "staged _lib.sh must match the source-of-truth"
        );
    }

    /// Skipping `_lib.sh` is fine — older source bundles without the
    /// marker-walk-up feature should still install cleanly.
    #[test]
    fn stage_hook_scripts_tolerates_missing_lib_sh() {
        let tmp = TempDir::new().unwrap();
        let bundle = tmp.path().join("hooks");
        let agent_src = bundle.join("stage-no-lib");
        fs::create_dir_all(&agent_src).unwrap();
        // Note: no _lib.sh in `bundle`.
        stub_scripts(&agent_src, &["session-start.sh"]);

        let data_dir = tmp.path().join("data");
        let staged = stage_hook_scripts_in(&agent_src, "stage-no-lib", &data_dir).unwrap();
        assert!(staged.join("session-start.sh").exists());
        assert!(!staged.join("_lib.sh").exists());
    }

    /// Regression for issue #52 — when `resolve_hooks_dir` picks the
    /// data-local dir as the source bundle (the docker `setup-agent`
    /// flow extracts scripts there) AND the staging destination is
    /// the *same* dir, the pre-fix wipe-then-copy loop would delete
    /// every populated script and report `staged 0`. The same-path
    /// branch must verify in place without wiping, so existing scripts
    /// survive a re-run.
    #[test]
    fn stage_hook_scripts_preserves_in_place_scripts_when_source_equals_dest() {
        let tmp = TempDir::new().unwrap();
        let data_dir = tmp.path().join("data");
        let agent_label = "stage-in-place";
        // Simulate "scripts already extracted into the data dir's hooks
        // dir by a prior `setup-agent` run".
        let in_place = data_dir.join("hooks").join(agent_label);
        fs::create_dir_all(&in_place).unwrap();
        stub_scripts(&in_place, &["session-start.sh", "post-tool-use.sh"]);

        // Source == destination (this is what resolve_hooks_dir hands
        // us when no other candidate exists).
        let staged = stage_hook_scripts_in(&in_place, agent_label, &data_dir).unwrap();

        assert_eq!(staged, in_place, "destination must canonicalize to source");
        assert!(
            staged.join("session-start.sh").is_file(),
            "in-place script must survive the same-path branch (not be wiped)"
        );
        assert!(
            staged.join("post-tool-use.sh").is_file(),
            "in-place script must survive the same-path branch (not be wiped)"
        );
    }

    /// Regression for issue #52 — the failure that the reporter actually
    /// hit: `resolve_hooks_dir` resolved to a pre-existing but empty
    /// data-local dir, so source == dest and there's nothing to verify.
    /// The pre-fix code silently returned Ok with `copied = 0` and the
    /// caller went on to rewrite `settings.json` against an empty dir,
    /// disabling capture without any error. We must bail with an
    /// actionable message instead.
    #[test]
    fn stage_hook_scripts_bails_when_source_equals_empty_dest() {
        let tmp = TempDir::new().unwrap();
        let data_dir = tmp.path().join("data");
        let agent_label = "stage-empty-in-place";
        // Must equal what `stage_hook_scripts_in` computes, or this stops
        // being the source==dest case it exists to cover and duplicates the
        // different-paths test below (#554 moved the destination shape).
        let in_place = data_dir.join("hooks").join(agent_label);
        fs::create_dir_all(&in_place).unwrap();
        // Intentionally no scripts in `in_place`.

        let err = stage_hook_scripts_in(&in_place, agent_label, &data_dir)
            .expect_err("an empty source dir must produce a hard error, not Ok(0)");
        let msg = format!("{err:#}");
        assert!(
            msg.contains("no hook scripts"),
            "error should call out the empty source: {msg}"
        );
        assert!(
            msg.contains("--hooks-dir") || msg.contains("setup-agent"),
            "error should point at the workaround (--hooks-dir or setup-agent): {msg}"
        );
    }

    /// Regression for issue #52 — same fail-on-zero guard applies even
    /// when source and dest are different paths (e.g. user pointed
    /// `--hooks-dir` at the wrong dir). Previously this also silently
    /// returned Ok with `copied = 0`.
    #[test]
    fn stage_hook_scripts_bails_when_source_dir_is_empty() {
        let tmp = TempDir::new().unwrap();
        let bundle = tmp.path().join("hooks");
        let agent_src = bundle.join("stage-empty-src");
        fs::create_dir_all(&agent_src).unwrap();
        // Source dir exists but has no scripts.

        let data_dir = tmp.path().join("data");
        let err = stage_hook_scripts_in(&agent_src, "stage-empty-src", &data_dir)
            .expect_err("zero scripts should be an error, not a silent success");
        assert!(format!("{err:#}").contains("no hook scripts"));
    }

    /// #554: with `AI_MEMORY_DATA_DIR` set, `install-hooks` probed and staged
    /// under the *platform default* instead of the data dir in use — so the
    /// server logged one path while `--apply` reported staging into another,
    /// silently populating a directory the operator was not using.
    #[test]
    fn a_configured_data_dir_is_where_the_bundle_is_probed_and_staged() {
        let tmp = TempDir::new().unwrap();
        let data_dir = tmp.path().join("custom-data");
        let source = tmp.path().join("bundle");
        fs::create_dir_all(&source).unwrap();
        fs::write(source.join("session-start.sh"), b"#!/bin/sh\n").unwrap();

        // Staged into the configured dir…
        let staged = stage_hook_scripts_in(&source, "claude-code", &data_dir).unwrap();
        assert_eq!(staged, data_dir.join("hooks").join("claude-code"));
        assert!(staged.join("session-start.sh").is_file());
        assert!(
            !tmp.path().join("ai-memory").exists(),
            "nothing may be written under a platform-default path"
        );

        // …and the probe looks in the same place, so the two halves agree.
        let candidates = hook_source_candidates("claude-code", None, None, Some(data_dir.clone()));
        assert!(
            candidates.contains(&data_dir.join("hooks").join("claude-code")),
            "the configured data dir must be probed; got {candidates:?}"
        );
    }

    /// The default install must be byte-identical to the old behaviour:
    /// `default_data_dir()` is `data_local_dir()/ai-memory`, so
    /// `<data_dir>/hooks/<agent>` is the same path the previous
    /// `<data_local>/ai-memory/hooks/<agent>` produced.
    #[test]
    fn the_default_data_dir_stages_to_the_same_path_as_before() {
        let tmp = TempDir::new().unwrap();
        let data_local = tmp.path().join(".local").join("share");
        let default_data_dir = data_local.join("ai-memory");
        let source = tmp.path().join("bundle");
        fs::create_dir_all(&source).unwrap();
        fs::write(source.join("session-start.sh"), b"#!/bin/sh\n").unwrap();

        let staged = stage_hook_scripts_in(&source, "claude-code", &default_data_dir).unwrap();
        assert_eq!(
            staged,
            data_local
                .join("ai-memory")
                .join("hooks")
                .join("claude-code"),
            "existing installs must keep staging exactly where they did"
        );
    }

    /// `install-hooks --agent codex --apply` writes to the CODEX_HOME that
    /// `Config::load` captured, not one re-read from the live process
    /// (invariant #1): an injected value decides the file.
    #[test]
    fn codex_apply_writes_under_the_captured_codex_home() {
        let home = TempDir::new().unwrap();
        let codex_home = TempDir::new().unwrap();
        let mut config =
            crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
        config.runtime_env = crate::config::RuntimeEnv::with_process_env_for_tests(&[(
            "CODEX_HOME",
            codex_home.path().to_str().unwrap(),
        )]);
        let args = InstallHooksArgs {
            agent: AgentChoice::Codex,
            apply: true,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            hooks_dir: Some(
                std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks"),
            ),
            ..default_hook_args()
        };

        run(&config, args).expect("apply should succeed");

        // Assert on the hook command, not the binary path: the test binary's
        // path depends on where the workspace is built.
        let written = std::fs::read_to_string(codex_home.path().join("hooks.json")).unwrap();
        assert!(
            written.contains("hook --event session-start --agent codex"),
            "{written}"
        );
    }

    /// #552, the regression guard: `--apply` must persist the bearer under the
    /// data dir and leave it out of the agent config entirely.
    ///
    /// Before this, the token was written into the rendered command — as
    /// `--auth-token <token>` for native hooks — so it sat in the agent's
    /// config file *and* in `/proc/<pid>/cmdline` for the lifetime of every
    /// hook, on every tool call.
    #[test]
    fn apply_persists_the_bearer_and_keeps_it_out_of_the_agent_config() {
        let home = TempDir::new().unwrap();
        let cfg_dir = TempDir::new().unwrap();
        let settings = cfg_dir.path().join("settings.json");
        std::fs::write(&settings, "{}").unwrap();

        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            apply: true,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            auth_token: Some("SEKRIT-BEARER-552".to_string()),
            config_file: Some(settings.clone()),
            // Point at the repo's bundle explicitly. Without this the test
            // leans on hook-dir discovery, which from `target/debug/deps`
            // walks to `<repo>/target` and then falls through to whatever the
            // machine happens to have staged — passing for a reason that has
            // nothing to do with what is under test.
            hooks_dir: Some(
                std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks"),
            ),
            ..default_hook_args()
        };

        run(&config, args).expect("apply should succeed");

        let rendered = std::fs::read_to_string(&settings).unwrap();
        assert!(
            !rendered.contains("SEKRIT-BEARER-552"),
            "the bearer must not be written into the agent config: {rendered}"
        );
        assert!(
            !rendered.contains("--auth-token"),
            "no --auth-token flag may reach a hook command line: {rendered}"
        );

        assert_eq!(
            crate::config::read_hook_auth_token(&config.data_dir).as_deref(),
            Some("SEKRIT-BEARER-552"),
            "the bearer must be persisted where the hook can read it"
        );
        assert!(
            std::fs::read_to_string(crate::config::hook_auth_header_path_in(&config.data_dir))
                .unwrap()
                .contains("SEKRIT-BEARER-552"),
            "the curl header file must carry it too"
        );
    }

    /// #993 regression guard: `--apply --as-user X --auth-token T` is the
    /// command docs/users.md tells operators to run, and it failed on every
    /// native install. The guard was handed the rendered credential, which is
    /// `None` precisely when the token was persisted (#552), so it reported the
    /// token as missing while the token sat under the data dir. The unit tests
    /// on `validate_as_user` itself could not see it — the wiring was wrong,
    /// not the function.
    #[test]
    fn apply_with_as_user_succeeds_when_the_token_is_persisted() {
        let home = TempDir::new().unwrap();
        let cfg_dir = TempDir::new().unwrap();
        let settings = cfg_dir.path().join("settings.json");
        std::fs::write(&settings, "{}").unwrap();

        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();

        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            apply: true,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            auth_token: Some("ALICE-KEY-993".to_string()),
            as_user: Some("alice".to_string()),
            config_file: Some(settings.clone()),
            hooks_dir: Some(
                std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks"),
            ),
            ..default_hook_args()
        };

        // The whole point of the fix: persisting the token must not turn a
        // present `--auth-token` into an "absent" one for the `--as-user` guard.
        run(&config, args).expect("install-hooks --apply --as-user with a token must succeed");

        // And the attribution it promised is real: the token is on disk for the
        // hooks, and still absent from the agent's own config.
        assert_eq!(
            crate::config::read_hook_auth_token(&config.data_dir).as_deref(),
            Some("ALICE-KEY-993"),
            "alice's key must be persisted where the hook reads it"
        );
        let rendered = std::fs::read_to_string(&settings).unwrap();
        assert!(
            !rendered.contains("ALICE-KEY-993"),
            "the bearer must not reach the agent config: {rendered}"
        );
    }

    /// F5 (docker-wrapper audit), the regression guard: when the bearer
    /// *cannot* be persisted under the data dir, `--apply` must still install
    /// working hooks by embedding the credential inline instead of aborting the
    /// whole install with no hooks at all.
    ///
    /// The real case is the docker wrapper: `data_dir` is `/data`, a container
    /// volume the host hooks never read from and that the container user often
    /// cannot write. Before this fix a persist failure hard-aborted, leaving the
    /// operator with neither the secure path nor any capture at all.
    #[test]
    fn apply_falls_back_to_inline_bearer_when_persisting_fails() {
        let home = TempDir::new().unwrap();
        let cfg_dir = TempDir::new().unwrap();
        let settings = cfg_dir.path().join("settings.json");
        std::fs::write(&settings, "{}").unwrap();

        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();

        // Make ONLY the secret write fail — like a data dir the installer cannot
        // write the token into — while leaving hook staging (which writes under
        // `<data_dir>/hooks/`) fully working: pre-create the `<data_dir>/auth-token`
        // path as a *directory*, so `write_secret`'s file open returns EISDIR.
        std::fs::create_dir_all(crate::config::hook_auth_token_path_in(&config.data_dir)).unwrap();

        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            apply: true,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            auth_token: Some("FALLBACK-BEARER-F5".to_string()),
            config_file: Some(settings.clone()),
            hooks_dir: Some(
                std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks"),
            ),
            ..default_hook_args()
        };

        // The whole point of the fix: a persist failure must not abort the install.
        run(&config, args).expect("apply must not abort when the bearer cannot be persisted");

        let rendered = std::fs::read_to_string(&settings).unwrap();
        assert!(
            rendered.contains("FALLBACK-BEARER-F5"),
            "the bearer must be embedded inline so the hooks still authenticate: {rendered}"
        );

        // It genuinely took the fallback, not the secure path: nothing persisted.
        assert_eq!(
            crate::config::read_hook_auth_token(&config.data_dir),
            None,
            "the token must not have been persisted in the failure case"
        );
    }

    /// New-install default: a token read from `[auth].bearer_token_file` is persisted for the
    /// hooks, and when persisting fails it is NOT embedded the way an inline
    /// token is (F5): that file exists to keep the token out of agent configs.
    #[test]
    fn a_file_sourced_token_is_persisted_but_never_embedded() {
        let home = TempDir::new().unwrap();
        let cfg_dir = TempDir::new().unwrap();
        let settings = cfg_dir.path().join("settings.json");
        let hooks_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks");
        let token = "FILE-SOURCED-ROOT-BEARER";
        let file_config = || {
            let mut config =
                crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
            let path = crate::server_profiles::root_token_path(&config.data_dir);
            config.auth.adopt_token_file(path, token.to_owned());
            config
        };
        let args = || InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            apply: true,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            config_file: Some(settings.clone()),
            hooks_dir: Some(hooks_dir.clone()),
            ..default_hook_args()
        };

        std::fs::write(&settings, "{}").unwrap();
        let config = file_config();
        run(&config, args()).unwrap();
        assert_eq!(
            crate::config::read_hook_auth_token(&config.data_dir).as_deref(),
            Some(token),
            "the hooks get the token through their credential files"
        );
        let rendered = std::fs::read_to_string(&settings).unwrap();
        assert!(!rendered.contains(token), "{rendered}");

        // The F5 failure shape: the credential file cannot be written.
        crate::config::clear_hook_auth_token(&config.data_dir).unwrap();
        std::fs::create_dir_all(crate::config::hook_auth_token_path_in(&config.data_dir)).unwrap();
        std::fs::write(&settings, "{}").unwrap();
        run(&config, args()).expect("a persist failure still installs the hooks");
        let rendered = std::fs::read_to_string(&settings).unwrap();
        assert!(
            !rendered.contains(token),
            "a file-sourced token must not fall back to the inline form: {rendered}"
        );
    }

    /// `--scope project` lands where Claude Code reads the file: the git root
    /// of the checkout, even from a subdirectory. A plain directory is its own
    /// root. On Windows, and when the repository root is the home directory,
    /// Claude Code reads the launch directory instead.
    #[test]
    fn project_claude_settings_local_resolves_where_claude_code_reads_it() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        let sub = repo.join("crates").join("x");
        std::fs::create_dir_all(&sub).unwrap();
        let status = std::process::Command::new("git")
            .args(["init", "-q"])
            .current_dir(&repo)
            .status()
            .unwrap();
        assert!(status.success(), "git init failed");
        let local = |dir: &Path| dir.join(".claude").join("settings.local.json");
        let unrelated_home = tmp.path().join("home");
        std::fs::create_dir_all(&unrelated_home).unwrap();
        // libgit2 reports the real path; compare canonicalised so a
        // /private/var vs /var prefix on macOS does not trip the assertion.
        let root_of = |file: PathBuf| {
            assert!(file.ends_with(Path::new(".claude").join("settings.local.json")));
            file.parent()
                .and_then(Path::parent)
                .unwrap()
                .canonicalize()
                .unwrap()
        };
        let repo_root = repo.canonicalize().unwrap();

        assert_eq!(
            root_of(project_claude_settings_local_for(
                &sub,
                false,
                Some(&unrelated_home)
            )),
            repo_root
        );
        assert_eq!(
            root_of(project_claude_settings_local_for(&sub, false, None)),
            repo_root,
            "an unknown home does not change the git-root rule"
        );
        assert_eq!(
            project_claude_settings_local_for(&sub, true, Some(&unrelated_home)),
            local(&sub),
            "Windows reads the launch directory, not the git root"
        );
        assert_eq!(
            project_claude_settings_local_for(&sub, false, Some(&repo)),
            local(&sub),
            "a repository rooted at home reads the launch directory"
        );

        let plain = tmp.path().join("plain");
        std::fs::create_dir_all(&plain).unwrap();
        for is_windows in [false, true] {
            assert_eq!(
                project_claude_settings_local_for(&plain, is_windows, Some(&unrelated_home)),
                local(&plain)
            );
        }
    }

    /// A project settings backup lands under the data dir with a stem that
    /// names the checkout, is a single safe file-name component, and keeps
    /// checkouts that flatten to the same text apart.
    #[test]
    fn project_settings_backup_stays_under_the_data_dir_per_checkout() {
        let data = Path::new("/data");
        let settings = |checkout: &str| {
            Path::new(checkout)
                .join(".claude")
                .join("settings.local.json")
        };
        let backup = project_settings_backup(data, &settings("/home/u/work/my repo"));
        assert_eq!(
            backup.dir,
            data.join("backups").join("claude-settings-local")
        );
        assert!(
            backup.stem.starts_with("home-u-work-my-repo-"),
            "{}",
            backup.stem
        );
        assert!(
            backup
                .stem
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '.' | '_')),
            "{}",
            backup.stem
        );
        assert_ne!(
            project_settings_backup(data, &settings("/a/b-c")).stem,
            project_settings_backup(data, &settings("/a-b/c")).stem
        );
        let deep = format!("/{}/repo", "x".repeat(300));
        let stem = project_settings_backup(data, &settings(&deep)).stem;
        assert!(stem.len() <= 64 + 13, "{stem}");
        assert!(stem.contains("repo-"), "the repository end is kept: {stem}");
    }

    /// `upgrade` and the `run` auto-wire use this to tell a `--scope project`
    /// install from a user-level one; a third-party hook alone must not count.
    #[test]
    fn settings_carry_ai_memory_hooks_recognizes_only_our_entries() {
        let ours = r#"{"hooks":{"Stop":[{"matcher":"","hooks":[{"type":"command","command":"AI_MEMORY_HOOK_URL=http://127.0.0.1:49374 /home/u/.local/share/ai-memory/hooks/claude-code/stop.sh"}]}]}}"#;
        assert!(settings_carry_ai_memory_hooks(ours));
        let third_party = r#"{"hooks":{"Notification":[{"matcher":"","hooks":[{"type":"command","command":"/usr/bin/n.sh"}]}]}}"#;
        assert!(!settings_carry_ai_memory_hooks(third_party));
        assert!(!settings_carry_ai_memory_hooks(r#"{"permissions":{}}"#));
        assert!(!settings_carry_ai_memory_hooks("not json"));
    }

    /// Project scope names a Claude Code file; no other agent has a
    /// project-local hook file ai-memory writes, so the install must fail
    /// before it stages anything.
    #[test]
    fn project_scope_is_rejected_for_agents_without_a_project_file() {
        let home = TempDir::new().unwrap();
        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Codex,
            scope: HookInstallScope::Project,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            hooks_dir: Some(PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks")),
            // Unreachable from the CLI (clap rejects the pair); set only so a
            // regression writes into the temp dir, not the real ~/.codex.
            config_file: Some(home.path().join("hooks.json")),
            ..default_hook_args()
        };
        let err = run(&config, args).unwrap_err();
        assert!(err.to_string().contains("--scope project"), "{err:#}");
        assert!(
            !config
                .data_dir
                .join(crate::install_layout::HOOKS_DIR_NAME)
                .exists(),
            "nothing may be staged after a refused install"
        );
    }

    /// The inline-bearer fallback (F5 above) writes the token into the hook
    /// config. Inside a checkout that file can be committed, so project scope
    /// refuses the fallback instead of taking it.
    #[test]
    fn project_scope_refuses_the_inline_bearer_when_persisting_fails() {
        let home = TempDir::new().unwrap();
        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
        // Same EISDIR trick as the fallback test: only the secret write fails.
        std::fs::create_dir_all(crate::config::hook_auth_token_path_in(&config.data_dir)).unwrap();
        let settings = home.path().join("settings.local.json");
        let args = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            scope: HookInstallScope::Project,
            apply: true,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            auth_token: Some("PROJECT-BEARER".to_string()),
            hooks_dir: Some(PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks")),
            // Unreachable from the CLI (clap rejects the pair); set only so a
            // regression writes into the temp dir, not this checkout.
            config_file: Some(settings.clone()),
            ..default_hook_args()
        };
        let err = run(&config, args).unwrap_err();
        assert!(format!("{err:#}").contains("refusing to embed"), "{err:#}");
        assert!(!settings.exists(), "no config may be written on refusal");
        assert_eq!(crate::config::read_hook_auth_token(&config.data_dir), None);
    }

    fn claude_apply_args(
        settings: &std::path::Path,
        hooks_dir: &std::path::Path,
        capture_assistant: bool,
    ) -> InstallHooksArgs {
        InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            apply: true,
            capture_assistant,
            server_url: Some("http://127.0.0.1:49374".to_string()),
            config_file: Some(settings.to_path_buf()),
            hooks_dir: Some(hooks_dir.to_path_buf()),
            ..default_hook_args()
        }
    }

    /// Regression for the auto-wire capture-downgrade (post-audit S1): a bare
    /// `--apply` without `--capture-assistant` — exactly what `ai-memory run`
    /// auto-wire issues — must PRESERVE a user's existing assistant-capture
    /// opt-in, not silently strip it.
    ///
    /// Unix-gated because this end-to-end render uses the host platform. The
    /// parser itself has a platform-independent Windows exec-form regression.
    #[cfg(unix)]
    #[test]
    fn a_bare_reapply_preserves_an_existing_capture_assistant_opt_in() {
        let home = TempDir::new().unwrap();
        let cfg_dir = TempDir::new().unwrap();
        let settings = cfg_dir.path().join("settings.json");
        std::fs::write(&settings, "{}").unwrap();
        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
        let hooks_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks");

        run(&config, claude_apply_args(&settings, &hooks_dir, true)).expect("first install");
        assert!(
            std::fs::read_to_string(&settings)
                .unwrap()
                .contains("--capture-assistant"),
            "the explicit opt-in must be baked on the first install"
        );

        // A bare re-apply (the auto-wire shape: capture_assistant = false).
        run(&config, claude_apply_args(&settings, &hooks_dir, false)).expect("bare re-apply");
        assert!(
            std::fs::read_to_string(&settings)
                .unwrap()
                .contains("--capture-assistant"),
            "a bare re-apply must preserve the existing --capture-assistant opt-in"
        );
    }

    #[test]
    fn windows_exec_form_preserves_capture_assistant_from_args() {
        let settings = serde_json::json!({
            "hooks": {
                "Stop": [{
                    "hooks": [{
                        "type": "command",
                        "command": r"C:\Program Files\ai-memory\ai-memory.exe",
                        "args": ["hook", "--event", "stop", "--agent", "claude-code", "--server-url", "http://127.0.0.1:49374", "--capture-assistant"]
                    }]
                }]
            }
        });
        assert_eq!(
            baked_capture_assistant(&serde_json::to_string(&settings).unwrap()),
            Some(true)
        );
    }

    /// The preserve logic must not false-positive: a fresh install without the
    /// flag stays off.
    #[test]
    fn a_fresh_install_without_the_flag_leaves_assistant_capture_off() {
        let home = TempDir::new().unwrap();
        let cfg_dir = TempDir::new().unwrap();
        let settings = cfg_dir.path().join("settings.json");
        std::fs::write(&settings, "{}").unwrap();
        let config = crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
        let hooks_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../hooks");

        run(&config, claude_apply_args(&settings, &hooks_dir, false)).expect("fresh install");
        assert!(
            !std::fs::read_to_string(&settings)
                .unwrap()
                .contains("--capture-assistant"),
            "a fresh install without the flag must not enable assistant capture"
        );
    }

    #[test]
    fn hook_source_candidates_include_native_package_dir() {
        let candidates = hook_source_candidates(
            "claude-code",
            Some(PathBuf::from("/repo")),
            Some(PathBuf::from("/opt/ai-memory")),
            // The resolved data dir, not the platform data-local root (#554).
            Some(PathBuf::from("/home/alice/.local/share/ai-memory")),
        );

        assert_eq!(candidates[0], PathBuf::from("/repo/hooks/claude-code"));
        assert_eq!(
            candidates[1],
            PathBuf::from("/opt/ai-memory/hooks/claude-code")
        );
        assert_eq!(
            candidates[2],
            PathBuf::from("/usr/local/share/ai-memory/hooks/claude-code")
        );
        assert_eq!(
            candidates[3],
            PathBuf::from("/usr/share/ai-memory/hooks/claude-code")
        );
        assert_eq!(
            candidates[4],
            PathBuf::from("/home/alice/.local/share/ai-memory/hooks/claude-code")
        );
    }

    /// Nix ships hook sources 0444 and `fs::copy` keeps that mode, so a
    /// second `install-hooks` used to fail copying onto its own staged copy.
    #[cfg(unix)]
    #[test]
    fn staging_replaces_read_only_existing_copies() {
        use std::os::unix::fs::PermissionsExt;
        let tmp = tempfile::TempDir::new().unwrap();
        let source = tmp.path().join("src/hooks/claude-code");
        fs::create_dir_all(source.parent().unwrap().join("lib")).unwrap();
        fs::create_dir_all(&source).unwrap();
        let script = source.join("session-start.sh");
        let support = source.parent().unwrap().join("lib/helper.ps1");
        fs::write(&script, "new\n").unwrap();
        fs::write(&support, "new\n").unwrap();
        let dest = tmp.path().join("dest/hooks/claude-code");
        fs::create_dir_all(dest.parent().unwrap().join("lib")).unwrap();
        fs::create_dir_all(&dest).unwrap();
        let staged = [
            dest.join("session-start.sh"),
            dest.parent().unwrap().join("lib/helper.ps1"),
        ];
        for path in &staged {
            fs::write(path, "old\n").unwrap();
            fs::set_permissions(path, fs::Permissions::from_mode(0o444)).unwrap();
        }

        copy_hook_file(&script, &dest).unwrap();
        copy_support_hook_scripts(&source, &dest).unwrap();

        for path in &staged {
            assert_eq!(
                fs::read_to_string(path).unwrap(),
                "new\n",
                "{}",
                path.display()
            );
        }
    }

    #[test]
    fn hook_source_candidates_include_standard_prefix_share_dir() {
        let candidates = hook_source_candidates(
            "claude-code",
            None,
            Some(PathBuf::from("/nix/store/pkg/bin")),
            None,
        );

        assert!(
            candidates.contains(&PathBuf::from(
                "/nix/store/pkg/share/ai-memory/hooks/claude-code"
            )),
            "standard prefix share hooks/ dir must be probed; got {candidates:?}"
        );
    }

    #[test]
    fn hook_source_candidates_ignores_non_bin_parent_for_prefix_share() {
        let candidates = hook_source_candidates(
            "claude-code",
            None,
            Some(PathBuf::from("/opt/ai-memory")),
            None,
        );

        assert!(
            !candidates.contains(&PathBuf::from("/opt/share/ai-memory/hooks/claude-code")),
            "non-bin exe dir must not probe parent share dir; got {candidates:?}"
        );
    }

    /// #546: `~/.local/bin/ai-memory -> <repo>/target/release/ai-memory` is
    /// what the quick start's `~/.local/bin` layout produces for a source
    /// build. Discovery is derived from the binary's own location, so the
    /// link has to be resolved first or every candidate misses the checkout.
    #[cfg(unix)]
    #[test]
    fn hooks_are_found_through_a_symlinked_binary() {
        let tmp = tempfile::tempdir().unwrap();
        let repo = tmp.path().join("repo");
        let exe = repo.join("target").join("release").join("ai-memory");
        fs::create_dir_all(exe.parent().unwrap()).unwrap();
        fs::write(&exe, b"").unwrap();
        let link_dir = tmp.path().join("home").join(".local").join("bin");
        fs::create_dir_all(&link_dir).unwrap();
        let link = link_dir.join("ai-memory");
        std::os::unix::fs::symlink(&exe, &link).unwrap();

        let resolved = resolve_exe_path(link);
        let candidates = hook_source_candidates(
            "claude-code",
            repo_root_from_exe(&resolved),
            resolved.parent().map(Path::to_path_buf),
            None,
        );

        assert_eq!(
            candidates[0],
            fs::canonicalize(&repo)
                .unwrap()
                .join("hooks")
                .join("claude-code"),
            "the checkout must be the first candidate, not the symlink's ancestor"
        );
    }

    #[test]
    fn resolve_exe_path_keeps_an_unresolvable_path() {
        let missing = PathBuf::from("/definitely/not/here/ai-memory");
        assert_eq!(resolve_exe_path(missing.clone()), missing);
    }

    #[test]
    fn hook_source_candidates_include_binary_sibling_for_flat_tarball() {
        // Extracted release tarball: no repo root, `hooks/` beside the binary
        // (issue #107). The sibling dir must be probed or discovery fails with
        // a bogus `/private/hooks/...` on macOS.
        let candidates = hook_source_candidates(
            "claude-code",
            None,
            Some(PathBuf::from("/private/tmp/ai-memory-macos-aarch64")),
            None,
        );
        assert!(
            candidates.contains(&PathBuf::from(
                "/private/tmp/ai-memory-macos-aarch64/hooks/claude-code"
            )),
            "binary-sibling hooks/ dir must be probed; got {candidates:?}"
        );
    }

    // ----------------------------------------------------------------
    // OpenCode tests
    // ----------------------------------------------------------------

    fn assert_generated_ts_uses_bounded_hook_queue(generated: &str) {
        assert!(generated.contains("const HOOK_QUEUE_MAX = 100;"));
        assert!(generated.contains("const HOOK_FLUSH_INTERVAL_MS = 2000;"));
        assert!(generated.contains("const HOOK_FLUSH_THRESHOLD = 20;"));
        assert!(generated.contains("const HOOK_INTER_REQUEST_DELAY_MS = 50;"));
        assert!(generated.contains("const HOOK_REQUEST_TIMEOUT_MS = 2000;"));
        assert!(generated.contains("const HOOK_IMMEDIATE_EVENTS = new Set([\"session-start\", \"stop\", \"session-end\", \"pre-compact\"]);"));
        assert!(generated.contains("const hookQueue: HookQueueItem[] = [];"));
        assert!(generated.contains(
            "function enqueueHook(event: string, url: URL, payload: Record<string, unknown>): void"
        ));
        assert!(generated.contains("if (hookQueue.length >= HOOK_QUEUE_MAX) hookQueue.shift();"));
        assert!(generated.contains(
            "HOOK_IMMEDIATE_EVENTS.has(event) || hookQueue.length >= HOOK_FLUSH_THRESHOLD"
        ));
        assert!(generated.contains("function scheduleHookFlush(): void"));
        assert!(generated.contains("hookFlushTimer.unref?.();"));
        assert!(generated.contains("async function drainHookQueue(): Promise<void>"));
        assert!(generated.contains("signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS)"));
        assert!(generated.contains("await sleep(HOOK_INTER_REQUEST_DELAY_MS)"));
        assert!(generated.contains("const policy = capturePolicy(payload"));
        assert!(generated.contains("if (policy.disposition === \"drop\") return;"));
        assert!(generated.contains("enqueueHook(event, url, policy.payload);"));
        assert!(generated.contains("const CAPTURE_POLICY_V1 = 1;"));
        assert!(generated.contains("const CAPTURE_MARKER_MAX_BYTES = 64 * 1024;"));
        assert!(generated.contains("async function fetchHandoff"));
        assert!(generated.contains("if (!process.env.AI_MEMORY_RUN_ID) {"));
        assert!(generated.contains("const response = await fetch(url, {"));
        assert!(generated.contains("signal: timeoutSignal(1000)"));
        assert!(!generated.contains("signal: timeoutSignal(500)"));
        assert!(!generated.contains("void fetch(url, {"));
    }

    #[test]
    fn generated_ts_integrations_spool_failed_deliveries() {
        // #580: every queue-based TS integration must persist a failed
        // delivery instead of dropping it, and must self-drain the spool.
        for (name, source) in [
            (
                "opencode",
                build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist"),
            ),
            (
                "omp",
                build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist"),
            ),
            (
                "pi",
                build_pi_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist"),
            ),
            (
                "opencode2",
                build_opencode2_plugin(
                    "http://127.0.0.1:49374",
                    Some("tok"),
                    None,
                    "denylist",
                    false,
                )
                .unwrap(),
            ),
        ] {
            // The fire-and-forget delivery must be gone...
            assert!(
                !source.contains("}).catch(() => undefined);\n      } catch (_e) {"),
                "{name}: still fire-and-forgets failed deliveries"
            );
            // ...replaced by capture + spool of network failures, 5xx and transient 4xx.
            assert!(
                source.contains(
                    "if (!resp || hookStatusRetryable(resp.status)) spoolFailedHook(item.url, item.payload);"
                ),
                "{name}: missing spool-on-failure"
            );
            // The spool runtime is present and CLI-compatible.
            assert!(source.contains("function spoolFailedHook("), "{name}");
            assert!(source.contains("async function drainHookSpool()"), "{name}");
            assert!(
                source.contains(r#"return join(env, "hook-spool");"#),
                "{name}: spool dir must honour AI_MEMORY_DATA_DIR"
            );
            // Every queue flush also kicks a spool drain.
            assert!(
                source.contains("if (hookDraining) return;\n  requestSpoolDrain();"),
                "{name}: drainHookQueue must trigger the spool drain"
            );
            crate::commands::render_shared::assert_shared_ts_delivery_runtime(name, &source);
            // Deliveries share one abort: a torn-down state spools the rest
            // of its queue at once instead of pacing it out.
            assert!(
                source.contains(
                    "if (hookQueue.length > 0 && !hookAbort.signal.aborted) await sleep(HOOK_INTER_REQUEST_DELAY_MS);"
                ),
                "{name}: an aborted drain must not keep pacing"
            );
            // The runtime's fs needs made it into the import line.
            for f in [
                "mkdirSync",
                "writeFileSync",
                "renameSync",
                "readdirSync",
                "unlinkSync",
            ] {
                assert!(
                    source.contains(&format!("{f},")) || source.contains(&format!("{f} }}")),
                    "{name}: node:fs import missing {f}"
                );
            }
        }
    }

    #[test]
    fn ts_spool_entries_are_readable_by_the_cli_drain() {
        // The TS runtime writes the CLI hook-spool's exact on-disk contract.
        // Mirror the bytes the generated code produces and prove the CLI
        // side parses them: entry JSON deserializes, the filename's
        // timestamp is honoured, and the body survives round-tripping.
        let created_ms: u64 = 1_756_800_000_000;
        // Filename exactly as the TS builds it:
        // `${String(createdMs).padStart(13, "0")}-${process.pid}-${spoolSeqPrefix}${seq}.json`
        let name = format!(
            "{created_ms:013}-4242-{:08x}{:08x}.json",
            0x9e37_79b9u32, 7u32
        );
        // Entry JSON exactly as the TS `JSON.stringify` emits it (key order
        // irrelevant to serde, but the shapes and enum strings are load-bearing).
        let json = format!(
            r#"{{"url":"http://127.0.0.1:49374/hook?event=stop&agent=open-code&ingest_key=ts18f3","body":"{{\"session_id\":\"s1\"}}","created_ms":{created_ms},"auth_mode":"static","token":"tok","attempts":0}}"#
        );
        let entry: crate::commands::hook_spool::SpoolEntry =
            serde_json::from_str(&json).expect("CLI drain must parse a TS-written entry");
        assert_eq!(entry.created_ms, created_ms);
        assert_eq!(entry.token.as_deref(), Some("tok"));
        assert_eq!(entry.attempts, 0);
        assert!(entry.url.contains("ingest_key=ts18f3"));
        serde_json::from_str::<serde_json::Value>(&entry.body)
            .expect("TS body must be raw JSON, not double-encoded");

        // And the anonymous variant (no token installed).
        let anon = r#"{"url":"http://h/hook?event=stop&agent=omp","body":"{}","created_ms":1,"auth_mode":"none","attempts":0}"#;
        serde_json::from_str::<crate::commands::hook_spool::SpoolEntry>(anon)
            .expect("auth_mode none must parse");

        // The timestamp-bearing filename is one the spool reader accepts:
        // spool_health derives oldest-age from names without reading files.
        let dir = tempfile::tempdir().expect("tempdir");
        let spool = dir.path().join("hook-spool");
        std::fs::create_dir_all(&spool).expect("mkdir");
        std::fs::write(spool.join(&name), json.as_bytes()).expect("write");
        assert_eq!(crate::commands::hook_spool::spool_len(&spool), 1);
        let health = crate::commands::hook_spool::spool_health(&spool);
        assert_eq!(health.pending, 1);
        assert!(
            health.oldest_age_ms.is_some(),
            "TS filename's 13-digit timestamp must be readable: {name}"
        );
    }

    #[test]
    fn opencode_plugin_cleanup_removes_only_exact_owned_incompatible_sibling() {
        let temp = tempfile::tempdir().unwrap();
        let v1 = temp.path().join("ai-memory.ts");
        let v2 = temp.path().join("ai-memory-opencode2.ts");
        fs::write(
            &v1,
            "// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.\nconst AGENT = \"open-code\";\n",
        )
        .unwrap();
        fs::write(
            &v2,
            "// Auto-generated by `ai-memory install-hooks --agent opencode2 --apply`.\nconst AGENT = \"opencode2\";\n",
        )
        .unwrap();

        remove_incompatible_opencode_plugin(&v2, AgentChoice::OpenCode2).unwrap();
        assert!(!v1.exists());
        assert!(v2.exists());

        fs::write(&v1, "export default function userPlugin() {}\n").unwrap();
        remove_incompatible_opencode_plugin(&v2, AgentChoice::OpenCode2).unwrap();
        assert_eq!(
            fs::read_to_string(&v1).unwrap(),
            "export default function userPlugin() {}\n"
        );

        fs::write(
            &v2,
            "// Auto-generated by `ai-memory install-hooks --agent opencode2 --apply`.\nconst AGENT = \"opencode2\";\n",
        )
        .unwrap();
        remove_incompatible_opencode_plugin(&v1, AgentChoice::OpenCode).unwrap();
        assert!(!v2.exists());
    }

    #[test]
    fn opencode_plugin_cleanup_preserves_a_concurrent_user_replacement() {
        let temp = tempfile::tempdir().unwrap();
        let v1 = temp.path().join("ai-memory.ts");
        let v2 = temp.path().join("ai-memory-opencode2.ts");
        fs::write(
            &v1,
            "// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.\nconst AGENT = \"open-code\";\n",
        )
        .unwrap();

        remove_incompatible_opencode_plugin_with(&v2, AgentChoice::OpenCode2, |sibling| {
            fs::write(sibling, "export default function userReplacement() {}\n")?;
            Ok(())
        })
        .unwrap();

        assert_eq!(
            fs::read_to_string(&v1).unwrap(),
            "export default function userReplacement() {}\n"
        );
        assert_eq!(
            fs::read_dir(temp.path())
                .unwrap()
                .filter_map(Result::ok)
                .filter(|entry| entry.file_name().to_string_lossy().contains("quarantine"))
                .count(),
            0,
            "the quarantined generated file is deleted, never the replacement"
        );
    }

    #[test]
    fn opencode_plugin_restore_moves_quarantine_when_destination_is_free() {
        let temp = tempfile::tempdir().unwrap();
        let sibling = temp.path().join("ai-memory.ts");
        let quarantine = temp.path().join(".ai-memory-opencode-quarantine-test");
        fs::write(&quarantine, "export default function original() {}\n").unwrap();

        restore_quarantined_opencode_plugin_with(&quarantine, &sibling, || Ok(())).unwrap();

        assert_eq!(
            fs::read_to_string(&sibling).unwrap(),
            "export default function original() {}\n"
        );
        assert!(!quarantine.exists());
    }

    #[test]
    fn opencode_plugin_restore_preserves_an_existing_replacement() {
        let temp = tempfile::tempdir().unwrap();
        let sibling = temp.path().join("ai-memory.ts");
        let quarantine = temp.path().join(".ai-memory-opencode-quarantine-test");
        fs::write(&quarantine, "export default function original() {}\n").unwrap();
        fs::write(&sibling, "export default function replacement() {}\n").unwrap();

        restore_quarantined_opencode_plugin_with(&quarantine, &sibling, || Ok(())).unwrap();

        assert_eq!(
            fs::read_to_string(&sibling).unwrap(),
            "export default function replacement() {}\n"
        );
        assert_eq!(
            fs::read_to_string(&quarantine).unwrap(),
            "export default function original() {}\n"
        );
    }

    #[test]
    fn opencode_plugin_restore_does_not_replace_a_file_created_at_restore_window() {
        let temp = tempfile::tempdir().unwrap();
        let sibling = temp.path().join("ai-memory.ts");
        let quarantine = temp.path().join(".ai-memory-opencode-quarantine-test");
        fs::write(&quarantine, "export default function original() {}\n").unwrap();

        restore_quarantined_opencode_plugin_with(&quarantine, &sibling, || {
            fs::write(&sibling, "export default function concurrent() {}\n")?;
            Ok(())
        })
        .unwrap();

        assert_eq!(
            fs::read_to_string(&sibling).unwrap(),
            "export default function concurrent() {}\n"
        );
        assert_eq!(
            fs::read_to_string(&quarantine).unwrap(),
            "export default function original() {}\n"
        );
    }

    #[test]
    fn opencode_plugin_apply_is_byte_idempotent_after_cleanup() {
        let temp = tempfile::tempdir().unwrap();
        let plugin = temp.path().join("ai-memory-opencode2.ts");
        let sibling = temp.path().join("ai-memory.ts");
        fs::write(
            &sibling,
            "// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.\nconst AGENT = \"open-code\";\n",
        )
        .unwrap();
        let mut args = default_hook_args();
        args.agent = AgentChoice::OpenCode2;
        args.config_file = Some(plugin.clone());

        apply_to_opencode2_plugin("http://127.0.0.1:49374", None, &args, "denylist").unwrap();
        let first = fs::read(&plugin).unwrap();
        apply_to_opencode2_plugin("http://127.0.0.1:49374", None, &args, "denylist").unwrap();
        assert_eq!(fs::read(&plugin).unwrap(), first);
        assert!(!sibling.exists());
    }

    #[test]
    fn opencode_plugin_cleanup_does_not_escape_custom_target_directory() {
        let temp = tempfile::tempdir().unwrap();
        let custom = temp.path().join("custom.ts");
        let sibling = temp.path().join("ai-memory.ts");
        fs::write(
            &sibling,
            "// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.\nconst AGENT = \"open-code\";\n",
        )
        .unwrap();

        remove_incompatible_opencode_plugin(&custom, AgentChoice::OpenCode2).unwrap();
        assert!(sibling.exists());
    }

    const RELOAD_TRIGGER_LINE: &str =
        r"const RELOAD_TRIGGER = /^\s*reload context(?![\p{L}\p{N}_])/iu;";

    #[test]
    fn opencode_plugin_fetches_a_recap_for_a_reload_prompt() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", None, None, "denylist");
        assert!(
            plugin.contains(RELOAD_TRIGGER_LINE),
            "trigger regex missing"
        );
        assert!(
            plugin.contains("const recapFetches = new Map<string, Promise<string | undefined>>();")
        );
        assert!(plugin.contains("async function fetchRecap(cwd: string, id: string)"));
        assert!(plugin.contains("`${SERVER}/recap`"));
        assert!(plugin.contains(
            "if (id && RELOAD_TRIGGER.test(prompt)) recapFetches.set(id, fetchRecap(cwd, id));"
        ));
        assert!(plugin.contains("if (recap) (output as any).system.push(recap);"));
        // A new compaction starts a new window: both compaction paths and the
        // session end forget the delivered recap.
        assert_eq!(plugin.matches("recapFetches.delete(id);").count(), 3);
    }

    #[test]
    fn opencode2_plugin_fetches_a_recap_for_a_reload_prompt() {
        let plugin =
            build_opencode2_plugin("http://127.0.0.1:49374", None, None, "denylist", false)
                .unwrap();
        assert!(
            plugin.contains(RELOAD_TRIGGER_LINE),
            "trigger regex missing"
        );
        assert!(plugin.contains("async function fetchRecap(cwd: string, id: string)"));
        assert!(plugin.contains("RELOAD_TRIGGER.test(event.prompt.text)"));
        assert!(plugin.contains("event.system.push({ type: \"text\", text: recap });"));
        assert!(plugin.contains("recapFetches.delete(event.data.sessionID);"));
    }

    #[test]
    fn omp_and_pi_extensions_do_not_fetch_a_recap() {
        for extension in [
            build_omp_extension("http://127.0.0.1:49374", None, None, "denylist"),
            build_pi_extension("http://127.0.0.1:49374", None, None, "denylist"),
        ] {
            assert!(!extension.contains("/recap"));
            assert!(!extension.contains("RELOAD_TRIGGER"));
        }
    }

    #[test]
    fn opencode_plugin_uses_real_plugin_hooks() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");

        assert!(plugin.contains("event: async (input)"));
        assert!(plugin.contains(r#""chat.message": async"#));
        assert!(plugin.contains(r#""tool.execute.before": async"#));
        assert!(plugin.contains(r#""tool.execute.after": async"#));
        assert!(plugin.contains(r#""experimental.chat.system.transform": async"#));
        assert!(plugin.contains("export default AiMemoryHooks"));
        assert!(plugin.contains("const startedSessions = new Set<string>();"));
        assert!(
            plugin
                .contains("const handoffFetches = new Map<string, Promise<string | undefined>>();")
        );
        assert!(!plugin.contains("handoffChecked"));
        assert!(plugin.contains("function startSession"));
        assert!(plugin.contains("function endSession"));
        // #755: a subagent session must forward its parentID as the `agent_id`
        // marker (so drop_subagent_captures recognizes it), and only when the
        // parentID is a real string (a root session stays unmarked).
        assert!(plugin.contains("agent_id: info.parentID"));
        assert!(plugin.contains("typeof info.parentID === \"string\""));
        assert!(plugin.contains("fetchHandoff"));
        assert!(plugin.contains("function applyMarkerParams"));
        assert!(plugin.contains("readFileSync(marker, \"utf8\")"));
        assert!(plugin.contains("text.split(/\\r?\\n/)"));
        assert!(plugin.contains("tomlKey(body, \"project_strategy\")"));
        assert!(plugin.contains("tomlKey(body, \"drop_subagent_captures\")"));
        assert!(plugin.contains("url.searchParams.set(\"project_strategy\", projectStrategy)"));
        assert!(plugin.contains("url.searchParams.set(\"drop_subagent\", dropSubagent)"));
        assert!(plugin.contains("function tomlFlag"));
        assert!(plugin.contains("tomlFlag(body, \"default_global\")"));
        assert!(plugin.contains("tomlFlag(body, \"inject_on_session_start\")"));
        assert!(plugin.contains("url.searchParams.set(\"briefing_budget\", briefingBudget)"));
        assert!(plugin.contains("tomlFlag(body, \"contribute\")"));
        assert!(plugin.contains("url.searchParams.set(\"profile_contribute\", profileContribute)"));
        assert!(plugin.contains("url.searchParams.set(\"profile_consume\", profileConsume)"));
        assert!(plugin.contains("tomlFlag(body, \"deliver_on_session_start\")"));
        assert!(plugin.contains("url.searchParams.set(\"handoff\", \"0\")"));
        // #668: applyMarkerParams resolves scope/settings via the
        // settings-walk, not the nearest-marker findMarker, so a nested
        // capture-only marker does not shadow an outer marker's scope.
        assert!(plugin.contains("function findSettingsMarker"));
        assert!(plugin.contains("function declaresSettings"));
        assert!(plugin.contains("let marker = findSettingsMarker(cwd);"));
        assert!(plugin.contains(
            "for (const key of [\"workspace\", \"project\", \"project_strategy\", \"drop_subagent_captures\", \"identity\", \"identity_style\"])"
        ));
        assert!(plugin.contains("if (/^\\s*aliases\\s*=/m.test(text)) return true;"));
        assert!(plugin.contains(
            "for (const key of [\"default_global\", \"inject_on_session_start\", \"inject_on_subagent_start\", \"max_chars\", \"contribute\", \"consume\", \"deliver_on_session_start\"])"
        ));
        assert!(plugin.contains("if (declaresSettings(text)) return marker;"));
        assert!(plugin.contains(
            "if (!applyMarkerParams(url, typeof payload.cwd === \"string\" ? payload.cwd : undefined)) return;"
        ));
        assert!(plugin.contains("if (!applyMarkerParams(url, cwd)) return undefined;"));
        assert!(plugin.contains("postPreCompact"));
        assert!(plugin.contains("dispose: async () =>"));
        assert!(plugin.contains("const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;"));
        assert!(plugin.contains("let hookDrainPromise: Promise<void> | undefined;"));
        assert!(plugin.contains("function requestHookDrain(): Promise<void>"));
        assert!(plugin.contains("function disposeDrainTimeout(): Promise<void>"));
        assert!(plugin.contains("timer.unref?.();"));
        assert!(plugin.contains("async function drainHookQueueForDispose(): Promise<void>"));
        assert!(plugin.contains("for (const id of Array.from(startedSessions))"));
        assert!(plugin.contains("await drainHookQueueForDispose();"));
        assert!(plugin.contains("postHook(\"session-start\""));
        assert!(plugin.contains(r#""session.deleted")"#));
        assert_eq!(
            plugin.matches("postHook(\"session-end\"").count(),
            1,
            "OpenCode generated plugin must route session closes through one idempotent helper"
        );
        assert!(plugin.contains("!startedSessions.delete(id)"));
        assert!(plugin.contains("sessionCwds.delete(id);"));
        assert!(plugin.contains("handoffFetches.delete(id);"));
        assert!(plugin.contains("preCompactLast.delete(id);"));
        assert!(plugin.contains("postHook(\"user-prompt\""));
        assert!(plugin.contains("Bearer ${token}"));
        assert!(plugin.contains("tok"));
        assert!(
            !plugin.contains(r#""session.created": async"#),
            "OpenCode bus events must be handled through the `event` hook"
        );
        assert!(plugin.contains("import { execFileSync } from \"node:child_process\";"));
        assert!(
            plugin.contains("import { basename, dirname, join, resolve, sep } from \"node:path\";")
        );
        assert!(plugin.contains("if (existsSync(join(probe, \".git\")))"));
        assert!(plugin.contains("boundary ??= dir;"));
        assert!(plugin.contains("function repoRootProject"));
        assert!(plugin.contains("repoProjectCache.set(cwd, project);"));
        assert_eq!(plugin.matches("windowsHide: true").count(), 3);
        assert!(plugin.contains("--git-common-dir"));
        assert!(
            plugin
                .contains("projectStrategy === \"repo-root\" || projectStrategy === \"repo_root\"")
        );
        assert!(plugin.contains("project = repoProject;"));
        assert!(plugin.contains("projectSource = \"repo-root\";"));
    }

    /// A single `event?.type === "..."` branch of the generated OpenCode
    /// plugin, so an assertion cannot be satisfied by a marker that lives in a
    /// neighbouring branch.
    fn opencode_event_branch<'a>(plugin: &'a str, event: &str) -> &'a str {
        let needle = format!("event?.type === \"{event}\"");
        let start = plugin
            .find(&needle)
            .unwrap_or_else(|| panic!("{event} branch missing"));
        let rest = &plugin[start..];
        let end = rest[needle.len()..]
            .find("event?.type ===")
            .map(|offset| offset + needle.len())
            .unwrap_or(rest.len());
        &rest[..end]
    }

    #[test]
    fn opencode_plugin_marks_a_subagent_session_end() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", None, None, "denylist");
        let branch = |event: &str| opencode_event_branch(&plugin, event);
        // #755: the router refuses to hand the next session a sub-task baton
        // only when a child session's `session-end` carries the marker, so the
        // end event must forward parentID just like `session.created` does.
        assert!(
            branch("session.deleted").contains("agent_id: info.parentID"),
            "session.deleted must forward the subagent marker"
        );
        assert!(
            branch("session.deleted").contains("typeof info.parentID === \"string\""),
            "a root session has no parentID and must stay unmarked"
        );
        // When OpenCode exits, `dispose` ends every started session, children
        // included, through `endSession` alone. Their marker comes from the
        // parent the plugin recorded, so it reaches every close path.
        let dispose = &plugin[plugin.find("dispose: async () =>").expect("dispose hook")..];
        let dispose = &dispose[..dispose.find("event: async (input)").expect("event hook")];
        assert!(dispose.contains("endSession(id, directory);"), "{dispose}");
        let end_session = &plugin[plugin.find("function endSession(").expect("endSession")..];
        let end_session = &end_session[..end_session.find("\n}\n").expect("endSession body")];
        assert!(
            end_session.contains("const parent = sessionParents.get(id);"),
            "{end_session}"
        );
        assert!(
            end_session.contains("...(parent ? { agent_id: parent } : {}), ...extra"),
            "endSession must mark a recorded subagent's end: {end_session}"
        );
        // Controls: `session.created` already forwards the marker (so the
        // branch slicer resolves real branches) and `session.idle` carries no
        // marker (so the slicer is not silently returning the whole plugin).
        assert!(branch("session.created").contains("agent_id: info.parentID"));
        assert!(!branch("session.idle").contains("agent_id"));
    }

    #[test]
    fn opencode_plugin_skips_the_handoff_for_a_subagent_session() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", None, None, "denylist");
        // OpenCode runs a `task` subagent in a child session and calls the
        // system transform for it like for any other session. The plugin
        // records the child from its `session.created`, and only from a real
        // string parentID.
        assert!(
            opencode_event_branch(&plugin, "session.created")
                .contains("rememberParent(id, info.parentID);")
        );
        assert!(plugin.contains(
            r#"if (id && typeof parentID === "string" && parentID) sessionParents.set(id, parentID);"#
        ));
        // A child the task tool resumes by `task_id` in a later process is
        // recognized from the `session.updated` its prompt publishes. An
        // update never starts a session of its own.
        let updated = opencode_event_branch(&plugin, "session.updated");
        assert!(
            updated.contains("rememberParent(properties.sessionID ?? info.id, info.parentID);"),
            "{updated}"
        );
        assert!(!updated.contains("startSession("), "{updated}");
        let transform = &plugin[plugin
            .find(r#""experimental.chat.system.transform": async"#)
            .expect("system transform hook")..];
        let guard = transform
            .find("if (sessionParents.has(id)) return;")
            .expect("the transform must skip a subagent session");
        let claim = transform
            .find("fetchHandoff(")
            .expect("the transform still claims for a top-level session");
        assert!(guard < claim, "a subagent must return before the claim");
        // Capture is untouched: no other hook consults the parent map.
        assert_eq!(plugin.matches("sessionParents.has(").count(), 1);
    }

    #[test]
    fn opencode2_plugin_binds_the_v2_api() {
        let plugin = build_opencode2_plugin(
            "http://127.0.0.1:49374",
            Some("tok"),
            None,
            "denylist",
            false,
        )
        .unwrap();

        // Ownership markers the uninstall gate keys on.
        assert!(plugin.contains("install-hooks --agent opencode2 --apply"));
        assert!(plugin.contains("const AGENT = \"opencode2\";"));
        // Type-only import: `Plugin.define` is identity, and a runtime
        // import does not resolve from the global plugins dir (the beta
        // refuses the load). The host only needs the `{ id, setup }` shape.
        assert!(plugin.contains("import type { Plugin } from \"@opencode/plugin\";"));
        assert!(!plugin.contains("export default Plugin.define"));
        assert!(!plugin.contains("Plugin.define({"));
        assert!(plugin.contains("const AiMemoryOpencode2: Plugin.Plugin = {"));
        assert!(plugin.contains("export default AiMemoryOpencode2;"));
        // #755: subagent sessions forward parentID as the `agent_id` marker,
        // only when it is a real string (root sessions stay unmarked).
        assert!(plugin.contains("agent_id: session.parentID"));
        assert!(plugin.contains("if (!session || session.parentID) return"));
        // V2 hooks, from `@opencode/[email protected]`.
        assert!(plugin.contains("ctx.event.subscribe"));
        assert!(plugin.contains("ctx.session.hook(\"prompt\""));
        assert!(plugin.contains("ctx.session.hook(\"context\""));
        assert!(plugin.contains("ctx.tool.hook(\"execute.before\""));
        assert!(plugin.contains("ctx.tool.hook(\"execute.after\""));
        // V2 lifecycle envelopes carry `{ type, data, location }`; each of
        // these event names is present in the OpenCode 2.0.14 binary.
        for event in [
            "session.created",
            "session.execution.succeeded",
            "session.execution.failed",
            "session.execution.interrupted",
            "session.text.ended",
            "session.moved",
            "session.deleted",
            "session.compaction.started",
        ] {
            assert!(plugin.contains(event), "missing {event}");
        }
        // Handoff injection moved off v1's removed experimental hook and
        // fires once per session (the context hook runs per model call).
        // System items are `{ type: "text", text }` objects on the V2 API, not strings.
        assert!(!plugin.contains("handoffInjected"));
        assert!(plugin.contains("system.push({ type: \"text\", text: handoff })"));
        assert!(!plugin.contains("experimental."));
        // Hook registrations are disposed on unload so a reload cannot
        // leave stale callbacks capturing twice.
        assert!(plugin.contains("registration.dispose()"));
        // #1074: OpenCode unloads the plugin on idle-location eviction while
        // the host and its sessions stay alive, so dispose must not end
        // tracked sessions. `session.deleted` (asserted above) stays the only
        // end: the definition plus that one call are the whole `endSession`
        // surface of the generated plugin.
        assert_eq!(
            plugin.matches("endSession(").count(),
            2,
            "endSession must appear only as the definition and the session.deleted call"
        );
        // Pre-compaction arrives on its own start event; the completion
        // event stays as the consolidation trigger, like v1.
        assert!(plugin.contains("session.compaction.started"));
        // Tool failures share the channel with the reason preserved.
        assert!(plugin.contains("status === \"error\""));
        assert!(plugin.contains("event.result.content ?? event.result.output"));
        // No v1 remnants.
        assert!(!plugin.contains("export default AiMemoryHooks"));
        assert!(!plugin.contains("chat.message"));
        // Shared capture prelude survived the rewrite byte-identical.
        for shared in [
            "function startSession",
            "function endSession",
            "postHook(\"session-start\"",
            "postHook(\"user-prompt\"",
            "function applyMarkerParams",
            "requestSpoolDrain();",
        ] {
            assert!(plugin.contains(shared), "missing {shared}");
        }
        // #625 made the generated adapters resolve the bearer at runtime
        // (resolveToken() -> `${token}`) instead of the static `${TOKEN}`;
        // the opencode2 plugin derives from v1 so it inherits that.
        assert!(plugin.contains("Bearer ${token}"));
        assert!(plugin.contains("tok"));
        // The shared repo-root lookup (memoized, console-less) survives too.
        assert!(plugin.contains(TS_REPO_ROOT_PROJECT));
    }

    #[test]
    fn opencode2_assistant_capture_is_explicit_and_preserved() {
        let off = build_opencode2_plugin("http://localhost:49374", None, None, "denylist", false)
            .unwrap();
        let on =
            build_opencode2_plugin("http://localhost:49374", None, None, "denylist", true).unwrap();
        assert_eq!(baked_capture_assistant(&off), Some(false));
        assert_eq!(baked_capture_assistant(&on), Some(true));
        // The executable path is baked only with the opt-in, so a plugin
        // generated without it is portable between machines.
        let exe = std::env::current_exe().unwrap();
        let exe = ts_string_literal(&strip_windows_verbatim_prefix(&exe.to_string_lossy()));
        assert!(off.contains("const NATIVE_HOOK: string | undefined = undefined;"));
        assert!(!off.contains(&exe));
        assert!(on.contains(&format!("const NATIVE_HOOK: string | undefined = {exe};")));
        assert!(!on.contains(r"\\\\?\\"), "no verbatim path is baked");
        // The spawn inherits no console from OpenCode 2's background service.
        let spawn = &on[on.find("spawn(NATIVE_HOOK, args, {").unwrap()..];
        assert!(spawn[..spawn.find("});").unwrap()].contains("windowsHide: true,"));
        // A hook that cannot run still records the turn, without its text.
        let failed = &spawn[spawn.find("child.on(\"error\"").unwrap()..];
        assert!(failed[..failed.find("});").unwrap()].contains("postHook(\"stop\", payload);"));
        assert!(on.contains("last_assistant_message: text"));
        assert!(on.contains("child.stdin.end(JSON.stringify"));
        assert!(!on.contains("postHook(\"stop\", { ...payload, last_assistant_message"));
        assert!(
            on.find("setup: async (ctx)").unwrap() < on.find("const hookQueue:").unwrap(),
            "capture state belongs to each location instance"
        );
    }

    /// Executes the generated plugin against a fake OpenCode 2 host
    /// (`tests/fixtures/opencode2-plugin.mjs`) instead of only matching
    /// template text: completion events, handoff claims, per-location
    /// cleanup, same-millisecond spooling and bounded unload.
    #[test]
    fn opencode2_plugin_passes_the_node_host_fixture() {
        let Some(()) = crate::commands::render_shared::node_strip_types_available() else {
            return;
        };
        let temp = tempfile::tempdir().unwrap();
        let plugin = temp.path().join("ai-memory-opencode2.ts");
        fs::write(
            &plugin,
            build_opencode2_plugin("http://127.0.0.1:49600", None, None, "denylist", false)
                .unwrap(),
        )
        .unwrap();
        // The fixture's sessions live in its cwd. Pin cwd, home and data dir
        // inside the tempdir so no operator marker or spool is reachable.
        let cwd = temp.path().join("location");
        fs::create_dir(&cwd).unwrap();
        let fixture = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tests")
            .join("fixtures")
            .join("opencode2-plugin.mjs");
        let output = std::process::Command::new("node")
            .arg("--experimental-strip-types")
            .arg(&fixture)
            .arg(&plugin)
            .current_dir(&cwd)
            .env("HOME", temp.path())
            .env("USERPROFILE", temp.path())
            .env("AI_MEMORY_DATA_DIR", temp.path().join("data"))
            .env_remove("AI_MEMORY_AUTH_TOKEN")
            .env_remove("AI_MEMORY_RUN_ID")
            .output()
            .unwrap();
        let stdout = String::from_utf8_lossy(&output.stdout);
        assert!(
            output.status.success() && stdout.matches("PASS:").count() == 3,
            "opencode2 host fixture failed ({})\nstdout:\n{stdout}\nstderr:\n{}",
            output.status,
            String::from_utf8_lossy(&output.stderr),
        );
    }

    #[test]
    fn opencode2_plugin_rejects_v1_template_drift() {
        // The builder rewrites the v1 template, so a v1 edit that moves the
        // binding anchor must fail loudly instead of shipping a hybrid.
        let plugin = build_opencode2_plugin(
            "http://127.0.0.1:49374/",
            None,
            Some("repo-root"),
            "denylist",
            false,
        )
        .unwrap();
        assert!(plugin.contains("const TOKEN: string | null = null;"));
        assert!(
            plugin.contains("const DEFAULT_PROJECT_STRATEGY = \"repo-root\";"),
            "strategy bake-through must survive the v2 rewrite"
        );
    }

    #[test]
    fn opencode2_anchor_rewrite_fails_loudly_on_drift() {
        let err =
            replace_opencode_anchor("no v1 anchors here", "missing", "x", "banner").unwrap_err();
        assert!(
            err.to_string().contains("banner"),
            "drift must name the moved anchor: {err:#}"
        );
        // A duplicated anchor is drift too: rewriting only the first copy
        // would silently leave the other one on v1 behavior.
        assert!(replace_opencode_anchor("a a", "a", "b", "banner").is_err());
    }

    #[test]
    fn opencode2_plugin_bakes_allowlist_admit_gate() {
        // opencode2 reuses v1's capture prelude verbatim (see
        // `build_opencode2_plugin`'s doc comment), so the gate must survive
        // the anchor rewrite into the beta's `{ id, setup }` host binding.
        let plugin = build_opencode2_plugin(
            "http://127.0.0.1:49374",
            Some("tok"),
            None,
            "allowlist",
            false,
        )
        .unwrap();
        assert!(
            plugin.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"allowlist\";"),
            "{plugin}"
        );
        assert!(plugin.contains(CAPTURE_ADMIT_GATE_TS), "{plugin}");
    }

    #[test]
    fn opencode2_plugin_denylist_bakes_inert_gate() {
        let plugin = build_opencode2_plugin(
            "http://127.0.0.1:49374",
            Some("tok"),
            None,
            "denylist",
            false,
        )
        .unwrap();
        assert!(
            plugin.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"denylist\";"),
            "{plugin}"
        );
        assert!(plugin.contains(CAPTURE_ADMIT_GATE_TS), "{plugin}");
    }

    #[test]
    fn opencode_plugin_normalizes_payloads_without_legacy_wrapper() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374/", None, None, "denylist");

        assert!(plugin.contains("const SERVER = \"http://127.0.0.1:49374/\".replace"));
        assert!(plugin.contains("const TOKEN: string | null = null;"));
        assert!(plugin.contains("sessionID: id,"));
        assert!(plugin.contains("cwd,"));
        assert!(plugin.contains("prompt: textFromParts"));
        assert!(plugin.contains("output: (output as any).output"));
        assert!(plugin.contains("if (typeof AbortSignal === \"undefined\")"));
        assert!(
            !plugin.contains("hook_event_name"),
            "new plugin should send normalized top-level fields, not legacy wrappers"
        );
    }

    #[test]
    fn opencode_plugin_bakes_repo_root_default() {
        let plugin = build_opencode_plugin(
            "http://127.0.0.1:49374",
            Some("tok"),
            Some("repo-root"),
            "denylist",
        );
        assert!(
            plugin.contains("const DEFAULT_PROJECT_STRATEGY = \"repo-root\";"),
            "repo-root install default must bake the const: {plugin}"
        );
        assert!(
            plugin.contains("if (!projectStrategy) projectStrategy = DEFAULT_PROJECT_STRATEGY;"),
            "must apply the default when a marker pins no strategy: {plugin}"
        );
        assert!(
            plugin.contains("project = repoProject;")
                && plugin.contains("projectSource = \"repo-root\";"),
            "{plugin}"
        );
        assert!(
            plugin.contains("let marker = findSettingsMarker(cwd);"),
            "the default-strategy variant must also walk past a capture-only marker (#668): {plugin}"
        );
    }

    #[test]
    fn opencode_plugin_default_omits_baked_strategy() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        assert!(
            !plugin.contains("DEFAULT_PROJECT_STRATEGY"),
            "basename default must bake no strategy: {plugin}"
        );
    }

    #[test]
    fn opencode_plugin_bakes_allowlist_admit_gate() {
        let plugin =
            build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None, "allowlist");
        assert!(
            plugin.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"allowlist\";"),
            "{plugin}"
        );
        assert!(plugin.contains(CAPTURE_ADMIT_GATE_TS), "{plugin}");
    }

    #[test]
    fn opencode_plugin_denylist_bakes_inert_gate() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        assert!(
            plugin.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"denylist\";"),
            "{plugin}"
        );
        assert!(plugin.contains(CAPTURE_ADMIT_GATE_TS), "{plugin}");
    }

    #[test]
    fn opencode_plugin_uses_bounded_hook_queue() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");

        assert_generated_ts_uses_bounded_hook_queue(&plugin);
    }

    #[test]
    fn opencode_plugin_resolves_token_at_runtime_when_not_embedded() {
        let plugin = build_opencode_plugin("http://127.0.0.1:49374", None, None, "denylist");
        assert!(plugin.contains("function resolveToken("));
        assert!(plugin.contains("const token = resolveToken();"));
        assert!(plugin.contains("if (!response.ok) return undefined;"));
    }

    #[test]
    fn omp_extension_resolves_token_at_runtime_when_not_embedded() {
        let extension = build_omp_extension("http://127.0.0.1:49374", None, None, "denylist");
        assert!(extension.contains("function resolveToken("));
        assert!(extension.contains("process.env.AI_MEMORY_AUTH_TOKEN"));
        assert!(extension.contains("auth-token"));
        assert!(extension.contains("if (!response.ok) return undefined;"));
    }

    #[test]
    fn omp_extension_prefers_statically_embedded_token() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        assert!(extension.contains("function resolveToken("));
        assert!(extension.contains("if (TOKEN) return TOKEN;"));
    }

    // ----------------------------------------------------------------
    // OMP tests
    // ----------------------------------------------------------------

    #[test]
    fn omp_extension_bakes_allowlist_admit_gate() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "allowlist");
        assert!(
            extension.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"allowlist\";"),
            "{extension}"
        );
        assert!(extension.contains(CAPTURE_ADMIT_GATE_TS), "{extension}");
    }

    #[test]
    fn omp_extension_denylist_bakes_inert_gate() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        assert!(
            extension.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"denylist\";"),
            "{extension}"
        );
        assert!(extension.contains(CAPTURE_ADMIT_GATE_TS), "{extension}");
    }

    #[test]
    fn omp_extension_uses_native_lifecycle_events() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");

        assert!(extension.contains("export default function AiMemoryExtension"));
        assert!(extension.contains("const AGENT = \"omp\";"));
        assert!(extension.contains("api.on(\"session_start\""));
        assert!(extension.contains("api.on(\"before_agent_start\""));
        assert!(extension.contains("api.on(\"tool_call\""));
        assert!(extension.contains("api.on(\"tool_result\""));
        assert!(extension.contains("api.on(\"session_shutdown\""));
        assert!(extension.contains("postHook(\"session-start\""));
        assert!(extension.contains("postHook(\"user-prompt\""));
        assert!(extension.contains("fetchHandoff"));
        assert!(extension.contains("if (!process.env.AI_MEMORY_RUN_ID) {"));
        assert!(extension.contains("function applyMarkerParams"));
        assert!(extension.contains("readFileSync(marker, \"utf8\")"));
        assert!(extension.contains("text.split(/\\r?\\n/)"));
        assert!(extension.contains("tomlKey(body, \"project_strategy\")"));
        assert!(extension.contains("tomlKey(body, \"drop_subagent_captures\")"));
        assert!(extension.contains("url.searchParams.set(\"project_strategy\", projectStrategy)"));
        assert!(extension.contains("url.searchParams.set(\"drop_subagent\", dropSubagent)"));
        assert!(extension.contains("function tomlFlag"));
        assert!(extension.contains("tomlFlag(body, \"default_global\")"));
        assert!(extension.contains("tomlFlag(body, \"inject_on_session_start\")"));
        assert!(extension.contains("url.searchParams.set(\"briefing_budget\", briefingBudget)"));
        // #668: same settings-walk as the OpenCode plugin (shared
        // `ts_apply_marker_params`), so a nested capture-only marker does
        // not shadow an outer marker's scope for the OMP/pi extensions.
        assert!(extension.contains("function findSettingsMarker"));
        assert!(extension.contains("function declaresSettings"));
        assert!(extension.contains("let marker = findSettingsMarker(cwd);"));
        assert!(extension.contains("if (declaresSettings(text)) return marker;"));
        assert!(extension.contains(
            "if (!applyMarkerParams(url, typeof payload.cwd === \"string\" ? payload.cwd : undefined)) return;"
        ));
        assert!(extension.contains("if (!applyMarkerParams(url, cwd)) return undefined;"));
        assert!(extension.contains("Bearer ${token}"));
        assert!(extension.contains("tok"));
        assert!(
            extension
                .contains("import { basename, dirname, join, resolve, sep } from \"node:path\";")
        );
        assert!(extension.contains("if (existsSync(join(probe, \".git\")))"));
        assert!(extension.contains("boundary ??= dir;"));
        assert!(extension.contains("import { execFileSync } from \"node:child_process\";"));
        assert!(extension.contains("function repoRootProject"));
        assert!(extension.contains("repoProjectCache.set(cwd, project);"));
        assert_eq!(extension.matches("windowsHide: true").count(), 3);
        assert!(extension.contains("--git-common-dir"));
        assert!(
            extension
                .contains("projectStrategy === \"repo-root\" || projectStrategy === \"repo_root\"")
        );
        assert!(extension.contains("project = repoProject;"));
        assert!(extension.contains("projectSource = \"repo-root\";"));
        // #676: pi/omp await session_shutdown's dispose flush instead of
        // returning immediately, so the runtime teardown that follows a sync
        // handler no longer kills the in-flight session-end fetch.
        assert!(extension.contains("const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;"));
        assert!(extension.contains("let hookDrainPromise: Promise<void> | undefined;"));
        assert!(extension.contains("function requestHookDrain(): Promise<void>"));
        assert!(extension.contains("function disposeDrainTimeout(): Promise<void>"));
        assert!(extension.contains("async function drainHookQueueForDispose(): Promise<void>"));
        assert!(
            extension.contains("api.on(\"session_shutdown\", async (_event: any, ctx: any) => {")
        );
        assert!(extension.contains("await drainHookQueueForDispose();"));
        assert!(
            !extension.contains("api.on(\"session_shutdown\", (_event: any, ctx: any) => {"),
            "session_shutdown must not regress to the sync fire-and-forget form: {extension}"
        );
    }

    /// OMP rebinds the extension into every subagent session and reports the
    /// session's agent as `ctx.agent` (`docs/extensions.md`, "Handler
    /// context"). A subagent session forwards `agent_id` and never claims the
    /// baton. Only the session's own lifecycle events record the kind: an
    /// advisor's tool calls reach the session they advise as `kind: "sub"`.
    #[test]
    fn omp_extension_marks_subagent_sessions_and_skips_their_handoff() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        // Slice a single `api.on("...")` handler so an assertion cannot be
        // satisfied by a call that lives in a neighbouring one.
        let handler = |event: &str| {
            let needle = format!("api.on(\"{event}\"");
            let start = extension
                .find(&needle)
                .unwrap_or_else(|| panic!("{event} handler missing"));
            let rest = &extension[start..];
            let end = rest[needle.len()..]
                .find("api.on(")
                .map(|offset| offset + needle.len())
                .unwrap_or(rest.len());
            &rest[..end]
        };
        assert!(extension.contains("if (!id || agent?.kind !== \"sub\") return;"));
        assert!(extension.contains("...(agentID ? { agent_id: agentID } : {}),"));
        assert!(
            handler("before_agent_start")
                .contains("if (!id || subagentSessions.has(id) || handoffChecked.has(id)) return;"),
            "a subagent's first prompt must not claim the baton"
        );
        for event in ["session_start", "before_agent_start", "session_shutdown"] {
            assert!(
                handler(event).contains("noteSubagent(ctx);"),
                "{event} carries the session's own agent and must record it"
            );
        }
        for event in ["tool_call", "tool_result", "agent_end"] {
            assert!(
                !handler(event).contains("noteSubagent"),
                "{event} can carry an advisor's identity and must not record it"
            );
        }
    }

    #[test]
    fn omp_extension_bakes_repo_root_default() {
        let extension = build_omp_extension(
            "http://127.0.0.1:49374",
            Some("tok"),
            Some("repo-root"),
            "denylist",
        );
        assert!(
            extension.contains("const DEFAULT_PROJECT_STRATEGY = \"repo-root\";"),
            "repo-root install default must bake the const: {extension}"
        );
        assert!(
            extension.contains("if (!projectStrategy) projectStrategy = DEFAULT_PROJECT_STRATEGY;"),
            "{extension}"
        );
        assert!(
            extension.contains("let marker = findSettingsMarker(cwd);"),
            "the default-strategy variant must also walk past a capture-only marker (#668): {extension}"
        );
    }

    #[test]
    fn omp_extension_default_omits_baked_strategy() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        assert!(
            !extension.contains("DEFAULT_PROJECT_STRATEGY"),
            "{extension}"
        );
    }

    #[test]
    fn omp_extension_uses_bounded_hook_queue() {
        let extension =
            build_omp_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");

        assert_generated_ts_uses_bounded_hook_queue(&extension);
    }

    /// The manual (non-`--apply`) instructions must name the same path
    /// `--apply` would write to. Printing the `~/.pi/agent` default to an
    /// operator who set `PI_CODING_AGENT_DIR` would tell them to hand-copy the
    /// extension exactly where the agent never loads it — reintroducing, in
    /// the manual path, the silent no-capture this change fixes.
    #[test]
    fn extension_hints_follow_pi_coding_agent_dir() {
        let custom = if cfg!(windows) {
            r"C:\custom\pi-agent"
        } else {
            "/custom/pi-agent"
        };
        let env = || Some(std::ffi::OsString::from(custom));

        for hint in [
            omp_extension_hint_with(None, &|name| {
                (name == "PI_CODING_AGENT_DIR").then(env).flatten()
            })
            .unwrap(),
            pi_extension_hint_in(env()),
        ] {
            assert!(
                hint.contains("custom")
                    && (hint.ends_with("ai-memory-omp.ts") || hint.ends_with("ai-memory-pi.ts")),
                "hint must point at the relocated agent home, got: {hint}"
            );
            assert!(
                !hint.contains(".pi/agent") && !hint.contains(".omp/agent"),
                "hint must not advertise the default home when the var is set: {hint}"
            );
        }

        // Unset: the hints keep naming the documented defaults. Build the
        // expected tail from path components rather than hardcoding `/` —
        // `Path::display` renders `\` on Windows, so a slash-literal suffix
        // asserts a path shape that platform never produces.
        for (agent_home, filename, hint) in [
            (
                ".omp",
                "ai-memory-omp.ts",
                omp_extension_hint_with(None, &|_| None).unwrap(),
            ),
            (".pi", "ai-memory-pi.ts", pi_extension_hint_in(None)),
        ] {
            let tail: PathBuf = [agent_home, "agent", "extensions", filename]
                .iter()
                .collect();
            assert!(
                hint.ends_with(&tail.display().to_string()),
                "unset must keep the documented default, got: {hint}"
            );
        }
    }

    fn env_of(
        pairs: &[(&'static str, &'static str)],
    ) -> impl Fn(&str) -> Option<std::ffi::OsString> + use<> {
        let pairs = pairs.to_vec();
        move |name| {
            pairs
                .iter()
                .find(|(key, _)| *key == name)
                .map(|(_, value)| std::ffi::OsString::from(value))
        }
    }

    fn omp_profile_extension(profile: &str) -> PathBuf {
        [
            ".omp",
            "profiles",
            profile,
            "agent",
            "extensions",
            "ai-memory-omp.ts",
        ]
        .iter()
        .collect()
    }

    fn omp_default_extension() -> PathBuf {
        [".omp", "agent", "extensions", "ai-memory-omp.ts"]
            .iter()
            .collect()
    }

    /// OMP gives a named profile its own agent dir and ignores
    /// `PI_CODING_AGENT_DIR` for it (`DirResolver` in OMP 18.2.5 drops the
    /// override whenever a profile is active). Installing into the override
    /// instead put the extension where that OMP never looks.
    #[test]
    fn omp_named_profile_ignores_pi_coding_agent_dir() {
        for custom in ["/custom/agent", "/custom/pi-agent"] {
            let env = env_of(&[("PI_CODING_AGENT_DIR", custom)]);
            let explicit = omp_extension_path_with(Some("work"), &env).unwrap();
            assert!(
                explicit.ends_with(omp_profile_extension("work")),
                "got {explicit:?}"
            );

            let env = env_of(&[("PI_CODING_AGENT_DIR", custom), ("OMP_PROFILE", "work")]);
            let from_env = omp_extension_path_with(None, &env).unwrap();
            assert_eq!(from_env, explicit);
        }
    }

    /// Profile names go through OMP's own normalization: `--profile` beats
    /// `OMP_PROFILE`, a set `OMP_PROFILE` (even empty) masks `PI_PROFILE`,
    /// names are trimmed, empty/whitespace/`default` select the default
    /// profile, and a name OMP refuses is refused here too.
    #[test]
    fn omp_extension_path_normalizes_profile_like_omp() {
        let default = omp_default_extension();
        let work = omp_profile_extension("work");
        type Case<'a> = (
            Option<&'a str>,
            &'a [(&'static str, &'static str)],
            &'a PathBuf,
        );
        let cases: &[Case] = &[
            (None, &[("OMP_PROFILE", "")], &default),
            (None, &[("OMP_PROFILE", "   ")], &default),
            (None, &[("OMP_PROFILE", "default")], &default),
            (None, &[("OMP_PROFILE", " work ")], &work),
            (None, &[("PI_PROFILE", "work")], &work),
            (
                None,
                &[("OMP_PROFILE", ""), ("PI_PROFILE", "work")],
                &default,
            ),
            (Some("work"), &[("OMP_PROFILE", "other")], &work),
            (Some("default"), &[("OMP_PROFILE", "other")], &default),
        ];
        for (explicit, pairs, expected) in cases {
            let path = omp_extension_path_with(*explicit, &env_of(pairs)).unwrap();
            assert!(
                path.ends_with(expected),
                "{explicit:?} {pairs:?} -> {path:?}"
            );
        }

        for (explicit, pairs) in [
            (None, &[("OMP_PROFILE", "Work")][..]),
            (None, &[("OMP_PROFILE", "../x")][..]),
            (None, &[("OMP_PROFILE", "work.")][..]),
            (None, &[("PI_PROFILE", "con")][..]),
            (Some(""), &[][..]),
        ] {
            assert!(
                omp_extension_path_with(explicit, &env_of(pairs)).is_err(),
                "{explicit:?} {pairs:?} must be refused"
            );
        }
    }

    /// The preview names the file `--apply` writes, so it follows
    /// `OMP_PROFILE` even when `--profile` is absent.
    #[test]
    fn omp_preview_hint_follows_omp_profile() {
        let hint = omp_extension_hint_with(None, &env_of(&[("OMP_PROFILE", "work")])).unwrap();
        assert!(
            hint.ends_with(&omp_profile_extension("work").display().to_string()),
            "got {hint}"
        );
    }

    /// `PI_CONFIG_DIR` renames OMP's `~/.omp` root, extensions included, while
    /// an XDG data dir moves only OMP's sessions.
    #[test]
    fn omp_extension_path_follows_pi_config_dir_but_not_xdg() {
        let renamed: PathBuf = [".omp-alt", "agent", "extensions", "ai-memory-omp.ts"]
            .iter()
            .collect();
        let path =
            omp_extension_path_with(None, &env_of(&[("PI_CONFIG_DIR", ".omp-alt")])).unwrap();
        assert!(path.ends_with(&renamed), "{path:?}");
        let profiled: PathBuf = [
            ".omp-alt",
            "profiles",
            "work",
            "agent",
            "extensions",
            "ai-memory-omp.ts",
        ]
        .iter()
        .collect();
        let path = omp_extension_path_with(Some("work"), &env_of(&[("PI_CONFIG_DIR", ".omp-alt")]))
            .unwrap();
        assert!(path.ends_with(&profiled), "{path:?}");

        let xdg = tempfile::tempdir().unwrap();
        std::fs::create_dir(xdg.path().join("omp")).unwrap();
        let xdg_value = xdg.path().to_string_lossy().into_owned();
        let path = omp_extension_path_with(None, &|name: &str| {
            (name == "XDG_DATA_HOME").then(|| std::ffi::OsString::from(&xdg_value))
        })
        .unwrap();
        assert!(path.ends_with(omp_default_extension()), "{path:?}");
    }

    /// With no override, `--profile` relocates to the documented
    /// `~/.omp/profiles/<name>/agent/extensions`.
    #[test]
    fn omp_profile_relocates_when_no_override_is_set() {
        let path = omp_extension_path_with(Some("work"), &|_| None).unwrap();
        assert!(
            path.ends_with(omp_profile_extension("work")),
            "got {path:?}"
        );

        let plain = omp_extension_path_with(None, &|_| None).unwrap();
        assert!(plain.ends_with(omp_default_extension()), "got {plain:?}");
    }

    /// `run` resolves the other Pi-family agent through its launch env, so
    /// the shared-directory check must use the env it is given, not
    /// ai-memory's own.
    #[test]
    fn shared_extensions_dir_follows_the_supplied_env() {
        let root = if cfg!(windows) {
            r"C:\relocated"
        } else {
            "/relocated"
        };
        let env = env_of(&[("PI_CODING_AGENT_DIR", root)]);
        let extensions = Path::new(root).join("extensions");
        for (agent, file) in [
            (AgentChoice::Pi, "ai-memory-pi.ts"),
            (AgentChoice::Omp, "ai-memory-omp.ts"),
        ] {
            let this_path = extensions.join(file);
            assert_eq!(
                shared_extensions_dir(agent, &this_path, &env),
                Some(extensions.clone())
            );
            assert_eq!(shared_extensions_dir(agent, &this_path, &|_| None), None);
        }
        assert_eq!(
            shared_extensions_dir(
                AgentChoice::ClaudeCode,
                &extensions.join("ai-memory-pi.ts"),
                &env
            ),
            None
        );
        // A named profile moves OMP off the shared directory.
        let profiled = env_of(&[("PI_CODING_AGENT_DIR", root), ("OMP_PROFILE", "work")]);
        assert_eq!(
            shared_extensions_dir(
                AgentChoice::Pi,
                &extensions.join("ai-memory-pi.ts"),
                &profiled
            ),
            None
        );
    }

    /// A blank relocation variable is unset for every auto-wired agent's hook
    /// target, the same rule `path_util::agent_config_home` and native session
    /// import use; otherwise the installer wrote into `<cwd>/   /`.
    #[test]
    fn hook_config_target_with_treats_blank_relocation_as_unset() {
        let home = home_dir().unwrap();
        let cases: &[(AgentChoice, &str, &[&str])] = &[
            (
                AgentChoice::ClaudeCode,
                "CLAUDE_CONFIG_DIR",
                &[".claude", "settings.json"],
            ),
            (AgentChoice::Codex, "CODEX_HOME", &[".codex", "hooks.json"]),
            (
                AgentChoice::Pi,
                "PI_CODING_AGENT_DIR",
                &[".pi", "agent", "extensions", "ai-memory-pi.ts"],
            ),
            (
                AgentChoice::Omp,
                "PI_CODING_AGENT_DIR",
                &[".omp", "agent", "extensions", "ai-memory-omp.ts"],
            ),
            (
                AgentChoice::Omp,
                "OMP_PROFILE",
                &[".omp", "agent", "extensions", "ai-memory-omp.ts"],
            ),
            (
                AgentChoice::Omp,
                "PI_CONFIG_DIR",
                &[".omp", "agent", "extensions", "ai-memory-omp.ts"],
            ),
            (
                AgentChoice::KimiCode,
                "KIMI_CODE_HOME",
                &[".kimi-code", "config.toml"],
            ),
            (AgentChoice::KiroCli, "KIRO_HOME", &[".kiro", "agents"]),
            (
                AgentChoice::KiroCliV3,
                "KIRO_HOME",
                &[".kiro", "hooks", "ai-memory.json"],
            ),
            (
                AgentChoice::Grok,
                "GROK_HOME",
                &[".grok", "hooks", "ai-memory.json"],
            ),
        ];
        for (agent, variable, tail) in cases {
            let expected: PathBuf = tail.iter().fold(home.clone(), |path, part| path.join(part));
            for blank in ["", "   ", "\t", " \n"] {
                let env = |name: &str| (name == *variable).then(|| std::ffi::OsString::from(blank));
                assert_eq!(
                    hook_config_target_with(*agent, &env).unwrap(),
                    expected,
                    "{agent:?} with {variable}={blank:?}"
                );
            }
        }
    }

    /// `remove_legacy_extension` must delete only what this tool generated.
    /// `uninstall` gates every delete on the same marker
    /// (`uninstall_omp_extension_deletes_only_generated_file`), so an
    /// unconditional delete on the install path would destroy exactly what
    /// uninstall refuses to touch.
    #[test]
    fn legacy_cleanup_spares_a_user_owned_file_of_the_same_name() {
        let dir = tempfile::tempdir().unwrap();
        let legacy = dir.path().join("ai-memory.ts");
        let user_content = "// user-owned extension that happens to use this filename\n";
        std::fs::write(&legacy, user_content).unwrap();

        remove_legacy_extension(&dir.path().join("ai-memory-omp.ts"), "omp");

        assert!(legacy.exists(), "user-owned file must survive");
        assert_eq!(std::fs::read_to_string(&legacy).unwrap(), user_content);
    }

    /// The generated marker (banner + agent constant) is what authorises
    /// removal.
    #[test]
    fn legacy_cleanup_removes_our_own_superseded_file() {
        let dir = tempfile::tempdir().unwrap();
        let legacy = dir.path().join("ai-memory.ts");
        std::fs::write(
            &legacy,
            "// Auto-generated by `ai-memory install-hooks --agent omp --apply`\nconst AGENT = \"omp\";\n",
        )
        .unwrap();

        remove_legacy_extension(&dir.path().join("ai-memory-omp.ts"), "omp");

        assert!(
            !legacy.exists(),
            "our own superseded file should be removed"
        );
    }

    /// Pi and OMP can share one extensions directory, so a Pi install must
    /// not delete an OMP-generated legacy file — that would silently stop
    /// OMP capturing until someone reinstalled it.
    #[test]
    fn legacy_cleanup_does_not_touch_the_other_agents_file() {
        let dir = tempfile::tempdir().unwrap();
        let legacy = dir.path().join("ai-memory.ts");
        let omp_content = "// Auto-generated by `ai-memory install-hooks --agent omp --apply`\nconst AGENT = \"omp\";\n";
        std::fs::write(&legacy, omp_content).unwrap();

        // A *Pi* install runs its cleanup over the shared directory.
        remove_legacy_extension(&dir.path().join("ai-memory-pi.ts"), "pi");

        assert!(legacy.exists(), "OMP's file must survive a Pi install");
        assert_eq!(std::fs::read_to_string(&legacy).unwrap(), omp_content);
    }

    /// `PI_CODING_AGENT_DIR` relocates Pi's whole agent config home
    /// (`~/.pi/agent`), not just session storage, so the extension must follow
    /// the variable or Pi never loads it — the install reports success and
    /// capture silently does nothing.
    #[test]
    fn pi_extension_path_honours_pi_coding_agent_dir() {
        let custom = if cfg!(windows) {
            r"C:\custom\pi-agent"
        } else {
            "/custom/pi-agent"
        };
        let path = pi_extension_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(
            path,
            Path::new(custom).join("extensions").join("ai-memory-pi.ts")
        );

        // Unset and blank both fall back to ~/.pi/agent/extensions/ai-memory-pi.ts.
        // Blank counts as unset because an exported-but-empty variable is nearly
        // always a failed shell expansion, not a request to install into the
        // filesystem root.
        for env in [None, Some(std::ffi::OsString::new())] {
            let path = pi_extension_path_in(env).unwrap();
            assert!(
                path.ends_with(
                    Path::new(".pi")
                        .join("agent")
                        .join("extensions")
                        .join("ai-memory-pi.ts")
                ),
                "default must be ~/.pi/agent/extensions/ai-memory-pi.ts, got {}",
                path.display()
            );
        }
    }

    /// Same relocation contract as Pi: OMP honors `PI_CODING_AGENT_DIR` for
    /// the default profile and moves `~/.omp/agent` wholesale, extensions
    /// included.
    #[test]
    fn omp_extension_path_honours_pi_coding_agent_dir() {
        let custom = if cfg!(windows) {
            r"C:\custom\omp-agent"
        } else {
            "/custom/omp-agent"
        };
        let path =
            omp_extension_path_with(None, &env_of(&[("PI_CODING_AGENT_DIR", custom)])).unwrap();
        assert_eq!(
            path,
            Path::new(custom)
                .join("extensions")
                .join("ai-memory-omp.ts")
        );

        for env in [None, Some(std::ffi::OsString::new())] {
            let path = omp_extension_path_with(None, &|name| {
                (name == "PI_CODING_AGENT_DIR")
                    .then(|| env.clone())
                    .flatten()
            })
            .unwrap();
            assert!(
                path.ends_with(
                    Path::new(".omp")
                        .join("agent")
                        .join("extensions")
                        .join("ai-memory-omp.ts")
                ),
                "default must be ~/.omp/agent/extensions/ai-memory-omp.ts, got {}",
                path.display()
            );
        }
    }

    #[test]
    fn omp_extension_path_honours_profile() {
        let path = omp_extension_path_with(Some("my-profile"), &|_| None).unwrap();
        assert!(
            path.ends_with(
                Path::new(".omp")
                    .join("profiles")
                    .join("my-profile")
                    .join("agent")
                    .join("extensions")
                    .join("ai-memory-omp.ts")
            ),
            "profile path must be correct, got {}",
            path.display()
        );
    }

    #[test]
    fn omp_extension_is_directly_discoverable_by_omp() {
        let tmp = TempDir::new().unwrap();
        let args = InstallHooksArgs {
            agent: AgentChoice::Omp,
            capture_assistant: false,
            no_capture_prompts: false,
            capture_mode: None,
            capture_prompts: false,
            hooks_dir: None,
            server_url: Some("http://127.0.0.1:49374".into()),
            auth_token: None,
            as_user: None,
            apply: true,
            config_file: Some(tmp.path().join("extensions").join("ai-memory-omp.ts")),
            scope: HookInstallScope::Global,
            project_strategy: Some(ProjectStrategyArg::Basename),
            profile: None,
        };

        let path = resolve_omp_extension_path(&args).unwrap();
        assert_eq!(
            path.file_name().and_then(|s| s.to_str()),
            Some("ai-memory-omp.ts")
        );
        assert_eq!(
            path.parent()
                .and_then(|p| p.file_name())
                .and_then(|s| s.to_str()),
            Some("extensions")
        );
    }

    #[test]
    fn pi_extension_is_directly_discoverable_by_pi() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("extensions").join("ai-memory-pi.ts");
        let args = InstallHooksArgs {
            agent: AgentChoice::Pi,
            capture_assistant: false,
            no_capture_prompts: false,
            capture_mode: None,
            capture_prompts: false,
            hooks_dir: None,
            server_url: Some("http://127.0.0.1:49374".into()),
            auth_token: None,
            as_user: None,
            apply: true,
            config_file: Some(path.clone()),
            scope: HookInstallScope::Global,
            project_strategy: Some(ProjectStrategyArg::Basename),
            profile: None,
        };

        let resolved = resolve_pi_extension_path(&args).unwrap();

        assert_eq!(resolved, path);
        assert_eq!(
            resolved.file_name().and_then(|s| s.to_str()),
            Some("ai-memory-pi.ts")
        );
        assert_eq!(
            resolved
                .parent()
                .and_then(|p| p.file_name())
                .and_then(|s| s.to_str()),
            Some("extensions")
        );
    }

    #[test]
    fn pi_extension_bakes_allowlist_admit_gate() {
        // Pi is `build_omp_extension` with the AGENT constant swapped, so the
        // gate must survive that string-replace rewrite too.
        let extension =
            build_pi_extension("http://127.0.0.1:49374", Some("tok"), None, "allowlist");
        assert!(
            extension.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"allowlist\";"),
            "{extension}"
        );
        assert!(extension.contains(CAPTURE_ADMIT_GATE_TS), "{extension}");
    }

    /// #992: the generated integrations do not route `server` profiles, so
    /// every one must drop a routed repository's events and skip its handoff
    /// fetch — both before anything reaches the install-default `SERVER`.
    #[test]
    fn generated_integrations_fail_closed_on_a_server_profile_marker() {
        let plugins = [
            (
                "opencode",
                build_opencode_plugin("http://127.0.0.1:49374", None, None, "denylist"),
            ),
            (
                "opencode2",
                build_opencode2_plugin("http://127.0.0.1:49374", None, None, "denylist", false)
                    .unwrap(),
            ),
            (
                "omp",
                build_omp_extension("http://127.0.0.1:49374", None, None, "denylist"),
            ),
            (
                "pi",
                build_pi_extension("http://127.0.0.1:49374", None, None, "denylist"),
            ),
        ];
        for (agent, plugin) in plugins {
            assert!(
                plugin.contains(
                    "if (captureServerRouted(cwd)) return { disposition: \"drop\", payload };"
                ),
                "{agent}: capture must drop a server-routed repository"
            );
            let handoff = plugin
                .split_once("async function fetchHandoff(")
                .unwrap_or_else(|| panic!("{agent}: no fetchHandoff"))
                .1;
            let guard = handoff
                .find("if (captureServerRouted(")
                .unwrap_or_else(|| panic!("{agent}: handoff fetch must be gated"));
            let request = handoff.find("/handoff`").unwrap();
            assert!(guard < request, "{agent}: gate must precede the request");
        }
    }

    /// `GET /handoff` claims a baton in whatever project the server resolves,
    /// so a generated integration must never send one without a directory:
    /// the server would use its default or last active project. OpenCode
    /// always has its plugin `directory`; Pi and OMP read `ctx.cwd`, which a
    /// host may omit.
    #[test]
    fn generated_integrations_never_fetch_a_handoff_without_a_directory() {
        let plugins = [
            (
                "opencode",
                build_opencode_plugin("http://127.0.0.1:49374", None, None, "denylist"),
            ),
            (
                "opencode2",
                build_opencode2_plugin("http://127.0.0.1:49374", None, None, "denylist", false)
                    .unwrap(),
            ),
            (
                "omp",
                build_omp_extension("http://127.0.0.1:49374", None, None, "denylist"),
            ),
            (
                "pi",
                build_pi_extension("http://127.0.0.1:49374", None, None, "denylist"),
            ),
        ];
        for (agent, plugin) in plugins {
            let handoff = plugin
                .split_once("async function fetchHandoff(")
                .unwrap_or_else(|| panic!("{agent}: no fetchHandoff"))
                .1;
            let guard = handoff
                .find("if (!cwd) return undefined;")
                .unwrap_or_else(|| panic!("{agent}: handoff fetch must require a directory"));
            let request = handoff.find("/handoff`").unwrap();
            assert!(guard < request, "{agent}: guard must precede the request");
        }
    }

    /// An allowlist build sends nothing for an unmarked repository: not the
    /// capture (#661), and not the handoff or recap GET either, which the
    /// server answers by resolving the directory into a project, creating it.
    /// The native hook returns before those requests for the same reason.
    #[test]
    fn allowlist_integrations_fetch_no_handoff_or_recap_outside_a_marked_repository() {
        const GATE: &str =
            "if (CAPTURE_MODE === \"allowlist\" && !findMarker(cwd)) return undefined;";
        let plugins = [
            (
                "opencode",
                build_opencode_plugin("http://127.0.0.1:49374", None, None, "allowlist"),
            ),
            (
                "opencode2",
                build_opencode2_plugin("http://127.0.0.1:49374", None, None, "allowlist", false)
                    .unwrap(),
            ),
            (
                "omp",
                build_omp_extension("http://127.0.0.1:49374", None, None, "allowlist"),
            ),
            (
                "pi",
                build_pi_extension("http://127.0.0.1:49374", None, None, "allowlist"),
            ),
        ];
        for (agent, plugin) in plugins {
            assert!(
                plugin
                    .contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"allowlist\";"),
                "{agent}: the mode must be baked in"
            );
            for (fetch, path) in [("fetchHandoff", "/handoff`"), ("fetchRecap", "/recap`")] {
                let Some((_, body)) = plugin.split_once(&format!("async function {fetch}(")) else {
                    assert_eq!(fetch, "fetchRecap", "{agent}: no {fetch}");
                    continue;
                };
                let gate = body
                    .find(GATE)
                    .unwrap_or_else(|| panic!("{agent}: {fetch} must honour the allowlist"));
                let request = body.find(path).unwrap();
                assert!(
                    gate < request,
                    "{agent}: {fetch} gate must precede the request"
                );
            }
        }
    }

    /// Slow tier: spawns Node to run the generated OMP extension.
    mod slow_generated_handoff_runtime {
        use super::*;

        const PLACEHOLDER_SERVER: &str = "http://127.0.0.1:65535";

        /// Binds a loopback stand-in for the server, points the rendered
        /// extension at it, then drives `before_agent_start` for a context
        /// whose `cwd` is empty and for one that names a directory. Every
        /// `/handoff` request is recorded with the `cwd` it named.
        const HARNESS: &str = r#"import { createServer } from "node:http";
import { readFileSync, writeFileSync } from "node:fs";

const project = process.argv[2]!;
const claims: string[] = [];
const server = createServer((req, res) => {
  const url = new URL(req.url ?? "/", "http://127.0.0.1");
  req.resume();
  if (url.pathname === "/handoff") {
    claims.push(url.searchParams.get("cwd") ?? "<none>");
    res.writeHead(200, { "content-type": "text/plain" });
    res.end("OTHER-PROJECT-HANDOFF");
    return;
  }
  res.writeHead(204);
  res.end();
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
const port = (server.address() as any).port;
writeFileSync(
  "./ext.ts",
  readFileSync("./ext.template.ts", "utf8").replace("http://127.0.0.1:65535", `http://127.0.0.1:${port}`),
);
const { default: AiMemoryExtension } = await import("./ext.ts");
const handlers: Record<string, any> = {};
AiMemoryExtension({ on: (name: string, fn: any) => { handlers[name] = fn; } });
const ctx = (id: string, cwd?: string) => ({
  sessionManager: { getSessionId: () => id },
  ...(cwd === undefined ? {} : { cwd }),
});
const unscoped = await handlers["before_agent_start"]({ prompt: "continue" }, ctx("s-unscoped", ""));
const scoped = await handlers["before_agent_start"]({ prompt: "continue" }, ctx("s-scoped", project));
console.log(JSON.stringify({
  claims,
  unscoped: unscoped?.message?.content ?? null,
  scoped: scoped?.message?.content ?? null,
}));
process.exit(0);
"#;

        fn node_strips_types() -> bool {
            Command::new("node")
                .args(["--experimental-strip-types", "--version"])
                .output()
                .is_ok_and(|output| output.status.success())
        }

        /// The rendered OMP extension with a wider handoff deadline. These
        /// tests prove which session claims, not the production deadline. A
        /// Windows runner executes them beside the full Rust suite, where a
        /// cold Node fetch can exceed one second.
        fn extension_under_test() -> String {
            let extension = build_omp_extension(PLACEHOLDER_SERVER, None, None, "denylist")
                .replacen(
                    "signal: timeoutSignal(1000)",
                    "signal: timeoutSignal(5000)",
                    1,
                );
            assert!(extension.contains("signal: timeoutSignal(5000)"));
            extension
        }

        /// The rendered OpenCode V1 plugin with the same wider handoff deadline
        /// as [`extension_under_test`].
        fn opencode_plugin_under_test() -> String {
            let plugin = build_opencode_plugin(PLACEHOLDER_SERVER, None, None, "denylist")
                .replacen(
                    "signal: timeoutSignal(1000)",
                    "signal: timeoutSignal(5000)",
                    1,
                );
            assert!(plugin.contains("signal: timeoutSignal(5000)"));
            plugin
        }

        /// Runs `harness` against `extension` in Node with `tmp` as its home
        /// and returns the JSON line the harness prints last.
        fn run_harness(
            tmp: &TempDir,
            extension: String,
            harness: &str,
            project: &std::path::Path,
        ) -> serde_json::Value {
            fs::write(tmp.path().join("ext.template.ts"), extension).unwrap();
            fs::write(tmp.path().join("harness.ts"), harness).unwrap();
            let mut command = Command::new("node");
            for (key, _) in std::env::vars_os() {
                let key_text = key.to_string_lossy();
                if key_text.starts_with("AI_MEMORY_") || key_text.starts_with("GIT_") {
                    command.env_remove(&key);
                }
            }
            let output = command
                .args(["--experimental-strip-types", "--no-warnings", "harness.ts"])
                .arg(project)
                .current_dir(tmp.path())
                .env("HOME", tmp.path())
                .env("USERPROFILE", tmp.path())
                .env("AI_MEMORY_HOME", tmp.path())
                .env("AI_MEMORY_DATA_DIR", tmp.path().join("data"))
                .env("GIT_CONFIG_GLOBAL", tmp.path().join("absent-gitconfig"))
                .env("GIT_CONFIG_SYSTEM", tmp.path().join("absent-gitconfig"))
                .output()
                .unwrap();
            assert!(
                output.status.success(),
                "harness failed\nstdout:\n{}\nstderr:\n{}",
                String::from_utf8_lossy(&output.stdout),
                String::from_utf8_lossy(&output.stderr)
            );
            serde_json::from_slice(
                String::from_utf8_lossy(&output.stdout)
                    .lines()
                    .last()
                    .unwrap()
                    .as_bytes(),
            )
            .unwrap()
        }

        #[test]
        fn omp_extension_never_claims_a_handoff_without_a_directory() {
            if !node_strips_types() {
                eprintln!("skipping: node lacks --experimental-strip-types");
                return;
            }
            let tmp = TempDir::new().unwrap();
            let project = tmp.path().join("project");
            fs::create_dir(&project).unwrap();
            let run = run_harness(&tmp, extension_under_test(), HARNESS, &project);
            // Only the scoped context claims, and it names its directory.
            assert_eq!(
                run["claims"],
                serde_json::json!([project.to_string_lossy()]),
                "{run}"
            );
            assert_eq!(run["unscoped"], serde_json::Value::Null, "{run}");
            assert_eq!(run["scoped"], "OTHER-PROJECT-HANDOFF", "{run}");
        }

        /// Drives one top-level OMP session the way OMP reports it
        /// (`ctx.agent`, `docs/extensions.md` "Handler context"): its advisor's
        /// tool calls, a task subagent, a `/tan` clone, a revived subagent this
        /// process never saw, and a session without `ctx.agent` (Pi). Records
        /// every `/handoff` claim by session id and every `/hook` event with
        /// the `agent_id` it carried.
        const SUBAGENT_HARNESS: &str = r#"import { createServer } from "node:http";
import { readFileSync, writeFileSync } from "node:fs";

const project = process.argv[2]!;
const claims: string[] = [];
const hooks: { event: string; sessionID: unknown; agent_id: unknown }[] = [];
const server = createServer((req, res) => {
  const url = new URL(req.url ?? "/", "http://127.0.0.1");
  let body = "";
  req.setEncoding("utf8");
  req.on("data", (chunk) => { body += chunk; });
  req.on("end", () => {
    if (url.pathname === "/handoff") {
      claims.push(url.searchParams.get("session_id") ?? "<none>");
      res.writeHead(200, { "content-type": "text/plain" });
      res.end("PENDING-HANDOFF");
      return;
    }
    if (url.pathname === "/hook") {
      const payload = JSON.parse(body);
      hooks.push({
        event: url.searchParams.get("event") ?? "",
        sessionID: payload.sessionID ?? null,
        agent_id: payload.agent_id ?? null,
      });
    }
    res.writeHead(204);
    res.end();
  });
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
const port = (server.address() as any).port;
writeFileSync(
  "./ext.ts",
  readFileSync("./ext.template.ts", "utf8").replace("http://127.0.0.1:65535", `http://127.0.0.1:${port}`),
);
const { default: AiMemoryExtension } = await import("./ext.ts");
const handlers: Record<string, any> = {};
AiMemoryExtension({ on: (name: string, fn: any) => { handlers[name] = fn; } });
const MAIN = { kind: "main", id: "Main", name: "main", depth: 0 };
const TASK = { kind: "sub", id: "0-Explore", name: "explore", depth: 1, parentId: "Main" };
const CLONE = { kind: "sub", id: "1-Clone", name: "sub", depth: 0, parentId: "Main" };
const ADVISOR = { kind: "sub", id: "advisor", name: "advisor", depth: 0, parentId: "Main" };
const ctx = (id: string, agent?: object) => ({
  sessionManager: { getSessionId: () => id },
  cwd: project,
  ...(agent === undefined ? {} : { agent }),
});
const tool = {
  toolName: "read",
  toolCallId: "call-1",
  input: { path: "README.md" },
  content: [{ type: "text", text: "ok" }],
};
const delivered: Record<string, unknown> = {};
async function prompt(id: string, agent?: object, event: object = { prompt: "continue" }) {
  const result = await handlers["before_agent_start"](event, ctx(id, agent));
  delivered[id] = result?.message?.content ?? null;
}
await handlers["session_start"]({}, ctx("main", MAIN));
await prompt("main", MAIN);
await handlers["tool_call"](tool, ctx("main", ADVISOR));
await handlers["tool_result"](tool, ctx("main", ADVISOR));
for (const [id, agent] of [["task", TASK], ["clone", CLONE]] as const) {
  await handlers["session_start"]({}, ctx(id, agent));
  await prompt(id, agent);
  await handlers["tool_call"](tool, ctx(id, agent));
  await handlers["agent_end"]({}, ctx(id, agent));
  await handlers["session_shutdown"]({}, ctx(id, agent));
}
await handlers["session_start"]({}, ctx("revived", TASK));
await prompt("revived", TASK, { prompt: "", reason: "revive" });
await prompt("legacy");
await handlers["session_shutdown"]({}, ctx("main", MAIN));
// The extension delivers in order, so the main session's end arrives last.
const deadline = Date.now() + 20000;
while (!hooks.some((hook) => hook.event === "session-end" && hook.sessionID === "main")) {
  if (Date.now() > deadline) break;
  await new Promise((resolve) => setTimeout(resolve, 50));
}
console.log(JSON.stringify({ claims, delivered, hooks }));
process.exit(0);
"#;

        #[test]
        fn omp_extension_keeps_subagent_sessions_off_the_baton() {
            if !node_strips_types() {
                eprintln!("skipping: node lacks --experimental-strip-types");
                return;
            }
            let tmp = TempDir::new().unwrap();
            let project = tmp.path().join("project");
            fs::create_dir(&project).unwrap();
            let run = run_harness(&tmp, extension_under_test(), SUBAGENT_HARNESS, &project);
            // Only the top-level session and the session without `ctx.agent`
            // claim; no subagent asks for the baton, not even a revived one.
            assert_eq!(
                run["claims"],
                serde_json::json!(["main", "legacy"]),
                "{run}"
            );
            assert_eq!(run["delivered"]["main"], "PENDING-HANDOFF", "{run}");
            for id in ["task", "clone", "revived"] {
                assert_eq!(run["delivered"][id], serde_json::Value::Null, "{id}: {run}");
            }
            let hooks = run["hooks"].as_array().unwrap();
            let session = |id: &str| -> Vec<(String, serde_json::Value)> {
                hooks
                    .iter()
                    .filter(|hook| hook["sessionID"] == id)
                    .map(|hook| {
                        (
                            hook["event"].as_str().unwrap().to_string(),
                            hook["agent_id"].clone(),
                        )
                    })
                    .collect()
            };
            // Every event of a subagent session is marked, its end included,
            // so the server leaves no baton and can drop it on request.
            for (id, agent_id, end) in [
                ("task", "0-Explore", true),
                ("clone", "1-Clone", true),
                ("revived", "0-Explore", false),
            ] {
                let events = session(id);
                assert!(
                    events.iter().any(|(event, _)| event == "session-start"),
                    "{id}: {run}"
                );
                assert_eq!(
                    events.iter().any(|(event, _)| event == "session-end"),
                    end,
                    "{id}: {run}"
                );
                assert!(
                    events.iter().all(|(_, marker)| marker == agent_id),
                    "every {id} event must carry agent_id {agent_id}: {run}"
                );
            }
            // The advisor's tool calls reach the top-level session as
            // `kind: "sub"` and must not mark it, or an opted-in project
            // would drop the rest of that session, its end included.
            let main = session("main");
            for event in ["pre-tool-use", "post-tool-use", "session-end"] {
                assert!(main.iter().any(|(seen, _)| seen == event), "{event}: {run}");
            }
            assert!(
                main.iter().all(|(_, marker)| marker.is_null()),
                "the top-level session must stay unmarked: {run}"
            );
            assert!(
                session("legacy").iter().all(|(_, marker)| marker.is_null()),
                "{run}"
            );
        }

        /// Drives the rendered OpenCode V1 plugin in the order OpenCode 1.x
        /// calls it: a top-level session, then a `task` subagent that
        /// `tool/task.ts` runs in a child session (a prompt as
        /// `session/prompt.ts` runs it, a tool call, a second model call), a
        /// subagent the task tool resumes by `task_id` and a top-level session
        /// continued from an earlier process (neither has a `session.created`
        /// here), then the `dispose` that `cli/bootstrap.ts` runs at exit.
        /// Records every `/handoff` claim by session id, what each session's
        /// first model call was given, and every `/hook` event with the
        /// `agent_id` it carried.
        const OPENCODE_SUBAGENT_HARNESS: &str = r#"import { createServer } from "node:http";
import { readFileSync, writeFileSync } from "node:fs";

const project = process.argv[2]!;
const claims: string[] = [];
const hooks: { event: string; sessionID: unknown; agent_id: unknown }[] = [];
const server = createServer((req, res) => {
  const url = new URL(req.url ?? "/", "http://127.0.0.1");
  let body = "";
  req.setEncoding("utf8");
  req.on("data", (chunk) => { body += chunk; });
  req.on("end", () => {
    if (url.pathname === "/handoff") {
      claims.push(url.searchParams.get("session_id") ?? "<none>");
      res.writeHead(200, { "content-type": "text/plain" });
      res.end("PENDING-HANDOFF");
      return;
    }
    if (url.pathname === "/hook") {
      const payload = JSON.parse(body);
      hooks.push({
        event: url.searchParams.get("event") ?? "",
        sessionID: payload.sessionID ?? null,
        agent_id: payload.agent_id ?? null,
      });
    }
    res.writeHead(204);
    res.end();
  });
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
const port = (server.address() as any).port;
writeFileSync(
  "./ext.ts",
  readFileSync("./ext.template.ts", "utf8").replace("http://127.0.0.1:65535", `http://127.0.0.1:${port}`),
);
const { default: AiMemoryHooks } = await import("./ext.ts");
const plugin = await AiMemoryHooks({ directory: project });
const info = (id: string, parentID?: string) => ({ id, directory: project, ...(parentID ? { parentID } : {}) });
const created = (id: string, parentID?: string) =>
  plugin.event({ event: { type: "session.created", properties: { sessionID: id, info: info(id, parentID) } } });
const delivered: Record<string, unknown> = {};
async function modelCall(id: string) {
  const output = { system: [] as string[] };
  await plugin["experimental.chat.system.transform"]({ sessionID: id }, output);
  if (!(id in delivered)) delivered[id] = output.system.join("\n") || null;
}
// A prompt: the user message, the session touch that publishes
// `session.updated`, then the model call.
async function prompt(id: string, parentID?: string) {
  await plugin["chat.message"]({ sessionID: id }, { parts: [{ type: "text", text: "continue" }] });
  await plugin.event({ event: { type: "session.updated", properties: { sessionID: id, info: info(id, parentID) } } });
  await modelCall(id);
}
await created("root");
await prompt("root");
await created("task", "root");
await prompt("task", "root");
const read = { tool: "read", sessionID: "task", callID: "call-1" };
await plugin["tool.execute.before"](read, { args: { filePath: "README.md" } });
await plugin["tool.execute.after"]({ ...read, args: { filePath: "README.md" } }, { title: "README.md", output: "ok", metadata: {} });
await modelCall("task");
await plugin.event({ event: { type: "session.idle", properties: { sessionID: "task" } } });
// A child the task tool resumes by `task_id` and a top-level session
// continued from an earlier process: neither has a `session.created` here.
await prompt("resumed", "root");
await prompt("continued");
await plugin.dispose();
// The plugin delivers in order; wait for every session's end.
const sessions = ["root", "task", "resumed", "continued"];
const ended = (id: string) => hooks.some((hook) => hook.event === "session-end" && hook.sessionID === id);
const deadline = Date.now() + 20000;
while (!sessions.every(ended)) {
  if (Date.now() > deadline) break;
  await new Promise((resolve) => setTimeout(resolve, 50));
}
console.log(JSON.stringify({ claims, delivered, hooks }));
process.exit(0);
"#;

        #[test]
        fn opencode_plugin_keeps_task_subagents_off_the_baton() {
            if !node_strips_types() {
                eprintln!("skipping: node lacks --experimental-strip-types");
                return;
            }
            let tmp = TempDir::new().unwrap();
            let project = tmp.path().join("project");
            fs::create_dir(&project).unwrap();
            let run = run_harness(
                &tmp,
                opencode_plugin_under_test(),
                OPENCODE_SUBAGENT_HARNESS,
                &project,
            );
            // Only the top-level sessions claim, the continued one included.
            // No model call of a subagent, resumed or not, asks for the baton
            // or is given one.
            assert_eq!(
                run["claims"],
                serde_json::json!(["root", "continued"]),
                "{run}"
            );
            for (id, given) in [
                ("root", serde_json::json!("PENDING-HANDOFF")),
                ("task", serde_json::Value::Null),
                ("resumed", serde_json::Value::Null),
                ("continued", serde_json::json!("PENDING-HANDOFF")),
            ] {
                assert_eq!(run["delivered"][id], given, "{id}: {run}");
            }
            let hooks = run["hooks"].as_array().unwrap();
            let markers = |id: &str, event: &str| -> Vec<serde_json::Value> {
                hooks
                    .iter()
                    .filter(|hook| hook["sessionID"] == id && hook["event"] == event)
                    .map(|hook| hook["agent_id"].clone())
                    .collect()
            };
            // The subagent's end, which `dispose` posts at exit, names its
            // parent, so the server closes it without a baton. Its prompt and
            // tool calls are still captured.
            let parent = [serde_json::json!("root")];
            assert_eq!(markers("task", "session-start"), parent, "{run}");
            assert_eq!(markers("task", "session-end"), parent, "{run}");
            for event in ["user-prompt", "pre-tool-use", "post-tool-use", "stop"] {
                assert!(!markers("task", event).is_empty(), "{event}: {run}");
            }
            // The resumed subagent is known from its `session.updated` by the
            // time OpenCode exits, so its end names the parent too.
            assert_eq!(
                markers("resumed", "session-end"),
                [serde_json::json!("root")],
                "{run}"
            );
            // The top-level sessions stay unmarked, their ends included.
            for id in ["root", "continued"] {
                assert_eq!(
                    markers(id, "session-end"),
                    [serde_json::Value::Null],
                    "{id}: {run}"
                );
                assert!(
                    hooks
                        .iter()
                        .filter(|hook| hook["sessionID"] == id)
                        .all(|hook| hook["agent_id"].is_null()),
                    "{id}: {run}"
                );
            }
        }

        /// Every request reaches a gateway in front of the server that
        /// answers with a redirect to its login page on another origin: 302
        /// for reads, 307 for the event posts, which a followed redirect
        /// would replay there. One event from an earlier offline session is
        /// already spooled.
        const REDIRECT_HARNESS: &str = r#"import { createServer } from "node:http";
import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

const project = process.argv[2]!;
const loginHits: string[] = [];
const login = createServer((req, res) => {
  req.resume();
  loginHits.push(`${req.method} ${req.url}`);
  res.writeHead(200, { "content-type": "text/html" });
  res.end("<html>GATEWAY-LOGIN</html>");
});
await new Promise<void>((resolve) => login.listen(0, "127.0.0.1", () => resolve()));
const loginPort = (login.address() as any).port;
const gatewayBodies: string[] = [];
const gateway = createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    gatewayBodies.push(body);
    res.writeHead(req.method === "POST" ? 307 : 302, {
      location: `http://127.0.0.1:${loginPort}/login`,
    });
    res.end();
  });
});
await new Promise<void>((resolve) => gateway.listen(0, "127.0.0.1", () => resolve()));
const port = (gateway.address() as any).port;

const spool = join(process.env.AI_MEMORY_DATA_DIR!, "hook-spool");
mkdirSync(spool, { recursive: true });
writeFileSync(join(spool, "0000000000001-1-0000000000000001.json"), JSON.stringify({
  url: `http://127.0.0.1:${port}/hook?event=user-prompt&agent=omp`,
  body: JSON.stringify({ sessionID: "s-offline", prompt: "SPOOLED-WHILE-OFFLINE" }),
  created_ms: 1,
  auth_mode: "none",
}));
writeFileSync(
  "./ext.ts",
  readFileSync("./ext.template.ts", "utf8").replace("http://127.0.0.1:65535", `http://127.0.0.1:${port}`),
);
const { default: AiMemoryExtension } = await import("./ext.ts");
const handlers: Record<string, any> = {};
AiMemoryExtension({ on: (name: string, fn: any) => { handlers[name] = fn; } });
const ctx = { sessionManager: { getSessionId: () => "s-gateway" }, cwd: project };
handlers["session_start"]({}, ctx);
const reply = await handlers["before_agent_start"]({ prompt: "continue" }, ctx);
await handlers["session_shutdown"]({}, ctx);
// A queue flush starts the spool drain in the background: wait until it has
// posted the spooled event, then give its answer time to land.
const drained = () => gatewayBodies.some((body) => body.includes("SPOOLED-WHILE-OFFLINE"));
for (let i = 0; i < 100 && !drained(); i++) {
  await new Promise((resolve) => setTimeout(resolve, 50));
}
await new Promise((resolve) => setTimeout(resolve, 300));
console.log(JSON.stringify({
  handoff: reply?.message?.content ?? null,
  loginHits,
  drained: drained(),
  spooled: readdirSync(spool).filter((name) => name.endsWith(".json")).sort(),
}));
process.exit(0);
"#;

        /// Followed, the gateway's redirect would put its login page in the
        /// agent's context, count it as the delivery of every event (the
        /// spooled one deleted, this session's never spooled) and replay the
        /// posts to the login origin. Refused, that origin is never
        /// contacted, no handoff is injected, and the events wait on disk
        /// for the real server.
        #[test]
        fn omp_extension_refuses_a_gateway_redirect() {
            if !node_strips_types() {
                eprintln!("skipping: node lacks --experimental-strip-types");
                return;
            }
            let tmp = TempDir::new().unwrap();
            let project = tmp.path().join("project");
            fs::create_dir(&project).unwrap();
            let run = run_harness(&tmp, extension_under_test(), REDIRECT_HARNESS, &project);
            assert_eq!(run["loginHits"], serde_json::json!([]), "{run}");
            assert!(run["handoff"].is_null(), "{run}");
            assert_eq!(run["drained"], serde_json::json!(true), "{run}");
            let spooled = run["spooled"].as_array().expect("spool listing");
            assert!(
                spooled.contains(&serde_json::json!("0000000000001-1-0000000000000001.json")),
                "the refused drain must keep the earlier event: {run}"
            );
            assert!(
                spooled.len() > 1,
                "this session's refused posts must be spooled: {run}"
            );
        }
    }

    #[test]
    fn pi_extension_denylist_bakes_inert_gate() {
        let extension = build_pi_extension("http://127.0.0.1:49374", Some("tok"), None, "denylist");
        assert!(
            extension.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"denylist\";"),
            "{extension}"
        );
        assert!(extension.contains(CAPTURE_ADMIT_GATE_TS), "{extension}");
    }

    #[test]
    fn pi_extension_contains_lifecycle_capture_and_mcp_bridge() {
        let extension =
            build_pi_extension("http://127.0.0.1:49374/base", Some("tok"), None, "denylist");

        assert!(extension.contains("export default function AiMemoryExtension(pi: any): void"));
        assert!(extension.contains("const AGENT = \"pi\";"));
        assert!(extension.contains("pi.on(\"session_start\""));
        assert!(extension.contains("pi.on(\"before_agent_start\""));
        assert!(extension.contains("pi.on(\"tool_call\""));
        assert!(extension.contains("pi.on(\"tool_result\""));
        assert!(extension.contains("pi.on(\"session_before_compact\""));
        assert!(extension.contains("pi.on(\"session_compact\""));
        assert!(!extension.contains("pi.on(\"session.compacting\""));
        assert!(extension.contains("pi.on(\"agent_end\""));
        assert!(extension.contains("pi.on(\"session_shutdown\""));
        assert!(extension.contains("postHook(\"session-start\""));
        assert!(extension.contains("postHook(\"user-prompt\""));
        assert!(extension.contains("postHook(\"pre-tool-use\""));
        assert!(extension.contains("postHook(\"post-tool-use\""));
        assert!(extension.contains("postHook(\"pre-compact\""));
        assert!(extension.contains("postHook(\"stop\""));
        assert!(extension.contains("postHook(\"session-end\""));
        assert!(extension.contains("fetchHandoff"));
        assert!(extension.contains("customType: \"ai-memory-handoff\""));
        assert!(
            extension.contains("const MCP_SERVER = `${deriveMcpServer(SERVER)}?flavor=moonshot`;")
        );
        assert!(
            extension.contains("return trimmed.endsWith(\"/mcp\") ? trimmed : `${trimmed}/mcp`;")
        );
        assert!(extension.contains("\"Accept\": \"application/json, text/event-stream\""));
        assert!(extension.contains("...authHeaders()"));
        assert!(extension.contains("headers[\"X-Memory-Actor-Session-Id\"] = session;"));
        assert!(extension.contains("headers[\"Mcp-Session-Id\"] = session;"));
        assert!(extension.contains("function mcpSignal(signal?: AbortSignal)"));
        assert!(extension.contains("anyFactory([signal, timeout])"));
        assert!(extension.contains("mcpRpc(\"initialize\""));
        assert!(extension.contains("mcpNotify(\"notifications/initialized\""));
        assert!(!extension.contains("mcpRpc(\"notifications/initialized\""));
        assert!(extension.contains(
            "async function mcpNotify(method: string, params?: unknown, ctx?: any, signal?: AbortSignal): Promise<void>"
        ));
        assert!(
            extension.contains(
                "body: JSON.stringify({ jsonrpc: \"2.0\", method, params: params ?? {} })"
            )
        );
        assert!(extension.contains("mcpRpc(\"tools/list\""));
        assert!(extension.contains("pi.registerTool"));
        assert!(extension.contains("label: tool.name"));
        assert!(extension.contains("parameters: toolInputSchema(tool)"));
        assert!(extension.contains(
            "mcpRpc(\"tools/call\", { name: tool.name, arguments: params ?? {} }, ctx, signal)"
        ));
        assert!(extension.contains("payload?.error"));
        assert!(extension.contains("payload?.result?.isError"));
        assert!(extension.contains("response.ok"));
        assert!(extension.contains("signal: mcpSignal(signal)"));
        assert!(extension.contains("Bearer ${token}"));
        assert!(extension.contains("tok"));
        assert!(extension.contains("import { execFileSync } from \"node:child_process\";"));
        assert!(!extension.contains(".omp"));
        assert!(extension.contains("repoProjectCache.set(cwd, project);"));
        assert_eq!(extension.matches("windowsHide: true").count(), 3);
        assert!(!extension.contains("serve --transport stdio"));
        assert!(!extension.contains("serve --stdio"));
        // #676: the pi string-transform (api.on( -> pi.on() must still
        // produce an async session_shutdown handler that awaits the bounded
        // dispose flush, mirroring the omp source it derives from.
        assert!(extension.contains("const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;"));
        assert!(extension.contains("function requestHookDrain(): Promise<void>"));
        assert!(extension.contains("async function drainHookQueueForDispose(): Promise<void>"));
        assert!(
            extension.contains("pi.on(\"session_shutdown\", async (_event: any, ctx: any) => {")
        );
        assert!(extension.contains("await drainHookQueueForDispose();"));
        assert!(
            !extension.contains("pi.on(\"session_shutdown\", (_event: any, ctx: any) => {"),
            "session_shutdown must not regress to the sync fire-and-forget form: {extension}"
        );
    }

    /// #1136: `notifications/initialized` is a JSON-RPC notification. The
    /// generated `mcpNotify` helper must omit `id`, must not parse a 2xx
    /// body (the server answers 202 empty), and must be the only path
    /// `bootstrapMcpBridge` uses for that method.
    #[test]
    fn pi_mcp_bridge_sends_initialized_as_a_jsonrpc_notification() {
        let extension =
            build_pi_extension("http://127.0.0.1:49374/base", Some("tok"), None, "denylist");

        let notify_start = extension
            .find("async function mcpNotify(")
            .expect("mcpNotify must be generated");
        let notify_end = extension[notify_start..]
            .find("function toolInputSchema")
            .expect("toolInputSchema follows mcpNotify");
        let notify = &extension[notify_start..notify_start + notify_end];
        assert!(
            notify.contains("JSON.stringify({ jsonrpc: \"2.0\", method, params: params ?? {} })"),
            "notification JSON must omit id: {notify}"
        );
        assert!(
            !notify.contains("\"id\""),
            "mcpNotify must not mint an id member: {notify}"
        );
        assert!(
            !notify.contains("response.json"),
            "empty 202 must not be parsed as JSON: {notify}"
        );
        assert!(
            notify.contains("if (!response.ok)"),
            "non-2xx still fails the notification: {notify}"
        );
        assert!(
            extension
                .contains("try { await mcpNotify(\"notifications/initialized\"); } catch (_e) {}"),
            "bootstrap must call mcpNotify: {extension}"
        );
        assert!(
            !extension.contains("mcpRpc(\"notifications/initialized\""),
            "bootstrap must not send initialized through mcpRpc"
        );
    }

    // Windows 11 + Git Bash support matters for regulated enterprise setups
    // where Git Bash is the approved shell available from the corporate
    // repository, so this installer contract should be exercised anywhere
    // Bash is the supported execution surface.
    #[cfg(any(unix, windows))]
    #[test]
    fn curl_installer_accepts_generated_integration_agents() {
        let script = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("scripts")
            .join("install-hooks.sh");
        let Some(bash) = bash_program_for_installer_test() else {
            return;
        };

        for alias in ["opencode", "openclaw", "omp", "oh-my-pi", "pi"] {
            let output = Command::new(&bash)
                .arg(&script)
                .arg("--agent")
                .arg(alias)
                .output()
                .unwrap_or_else(|e| {
                    panic!("failed to run {} for alias {alias}: {e}", script.display())
                });

            assert!(
                output.status.success(),
                "script rejected generated integration alias {alias}: stdout={}, stderr={}",
                String::from_utf8_lossy(&output.stdout),
                String::from_utf8_lossy(&output.stderr)
            );

            let stdout = String::from_utf8_lossy(&output.stdout);
            match alias {
                "opencode" => assert!(stdout.contains("install-hooks --agent opencode --apply")),
                "openclaw" => assert!(stdout.contains("install-hooks --agent openclaw --apply")),
                // The agent-distinct names the installers write, not the
                // pre-rename `ai-memory.ts`.
                "omp" | "oh-my-pi" => {
                    assert!(stdout.contains("install-hooks --agent omp --apply"));
                    assert!(stdout.contains("~/.omp/agent/extensions/ai-memory-omp.ts"));
                }
                "pi" => {
                    assert!(stdout.contains("install-hooks --agent pi --apply"));
                    assert!(stdout.contains("~/.pi/agent/extensions/ai-memory-pi.ts"));
                    assert!(stdout.contains("MCP tools come through the same generated bridge"));
                    assert!(!stdout.contains("~/.omp/agent/extensions"));
                }
                _ => unreachable!(),
            }
        }
    }

    // ----------------------------------------------------------------
    // Cursor tests
    // ----------------------------------------------------------------

    #[test]
    fn cursor_preserves_existing_user_hooks_and_adds_ours() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");
        // Pre-existing settings with a user hook under a different event.
        fs::write(
            &config_path,
            r#"{"version":1,"hooks":{"userHook":"something"}}"#,
        )
        .unwrap();

        merge_cursor_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // User's hook survives.
        assert_eq!(parsed["hooks"]["userHook"], "something");
        // Our hooks are present.
        assert!(
            parsed["hooks"]["sessionStart"].is_array(),
            "sessionStart hook should be present"
        );
        assert!(
            parsed["hooks"]["preToolUse"].is_array(),
            "preToolUse hook should be present"
        );
        assert_eq!(
            parsed["version"], 1,
            "version: 1 must be set at the top level"
        );
    }

    #[test]
    fn cursor_native_hooks_detection_requires_an_ai_memory_cursor_entry() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("hooks.json");
        assert!(!cursor_native_hooks_installed_in(&path), "missing file");

        fs::write(&path, "not json").unwrap();
        assert!(!cursor_native_hooks_installed_in(&path), "malformed file");

        fs::write(
            &path,
            r#"{"version":1,"hooks":{"sessionStart":[
                {"command":"/opt/third-party","args":["--agent","cursor"]},
                {"command":"/usr/bin/ai-memory","args":["hook","--event","session-start","--agent","claude-code","--server-url","http://h"]}
            ]}}"#,
        )
        .unwrap();
        assert!(
            !cursor_native_hooks_installed_in(&path),
            "third-party or non-cursor entries do not count"
        );

        fs::write(
            &path,
            r#"{"version":1,"hooks":{"stop":[
                {"command":"/usr/bin/ai-memory","args":["hook","--event","stop","--agent","cursor","--server-url","http://h"]}
            ]}}"#,
        )
        .unwrap();
        assert!(cursor_native_hooks_installed_in(&path), "exec form");

        fs::write(
            &path,
            r#"{"version":1,"hooks":{"stop":[
                {"command":"/usr/bin/ai-memory hook --event stop --agent cursor --server-url http://h"}
            ]}}"#,
        )
        .unwrap();
        assert!(
            cursor_native_hooks_installed_in(&path),
            "command-string form"
        );
    }

    #[test]
    fn unrecognized_ai_memory_hook_entries_flags_wrappers_only() {
        let root = serde_json::json!({
            "version": 1,
            "hooks": {
                "sessionStart": [
                    {"command": "/usr/bin/ai-memory", "args": ["hook", "--event", "session-start", "--agent", "cursor", "--server-url", "http://h"]},
                    {"command": "~/bin/ai-memory-cwd-shim.sh session-start"},
                    {"command": "/opt/other-tool --flag"}
                ],
                "stop": [
                    {"matcher": "", "hooks": [{"command": "/home/u/.local/ai_memory_wrap stop"}]}
                ]
            }
        });
        let found = unrecognized_ai_memory_hook_entries(&root);
        assert_eq!(
            found,
            vec![
                (
                    "sessionStart".to_string(),
                    "~/bin/ai-memory-cwd-shim.sh session-start".to_string()
                ),
                (
                    "stop".to_string(),
                    "/home/u/.local/ai_memory_wrap stop".to_string()
                ),
            ]
        );
    }

    #[test]
    fn cursor_apply_is_idempotent() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");

        let first = merge_cursor_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_ne!(
            first,
            ApplyOutcome::NoOp,
            "first apply should not be a no-op"
        );

        let second = merge_cursor_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_eq!(second, ApplyOutcome::NoOp, "second apply must be a no-op");
    }

    // ----------------------------------------------------------------
    // Codex tests
    // ----------------------------------------------------------------

    #[test]
    fn codex_preserves_unrelated_keys_and_adds_hooks() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
                "session-end.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");
        // Pre-existing settings with an unrelated key.
        fs::write(&config_path, r#"{"theme":"dark"}"#).unwrap();

        merge_codex_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
            false,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // Unrelated key survives.
        assert_eq!(parsed["theme"], "dark");
        // Our hooks are present.
        assert!(
            parsed["hooks"]["SessionStart"].is_array(),
            "SessionStart hook should be present"
        );
        assert!(
            parsed["hooks"]["SessionEnd"].is_array(),
            "SessionEnd is wired for Codex since Codex CLI 0.145.0"
        );
    }

    /// #743: with `--capture-assistant`, the Codex Stop command carries the
    /// `--capture-assistant` flag (and only Stop does); without it, no command
    /// does. Mirrors the native-command bake asserted for Claude Code.
    #[test]
    fn codex_bakes_capture_assistant_flag_on_stop_only_when_opted_in() {
        fn stop_and_start_commands(capture: bool) -> (String, String) {
            let hooks_tmp = TempDir::new().unwrap();
            stub_scripts(
                hooks_tmp.path(),
                &[
                    "session-start.sh",
                    "user-prompt-submit.sh",
                    "pre-tool-use.sh",
                    "post-tool-use.sh",
                    "pre-compact.sh",
                    "stop.sh",
                    "session-end.sh",
                ],
            );
            let config_tmp = TempDir::new().unwrap();
            let config_path = config_tmp.path().join("hooks.json");
            merge_codex_hooks(
                hooks_tmp.path(),
                "http://127.0.0.1:49374",
                None,
                config_tmp.path(),
                None,
                &config_path,
                capture,
            )
            .unwrap();
            let parsed: serde_json::Value =
                serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
            let cmd = |event: &str| {
                parsed["hooks"][event][0]["hooks"][0]["command"]
                    .as_str()
                    .unwrap_or_default()
                    .to_string()
            };
            (cmd("Stop"), cmd("SessionStart"))
        }

        let (stop_on, start_on) = stop_and_start_commands(true);
        assert!(
            stop_on.contains("--capture-assistant"),
            "opted-in Codex Stop must bake --capture-assistant: {stop_on}"
        );
        assert!(
            !start_on.contains("--capture-assistant"),
            "only Stop carries the flag, not SessionStart: {start_on}"
        );

        let (stop_off, _) = stop_and_start_commands(false);
        assert!(
            !stop_off.contains("--capture-assistant"),
            "without the opt-in no command carries the flag: {stop_off}"
        );
    }

    #[test]
    fn codex_session_end_preserves_third_party_and_adds_ours() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
                "session-end.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");
        // A third-party SessionEnd hook the user wired up themselves.
        fs::write(
            &config_path,
            r#"{"hooks":{"SessionEnd":[{"matcher":"","hooks":[{"type":"command","command":"user-own.sh"}]}]}}"#,
        )
        .unwrap();

        merge_codex_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
            false,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        let session_end = parsed["hooks"]["SessionEnd"].as_array().unwrap();
        let rendered = serde_json::to_string(&parsed["hooks"]["SessionEnd"]).unwrap();
        // Third-party entry survives.
        assert!(
            rendered.contains("user-own.sh"),
            "third-party SessionEnd entry must survive: {rendered}"
        );
        // Our managed entry was added alongside it.
        assert!(
            rendered.contains("session-end"),
            "ai-memory SessionEnd entry must be added: {rendered}"
        );
        assert_eq!(session_end.len(), 2);
        assert!(parsed["hooks"]["SessionStart"].is_array());
    }

    /// The test-only Codex wrapper must stage scripts under its injected
    /// data-local root and wire that stable path into the generated config.
    #[test]
    fn codex_apply_stages_into_injected_dir() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");
        let staging_tmp = TempDir::new().unwrap();

        apply_to_codex_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            staging_tmp.path(),
            &InstallHooksArgs {
                profile: None,
                agent: AgentChoice::Codex,
                capture_assistant: false,
                no_capture_prompts: false,
                capture_mode: None,
                capture_prompts: false,
                hooks_dir: Some(hooks_tmp.path().to_path_buf()),
                server_url: Some("http://127.0.0.1:49374".to_string()),
                auth_token: None,
                config_file: Some(config_path.clone()),
                scope: HookInstallScope::Global,
                project_strategy: Some(ProjectStrategyArg::Basename),
                as_user: None,
                apply: false,
            },
        )
        .unwrap();

        let staged_script = staging_tmp
            .path()
            .join("hooks")
            .join("codex")
            .join("session-start.sh");
        assert!(
            staged_script.is_file(),
            "expected hook script staged at {}, override was not honoured",
            staged_script.display()
        );

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        let command = parsed
            .pointer("/hooks/SessionStart/0/hooks/0/command")
            .and_then(serde_json::Value::as_str)
            .expect("SessionStart command should be present");
        assert!(
            command.contains(&staged_script.to_string_lossy().into_owned()),
            "generated command must reference staged script {}: {command}",
            staged_script.display()
        );
    }

    // ----------------------------------------------------------------
    // Gemini tests
    // ----------------------------------------------------------------

    #[test]
    fn gemini_preserves_mcp_servers_and_adds_hooks() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("settings.json");
        // Pre-existing settings with an mcpServers entry.
        fs::write(&config_path, r#"{"mcpServers":{"foo":{}}}"#).unwrap();

        merge_gemini_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // The pre-existing mcpServers.foo survives.
        assert!(
            parsed["mcpServers"]["foo"].is_object(),
            "mcpServers.foo must survive"
        );
        // Our hooks are present with Gemini-specific event names.
        assert!(
            parsed["hooks"]["SessionStart"].is_array(),
            "SessionStart hook should be present"
        );
        assert!(
            parsed["hooks"]["BeforeTool"].is_array(),
            "BeforeTool hook should be present"
        );
        // Claude-Code-only events must NOT appear.
        assert!(
            parsed["hooks"].get("PreToolUse").is_none(),
            "PreToolUse must not appear in Gemini config"
        );
    }

    // ----------------------------------------------------------------
    // Antigravity tests
    // ----------------------------------------------------------------

    #[test]
    fn antigravity_preserves_existing_hooks_and_adds_ours() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");
        // Pre-existing settings with another named hook group.
        fs::write(
            &config_path,
            r#"{"my-linter":{"PostToolUse":[{"matcher":"run_command","hooks":[{"type":"command","command":"lint.sh"}]}]}}"#,
        )
        .unwrap();

        merge_antigravity_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // The pre-existing my-linter group survives.
        assert!(
            parsed["my-linter"]["PostToolUse"].is_array(),
            "my-linter.PostToolUse must survive"
        );
        // Our named group "ai-memory" is present.
        assert!(
            parsed["ai-memory"]["PreInvocation"].is_array(),
            "PreInvocation hook should be present"
        );
        assert!(
            parsed["ai-memory"]["PreToolUse"].is_array(),
            "PreToolUse hook should be present"
        );
        assert!(
            parsed["ai-memory"]["PostToolUse"].is_array(),
            "PostToolUse hook should be present"
        );
        assert!(
            parsed["ai-memory"]["Stop"].is_array(),
            "Stop hook should be present"
        );
        assert!(
            parsed["ai-memory"]["SessionStart"].is_array(),
            "SessionStart hook should be present"
        );
    }

    /// An install from before SessionStart was wired ran `session-start` on
    /// PreInvocation. Re-installing moves PreInvocation to its own
    /// `pre-invocation` handler and adds SessionStart, one entry each.
    #[test]
    fn antigravity_reinstall_rewires_pre_invocation_and_adds_session_start() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "pre-invocation.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "stop.sh",
            ],
        );
        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");
        fs::write(
            &config_path,
            serde_json::json!({
                "ai-memory": {
                    "PreInvocation": [{
                        "type": "command",
                        "command": "'/old/bin/ai-memory' hook --event session-start --agent antigravity-cli --server-url 'http://127.0.0.1:49374'"
                    }]
                }
            })
            .to_string(),
        )
        .unwrap();

        merge_antigravity_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        for (event, token) in [
            ("SessionStart", "session-start"),
            ("PreInvocation", "pre-invocation"),
        ] {
            let entries = parsed["ai-memory"][event].as_array().unwrap();
            assert_eq!(entries.len(), 1, "{event}: {entries:?}");
            let command = entries[0]["command"].as_str().unwrap();
            assert!(command.contains(token), "{event}: {command}");
            assert!(!command.contains("/old/bin"), "{event}: {command}");
        }
    }

    #[test]
    fn antigravity_apply_is_idempotent() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.json");

        let first = merge_antigravity_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_ne!(
            first,
            ApplyOutcome::NoOp,
            "first apply should not be a no-op"
        );

        let second = merge_antigravity_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_eq!(second, ApplyOutcome::NoOp, "second apply must be a no-op");
    }

    // ----------------------------------------------------------------
    // Kimi Code tests
    // ----------------------------------------------------------------

    const KIMI_CODE_STUB_SCRIPTS: [&str; 9] = [
        "session-start.sh",
        "user-prompt-submit.sh",
        "pre-tool-use.sh",
        "post-tool-use.sh",
        "pre-compact.sh",
        "stop.sh",
        "session-end.sh",
        "subagent-start.sh",
        "subagent-stop.sh",
    ];

    fn kimi_code_hooks_in(config_path: &Path) -> Vec<(String, String)> {
        let doc: toml_edit::DocumentMut = fs::read_to_string(config_path)
            .unwrap()
            .parse()
            .expect("config.toml must stay valid TOML");
        doc.get("hooks")
            .and_then(toml_edit::Item::as_array_of_tables)
            .expect("`hooks` must be an array of tables")
            .iter()
            .map(|entry| {
                let event = entry
                    .get("event")
                    .and_then(|v| v.as_str())
                    .unwrap_or_default()
                    .to_string();
                let command = entry
                    .get("command")
                    .and_then(|v| v.as_str())
                    .unwrap_or_default()
                    .to_string();
                (event, command)
            })
            .collect()
    }

    #[test]
    fn kimi_code_apply_writes_all_events_into_fresh_config() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(hooks_tmp.path(), &KIMI_CODE_STUB_SCRIPTS);

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("config.toml");

        let outcome = merge_kimi_code_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_eq!(outcome, ApplyOutcome::Created);

        let entries = kimi_code_hooks_in(&config_path);
        assert_eq!(entries.len(), KIMI_CODE_EVENTS.len());
        for (i, (event, script)) in KIMI_CODE_EVENTS.iter().enumerate() {
            assert_eq!(entries[i].0, *event, "entry order follows KIMI_CODE_EVENTS");
            let stem = script.strip_suffix(".sh").unwrap();
            assert!(
                entries[i].1.contains(stem),
                "{event}: command must reference the staged script: {}",
                entries[i].1
            );
        }
        // Only the allowed keys are written — Kimi Code rejects unknown
        // fields by failing the whole config load.
        let doc: toml_edit::DocumentMut =
            fs::read_to_string(&config_path).unwrap().parse().unwrap();
        for entry in doc
            .get("hooks")
            .and_then(toml_edit::Item::as_array_of_tables)
            .unwrap()
        {
            let keys: Vec<&str> = entry.iter().map(|(k, _)| k).collect();
            assert_eq!(keys, ["event", "command"], "only event + command allowed");
        }
    }

    #[test]
    fn kimi_code_apply_preserves_providers_and_third_party_hooks() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(hooks_tmp.path(), &KIMI_CODE_STUB_SCRIPTS);

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("config.toml");
        fs::write(
            &config_path,
            r#"# Kimi Code user config
model = "kimi-k2"

[providers.moonshot]
api_key = "sk-secret"
base_url = "https://api.moonshot.cn/v1"

[[hooks]]
event = "SessionStart"
command = "echo third-party"

[[hooks]]
event = "SessionStart"
command = "/opt/alphaone/bin/ai-memory boot --quiet --limit 10 --budget-tokens 4096"

[[hooks]]
event = "SessionStart"
command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/session-start.sh"
"#,
        )
        .unwrap();

        merge_kimi_code_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();

        let content = fs::read_to_string(&config_path).unwrap();
        assert!(
            content.contains("# Kimi Code user config"),
            "comments survive"
        );
        assert!(
            content.contains(r#"api_key = "sk-secret""#),
            "providers table survives"
        );

        let doc: toml_edit::DocumentMut = content.parse().unwrap();
        assert_eq!(
            doc.get("model").and_then(|v| v.as_str()),
            Some("kimi-k2"),
            "model setting survives"
        );
        assert_eq!(
            doc.get("providers")
                .and_then(|p| p.get("moonshot"))
                .and_then(|m| m.get("base_url"))
                .and_then(|v| v.as_str()),
            Some("https://api.moonshot.cn/v1"),
            "providers.moonshot survives"
        );

        let entries = kimi_code_hooks_in(&config_path);
        // Two third-party entries + our 9: the stale ai-memory entry must be
        // replaced, not duplicated.
        assert_eq!(entries.len(), 2 + KIMI_CODE_EVENTS.len());
        let ours: Vec<&(String, String)> = entries
            .iter()
            .filter(|(_, command)| hook_command_is_ours(command))
            .collect();
        assert_eq!(ours.len(), KIMI_CODE_EVENTS.len(), "no duplicated entries");
        assert!(
            entries
                .iter()
                .any(|(_, command)| command == "echo third-party"),
            "third-party hook survives: {entries:?}"
        );
        assert!(
            entries.iter().any(|(_, command)| {
                command
                    == "/opt/alphaone/bin/ai-memory boot --quiet --limit 10 --budget-tokens 4096"
            }),
            "third-party string hook survives: {entries:?}"
        );
        assert!(
            !entries.iter().any(|(_, command)| command.contains("/old/")),
            "stale ai-memory entry must be replaced: {entries:?}"
        );
    }

    #[test]
    fn kimi_code_apply_is_idempotent() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(hooks_tmp.path(), &KIMI_CODE_STUB_SCRIPTS);

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("config.toml");

        let first = merge_kimi_code_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_ne!(
            first,
            ApplyOutcome::NoOp,
            "first apply should not be a no-op"
        );

        let second = merge_kimi_code_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_eq!(second, ApplyOutcome::NoOp, "second apply must be a no-op");
    }

    #[test]
    fn claude_settings_path_honours_claude_config_dir() {
        let custom = if cfg!(windows) {
            r"C:\custom\claude"
        } else {
            "/custom/claude"
        };
        let path = claude_settings_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(path, Path::new(custom).join("settings.json"));

        // Empty override and unset var both fall back to ~/.claude/settings.json.
        for env in [None, Some(std::ffi::OsString::new())] {
            let path = claude_settings_path_in(env).unwrap();
            assert!(
                path.ends_with(Path::new(".claude").join("settings.json")),
                "default must be ~/.claude/settings.json, got {}",
                path.display()
            );
        }
    }

    /// `CODEX_HOME` relocates Codex's entire config home, so hooks written to
    /// `~/.codex` are never loaded by a Codex configured that way — the install
    /// reports success and capture silently does nothing. ai-memory already
    /// honors the variable when resolving Codex transcripts, so the two halves
    /// of one install have to agree on where that home is.
    #[test]
    fn codex_hooks_path_honours_codex_home() {
        let custom = if cfg!(windows) {
            r"C:\custom\codex"
        } else {
            "/custom/codex"
        };
        let path = codex_hooks_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(path, Path::new(custom).join("hooks.json"));

        // Unset and blank both fall back to ~/.codex/hooks.json. Blank counts as
        // unset because an exported-but-empty variable is nearly always a failed
        // shell expansion, not a request to install into the filesystem root.
        for env in [None, Some(std::ffi::OsString::new())] {
            let path = codex_hooks_path_in(env).unwrap();
            assert!(
                path.ends_with(Path::new(".codex").join("hooks.json")),
                "default must be ~/.codex/hooks.json, got {}",
                path.display()
            );
        }
    }

    /// `COPILOT_HOME` relocates Copilot CLI's config home, hooks included
    /// (`$COPILOT_HOME/hooks/`, per Copilot's hooks reference).
    #[test]
    fn copilot_cli_hooks_path_honours_copilot_home() {
        let custom = if cfg!(windows) {
            r"C:\custom\copilot"
        } else {
            "/custom/copilot"
        };
        let path = copilot_cli_hooks_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(path, Path::new(custom).join("hooks").join("ai-memory.json"));

        for env in [None, Some(std::ffi::OsString::new())] {
            let path = copilot_cli_hooks_path_in(env).unwrap();
            assert!(
                path.ends_with(Path::new(".copilot").join("hooks").join("ai-memory.json")),
                "default must be ~/.copilot/hooks/ai-memory.json, got {}",
                path.display()
            );
        }
    }

    /// The test-only Claude Code wrapper must stage scripts under its injected
    /// data-local root and wire that stable path into the generated config.
    #[test]
    fn claude_code_apply_stages_into_injected_dir() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("settings.json");
        let staging_tmp = TempDir::new().unwrap();

        apply_to_claude_code_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            staging_tmp.path(),
            &InstallHooksArgs {
                profile: None,
                agent: AgentChoice::ClaudeCode,
                capture_assistant: false,
                no_capture_prompts: false,
                capture_mode: None,
                capture_prompts: false,
                hooks_dir: Some(hooks_tmp.path().to_path_buf()),
                server_url: Some("http://127.0.0.1:49374".to_string()),
                auth_token: None,
                config_file: Some(config_path.clone()),
                scope: HookInstallScope::Global,
                project_strategy: Some(ProjectStrategyArg::Basename),
                as_user: None,
                apply: false,
            },
        )
        .unwrap();

        let staged_script = staging_tmp
            .path()
            .join("hooks")
            .join("claude-code")
            .join("session-start.sh");
        assert!(
            staged_script.is_file(),
            "expected hook script staged at {}, override was not honoured",
            staged_script.display()
        );

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        let command = parsed
            .pointer("/hooks/SessionStart/0/hooks/0/command")
            .and_then(serde_json::Value::as_str)
            .expect("SessionStart command should be present");
        assert!(
            command.contains(&staged_script.to_string_lossy().into_owned()),
            "generated command must reference staged script {}: {command}",
            staged_script.display()
        );
        // The failure event shares the post-tool-use handler.
        let failure = parsed
            .pointer("/hooks/PostToolUseFailure/0/hooks/0/command")
            .and_then(serde_json::Value::as_str)
            .expect("PostToolUseFailure command should be present");
        assert_eq!(
            Some(failure),
            parsed
                .pointer("/hooks/PostToolUse/0/hooks/0/command")
                .and_then(serde_json::Value::as_str)
        );
    }

    #[test]
    fn claude_prompt_opt_out_survives_reapply_and_preserves_third_party_hook() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "pre-compact.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("settings.json");
        let staging_tmp = TempDir::new().unwrap();
        fs::write(
            &config_path,
            serde_json::json!({
                "hooks": {
                    "UserPromptSubmit": [
                        { "hooks": [{ "command": "third-party prompt guard" }] },
                        { "hooks": [{ "command": "/old/ai-memory hook --event user-prompt --agent claude-code --server-url http://old" }] }
                    ]
                }
            })
            .to_string(),
        )
        .unwrap();

        let disabled = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            config_file: Some(config_path.clone()),
            no_capture_prompts: true,
            capture_mode: None,
            ..default_hook_args()
        };
        apply_to_claude_code_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            staging_tmp.path(),
            &disabled,
        )
        .unwrap();

        let assert_disabled = || {
            let parsed: serde_json::Value =
                serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
            let prompts = parsed["hooks"][CLAUDE_PROMPT_EVENT]
                .as_array()
                .expect("third-party prompt hook keeps the event present");
            assert_eq!(prompts.len(), 1);
            assert!(
                serde_json::to_string(prompts)
                    .unwrap()
                    .contains("third-party prompt guard")
            );
            assert!(!prompts.iter().any(is_ai_memory_hook_entry));
        };
        assert_disabled();

        let bare_reapply = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            config_file: Some(config_path.clone()),
            ..default_hook_args()
        };
        apply_to_claude_code_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            staging_tmp.path(),
            &bare_reapply,
        )
        .unwrap();
        assert_disabled();

        let enabled = InstallHooksArgs {
            agent: AgentChoice::ClaudeCode,
            config_file: Some(config_path.clone()),
            capture_prompts: true,
            ..default_hook_args()
        };
        apply_to_claude_code_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            staging_tmp.path(),
            &enabled,
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        let prompts = parsed["hooks"][CLAUDE_PROMPT_EVENT].as_array().unwrap();
        assert_eq!(prompts.len(), 2, "third-party + one ai-memory hook");
        assert_eq!(
            prompts
                .iter()
                .filter(|entry| is_ai_memory_hook_entry(entry))
                .count(),
            1
        );
    }

    #[test]
    fn kimi_code_config_path_honours_kimi_code_home() {
        let custom = if cfg!(windows) {
            r"C:\custom\kimi"
        } else {
            "/custom/kimi"
        };
        let path = kimi_code_config_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(path, Path::new(custom).join("config.toml"));

        // Empty override and unset var both fall back to ~/.kimi-code.
        for env in [None, Some(std::ffi::OsString::new())] {
            let path = kimi_code_config_path_in(env).unwrap();
            assert!(
                path.ends_with(Path::new(".kimi-code").join("config.toml")),
                "default must be ~/.kimi-code/config.toml, got {}",
                path.display()
            );
        }
    }

    // ----------------------------------------------------------------
    // Kiro CLI v2 agent-config hook tests.
    // ----------------------------------------------------------------

    const KIRO_CLI_STUB_SCRIPTS: [&str; 5] = [
        "session-start.sh",
        "user-prompt-submit.sh",
        "pre-tool-use.sh",
        "post-tool-use.sh",
        "stop.sh",
    ];

    #[test]
    fn kiro_cli_apply_writes_all_v2_events_into_agent_config() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(hooks_tmp.path(), &KIRO_CLI_STUB_SCRIPTS);

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("dev.json");
        fs::write(
            &config_path,
            r#"{"name": "dev", "description": "my agent", "tools": ["*"]}"#,
        )
        .unwrap();

        let outcome = merge_kiro_cli_agent_hooks(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            None,
            &config_path,
        )
        .unwrap();
        assert_eq!(outcome, ApplyOutcome::Updated);

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // Non-hook agent fields survive the merge.
        assert_eq!(root["name"], "dev");
        assert_eq!(root["tools"][0], "*");
        let hooks = root["hooks"].as_object().expect("hooks object");
        assert_eq!(hooks.len(), KIRO_CLI_V2_EVENTS.len());
        for (event, script) in KIRO_CLI_V2_EVENTS {
            let entries = hooks[event].as_array().expect("event array");
            assert_eq!(entries.len(), 1, "{event}");
            let entry = entries[0].as_object().expect("entry object");
            let command = entry["command"].as_str().unwrap();
            let stem = script.strip_suffix(".sh").unwrap();
            assert!(
                command.contains(stem),
                "{event}: command must reference the staged script: {command}"
            );
            // The v2 Hook schema has no `type` field, and an empty-string
            // matcher would match no tool at all (absent = every tool), so
            // neither key may be written.
            assert!(!entry.contains_key("type"), "{event}: no type key");
            assert!(!entry.contains_key("matcher"), "{event}: no matcher key");
            if event == "agentSpawn" {
                // The handoff + brief must not be truncated mid-injection.
                assert_eq!(
                    entry["max_output_size"],
                    serde_json::json!(KIRO_CLI_V2_SESSION_START_MAX_OUTPUT)
                );
            } else {
                assert!(!entry.contains_key("max_output_size"), "{event}");
            }
        }
    }

    #[test]
    fn kiro_cli_apply_preserves_third_party_hooks_and_is_idempotent() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(hooks_tmp.path(), &KIRO_CLI_STUB_SCRIPTS);

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("dev.json");
        fs::write(
            &config_path,
            r#"{
  "name": "dev",
  "hooks": {
    "agentSpawn": [
      {"command": "git status"},
      {"command": "echo ai-memory status"},
      {"command": "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kiro-cli/session-start.sh"}
    ],
    "preToolUse": [
      {"matcher": "execute_bash", "command": "echo audit >> /tmp/audit.log"}
    ]
  }
}"#,
        )
        .unwrap();

        let apply = || {
            merge_kiro_cli_agent_hooks(
                hooks_tmp.path(),
                "http://127.0.0.1:49374",
                None,
                config_tmp.path(),
                None,
                &config_path,
            )
        };
        assert_eq!(apply().unwrap(), ApplyOutcome::Updated);

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        let spawn = root["hooks"]["agentSpawn"].as_array().unwrap();
        // Third-party entry first (preserved), our refreshed entry after;
        // the stale ai-memory entry is gone.
        assert_eq!(spawn.len(), 3);
        assert_eq!(spawn[0]["command"], "git status");
        assert_eq!(spawn[1]["command"], "echo ai-memory status");
        let ours = spawn[2]["command"].as_str().unwrap();
        assert!(ours.contains("session-start"), "{ours}");
        assert!(
            !ours.contains("http://old:1"),
            "stale entry replaced: {ours}"
        );
        // A third-party hook under a trigger we also write survives with
        // its matcher intact.
        let pre = root["hooks"]["preToolUse"].as_array().unwrap();
        assert_eq!(pre.len(), 2);
        assert_eq!(pre[0]["matcher"], "execute_bash");

        // Second apply with identical inputs must be a no-op.
        assert_eq!(apply().unwrap(), ApplyOutcome::NoOp);
    }

    #[test]
    fn kiro_cli_paths_honour_kiro_home() {
        let custom = if cfg!(windows) {
            r"C:\custom\kiro"
        } else {
            "/custom/kiro"
        };
        let agents = kiro_cli_home_join(Some(std::ffi::OsString::from(custom)), "agents").unwrap();
        assert_eq!(agents, Path::new(custom).join("agents"));
        let hooks = kiro_cli_home_join(Some(std::ffi::OsString::from(custom)), "hooks")
            .unwrap()
            .join("ai-memory.json");
        assert_eq!(hooks, Path::new(custom).join("hooks/ai-memory.json"));

        // Empty override and unset var both fall back to ~/.kiro.
        for env in [None, Some(std::ffi::OsString::new())] {
            let agents = kiro_cli_home_join(env.clone(), "agents").unwrap();
            assert!(
                agents.ends_with(Path::new(".kiro").join("agents")),
                "default must be ~/.kiro/agents, got {}",
                agents.display()
            );
        }
    }

    #[test]
    fn kiro_hooks_infer_the_managed_mcp_client() {
        assert_eq!(
            mcp_client_for_agent(AgentChoice::KiroCli),
            Some(McpClient::KiroCli)
        );
        assert_eq!(
            mcp_client_for_agent(AgentChoice::KiroCliV3),
            Some(McpClient::KiroCli)
        );
    }

    /// `install-hooks --agent copilot-cli` without `--server-url` reads the
    /// server URL and bearer back from an earlier `install-mcp --client
    /// copilot-cli`, the same root `mcpServers.ai-memory.url` entry it wrote.
    #[test]
    fn copilot_cli_hooks_infer_the_copilot_cli_mcp_client() {
        assert_eq!(
            mcp_client_for_agent(AgentChoice::CopilotCli),
            Some(McpClient::CopilotCli)
        );
        let inferred = infer_json_mcp_config(
            r#"{"mcpServers":{"ai-memory":{"type":"http","url":"https://memory.example/mcp","headers":{"Authorization":"Bearer tok"},"tools":["*"]}}}"#,
            &["mcpServers", "ai-memory"],
            "url",
        )
        .unwrap();
        assert_eq!(
            inferred.hook_server_url.as_deref(),
            Some("https://memory.example")
        );
        assert_eq!(inferred.auth_token.as_deref(), Some("tok"));
    }

    #[test]
    fn kiro_cli_v3_apply_writes_documented_schema_and_is_idempotent() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(hooks_tmp.path(), &KIRO_CLI_STUB_SCRIPTS);
        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks/ai-memory.json");

        let apply = || {
            merge_kiro_cli_v3_hooks(
                hooks_tmp.path(),
                "https://memory.example",
                Some("test-token"),
                config_tmp.path(),
                Some("repo-root"),
                &config_path,
            )
        };
        assert_eq!(apply().unwrap(), ApplyOutcome::Created);

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        assert_eq!(root["version"], "v1");
        let hooks = root["hooks"].as_array().expect("hooks array");
        assert_eq!(hooks.len(), KIRO_CLI_V3_EVENTS.len());
        for ((trigger, script), entry) in KIRO_CLI_V3_EVENTS.iter().zip(hooks) {
            assert_eq!(entry["trigger"], *trigger);
            assert_eq!(entry["action"]["type"], "command");
            assert_eq!(
                entry["timeout"],
                if *trigger == "SessionStart" { 5 } else { 1 }
            );
            assert_eq!(entry["enabled"], true);
            assert_eq!(
                entry["name"],
                format!("ai-memory-{}", script.trim_end_matches(".sh"))
            );
            let command = entry["action"]["command"].as_str().unwrap();
            assert!(is_ai_memory_kiro_hook_command(command), "{command}");
            assert!(command.contains("test-token"), "{command}");
            assert!(command.contains("repo-root"), "{command}");
            assert!(entry.get("matcher").is_none());
        }
        assert_eq!(apply().unwrap(), ApplyOutcome::NoOp);
    }

    #[test]
    fn kiro_cli_v3_apply_preserves_third_party_hooks_and_replaces_only_ours() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("ai-memory.json");
        fs::write(
            &config_path,
            r#"{
  "version": "v1",
  "owner": "user",
  "hooks": [
    {"name":"audit","trigger":"PreToolUse","action":{"type":"command","command":"audit-tool"}},
    {"name":"ai-memory-session-start","trigger":"SessionStart","action":{"type":"command","command":"AI_MEMORY_HOOK_URL=http://old /old/hooks/kiro-cli/session-start.sh"}}
  ]
}"#,
        )
        .unwrap();

        assert_eq!(
            merge_kiro_cli_v3_hooks(
                tmp.path(),
                "https://memory.example",
                None,
                tmp.path(),
                None,
                &config_path,
            )
            .unwrap(),
            ApplyOutcome::Updated
        );
        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        assert_eq!(root["owner"], "user");
        let hooks = root["hooks"].as_array().unwrap();
        assert_eq!(hooks.len(), 1 + KIRO_CLI_V3_EVENTS.len());
        assert_eq!(hooks[0]["name"], "audit");
        assert!(hooks[1..].iter().all(is_ai_memory_kiro_v3_hook_entry));
    }

    #[test]
    fn kiro_cli_v3_apply_rejects_incompatible_schema_and_reserved_collision() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("ai-memory.json");
        fs::write(&config_path, r#"{"version":"v2","hooks":[]}"#).unwrap();
        let error = merge_kiro_cli_v3_hooks(
            tmp.path(),
            "https://memory.example",
            None,
            tmp.path(),
            None,
            &config_path,
        )
        .unwrap_err();
        assert!(format!("{error:#}").contains("unsupported Kiro hook schema version"));

        fs::write(
            &config_path,
            r#"{"version":"v1","hooks":[{"name":"ai-memory-stop","trigger":"Stop","action":{"type":"command","command":"third-party"}}]}"#,
        )
        .unwrap();
        let error = merge_kiro_cli_v3_hooks(
            tmp.path(),
            "https://memory.example",
            None,
            tmp.path(),
            None,
            &config_path,
        )
        .unwrap_err();
        assert!(format!("{error:#}").contains("reserved name"));
    }

    #[test]
    fn kiro_cli_agent_config_listing_is_sorted_json_only() {
        let tmp = TempDir::new().unwrap();
        fs::write(tmp.path().join("b.json"), "{}").unwrap();
        fs::write(tmp.path().join("a.json"), "{}").unwrap();
        fs::write(tmp.path().join("notes.md"), "not an agent").unwrap();
        fs::create_dir(tmp.path().join("sub.json")).unwrap();

        let listed = list_kiro_cli_agent_configs(tmp.path()).unwrap();
        assert_eq!(
            listed,
            vec![tmp.path().join("a.json"), tmp.path().join("b.json")]
        );

        // A missing directory is an empty list, not an error.
        assert!(
            list_kiro_cli_agent_configs(&tmp.path().join("missing"))
                .unwrap()
                .is_empty()
        );

        let not_a_directory = tmp.path().join("agents.json");
        fs::write(&not_a_directory, "{}").unwrap();
        let error = list_kiro_cli_agent_configs(&not_a_directory).unwrap_err();
        assert!(
            format!("{error:#}").contains("reading"),
            "filesystem failures must not look like an empty agent directory: {error:#}"
        );
    }

    #[test]
    fn kiro_cli_v2_preflight_is_all_or_nothing_and_preserves_per_agent_strategy() {
        let tmp = TempDir::new().unwrap();
        let repo_root = tmp.path().join("a.json");
        let basename = tmp.path().join("b.json");
        // Script-form hooks always include the URL marker; the project strategy
        // is an additional setting, not the ownership signature.
        fs::write(
            &repo_root,
            r#"{"name":"a","hooks":{"agentSpawn":[{"command":"AI_MEMORY_HOOK_URL=http://old:1 AI_MEMORY_PROJECT_STRATEGY=repo-root /old/hooks/kiro-cli/session-start.sh"}]}}"#,
        )
        .unwrap();
        fs::write(&basename, r#"{"name":"b"}"#).unwrap();

        let prepared = preflight_kiro_cli_agent_configs(
            vec![repo_root.clone(), basename.clone()],
            tmp.path(),
            "http://127.0.0.1:49374",
            None,
            tmp.path(),
            None,
        )
        .unwrap();
        assert_eq!(prepared[0].1, Some(ProjectStrategyArg::RepoRoot));
        assert_eq!(prepared[1].1, None);

        let before = fs::read_to_string(&repo_root).unwrap();
        fs::write(&basename, "{not-json").unwrap();
        let error = preflight_kiro_cli_agent_configs(
            vec![repo_root.clone(), basename],
            tmp.path(),
            "http://127.0.0.1:49374",
            None,
            tmp.path(),
            None,
        )
        .unwrap_err();
        assert!(format!("{error:#}").contains("valid JSON"));
        assert_eq!(
            fs::read_to_string(repo_root).unwrap(),
            before,
            "a malformed later config must not mutate an earlier agent"
        );
    }

    // ----------------------------------------------------------------
    // Devin tests
    // ----------------------------------------------------------------

    #[test]
    fn devin_apply_writes_hooks_v1_json_by_default() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "post-compaction.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.v1.json");

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            config_tmp.path(),
            &InstallHooksArgs {
                profile: None,
                agent: AgentChoice::Devin,
                capture_assistant: false,
                no_capture_prompts: false,
                capture_mode: None,
                capture_prompts: false,
                hooks_dir: Some(hooks_tmp.path().to_path_buf()),
                server_url: Some("http://127.0.0.1:49374".to_string()),
                auth_token: None,
                config_file: Some(config_path.clone()),
                scope: HookInstallScope::Global,
                project_strategy: Some(crate::cli::ProjectStrategyArg::Basename),
                as_user: None,
                apply: false,
            },
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // hooks.v1.json: the entire file IS the hooks object (no wrapper)
        assert!(
            parsed["SessionStart"].is_array(),
            "SessionStart hook should be present"
        );
        assert!(
            parsed["PostCompaction"].is_array(),
            "PostCompaction hook should be present"
        );
        assert!(
            parsed.get("hooks").is_none(),
            "hooks.v1.json should not have a 'hooks' wrapper"
        );
    }

    #[test]
    fn devin_apply_config_json_hooks_key_via_flag() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "post-compaction.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("config.json");

        // Pre-existing config.json with mcpServers
        fs::write(
            &config_path,
            r#"{"mcpServers":{"other-server":{"url":"http://example.com"}}}"#,
        )
        .unwrap();

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            config_tmp.path(),
            &InstallHooksArgs {
                profile: None,
                agent: AgentChoice::Devin,
                capture_assistant: false,
                no_capture_prompts: false,
                capture_mode: None,
                capture_prompts: false,
                hooks_dir: Some(hooks_tmp.path().to_path_buf()),
                server_url: Some("http://127.0.0.1:49374".to_string()),
                auth_token: None,
                config_file: Some(config_path.clone()),
                scope: HookInstallScope::Global,
                project_strategy: Some(crate::cli::ProjectStrategyArg::Basename),
                as_user: None,
                apply: false,
            },
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // config.json: hooks are nested under the "hooks" key
        assert!(
            parsed["hooks"]["SessionStart"].is_array(),
            "SessionStart hook should be present"
        );
        assert!(
            parsed["hooks"]["PostCompaction"].is_array(),
            "PostCompaction hook should be present"
        );
        // mcpServers should be preserved
        assert!(
            parsed["mcpServers"]["other-server"].is_object(),
            "mcpServers should be preserved"
        );
    }

    #[test]
    fn devin_apply_both_targets_are_idempotent() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "session-end.sh",
                "user-prompt-submit.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "post-compaction.sh",
                "stop.sh",
            ],
        );

        // Test hooks.v1.json idempotency
        let config_tmp = TempDir::new().unwrap();
        let hooks_v1_path = config_tmp.path().join("hooks.v1.json");

        let args_v1 = InstallHooksArgs {
            profile: None,
            agent: AgentChoice::Devin,
            capture_assistant: false,
            no_capture_prompts: false,
            capture_mode: None,
            capture_prompts: false,
            hooks_dir: Some(hooks_tmp.path().to_path_buf()),
            server_url: Some("http://127.0.0.1:49374".to_string()),
            auth_token: None,
            config_file: Some(hooks_v1_path.clone()),
            scope: HookInstallScope::Global,
            project_strategy: Some(crate::cli::ProjectStrategyArg::Basename),
            as_user: None,
            apply: false,
        };

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            config_tmp.path(),
            &args_v1,
        )
        .unwrap();

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            config_tmp.path(),
            &args_v1,
        )
        .unwrap();

        // Idempotency check: second apply should be a no-op
        let v1_first_content = fs::read_to_string(&hooks_v1_path).unwrap();
        let v1_second_content = fs::read_to_string(&hooks_v1_path).unwrap();
        assert_eq!(
            v1_first_content, v1_second_content,
            "hooks.v1.json should be unchanged after second apply"
        );

        // Test config.json hooks key idempotency
        let config_tmp2 = TempDir::new().unwrap();
        let config_path = config_tmp2.path().join("config.json");
        fs::write(&config_path, "{}").unwrap();

        let args_config = InstallHooksArgs {
            profile: None,
            agent: AgentChoice::Devin,
            capture_assistant: false,
            no_capture_prompts: false,
            capture_mode: None,
            capture_prompts: false,
            hooks_dir: Some(hooks_tmp.path().to_path_buf()),
            server_url: Some("http://127.0.0.1:49374".to_string()),
            auth_token: None,
            config_file: Some(config_path.clone()),
            scope: HookInstallScope::Global,
            project_strategy: Some(crate::cli::ProjectStrategyArg::Basename),
            as_user: None,
            apply: false,
        };

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp2.path(),
            config_tmp2.path(),
            &args_config,
        )
        .unwrap();

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp2.path(),
            config_tmp2.path(),
            &args_config,
        )
        .unwrap();

        // Idempotency check: second apply should be a no-op
        let config_first_content = fs::read_to_string(&config_path).unwrap();
        let config_second_content = fs::read_to_string(&config_path).unwrap();
        assert_eq!(
            config_first_content, config_second_content,
            "config.json should be unchanged after second apply"
        );
    }

    #[test]
    fn devin_preserves_existing_hooks_and_adds_ours() {
        let hooks_tmp = TempDir::new().unwrap();
        stub_scripts(
            hooks_tmp.path(),
            &[
                "session-start.sh",
                "pre-tool-use.sh",
                "post-tool-use.sh",
                "post-compaction.sh",
                "stop.sh",
            ],
        );

        let config_tmp = TempDir::new().unwrap();
        let config_path = config_tmp.path().join("hooks.v1.json");
        // Pre-existing settings with another named hook group.
        fs::write(
            &config_path,
            r#"{"my-linter":{"PostToolUse":[{"matcher":"run_command","hooks":[{"type":"command","command":"lint.sh"}]}]}}"#,
        )
        .unwrap();

        apply_to_devin_settings_in(
            hooks_tmp.path(),
            "http://127.0.0.1:49374",
            None,
            config_tmp.path(),
            config_tmp.path(),
            &InstallHooksArgs {
                profile: None,
                agent: AgentChoice::Devin,
                capture_assistant: false,
                no_capture_prompts: false,
                capture_mode: None,
                capture_prompts: false,
                hooks_dir: Some(hooks_tmp.path().to_path_buf()),
                server_url: Some("http://127.0.0.1:49374".to_string()),
                auth_token: None,
                config_file: Some(config_path.clone()),
                scope: HookInstallScope::Global,
                project_strategy: Some(crate::cli::ProjectStrategyArg::Basename),
                as_user: None,
                apply: false,
            },
        )
        .unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // The pre-existing my-linter group survives.
        assert!(
            parsed["my-linter"]["PostToolUse"].is_array(),
            "my-linter.PostToolUse must survive"
        );
        // Our hooks are present at the top level (hooks.v1.json format).
        assert!(
            parsed["SessionStart"].is_array(),
            "SessionStart hook should be present"
        );
        assert!(
            parsed["PostCompaction"].is_array(),
            "PostCompaction hook should be present"
        );
        assert!(
            parsed["PostToolUse"].is_array(),
            "PostToolUse hook should be present"
        );
    }

    #[test]
    fn devin_session_start_injects_handoff_additional_context() {
        let hooks_root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("hooks");
        let devin_session_start = hooks_root.join("devin").join("session-start.sh");

        // Normalized because this is the only assertion below that spans a
        // line break: on a Windows checkout with core.autocrlf=true the
        // working-tree copy has CRLF even though the committed blob is
        // LF-only, which breaks an exact multi-line substring match.
        let script_content = fs::read_to_string(&devin_session_start)
            .unwrap()
            .replace("\r\n", "\n");
        // Verify the script injects handoff via hookSpecificOutput.additionalContext
        assert!(
            script_content.contains("hookSpecificOutput"),
            "Devin session-start.sh must inject handoff via hookSpecificOutput"
        );
        assert!(
            script_content.contains("additionalContext"),
            "Devin session-start.sh must use additionalContext field"
        );
        assert!(
            script_content.contains("ai_memory_get_handoff"),
            "Devin session-start.sh must fetch handoff"
        );
        assert!(
            script_content.contains("$SERVER/handoff?agent=devin${QS}${SID_QS}"),
            "Devin session-start.sh must bind the handoff claim to its generated session id"
        );
        assert!(
            !script_content.contains("/handoff/latest"),
            "Devin session-start.sh must not call the removed /handoff/latest route"
        );
        assert!(
            script_content.contains("ai_memory_json_string"),
            "Devin session-start.sh must JSON-escape handoff text before embedding it"
        );
        assert!(
            script_content.contains("else\n    printf '{}\\n'\nfi"),
            "Devin session-start.sh must print {{}} only when no handoff is available"
        );
    }

    #[test]
    fn startup_handoff_scripts_forward_native_session_ids() {
        let hooks_root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("..")
            .join("..")
            .join("hooks");
        for agent in ["claude-code", "codex", "opencode", "cursor", "gemini-cli"] {
            let script = fs::read_to_string(hooks_root.join(agent).join("session-start.sh"))
                .unwrap()
                .replace("\r\n", "\n");
            assert!(
                script.contains("SESSION_ID=$(ai_memory_extract_session_id \"$PAYLOAD\")"),
                "{agent} must extract the native receiver session id"
            );
            assert!(
                script.contains("${SESSION_QS}"),
                "{agent} must forward the native receiver session id to /handoff"
            );
        }
    }

    #[test]
    fn grok_placeholder_expansion_resolves_values_and_defaults() {
        let expanded = expand_grok_placeholders_with("${HOST}/mcp ${TOKEN:-fallback}", |name| {
            (name == "HOST").then(|| "https://memory.example".to_string())
        })
        .unwrap();
        assert_eq!(expanded, "https://memory.example/mcp fallback");
    }

    #[test]
    fn grok_placeholder_expansion_rejects_missing_variable() {
        let err = expand_grok_placeholders_with("${MISSING}", |_| None).unwrap_err();
        assert!(
            err.to_string()
                .contains("pass explicit --server-url and --auth-token")
        );
    }

    #[test]
    fn grok_project_overlays_cover_repo_root_through_cwd() {
        let temp = tempfile::tempdir().unwrap();
        let root = temp.path().join("repo");
        let parent = root.join("nested");
        let cwd = parent.join("leaf");
        fs::create_dir_all(&cwd).unwrap();
        let user_config = temp.path().join("grok-home/config.toml");

        for directory in [&root, &parent, &cwd] {
            let overlay = directory.join(".grok/config.toml");
            fs::create_dir_all(overlay.parent().unwrap()).unwrap();
            fs::write(&overlay, "# override").unwrap();
            assert_eq!(
                find_grok_project_overlay(&cwd, Some(&root), &user_config),
                Some(overlay)
            );
            fs::remove_file(directory.join(".grok/config.toml")).unwrap();
        }
        assert_eq!(
            find_grok_project_overlay(&cwd, Some(&root), &user_config),
            None
        );
    }

    #[test]
    fn grok_project_overlay_outside_repo_checks_only_cwd() {
        let temp = tempfile::tempdir().unwrap();
        let cwd = temp.path().join("outside").join("leaf");
        fs::create_dir_all(&cwd).unwrap();
        let user_config = temp.path().join("grok-home/config.toml");
        let parent_overlay = cwd.parent().unwrap().join(".grok/config.toml");
        fs::create_dir_all(parent_overlay.parent().unwrap()).unwrap();
        fs::write(&parent_overlay, "# ignored").unwrap();
        assert_eq!(find_grok_project_overlay(&cwd, None, &user_config), None);

        let cwd_overlay = cwd.join(".grok/config.toml");
        fs::create_dir_all(cwd_overlay.parent().unwrap()).unwrap();
        fs::write(&cwd_overlay, "# active").unwrap();
        assert_eq!(
            find_grok_project_overlay(&cwd, None, &user_config),
            Some(cwd_overlay)
        );
    }

    /// From `$HOME` with the default `GROK_HOME`, the only `.grok/config.toml`
    /// on the walk is the user config, which Grok does not read as a project
    /// layer, so there is nothing to refuse.
    #[test]
    fn grok_user_config_reached_from_home_is_not_a_project_overlay() {
        let temp = tempfile::tempdir().unwrap();
        let home = temp.path().join("home");
        let user_config = home.join(".grok/config.toml");
        fs::create_dir_all(user_config.parent().unwrap()).unwrap();
        fs::write(&user_config, "# user").unwrap();

        assert_eq!(find_grok_project_overlay(&home, None, &user_config), None);
        // Through a symlinked home it is still the same file.
        #[cfg(unix)]
        {
            let link = temp.path().join("home-link");
            std::os::unix::fs::symlink(&home, &link).unwrap();
            assert_eq!(find_grok_project_overlay(&link, None, &user_config), None);
        }
    }

    /// Control: with `GROK_HOME` pointing elsewhere, `~/.grok/config.toml` is
    /// a project layer to Grok, so reaching it from `$HOME` must still refuse.
    #[test]
    fn grok_config_under_home_is_an_overlay_when_grok_home_is_elsewhere() {
        let temp = tempfile::tempdir().unwrap();
        let home = temp.path().join("home");
        let overlay = home.join(".grok/config.toml");
        fs::create_dir_all(overlay.parent().unwrap()).unwrap();
        fs::write(&overlay, "# project").unwrap();
        let user_config = temp.path().join("custom-grok-home/config.toml");
        fs::create_dir_all(user_config.parent().unwrap()).unwrap();
        fs::write(&user_config, "# user").unwrap();

        assert_eq!(
            find_grok_project_overlay(&home, None, &user_config),
            Some(overlay)
        );
    }
}

/// The four clients that normalise a git remote into a repository identity
/// (#708) must agree on every case, or one repository lands in two projects
/// depending on which harness captured it. The Rust core is the reference and
/// checks itself against `remote_identity_cases.json`; these run the same
/// cases through the shell, PowerShell and TypeScript ports. Each port is
/// skipped when its interpreter is not installed, so the check never fails for
/// a missing tool — CI runs it wherever the tool exists.
#[cfg(test)]
mod identity_parity_tests {
    use std::path::PathBuf;
    use std::process::Command;

    const CASES: &str = include_str!("../../../ai-memory-core/fixtures/remote_identity_cases.json");

    fn cases() -> Vec<(String, Option<String>)> {
        let cases: serde_json::Value = serde_json::from_str(CASES).unwrap();
        cases["normalize"]
            .as_array()
            .unwrap()
            .iter()
            .map(|case| {
                (
                    case["url"].as_str().unwrap().to_owned(),
                    case["identity"].as_str().map(str::to_owned),
                )
            })
            .collect()
    }

    /// The `identity_style` fixture: each marker value and the explicit value
    /// every client forwards for it (#1033).
    fn style_cases() -> Vec<(String, Option<String>)> {
        let cases: serde_json::Value = serde_json::from_str(CASES).unwrap();
        cases["identity_style"]
            .as_array()
            .unwrap()
            .iter()
            .map(|case| {
                (
                    case["value"].as_str().unwrap().to_owned(),
                    Some(case["style"].as_str().unwrap_or("path").to_owned()),
                )
            })
            .collect()
    }

    fn home_route_cases() -> Vec<serde_json::Value> {
        let cases: serde_json::Value = serde_json::from_str(include_str!(
            "../../../ai-memory-core/fixtures/home_route_cases.json"
        ))
        .unwrap();
        cases["cases"].as_array().unwrap().clone()
    }

    fn expanded_route_case(case: &serde_json::Value, home: &std::path::Path) -> (String, String) {
        let text = match case["generate"].as_str() {
            Some("65_routes") => (0..65)
                .map(|index| format!("[routes.path.\"/route/{index}\"]\nroute_workspace=\"ws\"\nroute_project=\"p{index}\"\n"))
                .collect(),
            Some("selector_512") => format!(
                "[routes.path.\"/{}\"]\nroute_workspace=\"bounds\"\nroute_project=\"valid\"\n",
                "a".repeat(511)
            ),
            Some("selector_513") => format!(
                "[routes.path.\"/{}\"]\nroute_workspace=\"bounds\"\nroute_project=\"invalid\"\n",
                "a".repeat(512)
            ),
            Some("oversized_file") => format!("#{}\n", "x".repeat(65_536)),
            Some(other) => panic!("unknown route fixture generator {other}"),
            None => case["toml"]
                .as_str()
                .unwrap()
                .replace("{{HOME}}", home.to_str().unwrap())
                .replace("{{LONG_513}}", &"a".repeat(513)),
        };
        let cwd = match case["cwd_generate"].as_str() {
            Some("selector_512_child") => format!("/{}/child", "a".repeat(511)),
            Some(other) => panic!("unknown cwd fixture generator {other}"),
            None => case["cwd"]
                .as_str()
                .unwrap()
                .replace("{{HOME}}", home.to_str().unwrap()),
        };
        (text, cwd)
    }

    fn alias_cases() -> Vec<(String, Option<String>)> {
        let cases: serde_json::Value = serde_json::from_str(CASES).unwrap();
        cases["marker_aliases"]
            .as_array()
            .unwrap()
            .iter()
            .map(|case| {
                (
                    case["toml"].as_str().unwrap().to_owned(),
                    match case["status"].as_str().unwrap() {
                        "valid" => case["aliases"].as_array().and_then(|aliases| {
                            (!aliases.is_empty()).then(|| serde_json::to_string(aliases).unwrap())
                        }),
                        "absent" => None,
                        "invalid" => Some("invalid".to_owned()),
                        status => panic!("unknown fixture status {status}"),
                    },
                )
            })
            .collect()
    }

    fn assert_aliases_agree(port: &str, lines: &str) {
        let got: Vec<&str> = lines.split('\n').collect();
        for (index, (toml, expected)) in alias_cases().iter().enumerate() {
            let got = got
                .get(index)
                .copied()
                .unwrap_or("<missing>")
                .trim_end_matches('\r');
            assert_eq!(got, expected.as_deref().unwrap_or(""), "{port}: {toml}");
        }
    }

    /// Compare one port's forwarding decisions, one line per style case.
    fn assert_styles_agree(port: &str, lines: &str) {
        let got: Vec<&str> = lines.split('\n').collect();
        for (i, (value, style)) in style_cases().iter().enumerate() {
            let got = got
                .get(i)
                .copied()
                .unwrap_or("<missing>")
                .trim_end_matches('\r');
            let expected = style
                .as_deref()
                .map_or_else(String::new, |style| format!("&identity_style={style}"));
            assert_eq!(got, expected, "{port} forwarded {value:?} differently");
        }
    }

    fn repo_file(relative: &str) -> PathBuf {
        PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("../..")
            .join(relative)
    }

    /// Compare one port's output, one line per case, with the fixture.
    fn assert_agrees(port: &str, stdout: &[u8]) {
        let text = String::from_utf8_lossy(stdout);
        let got: Vec<&str> = text.split('\n').collect();
        let cases = cases();
        for (i, (url, expected)) in cases.iter().enumerate() {
            let got = got
                .get(i)
                .copied()
                .unwrap_or("<missing>")
                .trim_end_matches('\r');
            assert_eq!(
                got,
                expected.as_deref().unwrap_or(""),
                "{port} normalised {url:?} differently from the core"
            );
        }
    }

    #[test]
    fn the_shell_port_agrees_with_the_core() {
        if Command::new("sh").arg("-c").arg("true").status().is_err() {
            return;
        }
        let output = Command::new("sh")
            .arg("-c")
            .arg(r#". "$1"; shift; for u in "$@"; do printf '%s\n' "$(ai_memory_normalize_remote "$u")"; done"#)
            .arg("sh")
            .arg(repo_file("hooks/_lib.sh"))
            .args(cases().into_iter().map(|(url, _)| url))
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        assert_agrees("hooks/_lib.sh", &output.stdout);

        let output = Command::new("sh")
            .arg("-c")
            .arg(r#". "$1"; shift; for v in "$@"; do printf '%s\n' "$(ai_memory_identity_style_qs "$v")"; done"#)
            .arg("sh")
            .arg(repo_file("hooks/_lib.sh"))
            .args(style_cases().into_iter().map(|(value, _)| value))
            .output()
            .unwrap();
        assert!(output.status.success());
        assert_styles_agree("hooks/_lib.sh", &String::from_utf8_lossy(&output.stdout));

        let temp = tempfile::tempdir().unwrap();
        let files = alias_cases()
            .iter()
            .enumerate()
            .map(|(index, (toml, _))| {
                let path = temp.path().join(format!("alias-{index:03}.toml"));
                std::fs::write(&path, toml).unwrap();
                path
            })
            .collect::<Vec<_>>();
        let output = Command::new("sh")
            .arg("-c")
            .arg(r#". "$1"; shift; for f in "$@"; do printf '%s\n' "$(ai_memory_aliases_json "$f")"; done"#)
            .arg("sh")
            .arg(repo_file("hooks/_lib.sh"))
            .args(&files)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        assert_aliases_agree("hooks/_lib.sh", &String::from_utf8_lossy(&output.stdout));
    }

    #[test]
    fn the_powershell_port_agrees_with_the_core() {
        let Some(pwsh) = ["pwsh", "powershell"].into_iter().find(|exe| {
            Command::new(exe)
                .args(["-NoProfile", "-Command", "exit 0"])
                .status()
                .is_ok()
        }) else {
            return;
        };
        let tmp = tempfile::TempDir::new().unwrap();
        let script = tmp.path().join("parity.ps1");
        std::fs::write(
            &script,
            "param([string] $Lib, [string] $Cases, [string] $Styles, [string] $AliasesDir)\n\
             . $Lib\n\
             foreach ($u in (Get-Content -Raw $Cases | ConvertFrom-Json)) {\n\
                 $id = ConvertTo-AiMemoryRepositoryIdentity -Url $u\n\
                 if ($id) { [Console]::Out.Write(\"$id`n\") } else { [Console]::Out.Write(\"`n\") }\n\
             }\n\
             $decisions = @(\n\
                 (Get-AiMemoryIdentityQuery -Cwd '' -Explicit ' Acme/Platform ' -Project 'proj' -Style 'path'),\n\
                 (Get-AiMemoryIdentityQuery -Cwd '' -Explicit '' -Project 'proj'),\n\
                 (Get-AiMemoryIdentityQuery -Cwd '' -Explicit '' -Project '')\n\
             )\n\
             [Console]::Error.Write($decisions -join '|')\n\
             foreach ($s in (Get-Content -Raw $Styles | ConvertFrom-Json)) {\n\
                 [Console]::Out.Write(\"S:$(Get-AiMemoryIdentityStyleQuery -Style $s)`n\")\n\
             }\n\
             Get-ChildItem $AliasesDir -Filter '*.toml' | Sort-Object Name | ForEach-Object {\n\
                 [Console]::Out.Write(\"A:$(Get-AiMemoryTomlAliases -File $_.FullName)`n\")\n\
             }\n",
        )
        .unwrap();
        let urls = tmp.path().join("urls.json");
        let list: Vec<String> = cases().into_iter().map(|(url, _)| url).collect();
        std::fs::write(&urls, serde_json::to_string(&list).unwrap()).unwrap();
        let styles = tmp.path().join("styles.json");
        let values: Vec<String> = style_cases().into_iter().map(|(value, _)| value).collect();
        std::fs::write(&styles, serde_json::to_string(&values).unwrap()).unwrap();
        let aliases_dir = tmp.path().join("aliases");
        std::fs::create_dir(&aliases_dir).unwrap();
        for (index, (toml, _)) in alias_cases().iter().enumerate() {
            std::fs::write(aliases_dir.join(format!("alias-{index:03}.toml")), toml).unwrap();
        }
        let output = Command::new(pwsh)
            .args(["-NoProfile", "-NonInteractive", "-File"])
            .arg(&script)
            .arg(repo_file("hooks/lib/ai-memory-hook.ps1"))
            .arg(&urls)
            .arg(&styles)
            .arg(&aliases_dir)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        // Style decisions are tagged `S:` so they can share stdout with the
        // normalised URLs.
        let stdout = String::from_utf8_lossy(&output.stdout);
        let lines = stdout.split('\n').collect::<Vec<_>>();
        let styles = lines
            .iter()
            .copied()
            .filter(|line| line.starts_with("S:"))
            .collect::<Vec<_>>();
        let aliases = lines
            .iter()
            .copied()
            .filter(|line| line.starts_with("A:"))
            .map(|line| &line[2..])
            .collect::<Vec<_>>();
        let urls = lines
            .iter()
            .copied()
            .filter(|line| !line.starts_with("S:") && !line.starts_with("A:"))
            .collect::<Vec<_>>();
        assert_agrees("hooks/lib/ai-memory-hook.ps1", urls.join("\n").as_bytes());
        let styles: Vec<&str> = styles.iter().map(|line| &line[2..]).collect();
        assert_styles_agree("hooks/lib/ai-memory-hook.ps1", &styles.join("\n"));
        assert_aliases_agree("hooks/lib/ai-memory-hook.ps1", &aliases.join("\n"));
        // Same decisions as the other clients: explicit wins over a declared
        // project; a declared project alone sends nothing; no cwd sends nothing.
        assert_eq!(
            String::from_utf8_lossy(&output.stderr),
            "&identity=acme%2Fplatform&identity_src=explicit||"
        );
    }

    #[test]
    fn shell_home_route_runtime_fixture_agrees() {
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        std::fs::create_dir_all(&home).unwrap();
        let route_home = if cfg!(windows) {
            std::path::Path::new("C:/Users/ai-memory-test")
        } else {
            home.as_path()
        };
        for case in home_route_cases() {
            let (text, cwd) = expanded_route_case(&case, route_home);
            let marker = home.join(".ai-memory.toml");
            std::fs::write(&marker, text).unwrap();
            let output = Command::new("sh")
                .arg("-c")
                .arg(r#". "$1"; _amhome="$2"; ai_memory_home_route "$3" "$4" "$5""#)
                .arg("sh")
                .arg(repo_file("hooks/_lib.sh"))
                .arg(route_home)
                .arg(&marker)
                .arg(&cwd)
                .arg(case["identity"].as_str().unwrap_or(""))
                .env("MSYS2_ARG_CONV_EXCL", "*")
                .output()
                .unwrap();
            assert!(
                output.status.success(),
                "{}",
                String::from_utf8_lossy(&output.stderr)
            );
            let result = String::from_utf8(output.stdout).unwrap();
            let status = case["status"].as_str().unwrap();
            let expected = match status {
                "valid" => format!(
                    "{}\u{1c}{}",
                    case["workspace"].as_str().unwrap(),
                    case["project"].as_str().unwrap()
                ),
                "invalid" => "invalid".to_owned(),
                "none" => String::new(),
                status => panic!("unknown fixture status {status}"),
            };
            assert!(
                result.starts_with(&expected),
                "{}: {result:?}",
                case["name"]
            );
        }
    }

    #[test]
    fn portable_home_route_runtime_fixture_agrees() {
        let strips_types = Command::new("node")
            .args(["--experimental-strip-types", "-e", "0"])
            .output()
            .is_ok_and(|out| out.status.success());
        if !strips_types {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        std::fs::create_dir_all(&home).unwrap();
        let cases = home_route_cases();
        let input = cases
            .iter()
            .map(|case| {
                let (text, cwd) = expanded_route_case(case, &home);
                serde_json::json!({
                    "name": case["name"],
                    "text": text,
                    "cwd": cwd,
                    "identity": case["identity"],
                    "status": case["status"],
                    "workspace": case["workspace"],
                    "project": case["project"]
                })
            })
            .collect::<Vec<_>>();
        let module = tmp.path().join("home-route-fixture.ts");
        let source = format!(
            "import {{ closeSync, openSync, readSync, statSync }} from \"node:fs\";\nimport {{ homedir }} from \"node:os\";\nfunction markerAliases(text:string):string|undefined{{const m=/^aliases\\s*=\\s*\\[([^\\]]*)\\]\\s*$/.exec(text);if(!m)return \"invalid\";if(!m[1].trim())return undefined;const out:string[]=[];const p=m[1].split(\",\");if(p.length>16)return \"invalid\";for(const r of p){{if(r.includes(\"\\\\\"))return \"invalid\";const x=/^\\s*\"([^\"]*)\"\\s*$/.exec(r);if(!x)return \"invalid\";const v=x[1].trim();if(!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v)||Buffer.byteLength(v)>128)return \"invalid\";if(!out.includes(v))out.push(v);}}return JSON.stringify(out);}}\nfunction validNormalizedIdentity(value:string):boolean{{const host=value.split(\"/\",1)[0];return /^[a-z0-9.-]+(?:\\/[a-z0-9._-]+)+$/.test(value)&&value===value.toLowerCase()&&!host.startsWith(\".\")&&!host.endsWith(\".\");}}\n{}\nconst cases={} as any[];for(const c of cases){{try{{const r=homeRoute(c.text,c.cwd,c.identity);process.stdout.write(`${{c.name}}:${{r?r.workspace+\"/\"+r.project:\"none\"}}\\n`);}}catch{{process.stdout.write(`${{c.name}}:invalid\\n`);}}}}",
            super::TS_HOME_ROUTES,
            serde_json::to_string(&input).unwrap()
        );
        std::fs::write(&module, source).unwrap();
        let output = Command::new("node")
            .args(["--experimental-strip-types", "--no-warnings"])
            .arg(&module)
            .env("HOME", &home)
            .env("USERPROFILE", &home)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        let lines = String::from_utf8(output.stdout).unwrap();
        for case in &input {
            let expected = match case["status"].as_str().unwrap() {
                "valid" => format!(
                    "{}/{}",
                    case["workspace"].as_str().unwrap(),
                    case["project"].as_str().unwrap()
                ),
                status => status.to_owned(),
            };
            assert!(
                lines
                    .lines()
                    .any(|line| line == format!("{}:{expected}", case["name"].as_str().unwrap())),
                "{}: {lines}",
                case["name"]
            );
        }
    }

    #[test]
    fn generated_typescript_applies_home_identity_route_with_alias_provenance() {
        let strips_types = Command::new("node")
            .args(["--experimental-strip-types", "-e", "0"])
            .output()
            .is_ok_and(|out| out.status.success());
        if !strips_types {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = tmp.path().join("outside/repo");
        std::fs::create_dir_all(&home).unwrap();
        std::fs::create_dir_all(&repo).unwrap();
        assert!(
            Command::new("git")
                .args(["init", "-q"])
                .current_dir(&repo)
                .status()
                .unwrap()
                .success()
        );
        assert!(
            Command::new("git")
                .args(["remote", "add", "origin", "[email protected]:acme/api.git"])
                .current_dir(&repo)
                .status()
                .unwrap()
                .success()
        );
        std::fs::write(home.join(".ai-memory.toml"), "[routes.identity.\"github.com/acme/api\"]\nroute_workspace=\"oss\"\nroute_project=\"acme-api\"\nroute_identity_style=\"path\"\nroute_aliases=[\"main\"]\n[routes.path.\"/outside\"]\nroute_workspace=\"wrong\"\nroute_project=\"wrong\"\n").unwrap();
        let module = tmp.path().join("home-route.ts");
        let source = format!(
            "import {{ execFileSync }} from \"node:child_process\";\nimport {{ closeSync, existsSync, openSync, readFileSync, readSync, statSync }} from \"node:fs\";\nimport {{ basename, dirname, join, resolve, sep }} from \"node:path\";\nimport {{ homedir }} from \"node:os\";\nfunction tomlKey(text:string,key:string):string|undefined{{const m=new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`,`m`).exec(text);return m?.[1];}}\n{}\n{}\nconst url=new URL(\"http://h/hook\"); applyMarkerParams(url, {}); process.stdout.write(url.search);",
            super::TS_REPO_ROOT_PROJECT,
            super::ts_apply_marker_params(None, true),
            serde_json::to_string(&repo.to_string_lossy()).unwrap(),
        );
        std::fs::write(&module, source).unwrap();
        let output = Command::new("node")
            .args(["--experimental-strip-types", "--no-warnings"])
            .arg(&module)
            .env("HOME", &home)
            .env("USERPROFILE", &home)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        let query = String::from_utf8(output.stdout).unwrap();
        assert!(query.contains("workspace=oss"), "{query}");
        assert!(query.contains("project=acme-api"), "{query}");
        assert!(query.contains("project_src=marker"), "{query}");
        assert!(
            query.contains("identity=github.com%2Facme%2Fapi"),
            "{query}"
        );
        assert!(query.contains("identity_style=path"), "{query}");
        assert!(query.contains("aliases=%5B%22main%22%5D"), "{query}");
    }

    #[test]
    fn generated_typescript_non_git_home_path_route_omits_aliases() {
        if !Command::new("node")
            .args(["--experimental-strip-types", "-e", "0"])
            .output()
            .is_ok_and(|out| out.status.success())
        {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = home.join("src/api");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            home.join(".ai-memory.toml"),
            "[routes.path.\"~/src/api\"]\nroute_workspace=\"path\"\nroute_project=\"api\"\nroute_aliases=[\"old-api\"]\n",
        )
        .unwrap();
        let module = tmp.path().join("home-route-no-remote.ts");
        let source = format!(
            "import {{ execFileSync }} from \"node:child_process\";\nimport {{ closeSync, existsSync, openSync, readFileSync, readSync, statSync }} from \"node:fs\";\nimport {{ basename, dirname, join, resolve, sep }} from \"node:path\";\nimport {{ homedir }} from \"node:os\";\nfunction tomlKey(text:string,key:string):string|undefined{{const m=new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`,`m`).exec(text);return m?.[1];}}\n{}\n{}\nconst url=new URL(\"http://h/hook\");applyMarkerParams(url,{});process.stdout.write(url.search);",
            super::TS_REPO_ROOT_PROJECT,
            super::ts_apply_marker_params(None, true),
            serde_json::to_string(&repo.to_string_lossy()).unwrap(),
        );
        std::fs::write(&module, source).unwrap();
        let output = Command::new("node")
            .args(["--experimental-strip-types", "--no-warnings"])
            .arg(&module)
            .env("HOME", &home)
            .env("USERPROFILE", &home)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        let query = String::from_utf8(output.stdout).unwrap();
        assert!(query.contains("workspace=path"), "{query}");
        assert!(query.contains("project=api"), "{query}");
        assert!(!query.contains("aliases="), "{query}");
        assert!(!query.contains("identity_src="), "{query}");
    }

    #[test]
    fn generated_typescript_default_repo_root_sets_derived_provenance() {
        if !Command::new("node")
            .args(["--experimental-strip-types", "-e", "0"])
            .output()
            .is_ok_and(|out| out.status.success())
        {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = tmp.path().join("derived-project");
        std::fs::create_dir_all(&home).unwrap();
        std::fs::create_dir_all(&repo).unwrap();
        assert!(
            Command::new("git")
                .args(["init", "-q"])
                .current_dir(&repo)
                .status()
                .unwrap()
                .success()
        );
        let module = tmp.path().join("repo-root-provenance.ts");
        let source = format!(
            "import {{ execFileSync }} from \"node:child_process\";\nimport {{ closeSync, existsSync, openSync, readFileSync, readSync, statSync }} from \"node:fs\";\nimport {{ basename, dirname, join, resolve, sep }} from \"node:path\";\nimport {{ homedir }} from \"node:os\";\nfunction tomlKey(text:string,key:string):string|undefined{{const m=new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`,`m`).exec(text);return m?.[1];}}\n{}\n{}\nconst url=new URL(\"http://h/hook\");applyMarkerParams(url,{});process.stdout.write(url.search);",
            super::TS_REPO_ROOT_PROJECT,
            super::ts_apply_marker_params(Some("repo-root"), true),
            serde_json::to_string(&repo.to_string_lossy()).unwrap(),
        );
        std::fs::write(&module, source).unwrap();
        let output = Command::new("node")
            .args(["--experimental-strip-types", "--no-warnings"])
            .arg(&module)
            .env("HOME", &home)
            .env("USERPROFILE", &home)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        let params = reqwest::Url::parse(&format!(
            "http://h/hook{}",
            String::from_utf8(output.stdout).unwrap()
        ))
        .unwrap()
        .query_pairs()
        .into_owned()
        .collect::<std::collections::HashMap<_, _>>();
        assert_eq!(
            params.get("project").map(String::as_str),
            Some("derived-project")
        );
        assert_eq!(
            params.get("project_src").map(String::as_str),
            Some("repo-root")
        );
        assert_eq!(
            params.get("project_strategy").map(String::as_str),
            Some("repo-root")
        );
    }

    #[test]
    fn generated_typescript_applies_marker_alias_params_together() {
        let strips_types = Command::new("node")
            .args(["--experimental-strip-types", "-e", "0"])
            .output()
            .is_ok_and(|out| out.status.success());
        if !strips_types {
            return;
        }
        for default_strategy in [None, Some("basename")] {
            let tmp = tempfile::TempDir::new().unwrap();
            let repo = tmp.path().join("repo");
            std::fs::create_dir(&repo).unwrap();
            assert!(
                Command::new("git")
                    .args(["init", "-q"])
                    .current_dir(&repo)
                    .status()
                    .unwrap()
                    .success()
            );
            assert!(
                Command::new("git")
                    .args([
                        "remote",
                        "add",
                        "origin",
                        "[email protected]:Acme/API.git",
                    ])
                    .current_dir(&repo)
                    .status()
                    .unwrap()
                    .success()
            );
            std::fs::write(
                repo.join(".ai-memory.toml"),
                "project = \"acme-api\"\naliases = [\"former-name\"]\n",
            )
            .unwrap();
            let module = tmp.path().join("apply-marker.ts");
            let source = format!(
                "import {{ execFileSync }} from \"node:child_process\";\n\
                 import {{ closeSync, existsSync, openSync, readFileSync, readSync, statSync }} from \"node:fs\";\n\
                 import {{ basename, dirname, join, resolve, sep }} from \"node:path\";\n\
                 import {{ homedir }} from \"node:os\";\n\
                 function tomlKey(text: string, key: string): string | undefined {{\n\
                   const re = new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`);\n\
                   for (const line of text.split(/\\r?\\n/)) {{\n\
                     const match = re.exec(line);\n\
                     if (match) return match[1];\n\
                   }}\n\
                   return undefined;\n\
                 }}\n\
                 {}\n\
                 {}\n\
                 const url = new URL(\"http://h/hook\");\n\
                 applyMarkerParams(url, {});\n\
                 process.stdout.write(url.search);\n",
                super::TS_REPO_ROOT_PROJECT,
                super::ts_apply_marker_params(default_strategy, true),
                serde_json::to_string(&repo.to_string_lossy()).unwrap(),
            );
            std::fs::write(&module, source).unwrap();
            let output = Command::new("node")
                .args(["--experimental-strip-types", "--no-warnings"])
                .arg(&module)
                .env("HOME", tmp.path())
                .env("USERPROFILE", tmp.path())
                .output()
                .unwrap();
            assert!(
                output.status.success(),
                "{}",
                String::from_utf8_lossy(&output.stderr)
            );
            let params = reqwest::Url::parse(&format!(
                "http://h/hook{}",
                String::from_utf8(output.stdout).unwrap()
            ))
            .unwrap()
            .query_pairs()
            .into_owned()
            .collect::<std::collections::HashMap<_, _>>();
            assert_eq!(params.get("project").map(String::as_str), Some("acme-api"));
            assert_eq!(
                params.get("identity").map(String::as_str),
                Some("git.example.test/acme/api")
            );
            assert_eq!(
                params.get("identity_src").map(String::as_str),
                Some("git_remote")
            );
            assert_eq!(
                params.get("aliases").map(String::as_str),
                Some("[\"former-name\"]")
            );
            assert_eq!(
                params.get("project_src").map(String::as_str),
                Some("marker")
            );
        }
    }

    #[test]
    fn the_typescript_port_agrees_with_the_core() {
        let strips_types = Command::new("node")
            .args(["--experimental-strip-types", "-e", "0"])
            .output()
            .is_ok_and(|out| out.status.success());
        if !strips_types {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let module = tmp.path().join("parity.ts");
        let list: Vec<String> = cases().into_iter().map(|(url, _)| url).collect();
        let styles: Vec<String> = style_cases().into_iter().map(|(value, _)| value).collect();
        let source = format!(
            "import {{ execFileSync }} from \"node:child_process\";\n\
             void execFileSync;\n\
             {}\n\
             const urls: string[] = {};\n\
             process.stdout.write(urls.map((u) => normalizeRemote(u) ?? \"\").join(\"\\n\") + \"\\n\");\n\
             const aliasCases: string[] = {};\n\
             for (const marker of aliasCases) process.stdout.write(`A:${{markerAliases(marker) ?? \"\"}}\\n`);\n\
             const styles: string[] = {};\n\
             for (const s of styles) {{\n\
               const forwarded = identityStyleParam(s);\n\
               process.stdout.write(`S:${{forwarded ? `&identity_style=${{forwarded}}` : \"\"}}\\n`);\n\
             }}\n\
             const decide = (explicit?: string, project?: string): string => {{\n\
               const url = new URL(\"http://h/hook\");\n\
               applyIdentityParams(url, undefined, explicit, project, \"path\", undefined);\n\
               return url.search;\n\
             }};\n\
             process.stderr.write([decide(\" Acme/Platform \", \"proj\"), decide(undefined, \"proj\"), decide()].join(\"|\"));\n",
            super::TS_IDENTITY,
            serde_json::to_string(&list).unwrap(),
            serde_json::to_string(
                &alias_cases()
                    .into_iter()
                    .map(|(toml, _)| toml)
                    .collect::<Vec<_>>()
            )
            .unwrap(),
            serde_json::to_string(&styles).unwrap()
        );
        std::fs::write(&module, source).unwrap();
        let output = Command::new("node")
            .args(["--experimental-strip-types", "--no-warnings"])
            .arg(&module)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
        let stdout = String::from_utf8_lossy(&output.stdout);
        let lines = stdout.split('\n').collect::<Vec<_>>();
        let aliases = lines
            .iter()
            .copied()
            .filter(|line| line.starts_with("A:"))
            .map(|line| &line[2..])
            .collect::<Vec<_>>();
        let styles = lines
            .iter()
            .copied()
            .filter(|line| line.starts_with("S:"))
            .map(|line| &line[2..])
            .collect::<Vec<_>>();
        let urls = lines
            .iter()
            .copied()
            .filter(|line| !line.starts_with("S:") && !line.starts_with("A:"))
            .collect::<Vec<_>>();
        assert_agrees("TS_IDENTITY", urls.join("\n").as_bytes());
        assert_aliases_agree("TS_IDENTITY", &aliases.join("\n"));
        assert_styles_agree("TS_IDENTITY", &styles.join("\n"));
        // An explicit identity wins over a declared project; a declared
        // project alone sends nothing; no cwd sends nothing. A requested
        // `path` style never rides along with an explicit identity.
        assert_eq!(
            String::from_utf8_lossy(&output.stderr),
            "?identity=acme%2Fplatform&identity_src=explicit||"
        );
    }
}