switchroom 0.21.16 → 0.21.17

package/vendor/hindsight-memory/scripts/tests/test_prefetch_invalidation.py

@@ -0,0 +1,329 @@
+"""M4 prefetch-buffer MUTATION INVALIDATION — red-team-M3 R2 (BLOCKER).
+
+The M4 prefetch buffer holds a RECALLED memories block captured at a prior
+turn's Stop hook and consumed at the next UserPromptSubmit. If a mutation —
+a rule/directive retire, or a retain that supersedes a fact — lands between
+producing that buffer and consuming it, the pre-mutation snapshot can
+resurrect the just-retired/just-changed content on a later turn. Worse,
+``prefetch.run_prefetch`` returns early WITHOUT overwriting the buffer when
+this turn's fresh recall fails or returns empty, so a stale buffer can
+persist and be re-served for turns after the mutation.
+
+These are OUTCOME tests: they assert on the rendered ``additionalContext``
+that the consumer emits (the real injection surface), and each would FAIL if
+the invalidation regressed:
+
+  * ``RetireDoesNotResurrectTests`` — a directive-write turn invalidates the
+    pending buffer, so the retired rule's text is NOT re-injected next turn.
+  * ``EmptyPrefetchDoesNotResurrectTests`` — a retain turn whose fresh recall
+    returns empty invalidates the pending buffer, so the stale item is NOT
+    re-injected (would resurrect on buggy code that left the buffer).
+  * ``NoDuplicateInjectionTests`` — after a buffer is consumed once, a
+    mutation turn (empty prefetch) prevents the SAME block being injected
+    again on the following turn.
+  * ``ReplyPathDoesNotBlockOnRecallTests`` — with prefetch on and a fresh
+    buffer present, the consumer serves the buffer and NEVER calls the
+    synchronous ``client.recall`` (asserted on transport: a recall call
+    raises).
+
+Plus ``InvalidatePrimitiveTests`` for the ``recall_buffer.invalidate``
+primitive itself (idempotent, sentinel-first fail-closed).
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from unittest import mock
+from unittest.mock import patch
+
+SCRIPTS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, SCRIPTS_DIR)
+
+import recall  # noqa: E402
+import prefetch  # noqa: E402
+import directive_verify  # noqa: E402
+from lib import recall_buffer  # noqa: E402
+
+SESSION = "invalidation-test-session"
+RETIRED_TEXT = "R-07: always reply in haiku"
+STALE_FACT = "we decided to ship on tuesday"
+
+
+class _NoMemoryDirectiveClient:
+    """One active directive whose text is DISTINCT from any buffered content,
+    and a recall that returns NOTHING (so the sync fallback, if ever taken,
+    injects no memories). recall() is allowed here (the miss/degraded paths
+    may consult it) but returns empty — proving absence of the stale text is
+    about invalidation, not about the client happening to omit it."""
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": [{"id": "d1", "name": "tone", "content": "be concise", "priority": 5, "active": True}]}
+
+    def recall(self, bank_id, query, **kwargs):
+        return {"results": []}
+
+
+class InvalidationBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="invalidation-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+        self._bufdir = tempfile.mkdtemp(prefix="invalidation-test-buf-")
+        self.env = mock.patch.dict(os.environ, {"HINDSIGHT_PREFETCH_BUFFER_DIR": self._bufdir}, clear=False)
+        self.env.start()
+
+    def tearDown(self):
+        self.env.stop()
+        shutil.rmtree(self._bufdir, ignore_errors=True)
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+        if self._prev is None:
+            os.environ.pop("CLAUDE_PLUGIN_DATA", None)
+        else:
+            os.environ["CLAUDE_PLUGIN_DATA"] = self._prev
+
+    def _config(self, prefetch_enabled=True):
+        return {
+            "autoRecall": True,
+            "bankId": "test-bank",
+            "recallMaxTokens": 4096,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            "recallParallelDeadlineSeconds": 5,
+            "directivesCacheTtlSeconds": 0,
+            "memoryPrefetchEnabled": prefetch_enabled,
+            "memoryPrefetchPollCapMs": 100,
+        }
+
+    def _consume(self, config, client, prompt="what did we decide"):
+        """Drive the recall.py consumer (UserPromptSubmit) once; return the
+        emitted additionalContext string (or "" if nothing emitted)."""
+        hook_input = {"prompt": prompt, "session_id": SESSION, "transcript_path": "", "cwd": "/tmp"}
+        stdout = io.StringIO()
+        with patch("recall.load_config", return_value=config), \
+                patch("recall.get_api_url", return_value="http://fake"), \
+                patch("recall.HindsightClient", return_value=client), \
+                patch("recall.ensure_bank_mission"), \
+                patch("sys.stdin", io.StringIO(json.dumps(hook_input))), \
+                patch("sys.stdout", stdout):
+            recall.main()
+        out = stdout.getvalue()
+        if not out:
+            return ""
+        return json.loads(out)["hookSpecificOutput"]["additionalContext"]
+
+
+class InvalidatePrimitiveTests(InvalidationBase):
+    def test_invalidate_removes_buffer_and_sentinel(self):
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        self.assertTrue(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+        recall_buffer.invalidate(SESSION)
+
+        self.assertFalse(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertFalse(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+        # read_if_fresh must now report nothing fresh (fail-closed).
+        payload, _ = recall_buffer.read_if_fresh(SESSION, last_consumed_token=None)
+        self.assertIsNone(payload)
+
+    def test_invalidate_is_idempotent_on_absent_files(self):
+        # No buffer written — must not raise.
+        recall_buffer.invalidate(SESSION)
+        recall_buffer.invalidate(SESSION)
+
+    def test_orphaned_payload_after_sentinel_first_delete_fails_closed(self):
+        # Simulate a partial invalidation where only the sentinel unlink
+        # landed (sentinel is deleted FIRST by design): an orphaned payload
+        # must never read as fresh.
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        os.remove(recall_buffer._sentinel_path(SESSION))
+        payload, _ = recall_buffer.read_if_fresh(SESSION, last_consumed_token=None)
+        self.assertIsNone(payload)
+
+
+class RetireDoesNotResurrectTests(InvalidationBase):
+    """Assertion (1): a directive retire invalidates the pending buffer so the
+    retired item is NOT re-injected on the next turn."""
+
+    def _retire_turn_messages(self):
+        # A real turn transcript: the user retires a rule, the assistant issues
+        # a delete_directive tool_use. This is what directive_verify inspects.
+        return [
+            {"role": "user", "content": "Retire the haiku rule R-07, it no longer applies."},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "tool_use", "id": "t1", "name": "delete_directive", "input": {"id": "d-r07"}}
+                ],
+            },
+        ]
+
+    def test_directive_write_turn_invalidates_buffer_and_blocks_resurrection(self):
+        config = self._config(prefetch_enabled=True)
+
+        # Turn N Stop: prefetch buffered the rule text while it was still active.
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1: the retire lands. directive_verify's Stop-hook invalidation
+        # detects the delete_directive write and drops the pending buffer.
+        directive_verify.invalidate_prefetch_buffer_on_directive_write(
+            self._retire_turn_messages(), config, SESSION
+        )
+        self.assertFalse(
+            os.path.isfile(recall_buffer._sentinel_path(SESSION)),
+            "directive-write turn must invalidate the pending prefetch buffer",
+        )
+
+        # Turn N+2 UserPromptSubmit: the consumer must NOT re-inject the retired
+        # rule text. (With no fresh buffer it takes the sync/degraded path, which
+        # here surfaces only the fresh directive block, not the retired text.)
+        ctx = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            "R-07", ctx,
+            "retired rule text must not resurrect from a pre-retire prefetch buffer",
+        )
+        self.assertNotIn("haiku", ctx)
+
+    def test_non_directive_turn_leaves_buffer_intact(self):
+        # Guard against over-invalidation: an ordinary turn (no directive write)
+        # must NOT drop the buffer, or every turn would lose the prefetch.
+        config = self._config(prefetch_enabled=True)
+        recall_buffer.write_buffer(SESSION, "- a normal prefetched memory", {})
+        recall_buffer.write_sentinel(SESSION)
+        directive_verify.invalidate_prefetch_buffer_on_directive_write(
+            [
+                {"role": "user", "content": "what's the weather"},
+                {"role": "assistant", "content": "Sunny."},
+            ],
+            config,
+            SESSION,
+        )
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+    def test_flag_off_is_a_noop(self):
+        # Kill switch: with prefetch off, the directive-write invalidation must
+        # not touch the buffer module at all.
+        config = self._config(prefetch_enabled=False)
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        with patch("directive_verify.recall_buffer.invalidate",
+                   side_effect=AssertionError("must not invalidate when prefetch is off")):
+            directive_verify.invalidate_prefetch_buffer_on_directive_write(
+                self._retire_turn_messages(), config, SESSION
+            )
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+
+class EmptyPrefetchDoesNotResurrectTests(InvalidationBase):
+    """Assertion (1) via the RETAIN mutation path: a retain turn whose fresh
+    recall returns empty must invalidate the pending buffer so the stale item
+    is NOT re-served. This FAILS on buggy code that returns early leaving the
+    old buffer in place."""
+
+    def test_retain_turn_with_empty_recall_invalidates_stale_buffer(self):
+        config = self._config(prefetch_enabled=True)
+
+        # Turn N Stop: a stale fact was buffered.
+        recall_buffer.write_buffer(SESSION, STALE_FACT, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1 Stop: prefetch runs (a retain mutation), but this turn's
+        # fresh recall returns NOTHING. run_prefetch must have already
+        # invalidated the old buffer up front — so no stale buffer survives.
+        empty_client = mock.Mock()
+        empty_client.recall.return_value = {"results": []}
+        hook_input = {
+            "prompt": "and another thing",
+            "session_id": SESSION,
+            "transcript_path": "",  # _last_human_prompt degrades to "" -> we inject a query below
+            "cwd": "/tmp",
+        }
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=empty_client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch._last_human_prompt", return_value="and another thing"):
+            wrote = prefetch.run_prefetch(hook_input, config)
+
+        self.assertFalse(wrote, "empty recall must not write a fresh buffer")
+        self.assertFalse(
+            os.path.isfile(recall_buffer._sentinel_path(SESSION)),
+            "a mutation (retain) turn must invalidate the stale buffer even when the fresh recall is empty",
+        )
+
+        # Turn N+2 UserPromptSubmit: the stale fact must NOT re-inject.
+        ctx = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            STALE_FACT, ctx,
+            "stale buffered fact must not resurrect after a mutation turn with an empty recall",
+        )
+
+
+class NoDuplicateInjectionTests(InvalidationBase):
+    """Assertion (2): the same buffered block is not injected twice. After a
+    turn consumes a buffer, a mutation turn (empty prefetch) prevents the SAME
+    block from being re-served on the following turn."""
+
+    def test_consumed_buffer_not_reinjected_after_mutation_turn(self):
+        config = self._config(prefetch_enabled=True)
+        marker = "- unique-fact-abc123 decided at standup"
+
+        recall_buffer.write_buffer(SESSION, marker, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1: consumer injects the buffered block once.
+        first = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertIn("unique-fact-abc123", first)
+
+        # Turn N+1 Stop: a mutation turn whose recall returns empty -> the old
+        # buffer is invalidated, nothing fresh written.
+        empty_client = mock.Mock()
+        empty_client.recall.return_value = {"results": []}
+        hook_input = {"prompt": "next", "session_id": SESSION, "transcript_path": "", "cwd": "/tmp"}
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=empty_client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch._last_human_prompt", return_value="next"):
+            prefetch.run_prefetch(hook_input, config)
+
+        # Turn N+2: the same block must NOT be injected a second time.
+        second = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            "unique-fact-abc123", second,
+            "a consumed buffer must not be re-injected after a mutation invalidated it",
+        )
+
+
+class ReplyPathDoesNotBlockOnRecallTests(InvalidationBase):
+    """Assertion (3): with prefetch on and a fresh buffer present, the reply
+    path (UserPromptSubmit consumer) joins the buffer and NEVER blocks on a
+    synchronous recall. Asserted on transport: client.recall raises if called."""
+
+    def test_fresh_buffer_served_without_calling_recall(self):
+        config = self._config(prefetch_enabled=True)
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory xyz", {})
+        recall_buffer.write_sentinel(SESSION)
+
+        class _ExplodingRecallClient:
+            def list_directives(self, bank_id, active_only=True, timeout=2):
+                return {"items": []}
+
+            def recall(self, bank_id, query, **kwargs):
+                raise AssertionError("reply path must not block on synchronous recall when a fresh buffer exists")
+
+        ctx = self._consume(config, _ExplodingRecallClient())
+        self.assertIn("a prefetched memory xyz", ctx)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/vendor/hindsight-memory/scripts/tests/test_recall_directive_suppression.py

@@ -0,0 +1,328 @@
+"""Memory v2 M3 (Surface-A) — directive-injection flip guard tests.
+
+carve-M3.md §4/§8. The flip's whole point is DETERMINISTIC: once an agent has
+migrated its standing directives into the CLAUDE.md rules block (M1) and the
+operator sets `memory.inject_directives: false`, this hook must STOP injecting
+the `<active_directives>` block on every turn — but ONLY when a non-empty rules
+block physically carries the same guarantees. These tests assert on TRANSPORT
+(what reaches stdout across all three recall emit surfaces), never on an
+internal flag, and each one is written so it would FAIL on the pre-guard code
+(directives always injected).
+
+Three defenses under test:
+  * flag OFF + rules block present     → SUPPRESS `<active_directives>`
+  * flag ON  (default)                 → inject normally (control)
+  * flag OFF but NO/empty rules block  → FAIL SAFE: still inject + degraded
+    canary notice (a mis-sequenced flip is loud, never silently memoryless)
+
+The rules-block bytes come from the golden fixture generated by the TS
+`renderRulesBlock` (pinned by src/memory/m3-rules-block-golden.test.ts), so a
+format change on the TS side trips both languages.
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+SCRIPTS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, SCRIPTS_DIR)
+
+import recall  # noqa: E402
+
+_FIXTURE = os.path.join(
+    os.path.dirname(__file__), "fixtures", "rules-block.golden.md"
+)
+
+
+def _golden_rules_block() -> str:
+    with open(_FIXTURE, encoding="utf-8") as fh:
+        return fh.read()
+
+
+# An empty rules block (markers present, only the `(none)` placeholder inside)
+# — the shape M1 writes for an agent that has enabled the toolchain but added
+# no rules yet. This MUST NOT count as a populated block (fail-safe fires).
+_EMPTY_RULES_BLOCK = "\n".join(
+    [
+        "<!-- switchroom:rules:begin -->",
+        "Standing rules — sanctioned via the `memory rule` tool. Do not hand-edit;",
+        "edits made outside the tool break the tamper sentinel below.",
+        "",
+        "(none)",
+        "",
+        "<!-- switchroom:rules:sentinel sha256="
+        + ("0" * 64)
+        + " rules=0 -->",
+        "<!-- switchroom:rules:end -->",
+    ]
+)
+
+
+class _DirectiveClient:
+    """A client that always has one active directive AND one recallable memory.
+
+    `recall_called` records whether the noisy memory fetch ran — irrelevant to
+    the M3 assertions but kept so a test can prove recall still happens on the
+    non-flipped control (memory text present ⇒ synchronous path ran).
+    """
+
+    def __init__(self):
+        self.recall_called = False
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": [{
+            "id": "d1", "name": "always-wave", "priority": 10,
+            "content": "always end replies with a wave",
+        }]}
+
+    def recall(self, bank_id, query, **kwargs):
+        self.recall_called = True
+        return {"results": [{
+            "text": "a real memory", "type": "fact",
+            "mentioned_at": "2026-01-01", "id": "m1", "scores": {"final": 0.9},
+        }]}
+
+
+class _DirectiveFlipTestBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="recall-m3-flip-test-")
+        self._prev_data = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+        # Project dirs are resolved via CLAUDE_PROJECT_DIR / hook cwd. Pin the
+        # env to a NON-project sentinel so tests that rely on the hook `cwd`
+        # fallback aren't polluted by an inherited CLAUDE_PROJECT_DIR.
+        self._prev_proj = os.environ.get("CLAUDE_PROJECT_DIR")
+        os.environ.pop("CLAUDE_PROJECT_DIR", None)
+
+    def tearDown(self):
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+        for key, prev in (
+            ("CLAUDE_PLUGIN_DATA", self._prev_data),
+            ("CLAUDE_PROJECT_DIR", self._prev_proj),
+        ):
+            if prev is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = prev
+
+    def _project_dir(self, claude_md: str | None) -> str:
+        """Create a project dir; write CLAUDE.md with `claude_md` if given."""
+        proj = tempfile.mkdtemp(prefix="proj-", dir=self._tmpdir)
+        if claude_md is not None:
+            with open(os.path.join(proj, "CLAUDE.md"), "w", encoding="utf-8") as fh:
+                fh.write(claude_md)
+        return proj
+
+    def _config(self, inject_directives):
+        cfg = {
+            "autoRecall": True,
+            "bankId": "test-bank",
+            "recallMaxTokens": 4096,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            "recallParallelDeadlineSeconds": 5,
+            "directivesCacheTtlSeconds": 0,
+        }
+        if inject_directives is not None:
+            cfg["injectDirectives"] = inject_directives
+        return cfg
+
+    def _run_main(self, prompt, config, cwd, client):
+        hook_input = {
+            "prompt": prompt,
+            "session_id": "test-session",
+            "transcript_path": "",
+            "cwd": cwd,
+        }
+        stdout = io.StringIO()
+        with patch("recall.load_config", return_value=config), \
+                patch("recall.get_api_url", return_value="http://fake"), \
+                patch("recall.HindsightClient", return_value=client), \
+                patch("recall.ensure_bank_mission"), \
+                patch("sys.stdin", io.StringIO(json.dumps(hook_input))), \
+                patch("sys.stdout", stdout):
+            recall.main()
+        return stdout.getvalue()
+
+
+class RulesBlockDetectionTests(_DirectiveFlipTestBase):
+    """Unit coverage for the physical-evidence check the guard turns on."""
+
+    def test_present_block_from_golden_fixture_is_detected(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        self.assertTrue(recall.rules_block_present(proj))
+
+    def test_empty_none_placeholder_block_is_not_a_present_block(self):
+        proj = self._project_dir("# Agent\n\n" + _EMPTY_RULES_BLOCK)
+        self.assertFalse(
+            recall.rules_block_present(proj),
+            "the `(none)` placeholder must not count as a populated rules block",
+        )
+
+    def test_no_markers_is_not_a_present_block(self):
+        proj = self._project_dir("# Agent\n\njust some prose, no rules block.")
+        self.assertFalse(recall.rules_block_present(proj))
+
+    def test_missing_claude_md_is_not_a_present_block(self):
+        proj = self._project_dir(None)
+        self.assertFalse(recall.rules_block_present(proj))
+
+    def test_none_project_dir_is_not_a_present_block(self):
+        self.assertFalse(recall.rules_block_present(None))
+
+    def test_project_dir_prefers_env_then_hook_cwd(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        # env wins when set
+        os.environ["CLAUDE_PROJECT_DIR"] = proj
+        self.assertEqual(recall._recall_project_dir({"cwd": "/nope"}), proj)
+        # falls back to hook cwd when env unset
+        os.environ.pop("CLAUDE_PROJECT_DIR", None)
+        self.assertEqual(recall._recall_project_dir({"cwd": proj}), proj)
+
+
+class DirectiveInjectionDecisionTests(_DirectiveFlipTestBase):
+    """The pure decision function — the deterministic core the surfaces share."""
+
+    def test_flag_on_injects(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        inject, notice = recall.directive_injection_decision(
+            self._config(True), {"cwd": proj}
+        )
+        self.assertTrue(inject)
+        self.assertIsNone(notice)
+
+    def test_flag_absent_defaults_to_inject(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        inject, notice = recall.directive_injection_decision(
+            self._config(None), {"cwd": proj}
+        )
+        self.assertTrue(inject, "injectDirectives must default TRUE when unset")
+        self.assertIsNone(notice)
+
+    def test_flag_off_with_rules_block_suppresses(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        inject, notice = recall.directive_injection_decision(
+            self._config(False), {"cwd": proj}
+        )
+        self.assertFalse(inject, "flipped agent with a rules block must suppress")
+        self.assertIsNone(notice)
+
+    def test_flag_off_without_rules_block_fails_safe(self):
+        proj = self._project_dir("# Agent\n\nno rules block here.")
+        inject, notice = recall.directive_injection_decision(
+            self._config(False), {"cwd": proj}
+        )
+        self.assertTrue(inject, "flag off + no rules block must FAIL SAFE (inject)")
+        self.assertIsNotNone(notice)
+        self.assertIn("injectDirectives is OFF", notice)
+
+
+class MainPathTransportTests(_DirectiveFlipTestBase):
+    """Surface 1 (synchronous main path) — assert on stdout transport."""
+
+    def test_flipped_in_budget_agent_suppresses_active_directives(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        client = _DirectiveClient()
+        out = self._run_main("what did we decide about X?", self._config(False), proj, client)
+        # Recall still ran and returned a memory — but the directives block is gone.
+        self.assertTrue(out, "a flipped agent still emits its recalled memories")
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        self.assertNotIn(
+            "<active_directives>", ctx,
+            "flipped + in-budget agent must NOT inject the directives block",
+        )
+        self.assertNotIn("always end replies with a wave", ctx)
+        self.assertIn("a real memory", ctx, "non-directive recall must be untouched")
+
+    def test_unflipped_agent_still_injects_active_directives(self):
+        # Control: identical setup, flag ON — directives MUST still appear. A
+        # test that passed under the pre-guard code (always injects) is only
+        # valid because its sibling above proves suppression actually happens.
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        out = self._run_main("what did we decide about X?", self._config(True), proj, _DirectiveClient())
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        self.assertIn("<active_directives>", ctx)
+        self.assertIn("always end replies with a wave", ctx)
+
+    def test_flag_off_no_rules_block_fails_safe_with_notice(self):
+        proj = self._project_dir("# Agent\n\nno rules block here.")
+        out = self._run_main("what did we decide about X?", self._config(False), proj, _DirectiveClient())
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        # Fail-safe: directives STILL injected, plus the degraded canary notice.
+        self.assertIn("<active_directives>", ctx)
+        self.assertIn("always end replies with a wave", ctx)
+        self.assertIn("injectDirectives is OFF", ctx)
+
+
+class DirectivesOnlyPathTransportTests(_DirectiveFlipTestBase):
+    """Surface 2 (task-notification directives-only fast path)."""
+
+    def _run_directives_only(self, config, cwd, client):
+        return self._run_main(
+            "<task-notification>a background task finished</task-notification>",
+            config, cwd, client,
+        )
+
+    def test_flipped_in_budget_suppresses_on_task_notification(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        out = self._run_directives_only(self._config(False), proj, _DirectiveClient())
+        self.assertEqual(
+            out, "",
+            "flipped agent's task-notification path must emit no directives",
+        )
+
+    def test_unflipped_injects_directives_on_task_notification(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        out = self._run_directives_only(self._config(True), proj, _DirectiveClient())
+        self.assertTrue(out, "unflipped agent still injects directives on this path")
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        self.assertIn("<active_directives>", ctx)
+        self.assertIn("always end replies with a wave", ctx)
+
+
+class PrefetchPathTransportTests(_DirectiveFlipTestBase):
+    """Surface 3 (memory-prefetch fast path, `_handle_prefetch_buffer`)."""
+
+    def _run_prefetch(self, config, cwd, client):
+        hook_input = {
+            "prompt": "what did we decide about X?",
+            "session_id": "test-session",
+            "transcript_path": "",
+            "cwd": cwd,
+        }
+        stdout = io.StringIO()
+        with patch("recall.get_api_url", return_value="http://fake"), \
+                patch("recall.HindsightClient", return_value=client), \
+                patch("recall.recall_buffer.sentinel_exists", return_value=False), \
+                patch("recall.recall_buffer.read_if_fresh", return_value=(None, None)), \
+                patch("recall.read_state", return_value={}), \
+                patch("sys.stdout", stdout):
+            emitted = recall._handle_prefetch_buffer(config, hook_input, hook_input["prompt"])
+        return emitted, stdout.getvalue()
+
+    def test_flipped_in_budget_suppresses_on_prefetch_fast_path(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        _emitted, out = self._run_prefetch(self._config(False), proj, _DirectiveClient())
+        self.assertNotIn(
+            "<active_directives>", out,
+            "flipped agent must not leak directives on the prefetch fast path",
+        )
+        self.assertNotIn("always end replies with a wave", out)
+
+    def test_unflipped_injects_directives_on_prefetch_fast_path(self):
+        proj = self._project_dir("# Agent\n\n" + _golden_rules_block())
+        _emitted, out = self._run_prefetch(self._config(True), proj, _DirectiveClient())
+        self.assertIn("<active_directives>", out)
+        self.assertIn("always end replies with a wave", out)
+
+
+if __name__ == "__main__":
+    unittest.main()