Skip to content

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.md
index 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
### Fixed
diff --git a/README.md b/README.md
index 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.md
index 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 cannot
delete 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 local
actor hammering it with requests.
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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.rs
index 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 @@ where
return 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.rs
index 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.rs
index 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/sessio
config_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/sessio
config_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/sessio
let 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/sessio
let 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/sessio
config_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.rs
index 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.rs
index 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.rs
index 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.toml
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 JSON
modes; no XML, no Instructor wrapping. (agentmemory #492 / #539,
cognee #2840.)
diff --git a/docs/install.md b/docs/install.md
index 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 start
does a short bounded cleanup drain before fetching a handoff; cancellation-prone
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 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 at
body, and association is only by matching agent-provided call IDs. User-prompt stores its prompt
text, notification stores its message/text, and post-compaction stores its
summary; 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 they
do not claim to filter those other bodies.
diff --git a/hooks/claude-code/stop.sh b/hooks/claude-code/stop.sh
index 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
+ ;;
+esac
CWD=$(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.ps1
index 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 $Cwd
if ($env:AI_MEMORY_RUN_ID) {