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

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

@@ -2,22 +2,60 @@
 
 All notable changes to the `needlepath-langchain` Python package are documented here.
 
-## 0.2.2
+## 0.2.4 — 2026-11-05
 
 ### 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.
+- **A protected record the length guard would keep is withheld, never kept.**
+  Under workspace protection (the engine's `governance` forbids raw-context
+  fallback) and a verdict that is not blocked, `apply_selection` kept an
+  individual original whenever its excerpt or placeholder was empty or not
+  shorter, and the history seam and the LangGraph hook only declined when the
+  aggregate rewrite showed no saving, so a larger saving elsewhere masked the
+  per-record refusal and the protected original reached the model. Such a
+  record now collapses to the withheld notice (`rewrite_reason: "protected"`);
+  the aggregate no-saving decline does not apply under protection, since the
+  rewrite holds no original. On the tool-result seam the same case used to
+  decline, which under protection raised `NeedlepathGuardrailError` and
+  aborted the run; it now installs the notice and the run continues. The
+  engine's own stop conditions (an empty or unusable protected response)
+  still raise.
+- **Shadow never restores a protected original.** The adapter's own shadow
+  guard exempted only a blocked verdict, so a protected engaged or sanitized
+  delivery (the core keeps it applied in a shadow run) was discarded and the
+  original forwarded. The guard now exempts every protected result
+  (`SelectionResult.protected`). Shadow still forwards the original for every
+  unprotected delivery.
+- **A defect while installing a protected result stops the call.** Selection
+  and installation shared one fail-open handler, so a failure after a
+  protected result had been returned restored the original. The install step
+  now runs under `SelectionResult.applying()`: under protection it raises
+  `NeedlepathGuardrailError`; otherwise it fails open as before.
+
+## 0.2.3 — 2026-11-04
 
-## Unreleased
+### Fixed
+
+- **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 +75,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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: needlepath-langchain
-Version: 0.2.2
+Version: 0.2.4
 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'
@@ -110,7 +110,10 @@ the savings from deleting message envelopes.
 
 **A rewrite never grows a message and never empties one.** An excerpt longer than
 what it replaces, or an empty excerpt applied to a non-empty message, is refused
-here rather than trusted upstream.
+here rather than trusted upstream. Refusing keeps the original, except under
+workspace protection (the engine's `governance` forbids raw-context fallback):
+there the record is withheld with the notice instead, because the original is
+the one thing that may not be installed.
 
 By default only `ToolMessage`s are rewritten. `SystemMessage` never is, on any
 setting. An `AIMessage` carrying `tool_calls` never is: its content is usually

{needlepath_langchain-0.2.2 → needlepath_langchain-0.2.4}/README.md

@@ -86,7 +86,10 @@ the savings from deleting message envelopes.
 
 **A rewrite never grows a message and never empties one.** An excerpt longer than
 what it replaces, or an empty excerpt applied to a non-empty message, is refused
-here rather than trusted upstream.
+here rather than trusted upstream. Refusing keeps the original, except under
+workspace protection (the engine's `governance` forbids raw-context fallback):
+there the record is withheld with the notice instead, because the original is
+the one thing that may not be installed.
 
 By default only `ToolMessage`s are rewritten. `SystemMessage` never is, on any
 setting. An `AIMessage` carrying `tool_calls` never is: its content is usually

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "needlepath-langchain"
-version = "0.2.2"
+version = "0.2.4"
 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.4}/src/needlepath_langchain/_messages.py

@@ -22,7 +22,12 @@ to get it.
 **Invariant 2 — a rewrite never grows the context and never empties a message.**
 An excerpt longer than what it replaces, or an empty excerpt applied to a
 non-empty message, is a regression however the service arrived at it. Both are
-refused here rather than trusted upstream.
+refused here rather than trusted upstream. Refusing a rewrite keeps the
+original, which is the right degradation for an ordinary selection and the
+wrong one under workspace protection: when the engine's ``governance`` forbids
+raw-context fallback, a refused rewrite collapses to the withheld notice
+instead (``protected_notice``), because the original is the one thing that
+may not be installed.
 
 **No local "preserve the last N messages" policy (NEXPE-517 review).** An
 earlier version excluded a trailing window of messages from ``index_by_id``
@@ -45,7 +50,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 +303,8 @@ def apply_selection(
     index_by_id: dict[str, int],
     placeholder: str,
     request_id: str,
+    withhold: bool = False,
+    protected_notice: str | None = None,
 ) -> tuple[list[BaseMessage], int, int]:
     """Rewrite the selected and unselected messages. Returns (messages, before, after).
 
@@ -305,6 +312,18 @@ 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.
+
+    Two exceptions, both for a response under workspace protection, where the
+    original is the thing that must not be kept:
+
+    * ``withhold``, for a ``blocked`` verdict: every record collapses to
+      ``placeholder`` (the withheld notice) whatever its length. ``excerpts``
+      is ignored; a blocked response carries none.
+    * ``protected_notice``, for any other protected delivery: a record whose
+      rewrite invariant 2 refuses collapses to this notice instead of keeping
+      the original. The refusal is per record, and a caller that only checks
+      the aggregate saving cannot see it — a large saving elsewhere would mask
+      one kept original and send it to the model.
     """
     out: list[BaseMessage] = list(messages)
     before = 0
@@ -313,41 +332,56 @@ def apply_selection(
         original = out[index]
         original_text = message_text(original)
         before += approx_tokens(original_text)
-        excerpt = excerpts.get(record_id)
-        if excerpt is None and not placeholder.strip():
-            # Invariant 2, at the mutation boundary. A blank custom placeholder
-            # would rewrite a non-empty message to nothing — the pairing
-            # survives, the content does not. Refused rather than trusted.
-            after += approx_tokens(original_text)
-            continue
-        if excerpt is None:
-            # Not selected: collapse to the placeholder. This is the only place
-            # content is discarded, and it is the difference between selection
-            # and a no-op.
-            new_text = placeholder
-            reason = "not_selected"
-        elif not excerpt.strip():
-            # Selected with nothing in it. Applying this would delete content
-            # the service said to keep — refuse it and keep the original.
-            after += approx_tokens(original_text)
-            continue
-        elif len(excerpt) >= len(original_text):
-            # An "excerpt" that is not shorter buys nothing and may cost.
-            after += approx_tokens(original_text)
-            continue
+        if withhold:
+            new_text, reason = placeholder, "blocked"
         else:
-            new_text = excerpt
-            reason = "excerpt"
-        if len(new_text) >= len(original_text) and reason == "not_selected":
-            # A placeholder longer than the message it replaces. Rare, but a
-            # short tool result plus a long custom placeholder gets here.
-            after += approx_tokens(original_text)
-            continue
+            rewrite = _rewrite_for(excerpts.get(record_id), original_text, placeholder)
+            if rewrite is None and protected_notice is None:
+                # Invariant 2 refused the rewrite: the original stays.
+                after += approx_tokens(original_text)
+                continue
+            if rewrite is None:
+                # Under workspace protection the original is the one thing
+                # that may not be installed. Withheld, with the notice.
+                new_text, reason = protected_notice, "protected"
+            else:
+                new_text, reason = rewrite
         out[index] = rewrite_message(original, new_text, reason=reason, request_id=request_id)
         after += approx_tokens(new_text)
     return out, before, after
 
 
+def _rewrite_for(
+    excerpt: str | None, original_text: str, placeholder: str
+) -> tuple[str, str] | None:
+    """What replaces a message, as ``(text, reason)``, or ``None`` to refuse.
+
+    Invariant 2, at the mutation boundary. Every ``None`` here is a rewrite
+    that would grow the context or empty a message.
+    """
+    if excerpt is None:
+        if not placeholder.strip():
+            # A blank custom placeholder would rewrite a non-empty message to
+            # nothing — the pairing survives, the content does not.
+            return None
+        if len(placeholder) >= len(original_text):
+            # A placeholder longer than the message it replaces. Rare, but a
+            # short tool result plus a long custom placeholder gets here.
+            return None
+        # Not selected: collapse to the placeholder. This is the only place
+        # content is discarded, and it is the difference between selection
+        # and a no-op.
+        return placeholder, "not_selected"
+    if not excerpt.strip():
+        # Selected with nothing in it. Applying this would delete content the
+        # service said to keep.
+        return None
+    if len(excerpt) >= len(original_text):
+        # An "excerpt" that is not shorter buys nothing and may cost.
+        return None
+    return excerpt, "excerpt"
+
+
 def tool_call_keywords(args: Any, limit: int = 6, max_len: int = 120) -> list[str]:
     """Short string values from a tool call's arguments, as selection keywords.
 
@@ -399,6 +433,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 +468,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.4}/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
@@ -194,7 +196,11 @@ class NeedlepathPreModelHook:
                 selection_strategy=self.selection_strategy,
                 support_contract=self.support_contract,
             )
-            return self._apply(messages, plan, selection)
+            with selection.applying():
+                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 +210,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)
@@ -237,7 +246,8 @@ class NeedlepathPreModelHook:
                     support_contract=self.support_contract,
                 ),
             )
-        return self._apply(messages, plan, selection)
+        with selection.applying():
+            return self._apply(messages, plan, selection)
 
     # ------------------------------------------------------------------ #
 
@@ -299,8 +309,12 @@ 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. What shadow does not
+        # suppress is a protected delivery (a blocked verdict, or a selection
+        # under workspace protection): shadow never restores a withheld record
+        # or a protected original, so it is installed below, shadow or not.
+        blocked = selection.reason == Reason.BLOCKED
+        if not selection.applied or (self.shadow and not selection.protected):
             # 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"])
@@ -308,14 +322,31 @@ class NeedlepathPreModelHook:
                 _with_actual_tokens(selection, before=candidate_tokens, after=candidate_tokens)
             )
             return self._always_write(messages)
+        # Workspace protection: the engine's `governance` forbids raw-context
+        # fallback (a blocked verdict is one case of it). Nothing of the
+        # caller's original may be written, per record or in aggregate.
+        protected = not selection.raw_context_fallback_allowed
+        notice = withheld_notice(selection) if protected else None
         rewritten, before, after = apply_selection(
             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,
+            # Any other protected delivery: a record whose rewrite the length
+            # guards refuse is withheld with the notice, never kept.
+            protected_notice=notice,
         )
-        if after >= before:
+        if after >= before and not protected:
+            # The guard refuses a rewrite that saves nothing. Under protection
+            # it does not apply: the rewrite holds no original, a withheld
+            # record is not a saving, and declining would raise and stop a run
+            # the engine did not stop.
             declined = selection.declined(Reason.NO_SAVING)
             # Nothing is installed here either: `rewritten` is computed but
             # never written, so actual after == actual before.