Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(zero): explain that Zero's sandbox keeps hook events spooled
AkitaOnRailsecbe1e251653
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b43a8edc..3d42ab25 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Fixed+- Documented that Zero runs hook commands inside its sandbox, whose default+ policy blocks network (loopback included) and writes outside the+ workspace, so hook events stay in the spool instead of reaching the+ server. The `install-hooks --agent zero` and `setup-agent` notes and the+ Zero install docs now name the global `~/.config/zero/config.json`+ `sandbox` keys that allow delivery, their tradeoff, and the+ `ai-memory hook-drain` fallback. (#1172)- Fixed Cursor tool calls being stored with no title or content: Cursor's ownhooks, and the Claude Code hooks Cursor also runs, send Claude's`tool_name`/`tool_input` fields, but Cursor was missing from the tool-capturediff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex ed236460..edb4f644 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -6341,12 +6341,34 @@ fn apply_to_zero_hooks(re-enable them.");}- println!("# NOTE: Zero discards sessionStart hook stdout — capture works, but");- println!("# handoff injection does not. Recover a prior session's handoff");- println!("# via the MCP `memory_handoff_accept` tool.");+ print!("{}", zero_install_notes(data_dir.display()));Ok(())}+/// Caveats printed after both the Zero dry-run and `--apply` (#1172).+/// Zero runs hook commands inside its execution sandbox, which by+/// default denies all network (loopback included), keeps `/` read-only+/// outside the workspace and temp, and kills a hook's detached children+/// when it exits. Only the user's global Zero config can relax that, and+/// ai-memory must not edit it, so the note names the keys instead.+pub(crate) fn zero_install_notes(data_dir: impl std::fmt::Display) -> String {+ format!(+ "# NOTE: Zero discards sessionStart hook stdout — capture works, but\n\+ # handoff injection does not. Recover a prior session's handoff\n\+ # via the MCP `memory_handoff_accept` tool.\n\+ # NOTE: Zero runs hooks inside its sandbox, which by default blocks all\n\+ # network (127.0.0.1 too) and writes outside the workspace, so\n\+ # events stay in the hook spool instead of reaching the server.\n\+ # To deliver live, set in the global ~/.config/zero/config.json:\n\+ # \"sandbox\": {{\"network\": \"allow\",\n\+ # \"additionalWriteRoots\": [\"{}\"]}}\n\+ # (network allow applies to every Zero shell command), or\n\+ # \"sandbox\": {{\"enabled\": false}}. Otherwise run `ai-memory\n\+ # hook-drain` from a normal shell to deliver spooled events.\n",+ data_dir+ )+}+/// Print Zero's hooks.json to stdout (dry-run counterpart of/// [`apply_to_zero_hooks`]).fn render_zero(@@ -6371,9 +6393,7 @@ fn render_zero(println!("# Auth: token embedded in each hook's args below.");println!("# Treat hooks.json as sensitive (chmod 600).");}- println!("# NOTE: Zero discards sessionStart hook stdout — capture works, but");- println!("# handoff injection does not. Recover a prior session's handoff");- println!("# via the MCP `memory_handoff_accept` tool.");+ print!("{}", zero_install_notes(data_dir.display()));println!();println!("{serialized}");Ok(())@@ -8278,6 +8298,24 @@ command = "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/a);}+ // Issue #1172: Zero runs hooks in its sandbox (no network, read-only+ // `/`), so the install note must say how events get delivered.+ #[test]+ fn zero_install_notes_explain_the_hook_sandbox() {+ let notes = zero_install_notes(Path::new("/data/ai-memory").display());+ assert!(notes.contains("sessionStart"), "{notes}");+ assert!(notes.contains("sandbox"), "{notes}");+ assert!(notes.contains("~/.config/zero/config.json"), "{notes}");+ assert!(notes.contains(r#""network": "allow""#), "{notes}");+ assert!(+ notes.contains(r#""additionalWriteRoots": ["/data/ai-memory"]"#),+ "{notes}"+ );+ assert!(notes.contains(r#""enabled": false"#), "{notes}");+ assert!(notes.contains("hook-drain"), "{notes}");+ assert!(notes.lines().all(|l| l.starts_with('#')), "{notes}");+ }+#[test]fn zcode_hooks_config_covers_all_events_with_strict_entries() {let payload = super::super::render_shared::build_zcode_hooks_config(diff --git a/crates/ai-memory-cli/src/commands/setup_agent.rs b/crates/ai-memory-cli/src/commands/setup_agent.rsindex 757d6f0e..e29a52a4 100644--- a/crates/ai-memory-cli/src/commands/setup_agent.rs+++ b/crates/ai-memory-cli/src/commands/setup_agent.rs@@ -236,9 +236,10 @@ fn emit_zero(args: &SetupAgentArgs) -> Result<()> {if args.auth_token.is_some() {println!("# Treat hooks.json as sensitive (chmod 600).");}- println!("# NOTE: Zero discards sessionStart stdout, so this config captures");- println!("# but does not inject handoffs; recover them via the MCP");- println!("# `memory_handoff_accept` tool.");+ print!(+ "{}",+ super::install_hooks::zero_install_notes("<ai-memory data dir>")+ );println!();println!("{serialized}");Ok(())diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 46f06fd9..cc27743d 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -786,6 +786,28 @@ capture and session-end handoff *creation* work, but handoff *injection*does not — ask Zero to call `memory_handoff_accept` at the start of aresumed session.+Zero runs hook commands inside its execution sandbox. The default policy+denies all network, loopback included (a separate network namespace on+Linux, `(deny network*)` on macOS), mounts `/` read-only with writes limited+to the workspace and temp, and kills a hook's detached children when the+hook exits. Hooks therefore cannot reach `server_url`: events land in+`<data_dir>/hook-spool/` and stay there. Zero only lets the user's global+`~/.config/zero/config.json` relax this (a project config can only tighten+it), and ai-memory does not edit that file. Either add++```json+"sandbox": {+ "network": "allow",+ "additionalWriteRoots": ["<ai-memory data dir>"]+}+```++(network access is all-or-nothing and applies to every shell command Zero+runs, not only hooks), or set `"sandbox": {"enabled": false}`. Without+either, run `ai-memory hook-drain` from a normal shell to deliver the+spooled events. A leftover empty `hook-spool/.drain.lock` does not block+that drain: the lock is an OS file lock released when its holder exits.+## ZCode (z.ai)**Status:** MCP supported. Lifecycle hooks are not installed by this command;diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 515354c5..d9fdb92c 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -30,7 +30,7 @@| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). Only `PreInvocation` with `invocationNum = 0` maps to SessionStart; later model calls cannot consume a next-session handoff. No automatic true session-end hook, so run `ai-memory finalize-session --agent antigravity-cli` after the final turn when you need a summary, handoff, and opt-in SessionEnd consolidation; an interactive session launched with `ai-memory run antigravity` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; its conversation store is not decoded, so the ledger takes user prompts from `agy`'s `history.jsonl` (only this conversation's lines typed in this checkout) and assistant and tool steps from hook capture. Tool outputs (`run_command`, `view_file`, `list_dir`, etc.) are resolved directly from `.system_generated/steps/<stepIdx>/output.txt` during `post-tool-use` while mutation tools preserve code from arguments (#966). || Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works. `SessionStart` and `UserPromptSubmit` do not accept the handoff (Grok discards that stdout). The first `PostToolUse` prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`; the model sees it after that tool result. If no tool runs, recover via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. `ai-memory run grok` adds managed workstream resume with the context packet delivered natively through `--rules`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). || Swival CLI | MCP-only | `install-mcp --client swival --apply` merges a native HTTP entry into the project-root `.swival/mcp.json`, preserving sibling servers. Lifecycle and managed-workstream support are not claimed because Swival's callback contract does not expose a stable session identifier. |-| 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_list` then `memory_handoff_accept` with that `handoff_id`. |+| 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_list` then `memory_handoff_accept` with that `handoff_id`. Zero runs hooks in its sandbox, which by default denies network (loopback too) and writes outside the workspace, so events stay in the hook spool: allow `sandbox.network` and add the ai-memory data dir to `sandbox.additionalWriteRoots` in the global `~/.config/zero/config.json` (network allow covers every Zero shell command), or run `ai-memory hook-drain` from a normal shell (see [`mcp-install.md`](mcp-install.md#zero-gitlawbzero)). || ZCode | Supported | `install-mcp --client zcode --apply` merges a native HTTP entry (strict schema: `type`/`url`/`headers` only) into the `mcp.servers` map of `~/.zcode/cli/config.json`, preserving sibling servers. ZCode (z.ai, `zcode`, alias `zai`). Lifecycle-hook capture via `install-hooks --agent zcode --apply`: exec-form native commands (`type: "process"`, no shell) merged into the root `hooks` block of `~/.zcode/cli/config.json` around any third-party hooks; native commands enforce capture exclusions. Six documented triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`); `PostToolUseFailure` fires instead of `PostToolUse` when a tool throws and lands on the same capture channel with the error preserved. `PermissionRequest` is deliberately not installed — its hook chain races the interactive permission client, so passive capture of that event is unreliable by design. No true session-end — `Stop` is a per-turn boundary, so run `ai-memory finalize-session --agent zcode` after the final turn. Unlike Pool and Zero, `SessionStart` stdout injection works (`hookSpecificOutput.additionalContext`, verified live against the embedded engine v0.16.5), so the prior session's handoff is delivered automatically. No first-party `install-mcp` client and no managed workstream are claimed yet. || 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, unless it is an interactive session launched with `ai-memory run kiro`, which finalizes it automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |