Skip to content

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.md
index 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.0
stripped too. The server applies the same strip defensively on `/hook` and
`/hook/batch` before building an envelope. This field was already never
persisted, 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 to
native 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 2d1aed89..a22c411d 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -382,9 +382,9 @@ capability output reflects the selected integration. See the canonical
Some 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 pending
spooled events drain with the field stripped as well. Installs that run the
`.sh`/`.ps1` script fallback (the Docker script bundle or an explicit