Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(hooks): opt-in assistant/Stop capture for Claude Code (#196)
Samir Hanna Verzaf28029c690ea
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4c62eab5..3d158d4b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Opt-in assistant/Stop capture for Claude Code (#196). When BOTH the server+ (`capture_assistant = true` / `AI_MEMORY_CAPTURE_ASSISTANT=true`) and the+ client (`install-hooks --agent claude-code --capture-assistant`) opt in, a+ Claude Code `Stop` event carries a sanitized, 2 KB-capped excerpt of the+ assistant's final turn as the Stop body. The client sanitizes with the+ built-in patterns and truncates before the excerpt ever touches the spool or+ wire, splicing a versioned `_ai_memory_assistant` marker into the body and a+ `capture_assistant=1` flag onto the event URL; the server re-scrubs with its+ configured `[sanitize]` patterns and re-enforces the 2 KB cap at the+ persistence boundary (never trusting the client's length). Off by default,+ and any gate failure (server off, wrong agent/event, malformed or+ future-versioned marker, empty excerpt) degrades to an empty Stop with the+ same `202` response. Assistant text is privacy-sensitive — see `SECURITY.md`+ for what it can contain and where it flows. Script-fallback installs cannot+ sanitize the field and drop the whole Stop event instead; move to a native+ install to capture it.## [1.17.3] - 2026-07-22### Fixeddiff --git a/README.md b/README.mdindex 7052f400..14b0f760 100644--- a/README.md+++ b/README.md@@ -22,7 +22,7 @@| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). || Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. || Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](docs/windows.md). |-| Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. |+| Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). || Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. No automatic true session-end hook, so run `ai-memory finalize-session` when you need a final summary/handoff. || Devin CLI | Supported | MCP config + lifecycle hooks. Hooks use Devin's `PostCompaction` event, inject handoffs via `hookSpecificOutput.additionalContext`, and omit subagent events because Devin does not expose them. || OpenCode | Supported | Remote MCP config + generated TypeScript plugin; generated plugin enforces capture exclusions. |diff --git a/SECURITY.md b/SECURITY.mdindex 8321e229..881ca06d 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -43,6 +43,27 @@ the project is and is not designed to defend against.`(workspace_id, project_id)`. A purge operation for project A cannotdelete files that also belong to project B.+- **Assistant/Stop capture is opt-in and sanitized (#196).** The assistant's+ final turn is never persisted by default. Storing it requires a **double+ opt-in** — `capture_assistant` on the server and `install-hooks+ --capture-assistant` on the client. When enabled, be aware that:+ - The excerpt is sanitized twice — the client scrubs with the built-in+ patterns *before* it reaches the spool or wire, and the server re-scrubs+ with its configured `[sanitize]` patterns before storing. Operator+ `extra_patterns` run only on the server side, so a secret matched only by an+ `extra_patterns` rule may still sit in the excerpt on the client spool/wire+ before it reaches the server. Client-side redactions are irreversible: the+ server's `allowlist` cannot restore text the client already replaced with+ `[REDACTED]`.+ - Captured assistant text flows into the consolidation and reviewer prompts,+ and — if you configure a cloud LLM provider — is sent to that provider.+ - The opt-in is **global** to the install: there is no per-project marker to+ exclude a sensitive repository once the flag is on (assistant text is not+ path-attributable). Turn the server flag off to disable it everywhere.+ - The excerpt can quote code, secrets, or content from paths ai-memory never+ sees; the `Sanitizer` is a best-effort credential strip, not a guarantee+ (see the injection note below).+### Out of scope for v1- **Multi-tenant authentication and authorisation.** There is one bearer@@ -53,7 +74,11 @@ the project is and is not designed to defend against.controls, etc.).- **MCP tool-call injection via agent output.** The privacy strip(`Sanitizer`) removes obvious credential patterns from hook payloads, but- it is not a comprehensive injection fence.+ it is not a comprehensive injection fence. This applies to the opt-in+ assistant/Stop excerpt too: it is untrusted text (it can echo whatever a+ tool put in the assistant's response) that, once captured, flows into the+ consolidation/reviewer prompts. Enabling `capture_assistant` widens this+ surface — leave it off unless you accept that trade-off.- **Denial of service.** The server is not hardened against a malicious localactor hammering it with requests.diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 2dff993e..e0bae3aa 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -1345,6 +1345,13 @@ pub struct HookArgs {/// Inspect capture policy without spooling, draining, or contacting the server.#[arg(long)]pub check_capture: bool,+ /// Opt in to assistant/Stop capture: on a Claude Code `stop` event, attach a+ /// sanitized, capped excerpt of the assistant's final turn as the Stop body.+ /// Baked onto the native `stop` command by+ /// `install-hooks --capture-assistant`; the server must also enable+ /// `capture_assistant`. No effect on other events (#196).+ #[arg(long)]+ pub capture_assistant: bool,}/// Arguments for hidden `hook-drain`.@@ -1413,6 +1420,13 @@ pub struct InstallHooksArgs {/// identical to prior behavior.#[arg(long, value_enum, default_value_t = ProjectStrategyArg::Basename)]pub project_strategy: ProjectStrategyArg,+ /// Bake `--capture-assistant` onto the installed native `stop` command so a+ /// Claude Code `stop` event carries a sanitized excerpt of the assistant's+ /// final turn (#196). Only valid for `--agent claude-code` on a native+ /// platform; the server must also set `capture_assistant = true`. Re-running+ /// without this flag removes it (idempotent). Default off.+ #[arg(long)]+ pub capture_assistant: bool,}/// Arguments for `install-mcp`.diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 3999733a..9a892b70 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -328,16 +328,29 @@ wherereturn Ok(());}};- // 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). 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)?;- }+ // Assistant/Stop capture (#196). On an opted-in install+ // (`install-hooks --capture-assistant`), extract the assistant message,+ // sanitize + cap it, and splice the versioned `_ai_memory_assistant` marker+ // into the body. Otherwise just strip any raw assistant field defensively —+ // the field is never persisted until the server-gated opt-in accepts it.+ // Reserialize only when the JSON actually changed, so unrelated events keep+ // byte-exact spool bodies (see `native_hook_accepts_plain_and_bom_prefixed_json`).+ let capture_assistant = if args.capture_assistant {+ let transform = ai_memory_hooks::transform_for_client(+ &mut json,+ AgentKind::from_wire(&args.agent),+ ai_memory_hooks::HookEvent::parse(&args.event),+ );+ if transform.changed {+ payload = serde_json::to_string(&json)?;+ }+ transform.captured+ } else {+ if ai_memory_hooks::strip_assistant_message_raw(&mut json) {+ payload = serde_json::to_string(&json)?;+ }+ false+ };let (policy_cwd, canonical_session_id) = hook_context(&args.agent, &json);let policy = policy_cwd.as_deref().map(capture_policy);let tool_event = is_tool_event(&args.event);@@ -411,9 +424,17 @@ where.ok().flatten().is_some();+ // Append the opt-in capture flag outside the marker query so the server can+ // gate on it (#196). Only present when a valid protocol was actually spliced+ // into this event's body, so the flag and the marker always travel together.+ let capture_qs = if capture_assistant {+ "&capture_assistant=1"+ } else {+ ""+ };let event_url = format!(- "{base}/hook?event={}&agent={}{}",- args.event, args.agent, hook_qs+ "{base}/hook?event={}&agent={}{}{}",+ args.event, args.agent, hook_qs, capture_qs);let entry = hook_spool::entry_for(event_url,@@ -574,6 +595,7 @@ mod tests {auth_token: None,project_strategy: None,check_capture: false,+ capture_assistant: false,}}@@ -1044,6 +1066,7 @@ mod tests {auth_token: None,project_strategy: None,check_capture: false,+ capture_assistant: false,};run_with_payload(@@ -1085,6 +1108,7 @@ mod tests {auth_token: None,project_strategy: None,check_capture: false,+ capture_assistant: false,};run_with_payload(@@ -1125,6 +1149,7 @@ mod tests {auth_token: None,project_strategy: None,check_capture: false,+ capture_assistant: false,};run_with_payload(Some(data_dir), args, "{}".into(), &mut stdout, |_path| {@@ -1151,6 +1176,7 @@ mod tests {auth_token: None,project_strategy: None,check_capture: false,+ capture_assistant: false,};run_with_payload(diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rsindex a2f6e4af..4fc71404 100644--- a/crates/ai-memory-cli/src/commands/hook_spool.rs+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs@@ -944,6 +944,42 @@ mod tests {assert_eq!(loaded.body, body, "clean body must stay byte-exact");}+ #[test]+ fn drain_preserves_capture_flag_and_protocol_round_trip() {+ // An opted-in Stop entry carries `capture_assistant=1` on the URL and the+ // sanitized `_ai_memory_assistant` marker in the body. The drain must+ // preserve BOTH through spool → load → batch: the load-time strip only+ // targets the raw `last_assistant_message`, never the protocol (#196).+ let tmp = tempfile::tempdir().unwrap();+ let spool = spool_dir(tmp.path());+ let entry = entry_for(+ "https://x/hook?event=stop&agent=claude-code&capture_assistant=1".into(),+ r#"{"session_id":"s","_ai_memory_assistant":{"version":1,"excerpt":"done"}}"#.into(),+ None,+ false,+ );+ enqueue(&spool, &entry).unwrap();+ let path = list_entries(&spool).unwrap().into_iter().next().unwrap();++ let mut result = DrainResult::default();+ let loaded = load_live_entry(&path, &mut result).expect("entry is live");+ assert!(loaded.url.contains("capture_assistant=1"), "flag dropped");+ assert!(+ loaded.body.contains("_ai_memory_assistant"),+ "protocol dropped"+ );++ let batch = batch_payload(&[(path, loaded)]).expect("batch built");+ assert!(+ batch.contains("capture_assistant=1"),+ "batch lost the capture flag: {batch}"+ );+ assert!(+ batch.contains("_ai_memory_assistant"),+ "batch lost the protocol: {batch}"+ );+ }+#[cfg(unix)]#[test]fn enqueue_creates_spool_dir_private() {diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex 291581e6..350da1b1 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -219,6 +219,18 @@ pub fn run(config: &Config, args: InstallHooksArgs) -> Result<()> {"[ai-memory] selected shell/PowerShell compatibility path does not enforce capture-policy v1; use a native platform selection or generated integration.");}+ // Assistant/Stop capture is Claude Code + native-platform only (#196). No+ // silent fallback: bail so an operator on a script-fallback platform or a+ // different agent is told the flag has no effect instead of installing a+ // command whose capture would be silently dropped.+ if args.capture_assistant && !capture_assistant_allowed(args.agent) {+ anyhow::bail!(+ "--capture-assistant requires --agent claude-code on a native hook platform \+ (PosixNative/WindowsNative). The current selection uses the script fallback or a \+ different agent, where the opt-in cannot take effect. Remove --capture-assistant or \+ switch to a native Claude Code install."+ );+ }if args.apply {return match args.agent {AgentChoice::OpenCode => apply_to_opencode_plugin(&server_url, auth, &args),@@ -290,6 +302,7 @@ pub fn run(config: &Config, args: InstallHooksArgs) -> Result<()> {&config.data_dir,strategy,&settings_path,+ args.capture_assistant,)}AgentChoice::Codex => {@@ -790,6 +803,14 @@ fn overlay_event_hooks(/// Mutate `~/.claude/settings.json` in place: replace the hook entries/// ai-memory cares about (`CLAUDE_CODE_EVENTS`); preserve every other hook the/// user has wired up to other tools.+/// Whether `--capture-assistant` may take effect for this agent + platform+/// (#196): Claude Code on a native hook platform only. Any other agent or a+/// script-fallback platform cannot honor the opt-in, so the installer bails+/// instead of enabling it silently.+fn capture_assistant_allowed(agent: AgentChoice) -> bool {+ matches!(agent, AgentChoice::ClaudeCode) && local_hook_policy_v1_supported()+}+fn apply_to_claude_code_settings(hooks_dir: &Path,server_url: &str,@@ -810,6 +831,7 @@ fn apply_to_claude_code_settings(auth_token,Some(data_dir),strategy,+ args.capture_assistant,);let our_hooks = payload.get("hooks")@@ -2912,6 +2934,7 @@ fn render_claude_code(data_dir: &Path,project_strategy: Option<&str>,settings_path: &Path,+ capture_assistant: bool,) -> Result<()> {// Soft check: warn (don't bail) if a script is missing. The user// may be running this command inside docker against a host path@@ -2936,6 +2959,7 @@ fn render_claude_code(auth_token,Some(data_dir),project_strategy,+ capture_assistant,);let serialized =serde_json::to_string_pretty(&payload).context("serializing claude code hook config")?;@@ -3227,6 +3251,37 @@ mod tests {use std::process::Command;use tempfile::TempDir;+ #[test]+ fn capture_assistant_allowed_only_for_claude_native() {+ use crate::cli::AgentChoice::*;+ // Every non-Claude agent is rejected regardless of platform (#196): the+ // opt-in cannot take effect for them, so the installer must bail.+ for agent in [+ Codex,+ Cursor,+ GeminiCli,+ OpenCode,+ Pi,+ Omp,+ Openclaw,+ AntigravityCli,+ Grok,+ Zero,+ Devin,+ KimiCode,+ ] {+ assert!(+ !capture_assistant_allowed(agent),+ "{agent:?} must not allow --capture-assistant"+ );+ }+ // Claude Code tracks the native-platform gate exactly.+ assert_eq!(+ capture_assistant_allowed(ClaudeCode),+ local_hook_policy_v1_supported()+ );+ }+#[cfg(unix)]fn bash_program_for_installer_test() -> Option<std::path::PathBuf> {Some(std::path::PathBuf::from("bash"))@@ -3365,6 +3420,7 @@ mod tests {fn default_hook_args() -> InstallHooksArgs {InstallHooksArgs {agent: AgentChoice::OpenCode,+ capture_assistant: false,hooks_dir: None,server_url: None,auth_token: None,@@ -3684,6 +3740,7 @@ mod tests {.unwrap();let args = InstallHooksArgs {agent: AgentChoice::Zero,+ capture_assistant: false,config_file: Some(path.clone()),..default_hook_args()};@@ -4503,6 +4560,7 @@ model = "gpt-5"let tmp = TempDir::new().unwrap();let args = InstallHooksArgs {agent: AgentChoice::Omp,+ capture_assistant: false,hooks_dir: None,server_url: Some("http://127.0.0.1:49374".into()),auth_token: None,@@ -4531,6 +4589,7 @@ model = "gpt-5"let path = tmp.path().join("extensions").join("ai-memory.ts");let args = InstallHooksArgs {agent: AgentChoice::Pi,+ capture_assistant: false,hooks_dir: None,server_url: Some("http://127.0.0.1:49374".into()),auth_token: None,@@ -5303,6 +5362,7 @@ command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/sessioconfig_tmp.path(),&InstallHooksArgs {agent: AgentChoice::Devin,+ capture_assistant: false,hooks_dir: Some(hooks_tmp.path().to_path_buf()),server_url: Some("http://127.0.0.1:49374".to_string()),auth_token: None,@@ -5365,6 +5425,7 @@ command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/sessioconfig_tmp.path(),&InstallHooksArgs {agent: AgentChoice::Devin,+ capture_assistant: false,hooks_dir: Some(hooks_tmp.path().to_path_buf()),server_url: Some("http://127.0.0.1:49374".to_string()),auth_token: None,@@ -5416,6 +5477,7 @@ command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/sessiolet args_v1 = InstallHooksArgs {agent: AgentChoice::Devin,+ capture_assistant: false,hooks_dir: Some(hooks_tmp.path().to_path_buf()),server_url: Some("http://127.0.0.1:49374".to_string()),auth_token: None,@@ -5460,6 +5522,7 @@ command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/sessiolet args_config = InstallHooksArgs {agent: AgentChoice::Devin,+ capture_assistant: false,hooks_dir: Some(hooks_tmp.path().to_path_buf()),server_url: Some("http://127.0.0.1:49374".to_string()),auth_token: None,@@ -5529,6 +5592,7 @@ command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/sessioconfig_tmp.path(),&InstallHooksArgs {agent: AgentChoice::Devin,+ capture_assistant: false,hooks_dir: Some(hooks_tmp.path().to_path_buf()),server_url: Some("http://127.0.0.1:49374".to_string()),auth_token: None,diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rsindex 75280fce..b5c8aa09 100644--- a/crates/ai-memory-cli/src/commands/render_shared.rs+++ b/crates/ai-memory-cli/src/commands/render_shared.rs@@ -261,6 +261,7 @@ pub(crate) fn build_claude_code_payload_with_data_dir(auth_token: Option<&str>,data_dir: Option<&Path>,project_strategy: Option<&str>,+ capture_assistant: bool,) -> serde_json::Value {build_hook_payload_for_platform(&CLAUDE_CODE_EVENTS,@@ -274,7 +275,8 @@ pub(crate) fn build_claude_code_payload_with_data_dir(data_dir,project_strategy,)- .allow_claude_windows_exec(),+ .allow_claude_windows_exec()+ .with_capture_assistant(capture_assistant),)}@@ -776,6 +778,9 @@ struct HookCommandContext<'a> {/// snippets keep command-string script fallback even when the platform env/// is overridden to `windows-native`.claude_windows_exec_allowed: bool,+ /// Bake `--capture-assistant` onto the native `stop` command only (#196).+ /// Set exclusively by `install-hooks --agent claude-code --capture-assistant`.+ capture_assistant: bool,}impl<'a> HookCommandContext<'a> {@@ -791,6 +796,7 @@ impl<'a> HookCommandContext<'a> {data_dir,project_strategy,claude_windows_exec_allowed: false,+ capture_assistant: false,}}@@ -798,6 +804,22 @@ impl<'a> HookCommandContext<'a> {self.claude_windows_exec_allowed = true;self}++ const fn with_capture_assistant(mut self, on: bool) -> Self {+ self.capture_assistant = on;+ self+ }+}++/// Bake `--capture-assistant` onto the native `stop` command only (#196), so the+/// other events stay byte-identical. Empty for every other event, and for a+/// context that did not opt in.+fn native_capture_assistant_arg(context: HookCommandContext<'_>, event: &str) -> &'static str {+ if context.capture_assistant && event == "stop" {+ " --capture-assistant"+ } else {+ ""+ }}impl HookCommandPlatform {@@ -1067,6 +1089,7 @@ fn hook_command(context.project_strategy,NativeQuote::Windows,));+ cmd.push_str(native_capture_assistant_arg(context, event));cmd}HookCommandPlatform::PosixNative => {@@ -1095,6 +1118,7 @@ fn hook_command(context.project_strategy,NativeQuote::Posix,));+ cmd.push_str(native_capture_assistant_arg(context, event));cmd}}@@ -1151,6 +1175,11 @@ fn windows_native_exec_spec_with_exe(args.push("--project-strategy".to_string());args.push(strategy.to_string());}+ // Native-exec is the PRIMARY Windows Claude Code path, so the flag must be+ // baked here too — not only in the string form above (#196).+ if context.capture_assistant && event == "stop" {+ args.push("--capture-assistant".to_string());+ }HookHandlerSpec::Exec {command: plain_windows_path_arg(exe),args,@@ -1880,6 +1909,65 @@ check(activeKeep.disposition === "keep" && activeKeep.protocol?.version === 1 &&assert!(args.iter().all(|arg| !arg.contains(r"\\?\")));}+ fn exec_args(script: &str, capture_assistant: bool) -> Vec<String> {+ let spec = windows_native_exec_spec_with_exe(+ Path::new(r"C:\ai-memory\ai-memory.exe"),+ Path::new(script),+ "http://h:49374",+ None,+ HookCommandContext::new(+ HookCommandPlatform::WindowsNative,+ "claude-code",+ None,+ None,+ )+ .with_capture_assistant(capture_assistant),+ );+ let HookHandlerSpec::Exec { args, .. } = spec else {+ panic!("expected exec spec")+ };+ args+ }++ #[test]+ fn capture_assistant_exec_flag_only_on_stop_and_only_when_opted_in() {+ // Bare filenames so `file_stem()` yields the event on any host (a+ // backslash path is a single component on Unix).+ // Opted in: only the `stop` command carries the flag (#196, D1).+ assert!(exec_args("stop.sh", true).contains(&"--capture-assistant".to_string()));+ assert!(+ !exec_args("session-start.sh", true).contains(&"--capture-assistant".to_string()),+ "flag must not leak onto non-stop commands"+ );+ // Not opted in: even the stop command stays byte-identical to before.+ assert!(+ !exec_args("stop.sh", false).contains(&"--capture-assistant".to_string()),+ "flag must be absent without opt-in"+ );+ }++ #[test]+ fn capture_assistant_string_form_only_on_stop() {+ // POSIX + Windows string forms: the flag rides only the stop command.+ for platform in [+ HookCommandPlatform::PosixNative,+ HookCommandPlatform::WindowsNative,+ ] {+ let ctx = HookCommandContext::new(platform, "claude-code", None, None)+ .with_capture_assistant(true);+ let stop = hook_command(Path::new("stop.sh"), "http://h", None, ctx);+ let start = hook_command(Path::new("session-start.sh"), "http://h", None, ctx);+ assert!(+ stop.contains("--capture-assistant"),+ "{platform:?} stop missing flag: {stop}"+ );+ assert!(+ !start.contains("--capture-assistant"),+ "{platform:?} session-start must not carry flag: {start}"+ );+ }+ }+#[test]fn windows_native_exec_form_is_claude_only_and_guarded() {fn handler_for(diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 8f312347..5c56f65a 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -396,6 +396,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT,)),consolidate_on_session_end: config.consolidate_on_session_end,+ capture_assistant_enabled: config.capture_assistant,subagent_sessions: std::sync::Arc::new(tokio::sync::Mutex::new(ai_memory_hooks::SubagentSessionSet::default(),)),diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 8afbdef8..a1a67920 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -96,6 +96,14 @@ pub struct Config {/// and via manual `memory_consolidate`. Set with/// `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true`.pub consolidate_on_session_end: bool,+ /// Server-side opt-in for assistant/Stop capture (#196). When true, the+ /// server honors a client's sanitized `_ai_memory_assistant` marker on a+ /// `Stop` event and persists the excerpt as the Stop body. Off by default;+ /// when off the marker is stripped and the Stop stays empty. The client half+ /// of the double opt-in is baked separately by+ /// `install-hooks --capture-assistant`. Set with+ /// `AI_MEMORY_CAPTURE_ASSISTANT=true`.+ pub capture_assistant: bool,/// Optional embedding provider (`openai`, `voyage`, `google` / `gemini`).pub embedding_provider: Option<String>,/// Optional embedding model override.@@ -361,6 +369,7 @@ impl Default for Config {llm_base_url: None,llm_compat_strict: false,consolidate_on_session_end: false,+ capture_assistant: false,embedding_provider: None,embedding_model: None,embedding_dim: None,diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.tomlindex ba73018d..9b2d36fc 100644--- a/crates/ai-memory-cli/templates/config.default.toml+++ b/crates/ai-memory-cli/templates/config.default.toml@@ -25,6 +25,16 @@ log_level = "info"# hook_rate_per_sec = 0.0# hook_rate_burst = 0.0+# Server-side half of the assistant/Stop capture opt-in (#196). When true, the+# server persists a Claude Code Stop event's final assistant turn (sanitized and+# capped at 2 KB) as the Stop body. OFF by default: assistant text is privacy-+# sensitive — it can quote code, secrets, or content from paths ai-memory never+# sees, and it flows into consolidation/reviewer prompts (and out to a cloud LLM+# provider if one is configured). This is a DOUBLE opt-in: the client must also+# be installed with `ai-memory install-hooks --agent claude-code+# --capture-assistant`. Env equivalent: `AI_MEMORY_CAPTURE_ASSISTANT=true`.+# capture_assistant = false+# M8 retention-sweep parameters.## Formula:diff --git a/crates/ai-memory-cli/tests/hook_payload.rs b/crates/ai-memory-cli/tests/hook_payload.rsindex b16c14a1..b5e05f3d 100644--- a/crates/ai-memory-cli/tests/hook_payload.rs+++ b/crates/ai-memory-cli/tests/hook_payload.rs@@ -13,18 +13,26 @@ fn run_hook(data_dir: &Path, payload: &[u8]) -> Output {}fn run_hook_event(data_dir: &Path, event: &str, payload: &[u8]) -> Output {+ run_hook_full(data_dir, event, payload, false)+}++fn run_hook_full(data_dir: &Path, event: &str, payload: &[u8], capture_assistant: bool) -> Output {+ let mut args = vec![+ "hook".to_string(),+ "--event".to_string(),+ event.to_string(),+ "--agent".to_string(),+ "claude-code".to_string(),+ "--server-url".to_string(),+ "http://127.0.0.1:1".to_string(),+ ];+ if capture_assistant {+ args.push("--capture-assistant".to_string());+ }let mut child = Command::new(bin()).args(["--data-dir"]).arg(data_dir)- .args([- "hook",- "--event",- event,- "--agent",- "claude-code",- "--server-url",- "http://127.0.0.1:1",- ])+ .args(&args).stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::piped())@@ -58,6 +66,17 @@ fn spooled_body(data_dir: &Path) -> String {entry["body"].as_str().expect("spooled body").to_owned()}+fn spooled_entry(data_dir: &Path) -> serde_json::Value {+ // Use the filtered helper: boundary events spawn a detached drainer, so the+ // spool directory can also hold `.drain.lock` / `.json.tmp` while that child+ // is alive. Counting raw directory entries races with it (Windows loses most+ // often).+ let entries = spool_entries(data_dir);+ assert_eq!(entries.len(), 1);+ serde_json::from_slice(&std::fs::read(entries[0].path()).expect("read spool entry"))+ .expect("parse spool entry")+}+#[test]fn native_hook_accepts_plain_and_bom_prefixed_json() {let payload = br#"{"session_id":"windows-test","cwd":"C:\\dev\\project","tool_name":"Read","tool_input":{"file_path":"README.md"}}"#;@@ -158,3 +177,59 @@ fn spool_files_never_leak_the_assistant_field_on_disk() {"raw assistant field key leaked into the spool file bytes");}++#[test]+fn opted_in_stop_splices_protocol_and_capture_flag() {+ // With --capture-assistant, a Stop event spools the sanitized protocol+ // marker (NOT the raw field) and carries capture_assistant=1 on the URL so+ // the server can gate on it (#196).+ let tmp = tempfile::tempdir().expect("tempdir");+ let payload = br#"{"session_id":"opt-in","last_assistant_message":"the fix is here"}"#;++ let output = run_hook_full(tmp.path(), "stop", payload, true);+ assert!(output.status.success());+ assert_eq!(output.stdout, b"{}\n");++ let entry = spooled_entry(tmp.path());+ let body = entry["body"].as_str().expect("spooled body");+ let url = entry["url"].as_str().expect("spooled url");+ assert!(+ !body.contains("last_assistant_message"),+ "raw field survived: {body}"+ );+ assert!(+ body.contains("_ai_memory_assistant"),+ "protocol marker missing: {body}"+ );+ assert!(+ body.contains("the fix is here"),+ "excerpt missing from protocol: {body}"+ );+ assert!(+ url.contains("capture_assistant=1"),+ "capture flag missing from url: {url}"+ );+}++#[test]+fn opted_in_non_stop_event_is_inert() {+ // The flag is a no-op on non-Stop events: no protocol, no capture flag, and+ // (absent any assistant field) the body is byte-exact.+ let tmp = tempfile::tempdir().expect("tempdir");+ let payload = br#"{"session_id":"opt-in","prompt":"hello"}"#;++ let output = run_hook_full(tmp.path(), "user-prompt-submit", payload, true);+ assert!(output.status.success());++ let entry = spooled_entry(tmp.path());+ let url = entry["url"].as_str().expect("spooled url");+ assert!(+ !url.contains("capture_assistant=1"),+ "capture flag leaked onto a non-stop event: {url}"+ );+ assert_eq!(+ entry["body"].as_str().expect("spooled body").as_bytes(),+ payload,+ "unrelated event body must stay byte-exact"+ );+}diff --git a/crates/ai-memory-hooks/src/assistant_capture.rs b/crates/ai-memory-hooks/src/assistant_capture.rsindex 5ff76642..1f743990 100644--- a/crates/ai-memory-hooks/src/assistant_capture.rs+++ b/crates/ai-memory-hooks/src/assistant_capture.rs@@ -1,20 +1,204 @@-//! Raw assistant-message stripping (issue #196).+//! 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. 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.+//! 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};+use serde::{Deserialize, Serialize};++use crate::payload::{HookEnvelope, HookEvent, truncate_utf8_bytes};++/// 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;-/// Raw top-level field names known to carry assistant messages.+/// 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: 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,+ }+}++/// 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 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.+/// 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.pub fn strip_assistant_message_raw(raw: &mut serde_json::Value) -> bool {let Some(object) = raw.as_object_mut() else {return false;@@ -32,6 +216,66 @@ 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.@@ -56,4 +300,173 @@ mod tests {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]"), "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() {+ // Non-Claude agent: raw field still stripped defensively, no protocol.+ let mut raw = serde_json::json!({ "last_assistant_message": "hi" });+ 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_none());+ }++ #[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());+ }}diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rsindex d6fabd2a..8fc67e43 100644--- a/crates/ai-memory-hooks/src/lib.rs+++ b/crates/ai-memory-hooks/src/lib.rs@@ -32,7 +32,12 @@ 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::strip_assistant_message_raw;+// Client-side symbols used by the CLI crate; the server-side `apply_assistant_backstop`+// and the protocol/table internals stay crate-private (router reaches them via+// `crate::assistant_capture`).+pub use assistant_capture::{+ ClientAssistantTransform, strip_assistant_message_raw, transform_for_client,+};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 673c68be..3f9b2e62 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -58,6 +58,12 @@ pub struct HookQuery {/// Invocation-scoped `ai-memory run` lease. Absent for every direct/// harness launch, preserving legacy capture and handoff behavior.pub managed_run: Option<String>,+ /// Client-side opt-in for assistant/Stop capture, baked onto the native+ /// `stop` hook command by `install-hooks --capture-assistant`. A truthy+ /// value tells the server the client deliberately attached a sanitized+ /// `_ai_memory_assistant` excerpt; the server still gates on its own+ /// `capture_assistant` config before persisting it (#196).+ pub capture_assistant: Option<String>,}/// Coalesced view of an incoming hook event after light parsing of the@@ -99,6 +105,11 @@ pub struct HookEnvelope {pub extension: Option<String>,/// Optional source event name from the extension vocabulary.pub source_event: Option<String>,+ /// Whether the client requested assistant/Stop capture for this event+ /// (the `capture_assistant` query flag baked onto the native `stop`+ /// command). The server still gates on its own `capture_assistant` config+ /// before honoring it (#196).+ pub capture_assistant_requested: bool,/// Optional title hint extracted from the body.pub title_hint: Option<String>,/// Optional body excerpt extracted from the agent's raw payload.@@ -125,6 +136,10 @@ impl std::fmt::Debug for HookEnvelope {&self.recall_default_global_requested,).field("managed_run", &self.managed_run)+ .field(+ "capture_assistant_requested",+ &self.capture_assistant_requested,+ ).field("extension", &self.extension).field("source_event", &self.source_event).field(@@ -358,6 +373,7 @@ impl HookEnvelope {let drop_subagent_requested = query_flag_truthy(query.drop_subagent.as_deref());let recall_default_global_requested = query_flag_truthy(query.default_global.as_deref());let managed_run = query.managed_run.filter(|value| !value.trim().is_empty());+ let capture_assistant_requested = query_flag_truthy(query.capture_assistant.as_deref());let extension = normalize_extension_name(query.extension.as_deref());let source_event = extension.as_ref().and_then(|_| {let raw_source = query@@ -415,6 +431,7 @@ impl HookEnvelope {drop_subagent_requested,recall_default_global_requested,managed_run,+ capture_assistant_requested,extension,source_event,title_hint,@@ -734,25 +751,31 @@ fn truncate_for_title(s: &str) -> String {}fn truncate_excerpt(s: &str) -> String {- const MAX: usize = 2_000;- if s.len() <= MAX {- s.to_string()- } else {- // Reserve the ellipsis within the byte cap, not beyond it.- let limit = MAX - '…'.len_utf8();- let mut buf = String::with_capacity(MAX);- let mut end = 0;- for (idx, ch) in s.char_indices() {- let next = idx + ch.len_utf8();- if next > limit {- break;- }- end = next;+ truncate_utf8_bytes(s, 2_000)+}++/// Truncate `s` to at most `max` bytes on a UTF-8 char boundary, reserving the+/// ellipsis within the cap (never beyond it). Shared by the tool-excerpt cap+/// and the opt-in assistant excerpt cap (#196) so there is one UTF-8-safe+/// truncation, two named caps.+pub(crate) fn truncate_utf8_bytes(s: &str, max: usize) -> String {+ if s.len() <= max {+ return s.to_string();+ }+ // Reserve the ellipsis within the byte cap, not beyond it.+ let limit = max.saturating_sub('…'.len_utf8());+ let mut buf = String::with_capacity(max);+ let mut end = 0;+ for (idx, ch) in s.char_indices() {+ let next = idx + ch.len_utf8();+ if next > limit {+ break;}- buf.push_str(&s[..end]);- buf.push('…');- buf+ end = next;}+ buf.push_str(&s[..end]);+ buf.push('…');+ buf}fn normalize_extension_name(value: Option<&str>) -> Option<String> {diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex f377f3a4..7192c83d 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -409,6 +409,12 @@ pub struct HookState {/// session close stays cheap; the LLM checkpoint otherwise happens on/// PreCompact and via manual `memory_consolidate`.pub consolidate_on_session_end: bool,+ /// Opt-in (`AI_MEMORY_CAPTURE_ASSISTANT`): when true, the server honors the+ /// client's `_ai_memory_assistant` protocol on a `Stop` event and persists+ /// the sanitized excerpt as the Stop body. Off by default; when off the+ /// marker is stripped and the Stop stays empty. Double opt-in: the client+ /// must also have been installed with `--capture-assistant` (#196).+ pub capture_assistant_enabled: bool,/// Scoped session keys known to be subagents (seeded by `SubagentStart` / any/// marker-bearing event). For a project that opted into/// `drop_subagent_captures` (via its `.ai-memory.toml`, forwarded as the@@ -443,7 +449,11 @@ async fn handle_hook(// `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);- let env = HookEnvelope::from_query_and_body(query, body);+ let mut env = HookEnvelope::from_query_and_body(query, body);+ // Consume the opt-in `_ai_memory_assistant` marker and, when both opt-ins are+ // on for a supported Stop, populate the Stop body with the sanitized excerpt.+ // Any gate failure leaves an empty Stop with the same 202 "queued" response.+ crate::assistant_capture::apply_assistant_backstop(&mut env, state.capture_assistant_enabled);let Some(env) = inspect_capture_envelope(env) else {return (StatusCode::ACCEPTED, "capture policy dropped");};@@ -605,7 +615,11 @@ async fn handle_hook_batch(// per item before the envelope is built (#196).crate::assistant_capture::strip_assistant_message_raw(&mut item.body);let query = parse_hook_query(&item.url);- let env = HookEnvelope::from_query_and_body(query, item.body);+ let mut env = HookEnvelope::from_query_and_body(query, item.body);+ crate::assistant_capture::apply_assistant_backstop(+ &mut env,+ state.capture_assistant_enabled,+ );let Some(env) = inspect_capture_envelope(env) else {// A protocol-directed drop is committed from the spool's point of// view, but intentionally spends neither ingress capacity nor a@@ -2312,6 +2326,7 @@ mod tests {project_cache: Arc::new(tokio::sync::Mutex::new(ProjectCacheStore::default())),active_project: ActiveProject::new(),consolidate_on_session_end: false,+ capture_assistant_enabled: false,subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),ingest_rate: Arc::new(tokio::sync::Mutex::new(IngestRateLimiter::disabled())),home_dir: None,@@ -2970,6 +2985,98 @@ mod tests {);}+ /// Build a Stop batch item as an opted-in client would: raw field stripped,+ /// sanitized `_ai_memory_assistant` marker spliced in, `capture_assistant=1`+ /// on the URL.+ fn opted_in_stop_item(session_id: &str, message: &str) -> HookBatchItem {+ let mut body = serde_json::json!({+ "session_id": session_id,+ "last_assistant_message": message,+ });+ let out = crate::assistant_capture::transform_for_client(+ &mut body,+ ai_memory_core::AgentKind::ClaudeCode,+ HookEvent::Stop,+ );+ assert!(out.captured, "test fixture must produce a protocol");+ HookBatchItem {+ url: "http://h/hook?event=stop&agent=claude-code&capture_assistant=1".into(),+ body,+ }+ }++ fn stop_session_id(session_id: &str) -> ai_memory_core::SessionId {+ resolve_session_id(&HookEnvelope::from_query_and_body(+ HookQuery {+ event: "stop".into(),+ agent: Some("claude-code".into()),+ session_id: Some(session_id.into()),+ ..Default::default()+ },+ serde_json::json!({ "session_id": session_id }),+ ))+ .unwrap()+ }++ #[tokio::test]+ async fn assistant_capture_round_trips_when_both_opt_ins_on() {+ let tmp = TempDir::new().unwrap();+ let mut state = make_state(&tmp).await;+ state.capture_assistant_enabled = true;+ let state = Arc::new(state);++ let items = vec![opted_in_stop_item("cap-on", "the fix is in config.rs")];+ let response = handle_hook_batch(State(state.clone()), None, Json(items))+ .await+ .into_response();+ assert_eq!(response.status(), StatusCode::OK);++ let observations = state+ .reader+ .observations_for_session(stop_session_id("cap-on"))+ .await+ .unwrap();+ let stop = observations+ .iter()+ .find(|o| o.kind == ai_memory_core::ObservationKind::Stop)+ .expect("Stop persisted");+ assert_eq!(+ stop.body, "the fix is in config.rs",+ "excerpt must be persisted as the Stop body"+ );+ // The synthetic marker must not survive anywhere on disk.+ assert!(!any_file_contains(tmp.path(), b"_ai_memory_assistant"));+ }++ #[tokio::test]+ async fn assistant_capture_stays_empty_when_server_disabled() {+ let tmp = TempDir::new().unwrap();+ // make_state defaults capture_assistant_enabled = false.+ let state = Arc::new(make_state(&tmp).await);++ let items = vec![opted_in_stop_item("cap-off", "should not persist")];+ let response = handle_hook_batch(State(state.clone()), None, Json(items))+ .await+ .into_response();+ assert_eq!(response.status(), StatusCode::OK);++ let observations = state+ .reader+ .observations_for_session(stop_session_id("cap-off"))+ .await+ .unwrap();+ let stop = observations+ .iter()+ .find(|o| o.kind == ai_memory_core::ObservationKind::Stop)+ .expect("Stop still persisted, just empty");+ assert!(+ stop.body.is_empty(),+ "server-off Stop must be empty, got: {:?}",+ stop.body+ );+ assert!(!any_file_contains(tmp.path(), b"should not persist"));+ }+/// `pre-tool-use` query+agent for building an env to recompute a SessionId.fn grok_tool_query() -> HookQuery {HookQuery {diff --git a/crates/ai-memory-mcp/tests/autoscope_multiuser.rs b/crates/ai-memory-mcp/tests/autoscope_multiuser.rsindex 4d4f855c..962496be 100644--- a/crates/ai-memory-mcp/tests/autoscope_multiuser.rs+++ b/crates/ai-memory-mcp/tests/autoscope_multiuser.rs@@ -158,6 +158,7 @@ impl MultiUserHarness {DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT,)),consolidate_on_session_end: false,+ capture_assistant_enabled: false,subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),ingest_rate: Arc::new(tokio::sync::Mutex::new(ai_memory_hooks::IngestRateLimiter::disabled(),diff --git a/crates/ai-memory-mcp/tests/autoscope_stress.rs b/crates/ai-memory-mcp/tests/autoscope_stress.rsindex 5782e83a..f816d754 100644--- a/crates/ai-memory-mcp/tests/autoscope_stress.rs+++ b/crates/ai-memory-mcp/tests/autoscope_stress.rs@@ -157,6 +157,7 @@ impl Harness {DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT,)),consolidate_on_session_end: false,+ capture_assistant_enabled: false,subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),ingest_rate: Arc::new(tokio::sync::Mutex::new(ai_memory_hooks::IngestRateLimiter::disabled(),diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 00e19fe5..7082e700 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -340,6 +340,9 @@ that touch the relevant area.(agentmemory #221 / #143.)6. **Privacy strip is a typed boundary.** `Sanitized<NewObservation>`has no other constructor than `sanitize()`. (design-decisions §14.)+ The opt-in assistant/Stop excerpt (#196) enters through this same+ boundary: the client sanitizes it before it reaches the wire, and the+ server re-scrubs it here with its configured patterns before the write.7. **JSON-schema structured outputs only.** Native provider JSONmodes; no XML, no Instructor wrapping. (agentmemory #492 / #539,cognee #2840.)diff --git a/docs/install.md b/docs/install.mdindex 27bea4ef..9d8adab5 100644--- a/docs/install.md+++ b/docs/install.md@@ -393,21 +393,45 @@ capability output reflects the selected integration. See the canonical[capture exclusions reference](marker-file.md#capture-exclusions).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 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.+Claude Code sends it as a raw `last_assistant_message`. By default that text is+never persisted: the native hook binary strips the raw field before it can reach+the local spool or the wire, and the server strips it defensively on arrival.++**Opt-in capture (#196).** You can opt in to storing a sanitized, 2 KB-capped+excerpt of the assistant's final turn as the Stop body. It is a **double+opt-in** — enable the server first, then the client:++1. **Server:** set `capture_assistant = true` in `config.default.toml` (or+ `AI_MEMORY_CAPTURE_ASSISTANT=true`) and restart `ai-memory serve`.+2. **Client:** re-install the Claude Code hooks with the flag:++ ```bash+ ai-memory install-hooks --agent claude-code --capture-assistant --apply+ ```++The client sanitizes (built-in patterns) and truncates the excerpt before it+touches the spool or wire; the server re-scrubs with its `[sanitize]` patterns+before storing. If either side is off — or the marker is malformed — the Stop+stays empty. Re-running `install-hooks` without `--capture-assistant` removes+the flag (idempotent). `--capture-assistant` is Claude Code + native-platform+only; on any other agent or the script fallback the installer refuses it rather+than enabling something that cannot take effect. Assistant text is+privacy-sensitive — read the `SECURITY.md` notes on what it can contain and where+it flows (consolidation/reviewer prompts, and out to a cloud LLM provider if one+is configured) before enabling it.+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+spooled events drain with the raw field stripped as well. Installs that run the`.sh`/`.ps1` script fallback (the Docker script bundle or an explicit-`AI_MEMORY_HOOK_PLATFORM=posix`) still POST the raw field on the local wire-until they move to native commands. The Docker wrapper deliberately keeps-script commands because a binary path inside its helper container is not valid-on the host; running `install-hooks` through that wrapper refreshes the scripts-but does not convert them. To close the local-wire exposure, install a native-ai-memory client on the agent host, then use that native executable to run-`install-hooks --agent claude-code --apply`. If the script fallback is retained,-the server still strips the field immediately on receipt before persistence.+`AI_MEMORY_HOOK_PLATFORM=posix`) cannot sanitize the assistant text, so a `Stop`+payload still carrying the raw field is dropped whole by the script rather than+POSTed verbatim. The Docker wrapper deliberately keeps script commands because a+binary path inside its helper container is not valid on the host; running+`install-hooks` through that wrapper refreshes the scripts but does not convert+them. To capture assistant text safely, install a native ai-memory client on the+agent host, then use that native executable to run+`install-hooks --agent claude-code --apply`. Even if the script fallback is+retained, the server still strips any raw field on receipt before persistence.Native `ai-memory hook --event ...` commands spool events locally. Session startdoes a short bounded cleanup drain before fetching a handoff; cancellation-pronediff --git a/docs/marker-file.md b/docs/marker-file.mdindex 4c300ae3..bd9f712e 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -203,9 +203,13 @@ its existing tool-response/error excerpt and caps the complete rendered body atbody, and association is only by matching agent-provided call IDs. User-prompt stores its prompttext, notification stores its message/text, and post-compaction stores itssummary; other event bodies are currently empty unless explicitly supported.-Stop and assistant-message capture remain disabled and deferred. The metadata-header is closed; the PostToolUse response/error excerpt remains the existing-bounded content capture.+Stop/assistant-message capture is disabled by default and never persisted; it is+available only through the explicit double opt-in described in the install guide+(`install-hooks --capture-assistant` on the client plus `capture_assistant` on+the server), where the excerpt is sanitized on both sides and capped. It is not+gated by this marker file — assistant text is not path-attributable, so a+`.ai-memory.toml` cannot narrow it. The metadata header is closed; the+PostToolUse response/error excerpt remains the existing bounded content capture.Capture exclusions are evaluated only where paths have a proven schema, so theydo not claim to filter those other bodies.diff --git a/hooks/claude-code/stop.sh b/hooks/claude-code/stop.shindex 57e3b5c2..3d86f4b4 100755--- a/hooks/claude-code/stop.sh+++ b/hooks/claude-code/stop.sh@@ -13,6 +13,17 @@ _lib_dir="$(dirname "$0")"SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"PAYLOAD=$(cat)+# Assistant/Stop capture (#196) is native-only: the script fallback cannot+# sanitize the assistant message, so if the raw payload still carries the field+# we drop the whole Stop rather than POST it verbatim. A literal substring check+# (POSIX `case`, no bash-isms per _lib.sh) — conservative on purpose: any Stop+# mentioning the key is dropped. Move to a native install to capture it safely.+case "$PAYLOAD" in+ *'"last_assistant_message"'*)+ printf '{}\n'+ exit 0+ ;;+esacCWD=$(ai_memory_extract_cwd "$PAYLOAD")QS=$(ai_memory_marker_qs "$CWD")diff --git a/hooks/lib/ai-memory-hook.ps1 b/hooks/lib/ai-memory-hook.ps1index 7b6f2bfb..0025bf21 100644--- a/hooks/lib/ai-memory-hook.ps1+++ b/hooks/lib/ai-memory-hook.ps1@@ -187,6 +187,13 @@ function Invoke-AiMemoryHook {$Server = if ($env:AI_MEMORY_HOOK_URL) { $env:AI_MEMORY_HOOK_URL } else { "http://127.0.0.1:49374" }$Payload = Read-AiMemoryStdin+ # Assistant/Stop capture (#196) is native-only. Scoped to claude-code + stop+ # so a PostToolUse whose tool output legitimately contains the literal string+ # is unaffected. If a Stop payload still carries the raw field, drop the whole+ # event rather than POST it verbatim (the script fallback cannot sanitize it).+ if ($Agent -eq "claude-code" -and $Event -eq "stop" -and $Payload -and $Payload.Contains('"last_assistant_message"')) {+ return+ }$Cwd = Resolve-AiMemoryCwd -Payload $Payload -Agent $Agent$QS = Get-AiMemoryMarkerQuery -Cwd $Cwdif ($env:AI_MEMORY_RUN_ID) {