Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Assistant-message capture plumbing (issue #196).
//!
//! Some agent harnesses attach the assistant's final turn to their `Stop`
//! lifecycle event — Claude Code sends it as a top-level `last_assistant_message`
//! string. That text is high-value for recall but privacy-sensitive: it can
//! quote code, secrets, or content from paths ai-memory never sees. Capturing
//! it is therefore an explicit, double opt-in feature (server config +
//! `install-hooks --capture-assistant`).
//!
//! This module owns the single source of truth for WHICH raw field carries the
//! assistant message per agent/event, the unconditional strip that keeps that
//! raw field off the local spool, the wire, tracing, and storage, and the
//! opt-in path that re-introduces a sanitized, capped excerpt: the client-side
//! [`transform_for_client`] and the server-side [`apply_assistant_backstop`].
use ai_memory_core::{AgentKind, Sanitizer, truncate_utf8_bytes};
use serde::{Deserialize, Serialize};
use crate::payload::{HookEnvelope, HookEvent};
/// Synthetic body key carrying the opt-in, sanitized assistant excerpt from the
/// client to the server. Distinct from the raw `last_assistant_message` field,
/// which is always stripped: this one is the deliberate, capped protocol.
pub const ASSISTANT_MARKER_KEY: &str = "_ai_memory_assistant";
/// Protocol version for the opt-in `_ai_memory_assistant` body marker the client
/// attaches when capture is enabled. Bumping it invalidates markers a stale
/// server would otherwise trust.
pub const ASSISTANT_PROTOCOL_VERSION: u8 = 1;
/// Hard ceiling on the raw assistant-message string the client reads before
/// sanitizing/truncating. Oversized input is treated as absent.
pub const ASSISTANT_MESSAGE_MAX_INPUT_BYTES: usize = 64 * 1024;
/// Byte cap on the sanitized excerpt the opt-in path persists. Kept equal to
/// `truncate_excerpt`'s existing 2 KB excerpt contract so Stop bodies do not
/// become a second, larger excerpt norm.
pub const ASSISTANT_EXCERPT_MAX_BYTES: usize = 2_000;
/// Every raw top-level field name known to carry an assistant message across
/// supported agents. The unconditional strip removes each of these; the closed
/// per-agent table below decides which is a *candidate* for opt-in capture. The
/// union is kept tiny on purpose — one entry per distinct wire spelling.
const ASSISTANT_MESSAGE_FIELDS: &[&str] = &["last_assistant_message"];
/// The raw field that carries the assistant's final message for `(agent, event)`,
/// or `None` when the pair has no verified assistant-message field.
///
/// Closed table: Claude Code, Codex, and OpenCode support `Stop` capture.
/// Extend deliberately — a new entry opts an agent/event into capture and MUST
/// have its field name present in [`ASSISTANT_MESSAGE_FIELDS`] so the strip
/// covers it (enforced by `closed_table_fields_are_all_stripped`).
///
/// Codex's `Stop` hook payload carries `last_assistant_message` (verified on
/// codex-cli 0.154.0, #743) — the same spelling Claude Code uses, so no new
/// entry in [`ASSISTANT_MESSAGE_FIELDS`] is needed. Codex has no `SubagentStop`
/// in its supported event vocabulary, so only `(Codex, Stop)` is added.
#[must_use]
pub fn assistant_message_field(agent: AgentKind, event: HookEvent) -> Option<&'static str> {
match (agent, event) {
(AgentKind::ClaudeCode | AgentKind::Codex | AgentKind::OpenCode, HookEvent::Stop) => {
Some("last_assistant_message")
}
_ => None,
}
}
/// The opt-in assistant-capture wire protocol carried in the body under
/// [`ASSISTANT_MARKER_KEY`]. `deny_unknown_fields` + the explicit version gate
/// means a malformed or future-versioned marker is rejected (dropped, never
/// persisted) rather than partially trusted.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AssistantCaptureProtocol {
/// Wire version. Must equal [`ASSISTANT_PROTOCOL_VERSION`].
pub version: u8,
/// Client-sanitized, byte-capped assistant excerpt. The server re-scrubs it
/// with its configured `Sanitizer` at the persistence boundary.
pub excerpt: String,
}
impl AssistantCaptureProtocol {
/// Parse a marker value, accepting only the current protocol version. Any
/// unknown field, wrong type, or version mismatch yields `None`.
#[must_use]
fn parse(value: &serde_json::Value) -> Option<Self> {
let parsed: Self = serde_json::from_value(value.clone()).ok()?;
(parsed.version == ASSISTANT_PROTOCOL_VERSION).then_some(parsed)
}
}
/// Outcome of the client-side assistant transform.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub struct ClientAssistantTransform {
/// The raw JSON was mutated (raw field removed and/or protocol spliced in),
/// so the caller must reserialize the spool/wire payload.
pub changed: bool,
/// A valid protocol was spliced in, so the caller appends
/// `&capture_assistant=1` to the event URL.
pub captured: bool,
}
/// Client-side transform for an install that opted into assistant capture.
///
/// Reads the candidate assistant message for `(agent, event)`, unconditionally
/// strips the raw field, and — when the value is a non-empty, in-bounds string —
/// sanitizes it with the built-in `Sanitizer`, truncates it to
/// [`ASSISTANT_EXCERPT_MAX_BYTES`] on a UTF-8 boundary, and splices the versioned
/// [`AssistantCaptureProtocol`] into the body under [`ASSISTANT_MARKER_KEY`].
///
/// Scrub happens BEFORE truncation (a secret straddling the cap must be redacted
/// before it can be cut). Non-string, empty, or oversized values yield no
/// protocol — the raw field is still stripped, so the event degrades to an empty
/// Stop rather than leaking anything.
pub fn transform_for_client(
raw: &mut serde_json::Value,
agent: AgentKind,
event: HookEvent,
) -> ClientAssistantTransform {
// Read the eligible value BEFORE stripping removes the field.
let candidate = assistant_message_field(agent, event).and_then(|field| {
raw.as_object()
.and_then(|object| object.get(field))
.and_then(serde_json::Value::as_str)
.filter(|value| !value.is_empty() && value.len() <= ASSISTANT_MESSAGE_MAX_INPUT_BYTES)
.map(str::to_string)
});
let mut changed = strip_assistant_message_raw(raw);
let Some(value) = candidate else {
return ClientAssistantTransform {
changed,
captured: false,
};
};
let scrubbed = Sanitizer::builtin().scrub(&value);
let excerpt = truncate_utf8_bytes(&scrubbed, ASSISTANT_EXCERPT_MAX_BYTES);
if excerpt.is_empty() {
return ClientAssistantTransform {
changed,
captured: false,
};
}
let protocol = AssistantCaptureProtocol {
version: ASSISTANT_PROTOCOL_VERSION,
excerpt,
};
let mut captured = false;
if let Some(object) = raw.as_object_mut()
&& let Ok(marker) = serde_json::to_value(&protocol)
{
object.insert(ASSISTANT_MARKER_KEY.to_string(), marker);
changed = true;
captured = true;
}
ClientAssistantTransform { changed, captured }
}
/// Server-side backstop for the opt-in assistant excerpt (#196).
///
/// Always consumes the [`ASSISTANT_MARKER_KEY`] from `env.raw` so it can never
/// persist. Populates `env.body_excerpt` with the excerpt ONLY when every gate
/// holds: the server enabled capture, the client requested it (`capture_assistant`
/// query flag), the agent/event is a supported candidate, and the marker parses
/// as a current-version protocol with a non-empty excerpt. Any failure leaves
/// `body_excerpt` as `None` — an empty Stop — so a forged or stale marker cannot
/// inject content. Infallible: never returns an error, so a capture decision can
/// never turn into a batch fail-fast.
pub fn apply_assistant_backstop(env: &mut HookEnvelope, server_enabled: bool) {
// Consume the marker unconditionally: it must never survive into the stored
// raw, whether or not the gates below accept it.
let marker = env
.raw
.as_object_mut()
.and_then(|object| object.remove(ASSISTANT_MARKER_KEY));
let eligible = server_enabled
&& env.capture_assistant_requested
&& assistant_message_field(env.agent, env.event).is_some();
if !eligible {
return;
}
if let Some(marker) = marker
&& let Some(protocol) = AssistantCaptureProtocol::parse(&marker)
&& !protocol.excerpt.is_empty()
{
// Re-enforce the excerpt cap at the persistence boundary — never trust
// the client's length. Symmetric to the server re-scrub in `process()`:
// a forged or buggy client that satisfies the gates cannot inject an
// oversized Stop body (the request body limit alone is 10 MiB). Almost
// always a no-op, since a well-behaved client already truncated.
env.body_excerpt = Some(truncate_utf8_bytes(
&protocol.excerpt,
ASSISTANT_EXCERPT_MAX_BYTES,
));
}
}
/// Unconditionally remove every known assistant-message field from a raw hook
/// payload's top-level object, returning whether anything was removed.
///
/// This is a defense applied on BOTH sides of the wire (client pre-spool and
/// server pre-envelope) and for EVERY agent/event, not just the supported pair:
/// a raw assistant-message field must never reach the spool, the wire, tracing,
/// or storage unless the explicit opt-in path re-introduces it as a sanitized,
/// capped excerpt. Only top-level keys are inspected — the same scope
/// as `body_is_subagent`, and where every supported harness places the field.
pub fn strip_assistant_message_raw(raw: &mut serde_json::Value) -> bool {
let Some(object) = raw.as_object_mut() else {
return false;
};
let mut removed = false;
for field in ASSISTANT_MESSAGE_FIELDS {
if object.remove(*field).is_some() {
removed = true;
}
}
removed
}
#[cfg(test)]
mod tests {
use super::*;
/// Only Claude Code, Codex, and OpenCode Stop are capture candidates; every
/// other agent/event pair across the full agent surface must return `None`.
#[test]
fn only_supported_stop_events_are_capture_candidates() {
let events = [
HookEvent::SessionStart,
HookEvent::UserPrompt,
HookEvent::PreToolUse,
HookEvent::PostToolUse,
HookEvent::PreCompact,
HookEvent::PostCompaction,
HookEvent::Notification,
HookEvent::Stop,
HookEvent::SessionEnd,
HookEvent::SubagentStart,
HookEvent::SubagentStop,
HookEvent::Other,
];
for agent in AgentKind::ALL {
for event in events {
let expected = matches!(
agent,
AgentKind::ClaudeCode | AgentKind::Codex | AgentKind::OpenCode
) && event == HookEvent::Stop;
assert_eq!(
assistant_message_field(agent, event).is_some(),
expected,
"agent={agent:?} event={event:?}"
);
}
}
}
/// The strip must cover every field the closed table can name, or an opted-in
/// agent/event could carry a raw field the strip misses.
#[test]
fn closed_table_fields_are_all_stripped() {
let events = [
HookEvent::SessionStart,
HookEvent::UserPrompt,
HookEvent::PreToolUse,
HookEvent::PostToolUse,
HookEvent::PreCompact,
HookEvent::PostCompaction,
HookEvent::Notification,
HookEvent::Stop,
HookEvent::SessionEnd,
HookEvent::SubagentStart,
HookEvent::SubagentStop,
HookEvent::Other,
];
for agent in AgentKind::ALL {
for event in events {
if let Some(field) = assistant_message_field(agent, event) {
assert!(
ASSISTANT_MESSAGE_FIELDS.contains(&field),
"closed-table field {field:?} is not in the strip set"
);
}
}
}
}
/// The strip is unconditional: it removes the raw field regardless of agent
/// and reports the removal, so a client that never verified the agent still
/// cannot leak it.
#[test]
fn strip_removes_field_and_reports_change() {
let mut raw = serde_json::json!({
"session_id": "s1",
"last_assistant_message": "SENTINEL_ASSISTANT_MESSAGE",
});
assert!(strip_assistant_message_raw(&mut raw));
assert!(raw.get("last_assistant_message").is_none());
assert_eq!(raw.get("session_id").and_then(|v| v.as_str()), Some("s1"));
}
#[test]
fn strip_is_noop_when_absent_or_not_object() {
let mut without = serde_json::json!({"session_id": "s1"});
assert!(!strip_assistant_message_raw(&mut without));
assert_eq!(without, serde_json::json!({"session_id": "s1"}));
let mut array = serde_json::json!(["last_assistant_message"]);
assert!(!strip_assistant_message_raw(&mut array));
assert_eq!(array, serde_json::json!(["last_assistant_message"]));
}
fn stop_env(raw: serde_json::Value, requested: bool) -> HookEnvelope {
HookEnvelope::from_query_and_body(
crate::payload::HookQuery {
event: "stop".into(),
agent: Some("claude-code".into()),
capture_assistant: requested.then(|| "1".to_string()),
..Default::default()
},
raw,
)
}
#[test]
fn client_transform_splices_sanitized_capped_excerpt() {
let mut raw = serde_json::json!({
"session_id": "s1",
"last_assistant_message": "fixed the bug"
});
let out = transform_for_client(&mut raw, AgentKind::ClaudeCode, HookEvent::Stop);
assert!(out.changed && out.captured);
assert!(raw.get("last_assistant_message").is_none());
let marker = raw.get(ASSISTANT_MARKER_KEY).expect("protocol spliced");
let protocol = AssistantCaptureProtocol::parse(marker).expect("valid v1 protocol");
assert_eq!(protocol.version, ASSISTANT_PROTOCOL_VERSION);
assert_eq!(protocol.excerpt, "fixed the bug");
}
#[test]
fn client_transform_scrubs_before_truncating() {
// A built-in secret pattern must be redacted in the excerpt.
let secret = "AKIA".to_string() + &"A".repeat(16); // AWS access key id shape
let mut raw = serde_json::json!({ "last_assistant_message": format!("key {secret}") });
let out = transform_for_client(&mut raw, AgentKind::ClaudeCode, HookEvent::Stop);
assert!(out.captured);
let excerpt = raw[ASSISTANT_MARKER_KEY]["excerpt"].as_str().unwrap();
assert!(!excerpt.contains(&secret), "secret survived: {excerpt}");
assert!(
excerpt.contains("[REDACTED:aws_key]"),
"not redacted: {excerpt}"
);
}
#[test]
fn client_transform_truncates_multibyte_within_cap() {
let big = "é".repeat(ASSISTANT_EXCERPT_MAX_BYTES); // 2 bytes each → 2x the cap
let mut raw = serde_json::json!({ "last_assistant_message": big });
let out = transform_for_client(&mut raw, AgentKind::ClaudeCode, HookEvent::Stop);
assert!(out.captured);
let excerpt = raw[ASSISTANT_MARKER_KEY]["excerpt"].as_str().unwrap();
assert!(excerpt.len() <= ASSISTANT_EXCERPT_MAX_BYTES, "over cap");
assert!(excerpt.ends_with('…'), "truncation marker missing");
// Valid UTF-8 (no split codepoint): re-parsing as str succeeds by construction.
assert!(std::str::from_utf8(excerpt.as_bytes()).is_ok());
}
#[test]
fn client_transform_strips_but_omits_protocol_for_empty_or_oversized() {
for value in ["", &"x".repeat(ASSISTANT_MESSAGE_MAX_INPUT_BYTES + 1)] {
let mut raw = serde_json::json!({ "last_assistant_message": value });
let out = transform_for_client(&mut raw, AgentKind::ClaudeCode, HookEvent::Stop);
assert!(!out.captured, "value {:?} must not capture", value.len());
assert!(
raw.get("last_assistant_message").is_none(),
"raw not stripped"
);
assert!(
raw.get(ASSISTANT_MARKER_KEY).is_none(),
"protocol spliced anyway"
);
}
}
#[test]
fn client_transform_ignores_non_candidate_agent_event() {
// A non-candidate (agent, event): a candidate agent on a non-Stop event.
// The raw field is still stripped defensively, and no protocol is spliced.
let mut raw = serde_json::json!({ "last_assistant_message": "hi" });
let out = transform_for_client(&mut raw, AgentKind::Codex, HookEvent::PostToolUse);
assert!(!out.captured);
assert!(raw.get("last_assistant_message").is_none());
assert!(raw.get(ASSISTANT_MARKER_KEY).is_none());
}
#[test]
fn client_transform_captures_codex_stop() {
// Codex Stop is now a candidate (#743): the assistant excerpt is captured
// and the raw field removed, same as Claude Code.
let mut raw = serde_json::json!({ "last_assistant_message": "codex done" });
let out = transform_for_client(&mut raw, AgentKind::Codex, HookEvent::Stop);
assert!(out.captured);
assert!(raw.get("last_assistant_message").is_none());
assert!(raw.get(ASSISTANT_MARKER_KEY).is_some());
}
#[test]
fn client_transform_captures_opencode_stop_before_spooling() {
let secret = "AKIA".to_string() + &"A".repeat(16);
let mut raw = serde_json::json!({
"last_assistant_message": format!("Completed work with {secret}"),
"turn_checkpoint": true,
});
let out = transform_for_client(&mut raw, AgentKind::OpenCode, HookEvent::Stop);
assert!(out.captured && out.changed);
assert!(raw.get("last_assistant_message").is_none());
assert!(!raw.to_string().contains(&secret));
assert_eq!(raw["turn_checkpoint"], true);
assert!(
raw[ASSISTANT_MARKER_KEY]["excerpt"]
.as_str()
.unwrap()
.contains("Completed work")
);
}
#[test]
fn backstop_populates_body_when_all_gates_pass() {
let mut raw = serde_json::json!({ "last_assistant_message": "done" });
transform_for_client(&mut raw, AgentKind::ClaudeCode, HookEvent::Stop);
let mut env = stop_env(raw, true);
apply_assistant_backstop(&mut env, true);
assert_eq!(env.body_excerpt.as_deref(), Some("done"));
assert!(
env.raw.get(ASSISTANT_MARKER_KEY).is_none(),
"marker persisted"
);
}
#[test]
fn backstop_drops_when_server_off_or_flag_absent() {
let make = || {
let mut raw = serde_json::json!({ "last_assistant_message": "done" });
transform_for_client(&mut raw, AgentKind::ClaudeCode, HookEvent::Stop);
raw
};
// Server disabled.
let mut env = stop_env(make(), true);
apply_assistant_backstop(&mut env, false);
assert!(env.body_excerpt.is_none());
assert!(
env.raw.get(ASSISTANT_MARKER_KEY).is_none(),
"marker still consumed"
);
// Query flag absent (client did not request).
let mut env = stop_env(make(), false);
apply_assistant_backstop(&mut env, true);
assert!(env.body_excerpt.is_none());
}
#[test]
fn backstop_caps_oversized_excerpt_server_side() {
// A forged/buggy client can satisfy the gates with an excerpt far above
// the 2 KB cap (the client-side truncation is not trustworthy). The
// server must re-enforce the cap at the persistence boundary.
let huge = "a".repeat(ASSISTANT_EXCERPT_MAX_BYTES * 500);
let raw = serde_json::json!({
ASSISTANT_MARKER_KEY: { "version": 1, "excerpt": huge }
});
let mut env = stop_env(raw, true);
apply_assistant_backstop(&mut env, true);
let body = env.body_excerpt.expect("gates pass, body set");
assert!(
body.len() <= ASSISTANT_EXCERPT_MAX_BYTES,
"server did not cap oversized excerpt: {} bytes",
body.len()
);
}
#[test]
fn backstop_rejects_forged_empty_and_bad_version() {
for marker in [
serde_json::json!({ "version": 1, "excerpt": "" }),
serde_json::json!({ "version": 2, "excerpt": "future" }),
serde_json::json!({ "version": 1, "excerpt": "x", "extra": true }),
serde_json::json!({ "excerpt": "no version" }),
] {
let raw = serde_json::json!({ ASSISTANT_MARKER_KEY: marker });
let mut env = stop_env(raw, true);
apply_assistant_backstop(&mut env, true);
assert!(
env.body_excerpt.is_none(),
"forged marker accepted: {:?}",
env.body_excerpt
);
}
}
#[test]
fn backstop_ignores_non_stop_event() {
let raw = serde_json::json!({
ASSISTANT_MARKER_KEY: { "version": 1, "excerpt": "x" }
});
let mut env = HookEnvelope::from_query_and_body(
crate::payload::HookQuery {
event: "user-prompt-submit".into(),
agent: Some("claude-code".into()),
capture_assistant: Some("1".into()),
..Default::default()
},
raw,
);
apply_assistant_backstop(&mut env, true);
assert!(env.body_excerpt.is_none());
}
}