Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(capture): apply ignore_paths to backfill and run-ledger transcript imports

AkitaOnRailsdc80653d32bc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc040f45..3191b00e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
path; upgrade the server before the clients, because an older server drops
those events. This applies to the native hook, the server, and the
generated TypeScript integrations. (GHSA-gcpc-88hm-3xqr)
+- Fixed `ai-memory backfill`, including the automatic first-boot import, and
+ the `ai-memory run` workstream ledger not applying `[capture] ignore_paths`
+ to the harness transcripts they import, so the arguments and output of a
+ tool call on an ignored file could be stored even though live hooks drop
+ them. Both now apply the same decision as the live hook to every imported
+ tool call and its result: an excluded call is not imported at all, one the
+ policy cannot prove safe keeps only its tool family, and prompts and
+ assistant messages are imported as before. Results recorded without an id
+ linking them to their call take the strictest decision of their turn.
+ (GHSA-gcpc-88hm-3xqr)
- Fixed a web page open in the operator's browser being able to act on an
unauthenticated server (the loopback default, no token), such as claiming a
project's pending handoff or starting admin jobs. With auth off, the machine
diff --git a/crates/ai-memory-cli/src/commands/backfill.rs b/crates/ai-memory-cli/src/commands/backfill.rs
index 4c2d8a22..5cbf5265 100644
--- a/crates/ai-memory-cli/src/commands/backfill.rs
+++ b/crates/ai-memory-cli/src/commands/backfill.rs
@@ -39,6 +39,7 @@ use anyhow::{Context, Result, bail};
use serde::{Deserialize, Serialize};
use ai_memory_core::{NewWorkstreamEvent, WorkstreamEventKind};
+use ai_memory_hooks::capture_policy::metadata_only_body;
use ai_memory_workstream::{
LaunchRoots, ManagedHarness, build_launch_plan_with_env, export_transcript,
list_native_sessions, wait_for_transcript_flush,
@@ -46,6 +47,7 @@ use ai_memory_workstream::{
use super::doctor::{SCANNED_HARNESSES, relocated_session_dir};
use super::run;
+use super::transcript_capture::{EventCapture, TranscriptCapture};
use crate::config::Config;
use crate::http_client::{ServerEndpoint, get_json, post_json};
@@ -236,6 +238,10 @@ pub async fn run(config: &Config, args: crate::cli::BackfillArgs) -> Result<()>
return finish(&args, &report);
}
+ // The checkout's `[capture] ignore_paths`, applied to every imported tool
+ // call as the live hook applies it.
+ let capture = TranscriptCapture::for_checkout(&cwd);
+
// Import each selected session, oldest-first so the imported history reads
// chronologically, until the total-events circuit breaker trips.
for session in selected.into_iter().rev() {
@@ -243,7 +249,11 @@ pub async fn run(config: &Config, args: crate::cli::BackfillArgs) -> Result<()>
report.skipped_for_cap += 1;
continue;
}
- match import_one(&endpoint, &workspace, &project, &home, &cwd, &session).await {
+ match import_one(
+ &endpoint, &workspace, &project, &home, &cwd, &capture, &session,
+ )
+ .await
+ {
Ok(events) => {
report.imported_sessions += 1;
report.imported_events += events;
@@ -449,13 +459,15 @@ struct HookBatchAck {
/// the original harness and its native session id. Returns the number of
/// content events (messages/tools) imported. The server sanitizes and bounds
/// every event, so retroactive text crosses the same trust boundary as live
-/// capture.
+/// capture, and `capture` drops or strips tool events the checkout's
+/// `[capture] ignore_paths` excludes before anything is posted.
async fn import_one(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
home: &Path,
cwd: &Path,
+ capture: &TranscriptCapture,
session: &SessionRef,
) -> Result<usize> {
let roots = LaunchRoots { home, cwd };
@@ -500,8 +512,14 @@ async fn import_one(
serde_json::json!({ "session_id": sid, "occurred_at": resolved.earliest }),
)?);
let mut content = 0usize;
- for (event, occurred_at) in transcript.events.iter().zip(&resolved.per_event) {
- if let Some(mapped) = map_event(sid, event, occurred_at.as_deref()) {
+ let captures = capture.decide(&transcript.events);
+ for ((event, occurred_at), capture) in transcript
+ .events
+ .iter()
+ .zip(&resolved.per_event)
+ .zip(&captures)
+ {
+ if let Some(mapped) = map_event(sid, event, occurred_at.as_deref(), capture) {
items.push(hook_item(
endpoint,
workspace,
@@ -620,15 +638,30 @@ struct MappedEvent {
/// `occurred_at` (RFC 3339), already resolved by the caller, rides in the hook
/// body so the imported observation is dated at the transcript's own event
/// time rather than at import time.
+///
+/// `capture` is the checkout's capture decision for this event: a dropped
+/// event maps to nothing, and a metadata-only one carries the hook's
+/// metadata-only body with its `_ai_memory_capture` protocol, which the server
+/// validates and rebuilds from its allowlist exactly as for a live hook. A kept
+/// event carries no protocol: its body is a normalized transcript record, not
+/// the native tool payload the server's re-inspection reads, so a claim would
+/// be judged against the wrong schema and stripped; the server never receives
+/// the ignore patterns, so the client's decision is the only one possible.
fn map_event(
session_id: &str,
event: &NewWorkstreamEvent,
occurred_at: Option<&str>,
+ capture: &EventCapture,
) -> Option<MappedEvent> {
let content = event.content.trim();
if content.is_empty() {
return None;
}
+ let decision = match capture {
+ EventCapture::Drop => return None,
+ EventCapture::MetadataOnly(decision) => Some(decision),
+ EventCapture::Keep => None,
+ };
let role = event.role.as_deref().unwrap_or("");
let ingest_key = format!("{session_id}:{}", event.event_id);
match event.kind {
@@ -651,16 +684,26 @@ fn map_event(
_ if role.is_empty() => "message".to_string(),
_ => format!("{role}-message"),
};
- Some(MappedEvent {
- event: format!("backfill.{source_event}"),
- source_event: Some(source_event),
- ingest_key,
- body: serde_json::json!({
+ let body = match decision {
+ Some(decision) => {
+ let mut body = metadata_only_body(Some(session_id), None, decision);
+ if let Some(object) = body.as_object_mut() {
+ object.insert("occurred_at".into(), occurred_at.into());
+ }
+ body
+ }
+ None => serde_json::json!({
"session_id": session_id,
"title": first_line(content),
"message": event.content,
"occurred_at": occurred_at,
}),
+ };
+ Some(MappedEvent {
+ event: format!("backfill.{source_event}"),
+ source_event: Some(source_event),
+ ingest_key,
+ body,
})
}
WorkstreamEventKind::Compaction
@@ -891,6 +934,7 @@ mod tests {
"sid",
&event(WorkstreamEventKind::Message, Some("user"), "do the thing"),
Some("2026-09-10T12:00:00Z"),
+ &EventCapture::Keep,
)
.expect("user message maps");
assert_eq!(m.event, "user-prompt");
@@ -916,6 +960,7 @@ mod tests {
"here is the plan\nline2",
),
None,
+ &EventCapture::Keep,
)
.expect("assistant maps");
assert_eq!(a.event, "backfill.assistant-message");
@@ -934,6 +979,7 @@ mod tests {
"sid",
&event(WorkstreamEventKind::ToolCall, None, "grep foo"),
None,
+ &EventCapture::Keep,
)
.expect("tool call maps");
assert_eq!(t.event, "backfill.tool_call");
@@ -1053,6 +1099,7 @@ mod tests {
"sid",
&event(WorkstreamEventKind::Message, Some("user"), " "),
None,
+ &EventCapture::Keep,
)
.is_none(),
"whitespace-only content is not an observation"
@@ -1063,7 +1110,13 @@ mod tests {
WorkstreamEventKind::Annotation,
] {
assert!(
- map_event("sid", &event(kind, None, "boundary"), None).is_none(),
+ map_event(
+ "sid",
+ &event(kind, None, "boundary"),
+ None,
+ &EventCapture::Keep
+ )
+ .is_none(),
"{kind:?} is not session content"
);
}
@@ -1119,6 +1172,142 @@ mod tests {
assert!(only.is_empty(), "no session matches the filter: {only:?}");
}
+ /// GHSA-gcpc-88hm-3xqr: a planted Claude transcript reads one file under
+ /// the checkout's `[capture] ignore_paths` and one outside it. The
+ /// excluded read's call and output never reach `/hook/batch`; the public
+ /// read's do. A malformed read is posted as the hook's metadata-only body.
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn backfill_never_posts_tool_content_the_capture_policy_excludes() {
+ use axum::{Router, routing::post};
+ use std::sync::{Arc, Mutex};
+
+ let posted = Arc::new(Mutex::new(Vec::<serde_json::Value>::new()));
+ let captured = posted.clone();
+ let app = Router::new().route(
+ "/hook/batch",
+ post(
+ move |axum::Json(items): axum::Json<Vec<serde_json::Value>>| {
+ let captured = captured.clone();
+ async move {
+ let accepted = items.len();
+ captured.lock().unwrap().extend(items);
+ axum::Json(serde_json::json!({ "accepted": accepted }))
+ }
+ },
+ ),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+ let home = tempfile::tempdir().unwrap();
+ let repo = tempfile::tempdir().unwrap();
+ std::fs::write(
+ repo.path().join(".ai-memory.toml"),
+ "[capture]\nignore_paths = [\"docs/adr/**\"]\n",
+ )
+ .unwrap();
+ let session_dir = home
+ .path()
+ .join(".claude")
+ .join("projects")
+ .join(repo.path().to_string_lossy().replace('/', "-"));
+ std::fs::create_dir_all(&session_dir).unwrap();
+ let sid = "11111111-2222-3333-4444-555555555555";
+ let cwd = repo.path().to_string_lossy();
+ let record = |uuid: &str, kind: &str, content: serde_json::Value| {
+ serde_json::json!({
+ "type": kind, "uuid": uuid, "sessionId": sid, "cwd": cwd,
+ "timestamp": "2026-09-01T10:00:00Z",
+ "message": {"role": kind, "content": content},
+ })
+ .to_string()
+ };
+ let read = |id: &str, input: serde_json::Value| serde_json::json!({"type": "tool_use", "id": id, "name": "Read", "input": input});
+ let output = |id: &str, text: &str| serde_json::json!({"type": "tool_result", "tool_use_id": id, "content": text});
+ let lines = [
+ record("u1", "user", serde_json::json!("read the adr and lib")),
+ record(
+ "a1",
+ "assistant",
+ serde_json::json!([
+ read(
+ "toolu_adr",
+ serde_json::json!({"file_path": repo.path().join("docs/adr/1.md")})
+ ),
+ read(
+ "toolu_pub",
+ serde_json::json!({"file_path": repo.path().join("src/lib.rs")})
+ ),
+ read(
+ "toolu_bad",
+ serde_json::json!({"file_path": 7, "note": "ARGSENTINEL"})
+ ),
+ ]),
+ ),
+ record(
+ "u2",
+ "user",
+ serde_json::json!([
+ output("toolu_adr", "ADRSENTINEL private decision"),
+ output("toolu_pub", "PUBLICCONTROL public code"),
+ output("toolu_bad", "BADSENTINEL unprovable output"),
+ ]),
+ ),
+ ];
+ std::fs::write(
+ session_dir.join(format!("{sid}.jsonl")),
+ lines.join("\n") + "\n",
+ )
+ .unwrap();
+
+ let endpoint = ServerEndpoint::for_hook_target(format!("http://{address}"), None);
+ let session = SessionRef {
+ harness: ManagedHarness::Claude,
+ native_session_id: sid.into(),
+ updated_at: SystemTime::now(),
+ };
+ let capture = TranscriptCapture::for_checkout(repo.path());
+ import_one(
+ &endpoint,
+ "ws",
+ "proj",
+ home.path(),
+ repo.path(),
+ &capture,
+ &session,
+ )
+ .await
+ .unwrap();
+ server.abort();
+
+ let posted = posted.lock().unwrap();
+ let text = serde_json::to_string(&*posted).unwrap();
+ for sentinel in ["ADRSENTINEL", "docs/adr", "ARGSENTINEL", "BADSENTINEL"] {
+ assert!(!text.contains(sentinel), "{sentinel} was posted: {text}");
+ }
+ assert!(text.contains("PUBLICCONTROL"), "public output: {text}");
+ assert!(text.contains("src/lib.rs"), "public call: {text}");
+ let stripped: Vec<_> = posted
+ .iter()
+ .filter(|item| item["body"].get("_ai_memory_capture").is_some())
+ .collect();
+ assert_eq!(
+ stripped.len(),
+ 2,
+ "the malformed call and its output: {text}"
+ );
+ for item in stripped {
+ assert_eq!(
+ item["body"]["_ai_memory_capture"]["disposition"],
+ "metadata-only"
+ );
+ assert_eq!(item["body"]["tool_family"], "file");
+ assert_eq!(item["body"]["tool_call_id"], "toolu_bad");
+ }
+ }
+
fn spawned_args(
server_url: Option<&str>,
server_profile: Option<&str>,
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 8247171c..020ad638 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -1266,7 +1266,7 @@ fn file_route_anchor(cwd: &Path) -> FileRouteAnchor {
/// source files while its `workdir` points elsewhere. Without a reroute the
/// event stays with the payload cwd, whose policy then drops it exactly as it
/// would have before any rerouting existed.
-fn tool_location_routing_cwd(
+pub(crate) fn tool_location_routing_cwd(
agent: AgentKind,
raw: &serde_json::Value,
payload_cwd: &str,
@@ -1389,7 +1389,7 @@ fn resolve_hook_route(
/// including for a candidate file that doesn't exist on disk (canonicalize
/// would `Err` on that and silently fall back to the raw, un-normalized
/// cwd).
-fn lexical_capture_cwd(cwd: &str) -> String {
+pub(crate) fn lexical_capture_cwd(cwd: &str) -> String {
crate::marker::absolute_normalized(Path::new(cwd))
.into_os_string()
.into_string()
diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rs
index f78711e6..88ed3f8d 100644
--- a/crates/ai-memory-cli/src/commands/mod.rs
+++ b/crates/ai-memory-cli/src/commands/mod.rs
@@ -99,6 +99,7 @@ pub mod server;
pub mod setup_agent;
pub mod show;
pub mod status;
+pub mod transcript_capture;
pub mod uninstall;
pub mod upgrade;
pub mod user;
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index be842930..12e8b5b2 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -33,6 +33,7 @@ use tokio::process::Command;
use tokio_util::sync::CancellationToken;
use crate::cli::{RunArgs, RunHarnessChoice};
+use crate::commands::transcript_capture::TranscriptCapture;
use crate::commands::{path_util, resolve_scope_noting_marker_project};
use crate::config::Config;
use crate::http_client::{
@@ -1250,6 +1251,7 @@ async fn run_once_with_wiring(
checkpoint,
Some(exit_code),
&privacy,
+ &TranscriptCapture::for_checkout(&repository.cwd),
)
.await
{
@@ -3337,6 +3339,10 @@ async fn export_after_flush(
}
}
+/// Upload the exported transcript as the run's ledger segments. `capture`
+/// applies the checkout's `[capture] ignore_paths` first, so an excluded tool
+/// call and its output never reach a segment; a result whose call was imported
+/// by an earlier run has no call here and is dropped under a policy.
async fn import_batches(
endpoint: &ServerEndpoint,
run_path: &str,
@@ -3344,6 +3350,7 @@ async fn import_batches(
checkpoint: ai_memory_core::WorkstreamCheckpoint,
exit_code: Option<i32>,
sanitizer: &Sanitizer,
+ capture: &TranscriptCapture,
) -> Result<usize> {
let native_identity = nonempty_session(&transcript.native_session_id)
.map(|id| NativeSessionIdentity::parse(&id, sanitizer))
@@ -3351,8 +3358,9 @@ async fn import_batches(
for event in &transcript.events {
NativeSessionIdentity::parse(&event.native_session_id, sanitizer)?;
}
+ let events = capture.filter_ledger_events(transcript.events);
let mut imported = 0;
- let mut batches = event_batches(transcript.events).into_iter().peekable();
+ let mut batches = event_batches(events).into_iter().peekable();
while let Some(batch) = batches.next() {
let complete = batches.peek().is_none();
let request = FinishManagedRunRequest {
@@ -8767,6 +8775,7 @@ mod tests {
Default::default(),
Some(0),
&sanitizer,
+ &TranscriptCapture::for_checkout(home.path()),
)
.await
.is_err(),
@@ -8793,6 +8802,7 @@ mod tests {
Default::default(),
Some(0),
&sanitizer,
+ &TranscriptCapture::for_checkout(home.path()),
)
.await
.is_err(),
@@ -8808,6 +8818,7 @@ mod tests {
Default::default(),
Some(0),
&sanitizer,
+ &TranscriptCapture::for_checkout(home.path()),
)
.await
.unwrap(),
@@ -8824,6 +8835,108 @@ mod tests {
server.abort();
}
+ /// GHSA-gcpc-88hm-3xqr: the ledger upload applies the checkout's
+ /// `[capture] ignore_paths`. An excluded read's call and output never reach
+ /// the finish request (and so never a raw segment); a public read in the
+ /// same transcript still does.
+ #[tokio::test]
+ async fn ledger_upload_drops_tool_content_the_capture_policy_excludes() {
+ let requests = Arc::new(std::sync::Mutex::new(Vec::<FinishManagedRunRequest>::new()));
+ let captured = requests.clone();
+ let app = Router::new().route(
+ "/workstream/runs/{id}/finish",
+ post(
+ move |axum::Json(request): axum::Json<FinishManagedRunRequest>| {
+ let captured = captured.clone();
+ async move {
+ let imported_events = request.events.len();
+ captured.lock().unwrap().push(request);
+ axum::Json(FinishManagedRunResponse {
+ imported_events,
+ latest_sequence: 1,
+ })
+ }
+ },
+ ),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+ let home = tempfile::tempdir().unwrap();
+ let config = launch_config(home.path(), home.path(), address);
+ let endpoint = ServerEndpoint::from_config_resolving_auth(&config).await;
+ let repo = tempfile::tempdir().unwrap();
+ std::fs::write(
+ repo.path().join(".ai-memory.toml"),
+ "[capture]\nignore_paths = [\"docs/adr/**\"]\n",
+ )
+ .unwrap();
+ let event = |kind, content: String, metadata: serde_json::Value| {
+ ai_memory_core::NewWorkstreamEvent {
+ event_id: format!("e-{}", content.len()),
+ agent: AgentKind::ClaudeCode,
+ native_session_id: "sid-1".into(),
+ source_record_id: None,
+ kind,
+ role: None,
+ content,
+ occurred_at: None,
+ metadata,
+ }
+ };
+ let read = |path: &str, id: &str| {
+ event(
+ ai_memory_core::WorkstreamEventKind::ToolCall,
+ format!(
+ "Read: {}",
+ serde_json::json!({"file_path": repo.path().join(path)})
+ ),
+ serde_json::json!({"tool": "Read", "tool_use_id": id}),
+ )
+ };
+ let output = |text: &str, id: &str| {
+ event(
+ ai_memory_core::WorkstreamEventKind::ToolResult,
+ text.into(),
+ serde_json::json!({"tool_use_id": id}),
+ )
+ };
+ let transcript = ExportedTranscript {
+ native_session_id: "sid-1".into(),
+ source_cursor: Some("cursor".into()),
+ events: vec![
+ read("docs/adr/1.md", "adr"),
+ read("src/lib.rs", "pub"),
+ output("ADRSENTINEL private decision", "adr"),
+ output("PUBLICCONTROL code", "pub"),
+ ],
+ losses: Vec::new(),
+ };
+ let imported = import_batches(
+ &endpoint,
+ "/workstream/runs/test",
+ transcript,
+ Default::default(),
+ Some(0),
+ &Sanitizer::builtin(),
+ &TranscriptCapture::for_checkout(repo.path()),
+ )
+ .await
+ .unwrap();
+ server.abort();
+ let posted = serde_json::to_string(&*requests.lock().unwrap()).unwrap();
+ assert!(!posted.contains("ADRSENTINEL"), "excluded output: {posted}");
+ assert!(!posted.contains("docs/adr"), "excluded call: {posted}");
+ assert!(posted.contains("PUBLICCONTROL"), "public control: {posted}");
+ assert!(posted.contains("src/lib.rs"), "public call: {posted}");
+ assert_eq!(imported, 2);
+ assert_eq!(
+ requests.lock().unwrap()[0].source_cursor.as_deref(),
+ Some("cursor"),
+ "the cursor still advances past the excluded events"
+ );
+ }
+
#[tokio::test]
async fn native_identity_run_status_and_expected_refuse_before_discovery() {
let home = tempfile::tempdir().unwrap();
diff --git a/crates/ai-memory-cli/src/commands/transcript_capture.rs b/crates/ai-memory-cli/src/commands/transcript_capture.rs
new file mode 100644
index 00000000..245539c2
--- /dev/null
+++ b/crates/ai-memory-cli/src/commands/transcript_capture.rs
@@ -0,0 +1,442 @@
+//! `[capture] ignore_paths` for imported native transcripts.
+//!
+//! `ai-memory backfill` and the `ai-memory run` ledger read a harness's own
+//! transcript instead of receiving hook events, so the live hook's capture
+//! policy never saw those tool calls. This applies the same decision table
+//! rather than a second matcher: each recorded tool call is rebuilt in its
+//! agent's hook shape (`tool_call_payload`) and inspected by the checkout's
+//! `CapturePolicy`; a call the live hook would reroute to another checkout
+//! also answers to that checkout's policy; and each tool result inherits the
+//! decision of the call it answers.
+
+use std::collections::HashMap;
+use std::path::Path;
+
+use ai_memory_core::{NewWorkstreamEvent, WorkstreamEventKind};
+use ai_memory_hooks::{
+ CaptureDecision, CaptureDisposition, CapturePolicy, PolicyState, ToolFamily, tool_call_payload,
+};
+use serde_json::Value;
+
+use super::hook::{lexical_capture_cwd, tool_location_routing_cwd};
+use super::hook_capture::capture_policy;
+
+/// What an import does with one transcript event.
+#[derive(Clone, Debug)]
+pub(crate) enum EventCapture {
+ /// Import the event as recorded.
+ Keep,
+ /// Import nothing for this event.
+ Drop,
+ /// Record that the tool ran, never its arguments or output.
+ MetadataOnly(CaptureDecision),
+}
+
+impl EventCapture {
+ const fn rank(&self) -> u8 {
+ match self {
+ Self::Keep => 0,
+ Self::MetadataOnly(_) => 1,
+ Self::Drop => 2,
+ }
+ }
+
+ fn stricter(self, other: Self) -> Self {
+ if other.rank() > self.rank() {
+ other
+ } else {
+ self
+ }
+ }
+
+ fn from_decision(decision: CaptureDecision) -> Self {
+ match decision.protocol().disposition() {
+ CaptureDisposition::Keep => Self::Keep,
+ CaptureDisposition::Drop => Self::Drop,
+ CaptureDisposition::MetadataOnly => Self::MetadataOnly(decision),
+ }
+ }
+}
+
+/// The capture policy of the checkout a transcript was recorded in.
+pub(crate) struct TranscriptCapture {
+ policy: CapturePolicy,
+ cwd: String,
+ inspection_cwd: String,
+}
+
+impl TranscriptCapture {
+ /// Resolve the nearest marker's policy for `cwd`, exactly as the live hook
+ /// does for an event reporting that cwd.
+ pub(crate) fn for_checkout(cwd: &Path) -> Self {
+ let cwd = cwd.to_string_lossy().into_owned();
+ Self {
+ policy: capture_policy(&cwd),
+ inspection_cwd: lexical_capture_cwd(&cwd),
+ cwd,
+ }
+ }
+
+ /// One decision per event, in transcript order. Messages are always kept,
+ /// as live prompt capture keeps them.
+ ///
+ /// A result answers the call with the same native id. Some adapters record
+ /// no id, so a result without a matching call takes the strictest decision
+ /// of every call since the last user message: parallel calls may answer
+ /// out of order, and a positional guess could hand an excluded read's
+ /// output the decision of a public one. A result with no call at all is
+ /// dropped under a policy, since nothing proves it missed every ignored
+ /// path.
+ pub(crate) fn decide(&self, events: &[NewWorkstreamEvent]) -> Vec<EventCapture> {
+ let mut by_id: HashMap<&str, EventCapture> = HashMap::new();
+ let mut turn: Vec<EventCapture> = Vec::new();
+ let mut out = Vec::with_capacity(events.len());
+ for event in events {
+ let capture = match event.kind {
+ WorkstreamEventKind::ToolCall => {
+ let capture = self.decide_call(event);
+ if let Some(id) = call_id(event) {
+ by_id.insert(id, capture.clone());
+ }
+ turn.push(capture.clone());
+ capture
+ }
+ WorkstreamEventKind::ToolResult => {
+ match call_id(event).and_then(|id| by_id.get(id)) {
+ Some(capture) => capture.clone(),
+ None => turn
+ .iter()
+ .cloned()
+ .reduce(EventCapture::stricter)
+ .unwrap_or_else(|| self.orphan_result()),
+ }
+ }
+ WorkstreamEventKind::Message => {
+ if matches!(event.role.as_deref(), Some("user" | "human")) {
+ turn.clear();
+ }
+ EventCapture::Keep
+ }
+ WorkstreamEventKind::Compaction
+ | WorkstreamEventKind::Checkpoint
+ | WorkstreamEventKind::Annotation => EventCapture::Keep,
+ };
+ out.push(capture);
+ }
+ out
+ }
+
+ /// Keep the import's events the policy keeps, and strip the ones it makes
+ /// metadata-only, so excluded tool content never enters the run ledger.
+ pub(crate) fn filter_ledger_events(
+ &self,
+ events: Vec<NewWorkstreamEvent>,
+ ) -> Vec<NewWorkstreamEvent> {
+ let decisions = self.decide(&events);
+ events
+ .into_iter()
+ .zip(decisions)
+ .filter_map(|(event, capture)| match capture {
+ EventCapture::Keep => Some(event),
+ EventCapture::Drop => None,
+ EventCapture::MetadataOnly(decision) => Some(withheld(event, &decision)),
+ })
+ .collect()
+ }
+
+ fn orphan_result(&self) -> EventCapture {
+ if self.policy.state() == PolicyState::Inactive {
+ EventCapture::Keep
+ } else {
+ EventCapture::Drop
+ }
+ }
+
+ fn decide_call(&self, event: &NewWorkstreamEvent) -> EventCapture {
+ let (name, args) = recorded_call(event);
+ let raw = tool_call_payload(event.agent, name, args.as_ref(), call_id(event));
+ let decision = self.policy.inspect(event.agent, &raw, &self.inspection_cwd);
+ // A shell command cut by the adapter's size cap, or recorded as
+ // unparseable text, cannot be matched, and its output may name any path.
+ if args.is_none()
+ && decision.protocol().tool_family() == ToolFamily::NonFile
+ && self.policy.state() != PolicyState::Inactive
+ {
+ return EventCapture::Drop;
+ }
+ let capture = EventCapture::from_decision(decision);
+ match tool_location_routing_cwd(event.agent, &raw, &self.cwd) {
+ // The live hook would deliver this call to that checkout under its
+ // policy. An import stays in this scope, so both policies apply.
+ Some(destination) => {
+ let destination_decision = capture_policy(&destination).inspect(
+ event.agent,
+ &raw,
+ &lexical_capture_cwd(&destination),
+ );
+ capture.stricter(EventCapture::from_decision(destination_decision))
+ }
+ None => capture,
+ }
+ }
+}
+
+/// The native id linking a tool call and its result, when the adapter kept one.
+fn call_id(event: &NewWorkstreamEvent) -> Option<&str> {
+ ["tool_use_id", "tool_call_id"]
+ .iter()
+ .find_map(|key| event.metadata.get(*key).and_then(Value::as_str))
+ .filter(|id| !id.is_empty())
+}
+
+/// The tool name and arguments of a recorded call. Adapters write a call as
+/// `{name}: {arguments}`, the arguments usually JSON. `None` means they could
+/// not be recovered: truncated, or recorded as plain text.
+fn recorded_call(event: &NewWorkstreamEvent) -> (&str, Option<Value>) {
+ let name = event
+ .metadata
+ .get("tool")
+ .and_then(Value::as_str)
+ .filter(|name| !name.is_empty())
+ .or_else(|| event.content.split_once(": ").map(|(name, _)| name))
+ .unwrap_or("");
+ let args = event
+ .content
+ .strip_prefix(name)
+ .and_then(|rest| rest.strip_prefix(':'))
+ .map(str::trim)
+ .and_then(|rest| {
+ if rest.is_empty() {
+ Some(Value::Null)
+ } else {
+ serde_json::from_str(rest).ok()
+ }
+ });
+ (name, args)
+}
+
+/// A ledger event with its content replaced by the tool family, keeping only
+/// the labels that pair it with the other half of the call.
+fn withheld(mut event: NewWorkstreamEvent, decision: &CaptureDecision) -> NewWorkstreamEvent {
+ let family = serde_json::to_value(decision.protocol().tool_family())
+ .ok()
+ .and_then(|value| value.as_str().map(str::to_owned))
+ .unwrap_or_else(|| "unknown".to_owned());
+ let half = if event.kind == WorkstreamEventKind::ToolCall {
+ "call"
+ } else {
+ "output"
+ };
+ event.content = format!("[{family} tool {half} withheld by the capture policy]");
+ let mut metadata = serde_json::Map::new();
+ for key in ["tool", "tool_use_id", "tool_call_id", "parent_id"] {
+ if let Some(value) = event.metadata.get(key).filter(|value| value.is_string()) {
+ metadata.insert(key.into(), value.clone());
+ }
+ }
+ event.metadata = Value::Object(metadata);
+ event
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use ai_memory_core::AgentKind;
+ use serde_json::json;
+
+ fn event(
+ kind: WorkstreamEventKind,
+ role: &str,
+ content: &str,
+ metadata: Value,
+ ) -> NewWorkstreamEvent {
+ NewWorkstreamEvent {
+ event_id: "evt".into(),
+ agent: AgentKind::ClaudeCode,
+ native_session_id: "sid".into(),
+ source_record_id: None,
+ kind,
+ role: Some(role.into()),
+ content: content.into(),
+ occurred_at: None,
+ metadata,
+ }
+ }
+
+ fn checkout(ignore: Option<&str>) -> tempfile::TempDir {
+ let dir = tempfile::tempdir().unwrap();
+ if let Some(pattern) = ignore {
+ std::fs::write(
+ dir.path().join(".ai-memory.toml"),
+ format!("[capture]\nignore_paths = [\"{pattern}\"]\n"),
+ )
+ .unwrap();
+ }
+ dir
+ }
+
+ fn read_call(path: &Path, id: Option<&str>) -> NewWorkstreamEvent {
+ let mut metadata = json!({"tool": "Read"});
+ if let Some(id) = id {
+ metadata["tool_use_id"] = id.into();
+ }
+ event(
+ WorkstreamEventKind::ToolCall,
+ "assistant",
+ &format!("Read: {}", json!({"file_path": path})),
+ metadata,
+ )
+ }
+
+ fn result(content: &str, id: Option<&str>) -> NewWorkstreamEvent {
+ let metadata = id.map_or_else(|| json!({}), |id| json!({"tool_use_id": id}));
+ event(WorkstreamEventKind::ToolResult, "tool", content, metadata)
+ }
+
+ fn kinds(captures: &[EventCapture]) -> Vec<&'static str> {
+ captures
+ .iter()
+ .map(|capture| match capture {
+ EventCapture::Keep => "keep",
+ EventCapture::Drop => "drop",
+ EventCapture::MetadataOnly(_) => "metadata",
+ })
+ .collect()
+ }
+
+ /// Paired by id, an excluded read drops both halves while a public read in
+ /// the same turn is kept — even when the results answer out of order.
+ #[test]
+ fn an_excluded_read_drops_its_call_and_result_by_id() {
+ let repo = checkout(Some("docs/adr/**"));
+ let capture = TranscriptCapture::for_checkout(repo.path());
+ let events = [
+ event(WorkstreamEventKind::Message, "user", "read both", json!({})),
+ read_call(&repo.path().join("docs/adr/1.md"), Some("adr")),
+ read_call(&repo.path().join("src/lib.rs"), Some("pub")),
+ result("public code", Some("pub")),
+ result("ADR secret", Some("adr")),
+ event(WorkstreamEventKind::Message, "assistant", "done", json!({})),
+ ];
+ assert_eq!(
+ kinds(&capture.decide(&events)),
+ ["keep", "drop", "keep", "keep", "drop", "keep"]
+ );
+ }
+
+ /// Without ids, a result takes the strictest decision of its turn, so a
+ /// reordered pair cannot leak; the next user turn starts clean.
+ #[test]
+ fn id_less_results_take_the_strictest_call_of_their_turn() {
+ let repo = checkout(Some("docs/adr/**"));
+ let capture = TranscriptCapture::for_checkout(repo.path());
+ let events = [
+ event(WorkstreamEventKind::Message, "user", "turn one", json!({})),
+ read_call(&repo.path().join("docs/adr/1.md"), None),
+ read_call(&repo.path().join("src/lib.rs"), None),
+ result("public code", None),
+ result("ADR secret", None),
+ event(WorkstreamEventKind::Message, "user", "turn two", json!({})),
+ read_call(&repo.path().join("src/lib.rs"), None),
+ result("public code again", None),
+ ];
+ assert_eq!(
+ kinds(&capture.decide(&events)),
+ [
+ "keep", "drop", "keep", "drop", "drop", "keep", "keep", "keep"
+ ]
+ );
+ }
+
+ #[test]
+ fn unrecoverable_arguments_and_orphan_results_fail_closed_under_a_policy() {
+ let repo = checkout(Some("docs/adr/**"));
+ let capture = TranscriptCapture::for_checkout(repo.path());
+ let truncated_shell = event(
+ WorkstreamEventKind::ToolCall,
+ "assistant",
+ "Bash: {\"command\":\"cat docs/adr/1.md && echo",
+ json!({"tool": "Bash"}),
+ );
+ let truncated_read = event(
+ WorkstreamEventKind::ToolCall,
+ "assistant",
+ "Read: {\"file_path\":\"docs/ad",
+ json!({"tool": "Read"}),
+ );
+ assert_eq!(
+ kinds(&capture.decide(&[
+ truncated_shell,
+ truncated_read,
+ event(WorkstreamEventKind::Message, "user", "next", json!({})),
+ result("orphan output", None),
+ ])),
+ ["drop", "metadata", "keep", "drop"]
+ );
+ }
+
+ /// No marker: nothing changes, including id-less and orphan results.
+ #[test]
+ fn without_a_policy_every_event_is_kept() {
+ let repo = checkout(None);
+ let capture = TranscriptCapture::for_checkout(repo.path());
+ let events = [
+ read_call(&repo.path().join("docs/adr/1.md"), None),
+ result("ADR text", None),
+ result("orphan", Some("missing")),
+ ];
+ assert_eq!(kinds(&capture.decide(&events)), ["keep", "keep", "keep"]);
+ }
+
+ /// A read whose absolute target is another marked checkout answers to that
+ /// checkout's `ignore_paths` too, as the live hook's reroute would.
+ #[test]
+ fn a_call_into_another_checkout_honors_its_policy() {
+ let source = checkout(None);
+ let other = checkout(Some("private/**"));
+ let capture = TranscriptCapture::for_checkout(source.path());
+ let events = [
+ read_call(&other.path().join("private/key.txt"), Some("a")),
+ result("private", Some("a")),
+ read_call(&other.path().join("open.txt"), Some("b")),
+ result("open", Some("b")),
+ ];
+ assert_eq!(
+ kinds(&capture.decide(&events)),
+ ["drop", "drop", "keep", "keep"]
+ );
+ }
+
+ #[test]
+ fn ledger_events_are_dropped_or_stripped_before_upload() {
+ let repo = checkout(Some("docs/adr/**"));
+ let capture = TranscriptCapture::for_checkout(repo.path());
+ let malformed = event(
+ WorkstreamEventKind::ToolCall,
+ "assistant",
+ "Read: {\"path\": 7, \"secret\": \"SENTINEL-ARG\"}",
+ json!({"tool": "Read", "tool_use_id": "m", "parent_id": "p"}),
+ );
+ let kept = capture.filter_ledger_events(vec![
+ read_call(&repo.path().join("docs/adr/1.md"), Some("adr")),
+ result("SENTINEL-ADR", Some("adr")),
+ malformed,
+ result("SENTINEL-OUT", Some("m")),
+ read_call(&repo.path().join("src/lib.rs"), Some("pub")),
+ result("public code", Some("pub")),
+ ]);
+ let text = serde_json::to_string(&kept).unwrap();
+ assert!(!text.contains("SENTINEL"), "{text}");
+ assert!(text.contains("public code"), "control kept: {text}");
+ assert_eq!(kept.len(), 4);
+ assert_eq!(
+ kept[0].content,
+ "[file tool call withheld by the capture policy]"
+ );
+ assert_eq!(
+ kept[1].content,
+ "[file tool output withheld by the capture policy]"
+ );
+ assert_eq!(kept[1].metadata, json!({"tool_use_id": "m"}));
+ }
+}
diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rs
index 4410f849..7531bd0f 100644
--- a/crates/ai-memory-hooks/src/capture_policy.rs
+++ b/crates/ai-memory-hooks/src/capture_policy.rs
@@ -792,6 +792,34 @@ pub fn metadata_only_body(
Value::Object(body)
}
+/// Rebuilds the payload shape [`CapturePolicy::inspect`] and
+/// [`absolute_tool_location_paths`] read for `agent` from a tool call recorded
+/// outside a hook — a native transcript event replayed by `backfill` or the
+/// `ai-memory run` ledger — so the import applies the live decision table
+/// rather than a second matcher. `args: None` means the arguments could not be
+/// recovered, which a file tool treats as malformed.
+#[must_use]
+pub fn tool_call_payload(
+ agent: AgentKind,
+ name: &str,
+ args: Option<&Value>,
+ call_id: Option<&str>,
+) -> Value {
+ let args = args.cloned().unwrap_or(Value::Null);
+ let mut payload = match agent {
+ AgentKind::AntigravityCli => json!({"toolCall": {"name": name, "args": args}}),
+ AgentKind::Zero => json!({"toolName": name, "input": args}),
+ AgentKind::OpenCode | AgentKind::Omp | AgentKind::Pi | AgentKind::OpenClaw => {
+ json!({"tool": name, "args": args})
+ }
+ _ => json!({"tool_name": name, "tool_input": args}),
+ };
+ if let (Some(id), Some(object)) = (call_id, payload.as_object_mut()) {
+ object.insert("tool_use_id".into(), Value::String(id.into()));
+ }
+ payload
+}
+
#[derive(Default)]
struct Extracted<'a> {
family: ToolFamily,
@@ -2108,6 +2136,72 @@ mod tests {
assert_eq!(unknown.protocol().tool_family(), ToolFamily::Unknown);
}
+ /// A transcript import rebuilds each recorded tool call with
+ /// `tool_call_payload`; for every agent whose hook schema `extract`
+ /// supports, that rebuilt call must reach the same decision a live hook
+ /// gets, or `backfill` and the run ledger would store excluded content.
+ #[test]
+ fn tool_call_payload_reaches_the_live_decision_for_every_supported_agent() {
+ let policy = CapturePolicy::resolve(
+ CaptureSource::Parsed(&CaptureConfig {
+ ignore_paths: vec!["docs/adr/**".into()],
+ }),
+ "/repo",
+ None,
+ );
+ for agent in [
+ AgentKind::AntigravityCli,
+ AgentKind::Grok,
+ AgentKind::Zero,
+ AgentKind::ClaudeCode,
+ AgentKind::CommandCode,
+ AgentKind::Codex,
+ AgentKind::Cursor,
+ AgentKind::GeminiCli,
+ AgentKind::Devin,
+ AgentKind::Hermes,
+ AgentKind::KiroCli,
+ AgentKind::Pool,
+ AgentKind::Grizzybot,
+ AgentKind::Zcode,
+ AgentKind::CopilotCli,
+ AgentKind::OpenCode,
+ AgentKind::Omp,
+ AgentKind::Pi,
+ AgentKind::OpenClaw,
+ ] {
+ let decide = |name: &str, args: Option<&Value>| {
+ let raw = tool_call_payload(agent, name, args, Some("call-1"));
+ policy.inspect(agent, &raw, "/repo")
+ };
+ let excluded = decide("read", Some(&json!({"file_path": "docs/adr/1.md"})));
+ assert_eq!(
+ excluded.protocol().disposition(),
+ CaptureDisposition::Drop,
+ "{agent:?}: excluded read"
+ );
+ assert_eq!(excluded.call_id.as_deref(), Some("call-1"), "{agent:?}");
+ let public = decide("read", Some(&json!({"file_path": "src/lib.rs"})));
+ assert_eq!(
+ public.protocol().disposition(),
+ CaptureDisposition::Keep,
+ "{agent:?}: public read"
+ );
+ assert_eq!(public.protocol().tool_family(), ToolFamily::File);
+ let shell = decide("bash", Some(&json!({"command": "cat docs/adr/1.md"})));
+ assert_eq!(
+ shell.protocol().disposition(),
+ CaptureDisposition::Drop,
+ "{agent:?}: shell naming an excluded path"
+ );
+ assert_eq!(
+ decide("read", None).protocol().disposition(),
+ CaptureDisposition::MetadataOnly,
+ "{agent:?}: unrecoverable file arguments fail closed"
+ );
+ }
+ }
+
#[test]
fn hermes_documented_tool_names_map_to_canonical_families() {
for (tool, expected) in [
diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rs
index aa0629a8..71191dce 100644
--- a/crates/ai-memory-hooks/src/lib.rs
+++ b/crates/ai-memory-hooks/src/lib.rs
@@ -48,6 +48,7 @@ pub use capture_policy::{
CaptureConfig, CaptureDecision, CaptureDisposition, CaptureMode, CapturePolicy,
CaptureProtocol, CaptureSource, ExtractionState, PolicyState, ToolFamily,
absolute_tool_location_paths, describe_invalid_capture_config, repository_admits_capture,
+ tool_call_payload,
};
pub use payload::{
HookEnvelope, HookEvent, NOTIFICATION_EXCERPT_MAX_BYTES, POST_COMPACTION_EXCERPT_MAX_BYTES,
diff --git a/crates/ai-memory-workstream/src/transcript.rs b/crates/ai-memory-workstream/src/transcript.rs
index 6301ad26..db1bf8d8 100644
--- a/crates/ai-memory-workstream/src/transcript.rs
+++ b/crates/ai-memory-workstream/src/transcript.rs
@@ -933,7 +933,7 @@ fn parse_codex(
Some("assistant"),
&format!("{name}: {body}"),
timestamp(value),
- json!({"tool": name}),
+ with_tool_use_id(json!({"tool": name}), first_string(payload, &["call_id"])),
);
}
"function_call_output" | "custom_tool_call_output" | "tool_result" => {
@@ -948,7 +948,7 @@ fn parse_codex(
Some("tool"),
body,
timestamp(value),
- json!({}),
+ with_tool_use_id(json!({}), first_string(payload, &["call_id"])),
);
}
"web_search_call" => {
@@ -1029,10 +1029,13 @@ fn parse_pi_family(
Some("tool"),
&body,
timestamp(value),
- json!({
- "tool": tool,
- "is_error": message.get("isError").or_else(|| message.get("is_error")).and_then(Value::as_bool).unwrap_or(false)
- }),
+ with_tool_use_id(
+ json!({
+ "tool": tool,
+ "is_error": message.get("isError").or_else(|| message.get("is_error")).and_then(Value::as_bool).unwrap_or(false)
+ }),
+ first_string(message, &["toolCallId", "tool_call_id"]),
+ ),
);
}
_ => losses.push(format!(
@@ -2100,7 +2103,10 @@ fn parse_content_blocks(
Some("assistant"),
&format!("{name}: {input}"),
occurred_at.clone(),
- json!({"tool": name}),
+ with_tool_use_id(
+ json!({"tool": name}),
+ first_string(block, &["id", "toolCallId", "tool_call_id", "call_id"]),
+ ),
);
}
"tool_result" | "toolResult" => {
@@ -2122,7 +2128,13 @@ fn parse_content_blocks(
Some("tool"),
&body,
occurred_at.clone(),
- json!({"is_error": block.get("is_error").and_then(Value::as_bool).unwrap_or(false)}),
+ with_tool_use_id(
+ json!({"is_error": block.get("is_error").and_then(Value::as_bool).unwrap_or(false)}),
+ first_string(
+ block,
+ &["tool_use_id", "toolCallId", "tool_call_id", "call_id"],
+ ),
+ ),
);
}
"thinking" | "reasoning" | "redacted_thinking" => {
@@ -4243,6 +4255,16 @@ fn value_text(value: &Value) -> String {
}
}
+/// Record the native id pairing a tool call with its result, so a transcript
+/// import can apply one capture decision to both halves (`backfill`, the
+/// `ai-memory run` ledger).
+fn with_tool_use_id(mut metadata: Value, id: Option<&str>) -> Value {
+ if let (Some(id), Some(object)) = (id, metadata.as_object_mut()) {
+ object.insert("tool_use_id".into(), Value::String(id.to_owned()));
+ }
+ metadata
+}
+
fn compact_json(value: &Value) -> String {
serde_json::to_string(value).unwrap_or_default()
}
diff --git a/docs/design-boot-backfill.md b/docs/design-boot-backfill.md
index c6e2bbd1..e1ea8cfa 100644
--- a/docs/design-boot-backfill.md
+++ b/docs/design-boot-backfill.md
@@ -181,8 +181,20 @@ Retroactive text is exactly as untrusted as live hook text, since it is old mode
`Sanitized<NewObservation>` / workstream sanitize boundary and the same caps. The e2e
canary secret must be scrubbed from a backfilled body just as from a live one.
- **Capture exclusions honored.** `[capture] ignore_paths` from the nearest
- `.ai-memory.toml` must drop matching file-tool events in the backfill path too, not just
- live hooks.
+ `.ai-memory.toml` applies to the backfill path too, not just live hooks.
+ As built (`commands/transcript_capture.rs`), each imported tool call is rebuilt in
+ its agent's hook shape (`ai_memory_hooks::tool_call_payload`) and inspected by the
+ checkout's `CapturePolicy`, the same decision table the live hook uses; a call the
+ live hook would reroute to another marked checkout also answers to that checkout's
+ policy. A Drop removes both the call and its result before anything is posted; a
+ metadata-only decision posts the hook's metadata-only body with its
+ `_ai_memory_capture` protocol, which the server validates and rebuilds from its
+ allowlist. A result is paired with its call by native id; without one it takes the
+ strictest decision of every call since the last user message, and a result with no
+ call is dropped under a policy. Kept events carry no protocol: their body is a
+ normalized transcript record, not the native payload the server's re-inspection
+ reads, and the server never receives the ignore patterns. The `ai-memory run` ledger
+ applies the same decisions before its segments are uploaded.
- **Emptiness + lease** prevent a backfill from overwriting or racing an established
project's real history.
- **Multi-user posture.** On a shared server, default-on retro-import of a long local
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 7ec4620c..81f6a814 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -440,7 +440,12 @@ resume, continue, session, or fork selector.
there could own. Visible user/assistant messages, completed tool calls/results,
compaction summaries, and a non-mutating Git checkpoint enter an append-only
workstream ledger. Hidden reasoning and unsupported/private records are
- excluded and recorded as extraction-loss annotations. Each delivered
+ excluded and recorded as extraction-loss annotations. The checkout's
+ `[capture] ignore_paths` applies before upload, with the live hook's
+ decision table: an excluded tool call and its result never enter the
+ ledger, one the policy cannot prove safe keeps only its tool family, and a
+ result whose call was imported by an earlier run is dropped under a
+ policy. Messages are unaffected. Each delivered
workstream packet begins with a versioned origin marker. If Claude Code
persists that packet and its `Read` tool returns it, the Claude transcript
normalizer excludes the marked result instead of feeding delivered history
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 44012b0a..82037fc9 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -66,7 +66,7 @@ means the boundary is not built yet.
| 10e | Reconcile-tombstone of a disk-deleted page is opt-in, soft, scope-bound, and false-positive-guarded (invariant #16, #929 delete-half) | `ai-memory-wiki/src/watcher.rs` — off by default (`[maintenance] reconcile_tombstones_deleted_pages`); a page is tombstoned only after its file is observed missing on two consecutive passes (streak resets if the path's `PageId` changed), re-verified against the live filesystem immediately before acting, with reserved/indexed-but-unwalked paths (`bootstrap.md`, `_meta.md`, `_pending/`, `sessions/*.md`) excluded and a circuit breaker that skips a whole scope when `> max(3, 50%)` of its pages look missing or a non-partial walk finds nothing; `ai-memory-store/src/ops.rs` `soft_delete_for_reconcile_if_latest` is a soft tombstone (`is_latest=0` + `superseded_at`, decay's shape) through the single writer actor in one transaction — never a filesystem write — scoped to the page's own `(workspace_id, project_id)` | `watcher.rs` `reconcile_delete_disabled_by_default_never_tombstones_a_missing_page`, `reconcile_delete_cross_project_isolation` (project A's deletion never tombstones project B's same-path page), `reconcile_tombstone_refuses_a_stale_latest_id`, `reconcile_tombstone_refuses_when_the_file_still_exists`, `reconcile_tombstone_never_touches_the_filesystem`; `ops.rs` `reconcile_tombstone_resurrects_instead_of_orphaning_on_recreate` | STRONG |
| 10f | Session-time repair is scope-bound (no cross-project timestamp rewrite) | `ai-memory-store/src/ops.rs` `repair_session_times` — every candidate is read back and updated with `WHERE id=? AND workspace_id=? AND project_id=?`; a row outside that 3-tuple is reported `NotFound` and untouched, same code path as an id that does not exist at all; `ai-memory-mcp/src/admin.rs` `handle_repair_session_times` passes the caller's `(workspace, project)` straight through, never the candidate's own | `ops.rs` `repair_session_times_does_not_touch_a_session_of_another_project` (control: sibling session in-scope repaired in the same batch); `admin_repair_session_times.rs` `cross_project_session_is_not_found_and_untouched`; both bite-checked by dropping the `project_id` filter | STRONG |
| 11a | Hook backpressure (202/429) + bounded fan-out (invariant #5) | `ai-memory-hooks/src/router.rs` semaphore→429, 202 immediately, `MAX_HOOK_BATCH_ITEMS`, bounded LRU limiter; batch acknowledgements retain only processed indices and classify terminal drops without consuming capacity | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded`; `router.rs` `handle_hook_batch_skips_rate_limited_first_item_and_accepts_later_source`, `handle_hook_batch_reports_failed_index_after_rate_limited_skip`, `handle_hook_batch_drops_subagent_events_before_capacity_check` (each asserts result indices and includes an accepted control) | STRONG |
-| 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized); an invalid marker makes file and shell calls metadata-only; an active one makes a shell call metadata-only when a word uses unquoted brace expansion or a bracket class (`has_unevaluated_expansion`), and either makes tools that read back an earlier command's output metadata-only (`reads_earlier_output`: `BashOutput`, `TaskOutput`, `write_stdin`, `process`, `read_bash`/`write_bash` and PowerShell twins); the server admits a metadata-only shell or unknown-family body only under an active or invalid marker, with no paths and an `extracted` state (`router.rs` `metadata_protocol_is_legal`), and its own re-inspection strips an older client's keep for either; a Gemini `read_many_files` literal entry is also read as `entry/**` (`glob_matches_below`), and Copilot CLI's runtime `view`/`create`/`str_replace_editor` are file tools for that agent only (`agent_family`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`, `captureUnevaluatedExpansion`, `captureGlobBelow`, the `reader` flag). Candidate/argument flavor (`Flavor::Posix` vs `Flavor::Windows`, used to pick which `ignore_paths` patterns even apply) is derived from the **host** (the cwd), never from the candidate string alone — a POSIX-host candidate spelled with a leading `//` is collapsed to a single `/` before flavor detection (`normalize_candidate`; TS `captureNormalize`'s `windowsHost` parameter, sourced from `captureHostWindows(cwd)`), fixing GHSA-vh98 (a `//`-prefixed candidate used to self-classify as `Flavor::Windows` regardless of host, matching zero POSIX patterns and being captured instead of dropped); a genuine Windows/UNC host (cwd itself windows-flavored) is unaffected; `hook.rs` `--check-capture` preflight uses the same capture policy before any spool or spawn | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec` and `PowerShell`, `workdir`, glob directories, Windows paths, and a POSIX-host leading-`//` command via `/{root}/docs/adr/x.md`), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `claude_code_powershell_honors_ignored_paths_on_a_windows_host` (#1186: Windows-spelled and `-Param:value` paths drop, public-path and `git status` controls kept, invalid marker metadata-only), `gemini_cli_shell_and_read_many_files_honor_ignored_paths` (Gemini `run_shell_command` incl. `dir_path`/`directory`, and `read_many_files` globs via `match_globs`: excluded literal, mixed public+excluded, `docs/*`, recursive `**` and case-variant entries drop, an `exclude` list cannot rescue them, unsupported glob syntax and malformed lists are metadata-only, public entries kept, POSIX and Windows hosts) and `globstar_reaches_lets_double_star_span_any_depth`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors, and `normalization`'s leading-`//` POSIX vectors alongside the kept Windows-cwd UNC vectors as the no-regression control); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell admitted for an unevaluated expansion, inactive refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`, **`a_leading_double_slash_candidate_does_not_escape_posix_ignore_paths_via_flavor_mismatch`** (GHSA-vh98 adversarial: attempts the `//repo/secret/...` violation on a POSIX host, proves it now drops, with a plain-single-slash control and a Windows-hosted genuine-UNC control both still correct — fails on the pre-fix code); `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`, `gemini_cli_shell_and_read_many_files_exclusions_drop_before_spool` (pre- and post-tool events with an excluded path are never spooled; public controls spool with their family); `capture_policy.rs` `read_many_files_directory_entries_cannot_reach_ignored_paths` (shared `read_many_files_directories` vectors: `docs`, `.`, `./`, `docs/`, case and `..` variants drop; `src`, `README.md`, `docs/adrx` kept), `output_reader_tools_are_metadata_only_only_under_a_policy` (active and invalid strip, inactive and an unrelated unknown tool keep), `copilot_cli_runtime_file_tools_are_scoped_to_copilot`, `unevaluated_shell_expansions_respect_quoting`, the shell fixture's brace/class vectors (quoted, escaped, `${…}`, `{}`, `[ … ]`, `HEAD@{1}` controls kept); `router.rs` `capture_protocol_active_keep_of_unprovable_output_is_stripped`; `hook.rs` `excluded_content_cannot_reach_the_spool_through_unevaluated_tool_shapes` (directory entries and Copilot `view`/`create` never spool, readers and brace shells spool without content, public controls spool with it); `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections, including the GHSA-vh98 and Gemini `read_many_files`/`run_shell_command` vectors, plus unsupported-glob, empty-list and recursive-`**` checks, against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job); `hook.rs` `check_capture_refuses_partial_scope_and_excluded_content` (ignored-path and partial-scope violations refused, complete public-path control passes), `check_capture_bounds_marker_hints_and_refuses_oversized_scope` (513-byte hints refused, 512-byte control passes; native routing preserved) | STRONG with listed residuals. Matching is lexical by design, so these stay open: shell variables (`$VAR`, `FILE=… sh -c 'cat $FILE'`) and command substitution, a `cd` inside the command, symlinks (paths are never resolved on disk), a recursive search of a parent directory (`grep -r x docs`, `rg x`) through a shell, and tools the matcher does not list, which keep their current unknown-tool behavior. Mitigation: allowlist capture mode (`install-hooks --capture-mode allowlist`) for sensitive projects |
+| 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized); an invalid marker makes file and shell calls metadata-only; an active one makes a shell call metadata-only when a word uses unquoted brace expansion or a bracket class (`has_unevaluated_expansion`), and either makes tools that read back an earlier command's output metadata-only (`reads_earlier_output`: `BashOutput`, `TaskOutput`, `write_stdin`, `process`, `read_bash`/`write_bash` and PowerShell twins); the server admits a metadata-only shell or unknown-family body only under an active or invalid marker, with no paths and an `extracted` state (`router.rs` `metadata_protocol_is_legal`), and its own re-inspection strips an older client's keep for either; a Gemini `read_many_files` literal entry is also read as `entry/**` (`glob_matches_below`), and Copilot CLI's runtime `view`/`create`/`str_replace_editor` are file tools for that agent only (`agent_family`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`, `captureUnevaluatedExpansion`, `captureGlobBelow`, the `reader` flag). Candidate/argument flavor (`Flavor::Posix` vs `Flavor::Windows`, used to pick which `ignore_paths` patterns even apply) is derived from the **host** (the cwd), never from the candidate string alone — a POSIX-host candidate spelled with a leading `//` is collapsed to a single `/` before flavor detection (`normalize_candidate`; TS `captureNormalize`'s `windowsHost` parameter, sourced from `captureHostWindows(cwd)`), fixing GHSA-vh98 (a `//`-prefixed candidate used to self-classify as `Flavor::Windows` regardless of host, matching zero POSIX patterns and being captured instead of dropped); a genuine Windows/UNC host (cwd itself windows-flavored) is unaffected; `hook.rs` `--check-capture` preflight uses the same capture policy before any spool or spawn; transcript imports (`ai-memory backfill`, including the automatic first-boot run, and the `ai-memory run` ledger upload) apply the same decision table through `commands/transcript_capture.rs`: each recorded tool call is rebuilt in its agent's hook shape (`capture_policy.rs` `tool_call_payload`) and inspected by the checkout's policy, and by a reroute destination's policy too; a Drop removes the call and its result (paired by native id, else the strictest call of the turn; a call-less result drops under a policy), metadata-only posts the hook's metadata-only body with its protocol (backfill) or a withheld placeholder (ledger), and a shell call whose recorded arguments cannot be parsed drops (GHSA-gcpc-88hm-3xqr) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec` and `PowerShell`, `workdir`, glob directories, Windows paths, and a POSIX-host leading-`//` command via `/{root}/docs/adr/x.md`), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `claude_code_powershell_honors_ignored_paths_on_a_windows_host` (#1186: Windows-spelled and `-Param:value` paths drop, public-path and `git status` controls kept, invalid marker metadata-only), `gemini_cli_shell_and_read_many_files_honor_ignored_paths` (Gemini `run_shell_command` incl. `dir_path`/`directory`, and `read_many_files` globs via `match_globs`: excluded literal, mixed public+excluded, `docs/*`, recursive `**` and case-variant entries drop, an `exclude` list cannot rescue them, unsupported glob syntax and malformed lists are metadata-only, public entries kept, POSIX and Windows hosts) and `globstar_reaches_lets_double_star_span_any_depth`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors, and `normalization`'s leading-`//` POSIX vectors alongside the kept Windows-cwd UNC vectors as the no-regression control); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell admitted for an unevaluated expansion, inactive refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`, **`a_leading_double_slash_candidate_does_not_escape_posix_ignore_paths_via_flavor_mismatch`** (GHSA-vh98 adversarial: attempts the `//repo/secret/...` violation on a POSIX host, proves it now drops, with a plain-single-slash control and a Windows-hosted genuine-UNC control both still correct — fails on the pre-fix code); `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`, `gemini_cli_shell_and_read_many_files_exclusions_drop_before_spool` (pre- and post-tool events with an excluded path are never spooled; public controls spool with their family); `capture_policy.rs` `read_many_files_directory_entries_cannot_reach_ignored_paths` (shared `read_many_files_directories` vectors: `docs`, `.`, `./`, `docs/`, case and `..` variants drop; `src`, `README.md`, `docs/adrx` kept), `output_reader_tools_are_metadata_only_only_under_a_policy` (active and invalid strip, inactive and an unrelated unknown tool keep), `copilot_cli_runtime_file_tools_are_scoped_to_copilot`, `unevaluated_shell_expansions_respect_quoting`, the shell fixture's brace/class vectors (quoted, escaped, `${…}`, `{}`, `[ … ]`, `HEAD@{1}` controls kept); `router.rs` `capture_protocol_active_keep_of_unprovable_output_is_stripped`; `hook.rs` `excluded_content_cannot_reach_the_spool_through_unevaluated_tool_shapes` (directory entries and Copilot `view`/`create` never spool, readers and brace shells spool without content, public controls spool with it); `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections, including the GHSA-vh98 and Gemini `read_many_files`/`run_shell_command` vectors, plus unsupported-glob, empty-list and recursive-`**` checks, against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job); `hook.rs` `check_capture_refuses_partial_scope_and_excluded_content` (ignored-path and partial-scope violations refused, complete public-path control passes), `check_capture_bounds_marker_hints_and_refuses_oversized_scope` (513-byte hints refused, 512-byte control passes; native routing preserved); **`backfill.rs` `backfill_never_posts_tool_content_the_capture_policy_excludes`** (planted Claude transcript: the excluded read's call and output never reach `/hook/batch`, a malformed read posts only the metadata-only body, public read control posted) and **`run.rs` `ledger_upload_drops_tool_content_the_capture_policy_excludes`** (excluded call and output absent from the finish request, public control present, cursor still advances), both failing with the guard removed; `transcript_capture.rs` `an_excluded_read_drops_its_call_and_result_by_id`, `id_less_results_take_the_strictest_call_of_their_turn`, `unrecoverable_arguments_and_orphan_results_fail_closed_under_a_policy`, `a_call_into_another_checkout_honors_its_policy`, `ledger_events_are_dropped_or_stripped_before_upload`, `without_a_policy_every_event_is_kept` (control); `capture_policy.rs` `tool_call_payload_reaches_the_live_decision_for_every_supported_agent` | STRONG with listed residuals. Matching is lexical by design, so these stay open: shell variables (`$VAR`, `FILE=… sh -c 'cat $FILE'`) and command substitution, a `cd` inside the command, symlinks (paths are never resolved on disk), a recursive search of a parent directory (`grep -r x docs`, `rg x`) through a shell, and tools the matcher does not list, which keep their current unknown-tool behavior. Transcript imports add: assistant prose quoting an excluded file is kept (as live prompt/assistant capture keeps it), harnesses whose hook schema the matcher does not read (Crush, Kimi Code) keep their tool events as live capture would, and id-less adapters over-drop a whole turn's results when one call is excluded; `ai-memory run` and a manual `ai-memory backfill` do not consult the allowlist capture mode. Mitigation: allowlist capture mode (`install-hooks --capture-mode allowlist`) for sensitive projects |
| 11c | Capture hook ≤200ms budget (invariant #5) | `hooks/_lib.sh` capture path `curl --max-time 0.2` (context-fetch 1.0s and background drain 2.0s are separate, larger-budget paths) | none (shell-script timeout; hard to unit-test) — watch on any capture-path change | WATCH |
| 11d | Hook server-profile routing: a marker-selected server gets only its own capture and its own token (#992) | `ai-memory-cli/src/server_profiles.rs` `resolve` (validated `ProfileName`, strict `servers.toml` parse, `roots` required once two profiles exist, component-wise root match) and `marker.rs` `find_server_selection` (inherited down the tree, any value shape counts); `commands/hook.rs` `resolve_hook_route` drops a `Rejected` route before spool, handoff and backfill, and hands the drainer no live token for a profile route; `commands/hook_spool.rs` `static_retry_token` (a profile entry retries only with its own stored token), the loopback reroot skip, and chunk splitting on `profile`; generated TS `captureServerRouted` drops a routed repository and gates `fetchHandoff`; `hooks/_lib.sh` `ai_memory_server_routed` (flag refused by `ai_memory_post_hook`/`ai_memory_get_handoff`) and `hooks/lib/ai-memory-hook.ps1` `Test-AiMemoryServerRouted` drop it in the script hooks; `--check-capture` refuses a rejected server-profile selection without printing its token or URL | `hook.rs` `each_repository_spools_to_its_own_profile_with_its_own_token`, `a_selection_that_does_not_resolve_emits_nothing` (unknown / tokenless / outside roots / roots required / invalid name, plus a resolving control), `session_start_handoff_comes_from_the_profile_server_only`, `a_repository_without_a_server_key_keeps_the_install_default`; `hook_spool.rs` `a_profile_entry_is_never_retried_with_the_install_live_token` (server B accepts exactly the install's live token and must still not get it), `a_profile_entry_recovers_with_its_own_rotated_token` (control), `a_profile_entry_on_a_dead_loopback_port_is_not_rerouted_to_the_default`, `profile_and_default_entries_at_one_address_ride_separate_batches`; `server_profiles.rs` roots/registry/name tests; `marker.rs` `nested_markers_without_server_inherit_the_ancestor_selection`; `install_hooks.rs` `generated_integrations_fail_closed_on_a_server_profile_marker`, `openclaw_plugin.rs` `openclaw_plugin_fails_closed_on_a_server_profile_marker`, and the `server-routed-*` checks in `generated_capture_policy_v1_node_runtime_evidence`; `hook.rs` `an_event_without_a_payload_cwd_routes_by_the_process_cwd`, `a_refused_route_prints_nothing_for_kimi_user_prompts`; `hook_spool.rs` `a_profile_entry_is_not_retried_with_a_token_issued_for_a_new_url`; `server_profiles.rs` `changing_the_url_without_a_token_discards_the_old_token`, `omitted_roots_keep_the_registered_ones`; `marker.rs` `outside_home_the_walk_reaches_a_marker_above_the_checkout_root`, `encoding_noise_cannot_hide_a_server_key`, `an_unreadable_marker_is_a_refused_selection`; `backfill.rs` `a_spawned_backfill_authenticates_like_the_hook_that_spawned_it`; `tests/hooks/test_lib.sh` "server profiles (#992)" section; `hook.rs` `a_mixed_spool_drains_each_event_only_to_its_own_server` (two token-gated servers, one spool, one drain: each server receives exactly its own event with exactly its own bearer); `tests/suite/server_profiles.rs` (the built binary: `server add` → `hook` spools to the profile with its token, unknown profile spools nothing, `uninstall` removes the tokens; `two_real_servers_each_receive_only_their_own_repository` runs two real `ai-memory serve` children with different root tokens and checks on each server which repository landed there); `ai-memory-hooks` `powershell_server_routed.rs` `server_routed_guard_mirrors_the_native_walk` (runs `Test-AiMemoryServerRouted` under real PowerShell: inherited, BOM, look-alike keys, the `$HOME` boundary with its control, past a checkout root outside home, current directory); `hook.rs` `a_selection_that_does_not_resolve_emits_nothing` (rejected routes refuse preflight; resolved profile control passes); `tests/hooks/test_lib.sh` and `powershell_home.rs` `a_trailing_separator_on_home_keeps_the_walk_boundary` (a `$HOME` ending in `/` or `\` keeps both script walks at home: a `server` marker above it routes nothing, with a root-home control that does) | STRONG for native hooks, generated TS, `.sh` and `.ps1` hooks. Known gap: an older binary draining a shared spool ignores `profile` |
| 11e | Native self-upgrade archive confinement (#1025) | `ai-memory-cli/src/commands/upgrade.rs` normalizes every tar/zip path, rejects links and special entries, extracts only the binary and `hooks/`, accepts only the exact non-runtime support layout emitted by `release.yml`, and caps both entry count and declared expanded bytes before writing | `upgrade.rs` `release_workflow_support_assets_are_exact_and_ignored` (shipped support paths admitted, near-miss docs/packaging/template paths refused), `extracts_archive_built_like_release_yml` and `extracts_zip_happy_path_with_hooks` (real workflow-shaped archives succeed but support assets are not written), `validate_rejects_path_traversal`, `zip_extract_rejects_path_traversal`, `tar_extract_rejects_declared_expansion_past_limit`, with binary/hooks extraction as the legitimate control | STRONG |