Skip to content

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

Rust

fix(hooks): apply capture ignore_paths to shell commands

Peterson Salme57938c391c88
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9fab82ee..900dbc50 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- `[capture] ignore_paths` now covers shell commands. Shell tools (`Bash`,
+ `shell`, `execute_bash`, `terminal`, …) were classified as non-file and always
+ kept, so `cat docs/adr/*.md` stored the ignored file's full text in the
+ observation body. The native `ai-memory hook` now splits the command line
+ lexically and drops the event when an argument, resolved from the event's
+ `cwd`, matches an ignored pattern or is a glob that can reach one. Variables,
+ command substitution and commands that name no path are not followed. The
+ generated OpenCode, OMP, Pi and OpenClaw integrations are unchanged. The
+ marker-file reference also documents excluding large tool results that Claude
+ Code saves and re-reads from `~/.claude/projects/**/tool-results/**`. (#946)
- Grok Build CLI tool observations are no longer stored with an empty body.
Grok posts Claude Code's snake_case tool fields (`tool_name` / `tool_input` /
`tool_use_id`), but it was missing from both `closed_tool_agent` and the
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index d241446b..291b750e 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -2058,6 +2058,43 @@ mod tests {
assert_eq!(hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)), 0);
}
+ #[tokio::test]
+ async fn shell_command_reading_an_ignored_path_is_dropped_before_spool() {
+ for (command, spooled) in [("cat ./secret/*.md | head", 0), ("cat public/readme.md", 1)] {
+ for event in ["pre-tool-use", "post-tool-use"] {
+ let tmp = tempfile::tempdir().unwrap();
+ std::fs::write(
+ tmp.path().join(".ai-memory.toml"),
+ "[capture]\nignore_paths = [\"secret/**\"]\n",
+ )
+ .unwrap();
+ let data_dir = tmp.path().join("data");
+ let mut args = devin_hook_args(event);
+ args.agent = "claude-code".into();
+ let raw = serde_json::json!({
+ "session_id": "shell", "cwd": tmp.path(),
+ "tool_name": "Bash", "tool_input": {"command": command},
+ "tool_response": {"stdout": "SENTINEL_CONTENT"},
+ });
+ let mut stdout = Vec::new();
+ run_with_payload(
+ Some(data_dir.clone()),
+ args,
+ raw.to_string(),
+ &mut stdout,
+ |_, _| panic!("tool events below the threshold must only spool"),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)),
+ spooled,
+ "{event}: {command}"
+ );
+ }
+ }
+ }
+
#[tokio::test]
async fn codex_native_capture_policy_runs_before_spool_and_preserves_identity() {
for (tool, input, disposition) in [
diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rs
index 9614a200..eb50ed90 100644
--- a/crates/ai-memory-hooks/src/capture_policy.rs
+++ b/crates/ai-memory-hooks/src/capture_policy.rs
@@ -381,6 +381,7 @@ impl CaptureProtocol {
pub struct CapturePolicy {
state: PolicyState,
patterns: Vec<CompiledPattern>,
+ home: Option<String>,
}
#[derive(Clone, Debug)]
@@ -388,6 +389,8 @@ struct CompiledPattern {
path: String,
flavor: Flavor,
directory_base: Option<String>,
+ /// Whole segments before the first glob; a matching path must start here.
+ literal_prefix: String,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Flavor {
@@ -431,6 +434,7 @@ impl CapturePolicy {
return Self {
state: PolicyState::Invalid,
patterns: Vec::new(),
+ home: None,
};
}
CaptureSource::Parsed(config) => config,
@@ -443,10 +447,12 @@ impl CapturePolicy {
Ok(patterns) => Self {
state: PolicyState::Active,
patterns,
+ home: home_dir.and_then(|dir| normalize_root(dir).ok()),
},
Err(()) => Self {
state: PolicyState::Invalid,
patterns: Vec::new(),
+ home: None,
},
}
}
@@ -454,6 +460,7 @@ impl CapturePolicy {
Self {
state: PolicyState::Inactive,
patterns: Vec::new(),
+ home: None,
}
}
/// Evaluates every policy state using only direct fixture-backed schemas.
@@ -494,6 +501,18 @@ impl CapturePolicy {
),
},
},
+ // A shell command has no path field, but its arguments can
+ // still name an ignored file whose content lands in the
+ // output (`cat docs/adr/*.md`). An exhausted match budget
+ // fails closed like an unprovable file candidate.
+ ToolFamily::NonFile => match extracted
+ .command
+ .as_deref()
+ .map(|command| self.match_command(command, cwd))
+ {
+ Some(Ok(true) | Err(())) => (CaptureDisposition::Drop, extracted.state),
+ Some(Ok(false)) | None => (CaptureDisposition::Keep, extracted.state),
+ },
_ => (CaptureDisposition::Keep, extracted.state),
},
};
@@ -549,6 +568,64 @@ impl CapturePolicy {
}
Ok(false)
}
+ /// Lexically matches every path-like shell argument. Nothing is expanded
+ /// or executed: variables, command substitution, and `cd` are not
+ /// followed, so this narrows the leak rather than closing every alias.
+ fn match_command(&self, command: &str, cwd: &str) -> Result<bool, ()> {
+ let mut work = 0_usize;
+ for word in shell_words(command) {
+ for argument in shell_arguments(&word) {
+ let expanded = match (argument.strip_prefix("~/"), self.home.as_deref()) {
+ (Some(rest), Some(home)) => join(home, rest),
+ _ => argument.to_owned(),
+ };
+ // Not a usable path (drive-relative, oversized, bad cwd).
+ let Some(candidate) = normalize_candidate(&expanded, cwd) else {
+ continue;
+ };
+ let insensitive = candidate.flavor == Flavor::Windows;
+ let is_glob = candidate.path.contains(['*', '?']);
+ for pattern in self
+ .patterns
+ .iter()
+ .filter(|pattern| pattern.flavor == candidate.flavor)
+ {
+ // Linear and bounded by the command itself; only the
+ // quadratic matches below are charged to the budget.
+ let under_prefix =
+ starts_with_chars(&candidate.path, &pattern.literal_prefix, insensitive);
+ if !under_prefix && !is_glob {
+ continue;
+ }
+ work = work
+ .checked_add(
+ pattern
+ .path
+ .chars()
+ .count()
+ .saturating_mul(candidate.path.chars().count()),
+ )
+ .ok_or(())?;
+ if work > MAX_MATCH_WORK {
+ return Err(());
+ }
+ if (under_prefix
+ && glob_match(
+ &pattern.path,
+ &candidate.path,
+ pattern.directory_base.as_deref(),
+ insensitive,
+ ))
+ || (is_glob
+ && glob_reaches(&candidate.path, &pattern.literal_prefix, insensitive))
+ {
+ return Ok(true);
+ }
+ }
+ }
+ }
+ Ok(false)
+ }
}
/// Constructs a metadata-only replacement from scalar allowlisted envelope values and a decision.
@@ -578,6 +655,7 @@ pub fn metadata_only_body(
struct Extracted {
family: ToolFamily,
paths: Option<Vec<String>>,
+ command: Option<String>,
call_id: Option<String>,
state: ExtractionState,
}
@@ -633,6 +711,9 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted {
let paths = (family == ToolFamily::File)
.then(|| args.and_then(|value| extract_paths(name, value)))
.flatten();
+ let command = (family == ToolFamily::NonFile)
+ .then(|| args.and_then(shell_command))
+ .flatten();
let state = if family == ToolFamily::File && paths.is_none() {
ExtractionState::MissingOrMalformed
} else {
@@ -658,6 +739,7 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted {
Extracted {
family,
paths,
+ command,
call_id,
state,
}
@@ -787,6 +869,79 @@ fn direct_paths(object: &Map<String, Value>) -> Option<Vec<String>> {
(!paths.is_empty()).then_some(paths)
}
+/// The command line of a shell tool. Argument vectors (Codex exec) are
+/// joined so a `bash -lc "<script>"` element is tokenized like any script.
+fn shell_command(args: &Value) -> Option<String> {
+ match args.get("command").or_else(|| args.get("cmd"))? {
+ Value::String(command) => Some(command.clone()),
+ Value::Array(items) => items
+ .iter()
+ .map(Value::as_str)
+ .collect::<Option<Vec<_>>>()
+ .map(|items| items.join(" ")),
+ _ => None,
+ }
+}
+
+/// Splits a command line into words the way a POSIX shell would before
+/// expansion: quotes group, and whitespace and control/redirection operators
+/// separate. A backslash escapes only a character the shell treats specially,
+/// so Windows paths (`docs\adr\x.md`) keep their separators.
+fn shell_words(command: &str) -> Vec<String> {
+ let is_operator = |c: char| matches!(c, '|' | '&' | ';' | '<' | '>' | '(' | ')');
+ let mut words = Vec::new();
+ let mut word = String::new();
+ let mut in_word = false;
+ let mut quote = None;
+ let mut chars = command.chars().peekable();
+ while let Some(c) = chars.next() {
+ match (quote, c) {
+ (Some('\''), '\'') | (Some('"'), '"') => quote = None,
+ (Some('"'), '\\') if matches!(chars.peek(), Some('"' | '\\')) => {
+ word.extend(chars.next());
+ }
+ (Some(_), _) => word.push(c),
+ (None, '\'' | '"') => {
+ quote = Some(c);
+ in_word = true;
+ }
+ (None, '\\')
+ if chars.peek().is_some_and(|next| {
+ next.is_whitespace() || is_operator(*next) || matches!(next, '\'' | '"' | '\\')
+ }) =>
+ {
+ word.extend(chars.next());
+ in_word = true;
+ }
+ (None, c) if c.is_whitespace() || is_operator(c) => {
+ if in_word {
+ words.push(std::mem::take(&mut word));
+ in_word = false;
+ }
+ }
+ (None, c) => {
+ word.push(c);
+ in_word = true;
+ }
+ }
+ }
+ if in_word {
+ words.push(word);
+ }
+ words
+}
+
+/// Path-like values carried by one shell word: the word itself unless it is
+/// a flag, plus the value of a `--flag=value` or `NAME=value` word.
+fn shell_arguments(word: &str) -> impl Iterator<Item = &str> {
+ let whole = (!word.starts_with('-')).then_some(word);
+ let value = word.split_once('=').map(|(_, value)| value);
+ whole
+ .into_iter()
+ .chain(value)
+ .filter(|argument| !argument.trim().is_empty())
+}
+
#[derive(Clone)]
struct Normalized {
path: String,
@@ -848,6 +1003,7 @@ fn compile(
let flavor = flavor_of(&expanded);
let path = normalize_segments(&expanded).ok_or(())?;
Ok(CompiledPattern {
+ literal_prefix: literal_prefix(&path).into(),
directory_base: path.strip_suffix("/**").map(|base| {
if base.is_empty() {
"/".into()
@@ -984,6 +1140,51 @@ fn glob_match(
}
previous[pattern.len()]
}
+/// The whole leading segments of a normalized pattern that contain no glob.
+fn literal_prefix(path: &str) -> &str {
+ let Some(glob) = path.find(['*', '?']) else {
+ return path;
+ };
+ let Some(slash) = path[..glob].rfind('/') else {
+ return "";
+ };
+ let head = &path[..=slash];
+ // Keep the root separator of `/`, `C:/`; drop it everywhere else.
+ match head.strip_suffix('/') {
+ Some(trimmed) if !trimmed.is_empty() && !trimmed.ends_with(':') => trimmed,
+ _ => head,
+ }
+}
+fn starts_with_chars(path: &str, prefix: &str, insensitive: bool) -> bool {
+ let mut path = path.chars();
+ prefix.chars().all(|expected| {
+ path.next()
+ .is_some_and(|c| char_equal(expected, c, insensitive))
+ })
+}
+/// Whether a shell glob can expand to `prefix` itself or to a path below it.
+/// Only the glob's first segments, as many as `prefix` has, are compared:
+/// `docs/*/x.md` reaches `docs/adr`, while `*.md` in the parent never can.
+fn glob_reaches(glob: &str, prefix: &str, insensitive: bool) -> bool {
+ let prefix = prefix.trim_end_matches('/');
+ let depth = prefix.split('/').filter(|part| !part.is_empty()).count();
+ if depth == 0 {
+ return true;
+ }
+ let mut seen = 0;
+ let mut offset = 0;
+ for part in glob.split('/') {
+ offset += part.len();
+ if !part.is_empty() {
+ seen += 1;
+ if seen == depth {
+ return glob_match(&glob[..offset], prefix, None, insensitive);
+ }
+ }
+ offset += 1;
+ }
+ false
+}
fn equal_chars(left: &[char], right: &[char], insensitive: bool) -> bool {
left.len() == right.len()
&& left
@@ -1530,6 +1731,199 @@ mod tests {
PolicyState::Invalid
);
}
+ fn shell_policy() -> CapturePolicy {
+ CapturePolicy::resolve(
+ CaptureSource::Parsed(&CaptureConfig {
+ ignore_paths: vec!["docs/adr/**".into(), "~/notes/**".into()],
+ }),
+ "/repo",
+ Some("/home/me"),
+ )
+ }
+ fn bash(command: &str) -> Value {
+ json!({"tool_name": "Bash", "tool_input": {"command": command}, "tool_use_id": "call-1"})
+ }
+
+ #[test]
+ fn shell_commands_reading_ignored_paths_are_dropped() {
+ let policy = shell_policy();
+ for (command, cwd) in [
+ ("cat docs/adr/0001.md", "/repo"),
+ ("cat ./docs/adr/0001.md", "/repo"),
+ ("cat /repo/docs/adr/0001.md", "/repo"),
+ ("cat ../docs/adr/0001.md", "/repo/sub"),
+ ("cat docs/adr/*.md", "/repo"),
+ ("cat docs/*/0001.md", "/repo"),
+ ("ls docs/*", "/repo"),
+ ("cat 'docs/adr/a b.md'", "/repo"),
+ ("cat \"docs/adr/a b.md\"", "/repo"),
+ (r"cat docs/adr/a\ b.md", "/repo"),
+ ("head -n5 docs/adr/x.md | wc -l", "/repo"),
+ ("grep --file=docs/adr/x.md pattern", "/repo"),
+ ("FILE=docs/adr/x.md sh -c 'cat $FILE'", "/repo"),
+ ("cd /tmp && cat /repo/docs/adr/x.md;echo", "/repo"),
+ ("wc -l <docs/adr/x.md", "/repo"),
+ ("cat ~/notes/today.md", "/repo"),
+ ("cat docs/adr", "/repo"),
+ ] {
+ let decision = policy.inspect(AgentKind::ClaudeCode, &bash(command), cwd);
+ assert_eq!(
+ decision.protocol().disposition(),
+ CaptureDisposition::Drop,
+ "command: {command}"
+ );
+ assert_eq!(decision.protocol().tool_family(), ToolFamily::NonFile);
+ }
+ }
+
+ #[test]
+ fn shell_commands_not_touching_ignored_paths_are_kept() {
+ let policy = shell_policy();
+ for command in [
+ "cat src/main.rs",
+ "cat docs/adrx.md",
+ "cat docs/adr-notes/x.md",
+ "ls docs",
+ "cat *.md",
+ "git add .",
+ "cargo test -p ai-memory-hooks",
+ "echo 'docs/adr is ignored'x",
+ "cat notes/today.md",
+ "",
+ ] {
+ let decision = policy.inspect(AgentKind::ClaudeCode, &bash(command), "/repo");
+ assert_eq!(
+ decision.protocol().disposition(),
+ CaptureDisposition::Keep,
+ "command: {command}"
+ );
+ // Unchanged protocol fields keep old and new servers agreeing.
+ assert_eq!(decision.protocol().path_count(), 0);
+ assert_eq!(
+ decision.protocol().extraction_state(),
+ ExtractionState::Extracted
+ );
+ }
+ }
+
+ #[test]
+ fn shell_tool_shapes_of_every_adapter_honor_exclusions() {
+ let policy = shell_policy();
+ for (agent, raw) in [
+ (AgentKind::ClaudeCode, bash("cat docs/adr/x.md")),
+ (
+ AgentKind::Codex,
+ json!({"tool_name": "shell", "tool_input": {"command": ["bash", "-lc", "cat docs/adr/x.md"]}}),
+ ),
+ (
+ AgentKind::Codex,
+ json!({"tool_name": "exec_command", "tool_input": {"cmd": "cat docs/adr/x.md"}}),
+ ),
+ (
+ AgentKind::KiroCli,
+ json!({"tool_name": "execute_bash", "tool_input": {"command": "cat docs/adr/x.md"}}),
+ ),
+ (
+ AgentKind::Hermes,
+ json!({"tool_name": "terminal", "tool_input": {"command": "cat docs/adr/x.md"}}),
+ ),
+ (
+ AgentKind::OpenCode,
+ json!({"tool": "bash", "args": {"command": "cat docs/adr/x.md"}}),
+ ),
+ ] {
+ let decision = policy.inspect(agent, &raw, "/repo");
+ if decision.protocol().tool_family() == ToolFamily::NonFile {
+ assert_eq!(
+ decision.protocol().disposition(),
+ CaptureDisposition::Drop,
+ "raw: {raw}"
+ );
+ } else {
+ // `exec_command` is not a recognized shell tool name; it keeps
+ // today's unknown-tool behavior rather than guessing.
+ assert_eq!(decision.protocol().tool_family(), ToolFamily::Unknown);
+ }
+ }
+ }
+
+ #[test]
+ fn shell_matching_needs_an_active_policy_and_fails_closed_on_budget() {
+ let raw = bash("cat docs/adr/x.md");
+ let inactive = CapturePolicy::resolve(CaptureSource::Absent, "/repo", None);
+ assert_eq!(
+ inactive
+ .inspect(AgentKind::ClaudeCode, &raw, "/repo")
+ .protocol()
+ .disposition(),
+ CaptureDisposition::Keep
+ );
+ let invalid = CapturePolicy::resolve(CaptureSource::Invalid, "/repo", None);
+ assert_eq!(
+ invalid
+ .inspect(AgentKind::ClaudeCode, &raw, "/repo")
+ .protocol()
+ .disposition(),
+ CaptureDisposition::Keep
+ );
+ // Without a home directory `~/` is left literal and cannot match.
+ let homeless = CapturePolicy::resolve(
+ CaptureSource::Parsed(&CaptureConfig {
+ ignore_paths: vec!["docs/adr/**".into()],
+ }),
+ "/repo",
+ None,
+ );
+ assert_eq!(
+ homeless
+ .inspect(AgentKind::ClaudeCode, &bash("cat ~/notes/x.md"), "/repo")
+ .protocol()
+ .disposition(),
+ CaptureDisposition::Keep
+ );
+ let costly = CapturePolicy::resolve(
+ CaptureSource::Parsed(&CaptureConfig {
+ ignore_paths: vec!["docs/**/?".repeat(100)],
+ }),
+ "/repo",
+ None,
+ );
+ let long = format!("cat {}", vec!["docs/x".repeat(400); 8].join(" "));
+ assert_eq!(
+ costly
+ .inspect(AgentKind::ClaudeCode, &bash(&long), "/repo")
+ .protocol()
+ .disposition(),
+ CaptureDisposition::Drop
+ );
+ }
+
+ #[test]
+ fn shell_words_follow_posix_quoting_and_keep_windows_separators() {
+ assert_eq!(
+ shell_words(r#"a 'b c' "d \"e\"" f\ g h|i>j;k&&(l) C:\docs\adr\x.md"#),
+ [
+ "a",
+ "b c",
+ "d \"e\"",
+ "f g",
+ "h",
+ "i",
+ "j",
+ "k",
+ "l",
+ r"C:\docs\adr\x.md"
+ ]
+ );
+ assert_eq!(literal_prefix("/repo/docs/adr/**"), "/repo/docs/adr");
+ assert_eq!(literal_prefix("/**"), "/");
+ assert_eq!(literal_prefix("C:/*.md"), "C:/");
+ assert_eq!(literal_prefix("/repo/secret.txt"), "/repo/secret.txt");
+ assert!(glob_reaches("/repo/docs/*/x.md", "/repo/docs/adr", false));
+ assert!(!glob_reaches("/repo/*.md", "/repo/docs/adr", false));
+ assert!(glob_reaches("C:/Docs/*", "C:/docs/adr", true));
+ }
+
#[test]
fn metadata_rewrite_strips_all_sentinels_and_has_exact_protocol_keys() {
let policy = CapturePolicy::resolve(
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index f8474527..9d5f8dde 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -12233,6 +12233,34 @@ mod tests {
assert_eq!(inspect_capture_envelope(env).unwrap().raw, raw);
}
+ #[test]
+ fn capture_protocol_shell_decisions_survive_server_reinspection() {
+ // The server never sees the client's patterns, so its direct
+ // re-inspection of a shell command must accept the client's Keep
+ // unchanged and treat the client's Drop as terminal.
+ let query = || HookQuery {
+ event: "post-tool-use".into(),
+ agent: Some("claude-code".into()),
+ ..Default::default()
+ };
+ let kept = serde_json::json!({
+ "session_id": "shell-keep", "tool_name": "Bash",
+ "tool_input": { "command": "cat src/main.rs *.md" },
+ "_ai_memory_capture": capture_protocol("keep", "active", "non-file", 0, "extracted"),
+ });
+ let env = HookEnvelope::from_query_and_body(query(), kept.clone());
+ assert_eq!(inspect_capture_envelope(env).unwrap().raw, kept);
+
+ let dropped = serde_json::json!({
+ "session_id": "shell-drop", "tool_name": "Bash",
+ "tool_input": { "command": "cat docs/adr/0001.md" },
+ "tool_response": "SENTINEL_SECRET",
+ "_ai_memory_capture": capture_protocol("drop", "active", "non-file", 0, "extracted"),
+ });
+ let env = HookEnvelope::from_query_and_body(query(), dropped);
+ assert!(inspect_capture_envelope(env).is_none());
+ }
+
#[test]
fn capture_protocol_invalid_file_keep_becomes_canonical_metadata_only() {
let env = HookEnvelope::from_query_and_body(
diff --git a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json b/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
index 780b8320..c6d822ce 100644
--- a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
+++ b/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
@@ -20,7 +20,8 @@
{"agent":"kiro-cli","payload":{"tool_name":"fs_write","tool_input":{"command":"create","path":"secret/a"}},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":1},
{"agent":"kiro-cli","payload":{"tool_name":"read","tool_input":{"operations":[{"mode":"Line","path":"public"},{"mode":"Line","path":"secret/a"}]}},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":2},
{"agent":"kiro-cli","payload":{"tool_name":"read","tool_input":{"operations":[]}},"disposition":"metadata-only","tool_family":"file","extraction_state":"missing-or-malformed","path_count":0},
- {"agent":"kiro-cli","payload":{"tool_name":"execute_bash","tool_input":{"command":"cat secret/a"}},"disposition":"keep","tool_family":"non-file","extraction_state":"extracted","path_count":0},
+ {"agent":"kiro-cli","payload":{"tool_name":"execute_bash","tool_input":{"command":"cat secret/a"}},"disposition":"drop","tool_family":"non-file","extraction_state":"extracted","path_count":0},
+ {"agent":"kiro-cli","payload":{"tool_name":"execute_bash","tool_input":{"command":"cat public/a"}},"disposition":"keep","tool_family":"non-file","extraction_state":"extracted","path_count":0},
{"agent":"grok","payload":{"toolName":"Edit","toolInput":{"filePath":"secret/a"},"callID":"safe-1"},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":1},
{"agent":"zero","payload":{"toolName":"Edit","input":{"path":"secret/a"}},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":1},
{"agent":"antigravity-cli","payload":{"toolCall":{"name":"Edit","args":{"path":"secret/a"}}},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":1},
@@ -32,7 +33,7 @@
{"agent":"codex","payload":{"tool_name":"Edit","tool_input":{"path":" "}},"disposition":"metadata-only","tool_family":"file","extraction_state":"missing-or-malformed","path_count":0},
{"agent":"codex","payload":{"tool_name":"MultiEdit","tool_input":{"edits":[{"path":"public"},{"path":"secret/a"}]}},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":2},
{"agent":"codex","payload":{"tool_name":"Search","tool_input":{}},"disposition":"drop","tool_family":"search-list","extraction_state":"not-applicable","path_count":0},
- {"agent":"codex","payload":{"tool_name":"Bash","tool_input":{"command":"secret/a"}},"disposition":"keep","tool_family":"non-file","extraction_state":"extracted","path_count":0},
+ {"agent":"codex","payload":{"tool_name":"Bash","tool_input":{"command":"secret/a"}},"disposition":"drop","tool_family":"non-file","extraction_state":"extracted","path_count":0},
{"agent":"codex","payload":{"tool_name":"FutureTool","tool_input":{"path":"secret/a"}},"disposition":"keep","tool_family":"unknown","extraction_state":"extracted","path_count":0},
{"agent":"codex","payload":{"tool_name":"Edit","tool_input":{"nested":{"path":"secret/a"}}},"disposition":"metadata-only","tool_family":"file","extraction_state":"missing-or-malformed","path_count":0}
],
diff --git a/docs/marker-file.md b/docs/marker-file.md
index b9fd0543..0ab112f4 100644
--- a/docs/marker-file.md
+++ b/docs/marker-file.md
@@ -194,7 +194,8 @@ enforcement point, so allowlist mode does not gate them.
## Capture exclusions
Use the exact per-repository shape `[capture]` plus `ignore_paths = [...]`
-below to keep recognized file-tool activity under matching paths out of capture:
+below to keep recognized file-tool and shell-tool activity under matching paths
+out of capture:
```toml
[capture]
@@ -231,15 +232,34 @@ logs, or server storage. With an active policy, recognized search/list tools are
dropped conservatively; missing or malformed recognized file candidates, an
unsupported recognized schema, or an invalid policy become **metadata-only**.
That form contains only bounded routing/tool/decision metadata, never paths,
-patterns, arguments, output, errors, titles, or nested payload. Known non-file
-and unknown tools retain current behavior. Excluding content before transport
+patterns, arguments, output, errors, titles, or nested payload. Unknown tools
+retain current behavior.
+
+Recognized shell tools (`Bash`, `shell`, `execute_bash`, `terminal`, …) have no
+path field, so the command line is split into words lexically, the way a POSIX
+shell quotes and separates them, without expanding or running anything. Each
+argument that is not a flag, plus the value of a `--flag=value` or
+`NAME=value` word, is resolved from the event's `cwd` like a file-tool path. If
+one matches a pattern, the whole event is **dropped**, exactly like a matching
+file read. An argument containing `*` or `?` also matches when its glob can
+reach a pattern's directory: `cat docs/*/0001.md` is dropped under
+`docs/adr/**`, `cat *.md` at the repository root is not. A command that exceeds
+the match budget is dropped. Variables, command substitution, `cd` state, and
+commands that name no path at all (`rg TODO`, `git diff`) are not followed, so
+their output is still captured. Excluding content before transport
matters because it cannot then reach observations/FTS, session pages, handoffs,
reviewer requests, proposals, or logs.
This is a lexical capture boundary, **not complete DLP**. It does not resolve
-symlinks, junctions, bind mounts, or Windows 8.3 aliases. Shell commands and
-free-form patches are not parsed; prompts, assistant text, notifications, and
-quoted content are not path-attributable. Add each relevant visible alias
+symlinks, junctions, bind mounts, or Windows 8.3 aliases. Shell commands are
+matched only lexically (above), and free-form patches are not parsed; prompts,
+assistant text, notifications, and quoted content are not path-attributable.
+A copy of a file's content under another path is not linked back to it either:
+Claude Code saves a large tool result to
+`~/.claude/projects/<project>/<session>/tool-results/<id>.txt` and reads it back
+with its file tool, and that read no longer matches the original path. Add
+`"~/.claude/projects/**/tool-results/**"` to `ignore_paths` to exclude those
+re-reads too (for every file, not only the ignored ones). Add each relevant visible alias
explicitly, and do not rely on this feature to detect every way private content
can be mentioned.
@@ -247,7 +267,9 @@ can be mentioned.
Capture policy v1 is enforced by native `ai-memory hook` commands (including
native POSIX/Windows hook commands) and generated OpenCode, OMP, Pi, and
-OpenClaw integrations. Local installers default to native commands where that
+OpenClaw integrations. Shell-command matching is enforced by the native
+`ai-memory hook` commands only; the generated integrations still keep shell
+events. Local installers default to native commands where that
path is supported. Legacy `.sh`/`.ps1` hooks and remote-only/Docker script
bundles do **not** enforce it. Reinstall hooks or refresh/reinstall generated
plugins after upgrading; existing hooks/plugins keep their prior behavior.
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index ac3b7024..e565ee68 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -39,7 +39,7 @@ boundary not yet built.
| 10 | Destructive-op live-process refusal + confirm flags (invariant #9) | `ai-memory-cli/src/commands/process_guard.rs` `sibling_processes` + confirm flags in `reset`/`restore`/`reindex`/`uninstall --purge-data`/`purge_project` | `admin_purge.rs` confirm→400; `removal.rs` — injected live-sibling makes each destructive command bail before touching the data dir | STRONG |
| 10b | Session purge is scope+owner-bound (no cross-session/project over-delete) | `ai-memory-store/src/ops.rs` `purge_session` — selection scoped to `(workspace_id, project_id)` and keyed on this session's own `summary_page_id` **or** `path='sessions/<sid>.md'` + `json_extract(frontmatter_json,'$.session_id')=<sid>` (frontmatter owner, not the recursive latest-chain); `in_scope==0 → NotFound` fail-closed; whole op in one transaction | `ops.rs` `purge_session_leaves_a_sibling_session_in_the_same_project_intact`, `…refuses_a_session_from_another_project_and_deletes_nothing`, `…refuses_a_session_from_another_workspace`, `…does_not_delete_an_identically_pathed_page_in_another_project`, `…removes_older_summary_versions_without_deleting_prior_manual_page` (#862) | 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 | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded` | STRONG |
-| 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn) | `capture_policy.rs` per-agent `…honors_exclusions` tests | 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`) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_commands_reading_ignored_paths_are_dropped` (+ `…not_touching…are_kept` control); `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool` | STRONG |
| 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 |
| 12 | Network/auth posture | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer` | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401 | STRONG |
| 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), and never falls back to a link it set aside | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout |
diff --git a/docs/usage.md b/docs/usage.md
index 71e5e10f..379b9885 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -10,8 +10,9 @@ To keep recognized file-tool events under private paths out of ai-memory before
they are spooled or sent, configure `[capture] ignore_paths` in the nearest
`.ai-memory.toml`. The canonical grammar, limitations, support matrix, refresh
requirements, and safe local `--check-capture` command are in
-[the marker-file reference](marker-file.md#capture-exclusions). This is not a
-general prompt/output DLP filter.
+[the marker-file reference](marker-file.md#capture-exclusions). Shell commands
+are matched by their path arguments too (`cat docs/adr/*.md`), lexically. This
+is not a general prompt/output DLP filter.
## Cross-agent handoff
@@ -522,7 +523,9 @@ pull requests). Three facts frame how such a record and ai-memory interact:
```
The repo owns that record; a compiled copy goes stale the moment the
- repo moves. Details and bounds in [`docs/marker-file.md`](marker-file.md).
+ repo moves. Details and bounds in [`docs/marker-file.md`](marker-file.md),
+ including what shell matching cannot see and how to exclude large tool
+ results an agent saves and re-reads from another path.
3. **Wiki pages marked `pinned: true` are immutable to automation.**
Retention decay and curation skip them, multi-page consolidation