aria-code 0.119.0__tar.gz → 0.120.0__tar.gz

{aria_code-0.119.0/src/aria_code.egg-info → aria_code-0.120.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aria-code
-Version: 0.119.0
+Version: 0.120.0
 Summary: Open-source AI agent for coding, financial analysis and logistics operations: numbers you can check, client data kept apart, actions a person approves
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/artheras/aria-code
@@ -172,7 +172,7 @@ Numbers you can check, client data kept apart, actions a person approves.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/@artheras/aria-code"><img src="https://img.shields.io/npm/v/@artheras/aria-code/latest?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
   <!-- Release automation pins PyPI: the default endpoint still selects legacy 4.x. -->
-  <a href="https://pypi.org/project/aria-code/0.119.0/"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Faria-code%2F0.119.0%2Fjson&amp;query=%24.info.version&amp;prefix=v&amp;style=flat-square&amp;logo=pypi&amp;label=PyPI&amp;color=blue&amp;cacheSeconds=300" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/aria-code/0.120.0/"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Faria-code%2F0.120.0%2Fjson&amp;query=%24.info.version&amp;prefix=v&amp;style=flat-square&amp;logo=pypi&amp;label=PyPI&amp;color=blue&amp;cacheSeconds=300" alt="PyPI version"></a>
   <a href="https://github.com/artheras/aria-code/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/artheras/aria-code/ci.yml?branch=main&style=flat-square&logo=githubactions&label=CI" alt="CI status"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-64748b?style=flat-square" alt="Apache License 2.0"></a>
 </p>

{aria_code-0.119.0 → aria_code-0.120.0}/README.md

@@ -15,7 +15,7 @@ Numbers you can check, client data kept apart, actions a person approves.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/@artheras/aria-code"><img src="https://img.shields.io/npm/v/@artheras/aria-code/latest?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
   <!-- Release automation pins PyPI: the default endpoint still selects legacy 4.x. -->
-  <a href="https://pypi.org/project/aria-code/0.119.0/"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Faria-code%2F0.119.0%2Fjson&amp;query=%24.info.version&amp;prefix=v&amp;style=flat-square&amp;logo=pypi&amp;label=PyPI&amp;color=blue&amp;cacheSeconds=300" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/aria-code/0.120.0/"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Faria-code%2F0.120.0%2Fjson&amp;query=%24.info.version&amp;prefix=v&amp;style=flat-square&amp;logo=pypi&amp;label=PyPI&amp;color=blue&amp;cacheSeconds=300" alt="PyPI version"></a>
   <a href="https://github.com/artheras/aria-code/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/artheras/aria-code/ci.yml?branch=main&style=flat-square&logo=githubactions&label=CI" alt="CI status"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-64748b?style=flat-square" alt="Apache License 2.0"></a>
 </p>

{aria_code-0.119.0 → aria_code-0.120.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aria-code"
-version = "0.119.0"
+version = "0.120.0"
 description = "Open-source AI agent for coding, financial analysis and logistics operations: numbers you can check, client data kept apart, actions a person approves"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{aria_code-0.119.0 → aria_code-0.120.0}/src/aria_code/_version.py

@@ -17,4 +17,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.119.0"
+__version__ = "0.120.0"

{aria_code-0.119.0 → aria_code-0.120.0}/src/aria_code/apps/cli/chat_turn.py

@@ -693,6 +693,10 @@ class ChatTurnMixin:
                 "error": getattr(_rt_turn, "error", None) or getattr(_rt_final, "error", ""),
                 "stop_reason": getattr(_rt_final, "stop_reason", "completed"),
                 "acceptance": getattr(_rt_final, "acceptance", None),
+                "delivery": getattr(_rt_final, "delivery", None),
+                # Captured now: the run id is cleared when the run is marked done,
+                # before the report that names it for /rewind is printed.
+                "run_id": self._active_run_id,
                 "provider": _rt_provider,
                 "cancelled": False,
                 "usage": {
@@ -1026,6 +1030,21 @@ class ChatTurnMixin:
                 for _sym in _ml_signal_syms:
                     self._record_prediction(_sym, final_text)
 
+            # The runtime's delivery report: what changed, what was verified,
+            # risk, checkpoints — from evidence, not from the model's summary.
+            _delivery = result.get("delivery") if isinstance(result, dict) else None
+            if _delivery and self.config.get("delivery_report", True):
+                try:
+                    from ui.render.output import print_delivery_report
+                    print_delivery_report(
+                        console if HAS_RICH else None,
+                        _delivery,
+                        run_id=str(result.get("run_id") or ""),
+                        root=os.getcwd(),
+                    )
+                except Exception as _delivery_err:
+                    logger.debug("delivery report not shown: %s", _delivery_err)
+
             # Metadata line — detailed stats
             metadata = turn_result.metadata
             prompt_t = metadata.prompt_tokens

{aria_code-0.119.0 → aria_code-0.120.0}/src/aria_code/apps/cli/headless.py

@@ -212,6 +212,8 @@ class HeadlessMixin:
                     "provider": getattr(_turn.final, "provider", ""),
                     "tools_used": _tools_used,
                     "acceptance": getattr(_turn.final, "acceptance", None),
+                    "delivery": getattr(_turn.final, "delivery", None),
+                    "contract": getattr(_turn.final, "contract", None),
                     "stop_reason": getattr(_turn.final, "stop_reason", "") or _turn.error or "completed",
                 }
             finally:

{aria_code-0.119.0 → aria_code-0.120.0}/src/aria_code/apps/cli/providers/runtime_bridge.py

@@ -85,6 +85,16 @@ def _declared_acceptance_commands(cfg: dict, message: str) -> tuple:
     return tuple(commands)
 
 
+def _workspace_root(cfg: dict, executor=None) -> str:
+    """Where this turn's tools act: the executor's workspace if it names one."""
+    import os
+
+    root = cfg.get("_session_workspace_root") or cfg.get("workspace_root") or os.getcwd()
+    if getattr(executor, "execution_context", None) is not None:
+        root = dict(executor.execution_context() or {}).get("_workspace") or root
+    return str(root)
+
+
 def build_acceptance_gate(executor, config: Optional[dict] = None, message: str = ""):
     """The CLI's acceptance gate, or ``None`` when this session shouldn't have one.
 
@@ -108,14 +118,11 @@ def build_acceptance_gate(executor, config: Optional[dict] = None, message: str
     if "run_command" not in getattr(executor, "local_tools", {}):
         return None
 
-    import os
     from aria_code.runtime.acceptance import AcceptanceGate
     from aria_code.runtime.approval import ApprovalDecision
 
     timeout = int(cfg.get("acceptance_timeout", 300) or 300)
-    root = cfg.get("_session_workspace_root") or cfg.get("workspace_root") or os.getcwd()
-    if getattr(executor, "execution_context", None) is not None:
-        root = dict(executor.execution_context() or {}).get("_workspace") or root
+    root = _workspace_root(cfg, executor)
 
     def _runner(command: str) -> dict:
         return executor.execute_local("run_command", {
@@ -132,6 +139,25 @@ def build_acceptance_gate(executor, config: Optional[dict] = None, message: str
     )
 
 
+def build_change_contract(config: Optional[dict] = None, message: str = "", executor=None):
+    """The project's change contract with this request as its goal, or None.
+
+    Declared in ``.aria/policy.yaml`` under the workspace root. A file that
+    cannot be read yields a fail-closed contract rather than none — see
+    ``ChangeContract.fail_closed``.
+    """
+    from aria_code.runtime.contract import ChangeContract, ContractError
+
+    root = _workspace_root(config or {}, executor)
+    try:
+        contract = ChangeContract.load(root)
+    except ContractError as exc:
+        contract = ChangeContract.fail_closed(root, str(exc))
+    except Exception as exc:  # unreadable file, missing yaml, …: still fail closed
+        contract = ChangeContract.fail_closed(root, f"{type(exc).__name__}: {exc}")
+    return contract.with_goal(message) if contract is not None else None
+
+
 async def run_with_fallback(
     route: str,
     *,
@@ -354,6 +380,7 @@ async def run_chat_via_runtime(
     )
     executor = build_tool_executor(local_tools, config, execution_context)
     gate = build_acceptance_gate(executor, config, prompt)
+    contract = build_change_contract(config, prompt, executor)
 
     result = await run_turn(
         prompt, history,
@@ -369,5 +396,6 @@ async def run_chat_via_runtime(
         grounding_tools=grounding_tools,
         evidence_already_grounded=evidence_already_grounded,
         acceptance=gate,
+        contract=contract,
     )
     return result if return_result else result.text

{aria_code-0.119.0 → aria_code-0.120.0}/src/aria_code/runtime/__init__.py

@@ -33,6 +33,7 @@ from .agent_loop import (
     run_serial_tool,
     split_tool_calls,
 )
+from .contract import ChangeContract, ContractError, ContractVerdict
 from .acceptance import (
     AcceptanceGate,
     AcceptanceReport,
@@ -90,6 +91,9 @@ __all__ = [
     "Symbol",
     "extract_symbols",
     "AcceptanceGate",
+    "ChangeContract",
+    "ContractError",
+    "ContractVerdict",
     "AcceptanceReport",
     "CheckResult",
     "DEFAULT_MUTATING_TOOLS",

{aria_code-0.119.0 → aria_code-0.120.0}/src/aria_code/runtime/agent_loop.py

@@ -12,12 +12,16 @@ import inspect
 import re
 import time
 from dataclasses import dataclass, field
-from typing import AsyncGenerator, Awaitable, Callable, Dict, FrozenSet, Iterable, List, Optional, Sequence, Tuple, Union
+from typing import TYPE_CHECKING, AsyncGenerator, Awaitable, Callable, Dict, FrozenSet, Iterable, List, Optional, Sequence, Tuple, Union
 
 from .acceptance import AcceptanceGate
 from .approval import ApprovalDecision, apply_approval_decision
 from .tool_executor import ToolExecutor
 from .budget import BudgetTracker
+from .delivery import DeliveryLedger
+
+if TYPE_CHECKING:
+    from .contract import ChangeContract
 
 
 DEFAULT_SERIAL_TOOLS = {"write_file", "edit_file", "multi_edit", "run_command", "process"}
@@ -356,6 +360,8 @@ class AgentTurnState:
         error: str = "",
         acceptance: Optional[dict] = None,
         stop_reason: str = "completed",
+        contract: Optional[dict] = None,
+        delivery: Optional[dict] = None,
     ) -> "AgentTurnResult":
         metadata = self.build_metadata(
             elapsed=elapsed,
@@ -373,6 +379,8 @@ class AgentTurnState:
             sources=list(self.sources),
             acceptance=acceptance,
             stop_reason=stop_reason,
+            contract=contract,
+            delivery=delivery,
         )
 
     def build_cancelled_result(
@@ -447,6 +455,13 @@ class AgentTurnResult:
     # 有值时 ``acceptance["verified"]`` 才是「做完了」这句话的凭据。
     acceptance: Optional[dict] = None
     stop_reason: str = "completed"
+    # The change contract this turn ran under and what it refused, or None
+    # when no contract applied.
+    contract: Optional[dict] = None
+    # The runtime's account of the turn (runtime/delivery.py): what changed,
+    # what was verified, the risk, checkpoints. None when nothing happened
+    # worth reporting.
+    delivery: Optional[dict] = None
 
     @classmethod
     def cancelled_result(
@@ -918,6 +933,7 @@ async def execute_tool_turn(
     approval_applier: Callable[[dict, ApprovalDecision], dict] = apply_approval_decision,
     loop_guard: LoopGuard | None = None,
     serial_tools: Iterable[str] = DEFAULT_SERIAL_TOOLS,
+    contract: "ChangeContract | None" = None,
 ) -> ToolExecutionTurnResult:
     """Execute one model-requested tool batch and prepare the next turn.
 
@@ -944,13 +960,25 @@ async def execute_tool_turn(
         }
         for tool_call in pending
     ]
-    parallel_done = await run_parallel_tools(
-        pending,
+    # The contract is checked before anything runs — parallel-safe calls run
+    # first, all at once — and a refused call never reaches the executor: its
+    # refusal stands in for its result, so the model learns which rule held.
+    refused: Dict[int, dict] = {}
+    if contract is not None:
+        for index, tool_call in enumerate(pending):
+            verdict = contract.check(str(tool_call.get("tool", "")), tool_call.get("params", {}) or {})
+            if not verdict.allowed:
+                refused[index] = verdict.as_tool_result(str(tool_call.get("tool", "")))
+    runnable_indices = [index for index in range(len(pending)) if index not in refused]
+    ran_in_parallel = await run_parallel_tools(
+        [pending[index] for index in runnable_indices],
         tool_executor,
         remote_runner=remote_runner,
         hook=hook,
         serial_tools=serial_tools,
     )
+    parallel_done = {runnable_indices[i]: result for i, result in ran_in_parallel.items()}
+    parallel_done.update(refused)
     tool_turn = ToolTurnPlan(pending=pending, parallel_done=parallel_done)
     tool_batch = tool_turn.batch
     activities: List[ToolExecutionActivity] = []
@@ -1319,6 +1347,10 @@ class AgentOptions:
     # 只要本轮真的改写了磁盘上的文件，模型宣称完成时循环会先跑一遍推断出的
     # 检查命令；红了就把失败输出回灌给模型继续修，绿了才让这一轮结束。
     acceptance: Optional["AcceptanceGate"] = None
+    # Change contract. None = no task bounds beyond the permission mode. With
+    # one, the model is shown it before the first round and the runtime
+    # refuses every tool call that breaks it (see runtime/contract.py).
+    contract: Optional["ChangeContract"] = None
 
 
 # ── run_agent() ───────────────────────────────────────────────────────────────
@@ -1392,6 +1424,12 @@ async def run_agent(
             f"Grounding tools: {available_grounding_tools}\n\n"
             f"[User request]\n{prompt}"
         )
+    if opts.contract is not None:
+        request = current_message if opts.requires_evidence else f"[User request]\n{prompt}"
+        current_message = f"{opts.contract.prompt_block()}\n\n{request}"
+    contract_refusals: List[dict] = []
+    ledger = DeliveryLedger(root=str(
+        getattr(opts.acceptance, "root", None) or getattr(opts.contract, "root", None) or "") or None)
     token_count = 0
     thinking_tokens = 0
     result: dict = {}
@@ -1575,10 +1613,19 @@ async def run_agent(
             confirm_tools=opts.confirm_tools,
             approval_callback=opts.approval_callback,
             approval_applier=opts.approval_applier or apply_approval_decision,
+            contract=opts.contract,
         )
 
         for activity in tool_turn_result.activities:
             turn_state.tools_used.append(activity.tool)
+            ledger.record(activity.tool, activity.params, activity.result)
+            refusal = (activity.result or {}).get("contract_violation")
+            if refusal:
+                contract_refusals.append(dict(refusal))
+                yield AgentEventStatus(
+                    state="contract_blocked",
+                    message=f"{activity.tool} refused by the change contract: {refusal.get('reason', '')}",
+                )
             if opts.acceptance is not None:
                 opts.acceptance.record_tool(activity.tool, activity.result)
             canonical_tool = str(activity.tool).rsplit("__", 1)[-1]
@@ -1641,6 +1688,16 @@ async def run_agent(
     )
     if stop_reason == "completed" and acceptance_summary and acceptance_summary.get("verified") is False:
         stop_reason = "checks_failed"
+    contract_summary = (
+        {
+            "goal": opts.contract.goal,
+            "source": opts.contract.source,
+            "text": opts.contract.render(),
+            "refused": contract_refusals,
+        }
+        if opts.contract is not None else None
+    )
+    delivery = ledger.report(acceptance=acceptance_summary, contract=contract_summary, stop_reason=stop_reason)
     turn_result = turn_state.build_result(
         elapsed=elapsed,
         success=stop_reason == "completed",
@@ -1650,5 +1707,7 @@ async def run_agent(
         token_count=token_count,
         thinking_tokens=thinking_tokens,
         acceptance=acceptance_summary,
+        contract=contract_summary,
+        delivery=delivery.as_dict() if delivery.worth_showing else None,
     )
     yield AgentEventComplete(result=turn_result)

aria_code-0.120.0/src/aria_code/runtime/contract.py

@@ -0,0 +1,282 @@
+"""Change contracts — the bounds a coding task runs inside.
+
+Permission modes say what the agent may do anywhere: read only, write the
+workspace, or anything. A task needs narrower bounds than that, and different
+ones per project: "fix the auth refresh bug" has no business touching billing,
+running a migration or pushing to main, even under workspace-write. Telling the
+model so in the prompt is a request; this module makes it a rule the runtime
+enforces on every tool call, before the call runs.
+
+A contract names:
+
+- ``allow``    — path globs the task may change (empty: the whole workspace);
+- ``restrict`` — path globs it must not change, even inside ``allow``;
+- ``forbid``   — capabilities it may not use (``git.push``, ``cloud.deploy``,
+  ``database.write`` …; see :data:`aria_code.safety.risk.CAPABILITIES`);
+- ``max_level`` — the highest risk level an action may have (L0–L4);
+- ``success``  — what "done" means, shown to the model and in the report.
+
+Projects declare one in ``.aria/policy.yaml`` under ``contract:``. The runtime
+fills in the goal from the request, shows the contract to the model before the
+first round, and refuses any call that breaks it — the call does not run, and
+the model gets the reason as the tool's result so it can stay inside the lines.
+
+Reading is never restricted: a contract bounds what a task changes.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Optional
+
+from aria_code.safety.risk import (
+    CAPABILITIES,
+    LEVEL_NAMES,
+    RiskAssessment,
+    assess_tool,
+    tool_paths,
+)
+
+POLICY_FILE = Path(".aria") / "policy.yaml"
+
+# Capabilities that change something. A contract's path rules apply to calls
+# that use one of these; reads and verification are never path-restricted.
+_MUTATING = frozenset({
+    "filesystem.write", "filesystem.delete", "git.stage", "git.commit", "git.history",
+})
+
+
+class ContractError(ValueError):
+    """A policy file whose contract cannot be enforced as written."""
+
+
+@dataclass(frozen=True)
+class ContractVerdict:
+    allowed: bool
+    reason: str = ""
+    rule: str = ""
+    assessment: Optional[RiskAssessment] = None
+
+    def as_tool_result(self, tool: str) -> dict:
+        """What the model sees instead of the call's output."""
+        return {
+            "success": False,
+            "error": (
+                f"Blocked by the change contract ({self.rule}): {self.reason}. "
+                "The call was not run. Stay inside the contract, or tell the user "
+                "what you need and why."
+            ),
+            "contract_violation": {
+                "tool": tool,
+                "rule": self.rule,
+                "reason": self.reason,
+                "level": self.assessment.level if self.assessment else None,
+            },
+        }
+
+
+def _glob_regex(pattern: str) -> re.Pattern:
+    """``src/**``, ``**/*.sql``, ``billing/*`` — matched against a POSIX relative path."""
+    pattern = pattern.strip()
+    while pattern.startswith("./"):
+        pattern = pattern[2:]
+    if pattern in {"", "."}:
+        pattern = "**"
+    if pattern.endswith("/"):
+        pattern += "**"
+    out, i = [], 0
+    while i < len(pattern):
+        if pattern.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+        elif pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+    # A directory pattern also covers what is inside it.
+    return re.compile("^" + "".join(out) + "(?:/.*)?$")
+
+
+@dataclass(frozen=True)
+class ChangeContract:
+    root: Path
+    goal: str = ""
+    allow: tuple = ()
+    restrict: tuple = ()
+    forbid: frozenset = frozenset()
+    max_level: int = 4
+    success: tuple = ()
+    source: str = ""
+    _allow_re: tuple = field(default=(), repr=False, compare=False)
+    _restrict_re: tuple = field(default=(), repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        unknown = sorted(set(self.forbid) - CAPABILITIES)
+        if unknown:
+            raise ContractError(
+                f"unknown capabilit{'y' if len(unknown) == 1 else 'ies'} in forbid: {', '.join(unknown)}"
+            )
+        if not 0 <= int(self.max_level) <= 4:
+            raise ContractError(f"max_level must be 0-4, not {self.max_level}")
+        object.__setattr__(self, "root", Path(self.root).expanduser())
+        object.__setattr__(self, "_allow_re", tuple(_glob_regex(p) for p in self.allow))
+        object.__setattr__(self, "_restrict_re", tuple(_glob_regex(p) for p in self.restrict))
+
+    # ── construction ──────────────────────────────────────────────────────
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any], root: Path | str, *, source: str = "") -> "ChangeContract":
+        def _strings(key: str) -> tuple:
+            value = data.get(key) or ()
+            if isinstance(value, str):
+                value = [value]
+            if not isinstance(value, Iterable):
+                raise ContractError(f"{key} must be a list")
+            return tuple(str(item).strip() for item in value if str(item).strip())
+
+        try:
+            max_level = int(data.get("max_level", 4))
+        except (TypeError, ValueError):
+            raise ContractError(f"max_level must be 0-4, not {data.get('max_level')!r}") from None
+        return cls(
+            root=Path(root),
+            goal=str(data.get("goal") or "").strip(),
+            allow=_strings("allow"),
+            restrict=_strings("restrict"),
+            forbid=frozenset(_strings("forbid")),
+            max_level=max_level,
+            success=_strings("success"),
+            source=source,
+        )
+
+    @classmethod
+    def load(cls, root: Path | str) -> Optional["ChangeContract"]:
+        """The project's contract from ``.aria/policy.yaml``, or None if it declares none.
+
+        A malformed file raises :class:`ContractError`: a contract that fails to
+        load must not silently become no contract.
+        """
+        root = Path(root).expanduser()
+        path = root / POLICY_FILE
+        if not path.is_file():
+            return None
+        import yaml
+
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError as exc:
+            raise ContractError(f"{path}: not valid YAML ({exc})") from None
+        if not isinstance(data, Mapping):
+            raise ContractError(f"{path}: expected a mapping at the top level")
+        section = data.get("contract")
+        if section is None:
+            return None
+        if not isinstance(section, Mapping):
+            raise ContractError(f"{path}: 'contract' must be a mapping")
+        return cls.from_mapping(section, root, source=str(path))
+
+    @classmethod
+    def fail_closed(cls, root: Path | str, error: str) -> "ChangeContract":
+        """The contract to run under when the project's could not be read.
+
+        A broken policy file means someone meant to bound this project; running
+        unbounded would drop exactly the limits they wrote. Reading and
+        verification still work, so the model can find and report the problem.
+        """
+        return cls(root=Path(root), max_level=0, source=f"error: {error}")
+
+    @property
+    def load_error(self) -> str:
+        return self.source[len("error: "):] if self.source.startswith("error: ") else ""
+
+    def with_goal(self, goal: str) -> "ChangeContract":
+        line = " ".join(str(goal or "").split())
+        return replace(self, goal=line[:200] + ("…" if len(line) > 200 else ""))
+
+    # ── enforcement ───────────────────────────────────────────────────────
+
+    def _relative(self, path: str) -> Optional[str]:
+        candidate = Path(os.path.expanduser(path))
+        if not candidate.is_absolute():
+            candidate = self.root / candidate
+        try:
+            return candidate.resolve().relative_to(self.root.resolve()).as_posix()
+        except (ValueError, OSError):
+            return None
+
+    def _check_path(self, path: str) -> Optional[tuple[str, str]]:
+        relative = self._relative(path)
+        if relative is None:
+            return ("outside-workspace", f"{path} is outside the workspace")
+        for pattern, regex in zip(self.restrict, self._restrict_re):
+            if regex.match(relative):
+                return ("restrict", f"{relative} is restricted ({pattern})")
+        if self.allow and not any(regex.match(relative) for regex in self._allow_re):
+            return ("allow", f"{relative} is outside the allowed paths ({', '.join(self.allow)})")
+        return None
+
+    def check(self, tool: str, params: Mapping[str, Any] | None = None) -> ContractVerdict:
+        assessment = assess_tool(tool, params or {}, root=self.root)
+        used = assessment.capabilities & self.forbid
+        if used:
+            return ContractVerdict(False, f"uses {', '.join(sorted(used))}", "forbid", assessment)
+        if assessment.level > self.max_level:
+            return ContractVerdict(
+                False,
+                f"{assessment.summary or tool} is L{assessment.level} ({assessment.name}); "
+                f"this task allows up to L{self.max_level} ({LEVEL_NAMES[self.max_level]})",
+                "max_level",
+                assessment,
+            )
+        if assessment.capabilities & _MUTATING:
+            paths = tool_paths(params or {}) if tool != "run_command" else list(assessment.files)
+            for path in paths:
+                problem = self._check_path(path)
+                if problem:
+                    return ContractVerdict(False, problem[1], problem[0], assessment)
+        return ContractVerdict(True, assessment=assessment)
+
+    # ── presentation ──────────────────────────────────────────────────────
+
+    def render(self) -> str:
+        """The contract as the model and the user read it."""
+        lines = ["CHANGE CONTRACT"]
+        if self.load_error:
+            lines += ["", f"⚠ {POLICY_FILE} could not be read: {self.load_error}",
+                      "  Nothing may be changed until it is fixed; reading and verifying still work."]
+        if self.goal:
+            lines += ["", "Goal", f"  {self.goal}"]
+        lines += ["", "Allowed"]
+        lines += [f"  ✓ modify {p}" for p in self.allow] or ["  ✓ modify files in the workspace"]
+        restricted = [f"  × modify {p}" for p in self.restrict]
+        restricted += [f"  × {cap}" for cap in sorted(self.forbid)]
+        if self.max_level < 4:
+            restricted.append(f"  × actions above L{self.max_level} ({LEVEL_NAMES[self.max_level]} risk)")
+        if restricted:
+            lines += ["", "Restricted"] + restricted
+        if self.success:
+            lines += ["", "Success criteria"] + [f"  ✓ {item}" for item in self.success]
+        return "\n".join(lines)
+
+    def prompt_block(self) -> str:
+        return (
+            "[Change contract]\n"
+            "This task runs under the contract below. The runtime refuses any tool call "
+            "that breaks it, so plan inside it; if the task cannot be done within it, "
+            "stop and say which rule is in the way.\n\n"
+            + self.render()
+        )
+
+
+__all__ = ["ChangeContract", "ContractError", "ContractVerdict", "POLICY_FILE"]