Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `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(¤t_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(¬_a_directory, "{}").unwrap();
let error = list_kiro_cli_agent_configs(¬_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||"
);
}
}