Skip to content

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

Rust
49.5 KB
Raw Blame
//! `[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`, resolved from the working directory its own record names
//! when the adapter keeps one; a call the live hook would reroute to another
//! checkout also answers to that checkout's admission gate, server route,
//! project scope and policy; and each tool result inherits the decision of the
//! call it answers.

use std::collections::HashMap;
use std::path::{Path, PathBuf};

use ai_memory_core::{AgentKind, NewWorkstreamEvent, WorkstreamEventKind};
use ai_memory_hooks::{
    CaptureDecision, CaptureDisposition, CapturePolicy, PolicyState, ToolFamily, tool_call_payload,
    valid_call_id,
};
use ai_memory_workstream::{RECORD_CWD_KEY, SKIPPED_RECORD_KEY};
use serde_json::Value;

use super::hook::{
    checkout_admits_capture, delivers_to_same_server, foreign_capture_decision,
    lexical_capture_cwd, routes_to_same_project, 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,
    /// A tool the capture policy does not recognize: record that it ran,
    /// never its arguments or output. The live server stores only the family
    /// for an unknown-family tool, plus an MCP tool's validated server and
    /// tool names, whatever the policy, so an import must not store more.
    Unrecognized,
    /// 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::Unrecognized => 1,
            Self::MetadataOnly(_) => 2,
            Self::Drop => 3,
        }
    }

    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 {
    data_dir: PathBuf,
    admitted: bool,
    policy: CapturePolicy,
    cwd: String,
    inspection_cwd: String,
}

impl TranscriptCapture {
    /// Resolve the live hook's admission gate (this install's capture mode
    /// under `data_dir`) and the nearest marker's policy for `cwd`, exactly as
    /// the hook does for an event reporting that cwd.
    pub(crate) fn for_checkout(data_dir: &Path, cwd: &Path) -> Self {
        let cwd = cwd.to_string_lossy().into_owned();
        Self {
            data_dir: data_dir.to_path_buf(),
            admitted: checkout_admits_capture(data_dir, &cwd),
            policy: capture_policy(&cwd),
            inspection_cwd: lexical_capture_cwd(&cwd),
            cwd,
        }
    }

    /// Whether the live hook would emit anything at all from this checkout.
    /// Under allowlist capture mode an unmarked checkout admits nothing.
    pub(crate) const fn admits_capture(&self) -> bool {
        self.admitted
    }

    /// One decision per event, in transcript order. A checkout the hook's
    /// admission gate refuses drops every event, prompts included, as the
    /// live hook emits none. Otherwise messages are kept, as live prompt
    /// capture keeps them, except the output of a Claude Code `!` shell
    /// command, which live capture never receives.
    ///
    /// An event whose record names its own working directory is judged from
    /// there, as the live hook judges an event by its own `cwd`: that
    /// directory must pass the same admission gate, deliver to the same server
    /// and resolve to the same project as this checkout, or the event is
    /// dropped.
    ///
    /// A result answers the call with the same native id. Some adapters record
    /// no id, so a result without one 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 whose id matches no recorded call,
    /// or with no call at all, is an orphan: dropped under a policy, since
    /// nothing proves it missed every ignored path, and content-free without
    /// one. A record the exporter skipped as oversized could have been one of
    /// the turn's calls, so its marker counts as an orphan call there and an
    /// id-less result of that turn fails closed with it.
    pub(crate) fn decide(&self, events: &[NewWorkstreamEvent]) -> Vec<EventCapture> {
        if !self.admitted {
            return vec![EventCapture::Drop; events.len()];
        }
        // Codex's own memory-writing agent is dropped by the live hook (#1674)
        // on checkout cwd, an event's recorded cwd, or the prompt header. An
        // import of the same run must not reintroduce those events.
        if self.drops_codex_memory_agent(events) {
            return vec![EventCapture::Drop; events.len()];
        }
        let mut elsewhere = HashMap::new();
        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 cwd = record_cwd(event).unwrap_or(&self.cwd);
            let admitted = cwd == self.cwd || self.admits_elsewhere(cwd, &mut elsewhere);
            let capture = match event.kind {
                WorkstreamEventKind::ToolCall => {
                    let capture = if admitted {
                        self.decide_call(event, cwd, &mut elsewhere)
                    } else {
                        EventCapture::Drop
                    };
                    if let Some(id) = call_id(event) {
                        by_id.insert(id, capture.clone());
                    }
                    turn.push(capture.clone());
                    capture
                }
                WorkstreamEventKind::ToolResult if !admitted => EventCapture::Drop,
                WorkstreamEventKind::ToolResult => match call_id(event) {
                    Some(id) => by_id
                        .get(id)
                        .cloned()
                        .unwrap_or_else(|| self.orphan_result()),
                    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();
                    }
                    if admitted && !shell_mode_output(event) {
                        EventCapture::Keep
                    } else {
                        EventCapture::Drop
                    }
                }
                WorkstreamEventKind::Compaction
                | WorkstreamEventKind::Checkpoint
                | WorkstreamEventKind::Annotation => {
                    if skipped_record(event) {
                        turn.push(self.orphan_result());
                    }
                    if admitted {
                        EventCapture::Keep
                    } else {
                        EventCapture::Drop
                    }
                }
            };
            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::Unrecognized => Some(withheld(event, ToolFamily::Unknown)),
                EventCapture::MetadataOnly(decision) => {
                    Some(withheld(event, decision.protocol().tool_family()))
                }
            })
            .map(|mut event| {
                // The record's cwd only steers the decision above.
                if let Some(metadata) = event.metadata.as_object_mut() {
                    metadata.remove(RECORD_CWD_KEY);
                }
                event
            })
            .collect()
    }

    /// A result with no call to inherit from. Nothing proves its tool was
    /// recognized, so even without a policy it keeps no output.
    fn orphan_result(&self) -> EventCapture {
        if self.policy.state() == PolicyState::Inactive {
            EventCapture::Unrecognized
        } else {
            EventCapture::Drop
        }
    }

    /// Whether the live hook would deliver an event reported from `cwd`, a
    /// directory other than this checkout's, to this import's server and
    /// project at all: the hook's admission gate there (capture mode, marker
    /// opt-in, readable routing marker), the same server-profile route, and
    /// the same project scope. The import files everything under this
    /// checkout's project, so an event the hook would file under another one
    /// is left out rather than misfiled.
    fn admits_elsewhere(&self, cwd: &str, seen: &mut HashMap<String, bool>) -> bool {
        *seen.entry(cwd.to_owned()).or_insert_with(|| {
            checkout_admits_capture(&self.data_dir, cwd)
                && delivers_to_same_server(&self.data_dir, &self.cwd, cwd)
                && routes_to_same_project(&self.cwd, cwd)
        })
    }

    /// Whether this import is Codex's background memory-writing agent (#1674).
    ///
    /// The live hook's primary signal is cwd (every event of the run carries
    /// it, SessionStart included). The header catches a `CODEX_HOME` whose
    /// last component is not `.codex`. `backfill` and `run` pass the project
    /// checkout as this capture's cwd, so an event's recorded cwd is checked
    /// too.
    fn drops_codex_memory_agent(&self, events: &[NewWorkstreamEvent]) -> bool {
        if ai_memory_core::is_codex_memory_agent_cwd(&self.cwd) {
            return true;
        }
        events.iter().any(|event| {
            if event.agent != AgentKind::Codex {
                return false;
            }
            record_cwd(event).is_some_and(ai_memory_core::is_codex_memory_agent_cwd)
                || (matches!(event.kind, WorkstreamEventKind::Message)
                    && matches!(event.role.as_deref(), Some("user" | "human"))
                    && ai_memory_core::looks_like_codex_memory_agent_prompt(&event.content))
        })
    }

    /// Judge one call as the live hook would for an event reporting `cwd`,
    /// under this checkout's policy too, since the import stays in this scope.
    fn decide_call(
        &self,
        event: &NewWorkstreamEvent,
        cwd: &str,
        elsewhere: &mut HashMap<String, bool>,
    ) -> EventCapture {
        let (name, args) = recorded_call(event);
        let unreadable = args.is_none();
        let raw = tool_call_payload(event.agent, name, args.as_ref(), call_id(event));
        let recognized = self
            .policy
            .inspect(event.agent, &raw, &self.inspection_cwd)
            .protocol()
            .tool_family()
            != ToolFamily::Unknown;
        let inspect = |policy: &CapturePolicy, cwd: &str| {
            inspect_call(
                policy,
                event.agent,
                &raw,
                &lexical_capture_cwd(cwd),
                unreadable,
            )
        };
        let mut capture = if cwd == self.cwd {
            inspect_call(
                &self.policy,
                event.agent,
                &raw,
                &self.inspection_cwd,
                unreadable,
            )
        } else {
            inspect(&self.policy, cwd).stricter(inspect(&capture_policy(cwd), cwd))
        };
        // The live hook would deliver this call to that checkout under its
        // admission gate, route and policy. An import stays in this scope, so
        // both policies apply, and a destination the hook would refuse or send
        // to another server drops the call.
        if let Some(destination) = tool_location_routing_cwd(event.agent, &raw, cwd) {
            if !self.admits_elsewhere(&destination, elsewhere) {
                return EventCapture::Drop;
            }
            capture = capture.stricter(inspect(&capture_policy(&destination), &destination));
        }
        // Another checkout's `ignore_paths` hold for a call made here too,
        // as in the live hook.
        if let Some(foreign) = foreign_capture_decision(
            event.agent,
            &raw,
            &lexical_capture_cwd(cwd),
            crate::marker::find_marker(cwd).as_deref(),
        ) {
            capture = capture.stricter(EventCapture::from_decision(foreign));
        }
        if recognized {
            capture
        } else {
            capture.stricter(EventCapture::Unrecognized)
        }
    }
}

/// One policy's decision for a rebuilt call. 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.
fn inspect_call(
    policy: &CapturePolicy,
    agent: AgentKind,
    raw: &Value,
    inspection_cwd: &str,
    unreadable: bool,
) -> EventCapture {
    let decision = policy.inspect(agent, raw, inspection_cwd);
    if unreadable
        && decision.protocol().tool_family() == ToolFamily::NonFile
        && policy.state() != PolicyState::Inactive
    {
        return EventCapture::Drop;
    }
    EventCapture::from_decision(decision)
}

/// The absolute working directory the event's own record names, if any.
fn record_cwd(event: &NewWorkstreamEvent) -> Option<&str> {
    event
        .metadata
        .get(RECORD_CWD_KEY)
        .and_then(Value::as_str)
        .filter(|cwd| Path::new(cwd).is_absolute())
}

/// Claude Code records a `!` shell command's output as a user message that
/// opens with one of these blocks. Live capture never receives that output.
/// The opening tag decides alone: the output is arbitrary text, so it can
/// hold a closing tag of its own, and no reading of where a block ends is
/// safe.
fn shell_mode_output(event: &NewWorkstreamEvent) -> bool {
    const TAGS: [&str; 4] = [
        "<bash-stdout>",
        "<bash-stderr>",
        "<local-command-stdout>",
        "<local-command-stderr>",
    ];
    event.agent == AgentKind::ClaudeCode
        && TAGS
            .iter()
            .any(|tag| event.content.trim_start().starts_with(tag))
}

/// Whether the event is the exporter's marker for a record it skipped as
/// oversized.
fn skipped_record(event: &NewWorkstreamEvent) -> bool {
    event.kind == WorkstreamEventKind::Annotation
        && event
            .metadata
            .get(SKIPPED_RECORD_KEY)
            .and_then(Value::as_bool)
            == Some(true)
}

/// 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
/// what the live server keeps for such an event: the family and a call id
/// that passes its validation, never the tool's own name.
fn withheld(mut event: NewWorkstreamEvent, family: ToolFamily) -> NewWorkstreamEvent {
    let family = serde_json::to_value(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_use_id", "tool_call_id"] {
        if let Some(value) = event
            .metadata
            .get(key)
            .filter(|value| value.as_str().is_some_and(valid_call_id))
        {
            metadata.insert(key.into(), value.clone());
        }
    }
    event.metadata = Value::Object(metadata);
    event
}

#[cfg(test)]
mod tests {
    use super::*;
    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::Unrecognized => "unrecognized",
                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(), 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(), 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"
            ]
        );
    }

    /// A record the exporter skipped as oversized may have been an excluded
    /// call (a large write under an ignored path) whose result follows with
    /// no id. Its marker makes that result an orphan instead of letting a
    /// public sibling call lend it a keep; the next user turn starts clean.
    /// Control: the same turn without the marker keeps the result.
    #[test]
    fn a_skipped_record_makes_the_id_less_results_of_its_turn_orphans() {
        let skipped = || {
            event(
                WorkstreamEventKind::Annotation,
                "assistant",
                "a transcript record over the per-record size cap was skipped",
                json!({ SKIPPED_RECORD_KEY: true }),
            )
        };
        for (marker, orphan) in [(Some("secrets/**"), "drop"), (None, "unrecognized")] {
            let repo = checkout(marker);
            let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
            let turn = |gap: Option<NewWorkstreamEvent>| {
                let mut events = vec![
                    event(WorkstreamEventKind::Message, "user", "do it", json!({})),
                    read_call(&repo.path().join("src/lib.rs"), None),
                    result("public code", None),
                ];
                events.extend(gap);
                events.push(result("SKIPPEDSENTINEL wrote secrets/dump.json", None));
                events.extend([
                    event(WorkstreamEventKind::Message, "user", "next", json!({})),
                    read_call(&repo.path().join("src/lib.rs"), None),
                    result("public code again", None),
                ]);
                events
            };
            let events = turn(Some(skipped()));
            assert_eq!(
                kinds(&capture.decide(&events)),
                [
                    "keep", "keep", "keep", "keep", orphan, "keep", "keep", "keep"
                ],
                "{marker:?}"
            );
            let uploaded = serde_json::to_string(&capture.filter_ledger_events(events)).unwrap();
            assert!(!uploaded.contains("SKIPPEDSENTINEL"), "{uploaded}");
            assert!(uploaded.contains("public code again"), "{uploaded}");
            assert_eq!(
                kinds(&capture.decide(&turn(None))),
                ["keep", "keep", "keep", "keep", "keep", "keep", "keep"],
                "{marker:?}: without a gap the turn's public call decides"
            );
        }
    }

    #[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(), 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: a recognized call and its id-less result are kept; a result
    /// whose id answers no recorded call is an orphan and keeps no content.
    #[test]
    fn without_a_policy_every_event_is_kept() {
        let repo = checkout(None);
        let capture = TranscriptCapture::for_checkout(repo.path(), 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", "unrecognized"]
        );
    }

    /// Codex's memory-writing agent runs from `$CODEX_HOME/memories`, and the
    /// live hook drops every event of that run (#1674). An import must not
    /// reintroduce what the hook refused: all events drop, prompts included,
    /// while an ordinary checkout in the same import keeps them.
    #[test]
    fn an_import_of_codex_memory_agent_runs_captures_nothing() {
        let home = tempfile::tempdir().unwrap();
        let memories = home.path().join(".codex").join("memories");
        std::fs::create_dir_all(&memories).unwrap();
        let capture = TranscriptCapture::for_checkout(home.path(), &memories);
        let events = [
            event(
                WorkstreamEventKind::Message,
                "user",
                "consolidate",
                json!({}),
            ),
            read_call(&memories.join("notes.md"), None),
            result("notes", None),
        ];
        assert_eq!(kinds(&capture.decide(&events)), ["drop", "drop", "drop"]);

        let repo = checkout(None);
        let control = TranscriptCapture::for_checkout(repo.path(), repo.path());
        let events = [event(
            WorkstreamEventKind::Message,
            "user",
            "please fix the test",
            json!({}),
        )];
        assert_eq!(kinds(&control.decide(&events)), ["keep"]);
    }

    /// The live hook's second signal is the agent's prompt header, for a
    /// `CODEX_HOME` whose last component is not `.codex`. An import of that
    /// run from a project checkout must drop every event, not only the prompt.
    #[test]
    fn an_import_drops_a_codex_memory_agent_run_by_prompt_header() {
        let repo = checkout(None);
        let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
        let events = [
            as_codex(event(
                WorkstreamEventKind::Message,
                "user",
                "## Memory Writing Agent: Phase 2 (Consolidation)\n\nnotes",
                json!({}),
            )),
            as_codex(read_call(&repo.path().join("notes.md"), None)),
            as_codex(result("notes", None)),
        ];
        assert_eq!(kinds(&capture.decide(&events)), ["drop", "drop", "drop"]);
    }

    /// A Codex user prompt that is not the memory-writing header stays. The
    /// header matcher is prefix-based on `## Memory Writing Agent`; ordinary
    /// work that names the agent in prose must not drop the session.
    #[test]
    fn a_codex_run_with_an_ordinary_prompt_is_kept() {
        let repo = checkout(None);
        let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
        let events = [as_codex(event(
            WorkstreamEventKind::Message,
            "user",
            "Please update the memory writing agent docs",
            json!({}),
        ))];
        assert_eq!(kinds(&capture.decide(&events)), ["keep"]);
    }

    /// The header is a Codex signal. A Claude user message that opens with
    /// the same words is kept, matching the live hook's agent gate.
    #[test]
    fn a_claude_prompt_with_the_memory_agent_header_is_kept() {
        let repo = checkout(None);
        let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
        let events = [event(
            WorkstreamEventKind::Message,
            "user",
            "## Memory Writing Agent: Phase 2 (Consolidation)\n\nnotes",
            json!({}),
        )];
        assert_eq!(kinds(&capture.decide(&events)), ["keep"]);
    }

    /// `backfill` and `run` pass the project checkout as the capture cwd. An
    /// event whose recorded cwd is `$CODEX_HOME/memories` is still the
    /// memory-writing agent and must drop the whole import.
    #[test]
    fn an_import_drops_a_codex_memory_agent_run_by_recorded_cwd() {
        let repo = checkout(None);
        let memories = repo.path().join(".codex").join("memories");
        std::fs::create_dir_all(&memories).unwrap();
        let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
        let events = [
            as_codex(at(
                event(
                    WorkstreamEventKind::Message,
                    "user",
                    "consolidate",
                    json!({}),
                ),
                &memories,
            )),
            as_codex(at(read_call(&memories.join("notes.md"), None), &memories)),
            as_codex(at(result("notes", None), &memories)),
        ];
        assert_eq!(kinds(&capture.decide(&events)), ["drop", "drop", "drop"]);
    }

    /// A result carrying an id that matches no recorded call follows the
    /// orphan rule, not the turn's decision: a public read in the same turn
    /// must not lend it a keep. Control: the read's own result is kept.
    #[test]
    fn a_result_whose_id_matches_no_call_is_an_orphan() {
        for (marker, orphan) in [(Some("docs/adr/**"), "drop"), (None, "unrecognized")] {
            let repo = checkout(marker);
            let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
            let events = [
                event(WorkstreamEventKind::Message, "user", "read", json!({})),
                read_call(&repo.path().join("src/lib.rs"), Some("pub")),
                result("public code", Some("pub")),
                result("ORPHANSENTINEL", Some("never-called")),
            ];
            assert_eq!(
                kinds(&capture.decide(&events)),
                ["keep", "keep", "keep", orphan],
                "{marker:?}"
            );
            let uploaded =
                serde_json::to_string(&capture.filter_ledger_events(events.into())).unwrap();
            assert!(!uploaded.contains("ORPHANSENTINEL"), "{uploaded}");
            assert!(uploaded.contains("public code"), "{uploaded}");
        }
    }

    /// A read whose absolute target is another marked checkout of the same
    /// project 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 base = tempfile::tempdir().unwrap();
        let scope = "workspace = \"w\"\nproject = \"p\"\n";
        let source = marked(&base.path().join("source"), scope);
        let other = marked(
            &base.path().join("other"),
            &format!("{scope}[capture]\nignore_paths = [\"private/**\"]\n"),
        );
        let capture = TranscriptCapture::for_checkout(base.path(), &source);
        let events = [
            read_call(&other.join("private/key.txt"), Some("a")),
            result("private", Some("a")),
            read_call(&other.join("open.txt"), Some("b")),
            result("open", Some("b")),
        ];
        assert_eq!(
            kinds(&capture.decide(&events)),
            ["drop", "drop", "keep", "keep"]
        );
    }

    /// A shell command run here that names another checkout's excluded file
    /// answers to that checkout's policy on import too, as in the live hook;
    /// one naming its public file is kept.
    #[test]
    fn a_shell_command_naming_another_checkouts_file_honors_its_policy() {
        let source = checkout(None);
        let other = checkout(Some("private/**"));
        let capture = TranscriptCapture::for_checkout(source.path(), source.path());
        let bash = |path: PathBuf, id: &str| {
            event(
                WorkstreamEventKind::ToolCall,
                "assistant",
                &format!(
                    "Bash: {}",
                    json!({"command": format!("cat {}", path.display())})
                ),
                json!({"tool": "Bash", "tool_use_id": id}),
            )
        };
        let events = [
            bash(other.path().join("private/key.txt"), "a"),
            result("private", Some("a")),
            bash(other.path().join("open.txt"), "b"),
            result("open", Some("b")),
        ];
        assert_eq!(
            kinds(&capture.decide(&events)),
            ["drop", "drop", "keep", "keep"]
        );
    }

    /// A search, a directory glob or an `apply_patch` recorded here that
    /// reaches a sibling checkout's excluded file answers to that checkout's
    /// policy on import too, as in the live hook. The same tools kept to this
    /// checkout are imported whole.
    #[test]
    fn globs_and_searches_reaching_another_checkout_honor_its_policy() {
        let parent = tempfile::tempdir().unwrap();
        let (a, b) = (parent.path().join("a"), parent.path().join("b"));
        for dir in [&a, &b] {
            std::fs::create_dir_all(dir).unwrap();
        }
        std::fs::write(
            a.join(".ai-memory.toml"),
            "[capture]\nignore_paths = [\"secrets.env\"]\n",
        )
        .unwrap();
        let capture = TranscriptCapture::for_checkout(parent.path(), &b);
        let call = |tool: &str, input: Value, id: &str| {
            event(
                WorkstreamEventKind::ToolCall,
                "assistant",
                &format!("{tool}: {input}"),
                json!({"tool": tool, "tool_use_id": id}),
            )
        };
        let events = [
            call(
                "Grep",
                json!({"pattern": "KEY", "path": "../a/secrets.env"}),
                "a",
            ),
            result("secret", Some("a")),
            call("Bash", json!({"command": "cat ../*/secrets.env"}), "b"),
            result("secret", Some("b")),
            call("Glob", json!({"pattern": "../a/*.env"}), "c"),
            result("secret", Some("c")),
            call("Grep", json!({"pattern": "KEY", "path": "src"}), "d"),
            result("own", Some("d")),
            call("Bash", json!({"command": "ls src/*"}), "e"),
            result("own", Some("e")),
        ];
        assert_eq!(
            kinds(&capture.decide(&events)),
            [
                "drop", "drop", "drop", "drop", "drop", "drop", "keep", "keep", "keep", "keep"
            ]
        );
    }

    /// Under allowlist capture mode the live hook emits nothing — prompts
    /// included — from a checkout without a marker; an import drops every
    /// event there. A marked checkout and the default denylist mode keep them.
    #[test]
    fn allowlist_mode_admits_nothing_from_an_unmarked_checkout() {
        let allowlist = tempfile::tempdir().unwrap();
        std::fs::write(
            allowlist.path().join(super::super::hook::CAPTURE_MODE_FILE),
            "allowlist\n",
        )
        .unwrap();
        let denylist = tempfile::tempdir().unwrap();
        let unmarked = checkout(None);
        let marked = checkout(Some("docs/adr/**"));
        let events = |repo: &Path| {
            vec![
                event(WorkstreamEventKind::Message, "user", "a prompt", json!({})),
                read_call(&repo.join("src/lib.rs"), Some("pub")),
                result("public code", Some("pub")),
                event(WorkstreamEventKind::Message, "assistant", "done", json!({})),
            ]
        };

        let refused = TranscriptCapture::for_checkout(allowlist.path(), unmarked.path());
        assert!(!refused.admits_capture());
        assert_eq!(
            kinds(&refused.decide(&events(unmarked.path()))),
            ["drop", "drop", "drop", "drop"]
        );
        assert!(
            refused
                .filter_ledger_events(events(unmarked.path()))
                .is_empty()
        );

        let opted_in = TranscriptCapture::for_checkout(allowlist.path(), marked.path());
        assert!(opted_in.admits_capture());
        assert_eq!(
            kinds(&opted_in.decide(&events(marked.path()))),
            ["keep", "keep", "keep", "keep"]
        );
        let default = TranscriptCapture::for_checkout(denylist.path(), unmarked.path());
        assert!(default.admits_capture());
        assert_eq!(
            kinds(&default.decide(&events(unmarked.path()))),
            ["keep", "keep", "keep", "keep"]
        );
    }

    fn at(mut event: NewWorkstreamEvent, cwd: &Path) -> NewWorkstreamEvent {
        event.metadata[RECORD_CWD_KEY] = cwd.to_string_lossy().into_owned().into();
        event
    }

    fn as_codex(mut event: NewWorkstreamEvent) -> NewWorkstreamEvent {
        event.agent = AgentKind::Codex;
        event
    }

    /// The live hook judges every event — prompts included — by its own
    /// `cwd`. A record written after the session moved into a repository
    /// the hook would not capture under allowlist mode is dropped; records in
    /// a subdirectory of the opted-in checkout are kept, and the record cwd
    /// never reaches the ledger.
    #[test]
    fn a_record_cwd_answers_to_the_hook_admission_gate_there() {
        let data_dir = tempfile::tempdir().unwrap();
        std::fs::write(
            data_dir.path().join(super::super::hook::CAPTURE_MODE_FILE),
            "allowlist\n",
        )
        .unwrap();
        let marked = checkout(Some("docs/adr/**"));
        // Outside `$HOME` a marker lookup stops at the git root.
        let init = std::process::Command::new("git")
            .args(["init", "-q"])
            .arg(marked.path())
            .status()
            .unwrap();
        assert!(init.success());
        let subdir = marked.path().join("src");
        std::fs::create_dir_all(&subdir).unwrap();
        let unmarked = checkout(None);
        let capture = TranscriptCapture::for_checkout(data_dir.path(), marked.path());
        let events = |cwd: &Path| {
            vec![
                at(
                    event(WorkstreamEventKind::Message, "user", "a prompt", json!({})),
                    cwd,
                ),
                at(read_call(&cwd.join("lib.rs"), Some("r")), cwd),
                at(result("code", Some("r")), cwd),
            ]
        };
        assert_eq!(
            kinds(&capture.decide(&events(unmarked.path()))),
            ["drop", "drop", "drop"]
        );
        assert_eq!(
            kinds(&capture.decide(&events(&subdir))),
            ["keep", "keep", "keep"]
        );
        let uploaded = capture.filter_ledger_events(events(&subdir));
        assert!(
            uploaded
                .iter()
                .all(|event| event.metadata.get(RECORD_CWD_KEY).is_none()),
            "{uploaded:?}"
        );
    }

    /// A Claude Code `!` command's output is recorded as user messages that
    /// open with a `<bash-stdout>`/`<bash-stderr>` (or `<local-command-stdout>`)
    /// block, which live capture never receives — even when the output itself
    /// holds a closing tag. The typed command and an ordinary prompt quoting
    /// such a tag are kept, as is another agent's message.
    #[test]
    fn claude_shell_mode_output_is_not_imported() {
        let repo = checkout(None);
        let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
        let user = |text: &str| event(WorkstreamEventKind::Message, "user", text, json!({}));
        let mut codex = user("<bash-stdout>codex text</bash-stdout>");
        codex.agent = AgentKind::Codex;
        let events = [
            user("<bash-input>cat notes.txt</bash-input>"),
            user("<bash-stdout>SECRET</bash-stdout><bash-stderr></bash-stderr>"),
            user("<local-command-stdout>output</local-command-stdout>"),
            user("<bash-stdout>cut by the size cap"),
            user("why does <bash-stdout>x</bash-stdout> appear?"),
            user("<bash-stdout>x</bash-stdout> and then more output"),
            user("<bash-stdout>printf '</bash-stdout>' SHELLSENTINEL</bash-stdout>"),
            user("  <bash-stderr>e</bash-stderr><bash-stdout>a</bash-stdout>"),
            codex,
        ];
        assert_eq!(
            kinds(&capture.decide(&events)),
            [
                "keep", "drop", "drop", "drop", "keep", "drop", "drop", "drop", "keep"
            ]
        );
    }

    /// Live capture stores no arguments or output for a tool the policy does
    /// not recognize, with or without a policy, so neither does an import: a
    /// call and its result keep only the family, as does a result with no
    /// call to inherit from. A recognized public read is kept.
    #[test]
    fn unrecognized_tools_keep_no_content_with_or_without_a_policy() {
        let unknown = |id: &str| {
            event(
                WorkstreamEventKind::ToolCall,
                "assistant",
                "mcp__vault__fetch: {\"query\":\"ARGSENTINEL\"}",
                json!({"tool": "mcp__vault__fetch", "tool_use_id": id}),
            )
        };
        for marker in [None, Some("docs/adr/**")] {
            let repo = checkout(marker);
            let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
            let events = vec![
                unknown("u"),
                result("OUTSENTINEL", Some("u")),
                read_call(&repo.path().join("src/lib.rs"), Some("p")),
                result("public code", Some("p")),
            ];
            assert_eq!(
                kinds(&capture.decide(&events)),
                ["unrecognized", "unrecognized", "keep", "keep"],
                "{marker:?}"
            );
            let uploaded = serde_json::to_string(&capture.filter_ledger_events(events)).unwrap();
            assert!(!uploaded.contains("SENTINEL"), "{uploaded}");
            assert!(!uploaded.contains("mcp__vault"), "tool name: {uploaded}");
            assert!(uploaded.contains("\"tool_use_id\":\"u\""), "{uploaded}");
            assert!(uploaded.contains("public code"), "{uploaded}");
            assert!(
                uploaded.contains("[unknown tool output withheld by the capture policy]"),
                "{uploaded}"
            );
        }
        let repo = checkout(None);
        let capture = TranscriptCapture::for_checkout(repo.path(), repo.path());
        assert_eq!(
            kinds(&capture.decide(&[result("orphan output", Some("gone"))])),
            ["unrecognized"]
        );
        // The server keeps a call id only when it passes its validation.
        let mut odd = unknown("u");
        odd.metadata["tool_use_id"] = "not a valid/id".into();
        let kept = capture.filter_ledger_events(vec![odd]);
        assert_eq!(kept[0].metadata, json!({}), "{kept:?}");
    }

    #[test]
    fn ledger_events_are_dropped_or_stripped_before_upload() {
        let repo = checkout(Some("docs/adr/**"));
        let capture = TranscriptCapture::for_checkout(repo.path(), 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"}));
    }

    fn marked(dir: &Path, marker: &str) -> PathBuf {
        std::fs::create_dir_all(dir).unwrap();
        std::fs::write(dir.join(".ai-memory.toml"), marker).unwrap();
        dir.to_path_buf()
    }

    /// A compaction or annotation recorded in a directory the hook would not
    /// capture is dropped like every other event there; recorded in the
    /// opted-in checkout it is kept.
    #[test]
    fn boundary_events_answer_to_the_record_cwd_admission_gate() {
        let data_dir = tempfile::tempdir().unwrap();
        std::fs::write(
            data_dir.path().join(super::super::hook::CAPTURE_MODE_FILE),
            "allowlist\n",
        )
        .unwrap();
        let repo = checkout(Some("docs/adr/**"));
        let unmarked = checkout(None);
        let capture = TranscriptCapture::for_checkout(data_dir.path(), repo.path());
        let boundary = |cwd: &Path| {
            vec![
                at(
                    event(
                        WorkstreamEventKind::Compaction,
                        "assistant",
                        "COMPACTSENTINEL",
                        json!({}),
                    ),
                    cwd,
                ),
                at(
                    event(
                        WorkstreamEventKind::Annotation,
                        "assistant",
                        "NOTESENTINEL",
                        json!({}),
                    ),
                    cwd,
                ),
            ]
        };
        assert_eq!(
            kinds(&capture.decide(&boundary(unmarked.path()))),
            ["drop", "drop"]
        );
        assert!(
            capture
                .filter_ledger_events(boundary(unmarked.path()))
                .is_empty()
        );
        assert_eq!(
            kinds(&capture.decide(&boundary(repo.path()))),
            ["keep", "keep"]
        );
    }

    /// The hook files an event under the project its own cwd resolves to. An
    /// import files everything under the importing checkout's project, so
    /// records written in a checkout of another project on the same server
    /// are dropped, prompts included; a checkout declaring the same project
    /// is kept.
    #[test]
    fn a_record_cwd_in_another_project_is_dropped() {
        let data_dir = tempfile::tempdir().unwrap();
        let base = tempfile::tempdir().unwrap();
        let source = marked(
            &base.path().join("source"),
            "workspace = \"w\"\nproject = \"p\"\n",
        );
        let same = marked(
            &base.path().join("same"),
            "workspace = \"w\"\nproject = \"p\"\n",
        );
        let other = marked(
            &base.path().join("other"),
            "workspace = \"w\"\nproject = \"q\"\n",
        );
        let capture = TranscriptCapture::for_checkout(data_dir.path(), &source);
        let events = |cwd: &Path| {
            vec![
                at(
                    event(
                        WorkstreamEventKind::Message,
                        "user",
                        "PROMPTSENTINEL",
                        json!({}),
                    ),
                    cwd,
                ),
                at(read_call(&cwd.join("lib.rs"), Some("r")), cwd),
                at(result("CODESENTINEL", Some("r")), cwd),
            ]
        };
        assert_eq!(
            kinds(&capture.decide(&events(&other))),
            ["drop", "drop", "drop"]
        );
        assert!(capture.filter_ledger_events(events(&other)).is_empty());
        assert_eq!(
            kinds(&capture.decide(&events(&same))),
            ["keep", "keep", "keep"]
        );
    }

    /// The same for a call the hook would reroute by its absolute target: a
    /// read inside a checkout of another project is dropped, call and result.
    #[test]
    fn a_reroute_into_another_project_is_dropped() {
        let data_dir = tempfile::tempdir().unwrap();
        let base = tempfile::tempdir().unwrap();
        let source = marked(
            &base.path().join("source"),
            "workspace = \"w\"\nproject = \"p\"\n",
        );
        let other = marked(
            &base.path().join("other"),
            "workspace = \"w\"\nproject = \"q\"\n",
        );
        let same = marked(
            &base.path().join("same"),
            "workspace = \"w\"\nproject = \"p\"\n",
        );
        let capture = TranscriptCapture::for_checkout(data_dir.path(), &source);
        let events = [
            read_call(&other.join("x.txt"), Some("o")),
            result("OTHERSENTINEL", Some("o")),
            read_call(&same.join("y.txt"), Some("s")),
            result("same project", Some("s")),
        ];
        assert_eq!(
            kinds(&capture.decide(&events)),
            ["drop", "drop", "keep", "keep"]
        );
    }
}