Skip to content

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

Rust

fix(hooks): extend native session-id state file to ZCode

evanmaranzano4e8610043682
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f82367a3..a19f54b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- The native `ai-memory hook` session-id state file
+ (`<data_dir>/hook-state/<agent>-session-id`), introduced for Devin in #178,
+ now also covers ZCode. ZCode's hook payloads do not reliably carry a session
+ id, it fires `Stop` at the end of every turn, and it has no `SessionEnd`
+ event — without a persisted id, each turn with an id-less payload opened a
+ fresh server-side session that nothing ever closed (observed in production:
+ 4 sessions with NULL `ended_at` and 398 observations stuck in episodic).
+ ZCode events without a native id now share one stable stored id per agent
+ session; events carrying a native id are passed through untouched. The stored
+ id is cleared by `finalize-session --agent zcode` (which now also removes the
+ state file) or overwritten by the next `session-start`; `Stop` never clears
+ it. Other agents are unaffected: payloads that carry a session id short-circuit
+ the state file exactly as before.
+
+
## [2.2.1] - 2026-09-12
### Fixed
diff --git a/crates/ai-memory-cli/src/commands/finalize_session.rs b/crates/ai-memory-cli/src/commands/finalize_session.rs
index 4b41ac4e..2246cd41 100644
--- a/crates/ai-memory-cli/src/commands/finalize_session.rs
+++ b/crates/ai-memory-cli/src/commands/finalize_session.rs
@@ -88,6 +88,12 @@ pub async fn run(config: &Config, args: FinalizeSessionArgs) -> Result<()> {
finalized.push(session.session_id.clone());
}
+ // Agents with hook-maintained session state (ZCode: no SessionEnd event)
+ // keep a stored id in `<data_dir>/hook-state/<agent>-session-id`; once the
+ // session is finalized server-side, the stored id must go too, or the next
+ // agent session would inherit the closed id.
+ super::hook::clear_session_id(&config.data_dir, agent);
+
print_report(args, workspace, project, agent, finalized)
}
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index fd6ba9be..d3517d9f 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -153,7 +153,7 @@ fn store_session_id(data_dir: &Path, agent: AgentKind, session_id: &str) {
let _ = fs::write(path, session_id);
}
-fn clear_session_id(data_dir: &Path, agent: AgentKind) {
+pub(crate) fn clear_session_id(data_dir: &Path, agent: AgentKind) {
let _ = fs::remove_file(session_id_state_path(data_dir, agent));
}
@@ -250,6 +250,17 @@ fn payload_has_session_id(raw: &serde_json::Value) -> bool {
})
}
+/// Agents whose hook payloads do not reliably carry a session id. Devin's
+/// payloads may omit it; ZCode's do too (and ZCode fires `Stop` per turn with
+/// no SessionEnd, so without a persisted id each turn would fragment into a
+/// fresh server-side session). For these agents the hook maintains a
+/// `<data_dir>/hook-state/<agent>-session-id` file so a whole agent session
+/// shares one stable id. Agents whose payloads always carry an id never touch
+/// this path.
+fn agent_needs_session_id_state(agent_kind: AgentKind) -> bool {
+ matches!(agent_kind, AgentKind::Devin | AgentKind::Zcode)
+}
+
fn session_id_query_suffix(
data_dir: &Path,
agent: &str,
@@ -257,7 +268,7 @@ fn session_id_query_suffix(
raw: &serde_json::Value,
) -> String {
let agent_kind = AgentKind::from_wire(agent);
- if agent_kind != AgentKind::Devin || payload_has_session_id(raw) {
+ if !agent_needs_session_id_state(agent_kind) || payload_has_session_id(raw) {
return String::new();
}
@@ -651,6 +662,9 @@ where
"ai-memory hook warning: failed to spool lifecycle event; capture for this event was skipped"
);
}
+ // ZCode is intentionally absent here: it has no SessionEnd and fires Stop
+ // per turn, so its stored id is cleared by `finalize-session` (or
+ // overwritten by the next session-start), never by a hook event.
if AgentKind::from_wire(&args.agent) == AgentKind::Devin && args.event == "session-end" {
clear_session_id(&dd, AgentKind::Devin);
}
@@ -1548,7 +1562,7 @@ mod tests {
}
#[test]
- fn session_id_query_suffix_is_devin_only() {
+ fn session_id_query_suffix_is_opt_in_per_agent() {
let tmp = tempfile::tempdir().unwrap();
let raw = serde_json::json!({"hook_event_name": "PostToolUse"});
@@ -1558,6 +1572,60 @@ mod tests {
assert!(stored_session_id(tmp.path(), AgentKind::ClaudeCode).is_none());
}
+ #[test]
+ fn zcode_query_session_id_is_stable_across_turns_without_native_id() {
+ // ZCode fires Stop at the end of every turn and has no SessionEnd; the
+ // stored id must survive Stop so one agent session maps to one
+ // server-side session.
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path();
+ let bare = serde_json::json!({"hook_event_name": "SessionStart"});
+
+ let first = session_id_query_suffix(data_dir, "zcode", "session-start", &bare);
+ let after_stop = session_id_query_suffix(data_dir, "zcode", "stop", &bare);
+ let next_turn = session_id_query_suffix(data_dir, "zcode", "pre-tool-use", &bare);
+
+ assert!(first.starts_with("&session_id="), "{first}");
+ assert_eq!(after_stop, first);
+ assert_eq!(next_turn, first);
+ assert_eq!(
+ stored_session_id(data_dir, AgentKind::Zcode).as_deref(),
+ first.strip_prefix("&session_id=")
+ );
+ }
+
+ #[test]
+ fn zcode_query_session_id_does_not_override_native_payload_id() {
+ let tmp = tempfile::tempdir().unwrap();
+ let with_session = serde_json::json!({
+ "session_id": "zcode-native-session",
+ "hook_event_name": "PostToolUse"
+ });
+
+ let suffix = session_id_query_suffix(tmp.path(), "zcode", "post-tool-use", &with_session);
+
+ assert!(suffix.is_empty());
+ assert!(stored_session_id(tmp.path(), AgentKind::Zcode).is_none());
+ }
+
+ #[test]
+ fn zcode_stop_event_does_not_clear_stored_session_id() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path();
+ store_session_id(data_dir, AgentKind::Zcode, "stable-zcode-session");
+
+ // The only hook-side clearing is Devin's session-end; ZCode's stored
+ // id is cleared by `finalize-session` (or overwritten by the next
+ // session-start), never by Stop.
+ let bare = serde_json::json!({"hook_event_name": "Stop"});
+ let _ = session_id_query_suffix(data_dir, "zcode", "stop", &bare);
+
+ assert_eq!(
+ stored_session_id(data_dir, AgentKind::Zcode).as_deref(),
+ Some("stable-zcode-session")
+ );
+ }
+
#[test]
fn devin_missing_cwd_uses_devin_project_dir_before_process_cwd() {
let raw = serde_json::json!({