Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(grok): install the first-turn rule into the hook file's Grok home only

AkitaOnRailsd869d27e8958
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e65afddd..52c8dbb9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,21 +53,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`vector_ms`, `graph_ms`, `observation_ms`, `rerank_ms`), summed over `scopes`.
Streams that did not run are left out, and a query without `explain` reads
no clock for them.
-- Grok Build CLI first-turn handoff: `install-hooks --agent grok --apply`
- and `install-skills --scope global --agent grok` write
- `$GROK_HOME/rules/ai-memory-handoff.md` (default `~/.grok/rules/ai-memory-handoff.md`)
- so the model calls `memory_handoff_list` on the first turn. Grok discards
- SessionStart stdout, so that list is the first tool and PostToolUse still
- claims the baton through GET `/handoff`. The rule names Grok's invocation —
- `use_tool` with the qualified catalog key `ai-memory__memory_handoff_list` —
- because Grok reaches MCP tools only through that meta-tool. The rule puts
- that call ahead of any file read and corrects `workspace`/`project` from
- `./.ai-memory.toml` only when the list comes back empty, so scope resolution
- neither consumes the turn nor leaves the current repository.
- Project-scope Grok skills and `--target-dir` leave the user rule alone.
- Unmanaged same-name files are refused without `--force`; `install-hooks`
- warns and keeps the hook file. `uninstall --only skills` and `--only hooks`
- remove the markered rule. (#1228)
+- Added a Grok Build CLI first-turn handoff rule. `install-hooks --agent grok
+ --apply` and `install-skills --scope global --agent grok` write
+ `$GROK_HOME/rules/ai-memory-handoff.md` (into the Grok home the hook file
+ was written to), which has the model call `memory_handoff_list` as its first
+ tool, through `use_tool` with the qualified key
+ `ai-memory__memory_handoff_list`, before reading any file. Grok discards
+ SessionStart stdout, so that call is what lets the first PostToolUse claim
+ the baton through GET `/handoff`. The rule corrects `workspace` and
+ `project` from the marker or git remote when the first list is empty or
+ answers with a scope error, and treats the handoff PostToolUse claimed as
+ authoritative. A same-name file without the managed marker is kept unless
+ `--force`; `uninstall --only hooks` or `--only skills` removes the managed
+ rule. (#1228)
- Added the end reason to session-end observations. When a harness's
`SessionEnd` payload carries a `reason` (Claude Code sends `clear`,
`logout`, `prompt_input_exit` or `other`), its first line is stored,
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index a032f803..9ded3fbf 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -817,7 +817,11 @@ pub(crate) fn run_with_opencode_dialect_and_mcp_path(
let hooks_dir =
resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
apply_to_grok_settings(&hooks_dir, &server_url, auth, &config.data_dir, &args)?;
- crate::commands::install_skills::install_grok_companions_after_hooks()
+ let hook_file = match &args.config_file {
+ Some(path) => path.clone(),
+ None => grok_hooks_path()?,
+ };
+ crate::commands::install_skills::install_grok_companions_after_hooks(&hook_file)
}
AgentChoice::Zero => apply_to_zero_hooks(&server_url, auth, &config.data_dir, &args),
AgentChoice::Zcode => apply_to_zcode_hooks(&server_url, auth, &config.data_dir, &args),
diff --git a/crates/ai-memory-cli/src/commands/install_skills.rs b/crates/ai-memory-cli/src/commands/install_skills.rs
index e3cc8856..5f079a0a 100644
--- a/crates/ai-memory-cli/src/commands/install_skills.rs
+++ b/crates/ai-memory-cli/src/commands/install_skills.rs
@@ -77,20 +77,44 @@ pub(super) fn prepare_install(args: &InstallSkillsArgs) -> Result<PreparedInstal
}
/// After `install-hooks --agent grok --apply` writes the hook file, also
-/// install the always-on first-turn rule and, best-effort, the global Grok
-/// routing skills. Unmanaged same-name files are skipped with a warning so a
-/// user-authored skill or rule cannot fail the hook install.
-pub(super) fn install_grok_companions_after_hooks() -> Result<()> {
- match install_mcp::grok_home() {
- Ok(home) => install_grok_companions_in(&home, false),
- Err(err) => {
- eprintln!("[ai-memory] warning: skipped Grok first-turn companions: {err}");
+/// install the always-on first-turn rule, which the hook's first turn relies
+/// on. An unmanaged same-name file is skipped with a warning so a
+/// user-authored rule cannot fail the hook install. The global Grok skills are
+/// `install-skills --scope global --agent grok`'s job, so `uninstall --only
+/// hooks` removes everything this writes.
+///
+/// The companions go into the Grok home the hook file was written to, never
+/// the process `GROK_HOME`: a relocated home (`ai-memory run grok --env
+/// GROK_HOME=...`, or `--config-file`) must receive them, and a confined
+/// install must not write outside it. A hook file outside the
+/// `<grok home>/hooks/ai-memory.json` layout names no home, so the companions
+/// are skipped with a note.
+pub(super) fn install_grok_companions_after_hooks(hook_file: &Path) -> Result<()> {
+ match grok_home_of_hook_file(hook_file) {
+ Some(home) => {
+ install_grok_rule_in(home, false);
+ Ok(())
+ }
+ None => {
+ eprintln!(
+ "[ai-memory] note: skipped the Grok first-turn rule: {} is not \
+ <grok home>/hooks/ai-memory.json, so it names no Grok home",
+ hook_file.display()
+ );
Ok(())
}
}
}
-pub(super) fn install_grok_companions_in(grok_home: &Path, force: bool) -> Result<()> {
+/// The Grok home a hook file at `<home>/hooks/ai-memory.json` belongs to.
+fn grok_home_of_hook_file(hook_file: &Path) -> Option<&Path> {
+ let hooks_dir = hook_file.parent()?;
+ (hook_file.file_name()? == "ai-memory.json" && hooks_dir.file_name()? == "hooks")
+ .then(|| hooks_dir.parent())
+ .flatten()
+}
+
+fn install_grok_rule_in(grok_home: &Path, force: bool) {
let rule_path = grok_handoff_rule_destination(grok_home);
match write_grok_handoff_rule(&rule_path, force) {
Ok(outcome) => {
@@ -105,15 +129,6 @@ pub(super) fn install_grok_companions_in(grok_home: &Path, force: bool) -> Resul
eprintln!("[ai-memory] warning: skipped Grok first-turn handoff rule: {err}");
}
}
-
- let roots = vec![TargetRoot::new(grok_home.join(SKILLS_DIR))];
- match install_managed_skills(&roots, force) {
- Ok(reports) => print_reports(reports),
- Err(err) => {
- eprintln!("[ai-memory] warning: skipped global Grok skills: {err}");
- }
- }
- Ok(())
}
fn grok_handoff_rule_destination(grok_home: &Path) -> PathBuf {
@@ -395,6 +410,7 @@ fn agent_root(
Ok(base.join(agent_dir).join(SKILLS_DIR))
}
+#[cfg(test)]
fn install_managed_skills(roots: &[TargetRoot], force: bool) -> Result<Vec<InstallReport>> {
let plans = skill_file_plans(roots);
validate_overwrite_safety(&plans, force)?;
@@ -473,29 +489,36 @@ fn validate_rule_overwrite(path: &Path, force: bool) -> Result<()> {
}
fn print_install_plan(roots: &[TargetRoot], grok_handoff_rule: Option<PathBuf>) {
+ print!("{}", render_install_plan(roots, grok_handoff_rule));
+}
+
+fn render_install_plan(roots: &[TargetRoot], grok_handoff_rule: Option<PathBuf>) -> String {
+ use std::fmt::Write as _;
+ let mut out = String::new();
+ let push_file = |out: &mut String, content: &str| {
+ out.push_str(content);
+ if !content.ends_with('\n') {
+ out.push('\n');
+ }
+ out.push('\n');
+ };
for root in roots {
- println!("# Skill root: {}\n", root.path.display());
+ let _ = writeln!(out, "# Skill root: {}\n", root.path.display());
for skill in MANAGED_SKILLS {
let path = root.path.join(skill.relative_path);
- println!("# Would write: {}\n", path.display());
- print!("{}", skill.content);
- if !skill.content.ends_with('\n') {
- println!();
- }
- println!();
+ let _ = writeln!(out, "# Would write: {}\n", path.display());
+ push_file(&mut out, skill.content);
}
}
if let Some(path) = grok_handoff_rule {
- println!(
+ let _ = writeln!(
+ out,
"# Would write Grok first-turn handoff rule: {}\n",
path.display()
);
- print!("{GROK_HANDOFF_RULE_CONTENT}");
- if !GROK_HANDOFF_RULE_CONTENT.ends_with('\n') {
- println!();
- }
- println!();
+ push_file(&mut out, GROK_HANDOFF_RULE_CONTENT);
}
+ out
}
fn outcome_detail(outcome: ApplyOutcome) -> &'static str {
@@ -973,32 +996,37 @@ mod tests {
);
}
+ /// The hook install writes the first-turn rule into the Grok home its
+ /// hook file belongs to, and nothing else: no global skills, so
+ /// `uninstall --only hooks` takes back all of it.
#[test]
- fn grok_companions_keep_hooks_when_unmanaged_skills_exist() {
+ fn grok_hook_install_writes_only_the_rule_beside_its_hook_file() {
let tmp = tempfile::tempdir().unwrap();
- let grok_home = tmp.path();
- let unmanaged = grok_home.join("skills/ai-memory-retrieval/SKILL.md");
- fs::create_dir_all(unmanaged.parent().unwrap()).unwrap();
- fs::write(
- &unmanaged,
- "---\nname: ai-memory-retrieval\n---\nuser skill\n",
- )
- .unwrap();
+ let grok_home = tmp.path().join("relocated-grok");
+ let hook_file = grok_home.join("hooks").join("ai-memory.json");
- install_grok_companions_in(grok_home, false).unwrap();
+ install_grok_companions_after_hooks(&hook_file).unwrap();
- let rule_path = grok_handoff_rule_destination(grok_home);
assert!(
- fs::read_to_string(&rule_path)
+ fs::read_to_string(grok_handoff_rule_destination(&grok_home))
.unwrap()
- .contains(GROK_HANDOFF_RULE_MARKER),
- "the first-turn rule is the primary companion and must still land"
- );
- assert_eq!(
- fs::read_to_string(&unmanaged).unwrap(),
- "---\nname: ai-memory-retrieval\n---\nuser skill\n"
+ .contains(GROK_HANDOFF_RULE_MARKER)
);
- assert!(!grok_home.join("skills/ai-memory-handoff/SKILL.md").exists());
+ assert!(!grok_home.join(SKILLS_DIR).exists(), "no global skills");
+ }
+
+ /// A hook file outside `<home>/hooks/ai-memory.json` names no Grok home,
+ /// so nothing is written beside it or anywhere else.
+ #[test]
+ fn grok_hook_file_outside_the_layout_installs_no_rule() {
+ let tmp = tempfile::tempdir().unwrap();
+ let hook_file = tmp.path().join("custom").join("grok-hooks.json");
+
+ install_grok_companions_after_hooks(&hook_file).unwrap();
+
+ assert_eq!(grok_home_of_hook_file(&hook_file), None);
+ assert!(!tmp.path().join("rules").exists());
+ assert!(!tmp.path().join("custom").join("rules").exists());
}
#[test]
@@ -1006,19 +1034,13 @@ mod tests {
let tmp = tempfile::tempdir().unwrap();
let roots = vec![TargetRoot::new(tmp.path().join("skills"))];
let rule = grok_handoff_rule_destination(tmp.path());
- print_install_plan(&roots, Some(rule.clone()));
- // Function prints to stdout; the path and payload are what matter for
- // --print callers. Re-check the bytes it would dump.
- assert!(GROK_HANDOFF_RULE_CONTENT.contains(GROK_HANDOFF_RULE_MARKER));
- assert_eq!(
- rule.file_name().and_then(|name| name.to_str()),
- Some("ai-memory-handoff.md")
- );
- assert_eq!(
- rule.parent()
- .and_then(|parent| parent.file_name())
- .and_then(|name| name.to_str()),
- Some("rules")
- );
+ let plan = render_install_plan(&roots, Some(rule.clone()));
+ assert!(plan.contains(&format!(
+ "# Would write Grok first-turn handoff rule: {}",
+ rule.display()
+ )));
+ assert!(plan.contains(GROK_HANDOFF_RULE_MARKER));
+ // Without a rule path (project scope, --target-dir) the plan names none.
+ assert!(!render_install_plan(&roots, None).contains("first-turn handoff rule:"));
}
}
diff --git a/crates/ai-memory-core/src/routing_skills.rs b/crates/ai-memory-core/src/routing_skills.rs
index 80f05d58..8c3125e8 100644
--- a/crates/ai-memory-core/src/routing_skills.rs
+++ b/crates/ai-memory-core/src/routing_skills.rs
@@ -39,7 +39,7 @@ pub const HERMES_SKILL_DIR: &str = ".hermes";
pub const SKILLS_DIR: &str = "skills";
const RETRIEVAL_DESCRIPTION: &str = "Use this skill for any request whose goal is read-only retrieval from ai-memory: project history, prior context, decisions, rules, gotchas, recent activity, full wiki pages, or status/briefing. Trigger by semantic intent rather than exact wording, including when ai-memory is not named.";
-const HANDOFF_DESCRIPTION: &str = "Use this skill for any request whose goal is session continuity across agents or time: finding a pending handoff, resuming previous work, saving next-session context, wrapping up, or discarding a mistaken handoff. On Grok, the first turn with no visible handoff should call memory_handoff_list before answering. Trigger by semantic intent rather than exact wording.";
+const HANDOFF_DESCRIPTION: &str = "Use this skill for any request whose goal is session continuity across agents or time: finding a pending handoff, resuming previous work, saving next-session context, wrapping up, or discarding a mistaken handoff. Trigger by semantic intent rather than exact wording.";
const MESSAGING_DESCRIPTION: &str = "Use this skill for cross-project agent-to-agent messaging: sending a request to another project's inbox, checking or popping this project's inbox, or retracting a message you sent. Trigger by semantic intent (delegate to another repo, check my inbox, tell the other agent) rather than exact wording.";
const DURABLE_PAGES_DESCRIPTION: &str = "Use this skill for any explicit wiki mutation in ai-memory: saving durable or time-bounded project knowledge, recording a rule or annotation, updating a note, or deleting a memory page. Trigger by semantic intent rather than exact wording; routine session capture is not a durable-page request.";
const LEARNING_MAINTENANCE_DESCRIPTION: &str = "Use this skill for any ai-memory knowledge-base maintenance request: consolidating observations, reviewing session lessons, proposing durable learnings, auditing or linting the wiki, finding contradictions, pruning stale memory, or running auto-improvement. Trigger by semantic intent rather than exact wording.";
@@ -338,6 +338,11 @@ mod tests {
.contains("Do not call `memory_handoff_accept` as the first tool")
);
assert!(GROK_HANDOFF_RULE_CONTENT.contains("empty `handoffs` array"));
+ // A guessed project that does not exist answers with a scope error,
+ // not an empty list; the correction must fire on that too.
+ assert!(GROK_HANDOFF_RULE_CONTENT.contains("or a scope error"));
+ // The baton PostToolUse claimed is authoritative over listed rows.
+ assert!(GROK_HANDOFF_RULE_CONTENT.contains("it wins"));
}
#[test]
diff --git a/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md b/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md
index 0fd965c4..3d5300a0 100644
--- a/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md
+++ b/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md
@@ -1,6 +1,6 @@
---
name: ai-memory-handoff
-description: "Use this skill for any request whose goal is session continuity across agents or time: finding a pending handoff, resuming previous work, saving next-session context, wrapping up, or discarding a mistaken handoff. On Grok, the first turn with no visible handoff should call memory_handoff_list before answering. Trigger by semantic intent rather than exact wording."
+description: "Use this skill for any request whose goal is session continuity across agents or time: finding a pending handoff, resuming previous work, saving next-session context, wrapping up, or discarding a mistaken handoff. Trigger by semantic intent rather than exact wording."
---
<!-- ai-memory-managed: routing-skill -->
@@ -21,8 +21,6 @@ The SessionStart hook usually fetches and consumes any pending handoff before th
If no pending handoff block is visible, inspect with `memory_handoff_list` first. Listing does not claim or expire anything. When the user asks where we left off, claim one listed row with `memory_handoff_accept` and that `handoff_id`, using the client-aware project scope below. Do not treat list as a second accept path.
-On Grok Build CLI, SessionStart and UserPromptSubmit never inject a handoff (Grok discards that stdout). The first PostToolUse claims the pending row through GET `/handoff` and injects `additionalContext`. On the first turn, when no handoff block or additionalContext is visible, call `memory_handoff_list` as the first tool, before reading any file, so that PostToolUse can claim the baton on that call; do not call `memory_handoff_accept` first (that races the hook). Grok reaches MCP tools only through its `use_tool` meta-tool, so invoke it with `tool_name` set to the qualified catalog key `ai-memory__memory_handoff_list` (or `<server>__memory_handoff_list` when the server was registered under another name) instead of spending the turn on `search_tool`. Grok is a static MCP client, so that call carries `workspace` and `project` together, as in Project scope below; for this first call fill them from what the session context already shows — `workspace` `default` and the current directory's basename — rather than spending a tool call on scope. Only when the list comes back empty, resolve the names properly as in Project scope and list once more. Recap from the list payload plus any additionalContext that arrives with the tool result. An empty corrected list means nothing is pending; continue with the user's request.
-
## Creating a handoff
Create a handoff only at session end or when the user explicitly asks to save context for the next session. Do not use handoffs for status checks, briefings, project notes, or permanent memory. Keep the summary to two or three concise sentences, and put details in open questions and next steps bullets.
diff --git a/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md b/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md
index 9e1fab82..020cca8c 100644
--- a/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md
+++ b/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md
@@ -10,9 +10,9 @@ When this is the first model turn of the session and no pending-handoff block or
1. Call `memory_handoff_list` as the first tool, before reading any file, through `use_tool` with `tool_name` set to the qualified catalog key `ai-memory__memory_handoff_list` and the arguments in `tool_input`. Grok reaches MCP tools only through that meta-tool, so the bare name is not callable. The key is given here: do not spend the turn on `search_tool`. When this server was registered in `config.toml` under another name, the key is `<server>__memory_handoff_list`. Listing is read-only and does not claim or expire anything, so making this call first costs nothing when the scope turns out to be wrong.
2. Grok is a static MCP client, so that call carries `workspace` and `project` together in `tool_input`. Both are names, never filesystem paths. Fill them from what the session context already shows, without spending a tool call on it: `workspace` is `default` unless the context names another one, and `project` is the basename of the current working directory.
-3. Only when that list returns an empty `handoffs` array, resolve the real names and list once more: read `./.ai-memory.toml` when it declares them, otherwise take the project from normalized `upstream`, then `origin`, using the full repository path without its host (`github.com/acme/api` → `acme-api`), and keep the basename when no valid remote exists. Resolve this from the current repository alone — do not search the filesystem for another project's marker, and never rely on the server's last active project.
+3. Only when that list returns an empty `handoffs` array or a scope error (such as no project by that name), resolve the real names and list once more: read `./.ai-memory.toml` when it declares them, otherwise take the project from normalized `upstream`, then `origin`, using the full repository path without its host (`github.com/acme/api` → `acme-api`), and keep the basename when no valid remote exists. Resolve this from the current repository alone — do not search the filesystem for another project's marker, and never rely on the server's last active project.
4. Do not call `memory_handoff_accept` as the first tool. Accepting first races the PostToolUse GET `/handoff` claim.
-5. After a list returns, recap from that payload plus any `additionalContext` that arrives with the tool result. Then continue with the user's request.
+5. After a list returns, recap from that payload plus any `additionalContext` that arrives with the tool result. A handoff in that `additionalContext` is the one PostToolUse claimed for this session: when it differs from the listed rows, it wins. Then continue with the user's request.
6. When the corrected list is empty too, nothing is pending. Continue with the user's request.
When a pending-handoff block or `additionalContext` handoff is already visible, answer from that block. Do not list or accept again.
diff --git a/docs/install.md b/docs/install.md
index 303ba1d0..a7d238f9 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1768,7 +1768,7 @@ also writes `$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls
meta-tool, so the rule hands the model the qualified catalog key
`ai-memory__memory_handoff_list` instead of leaving it to `search_tool`. That
call comes before any file read, and the rule corrects `workspace`/`project`
-from `./.ai-memory.toml` only when the list comes back empty. The
+from `./.ai-memory.toml` only when the list comes back empty or with a scope error. The
first `PostToolUse` prints
`hookSpecificOutput.additionalContext` (pending handoff, plus an opted-in
`[briefing]`). The model sees it after that tool result. A session with no
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index d5151928..685430d4 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -1021,7 +1021,7 @@ so those events do not accept the handoff. `--apply` also writes
so the first turn calls `memory_handoff_list` through `use_tool` with the
qualified catalog key `ai-memory__memory_handoff_list` (Grok exposes MCP tools
only through that meta-tool), before any file read, and corrects the scope from
-`./.ai-memory.toml` only when that list is empty; PostToolUse then claims the
+`./.ai-memory.toml` only when that list is empty or a scope error; PostToolUse then claims the
row.
**Config file:** `install-mcp --client grok --apply` writes the user config at
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 65691eec..9cafeebe 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -33,7 +33,7 @@
| Claude Desktop (Code tab) | Supported | Local Code-tab sessions run Claude Code with the user's `~/.claude/settings.json`, so the Claude Code hooks capture them as `claude-code`; a session without a project folder lands in its own scratch-directory project. |
| OpenClaw | Supported | MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions. |
| 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). `install-hooks --agent grok --apply` and `install-skills --scope global --agent grok` also write `$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls `memory_handoff_list` through `use_tool` with the qualified catalog key `ai-memory__memory_handoff_list` (Grok reaches MCP tools only through that meta-tool) ahead of any file read, correcting `workspace`/`project` from `./.ai-memory.toml` only when that list is empty; the first `PostToolUse` then prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`. If that rule is absent and 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`). |
+| 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). `install-hooks --agent grok --apply` and `install-skills --scope global --agent grok` also write `$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls `memory_handoff_list` through `use_tool` with the qualified catalog key `ai-memory__memory_handoff_list` (Grok reaches MCP tools only through that meta-tool) ahead of any file read, correcting `workspace`/`project` from `./.ai-memory.toml` only when that list is empty or a scope error; the first `PostToolUse` then prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`. If that rule is absent and 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 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; `sessionEnd` then delivers in-process within a fixed 10-second budget, since the sandbox kills detached drainers), 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. |
diff --git a/docs/usage.md b/docs/usage.md
index e0d5e2d7..cfcb05f2 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -47,7 +47,7 @@ and `install-skills --scope global --agent grok` write
spells out Grok's invocation — `use_tool` with the qualified catalog key
`ai-memory__memory_handoff_list` — because Grok reaches MCP tools only through
that meta-tool, and puts that call ahead of any file read, correcting
-`workspace`/`project` from `./.ai-memory.toml` only when the list is empty.
+`workspace`/`project` from `./.ai-memory.toml` only when the list is empty or a scope error.
Until that
tool runs, or if the rule is absent and the session never calls a tool, call
`memory_handoff_list` then `memory_handoff_accept` with the listed