Skip to content

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

Rust

docs(security): add the Grok subagent handoff row

João Matheusde4d0fe74561
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 6e86a21a..64c51eb7 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -69,8 +69,9 @@ the legitimate restricted-project control and the failed-query cases.
| 4l | The cut-off-session pointer (session-start notice, `memory_briefing` `recent_sessions`, `memory_handoff_list` `newer_unended_session`) names only the caller's own or shared sessions, carries no captured text, and claims nothing; `memory_read_session_observations` without a `session_id` defaults through the same owner-filtered, scope-bound ordering | `ai-memory-store/src/reader.rs` `recent_session_activity` applies the same `OwnerFilter` clause on the session row as `sessions_for_scope` (`actor_user IS NULL OR = :actor`, or `IS NULL` for an unattributed caller) inside the resolved, authorized `(workspace, project)`; `ai-memory-hooks/src/router.rs` `render_continuity_notice` renders only the stored agent kind, the session UUID, an age and the scope's server-side names (the `render_handoff_notice`/`render_inbox_notice` bar) and is computed after `authorize_resolved`; the MCP fields reuse the tool's own resolved scope and owner filter | router `session_start_never_names_another_operators_cut_off_session` (adversarial: with registered users, bob's cut-off session is not named to alice; control: bob's next session is pointed at it; fails with the owner clause removed), `session_start_names_a_session_cut_off_without_ending` (the notice carries none of the session's prompt, command or output text); store `session_activity.rs` `the_owner_filter_hides_another_operators_sessions`; MCP `memory_read_session_observations_default_never_crosses_owner_or_project` (adversarial: bob's newer open session in alice's cwd and alice's newer session in another project are never alice's default; control: alice's own older session is, and bob's default is his own; fails with the owner filter set to `Any`); CLI `harness_switch_e2e.rs` (real server and hook binary; no captured text in the notice) | STRONG |
| 4m | A project's `[handoff] deliver_on_session_start = false` hides and claims only its own session-start baton | `ai-memory-hooks/src/router.rs` `fetch_and_accept_handoff_at` reads `HandoffQuery.handoff` for the one resolved `(workspace, project)`: opted out, it neither reads (`startup_handoff`), claims, announces nor renders the continuity notice; the handoff stays `open`, and the SessionEnd path that creates it is untouched | `router.rs` `handoff_opt_out_leaves_the_baton_open_and_undelivered` (falsy values hide the baton and leave it open; `1` still delivers and claims) and `handoff_opt_out_is_scoped_to_the_requesting_project` (a second project keeps receiving its own baton, never the opted-out one's, and does not consume it) | STRONG |
| 4n | A subagent's brief reads only its repository's brief and never claims, publishes or records | `ai-memory-hooks/src/router.rs` `handle_brief`/`fetch_brief` — the project comes from `resolve_readable_startup_scope`, the helper `/handoff` also uses (cwd, marker or explicit scope, then `grants::authorize_resolved(.., ProjectAccess::Read)`, whose refusal is a `403` with its reason); only the brief is rendered, with `[slots] per_user` visibility for the requesting identity and stored text inside the untrusted-history fence; no handoff is read or claimed, no active project is published and no `[profile]` flag is written. Clients (`ai-memory hook`, `hooks/claude-code/subagent-start.{sh,ps1}`) fetch it only for the `claude-code` agent's `SubagentStart` and only with the marker's `[briefing] inject_on_subagent_start`, and never fall back to `/handoff` when the route is missing | `router.rs` `brief_endpoint_never_claims_a_pending_handoff` (the baton stays open; control: `/handoff` with the same query delivers it), `brief_endpoint_delivers_nothing_from_a_repository_the_viewer_cannot_read` (no grant: `403` and no page text; control: a Read grant), `per_user_subagent_brief_carries_own_slot_body_and_not_others` (another operator's slot withheld; own slot delivered), `brief_endpoint_is_empty_without_the_opt_in`; `hook.rs` `subagent_start_delivers_the_opted_in_brief` (no `/handoff` request), `subagent_start_with_no_brief_prints_an_empty_reply` (a `404` never falls back to `/handoff`), `subagent_brief_skips_agents_without_subagent_context`; `tests/hooks/test_lib.sh` (the shell bundle never asks `/handoff`) | STRONG |
-| 4o | An OMP subagent session never claims a handoff or leaves one behind | `ai-memory-hooks/src/router.rs` SessionEnd `child_session`: an OpenCode or OMP end whose body carries a subagent marker (`payload.rs` `body_is_subagent`) closes and summarizes the session without a baton. The generated OMP extension (`ai-memory-cli/src/commands/install_hooks.rs` `build_omp_extension`) records a subagent session from `ctx.agent.kind` on the session's own `session_start`, `before_agent_start` and `session_shutdown`, never on a tool event (an advisor's tool calls reach the session they advise as `kind: "sub"` under that session's id), skips `fetchHandoff` for it and posts its events with `agent_id`. Pi reports no `ctx.agent`, so every Pi session stays top-level | router `omp_subagent_session_end_closes_and_summarizes_without_baton` (a marked OMP end leaves no baton; control: a top-level OMP session in the same project still leaves one), beside `opencode_child_session_end_closes_and_summarizes_without_baton`, and `drop_subagent_captures_drops_an_omp_subagent_session` (an opted-in project drops the marked session through its end; control: the top-level session is stored); `install_hooks.rs` `omp_extension_marks_subagent_sessions_and_skips_their_handoff` and, running the generated OMP extension in Node, `slow_generated_handoff_runtime::omp_extension_keeps_subagent_sessions_off_the_baton` (a task subagent, a `/tan` clone and a revived subagent never request `/handoff` and carry `agent_id` on every event, their ends included; controls: the top-level session and a session without `ctx.agent` claim, and the advisor's tool calls leave the top-level session unmarked). Each fails with its guard removed | STRONG |
+| 4o | An OMP subagent session never claims a handoff or leaves one behind | `ai-memory-hooks/src/router.rs` SessionEnd `child_session`: an OpenCode, OMP or Grok (row 4q) end whose body carries a subagent marker (`payload.rs` `body_is_subagent`) closes and summarizes the session without a baton. The generated OMP extension (`ai-memory-cli/src/commands/install_hooks.rs` `build_omp_extension`) records a subagent session from `ctx.agent.kind` on the session's own `session_start`, `before_agent_start` and `session_shutdown`, never on a tool event (an advisor's tool calls reach the session they advise as `kind: "sub"` under that session's id), skips `fetchHandoff` for it and posts its events with `agent_id`. Pi reports no `ctx.agent`, so every Pi session stays top-level | router `omp_subagent_session_end_closes_and_summarizes_without_baton` (a marked OMP end leaves no baton; control: a top-level OMP session in the same project still leaves one), beside `opencode_child_session_end_closes_and_summarizes_without_baton`, and `drop_subagent_captures_drops_an_omp_subagent_session` (an opted-in project drops the marked session through its end; control: the top-level session is stored); `install_hooks.rs` `omp_extension_marks_subagent_sessions_and_skips_their_handoff` and, running the generated OMP extension in Node, `slow_generated_handoff_runtime::omp_extension_keeps_subagent_sessions_off_the_baton` (a task subagent, a `/tan` clone and a revived subagent never request `/handoff` and carry `agent_id` on every event, their ends included; controls: the top-level session and a session without `ctx.agent` claim, and the advisor's tool calls leave the top-level session unmarked). Each fails with its guard removed | STRONG |
| 4p | An OpenCode 1.x subagent session never claims a handoff or leaves one behind | `ai-memory-cli/src/commands/install_hooks.rs` `build_opencode_plugin`: the generated V1 plugin records a child session's parent from its `session.created` and from the `session.updated` OpenCode publishes on every prompt before the model call (a child the task tool resumes by `task_id` in a later process), skips `fetchHandoff` in `experimental.chat.system.transform` for it, and `endSession` posts its end with `agent_id` on every close path, the `dispose` at exit included, so the router's SessionEnd `child_session` gate (row 4o) closes and summarizes it without a baton | `install_hooks.rs` `opencode_plugin_skips_the_handoff_for_a_subagent_session` (the parent comes from both session events, only from a string `parentID`, and the transform returns for a child before `fetchHandoff`) and `opencode_plugin_marks_a_subagent_session_end` (`dispose` ends sessions through `endSession`, which adds `agent_id` for a recorded child); running the generated plugin in Node, `slow_generated_handoff_runtime::opencode_plugin_keeps_task_subagents_off_the_baton` (a `task` subagent and one resumed by `task_id` never request `/handoff`, and their ends from `dispose` carry `agent_id`; controls: a top-level session and one continued from an earlier process claim and stay unmarked). Each fails with its guard removed | STRONG |
+| 4q | A Grok subagent session never claims a handoff or leaves one behind | `ai-memory-cli/src/commands/hook.rs` claims Grok's handoff on `PostToolUse` only for a payload without a subagent marker (`subagent_payload`), and `ai-memory-hooks/src/router.rs` SessionEnd `child_session` closes and summarizes a Grok end whose body carries `subagentType` (`payload.rs` `body_is_subagent`) without a baton. Grok runs a subagent in a session of its own and stamps `subagentType` on its events, its `SessionEnd` included (`HookPayload::SessionEnd` in xai-grok-hooks `event.rs`); the main session never carries it, and `SessionStart` does not fire for a subagent | `hook.rs` `grok_post_tool_skips_a_subagent_payload` (a marked tool result never requests `/handoff`); router `grok_subagent_session_end_closes_and_summarizes_without_baton` (a marked Grok end leaves no baton; control: a top-level Grok session in the same project still leaves one). Each fails with its guard removed | STRONG |
| 5a | Pages shared: `author_id` is never a read filter (invariant #16) | `ai-memory-store/src/reader.rs` `search_pages`/`page_body_by_ids` — `author_id` is an attribution JOIN only, never a WHERE term; `observation_stream_votes` lets every session vote whatever its owner (the owner filter only withholds the observation excerpt and ids, never the vote or the page) | `multi_session.rs` — a page with a **non-null** `author_id` (operator A) is readable by operator B in the same project; `multi_session.rs` `another_operators_observations_lift_their_session_page_in_a_shared_project` (operator B's owned session, authored page and observations lift that page for operator A's query); `ai-memory-mcp` `server.rs` `observation_stream_evidence_stays_inside_a_restricted_project` (a second operator with only a read grant gets the session page lifted by the first operator's observation); `multi_session.rs` `observation_excerpts_follow_the_session_owner_while_the_vote_stays_shared` (B still gets A's session page ranked by A's observation, with the page's own snippet) | STRONG |
| 5b | Page supersession (loser stays reachable) | `ai-memory-store/src/ops.rs` `upsert_page_in_tx` — demote `is_latest=0` (never delete) + `supersedes` chain; read side: `reader.rs` `page_versions` lists every row at the path, with no `is_latest` filter, for `/web/w/…/h/*path` and `/api/v1/…/history/*path`. It does apply TTL expiry (`reader.rs` `history_visible`): a version whose own `expires_at` passed is neither listed nor readable by id, a path whose live version expired shows no history at all (the forget sweep hard-deletes every row there), and a `supersedes` link to a hidden version reads as `null`. Expiry is the only thing that hides a superseded version; a concurrent write never does | `multi_session.rs` `concurrent_writes_to_one_path_supersede_rather_than_destroy`; `retrieval_superseded.rs`; `multi_session.rs` `page_history_keeps_the_overwritten_version_and_stays_in_scope`; `ai-memory-web` `history_replay.rs` `history_keeps_both_sides_of_a_concurrent_divergent_write` (two attributed writers on one base: all three versions and both authors listed, one `is_latest`, the two writers' versions diff by id) and `history_lists_k_plus_one_versions_newest_first_and_diffs_the_latest`; bite: an `is_latest = 1` filter in `page_versions` fails both; `history_hides_expired_versions_and_expired_pages` (an expired superseded version and every version of a page whose live version expired answer 404 by path and by id on HTML and JSON, and the live successor's `supersedes` is `null`; control: a TTL in the future is listed and diffable; bites with the per-row predicate removed, with the live-version clause disabled, and with the `supersedes` hiding removed) | STRONG |
| 5c | Watcher reindex and Wiki writes share per-page serialization (invariant #16) | `ai-memory-wiki/src/wiki.rs` `reindex_page` takes `mutation_lock.read` before `reindex_page_locked` takes `lock_page`, covering disk read through the single-writer upsert; callers already holding the exclusive global guard do not reacquire it. `write_page` uses the same page mutex and `apply_batch` retains sorted, deduplicated locks; embedding runs after both guards are released | `wiki.rs` `reindex_page_lock_waits_before_reading_and_allows_another_path` (transient snapshot refused while locked, another path progresses, release indexes the committed bytes without rewriting disk), `reindex_page_lock_serializes_write_through_the_upsert` and `reindex_page_lock_and_reversed_duplicate_batches_do_not_deadlock` (real concurrent operations, final disk/SQL winner and supersession ancestry preserved); all three fail with the reindex page guard removed. `reindex_page_lock_releases_both_guards_before_embedding` checks both body and abstract embedding; `decay_cleanup_reindex_does_not_embed_under_the_exclusive_lock` covers the exclusive caller | STRONG for a shared Wiki handle and its clones. External editors and independently constructed Wiki handles do not participate in these locks |