Skip to content

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.md
index 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.0
The fallback is unchanged and still serves hand-written pages and everything
written 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 counters
alongside the client spool section: events accepted, accepted-but-dropped
by capture policy, shed because ingest capacity was exhausted, shed by the
diff --git a/README.md b/README.md
index 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 Code
GitHub 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 - every
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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.rs
index 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.rs
index 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/a
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).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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.sql
new file mode 100644
index 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.rs
index 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.md
index 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 incompatible
stores. 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
```bash
diff --git a/hooks/_lib.sh b/hooks/_lib.sh
index 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.ps1
new file mode 100644
index 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 0
diff --git a/hooks/pool/post-tool-use.sh b/hooks/pool/post-tool-use.sh
new file mode 100755
index 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 0
diff --git a/hooks/pool/pre-tool-use.ps1 b/hooks/pool/pre-tool-use.ps1
new file mode 100644
index 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 0
diff --git a/hooks/pool/pre-tool-use.sh b/hooks/pool/pre-tool-use.sh
new file mode 100755
index 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 0
diff --git a/hooks/pool/session-start.ps1 b/hooks/pool/session-start.ps1
new file mode 100644
index 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 0
diff --git a/hooks/pool/session-start.sh b/hooks/pool/session-start.sh
new file mode 100755
index 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 0
diff --git a/hooks/pool/stop.ps1 b/hooks/pool/stop.ps1
new file mode 100644
index 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 0
diff --git a/hooks/pool/stop.sh b/hooks/pool/stop.sh
new file mode 100755
index 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 0
diff --git a/hooks/pool/user-prompt-submit.ps1 b/hooks/pool/user-prompt-submit.ps1
new file mode 100644
index 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 0
diff --git a/hooks/pool/user-prompt-submit.sh b/hooks/pool/user-prompt-submit.sh
new file mode 100755
index 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