Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(capture): read more shell spellings of a path in both matchers
AkitaOnRails4635b96c7858
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2bf85b37..eeaba27f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -37,6 +37,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0reads them. Inline interpreter code (`python3 -c`, `node -e` and similar)and further glob syntax the matcher does not evaluate (zsh glob groups,extglobs, encoded escapes) are now metadata-only under an active policy.+ Line continuations, parameter defaults, values glued to short flags,+ `file:` URLs, `~+`, PowerShell and cmd escape characters, and shell or+ interpreter options placed before the script or code are now read too, and+ more script runners and interpreters are recognized. A path under a+ directory only the running shell knows (`~-`, `~name`) makes the call+ metadata-only, and on macOS paths match without regard to case, as its+ default filesystem does.This applies to the native hook, the server, and thegenerated TypeScript integrations. (GHSA-gcpc-88hm-3xqr)- Fixed `ai-memory backfill`, including the automatic first-boot import, anddiff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rsindex 4a1697f4..00caea8d 100644--- a/crates/ai-memory-cli/src/commands/render_shared.rs+++ b/crates/ai-memory-cli/src/commands/render_shared.rs@@ -240,6 +240,8 @@ const CAPTURE_MAX_CANDIDATES = 32;const CAPTURE_MAX_WORK = 1000000;const CAPTURE_MAX_SHELL_NESTING = 4;const CAPTURE_MAX_CALL_ID_CHARS = 128;+// macOS's default filesystem ignores case, so `NOTES/X.md` reads `notes/x.md`; mirrors `fold_case`.+let captureFoldCase = typeof process !== "undefined" && process.platform === "darwin";type CaptureDisposition = "keep" | "drop" | "metadata-only";type CaptureProtocol = { version: 1; disposition: CaptureDisposition; policy_state: "inactive" | "active" | "invalid"; tool_family: "file" | "search-list" | "non-file" | "unknown"; path_count: number; extraction_state: "not-applicable" | "extracted" | "missing-or-malformed" | "unsupported-schema" };@@ -338,35 +340,49 @@ function captureShellCommand(args: Record<string, unknown> | undefined): string// word, and again every word inside a word that holds more than one// (`bash -c 'cat x'`, `"$(cat x)"`), down to CAPTURE_MAX_SHELL_NESTING levels;// a script nested deeper is opaque. Mirrors `ShellCommand::split`.-function captureShellSplit(command: string | string[]): { words: string[]; opaque: boolean } { const split = { words: [] as string[], opaque: false }; if (typeof command === "string") { split.opaque = captureUnevaluatedExpansion(command); captureNestedWords(captureShellWords(command), CAPTURE_MAX_SHELL_NESTING, split); return split; } split.opaque = command.some((item) => captureUnevaluatedExpansion(item)) || captureInlineCode(command); for (const item of command) { const tokens = captureShellWords(item); if (tokens.length === 1 && tokens[0] === item) { capturePushWord(item, split); continue; } if ([...item].length <= 256) split.words.push(item); captureNestedWords(tokens, CAPTURE_MAX_SHELL_NESTING - 1, split); } return split; }+// `windows` also reads the command without PowerShell backquote and cmd caret+// escapes. A `~-`, `~N` or `~name` prefix names a directory only the running+// shell knows, which makes the command unprovable.+function captureShellSplit(command: string | string[], windows = false): { words: string[]; opaque: boolean } { const split = { words: [] as string[], opaque: false }; if (typeof command === "string") { split.opaque = captureUnevaluatedExpansion(command); captureNestedWords(captureShellWords(command), CAPTURE_MAX_SHELL_NESTING, split); const plain = windows ? captureWithoutWindowsEscapes(command) : undefined; if (plain !== undefined) captureNestedWords(captureShellWords(plain), CAPTURE_MAX_SHELL_NESTING, split); } else { split.opaque = command.some((item) => captureUnevaluatedExpansion(item)) || captureInlineCode(command); for (const item of command) { captureArgvItem(item, split); const plain = windows ? captureWithoutWindowsEscapes(item) : undefined; if (plain !== undefined) captureArgvItem(plain, split); } } if (split.words.some((word) => captureShellArguments(word).some(([argument]) => captureUnknownDirectory(argument)))) split.opaque = true; return split; }+function captureArgvItem(item: string, split: { words: string[]; opaque: boolean }): void { const tokens = captureShellWords(item); if (tokens.length === 1 && tokens[0] === item) { capturePushWord(item, split); return; } if ([...item].length <= 256) split.words.push(item); captureNestedWords(tokens, CAPTURE_MAX_SHELL_NESTING - 1, split); }+// PowerShell's backquote and cmd's caret each stand for the next character; mirrors `without_windows_escapes`.+function captureWithoutWindowsEscapes(command: string): string | undefined { if (!/[`^]/.test(command)) return undefined; const chars = [...command]; let plain = ""; for (let i = 0; i < chars.length; i++) { if (chars[i] === "`" || chars[i] === "^") { i++; if (i < chars.length) plain += chars[i]; } else plain += chars[i]; } return plain; }+function captureUnknownDirectory(argument: string): boolean { if (!argument.startsWith("~")) return false; const prefix = argument.slice(1).split(/[\/\\]/)[0]; return prefix !== "" && prefix !== "+"; }// Only a script a shell runs expands braces and classes; a quoted message or pattern does not.function captureNestedWords(words: string[], depth: number, split: { words: string[]; opaque: boolean }): void { if (captureInlineCode(words)) split.opaque = true; words.forEach((word, index) => { capturePushWord(word, split); const tokens = captureShellWords(word); if (tokens.length === 1 && tokens[0] === word) return; if (depth === 0) { split.opaque = true; return; } if ((word.includes("$(") || word.includes("`") || captureShellScript(words, index)) && captureUnevaluatedExpansion(word)) split.opaque = true; captureNestedWords(tokens, depth - 1, split); }); }-// Also adds the POSIX reading of a word with `\o` escapes, which the shell reads as `o`.-function capturePushWord(word: string, split: { words: string[] }): void { split.words.push(word); if (!word.includes("\\")) return; const chars = [...word]; let plain = ""; for (let i = 0; i < chars.length; i++) { if (chars[i] === "\\") { i++; if (i < chars.length) plain += chars[i]; } else plain += chars[i]; } if (plain !== word) split.words.push(plain); }+// Also adds the POSIX reading of a word with `\o` escapes, which the shell reads as `o`, and the reading with each parameter default (`${X:-docs/x.md}`) replaced by its operand.+function capturePushWord(word: string, split: { words: string[] }): void { split.words.push(word); const operands = captureParameterOperands(word); if (operands !== undefined) split.words.push(operands); if (!word.includes("\\")) return; const chars = [...word]; let plain = ""; for (let i = 0; i < chars.length; i++) { if (chars[i] === "\\") { i++; if (i < chars.length) plain += chars[i]; } else plain += chars[i]; } if (plain !== word) split.words.push(plain); }+// Mirrors `parameter_operands`: `${NAME:-w}`, `${NAME:=w}`, `${NAME:+w}` (or without `:`) become `w`, nested down to CAPTURE_MAX_SHELL_NESTING levels.+function captureParameterOperands(word: string): string | undefined { let current = captureReplaceOperands(word); if (current === undefined) return undefined; for (let i = 1; i < CAPTURE_MAX_SHELL_NESTING; i++) { const next = captureReplaceOperands(current); if (next === undefined) break; current = next; } return current; }+function captureReplaceOperands(word: string): string | undefined { let output = ""; let rest = word; let changed = false; for (;;) { const start = rest.indexOf("${"); if (start < 0) break; output += rest.slice(0, start); const body = rest.slice(start + 2); const name = (/^[A-Za-z0-9_]*/.exec(body) ?? [""])[0].length; const after = body.slice(name); const operator = /^:[-=+]/.test(after) ? 2 : /^[-=+]/.test(after) ? 1 : 0; const operand = after.slice(operator); let depth = 0; let end = -1; for (let i = 0; i < operand.length; i++) { const c = operand[i]; if (c === "{") depth++; else if (c === "}") { if (depth === 0) { end = i; break; } depth--; } } if (end >= 0 && name > 0 && operator > 0) { output += operand.slice(0, end); changed = true; rest = operand.slice(end + 1); } else { output += "${"; rest = body; } } output += rest; return changed ? output : undefined; }function captureCommandName(word: string): string { const name = (word.split(/[\/\\]/).pop() ?? word).replace(/[A-Z]/g, (c) => c.toLowerCase()); return name.endsWith(".exe") ? name.slice(0, -4) : name; }-function captureShellScript(words: string[], index: number): boolean { let flagged = false; for (let i = index - 1; i >= 0; i--) { const word = words[i]; if (word.startsWith("-")) { flagged ||= !word.startsWith("--") && word.slice(1).includes("c"); continue; } const name = captureCommandName(word); return (flagged && ["sh","bash","zsh","dash","ksh","mksh","ash","yash","fish"].includes(name)) || (i + 1 === index && name === "eval"); } return false; }-// Inline interpreter code (`python3 -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `deno eval`) builds paths at run time; mirrors `runs_inline_code`.-function captureInlineCode(words: string[]): boolean { return words.some((word, index) => { const name = captureCommandName(word); const versioned = (prefix: string) => name.startsWith(prefix) && /^[0-9.]*$/.test(name.slice(prefix.length)); if (name === "deno") return words[index + 1] === "eval"; const letters = versioned("python") || versioned("pypy") || name === "py" ? "c" : versioned("perl") ? "eE" : versioned("ruby") ? "e" : ["node","nodejs","bun"].includes(name) ? "ep" : versioned("php") ? "r" : undefined; if (!letters) return false; for (const flag of words.slice(index + 1)) { if (!flag.startsWith("-")) break; if (["--eval","--print"].includes(flag) || flag.startsWith("--eval=") || flag.startsWith("--print=") || (!flag.startsWith("--") && [...flag.slice(1)].some((c) => letters.includes(c)))) return true; } return false; }); }-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 = ""; else if (c === "\\" && next !== undefined) { word += captureAnsiEscape(next) ?? c + next; i++; } else word += c; } else 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 === "'" || next === '"')) { quote = next === "'" ? "$" : '"'; i++; 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; }+// Skips options and their values (`bash -o pipefail -c`); mirrors `is_shell_script`/`takes_shell_value`.+function captureShellScript(words: string[], index: number): boolean { let flagged = false; for (let i = index - 1; i >= 0; i--) { const word = words[i]; if (word.startsWith("-")) { flagged ||= !word.startsWith("--") && word.slice(1).includes("c"); continue; } if (word.length > 1 && word.startsWith("+")) continue; if (i > 0 && captureShellValueOption(words[i - 1])) continue; const name = captureCommandName(word); return (flagged && ["sh","bash","zsh","dash","ksh","mksh","ash","yash","fish","su","script"].includes(name)) || (i + 1 === index && name === "eval"); } return false; }+function captureShellValueOption(flag: string): boolean { return ["--rcfile","--init-file","--init-command","-C"].includes(flag) || (flag.length > 1 && (flag.startsWith("+") || (flag.startsWith("-") && !flag.startsWith("--"))) && /[oO]$/.test(flag)); }+// Inline interpreter code (`python3 -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e`, `Rscript -e`, `osascript -e`, `deno eval`) builds paths at run time; mirrors `runs_inline_code`.+function captureInlineCode(words: string[]): boolean { return words.some((word, index) => { const name = captureCommandName(word); const versioned = (prefix: string) => name.startsWith(prefix) && /^[0-9.]*$/.test(name.slice(prefix.length)); if (name === "deno") return words[index + 1] === "eval"; const spec: [string, string[]] | undefined = versioned("python") || versioned("pypy") || name === "py" ? ["c", ["-W","-X","--check-hash-based-pycs"]] : versioned("perl") ? ["eE", ["-I","-M","-m"]] : versioned("ruby") ? ["e", ["-I","-r","-C","-E"]] : ["node","nodejs","bun"].includes(name) ? ["ep", ["-r","--require","--import","--loader","--experimental-loader","-C","--conditions","--input-type","--title","--env-file"]] : versioned("php") ? ["r", ["-d","-c","-z"]] : ["lua","luajit","rscript","osascript"].includes(name) ? ["e", ["-l"]] : undefined; if (!spec) return false; const [letters, values] = spec; for (let i = index + 1; i < words.length; i++) { const flag = words[i]; if (!flag.startsWith("-")) return false; if (["--eval","--print"].includes(flag) || flag.startsWith("--eval=") || flag.startsWith("--print=") || (!flag.startsWith("--") && [...flag.slice(1)].some((c) => letters.includes(c)))) return true; if (values.includes(flag)) i++; } return false; }); }+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 = ""; else if (c === "\\" && next !== undefined) { word += captureAnsiEscape(next) ?? c + next; i++; } else word += c; } else if (quote) { if (c === quote) quote = ""; else if (quote === '"' && c === "\\" && next === "\n") i++; else if (quote === '"' && c === "\\" && (next === '"' || next === "\\")) { word += next; i++; } else word += c; } else if (c === "'" || c === '"') { quote = c; inWord = true; } else if (c === "$" && (next === "'" || next === '"')) { quote = next === "'" ? "$" : '"'; i++; inWord = true; } else if (c === "\\" && next === "\n") { i++; } 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; }// `$'…'` escapes; numeric and control escapes stay as written. Mirrors `ansi_c_escape`.function captureAnsiEscape(escape: string): string | undefined { const decoded: Record<string, string> = { a: "\u0007", b: "\b", e: "\u001b", E: "\u001b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v", "\\": "\\", "'": "'", '"': '"', "?": "?" }; return Object.prototype.hasOwnProperty.call(decoded, escape) ? decoded[escape] : undefined; }// Whether an unquoted word holds syntax lexical matching does not evaluate: a brace expansion (`{a,b}`, `{1..3}`), a bracket class (`[ab]`, `[]a]`), a zsh glob group or extglob (`docs/(a|b)`, `(a|b)/x`), or an ANSI-C numeric/control escape; mirrors `has_unevaluated_expansion`.function captureUnevaluatedExpansion(command: string): boolean { const operator = (c: string) => "|&;<>()`".includes(c); const isWord = (c: string | undefined) => c !== undefined && !/\s/.test(c) && !operator(c); const chars = [...command]; let quote = ""; let previous = ""; let inWord = false; let parameter = false; let brace: boolean | undefined; let klass: number | undefined; const groups: boolean[] = []; for (let i = 0; i < chars.length; i++) { const c = chars[i]; if (quote) { if (((quote === "$" || quote === "'") && c === "'") || (quote === '"' && c === '"')) quote = ""; else if (quote === "$" && c === "\\") { const escape = chars[++i]; if (escape !== undefined && /^[xuUc0-7]$/.test(escape)) return true; } else if (quote === '"' && c === "\\") i++; if (klass !== undefined) klass++; previous = ""; inWord = true; continue; } if (c === "'" && previous === "$") quote = "$"; else if (c === "'" || c === '"') quote = c; else if (c === "\\") { i++; if (klass !== undefined) klass++; previous = ""; inWord = true; continue; } else if (c === "(") { if (inWord && previous !== "$" && previous !== "=") return true; groups.push(!inWord && previous !== "<" && previous !== ">"); parameter = false; brace = undefined; klass = undefined; inWord = false; } else if (c === ")") { if (groups.pop() === true && isWord(chars[i + 1])) return true; parameter = false; brace = undefined; klass = undefined; inWord = false; } else if (c === "|" && groups[groups.length - 1] === true && inWord && isWord(chars[i + 1])) return true; else if (/\s/.test(c) || operator(c)) { parameter = false; brace = undefined; klass = undefined; inWord = false; } else if (c === "{" && previous === "$") parameter = true; else if (c === "}" && parameter) parameter = false; else if (parameter) { /* parameter expansion */ } else if (c === "{") brace = false; else if (c === "," && brace !== undefined) brace = true; else if (c === "." && brace !== undefined && previous === ".") brace = true; else if (c === "}" && brace !== undefined) { if (brace) return true; brace = undefined; } else if (c === "[" && klass === undefined) klass = 0; else if (c === "]" && klass === 0) klass = 1; else if (c === "]" && klass !== undefined) return true; else if (klass !== undefined) klass++; if (!/\s/.test(c) && !operator(c)) inWord = true; previous = c; } return false; }-// Also the path of a git `REV:path` object name, flagged because git resolves it from the repository root; mirrors `shell_arguments`.-function captureShellArguments(word: string): [string, boolean][] { const flag = word.startsWith("-"); const out: [string, boolean][] = flag ? [] : [[word, false]]; const eq = word.indexOf("="); const colon = flag && eq < 0 ? word.indexOf(":") : -1; if (eq >= 0) out.push([word.slice(eq + 1), false]); else if (colon >= 0) out.push([word.slice(colon + 1), false]); const object = captureGitObjectPath(word); if (object !== undefined) out.push([object, true]); return out.filter(([argument]) => argument.trim() !== ""); }+// Also a value glued to a short flag (`-fFILE`), the path of a git `REV:path` object name, flagged because git resolves it from the repository root, and the path of any of these that is a `file:` URL; mirrors `shell_arguments`.+function captureShellArguments(word: string): [string, boolean][] { const flag = word.startsWith("-"); const out: [string, boolean][] = flag ? [] : [[word, false]]; const eq = word.indexOf("="); const colon = flag && eq < 0 ? word.indexOf(":") : -1; if (eq >= 0) out.push([word.slice(eq + 1), false]); else if (colon >= 0) out.push([word.slice(colon + 1), false]); if (flag && !word.startsWith("--")) { const glued = [...word.slice(1)].slice(1).join(""); if (glued) out.push([glued, false]); } const object = captureGitObjectPath(word); if (object !== undefined) out.push([object, true]); for (const [argument] of [...out]) { const url = captureFileUrlPath(argument); if (url !== undefined) out.push([url, false]); } return out.filter(([argument]) => argument.trim() !== ""); }+// The local path of a `file:` URL in any case, ASCII percent-escapes decoded; mirrors `file_url_path`.+function captureFileUrlPath(argument: string): string | undefined { if (argument.slice(0, 5).toLowerCase() !== "file:") return undefined; const rest = argument.slice(5); let path = rest; if (rest.startsWith("//")) { const slash = rest.indexOf("/", 2); if (slash < 0) return undefined; path = rest.slice(slash); } if (/^\/[A-Za-z]:/.test(path)) path = path.slice(1); return path.replace(/%([0-7][0-9A-Fa-f])/g, (_match, hex: string) => String.fromCharCode(Number.parseInt(hex, 16))); }function captureGitObjectPath(word: string): string | undefined { if (word.startsWith("-")) return undefined; const colon = word.indexOf(":"); if (colon < 0) return undefined; const revision = word.slice(0, colon); let path = word.slice(colon + 1); if (!revision && /^[0-3]:/.test(path)) path = path.slice(2); return !/^[A-Za-z]$/.test(revision) && /^[A-Za-z0-9._\/~^@{}-]*$/.test(revision) && !path.startsWith("//") ? path : undefined; }// 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, fromRoot] 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); for (const root of fromRoot && !absolute && config.root ? [base, config.root] : [base]) { if (!absolute && !root) continue; const candidate = captureNormalize(absolute ? expanded : captureJoin(root, expanded), config.windowsHost); if (!candidate) continue; const match = captureMatchCandidate(candidate, false, config, budget); if (match !== false) return match; } } return false; }+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, fromRoot] of captureShellArguments(word)) { const expanded = /^~[\/\\]/.test(argument) ? captureJoin(home, argument.slice(2)) : argument === "~+" ? base : argument.startsWith("~+/") && base ? captureJoin(base, argument.slice(3)) : argument; if ([...expanded].length > CAPTURE_MAX_PATH_CHARS) continue; const absolute = /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(expanded); for (const root of fromRoot && !absolute && config.root ? [base, config.root] : [base]) { if (!absolute && !root) continue; const candidate = captureNormalize(absolute ? expanded : captureJoin(root, expanded), config.windowsHost); if (!candidate) continue; const match = captureMatchCandidate(candidate, false, config, budget); if (match !== false) return match; } } return false; }// Gemini CLI `read_many_files` globs expand case-insensitively with `**`// recursing to any depth: a literal path matches like a file tool's, a glob// drops when it could expand into an ignored path, and glob syntax the matcher// cannot evaluate (classes, braces, extglobs, negation) fails closed.function captureMatchGlobs(paths: string[], candidates: { path: string; windows: boolean }[], config: CaptureConfig): boolean | undefined { const budget = { work: 0 }; for (let i = 0; i < paths.length; i++) { if (/[\[\]{}()!]/.test(paths[i])) return undefined; const match = captureMatchCandidate(candidates[i], true, config, budget); if (match !== false) return match; } return false; }-function captureMatchCandidate(candidate: { path: string; windows: boolean }, toolGlob: boolean, config: CaptureConfig, budget: { work: number }): boolean | undefined { const glob = /[*?]/.test(candidate.path); const directory = toolGlob && !glob; for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; const insensitive = toolGlob || pattern.windows; const under = captureStartsWith(candidate.path, pattern.prefix, insensitive); if (!under && !glob && !directory) continue; if (under) { const directory = pattern.directory ? captureGlob(pattern.directory, candidate.path, insensitive, budget) : false; if (directory !== false) return directory; const match = captureGlob(pattern.path, candidate.path, insensitive, budget); if (match !== false) return match; } if (glob) { const reaches = captureGlobstarReaches(candidate.path, pattern.prefix, insensitive, budget); if (reaches !== false) return reaches; } if (directory) { const below = captureGlobBelow(pattern.path, candidate.path, insensitive, budget); if (below !== false) return below; } } return false; }+function captureMatchCandidate(candidate: { path: string; windows: boolean }, toolGlob: boolean, config: CaptureConfig, budget: { work: number }): boolean | undefined { const glob = /[*?]/.test(candidate.path); const directory = toolGlob && !glob; for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; const insensitive = toolGlob || pattern.windows || captureFoldCase; const under = captureStartsWith(candidate.path, pattern.prefix, insensitive); if (!under && !glob && !directory) continue; if (under) { const directory = pattern.directory ? captureGlob(pattern.directory, candidate.path, insensitive, budget) : false; if (directory !== false) return directory; const match = captureGlob(pattern.path, candidate.path, insensitive, budget); if (match !== false) return match; } if (glob) { const reaches = captureGlobstarReaches(candidate.path, pattern.prefix, insensitive, budget); if (reaches !== false) return reaches; } if (directory) { const below = captureGlobBelow(pattern.path, candidate.path, insensitive, budget); if (below !== false) return below; } } return false; }function captureGlobstarReaches(glob: string, prefix: string, insensitive: boolean, budget: { work: number }): boolean | undefined { const star = glob.indexOf("**"); if (star < 0) return captureGlobReaches(glob, prefix, insensitive, budget); const slash = glob.lastIndexOf("/", star); const head = slash < 0 ? "" : glob.slice(0, slash); const depth = head.split("/").filter(Boolean).length; let seen = 0; let offset = 0; for (const part of prefix.split("/")) { if (seen === depth) break; offset += part.length; if (part) seen++; if (seen < depth) offset++; } if (seen < depth) return captureGlobReaches(glob, prefix, insensitive, budget); return captureGlob(head, prefix.slice(0, offset), insensitive, budget); }-function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string | string[]; shell?: boolean; workdir?: string; globs?: boolean; reader?: boolean } { 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","list_dir","grep_search","search_files","find_by_name","list_directory","search_file_content"].includes(name)) return { family: "search-list", extraction: "not-applicable", callID: call }; if (["bash","shell","shell_command","exec","execute","run_command","web_search","search_web","manage_task","manage_subagents","terminal","execute_bash","execute_cmd","powershell","run_shell_command"].includes(name)) { const workdir = ["workdir","dir_path","directory"].map((k) => args?.[k]).find((v) => v !== undefined); return { family: "non-file", extraction: "extracted", callID: call, command: captureShellCommand(args), shell: name !== "web_search", workdir: typeof workdir === "string" && workdir.trim() ? 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","read_many_files"].includes(name)) return { family: "unknown", extraction: "extracted", callID: call, reader: ["bashoutput","taskoutput","write_stdin","process","read_bash","write_bash","read_powershell","write_powershell"].includes(name) }; 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","TargetFile"]) 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 (name === "read_many_files" && args && "include" in args) { const include = args.include; if (!Array.isArray(include) || include.some((x: unknown) => typeof x !== "string") || (paths?.length ?? 0) + include.length > CAPTURE_MAX_CANDIDATES) paths = undefined; else paths = [...(paths ?? []), ...(include as string[])]; } if (!paths || !paths.length || 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, globs: name === "read_many_files" }; }+function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string | string[]; shell?: boolean; powershell?: boolean; workdir?: string; globs?: boolean; reader?: boolean } { 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","list_dir","grep_search","search_files","find_by_name","list_directory","search_file_content"].includes(name)) return { family: "search-list", extraction: "not-applicable", callID: call }; if (["bash","shell","shell_command","exec","execute","run_command","web_search","search_web","manage_task","manage_subagents","terminal","execute_bash","execute_cmd","powershell","run_shell_command"].includes(name)) { const workdir = ["workdir","dir_path","directory"].map((k) => args?.[k]).find((v) => v !== undefined); return { family: "non-file", extraction: "extracted", callID: call, command: captureShellCommand(args), shell: name !== "web_search", powershell: name === "powershell", workdir: typeof workdir === "string" && workdir.trim() ? 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","read_many_files"].includes(name)) return { family: "unknown", extraction: "extracted", callID: call, reader: ["bashoutput","taskoutput","write_stdin","process","read_bash","write_bash","read_powershell","write_powershell"].includes(name) }; 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","TargetFile"]) 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 (name === "read_many_files" && args && "include" in args) { const include = args.include; if (!Array.isArray(include) || include.some((x: unknown) => typeof x !== "string") || (paths?.length ?? 0) + include.length > CAPTURE_MAX_CANDIDATES) paths = undefined; else paths = [...(paths ?? []), ...(include as string[])]; } if (!paths || !paths.length || 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, globs: name === "read_many_files" }; }// An external lifecycle owner (`AI_MEMORY_CAPTURE_OWNER`, any value that is// non-empty after trimming) takes over capture for this process: the gate runs// before the capture-policy marker scan, so no disposition work, no marker read@@ -382,7 +398,7 @@ function captureOwnedExternally(): boolean { const owner = typeof process === "u// home the walk stops at home, outside it continues past the checkout root to an// organisation-level marker; an unreadable marker counts as a selection.function captureServerRouted(cwd: string | undefined): boolean { let dir = resolve(cwd ?? process.cwd()); const home = homedir(); let boundary: string | undefined; for (let probe = dir; ; probe = dirname(probe)) { if (probe === home) { boundary = home; break; } if (probe === dirname(probe)) break; } for (;;) { try { if (/^\s*server\s*=/m.test(readFileSync(join(dir, ".ai-memory.toml"), "utf8"))) return true; } catch (e) { if (!["ENOENT", "ENOTDIR", "EISDIR"].includes((e as { code?: string })?.code ?? "")) return true; } if (dir === boundary || dir === dirname(dir)) return false; dir = dirname(dir); } }-function capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { if (captureOwnedExternally()) return { disposition: "drop", payload }; if (captureServerRouted(cwd)) return { disposition: "drop", payload }; 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 || tool.reader)) disposition = "metadata-only"; else if (config.state === "active" && tool.reader) 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), config.windowsHost)); if (candidates.some((p) => !p)) disposition = "metadata-only"; else if (tool.globs) { const match = captureMatchGlobs(tool.paths, candidates as { path: string; windows: boolean }[], config); if (match !== false) disposition = match ? "drop" : "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) { const split = captureShellSplit(tool.command); if (captureMatchCommand(split.words, config, tool.workdir) !== false) disposition = "drop"; else if (split.opaque) disposition = "metadata-only"; } 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 capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { if (captureOwnedExternally()) return { disposition: "drop", payload }; if (captureServerRouted(cwd)) return { disposition: "drop", payload }; 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 || tool.reader)) disposition = "metadata-only"; else if (config.state === "active" && tool.reader) 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), config.windowsHost)); if (candidates.some((p) => !p)) disposition = "metadata-only"; else if (tool.globs) { const match = captureMatchGlobs(tool.paths, candidates as { path: string; windows: boolean }[], config); if (match !== false) disposition = match ? "drop" : "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 || captureFoldCase, budget)) { disposition = "drop"; break captureMatch; } const match = captureGlob(pattern.path, candidate.path, pattern.windows || captureFoldCase, 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) { const split = captureShellSplit(tool.command, tool.powershell || config.windowsHost); if (captureMatchCommand(split.words, config, tool.workdir) !== false) disposition = "drop"; else if (split.opaque) disposition = "metadata-only"; } 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)}@@ -2556,6 +2572,8 @@ function findMarker(cwd: string | undefined): string | undefined {{ return cwd ?{policy}const fixture = JSON.parse(fixtureText);+// Case-sensitive POSIX matching unless a check opts into a macOS-style host.+captureFoldCase = false;const privatePath = "/PRIVATE_PATH_SENTINEL/item";const privatePattern = "/PRIVATE_PATTERN_SENTINEL/item";const privateBody = "PRIVATE_BODY_SENTINEL";@@ -2604,8 +2622,10 @@ for (const vector of fixture.shell.vectors) {{const cwd = vector.cwd ? join(shellRoot, vector.cwd) : shellRoot;markerFixtures.set(cwd, join(shellRoot, ".ai-memory.toml"));const payload = JSON.parse(JSON.stringify(vector.payload ?? {{ tool: "bash", args: {{ command: vector.command }} }}).replaceAll("{{root}}", shellRoot));+ captureFoldCase = vector.fold_case === true;expectDecision(payload, cwd, vector.disposition, "non-file", "extracted", 0, `shell-${{vector.disposition}}: ${{JSON.stringify(vector)}}`);}}+captureFoldCase = false;// Gemini reads a `read_many_files` directory entry as `entry/**` (shared vectors).const directoryRoot = marker(`[capture]\nignore_paths = ${{JSON.stringify(fixture.read_many_files_directories.ignore_paths)}}\n`);for (const vector of fixture.read_many_files_directories.vectors) {{@@ -2621,6 +2641,17 @@ for (const cwd of [marker(active), marker('[capture')]) {{}}const bash = (command: string) => ({{ tool: "bash", args: {{ command }} }});check(capturePolicy(bash("cat docs/adr/x.md"), "/no-marker").disposition === "keep", "shell-inactive-keep");+// A Windows host reads cmd caret and PowerShell backquote escapes out of any+// shell tool; mirrors `windows_escape_characters_are_read_on_a_windows_host`.+const windowsShell = "D:/shell"; markerFixtures.set(windowsShell, markerFixtures.get(marker('[capture]\nignore_paths = ["C:/Secret/**"]\n'))!);+expectDecision(bash("type C:\\Secr^et\\x.md"), windowsShell, "drop", "non-file", "extracted", 0, "windows-host-caret");+expectDecision(bash("Get-Content C:\\Secr`et\\x.md"), windowsShell, "drop", "non-file", "extracted", 0, "windows-host-backquote");+expectDecision(bash("type C:\\Public\\x^.md"), windowsShell, "keep", "non-file", "extracted", 0, "windows-host-public");+// A macOS host folds case for file tools too; mirrors `a_case_folding_host_matches_paths_without_regard_to_case`.+captureFoldCase = true;+expectDecision({{ tool: "edit", args: {{ path: "CASE/item" }} }}, marker('[capture]\nignore_paths = ["case/**"]\n'), "drop", "file", "extracted", 1, "fold-case-file");+expectDecision({{ tool: "edit", args: {{ path: "PUBLIC/item" }} }}, marker('[capture]\nignore_paths = ["case/**"]\n'), "keep", "file", "extracted", 1, "fold-case-file-public");+captureFoldCase = false;check(capturePolicy(bash("cat docs/{{adr,x}}/1.md"), "/no-marker").disposition === "keep", "shell-expansion-inactive-keep");const shellExpansion = capturePolicy({{ ...bash("cat docs/{{adr,x}}/1.md"), output: privateBody }}, shellRoot);check(shellExpansion.disposition === "metadata-only" && !JSON.stringify(shellExpansion.payload).includes(privateBody), "shell-expansion-redaction");diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rsindex 620d24d8..c4676fea 100644--- a/crates/ai-memory-hooks/src/capture_policy.rs+++ b/crates/ai-memory-hooks/src/capture_policy.rs@@ -438,6 +438,9 @@ pub struct CapturePolicy {/// The marker directory, where git resolves a `REV:path` object name/// when the repository root holds the marker.root: Option<String>,+ /// POSIX paths compare without regard to ASCII case, as on macOS, whose+ /// default filesystem reads `NOTES/X.md` as `notes/x.md`.+ fold_case: bool,}#[derive(Clone, Debug)]@@ -508,6 +511,17 @@ impl CapturePolicy {/// `home_dir` is required only when at least one pattern starts with `~/`.#[must_use]pub fn resolve(source: CaptureSource<'_>, marker_dir: &str, home_dir: Option<&str>) -> Self {+ Self::resolve_for_host(source, marker_dir, home_dir, cfg!(target_os = "macos"))+ }+ /// [`Self::resolve`] for a host whose filesystem does (`fold_case`) or+ /// does not ignore case. Only the client holds the patterns, so the+ /// server's re-inspection never depends on this.+ fn resolve_for_host(+ source: CaptureSource<'_>,+ marker_dir: &str,+ home_dir: Option<&str>,+ fold_case: bool,+ ) -> Self {let config = match source {CaptureSource::Absent => return Self::inactive(),CaptureSource::Invalid => {@@ -516,6 +530,7 @@ impl CapturePolicy {patterns: Vec::new(),home: None,root: None,+ fold_case,};}CaptureSource::Parsed(config) => config,@@ -530,12 +545,14 @@ impl CapturePolicy {patterns,home: home_dir.and_then(|dir| normalize_root(dir).ok()),root: normalize_root(marker_dir).ok(),+ fold_case,},Err(_) => Self {state: PolicyState::Invalid,patterns: Vec::new(),home: None,root: None,+ fold_case,},}}@@ -545,6 +562,7 @@ impl CapturePolicy {patterns: Vec::new(),home: None,root: None,+ fold_case: false,}}/// Evaluates every policy state using only direct fixture-backed schemas.@@ -616,7 +634,11 @@ impl CapturePolicy {Some(dir) if is_absolute(cwd) => join(cwd, dir),_ => cwd.to_owned(),};- let split = command.split();+ // PowerShell's backquote and cmd's caret escape the next+ // character, so their commands also get a reading+ // without them.+ let split =+ command.split(extracted.powershell || flavor_of(cwd) == Flavor::Windows);self.match_command(&split.words, &base).map(|matched| (matched, split.opaque))}) {@@ -668,7 +690,7 @@ impl CapturePolicy {&pattern.path,&candidate.path,pattern.directory_base.as_deref(),- pattern.flavor == Flavor::Windows,+ pattern.flavor == Flavor::Windows || self.fold_case,) {return Ok(true);}@@ -683,9 +705,18 @@ impl CapturePolicy {let mut work = 0_usize;for word in words {for (argument, from_root) in shell_arguments(word) {- let expanded = match (argument.strip_prefix("~/"), self.home.as_deref()) {- (Some(rest), Some(home)) => join(home, rest),- _ => argument.to_owned(),+ let home = argument+ .strip_prefix("~/")+ .or_else(|| argument.strip_prefix("~\\"));+ // `~+` is the working directory.+ let expanded = if let (Some(rest), Some(home)) = (home, self.home.as_deref()) {+ join(home, rest)+ } else if argument == "~+" {+ cwd.to_owned()+ } else if let Some(rest) = argument.strip_prefix("~+/") {+ join(cwd, rest)+ } else {+ argument};// Git reads `REV:path` from the repository root, which only// the marker directory approximates; try the cwd as well.@@ -726,15 +757,15 @@ impl CapturePolicy {}/// Whether one normalized candidate, literal or glob, names or can expand/// into an ignored path. `tool_glob` selects `read_many_files` expansion- /// (case-insensitive, recursive `**`) over a shell's; Windows always- /// ignores case.+ /// (case-insensitive, recursive `**`) over a shell's; Windows, and a+ /// case-folding host, always ignore case.fn match_pattern_candidate(&self,candidate: &Normalized,tool_glob: bool,work: &mut usize,) -> Result<bool, ()> {- let insensitive = tool_glob || candidate.flavor == Flavor::Windows;+ let insensitive = tool_glob || candidate.flavor == Flavor::Windows || self.fold_case;let is_glob = candidate.path.contains(['*', '?']);// `read_many_files` reads a directory entry (`docs`, `.`) as// `entry/**`, and nothing here can tell a directory from a file.@@ -854,6 +885,8 @@ struct Extracted<'a> {globs: bool,/// The tool reads back output of an earlier command (`BashOutput`).output_reader: bool,+ /// Claude Code's `PowerShell` tool.+ powershell: bool,call_id: Option<String>,state: ExtractionState,}@@ -970,6 +1003,7 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted<'_> {search_paths,globs: name.eq_ignore_ascii_case("read_many_files"),output_reader: reads_earlier_output(name),+ powershell: name.eq_ignore_ascii_case("powershell"),call_id,state,}@@ -1232,7 +1266,7 @@ struct ShellWords {impl ShellCommand<'_> {#[cfg(test)]fn words(&self) -> Vec<String> {- self.split().words+ self.split(false).words}/// Every word, and again every word inside a word that holds more than@@ -1243,12 +1277,18 @@ impl ShellCommand<'_> {/// (`private notes/x.md`) and also tokenizes it, so a `bash -lc "<script>"`/// element is read like any script. Joining the elements instead would/// re-split paths with spaces and let one stray quote swallow the rest.- fn split(&self) -> ShellWords {+ ///+ /// `windows` also reads the command without PowerShell and cmd escapes+ /// ([`without_windows_escapes`]).+ fn split(&self, windows: bool) -> ShellWords {let mut split = ShellWords::default();match self {Self::Line(command) => {split.opaque = has_unevaluated_expansion(command);push_nested_words(&shell_words(command), MAX_SHELL_NESTING, &mut split);+ if let Some(plain) = windows.then(|| without_windows_escapes(command)).flatten() {+ push_nested_words(&shell_words(&plain), MAX_SHELL_NESTING, &mut split);+ }}Self::Argv(items) => {// Each element is scanned as a script too, the same@@ -1256,23 +1296,67 @@ impl ShellCommand<'_> {split.opaque = items.iter().any(|item| has_unevaluated_expansion(item))|| runs_inline_code(items);for item in items {- let tokens = shell_words(item);- if tokens.len() == 1 && tokens[0] == *item {- push_word(item, &mut split);- continue;+ push_argv_item(item, &mut split);+ if let Some(plain) = windows.then(|| without_windows_escapes(item)).flatten() {+ push_argv_item(&plain, &mut split);}- // Kept whole, a long script would exhaust the match budget.- if item.chars().count() <= MAX_ARGV_PATH_CHARS {- split.words.push((*item).to_owned());- }- push_nested_words(&tokens, MAX_SHELL_NESTING - 1, &mut split);}}}+ // `~-`, `~N` and `~name` name a directory only the running shell+ // knows, so a path under one proves nothing either way.+ split.opaque |= split.words.iter().any(|word| {+ shell_arguments(word)+ .iter()+ .any(|(argument, _)| names_unknown_directory(argument))+ });split}}+fn push_argv_item(item: &str, split: &mut ShellWords) {+ let tokens = shell_words(item);+ if tokens.len() == 1 && tokens[0] == item {+ push_word(item, split);+ return;+ }+ // Kept whole, a long script would exhaust the match budget.+ if item.chars().count() <= MAX_ARGV_PATH_CHARS {+ split.words.push(item.to_owned());+ }+ push_nested_words(&tokens, MAX_SHELL_NESTING - 1, split);+}++/// `command` without PowerShell's backquote and cmd's caret escapes, each of+/// which stands for the character after it (`secr`et.md`, `secr^et.md`).+fn without_windows_escapes(command: &str) -> Option<String> {+ if !command.contains(['`', '^']) {+ return None;+ }+ let mut plain = String::with_capacity(command.len());+ let mut chars = command.chars();+ while let Some(c) = chars.next() {+ if matches!(c, '`' | '^') {+ plain.extend(chars.next());+ } else {+ plain.push(c);+ }+ }+ Some(plain)+}++/// Whether an argument starts with a tilde prefix whose directory only the+/// running shell knows: `~-` (the previous directory), `~N`/`~+N` (the+/// directory stack) or `~name` (another account's home). `~`, `~/` and `~+`+/// (the working directory) are resolved instead.+fn names_unknown_directory(argument: &str) -> bool {+ let Some(rest) = argument.strip_prefix('~') else {+ return false;+ };+ let prefix = rest.split(['/', '\\']).next().unwrap_or(rest);+ !prefix.is_empty() && prefix != "+"+}+/// How many quoting levels a script inside a word is re-split.const MAX_SHELL_NESTING: usize = 4;@@ -1303,9 +1387,13 @@ fn push_nested_words(words: &[String], depth: usize, split: &mut ShellWords) {/// Adds a word, and its POSIX reading when it differs: outside quotes a/// shell drops the backslash of `\o`, but [`shell_words`] keeps it so a-/// Windows path keeps its separators.+/// Windows path keeps its separators. A word with a parameter default+/// (`${X:-docs/x.md}`) also adds the reading with the operand in its place.fn push_word(word: &str, split: &mut ShellWords) {split.words.push(word.to_owned());+ if let Some(operands) = parameter_operands(word) {+ split.words.push(operands);+ }if word.contains('\\') {let mut plain = String::with_capacity(word.len());let mut chars = word.chars();@@ -1322,6 +1410,70 @@ fn push_word(word: &str, split: &mut ShellWords) {}}+/// `word` with each `${NAME:-word}`, `${NAME:=word}` or `${NAME:+word}`+/// (or the form without `:`) replaced by its operand, which the shell+/// substitutes when `NAME` is unset (set, for `+`). Nested operands are+/// replaced down to [`MAX_SHELL_NESTING`] levels.+fn parameter_operands(word: &str) -> Option<String> {+ let mut current = replace_parameter_operands(word)?;+ for _ in 1..MAX_SHELL_NESTING {+ match replace_parameter_operands(¤t) {+ Some(next) => current = next,+ None => break,+ }+ }+ Some(current)+}++fn replace_parameter_operands(word: &str) -> Option<String> {+ let mut output = String::new();+ let mut rest = word;+ let mut changed = false;+ while let Some(start) = rest.find("${") {+ output.push_str(&rest[..start]);+ let body = &rest[start + 2..];+ let name = body+ .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))+ .unwrap_or(body.len());+ let after = &body[name..];+ let operator =+ if after.starts_with(":-") || after.starts_with(":=") || after.starts_with(":+") {+ 2+ } else if after.starts_with(['-', '=', '+']) {+ 1+ } else {+ 0+ };+ let operand = &after[operator..];+ let mut depth = 0_usize;+ let end = operand.char_indices().find_map(|(index, c)| match c {+ '{' => {+ depth += 1;+ None+ }+ '}' if depth == 0 => Some(index),+ '}' => {+ depth -= 1;+ None+ }+ _ => None,+ });+ match end {+ Some(end) if name > 0 && operator > 0 => {+ output.push_str(&operand[..end]);+ changed = true;+ rest = &operand[end + 1..];+ }+ _ => {+ output.push_str("${");+ rest = body;+ }+ }+ }+ output.push_str(rest);+ changed.then_some(output)+}+/// A command word's program name: its last path segment, lowercased,/// without `.exe`.fn command_name(word: &str) -> String {@@ -1334,7 +1486,9 @@ fn command_name(word: &str) -> String {}/// Whether `words[index]` is a script a shell runs: the argument after-/// `sh -c` (any flag cluster with `c`, as in `bash -lc`) or after `eval`.+/// `sh -c` (any flag cluster with `c`, as in `bash -lc`, past other options+/// and their values, as in `bash -o pipefail -c`), after `su -c` or+/// `script -c`, which hand it to a shell, or after `eval`.fn is_shell_script<S: AsRef<str>>(words: &[S], index: usize) -> bool {let mut script_flag = false;for previous in (0..index).rev() {@@ -1343,19 +1497,46 @@ fn is_shell_script<S: AsRef<str>>(words: &[S], index: usize) -> bool {script_flag |= !flag.starts_with('-') && flag.contains('c');continue;}+ // `+o pipefail`, `+x`.+ if word.len() > 1 && word.starts_with('+') {+ continue;+ }+ if previous > 0 && takes_shell_value(words[previous - 1].as_ref()) {+ continue;+ }let name = command_name(word);return (script_flag&& matches!(name.as_str(),- "sh" | "bash" | "zsh" | "dash" | "ksh" | "mksh" | "ash" | "yash" | "fish"+ "sh" | "bash"+ | "zsh"+ | "dash"+ | "ksh"+ | "mksh"+ | "ash"+ | "yash"+ | "fish"+ | "su"+ | "script"))|| (previous + 1 == index && name == "eval");}false}+/// Whether a shell option consumes the next word as its value: `-o`/`+o`+/// and `-O`/`+O` (also ending a flag cluster, as in `-eo`), `--rcfile`,+/// `--init-file`, and fish's `-C`/`--init-command`.+fn takes_shell_value(flag: &str) -> bool {+ matches!(flag, "--rcfile" | "--init-file" | "--init-command" | "-C")+ || (flag.len() > 1+ && (flag.starts_with('+') || (flag.starts_with('-') && !flag.starts_with("--")))+ && flag.ends_with(['o', 'O']))+}+/// Whether the words run inline interpreter code (`python3 -c`, `node -e`,-/// `ruby -e`, `perl -e`, `php -r`, `deno eval`). Code builds paths at run+/// `ruby -e`, `perl -e`, `php -r`, `lua -e`, `Rscript -e`, `osascript -e`,+/// `deno eval`). Code builds paths at run/// time (`'docs/' + name`), so no lexical match can rule an ignored path out.fn runs_inline_code<S: AsRef<str>>(words: &[S]) -> bool {(0..words.len()).any(|index| {@@ -1364,33 +1545,59 @@ fn runs_inline_code<S: AsRef<str>>(words: &[S]) -> bool {name.strip_prefix(prefix).is_some_and(|rest| rest.chars().all(|c| c.is_ascii_digit() || c == '.'))};- let letters: &[char] = if versioned("python") || versioned("pypy") || name == "py" {- &['c']- } else if versioned("perl") {- &['e', 'E']- } else if versioned("ruby") {- &['e']- } else if matches!(name.as_str(), "node" | "nodejs" | "bun") {- &['e', 'p']- } else if versioned("php") {- &['r']- } else if name == "deno" {- return words- .get(index + 1)- .is_some_and(|next| next.as_ref() == "eval");- } else {- return false;- };- words[index + 1..]- .iter()- .map(AsRef::as_ref)- .take_while(|word| word.starts_with('-'))- .any(|flag| {- matches!(flag, "--eval" | "--print")- || flag.starts_with("--eval=")- || flag.starts_with("--print=")- || (!flag.starts_with("--") && flag[1..].contains(letters))- })+ // The inline-code flag letters, and the options that take the+ // next word as their value (`python3 -W ignore -c …`).+ let (letters, values): (&[char], &[&str]) =+ if versioned("python") || versioned("pypy") || name == "py" {+ (&['c'], &["-W", "-X", "--check-hash-based-pycs"])+ } else if versioned("perl") {+ (&['e', 'E'], &["-I", "-M", "-m"])+ } else if versioned("ruby") {+ (&['e'], &["-I", "-r", "-C", "-E"])+ } else if matches!(name.as_str(), "node" | "nodejs" | "bun") {+ (+ &['e', 'p'],+ &[+ "-r",+ "--require",+ "--import",+ "--loader",+ "--experimental-loader",+ "-C",+ "--conditions",+ "--input-type",+ "--title",+ "--env-file",+ ],+ )+ } else if versioned("php") {+ (&['r'], &["-d", "-c", "-z"])+ } else if matches!(name.as_str(), "lua" | "luajit" | "rscript" | "osascript") {+ (&['e'], &["-l"])+ } else if name == "deno" {+ return words+ .get(index + 1)+ .is_some_and(|next| next.as_ref() == "eval");+ } else {+ return false;+ };+ let mut rest = words[index + 1..].iter().map(AsRef::as_ref);+ while let Some(flag) = rest.next() {+ if !flag.starts_with('-') {+ return false;+ }+ if matches!(flag, "--eval" | "--print")+ || flag.starts_with("--eval=")+ || flag.starts_with("--print=")+ || (!flag.starts_with("--") && flag[1..].contains(letters))+ {+ return true;+ }+ if values.contains(&flag) {+ rest.next();+ }+ }+ false})}@@ -1526,6 +1733,10 @@ fn shell_words(command: &str) -> Vec<String> {while let Some(c) = chars.next() {match (quote, c) {(Some('\'' | '$'), '\'') | (Some('"'), '"') => quote = None,+ // A backslash-newline outside single quotes continues the line.+ (Some('"') | None, '\\') if chars.peek() == Some(&'\n') => {+ chars.next();+ }(Some('"'), '\\') if matches!(chars.peek(), Some('"' | '\\')) => {word.extend(chars.next());}@@ -1597,22 +1808,75 @@ fn ansi_c_escape(escape: char) -> Option<char> {/// Path-like values carried by one shell word: the word itself unless it is/// a flag, plus the value of a `--flag=value`, `NAME=value`, or PowerShell-/// `-Param:value` word, plus the path of a git `REV:path` object name. The-/// flag is set for that last one, which git resolves from the repository-/// root.-fn shell_arguments(word: &str) -> impl Iterator<Item = (&str, bool)> {+/// `-Param:value` word, plus a value glued to a short flag (`-fFILE`), plus+/// the path of a git `REV:path` object name, plus the path of any of these+/// that is a `file:` URL. The flag is set for the object name's path, which+/// git resolves from the repository root.+fn shell_arguments(word: &str) -> Vec<(String, bool)> {let flag = word.starts_with('-');- let whole = (!flag).then_some((word, false));- let value = word+ let mut arguments: Vec<(String, bool)> = Vec::new();+ if !flag {+ arguments.push((word.to_owned(), false));+ }+ if let Some((_, value)) = word.split_once('=').or_else(|| flag.then(|| word.split_once(':')).flatten())- .map(|(_, value)| (value, false));- let object = git_object_path(word).map(|path| (path, true));- whole- .into_iter()- .chain(value)- .chain(object)- .filter(|(argument, _)| !argument.trim().is_empty())+ {+ arguments.push((value.to_owned(), false));+ }+ if let Some(cluster) = word.strip_prefix('-').filter(|rest| !rest.starts_with('-')) {+ let mut chars = cluster.chars();+ chars.next();+ if !chars.as_str().is_empty() {+ arguments.push((chars.as_str().to_owned(), false));+ }+ }+ if let Some(path) = git_object_path(word) {+ arguments.push((path.to_owned(), true));+ }+ let urls: Vec<_> = arguments+ .iter()+ .filter_map(|(argument, _)| file_url_path(argument))+ .map(|path| (path, false))+ .collect();+ arguments.extend(urls);+ arguments.retain(|(argument, _)| !argument.trim().is_empty());+ arguments+}++/// The local path a `file:` URL names (`file:///x`, `file://host/x`,+/// `file:/x`, any case), with ASCII percent-escapes decoded.+fn file_url_path(argument: &str) -> Option<String> {+ if !argument.get(..5)?.eq_ignore_ascii_case("file:") {+ return None;+ }+ let rest = &argument[5..];+ let path = match rest.strip_prefix("//") {+ Some(authority) => &authority[authority.find('/')?..],+ None => rest,+ };+ // `file:///C:/x` names the drive path `C:/x`.+ let path = path+ .strip_prefix('/')+ .filter(|drive| valid_drive_prefix(drive))+ .unwrap_or(path);+ let mut decoded = String::with_capacity(path.len());+ let mut chars = path.chars();+ while let Some(c) = chars.next() {+ let escape = chars.as_str().get(..2).and_then(|hex| {+ u8::from_str_radix(hex, 16)+ .ok()+ .filter(|byte| byte.is_ascii() && hex.chars().all(|d| d.is_ascii_hexdigit()))+ });+ match escape {+ Some(byte) if c == '%' => {+ decoded.push(char::from(byte));+ chars.nth(1);+ }+ _ => decoded.push(c),+ }+ }+ Some(decoded)}/// The path of a git object name such as `HEAD:docs/x.md`, `v1.2~3:x`,@@ -2922,12 +3186,19 @@ mod tests {.iter().map(|pattern| pattern.as_str().unwrap().to_owned()).collect();- let policy = CapturePolicy::resolve(- CaptureSource::Parsed(&CaptureConfig { ignore_paths }),- "/repo",- Some("/home/me"),- );+ let config = CaptureConfig { ignore_paths };+ // The host's case folding is pinned per vector, so the table means+ // the same on every CI OS.+ let policy = |fold_case| {+ CapturePolicy::resolve_for_host(+ CaptureSource::Parsed(&config),+ "/repo",+ Some("/home/me"),+ fold_case,+ )+ };for vector in shell["vectors"].as_array().unwrap() {+ let policy = policy(vector["fold_case"].as_bool().unwrap_or(false));let payload = vector.get("payload").cloned()@@ -3954,6 +4225,103 @@ mod tests {Some(vec!["/other/repo".to_owned()]));}+ /// On a Windows host cmd's caret and PowerShell's backquote escape the+ /// next character whatever the shell tool, so their readings without the+ /// escape are matched; a POSIX shell reads both literally (control).+ #[test]+ fn windows_escape_characters_are_read_on_a_windows_host() {+ let windows = CapturePolicy::resolve(+ CaptureSource::Parsed(&CaptureConfig {+ ignore_paths: vec!["docs/adr/**".into()],+ }),+ r"C:\repo",+ None,+ );+ for (command, expected) in [+ (r"type docs\ad^r\x.md", CaptureDisposition::Drop),+ (r"Get-Content docs\ad`r\x.md", CaptureDisposition::Drop),+ (r"type C:\repo\DOCS\A^DR\x.md", CaptureDisposition::Drop),+ (r"type src\ma^in.rs", CaptureDisposition::Keep),+ ("echo a^b", CaptureDisposition::Keep),+ ] {+ let decision = windows.inspect(AgentKind::ClaudeCode, &bash(command), r"C:\repo");+ assert_eq!(decision.protocol().disposition(), expected, "{command}");+ }+ let posix = CapturePolicy::resolve(+ CaptureSource::Parsed(&CaptureConfig {+ ignore_paths: vec!["docs/adr/**".into()],+ }),+ "/repo",+ None,+ );+ for command in ["cat docs/ad^r/x.md", "cat docs/ad`r`/x.md"] {+ assert_eq!(+ posix+ .inspect(AgentKind::ClaudeCode, &bash(command), "/repo")+ .protocol()+ .disposition(),+ CaptureDisposition::Keep,+ "{command}"+ );+ }+ }++ /// A macOS host reads `DOCS/ADR/x.md` as `docs/adr/x.md`, so file tools+ /// and shell arguments match without regard to case there, and only+ /// there (control: the same host-independent policy elsewhere).+ #[test]+ fn a_case_folding_host_matches_paths_without_regard_to_case() {+ let policy = |fold_case| {+ CapturePolicy::resolve_for_host(+ CaptureSource::Parsed(&CaptureConfig {+ ignore_paths: vec!["docs/adr/**".into()],+ }),+ "/repo",+ None,+ fold_case,+ )+ };+ let read = json!({"tool_name": "Read", "tool_input": {"file_path": "DOCS/Adr/x.md"}});+ for (raw, label) in [(read, "read"), (bash("cat DOCS/Adr/x.md"), "bash")] {+ for (fold_case, expected) in [+ (true, CaptureDisposition::Drop),+ (false, CaptureDisposition::Keep),+ ] {+ assert_eq!(+ policy(fold_case)+ .inspect(AgentKind::ClaudeCode, &raw, "/repo")+ .protocol()+ .disposition(),+ expected,+ "{label} fold_case={fold_case}"+ );+ }+ }+ let public = json!({"tool_name": "Read", "tool_input": {"file_path": "SRC/x.md"}});+ assert_eq!(+ policy(true)+ .inspect(AgentKind::ClaudeCode, &public, "/repo")+ .protocol()+ .disposition(),+ CaptureDisposition::Keep+ );+ assert!(+ !CapturePolicy::resolve(CaptureSource::Absent, "/repo", None).fold_case,+ "an inactive policy never folds"+ );+ assert_eq!(+ CapturePolicy::resolve(+ CaptureSource::Parsed(&CaptureConfig {+ ignore_paths: vec!["x/**".into()],+ }),+ "/repo",+ None,+ )+ .fold_case,+ cfg!(target_os = "macos")+ );+ }+/// Reading nested words and the new fail-closed syntax must not strip/// everyday commands that name no ignored path.#[test]@@ -3989,6 +4357,25 @@ mod tests {"(cd src && cargo test)","docker compose up -d","curl -s http://localhost:8080/health",+ // Near misses of the continuation, option-value, glued-flag,+ // URL, tilde and parameter-default readings.+ "cargo test \\\n --workspace",+ "bash -o pipefail -c 'cargo test'",+ "set -o pipefail; cargo test",+ "python3 -W ignore -m pytest",+ "node -r ts-node/register scripts/build.ts",+ "grep -fpatterns.txt src",+ "cargo build -j4",+ "tar -czf out.tgz src",+ "gcc -Isrc -o build/app src/main.c",+ "make -C src",+ "curl -s file:///tmp/report.txt",+ "cat ~+/src/main.rs",+ "ls -la ~",+ "echo ${HOME:-/tmp} ${PWD}",+ "git log --oneline HEAD~3..HEAD",+ "git rebase -i HEAD~2",+ "echo a^b",] {assert_eq!(policydiff --git a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json b/crates/ai-memory-hooks/tests/fixtures/capture-policy.jsonindex 6f6418cf..66b15176 100644--- a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json+++ b/crates/ai-memory-hooks/tests/fixtures/capture-policy.json@@ -109,7 +109,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.",+ "note": "Shell-tool vectors run by both matchers. `{root}` is the marker directory, `cwd` is relative to it, `command` is shorthand for a `bash` payload, and `fold_case` runs the vector as on a case-insensitive (macOS) host.","ignore_paths": ["docs/adr/**","~/notes/**","docs/n?tes/**","C:/Secret/**","private notes/**"],"vectors": [{"command":"cat docs/adr/0001.md","disposition":"drop"},@@ -238,6 +238,63 @@{"command":"echo $((1+2))","disposition":"keep"},{"command":"diff <(ls src) <(ls tests)","disposition":"keep"},{"command":"cat $'src/main.rs'","disposition":"keep"},+ {"command":"cat docs/ad\\\nr/x.md","disposition":"drop"},+ {"command":"cat \"docs/ad\\\nr/x.md\"","disposition":"drop"},+ {"command":"bash -c 'cat docs/ad\\\nr/x.md'","disposition":"drop"},+ {"command":"cat src/ma\\\nin.rs","disposition":"keep"},+ {"command":"cargo test \\\n -p ai-memory-hooks","disposition":"keep"},+ {"payload":{"tool":"powershell","args":{"command":"Get-Content docs/ad`r/x.md"}},"disposition":"drop"},+ {"payload":{"tool":"powershell","args":{"command":"Get-Content C:\\Secr`et\\x.md"}},"disposition":"drop"},+ {"payload":{"tool":"powershell","args":{"command":"type docs\\ad^r\\x.md"}},"disposition":"drop"},+ {"payload":{"tool":"powershell","args":{"command":"Get-Content src/ma`in.rs"}},"disposition":"keep"},+ {"command":"cat docs/ad^r/x.md","disposition":"keep"},+ {"command":"bash -o pipefail -c 'cat docs/{adr,x}/1.md'","disposition":"metadata-only"},+ {"command":"bash -O extglob -c 'cat docs/@(adr)/1.md'","disposition":"metadata-only"},+ {"command":"bash +o histexpand -c 'cat docs/{adr,x}/1.md'","disposition":"metadata-only"},+ {"command":"bash --rcfile x.rc -c 'cat docs/ad[r]/1.md'","disposition":"metadata-only"},+ {"command":"bash -o pipefail -c 'cargo test'","disposition":"keep"},+ {"command":"grep -o '{a,b}' src/main.rs","disposition":"keep"},+ {"command":"python3 -W ignore -c \"print(1)\"","disposition":"metadata-only"},+ {"command":"node -r fs -e \"1\"","disposition":"metadata-only"},+ {"command":"php -d x=1 -r 'echo 1;'","disposition":"metadata-only"},+ {"command":"ruby -I lib -e 'puts 1'","disposition":"metadata-only"},+ {"command":"lua -e 'print(1)'","disposition":"metadata-only"},+ {"command":"Rscript -e '1'","disposition":"metadata-only"},+ {"command":"osascript -l JavaScript -e '1'","disposition":"metadata-only"},+ {"command":"su -c 'cat docs/{adr,x}/1.md'","disposition":"metadata-only"},+ {"command":"script -qc 'cat docs/ad[r]/1.md' /dev/null","disposition":"metadata-only"},+ {"command":"lua scripts/x.lua","disposition":"keep"},+ {"command":"Rscript analysis.R","disposition":"keep"},+ {"command":"python3 -W ignore -m pytest","disposition":"keep"},+ {"command":"node -r ts-node/register scripts/build.ts","disposition":"keep"},+ {"command":"xargs -adocs/adr/x.md echo","disposition":"drop"},+ {"command":"grep -fdocs/adr/x.md src","disposition":"drop"},+ {"command":"grep -fpatterns.txt src","disposition":"keep"},+ {"command":"cargo build -j4","disposition":"keep"},+ {"command":"tar -czf out.tgz src","disposition":"keep"},+ {"command":"curl -s file://{root}/docs/adr/1.md","disposition":"drop"},+ {"command":"curl -s FILE://{root}/docs/adr/1.md","disposition":"drop"},+ {"command":"curl -s file://localhost{root}/docs/adr/1.md","disposition":"drop"},+ {"command":"curl -s file://{root}/docs/ad%72/1.md","disposition":"drop"},+ {"command":"curl -s file://{root}/src/main.rs","disposition":"keep"},+ {"command":"cat ~+/docs/adr/1.md","disposition":"drop"},+ {"command":"cat ~-/docs/adr/1.md","disposition":"metadata-only"},+ {"command":"cat ~bob/notes/x.md","disposition":"metadata-only"},+ {"command":"cat ~1/x.md","disposition":"metadata-only"},+ {"command":"cat ~+/src/main.rs","disposition":"keep"},+ {"command":"cat ~/src/x.md","disposition":"keep"},+ {"command":"git diff HEAD~1 -- src/","disposition":"keep"},+ {"command":"cat ${X:-docs/adr/1.md}","disposition":"drop"},+ {"command":"cat ${X:=docs/adr/1.md}","disposition":"drop"},+ {"command":"cat ${X:+docs/adr/1.md}","disposition":"drop"},+ {"command":"cat ${X-docs/adr/1.md}","disposition":"drop"},+ {"command":"cat \"${X:-docs}/adr/1.md\"","disposition":"drop"},+ {"command":"cat ${X:-${Y:-docs/adr/1.md}}","disposition":"drop"},+ {"command":"cat ${X:-src/main.rs}","disposition":"keep"},+ {"command":"cat DOCS/ADR/1.md","fold_case":true,"disposition":"drop"},+ {"command":"cat Docs/Adr/*.md","fold_case":true,"disposition":"drop"},+ {"command":"cat DOCS/ADR/1.md","disposition":"keep"},+ {"command":"cat SRC/MAIN.rs","fold_case":true,"disposition":"keep"},{"command":"jq .[] package.json","disposition":"keep"}]},diff --git a/docs/marker-file.md b/docs/marker-file.mdindex 8236ac61..b7ac15ae 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -538,11 +538,23 @@ whether it is an argument vector element, a quoted script (`bash -c '…'`,backquotes), so a script is read like any command line, up to four quotinglevels; a script nested deeper is **metadata-only**. A quoted message thatmentions an ignored path (`git commit -m "…docs/adr/…"`) therefore drops the-event too. An ANSI-C string (`$'…'`) is decoded and a backslash before an-ordinary letter is dropped, as the shell does. Each+event too. An ANSI-C string (`$'…'`) is decoded, a backslash before an+ordinary letter is dropped, and a backslash-newline outside single quotes+joins the two lines, as the shell does. A word with a parameter default+(`${X:-docs/x.md}`, also `:=`, `:+` and the forms without `:`) is also read+with the operand in its place. Under the `PowerShell` tool, or on a Windows+host, the command is also read without PowerShell's backquote and cmd's caret+escape characters. Eachargument that is not a flag, plus the value of a `--flag=value`, `NAME=value`,-or PowerShell `-Param:value` word, is resolved like a file-tool path: from the tool's own+or PowerShell `-Param:value` word, plus a value glued to a short flag+(`-fdocs/x.md`), plus the local path of a `file:` URL in any case (ASCII+percent-escapes decoded), is resolved like a file-tool path: from the tool's own`workdir` argument (Gemini CLI's `dir_path`, Antigravity's `Cwd`) when it has one, otherwise from the event's `cwd`.+`~/` (and PowerShell's `~\`) is the home directory and `~+` the working+directory. An argument under `~-`, `~N` or `~name` (the previous directory,+the directory stack, another account's home) names a directory only the+running shell knows, so the command is **metadata-only** under an active+policy.The path in a git object name (`HEAD:docs/x.md`, `:docs/x.md`) is resolvedfrom both the `cwd` and the marker directory, because git reads it from therepository root. If@@ -555,13 +567,16 @@ the match budget is dropped. A command that no argument matches outright isunquoted brace expansion (`docs/{adr,x}/1.md`, `{1..3}`), a bracket class(`docs/ad[r]/1.md`, including one that starts with `]`), a zsh glob group orextglob (`docs/(a|b)/1.md`, `@(…)`), or a numeric or control escape in an-ANSI-C string. The same holds for those inside a script run by `sh -c`,-`eval` or a command substitution, but not inside a quoted message or pattern+ANSI-C string. The same holds for those inside a script run by `sh -c`+(also past shell options and their values, as in `bash -o pipefail -c`),+`su -c`, `script -c`, `eval` or a command substitution, but not inside a quoted message or pattern(`git log --format='%h {a,b}'`). Quoted or escaped braces and brackets,`${…}`, `{}`, `[ -f x ]`, `$(…)`, `<(…)` and a `( … )` subshell areunaffected; a word glued to a parenthesis (`f()`, `(a|b)x`) also counts as aglob group. Inline interpreter code (`python3 -c`, `node -e`, `ruby -e`,-`perl -e`, `php -r`, `deno eval`) is **metadata-only** under an active policy+`perl -e`, `php -r`, `lua -e`, `Rscript -e`, `osascript -e`, `deno eval`,+also after options that take a value, as in `python3 -W ignore -c`) is+**metadata-only** under an active policyunless one of its words names an ignored path outright, which drops it:code can build a path at run time (`'docs/' + name`), so no lexical match canrule one out. Running a script file or a module (`python3 -m pytest`,@@ -570,7 +585,10 @@ commands 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 itsarguments miss every ignored path; this holds even when the command cannot be-read. An older server drops these metadata-only shell and output-reader+read. On macOS, whose default filesystem ignores case, the native hook and the+generated integrations match file-tool and shell paths without regard to case+(`NOTES/X.md` matches `notes/**`); other POSIX hosts compare case-sensitively,+and Windows paths always ignore case. An older server drops these metadata-only shell and output-readerevents, 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.@@ -600,7 +618,15 @@ can be mentioned.and a heredoc fed to an interpreter (`python3 - <<EOF`) is read only for thewords it spells out;- git resolves `REV:path` from the repository root, which is approximated by- the marker directory and the `cwd`;+ the marker directory and the `cwd`, and a tool's own directory option+ (`git -C dir`, `make -C dir`) is not followed;+- script runners and interpreters the matcher does not list (`awk` with+ `getline`, `watch`, `flock … -c`, `su user -c`) are read only for the words+ they spell out: an ignored path named there still drops the event, but+ brace expansion or inline code inside them is not recognized;+- a value glued to a short flag is read after the flag's first letter only,+ not after a cluster (`-rf…`), and a `file:` URL's non-ASCII percent-escapes+ are not decoded;- tools the matcher does not list keep their current behavior.For a project whose content must never be captured, use allowlist capture modediff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex b9d6617c..2da4bc40 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -66,7 +66,7 @@ means the boundary is not built yet.| 10e | Reconcile-tombstone of a disk-deleted page is opt-in, soft, scope-bound, and false-positive-guarded (invariant #16, #929 delete-half) | `ai-memory-wiki/src/watcher.rs` — off by default (`[maintenance] reconcile_tombstones_deleted_pages`); a page is tombstoned only after its file is observed missing on two consecutive passes (streak resets if the path's `PageId` changed), re-verified against the live filesystem immediately before acting, with reserved/indexed-but-unwalked paths (`bootstrap.md`, `_meta.md`, `_pending/`, `sessions/*.md`) excluded and a circuit breaker that skips a whole scope when `> max(3, 50%)` of its pages look missing or a non-partial walk finds nothing; `ai-memory-store/src/ops.rs` `soft_delete_for_reconcile_if_latest` is a soft tombstone (`is_latest=0` + `superseded_at`, decay's shape) through the single writer actor in one transaction — never a filesystem write — scoped to the page's own `(workspace_id, project_id)` | `watcher.rs` `reconcile_delete_disabled_by_default_never_tombstones_a_missing_page`, `reconcile_delete_cross_project_isolation` (project A's deletion never tombstones project B's same-path page), `reconcile_tombstone_refuses_a_stale_latest_id`, `reconcile_tombstone_refuses_when_the_file_still_exists`, `reconcile_tombstone_never_touches_the_filesystem`; `ops.rs` `reconcile_tombstone_resurrects_instead_of_orphaning_on_recreate` | STRONG || 10f | Session-time repair is scope-bound (no cross-project timestamp rewrite) | `ai-memory-store/src/ops.rs` `repair_session_times` — every candidate is read back and updated with `WHERE id=? AND workspace_id=? AND project_id=?`; a row outside that 3-tuple is reported `NotFound` and untouched, same code path as an id that does not exist at all; `ai-memory-mcp/src/admin.rs` `handle_repair_session_times` passes the caller's `(workspace, project)` straight through, never the candidate's own | `ops.rs` `repair_session_times_does_not_touch_a_session_of_another_project` (control: sibling session in-scope repaired in the same batch); `admin_repair_session_times.rs` `cross_project_session_is_not_found_and_untouched`; both bite-checked by dropping the `project_id` filter | STRONG || 11a | Hook backpressure (202/429) + bounded fan-out (invariant #5) | `ai-memory-hooks/src/router.rs` semaphore→429, 202 immediately, `MAX_HOOK_BATCH_ITEMS`, bounded LRU limiter; batch acknowledgements retain only processed indices and classify terminal drops without consuming capacity | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded`; `router.rs` `handle_hook_batch_skips_rate_limited_first_item_and_accepts_later_source`, `handle_hook_batch_reports_failed_index_after_rate_limited_skip`, `handle_hook_batch_drops_subagent_events_before_capacity_check` (each asserts result indices and includes an accepted control) | STRONG |-| 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized, and every word that holds several words, such as a quoted `sh -c` script or a `"$(…)"` substitution, re-split to four levels by `ShellCommand::split`/`push_nested_words`, a deeper script metadata-only; ANSI-C strings decoded and a backslash before an ordinary letter dropped (`shell_words`, `push_word`); the path of a git `REV:path` object name tried from the cwd and the marker directory (`git_object_path`); Antigravity `run_command` resolved from its `Cwd`); an invalid marker makes file and shell calls metadata-only; an active one makes a shell call metadata-only when a word uses unquoted brace expansion, a bracket class (a leading `]` included), a zsh glob group or extglob, or a numeric/control ANSI-C escape (`has_unevaluated_expansion`, also run on scripts given to `sh -c`, `eval` or a substitution), or when it runs inline interpreter code (`runs_inline_code`: `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `deno eval`), and either makes tools that read back an earlier command's output metadata-only (`reads_earlier_output`: `BashOutput`, `TaskOutput`, `write_stdin`, `process`, `read_bash`/`write_bash` and PowerShell twins); the server admits a metadata-only shell or unknown-family body only under an active or invalid marker, with no paths and an `extracted` state (`router.rs` `metadata_protocol_is_legal`), and its own re-inspection strips an older client's keep for either; a Gemini `read_many_files` literal entry is also read as `entry/**` (`glob_matches_below`), and Copilot CLI's runtime `view`/`create`/`str_replace_editor` are file tools for that agent only (`agent_family`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`, `captureShellSplit`, `captureUnevaluatedExpansion`, `captureInlineCode`, `captureGitObjectPath`, `captureGlobBelow`, the `reader` flag). Candidate/argument flavor (`Flavor::Posix` vs `Flavor::Windows`, used to pick which `ignore_paths` patterns even apply) is derived from the **host** (the cwd), never from the candidate string alone — a POSIX-host candidate spelled with a leading `//` is collapsed to a single `/` before flavor detection (`normalize_candidate`; TS `captureNormalize`'s `windowsHost` parameter, sourced from `captureHostWindows(cwd)`), fixing GHSA-vh98 (a `//`-prefixed candidate used to self-classify as `Flavor::Windows` regardless of host, matching zero POSIX patterns and being captured instead of dropped); a genuine Windows/UNC host (cwd itself windows-flavored) is unaffected; `hook.rs` `--check-capture` preflight uses the same capture policy before any spool or spawn; transcript imports (`ai-memory backfill`, including the automatic first-boot run, and the `ai-memory run` ledger upload) apply the same decision table through `commands/transcript_capture.rs`: each recorded tool call is rebuilt in its agent's hook shape (`capture_policy.rs` `tool_call_payload`) and inspected by the checkout's policy, and by a reroute destination's policy too; a Drop removes the call and its result (paired by native id, else the strictest call of the turn; a call-less result drops under a policy), metadata-only posts the hook's metadata-only body with its protocol (backfill) or a withheld placeholder (ledger), and a shell call whose recorded arguments cannot be parsed drops; both imports also apply the hook's repository admission gate (`hook.rs` `checkout_admits_capture`: persisted capture mode, marker opt-in, readable routing marker — the same helpers the hook's own gate uses), so under allowlist mode an unmarked checkout imports nothing, prompts included: `backfill` stops before contacting the server and the run ledger finishes with no events (GHSA-gcpc-88hm-3xqr) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec` and `PowerShell`, `workdir`, glob directories, Windows paths, and a POSIX-host leading-`//` command via `/{root}/docs/adr/x.md`), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `claude_code_powershell_honors_ignored_paths_on_a_windows_host` (#1186: Windows-spelled and `-Param:value` paths drop, public-path and `git status` controls kept, invalid marker metadata-only), `gemini_cli_shell_and_read_many_files_honor_ignored_paths` (Gemini `run_shell_command` incl. `dir_path`/`directory`, and `read_many_files` globs via `match_globs`: excluded literal, mixed public+excluded, `docs/*`, recursive `**` and case-variant entries drop, an `exclude` list cannot rescue them, unsupported glob syntax and malformed lists are metadata-only, public entries kept, POSIX and Windows hosts) and `globstar_reaches_lets_double_star_span_any_depth`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors, and `normalization`'s leading-`//` POSIX vectors alongside the kept Windows-cwd UNC vectors as the no-regression control); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell admitted for an unevaluated expansion, inactive refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`, **`a_leading_double_slash_candidate_does_not_escape_posix_ignore_paths_via_flavor_mismatch`** (GHSA-vh98 adversarial: attempts the `//repo/secret/...` violation on a POSIX host, proves it now drops, with a plain-single-slash control and a Windows-hosted genuine-UNC control both still correct — fails on the pre-fix code); `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`, `gemini_cli_shell_and_read_many_files_exclusions_drop_before_spool` (pre- and post-tool events with an excluded path are never spooled; public controls spool with their family); `capture_policy.rs` `read_many_files_directory_entries_cannot_reach_ignored_paths` (shared `read_many_files_directories` vectors: `docs`, `.`, `./`, `docs/`, case and `..` variants drop; `src`, `README.md`, `docs/adrx` kept), `output_reader_tools_are_metadata_only_only_under_a_policy` (active and invalid strip, inactive and an unrelated unknown tool keep), `copilot_cli_runtime_file_tools_are_scoped_to_copilot`, `unevaluated_shell_expansions_respect_quoting` (also leading-`]` classes, zsh groups and extglobs, ANSI-C numeric escapes; subshells, `$((…))`, `<(…)`, array assignments kept), the shell fixture's brace/class vectors (quoted, escaped, `${…}`, `{}`, `[ … ]`, `HEAD@{1}` controls kept); `quoted_scripts_in_string_commands_are_read_like_command_lines` (`sh -c`, `timeout … bash -c`, `"$(…)"`, `NAME="$(…)"`, backquotes, two nested shells and an inline-interpreter literal drop; `bash -c 'cargo test'` and `"$(git rev-parse HEAD)"` kept; four levels read, a fifth metadata-only), `inline_interpreter_code_is_metadata_only_under_an_active_policy` (inline code metadata-only, kept with no policy; modules, script files and `grep -e` unaffected), `git_object_names_are_path_candidates` (`HEAD:`, `:`, `:N:` and `@{n}` names drop, also from a subdirectory; drive letters, URLs, `NAME=a:b` and flags are not object names; a public object name kept), `ansi_c_strings_and_escaped_letters_are_read_like_the_shell`, `antigravity_run_command_resolves_arguments_from_its_cwd` (absolute and relative `Cwd` drop, a public `Cwd` kept, another agent's `Cwd` key ignored), and the shell fixture's quoted-script, git-object, ANSI-C, escaped-letter and inline-interpreter vectors with their controls (`cargo test`, `git status`/`log`, `pytest`, `python3 -m pytest`, `node build.js`, `npm run test`, a quoted commit message with braces); `router.rs` `capture_protocol_active_keep_of_unprovable_output_is_stripped`; `hook.rs` `excluded_content_cannot_reach_the_spool_through_unevaluated_tool_shapes` (directory entries and Copilot `view`/`create` never spool, readers and brace shells spool without content, public controls spool with it); `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections, including the GHSA-vh98 and Gemini `read_many_files`/`run_shell_command` vectors, plus unsupported-glob, empty-list and recursive-`**` checks, against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job); `hook.rs` `check_capture_refuses_partial_scope_and_excluded_content` (ignored-path and partial-scope violations refused, complete public-path control passes), `check_capture_bounds_marker_hints_and_refuses_oversized_scope` (513-byte hints refused, 512-byte control passes; native routing preserved); **`backfill.rs` `backfill_never_posts_tool_content_the_capture_policy_excludes`** (planted Claude transcript: the excluded read's call and output never reach `/hook/batch`, a malformed read posts only the metadata-only body, public read control posted) and **`run.rs` `ledger_upload_drops_tool_content_the_capture_policy_excludes`** (excluded call and output absent from the finish request, public control present, cursor still advances), both failing with the guard removed; `transcript_capture.rs` `an_excluded_read_drops_its_call_and_result_by_id`, `id_less_results_take_the_strictest_call_of_their_turn`, `unrecoverable_arguments_and_orphan_results_fail_closed_under_a_policy`, `a_call_into_another_checkout_honors_its_policy`, `ledger_events_are_dropped_or_stripped_before_upload`, `without_a_policy_every_event_is_kept` (control); `capture_policy.rs` `tool_call_payload_reaches_the_live_decision_for_every_supported_agent`; **`backfill.rs` `allowlist_mode_backfills_nothing_from_an_unmarked_checkout`** (no request reaches the server; marked-checkout and denylist controls do), **`run.rs` `ledger_upload_under_allowlist_mode_carries_nothing_from_an_unmarked_checkout`** (finish carries no prompt or tool content; marked and denylist controls upload both), `transcript_capture.rs` `allowlist_mode_admits_nothing_from_an_unmarked_checkout`, all failing with the admission gate removed | STRONG with listed residuals. Matching is lexical by design, so these stay open: shell variables (`$VAR`, `FILE=… sh -c 'cat $FILE'`) and the output of a command substitution, a `cd` inside the command, a script read from a file or a heredoc fed to an interpreter (read only for the words it spells out), git's repository root approximated by the marker directory, symlinks (paths are never resolved on disk), a recursive search of a parent directory (`grep -r x docs`, `rg x`) through a shell, and tools the matcher does not list, which keep their current unknown-tool behavior. Transcript imports add: assistant prose quoting an excluded file is kept (as live prompt/assistant capture keeps it), harnesses whose hook schema the matcher does not read (Crush, Kimi Code) keep their tool events as live capture would, and id-less adapters over-drop a whole turn's results when one call is excluded; a metadata-only import keeps an `event_id` (ledger) and `ingest_key` (backfill) derived from a SHA-256 of the original content plus session and record ids, left in place because those ids are the retry-dedupe keys and a content-free id would merge distinct events — it only confirms a guess of low-entropy content. Under allowlist mode a refused checkout's `ai-memory run` still records repository checkpoint metadata (HEAD, branch, a status hash and changed-path names, never file content), which the run also sends at launch. Re-splitting quoted words over-drops a quoted message naming an ignored path, and inline interpreter code is metadata-only under an active policy. Mitigation: allowlist capture mode (`install-hooks --capture-mode allowlist`) for sensitive projects. Bite checks: removing the nested re-split, the git object path or its marker-root base, Antigravity's `Cwd` key, the leading-`]` rule, either zsh-group rule, ANSI-C decoding or its numeric-escape rule, the `\o` reading, the inline-code rule, the nesting-depth rule or the nested-script scan each fails the Rust tests, and each TypeScript counterpart fails the Node evidence test |+| 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, and every word that holds several words, such as a quoted `sh -c` script or a `"$(…)"` substitution, re-split to four levels by `ShellCommand::split`/`push_nested_words`, a deeper script metadata-only; ANSI-C strings decoded and a backslash before an ordinary letter dropped (`shell_words`, `push_word`); backslash-newline continuations joined (`shell_words`); a parameter default's operand, a value glued to a short flag and a `file:` URL's path read as candidates (`parameter_operands`, `shell_arguments`, `file_url_path`); PowerShell and cmd escape characters read out under the `PowerShell` tool or on a Windows host (`without_windows_escapes`); `~+` resolved to the cwd and a `~-`/`~N`/`~name` prefix metadata-only (`names_unknown_directory`); shell and interpreter options that take a value skipped while looking for a `-c` script or inline code (`takes_shell_value`, `runs_inline_code`, which also lists `lua`/`Rscript`/`osascript -e`, and `su -c`/`script -c` as script runners); paths compared without regard to case on a macOS host (`fold_case`, set by `resolve`; client-only, the server's sentinel re-inspection never depends on it); the path of a git `REV:path` object name tried from the cwd and the marker directory (`git_object_path`); Antigravity `run_command` resolved from its `Cwd`); an invalid marker makes file and shell calls metadata-only; an active one makes a shell call metadata-only when a word uses unquoted brace expansion, a bracket class (a leading `]` included), a zsh glob group or extglob, or a numeric/control ANSI-C escape (`has_unevaluated_expansion`, also run on scripts given to `sh -c`, `eval` or a substitution), or when it runs inline interpreter code (`runs_inline_code`: `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `deno eval`), and either makes tools that read back an earlier command's output metadata-only (`reads_earlier_output`: `BashOutput`, `TaskOutput`, `write_stdin`, `process`, `read_bash`/`write_bash` and PowerShell twins); the server admits a metadata-only shell or unknown-family body only under an active or invalid marker, with no paths and an `extracted` state (`router.rs` `metadata_protocol_is_legal`), and its own re-inspection strips an older client's keep for either; a Gemini `read_many_files` literal entry is also read as `entry/**` (`glob_matches_below`), and Copilot CLI's runtime `view`/`create`/`str_replace_editor` are file tools for that agent only (`agent_family`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`, `captureShellSplit`, `captureUnevaluatedExpansion`, `captureInlineCode`, `captureGitObjectPath`, `captureGlobBelow`, the `reader` flag). Candidate/argument flavor (`Flavor::Posix` vs `Flavor::Windows`, used to pick which `ignore_paths` patterns even apply) is derived from the **host** (the cwd), never from the candidate string alone — a POSIX-host candidate spelled with a leading `//` is collapsed to a single `/` before flavor detection (`normalize_candidate`; TS `captureNormalize`'s `windowsHost` parameter, sourced from `captureHostWindows(cwd)`), fixing GHSA-vh98 (a `//`-prefixed candidate used to self-classify as `Flavor::Windows` regardless of host, matching zero POSIX patterns and being captured instead of dropped); a genuine Windows/UNC host (cwd itself windows-flavored) is unaffected; `hook.rs` `--check-capture` preflight uses the same capture policy before any spool or spawn; transcript imports (`ai-memory backfill`, including the automatic first-boot run, and the `ai-memory run` ledger upload) apply the same decision table through `commands/transcript_capture.rs`: each recorded tool call is rebuilt in its agent's hook shape (`capture_policy.rs` `tool_call_payload`) and inspected by the checkout's policy, and by a reroute destination's policy too; a Drop removes the call and its result (paired by native id, else the strictest call of the turn; a call-less result drops under a policy), metadata-only posts the hook's metadata-only body with its protocol (backfill) or a withheld placeholder (ledger), and a shell call whose recorded arguments cannot be parsed drops; both imports also apply the hook's repository admission gate (`hook.rs` `checkout_admits_capture`: persisted capture mode, marker opt-in, readable routing marker — the same helpers the hook's own gate uses), so under allowlist mode an unmarked checkout imports nothing, prompts included: `backfill` stops before contacting the server and the run ledger finishes with no events (GHSA-gcpc-88hm-3xqr) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec` and `PowerShell`, `workdir`, glob directories, Windows paths, and a POSIX-host leading-`//` command via `/{root}/docs/adr/x.md`), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `claude_code_powershell_honors_ignored_paths_on_a_windows_host` (#1186: Windows-spelled and `-Param:value` paths drop, public-path and `git status` controls kept, invalid marker metadata-only), `gemini_cli_shell_and_read_many_files_honor_ignored_paths` (Gemini `run_shell_command` incl. `dir_path`/`directory`, and `read_many_files` globs via `match_globs`: excluded literal, mixed public+excluded, `docs/*`, recursive `**` and case-variant entries drop, an `exclude` list cannot rescue them, unsupported glob syntax and malformed lists are metadata-only, public entries kept, POSIX and Windows hosts) and `globstar_reaches_lets_double_star_span_any_depth`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors, and `normalization`'s leading-`//` POSIX vectors alongside the kept Windows-cwd UNC vectors as the no-regression control); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell admitted for an unevaluated expansion, inactive refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`, **`a_leading_double_slash_candidate_does_not_escape_posix_ignore_paths_via_flavor_mismatch`** (GHSA-vh98 adversarial: attempts the `//repo/secret/...` violation on a POSIX host, proves it now drops, with a plain-single-slash control and a Windows-hosted genuine-UNC control both still correct — fails on the pre-fix code); `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`, `gemini_cli_shell_and_read_many_files_exclusions_drop_before_spool` (pre- and post-tool events with an excluded path are never spooled; public controls spool with their family); `capture_policy.rs` `read_many_files_directory_entries_cannot_reach_ignored_paths` (shared `read_many_files_directories` vectors: `docs`, `.`, `./`, `docs/`, case and `..` variants drop; `src`, `README.md`, `docs/adrx` kept), `output_reader_tools_are_metadata_only_only_under_a_policy` (active and invalid strip, inactive and an unrelated unknown tool keep), `copilot_cli_runtime_file_tools_are_scoped_to_copilot`, `unevaluated_shell_expansions_respect_quoting` (also leading-`]` classes, zsh groups and extglobs, ANSI-C numeric escapes; subshells, `$((…))`, `<(…)`, array assignments kept), the shell fixture's brace/class vectors (quoted, escaped, `${…}`, `{}`, `[ … ]`, `HEAD@{1}` controls kept); `quoted_scripts_in_string_commands_are_read_like_command_lines` (`sh -c`, `timeout … bash -c`, `"$(…)"`, `NAME="$(…)"`, backquotes, two nested shells and an inline-interpreter literal drop; `bash -c 'cargo test'` and `"$(git rev-parse HEAD)"` kept; four levels read, a fifth metadata-only), `inline_interpreter_code_is_metadata_only_under_an_active_policy` (inline code metadata-only, kept with no policy; modules, script files and `grep -e` unaffected), `git_object_names_are_path_candidates` (`HEAD:`, `:`, `:N:` and `@{n}` names drop, also from a subdirectory; drive letters, URLs, `NAME=a:b` and flags are not object names; a public object name kept), `ansi_c_strings_and_escaped_letters_are_read_like_the_shell`, `antigravity_run_command_resolves_arguments_from_its_cwd` (absolute and relative `Cwd` drop, a public `Cwd` kept, another agent's `Cwd` key ignored), `windows_escape_characters_are_read_on_a_windows_host` (caret and backquote spellings drop on a Windows host, public controls kept, a POSIX host reads both literally), `a_case_folding_host_matches_paths_without_regard_to_case` (file tool and shell drop with folding, keep without, public control kept; folding injected through `resolve_for_host` so it runs on every CI OS), the shell fixture's continuation, PowerShell/cmd escape, option-value, runner, interpreter, glued-flag, `file:` URL, tilde, parameter-default and `fold_case` vectors with their controls, the near-miss controls added to `common_commands_stay_kept_under_an_active_policy`, and the shell fixture's quoted-script, git-object, ANSI-C, escaped-letter and inline-interpreter vectors with their controls (`cargo test`, `git status`/`log`, `pytest`, `python3 -m pytest`, `node build.js`, `npm run test`, a quoted commit message with braces); `router.rs` `capture_protocol_active_keep_of_unprovable_output_is_stripped`; `hook.rs` `excluded_content_cannot_reach_the_spool_through_unevaluated_tool_shapes` (directory entries and Copilot `view`/`create` never spool, readers and brace shells spool without content, public controls spool with it); `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections, including the GHSA-vh98 and Gemini `read_many_files`/`run_shell_command` vectors, plus unsupported-glob, empty-list and recursive-`**` checks, against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job); `hook.rs` `check_capture_refuses_partial_scope_and_excluded_content` (ignored-path and partial-scope violations refused, complete public-path control passes), `check_capture_bounds_marker_hints_and_refuses_oversized_scope` (513-byte hints refused, 512-byte control passes; native routing preserved); **`backfill.rs` `backfill_never_posts_tool_content_the_capture_policy_excludes`** (planted Claude transcript: the excluded read's call and output never reach `/hook/batch`, a malformed read posts only the metadata-only body, public read control posted) and **`run.rs` `ledger_upload_drops_tool_content_the_capture_policy_excludes`** (excluded call and output absent from the finish request, public control present, cursor still advances), both failing with the guard removed; `transcript_capture.rs` `an_excluded_read_drops_its_call_and_result_by_id`, `id_less_results_take_the_strictest_call_of_their_turn`, `unrecoverable_arguments_and_orphan_results_fail_closed_under_a_policy`, `a_call_into_another_checkout_honors_its_policy`, `ledger_events_are_dropped_or_stripped_before_upload`, `without_a_policy_every_event_is_kept` (control); `capture_policy.rs` `tool_call_payload_reaches_the_live_decision_for_every_supported_agent`; **`backfill.rs` `allowlist_mode_backfills_nothing_from_an_unmarked_checkout`** (no request reaches the server; marked-checkout and denylist controls do), **`run.rs` `ledger_upload_under_allowlist_mode_carries_nothing_from_an_unmarked_checkout`** (finish carries no prompt or tool content; marked and denylist controls upload both), `transcript_capture.rs` `allowlist_mode_admits_nothing_from_an_unmarked_checkout`, all failing with the admission gate removed | STRONG with listed residuals. Matching is lexical by design, so these stay open: shell variables (`$VAR`, `FILE=… sh -c 'cat $FILE'`) and the output of a command substitution, a `cd` inside the command, a script read from a file or a heredoc fed to an interpreter (read only for the words it spells out), git's repository root approximated by the marker directory, symlinks (paths are never resolved on disk), a recursive search of a parent directory (`grep -r x docs`, `rg x`) through a shell, a tool's own directory option (`git -C`), script runners and interpreters the matcher does not list (their words are still read, but expansion or inline code in them is not recognized), a value glued after the first letter of a short-flag cluster, non-ASCII percent-escapes in a `file:` URL, and tools the matcher does not list, which keep their current unknown-tool behavior. Transcript imports add: assistant prose quoting an excluded file is kept (as live prompt/assistant capture keeps it), harnesses whose hook schema the matcher does not read (Crush, Kimi Code) keep their tool events as live capture would, and id-less adapters over-drop a whole turn's results when one call is excluded; a metadata-only import keeps an `event_id` (ledger) and `ingest_key` (backfill) derived from a SHA-256 of the original content plus session and record ids, left in place because those ids are the retry-dedupe keys and a content-free id would merge distinct events — it only confirms a guess of low-entropy content. Under allowlist mode a refused checkout's `ai-memory run` still records repository checkpoint metadata (HEAD, branch, a status hash and changed-path names, never file content), which the run also sends at launch. Re-splitting quoted words over-drops a quoted message naming an ignored path, and inline interpreter code is metadata-only under an active policy. Mitigation: allowlist capture mode (`install-hooks --capture-mode allowlist`) for sensitive projects. Bite checks: removing the nested re-split, the git object path or its marker-root base, Antigravity's `Cwd` key, the leading-`]` rule, either zsh-group rule, ANSI-C decoding or its numeric-escape rule, the `\o` reading, the inline-code rule, the nesting-depth rule, the nested-script scan, the line-continuation join, the Windows escape reading, the shell-option and interpreter-option value skips, the added runners and interpreters, the glued-flag value, the `file:` URL path, the `~+` resolution, the unknown-tilde rule, the parameter-default reading or case folding each fails the Rust tests, and each TypeScript counterpart fails the Node evidence test || 11c | Capture hook ≤200ms budget (invariant #5) | `hooks/_lib.sh` capture path `curl --max-time 0.2` (context-fetch 1.0s and background drain 2.0s are separate, larger-budget paths) | none (shell-script timeout; hard to unit-test) — watch on any capture-path change | WATCH || 11d | Hook server-profile routing: a marker-selected server gets only its own capture and its own token (#992) | `ai-memory-cli/src/server_profiles.rs` `resolve` (validated `ProfileName`, strict `servers.toml` parse, `roots` required once two profiles exist, component-wise root match) and `marker.rs` `find_server_selection` (inherited down the tree, any value shape counts); `commands/hook.rs` `resolve_hook_route` drops a `Rejected` route before spool, handoff and backfill, and hands the drainer no live token for a profile route; `commands/hook_spool.rs` `static_retry_token` (a profile entry retries only with its own stored token), the loopback reroot skip, and chunk splitting on `profile`; generated TS `captureServerRouted` drops a routed repository and gates `fetchHandoff`; `hooks/_lib.sh` `ai_memory_server_routed` (flag refused by `ai_memory_post_hook`/`ai_memory_get_handoff`) and `hooks/lib/ai-memory-hook.ps1` `Test-AiMemoryServerRouted` drop it in the script hooks; `--check-capture` refuses a rejected server-profile selection without printing its token or URL | `hook.rs` `each_repository_spools_to_its_own_profile_with_its_own_token`, `a_selection_that_does_not_resolve_emits_nothing` (unknown / tokenless / outside roots / roots required / invalid name, plus a resolving control), `session_start_handoff_comes_from_the_profile_server_only`, `a_repository_without_a_server_key_keeps_the_install_default`; `hook_spool.rs` `a_profile_entry_is_never_retried_with_the_install_live_token` (server B accepts exactly the install's live token and must still not get it), `a_profile_entry_recovers_with_its_own_rotated_token` (control), `a_profile_entry_on_a_dead_loopback_port_is_not_rerouted_to_the_default`, `profile_and_default_entries_at_one_address_ride_separate_batches`; `server_profiles.rs` roots/registry/name tests; `marker.rs` `nested_markers_without_server_inherit_the_ancestor_selection`; `install_hooks.rs` `generated_integrations_fail_closed_on_a_server_profile_marker`, `openclaw_plugin.rs` `openclaw_plugin_fails_closed_on_a_server_profile_marker`, and the `server-routed-*` checks in `generated_capture_policy_v1_node_runtime_evidence`; `hook.rs` `an_event_without_a_payload_cwd_routes_by_the_process_cwd`, `a_refused_route_prints_nothing_for_kimi_user_prompts`; `hook_spool.rs` `a_profile_entry_is_not_retried_with_a_token_issued_for_a_new_url`; `server_profiles.rs` `changing_the_url_without_a_token_discards_the_old_token`, `omitted_roots_keep_the_registered_ones`; `marker.rs` `outside_home_the_walk_reaches_a_marker_above_the_checkout_root`, `encoding_noise_cannot_hide_a_server_key`, `an_unreadable_marker_is_a_refused_selection`; `backfill.rs` `a_spawned_backfill_authenticates_like_the_hook_that_spawned_it`; `tests/hooks/test_lib.sh` "server profiles (#992)" section; `hook.rs` `a_mixed_spool_drains_each_event_only_to_its_own_server` (two token-gated servers, one spool, one drain: each server receives exactly its own event with exactly its own bearer); `tests/suite/server_profiles.rs` (the built binary: `server add` → `hook` spools to the profile with its token, unknown profile spools nothing, `uninstall` removes the tokens; `two_real_servers_each_receive_only_their_own_repository` runs two real `ai-memory serve` children with different root tokens and checks on each server which repository landed there); `ai-memory-hooks` `powershell_server_routed.rs` `server_routed_guard_mirrors_the_native_walk` (runs `Test-AiMemoryServerRouted` under real PowerShell: inherited, BOM, look-alike keys, the `$HOME` boundary with its control, past a checkout root outside home, current directory); `hook.rs` `a_selection_that_does_not_resolve_emits_nothing` (rejected routes refuse preflight; resolved profile control passes); `tests/hooks/test_lib.sh` and `powershell_home.rs` `a_trailing_separator_on_home_keeps_the_walk_boundary` (a `$HOME` ending in `/` or `\` keeps both script walks at home: a `server` marker above it routes nothing, with a root-home control that does) | STRONG for native hooks, generated TS, `.sh` and `.ps1` hooks. Known gap: an older binary draining a shared spool ignores `profile` || 11e | Native self-upgrade archive confinement (#1025) | `ai-memory-cli/src/commands/upgrade.rs` normalizes every tar/zip path, rejects links and special entries, extracts only the binary and `hooks/`, accepts only the exact non-runtime support layout emitted by `release.yml`, and caps both entry count and declared expanded bytes before writing | `upgrade.rs` `release_workflow_support_assets_are_exact_and_ignored` (shipped support paths admitted, near-miss docs/packaging/template paths refused), `extracts_archive_built_like_release_yml` and `extracts_zip_happy_path_with_hooks` (real workflow-shaped archives succeed but support assets are not written), `validate_rejects_path_traversal`, `zip_extract_rejects_path_traversal`, `tar_extract_rejects_declared_expansion_past_limit`, with binary/hooks extraction as the legitimate control | STRONG |