Skip to content

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

Rust

fix(capture): close output-spool, cross-checkout, URL, default and tilde gaps

AkitaOnRails18440871abc6
diff --git a/Cargo.lock b/Cargo.lock
index 1c8d0413..f97ccf57 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -162,6 +162,7 @@ dependencies = [
"async-trait",
"axum",
"git2",
+ "icu_normalizer",
"jiff",
"rusqlite",
"serde",
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 494add12..12f4fb64 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -20,8 +20,8 @@ use std::time::Duration;
use ai_memory_core::{AgentKind, ManagedRunId, SessionId};
use ai_memory_hooks::capture_policy::metadata_only_body;
use ai_memory_hooks::{
- CaptureDisposition, CaptureMode, HookEvent, PolicyState, absolute_tool_location_paths,
- repository_admits_capture,
+ CaptureDecision, CaptureDisposition, CaptureMode, CapturePolicy, CaptureSource, HookEvent,
+ PolicyState, absolute_tool_location_paths, capture_lookup_locations, repository_admits_capture,
};
use ai_memory_llm::OidcToken;
@@ -33,8 +33,8 @@ use sha2::{Digest as _, Sha256};
use super::hook_capture::{
build_client, canonical_context, capture_policy, extract_cwd, get_handoff, hook_scope,
- marker_query_suffix, marker_query_suffix_without_briefing, marker_requests_briefing,
- resolve_cwd_with_fallbacks, url_encode,
+ marker_capture_policy, marker_query_suffix, marker_query_suffix_without_briefing,
+ marker_requests_briefing, resolve_cwd_with_fallbacks, url_encode,
};
use super::hook_drain_process;
use super::hook_spool;
@@ -753,11 +753,19 @@ where
let inspection_cwd = policy_cwd.as_deref().map(lexical_capture_cwd);
let policy = policy_cwd.as_deref().map(capture_policy);
let decision = policy.as_ref().filter(|_| tool_event).map(|policy| {
- policy.inspect(
- AgentKind::from_wire(&args.agent),
- &json,
- inspection_cwd.as_deref().unwrap_or(""),
- )
+ let agent = AgentKind::from_wire(&args.agent);
+ let inspection_cwd = inspection_cwd.as_deref().unwrap_or("");
+ let decision = policy.inspect(agent, &json, inspection_cwd);
+ // Another checkout's `ignore_paths` protect its files from a call
+ // made here too (`cat ../other/secret.env`).
+ if decision.protocol().disposition() == CaptureDisposition::Drop {
+ return decision;
+ }
+ let own_marker = policy_cwd.as_deref().and_then(crate::marker::find_marker);
+ match foreign_capture_decision(agent, &json, inspection_cwd, own_marker.as_deref()) {
+ Some(foreign) => decision.stricter(foreign),
+ None => decision,
+ }
});
let dd = resolve_data_dir_with(data_dir.as_deref(), &runtime_env);
// Precedence: an explicit flag (tests, one-off runs) wins; otherwise the
@@ -1295,6 +1303,84 @@ pub(crate) fn tool_location_routing_cwd(
source_keeps.then(|| dir.to_string_lossy().into_owned())
}
+/// How many distinct directories, and markers other than the event's own, one
+/// tool call may make [`foreign_capture_decision`] look up.
+const MAX_FOREIGN_DIRECTORIES: usize = 256;
+const MAX_FOREIGN_MARKERS: usize = 16;
+
+/// The stricter decision of every other marker that governs a location the
+/// tool call names: a file-tool target, or a path a shell argument spells,
+/// resolved from the event's `cwd`. A checkout's `ignore_paths` must hold
+/// when the call is made from another checkout or an unmarked directory
+/// (`cat ../a/secret.env`), so each such marker's policy inspects the call
+/// as the event's own does. `None` when no other marker governs one.
+///
+/// Markers are found by the same lexical walk as the event's (no
+/// canonicalization), from the nearest existing directory of each location,
+/// with each directory looked up once. A call naming more locations,
+/// directories or markers than the bounds is unprovable and gets the
+/// fail-closed decision of an invalid policy.
+pub(crate) fn foreign_capture_decision(
+ agent: AgentKind,
+ raw: &serde_json::Value,
+ inspection_cwd: &str,
+ own_marker: Option<&Path>,
+) -> Option<CaptureDecision> {
+ let unprovable = || {
+ Some(
+ CapturePolicy::resolve(CaptureSource::Invalid, inspection_cwd, None).inspect(
+ agent,
+ raw,
+ inspection_cwd,
+ ),
+ )
+ };
+ let home = home_dir();
+ let Some(locations) = capture_lookup_locations(
+ agent,
+ raw,
+ inspection_cwd,
+ home.as_deref().and_then(Path::to_str),
+ ) else {
+ return unprovable();
+ };
+ let mut directories: std::collections::HashMap<PathBuf, Option<PathBuf>> =
+ std::collections::HashMap::new();
+ let mut markers: Vec<PathBuf> = Vec::new();
+ for location in locations {
+ let Some(dir) = existing_target_dir(Path::new(&location)) else {
+ continue;
+ };
+ let marker = match directories.get(&dir) {
+ Some(marker) => marker.clone(),
+ None => {
+ if directories.len() == MAX_FOREIGN_DIRECTORIES {
+ return unprovable();
+ }
+ let marker = crate::marker::find_marker(&dir.to_string_lossy());
+ directories.insert(dir, marker.clone());
+ marker
+ }
+ };
+ let Some(marker) = marker else {
+ continue;
+ };
+ if Some(marker.as_path()) == own_marker || markers.contains(&marker) {
+ continue;
+ }
+ if markers.len() == MAX_FOREIGN_MARKERS {
+ return unprovable();
+ }
+ markers.push(marker);
+ }
+ markers
+ .iter()
+ .map(|marker| {
+ marker_capture_policy(marker, inspection_cwd).inspect(agent, raw, inspection_cwd)
+ })
+ .reduce(CaptureDecision::stricter)
+}
+
/// Where one event is delivered (#992).
#[derive(Debug)]
enum HookRoute {
@@ -3063,6 +3149,145 @@ mod tests {
}
}
+ /// Adversarial: checkout A's `ignore_paths` hold for a call made from
+ /// checkout B or from an unmarked directory, by a shell argument
+ /// (relative or absolute) or a file tool, whatever B's own policy says.
+ /// Controls: A's public files, and B's own files, are still captured.
+ #[tokio::test]
+ async fn another_checkouts_exclusions_hold_for_a_call_made_elsewhere() {
+ let tmp = tempfile::tempdir().unwrap();
+ let a = tmp.path().join("a");
+ let b = tmp.path().join("b");
+ let bare = tmp.path().join("unmarked");
+ let broken = tmp.path().join("broken");
+ for dir in [&a, &b, &bare, &broken] {
+ std::fs::create_dir_all(dir).unwrap();
+ }
+ std::fs::write(
+ a.join(".ai-memory.toml"),
+ "project = \"a\"\n[capture]\nignore_paths = [\"secrets.env\"]\n",
+ )
+ .unwrap();
+ std::fs::write(b.join(".ai-memory.toml"), "project = \"b\"\n").unwrap();
+ std::fs::write(broken.join(".ai-memory.toml"), "[capture\n").unwrap();
+ let event = |agent_cwd: &Path, tool: &str, input: serde_json::Value| {
+ serde_json::json!({
+ "session_id": "cross",
+ "cwd": agent_cwd,
+ "tool_name": tool,
+ "tool_input": input,
+ "tool_response": {"stdout": "SENTINEL_MUST_NOT_BE_SPOOLED"}
+ })
+ };
+ let secret = a.join("secrets.env");
+ let cases = [
+ (
+ "relative shell",
+ "claude-code",
+ event(
+ &b,
+ "Bash",
+ serde_json::json!({"command": "cat ../a/secrets.env"}),
+ ),
+ ),
+ (
+ "absolute shell",
+ "claude-code",
+ event(
+ &b,
+ "Bash",
+ serde_json::json!({"command": format!("cat {}", secret.display())}),
+ ),
+ ),
+ (
+ "unmarked hermes terminal",
+ "hermes",
+ event(
+ &bare,
+ "terminal",
+ serde_json::json!({"command": format!("cat {}", secret.display())}),
+ ),
+ ),
+ (
+ "glob shell",
+ "claude-code",
+ event(&b, "Bash", serde_json::json!({"command": "cat ../a/*.env"})),
+ ),
+ ];
+ for (name, agent, raw) in cases {
+ let data_dir = tmp.path().join(format!("data-{}", name.replace(' ', "-")));
+ assert!(
+ spool_one(&data_dir, agent, None, &raw).await.is_empty(),
+ "{name}: A's exclusion must drop the event"
+ );
+ }
+ // A broken marker over the target fails closed: metadata-only.
+ let raw = event(
+ &b,
+ "Bash",
+ serde_json::json!({"command": "cat ../broken/x.md"}),
+ );
+ let entries = spool_one(&tmp.path().join("data-broken"), "claude-code", None, &raw).await;
+ assert_eq!(entries.len(), 1);
+ assert!(
+ !entries[0].body.contains("SENTINEL_MUST_NOT_BE_SPOOLED"),
+ "{}",
+ entries[0].body
+ );
+ assert!(
+ entries[0].body.contains("\"metadata-only\""),
+ "{}",
+ entries[0].body
+ );
+ // More markers than the bound is unprovable: metadata-only.
+ let mut many = String::from("cat");
+ for index in 0..=MAX_FOREIGN_MARKERS {
+ let dir = tmp.path().join(format!("m{index}"));
+ std::fs::create_dir_all(&dir).unwrap();
+ std::fs::write(dir.join(".ai-memory.toml"), "project = \"m\"\n").unwrap();
+ many.push_str(&format!(" ../m{index}/x.md"));
+ }
+ let raw = event(&b, "Bash", serde_json::json!({"command": many}));
+ let entries = spool_one(&tmp.path().join("data-many"), "claude-code", None, &raw).await;
+ assert_eq!(entries.len(), 1);
+ assert!(!entries[0].body.contains("SENTINEL_MUST_NOT_BE_SPOOLED"));
+ // Controls.
+ for (name, raw) in [
+ (
+ "public shell",
+ event(
+ &b,
+ "Bash",
+ serde_json::json!({"command": "cat ../a/public.md README.md"}),
+ ),
+ ),
+ (
+ "own file",
+ event(
+ &b,
+ "Bash",
+ serde_json::json!({"command": "cat secrets.env"}),
+ ),
+ ),
+ (
+ "few markers",
+ event(
+ &b,
+ "Bash",
+ serde_json::json!({"command": "cat ../m0/x.md ../m1/x.md"}),
+ ),
+ ),
+ ] {
+ let data_dir = tmp.path().join(format!("data-{}", name.replace(' ', "-")));
+ let entries = spool_one(&data_dir, "claude-code", None, &raw).await;
+ assert_eq!(entries.len(), 1, "{name}");
+ assert!(
+ entries[0].body.contains("SENTINEL_MUST_NOT_BE_SPOOLED"),
+ "{name}"
+ );
+ }
+ }
+
#[tokio::test]
async fn shell_command_reading_an_ignored_path_is_dropped_before_spool() {
for (command, spooled) in [("cat ./secret/*.md | head", 0), ("cat public/readme.md", 1)] {
diff --git a/crates/ai-memory-cli/src/commands/hook_capture.rs b/crates/ai-memory-cli/src/commands/hook_capture.rs
index 027099d6..b79cdc41 100644
--- a/crates/ai-memory-cli/src/commands/hook_capture.rs
+++ b/crates/ai-memory-cli/src/commands/hook_capture.rs
@@ -24,16 +24,23 @@ use ai_memory_hooks::{
/// Resolve the nearest marker's capture policy without changing routing parsing.
/// Root-level marker keys are intentionally ignored here; only `[capture]` is strict.
pub fn capture_policy(cwd: &str) -> CapturePolicy {
- let home = home_dir();
let Some(marker) = find_marker(cwd) else {
+ let home = home_dir();
return CapturePolicy::resolve(
CaptureSource::Absent,
cwd,
home.as_deref().and_then(Path::to_str),
);
};
+ marker_capture_policy(&marker, cwd)
+}
+
+/// The capture policy one marker file declares; `cwd` stands in for its
+/// directory only when that cannot be read as text.
+pub(crate) fn marker_capture_policy(marker: &Path, cwd: &str) -> CapturePolicy {
+ let home = home_dir();
let marker_dir = marker.parent().and_then(Path::to_str).unwrap_or(cwd);
- match read_capture_config(&marker) {
+ match read_capture_config(marker) {
Ok(config) => CapturePolicy::resolve(
CaptureSource::Parsed(&config),
marker_dir,
diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rs
index 00caea8d..125c24e5 100644
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@ -240,8 +240,14 @@ 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`.
+// Bounds on the other markers one call may make the policy read; mirror `capture_lookup_locations` and `foreign_capture_decision`.
+const CAPTURE_MAX_LOOKUP_LOCATIONS = 4096;
+const CAPTURE_MAX_FOREIGN_DIRECTORIES = 256;
+const CAPTURE_MAX_FOREIGN_MARKERS = 16;
+// macOS's default filesystem ignores case and Unicode composition, so `NOTES/X.md` reads `notes/x.md`; mirrors `fold_case`.
let captureFoldCase = typeof process !== "undefined" && process.platform === "darwin";
+// A path as a case-folding host compares it: NFC, then the full lowercase mapping; mirrors `fold_path`.
+function captureFold(path: string): string { return captureFoldCase ? path.normalize("NFC").toLowerCase() : path; }
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" };
@@ -261,8 +267,9 @@ function captureJoin(base: string, child: string): string { if (/^[^A-Za-z]?:|^[
function captureValidGlob(p: string): boolean { return !!p && [...p].length <= CAPTURE_MAX_PATTERN_CHARS && !/[!{}\[\]()|^$%]/.test(p) && !p.includes("${") && !p.includes("***") && !p.replace(/\\/g, "/").split("/").includes("..") && (!p.startsWith("~") || p.startsWith("~/")) && !/^[^A-Za-z]?:/.test(p) && !/^[A-Za-z]:[^/\\]/.test(p); }
function captureParseArray(value: string): string[] | undefined { let i = 0; const out: string[] = []; const ws = () => { while (/\s/.test(value[i] ?? "")) i++; }; const basic = { b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", '"': '"', "\\": "\\" } as Record<string, string>; ws(); if (value[i++] !== "[") return undefined; for (;;) { ws(); if (value[i] === "]") { i++; ws(); return i === value.length ? out : undefined; } const quote = value[i++]; if (quote !== '"' && quote !== "'") return undefined; let s = ""; for (;;) { if (i >= value.length) return undefined; const c = value[i++]; if (c === quote) break; if (c === "\\" && quote === '"') { const e = value[i++]; if (e in basic) s += basic[e]; else if (e === "u" || e === "U") { const count = e === "u" ? 4 : 8; const hex = value.slice(i, i + count); if (!new RegExp(`^[0-9A-Fa-f]{${count}}$`).test(hex)) return undefined; const n = Number.parseInt(hex, 16); if (n > 0x10ffff || (n >= 0xd800 && n <= 0xdfff)) return undefined; s += String.fromCodePoint(n); i += count; } else return undefined; } else if (c === "\n" || c === "\r") return undefined; else s += c; } out.push(s); ws(); if (value[i] === ",") { i++; continue; } if (value[i] === "]") continue; return undefined; } }
function captureHostWindows(path: string): boolean { return path.startsWith("\\\\") || path.startsWith("//") || /^[A-Za-z]:/.test(path); }
-function captureConfig(cwd: string | undefined): CaptureConfig {
- const marker = findMarker(cwd);
+function captureConfig(cwd: string | undefined): CaptureConfig { return captureConfigAt(findMarker(cwd), cwd); }
+// The policy one marker declares, for an event reported from `cwd`.
+function captureConfigAt(marker: string | undefined, cwd: string | undefined): CaptureConfig {
const candidateBase = captureNormalize(cwd ? resolve(cwd) : "")?.path ?? "";
// Host flavor comes from the cwd STRING itself, never from `resolve(cwd)`:
// `resolve` re-roots a drive/UNC-shaped cwd through the real OS's own path
@@ -312,8 +319,9 @@ function captureConfig(cwd: string | undefined): CaptureConfig {
: /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(source)
? source
: captureJoin(markerBase, source);
- const normalized = captureNormalize(expanded);
- if (!normalized) return undefined;
+ const parsed = captureNormalize(expanded);
+ if (!parsed) return undefined;
+ const normalized = { path: captureFold(parsed.path), windows: parsed.windows };
return { path: normalized.path, windows: normalized.windows, directory: normalized.path.endsWith("/**") ? (normalized.path.slice(0, -3) || "/") : undefined, prefix: captureLiteralPrefix(normalized.path) };
});
if (patterns.some((p) => !p)) return { state: "invalid", patterns: [], base: candidateBase, windowsHost };
@@ -342,18 +350,24 @@ function captureShellCommand(args: Record<string, unknown> | undefined): string
// a script nested deeper is opaque. Mirrors `ShellCommand::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); }
+// shell knows, which makes the command unprovable. Each word carries whether a
+// `~` in it was outside quotes: a quoted tilde, or one in an argv element or a
+// quoted message, is literal, except under PowerShell, which reads `~` itself.
+type CaptureSplit = { words: [string, boolean][]; opaque: boolean };
+function captureShellSplit(command: string | string[], windows = false): CaptureSplit { const split: CaptureSplit = { words: [], opaque: false }; if (typeof command === "string") { split.opaque = captureUnevaluatedExpansion(command); captureNestedWords(captureMarkedWords(command), CAPTURE_MAX_SHELL_NESTING, split); const plain = windows ? captureWithoutWindowsEscapes(command) : undefined; if (plain !== undefined) captureNestedWords(captureMarkedWords(plain), CAPTURE_MAX_SHELL_NESTING, split); } else { split.opaque = command.some((item) => captureUnevaluatedExpansion(item)) || captureInlineCode(command); command.forEach((item, index) => { const script = captureShellScript(command, index); captureArgvItem(item, script, split); const plain = windows ? captureWithoutWindowsEscapes(item) : undefined; if (plain !== undefined) captureArgvItem(plain, script, split); }); } if (windows) for (const word of split.words) word[1] = true; if (split.words.some(([word, tilde]) => tilde && captureShellArguments(word).some(([argument]) => captureUnknownDirectory(argument)))) split.opaque = true; return split; }
+function captureArgvItem(item: string, script: boolean, split: CaptureSplit): void { const tokens = captureMarkedWords(item); if (tokens.length === 1 && tokens[0][0] === item) { capturePushWord(item, false, split); return; } if ([...item].length <= 256) split.words.push([item, false]); captureNestedWords(captureLiteralTildes(tokens, script), CAPTURE_MAX_SHELL_NESTING - 1, split); }
+// Only a script a shell runs expands a tilde; mirrors `literal_tildes`.
+function captureLiteralTildes(tokens: [string, boolean][], script: boolean): [string, boolean][] { return script ? tokens : tokens.map(([token]) => [token, false] as [string, boolean]); }
// 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`, 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; }
+// Only a script a shell runs expands braces, classes and tildes; a quoted message or pattern does not.
+function captureNestedWords(words: [string, boolean][], depth: number, split: CaptureSplit): void { const texts = words.map(([word]) => word); if (captureInlineCode(texts)) split.opaque = true; words.forEach(([word, tilde], index) => { capturePushWord(word, tilde, split); const tokens = captureMarkedWords(word); if (tokens.length === 1 && tokens[0][0] === word) return; if (depth === 0) { split.opaque = true; return; } const script = word.includes("$(") || word.includes("`") || captureShellScript(texts, index); if (script && captureUnevaluatedExpansion(word)) split.opaque = true; captureNestedWords(captureLiteralTildes(tokens, script), depth - 1, split); }); }
+// Also adds the POSIX reading of a word with `\o` escapes, which the shell reads as `o`, and the reading of each with every parameter default (`${X:-docs/x.md}`) replaced by its operand; a default nested deeper than the matcher reads makes the command unprovable.
+function capturePushWord(word: string, tilde: boolean, split: CaptureSplit): void { capturePushReading(word, tilde, split); 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) capturePushReading(plain, tilde, split); }
+function capturePushReading(word: string, tilde: boolean, split: CaptureSplit): void { split.words.push([word, tilde]); const operands = captureParameterOperands(word); if (operands === undefined) return; split.words.push([operands[0], tilde]); if (operands[1]) split.opaque = true; }
+// Mirrors `parameter_operands`: `${NAME:-w}`, `${NAME:=w}`, `${NAME:+w}` (or without `:`) become `w`, nested down to CAPTURE_MAX_SHELL_NESTING levels; the flag is set when one is nested deeper still.
+function captureParameterOperands(word: string): [string, boolean] | 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) return [current, false]; current = next; } return [current, captureReplaceOperands(current) !== undefined]; }
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; }
// Skips options and their values (`bash -o pipefail -c`); mirrors `is_shell_script`/`takes_shell_value`.
@@ -361,26 +375,33 @@ function captureShellScript(words: string[], index: number): boolean { let flagg
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; }
+// Each word with whether it holds a `~` outside quotes and not after a backslash; mirrors `marked_shell_words`.
+function captureMarkedWords(command: string): [string, boolean][] { const special = (c: string) => /\s/.test(c) || "|&;<>()`".includes(c); const chars = [...command]; const words: [string, boolean][] = []; let word = ""; let tilde = false; 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, tilde]); word = ""; tilde = false; inWord = false; } else { if (c === "~" && !word.endsWith("\\")) tilde = true; word += c; inWord = true; } } if (inWord) words.push([word, tilde]); 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 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))); }
+// The local path of a `file:` URL in any case, cut at its query or fragment and then 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).split(/[?#]/)[0]; 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 = /^~[\/\\]/.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; }
+function captureMatchCommand(words: [string, boolean][], config: CaptureConfig, workdir?: string): { match: boolean | undefined; spool: boolean } { const budget = { work: 0 }; const home = homedir(); const base = captureBase(config, workdir); let spool = false; for (const [word, tilde] of words) for (const [argument, fromRoot] of captureShellArguments(word)) { const expanded = captureExpandTilde(argument, tilde, home, base); 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; if (captureOutputSpool(candidate.path)) spool = true; const match = captureMatchCandidate(candidate, false, config, budget); if (match !== false) return { match, spool }; } } return { match: false, spool }; }
+// The directory a shell tool's relative arguments resolve from; mirrors `command_base`.
+function captureBase(config: CaptureConfig, workdir?: string): string { return workdir === undefined ? config.base : /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(workdir) ? workdir : config.base && captureJoin(config.base, workdir); }
+// A leading unquoted `~/` (PowerShell `~\`) is home and `~+` the working directory; mirrors `expand_tilde`.
+function captureExpandTilde(argument: string, tilde: boolean, home: string, base: string): string { return !tilde ? argument : /^~[\/\\]/.test(argument) ? captureJoin(home, argument.slice(2)) : argument === "~+" ? base : argument.startsWith("~+/") && base ? captureJoin(base, argument.slice(3)) : argument; }
+// A harness's saved copy of an earlier tool's output, read back like `BashOutput`: Claude Code `~/.claude/projects/<project>/<session>/tool-results/<id>.txt` and `<tmp>/claude-<uid>/<project>/<session>/tasks/<id>.output`, OpenCode `<data>/opencode/tool-output/tool_<id>`, Pi `<tmp>/pi-bash-<id>.log`; mirrors `output_spool`.
+function captureOutputSpool(path: string): boolean { const segments = path.split("/").filter(Boolean).map((segment) => segment.replace(/[A-Z]/g, (c) => c.toLowerCase())); const file = segments.pop(); if (file === undefined) return false; const parent = segments[segments.length - 1]; const claudeResults = segments.some((segment, index) => segment === "projects" && index > 0 && segments[index - 1].includes("claude") && segments.slice(index + 1).includes("tool-results")); const claudeTask = parent === "tasks" && file.endsWith(".output") && segments.some((segment) => segment.startsWith("claude")); const opencode = parent === "tool-output" && segments.length >= 2 && segments[segments.length - 2] === "opencode"; const pi = file.startsWith("pi-bash-") && file.endsWith(".log"); return claudeResults || claudeTask || opencode || pi; }
// 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 || 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 captureMatchCandidate(raw: { path: string; windows: boolean }, toolGlob: boolean, config: CaptureConfig, budget: { work: number }): boolean | undefined { const candidate = { path: captureFold(raw.path), windows: raw.windows }; 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; 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
@@ -398,7 +419,15 @@ 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 || 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 }; }
+type CaptureTool = ReturnType<typeof captureTool>;
+// One policy's disposition for one call, shared by the event's own marker and every other marker it reaches.
+function captureDecide(tool: CaptureTool, config: CaptureConfig): CaptureDisposition { if (config.state === "invalid" && (tool.family === "file" || tool.shell || tool.reader)) return "metadata-only"; if (config.state !== "active") return "keep"; if (tool.reader) return "metadata-only"; if (tool.family === "search-list") return "drop"; if (tool.family === "file") { if (!tool.paths) return "metadata-only"; const parsed = tool.paths.map((p) => captureNormalize(/^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(p) ? p : captureJoin(config.base, p), config.windowsHost)); if (parsed.some((p) => !p)) return "metadata-only"; const candidates = parsed as { path: string; windows: boolean }[]; if (tool.globs) { const match = captureMatchGlobs(tool.paths, candidates, config); return match === false ? "keep" : match ? "drop" : "metadata-only"; } const budget = { work: 0 }; for (const raw of candidates) { const candidate = { path: captureFold(raw.path), windows: raw.windows }; for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; if (pattern.directory && captureGlob(pattern.directory, candidate.path, pattern.windows || captureFoldCase, budget)) return "drop"; const match = captureGlob(pattern.path, candidate.path, pattern.windows || captureFoldCase, budget); if (match === undefined) return "metadata-only"; if (match) return "drop"; } } return candidates.some((candidate) => captureOutputSpool(candidate.path)) ? "metadata-only" : "keep"; } if (tool.family === "non-file" && tool.command !== undefined) { const split = captureShellSplit(tool.command, tool.powershell || config.windowsHost); const matched = captureMatchCommand(split.words, config, tool.workdir); if (matched.match !== false) return "drop"; if (split.opaque || matched.spool) return "metadata-only"; } return "keep"; }
+const captureRank: Record<CaptureDisposition, number> = { keep: 0, "metadata-only": 1, drop: 2 };
+// Every other marker governing a path the call names (a file-tool target, or a shell argument with a separator resolved from its workdir, plus that directory) inspects it too, so a checkout's `ignore_paths` hold for a call made from elsewhere. Lexical; each directory is looked up once, and past the bounds the call is unprovable. Mirrors `capture_lookup_locations` and `foreign_capture_decision`.
+function captureForeignConfigs(tool: CaptureTool, config: CaptureConfig, cwd: string | undefined, own: string | undefined): CaptureConfig[] { const invalid: CaptureConfig[] = [{ state: "invalid", patterns: [], base: config.base, windowsHost: config.windowsHost }]; const locations = new Set<string>(); const add = (path: string, base: string) => { const absolute = /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(path); if (!absolute && !base) return; const candidate = captureNormalize(absolute ? path : captureJoin(base, path), config.windowsHost); if (candidate) locations.add(candidate.windows ? candidate.path.replace(/\//g, "\\") : candidate.path); }; if (tool.family === "file") for (const path of tool.paths ?? []) add(path, config.base); else if (tool.family === "non-file" && tool.command !== undefined) { const base = captureBase(config, tool.workdir); if (base) add(base, base); const home = homedir(); for (const [word, tilde] of captureShellSplit(tool.command, tool.powershell || config.windowsHost).words) for (const [argument] of captureShellArguments(word)) { const expanded = captureExpandTilde(argument, tilde, home, base); if (/[\/\\]/.test(expanded)) add(expanded, base); } } if (locations.size > CAPTURE_MAX_LOOKUP_LOCATIONS) return invalid; const directories = new Map<string, string | undefined>(); const markers: string[] = []; for (const location of locations) { const dir = captureExistingDir(location); if (dir === undefined) continue; let marker: string | undefined; if (directories.has(dir)) marker = directories.get(dir); else { if (directories.size === CAPTURE_MAX_FOREIGN_DIRECTORIES) return invalid; marker = findMarker(dir); directories.set(dir, marker); } if (!marker || marker === own || markers.includes(marker)) continue; if (markers.length === CAPTURE_MAX_FOREIGN_MARKERS) return invalid; markers.push(marker); } return markers.map((marker) => captureConfigAt(marker, cwd)); }
+// The nearest existing directory at or above `path`; mirrors `existing_target_dir`.
+function captureExistingDir(path: string): string | undefined { let probe = path; for (;;) { try { if (statSync(probe).isDirectory()) return probe; } catch (_e) { /* not there yet */ } const parent = dirname(probe); if (parent === probe || parent === ".") return undefined; probe = parent; } }
+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 own = findMarker(cwd); let config = captureConfigAt(own, cwd); const tool = captureTool(payload); let disposition = captureDecide(tool, config); if (disposition !== "drop" && tool.family !== "search-list" && tool.family !== "unknown") for (const other of captureForeignConfigs(tool, config, cwd, own)) { const decided = captureDecide(tool, other); if (captureRank[decided] > captureRank[disposition]) { disposition = decided; config = other; } } 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)
}
@@ -2561,7 +2590,7 @@ mod tests {
let fixture = include_str!("../../../ai-memory-hooks/tests/fixtures/capture-policy.json");
let fixture = serde_json::to_string(fixture).unwrap();
let source = format!(
- r#"import {{ closeSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, writeFileSync }} from "node:fs";
+ r#"import {{ closeSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, statSync, writeFileSync }} from "node:fs";
import {{ dirname, join, resolve }} from "node:path";
import {{ homedir }} from "node:os";
@@ -2672,6 +2701,26 @@ writeFileSync(nestedMarker, '[capture]\nignore_paths = ["private/**"]\n');
markerFixtures.set(nestedCwd, nestedMarker);
expectDecision({{ tool: "edit", args: {{ path: "../private/item" }} }}, nestedCwd, "drop", "file", "extracted", 1, "nested-cwd-parent-private");
expectDecision({{ tool: "edit", args: {{ path: "private/item" }} }}, nestedCwd, "keep", "file", "extracted", 1, "nested-cwd-local-public");
+// Another checkout's exclusions hold for a call made from elsewhere, file tool or shell; mirrors `another_checkouts_exclusions_hold_for_a_call_made_elsewhere`.
+const crossA = join(markerRoot, "cross-a"); const crossB = join(markerRoot, "cross-b"); const crossBare = join(markerRoot, "cross-bare"); const crossBroken = join(markerRoot, "cross-broken");
+for (const dir of [crossA, crossB, crossBare, crossBroken]) mkdirSync(dir, {{ recursive: true }});
+for (const [dir, text] of [[crossA, '[capture]\nignore_paths = ["secrets.env"]\n'], [crossB, 'project = "b"\n'], [crossBroken, "[capture\n"]]) {{ writeFileSync(join(dir, ".ai-memory.toml"), text); markerFixtures.set(dir, join(dir, ".ai-memory.toml")); }}
+expectDecision({{ tool: "read", args: {{ path: "../cross-a/secrets.env" }} }}, crossB, "drop", "file", "extracted", 1, "cross-file-relative");
+expectDecision({{ tool: "read", args: {{ path: join(crossA, "secrets.env") }} }}, crossBare, "drop", "file", "extracted", 1, "cross-file-unmarked");
+expectDecision(bash("cat ../cross-a/secrets.env"), crossB, "drop", "non-file", "extracted", 0, "cross-shell-relative");
+expectDecision(bash(`cat ${{join(crossA, "secrets.env")}}`), crossBare, "drop", "non-file", "extracted", 0, "cross-shell-unmarked");
+expectDecision(bash("cat ../cross-a/*.env"), crossB, "drop", "non-file", "extracted", 0, "cross-shell-glob");
+expectDecision({{ tool: "bash", args: {{ command: "cat secrets.env", workdir: crossA }} }}, crossB, "drop", "non-file", "extracted", 0, "cross-shell-workdir");
+const crossBrokenResult = capturePolicy({{ ...bash("cat ../cross-broken/x.md"), output: privateBody }}, crossB);
+check(crossBrokenResult.disposition === "metadata-only" && crossBrokenResult.protocol?.policy_state === "invalid" && !JSON.stringify(crossBrokenResult.payload).includes(privateBody), "cross-broken-metadata-only");
+let crossMany = "cat"; for (let i = 0; i <= CAPTURE_MAX_FOREIGN_MARKERS; i++) {{ const dir = join(markerRoot, `cross-m${{i}}`); mkdirSync(dir, {{ recursive: true }}); writeFileSync(join(dir, ".ai-memory.toml"), 'project = "m"\n'); markerFixtures.set(dir, join(dir, ".ai-memory.toml")); crossMany += ` ../cross-m${{i}}/x.md`; }}
+check(capturePolicy(bash(crossMany), crossB).disposition === "metadata-only", "cross-too-many-markers");
+for (const [payload, cwd, label] of [[bash("cat ../cross-a/public.md README.md"), crossB, "cross-shell-public"], [{{ tool: "read", args: {{ path: "../cross-a/public.md" }} }}, crossB, "cross-file-public"], [bash("cat secrets.env"), crossB, "cross-own-file"], [bash("cat ../cross-m0/x.md ../cross-m1/x.md"), crossB, "cross-few-markers"]] as [Record<string, unknown>, string, string][]) check(capturePolicy(payload, cwd).disposition === "keep", label);
+// A macOS host folds case beyond ASCII and composes Unicode; mirrors `a_case_folding_host_matches_paths_without_regard_to_case`.
+captureFoldCase = true;
+for (const path of ["\u00e9crits/x.md", "\u00c9CRITS/x.md", "E\u0301crits/x.md"]) expectDecision({{ tool: "edit", args: {{ path }} }}, marker('[capture]\nignore_paths = ["\u00c9crits/**"]\n'), "drop", "file", "extracted", 1, `fold-unicode ${{JSON.stringify(path)}}`);
+expectDecision({{ tool: "edit", args: {{ path: "ecrits/x.md" }} }}, marker('[capture]\nignore_paths = ["\u00c9crits/**"]\n'), "keep", "file", "extracted", 1, "fold-unicode-control");
+captureFoldCase = false;
expectDecision({{ tool: "edit", args: {{ path: `${{homedir()}}/home-private/item` }} }}, marker('[capture]\nignore_paths = ["~/home-private/**"]\n'), "drop", "file", "extracted", 1, "home-expansion");
expectDecision({{ tool: "edit", args: {{ path: "case/item" }} }}, marker('[capture]\nignore_paths = ["Case/**"]\n'), "keep", "file", "extracted", 1, "posix-case");
expectDecision({{ tool: "edit", args: {{ path: "c:/SECRET/item" }} }}, marker('[capture]\nignore_paths = ["C:/secret/**"]\n'), "drop", "file", "extracted", 1, "windows-drive-case");
@@ -2780,7 +2829,7 @@ check(capturePolicy(bash("echo hi"), routedChild).disposition === "drop", "serve
// `config.state`, or this second case would be wrongly dropped.
let allowlist_module = temp.path().join("capture-policy-allowlist-evidence.ts");
let allowlist_source = format!(
- r#"import {{ closeSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, writeFileSync }} from "node:fs";
+ r#"import {{ closeSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, statSync, writeFileSync }} from "node:fs";
import {{ dirname, join, resolve }} from "node:path";
import {{ homedir }} from "node:os";
@@ -2839,7 +2888,7 @@ check(markedButEmpty.disposition === "keep", "allowlist-marker-present-empty-cap
// evidence, so they stay on disk for inspection after the run.
let temp = tempfile::tempdir().unwrap().keep();
eprintln!("capture-owner gate modules retained at {}", temp.display());
- const HARNESS: &str = r#"import { closeSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, writeFileSync } from "node:fs";
+ const HARNESS: &str = r#"import { closeSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, statSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { homedir } from "node:os";
diff --git a/crates/ai-memory-cli/src/commands/transcript_capture.rs b/crates/ai-memory-cli/src/commands/transcript_capture.rs
index c905ff77..38650b19 100644
--- a/crates/ai-memory-cli/src/commands/transcript_capture.rs
+++ b/crates/ai-memory-cli/src/commands/transcript_capture.rs
@@ -21,8 +21,8 @@ use ai_memory_workstream::RECORD_CWD_KEY;
use serde_json::Value;
use super::hook::{
- checkout_admits_capture, delivers_to_same_server, lexical_capture_cwd,
- tool_location_routing_cwd,
+ checkout_admits_capture, delivers_to_same_server, foreign_capture_decision,
+ lexical_capture_cwd, tool_location_routing_cwd,
};
use super::hook_capture::capture_policy;
@@ -267,6 +267,16 @@ impl TranscriptCapture {
}
capture = capture.stricter(inspect(&capture_policy(&destination), &destination));
}
+ // Another checkout's `ignore_paths` hold for a call made here too,
+ // as in the live hook.
+ if let Some(foreign) = foreign_capture_decision(
+ event.agent,
+ &raw,
+ &lexical_capture_cwd(cwd),
+ crate::marker::find_marker(cwd).as_deref(),
+ ) {
+ capture = capture.stricter(EventCapture::from_decision(foreign));
+ }
if recognized {
capture
} else {
@@ -564,6 +574,37 @@ mod tests {
);
}
+ /// A shell command run here that names another checkout's excluded file
+ /// answers to that checkout's policy on import too, as in the live hook;
+ /// one naming its public file is kept.
+ #[test]
+ fn a_shell_command_naming_another_checkouts_file_honors_its_policy() {
+ let source = checkout(None);
+ let other = checkout(Some("private/**"));
+ let capture = TranscriptCapture::for_checkout(source.path(), source.path());
+ let bash = |path: PathBuf, id: &str| {
+ event(
+ WorkstreamEventKind::ToolCall,
+ "assistant",
+ &format!(
+ "Bash: {}",
+ json!({"command": format!("cat {}", path.display())})
+ ),
+ json!({"tool": "Bash", "tool_use_id": id}),
+ )
+ };
+ let events = [
+ bash(other.path().join("private/key.txt"), "a"),
+ result("private", Some("a")),
+ bash(other.path().join("open.txt"), "b"),
+ result("open", Some("b")),
+ ];
+ assert_eq!(
+ kinds(&capture.decide(&events)),
+ ["drop", "drop", "keep", "keep"]
+ );
+ }
+
/// Under allowlist capture mode the live hook emits nothing — prompts
/// included — from a checkout without a marker; an import drops every
/// event there. A marked checkout and the default denylist mode keep them.
diff --git a/crates/ai-memory-hooks/Cargo.toml b/crates/ai-memory-hooks/Cargo.toml
index 4437f17e..886a9279 100644
--- a/crates/ai-memory-hooks/Cargo.toml
+++ b/crates/ai-memory-hooks/Cargo.toml
@@ -22,6 +22,9 @@ serde_json.workspace = true
# Parse the per-event `?event=…` query of each spooled URL in `/hook/batch`,
# the same crate (and version) axum's `Query` extractor uses for `/hook`.
serde_urlencoded = "0.7"
+# Unicode composition (NFC) for comparing paths on a case-folding macOS host;
+# already built into the binary through `url`/`idna`, at this version.
+icu_normalizer = "2.2"
tokio.workspace = true
tracing.workspace = true
jiff.workspace = true
diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rs
index 1b497895..4e2e5240 100644
--- a/crates/ai-memory-hooks/src/capture_policy.rs
+++ b/crates/ai-memory-hooks/src/capture_policy.rs
@@ -438,8 +438,10 @@ 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`.
+ /// POSIX paths compare without regard to case or Unicode composition,
+ /// as on macOS, whose default filesystem reads `NOTES/X.md` as
+ /// `notes/x.md` and a decomposed `é` as a composed one. Patterns are
+ /// stored folded ([`fold_path`]); candidates are folded before matching.
fold_case: bool,
}
@@ -452,6 +454,16 @@ struct CompiledPattern {
literal_prefix: String,
}
impl CompiledPattern {
+ /// This pattern as a case-folding host compares it.
+ fn folded(self) -> Self {
+ let path = fold_path(&self.path);
+ Self {
+ literal_prefix: literal_prefix(&path).into(),
+ directory_base: self.directory_base.as_deref().map(fold_path),
+ path,
+ flavor: self.flavor,
+ }
+ }
/// Upper bound on `glob_match` steps for one candidate, directory glob included.
fn match_cost(&self, candidate: &str) -> usize {
let pattern = self.path.chars().count()
@@ -491,6 +503,22 @@ impl CaptureDecision {
pub const fn protocol(&self) -> &CaptureProtocol {
&self.protocol
}
+
+ /// The stricter of two policies' decisions for one tool call (drop, then
+ /// metadata-only, then keep), `self` on a tie.
+ #[must_use]
+ pub fn stricter(self, other: Self) -> Self {
+ let rank = |decision: &Self| match decision.protocol.disposition() {
+ CaptureDisposition::Keep => 0,
+ CaptureDisposition::MetadataOnly => 1,
+ CaptureDisposition::Drop => 2,
+ };
+ if rank(&other) > rank(&self) {
+ other
+ } else {
+ self
+ }
+ }
}
impl CapturePolicy {
@@ -542,7 +570,11 @@ impl CapturePolicy {
match compiled {
Ok(patterns) => Self {
state: PolicyState::Active,
- patterns,
+ patterns: if fold_case {
+ patterns.into_iter().map(CompiledPattern::folded).collect()
+ } else {
+ patterns
+ },
home: home_dir.and_then(|dir| normalize_root(dir).ok()),
root: normalize_root(marker_dir).ok(),
fold_case,
@@ -615,6 +647,16 @@ impl CapturePolicy {
};
match matched {
Ok(true) => (CaptureDisposition::Drop, ExtractionState::Extracted),
+ // A harness's saved copy of an earlier tool's
+ // output is read back like `BashOutput`.
+ Ok(false)
+ if paths.iter().any(|path| {
+ normalize_candidate(path, cwd)
+ .is_some_and(|candidate| output_spool(&candidate.path))
+ }) =>
+ {
+ (CaptureDisposition::MetadataOnly, ExtractionState::Extracted)
+ }
Ok(false) => (CaptureDisposition::Keep, ExtractionState::Extracted),
Err(()) => (
CaptureDisposition::MetadataOnly,
@@ -628,24 +670,21 @@ impl CapturePolicy {
// output (`cat docs/adr/*.md`). An exhausted match budget
// fails closed like an unprovable file candidate.
ToolFamily::NonFile => match extracted.command.as_ref().map(|command| {
- let base = match extracted.workdir.as_deref() {
- Some(dir) if is_absolute(dir) => dir.to_owned(),
- // `join` would turn an unusable cwd into `/dir`.
- Some(dir) if is_absolute(cwd) => join(cwd, dir),
- _ => cwd.to_owned(),
- };
+ let base = command_base(extracted.workdir.as_deref(), cwd);
// 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))
+ .map(|(matched, spool)| (matched, split.opaque || spool))
}) {
Some(Ok((true, _)) | Err(())) => (CaptureDisposition::Drop, extracted.state),
// Syntax the matcher does not evaluate (brace expansion,
// bracket classes, zsh groups, encoded escapes) and inline
- // interpreter code prove nothing either way.
+ // interpreter code prove nothing either way, and a
+ // harness's saved output file holds an earlier command's
+ // output.
Some(Ok((false, true))) => (CaptureDisposition::MetadataOnly, extracted.state),
Some(Ok((false, false))) | None => (CaptureDisposition::Keep, extracted.state),
},
@@ -675,6 +714,7 @@ impl CapturePolicy {
let candidates = candidates.ok_or(())?;
let mut work = 0_usize;
for candidate in candidates {
+ let candidate = self.fold_candidate(candidate);
for pattern in self
.patterns
.iter()
@@ -701,23 +741,14 @@ impl CapturePolicy {
/// Lexically matches every path-like shell argument. Nothing is expanded
/// or executed: variables, command substitution, and `cd` are not
/// followed, so this narrows the leak rather than closing every alias.
- fn match_command(&self, words: &[String], cwd: &str) -> Result<bool, ()> {
+ /// Also reports whether an argument names a harness's saved tool output
+ /// ([`output_spool`]).
+ fn match_command(&self, words: &[(String, bool)], cwd: &str) -> Result<(bool, bool), ()> {
let mut work = 0_usize;
- for word in words {
+ let mut spool = false;
+ for (word, tilde) in words {
for (argument, from_root) in shell_arguments(word) {
- 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
- };
+ let expanded = expand_tilde(argument, *tilde, self.home.as_deref(), cwd);
// Git reads `REV:path` from the repository root, which only
// the marker directory approximates; try the cwd as well.
let root = (from_root && !is_absolute(&expanded))
@@ -728,13 +759,25 @@ impl CapturePolicy {
let Some(candidate) = normalize_candidate(&expanded, base) else {
continue;
};
+ spool |= output_spool(&candidate.path);
if self.match_pattern_candidate(&candidate, false, &mut work)? {
- return Ok(true);
+ return Ok((true, spool));
}
}
}
}
- Ok(false)
+ Ok((false, spool))
+ }
+ /// `candidate` as this host compares it.
+ fn fold_candidate(&self, candidate: Normalized) -> Normalized {
+ if self.fold_case {
+ Normalized {
+ path: fold_path(&candidate.path),
+ flavor: candidate.flavor,
+ }
+ } else {
+ candidate
+ }
}
/// Matches the path arguments of Gemini CLI's `read_many_files`, which are
/// globs expanded case-insensitively (`nocase`) with `**` recursing into
@@ -765,6 +808,13 @@ impl CapturePolicy {
tool_glob: bool,
work: &mut usize,
) -> Result<bool, ()> {
+ let folded;
+ let candidate = if self.fold_case {
+ folded = self.fold_candidate(candidate.clone());
+ &folded
+ } else {
+ candidate
+ };
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
@@ -1068,6 +1118,44 @@ fn reads_earlier_output(name: &str) -> bool {
)
}
+/// Whether a normalized path is a file a harness saved a tool's output to and
+/// tells the model to read back: Claude Code's large results
+/// (`~/.claude/projects/<project>/<session>/tool-results/<id>.txt`) and
+/// background task output (`<tmp>/claude-<uid>/<project>/<session>/tasks/<id>.output`),
+/// OpenCode's truncated output (`<data>/opencode/tool-output/tool_<id>`) and
+/// Pi's (`<tmp>/pi-bash-<id>.log`). The command that produced it may have been
+/// dropped, so, like [`reads_earlier_output`], nothing proves it missed every
+/// ignored path. Segment names compare without regard to ASCII case.
+fn output_spool(path: &str) -> bool {
+ let segments: Vec<String> = path
+ .split('/')
+ .filter(|segment| !segment.is_empty())
+ .map(str::to_ascii_lowercase)
+ .collect();
+ let Some((file, directories)) = segments.split_last() else {
+ return false;
+ };
+ let parent = directories.last().map(String::as_str);
+ let claude_results = directories.iter().enumerate().any(|(index, segment)| {
+ segment == "projects"
+ && index > 0
+ && directories[index - 1].contains("claude")
+ && directories[index + 1..]
+ .iter()
+ .any(|segment| segment == "tool-results")
+ });
+ let claude_task = parent == Some("tasks")
+ && file.ends_with(".output")
+ && directories
+ .iter()
+ .any(|segment| segment.starts_with("claude"));
+ let opencode = parent == Some("tool-output")
+ && directories.len() >= 2
+ && directories[directories.len() - 2] == "opencode";
+ let pi = file.starts_with("pi-bash-") && file.ends_with(".log");
+ claude_results || claude_task || opencode || pi
+}
+
fn family(name: &str) -> ToolFamily {
match name.to_ascii_lowercase().as_str() {
"read"
@@ -1227,20 +1315,98 @@ pub fn absolute_tool_location_paths(
is_absolute(path)
.then(|| normalize_candidate(path, cwd))
.flatten()
- .map(|candidate| match candidate.flavor {
- // Matching works on `/`-separated paths, but this path
- // leaves the policy module: the hook sends its directory
- // as the event's `cwd`. It keeps the native style
- // (`C:\…`, like every other cwd the hook forwards) so
- // the server never sees two spellings of one checkout;
- // segment normalization (`.`/`..`) still applies.
- Flavor::Windows => candidate.path.replace('/', "\\"),
- Flavor::Posix => candidate.path,
- })
+ .map(native_path)
})
.collect()
}
+/// A normalized candidate in its own separator style. Matching works on
+/// `/`-separated paths, but this path leaves the policy module: the hook
+/// sends a directory as the event's `cwd` and looks markers up from it. It
+/// keeps the native style (`C:\…`, like every other cwd the hook forwards)
+/// so the server never sees two spellings of one checkout; segment
+/// normalization (`.`/`..`) still applies.
+fn native_path(candidate: Normalized) -> String {
+ match candidate.flavor {
+ Flavor::Windows => candidate.path.replace('/', "\\"),
+ Flavor::Posix => candidate.path,
+ }
+}
+
+/// Upper bound on the locations [`capture_lookup_locations`] returns for one
+/// tool call.
+pub const MAX_LOOKUP_LOCATIONS: usize = 4_096;
+
+/// The absolute locations a recognized file or shell tool call names, in
+/// their own separator style, for a hook client to find the marker that
+/// governs each: every file-tool target, and every shell argument that names
+/// a path (one with a separator, after `~/` expansion) resolved from the
+/// tool's `workdir` or the `cwd`, plus that directory itself.
+///
+/// A checkout's `ignore_paths` protect its files wherever the call is made
+/// from, so a client applies the policy of each location's own marker as
+/// well as the event's (`cat ../other-checkout/secret.env`). Search/list and
+/// unknown tools yield nothing; their policy is the event's. `None` when the
+/// call names more than [`MAX_LOOKUP_LOCATIONS`] distinct locations, since
+/// nothing then proves which markers govern it.
+pub fn capture_lookup_locations(
+ agent: AgentKind,
+ raw: &Value,
+ cwd: &str,
+ home: Option<&str>,
+) -> Option<Vec<String>> {
+ let extracted = extract(agent, raw);
+ let mut seen = std::collections::HashSet::new();
+ let mut locations = Vec::new();
+ let mut push = |candidate: Option<Normalized>| -> Option<()> {
+ let Some(candidate) = candidate else {
+ return Some(());
+ };
+ let location = native_path(candidate);
+ if seen.insert(location.clone()) {
+ if locations.len() == MAX_LOOKUP_LOCATIONS {
+ return None;
+ }
+ locations.push(location);
+ }
+ Some(())
+ };
+ match (extracted.family, extracted.command.as_ref()) {
+ (ToolFamily::File, _) => {
+ for path in extracted.paths.iter().flatten() {
+ push(normalize_candidate(path, cwd))?;
+ }
+ }
+ (ToolFamily::NonFile, Some(command)) => {
+ let base = command_base(extracted.workdir.as_deref(), cwd);
+ push(normalize_candidate(&base, &base))?;
+ let home = home.and_then(|dir| normalize_root(dir).ok());
+ let split = command.split(extracted.powershell || flavor_of(cwd) == Flavor::Windows);
+ for (word, tilde) in &split.words {
+ for (argument, _) in shell_arguments(word) {
+ let expanded = expand_tilde(argument, *tilde, home.as_deref(), &base);
+ if expanded.contains(['/', '\\']) {
+ push(normalize_candidate(&expanded, &base))?;
+ }
+ }
+ }
+ }
+ _ => {}
+ }
+ Some(locations)
+}
+
+/// The directory a shell tool's relative arguments resolve from: its own
+/// `workdir` (absolute, or relative to the `cwd`), else the `cwd`.
+fn command_base(workdir: Option<&str>, cwd: &str) -> String {
+ match workdir {
+ Some(dir) if is_absolute(dir) => dir.to_owned(),
+ // `join` would turn an unusable cwd into `/dir`.
+ Some(dir) if is_absolute(cwd) => join(cwd, dir),
+ _ => cwd.to_owned(),
+ }
+}
+
fn direct_paths(object: &Map<String, Value>) -> Option<Vec<String>> {
let mut paths = Vec::new();
for key in [
@@ -1279,18 +1445,24 @@ enum ShellCommand<'a> {
Argv(Vec<&'a str>),
}
-/// A shell tool's words, plus whether any of them holds syntax the lexical
-/// matcher does not evaluate, which makes a miss unprovable.
+/// A shell tool's words, each with whether a `~` in it was outside quotes
+/// (only such a tilde names a directory), plus whether any of them holds
+/// syntax the lexical matcher does not evaluate, which makes a miss
+/// unprovable.
#[derive(Default)]
struct ShellWords {
- words: Vec<String>,
+ words: Vec<(String, bool)>,
opaque: bool,
}
impl ShellCommand<'_> {
#[cfg(test)]
fn words(&self) -> Vec<String> {
- self.split(false).words
+ self.split(false)
+ .words
+ .into_iter()
+ .map(|(word, _)| word)
+ .collect()
}
/// Every word, and again every word inside a word that holds more than
@@ -1309,9 +1481,9 @@ impl ShellCommand<'_> {
match self {
Self::Line(command) => {
split.opaque = has_unevaluated_expansion(command);
- push_nested_words(&shell_words(command), MAX_SHELL_NESTING, &mut split);
+ push_nested_words(&marked_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);
+ push_nested_words(&marked_shell_words(&plain), MAX_SHELL_NESTING, &mut split);
}
}
Self::Argv(items) => {
@@ -1319,36 +1491,63 @@ impl ShellCommand<'_> {
// over-approximation its words make.
split.opaque = items.iter().any(|item| has_unevaluated_expansion(item))
|| runs_inline_code(items);
- for item in items {
- push_argv_item(item, &mut split);
+ for (index, item) in items.iter().enumerate() {
+ // An element reaches the program as is, so only a script
+ // a shell runs expands a tilde in it.
+ let script = is_shell_script(items, index);
+ push_argv_item(item, script, &mut split);
if let Some(plain) = windows.then(|| without_windows_escapes(item)).flatten() {
- push_argv_item(&plain, &mut split);
+ push_argv_item(&plain, script, &mut split);
}
}
}
}
+ // PowerShell resolves `~` in a path itself, quoted or not.
+ if windows {
+ for (_, tilde) in &mut split.words {
+ *tilde = true;
+ }
+ }
// `~-`, `~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.opaque |= split.words.iter().any(|(word, tilde)| {
+ *tilde
+ && 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);
+fn push_argv_item(item: &str, script: bool, split: &mut ShellWords) {
+ let tokens = marked_shell_words(item);
+ if tokens.len() == 1 && tokens[0].0 == item {
+ push_word(item, false, 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());
+ split.words.push((item.to_owned(), false));
}
- push_nested_words(&tokens, MAX_SHELL_NESTING - 1, split);
+ push_nested_words(
+ &literal_tildes(tokens, script),
+ MAX_SHELL_NESTING - 1,
+ split,
+ );
+}
+
+/// `tokens` re-split from one word, whose unquoted tildes count only when a
+/// shell runs that word as a script; in a quoted message or pattern
+/// (`-m "fix ~approx"`, `grep '~[a-z]+'`) a tilde is literal.
+fn literal_tildes(tokens: Vec<(String, bool)>, script: bool) -> Vec<(String, bool)> {
+ if script {
+ return tokens;
+ }
+ tokens
+ .into_iter()
+ .map(|(token, _)| (token, false))
+ .collect()
}
/// `command` without PowerShell's backquote and cmd's caret escapes, each of
@@ -1381,43 +1580,63 @@ fn names_unknown_directory(argument: &str) -> bool {
!prefix.is_empty() && prefix != "+"
}
+/// `argument` with a leading unquoted `~/` (PowerShell's `~\`) read as the
+/// home directory and `~+` as the working directory.
+fn expand_tilde(argument: String, tilde: bool, home: Option<&str>, cwd: &str) -> String {
+ if !tilde {
+ return argument;
+ }
+ let under_home = argument
+ .strip_prefix("~/")
+ .or_else(|| argument.strip_prefix("~\\"));
+ if let (Some(rest), Some(home)) = (under_home, home) {
+ join(home, rest)
+ } else if argument == "~+" {
+ cwd.to_owned()
+ } else if let Some(rest) = argument.strip_prefix("~+/") {
+ join(cwd, rest)
+ } else {
+ argument
+ }
+}
+
/// How many quoting levels a script inside a word is re-split.
const MAX_SHELL_NESTING: usize = 4;
-fn push_nested_words(words: &[String], depth: usize, split: &mut ShellWords) {
- if runs_inline_code(words) {
+fn push_nested_words(words: &[(String, bool)], depth: usize, split: &mut ShellWords) {
+ let texts: Vec<&str> = words.iter().map(|(word, _)| word.as_str()).collect();
+ if runs_inline_code(&texts) {
split.opaque = true;
}
- for (index, word) in words.iter().enumerate() {
- push_word(word, split);
- let tokens = shell_words(word);
- if tokens.len() == 1 && tokens[0] == *word {
+ for (index, (word, tilde)) in words.iter().enumerate() {
+ push_word(word, *tilde, split);
+ let tokens = marked_shell_words(word);
+ if tokens.len() == 1 && tokens[0].0 == *word {
continue;
}
let Some(depth) = depth.checked_sub(1) else {
split.opaque = true;
continue;
};
- // Only a script a shell runs expands its braces and classes; a
- // quoted message or pattern (`git log --format='%h {a,b}'`) does not.
- if (word.contains("$(") || word.contains('`') || is_shell_script(words, index))
- && has_unevaluated_expansion(word)
- {
+ // Only a script a shell runs expands its braces, classes and
+ // tildes; a quoted message or pattern (`git log --format='%h {a,b}'`)
+ // does not.
+ let script = word.contains("$(") || word.contains('`') || is_shell_script(&texts, index);
+ if script && has_unevaluated_expansion(word) {
split.opaque = true;
}
- push_nested_words(&tokens, depth, split);
+ push_nested_words(&literal_tildes(tokens, script), depth, split);
}
}
/// 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. 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);
- }
+/// (`${X:-docs/x.md}`) also adds the reading with the operand in its place,
+/// of the word as written and of its POSIX reading (`${X:-d\ocs/x.md}`).
+/// `tilde` says whether a `~` in the word was outside quotes.
+fn push_word(word: &str, tilde: bool, split: &mut ShellWords) {
+ push_word_reading(word, tilde, split);
if word.contains('\\') {
let mut plain = String::with_capacity(word.len());
let mut chars = word.chars();
@@ -1429,24 +1648,35 @@ fn push_word(word: &str, split: &mut ShellWords) {
}
}
if plain != word {
- split.words.push(plain);
+ push_word_reading(&plain, tilde, split);
}
}
}
+fn push_word_reading(word: &str, tilde: bool, split: &mut ShellWords) {
+ split.words.push((word.to_owned(), tilde));
+ if let Some((operands, exhausted)) = parameter_operands(word) {
+ split.words.push((operands, tilde));
+ // A default nested deeper than the matcher reads is unprovable.
+ split.opaque |= exhausted;
+ }
+}
+
/// `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> {
+/// replaced down to [`MAX_SHELL_NESTING`] levels; the flag is set when one
+/// is nested deeper still.
+fn parameter_operands(word: &str) -> Option<(String, bool)> {
let mut current = replace_parameter_operands(word)?;
for _ in 1..MAX_SHELL_NESTING {
match replace_parameter_operands(&current) {
Some(next) => current = next,
- None => break,
+ None => return Some((current, false)),
}
}
- Some(current)
+ let exhausted = replace_parameter_operands(&current).is_some();
+ Some((current, exhausted))
}
fn replace_parameter_operands(word: &str) -> Option<String> {
@@ -1747,10 +1977,21 @@ fn shell_command(args: &Value) -> Option<ShellCommand<'_>> {
/// opens or closes a command substitution, so it separates too. An ANSI-C
/// string (`$'…'`) has its escapes decoded; numeric and control escapes stay
/// as written, and [`has_unevaluated_expansion`] reports them.
+#[cfg(test)]
fn shell_words(command: &str) -> Vec<String> {
+ marked_shell_words(command)
+ .into_iter()
+ .map(|(word, _)| word)
+ .collect()
+}
+
+/// [`shell_words`], each word with whether it holds a `~` outside quotes and
+/// not after a backslash, the only tilde a shell expands.
+fn marked_shell_words(command: &str) -> Vec<(String, bool)> {
let is_operator = |c: char| matches!(c, '|' | '&' | ';' | '<' | '>' | '(' | ')' | '`');
let mut words = Vec::new();
let mut word = String::new();
+ let mut tilde = false;
let mut in_word = false;
let mut quote = None;
let mut chars = command.chars().peekable();
@@ -1797,18 +2038,19 @@ fn shell_words(command: &str) -> Vec<String> {
}
(None, c) if c.is_whitespace() || is_operator(c) => {
if in_word {
- words.push(std::mem::take(&mut word));
- in_word = false;
+ words.push((std::mem::take(&mut word), tilde));
+ (in_word, tilde) = (false, false);
}
}
(None, c) => {
+ tilde |= c == '~' && !word.ends_with('\\');
word.push(c);
in_word = true;
}
}
}
if in_word {
- words.push(word);
+ words.push((word, tilde));
}
words
}
@@ -1869,12 +2111,15 @@ fn shell_arguments(word: &str) -> Vec<(String, bool)> {
}
/// The local path a `file:` URL names (`file:///x`, `file://host/x`,
-/// `file:/x`, any case), with ASCII percent-escapes decoded.
+/// `file:/x`, any case), with ASCII percent-escapes decoded. A query or
+/// fragment (`?…`, `#…`) is not part of the path; an escaped `%3F` or `%23`
+/// is, so the URL is cut before decoding.
fn file_url_path(argument: &str) -> Option<String> {
if !argument.get(..5)?.eq_ignore_ascii_case("file:") {
return None;
}
let rest = &argument[5..];
+ let rest = rest.find(['?', '#']).map_or(rest, |end| &rest[..end]);
let path = match rest.strip_prefix("//") {
Some(authority) => &authority[authority.find('/')?..],
None => rest,
@@ -2285,6 +2530,15 @@ fn globstar_reaches(glob: &str, prefix: &str, insensitive: bool) -> bool {
}
glob_match(head, &prefix[..offset.min(prefix.len())], None, insensitive)
}
+/// A path as a case-folding (macOS) host compares it: composed (NFC), since
+/// its filesystem reads a decomposed `é` as the composed one, then lowercased
+/// with the full Unicode mapping (`Ä` as `ä`), which the generated
+/// TypeScript's `normalize("NFC").toLowerCase()` mirrors.
+fn fold_path(path: &str) -> String {
+ icu_normalizer::ComposingNormalizerBorrowed::new_nfc()
+ .normalize(path)
+ .to_lowercase()
+}
fn char_equal(left: char, right: char, insensitive: bool) -> bool {
if insensitive && left.is_ascii() && right.is_ascii() {
left.eq_ignore_ascii_case(&right)
@@ -3695,6 +3949,139 @@ mod tests {
);
}
+ /// A file a harness saved a tool's output to (Claude Code's
+ /// `tool-results/` and background `tasks/*.output`, OpenCode's
+ /// `tool-output/`, Pi's `pi-bash-*.log`) holds an earlier command's
+ /// output, which may come from a dropped event, so reading it back is
+ /// metadata-only under an active or invalid policy, like `BashOutput`.
+ /// Without a policy it is kept, and an ignored path still drops.
+ #[test]
+ fn reading_a_harness_output_spool_is_metadata_only_under_a_policy() {
+ let active = shell_policy();
+ let invalid = CapturePolicy::resolve(CaptureSource::Invalid, "/repo", None);
+ let inactive = CapturePolicy::resolve(CaptureSource::Absent, "/repo", None);
+ let read = |path: &str| {
+ json!({
+ "tool_name": "Read", "tool_input": {"file_path": path},
+ "tool_response": "PRIVATE_BODY_SENTINEL",
+ })
+ };
+ let disposition = |policy: &CapturePolicy, raw: &Value| {
+ policy
+ .inspect(AgentKind::ClaudeCode, raw, "/repo")
+ .protocol()
+ .disposition()
+ };
+ for spool in [
+ "/tmp/claude-1000/-repo/0f1e/tasks/bvljb9mrz.output",
+ "/private/var/folders/x/T/claude-501/-repo/0f1e/tasks/b1.output",
+ "/home/me/.claude/projects/-repo/0f1e/tool-results/toolu_1.txt",
+ "C:\\Users\\me\\.claude\\projects\\-repo\\0f1e\\tool-results\\t.txt",
+ "/home/me/.local/share/opencode/tool-output/tool_10a9b7111001",
+ "/tmp/pi-bash-0a1b2c3d4e5f6a7b.log",
+ ] {
+ for policy in [&active, &invalid] {
+ let decision = policy.inspect(AgentKind::ClaudeCode, &read(spool), "/repo");
+ assert_eq!(
+ decision.protocol().disposition(),
+ CaptureDisposition::MetadataOnly,
+ "{spool}"
+ );
+ let body = metadata_only_body(Some("s"), Some("/repo"), &decision).to_string();
+ assert!(!body.contains("PRIVATE_BODY_SENTINEL"), "{body}");
+ }
+ assert_eq!(
+ disposition(&inactive, &read(spool)),
+ CaptureDisposition::Keep
+ );
+ assert_eq!(
+ disposition(&active, &bash(&format!("cat '{spool}'"))),
+ CaptureDisposition::MetadataOnly,
+ "{spool}"
+ );
+ }
+ // Controls: the same names elsewhere are ordinary files.
+ for path in [
+ "/tmp/claude-1000/-repo/0f1e/scratchpad/notes.txt",
+ "/repo/tasks/b1.output",
+ "/repo/projects/x/0f1e/tool-results/a.txt",
+ "/repo/tool-output/tool_1",
+ "/repo/src/pi-bash.rs",
+ ] {
+ assert_eq!(
+ disposition(&active, &read(path)),
+ CaptureDisposition::Keep,
+ "{path}"
+ );
+ assert_eq!(
+ disposition(&active, &bash(&format!("cat {path}"))),
+ CaptureDisposition::Keep,
+ "{path}"
+ );
+ }
+ assert_eq!(
+ disposition(&active, &bash("cat docs/adr/1.md /tmp/pi-bash-1.log")),
+ CaptureDisposition::Drop
+ );
+ }
+
+ /// The locations a call names, for the hook to find each one's marker:
+ /// every file target, and every shell argument that spells a path,
+ /// resolved from the tool's directory, plus that directory.
+ #[test]
+ fn capture_lookup_locations_name_every_path_a_call_spells() {
+ let locations = |raw: &Value| {
+ capture_lookup_locations(AgentKind::ClaudeCode, raw, "/work/b", Some("/home/me"))
+ };
+ assert_eq!(
+ locations(
+ &json!({"tool_name": "Read", "tool_input": {"file_path": "../a/secrets.env"}})
+ ),
+ Some(vec!["/work/a/secrets.env".to_owned()])
+ );
+ assert_eq!(
+ locations(&bash(
+ "cat ../a/secrets.env /abs/c/x ~/notes/y \"~/lit/z\" secrets.env --in=../d/e"
+ )),
+ Some(vec![
+ "/work/b".to_owned(),
+ "/work/a/secrets.env".to_owned(),
+ "/abs/c/x".to_owned(),
+ "/home/me/notes/y".to_owned(),
+ "/work/b/~/lit/z".to_owned(),
+ "/work/d/e".to_owned(),
+ ])
+ );
+ assert_eq!(
+ locations(&json!({
+ "tool_name": "Bash",
+ "tool_input": {"command": "cat secrets.env", "workdir": "/work/a"},
+ })),
+ Some(vec!["/work/a".to_owned()])
+ );
+ assert_eq!(
+ capture_lookup_locations(
+ AgentKind::ClaudeCode,
+ &json!({"tool_name": "Read", "tool_input": {"file_path": "C:\\a\\x.md"}}),
+ "C:\\b",
+ None,
+ ),
+ Some(vec!["C:\\a\\x.md".to_owned()])
+ );
+ // Search/list and unknown tools stay with the event's own policy.
+ for raw in [
+ json!({"tool_name": "Grep", "tool_input": {"path": "../a"}}),
+ json!({"tool_name": "FutureTool", "tool_input": {"path": "../a/x"}}),
+ ] {
+ assert_eq!(locations(&raw), Some(Vec::new()));
+ }
+ let many = (0..=MAX_LOOKUP_LOCATIONS)
+ .map(|index| format!("d{index}/x"))
+ .collect::<Vec<_>>()
+ .join(" ");
+ assert_eq!(locations(&bash(&format!("cat {many}"))), None);
+ }
+
/// Copilot CLI's runtime `view`/`create` names are file tools for that
/// agent only; another agent's same-named tool stays unknown.
#[test]
@@ -4380,6 +4767,41 @@ mod tests {
.disposition(),
CaptureDisposition::Keep
);
+ // Beyond ASCII: the full lowercase mapping, and a decomposed `É`
+ // (`E` + U+0301) is the composed one.
+ let unicode = CapturePolicy::resolve_for_host(
+ CaptureSource::Parsed(&CaptureConfig {
+ ignore_paths: vec!["Écrits/Ärger/**".into()],
+ }),
+ "/repo",
+ None,
+ true,
+ );
+ for path in [
+ "écrits/ärger/x.md",
+ "ÉCRITS/ÄRGER/x.md",
+ "E\u{301}crits/A\u{308}rger/x.md",
+ ] {
+ let read = json!({"tool_name": "Read", "tool_input": {"file_path": path}});
+ for raw in [read, bash(&format!("cat {path}"))] {
+ assert_eq!(
+ unicode
+ .inspect(AgentKind::ClaudeCode, &raw, "/repo")
+ .protocol()
+ .disposition(),
+ CaptureDisposition::Drop,
+ "{path}"
+ );
+ }
+ }
+ let other = json!({"tool_name": "Read", "tool_input": {"file_path": "ecrits/arger/x.md"}});
+ assert_eq!(
+ unicode
+ .inspect(AgentKind::ClaudeCode, &other, "/repo")
+ .protocol()
+ .disposition(),
+ CaptureDisposition::Keep
+ );
assert!(
!CapturePolicy::resolve(CaptureSource::Absent, "/repo", None).fold_case,
"an inactive policy never folds"
@@ -4451,6 +4873,15 @@ mod tests {
"git log --oneline HEAD~3..HEAD",
"git rebase -i HEAD~2",
"echo a^b",
+ // A quoted tilde is literal, and a query or fragment is not part
+ // of a `file:` URL's path.
+ "git commit -m \"fix ~approx\"",
+ "grep -E '~[a-z]+' f",
+ "echo 'a ~b c'",
+ "sed -i 's/~old/~new/' src/main.rs",
+ "curl -s 'file:///tmp/report.txt?x=1#top'",
+ "echo ${A:-${B:-${C:-x}}}",
+ "tail -f /tmp/claude-1000/-repo/0f1e/scratchpad/build.log",
] {
assert_eq!(
policy
diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rs
index 71191dce..c8c04496 100644
--- a/crates/ai-memory-hooks/src/lib.rs
+++ b/crates/ai-memory-hooks/src/lib.rs
@@ -47,8 +47,8 @@ pub use assistant_capture::{
pub use capture_policy::{
CaptureConfig, CaptureDecision, CaptureDisposition, CaptureMode, CapturePolicy,
CaptureProtocol, CaptureSource, ExtractionState, PolicyState, ToolFamily,
- absolute_tool_location_paths, describe_invalid_capture_config, repository_admits_capture,
- tool_call_payload,
+ absolute_tool_location_paths, capture_lookup_locations, describe_invalid_capture_config,
+ repository_admits_capture, tool_call_payload,
};
pub use payload::{
HookEnvelope, HookEvent, NOTIFICATION_EXCERPT_MAX_BYTES, POST_COMPACTION_EXCERPT_MAX_BYTES,
diff --git a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json b/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
index 66b15176..61591572 100644
--- a/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
+++ b/crates/ai-memory-hooks/tests/fixtures/capture-policy.json
@@ -36,6 +36,15 @@
{"agent":"open-code","payload":{"tool":"bash","args":{"command":"cat secret/a | head"}},"disposition":"drop","tool_family":"non-file","extraction_state":"extracted","path_count":0},
{"agent":"omp","payload":{"tool":"bash","args":{"command":"cat secret/*"}},"disposition":"drop","tool_family":"non-file","extraction_state":"extracted","path_count":0},
{"agent":"pi","payload":{"tool":"bash","args":{"command":"cat 'secret/a b'"}},"disposition":"drop","tool_family":"non-file","extraction_state":"extracted","path_count":0},
+ {"agent":"claude-code","payload":{"tool_name":"Read","tool_input":{"file_path":"/tmp/claude-1000/-repo/s1/tasks/b1.output"}},"disposition":"metadata-only","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"claude-code","payload":{"tool_name":"Read","tool_input":{"file_path":"/home/me/.claude/projects/-repo/s1/tool-results/t1.txt"}},"disposition":"metadata-only","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"open-code","payload":{"tool":"read","args":{"filePath":"/home/me/.local/share/opencode/tool-output/tool_01"}},"disposition":"metadata-only","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"pi","payload":{"tool":"read","args":{"path":"/tmp/pi-bash-0a1b2c3d.log"}},"disposition":"metadata-only","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"pi","payload":{"tool":"read","args":{"path":"secret/pi-bash-1.log"}},"disposition":"drop","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"claude-code","payload":{"tool_name":"Read","tool_input":{"file_path":"/tmp/claude-1000/-repo/s1/scratchpad/notes.txt"}},"disposition":"keep","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"open-code","payload":{"tool":"read","args":{"filePath":"tasks/b1.output"}},"disposition":"keep","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"pi","payload":{"tool":"read","args":{"path":"projects/x/s1/tool-results/a.txt"}},"disposition":"keep","tool_family":"file","extraction_state":"extracted","path_count":1},
+ {"agent":"pi","payload":{"tool":"read","args":{"path":"src/pi-bash.rs"}},"disposition":"keep","tool_family":"file","extraction_state":"extracted","path_count":1},
{"agent":"openclaw","payload":{"tool":"exec","args":{"command":"wc -l <secret/a"}},"disposition":"drop","tool_family":"non-file","extraction_state":"extracted","path_count":0},
{"agent":"open-code","payload":{"tool":"bash","args":{"command":"cat public/a *.md"}},"disposition":"keep","tool_family":"non-file","extraction_state":"extracted","path_count":0},
{"agent":"openclaw","payload":{"tool":"exec","args":{"command":"git diff"}},"disposition":"keep","tool_family":"non-file","extraction_state":"extracted","path_count":0},
@@ -110,7 +119,7 @@
},
"shell": {
"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/**"],
+ "ignore_paths": ["docs/adr/**","~/notes/**","docs/n?tes/**","C:/Secret/**","private notes/**","secrets.env","\u00c4rger/**"],
"vectors": [
{"command":"cat docs/adr/0001.md","disposition":"drop"},
{"command":"cat ./docs/adr/0001.md","disposition":"drop"},
@@ -277,6 +286,12 @@
{"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":"curl -s 'file://{root}/secrets.env?x=1'","disposition":"drop"},
+ {"command":"curl -s 'file://{root}/secrets.env#frag'","disposition":"drop"},
+ {"command":"curl -s 'FILE://localhost{root}/secrets.env?a#b'","disposition":"drop"},
+ {"command":"curl -s 'file://{root}/secrets%2Eenv%3Fx'","disposition":"keep"},
+ {"command":"curl -s 'file://{root}/src/main.rs?x=1'","disposition":"keep"},
+ {"command":"curl -s 'file://{root}/docs%23adr/1.md'","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"},
@@ -291,10 +306,39 @@
{"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 ${X:-${Y:-${Z:-${W:-docs/adr/1.md}}}}","disposition":"drop"},
+ {"command":"cat ${X:-${Y:-${Z:-${W:-${V:-docs/adr/1.md}}}}}","disposition":"metadata-only"},
+ {"command":"cat ${X:-${Y:-${Z:-${W:-${V:-src/main.rs}}}}}","disposition":"metadata-only"},
+ {"command":"cat ${X:-sec\\rets.env}","disposition":"drop"},
+ {"command":"cat \"${X:-docs/ad\\r}/1.md\"","disposition":"drop"},
+ {"command":"cat ${X:-sr\\c/main.rs}","disposition":"keep"},
+ {"command":"git commit -m \"fix ~approx\"","disposition":"keep"},
+ {"command":"grep -E '~[a-z]+' f","disposition":"keep"},
+ {"command":"echo 'a ~b c'","disposition":"keep"},
+ {"command":"echo \"~1 and ~bob\"","disposition":"keep"},
+ {"command":"cat \"~\"/notes/x.md","disposition":"keep"},
+ {"command":"cat \\~/notes/x.md","disposition":"keep"},
+ {"payload":{"tool":"shell","args":{"command":["git","commit","-m","fix ~approx"]}},"disposition":"keep"},
+ {"payload":{"tool":"shell","args":{"command":["cat","~bob/x.md"]}},"disposition":"keep"},
+ {"command":"bash -c 'cat ~/notes/x.md'","disposition":"drop"},
+ {"command":"bash -c 'cat ~bob/x.md'","disposition":"metadata-only"},
+ {"command":"echo \"$(cat ~/notes/x.md)\"","disposition":"drop"},
+ {"payload":{"tool":"shell","args":{"command":["bash","-lc","cat ~bob/x.md"]}},"disposition":"metadata-only"},
+ {"command":"NOTES=~/notes/x.md make","disposition":"drop"},
+ {"payload":{"tool":"powershell","args":{"command":"Get-Content \"~/notes/x.md\""}},"disposition":"drop"},
+ {"command":"cat /tmp/claude-1000/-repo/s1/tasks/b1.output","disposition":"metadata-only"},
+ {"command":"tail -n 50 /tmp/pi-bash-0a1b.log","disposition":"metadata-only"},
+ {"command":"cat /tmp/claude-1000/-repo/s1/scratchpad/notes.txt","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":"cat \u00e4rger/x.md","fold_case":true,"disposition":"drop"},
+ {"command":"cat \u00c4RGER/x.md","fold_case":true,"disposition":"drop"},
+ {"command":"cat A\u0308rger/x.md","fold_case":true,"disposition":"drop"},
+ {"command":"cat \u00c4rger/x.md","disposition":"drop"},
+ {"command":"cat \u00e4rger/x.md","disposition":"keep"},
+ {"command":"cat arger/x.md","fold_case":true,"disposition":"keep"},
{"command":"jq .[] package.json","disposition":"keep"}
]
},