Merge v1.9.1-binding-collision: binding completeness, red pass closed

Author: webpro255

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.9.1] - 2026-09-10
+
+A patch release closing four binding gaps, all found by the same external review that found the three 1.9.0 gaps: one in the variadic keyword flattening, and three more found in a red pass against the 1.9.1 build before it was released. No new feature, no new denial reason and no schema change. The version did not move between the two rounds, because the first was never released.
+
+Suite: **1515 passed, 14 skipped on CPython 3.14.6 with no optional extras**, **1520 passed, 9 skipped on CPython 3.14.6 with `mcp 2.2.0`**, **1519 passed, 10 skipped on CPython 3.13.14 with `mcp 1.30.0`**, and **1521 passed, 8 skipped on CPython 3.13.14 with `mcp 2.2.0` and `pyautogen 0.9.0`**. 0 failed in every environment. `mypy agentlock/ --ignore-missing-imports` reports 0 errors.
+
+### Security
+
+- **A `**kwargs` key that names another parameter is refused instead of flattened over it.** `bind_call_parameters` flattened a `VAR_KEYWORD` mapping onto the top-level parameters dict with `parameters.update(value)`. A key in that mapping equal to the name of another bound parameter overwrote the bound value, and the gate was then shown a value the function does not receive. Two shapes carried it. With `def send(to, /, **extras)`, the call `send("attacker@evil.test", to="bob@company.com")` bound `to` to the attacker positionally, put `to="bob@company.com"` in `extras` because `to` is positional only, and flattened the contact over the attacker: the gate authorized a known contact and the function ran with the attacker. With `def f(*args, **kw)`, the call `f(1, 2, args="spoof")` showed the gate `args="spoof"` while the function received `args=(1, 2)`. The sync wrapper, the async wrapper and the AutoGen `protect_functions` map all reached the same binding and all three carried it. Before flattening, the binding now computes the set of names of every other parameter in the signature and raises `BindingError` if any key of the mapping is in it, naming the colliding key and the function. Credited to the same external review.
+- **This is a call-time refusal and it reaches the caller.** The error is raised from inside the binding, before `authorize()` is called, so the call is never authorized and the function never runs. No wrapper catches it: it propagates like `TokenInvalidError` does. A deployment calling a function whose signature genuinely has both a parameter and a `**kwargs` key of the same name will see `BindingError` where it previously saw execution.
+- **A key equal to the `**kwargs` parameter's own name is not a collision and stays allowed.** With `def g(**kw)`, the call `g(kw="spoof")` has no parameter named `kw` for the key to shadow: `kw` is the variadic itself, and the gate and the function see the same mapping. Nothing is hidden, so nothing is refused, and this call binds exactly as it did at 1.9.0.
+- **A `functools.partial` is bound through to the function underneath.** `inspect.signature` of a partial describes the call still to be made, not the function that will run, so the arguments the partial already carries are absent from it. With `def send(to, /, **extras)`, `partial(send, "attacker@evil.test")` called with `to="bob@company.com"` showed the gate the contact, which had landed in `extras`, and ran the function with the attacker the partial supplied. The binding now collapses a chain of partials into the call it stands for before binding: the callable becomes `partial.func`, the positional arguments become `partial.args` in front of the call's own, and the keywords become the partial's underneath the call's, repeatedly for nested partials. The collision rule above then applies to the partial's own arguments too, which is what refuses the shape just described. `partialmethod` is collapsed the same way. Wrappers invoke the callable underneath, because that is what the binding is taken against.
+- **A recipient is read for the characters it holds, not for what its methods say.** `_normalize_recipient` called `strip` and `casefold` on the value it was given. A `str` subclass satisfies every `isinstance` check the gate makes while overriding those two to name a known contact and `__str__` to name somewhere else, so the gate authorized the contact and the application, sending to `str(value)`, delivered to the attacker. Every recipient string is now coerced with `str.__str__`, which is the slot rather than the instance's override, before it is stripped, casefolded or compared, and before it is placed in the request context. Subclasses are not rejected: a subclass whose data is a known contact is allowed even if its methods claim otherwise, which is the same rule read in the other direction.
+- **A declared recipient parameter that can never be observed is refused at wrap time.** A block declaring `scope.recipient_parameter="to"` over `def send(*args)` was accepted. That signature has no `to` and no `**kwargs` for one to arrive in, so pipeline step 8 looked up a key that could never be present, found nothing, skipped, and the declared recipient policy decided nothing for every call. The wrapper now raises `BindingError` at decoration when the declared name is neither a parameter of the signature nor able to arrive through `**kwargs`, before the tool is registered. `def send(*args, **kw)` still wraps: `**kw` can carry it.
+- **A call that hides its recipient in `*args` is refused at call time.** `def send(*args, **kw)` can carry a `to`, so the pair is allowed to be built, but the call `send("attacker@evil.test")` binds `args=("attacker@evil.test",)` and no `to` at all, and step 8 skips again. When a recipient parameter is declared, the bound parameters carry no argument of that name, and positional arguments did arrive in `*args`, the binding now raises `BindingError`. The gate does not guess which unnamed positional was meant to be the recipient. A call with no positional extras is not this case: the declared parameter is simply absent, and the existing skip is unchanged.
+- **Threat model.** The gate binds to the callable's signature as `inspect` reports it, following `__wrapped__`. A wrapper that advertises one signature and alters the arguments before calling the inner function is the application's own code, on the trusted side of the boundary, and is outside what the gate can check. What the gate guarantees is that the call it authorizes is the call it binds, and that the wrappers invoke the function from that same binding.
+
+### Changed
+
+- **`BindingError`'s documentation now states all four reasons it is raised and where each is raised from.** Through 1.9.0 the class docstring read "Raised at wrap time, never at call time", which the collision rule makes false. This release adds two more reasons, one at each moment: an unobservable declared recipient parameter at wrap time, and a recipient hidden in `*args` at call time. The unreadable-signature case is still a wrap-time refusal and is unchanged.
+- **`AgentLockMCPServer` is unchanged, and the standalone adapters carry none of these rules.** The MCP integration does not bind call arguments to a Python signature; it passes the SDK's `arguments` mapping, which has names already. The five standalone adapters ship from their own repositories and are updated separately: none of them binds through partials, coerces recipient strings, or checks that a declared recipient parameter is observable.
+
 ## [1.9.0] - 2026-09-09
 
 The enforcement completeness release. An external review of the published 1.8.0 wheel found three places where the engine did not enforce what its own documentation said it enforced. All three are fixed. This release adds no detection feature, no new denial reason and no schema change.

CITATION.cff

@@ -7,13 +7,13 @@ authors:
   - family-names: Grice
     given-names: David
     orcid: "https://orcid.org/0009-0005-5388-123X"
-version: 1.9.0
+version: 1.9.1
 doi: 10.5281/zenodo.22681594
 identifiers:
   - type: doi
     value: 10.5281/zenodo.22681594
     description: "Concept DOI, resolves to the latest version"
-date-released: 2026-09-09
+date-released: 2026-09-10
 license: AGPL-3.0
 repository-code: "https://github.com/webpro255/agentlock"
 url: "https://agentlock.dev"

README.md

@@ -314,6 +314,7 @@ changelog. That is how we intend to keep working.
 
 | version | highlights | tests |
 |---------|-----------|-------|
+| 1.9.1   | binding completeness: a `**kwargs` key that names another parameter is refused rather than flattened over it; partials bound through to the function underneath; recipients read for the characters they hold; an unobservable declared recipient parameter refused | 1520 with the `crypto` and `mcp` extras, 9 skipped |
 | 1.9.0   | enforcement completeness: all call arguments reach the gate, tokens bind the empty call, MCP wrapper fails closed and supports both SDK majors | 1503 with the `crypto` and `mcp` extras, 9 skipped |
 | 1.8.0   | recipient policy enforcement at pipeline Step 8; declared recipient parameter read from the trusted permission block; recipient sets | 1495 with the `crypto` and `mcp` extras, 8 skipped |
 | 1.7.0   | cross-hop provenance linking; parent attribution at ingestion by whole-content carriage; taint-reachability walk at decision time | 1418 with optional extras, 7 skipped |
@@ -336,22 +337,29 @@ only on Python below 3.14; a bare install runs 1479 passed and 24
 skipped. For 1.9.0 it is 1503 passing and 9 skipped under `mcp 2.x`, the
 9 being those 8 plus the mcp 1.x test, which selects on the installed
 SDK major; under `mcp 1.x` it is 1502 passing and 10 skipped, the two 2.x
-tests taking the place of the 1.x one. Nothing fails in any of these
-environments.
-
-The 1.9.0 argument binding covers the engine's own decorators and in-repo
-integrations, which is the whole of what that release changes. The standalone
-adapters ship from their own repositories and are updated separately. At their
-current releases, `crewai-agentlock` 0.2.0 and `langchain-agentlock` 0.1.0
-authorize keyword arguments only, and of those two only `crewai-agentlock`
-carries positional arguments past the gate into the wrapped call;
-`mcp-agentlock` 0.2.1, `openai-agentlock` 0.1.0 and `openclaw-agentlock` 0.1.0
-hand the gate the same argument mapping they hand the tool and have no
-positional route. No standalone adapter applies the wrapped function's
-defaults, so a parameter the caller omits and the function defaults is not seen
-by the gate in any of them. The same release makes an execution token bind the
-empty call: the parameters passed to `execute()` must be the parameters passed
-to `authorize()`, and `None` and `{}` are the same call.
+tests taking the place of the 1.x one. For 1.9.1 it is 1520 passing and 9
+skipped under `mcp 2.x` and 1519 passing and 10 skipped under `mcp 1.x`, the
+seventeen added tests being the binding collision class and the binding red
+pass class, none of which is guarded by an extra; a bare install runs 1515
+passed and 14 skipped. Nothing fails in any of these environments.
+
+The 1.9.0 argument binding, and the 1.9.1 binding rules that refuse a
+`**kwargs` key naming another parameter, bind through a `functools.partial` to
+the function underneath, read a recipient for the characters it holds rather
+than for what its methods say, and refuse a declared recipient parameter the
+signature can never carry, cover the engine's own decorators and in-repo
+integrations, which is the whole of what those two releases change. The standalone adapters ship from their own
+repositories and are updated separately. At their current releases,
+`crewai-agentlock` 0.2.0 and `langchain-agentlock` 0.1.0 authorize keyword
+arguments only, and of those two only `crewai-agentlock` carries positional
+arguments past the gate into the wrapped call; `mcp-agentlock` 0.2.1,
+`openai-agentlock` 0.1.0 and `openclaw-agentlock` 0.1.0 hand the gate the same
+argument mapping they hand the tool and have no positional route. No standalone
+adapter applies the wrapped function's defaults, so a parameter the caller
+omits and the function defaults is not seen by the gate in any of them, and
+none of them carries any of the 1.9.1 binding rules. 1.9.0 also makes an execution
+token bind the empty call: the parameters passed to `execute()` must be the
+parameters passed to `authorize()`, and `None` and `{}` are the same call.
 
 Full feature history:
 [v1.1](docs/history.md#v11-memory--context-permissions),

agentlock/__init__.py

@@ -34,7 +34,7 @@ def send_email(to: str, subject: str, body: str) -> str:
 SPDX-License-Identifier: AGPL-3.0-or-later
 """
 
-__version__ = "1.9.0"
+__version__ = "1.9.1"
 
 from agentlock.action_class_audit import (
     ActionClassAudit,