needlepath-langchain 0.2.2__tar.gz → 0.2.3__tar.gz

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/CHANGELOG.md

@@ -2,22 +2,30 @@
 
 All notable changes to the `needlepath-langchain` Python package are documented here.
 
-## 0.2.2
+## 0.2.3 — 2026-11-04
 
 ### Fixed
 
-- **Tool-result seam applies a `sanitized_fallback`.** The service answers a
-  screened tool result with one model-facing packet (`rendered_context`, the
-  record with the offending span removed and marked in place) and no per-record
-  excerpt. The seam declined that packet as `NO_SAVING` and delivered the
-  unscreened original to the model. It now applies the packet
-  (`rewrite_reason: "sanitized"`), and the length guard is skipped for screened
-  packets, which are applied for what they removed, not for what they saved.
-- **Receipt on the message** (`response_metadata["needlepath"]`) now also carries
-  `outcome`, `security_action` and `usage`, so an agent trace holds the same
-  receipt the console shows.
-
-## Unreleased
+- **LangGraph `pre_model_hook` installs a blocked verdict.** The hook applied a
+  blocked selection through the ordinary placeholder path, where the length
+  guard could keep the withheld record. It now collapses every considered tool
+  result to the withheld notice, the same as the middleware's history seam.
+- **A blocked verdict is enforced in shadow mode too.** The middleware's and
+  the hook's own shadow flags no longer restore a withheld record: the notice
+  is installed in a shadow run and the receipt says it was one
+  (`shadow: true`, `reason: blocked`). Shadow still installs nothing for
+  every other reason.
+- **A `blocked` tool result is withheld from the model.** When workspace
+  policy withholds the record (`outcome: "blocked"`), the tool-result seam
+  returned the original message, so the withheld record reached the model.
+  The engine's verdict is now installed as the tool result: a short notice
+  naming the engine's categories (`rewrite_reason: "blocked"`), no length
+  guard, and the agent continues without the record. On the history seam
+  every record that was sent collapses to the same notice.
+- **Receipt carries `governance` verbatim.** `response_metadata["needlepath"]`
+  now includes the engine's `governance` block (records before/after/blocked,
+  category counts, policy revision, policies applied) when the response has
+  one. It is the audit evidence a governed workspace reads.
 
 ### Added
 
@@ -37,11 +45,25 @@ All notable changes to the `needlepath-langchain` Python package are documented
 
 ### Requires
 
-- **`needlepath` with `needlepath.integrations.system_one`**, which the
-  unreleased core adds. The dependency floor here still reads
-  `needlepath>=0.1.0,<1.0.0` and **must be raised to the core release that
-  carries that module before this package is published**, or a resolver is free
-  to pair this release with a core that cannot import it. Core releases first.
+- **`needlepath>=0.2.3`.** The dependency floor is raised from `0.1.0`: this
+  release reads `Reason.BLOCKED`, which core 0.2.3 adds, and imports
+  `needlepath.integrations.system_one`, which core 0.2.2 already ships. A
+  resolver can no longer pair this package with a core that lacks either.
+
+## 0.2.2 — 2026-11-03
+
+### Fixed
+
+- **Tool-result seam applies a `sanitized_fallback`.** The service answers a
+  screened tool result with one model-facing packet (`rendered_context`, the
+  record with the offending span removed and marked in place) and no per-record
+  excerpt. The seam declined that packet as `NO_SAVING` and delivered the
+  unscreened original to the model. It now applies the packet
+  (`rewrite_reason: "sanitized"`), and the length guard is skipped for screened
+  packets, which are applied for what they removed, not for what they saved.
+- **Receipt on the message** (`response_metadata["needlepath"]`) now also carries
+  `outcome`, `security_action` and `usage`, so an agent trace holds the same
+  receipt the console shows.
 
 ## 0.2.1 — 2026-09-03
 

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: needlepath-langchain
-Version: 0.2.2
+Version: 0.2.3
 Summary: Needlepath context selection for LangChain agents (AgentMiddleware) and LangGraph.
 Project-URL: Homepage, https://nextmoca.com
 Author: Next Moca Global, Inc.
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: langchain<2.0.0,>=1.2.9
-Requires-Dist: needlepath<1.0.0,>=0.1.0
+Requires-Dist: needlepath<1.0.0,>=0.2.3
 Provides-Extra: dev
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "needlepath-langchain"
-version = "0.2.2"
+version = "0.2.3"
 description = "Needlepath context selection for LangChain agents (AgentMiddleware) and LangGraph."
 readme = "README.md"
 requires-python = ">=3.10"          # langchain 1.x floor
@@ -29,7 +29,7 @@ classifiers = [
 # `langchain.agents.middleware` package and ModelRequest.system_message is
 # stable. Capped at the major, per §8.2.
 dependencies = [
-  "needlepath>=0.1.0,<1.0.0",
+  "needlepath>=0.2.3,<1.0.0",
   "langchain>=1.2.9,<2.0.0",
 ]
 

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/src/needlepath_langchain/_messages.py

@@ -45,7 +45,7 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any
 
-from needlepath import ContextRecord, RecordKind
+from needlepath import ContextRecord, RecordKind, SelectionResult
 
 try:  # pragma: no cover - exercised by the installed-langchain test matrix
     from langchain_core.messages import AIMessage, BaseMessage, SystemMessage, ToolMessage
@@ -298,6 +298,7 @@ def apply_selection(
     index_by_id: dict[str, int],
     placeholder: str,
     request_id: str,
+    withhold: bool = False,
 ) -> tuple[list[BaseMessage], int, int]:
     """Rewrite the selected and unselected messages. Returns (messages, before, after).
 
@@ -305,6 +306,11 @@ def apply_selection(
     would make a message *longer*, is refused and the original kept. Both are
     regressions however the service arrived at them, and refusing one message's
     rewrite is cheaper than failing the whole selection open.
+
+    ``withhold`` is the one exception, for a ``blocked`` verdict: every record
+    collapses to ``placeholder`` (the withheld notice) whatever its length,
+    because the original is the thing that must not be kept. ``excerpts`` is
+    ignored; a blocked response carries none.
     """
     out: list[BaseMessage] = list(messages)
     before = 0
@@ -313,6 +319,12 @@ def apply_selection(
         original = out[index]
         original_text = message_text(original)
         before += approx_tokens(original_text)
+        if withhold:
+            out[index] = rewrite_message(
+                original, placeholder, reason="blocked", request_id=request_id
+            )
+            after += approx_tokens(placeholder)
+            continue
         excerpt = excerpts.get(record_id)
         if excerpt is None and not placeholder.strip():
             # Invariant 2, at the mutation boundary. A blank custom placeholder
@@ -399,6 +411,26 @@ def reject_removed_options(kwargs: dict[str, Any]) -> None:
             raise TypeError(message)
 
 
+def withheld_notice(selection: SelectionResult, *, tool_name: str | None = None) -> str:
+    """The model-facing text installed for a record workspace policy withheld.
+
+    Built from the receipt only — the engine's category labels and the request
+    id — never from the record. The categories are the engine's own names for
+    what the policy matched (``scope:source:hr``, ``classifier:pii.us_ssn``);
+    they are wire fields, read here as labels, not evaluated.
+    """
+    response = selection.response
+    governance = response.extra.get("governance") if response is not None else None
+    counts = governance.get("category_counts") if isinstance(governance, dict) else None
+    categories = ", ".join(sorted(str(k) for k in counts)) if isinstance(counts, dict) else ""
+    what = f"the {tool_name} result" if tool_name else "this tool result"
+    why = f" ({categories})" if categories else ""
+    return (
+        f"[WITHHELD by workspace policy: {what} was not delivered to the model{why}. "
+        f"Request {selection.request_id}.]"
+    )
+
+
 __all__ = [
     "METADATA_KEY",
     "DEFAULT_PLACEHOLDER",
@@ -414,6 +446,7 @@ __all__ = [
     "prior_user_prompts",
     "rewrite_message",
     "apply_selection",
+    "withheld_notice",
     "tool_call_keywords",
     "REMOVED_OPTIONS",
     "reject_removed_options",

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/src/needlepath_langchain/langgraph.py

@@ -88,6 +88,7 @@ from typing import Any
 from needlepath import (
     AsyncNeedlepathClient,
     NeedlepathClient,
+    NeedlepathGuardrailError,
     Reason,
     SelectionResult,
     SelectionStats,
@@ -102,6 +103,7 @@ from ._messages import (
     latest_user_prompt,
     prior_user_prompts,
     reject_removed_options,
+    withheld_notice,
 )
 from .version import __version__
 
@@ -121,8 +123,8 @@ LLM_INPUT_MESSAGES = "llm_input_messages"
 class NeedlepathPreModelHook:
     """A callable ``pre_model_hook`` that selects context non-destructively.
 
-    Returns ``{"llm_input_messages": [...]}`` on every pass without exception,
-    and the list is never empty — see edges 2 and 3 in the module docstring.
+    Returns ``{"llm_input_messages": [...]}`` unless mandatory guardrail
+    enforcement fails. Returned lists are never empty; see edges 2 and 3.
 
     Instances are callable both synchronously and (via :meth:`ainvoke`)
     asynchronously; ``create_react_agent`` accepts any ``RunnableLike``, and a
@@ -195,6 +197,9 @@ class NeedlepathPreModelHook:
                 support_contract=self.support_contract,
             )
             return self._apply(messages, plan, selection)
+        except NeedlepathGuardrailError:
+            # Mandatory protection failures must stop the framework call.
+            raise
         except Exception:  # noqa: BLE001 - a defect here must not break the graph
             self._note(Reason.UNEXPECTED_ERROR)
             return self._always_write(messages)
@@ -204,6 +209,9 @@ class NeedlepathPreModelHook:
         messages = _messages_of(state)
         try:
             return await self._ainvoke(messages)
+        except NeedlepathGuardrailError:
+            # Mandatory protection failures must stop the framework call.
+            raise
         except Exception:  # noqa: BLE001 - a defect here must not break the graph
             self._note(Reason.UNEXPECTED_ERROR)
             return self._always_write(messages)
@@ -299,8 +307,11 @@ class NeedlepathPreModelHook:
         self.engine_stats.record(selection)
         # `self.shadow` is belt and braces — the core client already declines a
         # shadow result — but "measuring never changes behaviour" is enforced at
-        # the point of mutation rather than inherited.
-        if not selection.applied or self.shadow:
+        # the point of mutation rather than inherited. A blocked verdict is the
+        # one delivery shadow does not suppress: shadow never restores a
+        # withheld record, so it is installed below, shadow or not.
+        blocked = selection.reason == Reason.BLOCKED
+        if not selection.applied or (self.shadow and not blocked):
             # Nothing is installed on this path, so the ACTUAL before/after is
             # the size of what was considered, unchanged.
             candidate_tokens = sum(approx_tokens(r.text) for r in plan["records"])
@@ -312,10 +323,18 @@ class NeedlepathPreModelHook:
             messages,
             excerpts=selection.excerpts,
             index_by_id=plan["index_by_id"],
-            placeholder=self.placeholder,
+            # A blocked verdict covers every record that was sent: each one
+            # collapses to the withheld notice, which names the policy's
+            # categories, rather than to the selection placeholder, which
+            # would claim a record was merely not selected.
+            placeholder=withheld_notice(selection) if blocked else self.placeholder,
             request_id=selection.request_id,
+            withhold=blocked,
         )
-        if after >= before:
+        if after >= before and not blocked:
+            # The guard refuses a rewrite that saves nothing. A withheld
+            # record is not a saving, and refusing the notice on length would
+            # write the original — exactly what a blocked verdict forbids.
             declined = selection.declined(Reason.NO_SAVING)
             # Nothing is installed here either: `rewritten` is computed but
             # never written, so actual after == actual before.

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/src/needlepath_langchain/middleware.py

@@ -10,7 +10,8 @@ tool results in the history are selected against the *current* task. A result
 that mattered three steps ago and does not matter now collapses; the one that
 matters is excerpted verbatim.
 
-Both fail open. Both stand down below a trigger. Neither ever removes a message.
+Ordinary selection failures fail open; mandatory guardrail errors stop the call.
+Both stand down below a trigger. Neither ever removes a message.
 
 Positioning, because a developer evaluating this already has the free option
 installed (§8.3): LangChain ships ``ContextEditingMiddleware`` with a
@@ -47,6 +48,7 @@ from needlepath import (
     AsyncNeedlepathClient,
     NeedlepathClient,
     NeedlepathConfigError,
+    NeedlepathGuardrailError,
     Reason,
     SelectionResult,
     SelectionStats,
@@ -65,6 +67,7 @@ from ._messages import (
     reject_removed_options,
     rewrite_message,
     tool_call_keywords,
+    withheld_notice,
 )
 from .version import __version__
 
@@ -89,7 +92,7 @@ USER_AGENT_SUFFIX = f"needlepath-langchain/{__version__}"
 
 
 class NeedlepathMiddleware(AgentMiddleware):
-    """Select context for a LangChain agent, failing open on every error path.
+    """Select context; propagate mandatory guardrail enforcement failures.
 
     ::
 
@@ -249,6 +252,9 @@ class NeedlepathMiddleware(AgentMiddleware):
                 return result
             selection = self._select_sync(plan)
             return self._finish_tool_call(result, plan, selection)
+        except NeedlepathGuardrailError:
+            # Mandatory protection failures must stop the framework call.
+            raise
         except Exception:  # noqa: BLE001 - see _fail_open
             return self._fail_open(result)
 
@@ -264,6 +270,9 @@ class NeedlepathMiddleware(AgentMiddleware):
                 return result
             selection = await self._select_async(plan)
             return self._finish_tool_call(result, plan, selection)
+        except NeedlepathGuardrailError:
+            # Mandatory protection failures must stop the framework call.
+            raise
         except Exception:  # noqa: BLE001 - see _fail_open
             return self._fail_open(result)
 
@@ -283,6 +292,9 @@ class NeedlepathMiddleware(AgentMiddleware):
                 if plan is None
                 else self._finish_history(request, plan, self._select_sync(plan))
             )
+        except NeedlepathGuardrailError:
+            # Mandatory protection failures must stop the framework call.
+            raise
         except Exception:  # noqa: BLE001 - see _fail_open
             outgoing = self._fail_open(request)
         return handler(outgoing)
@@ -299,6 +311,9 @@ class NeedlepathMiddleware(AgentMiddleware):
                 if plan is None
                 else self._finish_history(request, plan, await self._select_async(plan))
             )
+        except NeedlepathGuardrailError:
+            # Mandatory protection failures must stop the framework call.
+            raise
         except Exception:  # noqa: BLE001 - see _fail_open
             outgoing = self._fail_open(request)
         return await handler(outgoing)
@@ -308,8 +323,8 @@ class NeedlepathMiddleware(AgentMiddleware):
     def _fail_open(self, original: Any) -> Any:
         """The last line of §8.2's fail-open rule: **our own** defects.
 
-        The core client already guarantees that ``select()`` never raises, so
-        the service being slow, down, or wrong is handled a layer below this.
+        The core client handles ordinary selection failures. Mandatory
+        guardrail errors are propagated before this fallback is reached.
         What is *not* handled a layer below is a bug in this package — an index
         slipping in ``apply_selection``, a message shape nobody anticipated, a
         framework minor that changes a field's type under us. Without this, such
@@ -420,13 +435,27 @@ class NeedlepathMiddleware(AgentMiddleware):
         self.engine_stats.record(selection)
         original = message_text(result)
         original_tokens = approx_tokens(original)
-        if not selection.applied or self._shadow_blocks():
+        if not selection.applied or self._shadow_blocks(selection):
             # Nothing is installed on this path: actual after == actual before.
             unchanged = _with_actual_tokens(
                 selection, before=original_tokens, after=original_tokens
             )
             self.stats.record(unchanged)
             return _annotate(result, selection)
+        if selection.reason == Reason.BLOCKED:
+            # Workspace policy withheld the record. The engine's verdict is
+            # installed as the tool result — a short notice in place of the
+            # content — so the agent continues without the record and the
+            # receipt says why. No length guard: a withheld record is not a
+            # saving, and refusing the notice would hand the record back.
+            notice = withheld_notice(selection, tool_name=getattr(result, "name", None))
+            self.stats.record(
+                _with_actual_tokens(selection, before=original_tokens, after=approx_tokens(notice))
+            )
+            rewritten = rewrite_message(
+                result, notice, reason="blocked", request_id=selection.request_id
+            )
+            return _annotate(rewritten, selection)
         excerpt = selection.excerpts.get(plan.records[0].id or "")
         rewrite_reason = "excerpt"
         if excerpt is None and selection.reason == Reason.SANITIZED_FALLBACK:
@@ -463,7 +492,7 @@ class NeedlepathMiddleware(AgentMiddleware):
         self, request: ModelRequest, plan: _Plan, selection: SelectionResult
     ) -> ModelRequest:
         self.engine_stats.record(selection)
-        if not selection.applied or self._shadow_blocks():
+        if not selection.applied or self._shadow_blocks(selection):
             # Nothing is installed on this path, so the ACTUAL before/after is
             # the size of what was considered, unchanged.
             candidate_tokens = sum(approx_tokens(r.text) for r in plan.records)
@@ -471,14 +500,23 @@ class NeedlepathMiddleware(AgentMiddleware):
                 _with_actual_tokens(selection, before=candidate_tokens, after=candidate_tokens)
             )
             return request
+        blocked = selection.reason == Reason.BLOCKED
         messages, before, after = apply_selection(
             plan.messages,
             excerpts=selection.excerpts,
             index_by_id=plan.index_by_id,
-            placeholder=self.placeholder,
+            # A blocked verdict covers every record that was sent: each one
+            # collapses to the withheld notice, which names the policy's
+            # categories, rather than to the selection placeholder, which
+            # would claim a record was merely not selected.
+            placeholder=withheld_notice(selection) if blocked else self.placeholder,
             request_id=selection.request_id,
+            withhold=blocked,
         )
-        if after >= before:
+        if after >= before and not blocked:
+            # The guard refuses a rewrite that saves nothing. A withheld
+            # record is not a saving, and refusing the notice on length would
+            # install the original — exactly what a blocked verdict forbids.
             declined = selection.declined(Reason.NO_SAVING)
             # Nothing is installed here either: `messages` is computed but
             # never returned, so actual after == actual before.
@@ -498,7 +536,7 @@ class NeedlepathMiddleware(AgentMiddleware):
     # Calling
     # ------------------------------------------------------------------ #
 
-    def _shadow_blocks(self) -> bool:
+    def _shadow_blocks(self, selection: SelectionResult) -> bool:
         """Belt and braces: shadow must not apply, whatever the result says.
 
         ``_finish`` in the core client already marks a shadow run's reason as
@@ -507,8 +545,12 @@ class NeedlepathMiddleware(AgentMiddleware):
         made to a customer running this against production traffic, and a
         promise like that should be enforced at the point of mutation rather
         than inherited from a value computed three call frames away.
+
+        The one delivery shadow does not suppress is a blocked verdict: shadow
+        never restores a withheld record, so the notice is installed in a
+        shadow run too, and the receipt says it was one.
         """
-        return self.shadow
+        return self.shadow and selection.reason != Reason.BLOCKED
 
     def _shadow_override(self) -> bool | None:
         """Per-call shadow, so a caller-supplied client cannot silently ignore it.
@@ -643,20 +685,12 @@ def _annotate(message: ToolMessage, selection: SelectionResult) -> ToolMessage:
     metadata = dict(getattr(message, "response_metadata", {}) or {})
     metadata.setdefault("needlepath", {})
     merged = dict(metadata["needlepath"]) if isinstance(metadata["needlepath"], dict) else {}
+    # The whole receipt comes from the core client: outcome, screening action,
+    # metered line and the governance evidence (records before and after, what
+    # was withheld and under which policy revision) included, verbatim. This
+    # package reads one label out of `governance` for the notice and decides
+    # nothing from it.
     merged.update(selection.metadata(prefix=""))
-    response = selection.response
-    if response is not None:
-        # The rest of the receipt, metadata-only like everything above: how the
-        # service resolved the request, what the screening did, and the
-        # metered line it billed. Nothing here is derived from record text.
-        if response.outcome is not None:
-            merged["outcome"] = response.outcome
-        action = response.format_metrics.get("security_action")
-        if action:
-            merged["security_action"] = str(action)
-        usage = response.extra.get("usage")
-        if isinstance(usage, dict):
-            merged["usage"] = dict(usage)
     metadata["needlepath"] = merged
     return message.model_copy(update={"response_metadata": metadata})
 

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/src/needlepath_langchain/version.py

@@ -1,3 +1,3 @@
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 __all__ = ["__version__"]

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/tests/test_langgraph_recipe.py

@@ -14,6 +14,7 @@ import pytest
 from conftest import OP, FakeToolCallingModel, big, clients, echoing_service, partial_service
 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
 from langchain_core.tools import tool
+from needlepath import NeedlepathGuardrailError, Reason
 from needlepath.testing import error
 
 from needlepath_langchain._messages import approx_tokens, message_text
@@ -63,6 +64,90 @@ def thread():
     ]
 
 
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.parametrize(
+    "response",
+    [
+        pytest.param(error(503, "guardrails_unavailable"), id="unavailable"),
+        pytest.param(
+            echoing_service(
+                governance={"enabled": True, "policies_applied": 1},
+            ),
+            id="malformed-evidence",
+        ),
+    ],
+)
+@pytest.mark.parametrize("shadow", [False, True])
+def test_guardrail_failure_never_writes_unfiltered_model_input(asynchronous, response, shadow):
+    h, _, _ = hook([response], shadow=shadow, history_max_tokens=10)
+    with pytest.raises(NeedlepathGuardrailError):
+        if asynchronous:
+            asyncio.run(h.ainvoke({"messages": thread()}))
+        else:
+            h({"messages": thread()})
+
+
+def blocked_service():
+    return echoing_service(
+        selected=[],
+        records_selected=0,
+        rendered_context="",
+        outcome="blocked",
+        governance={
+            "enabled": True,
+            "policies_applied": 1,
+            "records_blocked": 1,
+            "raw_context_fallback_allowed": False,
+            "category_counts": {"scope:source:hr": 1},
+        },
+    )
+
+
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.parametrize("shadow", [False, True])
+def test_a_blocked_verdict_withholds_the_records_from_the_model_input_never_raises(
+    asynchronous, shadow
+):
+    """The counterpart of the test above for ``outcome: blocked``: not an
+    enforcement failure but an applied verdict. The key is still written, the
+    list is still the full thread, and every considered tool result is the
+    withheld notice rather than the record. Shadow installs nothing."""
+    h, _, _ = hook([blocked_service()], shadow=shadow, history_max_tokens=10)
+    messages = thread()
+    out = (
+        asyncio.run(h.ainvoke({"messages": messages}))
+        if asynchronous
+        else h({"messages": messages})
+    )
+    written = out[LLM_INPUT_MESSAGES]
+    assert len(written) == len(messages)
+    tool_texts = [message_text(m) for m in written if isinstance(m, ToolMessage)]
+    assert tool_texts
+    # Shadow or live: shadow never restores a withheld record.
+    for text in tool_texts:
+        assert "withheld" in text.lower()
+        assert "scope:source:hr" in text
+        assert BIG_PAYLOAD not in text
+    assert h.stats.reasons == {Reason.BLOCKED: 1}
+    assert h.stats.applied == 1
+
+
+def test_shadow_still_withholds_a_blocked_record_from_the_model_input():
+    """The hook's own shadow flag is belt and braces for every delivery the
+    model could have had anyway. A withheld record is not one of those: the
+    notice is written to ``llm_input_messages`` in a shadow run too."""
+    h, transport, _ = hook([blocked_service()], shadow=True, history_max_tokens=10)
+    out = h({"messages": thread()})
+    assert len(transport.calls) == 1
+    written = out[LLM_INPUT_MESSAGES]
+    tool_texts = [message_text(m) for m in written if isinstance(m, ToolMessage)]
+    assert len(tool_texts) == 1
+    assert BIG_PAYLOAD not in tool_texts[0]
+    assert "withheld" in tool_texts[0].lower()
+    assert h.stats.reasons == {Reason.BLOCKED: 1}
+    assert h.stats.applied == 1
+
+
 # --------------------------------------------------------------------------- #
 # Edge 2: the key is written unconditionally
 # --------------------------------------------------------------------------- #

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.3}/tests/test_middleware.py

@@ -6,9 +6,9 @@ import asyncio
 
 import pytest
 from conftest import OP, big, clients, echoing_service, partial_service
-from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
 from langgraph.types import Command
-from needlepath import NeedlepathTimeoutError, Reason, SelectionResult
+from needlepath import NeedlepathGuardrailError, NeedlepathTimeoutError, Reason, SelectionResult
 from needlepath.testing import error
 
 from needlepath_langchain import NeedlepathMiddleware
@@ -43,6 +43,100 @@ class FakeModelRequest:
         return clone
 
 
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.parametrize("seam", ["tool", "model"])
+@pytest.mark.parametrize(
+    "response",
+    [
+        pytest.param(error(503, "guardrails_unavailable"), id="unavailable"),
+        pytest.param(
+            echoing_service(
+                governance={"enabled": True, "policies_applied": 1},
+            ),
+            id="malformed-evidence",
+        ),
+    ],
+)
+@pytest.mark.parametrize("shadow", [False, True])
+def test_guardrail_failure_stops_instead_of_forwarding_raw_context(
+    long_tool_message,
+    asynchronous,
+    seam,
+    response,
+    shadow,
+):
+    mw, _, _ = middleware([response], shadow=shadow, history_max_tokens=10)
+    request = (
+        FakeToolCallRequest()
+        if seam == "tool"
+        else FakeModelRequest([HumanMessage(content="question"), long_tool_message])
+    )
+
+    def handler(request):
+        if seam == "model":
+            pytest.fail("Model received context after failed enforcement")
+        return long_tool_message
+
+    async def ahandler(request):
+        return handler(request)
+
+    with pytest.raises(NeedlepathGuardrailError):
+        if asynchronous:
+            asyncio.run(getattr(mw, f"awrap_{seam}_call")(request, ahandler))
+        else:
+            getattr(mw, f"wrap_{seam}_call")(request, handler)
+
+
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.parametrize("seam", ["tool", "model"])
+@pytest.mark.parametrize("shadow", [False, True])
+def test_a_blocked_verdict_is_installed_never_raised_on_either_seam(
+    long_tool_message, asynchronous, seam, shadow
+):
+    """The counterpart of the test above for ``outcome: blocked``. A blocked
+    verdict is not an enforcement failure: it is applied as "deliver nothing
+    from these records" and the agent run continues. Live, the model sees the
+    withheld notice and never the record. In shadow nothing is installed (the
+    original is forwarded) and the receipt still carries the verdict."""
+    mw, _, _ = middleware([blocked_service()], shadow=shadow, history_max_tokens=10)
+    request = (
+        FakeToolCallRequest()
+        if seam == "tool"
+        else FakeModelRequest([HumanMessage(content="question"), long_tool_message])
+    )
+    seen: dict[str, list] = {}
+
+    def handler(request):
+        if seam == "model":
+            seen["messages"] = list(request.messages)
+            return None
+        return long_tool_message
+
+    async def ahandler(request):
+        return handler(request)
+
+    if asynchronous:
+        out = asyncio.run(getattr(mw, f"awrap_{seam}_call")(request, ahandler))
+    else:
+        out = getattr(mw, f"wrap_{seam}_call")(request, handler)
+    delivered = out if seam == "tool" else seen["messages"][1]
+    # Shadow or live, the verdict is installed: shadow never restores a
+    # withheld record. The receipt says which kind of run it was.
+    assert "withheld" in delivered.text.lower()
+    assert long_tool_message.text not in delivered.text
+    assert "scope:source:hr" in delivered.text
+    meta = delivered.response_metadata[METADATA_KEY]
+    assert meta["rewrite_reason"] == "blocked"
+    if seam == "tool":
+        # The tool seam annotates the delivered message with the whole
+        # receipt; the history seam records it on `.stats`.
+        assert meta["reason"] == Reason.BLOCKED
+        assert meta["outcome"] == "blocked"
+        assert meta["shadow"] is shadow
+        assert meta["governance"] == BLOCKED_GOVERNANCE
+    assert mw.stats.applied == 1 and mw.stats.reasons == {Reason.BLOCKED: 1}
+
+
 # --------------------------------------------------------------------------- #
 # wrap_tool_call
 # --------------------------------------------------------------------------- #
@@ -205,6 +299,245 @@ def test_a_sanitized_packet_longer_than_the_original_still_lands(long_tool_messa
     assert mw.stats.applied == 1
 
 
+#: A real governance block, as the local engine returned it for an HR record
+#: under a refunds-agent data-scope policy (workspace org_local_demo, 2026-11-04).
+BLOCKED_GOVERNANCE = {
+    "enabled": True,
+    "provider_id": "nextmoca",
+    "policy_scope": "workspace",
+    "policy_revision": 20,
+    "records_before": 1,
+    "records_after": 0,
+    "records_blocked": 1,
+    "engine_records_selected": 1,
+    "engine_tokens_after": 189,
+    "engine_latency_ms": 11.409166269004345,
+    "policies_applied": 2,
+    "scope_policies_applied": 1,
+    "raw_context_fallback_allowed": False,
+    "category_counts": {"scope:source:hr": 1},
+    "output_tokens": 0,
+    "context_changed": True,
+    "governance_latency_ms": 114.95654238387942,
+}
+
+#: What a governed workspace returns alongside an ordinary engaged selection.
+CLEAN_GOVERNANCE = {
+    "enabled": True,
+    "provider_id": "nextmoca",
+    "policy_scope": "workspace",
+    "policy_revision": 20,
+    "records_before": 1,
+    "records_after": 1,
+    "records_blocked": 0,
+    "policies_applied": 2,
+    "raw_context_fallback_allowed": False,
+    "category_counts": {},
+    "governance_latency_ms": 9.5,
+}
+
+
+def blocked_service(**overrides):
+    kwargs = dict(
+        selected=[],
+        records_selected=0,
+        rendered_context="",
+        outcome="blocked",
+        tokens_after=0,
+        governance=dict(BLOCKED_GOVERNANCE),
+        usage={
+            "meter_version": "npm-2026-08-r1",
+            "outcome": "pass_through",
+            "input_tokens": 232,
+            "charge_multiplier": "0",
+            "price_version": "npp-2026-08-r1",
+            "currency": "USD",
+        },
+    )
+    kwargs.update(overrides)
+    return echoing_service(**kwargs)
+
+
+def test_a_blocked_tool_result_is_withheld_from_the_model():
+    """`outcome: blocked` means workspace policy withheld every record. The
+    engine's verdict is installed as the tool result, a short notice, so the
+    agent continues without the record. The original must never be the
+    message the model sees, and the run must not abort."""
+    hr_record = ToolMessage(
+        content=big("employee Marcus Lee, SSN 123-45-6789, salary band L5"),
+        tool_call_id="call_hr",
+        name="lookup_employee",
+    )
+    mw, transport, _ = middleware([blocked_service()], operating_point=OP)
+    out = mw.wrap_tool_call(FakeToolCallRequest(name="lookup_employee"), lambda r: hr_record)
+    assert isinstance(out, ToolMessage)
+    assert out.tool_call_id == "call_hr"
+    assert "123-45-6789" not in out.text
+    assert out.text != hr_record.text
+    # The notice says what happened and names the engine's categories, nothing
+    # from the record itself.
+    assert "withheld" in out.text.lower()
+    assert "scope:source:hr" in out.text
+    assert transport.bodies[0]["request_id"] in out.text
+    meta = out.response_metadata[METADATA_KEY]
+    assert meta["rewritten"] is True
+    assert meta["rewrite_reason"] == "blocked"
+    assert meta["reason"] == Reason.BLOCKED
+    assert meta["applied"] is True
+    assert meta["outcome"] == "blocked"
+    assert meta["governance"] == BLOCKED_GOVERNANCE
+    assert meta["usage"]["outcome"] == "pass_through"
+    assert mw.stats.applied == 1 and mw.stats.reasons == {Reason.BLOCKED: 1}
+    assert mw.stats.failures == 0
+    assert mw.stats.tokens_after == approx_tokens(out.text)
+    assert mw.engine_stats.reasons == {Reason.BLOCKED: 1}
+
+
+def test_a_blocked_tool_result_is_withheld_even_when_the_notice_is_longer():
+    """The length guard exists to refuse a rewrite that saves nothing. A
+    withheld record is not a saving; refusing the notice on length would hand
+    the withheld record to the model."""
+    short = ToolMessage(content="SSN 123-45-6789", tool_call_id="call_hr", name="lookup_employee")
+    mw, _, _ = middleware([blocked_service()], operating_point=OP, tool_result_max_tokens=1)
+    out = mw.wrap_tool_call(FakeToolCallRequest(name="lookup_employee"), lambda r: short)
+    assert "123-45-6789" not in out.text
+    assert out.response_metadata[METADATA_KEY]["rewrite_reason"] == "blocked"
+
+
+def test_a_blocked_tool_result_without_categories_still_names_the_policy():
+    governance = dict(BLOCKED_GOVERNANCE, category_counts={})
+    mw, _, _ = middleware([blocked_service(governance=governance)], operating_point=OP)
+    out = mw.wrap_tool_call(
+        FakeToolCallRequest(),
+        lambda r: ToolMessage(content=big("payload"), tool_call_id="c", name="t"),
+    )
+    assert "withheld" in out.text.lower()
+    assert "workspace policy" in out.text
+
+
+def test_a_blocked_tool_result_is_withheld_on_the_async_seam_too():
+    hr_record = ToolMessage(content=big("SSN 123-45-6789"), tool_call_id="call_hr", name="t")
+    mw, _, _ = middleware([blocked_service()], operating_point=OP)
+
+    async def handler(request):
+        return hr_record
+
+    out = asyncio.run(mw.awrap_tool_call(FakeToolCallRequest(), handler))
+    assert "123-45-6789" not in out.text
+    assert out.response_metadata[METADATA_KEY]["reason"] == Reason.BLOCKED
+
+
+def test_a_blocked_history_selection_withholds_every_considered_tool_result(history):
+    """On the history seam a blocked verdict covers every record that was sent:
+    each collapses to the withheld notice, not to the selection placeholder and
+    never to its original text."""
+    mw, transport, _ = middleware([blocked_service()], operating_point=OP, history_max_tokens=100)
+    captured = {}
+    mw.wrap_model_call(FakeModelRequest(history), lambda r: captured.setdefault("r", r))
+    out = captured["r"].messages
+    assert len(out) == len(history)
+    for index in (2, 4):
+        assert out[index].text != history[index].text
+        assert "withheld" in out[index].text.lower()
+        assert "scope:source:hr" in out[index].text
+        assert out[index].tool_call_id == history[index].tool_call_id
+    assert out[0].content == history[0].content
+    assert mw.stats.applied == 1 and mw.stats.reasons == {Reason.BLOCKED: 1}
+
+
+def test_a_blocked_history_selection_is_installed_even_when_the_notice_is_longer():
+    tiny = [
+        HumanMessage(content="q"),
+        AIMessage(
+            content="", tool_calls=[{"name": "t", "args": {}, "id": "c1", "type": "tool_call"}]
+        ),
+        ToolMessage(content="SSN 123-45-6789", tool_call_id="c1", name="t"),
+        HumanMessage(content="and?"),
+    ]
+    mw, _, _ = middleware([blocked_service()], operating_point=OP, history_max_tokens=1)
+    captured = {}
+    mw.wrap_model_call(FakeModelRequest(tiny), lambda r: captured.setdefault("r", r))
+    assert "123-45-6789" not in captured["r"].messages[2].text
+
+
+def test_shadow_still_withholds_a_blocked_tool_result(long_tool_message):
+    """Shadow measures every delivery the caller could have had anyway; a
+    withheld record is not one of those. The middleware's own shadow flag,
+    which is belt and braces for every other reason, does not restore it:
+    the notice is installed and the receipt says this was a shadow run."""
+    mw, transport, _ = middleware([blocked_service()], operating_point=OP, shadow=True)
+    out = mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
+    assert len(transport.calls) == 1
+    assert out.text != long_tool_message.text
+    assert "withheld" in out.text.lower()
+    assert "scope:source:hr" in out.text
+    assert out.tool_call_id == long_tool_message.tool_call_id
+    meta = out.response_metadata[METADATA_KEY]
+    assert meta["applied"] is True
+    assert meta["shadow"] is True
+    assert meta["reason"] == Reason.BLOCKED
+    assert meta["rewrite_reason"] == "blocked"
+    assert meta["outcome"] == "blocked"
+    assert meta["governance"] == BLOCKED_GOVERNANCE
+    assert mw.stats.applied == 1 and mw.stats.reasons == {Reason.BLOCKED: 1}
+
+
+def test_the_governance_block_lands_on_the_receipt_verbatim(long_tool_message):
+    """The audit evidence a customer reads: carried as the engine sent it, on an
+    ordinary engaged selection as much as on a blocked one."""
+    mw, _, _ = middleware([echoing_service(governance=dict(CLEAN_GOVERNANCE))], operating_point=OP)
+    out = mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
+    meta = out.response_metadata[METADATA_KEY]
+    assert meta["applied"] is True
+    assert meta["governance"] == CLEAN_GOVERNANCE
+
+
+#: What a governed workspace returns when no policy applied to the request:
+#: governance is on, nothing matched, and the raw context is permitted.
+UNGOVERNED_GOVERNANCE = {
+    "enabled": True,
+    "provider_id": "nextmoca",
+    "policy_scope": "workspace",
+    "policy_revision": 20,
+    "records_before": 1,
+    "records_after": 1,
+    "records_blocked": 0,
+    "policies_applied": 0,
+    "raw_context_fallback_allowed": True,
+    "category_counts": {},
+    "governance_latency_ms": 9.5,
+}
+
+
+def test_the_governance_block_lands_on_a_passthrough_receipt_too(long_tool_message):
+    mw, _, _ = middleware(
+        [echoing_service(selected=[], records_selected=0, governance=dict(UNGOVERNED_GOVERNANCE))],
+        operating_point=OP,
+    )
+    out = mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
+    meta = out.response_metadata[METADATA_KEY]
+    assert meta["applied"] is False
+    assert meta["governance"] == UNGOVERNED_GOVERNANCE
+
+
+def test_an_empty_selection_under_workspace_protection_stops_the_call(long_tool_message):
+    """Policies applied, raw fallback forbidden, and nothing to apply: that is
+    not a blocked verdict, so there is no empty delivery to install, and a
+    passthrough would deliver the raw record. The call stops instead."""
+    mw, _, _ = middleware(
+        [echoing_service(selected=[], records_selected=0, governance=dict(CLEAN_GOVERNANCE))],
+        operating_point=OP,
+    )
+    with pytest.raises(NeedlepathGuardrailError):
+        mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
+
+
+def test_no_governance_block_means_no_governance_key(long_tool_message):
+    mw, _, _ = middleware([echoing_service()], operating_point=OP)
+    out = mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
+    assert "governance" not in out.response_metadata[METADATA_KEY]
+
+
 def test_an_excerpt_longer_than_the_original_is_refused(long_tool_message):
     """Whatever produced it, applying it is a regression."""
     longer = [