Skip to content

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.md
index 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 own
hooks, and the Claude Code hooks Cursor also runs, send Claude's
`tool_name`/`tool_input` fields, but Cursor was missing from the tool-capture
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 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.rs
index 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.md
index 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 a
resumed 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.md
index 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. |