constraintloop 0.3.0__tar.gz → 0.3.1__tar.gz

{constraintloop-0.3.0 → constraintloop-0.3.1}/CHANGELOG.md

@@ -5,6 +5,11 @@ Versioning, with the usual initial-development flexibility for `0.y.z`.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-31
+
+- Prevent recursive Claude Stop-hook invocations from repeatedly blocking completion.
+- Add actionable version-skew guidance when a hook runtime rejects unknown contract keys.
+
 ## [0.3.0] - 2026-08-18
 
 - Add native monotonic ratchet constraints with committed JSON baselines,

{constraintloop-0.3.0 → constraintloop-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: constraintloop
-Version: 0.3.0
+Version: 0.3.1
 Summary: Evidence-based completion gates for AI coding agents
 Project-URL: Homepage, https://github.com/mauhpr/constraintloop
 Project-URL: Documentation, https://github.com/mauhpr/constraintloop/tree/main/docs

{constraintloop-0.3.0 → constraintloop-0.3.1}/docs/faq.md

@@ -149,6 +149,22 @@ Generated commands include the resolved project argument. If the error remains,
 inspect the relevant `.claude`, `.codex`, or `.gemini` settings file for a stale
 manually copied command.
 
+### Why does a hook reject documented contract keys as extra inputs?
+
+The hook is running an older ConstraintLoop executable than the contract expects.
+Upgrade that installation, then regenerate the hook commands so they resolve to the
+same release:
+
+```bash
+constraintloop --version
+constraintloop setup --adapter all --project .
+```
+
+Current releases include their version and this recovery action when strict schema
+validation encounters unknown keys. Recursive Claude Stop-hook calls are allowed to
+finish after delivering the error once, so an invalid or version-skewed contract does
+not create a repeated Stop-hook loop.
+
 ## Loops
 
 ### Can I configure an unlimited repair loop?

{constraintloop-0.3.0 → constraintloop-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "constraintloop"
-version = "0.3.0"
+version = "0.3.1"
 description = "Evidence-based completion gates for AI coding agents"
 readme = "README.md"
 license = "MIT"

{constraintloop-0.3.0 → constraintloop-0.3.1}/src/constraintloop/__init__.py

@@ -4,4 +4,4 @@ The v0.2 supported interfaces are the CLI and documented versioned protocols.
 Python submodules are internal and may change during initial development.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{constraintloop-0.3.0 → constraintloop-0.3.1}/src/constraintloop/config.py

@@ -10,6 +10,7 @@ from typing import Any
 import yaml
 from pydantic import ValidationError
 
+from constraintloop import __version__
 from constraintloop.models import Contract
 
 CONFIG_NAMES = ("constraintloop.yml", "constraintloop.yaml")
@@ -69,7 +70,16 @@ def load_contract(project_root: Path, *, include_local: bool = True) -> tuple[Co
     except ContractError:
         raise
     except (OSError, yaml.YAMLError, ValidationError) as exc:
-        raise ContractError(f"Invalid contract {path}: {exc}") from exc
+        hint = ""
+        if isinstance(exc, ValidationError) and any(
+            error["type"] == "extra_forbidden" for error in exc.errors()
+        ):
+            hint = (
+                f"\nConstraintLoop {__version__} does not recognize one or more keys. "
+                "Check for typos; if the contract uses features from a newer release, upgrade "
+                "the hook executable and rerun `constraintloop setup --adapter all --project .`."
+            )
+        raise ContractError(f"Invalid contract {path}: {exc}{hint}") from exc
 
 
 def _merge_mappings(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:

{constraintloop-0.3.0 → constraintloop-0.3.1}/src/constraintloop/hooks.py

@@ -21,6 +21,15 @@ def handle_hook(
     event: str,
     payload: dict[str, Any],
 ) -> dict[str, Any]:
+    # Claude re-runs Stop hooks after a hook has already blocked completion and
+    # marks that recursive invocation explicitly. Blocking again traps the
+    # agent in a hook loop, so the recursive call must succeed without running
+    # the contract a second time.
+    if event == "stop" and (
+        payload.get("stop_hook_active") is True or payload.get("stopHookActive") is True
+    ):
+        return {}
+
     session_id = str(
         payload.get("session_id")
         or payload.get("sessionId")

{constraintloop-0.3.0 → constraintloop-0.3.1}/tests/test_cli.py

@@ -6,6 +6,7 @@ import pytest
 import yaml
 from click.testing import CliRunner
 
+from constraintloop import __version__
 from constraintloop.cli import main
 from constraintloop.config import ContractError, load_contract
 
@@ -127,6 +128,22 @@ def test_contract_rejects_ambiguous_and_non_mapping_overlays(tmp_path: Path) ->
         load_contract(tmp_path)
 
 
+def test_unknown_contract_keys_report_runtime_version_and_upgrade_action(tmp_path: Path) -> None:
+    payload = {
+        "settings": {"future_setting": True},
+        "constraints": {"check": {"kind": "command", "command": ["true"]}},
+    }
+    (tmp_path / "constraintloop.yml").write_text(yaml.safe_dump(payload), encoding="utf-8")
+
+    with pytest.raises(ContractError) as raised:
+        load_contract(tmp_path)
+
+    message = str(raised.value)
+    assert "future_setting" in message
+    assert f"ConstraintLoop {__version__} does not recognize one or more keys" in message
+    assert "constraintloop setup --adapter all --project ." in message
+
+
 @pytest.mark.parametrize(
     ("overlay", "field"),
     [

{constraintloop-0.3.0 → constraintloop-0.3.1}/tests/test_hooks.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import pytest
 import yaml
 
+from constraintloop import __version__
 from constraintloop.hooks import handle_hook
 from constraintloop.setup_hooks import install_hooks, uninstall_hooks
 from constraintloop.state import create_advisory_acknowledgment, load_latest_result, load_session
@@ -41,6 +42,20 @@ def test_stop_blocks_then_requires_human(tmp_path: Path, monkeypatch) -> None:
     assert "ask a human" in second["stopReason"]
 
 
+@pytest.mark.parametrize("active_field", ["stop_hook_active", "stopHookActive"])
+def test_recursive_stop_hook_succeeds_without_loading_contract(
+    tmp_path: Path, active_field: str
+) -> None:
+    response = handle_hook(
+        tmp_path,
+        "claude",
+        "stop",
+        {active_field: True},
+    )
+
+    assert response == {}
+
+
 def test_pre_tool_protects_contract(tmp_path: Path) -> None:
     response = handle_hook(
         tmp_path,
@@ -125,7 +140,7 @@ def test_setup_pins_uvx_and_supports_explicit_hook_executable(tmp_path: Path, mo
     command = json.loads(path.read_text(encoding="utf-8"))["hooks"]["Stop"][0]["hooks"][0][
         "command"
     ]
-    assert command.startswith("uvx --from constraintloop==0.3.0 constraintloop hook")
+    assert command.startswith(f"uvx --from constraintloop=={__version__} constraintloop hook")
 
     path = install_hooks(tmp_path, "codex", hook_executable="pipx run constraintloop")
     command = json.loads(path.read_text(encoding="utf-8"))["hooks"]["Stop"][0]["hooks"][0][

{constraintloop-0.3.0 → constraintloop-0.3.1}/tests/test_models.py

@@ -6,6 +6,40 @@ from pydantic import ValidationError
 from constraintloop.models import Contract
 
 
+def test_contract_accepts_progress_interval_and_command_retry_policies() -> None:
+    contract = Contract.model_validate(
+        {
+            "settings": {"progress_interval_seconds": 10},
+            "constraints": {
+                "alembic_heads": {
+                    "kind": "command",
+                    "command": ["check-alembic-heads"],
+                    "timeout_seconds": 300,
+                    "retry": {
+                        "max_attempts": 2,
+                        "exit_codes": [1],
+                        "total_timeout_seconds": 600,
+                    },
+                },
+                "async_postgres_tests": {
+                    "kind": "command",
+                    "command": ["pytest", "-m", "async_postgres"],
+                    "timeout_seconds": 900,
+                    "retry": {
+                        "max_attempts": 2,
+                        "retry_timeouts": True,
+                        "total_timeout_seconds": 1800,
+                    },
+                },
+            },
+        }
+    )
+
+    assert contract.settings.progress_interval_seconds == 10
+    assert contract.constraints["alembic_heads"].retry is not None
+    assert contract.constraints["async_postgres_tests"].retry is not None
+
+
 def test_required_rubric_demands_majority_quorum() -> None:
     with pytest.raises(ValidationError, match="at least two runs"):
         Contract.model_validate(