Skip to content

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

Rust

fix(hooks): keep argv paths whole and strip shell calls under an invalid marker

Peterson Salme929aa88e5bdf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ffc3a8c5..e118c746 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -70,6 +70,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`dir/**` as covering `dir` itself when `dir` holds a glob (`docs/a?r/**`), as
the generated plugins already did. Refresh or reinstall generated plugins to
pick it up. (#948)
+- Shell-command `ignore_paths` matching no longer joins an argument vector
+ before splitting it, which broke a path with spaces (`["cat", "private
+ notes/x.md"]`) apart and let one element's stray quote hide the elements
+ after it; each element now counts whole and is split on its own. An invalid
+ `.ai-memory.toml` now makes a shell command metadata-only, like a file tool,
+ instead of keeping its command and output. Applies to the native hook and
+ the generated plugins; the server accepts the new metadata-only shell form,
+ so upgrade it together with them (an older server drops such an event).
+ (#PR)
- 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/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rs
index 719bc1b2..54ba9ee0 100644
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@ -273,15 +273,17 @@ function captureCharEq(a: string, b: string, insensitive: boolean): boolean { re
function captureLiteralPrefix(path: string): string { const glob = path.search(/[*?]/); if (glob < 0) return path; const slash = path.lastIndexOf("/", glob); if (slash < 0) return ""; const head = path.slice(0, slash + 1); const trimmed = head.slice(0, -1); return trimmed && !trimmed.endsWith(":") ? trimmed : head; }
function captureStartsWith(path: string, prefix: string, insensitive: boolean): boolean { const p = path[Symbol.iterator](); for (const x of prefix) { const c = p.next(); if (c.done || !captureCharEq(x, c.value, insensitive)) return false; } return true; }
function captureGlobReaches(glob: string, prefix: string, insensitive: boolean, budget: { work: number }): boolean | undefined { const target = prefix.replace(/\/+$/, ""); const depth = target.split("/").filter(Boolean).length; if (!depth) return true; let seen = 0; let offset = 0; for (const part of glob.split("/")) { offset += part.length; if (part && ++seen === depth) return captureGlob(glob.slice(0, offset), target, insensitive, budget); offset++; } return false; }
-function captureShellCommand(args: Record<string, unknown> | undefined): string | undefined { if (!args || typeof args !== "object" || Array.isArray(args)) return undefined; const value = "command" in args ? args.command : args.cmd; if (typeof value === "string") return value; if (Array.isArray(value) && value.every((x) => typeof x === "string")) return value.join(" "); return undefined; }
+// An argv element is one word as given and is also tokenized on its own
+// (`bash -lc "<script>"`); joining elements would re-split paths with spaces.
+function captureShellCommand(args: Record<string, unknown> | undefined): string[] | undefined { if (!args || typeof args !== "object" || Array.isArray(args)) return undefined; const value = "command" in args ? args.command : args.cmd; if (typeof value === "string") return captureShellWords(value); if (Array.isArray(value) && value.every((x) => typeof x === "string")) return (value as string[]).flatMap((item) => { const tokens = captureShellWords(item); return tokens.length === 1 && tokens[0] === item ? tokens : [item, ...tokens]; }); return undefined; }
function captureShellWords(command: string): string[] { const special = (c: string) => /\s/.test(c) || "|&;<>()".includes(c); const chars = [...command]; const words: string[] = []; let word = ""; let inWord = false; let quote = ""; for (let i = 0; i < chars.length; i++) { const c = chars[i]; const next = chars[i + 1]; if (quote) { if (c === quote) quote = ""; else if (quote === '"' && c === "\\" && (next === '"' || next === "\\")) { word += next; i++; } else word += c; } else if (c === "'" || c === '"') { quote = c; inWord = true; } else if (c === "\\" && next !== undefined && (special(next) || next === "'" || next === '"' || next === "\\")) { word += next; i++; inWord = true; } else if (special(c)) { if (inWord) words.push(word); word = ""; inWord = false; } else { word += c; inWord = true; } } if (inWord) words.push(word); return words; }
function captureShellArguments(word: string): string[] { const out = word.startsWith("-") ? [] : [word]; const eq = word.indexOf("="); if (eq >= 0) out.push(word.slice(eq + 1)); return out.filter((argument) => argument.trim() !== ""); }
// Lexical only, like the native hook: nothing is expanded or executed, so
// variables, command substitution, and `cd` state are not followed. A tool's
// own `workdir` replaces the event cwd for relative arguments.
-function captureMatchCommand(command: string, config: CaptureConfig, workdir?: string): boolean | undefined { const budget = { work: 0 }; const home = homedir(); const base = workdir === undefined ? config.base : /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(workdir) ? workdir : config.base && captureJoin(config.base, workdir); for (const word of captureShellWords(command)) for (const argument of captureShellArguments(word)) { const expanded = argument.startsWith("~/") ? captureJoin(home, argument.slice(2)) : argument; if ([...expanded].length > CAPTURE_MAX_PATH_CHARS) continue; const absolute = /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(expanded); if (!absolute && !base) continue; const candidate = captureNormalize(absolute ? expanded : captureJoin(base, expanded)); if (!candidate) continue; const glob = /[*?]/.test(candidate.path); for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; const under = captureStartsWith(candidate.path, pattern.prefix, pattern.windows); if (!under && !glob) continue; if (under) { const directory = pattern.directory ? captureGlob(pattern.directory, candidate.path, pattern.windows, budget) : false; if (directory !== false) return directory; const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match !== false) return match; } if (glob) { const reaches = captureGlobReaches(candidate.path, pattern.prefix, pattern.windows, budget); if (reaches !== false) return reaches; } } } return false; }
-function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string; workdir?: string } { const name = typeof payload.tool === "string" ? payload.tool.toLowerCase() : ""; const args = payload.args as Record<string, unknown> | undefined; const call = ["tool_use_id","toolUseId","tool_call_id","toolCallId","call_id","callId","callID"].map((k) => payload[k]).find((v): v is string => typeof v === "string" && /^[A-Za-z0-9_.-]{1,128}$/.test(v)); if (["search","grep","glob","find","list","ls","list_files","read_dir"].includes(name)) return { family: "search-list", extraction: "not-applicable", callID: call }; if (["bash","shell","shell_command","exec","execute","run_command","web_search","terminal","execute_bash","execute_cmd"].includes(name)) return { family: "non-file", extraction: "extracted", callID: call, command: captureShellCommand(args), workdir: typeof args?.workdir === "string" && args.workdir.trim() ? args.workdir : undefined }; if (!["read","write","edit","apply_patch","notebookedit","notebook_edit","create_file","delete_file","rename_file","move_file","multi_edit","multiedit","replace","replace_all"].includes(name)) return { family: "unknown", extraction: "extracted", callID: call }; const direct = (o: any): string[] | undefined => { if (!o || typeof o !== "object") return undefined; const r: string[] = []; for (const k of ["file_path","filePath","path","absolute_path","AbsolutePath","notebook_path"]) if (k in o) { if (typeof o[k] !== "string") return undefined; r.push(o[k]); } if ("paths" in o) { if (!Array.isArray(o.paths) || o.paths.some((x: unknown) => typeof x !== "string")) return undefined; r.push(...o.paths); } return r.length && r.length <= CAPTURE_MAX_CANDIDATES ? r : undefined; }; let paths = direct(args); if (["multi_edit","multiedit","replace_all"].includes(name)) { const entries = args?.edits ?? args?.replacements; if (!Array.isArray(entries) || !entries.length || entries.length > CAPTURE_MAX_CANDIDATES) paths = undefined; else { paths = paths ?? []; for (const entry of entries) { const more = direct(entry); if (!more || paths.length + more.length > CAPTURE_MAX_CANDIDATES) { paths = undefined; break; } paths.push(...more); } } } if (!paths || paths.some((p) => !p.trim() || [...p].length > CAPTURE_MAX_PATH_CHARS)) return { family: "file", extraction: "missing-or-malformed", callID: call }; return { family: "file", paths, extraction: "extracted", callID: call }; }
-function capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === "allowlist" && !markerPresent) return { disposition: "drop", payload }; const config = captureConfig(cwd); const tool = captureTool(payload); let disposition: CaptureDisposition = "keep"; if (config.state === "invalid" && tool.family === "file") disposition = "metadata-only"; else if (config.state === "active" && tool.family === "search-list") disposition = "drop"; else if (config.state === "active" && tool.family === "file") { if (!tool.paths) disposition = "metadata-only"; else { const candidates = tool.paths.map((p) => captureNormalize(/^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(p) ? p : captureJoin(config.base, p))); if (candidates.some((p) => !p)) disposition = "metadata-only"; else { const budget = { work: 0 }; captureMatch: for (const candidate of candidates as { path: string; windows: boolean }[]) for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; if (pattern.directory && captureGlob(pattern.directory, candidate.path, pattern.windows, budget)) { disposition = "drop"; break captureMatch; } const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match === undefined) { disposition = "metadata-only"; break; } if (match) { disposition = "drop"; break captureMatch; } } } } } else if (config.state === "active" && tool.family === "non-file" && tool.command !== undefined && captureMatchCommand(tool.command, config, tool.workdir) !== false) disposition = "drop"; if (config.state === "inactive") return { disposition, payload }; const protocol: CaptureProtocol = { version: CAPTURE_POLICY_V1, disposition, policy_state: config.state, tool_family: tool.family, path_count: tool.paths?.length ?? 0, extraction_state: tool.extraction }; if (disposition === "metadata-only") { const session = payload.sessionID ?? payload.sessionId ?? payload.session_id; const routing = typeof payload.cwd === "string" ? payload.cwd : cwd; return { disposition, protocol, payload: { ...(typeof session === "string" ? { session_id: session } : {}), ...(typeof routing === "string" ? { cwd: routing } : {}), tool_family: tool.family, tool_name: tool.family, ...(tool.callID ? { tool_call_id: tool.callID } : {}), _ai_memory_capture: protocol } }; } if (disposition === "keep") return { disposition, protocol, payload: { ...payload, _ai_memory_capture: protocol } }; return { disposition, protocol, payload }; }
+function captureMatchCommand(words: string[], config: CaptureConfig, workdir?: string): boolean | undefined { const budget = { work: 0 }; const home = homedir(); const base = workdir === undefined ? config.base : /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(workdir) ? workdir : config.base && captureJoin(config.base, workdir); for (const word of words) for (const argument of captureShellArguments(word)) { const expanded = argument.startsWith("~/") ? captureJoin(home, argument.slice(2)) : argument; if ([...expanded].length > CAPTURE_MAX_PATH_CHARS) continue; const absolute = /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(expanded); if (!absolute && !base) continue; const candidate = captureNormalize(absolute ? expanded : captureJoin(base, expanded)); if (!candidate) continue; const glob = /[*?]/.test(candidate.path); for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; const under = captureStartsWith(candidate.path, pattern.prefix, pattern.windows); if (!under && !glob) continue; if (under) { const directory = pattern.directory ? captureGlob(pattern.directory, candidate.path, pattern.windows, budget) : false; if (directory !== false) return directory; const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match !== false) return match; } if (glob) { const reaches = captureGlobReaches(candidate.path, pattern.prefix, pattern.windows, budget); if (reaches !== false) return reaches; } } } return false; }
+function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string[]; workdir?: string } { const name = typeof payload.tool === "string" ? payload.tool.toLowerCase() : ""; const args = payload.args as Record<string, unknown> | undefined; const call = ["tool_use_id","toolUseId","tool_call_id","toolCallId","call_id","callId","callID"].map((k) => payload[k]).find((v): v is string => typeof v === "string" && /^[A-Za-z0-9_.-]{1,128}$/.test(v)); if (["search","grep","glob","find","list","ls","list_files","read_dir"].includes(name)) return { family: "search-list", extraction: "not-applicable", callID: call }; if (["bash","shell","shell_command","exec","execute","run_command","web_search","terminal","execute_bash","execute_cmd"].includes(name)) return { family: "non-file", extraction: "extracted", callID: call, command: captureShellCommand(args), workdir: typeof args?.workdir === "string" && args.workdir.trim() ? args.workdir : undefined }; if (!["read","write","edit","apply_patch","notebookedit","notebook_edit","create_file","delete_file","rename_file","move_file","multi_edit","multiedit","replace","replace_all"].includes(name)) return { family: "unknown", extraction: "extracted", callID: call }; const direct = (o: any): string[] | undefined => { if (!o || typeof o !== "object") return undefined; const r: string[] = []; for (const k of ["file_path","filePath","path","absolute_path","AbsolutePath","notebook_path"]) if (k in o) { if (typeof o[k] !== "string") return undefined; r.push(o[k]); } if ("paths" in o) { if (!Array.isArray(o.paths) || o.paths.some((x: unknown) => typeof x !== "string")) return undefined; r.push(...o.paths); } return r.length && r.length <= CAPTURE_MAX_CANDIDATES ? r : undefined; }; let paths = direct(args); if (["multi_edit","multiedit","replace_all"].includes(name)) { const entries = args?.edits ?? args?.replacements; if (!Array.isArray(entries) || !entries.length || entries.length > CAPTURE_MAX_CANDIDATES) paths = undefined; else { paths = paths ?? []; for (const entry of entries) { const more = direct(entry); if (!more || paths.length + more.length > CAPTURE_MAX_CANDIDATES) { paths = undefined; break; } paths.push(...more); } } } if (!paths || paths.some((p) => !p.trim() || [...p].length > CAPTURE_MAX_PATH_CHARS)) return { family: "file", extraction: "missing-or-malformed", callID: call }; return { family: "file", paths, extraction: "extracted", callID: call }; }
+function capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === "allowlist" && !markerPresent) return { disposition: "drop", payload }; const config = captureConfig(cwd); const tool = captureTool(payload); let disposition: CaptureDisposition = "keep"; if (config.state === "invalid" && (tool.family === "file" || tool.command !== undefined)) disposition = "metadata-only"; else if (config.state === "active" && tool.family === "search-list") disposition = "drop"; else if (config.state === "active" && tool.family === "file") { if (!tool.paths) disposition = "metadata-only"; else { const candidates = tool.paths.map((p) => captureNormalize(/^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(p) ? p : captureJoin(config.base, p))); if (candidates.some((p) => !p)) disposition = "metadata-only"; else { const budget = { work: 0 }; captureMatch: for (const candidate of candidates as { path: string; windows: boolean }[]) for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; if (pattern.directory && captureGlob(pattern.directory, candidate.path, pattern.windows, budget)) { disposition = "drop"; break captureMatch; } const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match === undefined) { disposition = "metadata-only"; break; } if (match) { disposition = "drop"; break captureMatch; } } } } } else if (config.state === "active" && tool.family === "non-file" && tool.command !== undefined && captureMatchCommand(tool.command, config, tool.workdir) !== false) disposition = "drop"; if (config.state === "inactive") return { disposition, payload }; const protocol: CaptureProtocol = { version: CAPTURE_POLICY_V1, disposition, policy_state: config.state, tool_family: tool.family, path_count: tool.paths?.length ?? 0, extraction_state: tool.extraction }; if (disposition === "metadata-only") { const session = payload.sessionID ?? payload.sessionId ?? payload.session_id; const routing = typeof payload.cwd === "string" ? payload.cwd : cwd; return { disposition, protocol, payload: { ...(typeof session === "string" ? { session_id: session } : {}), ...(typeof routing === "string" ? { cwd: routing } : {}), tool_family: tool.family, tool_name: tool.family, ...(tool.callID ? { tool_call_id: tool.callID } : {}), _ai_memory_capture: protocol } }; } if (disposition === "keep") return { disposition, protocol, payload: { ...payload, _ai_memory_capture: protocol } }; return { disposition, protocol, payload }; }
"##;
TEMPLATE.replace("__AI_MEMORY_CAPTURE_MODE__", capture_mode)
}
@@ -2142,7 +2144,10 @@ for (const vector of fixture.shell.vectors) {{
}}
const bash = (command: string) => ({{ tool: "bash", args: {{ command }} }});
check(capturePolicy(bash("cat docs/adr/x.md"), "/no-marker").disposition === "keep", "shell-inactive-keep");
-expectDecision(bash("cat docs/adr/x.md"), marker('[capture'), "keep", "non-file", "extracted", 0, "shell-invalid-keep");
+const shellInvalid = capturePolicy({{ ...bash(`cat ${{privatePath}}`), output: privateBody }}, marker('[capture'));
+check(shellInvalid.disposition === "metadata-only" && shellInvalid.protocol?.policy_state === "invalid" && shellInvalid.protocol?.tool_family === "non-file", "shell-invalid-metadata-only");
+for (const forbidden of [privatePath, privateBody]) check(!JSON.stringify(shellInvalid.payload).includes(forbidden), "shell-invalid-redaction");
+expectDecision({{ tool: "web_search", args: {{ query: "docs/adr" }} }}, marker('[capture'), "keep", "non-file", "extracted", 0, "invalid-commandless-non-file-keep");
expectDecision(bash(`cat ${{Array(8).fill("docs/x".repeat(400)).join(" ")}}`), marker(`[capture]\nignore_paths = ["${{"docs/**/?".repeat(100)}}"]\n`), "drop", "non-file", "extracted", 0, "shell-budget-fails-closed");
const nestedRoot = join(markerRoot, "nested-repo");
const nestedCwd = join(nestedRoot, "subdir");
diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rs
index 5903f58d..7085e6e0 100644
--- a/crates/ai-memory-hooks/src/capture_policy.rs
+++ b/crates/ai-memory-hooks/src/capture_policy.rs
@@ -480,7 +480,11 @@ impl CapturePolicy {
let extracted = extract(agent, raw);
let (disposition, extraction) = match self.state {
PolicyState::Inactive => (CaptureDisposition::Keep, extracted.state),
- PolicyState::Invalid if extracted.family == ToolFamily::File => {
+ // A broken marker cannot prove a shell command's arguments miss
+ // every ignored path, so it fails closed like a file tool.
+ PolicyState::Invalid
+ if extracted.family == ToolFamily::File || extracted.command.is_some() =>
+ {
(CaptureDisposition::MetadataOnly, extracted.state)
}
PolicyState::Invalid => (CaptureDisposition::Keep, extracted.state),
@@ -516,14 +520,14 @@ impl CapturePolicy {
// 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| {
+ ToolFamily::NonFile => match extracted.command.as_deref().map(|words| {
let base = match extracted.workdir.as_deref() {
Some(dir) if is_absolute(dir) => dir.to_owned(),
// `join` would turn an unusable cwd into `/dir`.
Some(dir) if is_absolute(cwd) => join(cwd, dir),
_ => cwd.to_owned(),
};
- self.match_command(command, &base)
+ self.match_command(words, &base)
}) {
Some(Ok(true) | Err(())) => (CaptureDisposition::Drop, extracted.state),
Some(Ok(false)) | None => (CaptureDisposition::Keep, extracted.state),
@@ -580,10 +584,10 @@ impl CapturePolicy {
/// 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, ()> {
+ fn match_command(&self, words: &[String], cwd: &str) -> Result<bool, ()> {
let mut work = 0_usize;
- for word in shell_words(command) {
- for argument in shell_arguments(&word) {
+ for word in words {
+ 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(),
@@ -658,7 +662,8 @@ pub fn metadata_only_body(
struct Extracted {
family: ToolFamily,
paths: Option<Vec<String>>,
- command: Option<String>,
+ /// A shell tool's command, already split into words.
+ command: Option<Vec<String>>,
workdir: Option<String>,
call_id: Option<String>,
state: ExtractionState,
@@ -881,16 +886,29 @@ 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> {
+/// The words of a shell tool's command. An argument vector (Codex exec) is
+/// already split: each element is one word as given (`private notes/x.md`),
+/// and is also tokenized on its own so a `bash -lc "<script>"` element is read
+/// like any script. Joining the elements instead would re-split paths with
+/// spaces and let one element's stray quote swallow the rest.
+fn shell_command(args: &Value) -> Option<Vec<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(" ")),
+ Value::String(command) => Some(shell_words(command)),
+ Value::Array(items) => {
+ let items = items
+ .iter()
+ .map(Value::as_str)
+ .collect::<Option<Vec<_>>>()?;
+ let mut words = Vec::new();
+ for item in items {
+ let tokens = shell_words(item);
+ if tokens.len() != 1 || tokens[0] != item {
+ words.push(item.to_owned());
+ }
+ words.extend(tokens);
+ }
+ Some(words)
+ }
_ => None,
}
}
@@ -1846,7 +1864,7 @@ mod tests {
}
#[test]
- fn shell_matching_needs_an_active_policy_and_fails_closed_on_budget() {
+ fn shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget() {
let raw = bash("cat docs/adr/x.md");
let inactive = CapturePolicy::resolve(CaptureSource::Absent, "/repo", None);
assert_eq!(
@@ -1856,10 +1874,23 @@ mod tests {
.disposition(),
CaptureDisposition::Keep
);
+ // A broken marker strips a shell call like a file call, but a
+ // non-file tool with no command (`web_search`) keeps its body.
let invalid = CapturePolicy::resolve(CaptureSource::Invalid, "/repo", None);
+ let decision = invalid.inspect(AgentKind::ClaudeCode, &raw, "/repo");
+ assert_eq!(
+ decision.protocol().disposition(),
+ CaptureDisposition::MetadataOnly
+ );
+ let body = metadata_only_body(Some("s"), Some("/repo"), &decision).to_string();
+ assert!(!body.contains("docs/adr"), "{body}");
assert_eq!(
invalid
- .inspect(AgentKind::ClaudeCode, &raw, "/repo")
+ .inspect(
+ AgentKind::ClaudeCode,
+ &json!({"tool_name": "web_search", "tool_input": {"query": "docs/adr"}}),
+ "/repo"
+ )
.protocol()
.disposition(),
CaptureDisposition::Keep
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 9d5f8dde..b3860a4a 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -993,10 +993,13 @@ fn metadata_only_protocol_envelope(
Some(env)
}
+/// An invalid marker also strips shell commands, which it cannot prove miss
+/// every ignored path; an active policy decides them outright (keep/drop).
const fn metadata_protocol_is_legal(protocol: &CaptureProtocol) -> bool {
matches!(
(protocol.policy_state(), protocol.tool_family()),
(PolicyState::Active | PolicyState::Invalid, ToolFamily::File)
+ | (PolicyState::Invalid, ToolFamily::NonFile)
)
}
@@ -12261,6 +12264,71 @@ mod tests {
assert!(inspect_capture_envelope(env).is_none());
}
+ #[test]
+ fn capture_protocol_invalid_marker_shell_is_metadata_only() {
+ let query = || HookQuery {
+ event: "post-tool-use".into(),
+ agent: Some("claude-code".into()),
+ ..Default::default()
+ };
+ let stripped = |state: &str| {
+ serde_json::json!({
+ "session_id": "shell-invalid", "cwd": "/repo",
+ "tool_family": "non-file", "tool_name": "non-file",
+ "_ai_memory_capture": capture_protocol("metadata-only", state, "non-file", 0, "extracted"),
+ })
+ };
+ // What a current client sends under a broken marker is accepted.
+ let env = inspect_capture_envelope(HookEnvelope::from_query_and_body(
+ query(),
+ stripped("invalid"),
+ ))
+ .unwrap();
+ assert_eq!(
+ env.raw["_ai_memory_capture"]["disposition"],
+ "metadata-only"
+ );
+ assert_eq!(env.raw["tool_family"], "non-file");
+
+ // An active policy decides a shell call outright, so a metadata-only
+ // claim for one is impossible and refused.
+ assert!(
+ inspect_capture_envelope(HookEnvelope::from_query_and_body(
+ query(),
+ stripped("active")
+ ))
+ .is_none()
+ );
+
+ // An older client that still keeps the command under a broken marker
+ // is stripped by the server's own re-inspection.
+ let kept = serde_json::json!({
+ "session_id": "shell-invalid-keep", "tool_name": "Bash",
+ "tool_input": { "command": "cat /PRIVATE_PATH_SENTINEL/x.md" },
+ "tool_response": "SENTINEL_SECRET",
+ "_ai_memory_capture": capture_protocol("keep", "invalid", "non-file", 0, "extracted"),
+ });
+ let env =
+ inspect_capture_envelope(HookEnvelope::from_query_and_body(query(), kept)).unwrap();
+ assert_eq!(
+ env.raw["_ai_memory_capture"]["disposition"],
+ "metadata-only"
+ );
+ let stored = serde_json::to_string(&env).unwrap();
+ assert!(!stored.contains("SENTINEL"), "{stored}");
+
+ // Control: a non-file tool with no command keeps its body.
+ let search = serde_json::json!({
+ "session_id": "web-search-invalid", "tool_name": "web_search",
+ "tool_input": { "query": "docs" },
+ "_ai_memory_capture": capture_protocol("keep", "invalid", "non-file", 0, "extracted"),
+ });
+ let env =
+ inspect_capture_envelope(HookEnvelope::from_query_and_body(query(), search.clone()))
+ .unwrap();
+ assert_eq!(env.raw, search);
+ }
+
#[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 08658473..2ae01b48 100644
--- a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
+++ b/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
@@ -47,7 +47,7 @@
],
"shell": {
"note": "Shell-tool vectors run by both matchers. `{root}` is the marker directory, `cwd` is relative to it, and `command` is shorthand for a `bash` payload.",
- "ignore_paths": ["docs/adr/**","~/notes/**","docs/n?tes/**","C:/Secret/**"],
+ "ignore_paths": ["docs/adr/**","~/notes/**","docs/n?tes/**","C:/Secret/**","private notes/**"],
"vectors": [
{"command":"cat docs/adr/0001.md","disposition":"drop"},
{"command":"cat ./docs/adr/0001.md","disposition":"drop"},
@@ -84,6 +84,12 @@
{"command":"ls C:/Pub*","disposition":"keep"},
{"payload":{"tool":"shell","args":{"command":["bash","-lc","cat docs/adr/x.md"]}},"disposition":"drop"},
{"payload":{"tool":"run_command","args":{"cmd":"cat docs/adr/x.md"}},"disposition":"drop"},
+ {"command":"cat 'private notes/x.md'","disposition":"drop"},
+ {"command":"cat private notes/x.md","disposition":"keep"},
+ {"payload":{"tool":"shell","args":{"command":["cat","private notes/x.md"]}},"disposition":"drop"},
+ {"payload":{"tool":"shell","args":{"command":["cat","it's/x","docs/adr/x.md"]}},"disposition":"drop"},
+ {"payload":{"tool":"shell","args":{"command":["bash","-lc","cat 'private notes/x.md'"]}},"disposition":"drop"},
+ {"payload":{"tool":"shell","args":{"command":["cat","private","notes/x.md"]}},"disposition":"keep"},
{"payload":{"tool":"bash","args":{"command":7}},"disposition":"keep"},
{"payload":{"tool":"exec","args":{"command":"cat docs/adr/x.md"}},"disposition":"drop"},
{"payload":{"tool":"shell_command","args":{"command":"cat docs/adr/x.md"}},"disposition":"drop"},
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 0e139fe5..5e2189f9 100644
--- a/docs/marker-file.md
+++ b/docs/marker-file.md
@@ -238,7 +238,9 @@ retain current behavior.
Recognized shell tools (`Bash`, `shell`, `exec`, `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
+A command given as an argument vector keeps each element as one word (a path
+with spaces stays whole) and also splits each element on its own, so a
+`bash -lc "<script>"` script is read like any command line. Each argument that is not a flag, plus the value of a `--flag=value` or
`NAME=value` word, is resolved like a file-tool path: from the tool's own
`workdir` argument when it has one, otherwise from the event's `cwd`. If
one matches a pattern, the whole event is **dropped**, exactly like a matching
@@ -247,7 +249,9 @@ 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
+their output is still captured. An invalid policy makes a shell command
+**metadata-only**, like a file tool, because a broken marker cannot prove its
+arguments miss every ignored path. Excluding content before transport
matters because it cannot then reach observations/FTS, session pages, handoffs,
reviewer requests, proposals, or logs.
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 00dadc30..1be4cbdc 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -40,7 +40,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), including shell commands whose arguments name an ignored path (`match_command`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `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`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | 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, and the server admits a metadata-only shell body only under an invalid marker (`router.rs` `metadata_protocol_is_legal`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `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`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `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 refused, older client's invalid-marker keep stripped, commandless control kept); `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | 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 |