Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: keep stale hook tails from stealing active scope
AkitaOnRailse6735202d433
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a140f379..bb1d4cda 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -29,6 +29,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0operator is still unreachable without `--all-owners`, same as the defaultquery ([#374]).+### Fixed+- Prevented delayed post-tool and shutdown hook tails from redirecting the+ shared active-project fallback after work moved to another project. Only+ session starts, user prompts, and pre-tool events now advance shared or+ identity-only fallbacks; other events refresh exact session mappings, and+ dropped-subagent preflight no longer publishes scope (#372).+## [1.24.0] - 2026-08-04### Addeddiff --git a/crates/ai-memory-core/src/active_project.rs b/crates/ai-memory-core/src/active_project.rsindex 71352569..8e3aaae5 100644--- a/crates/ai-memory-core/src/active_project.rs+++ b/crates/ai-memory-core/src/active_project.rs@@ -5,15 +5,17 @@//! The MCP protocol carries no working-directory context: a `memory_query`//! call arrives with its arguments and nothing else, so a tool handler has//! no way to know which project the agent is sitting in. The lifecycle hooks-//! *do* know — every `/hook` event carries the agent's `cwd`, and the hook+//! *do* know — lifecycle `/hook` events carry the agent's `cwd`, and the hook//! router resolves it to the correct per-cwd `(workspace_id, project_id)`.//!//! In HTTP mode the `/hook` ingress and the `/mcp` endpoint live in the same//! process, so the hook router can publish "the project the user is currently-//! active in" to this shared pointer, and the MCP tools can read it as their-//! default instead of falling back to the server's static `--project` (which-//! defaults to `scratch` and made the read tools return empty memory even-//! when the hooks were correctly populating a real project).+//! active in" to this shared pointer when work starts or advances, and the MCP+//! tools can read it as their default instead of falling back to the server's+//! static `--project` (which defaults to `scratch` and made the read tools+//! return empty memory even when the hooks were correctly populating a real+//! project). Completion events refresh exact actor-scoped entries only; a+//! delayed tail from an older session must not redirect a shared fallback.//!//! ## Isolation modes//!@@ -362,6 +364,38 @@ impl ActiveProject {);}+ /// Refresh only the exact actor-scoped entry without advancing either+ /// fallback slot.+ ///+ /// Hook completion events use this path so an exact `per_session` or+ /// `per_actor` caller keeps a fresh mapping, while a delayed tail from an+ /// older session cannot redirect the process-wide single slot or the+ /// identity-only fallback used by a caller with no session coordinate.+ /// `Single` mode and actors without a usable coordinate are no-ops.+ pub fn set_scoped_for(+ &self,+ actor: &ActorKey,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ default_global: bool,+ ) {+ if self.mode == ActiveProjectMode::Single || actor.is_empty() {+ return;+ }+ let scoped = self.scoped_key(actor);+ if scoped.is_empty() {+ return;+ }+ let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());+ guard.insert(+ scoped,+ workspace_id,+ project_id,+ default_global,+ Instant::now(),+ );+ }+/// Read the currently active project for the given actor, if any has/// been published yet. Falls back to the single slot only when:/// - the mode is `Single`, or@@ -733,6 +767,48 @@ mod tests {assert_eq!(ap.get_for(&sess_b), Some((ws, p_b)));}+ #[test]+ fn scoped_refresh_does_not_advance_single_fallback() {+ let ap = ActiveProject::with_mode(ActiveProjectMode::PerSession);+ let ws = WorkspaceId::new();+ let foreground = key_session("foreground");+ let stale = key_session("stale");+ let foreground_project = ProjectId::new();+ let stale_project = ProjectId::new();++ ap.set_for(&foreground, ws, foreground_project, true);+ ap.set_scoped_for(&stale, ws, stale_project, false);++ assert_eq!(ap.get(), Some((ws, foreground_project)));+ assert_eq!(ap.get_for(&foreground), Some((ws, foreground_project)));+ assert_eq!(ap.get_for(&stale), Some((ws, stale_project)));+ assert!(ap.default_global_for(&foreground));+ assert!(!ap.default_global_for(&stale));+ }++ #[test]+ fn scoped_refresh_does_not_advance_per_actor_identity_fallback() {+ let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);+ let ws = WorkspaceId::new();+ let foreground = key_actor("alice", "foreground");+ let stale = key_actor("alice", "stale");+ let foreground_project = ProjectId::new();+ let stale_project = ProjectId::new();++ ap.set_for(&foreground, ws, foreground_project, true);+ ap.set_scoped_for(&stale, ws, stale_project, false);++ let identity_only = ActorKey {+ user: Some("alice".to_string()),+ session_id: None,+ };+ assert_eq!(ap.get(), Some((ws, foreground_project)));+ assert_eq!(ap.get_for(&identity_only), Some((ws, foreground_project)));+ assert_eq!(ap.get_for(&stale), Some((ws, stale_project)));+ assert!(ap.default_global_for(&identity_only));+ assert!(!ap.default_global_for(&stale));+ }+#[test]fn per_session_ignores_user_field() {let ap = ActiveProject::with_mode(ActiveProjectMode::PerSession);diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex 56d383b3..b1d8d1ff 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -609,11 +609,7 @@ async fn handle_hook(// extensions still exist, and travels with the event into `process()`.let skip_webhooks = admission_skips(level_ext, &headers);let actor_storage_key = actor.as_ref().map(IdentityKey::storage_key);- let actor_key = ActorKey {- user: actor_storage_key.clone(),- session_id: env.session_id.clone(),- };- if should_drop_subagent(&state, &env, &actor_key).await {+ if should_drop_subagent(&state, &env).await {return (StatusCode::ACCEPTED, "subagent capture dropped");}let Ok(permit) = state.ingest_semaphore.clone().try_acquire_owned() else {@@ -769,14 +765,10 @@ async fn handle_hook_batch(accepted_indices.push(idx);continue;};- let actor_key = ActorKey {- user: actor_storage_key.clone(),- session_id: env.session_id.clone(),- };// Accept-but-drop subagent captures (see `handle_hook`): count the item// as committed so the client clears it from its spool, but do not store// it. Keeps the contiguous-prefix ack contract intact.- if should_drop_subagent(&state, &env, &actor_key).await {+ if should_drop_subagent(&state, &env).await {accepted_indices.push(idx);continue;}@@ -1058,7 +1050,7 @@ const fn canonical_tool_name(family: ToolFamily) -> &'static str {/// `stop` / `session_end`) of a session already known to be a subagent. No-op/// (returns `false`) unless this event's project opted in via the per-event/// `drop_subagent` flag (sourced from its `.ai-memory.toml`).-async fn should_drop_subagent(state: &HookState, env: &HookEnvelope, actor: &ActorKey) -> bool {+async fn should_drop_subagent(state: &HookState, env: &HookEnvelope) -> bool {if !env.drop_subagent_requested {return false;}@@ -1071,8 +1063,6 @@ async fn should_drop_subagent(state: &HookState, env: &HookEnvelope, actor: &Actenv.workspace_override.as_deref(),env.project_override.as_deref(),env.project_strategy,- actor,- env.recall_default_global_requested,).awaitelse {@@ -1206,12 +1196,15 @@ async fn fetch_and_accept_handoff(query.workspace.as_deref(),query.project.as_deref(),ProjectStrategy::parse(query.project_strategy.as_deref()),- &actor_key,- // The /handoff query carries no recall preference; the main capture- // path is what publishes default_global for read tools.- false,).await?;+ // Session-start handoff delivery is a foreground action. Publish it so+ // static MCP callers resolve to the directory that is opening now. The+ // query carries no recall preference; the main capture path publishes+ // `default_global` when its SessionStart arrives.+ if has_publishable_scope_hint(query.cwd.as_deref(), query.project.as_deref()) {+ state.active_project.set_for(&actor_key, ws, proj, false);+ }// The actor is what makes this lookup safe on a shared server: without it// the newest open handoff in the project is returned to whoever starts a// session next, and the claim below consumes it — so one operator's baton@@ -1740,7 +1733,13 @@ fn normalize_project_path_key(path: &str) -> String {}}-/// Resolve the `(workspace_id, project_id)` pair for a hook event.+fn has_publishable_scope_hint(cwd: Option<&str>, project_override: Option<&str>) -> bool {+ cwd.is_some_and(|value| !value.is_empty()) || project_override.is_some()+}++/// Resolve the `(workspace_id, project_id)` pair for a hook event without+/// publishing it as active. Callers decide separately whether the event is a+/// foreground interaction allowed to advance fallback routing.////// Precedence:/// 1. `workspace_override` (typically declared by the agent's host-side@@ -1753,15 +1752,12 @@ fn normalize_project_path_key(path: &str) -> String {/// project_strategy)` so the same `cwd` resolved with and without an/// override (e.g. during a hook-script upgrade window) doesn't poison each/// other's slot.-#[allow(clippy::too_many_arguments)]async fn resolve_project_ids_inner(state: &HookState,cwd: Option<&str>,workspace_override: Option<&str>,project_override: Option<&str>,project_strategy: ProjectStrategy,- actor: &ai_memory_core::ActorKey,- default_global: bool,) -> anyhow::Result<(WorkspaceId, ProjectId)> {let cwd_norm = cwd.filter(|s| !s.is_empty())@@ -1783,14 +1779,6 @@ async fn resolve_project_ids_inner({let mut cache = state.project_cache.lock().await;if let Some(ids) = cache.get(&cache_key) {- // Republish on every hit: a cache hit still means the agent- // is active in this project *now*, which is exactly what the- // MCP read tools need as their default. Keyed by the actor so- // opt-in isolation modes (`per_session`/`per_actor`) keep- // concurrent callers separated.- state- .active_project- .set_for(actor, ids.0, ids.1, default_global);return Ok(ids);}}@@ -1807,15 +1795,7 @@ async fn resolve_project_ids_inner((Some(p), None) => (p.to_string(), None),(None, Some(c)) => match derive_project_from_cwd(c, project_strategy) {Some(resolved) => resolved,- None => {- state.active_project.set_for(- actor,- state.workspace_id,- state.project_id,- default_global,- );- return Ok((state.workspace_id, state.project_id));- }+ None => return Ok((state.workspace_id, state.project_id)),},(None, None) => {// The early-return at the top of the function guards@@ -1824,12 +1804,6 @@ async fn resolve_project_ids_inner(// gets refactored. Same effect as `unreachable!`, but// visible at compile time instead of inside the panic// message.- state.active_project.set_for(- actor,- state.workspace_id,- state.project_id,- default_global,- );return Ok((state.workspace_id, state.project_id));}};@@ -1846,9 +1820,6 @@ async fn resolve_project_ids_inner("hook router: refusing to attribute event capture to the reserved \global scope; using the server-default project");- state- .active_project- .set_for(actor, state.workspace_id, state.project_id, default_global);return Ok((state.workspace_id, state.project_id));}@@ -2002,9 +1973,6 @@ async fn resolve_project_ids_inner(};let ids = (ws, proj);state.project_cache.lock().await.insert(cache_key, ids);- state- .active_project- .set_for(actor, ws, proj, default_global);Ok(ids)}@@ -2021,16 +1989,18 @@ async fn resolve_project_ids(project_strategy: ProjectStrategy,actor: &ai_memory_core::ActorKey,) -> anyhow::Result<(WorkspaceId, ProjectId)> {- resolve_project_ids_inner(+ let ids = resolve_project_ids_inner(state,cwd,workspace_override,project_override,project_strategy,- actor,- false,)- .await+ .await?;+ if has_publishable_scope_hint(cwd, project_override) {+ state.active_project.set_for(actor, ids.0, ids.1, false);+ }+ Ok(ids)}/// Whether session-sticky attribution may apply: the event's cwd must sit@@ -2107,6 +2077,36 @@ async fn enqueue_session_end_consolidation(Ok(())}+/// Only events that begin or actively advance work may move the legacy+/// process-wide and identity-only fallbacks. Completion events can arrive+/// after the operator has moved to another project, especially when a native+/// hook spool drains after an agent process exits unexpectedly (#372).+const fn advances_active_project_fallback(event: HookEvent) -> bool {+ matches!(+ event,+ HookEvent::SessionStart | HookEvent::UserPrompt | HookEvent::PreToolUse+ )+}++fn publish_active_project_for_event(+ state: &HookState,+ event: HookEvent,+ actor: &ActorKey,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ default_global: bool,+) {+ if advances_active_project_fallback(event) {+ state+ .active_project+ .set_for(actor, workspace_id, project_id, default_global);+ } else {+ state+ .active_project+ .set_scoped_for(actor, workspace_id, project_id, default_global);+ }+}+async fn process(state: &HookState,env: HookEnvelope,@@ -2163,19 +2163,10 @@ async fn process(} else {None};+ let publishable_scope = sticky_scope.is_some()+ || has_publishable_scope_hint(env.cwd.as_deref(), env.project_override.as_deref());let (mut ws, mut proj) = match sticky_scope {- Some((session_ws, session_proj, _)) => {- // Publish the pointer like resolve_project_ids does on a cache- // hit: this session being active is exactly what the MCP read- // tools should default to.- state.active_project.set_for(- &actor_key,- session_ws,- session_proj,- env.recall_default_global_requested,- );- (session_ws, session_proj)- }+ Some((session_ws, session_proj, _)) => (session_ws, session_proj),None => {resolve_project_ids_inner(state,@@ -2183,8 +2174,6 @@ async fn process(env.workspace_override.as_deref(),env.project_override.as_deref(),env.project_strategy,- &actor_key,- env.recall_default_global_requested,).await?}@@ -2291,8 +2280,6 @@ async fn process(env.workspace_override.as_deref(),env.project_override.as_deref(),env.project_strategy,- &actor_key,- env.recall_default_global_requested,).await?;ws = refreshed.0;@@ -2310,6 +2297,17 @@ async fn process(.await?;}+ if publishable_scope {+ publish_active_project_for_event(+ state,+ env.event,+ &actor_key,+ ws,+ proj,+ env.recall_default_global_requested,+ );+ }+// `AI_MEMORY_RUN_ID` is invocation-scoped. A valid active run links the// native session and switches only this hook invocation to managed// workstream semantics; direct harness launches keep the legacy path.@@ -3561,6 +3559,83 @@ mod tests {);}+ #[tokio::test]+ async fn delayed_hook_tail_does_not_steal_active_project_fallback() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;+ let project_a = tmp.path().join("project-a");+ let project_b = tmp.path().join("project-b");+ std::fs::create_dir_all(&project_a).unwrap();+ std::fs::create_dir_all(&project_b).unwrap();+ let session_a = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";+ let session_b = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";+ let fire = |event: &str, session_id: &str, cwd: &std::path::Path| {+ HookEnvelope::from_query_and_body(+ HookQuery {+ event: event.into(),+ agent: Some("claude-code".into()),+ cwd: Some(cwd.to_string_lossy().into_owned()),+ ..Default::default()+ },+ serde_json::json!({+ "session_id": session_id,+ "cwd": cwd.to_string_lossy(),+ "prompt": "continue",+ "tool_name": "Bash",+ }),+ )+ };++ process(+ &state,+ fire("session-start", session_b, &project_b),+ None,+ Vec::new(),+ )+ .await+ .unwrap();+ let active_b = state.active_project.get().expect("B published its scope");++ process(+ &state,+ fire("user-prompt-submit", session_a, &project_a),+ None,+ Vec::new(),+ )+ .await+ .unwrap();+ let active_a = state.active_project.get().expect("A published its scope");+ assert_ne!(active_a, active_b, "the fixture must resolve two projects");++ process(+ &state,+ fire("post-tool-use", session_b, &project_b),+ None,+ Vec::new(),+ )+ .await+ .unwrap();+ assert_eq!(+ state.active_project.get(),+ Some(active_a),+ "a delayed completion tail from B must not redirect unscoped reads away from A"+ );++ process(+ &state,+ fire("pre-tool-use", session_b, &project_b),+ None,+ Vec::new(),+ )+ .await+ .unwrap();+ assert_eq!(+ state.active_project.get(),+ Some(active_b),+ "a new foreground action in B must still advance the fallback"+ );+ }+/// Completed replays are skipped, while a claim left pending after the/// observation commit resumes and completes its downstream processing./// Fresh keys and keyless older clients keep landing normally.@@ -4483,7 +4558,6 @@ mod tests {async fn drop_subagent_tracking_is_scoped_by_project() {let tmp = TempDir::new().unwrap();let state = make_state(&tmp).await;- let actor = ai_memory_core::ActorKey::default();let marked_project_a = HookEnvelope::from_query_and_body(HookQuery {@@ -4497,7 +4571,11 @@ mod tests {"sessionId": "shared-session", "subagentType": "general-purpose"}),);- assert!(should_drop_subagent(&state, &marked_project_a, &actor).await);+ assert!(should_drop_subagent(&state, &marked_project_a).await);+ assert!(+ state.active_project.get().is_none(),+ "drop preflight may resolve scope but must not publish it as active"+ );let unmarked_project_b = HookEnvelope::from_query_and_body(HookQuery {@@ -4510,7 +4588,7 @@ mod tests {serde_json::json!({ "sessionId": "shared-session", "toolName": "kept" }),);assert!(- !should_drop_subagent(&state, &unmarked_project_b, &actor).await,+ !should_drop_subagent(&state, &unmarked_project_b).await,"a subagent session tracked in project-a must not drop same-id events in project-b");@@ -4525,7 +4603,7 @@ mod tests {serde_json::json!({ "sessionId": "shared-session", "toolName": "dropped" }),);assert!(- should_drop_subagent(&state, &unmarked_project_a, &actor).await,+ should_drop_subagent(&state, &unmarked_project_a).await,"the originally tracked project's unmarked tail still drops");}@@ -4534,7 +4612,6 @@ mod tests {async fn subagent_stop_keeps_session_tracked_until_session_end_tail_drops() {let tmp = TempDir::new().unwrap();let state = make_state(&tmp).await;- let actor = ai_memory_core::ActorKey::default();let query = |event: &str| HookQuery {event: event.into(),@@ -4548,20 +4625,20 @@ mod tests {query("subagent-start"),serde_json::json!({ "sessionId": "tail-session" }),);- assert!(should_drop_subagent(&state, &start, &actor).await);+ assert!(should_drop_subagent(&state, &start).await);let subagent_stop = HookEnvelope::from_query_and_body(query("subagent-stop"),serde_json::json!({ "sessionId": "tail-session" }),);- assert!(should_drop_subagent(&state, &subagent_stop, &actor).await);+ assert!(should_drop_subagent(&state, &subagent_stop).await);let unmarked_stop_tail = HookEnvelope::from_query_and_body(query("stop"),serde_json::json!({ "sessionId": "tail-session" }),);assert!(- should_drop_subagent(&state, &unmarked_stop_tail, &actor).await,+ should_drop_subagent(&state, &unmarked_stop_tail).await,"SubagentStop must not clear tracking before the unmarked stop tail");@@ -4570,7 +4647,7 @@ mod tests {serde_json::json!({ "sessionId": "tail-session" }),);assert!(- should_drop_subagent(&state, &session_end_tail, &actor).await,+ should_drop_subagent(&state, &session_end_tail).await,"SessionEnd tail is dropped and then clears tracking");@@ -4579,7 +4656,7 @@ mod tests {serde_json::json!({ "sessionId": "tail-session", "toolName": "kept" }),);assert!(- !should_drop_subagent(&state, &after_session_end, &actor).await,+ !should_drop_subagent(&state, &after_session_end).await,"SessionEnd clears tracking for that scoped session");}diff --git a/docs/auto-scope.md b/docs/auto-scope.mdindex 74fa5a69..b75ef1ce 100644--- a/docs/auto-scope.md+++ b/docs/auto-scope.md@@ -2,10 +2,13 @@`ai-memory serve` publishes a process-shared "currently active project"pointer that MCP read tools consult when the caller omits `workspace` /-`project`. The pointer is fed by the lifecycle hooks: every `/hook`-event that resolves a `cwd` to a real project updates the pointer so-read tools answer for the project the agent is actually in, not the-server's static `--project` default.+`project`. The pointer is fed by foreground lifecycle hooks: session start,+user prompt, and pre-tool events that resolve a `cwd` to a real project update+the pointer so read tools answer for the project the agent is actually in, not+the server's static `--project` default. Completion and shutdown events still+land in their resolved project, but do not advance shared fallback slots: a+delayed post-tool, stop, or session-end tail from an older process must not+redirect a newer session's unscoped reads.By default that pointer is a single process-wide slot — right for oneoperator running one project at a time, but it collapses parallel@@ -25,12 +28,13 @@ separated.| `per_session` | `session_id` | Session-aware clients/bridges that forward the hook session id on every MCP request. || `per_actor` | `(qualified identity, session_id)`, with an identity-only no-session slot | Shared engine fielding multiple authenticated users or trusted-proxy identities. Isolates across operators and fails closed when a forwarded session id does not match hook activity. |-Both opt-in modes still publish to the single slot in parallel, so a-caller with no actor identity (anonymous probe, legacy code path) sees-the most recent project rather than an empty pointer. That preserves-legacy behavior, but it is not per-session isolation; use explicit-`workspace` + `project` arguments when a client cannot send actor-identity and concurrent runs matter.+Both opt-in modes still publish foreground activity to the single slot in+parallel, so a caller with no actor identity (anonymous probe, legacy code+path) sees the most recently active project rather than an empty pointer.+Non-foreground events refresh only their exact keyed entry when one exists.+That preserves legacy behavior without letting a delayed tail take over, but+it is not per-session isolation; use explicit `workspace` + `project`+arguments when a client cannot send actor identity and concurrent runs matter.Explicit scope arguments fail closed. A `project` argument is resolvedinside the active workspace first, then inside the server's default