Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: narrow assistant payload hardening
AkitaOnRails60c9a882beda
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9b3feffe..d1310111 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -95,8 +95,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0stripped too. The server applies the same strip defensively on `/hook` and`/hook/batch` before building an envelope. This field was already neverpersisted, so there is no behavior change; it closes a raw-text exposure in- the spool/wire ahead of the opt-in assistant/Stop capture landing in a later- release. Upgrading the binary is sufficient for native Claude Code installs;+ the spool/wire. Optional assistant/Stop capture proposed in #196 remains+ disabled. Upgrading the binary is sufficient for native Claude Code installs;script-fallback installs (Docker wrapper, `AI_MEMORY_HOOK_PLATFORM=posix`)should run `ai-memory install-hooks --agent claude-code --apply` to migrate tonative commands and close the residual local-wire vector ([#196]).diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 7e5e672b..3999733a 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -330,10 +330,10 @@ where};// Defensively drop any raw assistant-message field (e.g. Claude Code's// `last_assistant_message` on Stop) BEFORE it can reach the local spool or- // the wire (#196). The explicit opt-in capture path lands in a later PR;- // today this field is never persisted, so stripping it pre-spool closes a- // raw-text exposure with no behavior change. Reserialize only when we- // actually removed something, so unrelated events keep byte-exact spool+ // the wire (#196). Optional capture remains disabled, so stripping it+ // pre-spool closes a raw-text exposure with no persisted-data behavior+ // change. Reserialize only when we actually removed something, so unrelated+ // events keep byte-exact spool// bodies (see `native_hook_accepts_plain_and_bom_prefixed_json`).if ai_memory_hooks::strip_assistant_message_raw(&mut json) {payload = serde_json::to_string(&json)?;diff --git a/crates/ai-memory-hooks/src/assistant_capture.rs b/crates/ai-memory-hooks/src/assistant_capture.rsindex 7e79d525..5ff76642 100644--- a/crates/ai-memory-hooks/src/assistant_capture.rs+++ b/crates/ai-memory-hooks/src/assistant_capture.rs@@ -1,64 +1,20 @@-//! Assistant-message capture plumbing (issue #196).+//! Raw assistant-message stripping (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, opt-in feature landing across later PRs.-//!-//! This module owns the single source of truth for WHICH raw field carries the-//! assistant message per agent/event, plus the unconditional strip that keeps-//! that raw field off the local spool, the wire, tracing, and storage until the-//! opt-in path deliberately re-introduces a sanitized, capped excerpt.--use ai_memory_core::AgentKind;--use crate::payload::HookEvent;--/// Protocol version for the opt-in `_ai_memory_assistant` body marker the client-/// attaches once capture is enabled (later PR). Defined here so the wire-/// contract has one home from the start.-pub const ASSISTANT_PROTOCOL_VERSION: u8 = 1;--/// Hard ceiling on the raw assistant-message string the client reads before-/// sanitizing/truncating (later PR). Oversized input is treated as absent.-pub const ASSISTANT_MESSAGE_MAX_INPUT_BYTES: usize = 64 * 1024;+//! string. The text can contain code, secrets, or content from paths ai-memory+//! never otherwise sees, so the raw field is removed before spooling, transport,+//! tracing, or storage. Optional capture remains disabled.-/// Byte cap on the sanitized excerpt the opt-in path persists (later PR). 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.+/// Raw top-level field names known to carry assistant messages.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: only `ClaudeCode + Stop` is supported today. 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`).-#[must_use]-pub fn assistant_message_field(agent: AgentKind, event: HookEvent) -> Option<&'static str> {- match (agent, event) {- (AgentKind::ClaudeCode, HookEvent::Stop) => Some("last_assistant_message"),- _ => None,- }-}-/// 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 (later PR) 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.+/// This defense is applied on both sides of the wire (client pre-spool and+/// server pre-envelope) and for every agent/event. Only top-level keys are+/// inspected, matching where supported harnesses place the field.pub fn strip_assistant_message_raw(raw: &mut serde_json::Value) -> bool {let Some(object) = raw.as_object_mut() else {return false;@@ -76,66 +32,6 @@ pub fn strip_assistant_message_raw(raw: &mut serde_json::Value) -> bool {mod tests {use super::*;- /// Only `ClaudeCode + Stop` is a capture candidate; every other agent/event- /// pair across the full agent surface must return `None`.- #[test]- fn only_claude_stop_is_a_capture_candidate() {- 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 = agent == AgentKind::ClaudeCode && 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.diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rsindex 7a2ff8a8..d6fabd2a 100644--- a/crates/ai-memory-hooks/src/lib.rs+++ b/crates/ai-memory-hooks/src/lib.rs@@ -21,7 +21,7 @@//! This crate does not read process environment directly; server configuration//! is resolved once by `ai-memory-cli` and threaded in as typed state.-pub mod assistant_capture;+mod assistant_capture;pub mod capture_policy;pub mod log;pub mod payload;@@ -32,10 +32,7 @@ pub mod workstream;// Re-export the sanitizer types from core so callers that grew up// pointing at this crate's `sanitize` module keep working.pub use ai_memory_core::{SanitizeConfig, Sanitized, Sanitizer};-pub use assistant_capture::{- ASSISTANT_EXCERPT_MAX_BYTES, ASSISTANT_MESSAGE_MAX_INPUT_BYTES, ASSISTANT_PROTOCOL_VERSION,- assistant_message_field, strip_assistant_message_raw,-};+pub use assistant_capture::strip_assistant_message_raw;pub use capture_policy::{CaptureConfig, CaptureDecision, CaptureDisposition, CapturePolicy, CaptureProtocol,CaptureSource, ExtractionState, PolicyState, ToolFamily,diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex 55e0071f..673c68be 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -107,11 +107,8 @@ pub struct HookEnvelope {pub raw: serde_json::Value,}-/// Manual `Debug` that never renders `raw` (#196). `raw` is the agent's full-/// payload; a stray `?env` / `%env` in a future tracing span would otherwise-/// copy it verbatim into the rolling log file on disk — including the opt-in-/// assistant excerpt landing in a later PR. Every other field stays visible so-/// the envelope is still debuggable.+/// Manual `Debug` that omits raw and derived hook content. A stray `?env` or+/// `%env` in a tracing span must not copy prompt or tool content into logs.impl std::fmt::Debug for HookEnvelope {fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {f.debug_struct("HookEnvelope")@@ -127,10 +124,17 @@ impl std::fmt::Debug for HookEnvelope {"recall_default_global_requested",&self.recall_default_global_requested,)+ .field("managed_run", &self.managed_run).field("extension", &self.extension).field("source_event", &self.source_event)- .field("title_hint", &self.title_hint)- .field("body_excerpt", &self.body_excerpt)+ .field(+ "title_hint",+ &self.title_hint.as_ref().map(|_| "<redacted>"),+ )+ .field(+ "body_excerpt",+ &self.body_excerpt.as_ref().map(|_| "<redacted>"),+ ).field("raw", &"<redacted>").finish()}@@ -821,29 +825,36 @@ mod tests {}#[test]- fn debug_never_renders_raw_payload() {- // `raw` holds the agent's full payload; the manual Debug impl must redact- // it so a stray `?env` in a tracing span cannot copy it into the rolling- // log file on disk (#196). Other fields stay visible for debugging.+ fn debug_never_renders_hook_content() {let env = HookEnvelope::from_query_and_body(HookQuery {- event: "stop".into(),+ event: "user-prompt".into(),agent: Some("claude-code".into()),+ managed_run: Some("run-1".into()),..Default::default()},serde_json::json!({"session_id": "dbg",- "secret": "SENTINEL_RAW_PAYLOAD"+ "prompt": "SENTINEL_DERIVED_CONTENT",+ "secret": "SENTINEL_RAW_PAYLOAD",}),);+ assert_eq!(+ env.body_excerpt.as_deref(),+ Some("SENTINEL_DERIVED_CONTENT")+ );let rendered = format!("{env:?}");assert!(!rendered.contains("SENTINEL_RAW_PAYLOAD"),"Debug leaked the raw payload: {rendered}");+ assert!(+ !rendered.contains("SENTINEL_DERIVED_CONTENT"),+ "Debug leaked derived hook content: {rendered}"+ );assert!(rendered.contains("<redacted>"), "raw was not redacted");- // Sanity: the redaction did not blank the whole struct.- assert!(rendered.contains("Stop"), "event field went missing");+ assert!(rendered.contains("UserPrompt"), "event field went missing");+ assert!(rendered.contains("run-1"), "managed run field went missing");}#[test]diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex 93c34a5d..f377f3a4 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -439,7 +439,7 @@ async fn handle_hook(actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,Json(mut body): Json<serde_json::Value>,) -> impl IntoResponse {- // Incondicional backstop (#196): drop any raw assistant-message field on the+ // Unconditional backstop (#196): drop any raw assistant-message field on the// `Value` before it becomes a `HookEnvelope`, so the field can never reach// `body_excerpt`, tracing, or the store — regardless of client version.crate::assistant_capture::strip_assistant_message_raw(&mut body);diff --git a/docs/install.md b/docs/install.mdindex 2d1aed89..a22c411d 100644--- a/docs/install.md+++ b/docs/install.md@@ -382,9 +382,9 @@ capability output reflects the selected integration. See the canonicalSome agent harnesses attach the assistant's final turn to their `Stop` event —Claude Code sends it as a raw `last_assistant_message`. That text is never-persisted, and the native hook binary now strips the raw field before it can-reach the local spool or the wire; the server strips it defensively on arrival-too. Explicit, sanitized opt-in capture of this text ships in a later release.+persisted, and the native hook binary strips the raw field before it can reach+the local spool or the wire; the server strips it defensively on arrival too.+Optional assistant/Stop capture proposed in issue #196 remains disabled.Upgrading the binary is sufficient for native Claude Code installs, and pendingspooled events drain with the field stripped as well. Installs that run the`.sh`/`.ps1` script fallback (the Docker script bundle or an explicit