brainiac-cli 0.20.34__tar.gz → 0.20.35__tar.gz

{brainiac_cli-0.20.34/src/brainiac_cli.egg-info → brainiac_cli-0.20.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainiac-cli
-Version: 0.20.34
+Version: 0.20.35
 Summary: Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index).
 License-Expression: Apache-2.0
 Requires-Python: >=3.9

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 # check. The IMPORT package stays `brain` and the console script stays
 # `brain` — only the distribution/project name changes.
 name = "brainiac-cli"
-version = "0.20.34"
+version = "0.20.35"
 description = "Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index)."
 readme = "README.md"
 license = "Apache-2.0"

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/_assets/AGENTS.md

@@ -1034,6 +1034,26 @@ whole plan to rebuild the already-shipped fusion fix (item 10, `d5b2c58`).
    query string itself is the leak. Web search is for terms that are already
    public. When in doubt, treat the topic as internal and stay in the vault.
 
+   **This rule has a MECHANISM now (SEC-07, 2026-09-01), and it is still your
+   rule to follow.** `brain check-egress "<text>"` judges one outbound string
+   against THIS vault's `overlay/keywords/` decoder ring and exits `6` when a
+   term is classified at or above the threshold (default `Confidential`,
+   `$BRAIN_EGRESS_TERM_MIN_TIER` to change it; an unrecognised value fails
+   CLOSED). It is `VM_ALLOWED` — the Cowork leg is the one reading wild content
+   beside a web tool, so it needs the guard most. `scripts/brainiac-egress-guard.sh`
+   is the Claude Code `PreToolUse` wiring; the script's own header carries the
+   settings entry, and on a harness-managed `~/.claude` that entry belongs to
+   the deploy repo, not to this engine.
+
+   **The engine ships NO terms and never will** — they come from the owner's
+   overlay, the same rows that already drive ingest classification, so there is
+   no second list to curate. **Its limits, stated so nobody over-trusts it:** it
+   matches DECLARED terms on word boundaries. It cannot see a paraphrase, a
+   codename nobody wrote down, or a fact you restate in your own words, and a
+   vault with an empty decoder ring protects nothing — `check-egress` says so
+   rather than reporting a clean pass. It is a floor under this rule, not a
+   replacement for it.
+
 This is the substrate's standing retrieval discipline; it replaces the old
 Obsidian "five-step retrieval cascade" rule for any harness reading this file.
 
@@ -1095,7 +1115,7 @@ Obsidian "five-step retrieval cascade" rule for any harness reading this file.
 >
 > **Where the kernel skills live per client:** the ten
 > kernel/extras skills (`kb-curator`, `promote`, `vault-ingestion`,
-> `vault-eval`, `save-conversation`, `voice`, `curation`, `improve`,
+> `vault-eval`, `save-conversation`, `overlay-style`, `curation`, `improve`,
 > `task-registrar`, `autoresearch`) ship three ways from ONE canonical copy
 > at `.claude/skills/<name>/SKILL.md`
 > (re-synced by `tools/package_clients.py`, never hand-edited in more than one
@@ -1155,6 +1175,18 @@ Obsidian "five-step retrieval cascade" rule for any harness reading this file.
   default: `Internal`** — the untrusted leg keeps the conservative
   deny-by-default cap, and elevation there is the explicit human gate.
   Levels, low→high: `Public < Internal < Confidential < Restricted < MNPI`.
+  **That `--role vm` cap binds the CLI, and since the Cowork cutover the CLI
+  is no longer how a Cowork session reads (2026-09-01).** A Cowork session
+  reaches the vault through the DESK — the host-run `brain-mcp` broker, whose
+  tools Claude Desktop announces into the session — and
+  `mcp_verbs._egress_ceiling_tier()` resolves from `$BRAIN_MAX_EGRESS_TIER`
+  alone. It never sees a role, because `connect.py` writes no `BRAIN_ROLE`
+  into any Desktop stanza. So the untrusted leg reads at the HOST ceiling,
+  which is the full vault. The owner was shown this and DECLINED a per-caller
+  clamp on 2026-08-31 (`docs/security-acceptances.md` A-05): the broker cannot
+  tell a Cowork caller from the owner's own Desktop, so capping one caps both.
+  Do not re-raise it; do not read the `Internal` line above as describing the
+  live Cowork path.
   **Default-deny is a READ rule, never a WRITE target (EXC-01,
   2026-08-22).** `classification.normalize` maps a missing or mis-cased label
   to MNPI, so an unlabelled note is withheld from every capped reader. That is
@@ -1173,6 +1205,19 @@ Obsidian "five-step retrieval cascade" rule for any harness reading this file.
   path; the leg that reads untrusted content must not also hold private data
   + an outbound channel. Surfacing sensitive content and any
   irreversible/outbound action is human-gated.
+  **This is the design, and on the Cowork leg it is no longer met (2026-09-01).**
+  The cutover removed the vault from the mount — a real gain, and it closed an
+  invisible bypass — but it routed the same session through the desk at the
+  host's full-vault ceiling (see the classification bullet above). The Cowork
+  leg therefore holds all three ingredients. What bounds it now is
+  DETECTION, not separation: the SEC-05 ingest quarantine refuses a document
+  carrying a CONCEALED instruction, `egress` marks every `raw/` hit
+  `content_trust: untrusted-source`, the SEC-06 read record is fail-closed,
+  and the Tuesday integrity fold raises a concealed-instruction count and a
+  bulk-read alarm. A plainly VISIBLE injected instruction still enters the
+  vault as `instruction_only` (flagged, not quarantined — presenter notes
+  tripped the stricter rule), so there the model's own compliance is the only
+  control. Accepted, with the reasoning, at A-05.
 - **We hold no model API keys** — the one egress is the desktop app's model call
   under the vendor's enterprise no-train/ZDR terms.
 - **Audit chain.** Every committed write is Ed25519-signed and hash-chained

brainiac_cli-0.20.35/src/brain/_assets/scripts/brainiac-egress-guard.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# SEC-07 — Claude Code PreToolUse guard: refuse a tool call whose arguments
+# carry a term this vault classifies Confidential or above.
+#
+# WHY THIS EXISTS. The classification gate decides what the model may READ. It
+# says nothing about what the model then does. A web search is an outbound
+# channel and nobody reviews a query string, so an injected instruction can put
+# a codename into one and the term has left before any result comes back.
+# `AGENTS.md` retrieval rule 4 has always said so; this script is what enforces
+# it.
+#
+# IT SHIPS NO TERMS. `brain check-egress` reads them from the vault's own
+# `overlay/keywords/` decoder ring. A vault with no ring maps nothing, this
+# guard allows everything, and `brain check-egress` says so in its own words
+# rather than reporting a cheerful pass.
+#
+# WHAT IT DOES NOT DO. It matches DECLARED terms on word boundaries. It cannot
+# see a paraphrase, an undeclared codename, or a fact the model states in its
+# own words. Treat it as a floor, not a seal.
+#
+# INSTALL (Claude Code). Place this file at ~/.claude/hooks/ and register it:
+#
+#   "hooks": {
+#     "PreToolUse": [
+#       { "matcher": "WebSearch|WebFetch",
+#         "hooks": [ { "type": "command",
+#                      "command": "~/.claude/hooks/brainiac-egress-guard.sh",
+#                      "timeout": 5 } ] }
+#     ]
+#   }
+#
+# Add your own web-tool names to the matcher — an MCP search tool is matched by
+# its full `mcp__<server>__<tool>` name.
+#
+# ON A HARNESS-MANAGED ~/.claude (one a deploy repo owns, per
+# `brain.session_hook.harness_managed`) the settings.json entry belongs to that
+# repo, not to this engine. Author it there.
+
+set -uo pipefail
+
+BRAIN_BIN="${BRAIN_BIN:-brain}"
+command -v "$BRAIN_BIN" >/dev/null 2>&1 || exit 0   # no engine here, no opinion
+
+payload="$(cat)"
+
+# The tool arguments, as one string. `jq` is not assumed: fall back to the raw
+# payload, which is a superset of the arguments and so can only over-refuse,
+# never under-refuse. Over-refusing is the safe direction for a guard.
+if command -v jq >/dev/null 2>&1; then
+  text="$(printf '%s' "$payload" | jq -r '.tool_input // empty | tostring' 2>/dev/null)"
+  [ -z "$text" ] && text="$payload"
+else
+  text="$payload"
+fi
+
+verdict="$(printf '%s' "$text" | "$BRAIN_BIN" check-egress 2>/dev/null)"
+status=$?
+
+# Exit 6 is the ONLY refusal. Any other non-zero status is this guard failing,
+# not the text failing, and a broken guard must not block the session — it
+# would be indistinguishable from a real refusal and would be switched off
+# within the day. A failure is reported on stderr and allowed through.
+if [ "$status" -eq 6 ]; then
+  printf '%s\n' "$verdict" >&2
+  exit 2            # Claude Code: block the tool call, show stderr to the model
+fi
+if [ "$status" -ne 0 ]; then
+  printf 'brainiac-egress-guard: check failed (exit %s) — ALLOWING, not blocking\n' \
+    "$status" >&2
+fi
+exit 0

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/_version.py

@@ -9,4 +9,4 @@ pip-installed host, importlib.metadata stays primary; brain/__init__.py reads
 this file only as the fallback before 0.0.0+unknown.
 """
 
-__version__ = "0.20.34"
+__version__ = "0.20.35"

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/cli.py

@@ -292,6 +292,12 @@ VM_ALLOWED = frozenset(
         # copy `maintain` already wrote there. It never writes, and
         # never reaches the host-only full page.
         "exceptions",
+        # SEC-07's outbound term guard. VM_ALLOWED on purpose, and it is the
+        # leg that needs it MOST: the Cowork session is the one reading wild
+        # content beside a web tool. Pure overlay file reads — no index, key,
+        # or network — and it only ever REFUSES, so admitting it to the VM
+        # widens nothing.
+        "check-egress",
         "mcp-config",  # prints a config string; no index/key/vault read
         "search",
         "hybrid-search",

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/cli_cmds/lifecycle.py

@@ -210,6 +210,39 @@ def _run_exceptions(args, ctx) -> int:
     return 0
 
 
+def _run_check_egress(args, ctx) -> int:
+    """SEC-07: judge one OUTBOUND string before a tool call carries it away.
+
+    Deliberately does NOT require a resolvable vault. The hook that calls this
+    fires in whatever directory the session happens to sit in, and a guard that
+    exits 3 outside a vault is a guard that is off most of the time. An
+    unresolvable vault means an empty decoder ring, which `explain` reports in
+    its own words rather than as a cheerful pass.
+    """
+    from .. import egress_terms
+
+    text = args.text
+    if text is None:
+        import sys as _sys
+
+        text = "" if _sys.stdin.isatty() else _sys.stdin.read()
+
+    try:
+        vault = ctx.config.vault_root(args.vault)
+    except Exception:
+        vault = None
+
+    result = egress_terms.check(
+        text, vault=vault, threshold=args.min_tier, strict=args.strict,
+    )
+    result["explanation"] = egress_terms.explain(result)
+    if args.json:
+        _emit(result, True)
+    else:
+        _emit(None, False, result["explanation"])
+    return 0 if result["allowed"] else egress_terms.EXIT_REFUSED
+
+
 def _run_alerts(args, ctx) -> int:
     role = ctx.role
     config = ctx.config
@@ -258,16 +291,17 @@ def _run_install_hook(args, ctx) -> int:
               "Code config); refused on role=vm", file=sys.stderr)
         return 3
 
-    claude_home = Path(args.claude_home).expanduser() if args.claude_home else (
-        Path.home() / ".claude")
-    result = session_hook.install(
-        claude_home, _packaged_script(session_hook.HOOK_SCRIPT))
+    from ..update import claude_home_default
+
+    claude_home = (Path(args.claude_home).expanduser() if args.claude_home
+                   else claude_home_default())
+    results = session_hook.install_all(claude_home, _packaged_script)
     _emit(
-        result if args.json else None,
+        {"hooks": results} if args.json else None,
         args.json,
-        None if args.json else session_hook.render_human(result),
+        None if args.json else session_hook.render_all(results),
     )
-    return 0 if result["ok"] else 1
+    return 0 if all(r["ok"] for r in results) else 1
 
 
 def _run_mcp_config(args, ctx) -> int:
@@ -382,6 +416,7 @@ _HANDLERS = {
     "init": _run_init,
     "doctor": _run_doctor,
     "alerts": _run_alerts,
+    "check-egress": _run_check_egress,
     "exceptions": _run_exceptions,
     "install-hook": _run_install_hook,
     "mcp-config": _run_mcp_config,

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/cli_cmds/lifecycle_parser.py

@@ -105,6 +105,33 @@ def _add_alerts(sub) -> None:
     )
 
 
+def _add_check_egress(sub) -> None:
+    sp = sub.add_parser(
+        "check-egress",
+        help="SEC-07: judge one OUTBOUND string (a web-search query, a URL, a "
+             "message body) against this vault's overlay keyword tiers, and "
+             "refuse when a term is classified at or above the threshold "
+             "(default Confidential). The classification gate protects the READ "
+             "side; this is the only check on the write side of a tool call. "
+             "Ships NO terms — they come from overlay/keywords/, so a vault "
+             "with no decoder ring maps nothing and SAYS SO. Pure file reads: "
+             "no index, embedder, network or key. Exit 6 = refused.",
+    )
+    sp.add_argument("text", nargs="?", help="the outbound string; omit to read stdin")
+    sp.add_argument("--json", action="store_true")
+    sp.add_argument(
+        "--min-tier",
+        help="refuse at or above this tier (default: $BRAIN_EGRESS_TERM_MIN_TIER, "
+             "else Confidential). An unrecognised value fails CLOSED.",
+    )
+    sp.add_argument(
+        "--strict",
+        action="store_true",
+        help="also refuse when the overlay maps NO terms — for a deployment that "
+             "will not accept an all-clear produced by an empty decoder ring",
+    )
+
+
 def _add_exceptions(sub) -> None:
     sp = sub.add_parser(
         "exceptions",
@@ -217,6 +244,7 @@ def add_parser(sub) -> None:
     _add_init(sub)
     _add_doctor(sub)
     _add_alerts(sub)
+    _add_check_egress(sub)
     _add_exceptions(sub)
     _add_install_hook(sub)
     _add_mcp_config(sub)

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/cli_cmds/maintenance.py

@@ -121,7 +121,10 @@ def _run_curate(args, ctx) -> int:
 
 def _run_integrity(args, ctx) -> int:
     core = ctx.core
-    res = core.integrity(min_score=args.min_score, k=args.k)
+    scan_injection = bool(getattr(args, "injection", False))
+    res = core.integrity(
+        min_score=args.min_score, k=args.k, scan_injection=scan_injection,
+    )
     pairs = res["near_dup_pairs"]
     nodes = {}
     for p in pairs:
@@ -145,7 +148,12 @@ def _run_integrity(args, ctx) -> int:
     ]
     if res.get("audit_issue"):
         action_required.insert(0, res["audit_issue"])
-    injection = _injection_rows(args, ctx) if getattr(args, "injection", False) else None
+    # Gated for DISPLAY only — a finding names a note, so reporting it to an
+    # Internal-capped reader would leak the very thing the gate withholds.
+    injection = (
+        _filter_dicts(res["injection_rows"], args.max_tier)[0]
+        if scan_injection else None
+    )
     if injection:
         action_required.extend(
             maint.action_required_item(
@@ -158,7 +166,7 @@ def _run_integrity(args, ctx) -> int:
             for row in injection
             if row["verdict"] == "conceal"
         )
-    reads = _read_log_status(ctx)
+    reads = res["read_log"]
     if reads.get("bulk_reads"):
         action_required.append(maint.action_required_item(
             f"{reads['bulk_reads']} bulk read(s) in the last {reads['days']} days "
@@ -199,30 +207,6 @@ def _run_integrity(args, ctx) -> int:
     return 0
 
 
-def _read_log_status(ctx) -> dict:
-    """SEC-06 access summary. Counts only — the log stores no note ids at all."""
-    from .. import read_log as _rl
-
-    try:
-        return _rl.status(getattr(ctx.core, "vault", None))
-    except Exception:
-        return {"available": False, "reason": "read-log unreadable"}
-
-
-def _injection_rows(args, ctx) -> list:
-    """SEC-05 corpus scan, gated at the same chokepoint as the near-dup pairs.
-
-    A finding NAMES a note, so it is egress-gated like any other content
-    surface — reporting "MNPI-note-x hides an instruction" to an Internal-capped
-    reader would leak the very thing the gate exists to withhold.
-    """
-    from .. import injection_scan as _isc
-
-    rows = _isc.scan_corpus(ctx.core.vault)
-    surfaced, _report = _filter_dicts(rows, args.max_tier)
-    return surfaced
-
-
 def _run_promote_scan(args, ctx) -> int:
     core = ctx.core
     res = core.promote_scan(k=args.k)

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/core/_health.py

@@ -227,7 +227,9 @@ class _CoreHealthMixin:
             },
             "auto_fixed": auto_fixed,
         }
-    def integrity(self, *, min_score: float = 0.95, k: int = 5) -> dict[str, Any]:
+    def integrity(
+        self, *, min_score: float = 0.95, k: int = 5, scan_injection: bool = True,
+    ) -> dict[str, Any]:
         """integrity-scan fold (task-disposition.md row 3): audit-chain verify
         + a corpus-wide near-dup scan directly over the brain vector backend
         (brain-cli-gaps.md G1 — no SC/MCP round-trip). READ-ONLY. UNFILTERED
@@ -299,12 +301,48 @@ class _CoreHealthMixin:
                 f"{type(exc).__name__}: {exc}",
                 "investigate the embedder/vector-backend, then re-run integrity"))
 
+        # SEC-05 corpus re-scan and the SEC-06 bulk-read alarm. Both lived ONLY
+        # in the `brain integrity` CLI body until 2026-09-01, so the Tuesday
+        # fold — the one caller that runs with no human present — fired neither
+        # of the two detectors built for indirect prompt injection. Moving them
+        # here is what arms them; the CLI now reads these keys instead of
+        # computing its own. UNFILTERED like `near_dup_pairs`: a finding NAMES a
+        # note, so every SURFACING caller egress-gates it.
+        injection_rows, reads = self._injection_and_reads(scan_injection, blocked)
+
         return {
             "ritual": "integrity", "min_score": min_score,
             "audit": audit_res, "audit_issue": audit_issue,
             "near_dup_pairs": pairs,  # UNFILTERED
+            "injection_rows": injection_rows,  # UNFILTERED
+            "read_log": reads,
             "blocked": blocked,
         }
+    def _injection_and_reads(
+        self, scan_injection: bool, blocked: list[dict[str, Any]],
+    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        """The two prompt-injection detectors, split out to keep `integrity`
+        inside the function-length ratchet. Appends to ``blocked`` in place:
+        a scan that raises is a reported gap, never a silent clean sweep."""
+        from .. import injection_scan as _isc
+        from .. import maintenance as maint
+        from .. import read_log as _rl
+
+        rows: list[dict[str, Any]] = []
+        if scan_injection:
+            try:
+                rows = _isc.scan_corpus(self.vault)
+            except Exception as exc:
+                blocked.append(maint.blocked_item(
+                    "concealed-instruction scan raised",
+                    f"{type(exc).__name__}: {exc}",
+                    "investigate brain.injection_scan, then re-run integrity"))
+        try:
+            reads = _rl.status(self.vault)
+        except Exception:
+            reads = {"available": False, "reason": "read-log unreadable"}
+        return rows, reads
+
     def promote_scan(self, *, k: int = 50) -> dict[str, Any]:
         """promotion-scan fold (task-disposition.md row 5 — ON-INVOKE triage;
         promotion itself stays a P-10 human gate). Candidates: ``raw/`` zone

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/deliverables_shelf.py

@@ -47,6 +47,7 @@ from __future__ import annotations
 
 import json
 import os
+import secrets
 import threading
 from dataclasses import dataclass
 from pathlib import Path
@@ -155,7 +156,11 @@ def _store_bindings(vault: Any, bindings: dict[str, Any]) -> None:
     path = _bindings_path(vault)
     path.parent.mkdir(parents=True, exist_ok=True)
     config.secure_file_permissions(path.parent, 0o700)
-    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    # A pid is not unique inside a process. Every caller today holds `_CLAIM_LOCK`
+    # plus the writer flock, so nothing races here now -- but a pid-named temp
+    # makes the NEXT caller's race silent, and the engine already has a
+    # collision-free convention (`cos/_io.py`, `lock.py`).
+    tmp = path.with_name(f"{path.name}.{secrets.token_hex(8)}.tmp")
     tmp.write_text(json.dumps(bindings, indent=2, sort_keys=True), encoding="utf-8")
     config.secure_file_permissions(tmp, 0o600)
     tmp.replace(path)

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/doctor_checks.py

@@ -209,9 +209,9 @@ def _terminal_rows(
                  *checks.mcp_vault_paths()])
     rows.append(checks.cos_deployed_skill())
     rows.extend(checks.desktop_plugin_store(context.app_support_dir, ssot))
-    from .session_hook import doctor_row as _session_hook_row
+    from .session_hook import doctor_rows as _session_hook_rows
 
-    rows.append(_session_hook_row(context.claude_home))
+    rows.extend(_session_hook_rows(context.claude_home))
     return rows
 
 

brainiac_cli-0.20.35/src/brain/egress_terms.py

@@ -0,0 +1,130 @@
+"""Outbound term guard (SEC-07) — refuse a protected term leaving in a tool call.
+
+**The gap this closes.** The classification gate protects the READ side: it
+decides what a caller may see. It says nothing about what the model then does
+with it. ``AGENTS.md``'s retrieval discipline rule 4 names the consequence —
+"the model's own web-search tool is an *ungated outbound channel*, and the
+query string itself is the leak" — and until this module that rule was PROSE,
+enforced by the model's compliance. A hostile document can carry an instruction
+that puts a codename into a search query; nobody reviews a query string, and by
+the time the results come back the term has already reached a third party.
+
+**Why the terms are not in this repo, and never will be.** A shipped list of
+one owner's counterparties is useless to every other owner and a disclosure in
+itself. The terms come from the vault's own **overlay** — ``overlay/keywords/``,
+the per-owner decoder ring whose rows are ``| Term | Expansion | Classification |``
+— read through :func:`brain.overlay.match_keyword_tier`. The engine ships the
+RULE; the vault supplies the DATA. That is the same split the overlay exists for
+(``overlay/README.md``), and those rows already drive ingest classification
+(``provenance.py``) and the COS grounding lane (``cos_ground.py``), so they stay
+current as a side effect of work the owner already does rather than as a second
+list to curate.
+
+**An empty decoder ring is REPORTED, never a quiet pass.** A vault that maps no
+terms cannot have a term caught, and a check whose all-clear means "nothing was
+looked at" is worse than no check. :func:`check` always returns
+``mapped_terms``, every caller surfaces it, and ``--strict`` turns an empty ring
+into a refusal for a deployment that wants fail-closed.
+
+**What this does NOT do.** It matches DECLARED terms, on word boundaries, case
+insensitively. It does not catch a paraphrase, a codename nobody wrote down, or
+a fact the model restates in its own words. It raises the bar for the terms an
+owner has declared. It does not close the channel, and no caller should describe
+it as though it did.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from . import classification as cls
+
+#: Terms at or above this tier refuse. `Internal` is deliberately NOT the
+#: default: an owner's whole vault is Internal by default, so defaulting there
+#: would refuse almost every query and the guard would be switched off within a
+#: day. `Confidential` is the first tier that means "this one is actually
+#: sensitive".
+DEFAULT_MIN_TIER = "Confidential"
+
+#: Exit code for a refused text. Distinct from 3 (VM refusal), 4 and
+#: 5 (SEC-06 record failure) so a hook can tell them apart.
+EXIT_REFUSED = 6
+
+MIN_TIER_ENV_VAR = "BRAIN_EGRESS_TERM_MIN_TIER"
+
+
+def min_tier() -> str:
+    """The configured refusal threshold, fail-CLOSED on an unrecognised value.
+
+    A typo must never silently widen what may leave: the only reason to set
+    this var is to change the threshold deliberately, so an unreadable value
+    falls to the most protective tier rather than the permissive default.
+    Same rule, and same reasoning, as ``mcp_verbs._egress_ceiling_tier``.
+    """
+    raw = os.environ.get(MIN_TIER_ENV_VAR, "").strip()
+    if not raw:
+        return DEFAULT_MIN_TIER
+    return raw if raw in cls.RANK else cls.TIERS[0]
+
+
+def check(
+    text: str,
+    *,
+    vault: str | os.PathLike[str] | None = None,
+    overlay_dir: str | os.PathLike[str] | None = None,
+    threshold: str | None = None,
+    strict: bool = False,
+) -> dict[str, Any]:
+    """Judge one outbound string against this vault's overlay keyword tiers.
+
+    Returns ``allowed`` plus everything a caller needs to explain itself:
+    the matched ``term`` and its ``tier``, the ``threshold`` applied, and
+    ``mapped_terms`` — the size of the decoder ring that was actually
+    consulted, so a zero is visible rather than indistinguishable from a pass.
+    """
+    from . import overlay as ov
+
+    if threshold is None:
+        bar = min_tier()
+    elif threshold in cls.RANK:
+        bar = threshold
+    else:
+        bar = cls.TIERS[0]  # fail-closed on a typo, as `min_tier` does
+    mapped = ov.resolve_keyword_tiers(vault, overlay_dir)
+    tier, term = (None, None)
+    if mapped and text:
+        tier, term = ov.match_keyword_tier(text, vault, overlay_dir)
+
+    refused = bool(tier) and cls.RANK[tier] >= cls.RANK[bar]
+    no_terms = not mapped
+    return {
+        "allowed": not refused and not (strict and no_terms),
+        "refused_for": "term" if refused else ("no-mapped-terms" if strict and no_terms else None),
+        "term": term if refused else None,
+        "tier": tier if refused else None,
+        "threshold": bar,
+        "mapped_terms": len(mapped),
+        "strict": strict,
+    }
+
+
+def explain(result: dict[str, Any]) -> str:
+    """One line a hook can print, saying WHY — including on the allow path.
+
+    The empty-decoder-ring case gets its own sentence on purpose: a caller
+    reading only "allowed" would report a vault that protects nothing as a
+    vault that found nothing.
+    """
+    if result.get("refused_for") == "term":
+        return (f"REFUSED: '{result['term']}' is classified {result['tier']} in this "
+                f"vault's overlay keywords (threshold {result['threshold']}). "
+                f"The query string itself is an egress event — rephrase without the term, "
+                f"or stay in the vault.")
+    if result.get("refused_for") == "no-mapped-terms":
+        return ("REFUSED (--strict): this vault's overlay maps NO keyword tiers, so "
+                "nothing could be checked. Fill overlay/keywords/ or drop --strict.")
+    if not result.get("mapped_terms"):
+        return ("allowed — but this vault's overlay maps NO keyword tiers, so no term "
+                "could have been caught. This is not evidence the text is safe.")
+    return (f"allowed — {result['mapped_terms']} mapped term(s) checked at "
+            f"threshold {result['threshold']}")

{brainiac_cli-0.20.34 → brainiac_cli-0.20.35}/src/brain/folds/weekly.py

@@ -46,6 +46,41 @@ class WeeklyFoldsMixin:
                         "near-dup scan",
                     )
                 )
+            # The two prompt-injection detectors. COUNTS ONLY, never note ids:
+            # `record_current_findings` persists this text into
+            # `.brain/notify-sent/current.json`, which the Cowork VM reads, so a
+            # name here would carry a title straight past the egress gate (the
+            # same rule `ingest_quarantine_findings` follows, and for the same
+            # reason). Each carries its own `notify_key` — without one an item
+            # stays in the maintain result and never reaches `brain alerts`.
+            conceal = [r for r in (result.get("injection_rows") or [])
+                       if r.get("verdict") == "conceal"]
+            if conceal:
+                item = maintenance.action_required_item(
+                    f"{len(conceal)} vault note(s) hide instructions from a human "
+                    f"reader (names withheld — run the gated command below)",
+                    "text concealed from a reader but visible to a model is the "
+                    "shape of an indirect prompt injection",
+                    "run `brain integrity --injection --json` for the gated list; "
+                    "read each note by hand and retire what is not yours",
+                    "concealed-instruction scan (SEC-05)",
+                )
+                item["notify_key"] = "injection:conceal"
+                run.action_required.append(item)
+            reads = result.get("read_log") or {}
+            if reads.get("bulk_reads"):
+                item = maintenance.action_required_item(
+                    f"{reads['bulk_reads']} bulk read(s) in the last "
+                    f"{reads['days']} day(s) (>= {reads['threshold']} notes "
+                    f"surfaced in one call)",
+                    "a single call surfacing hundreds of notes is a sweep, not a "
+                    "question — the shape an injected agent leaves when it "
+                    "exfiltrates through the gate",
+                    "review the rows; if none was yours, treat it as an incident",
+                    reads.get("dir", ""),
+                )
+                item["notify_key"] = "read-log:bulk"
+                run.action_required.append(item)
             run.mark("integrity", True)
         except Exception as exc:
             self._record_weekly_failure(run, "integrity", exc)