Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hooks): fail closed on unreadable shell calls and cap whole argv words
Peterson Salmefebaf9490352
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c172f91d..ef19d7a0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -75,10 +75,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0notes/x.md"]`) apart and let one element's stray quote hide the elementsafter 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).- (#973)+ instead of keeping its command and output, including one whose command is+ missing or unparseable (`web_search` runs nothing and is still kept), and the+ server now does the same when it cannot parse the client's capture marker. A+ long `bash -lc "<script>"` element is read only as words, not also as one+ path, so it can no longer exhaust the match budget and drop an innocuous+ event. 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). (#973)- 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 thediff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rsindex 54ba9ee0..0dae8f73 100644--- a/crates/ai-memory-cli/src/commands/render_shared.rs+++ b/crates/ai-memory-cli/src/commands/render_shared.rs@@ -275,15 +275,17 @@ function captureStartsWith(path: string, prefix: string, insensitive: boolean):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; }// 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; }+// A long element that splits is a script, not a path: keeping it whole would+// charge it, quadratically, against every pattern.+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 || [...item].length > 256 ? 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(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 }; }+function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string[]; shell?: boolean; 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), shell: name !== "web_search", 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.shell)) 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)}@@ -2148,6 +2150,12 @@ const shellInvalid = capturePolicy({{ ...bash(`cat ${{privatePath}}`), output: pcheck(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");+// A shell call whose command cannot be read still fails closed under a broken marker.+expectDecision({{ tool: "bash", args: {{ command: 7 }} }}, marker('[capture'), "metadata-only", "non-file", "extracted", 0, "invalid-unparseable-shell-metadata-only");+// A long `bash -lc` script is tokenized, not charged whole against every pattern.+const argvScript = "echo x; ".repeat(350) + "ls a?.rs";+const manyPatterns = marker(`[capture]\nignore_paths = [${{Array.from({{ length: 40 }}, (_, i) => `"private${{i}}/**"`).join(",")}}]\n`);+expectDecision({{ tool: "shell", args: {{ command: ["bash", "-lc", argvScript] }} }}, manyPatterns, "keep", "non-file", "extracted", 0, "argv-script-not-budget-dropped");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.rsindex 7085e6e0..6081e594 100644--- a/crates/ai-memory-hooks/src/capture_policy.rs+++ b/crates/ai-memory-hooks/src/capture_policy.rs@@ -16,6 +16,9 @@ pub const MAX_CANDIDATE_PATH_CHARS: usize = 4_096;pub const MAX_CAPTURE_CANDIDATES: usize = 32;/// Maximum aggregate pattern-by-candidate scalar comparisons per inspection.pub const MAX_MATCH_WORK: usize = 1_000_000;+/// Longest argv element kept whole as a path candidate when it also splits+/// into several words; longer ones are scripts (`bash -lc "<script>"`).+const MAX_ARGV_PATH_CHARS: usize = 256;const MAX_CALL_ID_CHARS: usize = 128;const CAPTURE_PROTOCOL_VERSION: u8 = 1;@@ -481,10 +484,9 @@ impl CapturePolicy {let (disposition, extraction) = match self.state {PolicyState::Inactive => (CaptureDisposition::Keep, extracted.state),// 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() =>- {+ // every ignored path, so it fails closed like a file tool, even+ // when the command itself is missing or unparseable.+ PolicyState::Invalid if extracted.family == ToolFamily::File || extracted.shell => {(CaptureDisposition::MetadataOnly, extracted.state)}PolicyState::Invalid => (CaptureDisposition::Keep, extracted.state),@@ -664,6 +666,9 @@ struct Extracted {paths: Option<Vec<String>>,/// A shell tool's command, already split into words.command: Option<Vec<String>>,+ /// A command-running tool, whether or not its command could be read.+ /// `web_search` is non-file but runs nothing.+ shell: bool,workdir: Option<String>,call_id: Option<String>,state: ExtractionState,@@ -725,6 +730,7 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted {.flatten();// OpenCode `bash`, OpenClaw `exec` and Codex `shell` run in `workdir`// when given, so relative arguments resolve from there.+ let shell = family == ToolFamily::NonFile && !name.eq_ignore_ascii_case("web_search");let workdir = command.as_ref().and_then(|_| args?.get("workdir")?.as_str())@@ -756,6 +762,7 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted {family,paths,command,+ shell,workdir,call_id,state,@@ -902,7 +909,12 @@ fn shell_command(args: &Value) -> Option<Vec<String>> {let mut words = Vec::new();for item in items {let tokens = shell_words(item);- if tokens.len() != 1 || tokens[0] != item {+ // Whitespace in a long element means a script, not a path;+ // its tokens are checked below. Keeping the blob whole would+ // charge it, quadratically, against every pattern.+ if (tokens.len() != 1 || tokens[0] != item)+ && item.chars().count() <= MAX_ARGV_PATH_CHARS+ {words.push(item.to_owned());}words.extend(tokens);@@ -1998,4 +2010,68 @@ mod tests {]);}+ // Review of #973, finding 2: the fail-closed rule under an invalid marker+ // keys on a *parsed* command, so a shell call whose command cannot be+ // parsed is still kept whole.+ #[test]+ fn invalid_marker_strips_shell_calls_with_unparseable_commands() {+ let policy = CapturePolicy::resolve(CaptureSource::Invalid, "/repo", None);+ for (agent, payload) in [+ (+ AgentKind::ClaudeCode,+ json!({"tool_name":"Bash","tool_input":{"command":7}}),+ ),+ (+ AgentKind::Codex,+ json!({"tool_name":"shell","tool_input":{"command":["cat", 7]}}),+ ),+ (+ AgentKind::ClaudeCode,+ json!({"tool_name":"Bash","tool_input":{"cmd_line":"cat secret/x.md"}}),+ ),+ ] {+ let decision = policy.inspect(agent, &payload, "/repo");+ assert_eq!(+ decision.protocol().disposition(),+ CaptureDisposition::MetadataOnly,+ "{payload}"+ );+ }+ }++ // Review of #973, finding 3: an argv element is pushed whole, so a+ // `bash -lc "<script>"` blob becomes one glob-bearing path candidate that+ // is charged against every pattern and can blow the match budget.+ #[test]+ fn long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget() {+ let ignore_paths = (0..40).map(|i| format!("/repo/private{i}/**")).collect();+ let policy = CapturePolicy::resolve(+ CaptureSource::Parsed(&CaptureConfig { ignore_paths }),+ "/repo",+ None,+ );+ assert_eq!(policy.state, PolicyState::Active);+ let script = format!("{}ls a?.rs", "echo x; ".repeat(350));+ assert!(script.chars().count() < MAX_CANDIDATE_PATH_CHARS);+ // Control: the same script as one command string is tokenized into+ // short words and is kept.+ let as_string = json!({"tool_name":"shell","tool_input":{"command": script}});+ assert_eq!(+ policy+ .inspect(AgentKind::Codex, &as_string, "/repo")+ .protocol()+ .disposition(),+ CaptureDisposition::Keep,+ "control"+ );+ let as_argv = json!({"tool_name":"shell","tool_input":{"command":["bash","-lc",script]}});+ assert_eq!(+ policy+ .inspect(AgentKind::Codex, &as_argv, "/repo")+ .protocol()+ .disposition(),+ CaptureDisposition::Keep,+ "innocuous script silently dropped by the match budget"+ );+ }}diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex b3860a4a..2f9920a4 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -891,11 +891,11 @@ fn inspect_capture_envelope(env: HookEnvelope) -> Option<HookEnvelope> {let Some(protocol) = CaptureProtocol::parse(raw_protocol) else {// A new/malformed marker must not make a recognized file operation- // less private. Mark the replacement invalid: an inactive/keep- // protocol would falsely describe the server's privacy fallback.- // Non-file legacy payloads retain their old behavior.+ // or shell command less private. Mark the replacement invalid: an+ // inactive/keep protocol would falsely describe the server's privacy+ // fallback. Other tools retain their old behavior.let decision = direct(PolicyState::Invalid);- if decision.protocol().tool_family() == ToolFamily::File {+ if decision.protocol().disposition() == CaptureDisposition::MetadataOnly {return Some(metadata_envelope(env, &decision, None));}return Some(env);@@ -12329,6 +12329,41 @@ mod tests {assert_eq!(env.raw, search);}+ // Review of #973, finding 1: an unparseable marker only made File events+ // metadata-only, so a shell event kept its command and output.+ #[test]+ fn capture_protocol_unparseable_marker_strips_shell_events() {+ for marker in [+ serde_json::json!("garbage"),+ serde_json::json!({"version": 99}),+ {+ let mut future = capture_protocol("keep", "invalid", "non-file", 0, "extracted");+ future["version"] = serde_json::json!(2);+ future+ },+ ] {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "post-tool-use".into(),+ agent: Some("claude-code".into()),+ ..Default::default()+ },+ serde_json::json!({+ "session_id": "shell-unparseable", "cwd": "/repo",+ "tool_name": "Bash",+ "tool_input": { "command": "cat docs/adr/secret.md" },+ "tool_response": "SENTINEL_SECRET",+ "_ai_memory_capture": marker,+ }),+ );+ let stored = inspect_capture_envelope(env).map(|env| env.raw.to_string());+ assert!(+ stored.is_none_or(|stored| !stored.contains("SENTINEL_SECRET")),+ "shell output survived an unparseable marker"+ );+ }+ }+#[test]fn capture_protocol_invalid_file_keep_becomes_canonical_metadata_only() {let env = HookEnvelope::from_query_and_body(diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 92d3b1ee..a2430990 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -125,7 +125,9 @@ patterns and candidates never leave the client, but shell/patch text, aliases,and non-path-attributable bodies remain outside its scope. The authoritativegrammar, limits, supported integrations, and `--check-capture` affordance arein [the marker-file reference](marker-file.md#capture-exclusions). It adds no-MCP tool and needs no DB migration; new-client/old-server is safe, while old+MCP tool and needs no DB migration. New-client/old-server is safe for file+tools, but under an invalid marker a new client also sends shell calls as+metadata-only, which an older server drops; upgrade the server first. Oldclients retain their previous capture behavior.## 7. Memory model (temporal)diff --git a/docs/marker-file.md b/docs/marker-file.mdindex 5e2189f9..c233171f 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -239,8 +239,9 @@ Recognized shell tools (`Bash`, `shell`, `exec`, `execute_bash`, `terminal`, …have no path field, so the command line is split into words lexically, the waya POSIX shell quotes and separates them, without expanding or running anything.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+with spaces stays whole, up to 256 characters) 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`. Ifone matches a pattern, the whole event is **dropped**, exactly like a matching@@ -251,7 +252,9 @@ the match budget is dropped. Variables, command substitution, `cd` state, andcommands that name no path at all (`rg TODO`, `git diff`) are not followed, sotheir 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+arguments miss every ignored path; this holds even when the command cannot be+read. An older server drops that metadata-only shell event, so upgrade the+server before the clients. Excluding content before transportmatters 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.mdindex 1be4cbdc..6ce8f0f0 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`; 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 |+| 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), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`; `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 |