Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(agents): add Pool (Poolside Agent CLI) hook capture and finalize-session (#476)
Ștefan Taloș35aa307c244b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5ffe1ee9..6fe428f8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -43,7 +43,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0The fallback is unchanged and still serves hand-written pages and everythingwritten before this. New writes only: no backfill, no migration.-+- Pool (Poolside Agent CLI) is a first-class agent kind. Hook ingestion+ recognizes `agent=pool` (alias `poolside`) and Pool's documented snake_case+ `session_id` / `cwd` / `tool_name` / `tool_input` payload for concrete+ session attribution and tool-family titles, and Pool's five events+ (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` —+ verified against Poolside CLI v1.0.16) ship as a `hooks/pool/` bundle.+ `install-hooks --agent pool` stages the scripts and prints a ready-to-paste+ `.poolside/settings.yaml` `hooks:` snippet — Pool's hook config is+ project-scoped YAML at each repo root, so the installer deliberately does+ not write project-local files. Native hook commands enforce `[capture]+ ignore_paths` for Pool's `read`/`edit`/`write`/`remove` file tools, with+ unknown payload shapes degrading to metadata-only capture. Pool has no true+ session-end event, so `ai-memory finalize-session --agent pool` closes the+ session (the same class as Codex and Antigravity CLI); a forward migration+ (V50) rebuilds the sessions constraint and pairing triggers to accept the+ `pool` kind without losing rows. `SessionStart` stdout injection is not+ demonstrated, so the session-start hook never fetches the single-use+ handoff — recover it via MCP `memory_handoff_accept`. No managed+ workstream (`ai-memory run pool`) is claimed: Pool's native session-store+ contract is not demonstrated, per docs/managed-harness-contributions.md.- `ai-memory status` now reports server-side hook-ingestion countersalongside the client spool section: events accepted, accepted-but-droppedby capture policy, shed because ingest capacity was exhausted, shed by thediff --git a/README.md b/README.mdindex b4681db3..2283a009 100644--- a/README.md+++ b/README.md@@ -41,6 +41,7 @@| Zero | Supported | `install-mcp --client zero` (native HTTP + bearer in `~/.config/zero/config.json`) + lifecycle hooks via `install-hooks --agent zero --apply` (exec-form native commands in `~/.config/zero/hooks.json`, JSON payload on stdin, no shell). Capture works incl. specialist (subagent) events; no handoff injection — Zero discards `sessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. || Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. || Kiro CLI | Supported | MCP config uses `install-mcp --client kiro-cli` (alias `kiro`) and Kiro's Bedrock-compatible schema flavor. `install-hooks --agent kiro-cli` merges v2 hooks into existing agent configs; the explicit `--agent kiro-cli-v3` target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor `$KIRO_HOME`, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use `ai-memory finalize-session --agent kiro-cli`, with `--session-id <uuid>` for concurrent sessions. `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |+| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing project-local files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_accept`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. || VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). || Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. || Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. |@@ -164,7 +165,8 @@ priors are at the [bottom](#influences-and-prior-art).Gemini CLI, Antigravity CLI, Grok Build CLI, Kimi Code, OpenClaw, Oh My Pi/ OMP (`omp` / `oh-my-pi`), Pi via generated bridge extension, VS CodeGitHub Copilot agent mode (MCP-only, workspace `.vscode/mcp.json`), Kiro CLI- (MCP + v2 lifecycle hooks), and Zed (MCP-only, user `settings.json`).+ (MCP + v2 lifecycle hooks), Pool (hooks-only, project+ `.poolside/settings.yaml` snippet), and Zed (MCP-only, user `settings.json`).Server runs local (loopback) OR on a homelab box (LAN/VPN/cloud)with bearer-token auth. Shared servers can opt into[`[auto_scope]` modes](docs/auto-scope.md) for per-user or@@ -491,6 +493,9 @@ ai-memory install-hooks --agent claude-code --apply# Command Code stable MCP + lifecycle example:# ai-memory install-mcp --client command-code --apply# ai-memory install-hooks --agent command-code --apply+# Pool (Poolside Agent CLI) example — stages scripts and prints the+# .poolside/settings.yaml snippet to paste into each repo (no MCP client yet):+# ai-memory install-hooks --agent pool --apply```On Linux/macOS, that's it. Start a Claude Code session as usual - everydiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 35011b2e..24c5b84a 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -1089,6 +1089,17 @@ pub enum AgentChoice {/// `~/.commandcode/settings.json`.#[value(alias = "commandcode", alias = "cmdc", alias = "cmd")]CommandCode,+ /// Pool (Poolside Agent CLI, `pool`) — project-scoped YAML hooks in+ /// the repo-root `.poolside/settings.yaml`. ai-memory stages the hook+ /// scripts and prints a ready-to-paste `hooks:` snippet; it does not+ /// write project-local files. NOTE: Pool's `SessionStart` stdout+ /// injection is not demonstrated, so capture works but handoff+ /// injection does not — recover the prior session's handoff via the+ /// MCP `memory_handoff_accept` tool, and close sessions with+ /// `ai-memory finalize-session --agent pool` (Pool has no true+ /// session-end event).+ #[value(alias = "poolside")]+ Pool,}impl AgentChoice {@@ -1116,6 +1127,7 @@ impl AgentChoice {Self::KimiCode => AgentKind::KimiCode,Self::KiroCli | Self::KiroCliV3 => AgentKind::KiroCli,Self::CommandCode => AgentKind::CommandCode,+ Self::Pool => AgentKind::Pool,}}@@ -1137,7 +1149,7 @@ impl AgentChoice {#[derive(Debug, Args)]pub struct FinalizeSessionArgs {/// Agent kind to finalize. Defaults to Codex for backward compatibility;- /// Codex and Antigravity CLI have no reliable true SessionEnd hook.+ /// Codex, Antigravity CLI, and Pool have no reliable true SessionEnd hook.#[arg(long, value_enum, default_value_t = AgentChoice::Codex)]pub agent: AgentChoice,/// Workspace name. Defaults to the nearest `.ai-memory.toml` marker's@@ -2392,6 +2404,33 @@ mod tests {}}+ #[test]+ fn pool_hook_and_finalize_aliases_parse() {+ for alias in ["pool", "poolside"] {+ let cli = Cli::try_parse_from([+ "ai-memory",+ "install-hooks",+ "--agent",+ alias,+ "--server-url",+ "http://127.0.0.1:49374",+ ])+ .unwrap_or_else(|error| panic!("failed to parse Pool alias {alias}: {error}"));+ let Command::InstallHooks(args) = cli.command else {+ panic!("expected install-hooks for Pool alias {alias}");+ };+ assert_eq!(args.agent, AgentChoice::Pool);+ assert_eq!(args.agent.kind(), ai_memory_core::AgentKind::Pool);+ assert_eq!(args.agent.script_hook_subdir(), Some("pool"));+ }+ let cli = Cli::try_parse_from(["ai-memory", "finalize-session", "--agent", "pool"])+ .expect("failed to parse finalize-session --agent pool");+ let Command::FinalizeSession(args) = cli.command else {+ panic!("expected finalize-session for pool");+ };+ assert_eq!(args.agent, AgentChoice::Pool);+ }+#[test]fn command_code_mcp_and_hook_aliases_parse() {for alias in ["command-code", "commandcode", "cmdc", "cmd"] {diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex da4c518f..cc5e0b95 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -1797,6 +1797,47 @@ mod tests {assert_eq!(hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)), 0);}+ #[tokio::test]+ async fn pool_file_exclusion_drops_before_spool_or_drain() {+ let tmp = tempfile::tempdir().unwrap();+ std::fs::write(+ tmp.path().join(".ai-memory.toml"),+ "[capture]\nignore_paths = [\"secret/**\"]\n",+ )+ .unwrap();+ let data_dir = tmp.path().join("data");+ let mut stdout = Vec::new();+ let called = std::cell::Cell::new(false);+ let mut args = devin_hook_args("post-tool-use");+ args.agent = "pool".into();+ let raw = serde_json::json!({+ "hook_event_name": "PostToolUse",+ "tool_name": "write",+ "tool_input": {+ "path": "secret/token.txt",+ "content": "SENTINEL_MUST_NOT_BE_SPOOLED"+ },+ "session_id": "pool-session",+ "cwd": tmp.path()+ });+ run_with_payload(+ Some(data_dir.clone()),+ args,+ raw.to_string(),+ &mut stdout,+ |_| {+ called.set(true);+ Ok(())+ },+ )+ .await+ .unwrap();++ assert_eq!(stdout, b"{}\n");+ assert!(!called.get());+ assert_eq!(hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)), 0);+ }+#[cfg(unix)]#[tokio::test]async fn capture_drop_handles_symlinked_cwd() {diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex 9a4e6785..8fdc54b9 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -27,9 +27,10 @@ use crate::commands::path_util::home_dir;use crate::commands::render_shared::{ANTIGRAVITY_LIFECYCLE_EVENTS, ANTIGRAVITY_TOOL_EVENTS, CODEX_PROFILE, COMMAND_CODE_PROFILE,CURSOR_PROFILE, GEMINI_PROFILE, KIMI_CODE_EVENTS, KIRO_CLI_V2_EVENTS, KIRO_CLI_V3_EVENTS,- build_antigravity_payload_with_data_dir, build_claude_code_payload_with_data_dir,+ POOL_EVENTS, build_antigravity_payload_with_data_dir, build_claude_code_payload_with_data_dir,build_devin_payload_with_data_dir, build_grok_payload_with_data_dir,- build_kiro_cli_v2_hooks_value, build_kiro_cli_v3_hooks_value, build_profile_payload_for_agent,+ 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_script_for_claude_code, hook_script_for_current_platform, kimi_code_hook_commands,local_hook_policy_v1_supported, ts_capture_policy_v1, ts_string_literal,};@@ -469,6 +470,10 @@ pub fn run(config: &Config, mut args: InstallHooksArgs) -> Result<()> {let hooks_dir = resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent)?;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)?;+ apply_to_pool(&hooks_dir, &server_url, auth, &config.data_dir, &args)+ }};}let strategy = args.project_strategy.and_then(ProjectStrategyArg::baked);@@ -577,6 +582,10 @@ pub fn run(config: &Config, mut args: InstallHooksArgs) -> Result<()> {let hooks_dir = resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent)?;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)?;+ render_pool(&hooks_dir, &server_url, auth, &config.data_dir, strategy)+ }}}@@ -695,6 +704,9 @@ fn existing_agent_config(args: &InstallHooksArgs) -> Option<String> {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()?,}};@@ -1050,6 +1062,9 @@ fn mcp_client_for_agent(agent: AgentChoice) -> Option<McpClient> {// 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,}}@@ -4628,6 +4643,107 @@ fn render_kiro_cli_v3(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 project-local 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")?;+ 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(())+}+#[cfg(test)]mod tests {use super::*;@@ -4701,6 +4817,7 @@ mod tests {KimiCode,KiroCli,KiroCliV3,+ Pool,] {assert!(!capture_assistant_allowed(agent),@@ -4734,6 +4851,7 @@ mod tests {KimiCode,KiroCli,KiroCliV3,+ Pool,] {assert!(!prompt_capture_options_allowed(agent), "{agent:?}");}@@ -5486,6 +5604,75 @@ command = "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/aassert_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).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 project-local 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"));+ }+// 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]diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rsindex 51f14a31..c618e2ab 100644--- a/crates/ai-memory-cli/src/commands/render_shared.rs+++ b/crates/ai-memory-cli/src/commands/render_shared.rs@@ -123,6 +123,24 @@ pub(crate) const DEVIN_EVENTS: [(&str, &str); 7] = [("SessionEnd", "session-end.sh"),];+/// Pool (Poolside Agent CLI) lifecycle events ai-memory hooks. Each pair is+/// `(event-name-in-.poolside-settings, POSIX hook-script-filename)`.+///+/// Pool's hook vocabulary uses Claude-shaped PascalCase names but is exactly+/// these five events (verified against Poolside CLI v1.0.16, hooks api 1.0):+/// no `SessionEnd`, no `PreCompact`, no subagent events. `Stop` is a turn+/// boundary, not a session end — `ai-memory finalize-session --agent pool`+/// is the close path. Adding a hook event means updating this list AND+/// adding the matching `.sh` and `.ps1` files under `hooks/pool/`; the+/// install-hooks parity test fails if the bundle drifts.+pub(crate) const POOL_EVENTS: [(&str, &str); 5] = [+ ("SessionStart", "session-start.sh"),+ ("UserPromptSubmit", "user-prompt-submit.sh"),+ ("PreToolUse", "pre-tool-use.sh"),+ ("PostToolUse", "post-tool-use.sh"),+ ("Stop", "stop.sh"),+];+/// Format an `Authorization: Bearer <token>` header value, or `None`/// when no token is supplied. Used by every MCP client renderer in/// `install-mcp` and every hook-config renderer that wants to@@ -514,6 +532,85 @@ pub(crate) fn build_devin_payload_with_data_dir()}+/// Pool (Poolside Agent CLI) `.poolside/settings.yaml` `hooks:` block for+/// install-hooks' print path. Pool's hook config is a project-scoped YAML+/// file at the repo root — there is no user-global hook file for ai-memory+/// to merge, so the installer renders a ready-to-paste snippet instead of+/// writing into the user's project checkouts.+///+/// One entry per event, shell command string on `command:`, `matcher: "*"`+/// and a bounded `timeout` per Pool's documented schema. YAML single-quote+/// escaping (`'` → `''`) keeps the embedded shell quoting intact.+#[must_use]+pub(crate) fn build_pool_settings_yaml_with_data_dir(+ emit_root: &Path,+ server_url: &str,+ auth_token: Option<&str>,+ data_dir: Option<&Path>,+ project_strategy: Option<&str>,+) -> String {+ build_pool_settings_yaml_for_platform(+ emit_root,+ server_url,+ auth_token,+ HookCommandContext::new(+ HookCommandPlatform::for_bash_runner(),+ "pool",+ data_dir,+ project_strategy,+ ),+ )+}++/// Script-fallback variant for `setup-agent` / docker-host snippets: the+/// copied `.sh` scripts are the artifact, so the commands reference them+/// rather than a host-local native binary.+#[must_use]+pub(crate) fn build_pool_settings_yaml(+ emit_root: &Path,+ server_url: &str,+ auth_token: Option<&str>,+) -> String {+ build_pool_settings_yaml_for_platform(+ emit_root,+ server_url,+ auth_token,+ HookCommandContext::new(+ HookCommandPlatform::for_bash_script_runner(),+ "pool",+ None,+ None,+ ),+ )+}++fn build_pool_settings_yaml_for_platform(+ emit_root: &Path,+ server_url: &str,+ auth_token: Option<&str>,+ context: HookCommandContext<'_>,+) -> String {+ let mut out = String::from("hooks:\n");+ for (event, script) in &POOL_EVENTS {+ let resolved = script_for_platform(script, context.platform);+ let abs = emit_root.join(resolved.as_ref());+ let command = hook_command(&abs, server_url, auth_token, context);+ let stem = script.strip_suffix(".sh").unwrap_or(script);+ out.push_str(&format!(+ " {event}:\n - name: ai-memory-{stem}\n matcher: \"*\"\n command: {}\n timeout: 20\n",+ yaml_single_quote(&command)+ ));+ }+ out+}++/// Emit a YAML single-quoted scalar: wrap in `'…'`, doubling any embedded+/// `'`. Single-quote style is the only YAML form in which the POSIX shell+/// quoting inside the hook command survives byte-for-byte.+fn yaml_single_quote(s: &str) -> String {+ format!("'{}'", s.replace('\'', "''"))+}+/// Different agents nest hook entries differently. Two shapes/// cover everyone we support:#[derive(Clone, Copy, Debug, PartialEq, Eq)]diff --git a/crates/ai-memory-cli/src/commands/setup_agent.rs b/crates/ai-memory-cli/src/commands/setup_agent.rsindex 9860d3c3..3e4e8c26 100644--- a/crates/ai-memory-cli/src/commands/setup_agent.rs+++ b/crates/ai-memory-cli/src/commands/setup_agent.rs@@ -39,7 +39,7 @@ use crate::commands::install_mcp;use crate::commands::render_shared::{ANTIGRAVITY_LIFECYCLE_EVENTS, ANTIGRAVITY_TOOL_EVENTS, CODEX_PROFILE, COMMAND_CODE_PROFILE,CURSOR_PROFILE, GEMINI_PROFILE, KIMI_CODE_EVENTS, KIRO_CLI_V2_EVENTS, KIRO_CLI_V3_EVENTS,- build_claude_code_payload, build_devin_payload, build_grok_payload,+ build_claude_code_payload, build_devin_payload, build_grok_payload, build_pool_settings_yaml,hook_script_for_current_platform,};use crate::config::{Config, DEFAULT_SERVER_URL};@@ -159,6 +159,7 @@ pub fn run(config: &Config, args: SetupAgentArgs) -> Result<()> {AgentChoice::KiroCliV3 => {emit_other(&emit_root, agent_sub, &args, &[&KIRO_CLI_V3_EVENTS]);}+ AgentChoice::Pool => emit_pool(&emit_root, &args),AgentChoice::OpenCode| AgentChoice::Pi| AgentChoice::Omp@@ -315,6 +316,29 @@ fn emit_grok(emit_root: &Path, args: &SetupAgentArgs) -> Result<()> {Ok(())}+/// Print Pool's `.poolside/settings.yaml` `hooks:` block. The staged `.sh`+/// scripts are the artifact — Pool's hook config is a project-scoped YAML+/// file at the repo root, so the snippet is pasted into each repository+/// rather than written by ai-memory.+fn emit_pool(emit_root: &Path, args: &SetupAgentArgs) {+ let snippet = build_pool_settings_yaml(emit_root, &args.server_url, args.auth_token.as_deref());+ println!("# Pool (Poolside Agent CLI) — merge into the repo-root .poolside/settings.yaml");+ println!("# of each project Pool runs in; ai-memory does not write project-local files.");+ println!("# Hook scripts (must be reachable from the host that runs Pool):");+ println!("# {}", emit_root.display());+ println!("# AI-memory server: {}", args.server_url);+ if args.auth_token.is_some() {+ println!("# Auth: AI_MEMORY_AUTH_TOKEN embedded in each hook command below.");+ println!("# Treat .poolside/settings.yaml as sensitive (chmod 600).");+ }+ println!("# NOTE: Pool's SessionStart stdout injection is not demonstrated — capture");+ println!("# works, but handoff injection does not. Recover handoffs via the");+ println!("# MCP memory_handoff_accept tool, and close finished sessions with");+ println!("# `ai-memory finalize-session --agent pool` (no true session-end event).");+ println!();+ print!("{snippet}");+}+fn emit_devin(emit_root: &Path, args: &SetupAgentArgs) -> Result<()> {print!("{}", render_devin_setup_output(emit_root, args)?);Ok(())diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rsindex 5b8e110d..1610a6cd 100644--- a/crates/ai-memory-core/src/ids.rs+++ b/crates/ai-memory-core/src/ids.rs@@ -243,6 +243,8 @@ pub enum AgentKind {CommandCode,/// Hermes Agent (Nous Research).Hermes,+ /// Pool (Poolside Agent CLI).+ Pool,/// Anything else (manual capture, future agents).Other,}@@ -253,7 +255,7 @@ impl AgentKind {/// CHECK constraint accepts every kind (the Zero integration shipped/// with the enum variant but without the V26 migration and only a/// live test caught it). Extend together with the enum.- pub const ALL: [Self; 19] = [+ pub const ALL: [Self; 20] = [Self::ClaudeCode,Self::Codex,Self::OpenCode,@@ -272,6 +274,7 @@ impl AgentKind {Self::KiroCli,Self::CommandCode,Self::Hermes,+ Self::Pool,Self::Other,];@@ -297,6 +300,7 @@ impl AgentKind {Self::KiroCli => "kiro-cli",Self::CommandCode => "command-code",Self::Hermes => "hermes",+ Self::Pool => "pool",Self::Other => "other",}}@@ -325,6 +329,7 @@ impl AgentKind {"kiro-cli" | "kiro" => Self::KiroCli,"command-code" | "commandcode" | "cmdc" | "cmd" => Self::CommandCode,"hermes" | "hermes-agent" => Self::Hermes,+ "pool" | "poolside" => Self::Pool,_ => Self::Other,}}@@ -350,11 +355,23 @@ impl AgentKind {/// dispatch return, verified in the v0.28.1 source), so the handoff is/// delivered on `UserPromptSubmit` instead — see/// [`Self::user_prompt_injects_handoff`].+ ///+ /// Pool (Poolside Agent CLI) tolerates plain hook stdout, but model-visible+ /// context injection from `SessionStart` stdout is not demonstrated+ /// (verified against Poolside CLI v1.0.16), so Pool fails safe like other+ /// unproven agents: the handoff stays available on demand via the MCP+ /// `memory_handoff_accept` tool.#[must_use]pub fn session_start_injects_handoff(self) -> bool {!matches!(self,- Self::Crush | Self::Grok | Self::Zero | Self::KimiCode | Self::Hermes | Self::Other+ Self::Crush+ | Self::Grok+ | Self::Zero+ | Self::KimiCode+ | Self::Hermes+ | Self::Pool+ | Self::Other)}@@ -477,6 +494,23 @@ mod tests {assert!(!AgentKind::Hermes.user_prompt_injects_handoff());}+ #[test]+ fn agent_kind_pool_round_trips_without_claiming_handoff_delivery() {+ assert_eq!(AgentKind::Pool.as_str(), "pool");+ assert_eq!(AgentKind::from_wire("pool"), AgentKind::Pool);+ assert_eq!(AgentKind::from_wire("poolside"), AgentKind::Pool);+ assert_eq!(serde_json::to_string(&AgentKind::Pool).unwrap(), "\"pool\"");+ assert_eq!(+ serde_json::from_str::<AgentKind>("\"pool\"").unwrap(),+ AgentKind::Pool+ );+ assert_eq!(AgentKind::from_wire("pool-2"), AgentKind::Other);+ // Pool's SessionStart stdout injection is not demonstrated, so the+ // destructive handoff fetch must not happen from its native hook.+ assert!(!AgentKind::Pool.session_start_injects_handoff());+ assert!(!AgentKind::Pool.user_prompt_injects_handoff());+ }+#[test]fn agent_kind_command_code_round_trips_and_injects_session_start_handoff() {assert_eq!(AgentKind::CommandCode.as_str(), "command-code");diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rsindex e93babc2..68a359c5 100644--- a/crates/ai-memory-hooks/src/capture_policy.rs+++ b/crates/ai-memory-hooks/src/capture_policy.rs@@ -185,6 +185,11 @@ pub(crate) fn tool_observation_metadata(.and_then(|extra| extra.get("tool_call_id")).and_then(Value::as_str),),+ // Pool (Poolside Agent CLI) tool hooks use snake_case `tool_name` ++ // `tool_input` (hooks api 1.0, verified against Poolside CLI v1.0.16);+ // no tool-call id is documented. Unknown payload shapes fail safe to+ // metadata-only under an active policy.+ AgentKind::Pool => (object.get("tool_name")?.as_str()?, None),_ => return None,};// PreToolUse needs a proven input shape. PostToolUse deliberately does@@ -200,6 +205,7 @@ pub(crate) fn tool_observation_metadata(| AgentKind::CommandCode| AgentKind::Hermes| AgentKind::KiroCli+ | AgentKind::Pool) {"tool_input"} else {@@ -573,7 +579,8 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted {| AgentKind::GeminiCli| AgentKind::Devin| AgentKind::Hermes- | AgentKind::KiroCli => object+ | AgentKind::KiroCli+ | AgentKind::Pool => object.get("tool_name").and_then(Value::as_str).map(|name| (name, object.get("tool_input"))),@@ -630,6 +637,7 @@ fn family(name: &str) -> ToolFamily {| "notebook_edit"| "create_file"| "delete_file"+ | "remove"| "rename_file"| "move_file"| "multi_edit"@@ -1134,6 +1142,51 @@ mod tests {}}+ #[test]+ fn pool_documented_tool_shape_is_closed_and_honors_exclusions() {+ let raw = json!({+ "hook_event_name": "PostToolUse",+ "tool_name": "write",+ "tool_input": {"path": "secret/token.txt", "content": "do not retain"},+ "session_id": "pool-session",+ "cwd": "/repo"+ });+ let metadata = tool_observation_metadata(AgentKind::Pool, &raw, true).unwrap();+ assert_eq!(metadata.tool_family, ToolFamily::File);+ assert_eq!(metadata.tool_call_id, None);++ let policy = CapturePolicy::resolve(+ CaptureSource::Parsed(&CaptureConfig {+ ignore_paths: vec!["secret/**".into()],+ }),+ "/repo",+ None,+ );+ let decision = policy.inspect(AgentKind::Pool, &raw, "/repo");+ assert_eq!(decision.protocol().tool_family(), ToolFamily::File);+ assert_eq!(decision.protocol().disposition(), CaptureDisposition::Drop);++ let unknown = policy.inspect(AgentKind::Other, &raw, "/repo");+ assert_eq!(+ unknown.protocol().extraction_state(),+ ExtractionState::UnsupportedSchema+ );+ assert_eq!(unknown.protocol().tool_family(), ToolFamily::Unknown);+ }++ #[test]+ fn pool_documented_tool_names_map_to_canonical_families() {+ for (tool, expected) in [+ ("read", ToolFamily::File),+ ("edit", ToolFamily::File),+ ("write", ToolFamily::File),+ ("remove", ToolFamily::File),+ ("shell", ToolFamily::NonFile),+ ] {+ assert_eq!(family(tool), expected, "tool: {tool}");+ }+ }+#[test]fn command_code_official_tool_shape_is_closed_and_honors_exclusions() {let policy = CapturePolicy::resolve(diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex dfb94bc9..468ae981 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -599,6 +599,7 @@ const fn closed_tool_agent(agent: AgentKind) -> bool {| AgentKind::Pi| AgentKind::AntigravityCli| AgentKind::Hermes+ | AgentKind::Pool)}@@ -1562,6 +1563,8 @@ mod tests {assert_eq!(parse_agent("oh-my-pi"), AgentKind::Omp);assert_eq!(parse_agent("hermes"), AgentKind::Hermes);assert_eq!(parse_agent("hermes-agent"), AgentKind::Hermes);+ assert_eq!(parse_agent("pool"), AgentKind::Pool);+ assert_eq!(parse_agent("poolside"), AgentKind::Pool);// Anything else is `Other`. Critical for the hook router:// a typo in the query string must not crash, it just gets// attributed to the catch-all bucket.@@ -1623,6 +1626,29 @@ mod tests {assert!(unknown.title_hint.is_none());}+ #[test]+ fn pool_tool_title_uses_the_documented_snake_case_shape() {+ let raw = serde_json::json!({+ "hook_event_name": "PostToolUse",+ "tool_name": "edit",+ "tool_input": {"path": "src/lib.rs", "old_string": "a", "new_string": "b"},+ "session_id": "pool-session",+ "cwd": "/repo"+ });+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "post-tool-use".into(),+ agent: Some("pool".into()),+ ..Default::default()+ },+ raw,+ );+ assert_eq!(env.agent, AgentKind::Pool);+ assert_eq!(env.title_hint.as_deref(), Some("tool file"));+ assert_eq!(env.session_id.as_deref(), Some("pool-session"));+ assert_eq!(env.cwd.as_deref(), Some("/repo"));+ }+/// Body is well-formed JSON but the expected `session_id` //// `cwd` keys are missing — extraction returns None per key.#[test]diff --git a/crates/ai-memory-store/migrations/V50__sessions_pool_agent_kind.sql b/crates/ai-memory-store/migrations/V50__sessions_pool_agent_kind.sqlnew file mode 100644index 00000000..d4431c73--- /dev/null+++ b/crates/ai-memory-store/migrations/V50__sessions_pool_agent_kind.sql@@ -0,0 +1,73 @@+-- Expand sessions.agent_kind CHECK for Pool (Poolside Agent CLI).+--+-- Keep the complete V47 schema, indexes, and scope-pairing triggers while+-- adding the `pool` wire value.++PRAGMA foreign_keys = OFF;++DROP TRIGGER IF EXISTS auto_improve_scheduler_claims_session_pairing_ai;+DROP TRIGGER IF EXISTS session_consolidation_jobs_session_pairing_ai;++CREATE TABLE sessions_new (+ id BLOB PRIMARY KEY NOT NULL,+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,+ agent_kind TEXT NOT NULL CHECK (agent_kind IN ('claude-code','codex','open-code','cursor','gemini-cli','claude-desktop','openclaw','antigravity-cli','omp','pi','crush','grok','zero','devin','kimi-code','kiro-cli','command-code','hermes','pool','other')),+ cwd TEXT,+ started_at INTEGER NOT NULL,+ ended_at INTEGER,+ summary_page_id BLOB REFERENCES pages(id) ON DELETE SET NULL,+ ended_observation_count INTEGER NOT NULL DEFAULT 0 CHECK (ended_observation_count >= 0),+ actor_user TEXT+);++INSERT INTO sessions_new (+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,+ summary_page_id, ended_observation_count, actor_user+)+SELECT+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,+ summary_page_id, ended_observation_count, actor_user+FROM sessions;++DROP TABLE sessions;++ALTER TABLE sessions_new RENAME TO sessions;++CREATE INDEX idx_sessions_recent ON sessions(workspace_id, project_id, started_at DESC);+CREATE INDEX idx_sessions_project ON sessions(project_id);+CREATE INDEX idx_sessions_started_at ON sessions(started_at DESC);+CREATE INDEX idx_sessions_scope_ended+ ON sessions(workspace_id, project_id, ended_at ASC)+ WHERE ended_at IS NOT NULL;+CREATE INDEX idx_sessions_open_owner+ ON sessions(workspace_id, project_id, agent_kind, actor_user)+ WHERE ended_at IS NULL;++CREATE TRIGGER sessions_ws_proj_pairing_ai+BEFORE INSERT ON sessions+FOR EACH ROW+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM projects WHERE id = NEW.project_id)+BEGIN+ SELECT RAISE(ABORT, 'sessions.workspace_id does not match the project''s workspace');+END;++CREATE TRIGGER auto_improve_scheduler_claims_session_pairing_ai+BEFORE INSERT ON auto_improve_scheduler_claims+FOR EACH ROW+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)+BEGIN+ SELECT RAISE(ABORT, 'auto_improve_scheduler_claims scope does not match the session scope');+END;++CREATE TRIGGER session_consolidation_jobs_session_pairing_ai+BEFORE INSERT ON session_consolidation_jobs+FOR EACH ROW+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)+BEGIN+ SELECT RAISE(ABORT, 'session_consolidation_jobs scope does not match the session scope');+END;++PRAGMA foreign_keys = ON;diff --git a/crates/ai-memory-store/src/migrations.rs b/crates/ai-memory-store/src/migrations.rsindex 1c1e424d..ba3e51e3 100644--- a/crates/ai-memory-store/src/migrations.rs+++ b/crates/ai-memory-store/src/migrations.rs@@ -733,6 +733,78 @@ mod tests {}}+ #[test]+ fn v49_to_v50_preserves_session_state_and_accepts_pool() {+ let mut conn = Connection::open_in_memory().unwrap();+ run_to(&mut conn, 49).unwrap();+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();+ let workspace_id = crate::ops::get_or_create_workspace(&mut conn, "default").unwrap();+ let project_id =+ crate::ops::get_or_create_project(&mut conn, &workspace_id, "project", None).unwrap();+ let existing = SessionId::new();+ conn.execute(+ "INSERT INTO sessions \+ (id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at, \+ ended_observation_count, actor_user) \+ VALUES (?1, ?2, ?3, 'command-code', '/repo', 1, 2, 7, 'user:alice')",+ params![+ existing.as_bytes(),+ workspace_id.as_bytes(),+ project_id.as_bytes(),+ ],+ )+ .unwrap();++ conn.pragma_update(None, "foreign_keys", "OFF").unwrap();+ run(&mut conn).unwrap();+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();++ let preserved: (String, String, i64, Option<String>) = conn+ .query_row(+ "SELECT agent_kind, cwd, ended_observation_count, actor_user \+ FROM sessions WHERE id = ?1",+ params![existing.as_bytes()],+ |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),+ )+ .unwrap();+ assert_eq!(+ preserved,+ (+ "command-code".into(),+ "/repo".into(),+ 7,+ Some("user:alice".into())+ )+ );++ crate::ops::begin_session(+ &mut conn,+ &NewSession {+ id: SessionId::new(),+ workspace_id,+ project_id,+ agent_kind: AgentKind::Pool,+ cwd: Some("/repo".into()),+ actor_user: Some("user:alice".into()),+ },+ )+ .unwrap();++ for name in [+ "idx_sessions_open_owner",+ "sessions_ws_proj_pairing_ai",+ "auto_improve_scheduler_claims_session_pairing_ai",+ "session_consolidation_jobs_session_pairing_ai",+ ] {+ let kind = if name.starts_with("idx_") {+ "index"+ } else {+ "trigger"+ };+ assert_eq!(schema_object_count(&conn, kind, name), 1, "missing {name}");+ }+ }+#[test]fn v48_to_v49_replaces_the_decay_tombstone_index_predicate() {let mut conn = Connection::open_in_memory().unwrap();diff --git a/docs/install.md b/docs/install.mdindex c429acf3..968a2e24 100644--- a/docs/install.md+++ b/docs/install.md@@ -9,7 +9,7 @@ path (docker + Claude Code). This page covers everything else:- [Arch Linux native packages (AUR)](#arch-linux-native-packages-aur)(systemd system service or user service)- [Configuring other agent CLIs](#configuring-other-agent-clis)- (Codex, Command Code, Devin CLI, OpenCode, OMP, Pi, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, Grok Build CLI, Zero, Kimi Code, Kiro CLI, OpenClaw, VS Code Copilot, Zed)+ (Codex, Command Code, Devin CLI, OpenCode, OMP, Pi, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, Grok Build CLI, Zero, Kimi Code, Kiro CLI, Pool, OpenClaw, VS Code Copilot, Zed)- [Installing hooks without docker](#installing-hooks-without-docker)(curl-based installer)- [Running ai-memory without docker](#running-ai-memory-without-docker)@@ -993,6 +993,48 @@ bare `ai-memory run` considers checkout-local sessions from both incompatiblestores. See[managed workstreams](managed-workstreams.md#native-adapter-behavior).+### Pool (Poolside Agent CLI)++Pool reads lifecycle hooks from a project-scoped `.poolside/settings.yaml` at+the root of each repository it runs in — there is no user-global hook file for+ai-memory to merge. `install-hooks --agent pool` (alias `poolside`) therefore+stages the hook scripts to the stable user-global location and prints a+ready-to-paste `hooks:` snippet; ai-memory deliberately does not write files+inside your repositories.++```bash+# Stage the scripts and print the snippet to paste into+# <repo>/.poolside/settings.yaml:+ai-memory install-hooks --agent pool --apply \+ --server-url "http://homelab:49374" \+ --auth-token "$TOKEN"+```++The snippet wires Pool's five documented events — `SessionStart`,+`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` (Claude-shaped+names, snake_case JSON payload on stdin, verified against Poolside CLI+v1.0.16). Local installs use the native `ai-memory hook` command, so Pool's+documented `tool_name`/`tool_input` file operations honor `[capture]+ignore_paths` and unknown file-tool payload shapes degrade to metadata-only+capture.++Pool has no true session-end event; `Stop` is a turn boundary. After the final+turn, close the session explicitly; use the exact id when several Pool+sessions are open in the same project:++```bash+ai-memory finalize-session --agent pool+ai-memory finalize-session --agent pool --session-id <uuid>+```++Pool tolerates hook stdout, but model-visible context injection from+`SessionStart` stdout is not demonstrated, so the session-start hook captures+only and never fetches the (single-use) handoff — recover a prior session's+handoff via the MCP `memory_handoff_accept` tool. No first-party+`install-mcp` client and no managed workstream (`ai-memory run pool`) are+claimed: Pool's native session-store contract is not demonstrated, per+[managed-harness contributions](managed-harness-contributions.md).+### OpenCode```bashdiff --git a/hooks/_lib.sh b/hooks/_lib.shindex cf90a0d7..198f4d79 100644--- a/hooks/_lib.sh+++ b/hooks/_lib.sh@@ -3,7 +3,7 @@# no bash-isms, no non-standard deps (no jq, no toml crate). Keep changes# byte-trivial because every supported agent (claude-code, codex,# cursor, gemini-cli, kimi-code, kiro-cli, antigravity-cli, opencode,-# omp) sources this same file.+# omp, pool) sources this same file.# Walk up from "$1" toward $HOME (or /) looking for `.ai-memory.toml`.# Prints the absolute path of the first marker found, or nothing.diff --git a/hooks/pool/post-tool-use.ps1 b/hooks/pool/post-tool-use.ps1new file mode 100644index 00000000..77640623--- /dev/null+++ b/hooks/pool/post-tool-use.ps1@@ -0,0 +1,3 @@+. "$PSScriptRoot\..\lib\ai-memory-hook.ps1"+Invoke-AiMemoryHook -Event "post-tool-use" -Agent "pool"+exit 0diff --git a/hooks/pool/post-tool-use.sh b/hooks/pool/post-tool-use.shnew file mode 100755index 00000000..d3fe5448--- /dev/null+++ b/hooks/pool/post-tool-use.sh@@ -0,0 +1,15 @@+#!/bin/sh+# Pool (Poolside Agent CLI) post-tool-use hook.+# Forwards the event JSON to the ai-memory server, fire-and-forget.+_lib_dir="$(dirname "$0")"+[ -f "$_lib_dir/_lib.sh" ] || _lib_dir="$_lib_dir/.."+. "$_lib_dir/_lib.sh"++SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"+PAYLOAD=$(cat)+CWD=$(ai_memory_extract_cwd "$PAYLOAD")+QS=$(ai_memory_marker_qs "$CWD")++printf '%s' "$PAYLOAD" \+ | ai_memory_post_hook "$SERVER/hook?event=post-tool-use&agent=pool${QS}" >/dev/null 2>&1 || true+exit 0diff --git a/hooks/pool/pre-tool-use.ps1 b/hooks/pool/pre-tool-use.ps1new file mode 100644index 00000000..2603a0b8--- /dev/null+++ b/hooks/pool/pre-tool-use.ps1@@ -0,0 +1,3 @@+. "$PSScriptRoot\..\lib\ai-memory-hook.ps1"+Invoke-AiMemoryHook -Event "pre-tool-use" -Agent "pool"+exit 0diff --git a/hooks/pool/pre-tool-use.sh b/hooks/pool/pre-tool-use.shnew file mode 100755index 00000000..15d8d6c7--- /dev/null+++ b/hooks/pool/pre-tool-use.sh@@ -0,0 +1,15 @@+#!/bin/sh+# Pool (Poolside Agent CLI) pre-tool-use hook.+# Forwards the event JSON to the ai-memory server, fire-and-forget.+_lib_dir="$(dirname "$0")"+[ -f "$_lib_dir/_lib.sh" ] || _lib_dir="$_lib_dir/.."+. "$_lib_dir/_lib.sh"++SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"+PAYLOAD=$(cat)+CWD=$(ai_memory_extract_cwd "$PAYLOAD")+QS=$(ai_memory_marker_qs "$CWD")++printf '%s' "$PAYLOAD" \+ | ai_memory_post_hook "$SERVER/hook?event=pre-tool-use&agent=pool${QS}" >/dev/null 2>&1 || true+exit 0diff --git a/hooks/pool/session-start.ps1 b/hooks/pool/session-start.ps1new file mode 100644index 00000000..f439b37c--- /dev/null+++ b/hooks/pool/session-start.ps1@@ -0,0 +1,7 @@+# Pool (Poolside Agent CLI) session-start hook.+# Capture only — Pool's SessionStart stdout injection is not demonstrated,+# so no -FetchHandoff: accepting a handoff is destructive and the context+# could be silently lost. Recover handoffs via MCP `memory_handoff_accept`.+. "$PSScriptRoot\..\lib\ai-memory-hook.ps1"+Invoke-AiMemoryHook -Event "session-start" -Agent "pool"+exit 0diff --git a/hooks/pool/session-start.sh b/hooks/pool/session-start.shnew file mode 100755index 00000000..1b1f1cf9--- /dev/null+++ b/hooks/pool/session-start.sh@@ -0,0 +1,19 @@+#!/bin/sh+# Pool (Poolside Agent CLI) SessionStart hook.+# Pool tolerates hook stdout, but model-visible context injection from+# SessionStart stdout is not demonstrated, so this hook captures the event+# only. Do NOT fetch /handoff here: accepting a handoff is destructive and+# an undelivered handoff would be silently lost. Recover a prior session's+# handoff via the MCP `memory_handoff_accept` tool instead.+_lib_dir="$(dirname "$0")"+[ -f "$_lib_dir/_lib.sh" ] || _lib_dir="$_lib_dir/.."+. "$_lib_dir/_lib.sh"++SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"+PAYLOAD=$(cat)+CWD=$(ai_memory_extract_cwd "$PAYLOAD")+QS=$(ai_memory_marker_qs "$CWD")++printf '%s' "$PAYLOAD" \+ | ai_memory_post_hook "$SERVER/hook?event=session-start&agent=pool${QS}" >/dev/null 2>&1 || true+exit 0diff --git a/hooks/pool/stop.ps1 b/hooks/pool/stop.ps1new file mode 100644index 00000000..427266c5--- /dev/null+++ b/hooks/pool/stop.ps1@@ -0,0 +1,3 @@+. "$PSScriptRoot\..\lib\ai-memory-hook.ps1"+Invoke-AiMemoryHook -Event "stop" -Agent "pool"+exit 0diff --git a/hooks/pool/stop.sh b/hooks/pool/stop.shnew file mode 100755index 00000000..c6059fac--- /dev/null+++ b/hooks/pool/stop.sh@@ -0,0 +1,15 @@+#!/bin/sh+# Pool (Poolside Agent CLI) stop hook.+# Forwards the event JSON to the ai-memory server, fire-and-forget.+_lib_dir="$(dirname "$0")"+[ -f "$_lib_dir/_lib.sh" ] || _lib_dir="$_lib_dir/.."+. "$_lib_dir/_lib.sh"++SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"+PAYLOAD=$(cat)+CWD=$(ai_memory_extract_cwd "$PAYLOAD")+QS=$(ai_memory_marker_qs "$CWD")++printf '%s' "$PAYLOAD" \+ | ai_memory_post_hook "$SERVER/hook?event=stop&agent=pool${QS}" >/dev/null 2>&1 || true+exit 0diff --git a/hooks/pool/user-prompt-submit.ps1 b/hooks/pool/user-prompt-submit.ps1new file mode 100644index 00000000..5d7ef004--- /dev/null+++ b/hooks/pool/user-prompt-submit.ps1@@ -0,0 +1,3 @@+. "$PSScriptRoot\..\lib\ai-memory-hook.ps1"+Invoke-AiMemoryHook -Event "user-prompt" -Agent "pool"+exit 0diff --git a/hooks/pool/user-prompt-submit.sh b/hooks/pool/user-prompt-submit.shnew file mode 100755index 00000000..19b4f3c7--- /dev/null+++ b/hooks/pool/user-prompt-submit.sh@@ -0,0 +1,15 @@+#!/bin/sh+# Pool (Poolside Agent CLI) user-prompt-submit hook.+# Forwards the event JSON to the ai-memory server, fire-and-forget.+_lib_dir="$(dirname "$0")"+[ -f "$_lib_dir/_lib.sh" ] || _lib_dir="$_lib_dir/.."+. "$_lib_dir/_lib.sh"++SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"+PAYLOAD=$(cat)+CWD=$(ai_memory_extract_cwd "$PAYLOAD")+QS=$(ai_memory_marker_qs "$CWD")++printf '%s' "$PAYLOAD" \+ | ai_memory_post_hook "$SERVER/hook?event=user-prompt&agent=pool${QS}" >/dev/null 2>&1 || true+exit 0