Skip to content

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

Rust

fix(capture): correct allowlist enforcement boundary and warn when unenforced (#480)

Fabio Akitad6a151dd732b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b39ec404..5ffe1ee9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -76,6 +76,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`capture_mode`, `marker_present` and `admits_capture` so an opt-out can be
verified without sending anything. Default behaviour is unchanged, and
`--capture-mode denylist` restores it.
+- Corrected the allowlist-mode documentation, which claimed "every agent's
+ hook honours it". The gate runs inside the native `ai-memory hook` binary
+ before the spool write, so script-based installs — the
+ `AI_MEMORY_HOOK_PLATFORM` override, the Docker host wrapper, and
+ `setup-agent` snippets — POST directly and never read the mode. That is the
+ same boundary `[capture] ignore_paths` already documents. `install-hooks
+ --apply` now warns when the install it is writing cannot enforce the mode it
+ just stored, so the gap is visible where it matters rather than only in a
+ doc (#446).
- `ai-memory status` now reports the capture mode when it is `allowlist`, in
both the human and `--json` renderings. Without it the new ingest counters
read identically whether hooks are broken or a repository simply never opted
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 43276d49..9a4e6785 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -374,6 +374,17 @@ pub fn run(config: &Config, mut args: InstallHooksArgs) -> Result<()> {
println!("capture mode: {capture_mode}");
if capture_mode == "allowlist" {
println!(" repositories without a .ai-memory.toml marker emit no lifecycle events");
+ // The gate lives inside the native hook binary, immediately before
+ // the spool write. A script install POSTs to the server directly
+ // and never runs it, so the mode is stored but unenforced. Saying
+ // nothing would leave an operator trusting a protection this
+ // install does not have — the exact failure #446 is about.
+ if !local_hook_policy_v1_supported() {
+ println!(
+ " WARNING: this install uses script hooks, which POST directly and \
+ cannot enforce the mode. Allowlist is stored but NOT in force here."
+ );
+ }
}
// Preserve a project-strategy an earlier `--apply` baked when this run
// did not pass `--project-strategy`. Without this, a bare re-apply —
diff --git a/docs/install.md b/docs/install.md
index 58b2869f..c429acf3 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -493,8 +493,22 @@ never opted in. Opting a repository in is just placing a `.ai-memory.toml`
marker in it, which is the same file that already configures routing and
`ignore_paths`.
-Unlike the flags above, this is not per-agent: the mode is stored once in the
-data directory and every agent's hook honours it. That also means a later bare
+**It is enforced by native `ai-memory hook` commands only** — the same
+boundary that already applies to `[capture] ignore_paths`, and for the same
+reason: the gate runs inside the hook binary, immediately before it spools.
+
+That is what a normal `install-hooks --apply` writes on Linux, macOS and
+Windows, so the usual install is covered. It is the *script* installs that are
+not: the bundled shell/PowerShell hooks POST to the server directly and never
+execute the binary, so nothing reads the mode. In practice that means the
+legacy `posix`/`windows` platform override (`AI_MEMORY_HOOK_PLATFORM`), the
+Docker host wrapper, and `setup-agent` snippets, which emit script commands by
+design. `install-hooks --apply` prints the mode and warns when the install it
+is writing cannot enforce it.
+
+Within that boundary the mode is not per-agent: it is stored once in the data
+directory and every native hook command reads it, whichever agent invoked it.
+That also means a later bare
`install-hooks --apply` — including the auto-refresh inside `ai-memory upgrade`
— leaves it alone by construction rather than by re-detecting it. Every
`--apply` prints the mode in force. Return to the default with
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 6ccaa1c7..e3a7c1f6 100644
--- a/docs/marker-file.md
+++ b/docs/marker-file.md
@@ -150,6 +150,12 @@ direction whose failure you would rather explain.
The mode is stored per install rather than per agent, and a later bare
`install-hooks --apply` (including an upgrade refresh) leaves it in place.
+Like `ignore_paths` below, it is enforced by native `ai-memory hook` commands
+only — which is what `install-hooks --apply` writes by default. Script-based
+installs (the `AI_MEMORY_HOOK_PLATFORM` override, the Docker host wrapper, and
+`setup-agent` snippets) POST to the server directly without running that
+binary, so allowlist mode does not gate them.
+
## Capture exclusions
Use the exact per-repository shape `[capture]` plus `ignore_paths = [...]`